nuget-packaging - SKILL.md Agent Skill

name: "nuget-packaging" description: "NuGet packaging patterns for the Aspire.Hosting.Minecraft package" domain: "dotnet-nuget" confidence: "high" source: "manual"

Context

These patterns apply to the single NuGet package produced by this repo: Fritz.Aspire.Hosting.Minecraft (PackageId). The RCON library (Aspire.Hosting.Minecraft.Rcon) is embedded into this package. The Worker project is not packaged — it runs as a standalone service. They ensure packages are NuGet.org-ready with reproducible builds.

Patterns

Single Package Architecture

Only Aspire.Hosting.Minecraft is packable (IsPackable=true). The Rcon project is embedded via PrivateAssets="All" on the ProjectReference plus TargetsForTfmSpecificBuildOutput to include the DLL in the lib folder. The Worker project is IsPackable=false — it's a standalone service consumers reference directly.

Never Use Floating Versions

All PackageReference entries must have exact pinned versions (e.g., Version="13.1.0"). Never use Version="*" or version ranges. NuGet.org rejects packages with floating version references and they break reproducible builds.

Directory.Build.props Owns Shared Config

Shared metadata (Authors, License, RepositoryUrl) and build hardening properties live in Directory.Build.props at the repo root. Individual csproj files only add project-specific properties (PackageId, Version, Description, PackageTags, IsPackable).

Required Hardening Properties

Every packable project inherits these from Directory.Build.props:

GenerateDocumentationFile — ships XML docs in the nupkg
EnablePackageValidation — catches breaking API changes between versions
Deterministic — ensures byte-identical builds from same source
ContinuousIntegrationBuild (CI-only) — embeds correct source paths for SourceLink
EmbedUntrackedSources — ensures all source files are available in SourceLink
Microsoft.SourceLink.GitHub — enables debugger source mapping to GitHub

Package README

The single packable project (Aspire.Hosting.Minecraft) has its own README.md in the project directory, included in the nupkg via:

<None Include="README.md" Pack="true" PackagePath="\" />

The PackageReadmeFile property in Directory.Build.props is set to README.md. Non-packable projects do not pack READMEs.

Pack and Verify Workflow

dotnet restore
dotnet build -c Release
dotnet pack -c Release -o nupkgs

Check for: zero warnings on src projects, correct package sizes, no floating versions in generated nuspec.

Anti-Patterns

Floating Version="*" — will be rejected by NuGet.org and breaks reproducibility
Multiple packages for a single integration — consolidate into one package for simpler consumer experience
Missing EnablePackageValidation — won't catch breaking API changes between releases
Missing SourceLink — consumers can't step into source during debugging
Embedding Worker in the hosting package — Worker uses Microsoft.NET.Sdk.Worker and runs as a separate process; it can't be a DLL inside the hosting package