Introduction

In classic ASP.NET projects, Web.config transforms let you change configuration values per environment during publish or build. For appSettings, the usual task is to locate an existing add entry by key and replace its value attribute. The core XDT pattern is Locator="Match(key)" plus Transform="SetAttributes(value)".

Base Web.config

Suppose the main configuration file contains this setting:

1<configuration>
2  <appSettings>
3    <add key="ApiBaseUrl" value="https://dev.example.com" />
4    <add key="FeatureFlag" value="false" />
5  </appSettings>
6</configuration>

During deployment, you might want the release build to point to a production URL instead.

Transform File Structure

Environment-specific transforms are usually stored in files such as Web.Release.config or Web.Debug.config. The transform file must declare the XDT namespace.

1<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
2  <appSettings>
3    <add key="ApiBaseUrl"
4         value="https://api.example.com"
5         xdt:Locator="Match(key)"
6         xdt:Transform="SetAttributes(value)" />
7  </appSettings>
8</configuration>

This tells the transform engine:

1. find the add element whose key attribute equals ApiBaseUrl
2. update only the value attribute

That is the standard answer for changing an existing app setting value.

Why Match(key) Matters

Without a locator, the transform engine has no precise way to identify which add element you mean. Match(key) is the normal choice because key is the identity field for appSettings entries.

1<add key="FeatureFlag"
2     value="true"
3     xdt:Locator="Match(key)"
4     xdt:Transform="SetAttributes(value)" />

This changes only the value attribute of the matching element and leaves other settings untouched.

SetAttributes Versus Replace

If you only need to modify one attribute, use SetAttributes. If you use Replace, you replace the entire matched element.

Targeted update:

1<add key="FeatureFlag"
2     value="true"
3     xdt:Locator="Match(key)"
4     xdt:Transform="SetAttributes(value)" />

Full element replacement:

1<add key="FeatureFlag"
2     value="true"
3     someCustomAttribute="1"
4     xdt:Locator="Match(key)"
5     xdt:Transform="Replace" />

Replace is more disruptive and easier to misuse. Prefer SetAttributes(value) when you only want to change the value field.

Adding a Setting If It Does Not Exist

Sometimes the desired key is missing from the base file. In that case, you need an insert transform instead of an attribute update.

1<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
2  <appSettings>
3    <add key="NewSetting"
4         value="enabled"
5         xdt:Transform="Insert" />
6  </appSettings>
7</configuration>

Do not expect SetAttributes to create a missing element. It only updates an existing match.

Multiple Attribute Updates

You can change more than one attribute by listing them in SetAttributes.

1<add key="ApiBaseUrl"
2     value="https://api.example.com"
3     custom="prod"
4     xdt:Locator="Match(key)"
5     xdt:Transform="SetAttributes(value, custom)" />

For plain appSettings, that is less common because the typical shape is just key and value, but the syntax is useful in other XML sections too.

How to Verify the Result

After publishing or transforming, inspect the generated configuration file rather than assuming the transform ran correctly. Common checks include:

• was the right build configuration used
• did the key exist in the base file
• did the output file contain the expected value

If the published config still shows the original setting, the issue is usually one of these:

• missing xmlns:xdt
• incorrect locator
• transform file not applied during publish

Example: Release Transform

Here is a complete release transform for two settings:

1<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
2  <appSettings>
3    <add key="ApiBaseUrl"
4         value="https://api.example.com"
5         xdt:Locator="Match(key)"
6         xdt:Transform="SetAttributes(value)" />
7    <add key="FeatureFlag"
8         value="true"
9         xdt:Locator="Match(key)"
10         xdt:Transform="SetAttributes(value)" />
11  </appSettings>
12</configuration>

This keeps the transform file focused and readable, which is important when multiple environments are maintained over time.

Common Pitfalls

The most common mistake is using SetAttributes without Match(key), which leaves the transform engine unable to target the correct element. Another is using Replace when only the value attribute should change. Developers also sometimes forget the XDT namespace declaration, in which case the transform attributes are ignored entirely. Finally, SetAttributes does not create missing keys, so it fails silently if the base element is not there.

Summary

• Use xdt:Locator="Match(key)" to identify the correct appSettings entry.
• Use xdt:Transform="SetAttributes(value)" to change only the value attribute.
• Use Insert instead of SetAttributes when the key does not exist yet.
• Prefer targeted attribute updates over full Replace when possible.
• Verify the transformed output after publish rather than assuming the change was applied.