13 Using features and solution Packages WhAt’S IN thIS chAPtER? ➤➤ Understanding SharePoint Features ➤➤ How to manage Features ➤➤ Working with SharePoint Solutions ➤➤ How to manage Solutions ➤➤ How to create a basic Feature and Solution Package All SharePoint administrators should understand both Features and Solutions While the creation of Features and Solutions is typically a development role, administrators need to understand their main components in order to manage and support them, as well as to understand a Feature or Solution’s impact on the farm Features are a key building block of SharePoint, and much of SharePoint’s own functionality is implemented using them A Feature is a collection of elements that are grouped together and, though they are not required to be, usually composed of logically related elements An element can be almost anything in SharePoint: a Web Part, a workflow, a content type defi nition, an event receiver, etc Name an artifact in SharePoint and the odds are good that it can be an element in a Feature Once Features are installed, they can be activated or subsequently deactivated so that their functionality can be enabled and disabled As you have seen in previous chapters, the authors may have asked you to either activate a Feature or ensure that a specific Feature was already activated The SharePoint Solution infrastructure enables you to have a single deployment point for all of the servers in your farm, and to schedule deployments and updates via jobs This in turn enables you to more with less, because during deployments you will not need to copy files to every server in the farm, or make web.config changes to all servers in the farm If a Solution has 350 ❘ chAPtER 13 UsiNg featUres aNd solUtioN Packages been created correctly, all of this will be handled by the Solution infrastructure All you have to is execute a deployment or update to the centralized solution store, and SharePoint takes care of the rest In addition, because you can use Solutions to schedule deployments and updates, you no longer need to pay someone to wait around until midnight for those tasks You can simply schedule them and then confi rm that they occurred later While not everyone will feel comfortable with scheduling a deployment to be run as an automated job, those who have a test and/or staging environments are likely to use this capability because success can be verified elsewhere fi rst Features and Solution Packages play a big role in deploying custom capability to SharePoint websites This chapter discusses what Features contain, how they are activated, and how they are managed You will also create a simple Feature so that you will have a better understanding of the process uSINg ShAREPOINt 2010 FEAtuRES Features are located in the TEMPLATE\FEATURES subdirectory of the SharePoint root folder located at C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\ FEATURES Within the FEATURES directory, each Feature has its own directory; and at a minimum, that directory contains a feature.xml fi le It is in this fi le where the Feature is actually defi ned A Feature defi nition is composed of element manifests, dependencies, upgrade actions and/or properties, and is used to register functionality at a given scope within SharePoint These directories will often have additional fi les and/or subdirectories that contain supporting fi les where the elements and other parts of the Feature are defi ned For most Features, it is the elements that we care about, not so much the Feature defi nition itself The elements are what defi ne the Web Parts, workflows, menus, content type, lists, and so on that you or your users will use and interact with defining Scope Features are defined in SharePoint for a particular scope — at the farm, web application, site collection, and site level The scope defined for a Feature determines what elements are available within it, and whether and how Feature dependencies will work for the Feature A table showing the elements by scope can be found at http://msdn.microsoft.com/en-us/library/ms454835(office.14).aspx ShAREPOINt ScOPE NAmES The nomenclature for scopes in SharePoint has changed over time but some of the legacy terms remain for compatibility purposes In the online table, you will notice the current term used to describe SharePoint’s scopes and another term in parentheses; for example, Site (site collection) The term in parentheses is the term SharePoint uses internally to refer to the scope, and the one that it expects to see in the scope attribute of the Feature element in the feature.xml fi le For example, for Features that have a Site Collection scope, you need to specify Site as the scope; and for Features that will have a Site scope, you need to specify a scope of Web This can be a little confusing at fi rst and is worth a review if you are having scoping issues with a Feature Using sharePoint 2010 features ❘ 351 Activating and deactivating Features The SharePoint infrastructure allows Features to be activated and deactivated, much like using a light switch During the activation process, SharePoint provisions elements or makes declarative elements available; and during the deactivation process, SharePoint unprovisions some of those same elements, but not all, and makes declarative elements unavailable You can see a listing of elements and how they are provisioned/unprovisioned or made declaratively available/unavailable here http://msdn.microsoft.com/en-us/library/ee537575(office.14).aspx The difference between provisioning an element and making a declarative element available is durability That is to say, when something is provisioned, SharePoint stores information in the configuration or content databases; and when something is declaratively made available, it is read directly from the Feature defi nition each time a SharePoint web application starts As mentioned above, not all elements provisioned during activation are unprovisioned during deactivation, and content that has been created based on elements will not be removed when the Feature is deactivated either The provisioning behavior described above reflects the default actions and behaviors that occur during the Feature activation/deactivation process; but using custom code, a Feature creator can change how parts of that process work managing Features SharePoint gives you the flexibility to manage things in a number of different ways, and Features are no different You can manage Features through the user interface or via the command line, using either legacy STSADM commands or PowerShell cmdlets; and they can be installed, uninstalled, activated/deactivated, and viewed Managing features via the User interface The user interface provides a limited amount of functionality for managing Features It allows users with the Manage Web permission to see the visible Features for the current site or site collection In order to manage Features scoped for the farm or web application, you must be a farm administrator The Manage Web permission must be given on the root site of a site collection in order for the user to be able to manage Features at the Site Collection level How you get to the Feature’s management page depends on the scope you want to manage Sites and Site Collections To manage Site and Site Collection scoped Features, go to the Site Actions menu and choose Site Settings, as shown in Figure 13-1 352  ❘  Chapter 13   Using Features and Solution Packages To manage Features for the site, choose Manage site features (see Figure 13-2) under the Site Actions section To manage Features for the site collection, choose Site collection features (see Figure 13-3) under the Site Collection Administration section Figure 13-1 Figure 13-3 Figure 13-2 Farm When managing web application and farm level Features through the user interface, you must access Central Administration You can get to the link for managing farm Features in a couple of different ways, but the simplest way is to use the link on the Central Administration home page under the System Settings section, as shown in Figure 13-4 Web Application Web application Features are accessed a little differently than the other scopes because they are accessed via the Ribbon To access web application Features, click the Manage web applications link that is available on the Central Administration home page, in the Application Management section, as shown in Figure 13-5 Figure 13-4 Figure 13-5 Once on the Web Application Management page, you need to click one of the listed web applications in order for the options in the Ribbon to become available (see Figure 13-6) Using SharePoint 2010 Features  ❘  353 Figure 13-6 Table 13-1 lists the direct URLs for each page based on scope Table 13-1:  Feature Management URLs Scope URL Farm http:///_admin/ManageFarmFeatures.aspx Web Application http:///_admin/ManageWebAppFeatures.aspx Site Collection http:////_layouts/ManageFeatures aspx?Scope=Site Site http:////_layouts/ ManageFeatures.aspx Feature Management Pages Each of the Feature management pages allows you to activate and deactivate Features for their given scope Keep in mind that these pages show only the visible Features for the given scope For each Feature, the page includes an activation/deactivation button, whose status appears immediately to the right of the Feature (see Figure 13-7) A status is shown only if the Feature is active Users can toggle the status of a Feature by using this button The action the button will take on the Feature is determined by the current state of the Feature and the action to be taken will be labeled on the button Figure 13-7 354 ❘ chAPtER 13 UsiNg featUres aNd solUtioN Packages The user interface will not necessarily show all of the Features for a given scope because a Feature can be hidden A Feature will be hidden when its hidden attribute is set to true (this attribute can be found on the Feature element in the feature.xml fi le) For Features that are marked as hidden, your only option for managing them is the command line, using either PowerShell cmdlets or legacy STSADM commands Why hide a Feature? You may not want to allow users to activate or deactivate it For instance, you may not want users to deactivate a Feature that has an event receiver that enforces data validation when an item is added or updated in a list, or you may not want them to activate a Feature that is not intended for all sites in the farm Another thing to keep in mind is that SharePoint shows all of the visible Features in the farm for the given scope Therefore, if you have a lot of Features deployed on a farm, the user interface can get a bit cluttered in a hurry For these types of environments, it is preferable to mark the Feature hidden unless it is necessary for a user to be able to control its status Managing features via the Command line The command line provides you with all of the administrative functions needed to manage Features, such as viewing information, installing/uninstalling, and activating/deactivating All of these functions are available from PowerShell, and all but viewing information are available using legacy STSADM commands PowerShell cmdlets for Features include Get-SPFeature, Enable-SPFeature, Disable-SPFeature, Install-SPFeature, and Uninstall-SPFeature Viewing Feature Information The PowerShell cmdlet Get-SPFeature enables you to view information about Features from the command line Used alone, the cmdlet is pretty basic and has very limited use It enables you to view a list of all of the Features in the entire farm or for a given scope Executing the cmdlet Get-SPFeature by itself will yield a list of all of the Features for all scopes The following example shows how to condition the output to view all of the Features in the farm that have a Site Collection scope level Get-SPFeature DisplayName PublishingStapling BasicWebParts XmlFormLibrary LinksList workflowProcessList GridList Id -001f4bd7-746d-403b-aa09-a6cc43de7942 00bfea71-1c5e-4a24-b310-ba51c3eb7a57 00bfea71-1e1d-4562-b56a-f05371bb0115 00bfea71-2062-426c-90bf-714c59600103 00bfea71-2d77-4a75-9fca-76516689e21a 00bfea71-3a1d-41d3-a0ee-651d11570120 Get-SPFeature | Where-Object DisplayName AccSrvSolutionGallery {$_.Scope -Eq “Site”} | Sort DisplayName Id Scope -744b5fd3-3b09-4da6-9bd1-de18315b045d Site Scope Farm Site Web Web Web Web Using SharePoint 2010 Features  AdminReportCore AssetLibrary BaseSite BasicWebParts b8f36433-367d-49f3-ae11-f7d76b51d251 4bcccd62-dcaf-46dc-a7d4-e38277ef33f4 b21b090c-c796-4b0f-ac0f-7ef1659c20ae 00bfea71-1c5e-4a24-b310-ba51c3eb7a57 ❘  355 Site Site Site Site Get-SPFeature -Site http:/// | Sort DisplayName DisplayName Id Scope -AccSrvSolutionGallery 744b5fd3-3b09-4da6-9bd1-de18315b045d Site AdminReportCore b8f36433-367d-49f3-ae11-f7d76b51d251 Site AssetLibrary 4bcccd62-dcaf-46dc-a7d4-e38277ef33f4 Site BaseSite b21b090c-c796-4b0f-ac0f-7ef1659c20ae Site BasicWebParts 00bfea71-1c5e-4a24-b310-ba51c3eb7a57 Site Note that there is no STSADM equivalent to these PowerShell cmdlets Installing and Uninstalling Features Generally, you should not install or uninstall Features outside of the Solution infrastructure, but in some cases it may be necessary Solutions are covered in detail later in this chapter, but for now you should know that they are the preferred method for installing and uninstalling Features, rather than using the command line To install and uninstall Features, you use the Install-SPFeature and Uninstall-SPFeature cmdlets, respectively The following examples show how to use these to install and uninstall a Feature named HelloWorldWebPart Both the install and uninstall cmdlets can take a -Force parameter When this parameter is specified, SharePoint will bypass some of the checks that it normally performs when the command is executed This can be helpful when trying to troubleshoot or fix issues with a Feature The following PowerShell cmdlet will install the Feature: Install-SPFeature HelloWorldWebPart DisplayName Id -HelloWorldWebPart d157638b-0fbd-4196-8683-155e24330314 The STSADM equivalent is: STSADM -o installfeature HelloWorldWebPart The following PowerShell cmdlet will uninstall the Feature: Uninstall-SPFeature HelloWorldWebPart The STSADM equivalent is: STSADM -o uninstallfeature HelloWorldWebPart Scope Site 356 ❘ chAPtER 13 UsiNg featUres aNd solUtioN Packages Activating and Deactivating Features As you have seen, you can activate and deactivate a visible Feature through the user interface Those same tasks can also be accomplished by using the PowerShell Enable-SPFeature and Disable-SPFeature cmdlets, respectively The cmdlet names use a different nomenclature than the user interface and the legacy STSADM commands For these cmdlets, Enable-SPFeature performs the activation of a Feature, and Disable-SPFeature performs the deactivation The -URL parameter for the enable and disable cmdlets is used to identify the web application, site collection, or site on which the cmdlet will take action Like the install and uninstall cmdlets, the enable and disable cmdlets support a -Force parameter This parameter can also be useful when troubleshooting issues with a Feature In the case of Enable-SPFeature, it allows you to issue the enable cmdlet for an already activated Feature This can be useful if you want to update a Feature defi nition without fi rst having to deactivate it The following PowerShell cmdlet will enable the Feature (no output is returned): Enable-SPFeature HelloWorldWebPart -URL http://sharepoint The STSADM equivalent is: STSADM -o activatefeature HelloWorldWebPart -URL http://sharepoint The following PowerShell cmdlet will disable the Feature: Disable-SPFeature HelloWorldWebPart -URL http://sharepoint The STSADM equivalent is: STSADM -o deactivatefeature HelloWorldWebPart -URL http://sharepoint The -Force parameter is a useful option with Features but you should exercise caution when using it Not all Features are built to handle being installed/ uninstalled, or activated/deactivated, repeatedly without first having the inverse command executed For these Features, you can end up with issues that manifest themselves in many ways, such as Feature elements appearing in the system multiple times, errors being generated during the execution process that may leave things in an inconsistent state, Feature or content corruption, and so on The possible issues with the -Force parameter are usually limited to complex Features but they can occur in simple ones as well, so proceed with caution creating a Feature As stated earlier, creating a Feature is generally considered a development task, but having a basic understanding of how Features are created can help you better understand how to troubleshoot issues if (when) they arise Creating a Feature can range in complexity from very simple to extremely complicated depending on the elements and artifacts that are being used This section focuses on creating a very basic Feature that will add a menu item to one of the menus in SharePoint and link to Wrox’s website Later in this chapter we will add this Feature to a Solution Using sharePoint 2010 features ❘ 357 Creating a Feature in this manner is not considered a best practice and should not be done this way in a real-world scenario As a best practice, Features should be packaged into Solutions and deployed with the same The purpose of this example is to show you the mechanics of creating a Feature manually so that you can see all of the moving parts It is recommended that you use a tool such as Visual Studio 2010 to create Features and package them in Solutions To begin creating the Feature, you need to create a directory in the TEMPLATE\FEATURES directory of the SharePoint root (C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\FEATURES) For this Feature, name the directory MyBasicMenuItem This step is illustrated in Figure 13-8 FIguRE 13-8 Inside the MyBasicMenuItem directory, create two fi les, a Feature fi le named feature.xml and an elements fi le named elements.xml Only the Feature’s fi lename is important; it must be named feature.xml The element’s fi lename is not important; the fi le can be named anything as long as it is referenced correctly from the Feature fi le Once the fi les are created, open the Feature fi le in the text editor of your choice (Notepad works just fi ne) Inside the Feature fi le, add the following XML: 358  ❘  Chapter 13   Using Features and Solution Packages Note the Scope and Id Scope attributes, which indicate to SharePoint the level in the hierarchy at which this Feature applies; and as a result, what elements it should expect to process and handle during its activation This Feature will be scoped at the Site level, so you specify the term “Web” (please refer to the “SharePoint Scope Names” note, earlier in the chapter, for an explanation of why these terms differ) The Id attribute is also important because it will be SharePoint’s internal identifier for the Feature This Id needs to be a unique GUID (global unique identifier) You cannot use the same Id /GUID across Features Note also that you specify an element manifest in the file, and that the manifest entry is pointing to a Location named elements.xml That is the elements file you created in the directory The path is relative to the Feature’s own directory, so if you wanted to have the elements file in a subdirectory named MenuItems, you would specify MenuItems\elements.xml as the Location, but for now leave it as just elements.xml Next, open the elements.xml file in Notepad and add the following XML The element in the file is a custom action that will add a menu item/hyperlink to the Site Settings menu in the Site Actions section Your Feature is now complete To let SharePoint know that it is there, use the Install-SPFeature cmdlet you learned about earlier in the chapter From PowerShell, execute the following: PS C:\> Install-SPFeature MyBasicMenuItem DisplayName Id -mybasicmenuitem 6c5f196c-a287-4019-a415-c55ed1782860 Scope Web At this point, you might assume that now that the Feature is installed, you should see the menu item in the Site Actions menu under Site Settings, right? Nope, you still need to activate the Feature for a specific site, as this Feature is scoped at the Site (web) level Before activating the Feature, however, take a look at the Site Actions section (see Figure 13-9) so you can compare it to what it looks like after the Feature is activated Now activate the Feature You can use the Enable-SPFeature cmdlet or you can enable it through the user interface, but you should probably experiment with both: PS C:\> Enable-SPFeature MyBasicMenuItem -URL http://sharepoint With the Feature activated, take another look at the Site Actions section (see Figure 13-10) on the site You can see that the menu item is now visible and ready for use Solutions  Figure 13-9 ❘  359 Figure 13-10 Of course, most Features that you will see in your life as a SharePoint administrator will be far more complex than the one you just created, but this should help give you an idea of what is involved in creating, installing, and activating a Feature in SharePoint Solutions Solutions are nothing more than a properly formatted cab file that has a wsp extension, and they are the recommended way to deploy Features and any other functionality to SharePoint Though they differ in many ways, you can think of a wsp file in SharePoint as being very much like an msi file for Windows Both contain instructions for deploying content to their respective environments SharePoint 2010 introduces a new type of Solution called a Sandbox Solution that allows Site Collection administrators to deploy and manage Solutions at the site collection level while providing the capability to throttle the amount of resources those Solutions use within the farm They are called Sandbox Solutions because their capabilities are constrained at runtime both from a security and functional standpoint Sandbox Solutions enable administrators to give users more freedom within their site collections, while also providing the ability for the administrator to limit users’ impact on the farm Managing Farm Solutions Managing Solutions is a lot like managing Features and other items in SharePoint With Solutions, you can manage their installation and deployment through the Central Administration user interface, and even more through the command line — whether it is with PowerShell or legacy STSADM commands Managing Farm Solutions via the User Interface When managing Solutions in SharePoint, you can almost anything through the user interface The only normal actions that you cannot perform through the user interface are adding and updating Solutions in the farm solution store Essentially, everything else can be done through the browser When managing a Solution through the browser, you always begin in the same place: Select Central Administration ​  ​ ystem Settings ​  ​ arm Management ​  ​ anage farm solutions, ➪S ➪F ➪M as shown in Figure 13-11  ... returned): Enable-SPFeature HelloWorldWebPart -URL http:/ /sharepoint The STSADM equivalent is: STSADM -o activatefeature HelloWorldWebPart -URL http:/ /sharepoint The following PowerShell cmdlet... Feature: Disable-SPFeature HelloWorldWebPart -URL http:/ /sharepoint The STSADM equivalent is: STSADM -o deactivatefeature HelloWorldWebPart -URL http:/ /sharepoint The -Force parameter is a useful... review if you are having scoping issues with a Feature Using sharePoint 2010 features ❘ 351 Activating and deactivating Features The SharePoint infrastructure allows Features to be activated and