As shown in A feature manifest file deploying a Web Part and A feature manifest supporting multiple languages, the key information in every feature manifest file is the list of one or more element manifest files. Those files are based on the same XML schema as the feature manifest (http://schemas.microsoft.com/sharepoint/). They make use of a predefined set of tags, each of which corresponds to a specific feature type. The full schema for these XML files is defined in the wss.xsd document, available in the SharePoint15_RootTEMPLATEXML folder. Table 4-2 provides a brief description of the main elements available in SharePoint 2013.

The element manifest file in An element manifest file that defines the Web Part deployed by A feature manifest supporting multiple languages declares the Web Part referenced by the feature in A feature manifest supporting multiple languages.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/" >
  <Module Name="SampleWebPart" List="113" Url="_catalogs/wp">
    <File Path="SampleWebPartSampleWebPart.webpart" Url="SampleWebPart.webpart"
      Type="GhostableInLibrary">
      <Property Name="Group" Value="DevLeap Web Parts" />
    </File>
  </Module>
</Elements>

To deploy a feature, you need to copy the feature’s folder to the SharePoint15_RootTEMPLATEFEATURES path of every target server for the feature. When this is complete, you can use the STSADM.exe command-line tool (found in the SharePoint15_RootBIN folder) to install and later activate the feature. The following is the syntax to install and activate a feature via STSADM.exe:

STSADM.EXE -o installfeature
           {-filename <relative path to Feature.xml from system feature directory> |
            -name <feature folder>}
           [-force]
STSADM.EXE -o activatefeature
           {-filename <relative path to Feature.xml> |
            -name <feature folder> |
            -id <feature Id>}
           [-url <url>]
           [-force]

As an example, to forcibly install and activate the feature named SampleWebPart, you would use the following syntax from the command prompt:

STSADM.EXE -o installfeature -name SampleWebPart -force
STSADM.EXE -o activatefeature -name SampleWebPart -force -url http://server/site/subsite

Alternately, you can use Windows PowerShell to install and activate your feature. Specifically, you would use the Install-SPFeature and Enable-SPFeature PowerShell cmdlets, which are equivalent options to STSADM:

Install-SPFeature -Path <relative path to Feature.xml from system feature directory> -Force
Enable-SPFeature -Identity <identity of the target feature> -Force -Url <target URL>

For the SampleWebPart example, you would use PowerShell with the following syntax:

Install-SPFeature -Path SampleWebPart -Force
Enable-SPFeature -Identity "SampleWebPart" -Force -Url "http://server/site/subsite"

Meanwhile, to deactivate a previously activated feature, you can use the following syntax from the command prompt:

STSADM.EXE -o deactivatefeature
           {-filename <relative path to Feature.xml> |
            -name <feature folder> |
            -id <feature Id>}
           [-url <url>]
           [-force]

Here’s the syntax to deactivate the SampleWebPart feature from the command prompt:

STSADM.EXE -o deactivatefeature -name SampleWebPart -force -url http://server/site/subsite

Within PowerShell, you can use the following cmdlet for deactivation:

Disable-SPFeature -Identity <identity of the target feature> -Force -Url <target URL>

This is the syntax to deactivate SampleWebPart feature:

Disable-SPFeature -Identity "SampleWebPart" -Force -Url "http://server/site/subsite"

You can also uninstall an inactive feature by using the following STSADM.exe command:

STSADM.EXE -o uninstallfeature
           {-filename <relative path to Feature.xml> |
            -name <feature folder> |
            -id <feature Id>}
           [-force]

This is the specific command for the SampleWebPart feature:

STSADM.EXE -o uninstallfeature -name SampleWebPart -force

Or, you can use the following PowerShell cmdlet:

Uninstall-SPFeature -Identity <identity of the target feature> -Force

From within PowerShell, you uninstall the SampleWebPart feature with the following:

Uninstall-SPFeature -Identity "SampleWebPart" -Force

All of these command prompt commands and PowerShell cmdlets offer and support a wide set of parameters; for the sake of simplicity, the examples are abridged. In real life, you should use PowerShell cmdlets because STSADM is provided only for backward compatibility. Moreover, by working with Microsoft Office 365, you will have the opportunity to use PowerShell cmdlets, but you will not be able to access the local command prompt of target servers.

To activate and deactivate a feature, you can use the web browser UI, especially if you like to manage features remotely or want to delegate feature management tasks to users who do not have access to the physical server farm. To manage features through the web browser interface, you need to go to the Site Settings page of the target site, select the Site Actions group, and then select Manage Site Features. Here, you can manage website-level features. If you need to manage site collection features, under the Site Collection Administration group, select Site Collection Features. Both of these menu items will lead you to a feature management page, from which you can activate or deactivate features.

Figure 4-1 shows the feature management page, which lists a site collection’s features. If your features provide multilanguage support, this page will give you the appropriate titles and descriptions, according to the languages configured for the current site and to the current user’s language.

Figure 4-1. The Site Collection Features page.

Notice the Activate and Deactivate buttons next to the feature descriptions. You need to have the proper rights to execute these actions, regardless of whether you use the STSADM.exe tool, a PowerShell script, or the web UI. Users can activate/deactivate a feature at the website-level only if they are site owners or higher, and they should do that only with a valid reason. To manage a feature targeting a site collection, you need to have a site collection administrator account. To manage a WebApplication-scoped or Farm-scoped feature, you need to be a farm administrator.

In the examples thus far, you have copied the features folders to each server by hand. Manually copying these folders is not the best practice, however, because of the high likelihood of errors. An easier and safer approach is to take advantage of a solution package, which is a cabinet file (a .cab compressed file) with a .wsp (Windows SharePoint Services Solution Package) extension provided to automate the process of installing features and customizations. Through a .wsp package, you can deploy a set of one or more features, automatically copying the files and folders to every front-end server from a centralized management console. A .wsp package contains a solution-specific manifest file called a solution manifest (yet another XML file, always with the name manifest.xml), which defines a set of information through attributes and child elements. The solution manifest file structure demonstrates the structure of the solution manifest.

<Solution
    Description = "Text"
    DeploymentServerType = "ApplicationServer" | "WebFrontEnd"
    ResetWebServer = "TRUE" | "FALSE"
    ResetWebServerModeOnUpgrade = "Recycle" | "StartStop"
    SharePointProductVersion = "Text"
    SolutionId = "Text"
    Title = "Text" >
    <ActivationDependencies />
    <ApplicationResourceFiles />
    <Assemblies />
    <CodeAccessSecurity />
    <DwpFiles />
    <FeatureManifests />
    <Resources />
    <SiteDefinitionManifests />
    <RootFiles />
    <TemplateFiles />
</Solution>

The Solution element belongs to the same namespace as the feature element (see http://schemas.microsoft.com/sharepoint/). Table 4-3 gives a brief description of each attribute of the Solution element.

In addition, a Solution tag of a solution manifest can contain child elements, such as the following:

You can deploy a .wsp package using a PowerShell script with syntax such as this:

Add-SPSolution file.wsp

Otherwise, you can use the STSADM.exe command-line tool and the following syntax:

STSADM.EXE -o addsolution -filename filepath.wsp

After installing a solution, you need to deploy it to be able to activate and deactivate it and upgrade its features. Using PowerShell, the following is the minimal script needed to deploy a solution for all the web applications on the farm:

Install-SPSolution -Identity file.wsp -GACDeployment -AllWebApplications

While using the STSADM.exe command-line tool, you can invoke the following command:

STSADM.EXE -o deploysolution
           -name <Solution name>
          [-url <virtual server url>]
          [-allcontenturls]
          [-time <time to deploy at>]
          [-immediate]
          [-local]
          [-allowgacdeployment]
          [-allowcaspolicies]
          [-lcid <language>]
          [-force]

After you add a solution to the farm, however, with SPCA, you can also deploy it using a web browser. Go to the System Settings page, and then click Manage Farm Solutions in the Farm Management group.

Regardless of the interface that you use to deploy a solution, if your farm does not operating 24 hours a day, 7 days a week, you can schedule the deployment at night to avoid any issues or failures during peak daytime usage. If your farm does operate all day, every day, you should have a set of front-end servers configured for network load balancing so that you can deploy and upgrade solutions one server at a time without any service interruption.

Just as you can install and deploy a solution, you can also retract and remove one. To retract a solution, you can still use the SPCA interface. Alternately, you can use a PowerShell script or the STSADM.exe command-line tool. The PowerShell cmdlet takes the following form:

Uninstall-SPSolution -Identity <solution identity>
            [-Time <scheduled time to uninstall>]
            [-AllWebApplications]
            [-WebApplication]

Meanwhile, this is the STSADM.exe syntax for retracting a solution:

STSADM.EXE -o retractsolution
            -name <Solution name>
            [-url <virtual server url>]
            [-allcontenturls]
            [-time <time to remove at>]
            [-immediate]
            [-local]
            [-lcid <language>]

To completely remove an unused solution, you can use the following PowerShell cmdlet:

Remove-SPSolution -Identity <solution identity> [-Force]

If you prefer using STSADM.exe, you need the following syntax:

STSADM.EXE -o deletesolution
            -name <Solution name>
             [-override]
             [-lcid <language>]

Solutions also can help you with versioning issues. After deploying a solution, you can upgrade it through a standard and supported upgrade path, as you’ll learn in the “Upgrading solutions and features” section later in this chapter. Before deploying and upgrading a solution, however, you need to package it, as the next section illustrates.

Visual Studio 2012 natively provides tools that support developers in releasing SharePoint solutions. Whenever you create a SharePoint 2013 project within Visual Studio 2012, you can choose to manage the project deployment through the Packaging Explorer and the Package Designer. These tools give you the ability to graphically define the content of the package that will be compiled while building your solution. Figure 4-2 depicts the interface of the Packaging Explorer and the Package Designer for a sample Web Part project.

The interface includes a tree view on the left, in which you can explore the package structure, as well as an editing interface in the body of Visual Studio. From the editing interface, you can configure the name of the package, the features that will be put inside it (chosen from the set of features available in the current Visual Studio solution), and the order of installation of those features. At the top of the editor, there are three tabs (Design, Advanced, and Manifest) that you can use to change the display of the Package Designer editing section. Figure 4-2 shows the editing section in Design view. In Advanced view, you can provide custom .NET assemblies (DLLs) that will be deployed by the current package. In Manifest view, you can see the autogenerated XML of the manifest, and you can customize the XML template that is used to generate it to provide any custom tag or attribute that’s not defined by default. You can also take full control of the XML manifest content, replacing the autogenerated code with a completely manual version.

Figure 4-2. The Visual Studio 2010 Packaging Explorer and Package Designer interface.

In addition to using the Packaging Explorer, you have the ability to manage the configuration of each feature included in the package. To configure a feature, double-click it in the Visual Studio Solution Explorer, or click the Edit command available for each feature in the Packaging Explorer. The feature editor is the place to provide descriptive information for the feature, such as its title and description; configuration and behavioral parameters, including the target scope of the feature; the set of items that make up the feature; and any feature activation dependencies. A feature activation dependency gives you the ability to define a sequence of deployment for features. For example, you can create a sequence that prevents you from deploying one specific feature before another specific feature has been deployed. As with the Packaging Explorer, you can switch to Manifest view so that you can see the XML that describes the current feature. You can also customize the XML using a model or from scratch.

After you define a package, right-click the Visual Studio project that contains it, and then deploy the .wsp package by clicking Deploy. By default, Visual Studio will deploy the package on the farm that you chose when you created the project. In a development environment, you usually target the local server, which performs double-duty as the development machine and the SharePoint server for first testing your solutions. You can also simply create the package by clicking the Publish menu item, in which case you will be prompted to select the target file location. The publishing command is useful whenever you need to deploy the .wsp package into an external environment and you need to copy the .wsp file from your development environment to the target environment. Lastly, you can retract a solution from the SharePoint server where you previously deployed it by clicking the Retract menu item. If you deploy a solution on a server where you have already deployed it—for example, because you fixed some bugs and you want to repeat solution testing—the deploy process offered by Visual Studio 2012 will automatically retract the old version and release the new one, deactivating the features before retraction and activating them again during deployment. From the perspective of SharePoint, it would be better to upgrade the solutions, as you will see in the next section of this chapter. For the sake of simplicity, however, Visual Studio retracts it and deploys it again.

One feature receiver event that deserves a dedicated section is FeatureUpgrading. Introduced in SharePoint 2010 for handling feature upgrades, this method targets all situations in which you need to upgrade a feature executing custom code. If you override the FeatureUpgrading method, you will receive an instance of the SPFeatureReceiverProperties type, as you do with all the other methods of the feature receivers. You will also receive an argument of type String with name upgradeActionName and an argument of type IDictionary<String, String> with name parameters. The values for these arguments can be defined in the feature manifest file, within the UpgradeActions section of the file schema (see A feature manifest that supports versioning with multiple upgrade paths ).

How would you use this method in practice? Suppose that you deployed the SampleWebPart feature version 1.0.0.0 in your environment. Later, you decide to upgrade it to version 2.0.0.0. This new version of your Web Part needs to change (by code) the configuration of the list instance that you created in the FeatureActivated event in A sample feature receiver that handles FeatureActivated and FeatureDeactivating events. Assume that your upgrade method changes the OnQuickLaunch status of the Sample List and configures the ContentTypesEnabled property. The feature manifest file with the configuration of the custom upgrade action shows the feature manifest with the configuration of the custom upgrade action.

<Feature xmlns="http://schemas.microsoft.com/sharepoint/" Version="2.0.0.0"
Title="DevLeap Sample Web Part"
Description="This feature deploys a sample Web Part."
Id="c46c270e-e722-4aa0-82ba-b66c8dd61f4e" ReceiverAssembly="DevLeap.SP2010.
SampleFeature, Version=1.0.0.0, Culture=neutral, PublicKeyToken=b001133e0647953d"
ReceiverClass="DevLeap.SP2010.SampleFeature.Features.SampleWebPart.
SampleWebPartEventReceiver" Scope="Site">
  <UpgradeActions>
    <CustomUpgradeAction Name="UpgradeSampleList">
      <Parameters>
        <Parameter Name="ShowOnQuickLaunch">False</Parameter>
        <Parameter Name="EnableContentTypes">True</Parameter>
      </Parameters>
    </CustomUpgradeAction>
  </UpgradeActions>
  <ElementManifests>
    <ElementManifest Location="SampleWebPartElements.xml" />
    <ElementFile Location="SampleWebPartSampleWebPart.webpart" />
  </ElementManifests>
</Feature>

The custom upgrade action is defined using a Name attribute and a set of Parameter elements. Meanwhile, Using the FeatureUpgrading method implementation to handle the custom upgrade action demonstrates the implementation of the FeatureUpgrading method, which uses the custom upgrade action configuration.

public override void FeatureUpgrading(SPFeatureReceiverProperties properties,
    string upgradeActionName,
    System.Collections.Generic.IDictionary<string, string> parameters) {
    // Get the parent of the feature
    // Current feature has a Site scope, thus the Parent
    // should be a Site Collection
    SPSite site = properties.Feature.Parent as SPSite;
    if (site != null) {
        // Check the type of upgrade action
        if (upgradeActionName == "UpgradeSampleList") {
            // Extract and convert the properties
            Boolean showOnQuickLaunch =
                Boolean.Parse(parameters["ShowOnQuickLaunch"]);
            Boolean enableContentTypes =
                Boolean.Parse(parameters["EnableContentTypes"]);
            SPWeb web = site.RootWeb;
            // Check to see if the list already exists
            try {
                SPList list = web.Lists["Sample List"];
                list.OnQuickLaunch = showOnQuickLaunch;
                list.ContentTypesEnabled = enableContentTypes;
                list.Update();
            }
            catch (ArgumentException) {
                // The list does not exist, thus you cannot upgrade it
            }
        }
    }
}

The method invocation receives the Name attribute of the CustomUpgradeAction element inside the upgradeActionName argument, as well as the set of Parameter elements through the parameters dictionary. Based on these arguments, the upgrade code can now do whatever is necessary to upgrade the feature.