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!
