Web Part Deployment/Practices

Best Practices

9/7/2009
Contents
Purpose of the Document:..........................................................................................3
Intended Audience:....................................................................................................3
Technology:................................................................................................................3
Reference Project Name:............................................................................................3
Contributors:..............................................................................................................3
Requirement Scenario:...............................................................................................3
Work Scope in the Project..........................................................................................3
Solution Identified and Provided:................................................................................4
Deploying Web Part / Feature as SharePoint Solution Package (.wsp file)..................4
12 Hive.......................................................................................................................4
Solution File................................................................................................................4
Manifest.xml file and how it relates to the WSP file....................................................5
Feature.xml................................................................................................................9
Generating the WSP using a DDF file.......................................................................10
Creating Build.cmd file.............................................................................................12
Creating Installation.bat file.....................................................................................13
SharePoint Deployment Graphical Representation...................................................14
Web Part Deployment Example................................................................................15
Where it can be used:...............................................................................................23
Is this the Work Around or Best Solution:.................................................................23
Document / Product / Component Repository Path:.................................................23
Document / Product / Component Repository Path:

2
Purpose of the Document:
This document is used to illustrate the Web Part deployment process using ddf file.

Intended Audience:
SharePoint Developer

Technology:
Microsoft SharePoint Server 2007

Reference Project Name:

Triveris

Contributors:
➢ Arun k Sahu
➢ Amol Sortey
➢ Mahesh Patil

Requirement Scenario:
Client wants the automation process to deploy the web part as feature using .ddf
file.

Work Scope in the Project

To deploy the web part as feature using .ddf file.

3
Solution Identified and Provided:

Deploying Web Part / Feature as SharePoint Solution

Package (.wsp file)
SharePoint features, web parts, and files are deployed using a solutions file
with the extension wsp. The wsp files are actually just a “.cab” file, which is
the native Windows archive format. The content of the solutions file must
follow a particular schema.

12 Hive
12 hive is where SharePoint files are installed. When we deploy a solution
package using the stsadm.exe command:

stsadm -o addsolution -filename MyFeature.wsp

The stsadm command copies the files from the WSP to 12 hive. By default,
12 hive is located in C:\Program Files\Common Files\Microsoft Shared\web
server extensions\12 on the MOSS /WSS server.

Typically, when you create a new MOSS /WSS project, you replicate the
directory structure of 12 hive in your project. The reason will become
apparent later when we create the solution. In addition, if you plan to use a
tool like wspbuilder, the tool expects you to organize the directory in the
same manner as 12 hive.

Solution File
Solution file has an extension “.wsp”. Solution file contains everything
needed to deploy your Web Part/ feature. Solution file is just a cab file, so we
can open it by changing the extension from “.wsp” to “.cab” and then
double-clicking on it.
Here’s an example of the content of a WSP file:

4
Manifest.xml
MyFeature\Feature.xml
ControlTemplates\MyFeatureForm.ascx
MyFeature.dll

Notice the Manifest.xml file at the beginning. A solution file may hold a
variety of different files, but it always has a manifest.xml file. This manifest
file list what is in the solutions file?

Manifest.xml file and how it relates to the WSP file

manifest.xml file specifies how the WSP file is put together. It determines
what’s in the WSP file
Here’s what manifest.xml file for the above solutions file looks like:
<Solution SolutionId="4AFC9950-F354-4439-B941-51377E854F2B"
xmlns="http://schemas.microsoft.com/sharepoint/">
<FeatureManifests>
<FeatureManifest Location="MyFeature\Feature.xml"/>
</FeatureManifests>
<TemplateFiles>
<TemplateFile Location="ControlTemplates\MyFeatureForm.ascx"/>
</TemplateFiles>
<Assemblies>
<Assembly DeploymentTarget="GlobalAssemblyCache"
Location="MyFeature.dll">
<SafeControls>
<SafeControl Assembly="MyFeature, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=9f4da00116c38ec5"
Namespace="MyFeature" TypeName="MyFeature" Safe="True" />
</SafeControls>
</Assembly>
</Assemblies>
</Solution>

This manifest tells us that this WSP has an Assembly (.dll), a user control
(.ascx), and a feature.xml file. There may be additional files in WSP. You can
even embed a movie into the WSP. But unless the file is specified in the
manifest, the installer will skip over it during installation.

The root element of the manifest is always <Solution>. The solution ID is a

GUID that uniquely identifies your solution (the deployment package) to

5
SharePoint. When you create a new package, you must always create a new
GUID. The other elements specify what is in the WSP file and where to find
them via the location attribute. The location does actually follow the 12 hive,
but the root location will change according to the element type.

Let’s examine the element <FeatureManifest> the location is based on

root of the FEATURES at 12\TEMPLATE\FEATURES. If we deploy this WSP,
the location tells it to look for the feature.xml file in MyFeature directory in
the WSP file and deploy it to
12\TEMPLATE\FEATURES\MyFeature\feature.xml.

If we take a look at the element <TemplateFile> for the control

“MyFeatureForm.ascx”, the location is based on the root of the TEMPLATE,
which is at 12\TEMPLATE. If you examine 12\TEMPLATE in the hive, you’ll
notice that there is already a CONTROLTEMPLATES and there is already a list
of controls there. When we deploy, the manifest will tell the installer that the
file MyFeatureForm.ascx is located in ControlTemplates directory in the WSP
and that the MyFeatureForm.ascx should be deployed to
12\TEMPLATE\CONTROLTEMPLATES\MyFeatureForm.ascx.

The <Assembly> element specifies where the DLL is located. The root for
this element is the web application bin file if you specify
DeploymentTarget=”WebApplication”, and the GAC if you specify
DeploymentTarget=”GlobalAssemblyCache”. In the above example, the
<Assembly> element tells the installer to look in the root of the WSP file for
the MyFeature.dll and deploy it to the GAC, which is typically located in
C:\Windows\System32\Assembly on most systems.

The <SafeControls> element specifies Safe Control entry to web.config file

of the SharePoint site.
The following is a small table listing the element and where the root of the
location in the hive.

6
Manifest Element Location’s Root

ApplicationResourceFile 12\Resources

Assembly WebApplication bin or GAC

FeatureManifest 12\TEMPLATE\FEATURES

ResourceFile 12\TEMPLATE\FEATURES

RootFile 12

SiteDefinationManifest 12\TEMPLATE\SiteTemplates

TemplateFile 12\TEMPLATE

WebTemplateFile 12\TEMPLATE

Note: Each manifest element has a different root

For example, you want to group your user controls (.ascx) under a folder
(12\TEMPLATE\CONTROLTEMPLATES\MyProject\), instead of deploying your user
control files to 12\TEMPLATE\CONTROLTEMPLATES\ you can change the location
from

<TemplateFile Location="ControlTemplates\MyFeatureForm.ascx"/>

To

<TemplateFile Location="ControlTemplates\MyProject\MyFeatureForm.asc
x"/>

Features are always limited to one layer deep. If you try to specify
location=”MyProject\MyFeature\feature.xml” for a FeatureManifest element,
you will get an error message that you cannot go beyond one level deep. In
additon, specifying location=”Myproject\MyFeature.dll” doesn’t make sense
either because you’ll end up with a subdirectory inside the GAC.

7
More Information
The solution element defines the solutionId, just a new GUID and the deployment
server type.

The FeatureManifests element refers to the feature.xml files collection. You can
deploy many features with one solution. Just specify the different Feature folders,
You must define one feature.xml file for each feature.

You cannot name “feature.xml” file as anything other than the feature.xml . Doing
so yield following error.

"The feature path <FeatureName>\otherfeat.xml' must be of the form

directory\feature.xml".

The Assemblies element defines which assembly you are deploying. For timer
jobs you must deploy to the GAC, however for other items, you can choose
WebApplication as the deployment target. If you deploy as a webapplication, you
must add an entry into the web.config file located in the root of the virtual directory
of the target of the deployment which specifies the file as “SafeControl” in the
SafeControls Element.

<SafeControl Assembly="Assembly Name, Version, Culture, PublicKeyToken" Namespace="Namespace" TypeName="*" />

The “TemplateFiles“ element defines the location and files from your project needs
to fetched in order to copy to the 12 hive directory. You can define multiple files
from your project.

8
Feature.xml
<?xml version="1.0" encoding="utf-8"?>
<Feature Id="f98c395e-9ac0-4176-9323-11b5c0cba0ca" Title="MyFeature"
Scope="Site" Version="1.0.0.0" Hidden="FALSE" DefaultResourceFile="core"
xmlns="http://schemas.microsoft.com/sharepoint/">
<ElementManifests>
<ElementManifest Location="MyFeature\feature.xml" />
<ElementFile Location="MyFeature\MyFeature.webpart" />
</ElementManifests>
</Feature>

Feature Id : Generates your own GUID.

Title: Give the feature a meaningful title.

Description: Defines a meaningful description of the feature.

ElementManifest: points to other files that are going to describe things that need
to be deployed with your feature.

9
Generating the WSP using a DDF file
A DDF is basically an instruction file for building WSP files. Let’s examine the
DDF file used to build the WSP example.

This DDF file is placed in the root of the project folder.

.OPTION EXPLICIT
; Specify the output filename
.Set CabinetNameTemplate="MyFeature.wsp"
; Specify where to create the WSP file
.Set DiskDirectoryTemplate="..\Deployment"
; Compress the solution package
.Set CompressionType=MSZIP
; You always have a manifest file
manifest.xml
; Assembly gets placed in the top level
bin\Release\MyFeature.dll
; Features placed in location specify in FeatureManifest
.Set DestinationDir="MyFeature"
12\TEMPLATE\FEATURES\MyFeature\feature.xml
; User control placed in location specified in TemplateFile
.SET DestinationDir="ControlTemplates"
12\TEMPLATE\ControlTemplates\MyFeatureForm.ascx
1. CabinetNameTemplate: Sepecifies what the output file name is
going to be.

2. DiskDirectoryTemplate: It tells the builder where to put the output

file. (e.g. ..\Deployment). The path is relative to
the project’s home directory, so this will generate a Deployment
directory into your Visual Studio’s Solution directory and put the WSP
file there. The idea is when you compile, all of the WSP file for all
projects in the solution will end up in the same deployment directory.

3. The rest of the DDF handles the adding of files to the WSP archive. You
specify the file using a path relative to your project’s root. In the above

10
 example, the first file written is manifest.xml and it expects the file to
be in the root of the project. You can also place

this file in any of the directory of the solution , but in this case you
need to specify the relative path within the ddf file.

4. For the assembly, you recall the location for the Assembly in the
manifest was location=”MyFeature.dll”. The manifest expects this file
to be in the root of the WSP. In your Visual Studio, the path is
bin\Release\MyFeature.dll, so the builder will grab the file from your
bin directory and add it to the WSP’s root.

5. .SET DestinationDir: This element specifies that the next item

written is feature and the manifest expects it at
“MyFeature\Feature.xml”. What we
are doing is setting the write directory to “MyFeature” by setting the
DestinationDir. Now all files will be written to the MyFeature directory,
including the “12\TEMPLATE\FEATURES\MyFeature\feature.xml”.

6. Finally, we write the user control file. The TemplateFile location in our
manifest specifies that it will be located at
“ControlTemplates\MyFeatureForm.ascx”. We will use DestinationDir to
set it to “ControlTemplates” and then write the user control, which is
located in our project at
“12\TEMPLATE\ControlTemplates\MyFeatureForm.ascx”.

7. Similarly we can define other files in the ddf file including its relative
path provided the files should be mentioned in manifest.xml file with
its relative path.

The DDF file only defines how the WSP is build. A utility call makecab does
the actualy work. It reads the DDF file, copies the files in the DDF into the
wsp. One way to have the files generated automatically is to add a script to
the post compile event of your project.

11
cd "$(ProjectDir)"

Now when you compile your project, the event script will run and generate
the WSP file.

12
Creating Build.cmd file
The intent of this file is to generate the wsp file.
1. Create a build.cmd file
2. Edit the file and add the following command
MakeCab /f Package.ddf
3. Running Biuld.cmd file will generate a wsp file in the specified directory
.

13
Creating Installation.bat file

The intent of this file is to install the wsp file to the SharePoint site.

@echo off

set path=%path%;c:\program files\common files\microsoft shared\web server

extensions\12\bin

@echo on

stsadm -o addsolution -filename "Deployment\ MyFeature.wsp"

stsadm -o deploysolution -name MyFeature.wsp -url "<Enter your SharePoint url>"

-immediate

-allowgacdeployment -force

@pause

1. set path : Defines the 12 hive path of the SharePoint where the package
needs to deploy. In this case we are using “c:\program files\common
files\microsoft shared\web server extensions\12\bin”
2. stsadm -o addsolution-filename: Specifies the wsp file needs to deploy.
3. stsadm -o deploysolution: This command deploys the “MyFeature.wsp” to
the SharePoint site.
4. –url : Specifies the SharePoint site url.
5. –immediate: Allows user to deploy the wsp package immediately to the
SharePoint site.
6. -allowgacdeployment: Deploys the ‘.dll’ files in the GAC if specified in the
ddf and manifest.xml file. It also adds the SafeControl entry in the Web.config
file of the SharePoint site.

14
SharePoint Deployment Graphical Representation

15
Web Part Deployment Example

1. Create a Web Part Project

➢ Open Visual Studio 2008 IDE
➢ Go to “File>New >New Project”
➢ It will open a new dialog box.
➢ Select Visual Studio c# Projects category and then from templates list
select “Web Part” Project type.
➢ Give suitable name to your project.
➢ In this example “MyFeature” is the project name.
➢ Delete “WebPart1” folder from the project.
➢ To add new Web Part , right click on the Project and go to “Add > New
Item”.
➢ It will open a new dialog box window “Add New Item – Solution Items”
➢ Under Visual c# category select “SharePoint” subcategory. It will
display the templates available under this subcategory
➢ Select “Web Part” template and give the name to Web Part. In this
case “MyFeature”
➢ Now create 12 hive structure for your Web Part, if your Web Part holds
any other files.
➢ This project contains a user control named as
“MyFeatureForm.ascx” and “OCS.jpg” files located under
“TEMPLATE\CONTROLTEMPLATES” and
“TEMPLATE\LAYOUTS\MyFeatureImages” respectively. as shown
in fig 1.

16
Fig 1: “MyFeature” project structure.

➢ MyFeature.ascx file

<%@ Assembly Name="MyFeature, Version=1.0.0.0, Culture=neutral,

PublicKeyToken=9f4da00116c38ec5" %>
<%@ Control Language="C#" AutoEventWireup="true"
Inherits="MyFeature.MyFeatureForm" %>
<table cellpadding="2" cellspacing="2" border="0" width="70%" style="border-
collapse:collapse;">
<tr>

17
 <td width="25%" >
<img src="~/_layouts/MyFeatureImages/OCS.jpg" />
</td>
<td width="55%">
<asp:Label ID="lblTest" runat=server></asp:Label>
</td>
</tr>
</table>

➢ The assembly tag refers the code behind file for the user control.
➢ Add a new class to the project with name “MyFeatureForm.cs”.
➢ Inherit the class from “System.Web.UI.UserControl” and change the
protection level of class to public partial.
➢ Define the controls used in the “MyFeatureForm.ascx” control as
below

protected System.Web.UI.WebControls.Label lblTest;

➢ Page Load event

protected void Page_Load(object sender, EventArgs e)

{
try
{
lblTest.Text = "MyFeature Web Part";
}
catch (Exception ex)
{
throw new Exception(ex);
}
}

➢ Now Create a folder under Web Part folder to create a deployment

package.
➢ Create a feature.xml file with unique feature id for the Web Part as
shown below.

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

<Feature Id="35910dbe-4a1e-4815-af16-1f843afc4c17" Title="MyFeature"
Scope="Site" Version="1.0.0.0"

18
 Hidden="FALSE" DefaultResourceFile="core"
xmlns="http://schemas.microsoft.com/sharepoint/">
<ElementManifests>
<ElementManifest Location="MyFeature\MyFeature.xml" />
<ElementFile Location="MyFeature\MyFeature.webpart" />
</ElementManifests>
</Feature>

➢ Create “manifest.xml” file with unique solution id

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

<Solution SolutionId="16235e9c-8454-43b0-9b67-823f26874e4b"
xmlns="http://schemas.microsoft.com/sharepoint/">
<FeatureManifests>
<FeatureManifest Location="MyFeature\feature.xml" />
</FeatureManifests>
<Assemblies>
<Assembly Location="MyFeature.dll" DeploymentTarget="GlobalAssemblyCache">
<SafeControls>
<SafeControl Assembly="MyFeature, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=9f4da00116c38ec5"
Namespace="MyFeature" TypeName="MyFeature" Safe="True" />
</SafeControls>
</Assembly>
</Assemblies>
<TemplateFiles>
<TemplateFile Location="CONTROLTEMPLATES\MyFeatureForm.ascx" />
<TemplateFile Location="LAYOUTS\MyFeatureImages\OCS.jpg" />
</TemplateFiles>
</Solution>

Note: Description of the manifest file is explained in “Manifest.xml file and how
it relates to the WSP file” section

➢ Now edit the “MyFeatute.xml” file and change the file path element.

<File Path="MyFeature.webpart" Url="MyFeature.webpart"

Type="GhostableInLibrary" />

To

<File Path="MyFeature/MyFeature.webpart" Url="MyFeature.webpart"

Type="GhostableInLibrary" />

<Elements Id="f604cf76-eafe-4299-9f99-9467e3f0a403"
xmlns="http://schemas.microsoft.com/sharepoint/" >

19
 <Module Name="WebParts" List="113" Url="_catalogs/wp">
<File Path="MyFeature/MyFeature.webpart" Url="MyFeature.webpart"
Type="GhostableInLibrary" />
</Module>
</Elements>

➢ Create a MyFeature.ddf file

.OPTION Explicit
.Set CabinetNameTemplate=MyFeature.wsp
.Set DiskDirectoryTemplate=CDROM ; All cabinets go in single directory
.Set CompressionType=MSZIP ; All files compressed in cabinet files
.Set UniqueFiles="ON"
.Set Cabinet=on
.Set DiskDirectory1=Package

manifest.xml manifest.xml
feature.xml MyFeature\feature.xml
..\MyFeature.webpart MyFeature\MyFeature\MyFeature.webpart
..\MyFeature.xml MyFeature\MyFeature\MyFeature.xml

..\..\bin\Debug\MyFeature.dll MyFeature.dll

.Set DestinationDir=CONTROLTEMPLATES
..\..\TEMPLATE\CONTROLTEMPLATES\MyFeatureForm.ascx

.Set DestinationDir=LAYOUTS\MyFeatureImages
..\..\TEMPLATE\LAYOUTS\MyFeatureImages\OCS.jpg

➢ Create build.cmd file to generate .wsp file (MyFeature.ddf)

makecab /f MyFeature.ddf
pause

➢ Create “InstallMyFeature.bat” to install feature/Web Part to the Share

Point site.

20
@echo off
set path=%path%;c:\program files\common files\microsoft shared\web server
extensions\12\bin
@echo on
stsadm -o addsolution -filename "Package\MyFeature.wsp"

stsadm -o deploysolution -name MyFeature.wsp -url "--Enter your sharepoint

url" -immediate -allowgacdeployment -force
@pause

➢ The final project structure with deployment package is shown below.

Fig 2: Complete “MyFeature” project structure with deployment package.

21
➢ Open the files in Explore window.
➢ Run build.cmd file.
➢ It will create “MyFeature.wsp” file.
➢ Run InstallMyFeature.bat file.

➢ It will Install the Feature/Web Part to the Share Point site .

➢ Go to Web Part gallery and add the web part to the web Part’s gallery.
➢ Now edit Web Part Page and click on “Add a Web Part .”
➢ It will open a Web Part dialog having list of all Web Parts Installed.
➢ Locate the “Miscellaneous” category and select “My Feature” Web
Part from the list.
➢ Click on Add, the Web Part will get added to the Web Part page.

22
Fig 3 : Add a Web Part.

23
Fig 4: My Feature Web Part

Where it can be used:

This process can be used while deploying web parts for any of the SharePoint site.

Document / Product / Component Repository Path:

This will be stored in Intranet.

24