SharePoint Ramp Up Webcasts for ASP.NET Developers

I wish I would have seen this schedule earlier since the first webcast was today. Nevertheless, I will be trying to catch the others live (or on demand if I miss them). Even as an experienced WSS3/MOSS2007 developer, getting the chance to see a couple of MVPs (Andrew Connell and Rob Bogue) introduce the basics is great review and a chance to check your skills.

Date (all times EDT) Topic & Registration URL Presenter
Tues, May 20 : 12-1p Web Parts Rob Bogue
Wed, May 21 : 12-1p Data Lists Rob Bogue
Tues, May 27 : 12-1p Silverlight Andrew Connell
Wed, May 28 : 12-1p Event Handlers Andrew Connell
Tues, June 3 : 12-1p Site Branding Andrew Connell
Wed, June 4 : 12-1p Workflow Rob Bogue
Tues, June 10 : 12-1p Web Services Andrew Connell
Wed, June 11 : 12-1p Page Navigation Andrew Connell
Tues, June 17 : 12-1p User Management Rob Bogue
Wed, June 18 : 12-1p Content Types Rob Bogue

If you have any interest in SharePoint development, then you don’t want to miss these webcasts.

Creating Solution Packages for WSS 3.0 and MOSS 2007 Deployments

A couple of weeks ago I posted an apology for not following through and posting anything about SharePoint solutions and features like I had promised almost a year ago. This post is a start on coming through with that promise. The only thing that is different from what I had promised in that post is that I will not focus on using Visual Studio 2005 or any other IDE. Rather, my approach will be to help you learn the essentials so that you don’t have to rely on a specific version of an IDE to accomplish the task.

Today in this post, I am going to explain why solution packages are important, what makes up a solution package, how the solution deployment works, and how to create them to effectively deploy solutions and features to a WSS 3.0 or MOSS 2007 farm.

Importance of Solution Packages

SharePoint deployments vary in size from a stand-alone installation on a single server to large multi-server farms. A solution or feature may require configuration changes to the web application, placing files on the file system, and/or deploying assemblies. As such, manual deployments can be administratively difficult since the possibility of deployment error increases with the number of servers in the farm as features and solutions are moved from a development environment to a test environment and finally to a production environment. In order to reduce deployment complexity and possibility of error, SharePoint uses solution packages a deployment mechanism to ensure consistent deployment of solutions and features to all servers in the farm. This allows the testing of a deployment and enables system administrators to create scripted installations (a typical requirement in most enterprise-class IT organizations).

Anatomy of a Solution Package

A solution package is a compressed CAB file with a WSP (.wsp) extension that contains the contents to be deployed including its required additional meta data.

The contents inside the WSP file may include, but is not limited to, assemblies, as?x files, feature manifests, schema XML files, site definitions, WEBPART files, DWP files, InfoPath forms, resource files, images, javascript files, other media files, html files, XML files and the solution manifest. In other words, it can contain just about any type of file you can think of. I may go into details of some of the SharePoint specific content files in some future post.

Every solution package requires additional meta-data to provide the WSS run time with instructions on what to do with the content of the WSP file. The meta-data is stored in a manifest file in XML that must be located in the root of the WSP file; the file is appropriately named manifest.xml. Perhaps I will dive into the details of the Solution schema that defines the XML structure of the solution manifest in another post in the future.

How Solution Packages Work

Basically, they just do.

But in all seriousness, the deployment of a solution package happens in two stages. In the first stage, or the installation stage, WSS takes the WSP file and copies it to the configuration database. In the second stage, or the deployment stage, WSS takes the WSP file from the configuration database, extracts the content(s), and places the content(s) as specified in the package meta-data. Simple huh? Obviously, a system administrator needs to tell WSS to install and deploy a package. This is easily accomplished by executing three simple STSADM utility commands.

stsadm -o addsolution -filename my.wsp
stsadm -o execadmsvcjobs
stsadm -o deploysolution -name my.wsp

The addsolution and deploysolution operations both take additional operational parameters that may be needed depending on the needs of actual solution to be deployed. It should be noted that the  STSADM utility commands only need to be executed on the server that is hosting the Central Administration application. Let’s look at what each command actually does:

  1. The first line (stsadm -o addsolution -filename my.wsp)creates a timer job that asynchronously performs the installation stage of the solution deployment. When the job executes, WSS takes the specified WSP file and copies it to the configuration database.
  2. The second line (stsadm -o execadmsvcjobs) forces WSS to execute any timer jobs that are pending. This is necessary because the actual deployment stage cannot commence until the installation stage has been completed successfully.
  3. The last line (stsadm -o deploysolution -name my.wsp) creates another timer job that asynchronously performs the actual deployment stage of the solution deployment. When the timer job executes, WSS gets the WSP file from the configuration database and deploys the contents of the package based on the instructions defined in the solution package meta-data. It should be noted that the WSS service on each server in the farm performs this task at the same time as triggered by the timer job ensuring a consistent and timely deployment on all servers in the farm.

Another great thing about the solution deployment mechanism is that it also simplifies the removal of a solution from a farm. Solution removal also happens in two stages. In the first stage, or retraction stage, WSS uses the solution package meta-data to remove the contents from each server in the farms. In the second and final stage, or deletion stage, WSS deletes the copy of WSP file from the configuration database. A system administrator can accomplish this easily be executing three STSADM utility commands on the server hosting the Central Administration application.

stsadm -o retractsolution -name my.wsp
stsadm -o execadmsvcjobs
stsadm -o deletesolution -name my.wsp

The retractsolution and deletesolution operations both take additional operational parameters that may be needed depending on the needs of actual solution to be removed. Like we did with the deployment commands, let’s now review what each command actually does:

  1. The first line (stsadm -o retractsolution -name my.wsp) creates a timer job that asynchronously tells the WSS service on each server in the farm to go get the WSP file from the configuration database, take a look at the solution package meta-data, and retract any features, files, and/or assemblies that were previously deployed. This command initiates the retraction stage of the removal process.
  2. The second line (stsadm -o execadmsvcjobs) forces WSS to execute any timer jobs that are pending. This is necessary because the actual deletion stage cannot commence until the retraction stage has been completed successfully.
  3. The last line (stsadm -o deletesolution -name my.wsp) creates another timer job that asynchronously performs the deletion stage of the solution removal. This job tells the WSS run-time to delete the copy of WSP file from the configuration database.

And that is how solution packages work.

Creating a Solution Package

While SharePoint elegantly utilizes Microsoft’s most advanced bleeding edge technology (such as SQL Server, the .NET 3.5 framework, etc.), the actual process of creating a WSP file is ironically a bit archaic. If you are using Visual Studio 2005 for development, then the Visual Studio 2005 extensions for WSS 3.0 can jump start the process of creating the WSP file (but it won’t save you as much time as I expected it to when I first used the extensions). The process of creating a WSP file is the same as creating a  CAB file using the MAKECAB operating system utility. The MAKECAB utility creates the WSP file by reading and processing the cabinet definition contained in a DDF file, also known as the Data Description File. Creating a DDF file is not difficult and can be done with any plain text editor, but the maintenance of the DDF file is manual (this is why I called the process a bit archaic) and become quite tedious with large solutions.In any case, let’s build a sample solution package.

The first step is to create the data description file (DDF) that describes the files for the CAB archive. You can use any text editor to create the file (download the sample DDF file).

; ** my.wsp (Alonso Robles) **
.OPTION EXPLICIT                   ; Generate Errors
.Set CabinetNameTemplate=my.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 Cabitet=on
.Set DiskDirectory1=Package
; All solution packages require additional metadata
manifest.xml   manifest.xml
; Deployment files, Schemas, and Assemblies
my.html        LAYOUTS/mysample/my.html

There are lot of things going on in the DDF file, but here is what I think is important to understand.

  • Comments in the file begin with a semi-colon
  • .OPTION lines tell the MAKECAB utility what options to use when building the CAB archive
  • .Set lines tell the MAKECAB utility what values to apply to certain parameters that are used when building the CAB archive
    • Make sure the CabinetNameTemplate parameter is set to what the name of the WSP file will be (in the example above the MAKECAB utility will generate a CAB archive named my.wsp)
  • Each content file to be added to the CAB archive is listed on a line in a space separated source-destination format
    • For example, this CAB archive will contain an HTML file (my.html); the last line in the example above tells the MAKECAB utility to grab the my.html file from the file system (the source location) and place copy it to LAYOUTS/mysample/my.html in the CAB archive (the destination location)
    • Double quotes can be used to define sources that contain spaces in the path or file name
    • Make sure to include the solution meta-data XML file (manifest.xml) at the root of the CAB archive

The next step is to create the solution manifest file (download the sample solution manifest file).

<Solution SolutionId="01234567-89AB-CDEF-0123-456789ABCDEF"
	 xmlns="http://schemas.microsoft.com/sharepoint/">
  <TemplateFiles>
    <TemplateFile Location="LAYOUTS/mysample/my.html" />
  </TemplateFiles>
</Solution> 

The example is a very simple solution manifest, but there are a couple of things to take away from it.

  • Every solution has a GUID (globally unique identifier) that identifies uniquely
  • As a general rule, every deployment file, schema, and/or assembly contained in the CAB archive must also be listed in the solution manifest or another manifest listed in the manifest.xmlfile; otherwise it will be ignored by the WSS runtime
  • The locations of the deployment file, schema, and/or assembly in the manifest refer to the location in the CAB archive

The last step is to use the MAKECAB utility to generate the solution package – the actual WSP file (you might want to download the sample HTML file if you want to try to create the sample solution package yourself). This is done by using a command window and executing a simple command:

makecab /f my.ddf

And that’s how a solution package (WSP file) is created.

I hope you enjoyed this post. Now I am not making any promises that I might have to apologize for, but I hope to post about other topics such as the solution and/or feature manifests or other fun SharePoint topics in the future.

References & Additional Linkage

Microsoft SQL Server 2005 Reporting Services Add-in for Microsoft SharePoint Technologies

The Microsoft® SQL Server™ 2005 Reporting Services Add-in for SharePoint Technologies is a Web download that provides features for running a report server within a larger deployment of Microsoft Windows® SharePoint® Services 3.0 or Microsoft Office SharePoint Server 2007. The Reporting Services Add-in provides the following functionality:

  • A Report Viewer Web Part, which provides report viewing capability, export to other rendering formats, page navigation, search, print, and zoom.
  • Web application pages so that you can create subscriptions and schedules, set model item security, and manage reports, models, and data sources.
  • Support for standard Windows SharePoint Services features including document management, collaboration, security, and deployment with report server content types. You can use alerts, versioning (check in/out), and Filter Web Parts with reports. You can add the Report Viewer Web Part to any page or dashboard on a SharePoint site and customize its appearance. You can use SharePoint permission levels and roles to control access to report server content. You can also use SharePoint forms authentication to support access over Internet connections.
  • Support for additional languages. The Web application pages, Report Builder, and ReportBuilder.chm are available in the standard SQL Server languages (Chinese Simplified, Chinese Traditional, English, French, German, Italian, Japanese, Korean, Russian, and Spanish), and the following additional languages: Czech, Danish, Dutch, Finnish, Greek, Hungarian, Norwegian (Bokmal), Polish, Portuguese (Portugal), Portuguese (Brazilian), Swedish, and Turkish.

The Reporting Services Add-in works together with updated program files that are in SQL Server 2005 Service Pack 2 (SP2). SP2 is required on the report server and provides the following functionality for a report server that is configured for SharePoint integrated mode:

  • Synchronization from SharePoint content databases to the report server database.
  • A custom security extension that uses SharePoint permissions to control access to report server operations.
  • A new delivery extension that you can use in subscriptions to deliver reports to SharePoint libraries.
  • A revised Reporting Services Configuration tool that you can use to configure a report server for SharePoint integrated operations.
  • Publish reports and models from Report Designer and Model Designer to a SharePoint library.
  • Open reports and models in Report Builder from a SharePoint library, and save reports to SharePoint libraries across the site.
  • A new SOAP endpoint for managing report server content in SharePoint integrated mode.

The add-in is available as a download from Microsoft.

SPFolder and Content Approval

Question:How do I approve a folder in a document library that requires content approval using the SharePoint object model?

Answer:It may seem like a trivial question. After working with the SharePoint object model to create and approve files, it would make sense that any item or folder object would also contain methods needed to check in, publish, and approve them. Well after checking the members of the SPFolder and SPListItem classes on MSDN, I found that they don’t contain properties or methods to intuitively check in, publish, and approve them.

At first, I figured I could use the approve method from SPFile class since the folder object has a property to access the underlying item which has a a property to access the underlying file. Well, it turns out that file property of the item property of the folder object returns a null reference. So, I was back to square one.

As it turns out, the solution to this problem lies in working with the underlying item object. The underlying item object has a property that allows you to access the moderation information object (SPModerationInformation) which contains information about the approval status of the folder. You can then check the status and change as it needed by manipulating the moderation information object directly. Below is a method that I wrote to solve my problem (which was just to approve the folder):

private void ApproveFolder(SPFolder spFolder, SPDocumentLibrary spDocumentLibrary)
{
  if (spFolder.Exists && spDocumentLibrary.EnableModeration)
  {
    SPModerationInformation spModerationInformation = spFolder.Item.ModerationInformation;
    switch (spModerationInformation.Status)
    {
      case SPModerationStatusType.Pending:
        spModerationInformation.Status = SPModerationStatusType.Approved;
        spModerationInformation.Comment = "Got approval?";
        spFolder.Item.Update();
        break;
      default:
        break;
    }
    spModerationInformation = null;
  }
}

Obviously there is a lot more that you can do with the moderation information object. Hopefully, you will find my experience useful.

So You Want to Develop Custom SharePoint Workflows

Elaine Hao, Program Manager of SharePoint Workflow @ Microsoft, put together a really nice series of blog posts on developing MOSS2007 workflows on the Microsoft SharePoint Products and Technologies Team Blog. At the end of the series, she attached a little mini whitepaper that covers everything she covered in her series. I found it extremely useful as I worked on some custom workflow for a client and decided to keep a copy of So You Want to Develop Custom SharePoint Workflows for myself.