Using the .NET Framework Web Config Transform Extension Buildpack

Page last updated:

This topic tells you how to use the .NET Framework Web Config Transform Extension Buildpack.

Prerequisites

  • A Linux, Windows or MacOS development machine or VM.
  • A foundation with Windows cells available to push to.
  • A foundation with the .NET Framework Web Config Transform Extension Buildpack installed.
  • The Spring Cloud Services Tile.

.NET Framework Web Config Transform Extension Buildpack overview

Cloud Native Applications derive their configurations and settings from external sources, for example, from config servers or by reading environment variables. Configuration settings are injected through Web.config files for applications that run on IIS, such as ASP.NET applications.

As per cloud native principles, configuration cannot be included in build artifacts.

The .NET Framework Web Config Transform Extension Buildpack provides a solution to this problem by using token replacement during ‘cf push’ staging.

To leverage the .NET Framework Web Config Transform Extension Buildpack, complete the following procedures:

  1. Identify Environment Dependent Configurations and Externalize.
  2. Create a Cloud Foundry App Manifest.
  3. Add Web Config Transformations.
  4. Move Config Settings to a Git Repository.
  5. Create a Configuration Service for Spring Cloud Config Server.
  6. Bind Config Service to App Using Manifest.
  7. Add ASPNETCORE_ENV Variable to App Manifest.
  8. Push the App by Parameterized Environment Name.

This buildpack can inject appSettings and connectionStrings regardless of whether the replacement tokens are present in the Web.Release.Config file. For more information please see Special Behavior for appSettings and connectionStrings sections.

Identifying environment dependent configurations and externalizations

To use the .NET Framework Web Config Transform Extension Buildpack you replace your Web.config files’ environment-specific settings with placeholder tokens, and externalize their values outside of your application.

To tokenize your workload’s environment specific configuration settings, complete the following steps:

  1. Backup your application’s Web.config file, and its transform files, for example Web.config, Web.Debug.Config, and Web.Release.Config.

  2. Identify configuration items in the Web.config transform files that are environment-dependent. These items need to be externalized.

  3. Modify your transform files to use tokenized configuration items by replacing hard-coded values with tokens following the format #{configPath:key}.
    For example, refer to the before and after tokenizing sample files, below:

    Transform xml attributes and tokens are case-sensitive.

    Before tokenizing

    Web.Config

    <connectionStrings>
    <add name="MyDB"
         connectionString="Data Source=LocalSQLServer;Initial Catalog=MyReleaseDB;User ID=xxxx;Password=xxxx" />
</connectionStrings>


    Web.Release.Config

    <connectionStrings>
    <add name="MyDB"
         connectionString="Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;User ID=xxxx;Password=xxxx"
         xdt:Transform="SetAttributes"
         xdt:Locator="Match(name)"/>
</connectionStrings>


    After tokenizing

    Web.Config (no change)
    Web.Release.Config

    <connectionStrings>
    <add name="MyDB"
         connectionString="#{connectionStrings:MyDB}"
         xdt:Transform="SetAttributes"
         xdt:Locator="Match(name)"/>
</connectionStrings>

Creating a Cloud Foundry app manifest

Perform the following steps to test your tokenizations by using environment variables in the Cloud Foundry app manifest to perform the token replacements.

Token replacements with environment variables is solely for testing purposes to ensure your tokens are correctly replaced. After validating using environment variables you will externalize your configuration settings using git repositories and Spring Cloud Config Server in later steps.

Creating a Cloud Foundry app manifest for your app

To create a Cloud Foundry app manifest for your workload, complete the following:

Ensure your application has a Cloud Foundry manifest file. If your application is in Cloud Foundry, you can create the manifest file by running the following command:

```
cf create-app-manifest APP-NAME
```

Where `APP-NAME` is your app's name.

Modifying your Cloud Foundry app manifest

To configure your workload’s Cloud Foundry app manifest for token replacement, complete the following steps:

You must prepare your Cloud Foundry app manifest for token replacement with debug/development environment connection values.

  1. Backup your app manifest file.

  2. Open the app manifest file in a text editor.

  3. Add a reference for the .NET Framework Web Config Transform Extension Buildpack to the manifest file’s buildpacks property.

    buildpacks:
- WEB-CONFIG-TRANSFORM-BUILDPACK
- hwc_buildpack

    Where WEB-CONFIG-TRANSFORM-BUILDPACK is name of the .NET Framework Web Config Transform Extension buildpack in your foundation. Confirm the buildpacks in your foundation by using cf buildpacks.

    <p class="note important">
Ensure the new entry precedes the existing
<code>hwc_buildpack</code> buildpacks entry.</p>

  4. Add key:value pairs to the manifest for each the Web Config file’s tokenized settings.
    For example, the following provides connection string values for a Web Config file’s#{connectionStrings:MyDB} placeholder:

    applications:
- name: sampleapp
  stack: windows
  buildpacks:
  - WEB-CONFIG-TRANSFORM-BUILDPACK
  - hwc_buildpack
  env:
    "connectionStrings:MyDB": "Data Source=ReleaseSQLServer;Initial Catalog=MyReleaseDB;User ID=xxxx;Password=xxxx"

    Create as many key:value pair lines as are needed by your application. The values you provide are your debug/development environment’s connection values.

Adding web config transformations

By default, all web apps and WCF apps are created with Debug and Release configurations and corresponding web config transformation files (Web.Debug.Config, Web.Release.Config).

  1. Add required transformations to your Web.Release.Config file.
    For example, the following Web.Release.Config has been edited with transformations:

    <?xml version="1.0" encoding="utf-8"?>
<!-- For Cloud Foundry -->
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">

  <connectionStrings  xdt:Transform="Replace">
    <add name="MyDB" connectionString="#{connectionStrings:MyDB}" providerName="System.Data.SqlClient"/>
  </connectionStrings>

  <system.serviceModel>
    <client xdt:Transform="Replace">

      <endpoint
        address="#{client:Default_IMyLogService:address}"
        binding="#{client:Default_IMyLogService:binding}"
        bindingConfiguration="#{client:Default_IMyLogService:bindingConfiguration}"
        contract="ServiceProxy.IMyLogService" name="Default_IMyLogService" />

    </client>
  </system.serviceModel>

</configuration>

    For developer machine debugging, use the Debug configuration profile and your Web.Debug.config for transformation.

  2. Build and push the application to Cloud Foundry to verify that your config settings are properly transformed:

    cf push

Moving config settings to a git repository

A multi environment, production- eady deployment configuration can be achieved by using Spring Cloud Config Server backed by a git repository data source.

To move your configuration settings to a Git repository, complete the following steps:

  1. Create a network accessible Git repository specifically for storing this application’s transform configuration files.

  2. Create a YAML file in your repository to hold your common settings across all environments. Name the file YOUR-APPLICATION.yaml.
    Where YOUR-APPLICATION is the identifier name for your application.
    For example:
    sampleapp.yaml

    appSettings:
  Setting1: "Common setting1"

  3. Create a separate YAML file for each of your unique app environments, for example your “Development”, “Debug”, and “Production” environments, to hold your environment-specific settings. Name the files YOUR-APPLICATION-APP-ENVIRONMENT.yaml.
    Where:

    • YOUR-APPLICATION is the identifier name for your application.
    • APP-ENVIRONMENT is the identifier name for a unique environment, such as “Development”, “Debug” or “Production”.

    Later you can use these app environment names as values for the ASPNETCORE_ENVIRONMENT environment variable to target different environments.

For example:
sampleapp-Development.yaml

    ```yaml
     connectionStrings:
       MyDB: "Data Source=devserver;Initial Catalog=mydb;User ID=serviceacc3;Password=PaKsAsEwWoOrOdT3"
    ```


sampleapp-Production.yaml

    ```yaml
     connectionStrings:
       MyDB: "Data Source=prodserver;Initial Catalog=mydb;User ID=serviceacc4;Password=PaKsAsEwWoOrOdT3"
    ```


Your configuration values are now present in your Git repository. They are also present in your manifest.yml file.
1. Remove your configuration key:value pairs from the env section of your manifest.yml.

The <code>manifest.yml</code> <code>env</code> section does not include
any configuration key:value pairs during the next step.

Creating a configuration service for Spring Cloud config server

The .NET Framework Web Config Transform Extension Buildpack requires a configuration file pointing to your transform configurations Git repository.

  1. Verify that you have a config server available in your CF marketplace. To confirm the name of the config server available in your CF Marketplace, run the following command:

    cf marketplace

    Review the return and determine whether you have either p.config-server or p-config-server.

  2. Create a JSON text file for configuration server settings. Add a single entry to the JSON file for the uri to your configuration Git repository.
    For example:

    {
    "git" : {
        "uri": "https://github.com/ACCOUNT-ID/CONFIG-REPO"
    }

}

    Where:

    • ACCOUNT-ID is your Git repository account ID.
    • CONFIG-REPO is the name of your configuration Git repository created in the step above.

  3. Save the text file as a JSON file, for example, config-server.json. Ensure that the file is not BOM-encoded.

  4. To create a config server using cf create service, and your configuration file, run the following command:

    cf create-service CONFIG-SERVER-MARKET standard SERVER-NAME  -c .\CONFIG-FILE

    Where:

    • CONFIG-SERVER-MARKET is the name of the config server, either p.config-server or p-config-server, available in your CF Marketplace.
    • SERVER-NAME is the name for your config server.
    • CONFIG-FILE is the filename of your server config json file.

    For example:

    $ cf create-service p.config-server standard my_configserver  -c .\config-server.json

Binding config service to app using a manifest file

Your app manifest file must be modified so it accepts configuration values from your externalized Git repository values.

  1. Backup your app manifest file.

  2. To bind your config server to your app, add a new services section to your app manifest file with the following format:

    services:
- SERVER-NAME

    Where SERVER-NAME is the name for your config server.
    For example:

    ---
applications:
- name: sampleapp
  stack: windows
  buildpacks:
    - web_config_transform_buildpack
    - hwc_buildpack
  services:
  - my_configserver

Adding ASPNETCORE_ENVIRONMENT variable to app manifest file

  1. To configure your config server so that it can target the correct configuration in your Git repository, add the ASPNETCORE_ENVIRONMENT variable to the env section of your app manifest with the value of ((env)).
    For example:

    ---
applications:
- name: sampleapp
  stack: windows
  buildpacks:
    - web_config_transform_buildpack
    - hwc_buildpack
  env:
    ASPNETCORE_ENVIRONMENT: ((env))

  services:
  - my_configserver

Pushing the app by parameterized environment name

You can now push your app using your parameterized configuration.

  1. To push your app, run the following command:

    cf push --var env=ENVIRONMENT


    Where ENVIRONMENT is the environment you wish to target, for example Development, Production, QA, or UAT. The specified environment cannot be present in your Git configuration repository.
    For example:

    cf push --var env=Production

  2. To confirm your app is running with the correct environment, review your logs for WebConfig Transform Buildpack execution:

    ================================================================================
=============== WebConfig Transform Buildpack execution started ================
================================================================================
-----> Using Environment: Production
-----> Config server binding found...

Special behavior for appSettings and connectionStrings values

This buildpack makes it possible to externalize appSettings and connectionString values in your Web.config without using tokenized values.

To externalize Web.config values without tokenizing, perform the following steps:

  1. Copy the contents of the YOUR-APPLICATION.yaml file in your Git configuration repository.

  2. Add the copied content to all of the Git configuration repository’s environment-specific YOUR-APPLICATION-APP-ENVIRONMENT.yaml config files.
    For example:
    sampleapp-Development.yaml

    appSettings:
  Setting1: "development setting"
 connectionStrings:
   MyDB: "Data Source=devserver;Initial Catalog=mydb;User ID=xxxx;Password=xxxx"

    sampleapp-Production.yaml

    appSettings:
  Setting1: "production setting"
 connectionStrings:
   MyDB: "Data Source=prodserver;Initial Catalog=mydb;User ID=xxxx;Password=xxxx"

  3. Follow the instructions in Push the App by Parameterized Environment Name above to deploy your application using the .NET Framework Web Config Transform Extension Buildpack.

Troubleshooting

For any issues you face with the web-config-transform-buildpack, please raise an issue at Issues in the Web Config Transform Buildpack GitHub repository.

A sample web application can be found here: WebConfigSampleApp.

Create a pull request or raise an issue on the source for this page in GitHub