Deploying a Solution

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Solution deployment is a multipart framework for letting developers create custom solutions, and letting administrators deploy those solutions in a straightforward, safe, and consistent manner. Specifically, deployment refers to the process of distributing, unpacking, and installing solution (.wsp files) to front-end Web servers.

Following are the main components of solution deployment:

• **The solution store   **A centralized collection of all SharePoint solutions for the server farm. The first step in deploying a solution is to add the solution to the store.

• **Deployment   **Distribution, unpacking, and installation of the solution to the front-end Web servers. After adding a solution—whether it is a new solution or an upgrade for an existing solution—to the server farm solution store, it must be deployed uniformly to the front-end Web servers.

• **Synchronization   **Process of taking a new front-end Web server, or a damaged or inconsistently performing front-end Web server, and synchronizing its state to that of the other front-end Web servers.

Solution Store

The solution store is a table in the Windows SharePoint Services configuration store that holds solution files.

You can add solutions to the solution store in one of three ways:

• **Command line   **An administrator can add and remove solution files from the solution store using the stsadm utility.

• **Administration user interface   **This user interface contains a section that lets administrators add and remove solution packages from their server.

  Note

  When using this administrative user interface, you can only remove solutions from the store, not add them to it.

• **Object model   **When you add a solution to the store, the contents of the solution file are validated against an .xsd file to verify that the files contained within the feature or site definition comply with the Windows SharePoint Services schemas. If the verification fails, an error message is returned. If the verification succeeds, the process of adding the solution continues.

Deployment

Solutions are deployed in one of two ways: either locally or by using a timer service. This applies both to new deployments, as well as to deployments of solution upgrades. Both local and timer-based deployments can be triggered either by using command-line instructions or programmatically by using the object model.

Local deployments that are initiated from the command line by a user with administrator privileges run in the context of the administrator. If initiated by using the timer service, however, the deployment runs in the context of the timer job itself, which uses administrator pool account credentials. Either set of credentials should be sufficient to read and write to the configuration store.

Local Deployment

In a local deployment, solution files are deployed only to the computer from which the deployment operation was initiated. Under this scenario, the solution is not marked as "deployed" in the configuration database until the solution files are deployed to all applicable servers in the server farm. Then, in the case of new solution deployments, solution features are registered, and schema and definition files are committed to the configuration store.

Timer Service Deployments

In deployments that use the timer service, the deployment creates a timer job. This timer job is picked up by the timer service on each Web server in the server farm. The timer job uses the Windows SharePoint Services Administrative Web service to access appropriate privileges to deploy solution files to each computer.

Initially, manifest and feature manifests are parsed to find assembly and _layouts files, which are copied to the appropriate locations. All other files contained within a feature directory are copied to the feature directory. After solution files are copied to the target computers, a configuration reset is scheduled for all front-end Web servers; the reset then deploys the files and restarts Microsoft Internet Information Services (IIS).

For upgrades, the deployment has no impact to the end user experience. The new versions of the solution files do not overwrite the old files; therefore, if a computer is restarted, or the upgrade process is aborted, the servers are synchronized with their other data files.

Finally, for new solution deployments, solution features are registered, and schema and definition files are committed to the configuration store.

Exception Handling

Deployment Failures

During deployment to the front-end Web servers, the following failures can occur:

• If the timer service is not activated on a front-end Web server, then the deployment job remains stopped. On the pending jobs page in the user interface, the job appears as pending but not being serviced. The administrator either must fix the timer service, or cancel the deployment job.

• If the Windows SharePoint Services Administrative service is not activated on a particular computer, an error code is set in the SPRunningJob object that marks the stage as failed and prevents any further operation. The failed deployment is converted to an administrative alert that notifies the administrator that the job failed due to a Windows SharePoint Services Administrative Web service that was not running.

• If the extraction of a solution package (.wsp) fails on any particular server, the stage is marked as having failed and processing stops.

• If one or more files fails to copy—for example, an existing file is marked as read-only—then the stage is marked as failed, and processing stops.

Final Stage Failures

In the final stage, the following failures can occur:

• If the code causes an exception, an administrative alert is created with the exception and deployment stops. The underlying job definitions are removed.

• If an external failure occurs (for example, a power outage), final deployment stops, but can then be rerun.

Canceling a Deployment Job

If the deployment is in its initial setup and the deployment timer job has not yet started running on any of the deployment targets, then the deployment job can be canceled. In such cases, the timer job is removed.

However, after a deployment timer job begins running an any target computer, the deployment timer job can no longer be canceled.

Version Changes and Deployment

Over time, a solution and its contents change. There are two fundamental types of change for a given solution:

• Makeup change   Features or site definitions are added to a solution. A solution may have entire features added. If a newer version of a solution is defined (solution versions are different solution packages that share a GUID) that is missing features or site definitions, then those features and site definitions are removed.

• Definition change   Elements are added or removed from features or site definitions. As a result of definition changes, a feature or a site template may add or lose files. As the feature or site definition change over time, files that are no longer defined in the feature definition are removed.

  This applies to assemblies as well. If a solution with global scope loses its assemblies, those assemblies are removed from the global assembly cache. If a feature with Web-application scope loses its assemblies, those assemblies are removed from the local bin directory.

Synchronization

A single computer can be synchronized to the current state of deployed solutions.

The synchronization process pulls solutions that the front-end Web server does not have. These solutions are then redeployed onto the computer selected for synchronization.

For a properly functioning computer that is connected to a server farm, incremental synchronization also redeploys the solutions, even if this has no practical effect.

Following are the steps synchronizing the .wsp files:

• The .wsp file is downloaded and files are placed in the temp folder of the Windows directory.

• The IIS process stops, files are copied to the proper locations, and then the IIS process restarts.

During synchronization, Web Part package files are placed in the global assembly cache (GAC), and safe control entries are placed in the web.config file.

See Also

Concepts

Upgrading a Solution