Debug apps in a local Docker container

Applies to: Visual Studio Visual Studio for Mac

Visual Studio provides a consistent way to develop Docker containers and validate your application locally. You can run and debug your apps in Linux or Windows containers running on your local Windows desktop with Docker installed, and you don't have to restart the container each time you make a code change.

If you already have a project of a supported type, Visual Studio can create a Dockerfile and configure your project to run in a container. See Container Tools in Visual Studio.

Prerequisites

To debug apps in a local Docker container, the following tools must be installed:

To run Docker containers locally, you must have a local Docker client. You can use Docker Desktop, which requires Windows 10 or later.

Docker containers are available for .NET Framework and .NET Core projects. Let's look at two examples. First, we look at a .NET Core web app. Then, we look at a .NET Framework console app.

Create a web app

If you have a project and you've added Docker support as described in the overview, skip this section.

Edit your Razor pages and refresh

To quickly iterate changes in your Razor pages, you can start your application in a container. Then, continue to make changes, viewing them as you would with IIS Express.

1. Make sure that Docker is set up to use the container type (Linux or Windows) that you are using. Right-click on the Docker icon on the Taskbar, and choose Switch to Linux containers or Switch to Windows containers as appropriate.

2. (.NET Core 3 and later only) Editing your code and refreshing the running site as described in this section is not enabled in the default templates in .NET Core >= 3.0. To enable it, add the NuGet package Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation. In Startup.cs, add a call to the extension method IMvcBuilder.AddRazorRuntimeCompilation to the code in the ConfigureServices method. You only need this enabled in DEBUG mode, so code it as follows:

   public IWebHostEnvironment Env { get; set; }
   
   public void ConfigureServices(IServiceCollection services)
   {
       IMvcBuilder builder = services.AddRazorPages();
   
   #if DEBUG
       if (Env.IsDevelopment())
       {
           builder.AddRazorRuntimeCompilation();
       }
   #endif
   
       // code omitted for brevity
   }
   

   Modify the Startup method as follows:

   public Startup(IConfiguration configuration, IWebHostEnvironment webHostEnvironment)
   {
       Configuration = configuration;
       Env = webHostEnvironment;
   }
   

   For more information, see Razor file compilation in ASP.NET Core.

3. Set Solution Configuration to Debug. Then, press Ctrl+F5 to build your Docker image and run it locally.

   When the container image is built and running in a Docker container, Visual Studio launches the web app in your default browser.

4. Go to the Index page. We'll make changes on this page.

5. Return to Visual Studio and open Index.cshtml.

6. Add the following HTML content to the end of the file, and then save the changes.

   <h1>Hello from a Docker container!</h1>
   

7. In the output window, when the .NET build is finished and you see the following lines, switch back to your browser and refresh the page:

   Now listening on: http://*:80
   Application started. Press Ctrl+C to shut down.
   

Your changes have been applied!

Debug with breakpoints

Often, changes require further inspection. You can use the debugging features of Visual Studio for this task.

1. In Visual Studio, open Index.cshtml.cs.

2. Replace the contents of the OnGet method with the following code:

       ViewData["Message"] = "Your application description page from within a container";
   

3. To the left of the code line, set a breakpoint.

4. To start debugging and hit the breakpoint, press F5.

5. Switch to Visual Studio to view the breakpoint. Inspect values.

Create a .NET Framework console app

When you use .NET Framework console app projects, the option to add Docker support without orchestration isn't supported. You can still use the following procedure, even if you're using only a single Docker project.

1. Create a new .NET Framework Console app project.
2. In Solution Explorer, right-click the project node, and then select Add > Container Orchestration Support. In the dialog box that appears, select Docker Compose. A Dockerfile is added to your project and a Docker Compose project with associated support files is added.

Debug with breakpoints

1. In Solution Explorer, open Program.cs.

2. Replace the contents of the Main method with the following code:

       System.Console.WriteLine("Hello, world!");
   

3. Set a breakpoint to the left of the code line.

4. Press F5 to start debugging and hit the breakpoint.

5. Switch to Visual Studio to view the breakpoint and inspect values.

Container reuse

During the development cycle, Visual Studio rebuilds only your container images and the container itself when you change the Dockerfile. If you don't change the Dockerfile, Visual Studio reuses the container from an earlier run.

If you manually modified your container and want to restart with a clean container image, use the Build > Clean command in Visual Studio, and then build as normal.

Troubleshoot

Learn how to troubleshoot Visual Studio Docker development.

Next steps

Get more details by reading How Visual Studio builds containerized apps.

More about Docker with Visual Studio, Windows, and Azure

• Learn more about container development with Visual Studio.
• To build and deploy a Docker container, see Docker integration for Azure Pipelines.
• For an index of Windows Server and Nano Server articles, see Windows container information.
• Learn about Azure Kubernetes Service and review the Azure Kubernetes Service documentation.