A Comprehensive Guide to Using Custom Domains with IIS Express

Introduction

Using custom domains (e.g., dev.example.com) in local development environments enhances flexibility, especially when integrating with external APIs like Facebook. Traditionally, developers could easily achieve this with the built-in Visual Studio Development Server by adding a CNAME record pointing to 127.0.0.1. However, transitioning to IIS Express often leads to configuration challenges, such as receiving a "Bad Request - Invalid Hostname" error after adding bindings to applicationHost.config. This article systematically explains how to configure custom domains in IIS Express, based on high-quality answers from the Stack Overflow community, covering core steps, common pitfalls, and solutions.

Core Configuration Steps

The following steps use Visual Studio 2013 as an example; note path differences for other versions (e.g., 2010 or 2015). First, right-click the web application project in Visual Studio, select "Properties," and navigate to the "Web" tab. In the "Servers" section, choose IIS Express from the dropdown, set the "Project Url" to http://localhost, and enter http://dev.example.com in the "Override application root URL" field. Click the "Create Virtual Directory" button; if errors occur, check for port conflicts (e.g., port 80 being used) or temporarily disable IIS services.

Next, edit the IIS Express configuration file applicationhost.config. This file is typically located at %USERPROFILE%\My Documents\IISExpress\config\ (Windows XP, Vista, and 7) or in the solution folder at \.vs\config (Visual Studio 2015). In the <sites> configuration block, modify or add a site definition, as shown in this example:

<site name="DevExample" id="997005936">
    <application path="/" applicationPool="Clr2IntegratedAppPool">
        <virtualDirectory
            path="/"
            physicalPath="C:\path\to\application\root" />
    </application>
    <bindings>
        <binding
            protocol="http"
            bindingInformation=":80:dev.example.com" />
    </bindings>
    <applicationDefaults applicationPool="Clr2IntegratedAppPool" />
</site>

For MVC applications, ensure the applicationPool is set to an integrated mode (e.g., Clr2IntegratedAppPool or Clr4IntegratedAppPool) to avoid handler issues. Then, edit the system's hosts file (located at C:\Windows\System32\drivers\etc\), adding the line 127.0.0.1 dev.example.com to resolve the domain to localhost. After completing these steps, start the application to access it via http://dev.example.com.

Advanced Configuration and Troubleshooting

If issues persist after configuration, first try running Visual Studio as an administrator, as certain operations (e.g., binding port 80) require elevated privileges. For example, execute netsh http add urlacl url=http://dev.example.com:80/ user=everyone in the command prompt to allow other users to access the site, useful in team development environments. Additionally, the bindingInformation parameter supports wildcards, such as setting it to "*:80:" to make the site respond to all hostnames, but be mindful of security and permission requirements.

For Visual Studio 2015 users, the configuration file location has changed; look for applicationhost.config in the solution folder at \.vs\config. Upgrades may leave old versions of the file, causing configurations to not take effect, so it's advisable to search the solution folder to confirm the correct file. Example configurations can include multiple bindings, such as supporting both localhost and custom domains:

<bindings>
    <binding protocol="http" bindingInformation="*:49707:" />
    <binding protocol="http" bindingInformation="*:49707:localhost" /> 
</bindings>

Common errors like "Bad Request - Invalid Hostname" often stem from incorrect hosts file configuration or malformed binding information. Ensure bindingInformation follows the <IP address>:<port>:<hostname> format and that the hostname matches entries in the hosts file. If using non-standard ports (e.g., 1288), specify them explicitly in the URL, such as http://dev.example.com:1288.

Conclusion and Best Practices

Configuring custom domains in IIS Express involves multiple coordinated steps: Visual Studio project settings, applicationhost.config editing, hosts file modification, and permission management. Key points include using integrated application pools, correctly binding ports and hostnames, and running the development environment as an administrator. For cross-version development, note changes in configuration file paths and regularly test setups for compatibility. Practice shows that with a systematic approach, IIS Express can effectively support custom domains, enhancing development experience and API integration efficiency. Developers are advised to tailor configurations to project needs and consult community resources for specific issues.