When distributing a library you often run up against versioning problems, once facet of which is simply determining which version of that library your client is running. Of course, each project in your solution has an AssemblyInfo.cs file which provides, among other things, the ability
to set the Assembly name and version number. Unfortunately, setting the assembly version here would require not only changing the version manually for each build (depending on your schedule), but keeping it in sync across all projects. There are many ways
to solve this versioning problem, and in this blog post I’m going
to try
to explain what I think is the easiest and most flexible solution. I will walk you through using MSBuild
to create a simple build script, and I’ll even show how
to (optionally) integrate with a Team City build server. All of the code from this post can be found at https://github.com/srkirkland/BuildVersion. Create CommonAssemblyInfo.cs The first step is
to create a common location for the repeated assembly info that is spread across all of your projects. Create a new solution-level file (I usually create a Build/ folder in the solution root, but anywhere reachable by all your projects will do) called CommonAssemblyInfo.cs. In here you can put any information common
to all your assemblies, including the version number. An example CommonAssemblyInfo.cs is as follows: using System.Reflection;
using System.Resources;
using System.Runtime.InteropServices;
[assembly: AssemblyCompany("University of California, Davis")]
[assembly: AssemblyProduct("BuildVersionTest")]
[assembly: AssemblyCopyright("Scott Kirkland & UC Regents")]
[assembly: AssemblyConfiguration("")]
[assembly: AssemblyTrademark("")]
[assembly: ComVisible(false)]
[assembly: AssemblyVersion("1.2.3.4")] //Will be replaced
[assembly: NeutralResourcesLanguage("en-US")]
.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, "Courier New", courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }
.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, "Courier New", courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }
Cleanup AssemblyInfo.cs & Link CommonAssemblyInfo.cs
For each of your projects, you’ll want
to clean up your assembly info
to contain only information that is unique
to that assembly – everything else will go in the CommonAssemblyInfo.cs file. For most of my projects, that just means setting the AssemblyTitle, though you may feel AssemblyDescription is warranted. An example AssemblyInfo.cs file is as follows:
using System.Reflection;
[assembly: AssemblyTitle("BuildVersionTest")]
.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, "Courier New", courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }
Next, you need
to “link” the CommonAssemblyinfo.cs file into your projects right beside your newly lean AssemblyInfo.cs file.
To do this, right click on your project and choose Add | Existing Item from the context menu. Navigate
to your CommonAssemblyinfo.cs file but instead of clicking Add, click the little down-arrow next
to add and choose “Add as Link.” You should see a little link graphic similar
to this:
We’ve actually reduced complexity a lot already, because if you build all of your assemblies will have the same common info, including the product name and our static (fake) assembly version. Let’s take this one step further and introduce a build script.
Create an MSBuild file
What we want from the build script (for now) is basically just
to have the common assembly version number changed via a parameter (eventually
to be passed in by the build server) and then for the project
to build. Also we’d like
to have a flexibility
to define what build configuration
to use (debug, release, etc).
In order
to find/replace the version number, we are going
to use a Regular Expression
to find and replace the text within your CommonAssemblyInfo.cs file. There are many other ways
to do this using community build task add-ins, but since we want
to keep it simple let’s just define the Regular Expression task manually in a new file, Build.tasks (this example taken from the NuGet build.tasks file).
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" DefaultTargets="Go" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<UsingTask TaskName="RegexTransform" TaskFactory="CodeTaskFactory" AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.v4.0.dll">
<ParameterGroup>
<Items ParameterType="Microsoft.Build.Framework.ITaskItem[]" />
</ParameterGroup>
<Task>
<Using Namespace="System.IO" />
<Using Namespace="System.Text.RegularExpressions" />
<Using Namespace="Microsoft.Build.Framework" />
<Code Type="Fragment" Language="cs">
<![CDATA[
foreach(ITaskItem item in Items) {
string fileName = item.GetMetadata("FullPath");
string find = item.GetMetadata("Find");
string replaceWith = item.GetMetadata("ReplaceWith");
if(!File.Exists(fileName)) {
Log.LogError(null, null, null, null, 0, 0, 0, 0, String.Format("Could not find version file: {0}", fileName), new object[0]);
}
string content = File.ReadAllText(fileName);
File.WriteAllText(
fileName,
Regex.Replace(
content,
find,
replaceWith
)
);
}
]]>
</Code>
</Task>
</UsingTask>
</Project>
.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, "Courier New", courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }
If you glance at the code, you’ll see it’s really just going a Regex.Replace() on a given file, which is exactly what we need.
Now we are ready
to write our build file, called (by convention) Build.proj.
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" DefaultTargets="Go" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<Import Project="$(MSBuildProjectDirectory)\Build.tasks" />
<PropertyGroup>
<Configuration Condition="'$(Configuration)' == ''">Debug</Configuration>
<SolutionRoot>$(MSBuildProjectDirectory)</SolutionRoot>
</PropertyGroup>
<ItemGroup>
<RegexTransform Include="$(SolutionRoot)\CommonAssemblyInfo.cs">
<Find>(?<major>\d+)\.(?<minor>\d+)\.\d+\.(?<revision>\d+)</Find>
<ReplaceWith>$(BUILD_NUMBER)</ReplaceWith>
</RegexTransform>
</ItemGroup>
<Target Name="Go" DependsOnTargets="UpdateAssemblyVersion; Build">
</Target>
<Target Name="UpdateAssemblyVersion" Condition="'$(BUILD_NUMBER)' != ''">
<RegexTransform Items="@(RegexTransform)" />
</Target>
<Target Name="Build">
<MSBuild Projects="$(SolutionRoot)\BuildVersionTest.sln" Targets="Build" />
</Target>
</Project>
Reviewing this MSBuild file, we see that by default the “Go” target will be called, which in turn depends on “UpdateAssemblyVersion” and then “Build.” We go ahead and import the Bulid.tasks file and then setup some handy properties for setting the build configuration and solution root (in this case, my build files are in the solution root, but we might want
to create a Build/ directory later). The rest of the file flows logically, we setup the RegexTransform
to match version numbers such as <major>.<minor>.1.<revision> (1.2.3.4 in our example) and replace it with a $(BUILD_NUMBER) parameter which will be supplied externally. The first target, “UpdateAssemblyVersion” just runs the RegexTransform, and the second target, “Build” just runs the default MSBuild on our solution.
Testing the MSBuild file locally
Now we have a build file which can replace assembly version numbers and build, so let’s setup a quick batch file
to be able
to build locally.
To do this you simply create a file called Build.cmd and have it call MSBuild on your Build.proj file. I’ve added a bit more flexibility so you can specify build configuration and version number, which makes your Build.cmd look as follows:
set config=%1
if "%config%" == "" (
set config=debug
)
set version=%2
if "%version%" == "" (
set version=2.3.4.5
)
%WINDIR%\Microsoft.NET\Framework\v4.0.30319\msbuild Build.proj /p:Configuration="%config%" /p:build_number="%version%"
.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, "Courier New", courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }
Now if you click on the Build.cmd file, you will get a default debug build using the version 2.3.4.5. Let’s run it in a command window with the parameters set for a release build version 2.0.1.453.
Excellent! We can now run one simple command and govern the build configuration and version number of our entire solution. Each DLL produced will have the same version number, making determining which version of a library you are running very simple and accurate.
Configure the build server (TeamCity)
Of course you are not really going
to want
to run a build command manually every time, and typing in incrementing version numbers will also not be ideal. A good solution is
to have a computer (or set of computers) act as a build server and build your code for you, providing you a consistent environment, excellent reporting, and much more. One of the most popular Build Servers is JetBrains’ TeamCity, and this last section will show you the few configuration parameters
to use when setting up a build using your MSBuild file created earlier. If you are using a different build server, the same principals should apply.
First, when setting up the project you want
to specify the “Build Number Format,” often given in the form <major>.<minor>.<revision>.<build>. In this case you will set major/minor manually, and optionally revision (or you can use your VCS revision number with %build.vcs.number%), and then build using the {0} wildcard. Thus your build number format might look like this: 2.0.1.{0}. During each build, this value will be created and passed into the $BUILD_NUMBER variable of our Build.proj file, which then uses it
to decorate your assemblies with the proper version.
After setting up the build number, you must choose MSBuild as the Build Runner, then provide a path
to your build file (Build.proj). After specifying your MSBuild Version (equivalent
to your .NET Framework Version), you have the option
to specify targets (the default being “Go”) and additional MSBuild parameters. The one parameter that is often useful is manually setting the configuration property (/p:Configuration="Release") if you want something other than the default (which is Debug in our example).
Your resulting configuration will look something like this:
[Under General Settings]
[Build Runner Settings]
Now every time your build is run, a newly incremented build version number will be generated and passed
to MSBuild, which will then version your assemblies and build your solution.
A Quick Review
Our goal was
to version our output assemblies in an automated way, and we accomplished it by performing a few quick steps:
Move the common assembly information, including version, into a linked CommonAssemblyInfo.cs file
Create a simple MSBuild script
to replace the common assembly version number and build your solution
Direct your build server
to use the created MSBuild script
That’s really all there is
to it. You can find all of the code from this post at https://github.com/srkirkland/BuildVersion.
Enjoy!
