Applications of Web.config (App.config) in .NET Framework

TLDR

• Use Build Configurations with Web.config Transform to automate the generation of environment-specific configuration files, preventing manual modification errors.
• Non-Web projects (such as Console Apps) require the SlowCheetah package to enable Config Transform functionality.
• When sharing configuration files across projects, you can reference external files using the configSource or file attributes and use TransformOnBuild to ensure automatic transformation during the build process.
• If configuration inheritance conflicts occur in IIS sub-sites, you can use <location inheritInChildApplications="false"> in the parent site's Web.config to disable inheritance.
• When using Entity Framework Database First, avoid moving connection strings to external reference files or wrapping them in <location> tags, as this prevents the design-time UI from reading the configuration.

---

Publishing Different Configuration Files for Different Build Configurations

In development, testing, and production environments, configuration file content is usually different. Through Visual Studio's Build Configuration and the Web.config Transform mechanism, you can automatically generate environment-specific configuration files during publishing.

Automatic Transformation for Web Projects

When Web.Debug.config or Web.Release.config exists in a project, Visual Studio applies transformation rules to Web.config based on the selected configuration during publishing.

• When you might encounter this issue: When the project is missing the corresponding transformation file (e.g., accidental deletion or adding a new configuration).
• Solution: Right-click on Web.config and select "Add Config Transform".
• Transformation mechanism: Use xdt:Transform to define the replacement method and xdt:Locator to locate the node.

Common transformation examples:

<!-- Replace a single attribute -->
<add key="MyKey" value="MyReleaseValue" xdt:Transform="SetAttributes" xdt:Locator="Match(key)" />

<!-- Remove a specific attribute -->
<compilation xdt:Transform="RemoveAttributes(debug)" />

<!-- Replace an entire node -->
<connectionStrings xdt:Transform="Replace">
  <add name="Default" connectionString="{connectionString}" />
</connectionStrings>

Transformation for Non-Web Projects

Non-Web projects (such as .NET Framework Console Apps) do not support Config Transform by default.

• When you might encounter this issue: When you want to automatically transform App.config in a non-Web project.
• Solution: Install the NuGet package Microsoft.VisualStudio.SlowCheetah. After installation, an "Add Transform" option will appear in the App.config right-click menu, allowing you to trigger transformations during the build.

---

Sharing Configuration Files Across Projects

When a solution contains multiple projects that need to share the same database connection or SMTP settings, you can extract the settings into separate files.

Setup Steps

1. Create an external configuration file: Create a file such as Connection.config and set its TransformOnBuild to true.
2. Project file (csproj) settings:
   • Add the external configuration file to the project and set <CopyToOutputDirectory>Always</CopyToOutputDirectory>.
   • Set the transformation file (e.g., Connection.Release.config) to <None /> and link it to the main configuration file using <DependentUpon>.
3. Referencing method:
   • Reference the file in Web.config or App.config using the configSource or file attributes.

Reference example:

<!-- Web.config -->
<connectionStrings configSource="bin\Connection.config" />
<appSettings file="bin\AppGlobal.config">
  <add key="MyKey" value="MyValue" />
</appSettings>

WARNING

If you are using Entity Framework's Database First mode, do not move the connection string to an external reference file; otherwise, the Entity Framework design-time UI will be unable to read the connection string.

---

Disabling Web.config Inheritance

IIS allows the creation of sub-applications under a website, but sub-applications inherit the Web.config settings from the parent level, which may lead to Framework version conflicts.

• When you might encounter this issue: When settings between the sub-site and the parent site conflict, or when their Framework versions are inconsistent.
• Solution: Use the <location> tag in the parent site's Web.config.

<location path="." inheritInChildApplications="false">
  <system.web>
    <!-- Relevant settings -->
  </system.web>
</location>

TIP

Do not wrap the <location> tag around <connectionStrings>, as this will also cause the Entity Framework UI to be unable to read the connection string.

---

Change Log

• 2022-11-10 Initial version of the document created.