Microsoft & .NET.NETCreating Solutions for SharePoint 2007

Creating Solutions for SharePoint 2007

Developer.com content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

Introduction: Defining the Snag in SharePoint 2003

Microsoft SharePoint 2003 (WSS and SPS) was the first version of SharePoint with a consistent and powerful realization of an Application Programming Interface (API) based in the Microsoft DotNet Framework. Creating the possibility of developing customizations for SharePoint has always been a hot item in the programming world. However, deploying the customizations made for the 2003 version has proven to be a frustrating issue in the reception of the system by the technical community. Truth be said, there is no official method of deploying custom software for SharePoint 2003. The developer has two time-consuming options: an awkward manual “copy and paste” of all the customized files and assemblies, or alternately, fabricating a custom-built installer.

The SPS 2003 customizations, which created a stir when they came out, consisted of new templates, some of them including many files; assemblies to install in the local IIS directory or in the Global Assembly Cache (GAC); custom aspx pages; Event Handlers; WebParts; Web Controls and Web Services. Of these, WebParts was the only component with an efficient, well-established installation procedure (using the “stsadm” tool, the command line administration tool of SharePoint); nevertheless, if the WebPart needed to be installed within a template, this useful deployment procedure became more complicated.

Creating purpose-built deployment tools was a popular way of installing complex customizations. For straightforward applications, this worked well; the difficulty arose when there was more code to build into the project. In this case, the development team was obliged to develop, debug, and test the extra software, with the subsequent strain on budget and resources.

Additional problems inherent in the long-standing deployment system were the lack of a versioning scheme, the inability to recover information or revert to the pre-deployment situation in an easy and consistent manner, and the difficulty in installing all the components in the server farm in a unified way (the deployment needs to be repeated in each independent server of the farm). Equally, the responsible individuals were required to make changes in the web.config file to ensure the registration of components and configuration for the Computer Access Security (CAS) policies.

SharePoint 2007 Solutions: Tackling the Problem

The latest version of SharePoint, Windows SharePoint Services (WSS 2007) and Microsoft Office SharePoint Server (MOSS 2007), has offered a resolution to the deployment problem with the introduction of SharePoint Solutions.

SharePoint Solutions is a framework that assembles all the components necessary to compose a customization in one Solution file, which then can be distributed in an effortless way. The framework allows for the installation, activation, deactivation, and removal actions to be employed by system administrators, without their involvement in the technical issues relative to the physical localization of files and assemblies.

In one skillful sweep, SharePoint Solutions provides for:

  • Compilation of all customization components (aspx files, DLLs, resource files, definition files, and so forth) in one file
  • Physical installation of the components in the farm without activation: The solution can be copied to all the servers in the farm without being activated
  • Activation in a timetabled way: The system administrator can decide when the customizations will be activated automatically
  • A versioning system that is able to install versions of the same customizations
  • If a new server is added to the farm, the Solutions Framework ensures the installation of the customization automatically, without intervention from the system administrator
  • Deactivation of the customization, allowing for a return to the original situation, also in a scheduled way
  • Physical de-installation of the components to remove them from the servers

In essence, a Solution file is a .cab comprised file that contains all the files to be installed as well as a “manifest.xml” file. The manifest file is a description for the solutions engine to define its tasks, the physical localization to install the custom files, and some metadata necessary for its registration in SharePoint. The extension for Solution files is “.wsp”, and if the extension is changed to “.cab”, it’s possible to open the file and examine its contents.

Microsoft, as a company strategy, is also taking advantage of SharePoint Solutions to distribute the latest in software for SharePoint; the new “Windows SharePoint Services 3.0 Application Templates: Server Admin Templates” uses an “Application Template Core” main application that installs an administration tool for the templates and which then is installed as a Solution. As an additional feature, all the templates are distributed as Solutions as well.

Using Solutions from the User Interface and stsadm

To install a Solution, use the “stsadm” SharePoint administrators’ tool, with the following syntax:

STSADM.EXE -o addsolution -filename <Path to the wsp file>

For example, to install the above-mentioned core application for the templates, this is the form:

"C:Program FilesCommon FilesMicrosoft Shared
    web server extensions12BINSTSADM.EXE" -o addsolution
-filename C: ApplicationTemplateCore.wsp

(if the .wsp is at the root of the file system)

After installation, the Solution is uploaded to the configuration DataBase (the “Objects” table of the “Config” database), but in this form it is not ready to be used in the system; it still needs to be activated. From this point forward, the handling of the Solution can be done from the Central Administration Web interface of SharePoint. Go to the Central Administration, the “Operations” tab, and under “Solution management” (section “Global configuration”) a list with all the installed solutions can be found, together with its status and which Web Application(s) have been deployed.

Figure 1: Solution Management web page in the Central Administration of SharePoint

When the desired Solution is selected on the page, the next screen will show a summary of the Solution plus two buttons: one to Deploy the Solution and one to Remove it. The second button will reverse the installation procedure and the first will finish the installation process.

Figure 2: Web page to Deploy or Remove a Solution

Deploying can be completed immediately or at any determined timeframe in the future. The Solution Framework can initiate a scheduled task; in this way, you can deploy the Solution when the system administrator considers it appropriate.

The metadata in the Solution definition or in each component determines the scope of the deployment in the farm. The example shown in Figure 3 illustrates a global deployment and because one or more assemblies are deployed in the GAC, the page displays a warning.

Figure 3: Deployment screen in the Central Administration

Deployment using the “stsadm” tool is also possible with the subsequent syntax:

STSADM.EXE -o deploysolution -name <Name of the Solution>
   [-url <Virtual Server URL>] [-allcontenturls]
   [-time <Time to Deploy at>] [-immediate] [-local]
   [-allowgacdeployment] [-allowcaspolicies]
   [-lcid <Language>] [-force]

Note: The parameters between “[]” are not obligatory.

Versioning of Solutions is possible if a Solution is deployed with the same solution ID of an existing Solution in the Store. In this case, the original Solution is removed from the Store, backed up and saved in the configuration Store, and the new Solution is added. The Backup is referred to in the event of an installation failure, and only one Backup is stored for each Solution.

After deployment, the Solution can be “Retracted” (deactivated) and removed by following the inverse procedure from the Central Administration’s user interface or using “stsadm” with the syntax:

STSADM.EXE -o retractsolution .name <Name of the Solution>
   [-url <Virtual Server URL>] [-allcontenturls]
   [-time <Time to Remove at>] [-immediate]
   [-local] [-lcid <Language>]

As observed in the parameters list of “deploysolution” and “retractsolution”, “stsadm” offers better control than the Web user interface. However, the downside is that it is a command line tool that is less user-friendly.

To delete the Solution from the farm, simply apply:

STSADM.EXE -o deletesolution -name <Name of the Solution>
   [-override] [-lcid <Language>]

Using Solutions Programmatically

The SharePoint user interface and “stsadm” are not the only means of installing and activating Solutions. SharePoint’s Object Model provides all the classes and methods to accomplish the task programmatically.

The SPSolution and SPSolutionCollection classes represent, respectively, one Solution and the collection of Solutions in the SharePoint farm. The SPSolutionLanguagePack and SPSolutionLanguagePackCollection classes have a similar structure, but are used exclusively for the management of Language Packs. There are also three specialized enumerations—SPSolutionDeploymentJobType, SPSolutionDeploymentState, and SPSolutionOperationResult—to define the types, states, and possible outcomes of Solutions.

All the classes and enumerations belong to the Microsoft.SharePoint.Administration NameSpace in the Microsoft.SharePoint.dll assembly. For an enumeration (without explanation) of the different classes, methods, and properties, consult the SDK of WSS 2007 (SPSolution Class and SPSolutionCollection Class).

To enumerate the Solutions and their properties in the farm, the code is as follows:

 1. SPSolutionCollection mySolutionColl = SPFarm.Local.Solutions;
 2. foreach(SPSolution mySolution in mySolutionColl)
 3. {
 4.    Console.WriteLine("Name - " + mySolution.DisplayName +
 5.                      ", Deployed - " +
                         mySolution.Deployed.ToString() +
 6.                      mySolution.DeploymentState.ToString() +
 7.                      ", Status - " +
                         mySolution.Status.ToString());
 8. }

The first line demonstrates a created object that contains the collection of Solutions in the local farm. The ‘foreach’ statement loops through each Solution illustrating some of its properties. There are a myriad of properties and methods to control all the potential of the Solution, for example: methods to Deploy and Retract Solutions; properties to discern whether the Solution contains CAS policies; resources or assemblies to be installed in the GAC; a test to determine whether the Solution has been deployed; a flag if there is a task to be deployed; its status, and so on.

To install a new Solution in the Solutions Store, the following code can be used:

 9. SPSolution mySolution =
       SPFarm.Local.Solutions.Add(@"C:HelpDesk.wsp");
10. Console.WriteLine("Solution "   + mySolution +
11.                   " installed:" + mySolution.Added.ToString() +
12.                   ", deployed:" + mySolution.Deployed.ToString());

The “Add” method employs three constructors that allow for installing a Solution; using a previously created SPSolution object; utilizing the path to the .wsp file; and thirdly, the .wsp path and language identification. The return value is an object of the SPSolution type.

To deploy the Solution, the code with the Object Model is:

13. SPSolution mySolution = SPFarm.Local.Solutions["HelpDesk.wsp"];
14. Console.WriteLine("Before: DeploymentState -
                      " + mySolution.DeploymentState.ToString()); 
15. mySolution.Deploy(DateTime.Now, false, false);
16. Console.WriteLine("After: DeploymentState - " +
                      mySolution.DeploymentState.ToString());

Note that if there is no Object with a reference to the Solution, as shown in Line 13, it is possible to craft a new one. The Deploy method has two constructors: one to deploy the Solution to all the Web Applications in the farm and another permitting the user to choose in which Web Application it will be deployed. In fact, this method does not literally deploy the Solution but it creates a SharePoint task to carry out the deployment. As a result of this situation, the second message of the Console.WriteLine will always indicate “NotDeployed”: a confirmation that there is a time gap between running the code and when the job engine initializes the task.

The first parameter of the method “Deploy” indicates when the activity will commence. The “globalInstallWPPAckDll” parameter (the second parameter in the example) is used exclusively in deploying WebParts and permits installing the assembly of the WebPart in the GAC. The third is a “force” (Boolean) parameter; if this parameter is ‘false’, and the Solution has already been deployed, the procedure will raise an exception.

If the Web Interface of the Central Administration (refer to Figure 2) is utilized, Solutions containing assemblies to be deployed in the GAC will display a warning message. If the “stsadm” administration tool is selected, it is essential to use the “-allowgacdeployment” flag to deploy to the GAC. If the Object Model is chosen to deploy the Solution, no warnings will be issued.

If it is necessary to execute an “iisreset” to reset the application pools of IIS, it must be programmed independently or done manually as the “Deploy” method does not do it automatically.

Updating a Solution can be done by using the SPSolution: Upgrade (System.String) method if the Solution has not yet been deployed and the SPSolution.Upgrade(System.String,System.DateTime) method if it already has been deployed.

Finally, to retract and remove the Solution, the corresponding methods of the SPSolution class are applied:

17. SPSolution mySolution = SPFarm.Local.Solutions["HelpDesk.wsp"];
18. mySolution.Retract(DateTime.Now);
19. mySolution.Delete();

Line 18 retracts a deployed Solution. This method can have one parameter (the date and time to start the retracting task) or two parameters (the timer for the job and a reference to the Web Application where the Solution has been deployed). Line 19 simply removes the Solution entirely from the farm.

It is important to note that employing the Object Model to install, activate, and retract Solutions has some inherent risks. The timing of the job engine can be substantially slower than running the code of the Object Model. It is critical that care is taken with the events ordering: always wait until one process is completely terminated before initializing the next one; if not, the solutions engine can generate an error, and some of the errors can be terminal. Also, the Solution will be in a ‘hold’ status preventing further steps and a success implementation.

Conclusions

SharePoint Solutions is a bona fide option to deploy customizations into SharePoint 2007, and it is a successful counter to the problems present in SharePoint 2003. There are diverse ways of implementing Solutions; applying the administration tool of SharePoint, utilizing the Web interface or operating programmatically. My next article will demonstrate how to create Solutions, elucidate the differing components of the schema, and discuss aspects relevant to the construction of the .wsp file.

About the Author

Gustavo Velez is a MCSD Senior Application Developer for Winvision (http://www.winvision.nl), a Microsoft Gold Partner in the Netherlands. He has had many years experience in developing Windows and Office applications, and more than five years of daily programming experience with SharePoint. The author’s articles, in English, Dutch, and Spanish, can be found in many of the leading trade magazines and he’s pleased to be Webmaster of http://www.gavd.net/servers, the only Spanish-language dedicated SharePoint site. Spanish-language readers may want to consult the author’s new book; Programación con SharePoint 2007.

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Latest Posts

Related Stories