Reproducible and Deterministic Builds

With Deterministic set to true (the default for modern .NET projects), csc produces the same assembly for the same inputs: the timestamp and MVID fields are derived from a hash of the compilation inputs instead of the clock and a random GUID. The documented inputs include the command line, the .rsp file, the exact compiler version and its referenced assemblies. "Same inputs" includes the full paths of the source files, which end up in the PDB and in the assembly’s debug directory. Building the library in two folders shows the problem:

The assembly records where its PDB was written, so two checkouts in different folders differ.

Source: C# compiler options: Deterministic.

ContinuousIntegrationBuild=true tells the SDK the build is an official one: source paths are normalised (the source root is mapped to /_/), and Source Link requires the source control information to be present. It should be on in CI and off locally, because the debugger cannot find local sources through /_/ paths. The documented pattern, which Ledgerline's Directory.Build.props uses, conditions it on the variables the CI systems set:

GITHUB_ACTIONS (GitHub Actions) and TF_BUILD (Azure Pipelines) are environment variables, which MSBuild turns into properties. Simulating CI with the variable gives identical assemblies in both folders, and the PDB path is now mapped:

Other CI systems need their own variable in the condition (for example CI on many hosted runners) or -p:ContinuousIntegrationBuild=true on the command line.

Source: MSBuild props: ContinuousIntegrationBuild.

Since .NET 8, Source Link is part of the SDK: no Microsoft.SourceLink.* package is needed for GitHub, GitLab, Azure Repos or Bitbucket repositories. During the build it reads the Git repository (without needing git on the PATH), sets SourceRevisionId to the commit and writes a Source Link JSON map into the PDB, so debuggers can download the exact source of each file. As a side effect — a documented breaking change of .NET 8 — the commit is appended to InformationalVersion as SemVer build metadata:

Keep the revision in official builds — it identifies the source of a binary — and turn it off only where the +<sha> suffix breaks something that parses the version. A build from a source archive without .git has no revision unless SourceRevisionId is passed explicitly. Packaging symbols and Source Link for nuget.org is covered on Symbols, Source Link and Deterministic Packages.

Some library-guidance pages still tell you to add the Microsoft.SourceLink.GitHub package; with SDK 8.0.100 and later that is unnecessary.

Source: .NET 8 breaking change: Source Link included in the .NET SDK, MSBuild props: SourceRevisionId, IncludeSourceRevisionInInformationalVersion.

A .nupkg is a ZIP file, and ZIP entries carry modification times. Even with identical assemblies, two packs differ. Packing the same commit in the two clones (with GITHUB_ACTIONS=true, so the DLLs are identical) and comparing the packages entry by entry with a small Python script (nupkgdiff.py: it hashes each entry and compares its ZIP timestamp):

Every content is the same; only the times differ. The pack target has two inputs for this:

With both properties set, the two clones produce the same package:

A practical choice for the timestamp is the commit time, so it changes only when the source does. In SDK 10.0.402 the SOURCE_DATE_EPOCH variable alone did not have that effect: with SOURCE_DATE_EPOCH exported and only -p:Deterministic=true, the entries still carried the current time and the two packages differed, because the pack targets set DeterministicTimestamp to false before NuGet looks at the variable. Passing the value explicitly works:

(17:53:05 UTC is the commit time; the unzip listing is abridged.) The documentation is also inconsistent on when deterministic pack arrived: the dotnet pack examples say ".NET 10.0.400 and later", the pack-target table gives the default as ".NET 11+". Both are true — available from 10.0.400, on by default in 11 — and .NET 11 is still a preview.

Source: NuGet: Pack target inputs (Deterministic, DeterministicTimestamp, SOURCE_DATE_EPOCH), dotnet pack examples, SOURCE_DATE_EPOCH specification.

Determinism of the compiler and the packer is worthless if the inputs move. Two more files close the gap, each with its own page:

The SDK’s built-in container publishing (dotnet publish -t:PublishContainer) produced different image digests for the same inputs, because of timestamps, archive headers and file enumeration order. The .NET 11 preview SDK fixes this: with SOURCE_DATE_EPOCH set to a stable value, independent publishes of the same inputs produce the same digest. It is not available on SDK 10.0.402 and is not run here; see Container Images.

Source: What’s new in the .NET 11 SDK: Reproducible container publishing.

To check that a published package matches its source: check out the commit named in its InformationalVersion or nuspec repository element, use the SDK version from the repository’s global.json, build with the same switches (ContinuousIntegrationBuild, Deterministic, the same DeterministicTimestamp), and compare — whole-file hashes first, then entry by entry as above. A package signed by nuget.org (repository signature) gains a signature file, so compare the entries other than .signature.p7s. The dotnet organisation’s dotnet/reproducible-builds repository (a dotnet-org GitHub project) collects MSBuild settings for reproducible builds.