Introduction
Since I have been using Code Project as a reference for several years now, I finally decided to make a few contributions of my own. I have been writing some web part components for SharePoint for about two years and while it is not something I do on a regular basis I have made a few accidental discoveries that I will share with the readers of Code Project.
Some of the Microsoft SharePoint Documentation is not absolutely clear, and clarifying this is one of my goals for this article. I also decided that one of the best, most stable, and visible resources on the web for Microsoft Programmers is Code Project and thus far Code Project has lacked many articles on SharePoint Technologies Web Parts. That being one of my main interests, I decided I would help fill that void as best I can manage.
This particular article will focus on deployment of Web Part Components and cover the usage of the STSADM.exe utility that is an essential element of SharePoint Management. I will also cover the basics of creating a cab file in Visual Studio. There is an article here on Code Project that lays out the methods of building cab file manually. In my previous article (Part I) I covered elements of creating a basic Web Part.
Background
Required
- Windows 2003 Server
- Windows SharePoint Services v2.0
- Visual Studio 2003
- Web Part Templates
Optional (highly recommended)
Deploying Web Parts (Cabs, Utilities and MSI's)
There is no code included with this article as it is about adding details to the requirements of effectively deploying SharePoint Web Parts.
The main and most important utility for working with SharePoint is the stsadm.exe utility. STSADM fulfills several roles, some of which can be accomplished in the SharePoint web interface. One thing that the web interface can't do for you is install Web Parts so you are left with two choices in that regard. You can deploy Web Parts via an MSI (Microsoft Installer) file or you can do it via specially constructed cab files. The cab file install is the simplest and most easily created installation method. MSI would require an msi editor such as the infamous and very basic Orca (from the MS SDK), the Wise for MSI authoring environment which is pretty easy or equally as easy, the Install shield Installer environment. There are other msi authoring environments, but I am mostly not acquainted with them and won't bother to list them.
So let's settle in on using the cab builder that comes with Visual Studio 2003. If you haven't used it yet, you will if you are going to develop Web Parts. Assuming you have begun a Web Part Component project and this is included in a VS Solution, go to the root of the solution and add a new project, then go to Setup and Deployment Projects and click on the Cab template. You should choose an appropriate folder location in the file system. I usually add it to the root of my project so I don't have to search around to find the cab when I actually go to deploy it. The Cab project is now an empty project. You will eventually need to add the Primary Output and Content files from the main Web Part Project. First though you would have to fulfill other requirements of a properly defined Web Part Deployment Cab, you will need at least two more items.
You need to add two items to your Web Part Project:
- A Web Part DWP
- A WP Manifest
The Manifest (Manifest.xml) is required for a functional cab installation and the filename.dwp which supplies information to SharePoint itself.
<!---->
<?xml version="1.0"?>
<!-- You need only one manifest per CAB project for Web Part Deployment.-->
<!-- This manifest file can have multiple assembly nodes.-->
<WebPartManifest xmlns="http://schemas.microsoft.com/WebPart/v2/Manifest">
<Assemblies>
<Assembly FileName="AKWebPart.dll">
<!-- Use the <ClassResource> tag to specify resources
like image files or JScript files that your Web Parts use. -->
<!-- Note that you must use relative paths when
specifying resource files. -->
<!--
<ClassResources>
<ClassResource FileName="Resource.jpg"/>
</ClassResources>
-->
<SafeControls>
<SafeControl Namespace="AKWebPart" TypeName="*" />
</SafeControls>
</Assembly>
</Assemblies>
<DwpFiles>
<DwpFile FileName="AKWebPart.dwp"/>
</DwpFiles>
</WebPartManifest>
As you can see in the above example Manifest you have an entry to the dll (in this case AKWebPart.dll) and another to the .dwp file (AKWebPart.dwp). Additionally you have an entry to the main Assemblies Namespace. The cab when generated will add an additional file .osd which actually directs the setup api and the stsadm.exe utility as to how to handle the installation of your cab file.
<!---->
<?XML version="1.0" ENCODING='UTF-8'?>
<!DOCTYPE SOFTPKG SYSTEM "http://www.microsoft.com/standards/osd/osd.dtd">
<?XML::namespace href=http:
as="MSICD"?>
<SOFTPKG NAME="setupakwebpart" VERSION="1,0,0,0">
<TITLE> setupakwebpart </TITLE>
<MSICD::NATIVECODE>
<CODE NAME="AKWebPart">
<IMPLEMENTATION>
<CODEBASE FILENAME="AKWebPart.dll">
</CODEBASE>
</IMPLEMENTATION>
</CODE>
</MSICD::NATIVECODE>
</SOFTPKG>
The DWP is the next critical element in a properly formed cab deployment file an example:
<!---->
<?xml version="1.0" encoding="utf-8"?>
<WebPart xmlns="http://schemas.microsoft.com/WebPart/v2" >
<Title>Sample Web Part</Title>
<Description>A demonstration web part</Description>
<Assembly>AKWebPart</Assembly>
<TypeName>AKWebPart.AKWebPart</TypeName>
<!-- Specify initial values for any additional base class
or custom properties here. -->
</WebPart>
In the DWP file you can see that there is a reference to the XML Namespace for Web Parts V2 You will see a Place for Title and Description, both of these are useful in helping you locate your Web Part in a Web Part Gallery that can get filled very quickly. You would do well to consider giving good names to the web parts you might create. The Assembly is the Namespace of the component and the TypeName references the class name of your Web Part prefixed by the namespace. When you get to actually deploying a web part, you will see why this is important, so don't get bored yet.
So let's assume you have successfully compiled your Web Part and have generated the cab file, you will need to perform the next step in the process. you will need to copy your completed cab to the intended development server for some testing. you can accomplish this through several methods by using a unc copy such as //servername/C$/Program Files/Microsoft Shared/web server extensions/60/bin as one of the possibilities. This is the location of the stsadm.exe utiliity and this is what will help get your new cab file containing your new web part installed on the test server.
STSADM is critical to deploying your new part. It has a number of parameters required in order to fully install a Web Part. Some examples:
stsadm -o addwppack -filename yourcab.cab -url http://yourSPServerName
Simply put -o is the operation to be performed -filename is your new cabfile and -url is the Web servers name in URL format. stsadm has a few other parameters that are useful to know when installing and removing Web Parts.
To Remove a Web Part:
stsadm -o deletewppack -name yourcab.cab -url http://yourservename
To get a list of Web Parts installed after the initial deployment of SharePoint, the built-in default web parts don't show in stsadm use.
List: stsadm -o enumwppacks -url http://yourwebservername
Make note that the parameters change subtly from one operation to the other Adding parts addwppack -filename, Deleting Parts deletewppack -name, Listing Part enumwppacks. They all contain subtle differences so typing errors can occur.
After a successful deployment using addwppacks, you will need to perform two more operations to get to test your new Web Part.
First you have to reset IIS in order to make your new parts visible in SharePoint. Here you get to use the venerable iisreset command simple enough. Run iisreset and you will see the message Attempting Stop....... after successfully stopping you will see Attempting Start..... and with only a little luck, you will succeed in restarting the server.
You will need to go into SharePoints Web interface to make your new Web Part accessible to you and your users and do the following:
Possible Alternatives
There is the possibility that you could author the installation with a product like Wise, Install Shield, Visual Studio Setup Project or other MSI authoring utilities, but I am not prepared to tackle that one at the moment. Perhaps I can add another article in the future regarding Web Part Installs via MSI.
History
- This is Version One unless I spot an error or someone recommends some additions or changes.
