[TechSpeak] How to Package Your Local Sitecore Instance for Microsoft Azure App Service

Updated Apr 8, 2024

For modern businesses, it’s extremely important to be flexible in order to satisfy the constantly changing customer needs. That’s why more and more companies turn to the evolving cloud computing services, which provide scalability, optimize connectivity and improve performance.

Sitecore is not an exception, as it allows you to deploy solutions on the Azure Platform as a Service (PaaS). For a new Sitecore environment, you can use out-of-the-box web deploy packages (WDP). But to deploy your existing (local) solution, you need to initially package it into a WDP.

In this article, I will tell you how you can package your local Sitecore Habitat into web deploy package (WDP). You will also see what issues you might run into during the process.

Guideline

Let’s imagine that you have a local Sitecore instance (in my case Sitecore Habitat) and you would like to deploy this instance into Microsoft Azure as PaaS.

For this purpose, you can use a special tool — Sitecore Azure Toolkit.

Main Sitecore Azure Toolkit features:

Packaging of Sitecore instances into role-specific packages using PowerShell command line programs
Integration with Microsoft Azure services
ARM templates for topologies such as XM, XP, XPSingle
Configuration for running on the Azure App Service
Security features provided by HTTPS, low-privileged SQL access, Sitecore password

Download Sitecore Azure Toolkit current version 2.2 here.

Step 1

To start working on this tool, you just need to extract the downloaded archive to a folder. In my case “C:\Sitecore\Azure Toolkit”.

Also, don’t forget to check that you have all the required prerequisites:

A cloud-hosted MongoDB cluster for the xDB Collection and Tracking databases that are used with XP and XP0. Note: this is a prerequisite for versions earlier than 9.0 only.
.NET Framework 4.6
PowerShell 4.0
Microsoft Azure PowerShell 2.0.1 or later.
Microsoft SQL Server Data-Tier Application Framework (DacFX) for SQL server 2012 or later. Note: this framework is usually installed with SQL Server or Visual Studio.

Step 2

Then, open the root folder where the toolkit is unpacked and load the main module into a PowerShell terminal :

Import-Module .\ tools \ Sitecore . Cloud.Cmdlets.psm1 -Verbose

This module has some commandlets responsible for:

Packaging a module into WDP
Packaging a local instance into WDP
Deployment onto Azure

Our main goal is to make a Sitecore web deploy package ( SCWDP ) based on local Sitecore Habitat instance. Run the following commandlet to achieve this goal:

Start-SitecoreAzurePackaging

This command contains parameters required for executing:

SitecorePath — the path to either a folder where the Sitecore installation should be packaged or to a folder in a zip file.
DestinationFolderPath — the path to the folder for generated packages storage.
CargoPayloadFolderPath — the path to the folder with the version-specific role and feature transformation files.
CommonConfigPath — the path to the file with a list of the transformation files to be applied to all of the roles.
SkuConfigPath — the path to the file with lists of role-specific transformations for the selected version and the Sitecore configuration on the Microsoft App Service.
ParameterXmlPath — the path to the WebDeploy Sitecore version-specific archive manifest and parameter declaration files.
FileVersion — an optional parameter for embedding a version marker in the generated WebDeploy packages.

I will note one more optional parameter a bit later.

Step 3

You should have your local instance on your dev machine. On my local machine, I have a Habitat Sitecore instance.

The website is located in C:\inetpub\wwwroot\habitat.dev.local and published on IIS as habitat.dev.local.

As for my local habitat SQL databases — they all are located in another VM machine.

Step 4

Now, you have to define the destination folder path. I would like to save the generated Sitecore WDP package into C:\Sitecore\WDPs.

I’ve already mentioned that the Azure toolkit is unpacked into:

Let’s populate all the parameters we need to run with Start-SitecoreAzurePackaging command:

$sitecorePath = "C:\inetpub\wwwroot\habitat.dev.local"
$destinationFolderPath = "C:\Sitecore\WDPs"
$cargoPayloadFolderPath = "C:\Sitecore\Azure Toolkit\resources\9.1.1\CargoPayloads"
$commonConfigPath = "C:\Sitecore\Azure Toolkit\resources\9.1.1\Configs\common.packaging.config.json"
$skuConfigPath = "C:\Sitecore\Azure Toolkit\resources\9.1.1\Configs\XPSingle.packaging.config.json"
$parameterXmlPath = "C:\Sitecore\Azure Toolkit\resources\9.1.1\MsDeployXmls"
$fileVersion = "9.1.1"

And define these parameters with a command:

Start-SitecoreAzurePackaging -sitecorePath $sitecorePath -destinationFolderPath $destinationFolderPath `
-cargoPayloadFolderPath $cargoPayloadFolderPath -commonConfigPath $commonConfigPath `
-skuConfigPath $skuConfigPath -parameterXmlPath $parameterXmlPath -fileVersion $fileVersion

Below, you can see how it looks like in my PowerShell ISE terminal session.

Step 5

Finally, it seems that we are ready to click on the green button to run Sitecore Azure Packaging!

But take your time! I instantly caught an error:

The following is the error text:

Connecting to database 'habitat_Core' on server 'test-server'.
Extracting schema
Extracting schema from database
New-SCWebDeployPackage : Connecting to database 'habitat_Core' on server 'test-server'.
Extracting schema
Extracting schema from database
At C:\Sitecore\Azure Toolkit\tools\Sitecore.Cloud.Cmdlets.psm1:195 char:49
+ ... ckagePath = New-SCWebDeployPackage -Path $SitecorePath -Destination $ ...
+              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo       : NotSpecified: (Connecting to d...a from database:String) [New-SCWebDeployPackage], Exception
+ FullyQualifiedErrorId : Microsoft.Extensions.Logging.EventId,Sitecore.Cloud.Cmdlets.Packaging.NewSCWebDeployPackage
System.IO.FileNotFoundException: Could not find file 'C:\Users\vap\AppData\Local\Temp\tempDacPacs1d5912bf-c65a-4c53-8f70-e8a335d6ea37\Sitec
ore.core.dacpac'.
File name: 'C:\Users\vap\AppData\Local\Temp\tempDacPacs1d5912bf-c65a-4c53-8f70-e8a335d6ea37\Sitecore.core.dacpac'
   at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
   at System.IO.FileStream.Init(String path, FileMode mode, FileAccess access, Int32 rights, Boolean useRights, FileShare share, Int32 buff
erSize, FileOptions options, SECURITY_ATTRIBUTES secAttrs, String msgPath, Boolean bFromProxy, Boolean useLongPath, Boolean checkHost)
   at System.IO.FileStream..ctor(String path, FileMode mode, FileAccess access, FileShare share, Int32 bufferSize, FileOptions options, Str
ing msgPath, Boolean bFromProxy, Boolean useLongPath, Boolean checkHost)
   at System.IO.File.InternalReadAllBytes(String path, Boolean checkHost)
   at Sitecore.Cloud.Package.Common.FileSystemProvider.ReadFile(String fileName)
   at Sitecore.Cloud.Packaging.WebDeployPackages.DatabasePackager.PackageDatabases(XDocument connStringFile, Boolean integratedSecurity)
   at Sitecore.Cloud.Packaging.WebDeployPackages.WebDeployPackageBuilder.Build(SitecoreInstallationFolderTree scInstFoldTree, DirPath outpu
tDir, String targetFileName, Boolean force, String version, Boolean integratedSecurity)
   at Sitecore.Cloud.Cmdlets.Packaging.NewSCWebDeployPackage.ProcessRecord()
New-SCWebDeployPackage : System.IO.FileNotFoundException: Could not find file 'C:\Users\vap\AppData\Local\Temp\tempDacPacs1d5912bf-c65a-4c
53-8f70-e8a335d6ea37\Sitecore.core.dacpac'.
File name: 'C:\Users\vap\AppData\Local\Temp\tempDacPacs1d5912bf-c65a-4c53-8f70-e8a335d6ea37\Sitecore.core.dacpac'
   at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
   at System.IO.FileStream.Init(String path, FileMode mode, FileAccess access, Int32 rights, Boolean useRights, FileShare share, Int32 buf
ferSize, FileOptions options, SECURITY_ATTRIBUTES secAttrs, String msgPath, Boolean bFromProxy, Boolean useLongPath, Boolean checkHost)
   at System.IO.FileStream..ctor(String path, FileMode mode, FileAccess access, FileShare share, Int32 bufferSize, FileOptions options, St
ring msgPath, Boolean bFromProxy, Boolean useLongPath, Boolean checkHost)
   at System.IO.File.InternalReadAllBytes(String path, Boolean checkHost)
   at Sitecore.Cloud.Package.Common.FileSystemProvider.ReadFile(String fileName)
   at Sitecore.Cloud.Packaging.WebDeployPackages.DatabasePackager.PackageDatabases(XDocument connStringFile, Boolean integratedSecurity)
   at Sitecore.Cloud.Packaging.WebDeployPackages.WebDeployPackageBuilder.Build(SitecoreInstallationFolderTree scInstFoldTree, DirPath outp
utDir, String targetFileName, Boolean force, String version, Boolean integratedSecurity)
   at Sitecore.Cloud.Cmdlets.Packaging.NewSCWebDeployPackage.ProcessRecord()
At C:\Sitecore\Azure Toolkit\tools\Sitecore.Cloud.Cmdlets.psm1:195 char:49
+ ... ckagePath = New-SCWebDeployPackage -Path $SitecorePath -Destination $ ...
+              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo       : NotSpecified: (System.IO.FileN...ProcessRecord():String) [New-SCWebDeployPackage], Exception
+ FullyQualifiedErrorId : Microsoft.Extensions.Logging.EventId,Sitecore.Cloud.Cmdlets.Packaging.NewSCWebDeployPackage
Could not find file 'C:\Users\vap\AppData\Local\Temp\tempDacPacs1d5912bf-c65a-4c53-8f70-e8a335d6ea37\Sitecore.core.dacpac'.

Hmm. Could not find the generated *.dacpac file in a temp folder. I’ve just checked this folder and found nothing. What could be a reason?

In a stack trace, I see that this happened during “ Extracting schema from database. ”

As I’ve mentioned before, all habitat.dev.local SQL dbs are located on another VM machine. That’s probably why the “sqlpackage.exe” (Microsoft SQL Server command-line tool used by Sitecore Azure toolkit to create a Sitecore database snapshot *.dacpac file from a live SQL Server) was not able to either connect SQL or generate the appropriate *.dacpac file.

I started “dotPeeking” (decompiling) Azure Toolkit binaries responsible for Start-SitecoreAzurePackaging to find the place where sqlpackage.exe joined the game. These are the most involved ones:

Sitecore-commandlets-dotPeek-Binaries-photo

In a while, I figured out a method

Sitecore.Cloud.Packaging.WebDeployPackages.CreateDacPac(string dbConnectionString, string targetFilePath){…}

in the source code where the appropriate dacpac file is being generated.

To test this functionality, I created a simple Console application to check if sqlpackage.exe works as expected. When I executed this app, I got the following output log:

Connecting to database 'habitat_Core' on server '&amp;lt;sql server name&amp;gt;'.
Extracting schema
Extracting schema from database
*** Error extracting database:Could not extract package from specified database.
The reverse engineering operation cannot continue because you do not have View Definition permission on the 'habitat_Core' database.

Aha, I see that a user defined in connection strings (connections that go from the App_Config/ConnectionStrings.config file in your instance) do not have appropriate grant permissions to be able to make a Sitecore.core.dacpac file.

So, I went to SQL server and noticed that “ coreuser” (this user is defined in a “core” connection string) does not belong to db_owner role:

I applied this role, rerun my Console App and got a Success output message:

Connecting to database 'habitat_Core' on server 'test-server'.
Extracting schema
Extracting schema from database
Resolving references in schema model
Validating schema model for data package
Validating schema
Exporting data from database
Exporting data
Processing Export.
Processing Table '[dbo].[AccessControl]'.
Processing Table '[dbo].[Archive]'.
Processing Table '[dbo].[ArchivedFields]'.
Processing Table '[dbo].[ArchivedItems]'.
Processing Table '[dbo].[ArchivedVersions]'.
Processing Table '[dbo].[aspnet_Applications]'.
Processing Table '[dbo].[aspnet_Membership]'.
Processing Table '[dbo].[aspnet_Paths]'.
Processing Table '[dbo].[aspnet_PersonalizationAllUsers]'.
Processing Table '[dbo].[aspnet_PersonalizationPerUser]'.
Processing Table '[dbo].[aspnet_Profile]'.
Processing Table '[dbo].[aspnet_Roles]'.
Processing Table '[dbo].[aspnet_SchemaVersions]'.
Processing Table '[dbo].[aspnet_Users]'.
Processing Table '[dbo].[aspnet_UsersInRoles]'.
Processing Table '[dbo].[aspnet_WebEvent_Events]'.
Processing Table '[dbo].[Blobs]'.
Processing Table '[dbo].[ClientData]'.
Processing Table '[dbo].[Descendants]'.
Processing Table '[dbo].[EventQueue]'.
Processing Table '[dbo].[History]'.
Processing Table '[dbo].[IDTable]'.
Processing Table '[dbo].[Items]'.
Processing Table '[dbo].[Links]'.
Processing Table '[dbo].[Notifications]'.
Processing Table '[dbo].[Properties]'.
Processing Table '[dbo].[PublishQueue]'.
Processing Table '[dbo].[RolesInRoles]'.
Processing Table '[dbo].[SharedFields]'.
Processing Table '[dbo].[Tasks]'.
Processing Table '[dbo].[UnversionedFields]'.
Processing Table '[dbo].[UserLogins]'.
Processing Table '[dbo].[VersionedFields]'.
Processing Table '[dbo].[WorkflowHistory]'.
Successfully extracted database and saved it to file 'C:\Temp\Sitecore.core.dacpac'.
Success

Now, we can see that the “Sitecore.core.dacpac” is created:

Cool! Then, I applied the “db_owner” role to all users under appropriate dbs defined in:

C:\inetpub\wwwroot\habitat.dev.local\App_Config\ConnectionStrings.config

Note:

At the beginning of the article, I’ve mentioned one optional parameter for executing the command Start-SitecoreAzurePackaging:

integratedSecurity

Sitecore-integrated-security-parameter-photo

By default, the value of this parameter is false , which means that the user creds will be used from ConnectionsStrings.config file.

If you specify the value true for this parameter, the process responsible for generating dacpac files will use the current Windows account. But there’s one condition — this account must have administrative rights to access the SQL server.

For some reason, I lost sight of this parameter at the very beginning and, therefore, I had to deal with the problem I described above.

Step 6

Then I executed

Start-SitecoreAzurePackaging -sitecorePath $sitecorePath -destinationFolderPath $destinationFolderPath `
-cargoPayloadFolderPath $cargoPayloadFolderPath -commonConfigPath $commonConfigPath `
-skuConfigPath $skuConfigPath -parameterXmlPath $parameterXmlPath -fileVersion $fileVersion

once again. The issue seems to be gone — the “*.dacpac” files started to appear in a temporary folder, as shown below:

In a few minutes, I got another exception message:

Sitecore-Habitat-Permissions-Issue-photo

The error text:

System.UnauthorizedAccessException: Access to the path 'C:\inetpub\wwwroot\habitat.dev.local\tempConnectionStringeb3ab08c-5c68-4d9d-bf05-8b72f845145c\' is denied.
   at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
   at System.IO.Directory.InternalCreateDirectory(String fullPath, String path, Object dirSecurityObj, Boolean checkHost)
   at System.IO.Directory.InternalCreateDirectoryHelper(String path, Boolean checkHost)
   at DotNet.Basics.IO.DirPath.CreateIfNotExists()
   at DotNet.Basics.IO.FileExtensions.CopyTo(FilePath source, FilePath target, Boolean overwrite, Boolean ensureTargetDir)
   at Sitecore.Cloud.Packaging.WebDeployPackages.WebDeployPackageBuilder.Build(SitecoreInstallationFolderTree scInstFoldTree, DirPath outputDir, String targetFileName, Boolean force, String version, B
oolean integratedSecurity)
   at Sitecore.Cloud.Cmdlets.Packaging.NewSCWebDeployPackage.ProcessRecord()
New-SCWebDeployPackage : System.UnauthorizedAccessException: Access to the path 'C:\inetpub\wwwroot\habitat.dev.local\tempConnectionStringeb3ab08c-5c68-4d9d-bf05-8b72f845145c\' is denied.
   at System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
   at System.IO.Directory.InternalCreateDirectory(String fullPath, String path, Object dirSecurityObj, Boolean checkHost)
   at System.IO.Directory.InternalCreateDirectoryHelper(String path, Boolean checkHost)
   at DotNet.Basics.IO.DirPath.CreateIfNotExists()
   at DotNet.Basics.IO.FileExtensions.CopyTo(FilePath source, FilePath target, Boolean overwrite, Boolean ensureTargetDir)
   at Sitecore.Cloud.Packaging.WebDeployPackages.WebDeployPackageBuilder.Build(SitecoreInstallationFolderTree scInstFoldTree, DirPath outputDir, String targetFileName, Boolean force, String version,
Boolean integratedSecurity)
   at Sitecore.Cloud.Cmdlets.Packaging.NewSCWebDeployPackage.ProcessRecord()
At C:\Sitecore\Azure Toolkit\tools\Sitecore.Cloud.Cmdlets.psm1:195 char:49
+ ... ckagePath = New-SCWebDeployPackage -Path $SitecorePath -Destination $ ...
+                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (System.Unauthor...ProcessRecord():String) [New-SCWebDeployPackage], Exception
    + FullyQualifiedErrorId : Microsoft.Extensions.Logging.EventId,Sitecore.Cloud.Cmdlets.Packaging.NewSCWebDeployPackage
Access to the path 'C:\inetpub\wwwroot\habitat.dev.local\tempConnectionStringeb3ab08c-5c68-4d9d-bf05-8b72f845145c\' is denied.

The process tries to do some stuff with a temporary file in the root folder of the habitat.dev.local site.

To avoid UnauthorizedAccessException, I just stopped IIS and rerun the PowerShell command.

Success

One minute, two minutes, no errors, waiting…and I see a good message:

The goal is achieved — local Habitat Sitecore Web Deploy Package has been generated:

C:\Sitecore\WDPs\habitat.dev.local_single.scwdp.zip

This is an archive where you can see all local Sitecore instance DB dacpac files, base SQL scripts to be executed during future deployment, and parameters:

We can also see a Content directory in which our local Sitecore Habitat root site folder was copied:

It took 7 minutes for my local Habitat Sitecore instance process to be completed.

Now, we have our local Sitecore instance packed. That means you can deploy this SCWDP to Azure as Sitecore PaaS, but that’s another topic for discussion.

Summary

I’ve described one of the first steps you have to take to prepare your local Sitecore Habitat for Azure deployment — the creation of a Sitecore web deploy package. The following is a summary of the process:

Download the Azure toolkit from the official portal
Unzip the toolkit into your deployment folder, for instance — C:\Sitecore\Azure Toolkit\
Check all prerequisites
Execute the following Commandlets into PowerShell terminal run from the root Azure Toolkit folder:

Import-Module .\ tools \ Sitecore . Cloud.Cmdlets.psm1 -Verbose

$sitecorePath = "C:\inetpub\wwwroot\habitat.dev.local"
$destinationFolderPath = "C:\Sitecore\WDPs"
$cargoPayloadFolderPath = "C:\Sitecore\Azure Toolkit\resources\9.1.1\CargoPayloads"
$commonConfigPath = "C:\Sitecore\Azure Toolkit\resources\9.1.1\Configs\common.packaging.config.json"
$skuConfigPath = "C:\Sitecore\Azure Toolkit\resources\9.1.1\Configs\XPSingle.packaging.config.json"
$parameterXmlPath = "C:\Sitecore\Azure Toolkit\resources\9.1.1\MsDeployXmls"
$fileVersion = "9.1.1"

Start-SitecoreAzurePackaging -sitecorePath $sitecorePath -destinationFolderPath $destinationFolderPath `
-cargoPayloadFolderPath $cargoPayloadFolderPath -commonConfigPath $commonConfigPath `
-skuConfigPath $skuConfigPath -parameterXmlPath $parameterXmlPath -fileVersion $fileVersion

If your Windows user has the Administrator role to access SQL server where your local Sitecore instance databases live — just add an additional parameter to avoid some issues I mentioned in this blog post:

-integratedSecurity 1 (means true)

5. Note that in some minutes you have a generated *.scwdp package in a folder you specified in the $destinationFolderPath parameter

6. To be more flexible, I suggest you save your PowerShell script and execute this script using Windows PowerShell ISE tool:

That’s all for today. If my experience comes in handy for you, I will be happy. If you have any questions, please contact me via Twitter and LinkedIn.

Rating: 4.9/5. From 9 votes. Show votes.

Please wait...

Comments: 1
Show comments.

About the Author

Vadzim Papko

Vadzim Papko is a Sitecore MVP, Sitecore Architect and Chief .NET Technologist at SaM Solutions. Adhering to the principles of non-stop self-development, he devotes himself to Sitecore innovation and popularization. Follow him on Twitter @VadzimPapko and subscribe to his Telegram channel Amazing Sitecore @amazingsitecore

View all posts Github LinkedIN Twitter

One Comment