Introduction

Containers have become a normal part of .NET development. Developers use them to reproduce production-like environments, run dependencies locally, and keep application environments consistent across machines.

Docker has traditionally been the most common container runtime in Visual Studio. Visual Studio now also supports Podman, giving .NET developers another option for building, running, inspecting, and debugging containerized applications directly from the IDE.

Visual Studio Container Tools can work with Podman Desktop and Podman as the active container runtime. Visual Studio can automatically detect the active runtime, or developers can explicitly select Podman from the Container Tools settings. The current tooling also supports viewing containers, logs, environment variables, ports, files, and other container information from the IDE.

The useful part is not simply running a container. Developers can start a .NET application in a Podman container and debug it using familiar Visual Studio features such as breakpoints and the debugger.

This article explains how the workflow works, how to configure Podman, how to debug a .NET application, and what to check when debugging does not work as expected.

What Is Podman?

Podman is a container engine that provides a daemonless container architecture and supports common container workflows.

For a .NET developer, the important point is that Podman can serve as the local container runtime while Visual Studio provides the development and debugging experience.

The architecture looks like this:

Visual Studio
      |
      v
Container Tools
      |
      v
Podman
      |
      v
.NET Container
      |
      v
ASP.NET Core Application

You can still work with project files, source code, breakpoints, debugging windows, and other Visual Studio features while the application itself runs inside the container.

Visual Studio also supports Podman Compose for multi-container applications.

Why Use Podman With Visual Studio?

The main benefit is development flexibility.

A team may already use Podman in its development environment, or developers may prefer its container workflow. Having Podman support in Visual Studio means the development environment does not have to be redesigned simply to use the IDE's container debugging features.

Podman can be useful when you want to:

  • Run .NET applications in containers locally.

  • Debug the application from Visual Studio.

  • Inspect container logs without leaving the IDE.

  • Work with container images and ports.

  • Run multi-container applications with Podman Compose.

  • Keep development closer to the container environment used elsewhere in the organization.

The Visual Studio documentation also supports switching between Docker and Podman container runtimes without changing the basic project workflow.

Prerequisites

Before starting, install the required development components.

You need:

  1. Visual Studio with the appropriate .NET development workload.

  2. Podman Desktop.

  3. A supported .NET project.

  4. A working Podman environment.

For current Visual Studio Podman support, Microsoft documents Visual Studio 2026 with the relevant development workload and Podman Desktop as prerequisites.

You can verify that Podman is available from a terminal:

podman --version

You can also check whether Podman can run a container:

podman run --rm hello-world

If this command cannot start a container, fix the Podman environment before troubleshooting Visual Studio.

Adding Container Support to a .NET Project

For a supported ASP.NET Core project, Visual Studio can add container support directly from the project.

In Solution Explorer, right-click the project and select the container support option.

Depending on the project and configuration, Visual Studio can use either a Dockerfile-based container build or the .NET SDK's built-in container support.

For Dockerfile-based projects, Visual Studio adds files such as:

Dockerfile
.dockerignore

and configures the project for Container Tools.

The resulting Dockerfile can still be used with Podman because Podman supports the container image and Dockerfile workflow.

For example, a simplified .NET Dockerfile might look like:

FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
WORKDIR /app
EXPOSE 8080

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src

COPY ["MyApi/MyApi.csproj", "MyApi/"]
RUN dotnet restore "MyApi/MyApi.csproj"

COPY . .
WORKDIR "/src/MyApi"

RUN dotnet build "MyApi.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "MyApi.csproj" -c Release -o /app/publish /p:UseAppHost=false

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .

ENTRYPOINT ["dotnet", "MyApi.dll"]

The exact target framework and base image should match the project you are building.

Selecting Podman as the Container Runtime

Visual Studio can automatically detect the active container runtime.

The default Container Runtime setting is Auto, which allows Visual Studio to detect Docker or Podman.

If you want to explicitly select Podman, open:

Tools
  → Options
    → Container Tools
      → Container Runtime

Then select Podman.

Microsoft documents both automatic runtime detection and manual runtime selection.

This is useful when both Docker and Podman are installed on the same development machine and you want to make the runtime choice explicit.

Starting the .NET Application in Podman

Once Podman is running and the project has container support, select the container launch profile in Visual Studio.

Visual Studio then handles the container development workflow.

Conceptually:

Build Project
     |
     v
Build Container Image
     |
     v
Start Podman Container
     |
     v
Start .NET Application
     |
     v
Attach Visual Studio Debugger

The application is now running inside the container rather than directly on the host.

This difference matters when troubleshooting environment-specific behavior.

For example, a file path that works on Windows may behave differently inside a Linux container.

Debugging With Breakpoints

The biggest advantage for a .NET developer is that container execution does not mean giving up the normal debugger.

Set a breakpoint in the application code:

app.MapGet("/orders/{id}", async (int id, OrderService service) =>
{
    var order = await service.GetOrderAsync(id);

    return order is null
        ? Results.NotFound()
        : Results.Ok(order);
});

Start the application using the container profile.

Then call the endpoint.

When execution reaches the breakpoint, Visual Studio can pause the application and let you inspect the current state.

You can inspect:

  • Local variables

  • Parameters

  • Call stack

  • Exceptions

  • Threads

  • Application state

This is particularly useful when the application behaves differently inside the container than it does when running directly on the development machine.

Using the Containers Window

Visual Studio's Containers window provides a central place to inspect running containers.

You can open it from:

View
  → Other Windows
    → Containers

The window provides information such as:

  • Environment variables

  • Labels

  • Port mappings

  • Volumes

  • Files

  • Logs

  • Container details

It can also provide access to debugging and terminal-related operations.

For example, if your application starts but you cannot access the HTTP endpoint, check the Ports information before changing application code.

The problem may simply be that the host and container ports are not mapped as expected.

Understanding Container Ports

Suppose your ASP.NET Core application listens on:

http://+:8080

The container may expose port 8080, while Visual Studio maps it to a different port on the host.

Conceptually:

Host
localhost:5001
      |
      v
Podman
      |
      v
Container
8080
      |
      v
ASP.NET Core

The host port and container port do not have to be identical.

Container launch settings can define values such as HTTP and HTTPS ports and environment variables. Visual Studio's container launch configuration is typically stored in launchSettings.json.

A simplified configuration can look like:

{
  "profiles": {
    "Container": {
      "commandName": "Container",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_HTTP_PORTS": "8080"
      },
      "publishAllPorts": true
    }
  }
}

The exact profile generated by Visual Studio can differ depending on the project and container build type.

Fast Mode and Debugging

Visual Studio uses optimizations during Debug builds to reduce the time required to work with containers.

With Fast Mode, Visual Studio can build the application on the local machine and use volume mounting so that the output is available inside the container. This avoids rebuilding the complete container image for every small code change.

The conceptual workflow is:

Developer Changes Code
        |
        v
Local Build
        |
        v
Volume Mount
        |
        v
Running Container
        |
        v
Debugger

This is important during day-to-day development because rebuilding an entire image for every edit would make the feedback cycle unnecessarily slow.

Fast Mode is primarily a development optimization. Your production container should still be built using the normal production-oriented container process.

Debugging a Container Directly

Visual Studio also supports attaching to a running Podman container.

The current Visual Studio experience can discover Podman containers through the Attach to Process workflow.

The process is:

Debug
  → Attach to Process
  → Connection Type: Podman
  → Find

Visual Studio can then display the available Podman containers and let you attach to a running .NET process. Microsoft documents Podman container discovery through Attach to Process, including .NET and C++ container debugging.

This is particularly useful when the container was started outside the normal Visual Studio launch workflow.

For example:

podman run -d -p 8080:8080 my-api:latest

You can start the container using the CLI and then use Visual Studio to attach to the running process.

Debugging Environment-Specific Problems

One of the strongest reasons to debug inside a container is reproducing problems that do not appear when the application runs directly on the host.

Common examples include:

  • Linux file-system behavior

  • Missing environment variables

  • Incorrect port configuration

  • Missing native libraries

  • Different timezone configuration

  • Case-sensitive file paths

  • Container networking problems

  • Missing runtime dependencies

For example, code such as:

var path = "Config/appsettings.json";

if (!File.Exists(path))
{
    throw new FileNotFoundException(path);
}

may work on one operating system and fail in another if the actual file name differs in casing.

Running the application in the same type of environment used by the deployment target can make these problems easier to reproduce.

Multi-Container Applications With Podman Compose

Real applications rarely contain only one service.

A typical development environment may contain:

ASP.NET Core API
      |
      +---- PostgreSQL
      |
      +---- Redis
      |
      +---- Message Broker

Visual Studio supports Podman Compose for multi-container scenarios.

A simplified Compose configuration could look like:

services:
  api:
    build:
      context: .
    ports:
      - "8080:8080"
    depends_on:
      - postgres

  postgres:
    image: postgres
    environment:
      POSTGRES_DB: orders
      POSTGRES_USER: app
      POSTGRES_PASSWORD: development-password

For actual projects, development secrets should not be committed to source control. Use appropriate local secret management or environment-specific configuration.

Common Podman Debugging Problems

Visual Studio Does Not Detect Podman

First verify that Podman is running.

Then check the Container Runtime setting:

Tools
  → Options
    → Container Tools
      → Container Runtime

Try selecting Podman explicitly instead of Auto.

The Container Starts but the Browser Cannot Connect

Check the port mapping.

Run:

podman ps

Look at the published ports.

Then compare them with the application's configured listening port.

Breakpoints Are Not Hit

Check that:

  1. The application is running in a Debug configuration.

  2. The debugger is attached to the correct process.

  3. The deployed code matches the source being debugged.

  4. The required runtime and debugging configuration are present.

For Dockerfile-based Fast Mode scenarios, Visual Studio's debugging configuration may require a suitable runtime layer. Microsoft documents a dedicated debug stage when the debugger requires the .NET runtime inside the image.

HTTPS Does Not Work

Check the ASP.NET Core development certificate and container HTTPS configuration.

Visual Studio's Container Tools settings include an option to prompt for trusting the ASP.NET Core SSL certificate.

Do not disable certificate validation as a permanent workaround.

Best Practices for Podman Development

Keep Development and Production Images Separate

Do not assume the optimized debugging container should be your production image.

Development containers may contain debugging support that is unnecessary in production.

Keep Secrets Out of Dockerfiles

Avoid:

ENV DATABASE_PASSWORD=my-password

Use secure configuration mechanisms instead.

Use Multi-Stage Builds

Multi-stage builds keep build dependencies separate from the final runtime image.

Make Ports Explicit

Document which application ports are exposed and which host ports are used during development.

Inspect the Container Before Changing Code

When something fails, check:

  • Logs

  • Environment variables

  • Ports

  • Files

  • Volumes

The Containers window makes these checks easier without switching constantly between terminal commands and the IDE.

Use Container Debugging for Environment Problems

If the application works locally but fails in its container, reproduce and debug it inside the container before assuming the problem is in the application logic.

Advantages of Podman Containers in Visual Studio

  • Integrated .NET debugging experience.

  • Support for breakpoints inside containerized applications.

  • Podman can be selected as the Visual Studio container runtime.

  • Container inspection is available through the IDE.

  • Supports single-container development.

  • Supports Podman Compose for multi-container applications.

  • Developers can attach to running Podman containers.

  • Reduces the need to switch constantly between the IDE and command line.

Disadvantages and Limitations

  • Podman must be installed and running correctly.

  • Container networking adds another layer to troubleshoot.

  • Debugging configuration can become complicated for customized images.

  • Container behavior can differ from direct host execution.

  • Multi-container applications require additional configuration.

  • Development optimizations such as Fast Mode should not be confused with the production container build process.

When Should You Use Podman With Visual Studio?

Podman is a practical choice when your development environment already uses Podman or when your team wants a container runtime other than Docker.

It is particularly useful when you want:

  • A local containerized .NET development environment.

  • Integrated debugging.

  • Container inspection from Visual Studio.

  • Podman-based multi-service development.

  • The ability to switch between container runtime choices without redesigning the application.

If your team already has a standardized Docker-based workflow, there may be little reason to change the runtime simply for the sake of changing it. The important consideration is whether Podman fits the team's development and operational requirements.

Summary

Podman support in Visual Studio brings container-based .NET development closer to the normal IDE workflow.

Developers can run .NET applications inside Podman containers, inspect the running environment, work with ports and logs, set breakpoints, and attach the Visual Studio debugger to running processes. Visual Studio also supports Podman Compose for applications that contain multiple services.

The biggest practical benefit is that developers do not have to choose between containerized execution and a familiar debugging experience.

For everyday development, the recommended workflow is straightforward: configure Podman, add container support to the project, start the application through Visual Studio, inspect the container when necessary, and debug the application using the normal Visual Studio tools.

The important distinction is between development convenience and production configuration. Fast Mode and debugging-specific settings are designed to shorten the development feedback loop. Production images should still be built, tested, secured, and deployed using the team's normal container practices.