Deploying Web Parts in Windows SharePoint Services

  • Article

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Windows SharePoint Services requires that a Web Part be deployed in the Web Part gallery before it can be added to the page. This section describes differences between the bin folder and the Global Assembly Cache (GAC), security permissions considerations, how to strong name an assembly for deployment, how to create a SafeControl entry, and finally, how to create a Web Part definition file to deploy the Web Part.

Deployment Considerations

There are two primary locations within a SharePoint site where you can deploy a Web Part assembly.

  • bin directory — The bin directory is a folder stored in your Web application root directory. The location of this folder is determined when the Web site is created in Internet Information Services (IIS). In Windows SharePoint Services, this can happen either through the SharePoint 3.0 Central Administration site, or by manually creating a new Web site in IIS manager.

    Important

    If a bin directory does not exist you must add one manually. Do not store Web Parts in the local _app_bin directory, which is reserved for use by Microsoft. For more information, see How to: Find the Web Application Root.

  • global assembly cache — A global location where signed assemblies can be deployed. The global assembly cache enables you to share assemblies across numerous applications. The global assembly cache is automatically installed with the .NET runtime. Components are typically stored in C:\WINNT\Assembly.

Each location has advantages and disadvantages, as described in the following table.

Deployment Location

Advantages

Disadvantages

bin directory

Assemblies run with partial trust, by default. Code that runs from this directory has a low level of code access security (CAS) permissions. Because administrators must explicitly raise permissions that have been granted to a Web Part so it can function properly, they often prefer that assemblies run in the bin directory with a known set of required CAS permissions.

A bin directory is specific to a Web application. This makes it possible to isolate code to a particular Web application.

In order for the Web Part to run in multiple Web applications, you must deploy it to the global assembly cache.

global assembly cache

Assemblies run with full trust by default. They are globally installed, so they will work in any Web application. The global assembly cache can contain multiple versions of the same assembly.

Generally no CAS restrictions on code installed to the global assembly cache; therefore, you lose the defense-in-depth security benefit.

Also, an assembly deployed to the GAC is cached, so if the assembly is rebuilt, it is not automatically updated on the SharePoint site. You must force Windows SharePoint Services to reload the assembly by resetting Internet Information Services (IIS).

Security Permissions Considerations

By default, code access security permissions for the bin directory are low; only pure execution is allowed. In most cases you need to elevate these permissions to make your assembly run correctly, for example, if your Web Part requires access to the SharePoint object model.

There are two ways to elevate permissions:

  • Recommended method — Create a new trust policy file and point your web.config file at the new file. This option is more complicated but it gives you a precise attribution of permissions for your Web Parts.

    For more information about trust policy files, see Securing Web Parts in Windows SharePoint Services.

  • Optional method — Raise the net trust level of the bin directory. In the web.config file in the Web application root, there is a tag called <trust> with a default attribute of level="WSS_Minimal". You can change this level to WSS_Medium. While this option is simpler, it grants arbitrary new permissions that you might not need and is less secure than creating a new trust policy file.

Strong Naming a Web Part Assembly

Strong naming uses a private key to digitally sign an assembly. Strong naming also stamps the assembly with a public key to validate the signature. This technique guards against unauthorized versions of a Web Part. If the public key fails to validate the digital signature, Windows SharePoint Services will refuse to run the module.

When deploying a Web Part to the bin, the recommend practice is to strong name the assembly. When deploying a Web Part to the Global Assembly Cache, the assembly must have a strong name. An assembly without a strong name is not recommended in Windows SharePoint Services.

To sign an assembly, you use the sn.exe tool that is included with the .NET Framework Software Development Kit (SDK). For more information about the .NET Framework SDK, see SDKs, Redistributables & Service Packs. The sn.exe tool is also used to extract the public key that is needed to register your control as safe in the SafeControls list. For more information about using the sn.exe tool, see Strong Name Tool (Sn.exe).

Creating a SafeControl Entry

A fundamental assumption of the Windows SharePoint Services technology is that untrusted users can upload and create ASPX pages within the system that is running Windows SharePoint Services. To prevent untrusted users from arbitrarily adding server-side code within ASPX pages, Windows SharePoint Services provides a SafeControls list.

The SafeControls list is a list of approved controls and Web Parts specific to your SharePoint site that you have designated as safe for invocation on any ASPX page within your site. This list is contained in the web.config file in your Web application root.

A SafeControl entry is an XML-based declaration of a Web Part that has the following form.

<SafeControl Assembly="AssemblyNameWithoutDLLExtension, Version=AssemblyVersionNumber, Culture=neutral, PublicKeyToken=PublicKeyToken" Namespace="NamespaceOfYourProject" TypeName="*" Safe="True" />

The SafeControl entry uses the assembly name, namespace, versioning information, and, if it is signed, it also requires a public key token to verify that the control is safe. If a Web Part assembly is signed, you can use the Strong Name Tool to retrieve the public key token for use in the SafeControl entry. The following command will retrieve the public key token for an assembly.

sn -T AssemblyName.dll

Creating a .Webpart File

A Web Part definition (.webpart) file is a simple XML file that contains property settings for a single Web Part. To import your Web Part into a Web Part Page, simply upload the .webpart file or add the Web Part to the Web Part gallery. After uploading the Web Part, you can display the Web Part by dragging it into one of the zones of the Web Part Page. To display a default name and description for the Web Part after it is imported, you should include the Title and Description properties. If you want to set other Web Part properties during import, you can also define them in a .webpart file. A .webpart file takes the following form.

<?xml version="1.0" encoding="utf-8" ?> 
  <webParts>
     <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
       <metaData>
         <type name="TypeName, Version=VersionNumber, Culture=neutral, 
         PublicKeyToken=PublicKeyToken" /> 
         <importErrorMessage>Cannot import this Web 
         Part.</importErrorMessage> 
       </metaData>
       <data>
         <properties>
           <property name="Title" type="string">
              WebPartTitle</property>
           <property name="Description" type="string">
              WebPartDescription
           </property>
         </properties>
       </data>
     </webPart>
   </webParts>

See Also

Concepts

Securing Web Parts in Windows SharePoint Services