Managing Web Parts on Virtual Servers (Windows SharePoint Services 2.0)

Article
05/05/2010

This topic describes Web Parts administration on virtual servers. Web Part administration tasks include:

Installing Web Parts.
Upgrading Web Parts.
Deleting Web Parts.
Managing an online Web Part gallery.
Allowing part-to-part connections.
Setting additional Web Part configuration options.

For information about managing Web Parts for a site collection, see Managing a Site Collection Web Part Gallery (Windows SharePoint Services 2.0).

Installing Web Parts

As a server administrator, you will be called on to install Web Parts on a server or server farm. To meet the needs of your organization, internal teams may develop Web Parts to deploy on some servers or across your entire intranet. Also, external software developers will build general purpose applications based on Web Parts technology and make them available to your user community. Installing a Web Part is a three-step process: evaluation, installation, and verification.

Evaluation

Evaluate a custom Web Part before installing it on your server or server farm. You should be comfortable that installing the Web Part will not compromise your server's security or performance. Web parts should be coded and tested by following recommended best practices, and they must be configured to run with the minimum level of permissions required to access the system and other resources that they need. Microsoft Windows SharePoint Services takes advantage of the Microsoft .NET Framework code access security mechanism to provide server administrators with the flexibility to set permissions on Web Part assemblies tailored to their needs. For a complete discussion, see Microsoft Windows SharePoint Services and Code Access Security.

The SharePoint Products and Technologies 2003 Software Development Kit contains guidelines for software developers that will help them implement their Web Parts following best security practices. For example, the SDK includes a topic, "Code Access Security for Administrators," that describes how code access security is used in Windows SharePoint Services and how an administrator can create custom security policy files if needed. Also, see SharePoint Products and Technologies on MSDN for additional information on creating and testing Web Parts, and see the Microsoft Security Developer Center for information that helps developers create secure software. Make sure that your developer community uses these resources in designing, coding, and testing Web Parts before you agree to deploy them.
Installation

Custom Web Part packages are distributed as cabinet (.cab) files. You use the command-line tool Stsadm.exe to add Web Parts from a Web Part package to one or more virtual servers.

In addition to installing the Web Part assemblies, .dwp files, and resources needed by Web Parts, Stsadm.exe puts a copy of the Web Part package in the configuration database. In a server farm configuration, you use this centrally located Web Part package when installing the Web Parts from other servers.

Note

The Wppackager tool is an alternative method of packaging and installing custom Web Parts. This unsupported tool is available on the Microsoft Download Center at SharePoint Products and Technologies Tool: wppackager for packaging and deploying Web Parts. A white paper on this tool is published at Using Wppackager to Package and Deploy Web Parts for Microsoft SharePoint Products and Technologies.

An important decision when adding a new Web Part assembly is whether to install it to the global assembly cache (GAC) or to the Bin directory (C:\inetpub\wwwroot\bin for the default virtual server). The Bin directory is the more secure option. When installed in the Bin directory, an assembly is only available to the virtual server. Because the administrator controls the trust level for the virtual server, assemblies installed in the Bin directory will run, by default, at a lower level of trust, such as WSS_Minimal, than they would in the GAC. (By default, assemblies installed in the GAC run at Full trust.)

In some IIS configurations, you must install assemblies in the GAC. For example, when you configure an IIS virtual server, extended by using Windows SharePoint Services, that has a host header name, you must install Web Part assemblies in the GAC. But generally, you should install custom Web Parts in the Bin directory, and you should demand of your developer community that they develop Web Parts that work properly under the trust level that you want to enforce on your virtual servers.
Verification

After installing Web Parts to each server, you can verify your installation by using the SharePoint Configuration Analyzer tool. Along with verifying that IIS and Windows SharePoint Services configurations are compatible, this tool reports on errors in Web Part and Web Control assemblies installations, mismatches between SafeControls lists (in web.config files) and the Web Parts that they reference, and Web Part assemblies that are missing from your server but referenced from pages in the database.

After installing a new Web Part assembly, using SharePoint Configuration Analyzer to check the installation, and fixing any errors, you should run SharePoint Configuration Analyzer again with the Save state information option selected. When you select Save state information, SharePoint Configuration Analyzer creates a reference XML file that it uses to reconstruct the mappings between global unique identifiers (GUIDs) and type names, so that it can report the more readable type names of Web Parts in its reports.

For information about installing and using SharePoint Configuration Analyzer, see Using SharePoint Configuration Analyzer (Windows SharePoint Services 2.0).

Installing Web Parts By Using Stsadm.exe

To add a new Web Part package to your virtual server, use the following syntax:

stsadm.exe -o addwppack -filename <path to Web Part Package> [-url <URL>] [-globalinstall]

-filename specifies the path to the cabinet file containing the Web Parts and associated resources.
-url optionally specifies the URL of the virtual server on which to install the Web Parts. To install the Web Parts on every virtual server on a server, omit the -url parameter.
-globalinstall tells Stsadm.exe to install the Web Parts in the global assembly cache (GAC) rather than in the Bin directories of each virtual server.

Assemblies installed in the GAC are available to all applications on the server. This is less secure than installing in Bin directories because it potentially grants a higher level of permission to your assemblies across a larger scope than might be necessary.
- Web Parts must be strongly named to be installed in the GAC. If one or more Web Parts in the Web Part package are not strongly named, the Web Part package will be installed in the Bin directory and not in the GAC. For more information, see the topic "Code Access Security for Developers" in the SharePoint Products and Technologies 2003 Software Development Kit.
- If you specify both the URL of a single virtual server and the -globalinstall parameter, the Web Part will only appear in the Web Part Gallery of the virtual server that you specified. However, the assembly will be installed in the GAC, will run at the Full Trust level by default, and will be available from other applications.

In a server farm configuration, if a Web Part package has already been installed on one front-end server, you can install the Web Part Package on another server from the configuration database by using the following syntax:

stsadm.exe -o addwppack -name <name of Web Part Package> [-url <URL>] [-globalinstall]

-name specifies the name of a Web Part Package.
-url optionally specifies the URL of the virtual server on which to install the Web Parts. To install the Web Parts on every virtual server on the server, omit the -url parameter.
-globalinstall specifies to install the Web Parts in the global assembly cache (GAC) rather than in the Bin directories of each virtual server. Use this flag consistently on all front-end servers of a server farm.

To enumerate the Web Part packages installed on a virtual server, use the following syntax:

stsadm.exe -o enumwppacks [-name <name of Web Part Package>] [-url <URL>]

-name specifies the name of a Web Part package. Omitting this parameter specifies to list all Web Part packages for the virtual server or virtual servers.
-url optionally specifies the URL of the virtual server for which to enumerate the Web Part packages. If -url is omitted, Stsadm.exe enumerates Web Part packages on every virtual server on the server.

Upgrading Web Parts

You may need to upgrade installed Web Parts on a server or server farm, either to introduce new functionality or to distribute repaired Web Parts in response to bugs or security issues. Upgrading Web Parts is a four-step process: evaluation, notification, installation, and verification.

Evaluation

Evaluate changes to a custom Web Part before upgrading it. As when installing new Web Parts, you should verify that changes to the Web Part do not compromise your server security or performance. Make sure that your developer community uses the resources available at the MSDN SharePoint Developer Center and in the SharePoint Products and Technologies 2003 Software Development Kit when designing, coding, and testing new or updated Web Parts before you agree to deploy them.
Notification

Before upgrading a Web Part package, you should notify everyone in your user community who is using Web Parts from the package. An upgraded Web Part may function differently, and an upgraded Web Part description (.dwp) file may expose new properties. Failing to notify your user community could result in broken Web sites and the resultant support calls.

To find all owners of pages containing a Web Part on a virtual server, use the SharePoint Configuration Analyzer tool. SharePoint Configuration Analyzer lists each Web Part installed on a virtual server and, for each Web Part, lists all of the pages that contain an instance of that Web Part in a Web Part Zone. Using this information, you can contact owners of pages containing Web Parts that are about to be upgraded. For more information about SharePoint Configuration Analyzer, including where to find this tool, see Using SharePoint Configuration Analyzer (Windows SharePoint Services 2.0).
Installation

Installing an upgraded Web Part package is similar to installing a new package. Use the Stsadm.exe command line tool to upgrade the Web Part package.
Verification

As with new Web Parts packages, after upgrading Web Parts to each server, you can verify your installation by using the SharePoint Configuration Analyzer tool.

After upgrading a Web Part assembly, using SharePoint Configuration Analyzer to check the upgrade, and fixing any errors, you should run SharePoint Configuration Analyzer again with the Save state information option selected. When you select Save state information, SharePoint Configuration Analyzer creates a reference XML file that it uses to reconstruct the mappings between GUIDs and type names, so that it can report the more readable type names of Web Parts in its reports.

Upgrading Web Parts By Using Stsadm.exe

You use the command-line tool Stsadm.exe to upgrade Web Parts from a Web Part package (in cabinet file format) to a virtual server. In addition to upgrading the Web Part assemblies and optional Web Part Definition (.dwp) files to the server, Stsadm.exe puts a copy of the Web Part package in the configuration database. In a server farm configuration, use this centrally located cabinet file when upgrading the Web Parts from other servers.

The syntax for upgrading a Web Part package on a virtual server is similar to the syntax for installing a new package:

stsadm.exe -o addwppack -filename <path to file> -force [-url <URL>] [-globalinstall]

-filename specifies the path to the cabinet file containing the Web Parts.
-force instructs Stsadm.exe to overwrite an existing Web Part package with a new version.
-url optionally specifies the URL of the virtual server on which to upgrade the Web Parts. If -url is omitted, Stsadm.exe upgrades the Web Parts in the Bin folder of every virtual server on the server. On servers where the Web Parts were not installed, this is equivalent to a new installation.
-globalinstall specifies to install the Web Parts in the global assembly cache (GAC) rather than in the Bin directories of each virtual server.

In a server farm, if a Web Part package has already been upgraded on one front-end server, you can upgrade the Web Part package from another server by using the following syntax, where -name specifies the name of the Web Part package:

stsadm.exe -o addwppack -name <name of Web Part Package> -force [-url <URL>] [-globalinstall]

When you upgrade a Web Part assembly that is currently in the global assembly cache, if you omit the -globalinstall parameter, the Web Part assembly will be moved to the Bin folder. When you upgrade a Web Part assembly that is currently in the Bin folder, adding the -globalinstall parameter will move the upgraded assembly to the global assembly cache.

Deleting Web Parts

When you delete a Web Part on a server, you delete the assembly (that part of the Web Part implementation that is executable code) and related resources. Users must remove the Web Part Definition file from any pages that use the Web Part. Deleting Web Parts is a three-step process: notification, deletion, and verification.

Notification

Before deleting a Web Part assembly, you should notify everyone in your user community who is using the assembly. Deleting Web Parts that are in use will break the functionality of Web pages that are dependent on the Web Part. Failing to notify your user community could result in support calls as pages stop working as expected.

To find all owners of pages containing a Web Part on a virtual server, use the SharePoint Configuration Analyzer tool, which lists each Web Part installed on a virtual server and, for each Web Part, lists all of the pages that contain an instance of the Web Part in a Web Part Zone. Using this information, contact owners of pages containing Web Parts that are to be deleted, so that they can remove instances of that Web Part from their pages. For more information about SharePoint Configuration Analyzer, see Using SharePoint Configuration Analyzer (Windows SharePoint Services 2.0).

Note

Because SharePoint Configuration Analyzer does not report on the Web Parts that have been added to each site collection gallery, you should also contact all site administrators of site collection galleries to warn them to remove Web Parts that you are deleting from these galleries.
Deletion

Use the Stsadm.exe tool to delete a Web Part assembly.
Verification

After deleting Web Part assemblies from each server, you can verify the operation using the SharePoint Configuration Analyzer tool. By using this tool, you can find unwanted Web Part assemblies that remain on virtual servers along with pages that refer to deleted assemblies.

Deleting Web Parts By Using Stsadm.exe

To delete the Web Parts in a Web Part package, use the following syntax:

stsadm -o deletewppack -name <name of Web Part package> [-url <url>]

-name specifies the name of the Web Part package.
-url optionally specifies the URL of the virtual server on which to delete the Web Parts. If -url is omitted, Stsadm.exe deletes the Web Parts from the Bin folder of every virtual server on the server or from the global assembly cache.

Note

When you delete the last instance of a Web Parts package on a server or server farm, Stsadm.exe also deletes the Web Part package from the configuration database.

Managing the Online Gallery

If your organization runs Windows SharePoint Services over multiple front-end servers, you may want to create your own online Web Part gallery as a central location for deploying Web Parts to all your sites.

Specifying an Online Web Part Gallery

To specify an online Web Part gallery for a virtual server:

On the Web server, navigate to the folder containing the virtual server, and then, using a text editor such as Microsoft Notepad, open the web.config file under the following directory:

\Inetpub\wwwroot
In the web.config file, modify the following line, which is contained in the <SharePoint> element:
```
<OnlineLibrary Url="https://Server/Path"/>
```
Where Server is the server hosting the online gallery and Path is the path to the .aspx page that implements the online gallery.
Save and close the web.config file.
Repeat steps 1 through 3 for each virtual server for which you want to specify an online Web Part gallery.

Adding Web Parts to an Online Web Part Gallery

As with all Web Part galleries, a new Web Part added to an online gallery can be implemented either as a Web Part description (.dwp) file or as a .dwp file along with a new assembly file. New Web Parts implemented as .dwp files provide their functionality by configuring existing assemblies to behave in new ways. New Web Parts that are implemented as both a .dwp file and an assembly file provide their functionality by implementing new code in the assembly file.

When a new Web Part that has a new assembly is added to an online gallery, the server administrator for each server that accesses the online gallery must install the assembly on each server. It is up the owner of the online gallery to contact each server administrator and provide a method for installing the new assembly, and the administrator of each server must evaluate the Web Part before installing its assembly, as with any custom Web Part.

Controlling Access to the Online Gallery

You can configure access to the online gallery for each virtual server. You must be an administrator of the local server computer or a member of the SharePoint Administrators group to configure access to the online gallery.

On your server computer, click Start, point to Administrative Tools, and then click SharePoint Central Administration.
On the SharePoint Central Administration page, click Configure virtual server settings.
On the Virtual Server List page, click the virtual server you want to configure.
On the Virtual Server Settings page, click Manage security settings for Web Part Pages.
In the Online Web Part Gallery section, click Enabled to allow access to the online Web Part gallery, or click Disabled to prevent access to the gallery, and then click OK.

You can also return to using the default server setting for enabling use of the Online Web Part gallery by clicking Restore Defaults.

Allowing Access to the Online Web Part Gallery from Behind a Proxy Server or Firewall

If your server is behind a proxy server or firewall, you must also edit the web.config file for each virtual server for which you want to enable an online Web Part gallery that is implemented outside of your firewall. In a server farm environment, you must edit this file for each virtual server in every front-end Web server in the server farm.

On your Web front-end server computer, open Notepad, navigate to the folder containing the virtual server for which you want to enable the online Web Part gallery, and then open the web.config file under the following directory:

\Inetpub\wwwroot

In the web.config file, add the following lines:

<system.net>
  <defaultProxy>
  <proxy proxyaddress="https://Proxy_Server:port" bypassonlocal = "true"/>
  </defaultProxy>
</system.net>

Where Proxy_Server:port is the proxy server or firewall used for your environment.

Save and close the web.config file.
Repeat steps 1 through 3 for each virtual server for which you want to enable access to the online Web Part gallery.

Allowing Part-to-Part Connections

You specify whether or not users can connect Web Parts to each other for each virtual server. You must be an administrator of the local server computer or a member of the SharePoint Administrators group to allow part-to-part connections.

On your server computer, click Start, point to Administrative Tools, and then click SharePoint Central Administration.
On the SharePoint Central Administration page, click Configure virtual server settings.
On the Virtual Server List page, click the virtual server you want to configure.
On the Virtual Server Settings page, click Manage security settings for Web Part Pages.
Select the options you want to enable or disable, and then click OK.

You can also return to using the default server setting for part-to-part connections by clicking Restore Defaults.

Additional Web Part Settings

There are additional Web Part options you can set in the Windows SharePoint Services web.config file. The web.config file is a text file containing custom XML elements. You can edit this file using a text editor, such as Microsoft Notepad. The web.config file for the default virtual server is located in the C:\Inetpub\wwwroot\ folder. When a virtual server is extended with Windows SharePoint Services, a top-level web.config file is placed within the content root folder of the extended virtual server.

The following is a summary of these additional Web Part options and their values.

Setting Safemode Attributes

There are two safe mode attributes:

MaxControls specifies the maximum number of server-side controls (controls with the HTML Element attribute runat = "server") on a Web Part Page, including Web Parts, static Web Parts (that is, Web Parts not in a zone), and Web Form Controls. The default value is 50.
CallStack shows or hides many (but not all) ASP.NET exceptions that may occur in addition to the initial error reported in the SharePoint Error page. You can do the following:
- To show these messages, set CallStack to "true".
- To hide these messages, set CallStack to "false". This is the default.
You might set this attribute to "true" for developers who are testing Web Parts so they can view these messages on a remote computer. You must also set the customErrors mode in the <system.web> section to "On".

Setting CallStack to "true" also enables stack tracing.

Note

Except when debugging, CallStack should be set to "false." Setting CallStack to "true" on a production Web server will make your Web server less secure.

The following example sets the safe mode attributes to their default values:

<SharePoint>
    <SafeMode MaxControls="50" CallStack="False" />
</SharePoint>
<system.web>
    <customErrors mode="On" />
</system.web>

Setting WebPartLimits Attributes

There are two Web Part limit attributes:

MaxZoneParts specifies the total number of Web Parts allowed within all Web Part zones on a Web Part Page.
PropertySize specifies the maximum number of bytes used to store Web Part properties on the server.

The following example sets the Web Part limit attributes to their default values:

<SharePoint>
    <WebPartLimits MaxZoneParts="50" PropertySize="1048576" />
</SharePoint>

Configuring Web Part Caching

WebPartCache Storage specifies how a Web Part is cached on the server, if at all. You can enter one of the following values:

Value	Description
None	Prevent caching Web Parts on the server.
CacheObject	Use ASP.NET Web server memory caching. This is the default. In general, this value helps improve performance if your site is installed on a single server.
Database	Cache Web Parts in site server database. In general, this value helps improve performance if your site is installed on a server farm.

The following example sets the Web Part cache storage attribute to its default value:

<SharePoint>
    <WebPartCache Storage="CacheObject" />
</SharePoint>

Note

A Web Part must implement caching to take advantage of the server or database cache. Developing Web Parts that use caching is described in the SharePoint Products and Technologies 2003 Software Development Kit.

Setting Web Part Timeout Values

WebPartWorkItem Timeout specifies a timeout value in milliseconds for any asynchronous child processes started by a Web Part. The default value is 7000.

The following example sets the Web Part work item timeout to its default value:

<SharePoint>
    <WebPartWorkItem Timeout value="7000" />
</SharePoint>

Setting the Default Security Policy and Trust Level

You can define and specify a default security policy and trust level for all Web Parts installed on the site server by using two configuration files. There are two default policies:

WSS_Minimal A copy of the ASP.NET web_minimaltrust.config file with WebPartPermission.Connections enabled. This is the default.
WSS_Medium A copy of ASP.NET web_mediumtrust.config file with WebPartPermission.Connections and SharePointPermission.ObjectModel enabled.

The following example defines and sets a minimal trust level:

<system.web>
  <securityPolicy>
      <trustLevel name="WSS_Minimal" policyFile="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\config\wss_minimaltrust.config" /> 
   </securityPolicy>     
   <trust level="WSS_Minimal" originUrl="" />
</system.web>

The following example defines and sets a medium trust level:

<system.web>
  <securityPolicy>
      <trustLevel name="WSS_Medium" policyFile="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\config\wss_mediumtrust.config" /> 
  </securityPolicy>
  <trust level="WSS_Medium" originUrl="" />
</system.web>

For a full discussion of setting trust levels, see the topic "Code Access Security For Administrators" in the SharePoint Products and Technologies 2003 Software Development Kit.

The SafeControls List

To register a Web Part as a safe control for use in Windows SharePoint Services, in the SafeControls block, add a SafeControl element that specifies the Web Part in the top-level web.config file of the virtual server. When you add and delete Web Part assemblies using the Stsadm.exe tool, this is handled by Stsadm.exe.

The following example, from the SharePoint Products and Technologies 2003 Software Development Kit registers a sample Web Part as a SafeControl:

<SafeControls>
  <SafeControl
   Assembly="SimpleWebPart, Version=1.0.0.0, Culture=neutral, PublicKeyToken=def148956c61a16b"
   Namespace="MyWebParts"
   TypeName="*" >
      .
      .
      .
<\SafeControls>

For an overview of Web Parts, see About Web Parts (Windows SharePoint Services 2.0).

For information on using SharePoint Configuration Analyzer, see Using SharePoint Configuration Analyzer (Windows SharePoint Services 2.0).

For information on managing a site collection Web Part Gallery, see Managing a Site Collection Web Part Gallery (Windows SharePoint Services 2.0).

For information on developing custom Web Parts, see the SharePoint Products and Technologies 2003 Software Development Kit.

Share via

Managing Web Parts on Virtual Servers (Windows SharePoint Services 2.0)

Installing Web Parts

Installing Web Parts By Using Stsadm.exe

Upgrading Web Parts

Upgrading Web Parts By Using Stsadm.exe

Deleting Web Parts

Deleting Web Parts By Using Stsadm.exe

Managing the Online Gallery

Specifying an Online Web Part Gallery

Adding Web Parts to an Online Web Part Gallery

Controlling Access to the Online Gallery

Allowing Access to the Online Web Part Gallery from Behind a Proxy Server or Firewall

Allowing Part-to-Part Connections

Additional Web Part Settings

Setting Safemode Attributes

Setting WebPartLimits Attributes

Configuring Web Part Caching

Setting Web Part Timeout Values

Setting the Default Security Policy and Trust Level

The SafeControls List

Additional resources

Share via

Managing Web Parts on Virtual Servers (Windows SharePoint Services 2.0)

Installing Web Parts

Installing Web Parts By Using Stsadm.exe

Upgrading Web Parts

Upgrading Web Parts By Using Stsadm.exe

Deleting Web Parts

Deleting Web Parts By Using Stsadm.exe

Managing the Online Gallery

Specifying an Online Web Part Gallery

Adding Web Parts to an Online Web Part Gallery

Controlling Access to the Online Gallery

Allowing Access to the Online Web Part Gallery from Behind a Proxy Server or Firewall

Allowing Part-to-Part Connections

Additional Web Part Settings

Setting Safemode Attributes

Setting WebPartLimits Attributes

Configuring Web Part Caching

Setting Web Part Timeout Values

Setting the Default Security Policy and Trust Level

The SafeControls List

Related Topics

Additional resources