VS Container Tools: Retire & forward to same VS doc covering ASP.NET Core

[wadepickett]

Description

This article references VS 2017 and 2019 out of date content.

At the same time there is a Visual Studio doc that already maintains this information and the VS doc tream recommends retiring this one and forwarding to this one in the VS set which actually has an ASP.NET Core example as well:

https://learn.microsoft.com/en-us/visualstudio/containers/add-container-support?view=visualstudio

Consider retiring this article, forwarding to the VS doc site equivelent mentioned above, and keep the TOC link, but just forward tot he VS topic inline. We have some other examples of that in the TOC already.

If for some reason we have to change direction and update this article instead, then I have extensive intruction for that below in the disucssion, but it is not the first choice at first glance.

See internal teams discussion with GHodgenson.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/docker/visual-studio-tools-for-docker?view=aspnetcore-10.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/host-and-deploy/docker/visual-studio-tools-for-docker.md

Document ID

5847cdf8-1823-7740-6e43-030902b26ad8

Platform Id

13fff26d-5016-fd79-2ed4-202bff28861a

Article author

@spboyer

Metadata

• ID: d772b44a-b5f3-5a10-4ea3-4463bdcf90bb
• PlatformId: 13fff26d-5016-fd79-2ed4-202bff28861a
• Service: aspnet-core
• Sub-service: hosting-deployment

Related Issues

[wadepickett]

🤖 AI Triage Summary

📌 Note to community: This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is not a resolution — it's a starting point for investigation.

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-01-14
Issue: 36625
Model: GitHub Copilot

---

Issue Analysis: Visual Studio Container Tools Documentation - Update for Visual Studio 2022

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

The article "Visual Studio Container Tools with ASP.NET Core" references outdated Visual Studio versions (VS 2017 and VS 2019) and related tooling. Beyond simple text updates, the article also lacks current best practices and modern workflows that ASP.NET Core developers should follow in 2024-2026, including:

• Missing . NET SDK container publishing (no-Dockerfile workflow available since .NET 7)
• Missing security best practices (running as non-root user, now default in .NET 8+)
• Outdated Dockerfile patterns (not multi-stage optimized for modern .NET)
• Missing Visual Studio 2022 features (Containers window, hot reload improvements)
• Outdated sample code targeting .NET Core 2.0/2.1 with obsolete APIs

📁 Potentially Affected Files

These files have been identified as possibly related to this issue and may need review.

File	Path	Lines	Section
Main article	aspnetcore/host-and-deploy/docker/visual-studio-tools-for-docker.md	1-241	Entire article
Sample Dockerfile	samples/2.1/HelloDockerTools/Dockerfile.original	1-21	Multi-stage Dockerfile
Sample Dockerfile (SF)	[samples/2.1/HelloDockerTools/Dockerfile](https://github.com/dotnet/AspNetCore. Docs/blob/6086e2cb219a6bbf30111b5cb2ca65b7fe9873a4/aspnetcore/host-and-deploy/docker/visual-studio-tools-for-docker/samples/2.1/HelloDockerTools/Dockerfile)	1-7	Service Fabric Dockerfile
Sample Startup.cs	samples/2.0/HelloDockerTools/Startup.cs	1-45	Obsolete Startup pattern
Docker Compose	[samples/2.1/docker-compose.override.yml](https://github.com/dotnet/AspNetCore.Docs/blob/6086e2cb219a6bbf30111b5cb2ca65b7fe9873a4/aspnetcore/host-and-deploy/docker/visual-studio-tools-for-docker/samples/2.1/docker-compose. override.yml)	1-14	Docker Compose config

---

📝 Preliminary Change Assessment

The following are initial observations for the documentation team to evaluate—not final decisions.

---

🆕 WORKFLOW/BEST PRACTICE GAPS (Not Just Outdated Text)

1. Missing: . NET SDK Container Publishing (No-Dockerfile Workflow)

Location: Should be added as a new section after "Add a project to a Docker container"
Type: New content — Modern alternative workflow

Issue: The article only covers Dockerfile-based containerization. Since .NET 7, developers can publish directly to a container image without writing a Dockerfile using the . NET SDK's built-in container support. This is now the recommended starting point for simple applications.

Suggested direction — Add new section:

## SDK Container Publishing (No Dockerfile Required)

For .NET 8 and later projects, Visual Studio 2022 offers a streamlined container publishing option that doesn't require a Dockerfile.  This approach uses the .NET SDK's built-in container support. 

### Enable SDK Container Support

When adding Docker support to a . NET 8+ project, Visual Studio presents two options: 
- **Dockerfile** - Full control over the container build process
- **.NET SDK** - Simplified approach using MSBuild properties

To publish using the SDK approach:

1. Right-click the project and select **Publish**
2. Choose **Docker Container Registry** as the target
3. Select **Container** as the publish method

Or from the command line: 

dotnet publish --os linux --arch x64 /t:PublishContainer

> [!TIP]
> Use SDK container publishing for simple applications.  Switch to a Dockerfile when you need custom base images, additional OS packages, or complex multi-stage builds.

---

2. Missing: Security Best Practice — Running as Non-Root User

Location: Should be added in "Dockerfile overview" section (after line 57)
Type: New content — Security best practice

Issue: The current article and sample Dockerfiles run containers as root, which is a security anti-pattern. Starting with .NET 8, official Microsoft container images include a non-root app user by default. The article should guide developers to use this.

Current Dockerfile sample (lines 17-20 of Dockerfile.original):

FROM base AS final
WORKDIR /app
COPY --from=publish /app . 
ENTRYPOINT ["dotnet", "HelloDockerTools. dll"]

Suggested direction — Updated Dockerfile with non-root user:

FROM base AS final
WORKDIR /app
COPY --from=publish /app .
USER app
ENTRYPOINT ["dotnet", "HelloDockerTools.dll"]

Suggested direction — Add security note:

> [!IMPORTANT]
> **Security Best Practice:** Starting with .NET 8, official Microsoft container images include a non-root user named `app`. Always add `USER app` before your `ENTRYPOINT` to run your container with least privileges.  Running as root inside containers increases the attack surface if your application is compromised.

---

3. Missing: Visual Studio 2022 Containers Window

Location: Should be added in the "Debug" section (around line 134)
Type: New content — Modern tooling feature

Issue: Visual Studio 2022 includes a powerful Containers window that lets developers view running containers, inspect images, browse the filesystem, view logs, and attach debuggers. This feature significantly improves the container development experience but is not mentioned.

Suggested direction — Add new subsection:

### Containers Window

Visual Studio 2022 provides a **Containers** window for managing your Docker environment directly from the IDE. 

To open the Containers window, select **View** > **Other Windows** > **Containers**. 

The Containers window allows you to:
- View all running containers and their status
- Inspect container images
- Browse the container filesystem
- View environment variables
- Stream container logs in real-time
- Open a terminal inside a running container
- Attach the debugger to a running container

> [!TIP]
> Use the Containers window to troubleshoot startup issues by viewing logs without leaving Visual Studio.

---

4. Outdated: Sample Code Uses Obsolete Startup.cs Pattern

File: [samples/2.0/HelloDockerTools/Startup. cs](https://github.com/dotnet/AspNetCore. Docs/blob/6086e2cb219a6bbf30111b5cb2ca65b7fe9873a4/aspnetcore/host-and-deploy/docker/visual-studio-tools-for-docker/samples/2.0/HelloDockerTools/Startup.cs)
Type: Complete replacement — Uses deprecated APIs

Current code uses:

• IHostingEnvironment (obsolete, replaced by IWebHostEnvironment)
• services.AddMvc() (replaced by minimal APIs or AddControllersWithViews())
• app.UseBrowserLink() (removed in .NET Core 3.0+)
• Separate Startup.cs class (modern . NET uses top-level Program.cs)

Current content:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseBrowserLink();
        app.UseDeveloperExceptionPage();
    }
    // ...
    app.UseMvc();
}

Suggested direction — Modern . NET 8+ Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();

app.Run();

---

5. Outdated: Docker Compose File Uses Deprecated Version Syntax

File: samples/2.1/docker-compose.override.yml
Type: Update needed — Deprecated syntax

Current content (line 1):

version: '3.4'

Issue: The version key in Docker Compose files is deprecated as of Docker Compose v2. Modern Compose files should omit this property entirely.

Current content also mounts to /root/ paths (lines 13-14):

volumes:
  - ${APPDATA}/ASP.NET/Https:/root/.aspnet/https:ro
  - ${APPDATA}/Microsoft/UserSecrets:/root/.microsoft/usersecrets:ro

Issue: Mounting to /root/ paths assumes the container runs as root. With non-root users, these should reference the app user's home directory.

Suggested direction:

services:
  hellodockertools:
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ASPNETCORE_URLS=https://+:443;http://+:80
      - ASPNETCORE_HTTPS_PORTS=44364
    ports:
      - "5000:80"
      - "5001:443"
    volumes:
      - ${APPDATA}/ASP.NET/Https:/home/app/.aspnet/https:ro
      - ${APPDATA}/Microsoft/UserSecrets:/home/app/.microsoft/usersecrets:ro

---

6. Missing: HEALTHCHECK Instruction in Dockerfile

Location: Sample Dockerfiles
Type: Best practice addition

Issue: Production containers should include a HEALTHCHECK instruction to allow orchestrators (Docker Compose, Kubernetes) to monitor container health. The current samples don't include this.

Suggested direction — Add to Dockerfile:

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl --fail http://localhost:8080/health || exit 1

Or for ASP.NET Core apps without curl:

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1

---

7. Missing: . dockerignore Best Practices

File: samples/2.0/.dockerignore
Type: Enhancement

**Current content is minimal. ** Modern .dockerignore files should also exclude:

• **/*. md (documentation)
• **/[Tt]ests/** (test projects)
• **/. git/**
• **/node_modules/** (if using npm)
• **/*.user
• **/*.suo

---

📅 TEXT/VERSION UPDATES (As Previously Identified)

8. Prerequisites Section — Outdated VS and Docker References

File: visual-studio-tools-for-docker.md
Location: Lines 18-27

Current content (lines 20-21):

* [Docker for Windows](https://docs.docker.com/desktop/windows/install/)
* [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link&utm_content=download+vs2019) with the **.NET Core cross-platform development** workload

Suggested direction:

* [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/) or [Podman](https://podman.io/) (preview support)
* [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/) version 17.0 or later with the **ASP.NET and web development** workload

---

9. Docker Image Names — Outdated Repository Names

File: [visual-studio-tools-for-docker. md](https://github.com/dotnet/AspNetCore. Docs/blob/6086e2cb219a6bbf30111b5cb2ca65b7fe9873a4/aspnetcore/host-and-deploy/docker/visual-studio-tools-for-docker.md#L140-L152)
Location: Lines 140-152

Current content:

* The *2.1-aspnetcore-runtime* tag of the *microsoft/dotnet* runtime image... 
microsoft/dotnet  2.1-aspnetcore-runtime  fcc3887985bb  6 days ago      255MB

Suggested direction:

* The *9.0* tag of the *mcr.microsoft.com/dotnet/aspnet* runtime image...
mcr.microsoft. com/dotnet/aspnet  9.0     abc123def456  2 days ago      220MB
mcr.microsoft.com/dotnet/sdk     9.0     def456abc789  2 days ago      850MB

---

10. Sample Dockerfile — Uses End-of-Life . NET Core 2.1 Images

File: Dockerfile.original
Location: Lines 1, 6

Current content:

FROM mcr.microsoft.com/dotnet/core/aspnet:2.1 AS base
... 
FROM mcr.microsoft.com/dotnet/core/sdk: 2.1 AS build

Issue: . NET Core 2.1 reached end-of-life in August 2021. The dotnet/core/ repository is deprecated.

Suggested direction:

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

FROM mcr.microsoft. com/dotnet/sdk:9.0 AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY ["HelloDockerTools.csproj", ". "]
RUN dotnet restore "HelloDockerTools.csproj"
COPY . .
RUN dotnet build "HelloDockerTools.csproj" -c $BUILD_CONFIGURATION -o /app/build

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

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
USER app
ENTRYPOINT ["dotnet", "HelloDockerTools. dll"]

---

11. Remove Unsupported Version Content

Location: Lines 59-76, 156-172, 213-225
Type: Remove outdated moniker content

The article includes moniker-gated content for <= aspnetcore-2.0 and ASP.NET Core 2.0/2.1. These versions are no longer supported and should be removed to reduce confusion.

---

🎯 Suggested Action Plan

For documentation team review

Phase 1: Critical Updates (Modern Best Practices)

1. Add . NET SDK Container Publishing section:

   • Location: After "Add a project to a Docker container"
   • Explain the no-Dockerfile workflow for .NET 8+
   • Provide guidance on when to use Dockerfile vs SDK publishing

2. Add Security Best Practices section:

   • Add non-root user guidance with USER app instruction
   • Include [!IMPORTANT] block about security implications
   • Update all sample Dockerfiles to include USER app

3. Add Containers Window documentation:

   • Location: In "Debug" section
   • Cover key features: logs, filesystem browsing, terminal access

4. Add HEALTHCHECK guidance:

   • Include example HEALTHCHECK instruction
   • Explain why this matters for production

Phase 2: Sample Code Updates

5. Replace all sample projects:

   • Create new samples targeting .NET 9 (or latest LTS)
   • Use modern Program.cs pattern (no Startup.cs)
   • Use current MCR image names
   • Include non-root user configuration
   • Include proper . dockerignore

6. Update Docker Compose samples:

   • Remove deprecated version key
   • Update volume mounts for non-root user paths
   • Use modern port conventions (8080/8081)

Phase 3: Text/Version Updates

7. Update Prerequisites:

   • Change to VS 2022
   • Update Docker Desktop link
   • Mention Podman preview support

8. Update all VS version references:

   • Remove VS 2017 version-specific references
   • Update VS 2019 to VS 2022

9. Update image names throughout:

   • Change microsoft/dotnet to mcr.microsoft.com/dotnet/aspnet and mcr.microsoft.com/dotnet/sdk

10. Remove unsupported version content:

    • Remove moniker ranges for <= aspnetcore-2.0
    • Remove ASP.NET Core 2.x-specific content

---

⚠️ Review Considerations

• Breaking changes: The shift to non-root containers may affect existing workflows that assume root access
• VS 2022 minimum version: Verify which VS 2022 version introduced each feature mentioned
• Podman support: Currently preview — verify scope and limitations before documenting
• Consider cross-references to:
  • Container development with Visual Studio
  • Secure . NET cloud apps with rootless Linux Containers
  • Publish .NET apps as container images
• Screenshots: All screenshots showing VS 2017/2019 UI or old Docker Desktop UI need replacement

---

🔗 References

• Published article: https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/docker/visual-studio-tools-for-docker
• Source file: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/host-and-deploy/docker/visual-studio-tools-for-docker.md
• Visual Studio Container Tools docs: https://learn.microsoft.com/en-us/visualstudio/containers/overview
• . NET SDK Container Publishing: https://learn.microsoft.com/en-us/dotnet/core/docker/publish-as-container
• Rootless . NET Containers: https://devblogs.microsoft.com/dotnet/securing-containers-with-rootless/
• Docker Security Best Practices: https://www.docker.com/blog/9-tips-for-containerizing-your-net-application/
• Docker Desktop documentation: https://docs.docker.com/desktop/

[ghogen]

That is a great list of things that could be updated. Visual Studio 2026 was released.

BTW: The branding has us just calling it "Visual Studio" without the year, except in contexts where you need to distinguish that version.