.NET XML configuration variables feature

The .NET XML configuration variables feature is one of the .NET configuration features you can enable as you define the steps in your deployment process.

This feature can be enabled for package deploy steps.

.NET XML configuration variables screenshot

Octopus will extract your package and parse your *.config files looking for any appSettings, connectionStrings, and applicationSettings elements where the name matches one of your variables.

You can perform simple convention-based replacements in .NET XML configuration files using this feature. We also have a feature tailored to JSON, YAML, XML, and Properties configuration files.

If you are looking for something more flexible, we have the Substitute Variables in Templates feature enabling you to perform complex transformations on any kind of file.

How to use this feature

The following example shows you how to use the this feature to provide your application with different configuration settings for each different environment you’re deploying to. In this example, we’re deploying to a Test and Production environment.

Suppose you have this web.config or MyApp.exe.config file in your package which is configured for your local development environment:

<configuration>
  <appSettings>
    <add key="AWSAccessKey" value="dev-key"/>
    <add key="AWSSecretKey" value="dev-secret"/>
  </appSettings>
  <connectionStrings>
    <add name="DBConnectionString" connectionString="Server=(local)\SQLExpress;Database=Dev-Database;Integrated Security=SSPI" />
  </connectionStrings>
  <applicationSettings>
    <AppSettings.Properties.Settings>
      <setting name="WelcomeMessage" serializeAs="String">
        <value>Hello developer!</value>
      </setting>
    </AppSettings.Properties.Settings>
  </applicationSettings>
</configuration>

Create the variables in Octopus. From the project overview page, click Variables:

Enter a the name for the variable, for instance, AWSAccessKey. This name must match the key in your configuration file.
Enter the value for the variable, for instance, ABCDEFG.
Scope the variable to the environment, for instance, Test.
Repeat the process for the Production environment, to give you a different value for the AWSAccessKey variable for each environment.

Repeat this for each element you want to replace in your configuration file.
Click SAVE.

In this example, you would have variables similar to the following:

Variable Name	Value	Sensitive	Scope
`AWSAccessKey`	`ABCDEFG`	`No`	`Test`
`AWSAccessKey`	`HIJKLMN`	`No`	`Production`
`AWSSecretKey`	`1111111`	`Yes`	`Test`
`AWSSecretKey`	`2222222`	`Yes`	`Production`
`DBConnectionString`	`Server=testserver.mycompany.com;Database=Test-Database;Integrated Security=SSPI`	`No`	`Test`
`DBConnectionString`	`Server=prodserver.mycompany.com;Database=Prod-Database;Integrated Security=SSPI`	`No`	`Production`
`WelcomeMessage`	`Hello tester!`	`No`	`Test`
`WelcomeMessage`	`Hello customer!`	`No`	`Production`

Variables marked sensitive (AWSSecretKey in this example) are encrypted in the Octopus database. During deployment they are encrypted during transport, but eventually decrypted and written in clear-text to the configuration files so your application can use the value.

Deploy your project to the Test environment, and Octopus will update the configuration file to:

<configuration>
  <appSettings>
    <add key="AWSAccessKey" value="ABCDEFG"/>
    <add key="AWSSecretKey" value="1111111"/>
  </appSettings>
  <connectionStrings>
    <add name="DBConnectionString" connectionString="Server=testserver.mycompany.com;Database=Test-Database;Integrated Security=SSPI" />
  </connectionStrings>
  <applicationSettings>
    <AppSettings.Properties.Settings>
      <setting name="WelcomeMessage" serializeAs="String">
        <value>Hello tester!</value>
      </setting>
    </AppSettings.Properties.Settings>
  </applicationSettings>
</configuration>

Deploy your project to the Production environment, and Octopus will update the configuration file to:

<configuration>
  <appSettings>
    <add key="AWSAccessKey" value="HIJKLMN"/>
    <add key="AWSSecretKey" value="2222222"/>
  </appSettings>
  <connectionStrings>
    <add name="DBConnectionString" connectionString="Server=prodserver.mycompany.com;Database=Prod-Database;Integrated Security=SSPI" />
  </connectionStrings>
  <applicationSettings>
    <AppSettings.Properties.Settings>
      <setting name="WelcomeMessage" serializeAs="String">
        <value>Hello customer!</value>
      </setting>
    </AppSettings.Properties.Settings>
  </applicationSettings>
</configuration>

Values are matched based on the key attribute for appSettings, and the name element for applicationSettings and connectionStrings.

Replacing variables outside appSettings, applicationSettings and connectionStrings

There may be other variables you would like Octopus to replace in your configuration files that are outside both the appSettings, connectionStrings, and applicationSettings areas. For example, changing the loginUrl for forms authentication in an ASP.NET application:

    <authentication mode="Forms">
      <forms loginUrl="HOW-CAN-I-CHANGE-THIS!" timeout="2880" />
    </authentication>

Learn how to do this with a fully worked example which describes how Octopus can take care of your deployment environments, without impacting how you configure your application for your local development environment.

This example uses the .NET XML Configuration Transforms feature and Substitute Variables in Templates feature together.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Sunday, January 1, 2023

Edit on GitHub