This topic describes using the Sitecore Azure Toolkit to package a local Sitecore instance into Web Deployment packages (WDPs) ready for deployment to the Microsoft Azure App Service®. This functionality is only required for packaging customized local Sitecore solutions. You can download WDPs for standard Sitecore solutions from the Sitecore Experience Platform download page.
Sitecore Azure Toolkit does not currently support packaging local XConnect components into roles. Standard WDPs for the roles: Collection, Reference Data, Marketing Automation, Collection Search, and Marketing Automation Reporting are available as part of the packages downloadable from the Sitecore Experience Platform download page.
This topic describes:
Before you start the packaging process, you must have:
- A local Sitecore instance that you use as input to the packaging process. The Sitecore Azure Toolkit supports packaging Sitecore instances that are installed with the installation program or from a ZIP file and uses the default folder structure.
- The Microsoft Data Tier Application Framework (DAC Fx). This framework is usually installed with Microsoft SQL Server® or Microsoft Visual Studio®. You can also download DAC Fx from the Microsoft Download Center.
- The Sitecore Azure Toolkit installed according to the instructions described in Getting Started with Sitecore Azure Toolkit.
During the process of packaging Sitecore to work correctly on Azure, the Sitecore Azure Toolkit will create one or more WDPs. Each of the WDPs contains the original Sitecore installation, transformed into the structures and configurations required to install a specific Sitecore role on an appropriate resource within Azure.
For example, the Content Management role in a 'Small' sized Sitecore Experience platform deployment, hosts exclusively on an Azure Web Apps resource. To ensure it works when deployed on that resource, you must ensure that the configuration uses Azure search as its content search provider. While the WDP for the Content Management role is being packed, instructions for this configuration enablement are provided to the process through a Sitecore Cargo Payload file (SCCPL).
Sitecore provides all the required SCCPL files to package a standard Sitecore installation into the various topologies deployable on Azure. These files are within the CargoPayloads folder that is part of the Sitecore Azure Toolkit download. However, to meet custom deployment requirements for a customized installation, you might have to extend, customize, or add to these files.
Invoking the packaging command
To start the packaging process, you import the Sitecore Azure Toolkit PowerShell module and invoke the
You must run the following commands in Microsoft Windows PowerShell® in the folder where the Sitecore Azure Toolkit is installed:
> Import-Module .\tools\Sitecore.Cloud.Cmdlets.psm1
> Start-SitecoreAzurePackaging [-sitecorePath] <String> [-destinationFolderPath] <String> [-cargoPayloadFolderPath] <String> [-commonConfigPath] <String> [-skuConfigPath] <String> [-parameterXmlPath] <String> [[-fileVersion] <String>]
Start-SitecoreAzurePackaging commandlet has the following parameters:
The path to either a Sitecore instance website folder of the Sitecore installation to be packaged or a packaged Sitecore instance folder in a zip file.
An example of a path to a website folder:
The folder where the generated packages are to be stored.
An example of a path to store the generated packages:
The path to the folder containing the Sitecore version-specific role and feature transformation files.
An example of the path for the Sitecore 9.0 specific role and feature transformation files:
The path to the file that contains a list of the transformations files to be applied to all of the roles.
An example of the path for the file containing all the generic transformations required for Sitecore 9.0:
The path to the file that contains the lists of role-specific transformations for the selected Sitecore version and the Sitecore configuration on the Microsoft App Service.
Examples of the paths to the files that contain the role-specific transformations for Sitecore 9.0:
For XM small to extra-large configurations,
For XP small to extra-large configurations,
For XP single configurations,
The path to the WebDeploy Sitecore version-specific archive manifest and parameter declaration files.
An example of the paths to the WebDeploy Sitecore version and role-specific archive manifest and parameter declaration files for Sitecore 9.0:
An optional parameter that allows you to embed a version marker in the generated WebDeploy packages. The marker is stored in the
Example of a version marker:
When invoked, the
Start-SitecoreAzurePackaging commandlet produces a number of WebDeploy packages in the destination folder. All packages follow the same name pattern, which includes the role name, for example,
Sitecore 9.0 rev. 171002_cm.scwdp.zip.
Sometimes the commandlet also generates an intermediate WDP package with no role-specific suffix in its name. You can ignore this package during deployment.
A packaging example
The following code sample shows how to use the
Start-SitecoreAzurePackaging commandlet to prepare WDP packages for an XP configuration. The sample assumes the following:
- Sitecore is installed locally in
C:\inetpub\example, and the website folder is
- Sitecore Azure Toolkit is installed in
- Generated packages are stored in
# Import commandlets
# Set the parameter variables
# Create the output folder
# Start the packaging process
-sitecorePath "$Website" `
-destinationFolderPath $Output `
-cargoPayloadFolderPath "$Resources\cargopayloads" `
-commonConfigPath "$Resources\configs\common.packaging.config.json" `
-skuConfigPath "$Resources\configs\$SKU.packaging.config.json" `
-parameterXmlPath "$Resources\msdeployxmls" `
The package(s) created by the commandlet are dependent on the Sitecore configuration requested during packaging. Typically, there is one WDP per role so, for example, an XM topology would have one WDP produced for the Content Management role and another one for the Content Delivery role.