web.config

web.config
Name	web.config
Type	Configuration file
Associated with	Microsoft IIS, ASP.NET, .NET Framework, .NET Core, Azure App Service
Format	XML
Extension	.config
Introduced	ASP.NET (2002)
Developer	Microsoft
License	Proprietary

web.config

web.config is an XML-based configuration file used to control settings for applications hosted on Internet Information Services and applications built with ASP.NET, ASP.NET Core, and components of the .NET Framework. It centralizes application-level configuration for modules, handlers, authentication, authorization, caching, session state, and compilation options, enabling administrators and developers working with Microsoft platforms, Azure, and enterprise deployments to manage behavior without recompiling code. As part of the Windows Server and web stack, it interacts with IIS configuration and deployment tooling such as MSBuild and Azure DevOps pipelines.

Overview

The web.config file operates alongside machine-level configuration files like machine.config and server-level configuration such as applicationHost.config in Internet Information Services. It is parsed by the Common Language Runtime and by hosting layers in the .NET Framework and affects components including the ASP.NET MVC pipeline, ASP.NET Web Forms, and ASP.NET Web API. In cloud scenarios it is often used in conjunction with Azure App Service settings or replaced by environment-specific configuration approaches promoted in .NET Core and ASP.NET Core, which emphasize JSON-based configuration and the Options pattern.

Structure and Syntax

web.config uses hierarchical XML with a root element that contains nested sections and elements. Typical children include , , , and , which map to runtime behaviors for the hosting environment provided by Internet Information Services and the Common Language Runtime. Elements are validated against XML schemas defined by Microsoft and are subject to inheritance rules: settings cascade from machine to application directories, with local files overriding parent settings, similar to directory-scoped configuration models in IIS Express and full IIS. Encoding, XML namespaces, and well-formedness are enforced by XML parsers used in the .NET Framework.

Configuration Sections and Elements

Important configuration sections include (controls ASP.NET runtime features), (IIS-specific handlers and modules), (key/value pairs for configuration), and (database connectivity information). Other sections manage sessionState, authentication (forms, Windows, OAuth), authorization rules, compilation settings, and custom configuration sections defined by developers through the ConfigurationSection API in the .NET Framework. IIS integration points include handlers and modules configuration, URL rewrite rules often authored with the URL Rewrite Module used in IIS Manager, and static content MIME-type mappings. The file can reference providers such as membership and role providers used by ASP.NET Identity and legacy Membership Provider implementations.

Security and Access Control

Sensitive information in web.config, particularly connection strings and keys, must be protected using techniques like encryption with the Protected Configuration API, machineKey management, and using external secret stores in Azure Key Vault or Azure App Service application settings. Access control is enforced via and elements, which can integrate with Windows Authentication, Forms Authentication, or federated identity providers like Active Directory Federation Services and OAuth 2.0 endpoints from providers such as Azure Active Directory. File system permissions on Windows, including NTFS ACLs and IIS application pool identity configuration, are critical for preventing unauthorized reads. Misconfigured settings have historically been vectors in vulnerabilities tracked by organizations such as Microsoft Security Response Center.

Deployment and Transformation

web.config is commonly transformed per-environment using XML Document Transform (XDT) transformations supported by MSBuild and Visual Studio publish profiles, enabling developers to apply environment-specific inserts, replacements, or deletes during CI/CD orchestration with tools such as Azure DevOps, Octopus Deploy, and Jenkins. For containerized workloads built for Docker and orchestrated by Kubernetes, configuration can be externalized to environment variables, ConfigMaps, or secrets, or the file can be templated during image build. The file may be replaced or augmented on deployment to Azure App Service where slot-specific settings and application settings can override values without changing the deployed web.config directly.

Troubleshooting and Common Errors

Common issues include malformed XML leading to HTTP 500 errors, configuration inheritance causing unexpected overrides, incorrect module or handler declarations blocking routes used by frameworks like ASP.NET MVC or SignalR, and permission errors when the application pool identity lacks read access. Diagnostics involve examining IIS logs, Windows Event Viewer, and ASP.NET trace information; enabling detailedErrors and settings can assist during development but must be disabled in production. Locking sections at higher levels such as applicationHost.config can prevent local overrides and produce configuration errors; resolving such cases typically requires coordination with administrators managing IIS server configuration. For secrets leakage, recommended remediation includes rotating credentials, encrypting protected sections, and migrating secrets to managed stores like Azure Key Vault.

Category:Microsoft IIS Category:ASP.NET