Documentation section: Configuration
Version Detection
The SDK reads the version field from a repository-root package.json and applies it to both
Version and PackageVersion automatically. When no repository root can be discovered at all
(non-strict mode), it silently falls back to 0.0.1.
Behaviour
Section titled “Behaviour”When UsePackageJsonVersion=true (the default) or UsePackageJsonVersion=Strict (compared
case-insensitively), the SDK resolves the file during the Sdk.props import:
- Explicit path — if
RootPackageJsonis set, reads that file directly. A relative path resolves from the project directory, whatever directory the build runs from — so a value inDirectory.Build.propsresolves per project; use$(MSBuildThisFileDirectory)package.jsonthere. - Auto-discovery — otherwise it finds the repository root (
RepoRoot), and readspackage.jsonfrom there. The first of these that gives an answer wins:- a
RepoRootyou set before the import; - the repository root recorded in the cache for this project;
- the CI workspace variables
GITHUB_WORKSPACE,BUILD_SOURCESDIRECTORY,BUILD_REPOSITORY_LOCALPATHandCI_PROJECT_DIR, in that order, when the folder exists; - the nearest folder above the project holding a
.gitfile or folder; - the nearest folder above the project holding a
package.json.
- a
The value of the first "version": "..." pair in the file is applied to both Version and
PackageVersion. It is a text match, not a JSON parse, so keep the top-level version field ahead of
any nested object that also has one.
ValidatePackageJsonVersion runs before BeforeBuild, GenerateNuspec and Pack, and fails the build
when:
RootPackageJsonwas set explicitly and that file does not exist;- a repository root was discovered but there is no
package.jsonin it — so a git repository without a rootpackage.jsonfails the build until you add one, setRootPackageJson, or setUsePackageJsonVersion=false; - a
package.jsonwas found but noversioncould be read from it; UsePackageJsonVersion=Strictand no source could be discovered at all (no explicitRootPackageJsonand no repository root). In non-strict mode that case silently keeps the0.0.1default.
UsePackageJsonVersion=false turns all of this off; Version keeps whatever was set elsewhere, or
0.0.1.
Caching
Section titled “Caching”Auto-discovery results are cached under the user’s temporary directory, in
Purview.BuildSdk/VersionDetection/, one file per project directory, so later evaluations can skip the
root search. VersionDetectionCacheFile overrides the file. The cache records the repository root, the
package.json path and the version, and is written by WriteVersionDetectionCache before
CollectPackageReferences, PrepareForBuild, GenerateNuspec and Pack. It is only used when
RootPackageJson is not set explicitly, and the version itself is always re-read from the cached
package.json, so editing the file is picked up straight away. Enable or disable it with
EnableVersionDetectionCache (default true).
Logging
Section titled “Logging”Version detection logging is disabled by default. Set VersionDetectionLogEnabled=true to emit a
high-importance message, from ValidatePackageJsonVersion, showing the detected package version and
the file it came from. It can be set anywhere, because only the target reads it.
Important — set before the import
Section titled “Important — set before the import”UsePackageJsonVersion, RootPackageJson, RepoRoot, EnableVersionDetectionCache and
VersionDetectionCacheFile must be set before the
<Import Sdk="Purview.BuildSdk" Project="Sdk.props" /> line in your Directory.Build.props.
The version logic runs during that import and cannot see properties set afterwards (for example in
individual .csproj files).
<Project> <PropertyGroup> <NamespacePrefix>Acme</NamespacePrefix> <!-- Set here, before the import --> <RootPackageJson>$(MSBuildThisFileDirectory)package.json</RootPackageJson> </PropertyGroup>
<Import Sdk="Purview.BuildSdk" Project="Sdk.props" /></Project>