EonaCat.Versioning.Helpers 1.0.1

EonaCat.Versioning

Add GIT or SVN versioning inside the assemblyInfo of your product

Debug/Console Information

Build your project using:

dotnet build msbuild YourProject.csproj /v:d

or to log to a file:

msbuild YourProject.csproj -fl -flp:logfile=YourProjectOutput.log;verbosity=diagnostic

(Make sure msbuild is in your EnvironmentPath (C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin))

Installation

Just install the NuGet package EonaCat.Versioning to your .NET Framework 4.8 or .NET Standard 2.1 .NET Standard 6.0 or higher

If you’re creating a NuGet package of your project, make sure to declare this package reference as private in your .csproj so that your final package does not depend on EonaCat.Versioning.

<ItemGroup>
  <PackageReference Include="EonaCat.Versioning" Version="..." PrivateAssets="all" />
</ItemGroup>

Default behaviour for Git

If not configured, tags following semantic versioning:

{semtagver}+{chash:10}.{c:ymd}

Examples:

• 0.0.1+8dda362328.20240207
• 1.0.0+8dda362328.20240207

Default behaviour for Subversion

If not configured otherwise, the revision number is used as the patch number. You should change that before you make a release. Its format is defined as:

0.0.{revnum}

Examples:

• 0.0.1 (Default version if not or incorrectly specified)
• 0.0.20
• 0.0.200

Configuration

MSBuild properties

Configuration of the version scheme is done through MSBuild properties defined in the project file to which the NuGet package was added. If you have multiple projects in your solution, you’d basically have to repeat these steps for each project, or you could factor them out into a separate .props file and import that into each project or you can use Directory.Build.props. This also applies to classic-style projects, even though editing the project file is a bit more involved.

Revision Format example (which has version 1.0.0): <EVRevisionFormat>1.0.0+{chash:10}.{c:ymd}</EVRevisionFormat>

Project csproj Example:

<PropertyGroup>
	<EVRevisionFormat>{semtagver}+{chash:10}.{c:ymd}</EVRevisionFormat>
	<EVDefault>true</EVDefault>
	<EVInfo>true</EVInfo>
	<EVTagMatch>v[0-9]*</EVTagMatch>
	<EVRemoveTagV>true</EVRemoveTagV>
	<EVVcs>git</EVVcs>
    <EVCheckAllAttributes>true</EVCheckAllAttributes>
    <EVShowRevision>true</EVShowRevision>
</PropertyGroup>

Default version example: <EVDefaultVersion>1.0.0</EVDefaultVersion>

The following MSBuild properties are supported:

EVRevisionFormat:

The revision format template. This is automatically detected from the AssemblyInfo file in your project, if it exists. It can be overridden for .NET Core/Standard projects.

EVDefault: boolean, default: true.

Specifies whether default version attributes are resolved to the determined version. This affects Version (AssemblyVersionAttribute) and FileVersion (AssemblyFileVersionAttribute). The Version identifies the assembly and must be dotted-numeric (max. 65535). The FileVersion is saved in the Win32 file version resource and must be dotted-numeric (max. 65535). Anything that doesn’t fit into this scheme is truncated from the determined version before setting it to these attributes.

EVInfo: boolean, default: true.

Specifies whether the infor version attribute is resolved to the determined version. This affects InformationalVersion (AssemblyInfoVersionAttribute). It is a free descriptive text that may contain version names like "beta" or a VCS commit hash.

DefaultVersion:

Determines if we need to set a default version instead of the 0.0.0.1

EVTagMatch: glob pattern, default: v[0-9]*

The pattern of tag names to match when looking for version tags. These tag names usually look like "v0.1" or "v1.0.0". Other tags should be ignored for this use. This should usually not be changed.

EVRemoveTagV: boolean, default: true.

Specifies whether the "v" prefix of a matching version tag should be removed to determine its version. This should usually not be disabled.

EVVcs: string, default: "git".

Specifies the name of the VCS that is expected to be found in the project directory. Can be "git" or "svn" (IVcsProvider.Name).

EVShowRevision: boolean, default: false.

Specifies whether the determined revision ID is printed during the build with higher importance than normal, so it can be seen more easily. When patching the AssemblyInfo file, it is also displayed to the console.

EVProjectDirectory: string, default: $(MSBuildProjectDirectory).

Sets the directory where EV starts searching for the VCS files. This is helpful if EV is added to a project that is a submodule of another repository and should observe the parent repository.

EVReplaceMetadata: boolean, default: true.

Indicates whether the AssemblyMetadata attribute is processed

ChangedRepoErrorPattern: string, default: ".Release."

Determines the value of the build configuration RegEx pattern that triggers an error on match if the repository is modified

CheckAllAttributes: boolean, default: true.

Determines if we need to check all the custom attributes from the AssemblyInfo

Revision format

You can customise the format of the resulting version with a revision format string that defines how information about the commit or revision is formatted into the final revision ID. It is a plain string that contains placeholders in {curly braces}.

The following data field placeholders are supported:

{chash}: Full commit hash.

{CHASH}: Full commit hash, in upper case.

{chash:<length>}: Commit hash truncated to the specified length. (Also for upper case)

{revnum}: Revision number.

{revnum-<offset>}: Revision number minus the offset. (Also available with +)

{!}: The "!" character if the working directory is modified, otherwise empty.

{!:<string>}: The specified string if the working directory is modified, otherwise empty.

{cname}, {cmail}: Committer’s name or e-mail address.

{aname}, {amail}: Author’s name or e-mail address.

{mname}: Build machine name (computer name).

{branch}: Currently checked-out branch.

{branch:<sep>:<ref>}: Branch name, if not <ref> or empty, separated by <sep>, otherwise empty.

{semtagver}: Semantic version based on the most recent matching tag name. Revisions that are not directly tagged are considered a pre-release after the last tag (the patch value is incremented by 1) and the branch name and number of commits after the tag will be appended.

{semtagver+chash}: Semantic version based on the most recent matching tag name, see {semtagver}. Pre-releases also have the abbreviated commit hash appended after a plus (+) sign as build info. This is part of the default format for Git repositories.

{semtagver+chash:<length>}: Same as {semtagver+chash} but with the commit hash truncated to the specified length instead of the default 7.

{semtagver+CHASH:<length>}: Same as {semtagver+chash:<length>} but with the commit hash in upper case.

{semtagver:<development>}: Same as {semtagver} but with the branch name left out if it is equal to <development>.

{semtagver:<development>:+chash}: Same as {semtagver+chash} but with the branch name left out if it is equal to <development>.

{semtagver:<development>:+chash:<length>}: Same as {semtagver+chash:<length>} but with the branch name left out if it is equal to <development>.

{semtagver:<development>:+CHASH:<length>}: Same as {semtagver+CHASH:<length>} but with the branch name left out if it is equal to <development>.

{tag}: Most recent matching tag name, with additional info.

{tagname}: Most recent matching tag name only.

{tagadd}: Number of commits since the most recent matching tag.

{tagadd:<sep>}: Number of commits since the most recent matching tag, prefixed with <sep>, or empty.

{tz}: Local time zone offset like "+02:00".

{url}: Repository URL.

{copyright}: Abbreviation for the copyright year (commit or build time).

{copyright:<first>-}: Abbreviation for the copyright year range, starting at <first>. The following dash is optional but recommended for clearer understanding.

Schemes

Schemes convert a commit or build time to a compact string representation. They can be used to assign incrementing versions if no revision number is provided by the VCS. First, select from the build, commit or authoring time with {b:…}, {c:…} or {a:…}. This is followed by the scheme name. There are 4 types of schemes.

The following time schemes are supported:

Readable date/time: Produces a readable date or time string in several formats.

Prefix with "u" for UTC instead of local time zone.

Dotted-decimal: Generates regular dotted version numbers with two segments. The first describes the days since the base year, the second the number of intervals since midnight (UTC). This scheme consists of multiple colon-separated values: interval length, base year.

The interval length is a number followed by "s" for seconds, "m" for minutes, "h" for hours, or "d" for days. Practical intervals are "15m" (2 digits), "2m" (3 digits).

A shortcut to the 15-minute interval is {dmin:<year>}.

Base-encoding: Converts a linear value to a higher number base to create more compact digit/letter combinations. These schemes consist of multiple colon-separated values: number base, interval length, base year, minimum output length.

Number base can be from 2 to 36. The digits 0–9 and then letters a–z are used. The higher the base, the higher the chance that profane words appear in a revision ID. Base 28 uses an optimised alphabet without vowels and similar characters to avoid errors when hand-writing and undesired words.

The number of passed intervals since the base year is encoded for the result (UTC). The minimum length padding generates fixed-length comparable strings. Set the length to a value that lasts for as long as you plan to use this versioning scheme (30 years recommended). Practical combinations are "16:1m" (6 chars), "28:20m" (4 chars), "36:10m" (4 chars).

All letters are lower case. Use a capital {A:…}, {B:…} or {C:…} for upper case.

Hours: Generates a single number of hours passed since the given base year and month. This scheme begins with "h:" followed by two hyphen-separated values: base year, base month.

For values up to 65535 this lasts over 7 years.

Examples:

Usage in C# source code

The following sample code from the AssemblyInfo.cs file would be resolved as described.

[assembly: AssemblyVersion("0.0")]
[assembly: AssemblyInfoVersion("1.0.0{chash:10}.{c:ymd}")]

Result:

Version: 1.0.0 InformationalVersion: 1.0.0+05876ca02e+20240210

API PowerShell example:

Add-Type -Path EonaCat.Versioning.dll
[EonaCat.Versioning.Api]::GetVersion()

API Batch example:

@echo off
%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe -Command "Add-Type -Path EonaCat.Versioning.dll; [EonaCat.Versioning.Api]::GetVersion()"
exit /b %errorlevel%

VCS providers

Git (for Windows) CLI must be installed using the setup for Windows or in one of %ProgramFiles*%\Git* or in the PATH environment variable. The revision number is provided by counting revisions with the --first-parent option in the current branch. This is a stable value for the master branch if merges from other branches are done the correct way (always merge temporary/work/feature branches into master, not reverse).

SVN CLI (svn and svnversion) must be available on the system. This is included in the "CLI" option of the TortoiseSVN setup.