Sitecore Azure Toolkit

Web Deploy Packages for a module

Abstract

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 tools\Sitecore.Cloud.Cmdlets.dll file.

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 using the following PowerShell call:

ConvertTo-SCModuleWebDeployPackage [-Path] <string> [[-Destination] <string>]

Parameters

Description

Path

The path to the original module ZIP package (or an .update package created by Team Development for Sitecore).

Destination

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

Content/Website/*

The files that you want to install on the website.

Content/Website/App_Data/Poststeps/*.poststep

Post step of the original package, if it was defined.

core.sql

The SQL script that installs items into the core database. This file is only present when the package installs items in the core database.

master.sql

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:

Application Path

The path to the website where you will install the application (use an IIS application name or a physical folder path).

Core Admin Connection String

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.

Master Admin Connection String

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 transformationsEmbedding files into the packageAdjusting parametersInvoking multiple commands in a rowTesting 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 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 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

CargoPayloadPath

An array of paths to the SCCPL files that apply to the WDP.

Path

The path to the WDP that you want to modify.

WhatIf

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

EmbedCargoPayloadPath

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.

Path

The path to the WDP that you want to modify.

WhatIf

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

SourcePath

The path to the file that you want to add.

Path

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

ParametersXmlPath

The path to the parameters.xml file that you want to embed.

Path

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 SqlDatabaseOptions for all dbdacFx users.

    ConvertTo-SCModuleWebDeployPackage -Path .\example.zip -Destination .\output -DisableDacPacOptions '*'
    
  • Disabling SqlDatabaseOptions for particular dbdacFx paths.

    Update-SCWebDeployPackage -ParametersXmlPath .\parameters.xml -Path .\example.scwdp.zip -DisableDacPacOptions 'core.dacpac', 'master.dacpac'