ASP.NET Core on IIS Express - Empty error starting application

Edit on GitHub

Usually on my development machine, I run ASP.NET Core applications in Kestrel. It’s easy to do, the project templates .NET Core provide create a nice launchSettings.json to start it from the command line, etc.

However, I was asked to help someone out with hosting ASP.NET Core in IIS Express. Great! The default launchSettings.json contain an entry for that as well, so I ran dotnet run --launch-profile "IIS Express".

Stupid me! .NET Core does not support IIS Express from the command-line! (it will fail, saying The launch profile type ‘IISExpress’ is not supported., then use Kestrel anyway). In Visual Studio though, we can select the IIS Express launch profile and run it from there.

To my surprise, not a lot happened. IIS Express did not launch, and the IDE was quite silent as well. So I tried in a nightly build of JetBrains Rider, seeing the same.

That must mean my IIS Express configuration is wrong! Good thing IIS Express can be launched from the command-line, and usually displays an error when something is wrong - this would help me troubleshoot for sure!

In a console, I ran "C:\Program Files (x86)\IIS Express\iisexpress.exe" /config:"C:/Users/maart/Desktop/AcmeCorp.Web/.idea/config/applicationhost.config" /site:"AcmeCorp.Web" /apppool:"Clr4IntegratedAppPool", and that indeed errored out:

IIS Express errors out on ASP.NET Core with no details

Ehm. Thanks? Windows Error logs and other places were not really helpful either.

Stepping back: prerequisites for ASP.NET Core on IIS Express

So, something was wrong in IIS Express, but it refused to tell me what. Taking a step back is always a good idea: what do we need to run ASP.NET Core on IIS Express?

To be sure I had all of them installed, I re-installed them all. Only to keep seeing Error: in IIS Express. Huh.

How does ASP.NET Core work in IIS Express?

As I mentioned before, the dotnet command does not support IIS Express directly. We need to use an IDE like Visual Studio or Rider to launch IIS Express with the correct arguments and a configuration file.

This configuration file is important: IIS Express cannot host .NET Core applications out of the box. It needs to have the .NET Core hosting bundle installed in order to glue ASP.NET Core into the IIS Express hosting model. It does that by adding a module that then spawns a child process, which IIS Express forwards traffic to.

Have you ever written such configuration file? Possibly, but most probably not. Visual Studio and Rider generate it for us, and store it under our solution folder in one of these locations:

  • .vs/config/applicationhost.config
  • .idea/config/applicationhost.config

After double-checking these files with a colleague, it seemed that these did not contain any mention of ASP.NET Core. More huh.

Side-step: how does the IDE generate applicationhost.config?

When Visual Studio or Rider launch an ASP.NET Core IIS Express profile, they verify whether an applicationhost.config file exist. If not, they copy the template file from %PROGRAMFILES(x86)%\IIS Express\config\templates\PersonalWebServer\applicationhost.config.

Next, the launchSettings.json file is read and used to set some details such as the application URL, whether SSL should be enabled or not, authentication settings, etc.

Once that’s done, the command I mentioned earlier is used to start IIS Express to host our application.

Now, checking %PROGRAMFILES(x86)%\IIS Express\config\templates\PersonalWebServer\applicationhost.config also yielded no mention of any .NET Core hosting modules. So any project that copied from that template, would also not have ASP.NET Core support. Let’s fix it!

Fixing the applicationhost.config template

The .NET Core hosting bundle should install a couple of things:

  • Some binaries:
    • %PROGRAMFILES(x86)%\IIS Express\aspnetcore.dll
    • %PROGRAMFILES(x86)%\IIS Express\Asp.Net Core Module\V2\...
  • Some updates to %PROGRAMFILES(x86)%\IIS Express\config\templates\PersonalWebServer\applicationhost.config

The binaries were there, the updates in applicationhost.config were not. Here’s what to add:

Diff of required changes

In case you want to copy/paste some things:

  • Under <system.webServer><globalModules>, add: <add name="AspNetCoreModule" image="%IIS_BIN%\aspnetcore.dll" /><add name="AspNetCoreModuleV2" image="%IIS_BIN%\Asp.Net Core Module\V2\aspnetcorev2.dll" />
  • Under <sectionGroup name="system.webServer">, add: <section name="aspNetCore" overrideModeDefault="Allow" />
  • Under <location path="" overrideMode="Allow"><system.webServer><modules>, add <add name="AspNetCoreModule" lockItem="true" /><add name="AspNetCoreModuleV2" lockItem="true" />

Save it, remove the .vs/config/applicationhost.config or .idea/config/applicationhost.config file, try again. Things will work!


I hope this helps you, or my future self, in case ASP.NET Core on IIS Express doesn’t work first-time.

A big thank you to Ivan Migalev, my colleague who helped troubleshoot!


Leave a Comment


8 responses

  1. Avatar for priya
    priya April 24th, 2019

    Hey, It was really a wonderful blog. Thanks for the provided information.

  2. Avatar for Dave
    Dave May 22nd, 2019

    Maarten, thanks for this writeup. In my case my swagger output was totally inaccessible, always resulting in a 404. I checked the applicationhost.config file and the IDE had created a /swagger virtual directory pointing to “/”.. I have no idea why it chose to do this, and the same config file from a fresh Swashbuckled project did not have this virtual directory, so I simply deleted applicationhost.config and let the IDE rebuild it - everything works fine now.

  3. Avatar for Jonas
    Jonas June 13th, 2019

    I am struggling with deploying my core & Kestrel Webapp on my Ubuntu server. I use azure devops to deploy it but that never works and there is basically no error message. So what I always end up doing is clone the repo and publish it myself…

  4. Avatar for Vincent
    Vincent July 12th, 2019

    Hi Maarten,

    Thanks for sharing this information. I try to deploy my core on asphostportal and I receive 502.5 error. Is there any insight?

    Thank you

  5. Avatar for Aaron Queenan
    Aaron Queenan September 11th, 2019

    I found exactly the same problem, but caused by 64-bit versions of the aspnetcore dlls and schema (the 32-bit versions were present). refers to the problem.

    Repairing Visual Studio 2019 fixed the problem for me.

    Note that this was from an almost clean install of Visual Studio 2019.

  6. Avatar for Aaron
    Aaron January 31st, 2020

    @Vincent If you receive 502 error message, you might try to see this article If you read the tutorial above correctly, it should be no problem and your .net core will work fine without any issue

  7. Avatar for Bala
    Bala February 26th, 2020

    This saved me! Thanks a lot.

  8. Avatar for khan hamiz
    khan hamiz November 17th, 2021

    Thanks for sharing this information. I try to deploy my core on asphostportal and I receive 502.5 error. Is there any insight?