> ## Documentation Index
> Fetch the complete documentation index at: https://buildcharts.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# .NET

> Get started with BuildCharts in .NET repositories using the built-in chart set.

## Prerequisites

* Docker with `buildx`
* BuildCharts installed
* A repository root that contains a `.sln` or `.slnx` files

## Scaffold a repository

Run `buildcharts init` from the repository root.

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
buildcharts init
```

In a .NET repository, this command:

* Creates `build.yml`
* Creates `charts/buildcharts/Chart.yaml`
* Creates `.github/workflows/buildcharts.yml` when the Git remote points to GitHub

| Target   | Description                                                                                       |
| -------- | ------------------------------------------------------------------------------------------------- |
| `build`  | `global.json` or target frameworks help determine the .NET SDK base image version                 |
| `test`   | Test package references such as `Microsoft.NET.Test.Sdk`, `xunit`, or `nunit`                     |
| `nuget`  | Package metadata such as `<PackageId>` or `<GeneratePackageOnBuild>true</GeneratePackageOnBuild>` |
| `docker` | A local `Dockerfile` in a project folder                                                          |

## Use the built-in .NET charts

BuildCharts ships with first-class .NET charts for common stage types. These are a practical starting point when you want working defaults before you introduce your own chart ecosystem.

The built-in .NET chart set is documented here:

* [buildcharts/charts/dotnet](https://github.com/buildcharts/charts/tree/main/dotnet)

The shipped Dockerfiles cover the common .NET workflows:

* `build` runs `dotnet build`
* `test` runs `dotnet test` and prepares test artifacts
* `nuget` runs `dotnet pack` and prepares package output
* `publish` runs `dotnet publish`
* `docker` publishes the app and assembles the runtime image

These charts are implemented as reusable Dockerfiles behind the chart aliases you reference from `build.yml`.

## Dependency chart

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
apiVersion: v2
name: buildcharts
version: 0.0.1
description: A meta-chart to define build pipeline targets and templates
type: application

dependencies:
  - name: dotnet-build
    alias: build
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts

  - name: dotnet-docker
    alias: docker
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts

  - name: dotnet-nuget
    alias: nuget
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts

  - name: dotnet-publish
    alias: publish
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts

  - name: dotnet-test
    alias: test
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts
```

This file maps target aliases in `build.yml` to the built-in .NET charts.

## Review the generated metadata

This shape matches the shipped samples:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
# yaml-language-server: $schema=https://raw.githubusercontent.com/eddietisma/buildcharts/main/schemas/v1beta.json

version: v1beta

variables:
  VERSION: "1.0.0"
  COMMIT: "local"

targets:
  buildcharts.sln:
    type: build
    with:
      contexts:
        base: docker-image://mcr.microsoft.com/dotnet/sdk:10.0

  src/BuildCharts.Tool/BuildCharts.Tool.csproj:
    - type: nuget
    - type: docker
      with:
        contexts:
          base: docker-image://mcr.microsoft.com/dotnet/runtime:10.0
        tags: ["docker.io/buildcharts/buildcharts:${VERSION}-${COMMIT}"]

  test/BuildCharts.Tests/BuildCharts.Tests.csproj:
    type: test

types:
  nuget:
    contexts:
      git: .git
```

<Note>
  You must define exactly one `build` target.
</Note>

### Parallelization: multiple targets vs `dotnet test`

`build` and `test` can also be placed directly on the solution target. This works well for .NET because `dotnet build` and `dotnet test` can run directly against a solution, so the solution can act as the shared source for both stages:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
targets:
  buildcharts.sln:
    type: [build, test]
    with:
      contexts:
        base: docker-image://mcr.microsoft.com/dotnet/sdk:10.0
```

That shifts test parallelization to `dotnet test`, which then delegates to the test framework and runner, such as xUnit, NUnit, or MSTest.

The tradeoff is execution strategy:

* Solution-level `test` keeps the config simpler and matches normal .NET workflows
* Separate test targets can let Docker Bake parallelize more work across targets
* Separate targets may also benefit differently from Docker layer caching

Which model is faster depends on your solution shape, test layout, hardware, number of tests, and how test assemblies are distributed, so benchmark both if build time matters.

<Tip>
  From [.NET 9](https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-9/sdk#run-tests-in-parallel), tests for the same project run in parallel across different target frameworks.
</Tip>

## Create a lock file (optional)

Pin chart digests to make generation repeatable and avoid accidental drift.

When a lock file is present, `buildcharts generate` checks for mismatches against `charts/buildcharts/Chart.yaml` before generating the build plan. For details, see [Lock files](/core-features/lock-files).

Create the lock file with:

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
buildcharts update
```

## Generate and run the plan

Bash:

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
export VERSION=1.0.0
export COMMIT=$(git rev-parse HEAD)

buildcharts generate
docker buildx bake --file .buildcharts/docker-bake.hcl
```

PowerShell:

```powershell theme={"theme":{"light":"plastic","dark":"plastic"}}
$env:VERSION = "1.0.0"
$env:COMMIT = (git rev-parse HEAD)

buildcharts generate
docker buildx bake --file .buildcharts/docker-bake.hcl
```

## Signature verification (optional)

The built-in .NET charts are published as OCI artifacts and signed with Cosign in GitHub Actions. You can verify a chart signature before using or trusting a chart digest.

Install [`cosign`](https://github.com/sigstore/cosign) and verify the chart by digest:

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
cosign verify \
  --certificate-identity-regexp 'https://github\.com/buildcharts/charts/\.github/workflows/.+' \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  docker.io/buildcharts/<chart>@sha256:<digest>
```

When using a lock file, the digest is available in `charts/buildcharts/Chart.lock`. That makes the lock file the natural source for verification input during CI or review.

## Next steps

* [Install BuildCharts](/install)
* [Learn how the generation flow works](/how-it-works)
* [Configure GitHub Actions](/quickstart/github-actions)
* [Read the `Metadata` guide](/core-features/metadata)
* [Read the lock files guide](/core-features/lock-files)
* [Enable built-in plugins](/core-features/plugins)