Using Wppackager to Package and Deploy Web Parts for Microsoft SharePoint Products and Technologies

Introduction

Deploying a Web Part solution includes more tasks than simply copying assemblies and resource files, and updating the SafeControl list. For example, it is recommended that you apply custom code access security permissions for the assembly to function properly. Additionally, when preparing to deploy a Web Part across a server or server farm that includes multiple portals sites, you may choose to deploy to Web Part only to specific virtual servers. This article describes how to use Wppackager for packaging and installing a Web Part solution across a server or server farm deployment of Microsoft SharePoint Products and Technologies. You can use this tool for stand-alone deployments of Microsoft Windows SharePoint Services or deployments of Microsoft Office SharePoint Portal Server 2003.

Note   The Wppackager download is a self-extracting file. To use the tool, download and extract the files. During installation, specify an appropriate location to extract the files. This also installs a sample packaging file to use for reference. Wppackager packages Web Parts into a Microsoft Windows Installer (.msi) file for distribution across a deployment of Microsoft SharePoint Products and Technologies.

To use Wppackager complete the following tasks:

1. Create a packaging file.
2. Create a manifest file.
3. Run Wppackager to package the files.

The following is a list of possible files used to create the MSI:

• Packaging file (mandatory)
• manifest.xml (mandatory)
• Web Part assemblies (optional)
• Class resource files (optional)
• .dwp files (optional)

Prerequisites

It is recommended that you are familiar with the following:

• Microsoft SharePoint Products and Technologies such as Windows SharePoint Services or SharePoint Portal Server.
• Web Parts, including how to create them.
• Web Part infrastructure.
• The stsadm tool and manifest file.

For more information, see Packaging and Deploying Web Parts for Microsoft Windows SharePoint Services.

The packaging file is an XML file that contains configuration information describing what contents to include in the Windows Installer.

The following table describes the nodes and sub nodes in the packaging file.

Table 1. Nodes and sub nodes in the packaging file

Node	Parent Node	Description	Required/Optional
Wppackager	Wppackager	Defines the XML Schema. Uses the xmlns attribute to specify the namespace. Set the value of xmlns attribute to the following: http://schemas.microsoft.com/WebPart/v1/Wppackager	Required
Manifest	Wppackager	Use the FileName attribute to define the manifest file. Important   The reference to the manifest file must be relative to the folder from which the tool is run.	Required
CodeAccessSecurity	Wppackager	Use to define the permission set required by the assembly. Set the following attributes for strong-named assemblies to create the CodeGroup entry in the policy file. The AssemblyName attribute defines the assembly to which the permission set applies. Set the PublicKeyBlob and Version attributes to specify the public key, public key blob, and the version of the assembly. These attributes are required to define the codegroup element using the StrongNameCondition.	Optional
MSI	Wppackager	Use the Name attribute to specify the name of the Windows Installer including as it appears in the Add or Remove Programs list. Use the Version attribute to specify the Windows Installer version. Use the Manufacturer attribute to specify the name of the manufacturer.	Required

The following example shows a packaging file and sets the WebPermission permission for a strong-named assembly.

<?xml version="1.0" ?>
<WPPackager xmlns="http://schemas.microsoft.com/WebPart/v1/Wppackager">
  <Manifest FileName="Manifest.xml" />
   <MSI Name="SampleMSI" Version="1.0.0.1" Manufacturer="Microsoft
   corporation"/>
   <CodeAccessSecurity Assembly=" WebPartLibrary1" Version="1.0"
   PublicKeyBlob="xxxxxxxxxx">
      <PermissionSet class="NamedPermissionSet" version="1"
      Name="uniquenameforPermSet">
         <IPermission class="AspNetHostingPermission" version="1"
         Level="Minimal"/>
         <IPermission class="SecurityPermission" version="1"
         Flags="Execution" />
         <IPermission class="Microsoft.SharePoint.Security.SharePointPermission, 
Microsoft.SharePoint.Security, Version=11.0.0.0, Culture=neutral, 
PublicKeyToken=XXXXXXXXXXXX" version="1" Unrestricted="True" />
      </PermissionSet>
   </CodeAccessSecurity>
</WPPackager>

The Wppackager download contains a sample packaging file, Wppackager.xml. The sample packaging file contains a set of permissions you can use for reference. For more information about code access security, see Microsoft Windows SharePoint Services and Code Access Security.

Creating a Manifest File

The manifest file describes the contents of the CAB file that is created by the Wppackager tool. You must create a manifest file before running Wppackager to identify the files to include in the Windows Installer. For more information about how to create the manifest file, see Packaging and Deploying Web Parts for Microsoft Windows SharePoint Services.

Using Wppackager to Create the Windows Installer

Wppackager is a tool that is available for download from Microsoft. For help when using Wppackager as a command-line tool, type the following at a command prompt:

wppackager -help

To use Wppackager to create a Windows Installer

1. Create the packaging file (Wppackager.xml).
2. Create the manifest file (manifest.xml).
3. Copy all the files you want to package into the directory in which the tool is located.

   Note   Ensure the files match the directory structure outlined in the manifest file.

4. Open the command prompt and go to the directory that contains the files that you want packaged, and run the following command:

   wppackager name_of_packaging_file

   For example, wppackager wppackager.xml

Wppackager creates an unsigned Windows Installer file with the following name: MSI_NameManufacturer_Name.msi.

Important   It is recommended that you sign the Windows Installer to ensure it is trusted by the Administrator. Wppackager warns you during creation that the package is not signed. For more information about signing, see Microsoft Windows SharePoint Services and Code Access Security.

The total length of the string MSI_NameManufacturer_Name.msi should not exceed 225 characters.

Installing the Windows Installer

The Windows Installer with the Web Part solution is now ready to be deployed to Administrators. Complete the following steps to install the Windows Installer on the server computer.

Important   You must be a member of the local Administrators group on the computer to install the Windows Installer. The computer also must have Windows SharePoint Services installed.

To deploy the Web Part solution across a server farm deployment of Microsoft SharePoint Products and Technologies, the administrator must run the Windows Installer on each front-end Web server individually. The tool does not install across all front-end Web servers automatically.

To install the Windows Installer to a server running Windows SharePoint Services

1. Double-click MSI_NameManufacturer_Name.msi to begin installation.
2. On the MSI_NameManufacturer_Name Setup page, do one of the following:
   • Click All virtual servers to install the Windows Installer on all virtual servers for this computer, and then click Next.

     OR

   • Click Specific virtual servers to install the Windows Installer only on specific virtual servers.

     In the text box, type the name of one or more virtual servers on which you want to install the Windows Installer, separated by semicolons, and then click Next. For example, \ http://myserver/site1; http://myserver/site2.

   Important   To install the Windows Installer on an additional virtual server, you must remove the Windows Installer by using Add or Remove Programs and reinstall it specifying each virtual server to which to install the Windows Installer.

3. If you are installing a strong-named assembly, on the Global Assembly Cache Options page, click Yes to install the assembly to the global assembly cache and apply the default permissions specified for global assembly cache. Click No to install the assembly to the BIN directory.

   Note   By default, if you choose to install the assembly to the global assembly cache, strongly-named assemblies are installed to the global assembly cache. All other assemblies are installed to the BIN directory.

4. On the Code Access Security Options page, do one of the following:
   • Click Yes to set permissions for each assembly as specified in the packaging file.
   • Click No if you do not want to apply the specified permissions.

     Note   If you are installing this Windows Installer to the global assembly cache, choose No to use the permissions specified for that application domain.

5. Repeat the previous step for each permission set.
6. Click OK to close the setup window.

Specifying Additional Administrators to Remove the Web Part Package

By default, the Administrator who installed the Web Part package can remove the package. You can, however, specify additional Administrators who can remove the Web Part package by completing the following steps:

• Make the Administrator a member of the Administrators group on each Web server from which the Web Part package needs to be removed.
• Ensure that the Administrator has the correct SQL Server permissions to access SharePoint content and configuration databases. You can accomplish this by using one of the following techniques:
  • Create a SQL Server login for the new Administrator account with Database Creators and Security Administrators roles, and grant Database Access to all SharePoint content and configuration databases.
  • Make the Administrator a System Administrator on the SQL Server.

    Note   As System Administrator, the user is granted unlimited access to the computer running SQL Server.

• When installing the Windows Installer (.msi), specify that the installation is per computer rather than per user as follows:

  msiexec.exe MSI_NameManufacturer_Name.msi allusers=1 
  

In this way, Administrators other than the installer can remove a Web Part package using Add or Remove Programs.

Removing the Web Part Solution

To remove the Web Part solution, point to Start, Control Panel, and then click Add or Remove Programs. Click the MSI_Name in the list and then click Remove. Follow the prompts to remove the Web Part solution from the server computer.

Note   When you remove the Windows Installer, you also remove the code access security settings as well. If any of the actions fail when removing the Windows Installer and related settings, all messages are included in the log file.

Event Logging for Wppackager

Wppackager logs event messages during use. You can check the event log for information during packaging, installation, and removal of a Windows Installer. To do so, Wppackager logs all messages to %temp%/wppackager.log where %temp% is the user-specified temp folder. Wppackager includes four message types: Critical Error, Error, Warning, and Success.

• Critical Error   Messages that lead to termination of the process occurring during the time of the error, for example, those that occur during installation.
• Error   Errors that do not lead to a termination, but whose results may not be expected or consistent. For example, the installation completed but failed to apply the code access security permission setting for the assembly. In this case, installation is completed, but it adds this error message because the Web Part may not work properly due to a lack of permissions.
• Warning   Actions that were taken that the User should be aware of. For example, if a Web Part package was force installed, a warning message is added to the log to inform the user of the force install.
• Success   Indicators of a successful completion of the task.

Conclusion

You can use Wppackager to package and create a Windows Installer for a Web Part solution. Additionally, while packaging the Web Part, you can specify other permissions to set for the Web Part during installation. This automates installation so that Administrators can deploy Web Parts without knowing what code access security permissions to add or how to add them for Web Part assemblies. Administrators can install Web Part assemblies directly to the global assembly cache or to the BIN directory for the specified virtual servers according to the specified deployment plan. Administrators can also easily remove the Web Part solution by using Add or Remove Programs on the front-end Web server.