What is the difference between various MSBuild version properties, such as Version, VersionPrefix, and VersionSuffix?

Building projects with MSBuild 15 and Microsoft.NET.Sdk allows users to specify half a dozen version properties. What is the difference between each of these and what is the right way to use them?

• Version
• VersionPrefix
• VersionSuffix
• AssemblyVersion
• FileVersion
• PackageVersion

And to be clear, I'm talking about "properties" as MSBuild properties that are defined in the file (as below)

<PropertyGroup>
   <Version>1.2.0</Version>
</PropertyGroup>

...or on command line as msbuild.exe /p:Version=1.2.0

Solution 1:

Also, setting these values explicitly will override the defaults.

VersionPrefix

Format: major.minor.patch

Examples: 14.2.4, 0.1.0, 99.99.99

Meaning: The normal part of the semver version number. This is used to determine the beginning of the Version value.

Default: "1.0.0"

VersionSuffix

Format: [0-9A-Za-z-.]* (arbitrary string)

Examples: alpha, beta, build0123, rc4-build201701, rc.1, rc-1

Meaning: The pre-release label of the version number. Used to determine the ending of a Version value.

Default: (empty)

Version

Format: major.minor.patch[-prerelease]

Examples: 5.3.9-beta, 0.0.1-alpha-01, 0.0.1-alpha.1, 2.0.0

Meaning: This property is the most commonly used property in user projects. Other version properties look to this value as a default. It is also used to generate the value of System.Reflection.AssemblyInformationalVersionAttribute. The preprelease value is optional.

Default: VersionPrefix if VersionSuffix is empty. VersionPrefix-VersionSuffix if VersionSuffix is not empty.

Note: setting Version explicitly will override any VersionPrefix or VersionSuffix settings.

Also, this typically follows SemVer rules. See http://semver.org/ for details

PackageVersion

Format: major.minor.patch[-prerelease]

Meaning: Used to generate the package version when producing a NuGet package from an MSBuild project.

Default: matches Version

AssemblyVersion

Format: major.minor.patch.revision

Examples: 4.5.6.2, 1.0.0.0

Meaning: Used to generate the value of System.Reflection.AssemblyVersionAttribute. The compiler uses this to determine the final AssemblyVersion value, an essential part of assembly identity. See https://msdn.microsoft.com/en-us/library/51ket42z(v=vs.110).aspx#Anchor_0

Default: matches Version without the prerelease label.

FileVersion

Format major.minor.patch.buildnumber

Examples: 1.0.0.43952, 0.1.0.0

Meaning: Used to generate the value of System.Reflection.AssemblyFileVersionAttribute. This is not required to match AssemblyVersion. It is common to add a build number to this version.

Default: matches AssemblyVersion

InformationalVersion

Format: any

Meaning: Used to generate the value of System.Reflection.AssemblyInformationalVersionAttribute. This attribute can contain any additional version information.

Default: matches Version