System.Security.PermissionSet Class

public class PermissionSet : ICollection, IEnumerable

Base Types

Object
  PermissionSet

This type implements ICollection and IEnumerable.

Assembly

mscorlib

Library

BCL

Summary

Represents a collection that can contain different kinds of permissions and perform security operations.

Description

[Note: Use PermissionSet to perform operations on different permission types as a group.]

The XML encoding of a PermissionSet instance is defined below in EBNF format. The following conventions are used:

The following meta-language symbols are used:

The XML encoding of a PermissionSet instance is as follows:

PermissionSet::=

(

<PermissionSet

class="System.Security.PermissionSet"

version="1" Unrestricted="true"/>

)

|

(

<PermissionSet

class="System.Security.PermissionSet"

version="1">

DnsPermissionXML ?

SocketPermissionXML ?

WebPermissionXML ?

EnvironmentPermissionXML ?

FileIOPermissionXML ?

ReflectionPermissionXML ?

SecurityPermissionXML ?

CustomPermissionXML *

</PermissionSet>

)

CustomPermissionXML represents any custom permission. The XML encoding for custom permissions makes use of the following symbols:

ClassName is the name of the class implementing the permission.

AssemblyName is the name of the assembly that contains the class implementing the permission.

Version is the version number indicating the version of the assembly implementing the permission.

StrongNamePublicKeyToken is the strong name public key token constituting the strong name of the assembly that implements the permission.

version is version information for the custom permission. Format and content are defined by the author of the custom permission.

PermissionAttributes is any attribute and attribute value on the IPermission element used by the permission to represent a particular permission state, for example, unrestricted= "true". Format and content are defined by the author of the custom permission.

PermissionXML is any valid XML used by the permission to represent permission state. Format and content are defined by the author of the custom permission.

The XML encoding of a custom permission instance is as follows:

CustomPermissionXML ::=

<IPermission class="

ClassName,

AssemblyName,

Version= Version,

Culture=neutral,

PublicKeyToken= StrongNamePublicKeyToken"

version=" version"

(PermissionAttributes)*

&gt;

(PermissionXML)?

</IPermission>

See Also

System.Security Namespace

Members

PermissionSet Constructors

PermissionSet(System.Security.PermissionSet) Constructor
PermissionSet(System.Security.Permissions.PermissionState) Constructor

PermissionSet Methods

PermissionSet.AddPermission Method
PermissionSet.Assert Method
PermissionSet.Copy Method
PermissionSet.CopyTo Method
PermissionSet.Demand Method
PermissionSet.Deny Method
PermissionSet.FromXml Method
PermissionSet.GetEnumerator Method
PermissionSet.IsSubsetOf Method
PermissionSet.PermitOnly Method
PermissionSet.ToString Method
PermissionSet.ToXml Method
PermissionSet.Union Method

PermissionSet Properties

PermissionSet.Count Property
PermissionSet.IsSynchronized Property
PermissionSet.SyncRoot Property

PermissionSet(System.Security.PermissionSet) Constructor

public PermissionSet(PermissionSet permSet);

Summary

Constructs a new instance of the PermissionSet class with the values of the specified PermissionSet instance.

Parameters

permSet
The PermissionSet instance with which to initialize the values of the new instance, or null to initialize an empty permission set.

Exceptions

Exception TypeCondition
ArgumentExceptionpermSet is not null and is not an instance of PermissionSet.

Description

If permSet is not null , the new instance is initialized with copies of the objects in permSet, not references to those objects. If permSet is null , the new instance contains no permissions.

[Note: To add a permission to an empty PermissionSet , use System.Security.PermissionSet.AddPermission(System.Security.IPermission).]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet(System.Security.Permissions.PermissionState) Constructor

public PermissionSet(PermissionState state);

Summary

Constructs a new instance of the PermissionSet class with the specified value.

Parameters

state
A PermissionState value. This value is either System.Security.Permissions.PermissionState.None or System.Security.Permissions.PermissionState.Unrestricted , to specify fully restricted or fully unrestricted access.

Exceptions

Exception TypeCondition
ArgumentExceptionstate is not a valid PermissionState value.

Description

[Note: The new instance contains no permissions. To add a permission to the new instance, use System.Security.PermissionSet.AddPermission(System.Security.IPermission).]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.AddPermission Method

public virtual IPermission AddPermission(IPermission perm);

Summary

Adds the specified IPermission object to the current instance if that permission does not already exist in the current instance.

Parameters

perm
The IPermission object to add.

Return Value

If perm is null , returns null . If a permission of the same type as perm already exists in the current instance, the union of the existing permission and perm is added to the current instance and is returned.

Exceptions

Exception TypeCondition
ArgumentExceptionperm is not a IPermission object.

Description

[Behaviors: The IPermission is added if perm is not null and a permission of the same type as perm does not already exist in the current instance.]

[Usage: Use this method to add permission objects to the current instance.]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.Assert Method

public virtual void Assert();

Summary

Asserts that calling code can access the resources identified by the permissions contained in the current instance through the code that calls this method, even if callers have not been granted permission to access the resource.

Exceptions

Exception TypeCondition
SecurityExceptionThe asserting code does not have sufficient permission to call this method.

-or-

This method was called with permissions already asserted for the current stack frame.

Description

[Note: This method is the only way to assert multiple permissions at the same time within a frame because only a single assert can be active on a frame at one time; subsequent asserts will result in an exception.]

[Behaviors: As described above.]

[Usage: Use this method to insure that all callers can access a set of secured resources.]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.Copy Method

public virtual PermissionSet Copy();

Summary

Returns a new PermissionSet containing copies of the objects in the current instance.

Return Value

A new PermissionSet that is value equal to the current instance.

Description

[Behaviors: This method creates copies of the permission objects in the current instance, and adds them to the new instance.]

[Default: This method calls the PermissionSet constructor that takes a PermissionSet argument, and passes the current instance as that parameter.]

[Usage: Use this method to create a new PermissionSet instance containing permissions that are identical to the permissions contained in the current instance.]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.CopyTo Method

public virtual void CopyTo(Array array, int index);

Summary

Copies the permission objects in the current instance to the specified location in the specified Array .

Parameters

array
The destination Array .
index
A Int32 that specifies the zero-based starting position in the array at which to begin copying.

Exceptions

Exception TypeCondition
ArgumentExceptionarray has more than one dimension.
IndexOutOfRangeExceptionindex is outside the range of allowable values for array.
ArgumentNullExceptionarray is null .

Description

[Note: This method is implemented to support the ICollection interface.]

[Behaviors: As described above.]

[Default: The default implementation uses the System.Array.SetValue(System.Object,System.Int32)(Object, Int32) method to add the value to the array.]

[Overrides: Override this method to customize the manner in which elements are added to array . ]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.Demand Method

public virtual void Demand();

Summary

Forces a SecurityException if all callers do not have the permissions specified by the objects contained in the current instance.

Exceptions

Exception TypeCondition
SecurityExceptionA caller does not have the permission specified by the current instance.

Description

[Behaviors: The permission check for System.Security.PermissionSet.Demand begins with the immediate caller of the code that calls this method and continues until all callers have been checked or a caller has been found that is not granted the demanded permission, in which case a SecurityException exception is thrown.

If the current instance is empty, a call to System.Security.PermissionSet.Demand succeeds.

]

[Usage: Use this method to ensure in a single operation that all callers have all permissions contained in a permission set.]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.Deny Method

public virtual void Deny();

Summary

Denies access to the resources secured by the objects contained in the current instance through the code that calls this method.

Exceptions

Exception TypeCondition
SecurityExceptionA previous call to Deny has already restricted the permissions for the current stack frame.

Description

This is the only way to deny multiple permissions at the same time within a frame because only a single deny can be active on a frame at one time; subsequent denies will result in an exception.

[Behaviors: This method is required to prevent callers from accessing all resources protected by the objects in the current instance even if the callers had been granted permission to access them.

A call to System.Security.PermissionSet.Deny is effective until the calling code returns.

]

[Usage: Use this method to force all security checks for the objects contained in the current instance to fail.]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.FromXml Method

public virtual void FromXml(SecurityElement et);

Summary

Reconstructs the state of a PermissionSet object using the specified XML encoding.

Parameters

et
A SecurityElement instance containing the XML encoding to use to reconstruct the state of a PermissionSet object.

Exceptions

Exception TypeCondition
ArgumentNullExceptionet is null .
ArgumentExceptionet does not contain an XML encoding for a PermissionSet instance.

-or-

An error occurred while reconstructing et .

Description

[Note: For the XML encoding for this class, see the PermissionSet class page.]

[Behaviors: When this call completes, the objects in the current instance are required to be identical to the objects in the PermissionSet encoded in et .]

[Overrides: Override this method to reconstruct subclasses of PermissionSet .]

[Usage: Applications do not typically call this method; it is called by the system.]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.GetEnumerator Method

public virtual IEnumerator GetEnumerator();

Summary

Returns an enumerator used to iterate over the permissions in the current instance.

Return Value

A IEnumerator object for the permissions of the set.

Description

[Note: This method is implemented to support the ICollection interface, which supports the IEnumerable interface.]

[Behaviors: As described above.]

[Overrides: Override this method to customize the enumerator returned by this method.]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.IsSubsetOf Method

public virtual bool IsSubsetOf(PermissionSet target);

Summary

Determines whether the current instance is a subset of the specified object.

Parameters

target
A PermissionSet instance that is to be tested for the subset relationship.

Return Value

true if the current instance is a subset of target; otherwise, false .

Description

[Note: The current instance is a subset target if all demands that succeed for the current instance also succeed for target. That is, the current instance is a subset of target if target contains at least the permissions contained in the current instance.

If this method returns true , the current instance does not describe a level of access to a set of resources that is not already described by target.

]

[Behaviors: As described above.]

[Usage: Use this method to determine if the all permissions contained in the current instance are also contained in target.]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.PermitOnly Method

public virtual void PermitOnly();

Summary

Specifies that only the resources described by the current instance can be accessed by calling code, even if the code has been granted permission to access other resources.

Exceptions

Exception TypeCondition
SecurityExceptionA previous call to PermitOnly has already set the permissions for the current stack frame.

Description

[Note: System.Security.PermissionSet.PermitOnly is similar to System.Security.PermissionSet.Deny in that both methods cause access to fail where it might otherwise succeed. The difference is that System.Security.PermissionSet.Deny specifies permissions for which to refuse access, while System.Security.PermissionSet.PermitOnly specifies the only permissions that will succeed.

This is the only way to permit multiple permissions at the same time within a stack frame because only a single permit at a time can be active on a frame; subsequent permits will result in an exception.

]

[Behaviors: Callers are required to be prevented from accessing resources not secured by the contents of the current instance, even if a caller has been granted permission to access such resources.

A System.Security.PermissionSet.PermitOnly is in effect until the calling code returns to its caller.

]

[Usage: Use this method to limit access to a specified set of resources.]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.ToString Method

public override string ToString();

Summary

Returns a String representation of the state of the current instance.

Return Value

A String containing the XML representation of the state of the current instance.

Description

[Note: This method overrides System.Object.ToString.

]

Example

The following example displays the XML that encodes the state of a PermissionSet .

using System;
using System.Security;
using System.Security.Permissions;

public class PermissionSetToStringExample {
  public static void Main() {

    PermissionSet ps = new PermissionSet(PermissionState.Unrestricted);
    Console.WriteLine(ps.ToString());
  }
}
The output is

&lt;PermissionSet class="System.Security.PermissionSet" version="1" Unrestricted="true"/>

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.ToXml Method

public virtual SecurityElement ToXml();

Summary

Returns the XML encoding of the current instance.

Return Value

A SecurityElement containing an XML encoding of the state of the current instance.

Description

[Behaviors: As described above.]

[Overrides: Override this method to return an object containing the XML encoding for types derived from PermissionSet.]

[Usage: This method is called by the system.]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.Union Method

public virtual PermissionSet Union(PermissionSet other);

Summary

Returns a PermissionSet object that is the union of the current instance and the specified object.

Parameters

other
A PermissionSet instance to be combined with the current instance.

Return Value

A new PermissionSet instance that represents the union of the current instance and other. If the current instance or other is unrestricted, returns a PermissionSet instance that is unrestricted.

Description

The result of a call to System.Security.PermissionSet.Union(System.Security.PermissionSet) is a new PermissionSet instance that represents all the operations represented by the current instance as well as all the operations represented by other . If either set is unrestricted, the union is unrestricted, as well.

[Behaviors: As described above.]

[Usage: Use this method to create a PermissionSet instance that contains all of the permissions of the current instance and other .]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.Count Property

int ICollection.Count { get; }

Summary

Implemented to support the ICollection interface. [Note: For more information, see System.Collections.ICollection.Count.]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.IsSynchronized Property

bool ICollection.IsSynchronized { get; }

Summary

Implemented to support the ICollection interface. [Note: For more information, see System.Collections.ICollection.IsSynchronized.]

See Also

System.Security.PermissionSet Class, System.Security Namespace

PermissionSet.SyncRoot Property

object ICollection.SyncRoot { get; }

Summary

Implemented to support the ICollection interface. [Note: For more information, see System.Collections.ICollection.SyncRoot.]

See Also

System.Security.PermissionSet Class, System.Security Namespace