SemanticVersion 2.0.0

.NET Standard 1.2 .NET Framework 4.5.2
There is a newer version of this package available.
See the version list below for details.
dotnet add package SemanticVersion --version 2.0.0
NuGet\Install-Package SemanticVersion -Version 2.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SemanticVersion" Version="2.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add SemanticVersion --version 2.0.0
#r "nuget: SemanticVersion, 2.0.0"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install SemanticVersion as a Cake Addin
#addin nuget:?package=SemanticVersion&version=2.0.0

// Install SemanticVersion as a Cake Tool
#tool nuget:?package=SemanticVersion&version=2.0.0

Abstract

This project aims to implement the complete 2.0 semantic versions standard as a Netstandard library. In addition to 2.0 standard features it extends the standard to allow users to specify version ranges via simple to use and know C# operators.

Description

Current implementations of the semantic versions standard available on NuGet are either implemented as full .NET projects, or old PCL profiles. In many cases the last update to the codebase was from over a year ago and an update is not likely anymore. Since full .NET versions can't be used from ASP.NET/DnxCore projects and PCLs are sometimes a bit "wonky", a implementation based entirely on the new ASP.NET/DnxCore was in order. This library aims to provide a strict implementation of the version standard with extras added on top of it. This means, that every single semantic version is also a valid version for this library, but not necessary vice versa.

An extension of the the standard includes a method to parse multiple versions from a string into a set of versions (also called: version range) and partial versions. Partial versions are mostly syntactic sugar for a version range and will be described in more detail below.

Equality

By default this library compares two semantic versions as described in the standard. This means, that 1.0.0 == 1.0.0 == 1.0.0+1234 equals to true, but 1.2.0 == 1.2.0-alpha equals to false. If a different comparison behaviour is intended a user can roll out their own implementation of the IComparer<SemanticVersion> interface and pass it to the version via the static factory method SemanticVersion.ChangeComparer. Usually it is not necessary to implement the IEqualityComparer<T> interface, since two versions are considered equal if CompareTo == 0 applies. However the reference equality comparer implements this interface, too.

Parsing

This library supports implicit casting from strings into a suitable semantic version object. Parsing via an implicit conversion will -- like the SemanticVersion.Parse method -- throw an error, if the string has the wrong format. Additionally the SemanticVersion class includes a TryParse method which returns true if the cast was successful. See the documentation for additional details. Some users might want to convert from a C# version object into an appropriate semantic version. Since a C# version object handles builds and prereleases different from semantic versions and any conversion inevitably leads to data loss, this library only supports explicit casting. With this method, the C# Build property is identical to the Patch property, whereas the Revision property is equivalent to the Build property. A Prerelease property is never set.

Version Ranges

As describes above, this implementation supports a set of versions, mainly to describe dependencies against other APIs. A goal was to make version ranges as intuitive as possible. Thus, many C# logic operators apply to version ranges. Currently the supported operators are:

  • OrElse (x || y)
  • AndAlso (x && y)
  • Not (!x)

In addition to the above operators, any equality (==/!=) and ordering (<, <=, >, >=) operators can be used to create version ranges. The syntax requires the variable to reside on the left side of the operator (i.e. x >= 1.0.0), however the variable may be omitted entirely.

If an expression has to be handled before another expression the expression can be wrapped into the ( and ) parentheses. This will raise the expressions precedence to the highest level. Nested parentheses are also possible.

Operator Precedence

All expressions in this library are left-associative, meaning if two expression with the same precedence have to be evaluated, they are looked at from left to right. Implicitly an expression with a higher precedence is evaluated before any expression with a lower precedence. The current precedence order is (high to low):

  • Parentheses
  • AndAlso
  • OrElse
  • Equality, Ordering, Not
Range parsing

Parsing a version range from a string can be beneficial on many occasions. Thus this library includes a version range parser, that parses a version range from a string into the appropriate Expression<Func<SemanticVersion, bool>>, which the user can further alter to suit his needs. In most cases the RangeParser.Evaluate method will suffice, since it compiles the expression into a usable Func<SemanticVersion, bool>, although this comes with a certain performance cost. Since the RangeParser.Parse and RangeParser.Evaluate methods throw exceptions when encountering an error, the library also includes a RangeParser.TryParse and RangeParser.TryEvaluate method.

Eamples

Example 1, Creating a version with a constructor

SemVer.SemanticVersion version = new SemVer.SemanticVersion(1,0,0, "alpha", "1234");

Example 2, Implicitly converting a string into a SemanticVersion

SemVer.SemanticVersion version = "1.0.0-alpha.1+1234"

Example 3, Parsing a version range and compare to specific version

SemVer.Parser.RangeParser parser = new SemVer.Parser.RangeParser();
Func<SemVer.SemanticVersion, bool> range = parser.Evaluate(">= 1.0.0 && < 2.0.0");

if(range(new SemVer.SemanticVersion(1,2,0, "alpha")))
    Console.WriteLine("Passed");
else
    Console.WriteLine("Failed");
Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows net7.0 net7.0-android net7.0-ios net7.0-maccatalyst net7.0-macos net7.0-tvos net7.0-windows
.NET Core netcoreapp1.0 netcoreapp1.1 netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard1.2 netstandard1.3 netstandard1.4 netstandard1.5 netstandard1.6 netstandard2.0 netstandard2.1
.NET Framework net451 net452 net46 net461 net462 net463 net47 net471 net472 net48 net481
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen30 tizen40 tizen60
Universal Windows Platform uap uap10.0
Windows Phone wpa81
Windows Store netcore451
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (10)

Showing the top 5 NuGet packages that depend on SemanticVersion:

Package Downloads
Microsoft.DurableTask.SqlServer The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Microsoft SQL service provider for the Durable Task Framework.

OpenWorkShop.MakerHub

A web-based controller for CNC & 3DP machines.

Omnia.Cloud.Models

Package Description

Neuroglia.AsyncApi.Core

A .NET library to read, write, build and validate Async API documents

MakerHub

Package Description

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on SemanticVersion:

Repository Stars
dotpcap/sharppcap
Official repository - Fully managed, cross platform (Windows, Mac, Linux) .NET library for capturing packets
Version Downloads Last updated
2.1.0 540,902 12/22/2019
2.0.0 188,423 4/9/2018
1.0.0 1,484 2/27/2016
0.5.0 1,085 1/27/2016
0.4.0 1,229 1/24/2016
0.3.0 1,411 1/23/2016