Feature Designer Share Point 2010

In a solution package, the FeatureManifest element is used to specify the reference to the manifest file for a particular feature. To a certain extent, features work in a similar way to solutions in that they can contain a number of individual components and make use of a manifest file to specify what should be done with these components.

Feature Designer

Using the Chapter project that we created earlier, double-click the Feature1 node in the Features folder to display the Feature Designer:

Feature Designer

As you know, features are individual items of functionality that can be activated or deactivated within a SharePoint farm. You can see in the Feature Designer that features comprise one or more elements, where an element may be a web part, a list definition, a workflow, or a number of different components. Using the Feature Designer, we can select which elements should be included in a feature and therefore specify which functionality will be enabled when the feature is activated.

Activation Dependencies

For the most part, we don’t need to think about feature elements, because Visual Studio automatically creates features for us and adds our project items to them. However, in the real world, this default behavior may not be appropriate. For example, rather than having many features, each with a different project item in it, we may want to consolidate related items into a single feature. This makes it easier for users to activate our customization since they need to activate only one feature rather than many separate items. It also makes it easier for us to ensure that all the parts of our solution are activated.

We can consolidate related items in a few ways: We can use the Feature Designer to specify which elements should be included in a feature, or we can define feature dependencies. Where a dependency is defined, a feature cannot be activated unless its dependencies have also been activated. This may seem like a poor solution, because it means that users still have to activate a load of individual features, but we can take this a step further. Under some circumstances, dependency features will be automatically activated when a feature that depends upon them is activated. Furthermore, we can hide features so that they don’t appear in the feature activation user interface. Effectively, this brings us back to the idea of a single activation click for our customization, while at the same time allows us to keep individual features relatively simple.

Feature Scope

The activation dependency approach has a few limitations, but before we look at those, we need to consider feature scope. Again, this is something that we’ve been able to ignore because Visual Studio handles it for us automatically; in the real world, an understanding of scope is essential when building complex solutions.

In the Feature Designer, under the Description text box is a drop-down that we can use to select the scope of a feature: Farm, WebApplication, Site, and Web. As you’ve probably guessed, these options determine the level at which the components are activated. Components within a feature scoped as Web will be activated for a single site only, whereas components within a feature scoped as Farm will be available to the entire farm. However, it’s not quite as straightforward as that. Not all types of component can be installed in all scopes. For example, if we’re creating a content type, we can deploy it only using a feature scoped at the Site level; if we’re adding an event receiver, it can be scoped only at the Web level.

Feature Activation Rules

To return to our discussion of the limitations of feature dependencies, the first limitation concerns scope. Features cannot be dependent on features of a more restrictive scope— that is, a feature scoped at the site collection (Site) level cannot depend on a feature scoped at the site (Web) level. This makes sense when you think about it, because a site collection can contain multiple sites, each with its own set of activated features—so there’s no way to satisfy such a dependency properly. The opposite is not true, however. Features scoped at the site level can depend on features at the site collection level. There is one caveat to this rule: A feature can’t depend on another feature at a higher scope if the higher level feature is not visible. So a site feature can’t be dependent on a site collection feature that’s hidden. There is a good reason for this: Although we can automatically activate dependent features, we can do so only within the same level. So we would be unable to activate our site feature because there would be no way to activate the site collection feature upon which it depended if the site collection feature were hidden.

The second limitation concerns dependency chains. Generally speaking, activations can be only one level deep. For example, if feature A depends on feature B, then feature B cannot have any dependencies. This is true only for visible dependencies, however. If feature B is dependent upon feature C, which is hidden, then the dependency chain is allowed. Hidden features cannot have any dependencies; therefore, the maximum chain depth is two levels.

Feature Properties

With the Feature Designer open, we can set feature properties using the Properties pane in Visual Studio. For example, we can hide a feature by setting the Is Hidden property to True. Many of the properties are set automatically by Visual Studio, but the following properties can also be used to meet specific configuration requirements:

  • Activate on Default This Boolean value dictates whether the feature should be activated when the solution package is deployed.
  • Always Force Install The SharePoint deployment mechanism is pretty clever when it comes to installing features. Because features can be shared by many solutions, only features that are not already installed are installed when a package is deployed. Each feature has a unique identifier that’s used as the reference for activation dependencies and so on. To force an installation when the solution is deployed, this value can be set to True.
  • Deployment Path All features are deployed to their own folder at %SPROOT% TEMPLATE FEATURES. By default, Visual Studio creates folders named ProjectName_FeatureName. In our project, our feature will be deployed in a folder named Chapter_Feature. We can change the name of this folder by changing the Deployment Path. (The name Deployment Path is something of a misnomer; it more accurately contains the Deployment folder name.)
  • Image URL & Image Alt Text In the Manage Features page, an icon appears to the left of each feature’s description. These properties can be used to specify an alternative image file and appropriate alternative text if required. In no alternative is specified, the default feature icon will be used.

We’ll look at few other properties, such as Receiver Assembly, Upgrade Actions Receiver Assembly, and Version in more detail in later sections.

Feature Elements

With a few exceptions, almost all the items we can add to a project using Visual Studio are packaged as feature elements. In our demonstration project, we added an empty element named FirstElement; in the Solution Explorer page, we can see that it contains a single file named Elements.xml. In the Feature Designer, we can click the Manifest button at the bottom of the page to see the manifest file for the feature:

Similar to how the manifest file for the solution was made up of FeatureManifest elements, we can see that the feature manifest is made up of ElementManifest elements.

Let’s add a more complex element to our project to see how this is represented:

  1. In Visual Studio, choose Project | Add New Item. In the Add New Item dialog, select List Definition and name the element SampleList.
  2. In the SharePoint Customization Wizard dialog, accept the defaults and then click Finish. A new SampleList folder will be added to the project, as shown:

Feature Elements

If we look at the feature manifest file again, we can see that three new elements have been added:

Two new ElementManifest elements point to the new Elements.xml files that were added and an ElementFile element. This prompts the question, What’s the difference between an ElementManifest and an ElementFile? We’ll find the answer by examining the Elements.xml file in the SampleList folder:

In our Elements file, we’re specifying that we are creating a new ListTemplate. Our Elements file is effectively issuing a command to the deployment framework. If we open the Schema.xml file, we find much more information contained within it. The Schema file is effectively a resource file that’s used by the deployment framework to provision our list template. Another way to look at it is that our ElementManifest files dictate what should be done, whereas our ElementFile files provide the required resources to do the job.

A number of commands can be issued using ElementManifest files, and although these are mostly wrapped by a SharePoint Project Item in Visual Studio.

Although covering the various resource files that can be used by features is beyond the scope of this one very important point needs to be made here: Although most of the content within a SharePoint site is stored in a content database, the same is not true for configuration. Much of the configuration for a site is defined within features, and the element files within the features are actually used to deliver the appropriate functionality.

To get a better understanding of the significance of this, we can navigate to %SPROOT%TEMPLATE/FEATURES and then open the TaskList folder. In the folder, we’ll find a Feature.xml manifest file, which refers to the Tasks.xml ElementManifest file in the ListTemplates folder. When this feature is activated, the Task List list template is added to the list of lists that can be created for a SharePoint site.

If we examine the contents of the Tasks folder, we’ll find a schema.xml file. This file defines the schema for every task list that’s currently in use on the SharePoint farm. Looking through the contents of the Features folder, we’ll find that much of the functionality of the SharePoint platform is defined here.

Feature Receivers
We’ve used a few feature receivers in some of the example projects in this book. A feature receiver is basically an event handler responsible for handling installation and activation eventsfor a feature. We can add feature receivers to any type of feature by right-clicking a Featurenode in the Solution Explorer pane and selecting Add Event Receiver. When we performthis action, Visual Studio adds a new code file to our project and sets the Receiver Assemblyand Receiver Class properties of the feature to reference the new code file. Let’s do this now:

  1. Right-click the Features node and select Add Feature. A new feature will be added to the project.
  2. Right-click the Feature2 node in the Features folder and select Add Event Receiver.
  3. Double-click Feature2.feature in the Feature 2 folder. In the Properties pane, the Receiver Assembly and Receiver Class have been automatically set.

In the Feature2.EventReceiver.cs file are five commented methods representing the events that can be handled by the feature receiver. By uncommenting these methods, we can add custom code to do whatever we need to do. As you embark on more complex SharePoint projects, you’ll find that although you can perform much configuration using the SharePoint Project Items available in Visual Studio, a lot of configuration still needs to be done programmatically. In these situations, the feature receiver is the tool of choice. Bearing that in mind, let’s look at how feature receivers work and how we can best make use of them.

  1. Add the following code to Feature2.EventReceiver.cs:
  2. Deploy the solution by selecting Deploy Chapter 19 from the Build menu.

If all is well, we’ll find that our blank demo site now contains two new lists: one named Chapter ListInstance1, which has been created by the ElementManifest in Feature1, and another named My New List, which has been created programmatically by our feature receiver in Feature 2.

Notice in this code snippet that we’re using the properties.Feature.Parent property to obtain a reference to the SPWeb object on which our feature is being installed. Some investigation of the Parent property will reveal that it’s of type object, and for that reason we’re checking its type before casting it to a variable of the correct type. To understand why this is the case, you can take a look at how features are defined within the server object model, as shown here:

Feature Receivers

Features can have four possible scopes. When a feature of a particular scope is installed, it’s added to the Features collection of the appropriate object. For example, a site collection– scoped feature would be added to the Features collection of the appropriate SPSite object. The SPFeature object that is returned by properties.Feature can therefore have one of four possible parents, depending on the scope of the feature.

To confirm that our receiver is working as expected, we can take the following steps:

  1. From the Site Actions menu, select Site Settings, and then select Manage Site Features from the Site Actions section.
  2. Both Chapter Feature 1 and Chapter Feature 2 are active. Deactivate Chapter Feature 2. Notice that My New List is removed from the site. This confirms that our feature receiver is working as expected.

Debugging Feature Receivers
Feature receivers can be difficult to debug because they are often executed within a separate process. To see an example of this problem, put a breakpoint on the first line of our FeatureActivated method and try debugging using Visual Studio. The code will be deployed and the feature will be activated, but execution will not stop at the breakpoint. Visual Studio makes use of a separate process, VSSPHost4.exe, to automate the deployment process. The Visual Studio debugger, however, is set up to attach to a W3SVC.exe process only, and therefore the breakpoint is never hit but the code still executes.

We can work around this issue in one of two ways: we can either attach a debugger to the appropriate process, or we can ensure that our feature receiver runs in the W3SVC process. To ensure that a debugger is attached to the correct process, we can take the following steps:

  1. Add the following line of code to the method to be debugged:
  2. Debugger.Break();
  3. Start the debugging process as normal. An error dialog will be displayed:
  4. Debugging Feature Receivers

  5. Click Debug The Program, and then in the Visual Studio Just-In-Time Debugger select the appropriate instance of Visual Studio. Click Yes to begin debugging.

This technique will work regardless of the host process. For example, if PowerShell is used to install a package, the same error dialog will be displayed.

Our second option is to ensure that the feature receiver code runs in the W3SVC process. This is relatively easy to do. Earlier when we looked at feature properties, we saw that the Activate On Default value is used to determine whether a feature should be automatically installed. We can use this setting as follows:

  1. Remove the line of code that we added in the preceding example.
  2. Double-click the Feature 2 node and set the Activate On Default property to False.
  3. Debug the solution as normal. This time, when the solution is deployed, our feature will not be automatically activated.
  4. When the web site being debugged is shown in the browser, select Site Settings from the Site Actions menu, and then select Manage Site Features from the Site Actions section. Manually activate the feature being debugged. The debugger will now stop on the breakpoints.

This method works because when features are activated via the user interface, the feature receiver runs under the W3SVC process, and Visual Studio has attached a debugger to this process as part of the standard debugging mechanism.

Passing Parameters to Feature Receivers
You’ve seen how to create feature receivers and how to pick up references to the object that you need in order to access the server object model. We’ve looked at a few ways to enable debugging. Let’s move on to look at more complex feature receivers.

As mentioned, practically every real-world SharePoint project will require some custom feature receivers. This is especially true when code being developed must be shared among multiple developers or deployed to testing or staging environments. As a result, it is sensible to create a library of feature receivers that perform specific configuration tasks. For example, I have a collection of feature receivers that perform actions such as configuring security for a site or setting up search scopes. These are actions that are common to many SharePoint projects but that can’t be performed declaratively.

One essential aspect of creating reusable feature receivers is the ability to pass configuration into the receiver.

Let’s look at a few ways to solve this problem. The first method is appropriate if a collection of name/value pairs is sufficient for our purposes.

  1. Open the Feature Designer for Feature 2.
  2. Add the FirstElement element that we created earlier to the feature, as shown:
  3. Passing Parameters to Feature Receivers

  4. In the Solution Explorer pane, select the First Element node. Then in the Properties pane, click the ellipsis next to Feature Properties.
  5. Add two new properties, ListName and ListDescription. Set the values to Another New List and This is Another list, respectively.
  6. Click OK to close the dialog.
  7. Although every element in a feature has a Feature Properties property, in reality the properties are applied at the feature manifest level—that is, the combination of all the properties that are added to each element in Visual Studio are actually written within a single Properties element in the feature manifest.

  8. Update the code in Feature2.EventReceiver.cs as follows:

You can see that we’re able to address the properties via the properties.Definition object. The Definition object is of type SPFeatureDefinition and is an object representation of the various XML elements that make up the feature.

The next method for solving the problem is appropriate if more complex configuration is required. For example, when configuring security settings for a site using a feature receiver, I use this approach to load an XML file containing the security configuration.

  1. Add an XML file named MyConfig.xml to the FirstElement folder. Add the following code:
  2. To specify that the MyConfig.xml should be included as an element file, select the MyConfig.xml node in the Solution Explorer. Then, in the Properties pane, change the Deployment Type to ElementFile, as shown here:
  3. Passing Parameters to Feature Receivers

  4. Update the code in Feature2.EventReceiver.cs as follows:

When we deploy the solution and activate the feature, three new lists will be added to the site as specified in the MyConfig.xml file. In this example, we’ve used an XmlReader to parse the configuration file for the sake of keeping the example simple. In a real-world solution, using an XmlSerializer to deserialize the configuration file into an appropriate collection of objects would be more robust.

Upgrading Features
In SharePoint 2010, one of the important new capabilities from a packaging and deployment perspective is the ability to upgrade features. In previous versions, an upgrade was possible, but it was more a case of replacing an old feature with a new version. This could leave a system in an indeterminate state, because actions performed by the old feature would not necessarily be undone when a new version of the feature was installed.

For example, if a feature created a list that users subsequently populated with data and then a new version of the feature created a new version of the list with a different name, the result of deploying the new feature would be two lists. A better approach would be to rename the old list.

With the upgrade capabilities in SharePoint 2010, we can define a number of upgrade actions declaratively in the feature manifest, and for more complex upgrade processes we can also use a feature receiver to make any changes programmatically.

Using PSCONFIG.EXE
We can trigger an upgrade in a few different ways, including using the psconfig tool to upgrade all features within a farm. This tool is useful when many features have been updated, since it’s a pretty lengthy process. For example, if a service pack updates many system features, running psconfig will ensure that instances of the updated features are upgraded where appropriate.

Let’s look at several possible psconfig commands. This command performs a version-toversion upgrade:

psconfig.exe -cmd upgrade -inplace v2v

Feature versions are in the format major.minor.build.build. When using a version-to-version upgrade, only features in which the major or minor version number has changed will be upgraded. So for a feature with version 1.0.0.0, if we deploy a new build with the version 1.0.1.234, no upgrade will be performed. However, if we deploy version 1.1.1.234, an upgrade will be performed because the minor version number has changed.

This command performs a build-to-build upgrade:

psconfig.exe -cmd upgrade -inplace b2b

By using this mode, we ensure that any changes to the version number will trigger an upgrade. So, for example, version 1.0.0.0 will be upgraded if version 1.0.0.1 is deployed.

Using PowerShell
A quicker way to upgrade an individual feature instance is to use PowerShell. Follow these steps to see the upgrade process in action:

  1. Open the Feature Designer for Feature2. In the Properties pane, set the version number to 1.0.0.0. Where no version number is specified, a default of 0.0.0.0 is assumed. Version numbers must contain four components.
  2. From the Build menu, select Deploy. This will deploy our version 1 solution to the farm.
  3. In the Feature Designer, click the Manifest button at the bottom of the page. Expand the Edit Options section to display the Manifest Template. Replace the template XML with the following:
  4. By attaching this XML to the feature definition, we’re defining the steps that should be taken to upgrade existing features. The CustomUpgradeAction element specifies that we’re using a feature receiver to perform the upgrade programmatically. In this example, we haven’t specified a version range, so this upgrade action will apply for all versions. If we needed to include different upgrade actions for different versions we could add this:

  5. In the Properties pane, change the Version number for Feature 2 to 2.0.0.0.

    NOTE Within the Properties pane are options to set the Upgrade Actions Receiver Assembly and Class properties. These properties allow a feature to use a separate assembly for handling standard feature events such as Activate and Deactivate and a separate assembly for handling upgrade events. This facility is useful for retrofitting upgrade capabilities to a feature if the existing receiver assembly isn’t available or can’t be altered for some reason.

  6. For the sake of simplicity, we’ll implement our upgrade code in our existing feature receiver. In the Feature2.EventReceiver.cs file, add the following code:
  7. Notice the use of a switch block in this code snippet to handle the upgradeActionName. This value is specified in the Name attribute of the CustomUpgradeAction element in the feature manifest.

  8. If we deploy our updated feature using Visual Studio, our existing version will be removed first, which will make it impossible to test our upgrade process. Instead, we’ll package our solution using Visual Studio and deploy it manually. From the Build menu, select Package.
  9. To test our upgrade process quickly, we can use PowerShell to upgrade a single feature. Choose Start | SharePoint 2010 Management Shell, and then enter the following script:
  10. NOTE This command should be entered as a single line.

  11. This command will upgrade the Chapter solution package to the latest version. We can confirm this by entering the following script:
  12. if all is well, the resultant output should be this:

    Current Version: 1.0.0.0, Latest Version: 2.0.0.0
  13. We can upgrade a single feature using the following script:
  14. Any errors that occur as part of the upgrade process will be shown in the PowerShell window. However, we can confirm that our upgrade was successful by issuing the following command:
  15. write-host ($theFeature).

    Version The new version number should be reported as 2.0.0.0.


All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

Share Point 2010 Topics