Table of Contents

Getting Started

Installing

First check prerequisites and then install the dotnet tool Git2SemVer.Tool:

dotnet tool install --global NoeticTools.Git2SemVer.Tool
Note

Git2SemVer.Tool is only required for solution setup. For a single project solution you could just reference the Git2SemVer.MSBuild package.

Then, in the solution's directory, run:

Git2SemVer add

You will be prompted with a few options and then setup is done.

Try building the solution, all projects will be automatically versioned using Git2SemVer's default versioning.

Tip

Git2SemVer outputs the generated informational version to the compiler's output.

Quick Start

First build

If you have not installed Git2SemVer and configured your test solution for solution versioning, do it now. Instructions are here.

Your test solution must be under Git revision control.

Rebuild and you will see the generated version in compiler's output. It will be something like:

Git2SemVer calculated version: 0.18.2-Alpha-InitialDev.MyPC.1422+Documentation-updates.3bda6f4fbedf2fe469da35b9f1a58146d4a36927
Important

If the message does not appear check that build output verbosity is at least Normal in Visual Studio Tools | Options | Projects and Solutions or detailed if using dotnet CLI.

Tip

A versioning log Git2SemVer.MSBuild.log is written to the project's intermediate file folder (obj). This log includes information to show how the version was calculated.

Build with custom C# script

Customise the versioning open the file Git2SemVer.csx in the SolutionVersioning (or the name given during setup) project and add:

Log.LogInfo("Hello world - my first Git2SemVer C# script is born.");

Rebuild and you will the message Hello world - my first After Burner C# script is born. in the compiler's output. If the message does not appear check that build output verbosity is at least Normal in Visual Studio Tools | Options | Projects and Solutions. The message will not appear if set to Minimal or Quiet.

That was using C# script globals. Log is a global property. Another way is to use a context instance exposted by the VersionContext property:

var context = VersioningContext.Instance!;

context.Logger.LogInfo("Hello world - my second Git2SemVer C# script is born.");

VersioningContext.Instance provides the global properties as a context object. It provides a better coding experience. We will use the context object but the same can be done using the global properties.

Tip

Git2SemVer has loaded common libraries and has setup implied using namespaces. Using statements may added to the file for more advanced editing.

As a simple example of seting assembly, file, informational, as well as package versions, replace the code in the csx file with:

var context = VersioningContext.Instance!;
context.Logger.LogInfo("Running demo Git2SemVer customisation script.");

context.Outputs.SetAllVersionPropertiesFrom(SemVersion.ParseFrom("1.2.3-Demo.999+ASimpleDemoScriptVersion"));

This will give you:

 Informational version:     1.2.3-Demo.999+ASimpleDemoScriptVersion
 Version:                   1.2.3-Demo.999
 AssemblyVersion:           1.2.3.0
 FileVersion:               1.2.3.0
 Build system version:      1.2.3-Demo.999
 Prereleaase label:         Demo
 Is in initial development: false

To demonstate reading Git2SemVer properties and overriding/customising everything replace the code in the csx file with:

// For demonstration of concepts only

// These using statement are not necessary but may help editing
using System;
using Microsoft.Build.Utilities;
using NoeticTools.Git2SemVer.MSBuild;
using NoeticTools.Git2SemVer.MSBuild.Framework.Semver;
using NoeticTools.Git2SemVer.MSBuild.Scripting;
using Semver;   // the `Semver` library has been loading for the script to use.

// The versioning context gives the script access to:
// - All inputs and outputs.
// - API for working with semmantic versions.
var context = VersioningContext.Instance!;
context.Logger.LogInfo("Running demo Git2SemVer customisation script.");

// Demo that generated version information is accessible here
var version = context.Inputs.Version;
var buildNumber = context.Host.BuildNumber;
var branchName = context.Outputs.Git.BranchName;
context.Logger.LogInfo($"""
                        Git2SemVer provided script information:
                          Version = ${version}
                          Build number = ${buildNumber} 
                        """);

// As a demonstration, force outputs, making each (assembly, file, package) different.
context.Outputs.Version = new SemVersion(11, 12, 13).WithPrerelease("a-prerelease");
context.Outputs.InformationalVersion = context.Outputs.Version.WithMetadata("metadata");
context.Outputs.AssemblyVersion = new Version(1, 2, 3);
context.Outputs.FileVersion = new Version(4, 5, 6);
context.Outputs.PackageVersion = new SemVersion(4, 6, 7);

/*
 * Expected outcome:
 *
 *  Assembly version:       1.2.3.0
 *  File version:           4.5.6
 *  Informational version:  11.12.13-a-prerelease+metadata
 *  Nuget package version   4.6.7
 */

Configuring build system

Your build system may need to be configured to make the build number available to Git2SemVer. See Build Hosts.

Edit this page