Global .NET Versioning Strategy – AssemblyInformationalVersion

August 24, 2015

Ever heard of a third (optional) versioning attribute in the AssemblyInfo files: AssemblyInformationalVersion. No? Please read!

Without a methodical (assembly) version numbering strategy, the ability to determine what changes were included in which version is lost. In my opinion, you always need to know exactly which source files went into which build and which version of the sofware is currently deployed in a specific environment. A random version numbering system creates confusion and will soon or later cause deployment risks. It will become a nightmare to fetch the exact source files to reproduce a bug from production.

All versioning of .NET assemblies that use the common language runtime is done at the assembly level. The specific version of an assembly and the versions of dependent assemblies are recorded in the assembly’s manifest. The default version policy for the runtime is that applications run only with the versions they were built and tested with, unless overridden by explicit version policy in configuration files.

Each .NET project has an AssemblyInfo file which contains an AssemblyVersion attribute and an AssemblyFileVersion attribute.

  • AssemblyVersion: this is the version number used by the .NET framework during build and at runtime to locate, link and load the assemblies. When you add a reference to any assembly in your project, it is this version number which gets embedded. At runtime, the CLR looks for assembly with this version number to load. But remember this version is used along with name, public key token and culture information only if the assemblies are strong-named signed. If assemblies are not strong-named signed, only file names are used for loading.
  • AssemblyFileVersion: This is the version number given to a file as in file system. It is displayed by Windows Explorer. It’s never used by .NET framework or runtime for referencing.

But what about this difference between AssemblyVersion and AssemblyFileVersion? Many times, I see that the same version is applied to both attributes … but why are these two (different) attributes provided by the .NET Framework? The AssemblyVersion should be the public version of an entire software application, while the AssemblyFileVersion is more the version of a specific component which may only be a small part of the entire application. The AssemblyFileVersion is the best place to put extra build version information which can be important for patching individual components of a software application.

Please follow the Semantic Versioning recommendations to dictate how the AssemblyVersion should be assigned and incremented. For the AssemblyFileVersion, I tend to include specific build information. Often, you will need to build (and test) a number of time a specific SemVer version of your software.

For example: release 1 of a software application could have the AssemblyVersion set to 1.0.0 (all components), while the AssemblyFileVersion of the individual components could be set to 1.0.15234.2 which refers to a unique build number of the build system and is linked to a particular date and a revision: “15” = year 2015; “234” = day number in 2015; “2” = second build processed that day. This also allows to later patch individual components in production with a similar AssemblyVersion (1.0.0), but a different AssemblyFileVersion (1.0.15235.1).

So, let’s try to apply this to a test project in Visual Studio and see the assembly details after building the project …

Versioning-1

Now you should be confused! Why does the Product Version display the AssemblyFileVersion and where’s the AssemblyVersion? The problem here is that a new Visual Studio project doesn’t include a third version attribute AssemblyInformationalVersion which is intended to represent the public version of your entire software application. Note that the CLR doesn’t care about this third (optional) version attribute. In short, the same Semantic Versioning rules of AssemblyVersion should be applied to AssemblyInformationalVersion.

Versioning-2

Aha! This looks much better right? Now it’s also easy to extract this metadata from your deployed assemblies and this information can be nicely listed in the about box of your software. The only issue with this approach is that the AssemblyFileVersion doesn’t include the “patch” number (Semantic Versioning) of the AssemblyVersion, but this can be ignored with the fact that the AssemblyFileVersion will be unique and can be linked to a unique build run in the build system. This way of working is my personal interpretation of how versioning can be properly applied in complex software applications and doesn’t reflect official guidelines from Microsoft. My goal here is to make software developers aware of the potential risks of not having a clear versioning strategy.

Now, forget about manually setting version information in the AssemblyInfo files and never ever release software from a local Visual Studio build. In a streamlined build process, generating unique build and version numbers are centrally coordinated. For effective troubleshooting and traceability, it’s imperative that the generated assemblies are stamped with a unique identifier that can be easily traced back to a system build number.

In a next post I will talk about how you can achieve this global .NET versioning strategy with the new build system in TFS 2015.


Deep copy of Test Cases to a TFS Team Project in another Team Project Collection

July 22, 2015

A few days ago I got stuck in a project to migrate a set of test cases from an “old” Team Project to another (new) Team Project in another Team Project Collection (TFS 2013 Update 4 environment). Via the TFS API I used the work item Copy method to perform a deep copy [including links/attachments] with the WorkItemCopyFlags set to CopyFiles.

ITestCase testCase = <MyTestCase>;
WorkItem wiCopy = testCase.WorkItem.Copy(<TargetProjectWorkItemType>, WorkItemCopyFlags.CopyFiles);
wiCopy.Save();

This always worked when copying test cases to a Team Project in the same Team Project Collection (TPC) as the original Team Project, but copying the test cases to a Team Project in another TPC always caused an error:

TF237136: File attachment was not found on attachment server.

I expected this to work, but after I verified that the MTMCopyTool also generated the same error when copying test cases across Team Projects, I decided to search for a workaround … downloading and uploading the attachments as after-processing.

DownloadUploadAttachments

Not perfect, but good enough to keep going and moving all attachments to the other Team Project in the other Team Project Collection.


Reporting Services issues after migration to TFS 2015 RC2 (from TFS 2010)

July 10, 2015

Yesterday, I blogged about the migration activities to get to TFS 2015 RC2, but I was still stuck at an error during new Team Project creation.

TeamProjectFailure

Looking into the logs it looked like there was some kind of issue during the upload of the first Reporting Services report “Bug Status” (part of the latest TFS 2015 Agile process template).

TeamProjectFailure-ReportUpload

First I thought there was something wrong with permissions on the Reporting Services site because I also applied a certificate to offer accessibility via https, but that wasn’t it. All seemed to be setup correctly. A sign to look further into the details of the Bug Status .rdl report definition and why it couldn’t be correctly uploaded to the Reporting Services site. After downloading the process template from the Team Project Collection and opening the report with notepad, I knew I was getting closer to the root cause.

DataSourceIssue

As shown in the picture above, the (default TFS 2015) Data Source mentioned in the report definition did not exist in the Report Server database after the migration from TFS 2010 SP1. In the TFS 2010 timeframe, all report defintions were linked to a “2010” Data Source.

Instead of renaming the existing Data Sources (that would break the existing reports, created from a TFS 2010 Team Project), I duplicated the entries to provide extra Data Sources with the expected names for usage with TFS 2015.

Issues resolved. Back on track!


Upgrading TFS 2010 SP1 to TFS 2015 RC2

July 9, 2015

Today I got the opportunity to upgrade a customer from TFS 2010 SP1 to TFS 2015. As blogged by Brian Harry a few days ago, the RTM release of TFS 2015 (not Visual Studio 2015!) is delayed (for a good reason!) and in order to further test the overall migration/upgrade process a new RC2 release has been made available (with go-live license). That’s the build I used today to upgrade from TFS 2010 SP1. The official installation guide is not yet available, so here are some tips to get you started in the right direction … At the customer I got 2 new servers at my disposal with a clean Windows Server 2012 R2 OS. The first server is used for the TFS Application and TFS Data Tier (Single Server Topology). The second one will be used as the TFS Build Server.

Prerequisites

Installing SQL Server 2014 Standard Edition

Before starting the installation of SQL Server 2014, I enabled the .NET 3.5 feature on Windows Server 2012 R2. OSFeature

Required SQL Server features:

SQL2014-FeatureSelection

I always recommend to use dedicated domain service accounts for running SQL Server. In this case I decided to reuse the <TFSSERVICE> account. Note that all services are set to start automatically. ServiceAccountsForSQL

SQL2014-InstallationResult

After successful installation of SQL Server 2014 I started the backup procedure on the old TFS 2010 environment and I copied all SQL .bak files to the new server for restoring all TFS related databases to the SQL Server 2014 instance. SQLDatabases

Configuration of SQL 2014 Reporting Services

Start-RS

Link to the existing restored “ReportServer” SQL Server database.

SetRSDatabase

RS-ExistingDB

RS-SelectReportServerDatabase

RS-Summary

Restore the SQL Server Reporting Services Encryption key.

RS-RestoreEncryptionKey

RS-RestoreEncryptionKey2

Run/Apply the web service and the report manager service.

RS-Webservice

RS-ReportManager

Remove the “old” server from the scale-out deployment configuration [https://intovsts.net/2014/07/14/tfs-migration-upgrade-scale-out-reporting-services-issues/] Test the Report Server website …

RS-Running

Installation TFS 2015 RC2

InstallTFS2015

trialLicense

The trial license is valid for 90 days and can be extended for 30 days. At this moment, there are no product keys available for the RC2 release.

Wizard-Upgrade

Wizard-Upgrade2

Wizard-Upgrade3

Wizard-Upgrade4

No Build Configuration yet.

Wizard-Upgrade5

Wizard-Upgrade6

Wizard-Upgrade7

Wizard-Upgrade8

Wizard-Upgrade9

Wizard-Upgrade10

No SharePoint link (yet).

Wizard-Upgrade11

Verification …

Wizard-Upgrade-Verification

Successful upgrade!

Upgrade-Success

Once the TFS 2015 RTM release becomes available, it’s only a minor upgrade to move to the official RTM bits. Interested in the release notes for TFS 2015? Check out the official news update, posted in April 2015.


Connect Visual Studio Release Management to Visual Studio Online and Microsoft Azure

November 6, 2014

Today was a very big day for developers around the world. Microsoft announced a ton of exciting news at the Connect event in New York with keynotes from Scott Guthrie, Soma Somasegar, Scott Hanselman and Brian Harry. Read more details in the Microsoft News Center: Microsoft takes .NET open source and cross-platform, adds new development capabilities with Visual Studio 2015, .NET 2015 and Visual Studio Online. On MSDN, you can now also download Team Foundation Server and Visual Studio Release Management 2013 Update 4 which offers the capability to connect Visual Studio Release Management to Visual Studio Online. Before it was only possible to connect Visual Studio Release Management to an on-premises Team Foundation Server.

I wrote a small guide to get you started with Visual Studio Release Management for Visual Studio Online and how to create an Azure Release Management environment via the (old) Azure Management Portal.

  1. Download and Install the latest bits of the Release Management Client.
  2. Configure the Release Management Client to connect to Visual Studio Online.Provide the url of your Visual Studio Online account

    image

    Hit OK and after logging in with your account credentials to VSO, the RM client should be connected to “TFS in the cloud”.

  3. Create a new Cloud Service via the Azure Portal to group all Release Management VMs.image

    image

  4. Create a new Storage Account via the Azure Portal to group all Release Management VM storage.image

    image

    Note that I have created my storage account in West Europe. Be consistent and reuse your region of choice when creating the VM(s) later. Find out more about all Azure Regions.

  5. Create new (Gallery) VM(s) via the Azure Portal in the newly created Storage Account.image

    Follow the wizard to create a new VM and don’t forget to add a HTTP endpoint …

    image

    image

  6. Download the Azure Publish Settings file to get the Management Certificate Key.To be able to complete the next step, you will need the Management Certificate key to connect from the Release Management client to your Azure subscription. There are a number of ways to get the key, but the easiest way in my opinion is to navigate to https://manage.windowsazure.com/publishsettings, log in with your Azure credentials and save the publishsettings file. Open the file with notepad and copy the full ManagementCertificate value (without quotes) in your subscription.
  7. Configure the Release Management Client to add your Microsoft Azure subscription.Navigate to the Manage Azure section in the Release Management Client and add a new Azure Subscription.

    image

    image

    Make sure to enter the Storage Account Name you have created in one of the previous steps.

  8. Create a new Release Management Environment, linked to the Azure subscription.

    Navigate to the Configure Paths tab and select the Environments link to click for a new vNext Azure environment.

    image

    Now, before you can add your VMs to an environment you must link the environment to an Azure environment via the top right button “Link Azure Environment”.

    image

    Select the Azure VM Cloud Service endpoint you want to include in the new Release Management (RM) environment and finish off by hitting the Link button.

    SNAGHTMLd6951fe

    This linking will enable you to select Azure VM machines in the RM environment. Also note that the Environment name and the MSDN Subscription have been populated (read-only), but you still need to link the Azure Servers.

    image

    Finally you can select the Azure VM which has been created in one of the previous steps. Linking this VM from this dialog window will push it in the RM environment. Save and Close to return

    image

    image

    image

With one or more Release Management environments setup, you can start defining a Release Path and once that has been setup, it will be possible to create a new (vNext) Release Template to define your deployment actions. All the appropriate Azure VMs will show up in the Release Template toolbox.

image

Enjoy connecting RM to VSO! No excuses anymore to not setup your release pipeline!

 

 

 

 


Update TFS Build Controller via Powershell

October 21, 2014

During a trial-migration of TFS, I typically prepare a lot of command-line tools to run some background update processes. Instead of writing little C# command-line applications in Visual Studio, I’m moving more and more away from Visual Studio and do stuff via PowerShell.

For a migration upgrade from TFS 2010 to TFS 2013, I have to deal with an update of the Build Controller to a new build machine/server. For a Team Project Collection of 100+ Team Projects and lots of build definitions, this is not something you want to do manually or delegate to all involved dev teams.

Instead of having to start from zero, I found this interesting post from Daniel Mann which does exactly what I want: updating the Build Controller from PowerShell via the TFS API. Except, it does it specifically for one dedicated Team Project.

So, the PowerShell script only needed a bit of tweaking to fetch all available Team Projects via the ListAllProjects method of the ICommonStructureService interface.

param(
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string]
$TfsUrl,
[Parameter(Mandatory)]
[ValidateNotNullOrEmpty()]
[string]
$NewBuildController,
[Switch]
$WhatIf
)

Function SetBuildControllerForTeamProject($TeamProject, $BuildController, $WhatIf)
{
$buildDefinitions = $buildClient.QueryBuildDefinitions($TeamProject)
$buildDefinitions | % {
Write-Host " >> Checking Build Definition" $_.Name
Write-Host " >>" $_.Name "is using" $_.BuildController.Name

if ($_.BuildController.Uri -ne $controller.Uri) {
Write-Host " >>> Setting" $_.Name "to use $BuildController"
if (!$WhatIf) {
$_.BuildController = $controller
$_.Save()
}
}
else {
Write-Host " >> Build controller is already set. Taking no action."
}
}
}

add-type -Path 'C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\ReferenceAssemblies\v2.0\Microsoft.TeamFoundation.Common.dll'
add-type -Path 'C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\ReferenceAssemblies\v2.0\Microsoft.TeamFoundation.Client.dll'
add-type -Path 'C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\ReferenceAssemblies\v2.0\Microsoft.TeamFoundation.Build.Client.dll'

$tfsUri = new-object System.Uri $TfsUrl
$tpc = new-object Microsoft.TeamFoundation.Client.TfsTeamProjectCollection $tfsUri

$buildClient = $tpc.GetService('Microsoft.TeamFoundation.Build.Client.IBuildServer')
$commonStructure = $tpc.GetService('Microsoft.TeamFoundation.Server.ICommonStructureService')
$controller = $buildClient.GetBuildController($NewBuildController)

$allTeamProjectInfo = $commonStructure.ListAllProjects()
$sortedTeamProjectInfo = $allTeamProjectInfo | sort-object { $_.Name }

foreach($teamProjectInfo in $sortedTeamProjectInfo)
{
Write-Host '************** Scanning Build Definitions in Team Project' $teamProjectInfo.Name
SetBuildControllerForTeamProject $teamProjectInfo.Name $NewBuildController $WhatIf
Write-Host ''
}

You may also use the Community TFS Build Manager (Visual Studio 2013 extension) to modify a number of Build Definitions in bulk, but for my migration scenario, I preferred to have a PowerShell script. Having this script also allows me to modify other settings in the Build Definitions … for example the Build Drop Location.

Community TFS Build Manager


Update MSBuild Toolpath in TFS build process template

October 20, 2014

I have experienced a number of migration scenarios where it was decided to first upgrade old Visual Studio 2010 solutions to the latest and greatest version of Visual Studio (VS 2013 at this moment) without forcing a TFS upgrade at the same time.

Depending on the type of included projects for the Visual Studio solution, the TFS build might not work anymore because it requires other MSBuild .targets files (related to the .NET Framework version / Visual Studio version).

The easiest way to fix your TFS build failures is to modify the TFS 2010 build process templates and explicitly set the MSBuild ToolPath variable in the MSBuild activity to the upgraded Visual Studio version.

Visual Studio 2013 => C:\Program Files (x86)\MSBuild\12.0\Bin

MSBuild