web.config Essentials for Windows Hosting

On Windows Hosting, web.config does the job that .htaccess does on Linux hosting: it tells IIS how to handle your site. It is an XML file in your site's root folder, and IIS applies changes as soon as you save it, with no restart needed.

This article gives you tested snippets for the settings people most often need. Rewrite and redirect rules have their own article: URL Rewrite Rules in web.config.

Before you edit

• Download a backup copy of your current web.config. One typo takes the whole site down with an HTTP 500.19 error.
• A site has only one <configuration> root. Merge new snippets into the existing sections; don't paste a second <configuration> or <system.webServer> block.
• XML is case-sensitive: <system.webServer>, not <System.WebServer>.
• Edit with the StackCP File Manager or a proper text editor (VS Code, Notepad++). Word processors break the file.

A minimal web.config

If your site is static HTML or PHP and has no web.config yet, start from this:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <!-- snippets from this article go here -->
  </system.webServer>
</configuration>

                        
                    

Set the default document

IIS already looks for default.aspx, Default.asp, index.php, index.htm, Default.htm, index.asp, index.html and iisstart.htm in that order. To make a different file the home page, or to change the order:

<system.webServer>
  <defaultDocument enabled="true">
    <files>
      <clear />
      <add value="home.html" />
      <add value="index.html" />
    </files>
  </defaultDocument>
</system.webServer>

                        
                    

<clear /> removes the built-in list so only your entries apply. Without it, your entries are added to the top of the existing list.

Custom error pages

Show your own friendly pages instead of IIS's generic ones. Create 404.html and 500.html in the site root, then add:

<system.webServer>
  <httpErrors errorMode="Custom" existingResponse="Replace">
    <remove statusCode="404" />
    <error statusCode="404" path="/404.html" responseMode="ExecuteURL" />
    <remove statusCode="500" />
    <error statusCode="500" path="/500.html" responseMode="ExecuteURL" />
  </httpErrors>
</system.webServer>

                        
                    

For ASP.NET pages, also set the ASP.NET-level setting so exceptions are handled the same way:

<system.web>
  <customErrors mode="RemoteOnly" defaultRedirect="~/500.html" redirectMode="ResponseRewrite">
    <error statusCode="404" redirect="~/404.html" />
  </customErrors>
</system.web>

                        
                    

RemoteOnly shows friendly pages to visitors. With existingResponse="Replace", IIS replaces errors your code returns too, which can hide JSON error bodies from an API. Use existingResponse="Auto" if that is a problem.

Add missing MIME types

IIS refuses to serve file types it doesn't know, returning 404.3. Newer formats may need adding. Remove each extension first, so you don't hit a “duplicate collection entry” error if it already exists on the server:

<system.webServer>
  <staticContent>
    <remove fileExtension=".webp" />
    <mimeMap fileExtension=".webp" mimeType="image/webp" />
    <remove fileExtension=".avif" />
    <mimeMap fileExtension=".avif" mimeType="image/avif" />
    <remove fileExtension=".woff2" />
    <mimeMap fileExtension=".woff2" mimeType="font/woff2" />
    <remove fileExtension=".webmanifest" />
    <mimeMap fileExtension=".webmanifest" mimeType="application/manifest+json" />
    <remove fileExtension=".json" />
    <mimeMap fileExtension=".json" mimeType="application/json" />
  </staticContent>
</system.webServer>

                        
                    

Browser caching for static files

Tell browsers to keep images, CSS and JavaScript for 30 days, which makes repeat visits much faster:

<system.webServer>
  <staticContent>
    <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="30.00:00:00" />
  </staticContent>
</system.webServer>

                        
                    

<clientCache> lives inside the same <staticContent> element as your MIME types. If you change a file but keep its name, visitors may see the old copy until the cache expires; add a version to the file name or query string (style.css?v=2) when you update.

Compression

Compressing text responses makes pages smaller. Enable it for your site with:

<system.webServer>
  <urlCompression doStaticCompression="true" doDynamicCompression="true" />
</system.webServer>

                        
                    

This switches on whatever compression the server provides. If dynamic (ASP.NET page) compression isn't available on the server, the setting is simply ignored. You can check the result in your browser's developer tools: a compressed response shows Content-Encoding: gzip (or br).

Allow bigger uploads

ASP.NET limits request size to 4 MB by default, and IIS to about 28.6 MB. To allow uploads up to 50 MB, raise both. Note the different units:

<system.web>
  <!-- kilobytes: 51200 KB = 50 MB -->
  <httpRuntime maxRequestLength="51200" executionTimeout="300" />
</system.web>
<system.webServer>
  <security>
    <requestFiltering>
      <!-- bytes: 52428800 = 50 MB -->
      <requestLimits maxAllowedContentLength="52428800" />
    </requestFiltering>
  </security>
</system.webServer>

                        
                    

If you already have an <httpRuntime> element (for example with targetFramework), add the attributes to it rather than creating a second one. Too large an upload fails with 404.13 (IIS limit) or “Maximum request length exceeded” (ASP.NET limit).

Add or remove response headers

<system.webServer>
  <httpProtocol>
    <customHeaders>
      <remove name="X-Powered-By" />
      <add name="X-Content-Type-Options" value="nosniff" />
      <add name="Referrer-Policy" value="strict-origin-when-cross-origin" />
    </customHeaders>
  </httpProtocol>
</system.webServer>

                        
                    

More security settings are in Secure Your ASP.NET Site with web.config.

Common problems

• HTTP 500.19 right after saving. The XML is invalid or a section is duplicated. Restore your backup, then add the change again carefully. The error page shows the line number.
• “This configuration section cannot be used at this path”. That section is locked at server level on shared hosting. Remove it and ask support if you need the setting.
• “Cannot add duplicate collection entry”. Add a <remove> line before the <add> or <mimeMap>, as shown above.

Need help?

If something doesn't work as described, open a support ticket from your client area or message us on WhatsApp at 01818160926. Attach your web.config (with passwords removed) and we will check it for you.