Skip to main content

​
Overview

The Intent.AspNetCore.Docker module installs Docker support into your ASP.NET Core application, similar to how Visual Studio would if you select “Enable Docker support” on solution creation. This module generates production-ready Dockerfiles with multi-stage builds optimized for .NET applications, along with .dockerignore files and debugging configurations.

​
What Gets Generated

​
Dockerfile

A multi-stage Dockerfile optimized for ASP.NET Core applications:
YourApi/Dockerfile
# See https://aka.ms/customizecontainer to learn how to customize your debug container
# and how Visual Studio uses this Dockerfile to build your images for faster debugging.

# This stage is used when running from VS in fast mode (Default for Debug configuration)
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
USER $APP_UID
WORKDIR /app
EXPOSE 8080
EXPOSE 8081

# This stage is used to build the service project
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY ["YourApi/YourApi.csproj", "YourApi/"]
RUN dotnet restore "./YourApi/YourApi.csproj"
COPY . .
WORKDIR "/src/YourApi"
RUN dotnet build "./YourApi.csproj" -c $BUILD_CONFIGURATION -o /app/build

# This stage is used to publish the service project to be copied to the final stage
FROM build AS publish
ARG BUILD_CONFIGURATION=Release
RUN dotnet publish "./YourApi.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false

# This stage is used in production or when running from VS in regular mode
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "YourApi.dll"]

​
.dockerignore

A .dockerignore file to exclude unnecessary files from the Docker build context:
.dockerignore
**/.classpath
**/.dockerignore
**/.env
**/.git
**/.gitignore
**/.project
**/.settings
**/.toolstarget
**/.vs
**/.vscode
**/*.*proj.user
**/*.dbmdl
**/*.jfm
**/azds.yaml
**/bin
**/charts
**/docker-compose*
**/Dockerfile*
**/node_modules
**/npm-debug.log
**/obj
**/secrets.dev.yaml
**/values.dev.yaml
LICENSE
README.md

​
Visual Studio Integration

When using Visual Studio, the module configures:
  • Debug targets for Docker
  • Fast mode debugging support
  • Docker Compose integration (if applicable)

​
Installation

​
Prerequisites

  • An ASP.NET Core application in Intent Architect
  • Docker Desktop installed on your development machine

​
Installation Steps

1

Install Docker Desktop

Download and install Docker Desktop for your operating system.
2

Install the module

In Intent Architect, right-click on your application and select Manage Modules. Search for Intent.AspNetCore.Docker and install it.
3

Run the Software Factory

Execute the Software Factory to generate the Dockerfile and related files.
4

Build the Docker image

Use docker build or Visual Studio’s Docker debugging to build your containerized application.

​
Usage

​
Running in Visual Studio

The easiest way to run or debug your application under Docker in Visual Studio:
  1. Open your solution in Visual Studio
  2. Select Docker from the Debug Target dropdown
  3. Press F5 to start debugging
The Debug Target drop down in Visual Studio Visual Studio will:
  • Build your Docker image
  • Start a container
  • Attach the debugger
  • Open your browser to the application URL

​
Building with Docker CLI

From a terminal in the folder of the project with the entry point of your application: 
docker build -f ./Dockerfile -t my-api:latest ..
  • -f specifies the Dockerfile to use
  • -t specifies the docker image name and tag
  • .. at the end specifies the build context (parent directory)
The build context should be the solution root directory (one level up from the project folder) to ensure all project references can be resolved.

​
Running with Docker CLI

docker run -p 8080:8080 my-api:latest
  • -p maps host port 8080 to container port 8080
  • Use -P to publish all exposed ports to random ports
See Docker’s documentation for more options.

​
Configuration

​
Environment Variables

ASP.NET Core applications can be configured using appsettings.json and environment variables.

​
Hierarchy

Configuration sources are applied in this order (later sources override earlier ones):
  1. appsettings.json - Base configuration
  2. appsettings..json - Environment-specific overrides
  3. Environment Variables - Runtime configuration
  4. Command-line arguments - Highest priority
For more details, see ASP.NET Core Configuration.

​
Setting Environment Variables

Pass via command-line arguments: 
docker run -it --name "my-api" \
  -e ConnectionStrings__DefaultConnection="Server=myserver;Database=mydb;User=sa;Password=Pass123" \
  my-api:latest
Use double underscores __ to represent nested configuration sections. For example, ConnectionStrings__DefaultConnection maps to ConnectionStrings:DefaultConnection in appsettings.json.
Pass via environment file: Create a .env file:
.env
ConnectionStrings__DefaultConnection=Server=myserver;Database=mydb;User=sa;Password=Pass123
Logging__LogLevel__Default=Information
ASPNETCORE_ENVIRONMENT=Production
Run with the environment file: 
docker run -it --name "my-api" --env-file ./.env my-api:latest

​
Example Configuration Override

appsettings.json: 
{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=MyApp;Trusted_Connection=True"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}
Override in Docker: 
docker run -e ConnectionStrings__DefaultConnection="Server=prod-sql;Database=MyApp;User=sa;Password=SecurePass" my-api
The environment variable will override the connection string from appsettings.json.

​
Docker Compose

For applications with multiple services (API, database, cache), consider using Docker Compose:
docker-compose.yml
version: '3.8'

services:
  api:
    build:
      context: .
      dockerfile: MyApi/Dockerfile
    ports:
      - "8080:8080"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
      - ConnectionStrings__DefaultConnection=Server=db;Database=MyApp;User=sa;Password=Pass123
    depends_on:
      - db

  db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=Pass123
    ports:
      - "1433:1433"
    volumes:
      - sqldata:/var/opt/mssql

volumes:
  sqldata:
Run with: 
docker-compose up

​
Best Practices

Multi-Stage Builds

The generated Dockerfile uses multi-stage builds to minimize final image size by excluding build tools.

Use .dockerignore

Keep your build context small by excluding unnecessary files like bin, obj, and .git.

Non-Root User

The container runs as a non-root user ($APP_UID) for improved security.

Environment-Specific Config

Use environment variables for sensitive data instead of hardcoding in appsettings.json.

​
Security Considerations

  • Never commit secrets to version control
  • Use environment variables for connection strings and API keys
  • Scan images for vulnerabilities regularly
  • Keep base images updated to receive security patches

​
Performance Optimization

# Layer caching: Copy project files first, then restore
COPY ["MyApi/MyApi.csproj", "MyApi/"]
RUN dotnet restore "./MyApi/MyApi.csproj"

# Then copy source code (changes more frequently)
COPY . .
This ensures that NuGet restore only runs when dependencies change, not on every code change.

​
Troubleshooting

​
Clear Visual Studio Docker Cache

There are scenarios where you need to clear out your local .vs folder:
  • When changing your development hosting option (from Docker to Local Kestrel or vice versa)
  • To regenerate the Docker certificate setup when running the dockerized solution
  • When experiencing connection issues during debugging
Steps:
  1. Close Visual Studio
  2. Delete the .vs folder in your solution directory
  3. Restart Visual Studio

​
Common Issues

Issue: Container can’t connect to host SQL Server Solution: Use host.docker.internal instead of localhost in connection strings: 
docker run -e ConnectionStrings__DefaultConnection="Server=host.docker.internal;Database=MyApp;..." my-api
Issue: Port already in use Solution: Change the host port mapping: 
docker run -p 8081:8080 my-api  # Map host port 8081 to container port 8080
Issue: File not found during build Solution: Ensure the build context is the solution root: 
cd /path/to/solution
docker build -f ./MyApi/Dockerfile -t my-api ..

​
Integration with Other Modules

Azure Pipelines

Build and push Docker images in CI/CD pipelines.

OpenTelemetry

Monitor containerized applications with distributed tracing.

Serilog

Structured logging works seamlessly in containers.

Health Checks

Container orchestrators use health checks for readiness probes.

​
Next Steps

Azure Pipelines

Automate Docker builds in CI/CD

Kubernetes

Deploy containers to Kubernetes

Monitoring

Add observability to containers

Build docs developers (and LLMs) love

Get started for freeTalk to us