webpart deployment
TRANSCRIPT
Best Practices
9/7/2009
ContentsPurpose 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
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.xmlMyFeature\Feature.xmlControlTemplates\MyFeatureForm.ascxMyFeature.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.
5
The root element of the manifest is always <Solution>. The solution ID is a GUID that uniquely
identifies your solution (the deployment package) to 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 RootApplicationResourceFile 12\ResourcesAssembly WebApplication bin or GACFeatureManifest 12\TEMPLATE\FEATURESResourceFile 12\TEMPLATE\FEATURESRootFile 12SiteDefinationManifest 12\TEMPLATE\SiteTemplatesTemplateFile 12\TEMPLATEWebTemplateFile 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.ascx"/>
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 filemanifest.xml; Assembly gets placed in the top levelbin\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 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
10
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.
cd "$(ProjectDir)"
Now when you compile your project, the event script will run and generate the WSP file.
11
Creating Build.cmd file
The intent of this file is to generate the wsp file.
1. Create a build.cmd file2. 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 .
12
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.
13
SharePoint Deployment Graphical Representation
14
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.
15
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> <td width="25%" > <img src="~/_layouts/MyFeatureImages/OCS.jpg" /> </td> <td width="55%"> <asp:Label ID="lblTest" runat=server></asp:Label> </td>
16
</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" Hidden="FALSE" DefaultResourceFile="core" xmlns="http://schemas.microsoft.com/sharepoint/"> <ElementManifests> <ElementManifest Location="MyFeature\MyFeature.xml" /> <ElementFile Location="MyFeature\MyFeature.webpart" /> </ElementManifests></Feature>
17
<?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>
Create “manifest.xml” file with unique solution id
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/" > <Module Name="WebParts" List="113" Url="_catalogs/wp"> <File Path="MyFeature/MyFeature.webpart" Url="MyFeature.webpart" Type="GhostableInLibrary" /> </Module></Elements>
18
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.xmlfeature.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.ddfpause
Create “InstallMyFeature.bat” to install feature/Web Part to the Share Point site.
@echo offset path=%path%;c:\program files\common files\microsoft shared\web server extensions\12\bin@echo onstsadm -o addsolution -filename "Package\MyFeature.wsp" stsadm -o deploysolution -name MyFeature.wsp -url "--Enter your sharepoint url" -immediate -allowgacdeployment -force@pause
19
The final project structure with deployment package is shown below.
Fig 2: Complete “MyFeature” project structure with deployment package.
Open the files in Explore window.
Run build.cmd file.
It will create “MyFeature.wsp” file.
Run InstallMyFeature.bat file.
20
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.
21
Fig 3 : Add a Web Part.
22
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.
23