EPiServer CMS Installation and Deployment System Overview
EPiServer CMS 5 R2 SP1
Document last saved:
The new EPiServer Installation and Deployment System was introduced as part of EPiServer CMS 5 R2. It has since been built upon and shipped with the EPiServer Relate+ and EPiServer Community products.
For information about EPiServer CMS 5 R2 installation see the Instructions Instructions document.
Table of Contents
- Installing the System
- On the surface - User Interface
» EPiServer Deployment Center
» Task Wizards
» EPiServer Deployments API
- Under the covers - how it works
» System Flow
» Script Flow
» EPiServer PowerShell Snap-ins
» User Interface Wizards
» Deployment API
Installing the system
Although the Installation and Deployment System is shipped with many of the EPiServer products, such as EPiServer CMS 5 R2 SP1, Relate+ and Community; it is not a standalone product in itself. The system is separated into two parts, a common part that is used by all EPiServer products and a product specific part for each product.
The common part is installed under the <Program Files>\EPiServer\Shared\Install folder and the product specific parts are installed under <Program Files>\EPiServer\ProductName\ProductVersion\Install where ProductName is the product name such as CMS or Relate+ and ProductVersion is the version number of that product.
The EPiServer Deployment Center is the user interface of the EPiServer Installation and Deployment System (the original version shipped with EPiServer CMS 5.2 was known as EPiServer Installation Manager). It is used to browse and execute the actions that are available for the products installed. Examples of such actions are: Creating EPiServer (CMS/Community/Relate+) Web sites, removing EPiServer Web sites, installing modules onto EPiServer Web sites etc.
Figure 1 below shows the main task selection screen in the EPiServer Deployment Center:
All installed EPiServer products that support EPiServer Deployment Center are shown in the tree under “Installed Products. Under each product node there is a version node for each version of the product installed. The tasks that can be performed for/on the product version are listed under the product version node.
Most tasks listed in the Deployment Center have an associated user interface wizard. A wizard is one or more pages where information needed to perform the task is collected from the user. Most wizards show a summary page before execution as final confirmation about what is going to happen. Figures 2 and 3 show examples of wizard pages from the EPiServer CMS Install Site (SqlServer) Wizard.
The wizard summary page is shown above which gives details of the Web site, database and other resources that will be created by the task.
When the task is running, a progress dialog is shown to keep the user informed. Figure 4 shows an example of this:
The figure above shows the progress when a task is run from the EPiServer Deployment Center. The dialog can be hidden, in this case a message box will be shown when the task has completed.
The tasks that appear in the EPiServer Deployment Center are actually implemented as PowerShell scripts. More information about Windows PowerShell can be found on microsoft.com.
It is these PowerShell scripts that decide if a user interface wizard should be shown to the user to collect input information and then subsequently carry out the task in hand using a combination of in-built PowerShell functionality and EPiServer’s Deployment API.
EPiServer Deployment API
The EPiServer Deployment API is a managed code set that can perform actions to create, delete and manipulate Web sites, databases, files, folders and much more in a transactional manner. The API also includes re-usable wizard controls and classes.
As mentioned in the Installing the system section in this document, the system is divided into common and product specific parts with the Deployment API being a prime example of this.
The EPiServer Deployment Center enumerates configurable folders on the system to locate primarily, Metadata files (.metadata) and secondarily, PowerShell files (.ps1). The folders searched are defined in the EPiServerInstall.exe.config file located in the <Program Files>\EPiServer\Shared\Install folder.
If Metadata files are found then these are used to populate the tree with task nodes. Otherwise, if only PowerShell script files are found (this is how CMS 5.2 pre. SP1 works) then the PowerShell file names are used to populate the tree with task nodes.
The Metadata files, if present, are XML files that contain information about what tasks are available to the Deployment Center. The XML elements describing each task have an attribute point to the PowerShell script that should be run to carry out the task. For futher information regarding this see the technical note XML Update Reference technical note.
The PowerShell scripts developed by EPiServer typically have the same logical flow as shown below:
A PowerShell snap-in is a managed .NET assembly that plays hosts to special classes called Cmdlets (pronounced commandlets). A cmdlet class derives from one of the Microsoft base classes (Cmdlet or PSCmdlet) and provides a function which is callable from PowerShell using a noun and verb. The noun and the verb together product the function name, e.g. Get-EPiWebApp. More detailed information can be found about PowerShell snap-ins and cmdlets in the Windows PowerShell Programmer's Guide.
EPiServer currently provides 3 PowerShell snap-ins:
- The ‘EPiServer.Install.SnapIn.5.2.375.7‘snap-in which shipped with EPiServer CMS 5.2. This provides the cmdlets to manage and deploy EPiServer CMS 5.2 entities. This snap-in is superseded by the following snap-ins for later version of CMS
- The ‘EPiServer.Install.Common.1’ snap-in which ships with EPiServer Relate+, EPiServer Community 3 and EPiServer CMS 5.2 SP1 products. This provides the cmdlets to manage and deploy EPiServer product entities.
- The ‘EPiServer.Install.CMS.5.2.xxx.xx’ (exact version unknown at time of writing) snap-in which ships with EPiServer CMS 5.2 SP1. This provides the cmdlets to manage and deploy EPiServer CMS specific entities.
More information about the cmdlets available in the EPiServer snap-ins can be found in the tech note EPiServer for PowerShell applications.
The UI Wizards are shown by the PowerShell scripts in order to collect input information for the task from the user. The EPiServer Deployment API contains a base class for wizards, EPiServer.Install.UI.WizardBase. The base class provides the entire wizard infrastructure (modal dialog, next, back, cancel functionality etc) so all the derived class needs to define is the pages to be shown in the wizard. Each page is actually an instance of a class derived from System.Windows.Forms.UserContol. The EPiServer Deployment API contains many pre-defined ‘pages’ for typical scenarios (Web site creation, database creation, folder creation etc).
The derived wizard class needs to override the PreShow and PostShow methods of WizardBase. In the PreShow method, the class should initialize its page user controls and then add them to the WizardBase.Pages collection. In the PostShow method, the class should take the opportunity to process the information entered by the user into the page user controls and set its public properties appropriately to enable the PowerShell script to read them and carry out its task.
The EPiServer Deployment API can be sliced both horizontally, in terms of functionality provided, and vertically, in terms of physical implementation layers.
Functionality implemented in the Common Deployment API:
Functionality implemented in the CMS Deployment API:
Each API is made up of a physical 3 tier implementation stack:
The cmdlets are provided to give the PowerShell scripts easy access to the .NET managed API. In most cases, they do not do much in themselves but rather create an instance of the appropriate .NET managed API class for the task and call the appropriate method.
The .NET Managed API is a collection of classes, one for each of the functionality areas, plus a controller class. These classes create and initialize one or more installers for the task they are asked to do and pass them off to the controller for transacted execution.
The installer classes are the ones that perform the actual implementation for the task in hand. Each class derives from the Microsoft base class System.Configuration.Install.Installer. The installer model was chosen as it naturally lends itself to transactions. The controller ensures that all the installers added as part of a bulk install are executed in a transaction. This means that if anything goes wrong in the install phase then the controller will execute a rollback to restore the system to its previous state.