Debug apps in a local Docker container

  • Article

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

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.

This article illustrates how to use Visual Studio to start an 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 apps. Supported project types include .NET Framework and .NET Core web and console apps. In this article, we use ASP.NET Core web apps and .NET Framework console apps.

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.

  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.

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