September 2008 - Posts - Tech Talk with Brett Maytom

SharePoint - Creating a Solution Manifest

Provisioning a solution to a SharePoint server can be done using several methods, however the only correct methods are to use templates and solution packages. In my series of posts on provisioning, discussed the relevance of provisioning, if this is your first article you are reading, I would suggest looking at Overview of features, templates, site definitions, solutions in SharePoint and SharePoint - Overview to creating a Solution Package.

Now, remember WSS is a powerful provisioning engine and is geared up to deploy web sites and components. These can be deployed to a single or multiple servers in a web farm with ease. Provisioning is easy once you get to grips with the WSS provisioning engine, the most important thing is follow the rules and you will not have issues deploying to SharePoint. I strongly urge you to master this deployment mechanism especially solutions and solution packages, it is not conventional deployment as it is geared to SharePoint.

After you have created the content of your new SharePoint functionality, that is features, web parts, assemblies, pages, resources etc; you will have to register them into a solution manifest file. The manifest file is an xml file that follows the CAML schema and has a <Solution...> root element. When the solution is deployed using a package, SharePoint will open up the .wsp file looking for this solution manifest. It will then proceed to extract and register everything in the solution manifest.

The basic schema of a solution manifest

<Solution
  DeploymentServerType = "ApplicationServer"
  ResetWebServer = "TRUE"
  SolutionId = "GUID">
  <ApplicationResourceFiles />
  <Assemblies />
  <CodeAccessSecurity />
  <DwpFiles />
  <FeatureManifests />
  <Resources />
  <SiteDefinitionManifests />
  <RootFiles />
  <TemplateFiles />
</Solution>

The attributes are

DeploymentServerType
	Optional. Default=WebFrontEnd. This attribute indicates the target of your solution to either a web front end server (WebFrontEnd) or an application server (ApplicationServer).
ResetWebServer
	Optional. Default=FALSE. Indicates a boolean value whether the web server needs to be reset after the solution is deployed.
SolutionId
	Required. A globally unique identifier that should be created for the solution. Each solution should have its own unique GUID.

What can be deployed using a solution manifest

Application Resource Files
	In order to globalise your solution and templates, you will need to create resource files for each localised language. These resource files should be placed into the 12\Resources directory. Using a solution, you will be able to deploy these resources files. Note that the resorce files are globally available to the entire application across different servers and web applications. The basic schema for the ApplicationResourceFiles element is shown below <ApplicationResourceFiles> <ApplicationResourceFile Location="Text"/> . . </ApplicationResourceFiles>
Assemblies
	The most useful thing about a solution is that it can deploy your assemblies into either the local bin folder of a site that uses the assembly or it can register the assembly in the Global Assembly Cache (GAC). Now for the infomercial, "However when you buy into this concept; the provisioning engine will allow you to automatically register these assemblies as SafeControls ... absolutely for free" . It is simply done by putting a <SafeControl> element in the manifest and it will be done. Again this will be deployed onto all servers in a web farm making your assembly available on all servers, and automatically registered in all servers web.config files. The basic schema for the Assemblies element is shown below <Assemblies> <Assembly DeploymentTarget = "GlobalAssemblyCache" Location = "Text"> <SafeControls> <SafeControl Assembly = "Text" Namespace = "Text" Safe = "TRUE" TypeName = "Text"/> ... </SafeControls> <ClassResources> <ClassResource FileName = "Text" Location = "Text"> </ClassResource> ... </ClassResources> </Assembly> . . </Assemblies>
Code Access Security
	By default, assemblies deployed into the bin folder are sandboxed with a very restrictive trust level. You will need to define the appropriate trust level of your assembly especially if you access local resources or play with the WSS object model. Should you not do this your assembly will fail in a production environment. The basic schema for the CodeAccessSecurity element is shown below <CodeAccessSecurity> <PolicyItem> <PermissionSet .... ... </PermissionSet> <Assemblies> <Assembly ... ... </Assemblies> </PolicyItem> </CodeAccessSecurity>
Dwp Files
	There are a number of ways to deploy a web part, however the recommended way is to use a solution package. You will have to specify the location of the .webpart files in the DwpFile element. also include your assemblies and resource files into the solution. The best part about a solution is that the assemblies can be deployed to all servers in the farm as well as registered as a safe control. The basic schema for the DwpFiles element is shown below <DwpFiles> <DwpFile Location= "Text"> </DwpFile> ... </DwpFiles> Note that the SharePoint SDK indicates FileName instead of Location which is incorrect.
Feature Manifests
	Typically a solution will contain many different features, all these features can then be activated together to form part of a bigger system or solution you are deploying. You may have a feature for your site columns and content types, different features for different web parts and then even different features for lists and list templates. It is important to not and often I get many questions around this : A solution can install many features into the 12 hive, however the opposite is not possible. Remember that a solution is a deployment unit and will copy over all your features, these features can then be activated either manually or through templates. The basic schema for the Featuremanifests element is shown below <FeatureManifests> <FeatureManifest Location="Text"/> </FeatureManifests>
Resources
	Should you wish to localise a feature, you can install a resource file into the features folder. It is preferable that you localise the file using the <Resource> element instead of using a the <RootFile>. The resource will be deployed to 12\TEMPLATE\FEATURES\<featurename> folder. The basic schema for the Resources element is shown below <Resources> <Resource Location="Text"/> ... </Resources>
Site Definition Manifests
	The really cool thing about a solution is deploy all you site definitions and these site definitions will be used by administrators and users to create sites. Remember that the site definition will then activate needed features, provision pages and menus and place web parts onto site pages. The basic schema for the SiteDefinitionManifests element is shown below <SiteDefinitionManifests> <SiteDefinitionManifest Location="Text"> <WebTempFile Location="Text"> </SiteDefinitionManifest> ... </SiteDefinitionManifests>
Root Files
	The root file element allows you to copy over any other file, such as images, style sheets, controls. The root files element will copy files relative to the 12 hive. The basic schema for the RootFiles element is shown below <RootFiles> <RootFile Location = "Text"> </RootFile> ... </RootFiles>
Template Files
	The Template Files element is similar to the root element, however it will allow you to target files to the 12\TEMPLATE folder. The basic schema for the ApplicationResourceFiles element is shown below <TemplateFiles> <TemplateFile Location="Text"/> ... </TemplateFiles>

Location attribute

Many of the child elements in the solution package include a Location attribute, this location is the location of the file within the solution package (.wsp) file. In a future post I will walk you through the steps to create a .wsp file, however it is a standard cabinet file and when you open the cabinet the root directory of the cabinet is displayed.

Example

The RSSView web part is in a folder FEATURE\GroundingRSS in the .wsp file. You would specify the location of the <DwpFile element as FEATURES\GroundingRSS\RSSView.webpart

Reasons to deploy using a solution package

Now it is important to highlight issues to the reasons why you should rather use solution packages instead of manually copying them over.

SharePoint tracks usage of the components and will give errors should you try to uninstall the solution package if being used.
Deploying to multiple servers in a farm could be prone to human error and one may forget to deploy to a server.
Should a server be down while deploying, you may forget to to deploy to the server when it comes up again. However with as solution package it will automatically be deployed to the server when it comes up.
When installing new servers into your farm, you may forget to install your components especially if you have a lot of components that were added over time. Provisioned solution packages will automatically be deployed to new server that are added to the farm.
Deploying custom DLL's to the Global Assembly Cache to a remote machine may be tricky.
Deploying custom DLL's to every bin folder of each web application that uses your components may be tricky especially on a server where new web applications and site collections are being used.
Modifying the web.config on all servers may be pose problems, using a solution package you can very easily modify the web.config especially your safe controls section.

WSS is a exceptionally strong provisioning engine which will manage the deployment of your components and resources to multiple servers in a web farm automatically.

The bottom line here is if you do not use a solution package, you are giving yourself more problems than you need. These will definitely come back and bite you at a later date, causing you and many other people unnecessary stress. It is easy to resolve this by creating a solution package.

How does deployment work with a solution package

The diagram below indicates what needs to be done to create a solution package.

Step 1 - Create custom features

The first thing that a developer has to do is to make the necessary features, templates, assemblies, web parts, pages and other resources that need to be placed into the 12 hive. The developer will copy and test these features to his/her development machine to make sure it works.

For more information, see

Step 2 - Create a solution manifest with CAML

The next step is create a CAML solution manifest that is called manifest.xml. This solution manifest will contain all the information about the resources that need to be deployed. When executing stsadm -o deploysolution, this manifest will be read and executed on all servers on the farm.

For more information, see

SharePoint - Creating a solution manifest
SharePoint - Adding a feature to a solution manifest
SharePoint - Adding a webpart to solution manifest
SharePoint - Deploying assemblies with a solution manifest

Step 3 - Build a cab file (.wsp)

The programmer then needs to generate a data description file (ddf) with a text editor that contains a list of files to add to the .wsp (cabinet) file. This ddf file will contain all the resources file names and the manifest.xml file that need to be deployed to the 12 hive.
Using makecab.exe <ddf filename>, the cabinet file with extension .wsp will be created.

For more information, see

SharePoint - Creating a solution package with makecab.exe

Step 4 - Deploy the solution package.

The developer gives the single .wsp file to the administrator.
The administrator then uses stsadm -o addsolution -filename pathname\<package.wsp>. This adds an asynchronous job to load the solution package file into the configuration database.
You can force the job to run immediately by executing stsadm -o execadmsvcjobs. At this point the solution package is copied into the the configuration database.
Finally, the administrator deploys the package to the the farm, this will read the manifest.xml file in the solution package and proceed to extract the contents into the 12 hive.
This is done by executing stsadm -o deploysolution -name <package.wsp>. This will execute a job on every server in the farm and whereby the server opens the solution package, reads the solution's manifest.xml file and deploys what is defined in the manifest file.

Note the following

The package is deployed to all servers in the farm, regardless of geography. The state of what has been deployed to what server is managed in the config database.
Should a server be offline when you deploy the solution, when it comes online there will be a job waiting for it to deploy the package. The job will be executed on startup thus ensuring the package is deployed.
Should you add a new server to the farm, even months later. A job will be created to deploy all packages to the new server. Thus when the new server comes online after being added to an existing farm, it will have all the packages deployed.

Lists and libraries can be defined either to use a set of columns or it can be defined to use a content type which was introduced in WSS 3.0. The content type defines the columns for a list item or row and a list can be set to use one or several different content types. This effectively allows a list to contain multiple rows with each row having a different set of columns as defined in different content types. It is important to note that content types are defined outside of lists and are consumed by a list, thus several lists can implement the same content type.

Another nice feature of content types is they are defined using an inheritance mechanism, thus a content type can is based on another content type. In fact, you cannot create a content type from scratch, you always have to inherit from another content type. When inheriting a content type, all the fields in the base/parent content type will be included in the new child content type you are defining. There are several content types provided by SharePoint you can inherit from, the core two are either a item type for lists or library types for document libraries.

A final feature is that a library content type can contain a document template which will be used when creating new items for the library, e.g. you may create a word template for a proposal and a content type for the proposal. This template document may contain default text, logos and formatting to your companies standards. When creating a new "proposal" in the library, word will create a new document based on the template that includes all your default content.

Content types can also be associated with events and workflow's making it a really powerful feature of SharePoint.

Methods of creating a content type

There are several ways to create content types, either through the front-end, through code or through a feature. The best method is to create it using CAML and a feature. This method allows you to redeploy and reuse your content type on different farms, sites and site collections. The feature method of deployment is the preferred method of deploying your content types.

Provisioning a content type with CAML and a feature

In order to create a content type you will need to create a feature with an elements manifest file, I have already written several posts on how to do this, see the "See Also" section below if you do not know how to do this.

A simple content type is easy to provision, however the trick part is to know that content types always must inherit from another content type, thus the get the characteristics of the base content type. The ID of your new content type must be created and I have written a post SharePoint - Content Type ID's on how to do this, please read this as it is important.

The next trick is to understand content types can include additional fields, however these fields must be defined as site columns, you can use the site columns that ship with SharePoint, or you can create your own as described in my post SharePoint - How to provisioning a site column with CAML.

The sample elements manifest file below, defines a site column called Customer Account Number and a Content type called Customer which inherits from a contact (0x0106). The content type customer then also includes the a optional field for the Customer Account Number.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <!--Site Columns-->
  <Field
  ID="{63590418-87F5-4fa7-AF50-B371C88F2F56}"
  Name="CustomerAccountNumber"
  DisplayName="Customer Account Number"
  Description="A customer account number used within the company."
  Type="Text"
  MaxLength="10"
  Group="Grounding Site Columns"
    >
  </Field>
  <!--Content Types-->
  <ContentType
    ID="0x0106000BB3F82D2A624B77833C28045F765D7A"
    Group="Grounding Content Types"
    Name="Customer">
    <FieldRefs>
      <FieldRef ID="{63590418-87F5-4fa7-AF50-B371C88F2F56}" />
    </FieldRefs>
  </ContentType>
</Elements>

Verifying the content type

Once you have created the feature, installed and activate the feature. Navigate to the Site Content Type Gallery in your site settings:

Notice the following when viewing your content type:

The parent indicates it is a contact
The columns defined in contact are in your contact.
The new site column "Customer Account Number" is also in the content type.

Where to set the ID

When you define your content type in the Elements manifest file, there is a mandatory ID field which needs to be the content type. A snipit of a content type is shown below:

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<ContentType
ID="0x0106000BB3F82D2A624B77833C28045F765D7A"
>

</ContentType>
</Elements>

The syntax is :

Parent ID + 00 + GUID

Examples

To create a content type with GUID {0BB3F82D-2A62-4b77-833C-28045F765D7A} that is based on contact (0x0106), you would se the ID to
0x0106000BB3F82D2A624B77833C28045F765D7A
To create a content type with GUID {0E3E8F35-3A21-4ed7-8151-816C48E2D64F} that is a based on document (0x0101), you would set the ID to
0x0101000E3E8F353A214ED78151816C48E2D64F
To create your own item with GUID {A6C62A39-E374-4d8d-9EFE-90DD65B659F9} that is based on item (0x01), you would set the ID to
0x0100A6C62A39E3744D8D9EFE90DD65B659F9

Creating the field element

Create a field in an elements manifest, see my post SharePoint - How to provisioning a site column with CAML on how to do this.
Give your field a Name and DisplayName.
Set the type to Choice

Creating the choices

In the Field element, create a child element called <CHOICES>
Add a <CHOICE>Item</CHOICE> element for each item that you want to appear in the list, e.g. <CHOICE>Red</CHOICE>

Setting the default

Add a <Default>Item</Default> element for the default as a child element of Field.

Testing

You will need to install and activate your feature, once done you will need to create a list and add your new site column. Notice the site column appears under the list of Available site columns

Finally, when you add a new item to the list and you will notice that it shows the choices in a drop down list.

Summary of steps

This post will walk you through the steps below in order to create a site column, the most important step is Step 3 which

Create a feature project
Create a feature manifest
Create a site column elements manifest file
Deploy the feature
Provision and Activate the feature
Verify the columns exist

Creating a feature to provision a site column

Download the code

Step 1 - Create a feature project

In creating a project for SharePoint, I somewhat follow the project structure as defined in the Microsoft Press Book: Inside Microsoft Windows SharePoint Services 3.0 by Ted Pattison and Daniel Larson.

Create a Library project in visual studio, in this example I have called it Grounding.Demo.SiteColumn
In this project we will not be deploying the actual DLL, so I will skip the steps of creating a strong named assembly
Create a directory structure to mimic the feature folder in the 12 hive where we are going to deploy the feature to.
Edit the build events to deploy your SharePoint solution onto your development box.
Please note that you should be provisioning your solution using a site definition, however I did not want to complicate this post.

For this demo, the post-build event command line is:
XCOPY "$(ProjectDir)TEMPLATE" "C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\" /s

Step 2 - Create a feature manifest

In this step, we need to create a SharePoint feature for our content types in order to set up a proper deployment environment for our content types. Once completed the feature will be used to deploy to other server environments, i.e. test and production.

Create a feature.xml file in the TEMPLATE\FEATURES\Grounding.Demo.SiteColumns folder.

Add the following xml to the file.

<?xml version="1.0" encoding="utf-8" ?>
<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
         Id="{1EED8F45-4FF6-473d-9B8F-99CB6599D50C}"
         Title="Grounding Demo - Provision Site Column"
         Description="This demonstration teaches you how to provision a site column using CAML"
         Version="1.0.0.0"
         Hidden="FALSE"
         Scope="Site">
  <ElementManifests>
    <ElementManifest Location="SiteColumns.xml" />
  </ElementManifests>
</Feature></PRE< P>

Important points to note

The site columns are provisioned to the "Site" scope i.e. the site collection
The feature has a unique GUID, which you can generate from Visual Studio menu, Tools\Create GUID (Use the registry format).
The ElementManifest points to a file (created in the next step) that includes the site columns.

Step 3 - Creating a site column

Creating a CAML site is done by placing a field element into an element manifest file which is explained in the steps below. For demonstration purposes I have created a simple customer account number field.

The first thing to do is create a element manifest file using an XML editor.
In this case the it was called SiteColumns.xml (see the ElementManifest in the feature above).

Add the following XML to the file

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Field
    ID="{63590418-87F5-4fa7-AF50-B371C88F2F56}"
    Name="CustomerAccountNumber"
    DisplayName="Customer Account Number"
    Description="A customer account number used within the company."
    Type="Text"
    MaxLength="10"
    Group="Grounding Site Columns"
    >
  </Field>
</Elements>

Important points to note

The ID must be a unique GUID which you can create using visual studio, Tools\Create GUID. Use the registry format.
Type and Title are mandatory.
You can provision several fields in a single element manifest file, just create as many <Field .... /> elements as you need.
Grouping your fields makes them easier to find and use from the front-end

Some field attributes

ID

The ID is a globally unique identifier (GUID) which you should generate for each field. This ID will be used in lists when referencing the site column

Type

The type indicates the data type of the column and can be of the any following:

AllDayEvent	The all day event flag is used in calendar lists.
Attachments	The URL of an attachment.
Boolean	A boolean indicator with Yes/No.
Calculated	Indicates that the column is a calculated column based on a expression.
Choice	Indicates that the column is choice from a list of items
Computed	Indicates the field's value is dependant on another field's value.
ContentTypeId	A Content Type ID value.
Counter	An internal unique ID's / counter for each item.
Currency	A currency value (its format depends on the locale).
DateTime	A Date and Time field.
File	A file object when used in document libraries.
GridChoice	A rating scale as used in surveys
Guid	A globally unique identifier.
Integer	An integer number field.
Lookup	The field is a lookup which is a choice, however the choice is from another list.
LookupMulti	A lookup field, however multiple selections are allowed.
ModStat	An approval status.
MultiChoice	A choice field, however multiple selections are allowed
Note	Multiple lines of text which can be plain or formatted.
Number	A numerical field which allows decimal places.
PageSeparator	A page separator field, for surveys.
Recurrence	An indicator that identifies the field as a reoccurring calendar event.
Text	A single line of text
ThreadIndex	The ID of a discussion thread.
Threading	Indicates the field supports threading (in discussions).
URL	A Unified Resource Locator (URL) is stored.
User	A person or group.
UserMulti	A person or group, however multiple people or groups can be selected.
WorkflowEventType	Contains the type of workflow history event (used in workflow history list).
WorkflowStatus	The status of a workflow is stored.

Title

The name of the field as displayed in the user interface. This title may be set using a resource file.

Name

(optional) The name of the field which should be guaranteed to never change. The default is the Title with spaces and invalid characters removed.

StaticName

(optional) The logical name of the field which is similar to Name, however this can be programmatically changed.

DisplayName

(optional) See title.

Description

(optional) A description of the field which will be displayed in front ends. The description can be placed into a resource file.

Required

(optional) Indicates whether or not the field is mandatory. The default is FALSE.

MaxLength

(optional) The maximum number of characters allowed.

Hidden

(optional) Indicates that the field should be hidden from the interface. If TRUE, this field will not be shown on views or forms. The default is FALSE.

ReadOnly

(optional) The field should be read-only and can be displayed and not edited. The default is FALSE.

ShowInDisplayForm

(optional) Indicates whether the field should be shown on a display form. The default is TRUE.

ShowInEditForm

(optional) Indicates whether the field should be shown on an edit form. The default is TRUE.

ShowInListSettings

(optional) Indicates whether the field should be shown in the list settings screen. The default is TRUE.

ShowInNewForm

(optional) Indicates whether the field should be shown on a New form. The default is TRUE.

ShowInVersionHistory

(optional) Indicates whether the field should be shown in the version history of an item. The default is TRUE.

ShowInViewForms

(optional) Indicates whether the field should be shown on a view form. The default is TRUE.

Group

(optional) A group name allowing you to group fields together.

Step 4 - Deploy the feature

In my sample, I have inserted a post build event into the project properties which copies the feature to the 12 hive. This is simply for demonstration purposes and you should provision your features correctly using a site definition.

Step 5 - Provision and Activate the feature

The next step is to actually deploy the feature and then activate the feature on a site

Open the command console. Start, Run, cmd.exe\
(OPTIONAL)Create an environment variable to the STSADM.EXE by typing
SET STSADM=C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN\STSADM.EXE
Install the feature by typing the following command:
STSADM -o installfeature -filename Grounding.Demo.SiteColumn\feature.xml -force
Open your web site
Click Site Actions
Click Site Settings.
Click Site collection features under Site Collection Administration.
Activate the Grounding Demo - Provision Site Column feature

Note you could have activated the feature using stsadm -o activatefeature

Step 6 - Verify the site columns exist

Now the feature is activated, verify the column exists

Open your web site (should still be open).
Click Site Actions
Click Site Settings.
Click Site columns under Galleries
Scroll down to find the column

Grounding.co.za

Tech Talk with Brett Maytom