ASP.NET Web.config

The ASP.NET web.config file is one of the most important files in many Microsoft web applications. It can control application settings, database connections, authentication, authorisation, error handling, URL redirects, IIS modules, request limits, security headers, and deployment behaviour.

For businesses running ASP.NET Framework, ASP.NET MVC, Web Forms, Web API, or ASP.NET Core applications behind IIS, a well-managed web.config file can be the difference between a stable production system and a fragile application that is hard to deploy, secure, or troubleshoot.

What is web.config?

web.config is an XML configuration file used by ASP.NET and IIS-hosted applications. It usually lives in the root of a web application, although additional web.config files can exist in subfolders to apply more specific rules.

The file gives ASP.NET and IIS instructions about how the application should behave. It can define runtime settings, request handling rules, security policies, connection strings, error pages, HTTP headers, URL rewriting, static content behaviour, and many hosting-related options.

In traditional ASP.NET Framework applications, web.config is central to runtime behaviour. In ASP.NET Core applications, configuration is often handled through appsettings.json, environment variables, secret stores, and configuration providers, but a web.config file is still commonly used when the app is hosted on IIS because it configures the ASP.NET Core Module and IIS hosting behaviour.

Why web.config matters

A small configuration mistake can cause major operational problems. A missing handler can break routing. A bad connection string can take the site offline. A weak error setting can expose stack traces. A misconfigured rewrite rule can create redirect loops. An incorrect application pool or module setting can stop the application from starting.

Because web.config sits between application code, IIS, security, and deployment, it should be treated as a production-critical file rather than a simple local development setting.

How web.config works with IIS

IIS reads configuration from multiple levels: machine-level configuration, server-level settings, site-level settings, application-level settings, and folder-level web.config files. This layered model allows broad defaults to be set centrally while individual applications override specific settings when needed.

When a request reaches IIS, the server uses configuration to decide how to process it. That may include SSL enforcement, request filtering, authentication, routing, handler selection, module execution, static file handling, compression, logging, and hand-off to the ASP.NET runtime or ASP.NET Core Module.

This means web.config is not just an application file. It is also part of the hosting contract between the application and IIS.

Common sections in an ASP.NET web.config file

appSettings

The appSettings section stores simple key-value pairs used by the application. Older ASP.NET applications often use it for feature flags, environment names, API endpoints, email settings, or behaviour toggles.

It is useful for non-sensitive settings, but production secrets should not be stored in plain text inside committed configuration files.

connectionStrings

The connectionStrings section defines database connections, often for SQL Server, Entity Framework, or other data providers. This section is business-critical because the application may fail immediately if the connection string is wrong.

Connection strings should be protected carefully. Teams should avoid committing production credentials to source control and should use secure deployment processes, encrypted configuration, environment variables, or secret management where possible.

system.web

The system.web section is heavily used by ASP.NET Framework applications. It can include settings for compilation, authentication, authorisation, custom errors, session state, pages, globalization, HTTP runtime limits, and membership providers.

Important production checks include ensuring debug mode is disabled, custom errors are configured safely, request limits are appropriate, and authentication settings match the application’s security model.

system.webServer

The system.webServer section controls IIS-specific behaviour. It may include handlers, modules, rewrite rules, static content settings, compression, custom headers, request filtering, default documents, HTTP errors, and security settings.

This section is often where IIS hosting issues appear. If modules, handlers, or rewrite rules are wrong, the application may build correctly but fail when deployed.

runtime

The runtime section can include assembly binding redirects in older .NET Framework applications. Binding redirects tell the runtime which assembly version to load when different libraries depend on different versions.

Incorrect binding redirects can cause production-only errors such as missing methods, assembly load failures, or version conflicts.

aspNetCore

For ASP.NET Core applications hosted on IIS, the aspNetCore element configures the ASP.NET Core Module. It can define the process path, arguments, hosting model, environment variables, and stdout logging settings.

This section is especially important during ASP.NET Core deployments because it helps IIS start and proxy requests to the application correctly.

web.config in ASP.NET Framework

In ASP.NET Framework applications, web.config is often the main configuration source. It may control:

• Application settings and feature flags.
• Database connection strings.
• Authentication mode, such as Forms, Windows, or None.
• Role-based authorisation rules.
• Session state and cookie behaviour.
• Compilation and target framework settings.
• HTTP handlers and modules.
• Custom errors and error pages.
• Request size, timeout, and upload limits.
• Assembly binding redirects.

This makes the file extremely powerful, but it also means it can accumulate years of old settings, comments, workarounds, and environment-specific edits. Cleaning it up often reveals technical debt and deployment risk.

web.config in ASP.NET Core

ASP.NET Core changed the configuration model. Most application settings are now commonly stored in appsettings.json, environment variables, user secrets, Azure App Configuration, Key Vault, command-line arguments, or custom providers.

Even so, IIS-hosted ASP.NET Core applications often include a web.config file generated during publish. Its job is usually to configure the IIS ASP.NET Core Module so IIS can launch or proxy to the application.

Typical ASP.NET Core web.config concerns include:

• Correct process path and hosting model.
• Environment variable injection.
• stdout logging for startup troubleshooting.
• Request handler mapping for ASP.NET Core.
• IIS-level redirects or security headers where required.

Security best practices for web.config

Because web.config can contain sensitive settings and security controls, it should be reviewed as part of any production readiness process.

• Do not commit production secrets: Avoid storing live passwords, API keys, tokens, or certificates in source-controlled configuration files.
• Disable debug in production: Debug mode can expose extra detail and reduce performance.
• Protect custom errors: Users should see friendly error pages, not internal stack traces, database errors, or server paths.
• Force HTTPS: Use HTTPS redirects, HSTS, and correct certificate configuration where appropriate.
• Use secure cookies: Configure authentication and session cookies with secure, HttpOnly, and SameSite behaviour where suitable.
• Harden headers: Add appropriate security headers such as Strict-Transport-Security, X-Content-Type-Options, Referrer-Policy, X-Frame-Options, and Content-Security-Policy.
• Limit request sizes: Prevent unnecessarily large uploads or requests from exhausting server resources.
• Review authentication and authorisation: Ensure protected paths are not accidentally exposed.
• Lock down file access: Prevent direct access to sensitive files, backups, logs, or configuration artifacts.
• Use least privilege: Match IIS application pool identity permissions to the application’s real needs.

Performance and reliability settings

A well-tuned web.config file can improve performance and reliability. The right settings depend on the application, but common areas include:

• Compression: Reduce response sizes for text-based assets and API responses.
• Static content caching: Cache images, CSS, JavaScript, and fonts safely for faster page loads.
• Request limits: Configure upload size, timeout, and request filtering based on real requirements.
• Default documents: Ensure the correct start page or route is served.
• Error pages: Provide clear user-facing error handling while preserving diagnostic logs.
• Logging: Use appropriate logging and avoid excessive noisy output in production.
• Rewrite rules: Keep redirects efficient, predictable, and loop-free.

URL rewriting and redirects

Many ASP.NET sites use IIS URL Rewrite rules in web.config. Rewrite rules can enforce HTTPS, redirect old URLs, support clean URLs, route legacy paths, remove or add trailing slashes, redirect non-www to www, or preserve SEO value during migrations.

Redirects are powerful but risky. A badly written rule can create loops, break APIs, redirect assets incorrectly, or damage search performance. Redirect rules should be tested across real paths, API routes, static files, and edge cases before production release.

Environment-specific configuration

Most applications need different settings for development, staging, and production. The challenge is to separate environment-specific values without creating manual, error-prone deployment steps.

Common approaches include:

• Web.config transforms: Traditional ASP.NET projects can use transforms such as Web.Release.config.
• Deployment variables: CI/CD pipelines can inject environment-specific values during release.
• Environment variables: Useful for containerised, cloud, and modern hosting models.
• Secret stores: Azure Key Vault, AWS Secrets Manager, Parameter Store, or other vault systems can protect sensitive values.
• External configuration: Azure App Configuration or centralised configuration services can reduce hard-coded deployment settings.

The best approach depends on whether the application is ASP.NET Framework, ASP.NET Core, IIS-hosted, cloud-hosted, containerised, or part of a hybrid environment.

Common web.config problems

Many production issues in ASP.NET systems are caused by configuration drift or misunderstood settings. Common problems include:

• Production secrets committed to source control.
• Debug enabled in production.
• Custom errors disabled, exposing stack traces.
• Incorrect connection strings after deployment.
• Missing or incorrect binding redirects.
• URL rewrite rules that create redirect loops.
• Request limits too low for legitimate uploads.
• Request limits too high, creating denial-of-service risk.
• Environment-specific settings edited manually on the server.
• ASP.NET Core Module misconfiguration.
• Incorrect file permissions for the IIS application pool identity.
• Security headers missing or duplicated by multiple layers.
• Configuration differences between developer machines, staging, and production.

web.config and CI/CD

Modern teams should avoid treating web.config as a manual server file. Instead, it should be part of a repeatable deployment process. CI/CD pipelines can validate, transform, package, and deploy configuration consistently.

A robust ASP.NET deployment pipeline may:

1. Restore packages and build the solution.
2. Run unit and integration tests.
3. Validate XML configuration syntax.
4. Apply environment-specific transforms or variables.
5. Scan for accidentally committed secrets.
6. Package the web application.
7. Deploy to IIS, Azure App Service, containers, or another hosting target.
8. Run smoke tests after deployment.
9. Monitor logs and metrics for startup or configuration failures.

This reduces risk and makes deployments easier to reproduce, audit, and roll back.

How to review a web.config file

A practical review should look at both technical correctness and business risk. Useful questions include:

• Does the file contain secrets or sensitive production values?
• Are development and production settings clearly separated?
• Are authentication and authorisation rules correct?
• Are error pages safe for production?
• Are HTTPS redirects and security headers configured properly?
• Are request limits appropriate for the application?
• Are rewrite rules tested and documented?
• Are binding redirects still needed and correct?
• Does the configuration match the IIS application pool and hosting model?
• Can the same configuration be rebuilt and redeployed by CI/CD?
• Are obsolete settings adding confusion or risk?

Modernising legacy web.config files

Older ASP.NET applications often have large web.config files that have grown over many years. They may contain obsolete settings, commented-out experiments, old provider configuration, unused app settings, duplicated redirects, and environment-specific values that no one fully understands.

Modernisation should be careful and staged:

1. Inventory current settings: Document each section and identify what still matters.
2. Remove dead configuration: Clean up unused keys, duplicate rules, and obsolete comments.
3. Separate secrets: Move sensitive values into secure storage or deployment variables.
4. Standardise environments: Make development, staging, and production differences explicit.
5. Automate transforms: Remove manual server edits from the release process.
6. Harden security: Review headers, errors, authentication, cookies, request filtering, and permissions.
7. Add tests: Use smoke tests and deployment checks to catch broken configuration early.
8. Plan migration: If moving to ASP.NET Core or cloud hosting, decide which settings should stay in web.config and which should move elsewhere.

How Eight Mile can help

Eight Mile can help with custom software development, web applications, backend APIs, cloud infrastructure, CI/CD, workflow automation, system architecture, technical consultancy, and legacy modernisation. ASP.NET web.config work often touches all of these areas because it affects application behaviour, hosting, deployment, security, and long-term maintainability.

For ASP.NET web.config projects, Eight Mile can support:

• web.config audits: Review security, connection strings, redirects, headers, modules, handlers, request limits, and environment settings.
• ASP.NET troubleshooting: Diagnose configuration-related startup failures, IIS errors, routing problems, deployment issues, and production-only bugs.
• IIS configuration: Align web.config with IIS sites, application pools, bindings, certificates, permissions, logging, and hosting requirements.
• Security hardening: Improve secrets handling, HTTPS enforcement, headers, custom errors, cookie policies, request filtering, and access control.
• CI/CD implementation: Build Azure DevOps, GitHub Actions, or other pipelines that transform, validate, package, and deploy ASP.NET applications safely.
• Legacy modernisation: Clean up older ASP.NET Framework, Web Forms, MVC, and Web API applications without unnecessary rewrite risk.
• ASP.NET Core migration: Plan how configuration should move from legacy web.config patterns into modern configuration providers.
• Cloud migration: Move IIS-hosted workloads to Azure App Service, virtual machines, containers, or hybrid environments where appropriate.
• Performance improvement: Tune caching, compression, request limits, startup behaviour, logging, and operational settings.
• Ongoing support: Maintain, monitor, and improve ASP.NET systems after launch or migration.

Whether you need a single configuration fix, a full production hardening review, a safer deployment pipeline, or a phased ASP.NET modernisation plan, Eight Mile can help turn configuration risk into a reliable delivery process.

Conclusion

The ASP.NET web.config file is small in size but large in impact. It influences security, hosting, deployment, routing, application settings, database access, error handling, and IIS behaviour. Teams that understand and manage it carefully can reduce downtime, improve security, make deployments repeatable, and keep ASP.NET applications easier to maintain.

Need help with ASP.NET web.config files, IIS hosting, or Microsoft application modernisation? Contact Eight Mile.