Builds and Version Control
| This article is in a draft stage.|
This article describes how to create a Build Definition and set the Version.
Using SolutionInfo.cs to Control Build Version
To allow project teams control and flexibility over version numbering, the Stack Build Process Template checks for a specific solution item named
SolutionInfo.cs. If the file does not exist, a default build version of 1.0.0.x will be used for the Build Number, and the version will not be applied to the output assemblies. We do not process or update
AssemblyInfo.cs for individual projects within a solution, so if you need to "hide" version information from the build process, simply continue to use an
AssemblyInfo.cs file for each project.
SolutionInfo.cs file is not only a method for controlling the build version, it is an excellent way to consistently apply attributes to all of the projects in your solution without having to edit
AssemblyInfo.cs for each project. You can read about the technique in Juval Lowy's book, "Programming .NET Components."
Adding SolutionInfo.cs to your solution
1. Right click the solution and choose Add > New Item.
2. For simplicity, select the Text File template and name it SolutionInfo.cs. This will give you an empty C# file. (You can also select the Visual C# Class template, name it SolutionInfo.cs, and delete the contents). By default, the file is placed in the virtual Solution Items folder, and the important thing is that this file is a solution-level item, not part of any project.
3. Add the following code to
SolutionInfo.cs, then save the file:
using System.Reflection; [assembly: AssemblyVersion("220.127.116.11")] [assembly: AssemblyFileVersion("18.104.22.168")]
Replace 22.214.171.124 with the actual version number of your product. You can generally leave the revision number (the last component of the version) as 0, but if you set a value it will be treated as the Starting Revision Number by the build server when you use the Stack Build Process Template.
Optionally, add additional common attributes to
SolutionInfo.cs. Any attributes defined here will be applied globally to your assemblies when these steps are complete (Make sure to not include any attributes that should be unique to each assembly, such as GUIDs or InternalsVisibleTo attributes). Here are a few examples you might want to use:
[assembly: AssemblyTitle("")] [assembly: AssemblyProduct("")] [assembly: AssemblyDescription("")] [assembly: AssemblyCompany("")] [assembly: AssemblyCopyright("")] [assembly: AssemblyTrademark("")] [assembly: AssemblyCulture("")]
SolutionInfo.cs to each project in the solution. Right click the project in Solution Explorer and select Add > Existing Item.
Note: Do not click the Add button yet.
|Linking SolutionInfo.cs to your project|
Instead, click the drop down arrow next to the Add button, and select Add As Link. a link to the solution-level
SolutionInfo.cs will be added to your project. The file will be treated as though it were part of the project at compile time, even though it is not actually in the project folder on disk.
As a matter of preference, you can place both the
AssemblyInfo.cs files into the Properties folder of your project. Strangely, you cannot click on the Properties folder to add an item, which means that the link you just added will always be a top-level item in your project. Make it a habit to simply drag
SolutionInfo.cs into its correct place in the Properties folder immediately after linking to the file.
AssemblyInfo.cs for each project where you added a link to
SolutionInfo.cs and remove any attributes which you moved to
SolutionInfo.cs (If you do not remove the duplicate attributes, your project will not compile).
6. Save and check in your changes.
In addition to the convenience of managing assembly attributes from a single file, any build definitions for your solution that use the Stack Build Process Template will now use the version information in
SolutionInfo.cs to determine the build version and apply the version to your assemblies.
Creating a New Build Definition using the Stack Build Process Template
1. From Team Explorer, expand your team project and right click Builds. From the pop-up menu, select New Build Definition.
|Creating a new Build Definition|
2. On the General tab, type in the build definition name. The name can be any value you want, and can even be reused across multiple team projects, but must be unique within each team project. The build definition name will be used in the Build Number label and as the drop folder name.
3. On the Trigger tab, determine what events should trigger a new build using this definition. The options of Manual, Continuous Integration, Rolling Builds, Gated Check-in, and Schedule are all explained clearly on this tab.
4. The Workspace tab defines which files will be downloaded from Source Control to build your solution(s).
Note: The more you include in the workspace, the longer your build will take, since all files in the specified path will be pulled to the build server and compared for changes from the previous build, even if they are not actually part of your solution!
You can significantly reduce unnecessary build time and improve performance on the build server by specifying only the paths in your team project that contain files required for your solution to build. For example, the .NET Stack's Daily Build configuration looks like this:
|Set Appropriate Workspace options.|
5. The Build Defaults tab lets you specify the drop folder for the output from your build. Specify the drop folder in the format
6. The Process tab is where things finally get fun. When you create a new build definition, the default, out-of-the-box TFS 2010 template is selected. Let's start by selecting the Stack Build Process Template instead. Expand the Build process template selection section by clicking the Show Details button, and selecting
|Selecting the Stack Build Process Template.|
Note: If the
StackBuildProcessTemplate.xaml is not on the list, you need to create a link to it for your project. To do this, follow these steps:
Click New... and the following dialog appears:
|Adding a link to the Stack Build Process Template.|
It is important to notice that instead of copying a XAML file, the option to Select an existing XAML file is selected. Browse to the shared template at
$/MSStack/TFS/BuildProcessTemplates/StackBuildProcessTemplate and click OK. The Stack Build Process Template will now be available for this and all future build definitions for your team project.
With the Stack Build Process Template selected, the first three sections of Process options are the same as the standard TFS 2010 template. The required section, rather obviously labeled 1. Required, is where you select the solution(s) and configuration(s) to build with this build definition. You can select multiple solutions and multiple configurations for those solutions, but only the configurations that actually exist in all selected solutions will be compiled. Also worth nothing is that in the Configuration tab, when you select configurations to build, only Debug and Release options are in the drop down list; you have to manually type in any other build configurations you have created for your project.
Below the three standard sections are two additional sections enabled by the Stack Build Process Template and the Stack TFS Build Activities.
|Build Process Parameters.|
Section 4. Deployment allows you to choose to create a deployment package each time a build is created from this build definition. When Create a Deployment Package is set to
true, a Web Deployment Package will be created and placed in a Packages folder in the build's drop location for any Web Application projects in your solution. This option has no effect if there are no web-based projects being built.
Section 5. Versioning gives you control over the way Build Versions are determined and applied to your assemblies.
Associated Build Definitions lets you define other build definitions (in the same project) which should be used to keep revision numbers in sync. In the Build Process Parameters image above, which is taken from the Stack Daily Build Definition, the Stack CI Build is listed as an associated build definition. This ensures that when the most recent Stack CI Build for the current version was 126.96.36.199, the next Stack Daily Build will be 188.8.131.52, even if only a few builds have been created with the Stack Daily Build.
Note: For this association to work properly, the Stack CI Build definition should also list Stack Daily Build as an associated build definition.
Apply File Version to Binaries updates each solution's
AssemblyFileVersionattribute to match the Build Version when the solution is compiled. The
AssemblyFileVersionis applied to the output assemblies and is available to the operating system. You can use this value to determine which version of your project has been deployed to a particular environment. You would only need to set this value to
falseif you need to manually control the File and Product version properties available to the OS. Otherwise, leave the default of
Apply Assembly Version to Binaries updates each solution's
AssemblyVersionattribute to match the Build Version when the solution is compiled. The
AssemblyVersionis applied to the output assemblies and is available to the CLR; this value can be easily retrieved from code and is used any time you make a fully-qualified reference to an assembly from another assembly. You might set this value to
falseif you are publishing a library which is often updated independently of the projects which reference it. For example, you might want to keep the
AssemblyVersionas 184.108.40.206 when deploying a patch in order to not break existing references. In that situation, Apply File Version to Binaries can be very useful in determining which patched version of your library has been deployed, even though the Assembly Version has not changed.
Note: In all cases the Apply to Binaries options are ignored if your solution does not contain a solution-level
SolutionInfo.csas described in "Using SolutionInfo.cs to Control Build Versions."
7. Save your new Build Definition. At this point, new builds for your project can be queued using this definition, or triggered using any options you set on the Trigger tab.