Versioning .NET Core Assemblies in Azure DevOps isn’t Straightforward (and Probably Won’t be in Other CI/CD Tools Either)
As part of ongoing work to enhance an existing Azure DevOps CI/CD pipeline that builds and deploys an ASP.NET Core application I thought I'd spend a pleasant 5 minutes versioning the .NET Core assemblies with the pipeline's build number. A couple of hours and 20+ test builds later...
Out of the box, creating a new build in Azure Pipelines using the ASP.NET Core template in the classic editor results in five tasks of which four are concerned with dotnet commands:
A quick look at the documentation for dotnet build and then this awesome blog post that explains the dizzying array of options and it's pretty clear that adding /p:Version=$(Build.BuildNumber) as a command line parameter to dotnet build should suffice as a good starting point. Except it didn't, with File version and Product version stubbornly remaining at their default values:
I established that /p:Version= works fine from a command line, so what's going on? After a bit of research and testing I discovered that unless you tell it otherwise dotnet publish (and dotnet test for that matter) compiles the application before doing its thing of publishing files to a folder. The way the Azure Pipelines tasks are configured means that dotnet publish is effectively cancelling out the effect of dotnet build. (And since dotnet test also cancels out out the effect of dotnet build leaves me wondering what is the point of including dotnet build in the first place?) As part of this research I also discovered that build, test and publish also do a restore unless told otherwise, again making me wonder what the point of the Restore task is? So out of the box then it seems like the four .NET Core tasks are resulting in lots of duplication and for someone like me the cause of head-scratching as to why assembly versioning doesn't work.
So based on a few hours of testing here is what I think the arguments of the different tasks need to be (for visual tasks or as YAML) to avoid duplication and implement assembly versioning.
Firstly, if you want to include an implicit Restore task:
- build = --configuration $(BuildConfiguration) --no-restore /p:Version=$(Build.BuildNumber)
- test = --configuration $(BuildConfiguration) --no-build
- publish = --configuration $(BuildConfiguration) --output $(Build.ArtifactStagingdirectory) --no-build
Secondly, if you want to omit an explicit Restore task:
- test = --configuration $(BuildConfiguration)
- publish = --configuration $(BuildConfiguration) --output $(Build.ArtifactStagingdirectory) /p:Version=$(Build.BuildNumber)
In the first version build creates the binaries which are then used by test and publish, with the --no-build switch implicitly setting the --no-restore flag. I haven't tested it but that presumably means that --configuration $(BuildConfiguration) for test and publish is redundant.
Update A friend and former colleague Tweeted that --configuration is still needed for test and publish:
In the second version test and publish both create their own sets of binaries. (Is that the right thing to do from a purist CI/CD perspective? Maybe, maybe not.)
I did my testing on a Microsoft-hosted build agent and whilst it felt like both options above were quicker than the default settings I can't be certain without rigorous testing on a self-hosted agent with no other load. Either way though, it feels good to have optimised the tasks and I finally got assembly versioning working. Are there other optimisations? Have I missed something? Please leave a comment!
Cheers -- Graham
Git with Visual Studio 2015 and TFS 2015
If you work in an organisation that has a longstanding investment in TFS chances are that you haven't done much with Git. This is because when you create a new team project in TFS you have to choose the version control system you want to use and once chosen that's it -- no changing your mind. (This was correct when I first started writing this post but things are changing as I mention later.) If your projects were created a few years ago either Git wasn't an option back then since it only became available in early 2013 or you may have thought it was just too new and shiny to consider for use with TFS, and very likely these projects use Team Foundation Version Control (TFVC).
That has all changed now and Git is firmly embedded in TFS. In fact Git seems to be firmly embedded everywhere, not least at Microsoft where open source projects are being hosted on GitHub and internal teams are using Git via Visual Studio and TFS. Keen to understand what all the fuss is about I've been learning about and using Git over the past few months and the recent release of Visual Studio 2015 and TFS 2015 seemed like a good time to share some of my experiences. As always when learning something new I recommend taking some time to do some training and to that end I have a Getting Started blog post here where I've compiled what I think are the most useful resources for Visual Studio developers.
The Bigger Picture
Before getting in to the tooling I want to take a step back and say a few words about the big picture because if you want to start using Git and already have a team project based on TFVC you have some thinking to do. When I first started writing this post moving to Git would have meant creating a new Team Project based on Git and either starting from scratch or importing history and / or work items from the TFVC-based project. There are some resources that offer help in this regard and I've compiled a short list to help anyone contemplating a migration understand what's involved:
I haven't tried to perform a migration and with luck I won't have to, since Microsoft recently announced support for creating a Git repo in a TFVC project. It looks like this will ship with TFS 2015.1 although quite what we'll get in practice remains to be seen. If you want to know more there is some commentary here.
Trying this at Home
For this post I used TFS 2015.RTM and Visual Studio 2015.RTM. If you don't have access to TFS 2015 then you can follow along using VSO since features in TFS tend to appear first in VSO, although some of the screenshots in this post may be slightly different. If you are new to VSO I have a Getting Started post here, however be aware that a key difference compared with TFS is that you create a new team project in the VSO web portal.
Whilst writing this post I encountered what seemed to be a bug in Visual Studio and in my description of how I fixed it I talk about dropping to the command line. For this you'll need to have Git installed and the easiest route is probably to get it from Chocolatey. The Install and Configure Git video in this MVA series has a step-by-step walkthrough.
Getting Started
The first step to working with Git in TFS is to create a new Team Project based on Git. In Visual Studio connect to the Team Collection where you want to create the new project and in Team Explorer navigate to Home and then click on Home (or use the down arrow button) to display the Home menu. The ability to create a New Team Project is available under Projects and My Teams:
Navigate through the wizard and ensure you choose Git at the Specify Source Control Settings page:
With the new project created (I called mine ContosoUniversity and used the Scrum process template) you will need to clone the repository before you can do much else. Team Explorer helpfully prompts you to do this:
Some people like to clone to a folder created off the root of a drive (possibly to avoid maximum path length issues?) but I accepted the offered default of C:\Users\Graham.ALM\Source\Repos\ContosoUniversity. If you examine the folder that is created you'll see that it is empty, although in reality there is a hidden .git folder. I don't like placing code files in my repo until it contains the .gitignore and .gitattributes files and Visual Studio has a neat feature for adding these. In Team Explorer navigate to Home and then choose Settings. In the lower Git panel choose Repository Settings. This pane allows you to add the the .gitignore and .gitattributes files as well as alter other aspects of the repo (not all details shown):
The great thing about the .gitignore file that Visual Studio adds is that it's tuned for Visual Studio development. It's the small things...
This is a good time perform a commit, so choose Changes from the Team Explorer menu bar and notice that you are requested to Configure your user name and email address before committing changes. Defaults are taken from the current TFS connection -- edit as required, optionally choose to Enable download of author images from 3rd party source and click Update. Now head back to Changes, enter a commit message and click Commit.
Bear in mind that at the moment we have only committed locally and the TFS knows nothing about the changes. Before pushing any changes to TFS let's get a Visual Studio solution added. I used my ContosoUniversity solution which you can download here. After unblocking and unzipping it copy the contents of the folder that contains the solution file and project folders to the root of your repo. Switching back to Visual Studio and the Team Explorer Home panel and you should see that the Contoso University solution file is listed under Solutions:
Now navigate to the Changes panel and notice that there are Untracked Files:
Click on Add All to move these files to Included Changes, add a suitable comment and Commit the change. Back at the Home panel you can now open the solution. If you are opening the solution on a machine with only Visual Studio 2015 installed you might get a warning about LocalDB versions. You can ignore this but if you want to run the application do update the connection strings in CU-DEV.publish.xml in ContoUniversity.Database and Web.config in ContosoUniversity.Web with (localdb)\MSSQLLocalDB as per this post.
Whilst editing CU-DEV.publish.xml you will likely see that it is being ignored by Git. We do want this file to be included in version control as it's how new developers can quickly publish the database to LocalDB. Right-clicking the file shows Add Ignored File to Source Control which looks promising so let's try that. Navigating to Team Explorer -- Changes you'll see that there is a change and you can add a commit message and commit the change. Except you can't, or at least I couldn't:
The situation here seems to be a standoff between .gitignore which is indicating that CU-DEV.publish.xml should be ignored and Visual Studio which is honoring our desire to add the file. The fix was to drop to the command line and to open a command prompt at the root of the repo and run git add ContosoUniversity.Database\CU-DEV.publish.xml -f. This forces the file to be added against .gitignore's wishes. Presumably the problem is that Visual Studio is not using the -f switch. One to report...
The final task for this section is to publish the local changes to TFS. If you want proof that no code has been pushed to TFS yet you can open the project in the TFS Web Portal and navigate to the Code tab. You'll see something like this:
In Visual Studio Team Explorer -- Synchronization you use the Push link to publish Outgoing Commits to TFS:
I've not shown it here but refreshing the Code tab of the TFS Web Portal will now display your code along with the latest comment for each file and folder.
Pull Request Workflow
One aspect of the Git integration with Visual Studio and TFS that I particularly like is the pull request workflow since it lends itself very well for code reviews. To evaluate this for yourself the first step is to set up a branch policy to ensure that the pull request workflow cannot be circumvented. From the TFS Web Portal make sure you are somewhere in your team project and open the Control Panel (cog icon on the right of the blue bar). Navigate to the Version Control tab and then in the Git repositories panel expand the tree until the required branch is highlighted -- master in my case. Now click on Branch Policies in the right-hand panel and as a minimum check Require code reviews using pull request. You'll probably also want to check Allow users to approve their own changes if you are only using one account for the evaluation.
As you can see from the screenshot there are more options and you can find details here. I'm keeping things simple and with the changes saved it's time to head back to Visual Studio to see what's different. As a quick test, make a simple change to a file and commit to master (remember this is just your local copy). Now try and push the change to TFS. You should get an Errors encountered during push. See the Output window for details. message. In the Output window you should see a The following errors were reported during push: refs/heads/master, TF402455: Pushes to this branch are not permitted; you must use pull requests to commit changes. message.
The starting point to create a pull request is to create a branch from master. In Team Explorer -- Branches right click master and select New Local Branch From. In the panel that is now displayed type a name for the branch and click Create Branch.
This new branch is now shown in bold and is considered checked out. Make another simple change to a file and commit it and then in Team Explorer -- Synchronization click Publish to publish the branch and push both the change that was just made to the new branch and the earlier change to master.
The workflow now switches back to TFS Web Portal and in either Code > Explorer or Code > Pull Requests there should be a button to Create Pull Request:
Slightly confusingly this button doesn't do what it says but rather displays the Pull Requests panel with options to configure aspects of this pull request. In particular there is a more options link that does give you more options:
The changes you can make are all fairly obvious although I didn't make any. (Do note the existence of the New Pull Request link which allows you to configure your own pull request.) From this panel the Create Pull Request link does what you expect it to do.
The pull request as created above will sit in the Assigned to the team list of pull requests:
When a particular pull request is selected the panel allows comments to be made as a Discussion, right in the Files that have changed or against Commits. It's quite a busy window and there's a lot going on since it's also the place where Reviewers are selected and can indicate their approval decision:
In my case above there were no merge conflicts so once I'd marked my approval I could click the Complete pull request button. This then morphs in to a Delete source branch button to allow you to get rid of the source branch which for most teams is probably the right thing to do since you want these to be short lived.
Back in Visual Studio and your local repo, master hasn't got the latest changes and the short-lived branch created for the pull request is still hanging around. To fix all this up, in Team Explorer -- Branches double-click master so it's checked-out. Then navigate to Team Explorer -- Synchronization and use the Pull link to bring the changes to down to master. Finally back in Team Explorer -- Branches right-click the short-lived branch and delete it.
Tour Finishes Here
That's as far as I'm planning to cover in this post but obviously there's lots more I could have covered -- resolving merge conflicts for example. Whilst I like the pull request workflow a colleague pointed out that it could lead to Scrum team members working in silos and a presentation at this year's Agile on the Beach conference made the point that pull request workflows can have a negative effect on effective continuous integration. Whilst important and valid points these are probably people and process problems and if they are going to happen with Git they are probably already happening with TFVC shelvesets.
Cheers -- Graham
Upgrading a TFS 2013 Continuous Delivery Platform to TFS 2015
In a previous post I described the high-level process for upgrading the continuous delivery platform I've been using for my Continuous Delivery with TFS blog post series to TFS 2013 Update 5. With the release of TFS 2015 on 6 August 2015 it's now time to upgrade this platform to the brand new version. See my previous post for the list of servers that participate in my continuous delivery platform, and as with the upgrade to TFS 2013 Update 5 all servers had been patched with the latest Windows Updates.
Team Foundation Server
There is a wealth of advice for upgrading to TFS 2015 and if you are upgrading a production instance you'll probably want to do some research. A good starting point is the ALM Rangers' TFS Upgrade -- New Elements of TFS 2015 that influence an upgrade. I can also recommend listening to Radio TFS episode 95 -- Out and About with TFS 2015, and don't forget to check out the show links.
Since I was upgrading a non-production instance I dove straight in, mounted the iso and started the setup routine. After installing the bits the Upgrade Wizard started automatically and as with previous upgrades each page of the wizard was straightforward.
One addition to the wizard is a page to configure the new Team Foundation Build. Although in the fullness of time anyone upgrading will want to move to the new build system it is quite likely that you will need to keep existing XAML builds running as you gradually move over. This is fully supported but you will need to enable this from the Team Foundation Server Administration Console under Additional Tools and Components > XAML Build Configuration. The good news is that settings from the previous version of TFS are remembered. You can read the release notes for TFS 2015 here and the list of known issues here.
Visual Studio
Although TFS 2015 is backwards compatible with some prior versions of Visual Studio many teams are likely to want to move to Visual Studio 2015 at the same time as moving to TFS 2015. Visual Studio 2015 installs side-by-side with previous versions and whilst the installation process is straightforward there are some other things to consider since the installation routine now offers third party products as well as the ability to select just the Microsoft components you require. I chose to keep things light but did take the opportunity to install PowerShell and Git-based components as they are areas I want to explore for future blogs.
As a test of Visual Studio 2015 I opened up my Contoso University sample application (previously created in Visual Studio 2013) and the only issue was with the SQL Server Database Project whose connection string was referring to a previous version of LocalDB. This was a quick fix as per Bill Wagner's post -- don't forget to update Web.config as well if this affects you. Whilst Contoso University worked fine locally, running an existing XAML build on the new TFS 2015 instance wasn't quite as successful and partially failed with TF900547: The directory containing the assemblies for the Visual Studio Test Runner is not valid ‘C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\CommonExtensions\Microsoft\TestWindow'. I'd pretty much expected something like this since I hadn't installed Visual Studio 2015 yet on my all-in-one TFS machine which hosts the build agent, and performing the install (Microsoft components only) fixed this problem. (As an aside, I always make sure Visual Studio instances on a build agent server are registered with a licence key to avoid trial period expiry problems.) You can read the release notes for Visual Studio 2015 here and the list of known issues here.
Release Management
As discussed in my previous post there was no Update 5 to Release Management 2013 and instead Release Management 2015 was released and is backwards compatible with TFS 2013. Since I'd already upgraded to Release Management 2015 there was nothing much for me to do except test that the build definition that started my release pipeline still worked -- which it did! However, the automated web tests part of the pipeline (based on the MTM Automated Tests Manager tool) was still running against 2013 Agents and Microsoft Test Manager 2013 and naturally I wanted to get these components upgraded.
Microsoft Test Manager and Agents for Visual Studio
Microsoft Test Manager 2015 (aka Test Professional 2015) is installed as part of Visual Studio 2015 Enterprise however it is also available as a separate installation for testers who don't use Visual Studio or where it is needed to run the bundled tcm.exe. The latter scenario applies to me as I have a Windows 8.1 web client machine that runs automated web tests written using Selenium that require FireFox, Microsoft Test Manager and Agents for Visual Studio (Test Agent component) to be installed. I upgraded this machine (please keep reading as most of what I did was unnecessary) by first uninstalling Microsoft Test Manager 2013 and the Agents for Visual Studio 2013 and then installing and configuring the 2015 replacements. One key difference was that at the time of writing there was no upgrade to the Test Controller component of the Agents for Visual Studio 2015 so the Test Agent was shipping as a standalone exe. However, when I came to configure the Test Agent there was no Test Agent Configuration Tool for Agents for Visual Studio 2015. No matter since I knew it would be possible to partially configure the agent from Microsoft Test Manager 2015 (Lab Center > Environments and then choose to repair). However, all this did was install Agents for Visual Studio 2013. (Note that when it does this the service will run under Network Service. If you want to use a domain account you need to use the Test Agent Configuration Tool on the machine where the test agent is installed.) So a lot of work for nothing and it looks like we'll need to wait for a new Test Controller before the Test Agent can be upgraded.
Last Piece of the Puzzle
I wasn't done yet, since I upgraded Microsoft Test Manager on the web client and it turns out that the PowerShell script that forms part of the MTM Automated Tests Manager tool in Release Management 2015 hasn't been upgraded to work with the Visual Studio 2015 installation path. The proper way to fix this would be to create a new tool in Release Management (since the built-in tools can't be edited) with an updated script that includes a reference to the VS140COMNTOOLS system environment variable which allows the script to locate tcm.exe. Since I'm due to retire my current continuous delivery infrastructure in the near future (as I prepare for a new blog post series based on TFS2015 Update 1 which should contain the new web-based Release Management) I opted for the quick and dirty trick of pointing the VS120COMNTOOLS system environment variable to C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\Tools\. Probably not something for a production environment but good enough to get my automated web tests working and showing green. Always a relief...
Cheers -- Graham
Upgrading a TFS 2013 Continuous Delivery Platform to Update 5
For both Microsoft and .NET developers alike 20 June 2015 was a big day, with a huge raft of updates being released. Whilst the headline news was Visual Studio 2015 (TFS 2015 missing the original launch date because of quality issues) there was also an Update 5 release for Visual Studio 2013 and TFS 2013. Whilst I'm sure Microsoft would love everyone to move to TFS 2015 very quickly for many organisations this isn't a possibility for a variety of reasons. On the other hand, an upgrade to Update 5 may well be following a well-trodden path and a more realistic next step in the upgrade cycle.
I decided to upgrade the Azure-based TFS 2013 continuous delivery platform I've been using for my Continuous Delivery with TFS blog post series to Update 5 as it's one option we're considering where I work. However when I stopped to think about what was involved I realised that it amounted to quite a few upgrades. I've documented the high-level process I followed in case it helps anyone else considering this route.
Server Landscape
My setup in Azure is focussed on conserving the Azure credits I get with MSDN rather than creating a typical TFS environment, so I have fewer servers than might otherwise be present in a live environment. My setup comprises:
- Active Directory Domain Controller running Windows Server 2012 R2.
- All-in-one TFS server (including SQL Server 2012 SP2) running Windows Server 2012 R2.
- Development machine for Visual Studio, Release Management Client, Microsoft Test Manager and the like running Windows 8.1.
- Application web server (for IIS) running Windows Server 2012 R2.
- Application database server (for SQL Server 2012 SP2) running Windows Server 2012 R2.
- Application client machine (for FireFox and Microsoft Test Manager) running Windows 8.1.
All machines were patched with the latest Windows Updates and the TFS ecosystem components were all at Update 4.
Team Foundation Server
Because I have an all-in-one machine for TFS that was the only box that needed the new version, however if you have build controller and build agent machines (and there are other variants) don't forget you will need to upgrade these machines as well. I have upgraded TFS many times and always found it to be a very slick, the wizard-driven process being very intuitive. However, if you are upgrading your live environment then do take all the usual upgrade precautions of having backups available and so on. Don't forget that the process involves uninstalling the current version of TFS (the databases are not affected) and then installing and configuring the new version, although the installer takes care of all of this. You can read the release notes here and the list of fixed bugs and known issues here.
Visual Studio
Whilst it's pretty obvious that you will have Visual Studio installed on your development machine(s) it's easy to forget that you probably have it installed on the machines running your build agents as this is the easiest way to ensure a build agent server has all of the bits needed to compile your application. This can add up to quite a few servers in a live environment but in my case I only had two instances. Update 5 for Visual Studio 2013 updates an existing instance of Visual Studio and the upgrade -- as usual -- was uneventful. One thing I did do after upgrading both versions of Visual Studio was check for any new versions of extensions (Tools > Extensions and Updates). The extensions that seemed most critical were an update to NuGet, the latest version of the Microsoft Azure SDK and the latest release of the SQL Server Data Tools.
Since there was an update to NuGet I also ensured that the version of NuGet used by TFS Build was updated, as this is not the one installed as the Visual Studio extension. The procedure is to open an Administrative command prompt at C:\Program Files\Microsoft Team Foundation Server 12.0\Tools and run nuget.exe update -self. You can read the release notes for Visual Studio 2013 Update 5 here and the list of fixed bugs and known issues here.
Release Management
The Release Management situation might seem confusing at first because there is no Update 5 for Release Management 2013 however there is a Release Management 2015 release. This 2015 release is fully compatible with TFS 2013 and is the upgrade to go for if you want the current latest and greatest. It's worth mentioning here that TFS 2015 Update 1 will ship with an all-new browser-based release management service which will presumably eventually replace the current offering so it's worth bearing this in mind if you are considering starting a new project with the Release Management 2013 / 2015 tooling.
There are three separate components to Release Management: server, client and deployment agent. As with TFS the existing components need uninstalling (the database is unaffected) before the new ones are installed, however unlike TFS the installer doesn't do this for you and it's a manual process. During the installation process for all components it amusingly looks like you are forced in to joining the customer experience program which is greyed-out and can't be unchecked:
As it turned out it was possible to change this when configuring each component -- possibly important if your servers don't have access to the Internet.
There is only one installed instance of the server component of course and for me this lives on my all-in-one TFS server. I have the client installed on my all-in-one TFS server and my development machine and the deployment agent on my three application machines. It's a few minutes' work to get all this upgraded and it's not helped by the components not remembering any of their previous configuration settings (with the exception of the server component that remembered a couple of them).
Whilst the upgrade process was successful the initial testing wasn't, and the release part of the build process kept returning an Exception Message: The directory name is invalid (type Win32Exception) error. I eventually traced this to an updated ReleaseTfvcTemplate.12.xaml template that shipped with Release Management 2015. Fixing this involved copying this file from C:\Program Files (x86)\Microsoft Visual Studio 14.0\Release Management\Client\bin to the BuildProcessTemplates folder of my Team Project workspace and checking the file in. I then cloned an existing (but failing) build definition and upgraded the template in Process > Build process template. The reason for cloning is that I've edited my build process template so when I get some time I'll need to fix the template in the original build definition. If you go down the cloning route do make sure you remove any spaces from the build definition name (otherwise automated tests run via tcm.exe are unlikely to run) and also update the properties of the Release Management template with the new build definition name or nothing will run. Don't ask me how I know.
Microsoft Test Manager
Although there is an Update 5 for Microsoft Test Manager 2013 it's not immediately obvious how to apply it since as far as I know there is no separate standalone installer for Microsoft Test Manager. Rather, if Microsoft Test Manager 2013 was installed at the same time as Visual Studio 2013 it will be upgraded to Update 5 when you upgrade Visual Studio. If you installed Microsoft Test Manager separately -- on a Web client machine for example -- then one way to upgrade is to use the Updates link on the home screen:
All this really does though is start the Visual Studio 2013 Update 5 installer so feel free to use that if you have a copy handy. Please don't miss upgrading standalone versions of Microsoft Test Manager as I have seen nasty bugs when using the recording tools on an outdated version against an upgraded TFS instance.
Agents for Visual Studio
Last but not least is ensuring that any test controller or test agent services are upgraded. My test controller is on my all-in-one TFS server and upgrading was just a case of running the exe from the TestController folder of the mounted iso. A reboot was required after which it's necessary to run the Test Controller Configuration Tool. The settings hadn't been remembered so make sure you have these handy before upgrading.
You need the test agent installed anywhere you are running tests or collecting metrics and for me this was my Web client machine and my application Web server which I'd previously configured for Test Impact Analysis. The iso contains an exe in a TestAgent folder and this starts a configuration mini wizard which again doesn't remember previous settings. You'll probably find that after upgrading the environment that the machine running the test agent has errors so you'll need to go to Microsoft Test manager and repair the environment from Lab Center > Lab > Environments.
Final Thoughts
Although I encountered relatively few glitches with this multi-machine upgrade it took a good few hours to accomplish over several days. Having the iso files already downloaded from MSDN and copied a media library was a big time saver as was knowing what was installed on which server. My continuous delivery platform is now in good shape to be upgraded to TFS 2015 soon after the RTM is available. As always, please share your own experiences in the comments!
Cheers -- Graham
Upgrade TFS 2013 Reports
For some organisations the Stakeholder licence that was introduced for on premises TFS 2013 with Update 4 probably means that an increasing number of individuals are interacting with TFS. Inevitably this leads to more people asking the question "What reports can we have?".
Most TFS administrators will of course know that TFS ships with reports written for SQL Server Reporting Services (SSRS) out of the box. What might be less obvious is that the reports were updated with TFS 2013 Update 3. There is a gotcha though, in that reports that have already been deployed for existing projects do not get upgraded. However, help is at hand with a utility that can upgrade deployed reports. In this post we look at the steps to run the utility, which will upgrade TFS 2013 reports associated with Team Projects created in TFS 2012 through to TFS 2013 Update 2. Team Projects created after Update 3 was installed will of course already be on the new version.
Overview
The process isn't complicated but it's worth explaining the big picture. The TFS Reporting Bulk Update Tool is a PowerShell script that takes the URI of a Team Collection as its parameter and, in conjunction with Team Project process templates, creates a file that contains a Team Foundation Power Tool Command Line (tfpt.exe) command that actually performs the upgrade. The process can be performed on a developer workstation with http(s) access to TFS but appropriate permissions will obviously be required.
Prerequisites
Procedure
- On the machine where you will perform the process create a working folder eg C:\ReportUpdate.
- Download, unblock and unzip ReportingBulkUpdateToolForTfs2013.ps1 to this folder from its location on CodePlex.
- Download the process template(s) that have been specified for the Team Projects in the Team Collection you are upgrading:
- In an instance of Visual Studio that is connected to the Team Collection navigate to Team > Team Project Collection Settings > Process Template Manager.
- In the Process Template Manager dialog download whichever templates are in use in the Team Collection to C:\ReportUpdate:
- Open up PowerShell ISE (or other PowerShell editor of choice) as Administrator and change directory to the working folder.
- Construct and run a PowerShell command based on ReportingBulkUpdateToolForTfs2013.ps1 appropriate to the Team Collection you are working against, for example:
|
|
.\ReportingBulkUpdateToolForTfs2013.ps1 -ProjectCollectionUri "http://almtfsadmin:8080/tfs/PrmCollection" |
- If there were no errors the preceding command should have created BulkUpload.cmd in C:\ReportUpdate. This can now be run from the PowerShell command line using Invoke-Item .\BulkUpload.cmd.
- You can verify if the update was successful by navigating to the SSRS report portal in a browser (something like this: http://almtfsadmin/Reports/Pages/Folder.aspx?ItemPath=%2fTfsReports%2fPrmCollection%2fContosoUniversity) and switching to Details View:
- In Details View you can examine the Modified Date column which should show the date and time you ran BulkUpload.cmd. Of course, whether anything actually changed will depend on whether the reports were created before TFS 2013 Update 3 was applied.
- Finally, you should of course check that the reports still actually work.
Wrap-up
Do take the time to read the opening comments of ReportingBulkUpdateToolForTfs2013.ps1 because there are some caveats that you need to consider. In particular is that if you have made any customisations to the report or to data sources they will be overwritten. Hopefully you will have any customised reports saved in version control but as always it would be wise to take a backup.
Cheers -- Graham
