The content you're reading is getting on in years
This post is on the older side and its content may be out of date.
Be sure to visit our blogs homepage for our latest news, updates and information.
There are two types of modules in Sitefinity – static and dynamic. Dynamic modules are much easier to work with and we recommend you use those, unless you have very specific requirements that are not supported (hierarchies, complex data models, integrations with other systems). There are still cases where customers use static modules and we often get questions about them. This blog post will explain how Sitefinity installs static modules and how you can take advantage of this process to upgrade older versions that are already used.
In most cases it is safe to assume that you’re starting to build a Sitefinity module from scratch. However, this is not always the case. As vendors of a product that needs to be upgraded on customer premises, we know this well. As a module developer, you might want to sell your module to third parties or change/add functionality when it is already working with live data in production. This changes after your module has shipped are what we call a module upgrade. Although the code for your module is always replaced, sometimes you need to change the schema and data that your module manages.
Apart from the data model and API of your module, you always need to create a module class. This class is how Sitefinity knows that you actually have a module – it is your module’s entry point. There are three important member methods that take part in the installation and upgrade of a module - Install, Initialize and Upgrade.
To understand how to implement those methods, first you need to know how Sitefinity uses them when stating up all modules.
When the Sitefinity application starts, it goes through all registered modules in configuration and decides whether they should be installed or upgraded, according to the above flowchart.
Entries for all registered modules in the configuration look like this:
As you can see, all decisions involve the current version of the module stored in its configuration element. The first time Sitefinity installs your module, it will set the version to the version of the module assembly. From then on, you can control when the upgrade method for your module gets called by managing the version of the assembly.
By default, when you create a class library project in Visual Studio, the assembly version is static and is set to 18.104.22.168. You can change this from the AssemblyInfo.cs file, under Properties. For Sitefinity assemblies, we always manually set the major and minor version. The build number is automatically incremented. You can do the same for your custom modules.
// Version information for an assembly consists of the following four values:
// Major Version
// Minor Version
// Build Number
// You can specify all the values or you can default the Build and Revision Numbers
// by using the '*' as shown below:
// [assembly: AssemblyVersion("1.0.*")]
Note: For more information you can read Assembly Versioning on MSDN.
Once you have control over the assembly version of your module, you can use that to execute custom logic whenever you module is upgraded. When Sitefinity calls your Upgrade method, it always supplies the old version in an argument.
You as the developer of the module should know what changes you’ve made between different versions and execute code that updates your model to work with the newer version. It might be the addition of a new persistent class or property of an existing one, a new relation between persistent items, etc.
Upgrade(SiteInitializer initializer, Version upgradeFrom)
(upgradeFrom.Build > 2500)
// upgrading from 5.0
(upgradeFrom.Build > 2800)
// upgrading from 5.0 SP1
(upgradeFrom.Build < 1800)
// upgrading older versions - change schema
This method gives you control over what happens when someone replaces your module assembly with a new one. We advise everyone who submits modules to the Sitefinity marketplace to use these versioning mechanisms. They makes managing upgrades much easier and prevent any need to communicate directly with the users of your module for detailed instructions. If all this seems too complex, this is yet another reason to use dynamic modules. They have no need of upgrades and similar scenarios are handled seamlessly by Sitefinity.
View all posts from The Progress Team on the Progress blog. Connect with us about all things application development and deployment, data integration and digital business.
Subscribe to get all the news, info and tutorials you need to build better business apps and sites
Copyright © 2019 Progress Software Corporation and/or its subsidiaries or affiliates.
All Rights Reserved.
Progress, Telerik, and certain product names used herein are trademarks or registered trademarks of Progress Software Corporation and/or one of its subsidiaries or affiliates in the U.S. and/or other countries. See Trademarks for appropriate markings.