VersionTasks is an MSBuild Tasks library to automatically insert the current repository's changeset into your project.
The following source control systems are supported:
- Git
- Mercurial
- Team Foundation Server 2010
- Team Foundation Server 2012.
NuGet is a Visual Studio extension that makes it easy to install and update third-party libraries and tools in Visual Studio.
To install VersionTasks, run the following command in the Package Manager Console:
PM> Install-Package VersionTasks
There are three tasks to support different source control systems: GitVersionFile
, HgVersionFile
and TfsVersionFile
.
Attributes
TemplateFile
: Path of the template file to parse (Required).DestinationFile
: Path of the file to get generated from the template file (Required).WorkingDirectory
: Path to the source controled working directory (Optional).TfsVersion
: Version of the Team Foundation Server (e.g.2010 (default)
,2012
) (Optional).
All paths are relative from your project's root directory. The WorkingDirectory
attribute is only required if you are using the TfsVersionFile
task.
Examples
<GitVersionFile TemplateFile="Properties\Version.tmp" DestinationFile="Properties\Version.cs" />
<HgVersionFile TemplateFile="Properties\Version.tmp" DestinationFile="Properties\Version.cs" />
<TfsVersionFile TemplateFile="Properties\Version.tmp" DestinationFile="Properties\Version.cs"
WorkingDirectory="\" />
<TfsVersionFile TemplateFile="Properties\Version.tmp" DestinationFile="Properties\Version.cs"
WorkingDirectory="\" TfsVersion="2012" />
The template contains the placeholders, which are replaced on every build with the corresponding values from your repository. There are no restrictions on the file type or what a template needs to look like.
For example a template written in C# could look like the following:
TemplateFile: Version.tmp
using System;
public static class Version
{
public const string Changeset = "$changeset$";
public const string ChangesetShort = "$changesetshort$";
public const bool DirtyBuild = $dirtybuild$;
}
The build task will then create a file based on this template under the path and with the file name you specified in the DestinationFile
attribute. For the above example using e.g. the GitVersionFile
task a file like the following gets generated:
DestinationFile: Version.cs
using System;
public static class Version
{
public const string Changeset = "8d596df194b12b6d66baad2f16a240afbf7627d6";
public const string ChangesetShort = "8d596df194";
public const bool DirtyBuild = false;
}
Note that you can add this generated file to your solution - if you need it to be compiled - but you don't want to add it to your version control. This file will be different with every new changeset.
Placeholders
$changeset$
: Changeset of the repository.$changesetshort$
: Shortened changeset of the repository.$dirtybuild$
: Indicates a dirty build.true
if there are uncommitted changes; otherwise,false
.
All placeholders are delimited using dollar signs ($) and are replaced with the currently checked-out repository's values. Note that Team Foundation Server's shortened changeset will be the same value as the changeset due to its increased number format.
If you want to see everything working together dig into this small console application sample.
The setup is currently not fully automated via NuGet - I'd love to do so when I find the time. Therefore some simple steps are necessary to get it up and running after the package is installed. Don't be scared, it's a piece of cake:
-
In Visual Studio add a new text file to the root of your project - or wherever you want, but stick with me here - and name it
Version.tmp
. Insert the placeholder$changeset$
into that file and save it.
Tip: If you have multiple projects in your solution you probably want to pick the most generic one (e.g. Common, Core). -
In Solution Explorer right-click the project and select Unload Project. If it has been unloaded it should be designated as (unavailable). Right-click the project again and select Edit ProjectName.
-
The project will open as an XML document in your editor. Scroll to the the end of the document where you'll most likely see something like the following code:
<!-- To modify your build process, add your task inside one of the targets below and uncomment it.
Other similar extension points exist, see Microsoft.Common.targets.
<Target Name="BeforeBuild">
</Target>
<Target Name="AfterBuild">
</Target>
-->
- Edit this section to the below code. Note that we added the import
VersionTasks.targets
, uncommented theBeforeBuild
target and added theHgVersionFile
task to be executed before build. Change this task appropriately toHgVersionFile
orTfsVersionFile
if your repository is not using Git as source control system:
<Import Project="..\packages\VersionTasks.*\tools\VersionTasks.targets" />
<Target Name="BeforeBuild">
<GitVersionFile TemplateFile="Version.tmp" DestinationFile="Version.txt" />
</Target>
<!-- To modify your build process, add your task inside one of the targets below and uncomment it.
Other similar extension points exist, see Microsoft.Common.targets.
<Target Name="AfterBuild">
</Target>
-->
-
When you're done right-click the project again and select Reload Project.
-
Build your project - that's where all the magic is happening.
-
In the Solution Explorer enable Show All Files and click Refresh. You should see a new file
Version.txt
in the root of your project. Open that file and you should see the current changeset of your repository. Et voilĂ !
If you found this project useful you can follow me on Twitter (@martinbuberl) or buy me a beer.
VersionTasks is released under the MIT license.