Debug apps in a local Docker container

Visual Studio provides a consistent way to develop in a Docker container and validate your application locally. You don't have to restart the container each time you make a code change.

This article illustrates how to use Visual Studio to start an ASP.NET Core web app in a local Docker container, make changes, and then refresh the browser to see the changes. This article also shows you how to set breakpoints for debugging for containerized ASP.NET Core web apps and .NET Framework console apps.

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 the Docker Toolbox, which requires Hyper-V to be disabled. You also can use Docker for Windows, which uses Hyper-V and requires Windows 10.

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

  1. In the Visual Studio menu, select File > New > Project.
  2. In the Templates section of the New Project dialog box, select Visual C# > Web.
  3. Select ASP.NET Core Web Application.
  4. Enter a name for your new application (or use the default name), and then select OK.
  5. Select Web Application.
  6. Select the Enable Docker Support check box.
  7. Select the type of container you want (Windows or Linux), and then select OK.
  1. In the Visual Studio start window, select Create a new project.
  2. Select ASP.NET Core Web Application, and then select Next.
  3. Enter a name for your new application (or use the default name), and then select Create.
  4. Select Web Application.
  5. Choose whether you want SSL support by selecting or clearing the Configure for HTTPS check box.
  6. Select the Enable Docker Support check box.
  7. Select the type of container you want (Windows or Linux), and then select Create.

Edit your code and refresh

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

  1. 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.

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

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

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

    <h1>Hello from a Docker container!</h1>
    
  5. 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.

    Breakpoint

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.

    Breakpoint

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.

More about Docker with Visual Studio, Windows, and Azure