IntermediateLesson 8 of 16

IIS Configuration Files and .NET Registration

applicationHost.config, web.config, machine.config — understand the IIS configuration hierarchy, delegation model, XML schema, and how to correctly register .NET Framework and .NET Core with IIS to prevent the notoriously cryptic 500.19, 500.21, and 502.5 errors.

🧒 Simple Explanation (ELI5)

IIS configuration files are like a set of nested rule books. The top-level book is applicationHost.config — the company HR policy manual that applies to everyone. Each department (website) has its own sub-handbook (web.config) that can extend the company rules but cannot break them unless the company policy gives permission. The .NET registration is like a stamp of certification: it tells IIS "yes, version 4.8 of the .NET runtime is installed and ready to be loaded — here's where to find it." Without that stamp, IIS refuses to start any application that needs .NET.

🔧 Why Do We Need It?

Understanding 500.19 errors: misconfigured or unreadable applicationHost.config or web.config is the #1 cause of IIS startup failures — knowing the file structure means you can fix it in minutes.
Layered configuration: enterprise environments use applicationHost.config for server-wide security policies (deny certain HTTP headers, enforce TLS settings) that individual site web.config files cannot override — prevents misconfigurations at the application level from weakening server security.
Deployment automation: CI/CD pipelines (Azure Pipelines, Jenkins) use XML transformations on web.config to swap connection strings and settings between dev/staging/prod — you must understand the config schema to build these pipelines correctly.
.NET registration: installing .NET Framework or .NET Core does not automatically register it with IIS — missing registration is the cause of 500.21 and 502.5 errors that confuse junior engineers who "definitely installed .NET."

🌍 Real-world Analogy

The configuration hierarchy is like a legal system. applicationHost.config is federal law — it applies everywhere and cannot be overridden by state law without explicit delegation. web.config at the site level is state law — it can add rules within the federally permitted scope. web.config in a subdirectory is local ordinance — the most specific rule for that location. When there is a conflict, the higher-level rule always wins — unless the federal (applicationHost) law explicitly says "states may decide this themselves" (allowOverride=true). .NET registration is like a contractor's licence — even if the contractor exists, they cannot legally work on your building until they are registered with the city (IIS).

⚙️ Technical Explanation

applicationHost.config is stored at %SystemRoot%\System32\inetsrv\config\applicationHost.config. It contains global IIS configuration: all sites, applications, virtual directories, application pools, global modules, authentication defaults, MIME types, handler mappings, and security feature settings. Think of it as the master configuration the IIS Manager GUI reads and writes. All changes made in IIS Manager are persisted here. The file is XML with a defined schema stored in %SystemRoot%\System32\inetsrv\config\schema\IIS_schema.xml. Administrative permission is required to edit applicationHost.config — the IIS worker process NEVER writes to this file.

web.config exists per-site and per-application. Located in the application's physical root directory. It can override inherited configuration sections that applicationHost.config allows to be overridden (controlled by allowOverride and overrideModeDefault attributes in the section definitions). web.config configures: handler mappings, modules, authentication settings (for the specific application), connection strings, app settings, URL rewrite rules, custom errors, output caching, and ASP.NET-specific settings (session state, globalization, compilation). The ASP.NET application reads web.config via the System.Configuration API and the W3C/IIS pipeline reads it via the IIS config manager.

.NET Registration: Installing .NET Framework creates its runtime files but does not automatically hook them into IIS. The aspnet_regiis tool registers the ASP.NET ISAPI handler, updates HTTP handler mappings in applicationHost.config, updates the script map in the metabase, and ensures the managed engine module is registered. For .NET Core: the .NET Core Hosting Bundle installer registers the ANCM (aspnetcoremodule.dll) as an IIS module globally in applicationHost.config. Without ANCM, ASP.NET Core apps return 500.0 errors.

⚠️

Configuration File Hierarchy — Delegation and Lock-down

IIS uses two override modes: Allow (web.config can override the parent) and Deny (section is locked — web.config cannot change it). Administrative lock-down is critical for shared hosting and security compliance: lock the requestFiltering section (prevents applications from self-removing URL filters), the security section (prevents applications from re-enabling directory browsing or disabling auth), and the httpModules section (prevents applications from adding malicious managed modules). In applicationHost.config: <section name="requestFiltering" overrideModeDefault="Deny" /> prevents all web.configs from overriding that section. Locked sections accessed by web.config produce HTTP 500.19 with error code 0x80070021 (file is locked).

📊 Visual Representation

IIS Configuration Hierarchy

Level 1 — Machine

machine.config

%WINDIR%\Microsoft.NET\Framework64\v4.0.30319\Config\

CLR defaults for all .NET apps

↓ inherits

Level 2 — IIS Server

applicationHost.config

%WINDIR%\System32\inetsrv\config\

All sites, pools, modules, global settings

↓ inherits (if allowed)

Level 3 — Site/App Root

web.config (site root)

C:\inetpub\wwwroot\MySite\web.config

Site-specific overrides

↓ inherits (if allowed)

Level 4 — Subdirectory

web.config (subdirectory)

C:\inetpub\wwwroot\MySite\api\web.config

Path-specific overrides

⌨️ Commands / Syntax

cmd / PowerShell / XML

# === applicationHost.config location ===
%windir%\system32\inetsrv\config\applicationHost.config

# Backup before editing
appcmd add backup "BeforeManualEdit"
# Restore
appcmd restore backup "BeforeManualEdit"

# === View effective config for a site (merged hierarchy) ===
appcmd list config "Default Web Site/" /section:system.webServer
appcmd list config "Default Web Site/" /section:system.webServer/security/authentication

# === .NET Framework registration ===
# Register ASP.NET 4.0 with IIS (Server 2008/old environments)
%windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe -iru
# -i registers ASP.NET for the IIS 6 metadata (needed for Classic pool mode compatibility)
# -r registers all existing IIS applications with the new .NET version
# -u unregisters (do NOT run this on a live server without testing first)

# Check .NET Framework registration in appHost.config:
%windir%\system32\inetsrv\appcmd list config /section:system.webServer/handlers

# === .NET Core: Install Hosting Bundle ===
# Download from https://dotnet.microsoft.com/download (use official link)
# After installing, verify ANCM is registered:
%windir%\system32\inetsrv\appcmd list config /section:system.webServer/globalModules | findstr aspNetCore

# === web.config structure (minimal for ASP.NET Core in-process) ===
# <configuration>
#   <system.webServer>
#     <handlers>
#       <add name="aspNetCore" path="*" verb="*"
#            modules="AspNetCoreModuleV2"
#            resourceType="Unspecified" />
#     </handlers>
#     <aspNetCore processPath="dotnet"
#                 arguments=".\MyApp.dll"
#                 stdoutLogEnabled="false"
#                 stdoutLogFile=".\logs\stdout"
#                 hostingModel="inprocess" />
#   </system.webServer>
# </configuration>

# === Validate web.config XML syntax ===
# No built-in validator, but these reveal errors:
appcmd list config "MySite/" >nul   # Error output if config invalid
# Or use:
[xml]$cfg = Get-Content web.config  # PowerShell XML parse

💼 Example (Real-world Use Case)

A DevOps team uses Azure Pipelines to deploy an ASP.NET 4.8 application. They have three environments: Dev, Staging, Production. Each environment has a different web.config connectionString and appSetting for API keys. The pipeline uses the XDT transform pattern: base web.config holds production-safe defaults; web.Dev.config and web.Release.config contain transform instructions: <connectionStrings><add name="DB" connectionString="SERVER=prod-sql;" xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/></connectionStrings>. The pipeline applies the correct transform at build time via msdeploy -EnableLink:contentLibExtension. The result: correct connection strings are deployed per environment without hardcoding secrets in version control — the environment-specific config is applied during deployment, not committed to source.

🧪 Hands-on

Open %windir%\system32\inetsrv\config\applicationHost.config in Notepad++ or VS Code. Find the <sites> section — identify your Default Web Site's binding entry, physicalPath, and applicationPool reference.
Use appcmd to view the effective configuration for the Default Web Site: appcmd list config "Default Web Site/" /section:system.webServer/staticContent. Note the MIME type list — these are the allowed file extensions IIS will serve.
Create a web.config in C:\inetpub\wwwroot that adds a MIME type for .json files if it doesn't exist: <system.webServer><staticContent><mimeMap fileExtension=".json" mimeType="application/json" /></staticContent></system.webServer>. Browse a .json file in the wwwroot directory to confirm IIS serves it with the correct content-type header.
Verify .NET Framework registration: run appcmd list config /section:system.webServer/handlers | findstr "ASPX\|aspNetCore". Confirm ASP.NET 4.x handler entries exist. If missing, run aspnet_regiis -iru.
Create a backup of applicationHost.config: appcmd add backup "TestBackup". Check it exists: dir %windir%\system32\inetsrv\backup\. Restore it: appcmd restore backup "TestBackup". This is your disaster recovery drill for config file corruption.

💡

Never Edit applicationHost.config Directly in Production

Always edit IIS configuration through IIS Manager, PowerShell WebAdministration module, or appcmd — these tools validate changes and use proper locking mechanisms. Direct XML editing of applicationHost.config while IIS is running risks data loss (IIS writes to this file too) or partial writes causing parse errors that prevent IIS from starting. If you must edit directly: stop IIS first (iisreset /stop), make the edit, validate the XML, then start IIS. Always take an appcmd backup immediately before any direct edit.

🐛 Debugging Scenario

Failure: A newly deployed ASP.NET API returns HTTP 500.19 with the description "The configuration section 'system.webServer/aspNetCore' cannot be read because it is missing a section declaration." Sub-error code 0x8007007e.

The error means the aspNetCore config section is referenced in web.config but its schema definition is not in applicationHost.config — the ANCM module is not installed.
Verify: appcmd list config /section:system.webServer/globalModules | findstr aspNetCore — no output. ANCM is missing.
Check if .NET Core Hosting Bundle is installed: dotnet --version — "dotnet is not recognized." The Hosting Bundle was never installed on this server.
Download and install the correct .NET Core Hosting Bundle version matching the app's target framework from the official Microsoft .NET downloads page. After install, run appcmd list config /section:system.webServer/globalModules | findstr aspNetCore — the module now appears.
Clear the browser cache or test with curl http://localhost/api/health. The 500.19 is resolved. The API returns 200.

🎯 Interview Questions

Beginner

What is applicationHost.config and where is it located?▾

applicationHost.config is the master IIS configuration file containing all server-level settings: all websites, applications, virtual directories, application pools, global IIS module registrations, MIME type mappings, default document definitions, authentication settings, and security configurations. Located at: C:\Windows\System32\inetsrv\config\applicationHost.config. Every change made in IIS Manager is persisted here. It is an XML file with a strict schema. IIS reads this file at startup to build its internal configuration. Corruption or invalid XML in this file prevents IIS from starting. Its importance is often compared to the Windows registry for IIS — it is the single source of truth for all IIS configuration.

What is web.config and what can it override?▾

web.config is an XML configuration file placed in the physical root directory of an IIS application (or any subdirectory within it). It configures ASP.NET and IIS settings specific to that application. What it can configure depends on the allowOverride settings in applicationHost.config. Typically, web.config controls: application settings (AppSettings), connection strings, session state provider, authentication settings (when allowed), URL rewrite rules, custom error pages, handler and module registrations, output caching, MIME types, and ASP.NET compilation and globalization settings. Web.config is read by both IIS (for IIS-specific sections like system.webServer) and the .NET runtime (for sections like system.web, appSettings, connectionStrings).

What does aspnet_regiis do and when do you need to run it?▾

aspnet_regiis.exe is the ASP.NET IIS Registration Tool. It registers the installed .NET Framework version with IIS by updating the script maps, ISAPI handler entries, and module registrations in applicationHost.config. You need to run it: (1) after installing IIS when .NET Framework was already present (installation order matters — ideally install IIS before .NET, but if not, aspnet_regiis fixes it); (2) after a .NET Framework upgrade where handlers need to point to the new version; (3) after repairing an IIS installation where handler mappings were lost. For Server 2012+ with the feature-based installation, running Install-WindowsFeature Web-Asp-Net45 handles the registration automatically — aspnet_regiis is only needed for manual fixes or legacy scenarios.

What is the .NET Core Hosting Bundle and what does it install?▾

The .NET Core Hosting Bundle (or "IIS Hosting Bundle") is a Microsoft package that installs three components together: the .NET Runtime (for running .NET Core console apps and services), the ASP.NET Core Runtime (class libraries for web apps), and the IIS ANCM (ASP.NET Core Module v2 — aspnetcorev2.dll). ANCM is registered as a global IIS module in applicationHost.config during installation. Without ANCM, IIS cannot host ASP.NET Core applications — requests return 500.0 ANCM error. After installing the Hosting Bundle, iisreset is required for ANCM to be loaded by existing IIS worker processes. The Hosting Bundle version must be equal to or higher than the .NET version targeted by the application.

What is machine.config and how does it relate to web.config?▾

machine.config is the highest-level .NET configuration file, applied to all .NET applications on the machine. Located at: C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Config\machine.config (for .NET 4.x 64-bit). It sets CLR-wide defaults: connection pooling defaults, HTTP connection limits, cryptographic providers, and other system-wide .NET behaviors. web.config inherits from machine.config and can override some settings. In enterprise environments, machine.config is sometimes modified to: disable legacy TLS versions in the ServicePointManager (forces TLS 1.2 for all .NET outbound connections), increase connection pool limits for database-heavy servers, or change the default thread pool sizes. Changes to machine.config require an IIS restart to take effect for existing application pools.

Intermediate

What is allowOverride and how do you use it to lock down IIS configuration?▾

allowOverride is an attribute on configuration section definitions in applicationHost.config that controls whether web.config files in site directories can override that section's settings. Set via: <section name="requestFiltering" overrideModeDefault="Deny" /> in the config schema section definitions. Values: Allow (default for most sections) = web.config can override; Deny = section is locked and web.config cannot change it (attempting to do so produces 500.19 error code 0x80070021). You can also lock at the location level: <location path="MySite" overrideMode="Deny"><system.webServer><security>...settings...</security></system.webServer></location>. Security hardening practice: lock requestFiltering, directoryBrowse, and authentication sections for shared hosting or when you need to ensure application developers cannot override security policies.

Explain the XDT (XML Document Transform) pattern for web.config and how it is used in CI/CD.▾

XDT is a transformation syntax for XML files. A transform file (web.Release.config) contains XML instructions using xdt: namespace attributes. Key transforms: xdt:Transform="Replace" replaces a node. xdt:Transform="SetAttributes" updates attribute values on a matching node. xdt:Transform="RemoveAttributes" removes attributes. xdt:Locator="Match(name)" selects the element to transform by attribute value. In CI/CD: the base web.config contains development values. The pipeline applies web.Release.config transformations using the MSBuild "TransformXml" task or msdeploy -setParam. Result: the deployed web.config has production connection strings, disabled debug mode, correct app service URLs. This pattern keeps sensitive production values out of source control — the transform file contains placeholder references while the actual secret values come from CI/CD pipeline variables or Azure Key Vault.

What is a configuration section group and why does web.config reference them?▾

Configuration section groups are logical namespaces in the XML hierarchy. In .NET configuration: system.web contains ASP.NET Framework sections (authentication, compilation, sessionState, httpRuntime). system.webServer contains IIS 7+ sections (handlers, modules, defaultDocument, security, staticContent). connectionStrings is a root-level section group. AppSettings is also root-level (key-value pairs). The grouping matters because: handlers registered under system.webServer/handlers affect the IIS native pipeline for all requests; handlers under system.web/httpHandlers only affect the ASP.NET managed pipeline in Classic mode. Using the wrong section group is a common mistake when migrating from Classic to Integrated pipeline mode — system.web handlers must be duplicated in system.webServer for Integrated mode to work.

How do you encrypt sensitive sections of web.config (like connectionStrings)?▾

Use the RSA Protected Configuration Provider or DPAPI (Data Protection API). For IIS on a single server: DPAPI encryption ties the encrypted section to the machine — only that server can decrypt it. Command: aspnet_regiis -pef "connectionStrings" C:\inetpub\wwwroot\MySite -prov "DataProtectionConfigurationProvider". For a web farm: use RSA (machine key-store encryption that can be exported to other servers) or shared Certificate-based encryption. After encryption, the web.config connectionStrings section becomes encrypted XML — the .NET config system decrypts it in memory at runtime; the application code still reads ConfigurationManager.ConnectionStrings["DB"] normally without modification. Never store plaintext passwords in web.config for production — use encrypted config sections, environment variables, or Azure Key Vault references (for cloud deployments).

After installing IIS on a new server, all ASP.NET sites return 404.17. What does this mean and how do you fix it?▾

HTTP 404.17 is "Dynamic content mapped to the static file handler." It means IIS received a request for a .aspx, .asmx, or similar extension but no handler is mapped to process it — the request fell through to the StaticFileModule which cannot execute dynamic content and returns 404.17. Root cause: ASP.NET is not registered with IIS. Fix: for .NET 4.x, run %windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe -iru. On Server 2012+, ensure the IIS features "ASP.NET 4.5", "ISAPI Extensions", and "ISAPI Filters" are all installed: Install-WindowsFeature Web-Asp-Net45 -IncludeAllSubFeature. After installing features, the handler mappings for .aspx → aspnet_isapi.dll appear in applicationHost.config and IIS routes dynamic requests to the CLR instead of the static file handler.

Scenario-based

A site returns HTTP 500.19 with error code 0x80070021 after a policy change. What does this mean?▾

Error code 0x80070021 is ERROR_LOCK_VIOLATION — the configuration section referenced in web.config is locked at a higher level in applicationHost.config. Specifically, the application's web.config is attempting to set a configuration section that has overrideModeDefault="Deny" (or has been locked via a location tag). Resolution: (1) If the web.config change is legitimate (e.g., enabling Windows Authentication for this specific app): unlock the section in applicationHost.config using IIS Manager → Feature Delegation (server-level), change the section's override mode to Allow for that site. (2) If the web.config shouldn't be changing that section: remove the offending section from web.config — the application should inherit the server policy. (3) Use appcmd to check: appcmd list config "MySite/" /section:system.webServer/security/authentication and look for locked="true" attributes.

How do you troubleshoot a web.config that was manually edited and now produces 500.19 with error code 0xC00CE55D?▾

Error 0xC00CE55D is a malformed XML error — the web.config contains invalid XML syntax. The page text often says "Config Error: There is a duplicate 'X' attribute" or "Cannot read configuration file due to insufficient permissions." Steps: (1) Open web.config in a text editor and look for obvious syntax issues: unclosed tags, duplicate attribute names, wrong encoding, or copy-paste artifacts. (2) Validate the XML locally: [xml](Get-Content web.config) in PowerShell — any XML parse error is displayed with line number. (3) Compare with a reference copy from source control or the last known good backup. (4) If edited via RDP and the file got corrupted during copy-paste: re-upload from the CI/CD pipeline or restore from the appcmd backup. (5) Use the Server Manager's Configuration Editor in IIS Manager to make future changes instead of raw text editing — it validates schema before saving.

An ASP.NET Core app returns 502.5 after upgrading from .NET 6 to .NET 8. What is the most likely cause?▾

HTTP 502.5 is "ANCM Out-Of-Process Startup Failure" or "Process Failure" — the ANCM was unable to start the application process. After a .NET version upgrade, the most common causes are: (1) The .NET 8 Hosting Bundle is not installed on the server — the app tries to start with .NET 8 runtime but it doesn't exist. Fix: install the .NET 8 Hosting Bundle and run iisreset. (2) The web.config still references .NET 6 process arguments or process path that doesn't work for .NET 8. (3) Application dependency missing for .NET 8 — a NuGet package that was compatible with 6 is incompatible or not updated for 8. Diagnosis: enable stdout logging in web.config (stdoutLogEnabled=true, stdoutLogFile=.\logs\stdout) and create the logs directory with write permissions for the app pool. The stdout log will show the exact startup exception from the .NET runtime.

A CI/CD pipeline deploys the same web.config to all three environments (dev, staging, prod) and production breaks because of wrong connection strings. How do you fix the pipeline?▾

Short-term fix: use XDT transforms. Create web.Dev.config, web.Staging.config, web.Release.config transform files next to the base web.config. The pipeline selects the correct transform based on the build configuration (Debug for Dev, Release/Prod for prod). Long-term best practice: remove connection strings from web.config entirely and use environment-specific injection: On IIS, set Environment Variables on the app pool (IIS Manager → App Pool → Advanced Settings → Environment Variables). In ASP.NET Core, use IConfiguration which automatically reads environment variables — these override web.config settings without file changes. In Azure App Service, Application Settings override web.config at runtime. In Windows on-prem enterprise: use Web.config transforms in the pipeline with the actual secrets coming from a secret manager (HashiCorp Vault, CyberArk, or Azure Key Vault) — never commit environment-specific secrets to source control.

The IIS team says applicationHost.config was corrupted and IIS won't start. What are the recovery steps?▾

Recovery steps in order: (1) Check appcmd backups: dir %windir%\System32\inetsrv\backup\. If backups exist: appcmd restore backup "BackupName". IIS should start after restore. (2) If no backup: check if there is a redirection.config at the same path — it redirects to a shared config location (web farms), which may be intact. (3) Roll back to the file that was present before the corruption from your change management backup (filesystem backup, shadow copies: vssadmin list shadows). (4) If no backups: copy applicationHost.config from another identical server in the farm (same IIS version, same features installed) — you will need to re-add your site and pool configurations but IIS will start. (5) Last resort: reinstall IIS. Use Get-WindowsFeature Web-* output (saved beforehand ideally) to reinstall the exact same feature set and then reconfigure from scratch. Lesson: create automated appcmd backups before every IIS configuration change in your runbooks.

🌐 Real-world Usage

Configuration file knowledge is tested in every senior IIS engineer interview. In operational roles, understanding the config hierarchy directly reduces time-to-resolution for 500.19 and registration errors from hours to minutes. In DevOps roles, knowing how to build config transformation pipelines and securely manage connection strings is the difference between a fragile deployment process and a robust, repeatable one.

📝 Summary

applicationHost.config is the IIS master config file — never edit directly without a backup. web.config is per-application and inherits from the server policy unless sections are locked. .NET Framework needs aspnet_regiis registration; .NET Core needs the Hosting Bundle for ANCM. Every 500.19, 404.17, and 502.5 error traces back to a missing registration, locked section, or XML syntax error in one of these files.

← IIS Sites, App Pools, and Bindings NextSSL/TLS Certificates and HTTPS Binding