Configure and deploy Web Parts (SharePoint Server 2010)

  • Article

 

Applies to: SharePoint Server 2010, SharePoint Foundation 2010

This article provides information and procedures that are required to configure and deploy secure Web Parts to either the Bin directory or the .NET Framework Global Assembly Cache (GAC) on your server.

In this article:

  • Configuration options

  • Setting security attributes

  • Safe Controls list

  • Deploy and configure a Web Part

  • Add a component to the Web Part Gallery

Microsoft SharePoint Server includes a set of Web Parts that users can add to pages after installing the product. If an organization needs custom Web Parts, a developer can write custom ASP.NET Web Parts and ask you to install them to a deployment of SharePoint Server. This process typically requires testing and approval of the code before the Web Part can be deployed in a full-trust environment. A developer who uses Visual Studio 2010 can deploy a Web Part to SharePoint Server by right clicking the project and selecting Deploy. The destination for the Web Part is determined by the trust level established with the SharePoint server when the developer created the project in Visual Studio 2010.

Microsoft SharePoint Server 2010 enables you to configure a sandboxed environment where site collection administrators, site administrators, or information workers can deploy and run partially trusted Web Parts and solutions in a sandboxed worker process. Web Parts and solutions that run in a sandboxed environment have limited permissions to access the server operating system and hardware, and they are isolated from other parts of the Web application.

For more information on using sandboxed solutions, see Sandboxed solutions administration (SharePoint Server 2010).

SharePoint Server uses some of the configuration management settings that are provided by the Microsoft .NET Framework. Some of these settings are stored in XML configuration files and provide a broad range of settings that enable server administrators to manage the Web application and its environment. For more information about ASP.NET configuration files, see Machine.Config and Web.Config Explained (https://go.microsoft.com/fwlink/p/?LinkId=103450&clcid=0x409) in "Securing Your ASP.NET Application and Web Services" in the MSDN Library Online.

Configuration options

System administrators can deploy ASP.NET Web Parts to a deployment of SharePoint Server in either of two locations:

  • Bin directory   Stored in the bin folder under the root directory of your Web application.

  • Global Assembly Cache (GAC)   All standard Web Parts are automatically installed in the GAC, where the common language runtime of the .NET Framework is located, at %windir%\assembly. Web Parts stored in the GAC can be shared across applications.

The following table describes the advantages and disadvantages of each location.

Deployment location Advantages Disadvantages

Bin directory

A partial-trust location. By default, code that runs from this directory has a low level of code access security permissions. If the Web Part requires access across applications or more access than the default permissions allow, the administrator must explicitly raise permissions that are granted to a Web Part so that it can function correctly. Administrators might prefer that assemblies run in the Bin directory, with a known minimum set of required code access security permissions.

Because the Bin directory is specific to a Web application, you can use this method if you want to isolate code to a single Web application.

To run your Web Part everywhere, you must deploy your assembly to the Bin directory on each server.

GAC

A global location where you can deploy signed assemblies, which can run with full trust by default. Because the assemblies are installed globally, they work in any Web application.

Generally, there are no code access security restrictions on code that is installed to the GAC; therefore, you lose the benefit of defense-in-depth security.

Additionally, it can be difficult to deploy your program database (.pdb) files to assemblies in the GAC.

Setting security attributes

ASP.NET Web Parts that are stored in the Bin directory have additional security attributes. You can decide whether to set these attributes for your Web Part, depending on how you plan to use it.

The Bin directory is a partial-trust location. Therefore, your Web Part is not automatically granted full trust code permissions when it is executed. Because the code that calls into your Web Part is granted only partial trust permissions, the Web Part developer must set the AllowPartiallyTrustedCallers attribute on your ASP.NET Web Part.

Marking a component as "safe" with the AllowPartiallyTrustedCallers attribute puts the responsibility for safe implementation on the development team.

By default, code access security permissions for the Bin directory are very low. You should test your Web Parts carefully to determine the correct level of permissions to assign, and to ensure that the Web Part does not present a security risk to your environment.

You can elevate permissions in either of two ways:

  • (Recommended) Create a trust policy file and point your Web.config file at the new file. This option is more complex, but it enables you to set precise permissions for your Web Parts. For more information about trust policy files, see Microsoft Windows SharePoint Services and Code Access Security (https://go.microsoft.com/fwlink/p/?LinkID=103436&clcid=0x409) in the MSDN Library Online.

  • Raise the overall trust level of the Bin directory. In the Web.config file in the root directory of your Web application, locate the trust element. The default value for the trust element's level attribute is 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 it is less secure than creating a trust policy file.

Safe Controls list

A fundamental assumption of SharePoint Products is that untrusted users can upload and create .aspx pages within the system on which SharePoint Server is running. These users should be prevented from adding server-side code within .aspx pages, but there should be a list of approved controls that those untrusted users can use. In SharePoint Server, this list is provided by the Safe Controls list.

The Safe Controls list contains the names of controls and Web Parts, specific to your SharePoint site, that server administrators can designate as safe for invocation on any .aspx page within a site. This list is part of the Web.config file in your Web application root.

Deploy and configure a Web Part

The method that you use to deploy a new Web Part will depend on the finished package that the developer provides. If the developer provided you with the Web Part as a single dynamic-link library (DLL) file, you can manually deploy the DLL by copying it to your Web application’s Bin folder. If the developer provides you with a CAB file containing the Web Part, you can use Windows PowerShell to deploy the Web Part.

To manually deploy and configure a Web Part

  1. Verify that you have the following administrative credentials:

    • You must be a member of the local Administrators group on the server hosting SharePoint Server.

  2. Copy the <YourWebPartName>.dll assembly in the project's Bin directory to the Bin directory in your Web application root directory. For example: C:\inetpub\wwwroot\wss\VirtualDirectories\80\.

  3. Locate the Web.config file in your application root directory and open it for editing.

  4. Add the following safe-control entry for your custom assembly to the Web.config file:

    <SafeControl Assembly="<YourWebPartName>, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" Namespace="<YourWebPartNamespace>" TypeName="*" Safe="True" AllowRemoteDesigner="True"/>

    Where:

    1. <YourWebPartName> is the name of the Web Part that is being deployed.

    2. <YourWebPartNamespace> is the namespace that is associated with your Web Part.

An alternative to manually installing a Web Part to the Bin folder or manually changing the Web.config file is to use Windows PowerShell to install the Web Part package. For this process to work, a developer or system administrator must create a CAB solution package for the Web Part. For more information about creating a CAB package, see the Solutions and Web Part Packages (https://go.microsoft.com/fwlink/p/?LinkID=95855&clcid=0x409) documentation in the MSDN Library Online. After you create a CAB file, follow these steps to deploy the Web Part.

To deploy the Web Part by using Windows PowerShell

  1. Verify that you meet the following minimum requirements: See Add-SPShellAdmin.

  2. On the Start menu, click All Programs.

  3. Click Microsoft SharePoint 2010 Products.

  4. Click SharePoint 2010 Management Shell.

  5. At the Windows PowerShell command prompt (PS C:\>), type the following command, and then press ENTER:

    Install-SPWebPartPack -LiteralPath "<PathToCabFile>" -Name "<WebPartName>"

    Where:

    • <PathToCabFile> is the full path to the CAB file that is being deployed.

    • <WebPartName> is the name of the Web Part that is being deployed.

Note

The previous procedure shows a common way to use Install-SPWebPartPack to deploy a Web Part. You can specify additional parameters to change the way the Web Part is deployed. For more information, see Install-SPWebPartPack.

Note

We recommend that you use Windows PowerShell when performing command-line administrative tasks. The Stsadm command-line tool has been deprecated, but is included to support compatibility with previous product versions.

Every Web Part should have a .webpart file, which is an XML file that describes the Web Part. The .webpart file also causes your Web Part to appear in the Web Part gallery. The following procedure is the easiest way to create a .webpart file after you deploy your Web Part and register it in the Safe Control list.

To add a component to the Web Part gallery

  1. Verify that you have the following administrative credentials:

    • You must be a member of the Farm Administrators group.

  2. To create a .webpart file, navigate to http://<MyServer>/_layouts/newdwp.aspx, where <MyServer> is the name of the server on which your SharePoint site is deployed.

  3. Select the check box next to <YourWebPartNamespace>.<YourWebPartName>.

  4. Click Populate Gallery to add the YourWebPartName Web Part to the Team Site gallery.

  5. In the Web Part gallery, select Edit to edit the Web Part, and then click Import.

    You are prompted to specify a location for the .webpart file. You can also export ASP.NET Web Parts and import them to SharePoint sites.