XploRe.Versioning.Tools.DotNet 0.1.2

Automated Repository-based SemVer 2.0 Versioning for .NET

Provides targets that hook into the MSBuild building process to automatically set a SemVer 2.0-compatible version suffix based on the repository revision information.

Usage

Configuration

Set a version prefix in your project file and define the repository type:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    
    <VersionPrefix>1.2.0</VersionPrefix>
    <RepositoryType>hg</RepositoryType>
  </PropertyGroup>
  
</Project>

The version prefix is used verbatim and should be compliant to SemVer 2.0 versioning, i.e. consist of a major X, minor Y and patch number Z in the format X.Y.Z. All three number components should be provided for best compatibility, even if the patch number and minor number are 0.

The repository type is used to determine how to retrieve repository information. Currently the following source control systems are supported:

• bzr (Bazaar, uses the revision number and a shortened hash)
• git (Git, uses the hash and calculates a revision number from the revisions since the first parent)
• hg (Mercurial, uses the revision number and hash)
• svn (Subversion, uses the base revision number)

If no repository type is defined, the repository type is auto-detected by searching for a corresponding source control system metadata-folder in the project root folder.

Activation

To activate automated versioning, add the following package reference to the project file:

<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    
    <PackageReference Include="XploRe.Versioning.Tools.DotNet" Version="0.1.2" PrivateAssets="All" />
  </ItemGroup>
</Project>

Setting PrivateAssets to All ensures that the package reference is used for building only and will not appear as a dependency in the NuSpec file of the project.

A repository-based version suffix is now automatically applied whenever the project is being build.

Version Format

Depending on the repository type, the current revision number, revision ID and branch name are obtained.

If the project is build using the Debug configuration, a version tag of "dev" (for development version) is automatically added.
If the project is build using the Release configuration and the repository branch is not master, default or trunk, a version tag of "rc" (for release candidate) is automatically added.

The final version number has the following format:

VersionPrefix "-" [VersionTag] ["." BuildNumber] ["+" RevisionID]

where blocks of non-existing information are omitted. The build number defaults to the revision number.

Overrides

Values such as the VersionTag or BuildNumber can be overridden by explicitly setting the corresponding MSBuild properties:

dotnet pack /p:VersionTag=beta /p:BuildNumber=2

Output:

[...]
Building version 1.2.0-beta.2+37d39626d4cb for target netstandard1.3.
[...]

Alternatively, properties can also be overridden in the BeforeBuild target.

Options

Options are normal MSBuild properties and can be either defined in the project file or via the command-line.

RepositoryRevisionIDMaxLength number

Controls the maximum length of the repository revision ID. If a revision ID is available and longer than the defined maximum length, the revision ID is truncated:

dotnet pack /p:VersionTag=beta /p:BuildNumber=2 /p:RepositoryRevisionIDMaxLength=4

Output:

[...]
Building version 1.2.0-beta.2+37d3 for target netstandard1.3.
[...]

License

Released under the Apache License, Version 2.0.

Copyright (C) 2018, xplo.re IT Services, Michael Maier. All rights reserved.