Debugging Multiple ASP.NET Core Projects in a Single Solution

We recently setup a new solution with multiple ASP.NET Core projects and wanted to debug them all at the same time.  This ended up being far more difficult than we expected.  Not because its actually hard but without some context it can be super confusing and the errors aren’t helpful.  So I decided to write this post to try to help others who are likely hitting the same/similar issues.

Hosting Options

There are two default options for debug hosting ASP.NET Core projects: IIS Express and Kestrel.

As you can see here IIS Express is selected by default.  The second option is the name of your ASP.NET Core project.  This is the Kestrel hosted option.  Behind the scenes this is simply calling “dotnet run” for the project. 

NOTE – There are additional options you can configure but that is outside the scope of this post.

Multi-project Debugging

Option1: Manually choose projects to debug

After starting to debug your first application you can right click another project in the solution explorer and choose to debug it as well:

Visual Studio tracks how you hosted each project previously (IIS Express or Kestrel) and will start in the same way.  To change how it opens you simply need to manually start debugging that application using your preferred hosting and then it will be remembered for the next time you want to debug.

Option 2: Single click

Visual Studio also provides a way to start debugging multiple projects at the solution level.  Right click your solution in the solution explorer and choose “Set Startup Projects…”:

Then you can select the “Multiple startup projects” option and set any number of your projects to Start.

Finally press F5 or the Start button and all the projects you selected should start with debugging:

Port and Other Errors

Web servers listen for requests which requires a networking port to listen to.  Ports cannot be shared and once a port is assigned to a IIS Express web server it keeps it even after debugging stops. This is the underlying cause of much of the confusion when trying to setup a solution to debug multiple ASP.NET Core projects.

Port conflicts caused by multiple web server hosts configured to use the same port can result in several different errors.  For example, when trying to debug two projects using the Kestrel host on the same port the second project will fail with the following error:

Failed to bind to address https://127.0.0.1:5001: address already in use.
Only one usage of each socket address (protocol/network address/port) is normally permitted.

If two projects are configured to IIS Express on the same port you will see a different error:

Starting the web server is taking longer than expected.

In this case IIS Express is trying to start the second web app but is unable to secure the configured port because the first web app as already been hosted using it.

There are further other errors as well that can occur:

Unable to connect to web server ‘IIS Express’.

When swapping between IIS Express and Ketrel hosting you may also see an error stating the web app files could not be copied due to a host locking the file:

Error    MSB3027    Could not copy “obj\Debug\netcoreapp2.1\MultiDebugSample.WebApp1.dll” to “bin\Debug\netcoreapp2.1\MultiDebugSample.WebApp1.dll”. Exceeded retry count of 10. Failed. The file is locked by: “.NET Core Host (31628)”    MultiDebugSample.WebApp1    C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\MSBuild\15.0\Bin\Microsoft.Common.CurrentVersion.targets    4187   

These are just a few of the others I was able to reproduce.  Now we will fix them!

Launch Settings

The very first thing you should check when hitting these errors is to verify all your ports are configured correctly. 

The launchSettings.json file (located in the Properties folder) controls how the web app is launched for debugging.

Here is a sample of the default contents of the file after creating a new project:

{
   “iisSettings”: {
     “windowsAuthentication”: false,
     “anonymousAuthentication”: true,
     “iisExpress”: {
       “applicationUrl”: “http://localhost:54450″,
       “sslPort”: 44337
     }
   },
   “profiles”: {
     “IIS Express”: {
       “commandName”: “IISExpress”,
       “launchBrowser”: true,
       “environmentVariables”: {
         “ASPNETCORE_ENVIRONMENT”: “Development”
       }
     },
     “MultiDebugSample.WebApp1”: {
       “commandName”: “Project”,
       “launchBrowser”: true,
       “applicationUrl”: “https://localhost:5001;http://localhost:5000″,
       “environmentVariables”: {
         “ASPNETCORE_ENVIRONMENT”: “Development”
       }
     }
   }
}

The Microsoft documentation for this file is very comprehensive and you should read it.  It doesn’t, however, cover the port configurations (at least not when I read it).  Notice the applicationUrl and sslPort properties under iisSettings/iisExpress as well as the applicationUrl property under the web app project (Kestrel hosted) profile.  These fields configure the ports used for debugging.  All of these ports should be unique.

By default when adding multiple ASP.NET Core web application projects to a solution the IIS Express ports are dynamically set and should all be different but they could start to overlap when you have many web app projects.  The Kestrel ports however are always set to:

https://localhost:5001;http://localhost:5000

The port Kestrel uses is released when debugging is stopped so this probably won’t be an issue for you if you only ever use Kestrel and only debug one project at a time.  But as soon as you try to debug two or use the same port between IIS Express and Kestrel you will starting getting the errors above.

So you should set each project’s launchSettings.json file to a use a unique set of ports for each of these properties.

Reset Everything

After you have updated/verified all the ports are unique across projects you will probably need to restart Visual Studio in order to release any assigned ports.  This should stop IIS Express and any debugging sub-process.

This is usually all that is needed but in some cases users have reported also needing to delete the hidden \.vs directory located in the root solution directory before restarting Visual Studio:

And that’s it.  Hopefully this post was helpful to you and got you debugging multiple projects quickly/easily.  Please share you debugging setup results (good or bad) in the comments below for everyone to learn from.  I’ll be happy to answer any further questions here as well.

I also uploaded the sample solution I used for writing this post to Github:

https://github.com/rschiefer/MultiDebugSample

Happy Debugging!