https://github.com/jerrettdavis/jd.msbuild.containers
MSBuild tasks, targets, and props to integrate OCI containers with your .NET projects
https://github.com/jerrettdavis/jd.msbuild.containers
build build-automation c containers csharp docker msbuild
Last synced: about 1 month ago
JSON representation
MSBuild tasks, targets, and props to integrate OCI containers with your .NET projects
- Host: GitHub
- URL: https://github.com/jerrettdavis/jd.msbuild.containers
- Owner: JerrettDavis
- License: mit
- Created: 2026-01-15T22:44:37.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-06-16T02:35:26.000Z (about 1 month ago)
- Last Synced: 2026-06-16T03:11:29.311Z (about 1 month ago)
- Topics: build, build-automation, c, containers, csharp, docker, msbuild
- Language: C#
- Homepage: https://jerrettdavis.github.io/JD.MSBuild.Containers/
- Size: 1.19 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# JD.MSBuild.Containers
**MSBuild tasks, targets, and props to integrate OCI containers with your .NET projects**
[](https://www.nuget.org/packages/JD.MSBuild.Containers/)
[](LICENSE)
[](https://github.com/JerrettDavis/JD.MSBuild.Containers/actions/workflows/ci.yml)
[](https://github.com/JerrettDavis/JD.MSBuild.Containers/security/code-scanning)
[](https://codecov.io/gh/JerrettDavis/JD.MSBuild.Containers)
[](https://jerrettdavis.github.io/JD.MSBuild.Containers/)
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](https://jerrettdavis.github.io/JD.MSBuild.Containers/)**
- [Introduction](https://jerrettdavis.github.io/JD.MSBuild.Containers/articles/introduction.html) - Project overview and architecture
- [Getting Started](https://jerrettdavis.github.io/JD.MSBuild.Containers/articles/getting-started.html) - Installation and quick start guide
- [Tutorials](https://jerrettdavis.github.io/JD.MSBuild.Containers/tutorials/tutorial-basic.html) - Step-by-step walkthroughs
- [API Reference](https://jerrettdavis.github.io/JD.MSBuild.Containers/api/) - Complete property and task reference
- [Samples](https://jerrettdavis.github.io/JD.MSBuild.Containers/samples/sample-overview.html) - Working example projects
## Quick Start
### Installation
```bash
dotnet add package JD.MSBuild.Containers
```
### Basic Usage - Generate Dockerfile Only
```xml
net8.0
true
true
```
Run `dotnet build` and a Dockerfile will be generated in your project directory.
### Full Automation - Generate and Build
```xml
true
true
true
true
```
Run `dotnet publish` to generate the Dockerfile and build the Docker image.
### Build-Only Mode - Use Existing Dockerfile
```xml
true
false
true
true
$(MSBuildProjectDirectory)\custom.Dockerfile
```
## 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
| Mode | Generate | Build | Use Case |
|------|----------|-------|----------|
| **Generate-Only** | ✅ | ❌ | Review/commit Dockerfiles, manual builds |
| **Build-Only** | ❌ | ✅ | Use existing Dockerfiles, custom templates |
| **Full Automation** | ✅ | ✅ | Complete CI/CD, zero manual steps |
| **Custom Hooks** | ➖ | ➖ | Execute scripts only, manual everything else |
## Configuration Reference
### Core Enablement
| Property | Default | Description |
|----------|---------|-------------|
| `DockerEnabled` | `false` | Master switch for Docker integration |
| `DockerGenerateDockerfile` | `true` (when enabled) | Controls Dockerfile generation |
| `DockerBuildImage` | `false` | Controls Docker image building |
| `DockerRunContainer` | `false` | Controls container execution |
| `DockerPushImage` | `false` | Controls pushing to registry |
### Hook Integration
| Property | Default | Description |
|----------|---------|-------------|
| `DockerGenerateOnBuild` | `true` | Generate Dockerfile during Build |
| `DockerBuildOnBuild` | `false` | Build image during Build |
| `DockerBuildOnPublish` | `true` | Build image during Publish |
| `DockerRunOnBuild` | `false` | Run container after Build |
| `DockerPushOnPublish` | `true` | Push image after Publish |
### Script Execution
| Property | Default | Description |
|----------|---------|-------------|
| `DockerPreBuildScript` | - | Path to pre-build script |
| `DockerPostBuildScript` | - | Path to post-build script |
| `DockerPrePublishScript` | - | Path to pre-publish script |
| `DockerPostPublishScript` | - | Path to post-publish script |
| `DockerExecutePreBuildScript` | `true` (if script set) | Enable pre-build script |
| `DockerExecutePostBuildScript` | `true` (if script set) | Enable post-build script |
| `DockerExecutePrePublishScript` | `true` (if script set) | Enable pre-publish script |
| `DockerExecutePostPublishScript` | `true` (if script set) | Enable post-publish script |
### Image Configuration
| Property | Default | Description |
|----------|---------|-------------|
| `DockerImageName` | `$(AssemblyName).ToLower()` | Docker image name |
| `DockerImageTag` | `latest` | Docker image tag |
| `DockerRegistry` | - | Container registry URL |
| `DockerBaseImageRuntime` | `mcr.microsoft.com/dotnet/aspnet` | Runtime base image |
| `DockerBaseImageSdk` | `mcr.microsoft.com/dotnet/sdk` | SDK base image |
| `DockerBaseImageVersion` | Auto-detected | Base image version |
### Build Options
| Property | Default | Description |
|----------|---------|-------------|
| `DockerBuildContext` | `$(MSBuildProjectDirectory)` | Docker build context |
| `DockerBuildArgs` | - | Additional build arguments |
| `DockerBuildPlatform` | - | Target platform (e.g., `linux/amd64`) |
| `DockerBuildTarget` | - | Target stage in multi-stage builds |
| `DockerUseMultiStage` | `true` | Use multi-stage Dockerfiles |
| `DockerOptimizeLayers` | `true` | Optimize Docker layers |
### File Paths
| Property | Default | Description |
|----------|---------|-------------|
| `DockerfileOutput` | `$(MSBuildProjectDirectory)\Dockerfile` | Generated Dockerfile path |
| `DockerfileSource` | `$(MSBuildProjectDirectory)\Dockerfile` | Existing Dockerfile path |
| `DockerOutput` | `$(BaseIntermediateOutputPath)docker\` | Build output directory |
| `DockerTemplateFile` | - | Custom Dockerfile template |
### Advanced Options
| Property | Default | Description |
|----------|---------|-------------|
| `DockerUseFingerprinting` | `true` | Enable incremental builds |
| `DockerLogVerbosity` | `minimal` | Logging level (quiet/minimal/normal/detailed/diagnostic) |
| `DockerCommand` | `docker` | Docker CLI command |
| `DockerProjectType` | Auto-detected | Project type (console/library) |
| `DockerExposePort` | `8080` (ASP.NET) | Exposed port |
| `DockerUser` | `app` | Container user |
| `DockerCreateUser` | `true` | Create non-root user |
## Usage Examples
### Example 1: Generate-Only Mode (Default)
Perfect for committing Dockerfiles to version control and reviewing before build:
```xml
true
```
```bash
dotnet build
# Dockerfile generated at ./Dockerfile
# No Docker image built
```
### Example 2: Build-Only Mode
Use your own hand-crafted Dockerfile:
```xml
true
false
true
true
$(MSBuildProjectDirectory)\deploy\Dockerfile
```
```bash
dotnet publish
# Uses existing Dockerfile at ./deploy/Dockerfile
# Builds Docker image
```
### Example 3: Full Automation
Generate and build automatically:
```xml
true
true
true
true
myapp
$(Version)
myregistry.azurecr.io
```
```bash
dotnet publish
# Generates Dockerfile
# Builds image: myregistry.azurecr.io/myapp:1.0.0
```
### Example 4: CI/CD with Scripts and Push
```xml
true
true
true
true
true
true
$(MSBuildProjectDirectory)\scripts\pre-build.sh
$(MSBuildProjectDirectory)\scripts\deploy.ps1
myregistry.azurecr.io
myapp
$(GitVersion_SemVer)
```
### Example 5: Development Workflow with Auto-Run
```xml
true
true
true
true
true
true
8080:8080
ASPNETCORE_ENVIRONMENT=Development
$(MSBuildProjectDirectory)/data:/app/data
```
```bash
dotnet build
# Generates Dockerfile
# Builds image
# Starts container with port mappings
```
### Example 6: Selective Script Execution
Execute only specific scripts:
```xml
true
true
$(MSBuildProjectDirectory)\scripts\setup.sh
$(MSBuildProjectDirectory)\scripts\cleanup.sh
true
false
```
## 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:
```xml
```
## Requirements
- **.NET SDK 8.0+**
- **Docker** (when building images)
## Comparison with Alternatives
| Feature | JD.MSBuild.Containers | Built-in SDK | Docker Desktop |
|---------|----------------------|--------------|----------------|
| Auto-generate Dockerfiles | ✅ | ❌ | ❌ |
| Granular control | ✅ | ❌ | ❌ |
| Build-only mode | ✅ | ❌ | N/A |
| Generate-only mode | ✅ | N/A | N/A |
| Pre/Post scripts | ✅ | ❌ | ❌ |
| MSBuild integration | ✅ | Limited | ❌ |
| Incremental builds | ✅ | ❌ | ❌ |
| Custom templates | ✅ | ❌ | N/A |
| Multi-stage support | ✅ | ❌ | ✅ |
## Code Coverage
This project maintains comprehensive code coverage with automated reporting:
- 📊 **Coverage reports** generated on every PR
- 📈 **Historical tracking** via [Codecov](https://codecov.io/gh/JerrettDavis/JD.MSBuild.Containers)
- 💬 **PR comments** with coverage summaries
- 📦 **HTML reports** available as CI artifacts
See [CODE_COVERAGE.md](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](LICENSE) for details.
## Acknowledgments
- Architecture inspired by [JD.Efcpt.Build](https://github.com/jerrettdavis/JD.Efcpt.Build)
- Docker for container runtime
- Microsoft for .NET SDK and MSBuild