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!
