The build will generate the version 1.2.3-mybranch.b.4567.

To build a custom pre-release or a final release, use a version-like Git tag.

dotnet build -c Release -p:Branch=refs/tags/release/1.2.3-beta -p:Counter=4567

The build will generate the version 1.2.3-beta. When the Git tag looks like a SemVer2 version, the build uses that version verbatim and does not append a timestamp or a build number.

Interaction With Build Servers

To communicate the generated version number to a build server, add one or more of the following MSBuild properties to one of your project files.

<PropertyGroup>
  <SetAzurePipelinesBuildName>true</SetAzurePipelinesBuildName>
  <SetGitHubActionsVersion>true</SetGitHubActionsVersion>
  <SetTeamCityBuildNumber>true</SetTeamCityBuildNumber>
</PropertyGroup>

Custom Version-Like Tag Prefix

By default, this package expects version-like Git tags to have a release/ prefix. To use a different prefix, override the VersionTagPrefix MSBuild property. This can be useful if you prefer the v prefix.

<PropertyGroup>
  <VersionTagPrefix>v</VersionTagPrefix>
</PropertyGroup>

A custom prefix is useful to disambiguate the version-like Git tags of unrelated subprojects in a monorepo.

<PropertyGroup>
  <VersionTagPrefix>MyProject/v</VersionTagPrefix>
</PropertyGroup>

Version Stamping

TODO

MSBuild Property Reference

Branch

The full git refspec of the code being built. The behavior of this package depends primarily on the format of the refspec:

• refs/heads/foo
  • Recognized as a branch named foo.
  • Sets the version suffix to foo followed by a build counter.
• refs/heads/foo/bar
  • Recognized as a branch named foo/bar.
  • Sets the version suffix to foo-bar followed by a build counter.
• refs/pull/42
  • Recognized as pull request 42.
  • Sets the version suffix to pr.42 followed by a build counter.
• refs/tag/release/1.2.3-foo.42
  • Recognized as a version-like Git tag with the pre-release version 1.2.3-foo.42.
  • Emits a build error if the VersionPrefix property does not match the tag version, 1.2.3.
  • Sets the version suffix to foo.42 followed by a build counter.
  • The release/ prefix is configurable.
• refs/tag/release/1.2.3
  • Recognized as a version-like Git tag with the release version 1.2.3.
  • Emits a build error if the VersionPrefix property does not match the tag version, 1.2.3.
  • Does not set a version suffix or append a build counter.
  • The release/ prefix is configurable.
• something else entirely
  • Not recognized.
  • Sets the version suffix to something-else-entirely followed by a build counter.
• empty or not set
  • Sets the version suffix to local, without a build counter. This default is intended to ease local development.

Counter

An arbitrary number to distinguish the current build from other builds of the same refspec. If not set, the build generates a date/time-based counter of the form yyyymmdd.ThhmmssZ using the current UTC time.

StampOnBuild

TODO

SetAzurePipelinesBuildName

When true, the build outputs magic text that sets the name and $(Build.BuildNumber) variable of the current Azure DevOps pipeline run.

SetGitHubActionsVersion

When true, the build outputs magic text that sets the Version output parameter of the current workflow step.

SetTeamCityBuildNumber

When true, the build outputs magic text that sets the build number of the current TeamCity build.

VersionTagPrefix

The prefix that identifies a version-like Git tag. The default value is release/.