Updated on 14th of March 2012
This post is lab 4 from series of training materials for WebTemplate creation and maintenance. Please check the following posts for details and other exercises. Notice that you can download full package with all required lab material from link available in introduction post. This package contains all supplementary materials and labs in word format.
This particular post will concentrate on following functionalities.
The project files for this lab are in the ‘C:\Student\Labs\04_Lifecycle’ folder
Lab Overview: In this lab you will update existing sites using feature upgrade definition.
This lab includes the following additional resources:
Files that can be used to help complete the labs.
Completed lab source code after this exercise
Solution structure started in previous exercise.
Notice that all code and xml elements which are meant to be copied are available as text in the Word documents. This means that if you need to copy any of those elements, it’s better to use Word document formats of these labs.
This Hands-On Lab contains a number of additional resources in fixed locations. By default, it is assumed that the base HOL directory is C:\Student and that the labs and additional resources are located under this directory.
The default working folder for this lab is ‘C:\Student\Labs\04_Lifecycle’.
Please notice that this exercise is assuming that you have environment with url http://intranet.contoso.com in your usage. If you use some alternative url, you’ll have to update scripts and use correct entries in exercises to make exercise to work properly.
In the lab setup you will execute a PowerShell script that will create a new SharePoint site collection.
1. Start the Virtual Machine in Hyper-V.
2. Log on to the Virtual Machine as the local administrator with a user name of Contoso\Administrator and a password of pass@word1.
3. Open Windows Explorer and browse to the location C:\Student\Labs\Contoso.Intranet, in the folder double click Contoso.Intranet.sln to start the previously created solution structure.
In this exercise we will create simple application page to list features, which could be upgraded. This exercise will familiarize you to feature framework object model and how we can use that for upgrading features granularly. Notice that depending on the actual deployment, you might actually want to upgrade your features using PowerShell, not by adding this kind of additional application page to site settings page also to avoid accidental upgrades by other end users.
1. Expand Layouts folder in the Solution Explorer
2. Right click Contoso.Intranet folder and choose Add – New Item…
3. Choose Application Page template and name it as UpgradePage.aspx
4. Click Add
5. Locate ContentPlaceHolder with the Id PlaceHolderMain
6. Update place holder as in the following code snipped to include two different tables
7. Save changes
8. Open Upgradepage.aspx.cs file under the aspx file
9. Add following using statements
10. Add override for CreateChildIControls method as follows below the Page_Load method · Notice that we use QueryFeatures method to query features which can be upgraded
11. Add following DisplayFeature method below the CreateChildControls method
12. Add btnUpgrade_Click event handler below DisplayFeature method
13. Right click the SPIs folder in the solution explorer and choose Add – New Folder
14. Name folder as CustomActions
15. Right click CustomActions folder and choose Add – New
16. Choose Empty template and name it as FeatureUpgradeSiteSettings and click Add
17. Update the Elements.xml file for the custom action as follows
18. Update feature association for the just added custom action FeatureUpgradeSiteSettings so that it’s activated in the SiteMainResources feature
19. Open SiteMainResources feature and use properties window to set the version to 126.96.36.199
20. Right click Contoso.Intranet and choose Deploy
21. Move to address http://intranet.contoso.com
22. Move the Site Settings from the Site Actions
23. Click Site collection features under the Site Collection Administration
24. Activate Contoso.Intranet Site Main Resources feature
25. Move back to Site Settings page and ensure that the Site Collection Feature Upgrade link is present under the Contoso Configuration
26. Click Site Collection Feature Upgrade link is present under the Contoso Configuration to ensure that code is working properly
1. Move back to Visual Studio side
2. Expand SPIs folder, right click SiteColumns and choose Add – New Item
3. Choose Empty Element and name it as v2Fields
4. Update the Elements.xml as in the following code snipped
5. Save changes
6. Expand Features node and open up Contoso.Intranet Site Main Resources feature
7. Associate the v2Fields to Contoso.Intranet Site Main Resources feature. You can use packaging explorer to ensure the current associations.
8. Expand SPIs folder and ContentTypes folder in the solution explorer
9. Open Contract content type element.xml file and review the content – notice that our field is not present and it should not be added here either
Upgrading content types – what to do and what not to do?
You should NEVER EVER update content type definition which has been already deployed to any site collection. This would not result outcome you’re looking for. When we are updating existing content types, we’ll need to do two different things.
Update initial definition for new site collections – even for this, you should not update actual ContentType definition, since that would break reference to it from existing site collections. What we’ll need to do is to add some code to add newly added field to existing site collection from feature receiver.
Update existing content types – Most reliable way to do this also by using code – by adding required changes to feature upgrade method, which is called when feature is upgraded to latest version.
We’ll cover both approaches in following steps in this exercise.
10. Open Page content type element.xml file and review the content, notice hat our new field is not present and should not be added here either
11. Let’s start by handling upgrade scenario for existing site collections. Expand the SiteMainResources feature node and open up SiteMainResources.Template.xml file by double clicking it
12. Update the template file as follows, so that there’s few upgrade actions to perform, when we upgrade from previous version to newer one
13. Update [PAGEID] and [CONTRACTID] stamps in the just copied xml element with the proper identifiers. You can locate the ID’s from the following locations. These refer to unique identifiers of the content types in following files:
More on feature upgrade options and techniques
You can find more information on the feature upgrade options and techniques from Internet. In this case we used ApplyElementManifest first to introduce new field to site collection. After that we are using CustomUpgradeAction element to which we write the required code in following step – in this case are also using custom upgrade action to provision newly added fields to existing content type.
There’s also out of the box element for updating existing content type declaratively, but since this element have been having some issues in certain cumulative updates, it’s more reliable to use custom code, which we will include to our feature receiver. This also gives us additional change to perform additional confirmation or code validation, if needed for the code.
14. Since we will manipulate Publishign object model, we’ll need to add reference to Microsoft.SharePoint.Pulbishing.dll
15. Right click References in the Contoso.Intranet project and choose Add Reference…
16. Move to Browse tab and move to folder C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\ISAPI
17. Select Microsoft.SharePoint.Publishing.dll and click OK
18. Open SiteMainResources.EventReceiver.cs to see the content of the feature receiver
19. Add following override for FeatureUpgrading below FeatureDeactivating method
20. Let’s continue by adding that required business logic to our project by right clicking Contoso.Intranet and choose Add – Folder
21. Rename newly added folder as ApplicationLogic
22. Right click ApplicationLogic folder and choose – Add Item…
23. Choose Class and name it as UpgradeManager.cs
24. Your solution should be looking like in following picture
25. Open just added UpgradeManager.cs file
26. Add following using statements to file
27. Let’s also change the class to be static and include required business logic methods as follows
28. Before this class can be used in feature receiver, we’ll need to also add using statement for that, so let’s open SiteMainResources.EventReceiver.cs to see the content of the feature receiver
29. Add following using statements to file
30. Open Contoso.Intranet Site Main Resources feature in designer and use properties window to set the version to 188.8.131.52
31. Right click Contoso.Intranet and choose Build
32. To handle content type change requirements in proper way, let’s open SiteMainResources.EventReceiver.cs one more time. Let’s update the feature activated event as follows – notice that we add the required code for adding programmatically field to content types.
33. Update [PageID] and [CONTRACTID] stamps in the just copied xml element with the proper identifiers. You can locate the ID’s from the following locations. These refer to unique identifiers of the content types in following files:
23. Right click Contoso.Intranet and choose Package
24. Right click Contoso.Intranet and choose Open Folder in File Explorer
25. Move to bin – debug sub folder and verify that you have compiled successful Contoso.Intranet.wsp file, which is the actual solution package to be deployed
26. Copy current path to clip board, since we need to use that in PowerShell. If you are using defined guidance, path is following - C:\StudentWebTemplate\Labs\Contoso.Intranet\Contoso.Intranet\bin\Debug
27. Open SharePoint 2010 Management Shell from Start | All Programs | Microsoft SharePoint 2010 Products
28. Run following command in the PowerShell window
Upgrade or Re-deploy
In this case we used Update-SPSolution cmdlet, but you could also do retract and deploy commands in PowerShell script. Difference is that when we use update command, none of the feature installed or uninstalled methods are executed, but if you have added features to your package, those don’t get installed either.
If you use retract – deploy method, feature installed and unistalled commands will be executed and possible new features are automatically installed. Key point to notice though that both options don’t activate or deactivate features in the sites, like Visual Studio does. This is critical difference between development and production environment deployments.
29. Run command “iisreset” in the PowerShell to ensure that updated xml files will be loaded to memory
30. Open Internet Explorer and browse to site http://intranet.contoso.com
31. Make sure that front page has not been checked out – you can publish it manually before moving forward
32. Move to Site Settings page from the Site Actions
33. Click Site Collection Feature Upgrade link under Contoso Configuration
34. Notice that the Contoso.Intranet Site Main Resources feature is listed here as possibility to upgrade
35. Click Upgrade button
36. Refresh page by pressing [F5] and verify that feature is not anymore listed to be upgrade
37. Move back to Site Settings page
38. Move to Site Content Types
39. Click Contoso.Intranet – Contract and ensure that Additional details fields has been added to content type
40. Move back to front page of the site and verify that web part was successfully added to the page
Upgrading features without custom application page
In this exercise we created custom application page to update feature. Depending on environment, PowerShell is much more convenient so that you have full control when upgrade is executed and nobody will upgrade features accidently just from the browser user interface.