diff --git a/docfx/docs/build-systems/msbuild.md b/docfx/docs/build-systems/msbuild.md index e6ea9bc5..2b2ba4ab 100644 --- a/docfx/docs/build-systems/msbuild.md +++ b/docfx/docs/build-systems/msbuild.md @@ -51,6 +51,15 @@ Property | Default | Description `NBGV_ThisAssemblyIncludesPackageVersion` | `false` | When `true`, a `NuGetPackageVersion` property is added to the `ThisAssembly` class. `NBGV_UseAssemblyVersionInNativeVersion` | `true` | When `false`, uses the `AssemblyFileVersion` as a native `PRODUCTVERSION`. +### Items + +The following MSBuild items may be declared in your project to customize the computed version: + +Item type | Description +--|-- +`BuildMetadata` | Adds `+ItemName` build metadata for each item to the computed version. +`PrereleaseIdentifier` | Adds `-ItemName` build metadata for each item to the computed version. + ### Custom `ThisAssembly` static fields and constants Custom constants may be added to the `ThisAssembly` class through `AdditionalThisAssemblyFields` items defined in your project. diff --git a/src/NerdBank.GitVersioning/VersionOracle.cs b/src/NerdBank.GitVersioning/VersionOracle.cs index 89157ee3..64bdfe08 100644 --- a/src/NerdBank.GitVersioning/VersionOracle.cs +++ b/src/NerdBank.GitVersioning/VersionOracle.cs @@ -208,7 +208,31 @@ public IEnumerable BuildMetadataWithCommitId /// /// Gets the prerelease version information, including a leading hyphen. /// - public string PrereleaseVersion => this.ReplaceMacros(this.VersionOptions?.Version?.Prerelease ?? string.Empty); + /// An empty string for a stable release, or a string like -beta. + public string PrereleaseVersion + { + get + { + string result = this.ReplaceMacros(this.VersionOptions?.Version?.Prerelease ?? string.Empty); + + foreach (string identifier in this.ExtraPrereleaseIdentifiers) + { + if (result.Length == 0) + { + result = "-"; + } + else + { + // In semver v2, identifiers should be separated by periods. + result += this.VersionOptions?.NuGetPackageVersionOrDefault.SemVerOrDefault >= 2 ? '.' : '-'; + } + + result += identifier; + } + + return result; + } + } /// /// Gets the prerelease version information, omitting the leading hyphen, if any. @@ -379,6 +403,12 @@ public IDictionary CloudBuildVersionVars [Ignore] public List BuildMetadata { get; } = new List(); + /// + /// Gets a list of prerelease identifiers to add to whatever the default prerelease identifiers are. + /// + [Ignore] + public List ExtraPrereleaseIdentifiers { get; } = new List(); + /// /// Gets the +buildMetadata fragment for the semantic version. /// diff --git a/src/Nerdbank.GitVersioning.Tasks/GetBuildVersion.cs b/src/Nerdbank.GitVersioning.Tasks/GetBuildVersion.cs index 683ff6d0..703591fa 100644 --- a/src/Nerdbank.GitVersioning.Tasks/GetBuildVersion.cs +++ b/src/Nerdbank.GitVersioning.Tasks/GetBuildVersion.cs @@ -1,12 +1,7 @@ // Copyright (c) .NET Foundation and Contributors. All rights reserved. // Licensed under the MIT license. See LICENSE file in the project root for full license information. -using System; -using System.Collections.Generic; using System.Globalization; -using System.IO; -using System.Linq; -using System.Reflection; using Microsoft.Build.Framework; using Microsoft.Build.Utilities; using MSBuildExtensionTask; @@ -28,6 +23,11 @@ public GetBuildVersion() /// public string BuildMetadata { get; set; } + /// + /// Gets or sets an array of prerelease identifiers to append to whatever else may be determined by default. + /// + public string PrereleaseIdentifiers { get; set; } + /// /// Gets or sets the value of the PublicRelease property in MSBuild at the /// start of this Task. @@ -256,6 +256,11 @@ protected override bool ExecuteInner() oracle.BuildMetadata.AddRange(this.BuildMetadata.Split(';')); } + if (this.PrereleaseIdentifiers is { Length: > 0 }) + { + oracle.ExtraPrereleaseIdentifiers.AddRange(this.PrereleaseIdentifiers.Split(';')); + } + if (IsMisconfiguredPrereleaseAndSemVer1(oracle)) { this.Log.LogWarning("The 'nugetPackageVersion' is explicitly set to 'semVer': 1 but the prerelease version '{0}' is not SemVer1 compliant. Change the 'nugetPackageVersion'.'semVer' value to 2 or change the 'version' member to follow SemVer1 rules (e.g.: '{1}').", oracle.PrereleaseVersion, GetSemVer1WithoutPaddingOrBuildMetadata(oracle)); diff --git a/src/Nerdbank.GitVersioning.Tasks/build/InProjectVersionComputation.targets b/src/Nerdbank.GitVersioning.Tasks/build/InProjectVersionComputation.targets index 349fff64..b095c014 100644 --- a/src/Nerdbank.GitVersioning.Tasks/build/InProjectVersionComputation.targets +++ b/src/Nerdbank.GitVersioning.Tasks/build/InProjectVersionComputation.targets @@ -6,6 +6,7 @@ CallTarget invoked targets do not see properties set by the calling target. --> @(BuildMetadata, ',') + @(PrereleaseIdentifier, ',') diff --git a/src/Nerdbank.GitVersioning.Tasks/build/MSBuildTargetCaching.targets b/src/Nerdbank.GitVersioning.Tasks/build/MSBuildTargetCaching.targets index 2a9a7daa..e767c328 100644 --- a/src/Nerdbank.GitVersioning.Tasks/build/MSBuildTargetCaching.targets +++ b/src/Nerdbank.GitVersioning.Tasks/build/MSBuildTargetCaching.targets @@ -16,12 +16,13 @@ <_BuildMetadataSnapped Include="@(BuildMetadata)" /> + <_PrereleaseIdentifierSnapped Include="@(PrereleaseIdentifier)" /> GetBuildVersion_Properties;GetBuildVersion_CloudBuildVersionVars - $(NBGV_InnerGlobalProperties)BuildMetadata=@(BuildMetadata, ','); + $(NBGV_InnerGlobalProperties)BuildMetadata=@(BuildMetadata, ',');PrereleaseIdentifiers=@(PrereleaseIdentifier, ',') Configuration=Release Platform=AnyCPU @(NBGV_GlobalPropertiesToRemove) @@ -44,6 +45,7 @@ + diff --git a/src/Nerdbank.GitVersioning.Tasks/build/Nerdbank.GitVersioning.Inner.targets b/src/Nerdbank.GitVersioning.Tasks/build/Nerdbank.GitVersioning.Inner.targets index ac037a13..20c36728 100644 --- a/src/Nerdbank.GitVersioning.Tasks/build/Nerdbank.GitVersioning.Inner.targets +++ b/src/Nerdbank.GitVersioning.Tasks/build/Nerdbank.GitVersioning.Inner.targets @@ -17,6 +17,7 @@