How to: Deploy a Health Rule with a Solution Package

Applies to: SharePoint Foundation 2010

In your development environment, deploying a new health rule is straightforward and simple. You can manually install the assembly that contains your rule by using the Global Assembly Cache Tool (Gacutil.exe) to place the assembly in the Global Assembly Cache (GAC) of your development server. If you have created a SharePoint Feature to register the rule with SharePoint Health Analyzer, you can manually install the Feature by using the SharePoint Management Shell to run the following Windows Powershell cmdlet: Install-SPFeature. You can use the following Windows Powershell cmdlet to activate the Feature and register the rule: Enable-SPFeature.

The manual procedure is not practical in a production environment where the server farm is likely to consist of multiple servers—and where additional servers are likely to be brought online over time. In a production environment, the best approach is to use a solution package. You can upload a solution package once, and the solution is propagated across all servers in the farm. When new servers are brought online, they get the solution automatically as part of their provisioning.

This topic explains how to create a solution package that contains a health rule, and how to upload and deploy the solution to a server farm. The topic assumes that you have completed the procedures described in How to: Create a Health Rule and How to: Create a Feature to Register a Health Rule.

Creating the Solution Package

A solution package is a CAB file with a .wsp filename extension that contains all the files that must be deployed on servers in the farm. Because we are using a solution package to deploy a health rule, the package will install two files: feature.xml and the assembly for the rule. Each solution package must also contain a file named manifest.xml that includes instructions for installing the solution.

The first step in creating a solution package is to create manifest.xml. The second step is to create a Diamond Directive File (.ddf) that instructs the MAKECAB.EXE command-line utility what files to include in the output CAB file. The last step is to use MAKECAB.EXE to compile the CAB file.

To create the manifest for a solution package

1. Open Visual Studio as an administrator by right-clicking the program in the Start menu and selecting Run as administrator.

2. Open the project that contains the code for your health rule.

3. Create a Solution folder.

   In Solution Explorer, right-click the project name, choose Add, and choose New Folder. Type Solution.

4. Create a solution manifest file.

   Right-click the Solution folder, choose Add, and then choose New Item.... In the Add New Item dialog, select the XML File template. Name the file manifest.xml. Then click Add.

5. Open manifest.xml in the editor.

6. Delete the first (and only) line in the file. In its place, paste the following code.

   <Solution SolutionId="00000000-0000-0000-0000-000000000000"
             xmlns="https://schemas.microsoft.com/sharepoint/">
     <FeatureManifests>
       <FeatureManifest Location="FeatureFolderName\feature.xml" />
     </FeatureManifests>
     <Assemblies>
       <Assembly DeploymentTarget="GlobalAssemblyCache"
                 Location="AssemblyName.dll" />
     </Assemblies>
   </Solution>
   

7. Replace the value of the SolutionId attribute with a newly generated GUID (without braces).

   You can use the GuidGen Tool (guidgen.exe) to get a new GUID. On the Tools menu in Visual Studio, choose Create GUID. In the Create GUID dialog, select 4. Registry Format, then click Copy. Paste the content of the clipboard between the quotation marks after the SolutionId attribute. Remove the braces from the GUID.

8. Modify the value of the FeatureManifest element’s Location attribute, replacing "FeatureFolderName" with the name of the folder in your solution that contains the feature.xml file.

   When the solution is deployed, a folder with the same name is created in the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\FEATURES folder of every server in the farm.

9. Modify the value of the Assembly element’s Location attribute, replacing "AssemblyName.dll" with the filename of your rule’s assembly.

10. Save manifest.xml.

To create a directive file for the solution package

1. Create a package folder in your Visual Studio project.

   In Solution Explorer, right-click the project name, choose Add, and choose select New Folder. Type Package.

   This is the output directory for the MAKECAB.EXE command-line utility.

2. Create a Diamond Directive File (.ddf) in the Solution folder of your Visual Studio project.

   In Solution Explorer, right-click the folder named Solution, choose Add, and then choose New Item.... In the Add New Item dialog, select the Text File template. Name the file cab.ddf. Then click Add.

   This file will be used with the MAKECAB.EXE command-line utility.

3. Open cab.ddf in the editor. Copy the following markup and paste it into the cab.ddf file.

   .OPTION EXPLICIT     ; Generate errors 
   .Set CabinetNameTemplate=SolutionName.wsp
   .set DiskDirectoryTemplate=CDROM ; All cabinets go in a single directory.
   .Set CompressionType=MSZIP;** All files are compressed in cabinet files.
   .Set UniqueFiles="ON"
   .Set Cabinet=on
   .Set DiskDirectory1=Package ; This is the output directory.
   
   ; Files to include.
   Solution\manifest.xml manifest.xml
   FeatureFolderName\feature.xml FeatureFolderName\feature.xml
   bin\Release\AssemblyName.dll AssemblyName.dll
   

4. Modify the value of the CabinetNameTemplate argument, replacing "SolutionName" with the filename that you want to use for your solution package. (Keep the .wsp file extension.)

5. Replace "FeatureFolderName" (it occurs twice) with the name of the folder in your solution that contains the file feature.xml.

6. Replace "AssemblyName.dll" (it occurs twice) with the filename of your rule’s assembly. In addition, if the relative path to the assembly is not "bin\Release\", replace that string with the correct path.

7. Save cab.ddf.

To create the solution package file

1. Open a Visual Studio command prompt.

2. Navigate to the directory for your Visual Studio project.

   The file paths in cab.ddf and in the command that is issued in the next step are relative to the Visual Studio project directory.

3. At the command prompt, issue the following command:

   makecab /f solution\cab.ddf
   

   A solution package is created in the Package folder.

Uploading and Deploying the Solution

After you create a new solution package, you should test it on a SharePoint installation, preferably on a clean image rather than on your development server. This involves two tasks: First, you must upload the solution package to the server farm. Second, you must deploy the solution.

To upload and deploy a solution package to the farm

1. Open SharePoint Management Shell as an administrator by right-clicking the item on the Start/Administrative Tools menu and then selecting Run as administrator.

2. At the command prompt, issue the following command to upload the solution. (Substitute the full path and filename for your solution package.)

   add-spsolution -literalpath <full path and filename.wsp>
   

   The solution package is now uploaded to the server farm.

3. At the command prompt, issue the following command to deploy the solution. (Substitute the correct filename for your .wsp file.)

   install-spsolution -identity filename.wsp -force -gacdeployment
   

Your health rule is now installed and registered. You can verify this by checking the Health Analyzer Rule list in the Monitoring section of Central Administration.

See Also

Tasks

How to: Create a Health Rule

How to: Create a Feature to Register a Health Rule

Concepts

Manually Creating Solutions in SharePoint Foundation

Other Resources

Automating Solution Package Creation for Windows SharePoint Services by Using MSBuild