dotnet-artifacts-output

Reference guide for the .NET SDK artifacts output layout, which centralizes build outputs (bin/, obj/, publish/, package/) into a single artifacts/ directory at the repo root. Available since .NET 8 as an opt-in feature. Recommended for new projects; evaluate tradeoffs before migrating existing projects.

Prerequisites: Run [skill:dotnet-version-detection] first to confirm .NET 8+ SDK -- artifacts output layout is not available in earlier SDK versions.

Scope

• UseArtifactsOutput opt-in and ArtifactsPath configuration
• Centralized build output layout (artifacts/bin/, artifacts/obj/, artifacts/publish/)
• Impact on CI artifact upload paths and Docker builds
• Migration tradeoffs for existing projects

Out of scope

• Source tree organization (.sln, .csproj, src/, tests/) -- see [skill:dotnet-project-structure]

Cross-references: [skill:dotnet-project-structure] for solution layout, [skill:dotnet-containers] for Dockerfile path adjustments, [skill:dotnet-gha-build-test] for CI artifact upload paths, [skill:dotnet-scaffold-project] for generating new projects with artifacts output enabled.

---

Why Use Artifacts Output

Traditional .NET build output scatters bin/ and obj/ directories throughout the source tree, one per project. The artifacts output layout consolidates all build outputs under a single artifacts/ directory next to Directory.Build.props.

Benefits:

• Simpler .gitignore -- one artifacts/ entry replaces per-project bin/ and obj/ entries
• Easier clean builds -- delete one directory instead of hunting for scattered bin//obj/ folders
• Predictable output paths -- tooling can anticipate where to find build outputs without traversing the source tree
• Cleaner source tree -- no build artifacts mixed into project directories

Tradeoffs:

• Breaking path assumptions -- existing CI pipelines, Dockerfiles, and tooling that reference bin/Debug/net10.0/ paths must be updated
• IDE/tool compatibility -- some older tools may not resolve the new output paths correctly
• Migration effort -- existing projects require updating all hardcoded output path references

---

Enabling Artifacts Output

Add UseArtifactsOutput to your Directory.Build.props at the repo root:

<Project>
  <PropertyGroup>
    <UseArtifactsOutput>true</UseArtifactsOutput>
  </PropertyGroup>
</Project>

```text

Alternatively, generate a new `Directory.Build.props` with artifacts output pre-configured:

```bash

dotnet new buildprops --use-artifacts

```bash

This creates:

```xml

<Project>
  <PropertyGroup>
    <ArtifactsPath>$(MSBuildThisFileDirectory)artifacts</ArtifactsPath>
  </PropertyGroup>
</Project>

```text

Setting `ArtifactsPath` directly is equivalent to `UseArtifactsOutput=true` and additionally lets you customize the root
directory location.

---

## Output Path Structure

All build outputs are organized under `artifacts/` with three levels: output type, project name, and pivot
(configuration/TFM/RID).

```text

artifacts/
  bin/
    MyApp/
      debug/                          # Single-targeted project
      debug_net10.0/                  # Multi-targeted project
      release_linux-x64/              # RID-specific build
    MyApp.Core/
      debug/
  obj/
    MyApp/
      debug/
  publish/
    MyApp/
      release/                        # dotnet publish output
      release_linux-x64/              # RID-specific publish
  package/
    release/                          # NuGet .nupkg files (no project subfolder)

```text

### Output Type Directories

| Directory            | Contents                                 | Traditional equivalent                  |
| -------------------- | ---------------------------------------- | --------------------------------------- |
| `artifacts/bin/`     | Compiled assemblies and dependencies     | `<project>/bin/`                        |
| `artifacts/obj/`     | Intermediate build files, generated code | `<project>/obj/`                        |
| `artifacts/publish/` | Published application output             | `<project>/bin/<config>/<tfm>/publish/` |
| `artifacts/package/` | NuGet packages (`.nupkg`, `.snupkg`)     | `<project>/bin/<config>/`               |

### Pivot Naming

The pivot subfolder combines configuration, TFM, and RID joined by underscores. Components that are not present are
omitted:

| Scenario               | Pivot               | Full path example                        |
| ---------------------- | ------------------- | ---------------------------------------- |
| Single-targeted, debug | `debug`             | `artifacts/bin/MyApp/debug/`             |
| Multi-targeted, debug  | `debug_net10.0`     | `artifacts/bin/MyApp/debug_net10.0/`     |
| Release, RID-specific  | `release_linux-x64` | `artifacts/bin/MyApp/release_linux-x64/` |
| Package output         | `release`           | `artifacts/package/release/`             |

Note: `artifacts/package/` omits the project name subfolder. The pivot includes only the configuration.

---

## Customizing the Artifacts Path

### Custom Root Directory

Set `ArtifactsPath` to change the root location:

```xml

<PropertyGroup>
  <ArtifactsPath>$(MSBuildThisFileDirectory).output</ArtifactsPath>
</PropertyGroup>

```xml

This places all build outputs under `.output/` instead of `artifacts/`.

### Custom Pivot

Customize the pivot subfolder naming with `ArtifactsPivots`:

```xml

<PropertyGroup>
  <ArtifactsPivots>$(ArtifactsPivots)_MyCustomPivot</ArtifactsPivots>
</PropertyGroup>

```xml

---

## Impact on .gitignore

With artifacts output enabled, simplify `.gitignore`:

```gitignore

# Artifacts output layout (replaces per-project bin/ and obj/ entries)
artifacts/

```text

This single entry replaces the traditional pattern:

```gitignore

# Traditional layout (no longer needed with artifacts output)
[Bb]in/
[Oo]bj/

```text

If using a custom `ArtifactsPath`, update the `.gitignore` entry to match.

---

## Impact on Dockerfiles

Multi-stage Dockerfiles that copy build output must reference the new path structure. See [skill:dotnet-containers] for
full Dockerfile patterns.

**Traditional paths:**

```dockerfile

COPY --from=build /app/src/MyApp/bin/Release/net10.0/publish/ .

```dockerfile

**Artifacts output paths:**

```dockerfile

COPY --from=build /app/artifacts/publish/MyApp/release/ .

```dockerfile

Key differences in Dockerfile paths:

- Output is under `artifacts/publish/` not `bin/Release/<tfm>/publish/`
- Project name becomes a subdirectory under the output type
- Configuration pivot is lowercase (`release` not `Release`)
- TFM is omitted from single-targeted project pivots

---

## Impact on CI Pipelines

CI workflows that upload build artifacts or reference output paths must be updated. See [skill:dotnet-gha-build-test]
for full CI workflow patterns.

**GitHub Actions -- upload build output:**

```yaml

- name: Publish
  run: dotnet publish src/MyApp/MyApp.csproj -c Release

- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: app
    path: artifacts/publish/MyApp/release/

```text

**GitHub Actions -- upload NuGet packages:**

```yaml

- name: Pack
  run: dotnet pack -c Release

- name: Upload packages
  uses: actions/upload-artifact@v4
  with:
    name: packages
    path: artifacts/package/release/*.nupkg

```text

**Azure DevOps -- publish artifacts:**

```yaml

- script: dotnet publish src/MyApp/MyApp.csproj -c Release
  displayName: 'Publish'

- task: PublishPipelineArtifact@1
  inputs:
    targetPath: 'artifacts/publish/MyApp/release/'
    artifact: 'app'

```text

---

## Migration Checklist

When enabling artifacts output on an existing project:

1. **Add `UseArtifactsOutput`** to `Directory.Build.props`
2. **Update `.gitignore`** -- replace `[Bb]in/` and `[Oo]bj/` with `artifacts/`
3. **Update Dockerfiles** -- change all `COPY --from=build` paths to use `artifacts/` structure
4. **Update CI pipelines** -- fix artifact upload paths, test result paths, and publish paths
5. **Update local scripts** -- fix any shell scripts that reference `bin/` or `obj/` paths
6. **Clean old output** -- delete existing `bin/` and `obj/` directories from all projects
7. **Verify builds** -- run `dotnet build` and `dotnet publish` to confirm output appears under `artifacts/`
8. **Verify tests** -- run `dotnet test` to confirm test execution with new paths

---

## Agent Gotchas

1. **Do not hardcode TFM in artifacts output paths for single-targeted projects.** The pivot for single-targeted
   projects is just the configuration (e.g., `debug`), not `debug_net10.0`. Multi-targeted projects include the TFM in
   the pivot.
2. **Do not use capitalized configuration names in artifacts paths.** The artifacts layout uses lowercase pivots
   (`debug`, `release`), not the traditional capitalized names (`Debug`, `Release`).
3. **Do not assume `artifacts/package/` has a project name subfolder.** Unlike `bin/`, `obj/`, and `publish/`, the
   `package/` output type omits the project name level. Packages appear directly under `artifacts/package/<config>/`.
4. **Do not enable artifacts output without updating Dockerfiles and CI pipelines first.** Path changes will break
   `COPY --from=build` directives and artifact upload steps that reference traditional `bin/` paths.
5. **Do not present artifacts output as the default .NET layout.** It is opt-in since .NET 8 and remains opt-in.
   Recommend it for new projects; for existing projects, evaluate the migration effort against the benefits.

---



## Code Navigation (Serena MCP)

**Primary approach:** Use Serena symbol operations for efficient code navigation:

1. **Find definitions**: `serena_find_symbol` instead of text search
2. **Understand structure**: `serena_get_symbols_overview` for file organization
3. **Track references**: `serena_find_referencing_symbols` for impact analysis
4. **Precise edits**: `serena_replace_symbol_body` for clean modifications

**When to use Serena vs traditional tools:**
- ✅ **Use Serena**: Navigation, refactoring, dependency analysis, precise edits
- ✅ **Use Read/Grep**: Reading full files, pattern matching, simple text operations
- ✅ **Fallback**: If Serena unavailable, traditional tools work fine

**Example workflow:**
```text
# Instead of:
Read: src/Services/OrderService.cs
Grep: "public void ProcessOrder"

# Use:
serena_find_symbol: "OrderService/ProcessOrder"
serena_get_symbols_overview: "src/Services/OrderService.cs"
```
## References

- [Artifacts output layout](https://learn.microsoft.com/en-us/dotnet/core/sdk/artifacts-output)
- [Customize your build (Directory.Build.props)](https://learn.microsoft.com/en-us/visualstudio/msbuild/customize-your-build)
- [dotnet new buildprops](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-new-sdk-templates#buildprops)