Webpart Deployment

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/"> <SafeControls> <SafeControl Assembly="MyFeature, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9f4da00116c38ec5" Namespace="MyFeature" TypeName="MyFeature" Safe="True" />



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 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 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 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 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 To

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 \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

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" %>

17



➢ 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.
18

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

➢

Create “manifest.xml” file with unique solution id

<Solution SolutionId="16235e9c-8454-43b0-9b67-823f26874e4b" xmlns="http://schemas.microsoft.com/sharepoint/"> <SafeControls> <SafeControl Assembly="MyFeature, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9f4da00116c38ec5" Namespace="MyFeature" TypeName="MyFeature" Safe="True" />

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. To

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

19

<Module Name="WebParts" List="113" Url="_catalogs/wp">

➢ 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