Explorations: Web Deploy Parameters, a first look

Sunday, September 19, 2021

Web Deploy Parameters, a first look

WebDeploy is a foundational technology for SIF, as well as Azure deployments and even Docker (where content packages need to be converted into web deploy packages to build images). I recently did some digging into the basics of WebDeploy, including how to configure parameters in projects. This short walkthrough shows how to create a web deployment package form a project, how to publish it to an IIS site, and how to add and set a custom parameter. We'll use this to set the "My Application" text in the MVC scaffold project in Visual Studio.

First, let's create an empty site in IIS:

Next, in Visual Studio, create a .Net Framework MVC project with "Individual User Accounts" (the DB connection string is created as a parameter later, which will play with a bit.)

Hit F5, to bring it up in IIS Express. It should look like this. Note the My Application text. We'll parameterize that later on.

Okay, now let's build the deployment package. Hit Build/Publish to bring up this screen:

Select IIS, FTP, etc.

Change from Web Deploy to Web Deploy Package, and point to a new target directory. List the site you created in IIS earlier under Site name:

This causes several files to be created, besides the zip file show above after Package location.

The Zip file has a familiar structure if you've looked at the scwdp files that come in a Sitecore distribution, minus all the dacpacs and SQL commands, but we do have a Content folder, and a file that lists parameters:

The parameters file in the package lists two parameters site name and connection string, with details as to what they refer to (e.g. which Web.config location):

And the SetParameters file (outside the zip) gives default values for these. Notice the DB connection string, and the site name.

Finally, the .deploy.cmd file provides a wrapper for the call to MSDeploy, and the deploy-readme.txt provides documentation.

Worth noting is you can call with a /T for "WhatIF" mode (mnemonic: "test" or "try"), and /Y (mnemonic, "yeah, let it rip")

Let's open an elevated PowerShell prompt (so it has access to the target location), and run the deploy command with /T. We'll see a list of all the files that would be deployed:

...

Seems legit. Let's run with /Y:

Now we can load the site from IIS proper:

Let's try changing that DB parameter. Open the SetParameters file, and change "(LocalDb)\MSSQLLocalDB" to ".", and run the same command with /T. Now we just see one file, web.config, listed:

Run with /Y, and we can confirm that value gets updated in Web.config in IIS.

Okay, now let's add a custom parameter. It turns out we can do that with a parameters.xml file in the project root. This syntax states, to any file named __Layouts.cshtml, replace "My Application" with this parameter.

With that in place, let's rebuild. We now see that parameter added to the parameters.xml:

And it's added inside the zip as well, with information on where to apply it:

We could edit the first of these to push a change, but we can also pass parameters directly through to MSDeploy, like this:

.\WebApplication2.deploy.cmd /T "-setParam:name='Application Ribbon Home Label',value='Changed!!'"

Note that the entire parameter is in double quotes, with the values in single quotes. This is specified by the readme, and took me way too long to get right.

Let's run this with /Y. The output shows that the _Layout file was updated:

And let's reload the website:

This article shows how parameters are integrated into the Visual Studio Web Publishing Pipeline, how they can be customized, and shows two ways of passing parameters through to the web deploy, using configuration and using a command line parameter. In a future post, we'll see how these parameters work in Sitecore web deploy packages and are supported in the SIF WebDeploy command.