Web Deploy Packages for a module
Use this reference to create Web Deploy Packages.
The following sections describe references and commands you can use to create Web Deploy Packages (WDPs) that you can deploy either on-premise or on Azure, using ARM templates.
Before you start, you must install the Sitecore Azure Toolkit and load the commandlets into a PowerShell session. The required commandlets are defined in the following files:
tools\Sitecore.Cloud.Cmdlets.dlltools\Sitecore.Cloud.Cmdlets.psm1
You can use a Sitecore module ZIP package or a Team Development for Sitecore .update package and convert it into an equivalent .scwdp.zip package that is compatible with MSDeploy by using the following PowerShell call:
ConvertTo-SCModuleWebDeployPackage [-Path] <string> [[-Destination] <string>]
Note
Only added items and files are supported in .update packages.
Parameters | Description |
|---|---|
| The path to the original module ZIP package (or an .update package created by Team Development for Sitecore). |
| The path to the file or folder that you want to save the generated package into. |
This creates a .scwdp.zip package with the following content:
Content | Description |
|---|---|
| The files that you want to install on the website. |
| Post step of the original package, if it was defined. |
| The SQL script that installs items into the core database. This file is only present when the package installs items in the core database. |
| The SQL script that installs items into the master database. This file is only present when the package installs items in the master database. |
The .scwdp.zip package accepts the following parameters:
Parameter | Description |
|---|---|
| The path to the website where you will install the application (use an IIS application name or a physical folder path). |
| The connection string that connects to the core database during installation. This parameter is only added when the original package installs items onto the core database. |
| The connection string that connects to the master database during installation. This parameter is only added when the original package installs items onto the master database. |
Advanced scenarios
Refer to the following sections (Applying transformations, Embedding dynamic transformations, Embedding files into the package, Adjusting parameters, Invoking multiple commands in a row, Testing your package) if you want to perform more advanced scenarios, such as:
Changing the default module configuration when you install it on Azure, for example, if you want to enable App Insights or Azure Cognitive Search integration.
Generating multiple WDPs for different roles or configurations from a single Sitecore ZIP as a part of your build pipeline.
Installing a new database together with the module.
Updating a database (including adding new tables or users and roles), when installing a module.
Adding parameters to make a package installation more configurable.
You can apply transformations to configure your module in the following scenarios:
If you want a non-standard installation of a module on Azure. For example, to enable Azure Cognitive Search integration or to tweak performance parameters.
You can also use transformations to create role-specific packages from a single source package.
Note
You can only apply transformations to the content of a module package, that is, the transformations can only affect the files that the module delivers.
Use the following as a reference:
Update-SCWebDeployPackage [-CargoPayloadPath] <string[]> [-Path <string>] [-WhatIf]:
Parameters | Description |
|---|---|
| An array of paths to the SCCPL files that apply to the WDP. |
| The path to the WDP that you want to modify. |
| A switch that enables a dry run of the transformation and produces the actions that would be performed, without modifying the package. |
Dynamic transformations allow a module to transform the target Sitecore installation at the time the module is installed. For example, you can add an HTTP handler to the Web.config file.
Note
Dynamic transformations are applied to the entire Sitecore installation when the module package is deployed and can affect any preexisting files. Improper use of dynamic transformations can make your Sitecore instance unusable.
Use the following reference:
Update-SCWebDeployPackage [-EmbedCargoPayloadPath] <string[]> [-Path <string>] [-WhatIf]
Parameters | Description |
|---|---|
| An array of paths to the SCCPL files that embed into the WDP. .Transformations are stored in the Content/Website/App_Data/Transformations folder and applied by Bootloader during the installation process. |
| The path to the WDP that you want to modify. |
| A switch that enables a dry run of the transformation and produces the actions that would be performed, without having to modify the package. |
SCCPL transformations are convenient to add prebuilt sets of files and configuration changes into WDPs. However, you can also embed individual files, for example, dacpac files, for new databases into a WDP.
Use the following reference:
Update-SCWebDeployPackage [-SourcePath] <string> [-Path <string>]
Parameters | Description |
|---|---|
| The path to the directory that contains the files that you want to add. |
| The path to the WDP that you want to modify. |
If you want to customize your deployment process, or if you need to deploy dacpac or SQL files with the module, you must create and embed a custom parameters.xml file into your deployment package. You can also define parameters by using the reference for IIS Web Application packages.
When you apply a parameters.xml file to your WDP, SAT automatically regenerates the package manifest to include the files you reference in your parameters. This means that your parameters.xml file becomes a kind of manifest, describing what is inside the package.
The following command adds parameters and regenerates the manifest:
Update-SCWebDeployPackage [-ParametersXmlPath] <string> [-Path <string>]
Parameters | Description |
|---|---|
| The path to the |
| The path to the WDP that you want to modify. |
It is also possible to pipe commands in a single command line:
$WDP = ConvertTo-SCModuleWebDeployPackage $ZIP or $Update | `Update-SCWebDeployPackage -CargoPayloadPath @($SCCPL) | `Update-SCWebDeployPackage -SourcePath $DACPAC | `Update-SCWebDeployPackage -ParametersXmlPath $Parameters
When using .Net, replace ConvertTo-SCModuleWebDeployPackage with dotnet, publish, and then manipulate the WDP as usual.
With Microsoft Web Deploy you can test your package installation on a local system with the following command line:
msdeploy -verb:sync -source:package=%CD%\test.scwdp.zip -dest:archiveDir=%CD%\output -setParam:X=TESTVALUE
Use DisableDacPacOptions to create tables or users when you are deploying. You must disable SqlDatabaseOptions for the module WDP package if you want to deploy them to an on-premise instance. If you do not disable SqlDatabaseOptions, msDeploy will try to convert the contained database into an uncontained database and the attempts to apply these options while deploying the module package produces the wrong result.
The property, DisableDacPacOptions, that is available for ConvertTo-SCModuleWebDeployPackage and Update-SCWebDeployPackage, allows you to configure disabling the SqlDatabaseOptions for a module package.
The default value is empty. This means that the database options of the module WDP package is synched for all uses of dbdacfx.
If you provide the value: "*", then all uses of the dbdacfx provider will have the provider property, ScriptDatabaseOptions, set to "false". You may also receive a list of dbdacfx paths.
The following code samples are examples of:
Disabling
SqlDatabaseOptionsfor alldbdacFxusers.ConvertTo-SCModuleWebDeployPackage -Path .\example.zip -Destination .\output -DisableDacPacOptions '*'
Disabling
SqlDatabaseOptionsfor particulardbdacFxpaths.Update-SCWebDeployPackage -ParametersXmlPath .\parameters.xml -Path .\example.scwdp.zip -DisableDacPacOptions 'core.dacpac', 'master.dacpac'