Deploying Web Parts in SharePoint Foundation
Applies to: SharePoint Foundation 2010
Microsoft SharePoint Foundation requires that a Web Part be deployed in the Web Part gallery before it can be added to a webpage. This section describes the differences between the bin folder and the global assembly cache, security permission considerations, how to strong name an assembly for deployment, how to create a SafeControl entry, and how to create a Web Part definition file to deploy the Web Part.
Deployment Considerations
There are multiple locations within a SharePoint site where you can deploy a Web Part assembly.
Solution Gallery – The Solution Gallery is the recommend placed to deploy a Web Part by using a sandboxed solution. It provides monitoring and security for your Web Parts by default. For more information about sandboxed solutions, see Sandboxed Solutions in SharePoint 2010.
global assembly cache — A global location where signed assemblies can be deployed, especially code for workflows, events, and Feature receivers. 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:\Windows\Assembly.
bin directory — A folder stored in your web application root directory; deployment to the bin directory should be limited to controls and Web Parts . The location of this folder is determined when the website is created in Internet Information Services (IIS). In SharePoint Foundation, this can occur either through the Central Administration site, or by manually creating a new website 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.
Each deployment location has advantages and disadvantages, as described in the following table.
Deployment Location |
Advantages |
Disadvantages |
|---|---|---|
Solution Gallery |
By default, code deployed to the Solution Gallery is run in partial trust. Code in the Solution Gallery also have resource usage monitoring to ensure the health of the farm. The Solution Gallery is specific to a site collection. |
All of the object model in SharePoint Foundation is not available in the Solution Gallery. |
global assembly cache |
By default, assemblies run with full trust. They are globally installed, so they work in any web application. The global assembly cache can contain multiple versions of the same assembly. |
Generally there are no code access security (CAS) restrictions on code installed to the global assembly cache. Also, an assembly deployed to the global assembly cache is cached, so if the assembly is rebuilt, it is not automatically updated on the SharePoint site. You must force SharePoint Foundation to reload the assembly by resetting Internet Information Services (IIS). |
bin directory |
By default, assemblies run with partial trust. Code that runs from this directory has a low level of 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, but we recommend that you use sandboxed solutions for security protection. |
In order for the Web Part to run in multiple web applications, you must deploy it to the global assembly cache. Deploying assemblies to the bin folder may affect performance because there is additional time required to load the .NET Framework runtime to manage code access security permissions. |
Security Permissions Considerations for the Bin Directory
By default, code access security permissions for the bin directory are low; only pure execution is allowed. In most cases, you must 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 SharePoint Foundation.
Optional method — Raise the trust level of the bin directory. In the web.config file in the web application root, there is a tag named <trust> with a default attribute of level="WSS_Minimal". You can change this level to WSS_Medium. Although 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, SharePoint Foundation refuses to run the module.
When you deploy 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 SharePoint Foundation.
To sign an assembly, you use the sn.exe tool that is included with the Microsoft .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 SharePoint Foundation technology is that untrusted users can upload and create ASPX pages within the system that is running SharePoint Foundation. To prevent untrusted users from arbitrarily adding server-side code within ASPX pages, SharePoint Foundation 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 file is a simple XML file that contains property settings for a single Web Part. To import your Web Part into a Web Parts page, 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 adding it to a site page. To display a default name and description for the Web Part after it is imported, you should include the Title and Description properties in the Web Part definition file. 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="https://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>
SharePoint Foundation also supports .dwp files for Web Parts. When exporting a Web Part, you may see a .dwp or a .webpart file. For more information, see Upgrading Web Parts in SharePoint Foundation.
See Also
Tasks
Walkthrough: Creating a Basic Web Part