Calculating the Required Assembly Permission Set

Visual Studio 2005 can help to estimate the permissions an assembly requires. Although Visual Studio 2005 is a developer tool, as an administrator, you will find it helpful to get an idea of the permissions that a Web Part library requires. For example, if you are using a Weather Web Part that requires full permissions, something is definitely wrong with it. As an added bonus, Visual Studio 2005 can help you to retrieve the XML needed to define permissions in security policy files. If you want to try the techniques outlined in this section, you will need access to Visual Studio 2005, preferably installed on a test SharePoint server. This section does not assume you have any knowledge about Visual Studio 2005, and will guide you through the permission calculation process step by step.

During the first steps, you will create a test Web Part library. It will contain the minimal amount of code necessary to perform a successful calculation of the required permissions.

1. Start Visual Studio 2005. From the Start menu, point to All Programs, Microsoft Visual Studio 2005, and then select Microsoft Visual Studio 2005.

2. From the File menu, point to New, and then select Project.

3. In the left pane of the New Project window, expand the Visual C# node, under Project types, select the Class Library template.

4. Specify the following name: MyWPLibrary.

5. Specify the following location: C:\projects.

6. Leave the other default settings and click OK.

This creates a skeleton for a library file that can be used to contain Web Parts. During the next steps, you will use the Microsoft.SharePoint.Security assembly that contains SharePoint-specific permissions to demand the permission to use the SharePoint object model for the test Web Part library.

1. Right-click the References node and choose Add Reference to open the Add Reference window.

2. On the .NET tab, select Microsoft.SharePoint.Security.dll. Choose the second component name that is called Windows SharePoint Services. Verify that this component refers to Microsoft.SharePoint.Security.dll under Path.

   Note 

   The component name of this dll is Windows SharePoint Services. Because a default SharePoint installation contains multiple components with this name, picking the correct assembly is a bit more complicated than it should be.

3. Double-click Class1.cs. Replace the code in this file with the following code:

    using System.Security.Permissions; using Microsoft.SharePoint.Security; namespace MyWPLibrary {   public class Class1   {     [FileIOPermission(SecurityAction.Demand, Read = @"c:\test.txt")]     [SharePointPermission(SecurityAction.Demand, ObjectModel = true,     Impersonate = true)]     public void Test() {}   } } 

This code creates a method called Test() and requires the presence of a couple of permissions; if the permissions are missing, this assembly will fail to execute. One of the permissions, FileIOPermission, requires the permission to read a file called test.txt and is not SharePoint-related at all. The other permission is SharePoint-related; SharePointPermission represents a custom permission that controls the ability to access SharePoint. This demand requires that the permission to use the SharePoint object model and impersonate code is granted to the assembly.

You cannot use Visual Studio 2005 to calculate the required permissions for libraries directly. Because .NET libraries cannot be executed without being hosted by another application, you first need to create a host application for it, and then you can calculate permissions for the test Web Part library. To do this, follow these steps:

1. Right-click the MyWPLibrary solution, point to Add, and then select New Project.

2. Expand the Visual C# section and choose the Windows Application template.

3. Specify the name WPLibHost, and then click OK.

At this point, you have created an application that can host a .NET library. Visual Studio 2005 will perform a static analysis of all method calls, so for the analysis to work, you need to call all the methods you want to analyze within the host application.

In this procedure, you will analyze the Test() method of the MyWPLibrary assembly. To do so, you must add a reference in the WPLibHost application host to this assembly and call this method.

1. Click the References node of the WPLibHost application, and choose Add Reference.

2. In the Add Reference window, click the Projects tab.

3. Ensure the MyWPLibrary project name is selected, and then click OK.

4. Double-click Form1.cs.

5. Press F7, or select View and then select Code, to open the code view for this class.

6. Add the code that calls the Test() method of the MyWPLibrary assembly to the Form1() constructor. The Form1() constructor should look like this:

    public Form1() {   InitializeComponent();   MyWPLibrary.Class1 testClass = new MyWPLibrary.Class1();   testClass.Test(); } 

Because you have set up an application host that calls the test Web Part library, Visual Studio 2005 is now able to calculate the permissions the Web Part library requires to operate. Visual Studio 2005 will perform a static analysis of the current application and all referenced assemblies. The analysis involves all method calls, declarative attributes, and programmatic demands. This analysis provides only an estimate and might overestimate permissions because it analyzes all code paths including those that are never used. It might also underestimate permissions because it is not able to detect dynamic calls made using reflection. The correctness of the analysis is improved greatly if Web Part developers have taken the time and effort to demand permissions explicitly via declarative attributes.

In the next procedure, you learn how to calculate permissions for the test Web Part library.

1. Right-click WPLibHost and choose Properties.

2. Click the Security tab.

3. Select the Enable ClickOnce Security Settings check box.

4. Click the This Is A Partial Trust Application option.

5. Go to the Zone Your Application Will Be Installed From drop-down list and choose the following value: (Custom).

6. Click the Calculate Permissions button.

This starts the permission calculation. Ultimately, the permissions will appear in the Permissions Required By The Application section, as shown in Figure 31-1.

Figure 31-1: Calculated permissions

If you scroll down to the SharePointPermission permission and click Properties, you see the XML definition for this permission as shown in Figure 31-2. You can copy this XML definition and use it within a security policy file.

Figure 31-2: XML for a custom permission

As an alternative to using Visual Studio 2005, you can use the command-line tool Permcalc.exe, which is a part of the Visual Studio 2005 SDK, to calculate permissions for .NET assemblies. An advantage of Permcalc.exe is that it is also able to calculate permissions for library assemblies (.dll) directly. Open a Visual Studio 2005 command prompt, and type the following command:

 permcalc.exe [myassembly].dll 

As a result, Permcalc.exe starts to calculate the permissions required for the assembly and generates an XML file (by default, this XML file is called [myassembly].dll.PermCalc.xml) containing an overview of those permissions. By default, this XML file is saved in the folder where the assembly for which you are calculating permissions is located.

As was true for the Visual Studio 2005 tool, Permcalc.exe is accurate at calculating permissions that are demanded declaratively. It is less accurate when permissions are demanded programmatically, and even less accurate when it calculates permissions that are defined imperatively. Imperative permissions are permissions that are required because the code in a .NET assembly requires them, not because the permissions are demanded explicitly. For example, if someone writes a line of code that reads a given file, this is an imperative permission demand: the code will fail if it does not have the permission to read the file.

Best Practices 

In SharePoint scenarios, use the visual permission calculation tool included in Visual Studio 2005. Although Permcalc.exe might be useful for calculating permissions required for assemblies that do not require SharePoint permissions, currently this tool is useless in SharePoint scenarios. If you try to analyze an assembly that demands SharePoint permissions, you receive an error during XML output generation stating that SharePoint permissions are not marked as serializable.