WebTemplate training materials – Lab 4 - Upgrading existing sites with feature versioning
|
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.
- WebTemplate training materials – Introduction to material
- WebTemplate training materials – Lab 1 - Creation of features and basic structures
- WebTemplate training materials – Lab 2 - Creation of custom navigation control and master pages
- WebTemplate training materials – Lab 3 - Creation of WebTemplate for WCM site
- WebTemplate training materials – Lab 4 - Upgrading existing sites with feature versioning
This particular post will concentrate on following functionalities.
- Creating application page to site settings to manage feature versions
- Update previously deployed content type by adding new field to it
- Creating feature upgrade definitions for the existing features to update existing sites
Lab 04 – Life cycle management for WebTemplate created publishing sites
The project files for this lab are in the ‘C:\Student\Labs\04_Lifecycle’folder
Lab Objective
Lab Overview: In this lab you will update existing sites using feature upgrade definition.
Additional Resources
This lab includes the following additional resources:
Starter Files |
C:\Student\Labs\04_Lifecycle\StarterFiles |
Files that can be used to help complete the labs. |
Source Code |
C:\Student\Labs\04_Lifecycle\Solution |
Completed lab source code after this exercise |
Solution structure |
C:\Student\Labs\Contoso.Intranet\ |
Solution structure started in previous exercise. |
Getting Started
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 https://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.
Lab Setup Instructions
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.
- This step assumes that you have already created lab 1, 2 & 3 based on the lab guidance’s, so that we can continue building up the customization package.
- Notice also that package contains full source code status after lab 3 in folder C:\StudentWebTemplate\Labs\03_WCM\Solution\Contoso.Intranet - Lab 3 which you can copy as your starting point if you want to skip previous labs completely.
Exercise 1 – Creating upgrade application page
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.
Task 1 – Adding custom application page to solution
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 1.0.0.0
20. Right click Contoso.Intranet and choose Deploy
21. Move to address https://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
- Page should list all activated features in site collection scope and their version
- Notice that look and feel depends on which master page has been enabled for the system pages.
Task 2 – Updating features and content types
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.
- This is done for new site collections, so that now added field is added automatically when new sites are created. Steps to modify existing sites will follow up later in this exercise.
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
|
| |
| 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. | |
![clip_image014[1]](https://msdntnarchive.blob.core.windows.net/media/MSDNBlogsFS/prod.evol.blogs.msdn.com/CommunityServer.Blogs.Components.WeblogFiles/00/00/00/81/08/metablogapi/7713.clip_image0141_463EFB2A.png "clip_image014[1]"){kind=small}
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
- Notice that we use one out of the box feature upgrade action and then we’ll include two custom feature upgrade actions to handle more specific updates on our existing site collection.
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:
- [PAGEID] – SPIs – ContentTypes – Page – Elements.xml
- [CONTRACTID] – SPIs – ContentTypes – Contract – Elements.xml
|
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
- Notice that we place our actual business logic code for updating existing sites outside of the feature receiver, which gives us possibility to test that business logic separately without need for feature receiver deployments etc.
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
![clip_image002[1]](https://msdntnarchive.blob.core.windows.net/media/MSDNBlogsFS/prod.evol.blogs.msdn.com/CommunityServer.Blogs.Components.WeblogFiles/00/00/00/81/08/metablogapi/7343.clip_image0021_52D82C2C.jpg "clip_image002[1]")
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 2.0.0.0
31. Right click Contoso.Intranet and choose Build
- Notice that until now we’ve only added code for handling upgrade of the existing structures, we’ll still need to ensure that if new site collections are created where this site collection scoped feature is activated, content types will match on latest requirements
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.
- Again – just to emphasis why we did above add-in to feature activation, not on xml. This is for newly created site collections, since we should NOT be updating ContentType xml definition anymore, since we have already that used in one site collection in our environment.
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:
- [PAGEID] – SPIs – ContentTypes – Page – Elements.xml
- [CONTRACTID] – SPIs – ContentTypes – Contract – Elements.xml
23. Right click Contoso.Intranet and choose Package
- Note. DO NOT DEPLOY PACKAGE DIRECTLY FROM VISUAL STUDIO, since we will imitate production upgrades in following steps and if you use Visual Studio, your upgrade option is not available since Visual Studio will “try to help you” and it reinstalls features using activate/deactive commands, which doesn’t happen in actual production deployments.
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
- Notice that path depends on your solution structure location
| Update-SPSolution -Identity contoso.intranet.wsp -LiteralPath "C:\Student\Labs\Contoso.Intranet\Contoso.Intranet\bin\Debug\Contoso.Intranet.wsp" –GACDeployment |
|
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 https://intranet.contoso.com
31. Make sure that front page has not been checked out – you can publish it manually before moving forward
- This is just due the code for the feature receiver, which doesn’t have exception handling if the page has been checked out.
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
- This will execute the FeatureUpgrading event definitions (code and xml based configurations)
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
- You might want to verify successful update also on content type instances provisioned to existing lists, like pages list. You can do this by moving to list where content type is used and checking content type properties from list settings.
40. Move back to front page of the site and verify that web part was successfully added to the 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. |
![clip_image014[2]](https://msdntnarchive.blob.core.windows.net/media/MSDNBlogsFS/prod.evol.blogs.msdn.com/CommunityServer.Blogs.Components.WeblogFiles/00/00/00/81/08/metablogapi/1513.clip_image0142_3FA82942.png "clip_image014[2]"){kind=small}
If you find any issues on the lab, please add comments below, so that we are able to fix them as fast as possible. You can also suggest any enhancements for the lab, but due other on-going projects, I can’t promise to have time to include them. Thanks for your comments and feedback advance.
- Vesku