Packaging and Deploying Web Parts for Microsoft

Windows SharePoint Services

Suraj Poozhiyil and Jeremy Martin

Microsoft Corporation

May 2003

Applies to:

Microsoft® Windows® SharePoint™ Services

Microsoft Office SharePoint Portal Server 2003

Microsoft Visual Studio® .NET

Web Part infrastructure

Summary: Learn how to package and deploy Web Parts by using the administration tools provided with

Microsoft Windows SharePoint Services. (12 printed pages)

Note The information in this article also applies to Microsoft Office SharePoint Portal Server 2003, which
is built on the Windows SharePoint Services platform.

Contents

Introduction

Building a Web Part Package

Deploying a Web Part Package

Adding a Web Part Package

Deleting a Web Part Package

Enumerating a Web Part Package

Switches

Installing a Web Part Package

Conclusion

Introduction

Web Parts are more than just the assemblies into which they are compiled. A Web Part may have class

resources such as images, Microsoft JScript® files, and Help files. These files may also be localized and

deployed in locations that are different from the location of the Web Part. Additionally, the Web Part must

be added to the SafeControl list for the specific virtual server before users can take advantage of its

functionality.

Prerequisites
 • Familiarity with Microsoft Windows® SharePoint™ Services and/or Microsoft Office SharePoint

Portal Server 2003

• Knowledge about how to create a Web Part

• Familiarity with the Web Part infrastructure

Building a Web Part Package

A Web Part package is a cabinet (.cab) file that contains the following items:

1. Manifest.xml (mandatory)

2. Web Part assemblies (optional)

3. Class resource files (optional)

4. .dwp files (optional)

Creating a Manifest File for a .cab File

The Manifest file, a configuration file that describes the structure and contents of the .cab file, is the only

required component for the .cab file. The Stsadm.exe tool uses this file to deploy the remaining content of

the .cab file.

The following table describes the nodes and subnodes in the Manifest.xml file.

Node Parent Node Description

WebPartManifest WebPartManifest Defines the schema of the XML.

Assemblies WebPartManifest Contains definitions for each of the

assemblies being deployed.

Assembly Assemblies Uses the FileName attribute to

define the assembly file name,
contains the definitions for the
class resources, and contains the
XML for the SafeControls list.

ClassResources Assembly Contains the definitions for each

class resource being deployed.

ClassResource ClassResources Uses the FileName attribute to

define the class resource file
name.

SafeControls Assembly Contains the definitions for each

line of XML in the SafeControls
list.

SafeControl SafeControls Defines each line of the

SafeControls list.

DwpFiles WebPartManifest Contains definitions of each .dwp

file being deployed.

DwpFile DwpFiles Uses the FileName attribute to

define the file name of the .dwp
 file.

The following example shows a manifest file for a package that deploys two assemblies and their

resources:

<?xml version="1.0" encoding="utf-8" ?>

<WebPartManifest
xmlns="http://schemas.microsoft.com/WebPart/v2/Manifest">

<Assemblies>

<Assembly FileName="WebPartLibrary1.dll">

<ClassResources>

<ClassResource FileName="image1.gif"/>

<ClassResource FileName="image2.gif"/>

</ClassResources>

<SafeControls>

<SafeControl Namespace="WebPartLibrary1" TypeName="*"/>

</SafeControls>

</Assembly>

<Assembly FileName="WebPartLibrary2.dll">

<ClassResources>

<ClassResource FileName="MyCustomHelp.htm"/>

<ClassResource FileName="LargeIcon.gif"/>

</ClassResources>

<SafeControls>

<SafeControl Namespace="WebPartLibrary2" TypeName="*"/>

</SafeControls>

</Assembly>

</Assemblies>

<DwpFiles>

<DwpFile FileName="WebPart1.dwp"/>
 <DwpFile FileName="WebPart2.dwp"/>

</DwpFiles>

</WebPartManifest>

Creating a .cab File

Developers can use either of the following methods to create a .cab file:

• Use Microsoft Visual Studio® .NET Professional to create a CAB Project.

• Use MakeCAB.exe, a command-line tool included with Microsoft Windows 2000 and later.

Using Visual Studio

To use Visual Studio.NET Professional to create a CAB project, follow these steps:

1. Start Visual Studio .NET.

2. Create a new solution.

• On the File menu, point to New, and then click Blank Solution.

• Type a name for the solution, and then click OK.

3. Open the Web Part project within this solution.

• In Solution Explorer, right-click the new solution, point to Add, and then click Existing

Project.

• Browse to the location of Web Part project that you want to add, click the project, and

then click Open.

4. Create a new CAB project

• In Solution Explorer, right-click the new solution, point to Add, and then click New

Project.

5. Under Project Types, click Setup and Deployment Projects, and then under Templates,
click Cab Project.

• Type a name for the CAB project, and then click OK.

6. Add the Web Part project output to the CAB project.

• In Solution Explorer, right-click the CAB project, point to Add, and then click Project

Output.

• In the Project box, click the Web Part project that you added to the solution in step 3.
 • Select all the appropriate file categories that appear in the list, and then click OK.

Make sure that you select Primary output and Content Files. These categories add the

Manifest.xml file, the .dwp files, and the Web Part assembly to the .cab file. Verify that the

Manifest.xml file and the .dwp files are marked as content for build action in their respective

properties sheets.

7. Build the solution to create the .cab file.

Using MakeCAB.exe

MakeCAB.exe is a tool included with Windows 2000 or later. To use MakeCAB.exe to create a .cab file,

follow these steps:

1. Create a directive file for makecab.exe, and save the file with a .ddf extension. The following
sample directive file (named sample.ddf) creates a .cab file for a simple Web Part library project:

2. ;*** Sample Source Code MakeCAB Directive file example

3. ;

4. .OPTION EXPLICIT ; Generate errors

5. .Set CabinetNameTemplate=SampleCab.cab

6. .set DiskDirectoryTemplate=CDROM ; All cabinets go in a single

7. directory

8. .Set CompressionType=MSZIP;** All files are compressed in cabinet

files

9. .Set UniqueFiles="OFF"

10. .Set Cabinet=on

11. .Set DiskDirectory1=SAMPLECAB.CAB

12. manifest.xml

13. WebPart1.dwp

14. WebPartLibrary1.dll

15. ;*** <the end>

16. Copy all the files that you want to include in the .cab file into the directory where you created the
.ddf file. In this example, these files are the Manifest.xml file, the WebPart1.dwp file, and the
WebPartLibrary1.dll file.

17. Open a command prompt, change to the directory that contains the .ddf file and the files that you
want to include in the .cab file, and then run the following command:
 18. Makecab.exe /F sample.ddf

MakeCAB.exe creates a directory named SAMPLECAB.CAB, and in this directory MakeCAB.exe creates a

.cab file named SampleCab.cab that contains the three files listed in the Sample.ddf directive file.

For more information about MakeCAB.exe, download the Microsoft Cabinet Software Development Kit.

Creating a CAB File with Localized Resources

Visual Studio does not support creating .cab files with internal directories. However, localized Web Parts

may require a .cab file with internal directories. Because of this you must use a tool like MakeCAB.exe or

another, third-party CAB utility to deploy localized Web Parts.

The following example describes how to create a .cab file for an English language Web Part project named

SampleWebPartLibrary that also provides German localized resources. The .cab file in this example is

named Sample.cab, and it must include the following files:

• SampleWebPartLibrary.dll

• Help.htm

• Image1.gif

• WebPart1.dwp

• de-DE/Help.htm

• de-DE/Image1.gif

• de-DE/WebPart1.dwp

To create the .cab file for this example Web Part project, follow these steps:

1. Create the appropriate Manifest.xml file. The following example shows the Manifest.xml file for
the Sample.cab file:

2. <?xml version="1.0" encoding="utf-8" ?>

3. <WebPartManifest

4. xmlns="http://schemas.microsoft.com/WebPart/v2/Manifest">

5. <Assemblies>

6. <Assembly FileName="SampleWebPartLibrary.dll">

7. <ClassResources>

8. <ClassResource FileName="image1.gif"/>
9. <ClassResource FileName="help.htm"/>

10. <ClassResource FileName="de-DE\image1.gif"/>

11. <ClassResource FileName="de-DE\help.htm"/>

12. </ClassResources>

13. <SafeControls>

14. <SafeControl Namespace="SampleWebPartLibrary"

15. TypeName="*"/>

16. </SafeControls>

17. </Assembly>

18. </Assemblies>

19. <DwpFiles>

20. <DwpFile FileName="WebPart1.dwp"/>

21. <DwpFile FileName="de-DE\WebPart1.dwp"/>

22. </DwpFiles>

23. </WebPartManifest>

24. Create the appropriate Makecab.exe directive file. The following example shows the directive file
for the Sample.cab file:

25. ;*** Sample Source Code MakeCAB Directive file example

26. ;

27. .OPTION EXPLICIT ; Generate errors

28. .Set CabinetNameTemplate=Sample.cab

29. .set DiskDirectoryTemplate=CDROM ; All cabinets go in a single

30. directory

31. .Set CompressionType=MSZIP ;** All files are compressed in

cabinet

32. files

33. .Set UniqueFiles="OFF"

34. .Set Cabinet=on

35. .Set DiskDirectory1=SAMPLE.CAB

 36. manifest.xml

37. WebPart1.dwp

38. SampleWebPartLibrary.dll

39. Image1.gif

40. help.htm

41. .Set DestinationDir=de-DE

42. de-DE\WebPart1.dwp

43. de-DE\image1.gif

44. de-DE\help.htm

45. ;*** <the end>

46. Copy all the files that you want to include in the .cab file into the directory where you created the
.ddf file, and copy all of the localized resources into the appropriate subdirectories. The following
example shows the directory structure for the Sample.cab file:

47. \Directory with directive file

48. Sample.ddf

49. Manifest.xml

50. SampleWebPartLibrary.dll

51. WebPart1.dwp

52. Image1.gif

53. Help.htm

54. \de-DE

55. WebPart1.dwp

56. Image1.gif

57. Help.htm

58. Open a command prompt, change to the directory that contains the .ddf file and the files that you
want to include in the .cab file, and then run the following command to create a subdirectory in the
Sample.cab file and prepare the Sample.cab file for deployment:

59. Makecab.exe /F sample.ddf

Deploying a Web Part Package

Administrators can use the Stsadm.exe tool to deploy .cab files created by developers. Stsadm.exe is a

command-line tool that you can use to manage a Windows SharePoint Services computer. Three

Stsadm.exe options apply to Web Part package deployment:

• AddWPPack

• DeleteWPPack

• EnumWPPacks

For more information about a specific Stsadm.exe command-line option, type the following line at a

command prompt:

stsadm –help option

Adding a Web Part Package

To use the Stsadm.exe command to deploy a Web Part package on a server computer running Windows

SharePoint Services, open a command prompt, and then type the following command:

stsadm.exe -o addwppack

-filename Web_Part_Pack_name

[-url URL]

[-globalinstall]

[-force]

If you want to install a Web Part package on a virtual server when the Web Part package is already

installed on another virtual server on the same computer, use the following command:

stsadm.exe -o addwppack

-name Web_Part_Pack_name

[-url URL]

[-globalinstall]

[-force]

Switches

The following table describes Stsadm.exe command-line switches that support adding Web Part packages.

Switch Description
 Specifies the URL of the virtual server on which you
-url want to install the Web Part package.
Note If you do not use this switch, then the
package is installed on all Windows SharePoint
Services-enabled virtual servers on the computer.

Installs a Web Part package to a virtual server from

-name the Configuration database. When the package is
installed on the computer for the first time,
Stsadm.exe makes a copy of the .cab file in the
Configuration database. In a server farm
deployment, after the administrator installs a Web
Part package on the front-end Web server, you can
install the Web Part package on all front-end Web
servers without a local copy of the .cab file.

Installs the Web Part package to the global

-globalinstall assembly cache (GAC). Only strong-named Web
Part assemblies in the Web Part package are
installed to the GAC; all other assemblies are
installed in the Bin directory of the virtual server.

Forces Stsadm.exe to overwrite an installed Web

-force Part package. If the Web Part package specified on
the command line already exists on the server, you
can use this switch to overwrite that package.

Forces Stsadm.exe to use the .cab file specified by

-filename the path on the command line.

Deleting a Web Part Package

To delete a Web Part package from specified virtual servers on a computer running Windows SharePoint

Services, open a command prompt, and then type the following command:

stsadm.exe -o deletewppack

-name Web_Part_Pack_name

[-url URL]

Switches

The following table describes Stsadm.exe command-line switches that support deleting Web Part

packages.

Switch Description

Used to specify the Web Part package to delete.

-name

Specifies the URL of the virtual server that contains

-url the Web Part package that you want to delete.
Note If you do not use this switch, then the
package is deleted from all Windows SharePoint
Services-enabled virtual servers on the computer.
Enumerating a Web Part Package

To list all the Web Part packages installed on a computer running Windows SharePoint Services, open a

command prompt, and then type the following command:

stsadm.exe -o enumwppacks

[-name Web_Part_Pack_name]

[-url URL]

[-farm]

Switches

The following table describes Stsadm.exe command-line switches that support enumerating Web Part

packages.

Switch Description

Determines if the specified Web Part package is

-name installed.

Specifies the URL of the virtual server that contains

-url the Web Part packages that you want to enumerate.
If you do no use this switch, then the list includes all
packages that are installed on all Windows
SharePoint Services-enabled virtual servers on the
computer.

Enumerates all the Web Part packages that are

-farm installed on a server farm deployment of Windows
SharePoint Services.

Installing a Web Part Package

To decide whether to install a Web Part package in the GAC or in the Bin directory, ask the following

questions:

• Do you want to make this package available to all virtual servers on your computer?

• Do you trust the assemblies and resources of the package completely?

If you answer "yes" to both of these questions, install the Web Part package to the GAC. Assemblies in the

GAC are fully trusted and are available to all virtual servers.

The following table lists the differences between installing to the GAC and installing to the Bin directory.

Item GAC Bin directory

Assembly location local_drive:\Windows\Assembly local_drive:\virtual_server_file

 system_location\bin

Class resources local_drive:\Program local_drive:\ virtual_server_file

Files\Common Files\Microsoft system_location\wpresources
Shared\Web Server
Extensions\wpresources
URL:

URL: http://virtual_server/wpresources

http://virtual_server/_wpresources

Default Security Trust Level Full Partial (WSS_Minimal)

Accessible by all Virtual Yes (The assemblies and types No (The Web Part package is only
Servers must be enabled in the accessible from the virtual server on
SafeControls list for each virtual which the assembly is installed.)
server)

Pre-requisites for using The assembly must be a strong-

Stsadm.exe named assembly.

Requires using the Yes No

-globalinstall switch.
Note If you install the assembly to the Bin directory and the assembly requires code access security
permissions that exceed the default policy for the Bin directory, you can assign these permissions after
the deployment is complete. For information about code access security, see the Microsoft Windows
SharePoint Services 2.0 Software Development Kit (SDK) available from the Microsoft SharePoint Products
and Technologies Developer Center.

Conclusion

You can use Stsadm.exe to deploy Web Part packages to the GAC or to the Bin directory for specified

virtual servers. This allows you to deploy Web Part packages across an entire organization or only to a

limited set of sites according to your requirements.