I’ve been working on a thing for a while now on my spare time, which hasn’t been all that much I’m sorry to say, that I got an idea for while I was writing the TeamCity meta-runner for semantic versioning, aka “the semver meta-runner”.
If you don´t know what a meta-runner is or you’d like to know how to install one, first have a look here.
Note: You can download this meta-runner from my github repo or from the JetBrains github repo.
The Idea
The basic idea is that I saw a need for the ability to being able to stamp an assembly, or multiple ones, with a version number during the build phase.
That, in .NET speak, usually means an poking around in the AssemblyInfo.cs/vb file (or files with assembly scoped attributes….e.g. [assembly: SOMEATTRIBUTE(‘SOMEVALUE’)]).
Hey wait a minute!
Isn’t this already possible via the assembly patcher build feature?
Well, yes it is…but that function lacks a few important features that I was looking for, like the ones listed below.
These where my requirements so to say:
- You should be able to use any assembly attribute (not just the “OOB” ones like AssemblyVersion and so on).
The scenario is that you have a custom attribute that you’d like to use. - You should be able to use any “AssemblyInfo” file.
The scenario is that some projects use a “global” assembly information file and link that into each project. That should be supported. - You should be able to use different versions (or values really) for the attributes if you need to.
The scenario is that you’re using a semantic version with build meta-data (e.g. 1.2.3+99) and you would like one attribute to receive the short version (i.e. 1.2.3) and another attribute to receive the long/complete version. - It should auto-detect semantic versions and apply convention over configuration in such occasion.
The scenario is that a semver like 1.2.3+99 can only be used on the AssemblyInformationalVersion attribute but the AssemblyVersion and AssemblyFileVersion attributes doesn’t support semver OOB.
Thus, it should parse the semver version and use the correct values for each of the attributes. - It should use default conventions but you should be able to change them. Convention over configuration is what I´d like to call that.
The Solution
First of all the meta-runner is built using PowerShell (v3++) and MSBuild, therefore I decided to call it PSBuild.
I know I could probably have used PSake but I decided I wanted to keep it all in one single file for now and without any external dependencies.
General Settings
Here’s a look at the general settings you can alter.
The path to the Build File is required and you just give it the path to a solution or project file to build.
Optionally you can change the Working Directory so you don’t have to give complete paths to all files from the checkout directory. Default is the checkout directory.
MSBuild Settings
Below are the MSBuild specific settings you can alter.
MSBuild Version (not necessarily the same as .NET version but they often correlate). That will along along with Bitness decides where PSBuild will look for msbuild.exe on the build server.
The default values are version 4.5 and x86.
Configuration relates to the VS configuration, and you can leave it blank to use the default.
You can specify any MSBuild property like for example the OutDir. See the example above. (key=value and separate them by semicolon).
The Arguments lets you pass along any argument that you might wish to msbuild.exe. See the example above.
Version Settings
Below are the version specific settings you can alter.
First of all you can add a global version that will apply to all attributes listed below. It supports hard-coded values or TeamCity parameters so you can insert your build version.
You can use the semver meta-runner to get you a Semantic Version to apply here if you’d like to, just remember to that one before PSBuild if that’s the case.
If you like to you also have the option to specify the attributes that will get stamped with the global version stated above. Separate them by semicolon. If you don’t add any values here the defaults will apply. They are:
- AssemblyVersion
- AssemblyFileVersion
- AssemblyInformationalVersion (only get’s stamped in case of a semver version…it will receive the complete/full version but the other 2 will get a short version if the version is a semver.)
You can of course override the global version as I’ll show you next.
Lastly, you can override the default files (all AssemblyInfo.cs files) that will be stamped with version attributes. The example above finds a file named GlobalAssemblyInfo.cs (that is a path to a file, not the name of a file).
As I told you, there’s an option to use a global version for all the attribute values. But you also have the option to say that one of the attributes should receive a custom value (usually a custom version then).
You’d just specify the name of the attribute followed by an equals sign and then the value. See the example above.
That’s it! Go play with it…
Send me, or JetBrains, a pull request if anything is missing or simply wrong (in your opinion)…
Johan Leino 