How Do I...Request the permissions my code needs?

Since you do not necessarily have control over what permissions are assigned to the code you write, the common language runtime provides a mechanism for requesting the permissions that you feel your code must have in order to run properly. If the code is not granted the required permissions, it will not run. And, because permission requests are stored in an assembly's manifest, the end user can run a tool to determine what permissions have been requested by the assembly author and then take the appropriate steps to grant those permissions if they need the code to run on their machine.

Three types of permission requests are supported:

• RequestMinimum: The permissions the code must have to run properly. If these permissions cannot be granted, the code will not be executed.
• RequestOptional: The permissions that should be granted if allowed by policy. The runtime will attempt to execute code even if permissions it requests as optional have not been granted.
• RequestRefuse: The permissions that code should never be granted. Code will not receive these permissions, even if they would normally be granted to it. This is an extra precaution you can take to prevent your from code being misused.

Permission requests can only be made in a declarative fashion and must always be at the assembly level (the assembly is the unit to which permissions are granted by the security system). The following code is a request stating that an assembly must have unrestricted access to the file system in order to function.

[assembly:FileIOPermission(SecurityAction.RequestMinimum, Unrestricted=true)] public class FileMover { //something interesting } Public Class FileMover 'something interesting End Class [assembly:FileIOPermission(SecurityAction.RequestMinimum, Unrestricted=true)] public class FileMover { //something interesting }

Several requests of the same type can be made, in which case the final permission set requested is the aggregate of all requests of that type. In the example below RequestMinimum is used twice with different permissions to state that the assembly must have the ability to use Reflection Emit and perform serialization in order for it to function.

[assembly:ReflectionPermission(SecurityAction.RequestMinimum, ReflectionEmit=true)] [assembly:SecurityPermission(SecurityAction.RequestMinimum, SerializationFormatter=true)] public class CodeGenerator { //something interesting } Public Class CodeGenerator 'something interesting End Class [assembly:ReflectionPermission(SecurityAction.RequestMinimum, ReflectionEmit=true)] [assembly:SecurityPermission(SecurityAction.RequestMinimum, SerializationFormatter=true)] public class CodeGenerator { //something interesting }

The same permission can also appear in requests of different types. For instance, the example program at the bottom of this page uses an EnvironmentPermission in each of its three requests (Minimum, Optional, and Refuse). This is useful when a permission encompasses a number of operations and you want to ensure that your assembly has the ability to perform some of those operations while being prevented from performing others. It is important to note that any permission you refuse using RequestRefuse will not be granted to your assembly even if you request that same permission using RequestMinimum.

In addition to requesting individual permissions, entire sets of permissions can be requested in a compact fashion. The example below shows two requests: one stating that an assembly must have unrestricted access to the file system in order to function and one stating that it will take any and all other permissions that the security system is willing to grant it.

[assembly:FileIOPermission(SecurityAction.RequestMinimum, Unrestricted=true)] [assembly:PermissionSet(SecurityAction.RequestOptional, Name="FullTrust")] public class FileMover { //something interesting } Public Class FileMover 'something interesting End Class [assembly:FileIOPermission(SecurityAction.RequestMinimum, Unrestricted=true)] [assembly:PermissionSet(SecurityAction.RequestOptional, Name="FullTrust")] public class FileMover { //something interesting }

The previous example shows how to request a permission set by name, but it is also possible to use a custom permission set representing the exact permissions you want. For more information on how to do this, search for PermissionSetAttribute in the .NET Framework SDK Reference.

The SDK provides a tool called PERMVIEW that is useful for verifying that your permission requests are correct. Running PERMVIEW on a compiled assembly will read the permission requests out of the assembly's manifest and display them as shown below.

The following example shows a simple program for reading Windows environment variables. The program is intending to collect very basic information about the user's hardware (processor type, # of processors, etc.) but has safeguards in place to prevent it from ever being used to obtain private information (user name, computer name, etc.).