CODEWITHSUNDEEP
c#.netmsbuild
natemcmaster
natemcmaster

Reputation: 26773

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?

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

Upvotes: 61

Views: 11237

Answers (2)

Greg Gum
Greg Gum

Reputation: 37909

I would like to expand on the answer which was already given above to Visual Studio. If you got here because you were wondering how this all works in Visual Studio 2022 (and earlier), this is a short explanation as I could not find any official docs on the matter.

If you create a .net core Console app, and go to Project Properties, you will see a section "Package --> General" that covers versioning. It is populated with default values which are shown beneath each element.

Here is a screenshot of one of the elements with it's default value. So what is "$(VersionPrefix)"? As discussed above, it is one of the properties that can be set. But note there is no place in the UI to set this, but you can set it directly in the project file by editing it.

enter image description here

So let's do that now:

enter image description here

After saving the file, you now see the following:

enter image description here

But that's not really very useful for a version number. So lets add a Suffix to the project file.

<VersionSuffix>5-beta</VersionSuffix>

But now the version looks like this:

enter image description here

But that's not really what we want, so lets add a version number to the center:

enter image description here

And this give us this in the file explorer:

enter image description here

So, to recap: The UI is just writing to the Project File. No magic there. But how does it get consumed from the project file? Well, actually, there is a file being created in the background called .AssemblyInfo.cs. It looks like this:

[assembly: System.Reflection.AssemblyCompanyAttribute("ConsoleApp2")]
[assembly: System.Reflection.AssemblyConfigurationAttribute("Debug")]
[assembly: System.Reflection.AssemblyFileVersionAttribute("2.3.5.0")]
[assembly: System.Reflection.AssemblyInformationalVersionAttribute("2.3.5-beta")]
[assembly: System.Reflection.AssemblyProductAttribute("ConsoleApp2")]
[assembly: System.Reflection.AssemblyTitleAttribute("ConsoleApp2")]
[assembly: System.Reflection.AssemblyVersionAttribute("2.3.5.0")]

And that file is being consumed by the compiler when the project is compiled.

If you wanted to, you could skip all of the UI and project files, and just create the AssemblyInfoFile directly. But when you do that, you lose the VersionPrefix and VersionSuffix functionality and you have to do it manually.

Upvotes: 9

natemcmaster
natemcmaster

Reputation: 26773

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

Upvotes: 88

Related Questions