JD.MSBuild.Containers 0.1.8

JD.MSBuild.Containers

MSBuild tasks, targets, and props to integrate OCI containers with your .NET projects

Automate Docker containerization during dotnet build. Zero manual steps, full CI/CD support, reproducible container builds with granular control over every step of the process.

📚 Documentation

View Complete Documentation

• Introduction - Project overview and architecture
• Getting Started - Installation and quick start guide
• Tutorials - Step-by-step walkthroughs
• API Reference - Complete property and task reference
• Samples - Working example projects

Quick Start

Installation

dotnet add package JD.MSBuild.Containers

Basic Usage - Generate Dockerfile Only

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    
    
    <DockerEnabled>true</DockerEnabled>
    
    
    <DockerGenerateDockerfile>true</DockerGenerateDockerfile>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="JD.MSBuild.Containers" Version="*" />
  </ItemGroup>
</Project>

Run dotnet build and a Dockerfile will be generated in your project directory.

Full Automation - Generate and Build

<PropertyGroup>
  <DockerEnabled>true</DockerEnabled>
  <DockerGenerateDockerfile>true</DockerGenerateDockerfile>
  <DockerBuildImage>true</DockerBuildImage>
  <DockerBuildOnPublish>true</DockerBuildOnPublish>
</PropertyGroup>

Run dotnet publish to generate the Dockerfile and build the Docker image.

Build-Only Mode - Use Existing Dockerfile

<PropertyGroup>
  <DockerEnabled>true</DockerEnabled>
  
  
  <DockerGenerateDockerfile>false</DockerGenerateDockerfile>
  
  
  <DockerBuildImage>true</DockerBuildImage>
  <DockerBuildOnPublish>true</DockerBuildOnPublish>
  
  
  <DockerfileSource>$(MSBuildProjectDirectory)\custom.Dockerfile</DockerfileSource>
</PropertyGroup>

Key Features

Granular Control

JD.MSBuild.Containers is designed as a configurable OCI MSBuild shim integration. Every feature can be independently enabled or disabled:

• ✅ Generate Dockerfile - Auto-generate optimized multi-stage Dockerfiles
• ✅ Build Images - Execute docker build during MSBuild
• ✅ Run Containers - Start containers after build (opt-in)
• ✅ Push to Registry - Automatically push to container registries
• ✅ Pre/Post Scripts - Execute custom scripts at any stage
• ✅ Incremental Builds - Skip regeneration when nothing changes
• ✅ MSBuild Hooks - Integrate with Build, Clean, Publish, Run targets

Configuration Modes

Configuration Reference

Core Enablement

Hook Integration

Script Execution

Image Configuration

Build Options

File Paths

Advanced Options

Usage Examples

Example 1: Generate-Only Mode (Default)

Perfect for committing Dockerfiles to version control and reviewing before build:

<PropertyGroup>
  <DockerEnabled>true</DockerEnabled>
  
  
</PropertyGroup>

dotnet build
# Dockerfile generated at ./Dockerfile
# No Docker image built

Example 2: Build-Only Mode

Use your own hand-crafted Dockerfile:

<PropertyGroup>
  <DockerEnabled>true</DockerEnabled>
  <DockerGenerateDockerfile>false</DockerGenerateDockerfile>
  <DockerBuildImage>true</DockerBuildImage>
  <DockerBuildOnPublish>true</DockerBuildOnPublish>
  
  
  <DockerfileSource>$(MSBuildProjectDirectory)\deploy\Dockerfile</DockerfileSource>
</PropertyGroup>

dotnet publish
# Uses existing Dockerfile at ./deploy/Dockerfile
# Builds Docker image

Example 3: Full Automation

Generate and build automatically:

<PropertyGroup>
  <DockerEnabled>true</DockerEnabled>
  <DockerGenerateDockerfile>true</DockerGenerateDockerfile>
  <DockerBuildImage>true</DockerBuildImage>
  <DockerBuildOnPublish>true</DockerBuildOnPublish>
  
  <DockerImageName>myapp</DockerImageName>
  <DockerImageTag>$(Version)</DockerImageTag>
  <DockerRegistry>myregistry.azurecr.io</DockerRegistry>
</PropertyGroup>

dotnet publish
# Generates Dockerfile
# Builds image: myregistry.azurecr.io/myapp:1.0.0

Example 4: CI/CD with Scripts and Push

<PropertyGroup>
  <DockerEnabled>true</DockerEnabled>
  <DockerGenerateDockerfile>true</DockerGenerateDockerfile>
  <DockerBuildImage>true</DockerBuildImage>
  <DockerBuildOnPublish>true</DockerBuildOnPublish>
  <DockerPushImage>true</DockerPushImage>
  <DockerPushOnPublish>true</DockerPushOnPublish>
  
  
  <DockerPreBuildScript>$(MSBuildProjectDirectory)\scripts\pre-build.sh</DockerPreBuildScript>
  <DockerPostPublishScript>$(MSBuildProjectDirectory)\scripts\deploy.ps1</DockerPostPublishScript>
  
  <DockerRegistry>myregistry.azurecr.io</DockerRegistry>
  <DockerImageName>myapp</DockerImageName>
  <DockerImageTag>$(GitVersion_SemVer)</DockerImageTag>
</PropertyGroup>

Example 5: Development Workflow with Auto-Run

<PropertyGroup>
  <DockerEnabled>true</DockerEnabled>
  <DockerGenerateDockerfile>true</DockerGenerateDockerfile>
  <DockerBuildImage>true</DockerBuildImage>
  <DockerBuildOnBuild>true</DockerBuildOnBuild>
  <DockerRunContainer>true</DockerRunContainer>
  <DockerRunOnBuild>true</DockerRunOnBuild>
  
  
  <DockerPortMappings>8080:8080</DockerPortMappings>
  <DockerEnvironmentVariables>ASPNETCORE_ENVIRONMENT=Development</DockerEnvironmentVariables>
  <DockerVolumeMappings>$(MSBuildProjectDirectory)/data:/app/data</DockerVolumeMappings>
</PropertyGroup>

dotnet build
# Generates Dockerfile
# Builds image
# Starts container with port mappings

Example 6: Selective Script Execution

Execute only specific scripts:

<PropertyGroup>
  <DockerEnabled>true</DockerEnabled>
  <DockerGenerateDockerfile>true</DockerGenerateDockerfile>
  
  
  <DockerPreBuildScript>$(MSBuildProjectDirectory)\scripts\setup.sh</DockerPreBuildScript>
  <DockerPostBuildScript>$(MSBuildProjectDirectory)\scripts\cleanup.sh</DockerPostBuildScript>
  
  
  <DockerExecutePreBuildScript>true</DockerExecutePreBuildScript>
  <DockerExecutePostBuildScript>false</DockerExecutePostBuildScript>
</PropertyGroup>

Lifecycle Hooks

JD.MSBuild.Containers provides extensibility points at every stage:

Build:
  ├─ BeforeDockerGeneration
  ├─ DockerResolveInputs
  ├─ DockerComputeFingerprint
  ├─ DockerGenerateDockerfile
  ├─ AfterDockerGeneration
  ├─ DockerExecutePreBuildScript
  ├─ BeforeDockerBuild
  ├─ DockerBuild
  ├─ AfterDockerBuild
  ├─ DockerExecutePostBuildScript
  ├─ BeforeDockerRun
  ├─ DockerRun
  └─ AfterDockerRun

Publish:
  ├─ DockerExecutePrePublishScript
  ├─ DockerPublish (generates + builds)
  ├─ DockerExecutePostPublishScript
  └─ DockerPushImage (if enabled)

Clean:
  └─ DockerClean (removes generated files)

You can define custom targets that depend on or extend these hooks:

<Target Name="MyCustomPreBuild" BeforeTargets="DockerBuild">
  <Message Text="Running custom logic before Docker build" Importance="high" />
</Target>

<Target Name="MyCustomPostBuild" AfterTargets="AfterDockerBuild">
  <Message Text="Running custom logic after Docker build" Importance="high" />
</Target>

Requirements

• .NET SDK 8.0+
• Docker (when building images)

Comparison with Alternatives

Code Coverage

This project maintains comprehensive code coverage with automated reporting:

• 📊 Coverage reports generated on every PR
• 📈 Historical tracking via Codecov
• 💬 PR comments with coverage summaries
• 📦 HTML reports available as CI artifacts

See CODE_COVERAGE.md for detailed configuration and usage.

Contributing

Contributions are welcome! Please open an issue first to discuss changes.

License

This project is licensed under the MIT License. See LICENSE for details.

Acknowledgments

• Architecture inspired by JD.Efcpt.Build
• Docker for container runtime
• Microsoft for .NET SDK and MSBuild