Installation and Deployment of a Farm Solution in SharePoint 2010
This topic provides an overview of the installation of farm solutions.
Applies to: SharePoint Foundation 2010
Farm solution installation in Microsoft SharePoint Foundation is a system that enables developers to package custom farm solutions and administrators to deploy those farm solutions in a straightforward, safe, and consistent manner. Specifically, installation refers to the process of uploading and unpacking solution packages (.wsp files) to front-end web servers, and deploying the contents.
Installation can be done with either the Central Administration application or SharePoint Management Shell. See Technet for information about how to do these tasks.
You can programmatically install a farm solution by using the Add method of the collection stored in the SPFarm.Solutions property, followed by a call of the SPSolution.Deploy method.
Major Steps of Installing a Farm Solution
There are two or three major steps to farm solution installation:
Adding: A solution package is added by a farm administrator to the farm's solution store, which is in the farm's configuration database. This is done either with the SharePoint Management Shell (or with the object model). It cannot be done in Central Administration.
Deploying: The solution package is unpacked, and its elements are copied to their appropriate places.
This step also requires a farm administrator and can be done with either Central Administration, SharePoint Management Shell, or the object model. Some examples of how elements are deployed: user control files (.ascx) are copied to %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\ControlTemplates or a subfolder of it, and assemblies are deployed to the global assembly cache or to a web application's \bin folder. If there are Features in the farm solution, they are in this step copied to a subfolder of %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\FEATURES and installed in the Feature Gallery of the farm, web application, site collection, or website, depending on the scope of the Feature.
Administrators do not have to deploy a solution immediately after adding it to the solution store. It can be stored in an undeployed state indefinitely.
Feature Activating: Features must be activated before they can be used, so activating becomes a third step of installation for solutions that contain Features. Features can contain content types, controls, custom actions, custom fields, files, workflows, list instances, list templates, event receivers, and document converters; although some of these cannot be included in certain scopes.
Note
SharePoint Foundation is not consistent in its terminology with regard to installation and uninstallation of farm solutions. The terms Adding, Deploying, and Activating are the most commonly used to refer to the three steps of installation; but depending on what tool is used to carry out a step, you will see a variety of terminology. The second step, for example, is called deploying in Central Administration, but installing in SharePoint Management Shell. There is a similar inconsistency in the terms for reversing these steps; but most commonly, reversing the second step is called retracting (but it is called uninstalling in SharePoint Management Shell), and reversing the first step is called removing. The third step, which applies only to Features, is always called activating, and its reversal is always called deactivating.
Farm Solution Store
The farm solution store is a table in the SharePoint Foundation configuration database that holds solution packages.
Administrators can add farm solutions to the farm solution store in one of two ways:
Command line: An administrator can add and remove solution files from the farm solution store by using the SharePoint Management Shell. For more information, see Features and solutions cmdlets (SharePoint Server 2010.
Object model: When you add a farm solution to the store, the contents of the solution file are validated against an .xsd file to verify that the files contained in it comply with the SharePoint Foundation schemas. If the verification fails, an error message is returned. If the verification succeeds, the process of adding the farm solution continues.
Note
It is possible to deploy a solution on only one server even in a multi-server farm, using the DeployLocal property. This should be done only temporarily as a troubleshooting step. At all other times, the front-end web servers should be identically configured.
Details of the Deployment Step
The deployment step for a farm solution creates a timer job. This timer job is used by the timer service on each web server in the server farm. The timer job also uses the SharePoint Foundation Administrative web service to access appropriate privileges to deploy solution files to each computer, so both services must be running on all servers for the deployment to succeed.
Initially, the package manifest is parsed to find assemblies, application pages, JavaScript, and other files that are not part of a Feature. These are copied to the locations specified in the manifest. All files contained within a Feature are copied to the Feature directory, a subdirectory of %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\FEATURES. 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 Internet Information Services (IIS). Farm administrators can specify when this occurs.
Finally, farm solution Features are registered, and schema and definition files are committed to the configuration store.
Farm administrators can choose to deploy a solution on only some web applications in the farm.
Canceling a Deployment Job
If the deployment step is in its initial setup, and the deployment timer job has not yet started running on any of the deployment targets, the deployment job can be canceled. In such cases, the timer job is removed.
However, after a deployment timer job begins running on any target computer, the deployment timer job can no longer be canceled.
Installation Failures
During installation to the front-end web servers, the following failures can occur:
If the timer service is not activated on a front-end web server, 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 must either fix the timer service or cancel the deployment job.
If the SharePoint Foundation 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 SharePoint Foundation 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. "Error" will appear in red in the Status field for the solution in the Solution Management page of Central Administration.
If one or more files fail to copy—for example, an existing file is marked as read-only—the stage is marked as failed, and processing stops.
If the deployment stage 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.
See Also
Concepts
Uninstallation and Retraction of a Farm Solution
Upgrading a Farm Solution in SharePoint 2010