Comparing TFS Process Templates Across Team Projects



I have a new favorite tool for managing and administering a Team Foundation Server environment from day to day.  It has been so helpful both internally with administering our TFS environment but also as I go from site to site.  A great part about the tool is that the source code is completely available with an open license for use.  The product is maintained transparently and there have been a few occasions where I will request a feature and it’s literally done and released the next morning when I wake up.

CodePlex LogoTFS Team Project Manager LogoIntroducing the TFS Team Project Manager on CodePlex!  It’s a tool that helps you take care of common administration and maintenance tasks across lots of multiple team projects.  I have found it to be so useful in tons of different ways.  One of them is something that I’m particularly finding useful this week with a customer that is upgrading from Team Foundation Server 2008 to Team Foundation Server 2010.  They have 117 team projects on their instance and as you know, it can get tedious to manage that many team projects.  This tool helps out in scenarios like this.  We’ll talk with them later about potential consolidation of all of those team projects though!

Viewing Multiple Team Projects in TFS Team Project Manager

One of the things I need to do is figure what’s the best course of action after upgrade for the work item type definitions (and other process template features) for all of the existing team projects.  Everyone will be functional if we don’t do anything but I wouldn’t mind giving the teams a few of the new features in TFS 2010.  The feature of TFS Team Project Manager that can let me get a good sense of where the team projects currently sit with their process template choice & customizations is a “Compare” feature for work item type definitions.

The way that it works is that you load up different sets of work item type definitions from a process template.  You can even use an existing team project’s work item type definitions as a base set as well.

Defining Process Template Source Sets in TFS Team Project Manager

Once you have defined a few different sets that you want to compare against, you just select the team projects that you want to compare and click “Compare Team Projects With Sources.”  The tool has a fairly rudimentary compare algorithm but the summary & detailed data you can get is very handy.  It’s pretty magical if you were to ask me.

Process Template Comparison Results in TFS Team Project Manager

The grid lists all of the results including:

  • What is the best matching process template based on the source sets that are available?
  • What is the best matching percentage?
  • What were matching percentages for the other source sets of process templates?

Initially seeing the results may uncover a little chaos in your TFS environments. That’s okay because there are options. You might want to tame some of that chaos by moving your process templates and storing them in the version control repository. Once it is in version control, you can attempt to “merge” similar process templates together as best as you can and consolidate. You could then use my handy custom build process template for managing deployments of changes to the process templates to existing team projects on your system.

Shameless Plug: We end up talking about these concepts in our book, Professional Team Foundation Server 2010 by Wrox if you are interested in more information!

First, I like to sort by the “Best Matching Percentage” column in the results to see which team projects have attempted to go off the path and made individual customizations.  I don’t really need to worry about the other ones because I can take care of them in bulk.  The key in this particular case is to get them to same the base so that we can deal with them altogether in bulk after the upgrade.  (Customer’s Desire)

If you want to dive into a little more detail for any of the rows, you can choose “View Comparison Details” or double-click the row entry to pop up a great dialog that will help you with understanding the changes even more.  You can see which work item types are changed and if you can even open up the changes in a diff tool that is configurable.

Process Template Comparison Details in TFS Team Project Manager

There was even a new feature implemented last night that detects whether you have Visual Studio vNext (currently Visual Studio “11” Beta) and will use that nice new diff & compare experience in Team Explorer!

Work Item Type Definition Diff Compare Experience in Visual Studio 11 with TFS Team Project Manager

How about that?  This just makes things a ton easier for me!

This tool has a lot of other great features for TFS administration tasks across team projects.  that I’ll talk about in the future.  Just wanted to mention this one and how useful it can be!  Please make sure that you Donate Donate to Jelle Druyts if you find the tool useful to you as well.  It’s absolutely free and he puts a lot of work into keeping the project going.  At least buy him a drink for his hard work! Smile

Ed Blankenship

Posted in TFS | Tools | VSTS | VSTS Process


Visual Studio and TFS Updates through Windows Updates



I have run into a new situation more often that caused a few concerns for me that I thought I would discuss it some here.  Let’s face it:  there are bugs in the Visual Studio family of products.  People have reported performance problems (and thankfully PerfWatson has been helping out tremendously with rich actionable data for the Visual Studio product teams.)  However, did  you know that a ton of these bugs are resolved & released after initial release?  There are been great stability and performance improvements that have been released since the initial RTM of each of the Visual Studio versions.

Starting with the Visual Studio 2010 and Team Foundation Server 2010 release cycle, Microsoft has started to put more and more of these updates through the Windows Updates distribution system.  It’s great!  They are easily discoverable and can be part of your regular updating schedule.  However, this only works if they are actually available to you.

I have found more and more that people aren’t actually seeing these Windows Updates for Visual Studio and TFS in corporate environments.  When I started looking into this with a few companies, I discovered that IT departments are purposely either ignoring anything “developer” related in the Windows Updates system or rejecting them completely.  What?!  There were some that didn’t even know to look at these important categories. 

If they do see them but have been ignoring them, the reasoning has typically been because IT groups don’t understand the impact of those changes so they just would rather ignore them until they understand them more.  I think that’s fair but there didn’t seem to be any drive for already over-burdened IT teams to actually figure out those impacts.  IT departments are not traditionally using Visual Studio from day to day and don’t typically have the right expertise to understand the impacts.  There has traditionally been a gap between Software Engineering groups and IT departments at companies.  That’s a bigger problem to tackle for a different day. Smile  However, this is where a software engineering team can collaborate and help IT departments out.

Distributed Updates in Corporate Environments

You may have been asking, “why would my IT department have anything to do with the Windows Updates on my development or testing machines?”  That’s a great question.  In some corporate environments, you can actually setup internal servers to act as an intermediary between the machines on the internal network and the central Windows Update system.  IT departments do this for many reasons including making sure that certain updates won’t impact existing applications on business users machines.  Let’s face it – your VB6 invoicing & order processing app that you built 15 years ago that is still limping along but vitally important to your business may or may not get impacted by a new update that’s available for Windows 7.  It happens, right?

To help you feel better about the updates we’re discussing in this blog article: there is a very high cost internally for anyone on the Visual Studio product teams to push an update through the Windows Updates system.  There’s a very high quality bar before they are approved internally.  They also wait for several weeks to a couple of months to make sure that no critical issues are reported from early adopters of those updates.  Not every update is sent through the Windows Updates system so the ones that do really are important.  There are many updates that are beneficial that never get released through Windows Updates.

There are many commercially available tools for “pushing” updates to customers.  Off the top of my head, Microsoft has a high-end version called System Center Configuration Manager and a free version included with Windows called Windows Server Update Services (WSUS).  Additionally, there are group policies in Active Directory that IT Administrators can apply to have machines in the domain talk back to one of these servers for their updates.  You can usually tell if you are in this situation by heading to Windows Updates from your Control Panel and checking to see if it says something like “Managed by your system administrator.”

Check out the Best Practices for Group Policies when using WSUS

Windows Updates Managed by System Administrators or IT Departments

You could click the link that says “Check online for updates from Microsoft Update” but some IT departments have even disabled that link from working through Global Policy.  If any of this is setup internally, it means that all updates basically go through a gatekeeper which is someone who is actively (or inactively) managing the updates in your IT department in one of these internal update servers.  This can be a good thing or a bad thing from what I am seeing more often.

Approve the Visual Studio Family Updates

This is the time when you might want to setup a meeting with your IT department to indicate that your software engineering teams actually do care about these updates and want them approved or even delivered automatically.  They may not even know that they even exist now with this new release.  Here are the categories that the teams should think about covering:

  • Visual Studio (including Agents)
  • Team Foundation Server
  • Expression
  • .NET Framework

There was improvements that helped performance in the Workflow Designer when editing TFS Build process templates in Visual Studio 2010.  These improvements were actually delivered as a .NET Framework QFE.  BTW, There are also additional steps that you could take that I have discussed previously on my blog.  My point by mentioning this is that IT Departments still need to monitor for even .NET Framework updates to help improve the stability and performance for the development environment for software engineering teams.


Enabling Microsoft Update

If your machine isn’t dictated by an internal Windows Updates server by global policy (or if you use check for updates online using the central Windows/Microsoft Updates infrastructure) you may still not see the Visual Studio updates.  This is because by default Windows only checks for Windows Updates.  If you want to check for updates for all Microsoft software then you actually need to enable Microsoft Update.  There is a small distinction but has a large impact on what’s available for your machine.  Smile

Enabling Microsoft Update to Receive Additional Updates for Microsoft Products


Product Updates Improvements in Visual Studio vNext

For those that seem to still have issues with Windows Updates internally, you’ll like seeing that Visual Studio “11” now has Product Updates shown with other types of tools & extensions updates in the Extension Manager.  I doubt that this will include Microsoft Test Manager or Team Foundation Server updates though. Sad smile  I hope I am very wrong about it though and would be very happy if they do send those types of updates down through this new mechanism!

You can see these by heading to Tools –> Extension Manager and then look at the Updates section of the window as shown below.  I can imagine us seeing all sorts of new updates that will come through this system including feature packs, power tools, cumulative updates, etc.  I would imagine that there will be quite a few more updates then would even traditionally be sent through Windows Updates.  That’s a big win for us especially when you want to have the latest features & stability improvements available for your development environment.

Visual Studio Product Updates in Extension Manager

Go have that discussion with your IT department now and if you can see what might be missing by checking for updates from Microsoft’s centralized Windows or Microsoft Update.

Ed Blankenship



Providing Actionable Feedback & Bugs for the Microsoft Visual Studio and TFS Product Teams



Now that the new Visual Studio and TFS “11” Beta release is available for you to use for evaluation or even “Go-Live” in production, you’ll likely find some bugs or suggestions for rough spots in the product that might be able to be addressed before the final release.  Even so that feedback can be acted on in a subsequent patch, feature pack, or service pack so it’s always good to at least put it on the product team’s backlog.

The traditional way to provide feedback in the past for the Visual Studio 2010 release and before was to use Microsoft Connect for Visual Studio to file your bugs for the .NET Framework, Visual Studio, Team Foundation Server, Microsoft Test Manager, etc.  It still is but now you have another tool in your tool belt to provide some great information for the product team that’s new for the Visual Studio “11” family release now in Beta.

Introducing the Microsoft Visual Studio “11” Feedback Tool available on the Visual Studio Extension Gallery.  It’s easy – after installing the extension you’ll get an option in the Help menu for “Report a Bug” which will start a nice wizard process that will create an awesome Connect bug for you.  You can use this wizard for anything you would normally create a bug for like the .NET framework, TFS, Visual Studio, Microsoft Test Manager, etc.

Report a Bug in Visual Studio 11

One of the awesome pieces of this tool and very important is that it captures all sorts of logs and valuable information to be used in helping reproduce the problem.  You can review all of those files before you submit the feedback to make sure you are comfortable with that data.  The Microsoft Connect item is also marked as “private” so that your details aren’t exposed to the public.  You can always go in to the Microsoft Connect site to change it to Public if you want it available for other people to vote it as something that is important to fix.  That’s not required though.

After you have started the tool, you can access it from the Windows Notification Area (aka System Tray) by clicking the tool’s icon.

Visual Studio Feedback Tool System Tray Icon

Here are some things you can also do to make your bug reports super stellar and give it some traction whenever someone looks at it:

  • What are the steps to reproduce your problem?  Be sure to give all the steps. Some things may seem extremely obvious to you but when you are looking at lots of bug reports, something obvious to you may not be obvious to them.  If the problem is intermittent, describe the best you can to provide what you can to help the person reading your bug report to attempt to reproduce it.
  • Provide screenshots in a logical manner and show someone what’s going on with annotations like .
  • Even better – you could always create a quick screen recording using a tool like Screenr (free) to show someone what’s going on.  Feel free to put the link inside your bug report.
  • Help the team understand how many people or the types of customers you think this would impact.
  • Are there any others with similar machine specs or environmental conditions that are experiencing this problem?
  • Provide some information about your environment and computer.  What versions of Visual Studio do you have installed including older versions?  Did you have a previous pre-release edition on your computer?  How did you get that one removed from your machine?
  • Is the bug preventing your business from functioning?  Honestly answer this.  Remember that not everything can be Priority 1.  If the bug is truly keeping your business from functioning, then I would file the Connect bug and note the ID number.  After that, pick up the phone for Microsoft Product Support Services and help them with understanding the severity.  You can provide the support technicians with the Connect ID and that can get them started with working through the issue.  Don’t file a Connect item though if it’s not a bug.  You can always call the Support team for non-bug issues to help you through your problems too so keep that in mind!
  • Any others that I might have missed that would be important?

If you want to take a look at all the other details about using the Visual Studio Feedback Tool, check out the documentation here:  https://connect.microsoft.com/VisualStudio/content/content.aspx?ContentID=26698

If you have a feature request, instead of a bug report, then I would head on over to the Visual Studio User Voice site.  You’ll have the opportunity to create new feature requests and vote on those coming from other people.

Ed Blankenship

Posted in TFS | Tools | VSTS


Feature Request: Treat TFS as an Enterprise Symbol Server



If you haven’t talked to me before, I am a serious fan of the Symbol Server and Source Integration in Team Foundation Server.  Recently, I thought about reducing the complexity of the entire story especially for those using Team Foundation Server.  You still have to have a file share available for symbols which is just something else to have to request, manage, deal with for disaster recovery, and is particularly problematic when users are in geographically remote offices.  Individual developers also have to manually register the symbol server in the Visual Studio options for each of the development machines they ever use.  Why though?  It shouldn’t be this difficult especially when you have already adopted TFS.

User Voice LogoI submitted a new feature request on the Visual Studio Team Foundation Server product team’s User Voice site specifically for assisting with this complexity.  I would like TFS just to be treated like an enterprise symbol server and Visual Studio can just take advantage.  My good friend and colleague, Adam Cogan, encouraged me to share with my blog readers more details about this feature request.

I would also like to ask for your help with voting on the feature request if you like the idea and would be important for your team & organization.

VOTE HERE

User Voice Feature Request Details - Treat TFS as an Enterprise Symbol Server

Additional Details for the Feature Request

Version Control Folder to Hold Symbol Server Files

The main part of this would be something like a version control folder to hold the symbol server files such as $/Symbols.  This would be a special folder that would only be used for Symbols.  You would then be able to have a URL endpoint that TFS recognizes and handles appropriately (i.e. https://tfs.myserver.com/tfs/DefaultCollection/Symbols).

With this type of feature in TFS you can take advantage of many side benefits including:

· No file share to worry about getting provisioned by IT or backed up

· Takes advantage of TFS Proxy caching for geographically distributed locations

· This could be a special version control folder type where it doesn’t have to keep history – only the latest version (T)

· Would work out really well for those using TFS on Azure (especially with on-premises build servers)

· Potentially Symbol Server for CodePlex projects!

· IntelliTrace & the VS Profiler benefits greatly from this as well!

clip_image002

Automatic TFS Build Configuration

If this feature is setup & configured, then why not just go ahead and auto-configure new TFS build definitions as well?  Pop it right in there…

clip_image004

Automatic Client-Side Configuration

If I connect to a Team Project Collection, I want my Visual Studio (and other clients that use symbol server) to be auto-configured for the symbol server to be used.  It should just be automatic!  This would be very similar to how the client auto-configuration for TFS Proxy just works for anyone doing a version control get.

clip_image006

Build Retention Policies

If you have symbols turned on for TFS builds to handle when retention policies are run, you could configure it to either destroy or delete the symbols from the special version control folder.  As an administrator, I may want to actually destroy the symbols with retention policies for some of my build definitions just to save on space.

clip_image008

 

Help me everyone out with your votes!

Ed Blankenship



Using Exchange Server with TFS for Delivering E-Mail Alerts



Team Foundation Server has the ability to deliver e-mail alerts.  I have talked about this feature a few times (like here, here,  and here) and it’s a very handy feature of any work item tracking system let alone version control, automated builds, test case management, etc.  In the TFS Administration Console window, you just need to enable and specify the e-mail alert settings from the Application Tier node.

Enabling E-Mail Alerts in TFS Administration Console

Here’s the one caveat about this functionality:  TFS needs the SMTP server to allow unauthenticated requests.  Notice that TFS doesn’t allow you to specify a user name and password.  Other applications do allow this -- for example, my Windows Home Server 2011 instance at home asks for additional information.

Specifying E-Mail Alert SMTP Settings for Windows Home Server 2011

Several e-mail servers on the market, including Microsoft Exchange Server, do not allow unauthenticated SMTP requests by default.  In general, you actually don’t want to open up your SMTP server for unauthenticated requests or have an open SMTP server on your network.  This can open you up to security issues and would allow malware or compromised servers to use it as a relay.  Not fun stuff at all.

The preferred approach would be to let your e-mail server know to allow unauthenticated e-mails from each of your TFS application tier servers.  (Note:  You may have multiple application tier servers if you have setup your TFS environment to be highly available using network load balancing and created an AT web farm.)  Since most of the customers I visit have adopted Microsoft Exchange Server, here are the steps for you to pass on to your Exchange Administrator to take to “trust” TFS to deliver e-mail alerts.  As a TFS Administrator, you will not like have the permissions necessary to make these changes in your internal Exchange environment.

Thanks to the Imaginet Infrastructure team (specifically Kelsey Epps)  for help with these instructions!


Configuring the Exchange Hub Transport for TFS E-Mail Delivery

Your first step is to open the Exchange Management Console and head to the Hub Transport node underneath Server Configuration.  This will show you all of the receive connectors that are currently defined when you select the appropriate hub transport server from this list.

Hub Transport Receive Connects in Exchange Management Console

What we will end up doing is creating a new receive connector specifically for use by each of the TFS application tier servers.  In the Actions pane for the Exchange Management Console, choose “New Receive Connector…”

Creating a New Hub Transport Receive Connector in Exchange Management Console

On the Introduction page for the New Receive Connector wizard, enter a friendly name to help other Exchange Administrators understand the purpose of this receive connector and choose “Custom” for the intended use.

New Exchange Hub Transport Receive Connector Wizard - Introduction Page

On the next page for specifying the Local Network Settings, you’ll likely just want to leave the defaults and specify the fully-qualified DNS entry that will be used in the SMTP response when a client like TFS connects to it.

New Exchange Hub Transport Receive Connector Wizard - Local Network Settings Page

The next screen for specifying the Remote Network Settings is the important one.  This tells Exchange server which IP addresses should be allowed to use this receive connector.  You’ll want to remove the default entry that exists in the list and then add each of the IP addresses of each of the TFS application tier servers.  (Remember from above, you might have multiple application tier servers in your TFS environment.)

New Exchange Hub Transport Receive Connector Wizard - Remote Network Settings Page

At this point, you are ready to complete the wizard and it will create the new custom receive connector to be used by the TFS application tier servers.  Once the wizard has completed and created the new receive connector, you’ll want to open the properties dialog window for the new receive connector and enable “Anonymous Users” on the Permissions Group tab.

Enabling Anonymous Users on Custom Exchange Hub Transport Receive Connector

Now, give the fully-qualified DNS name for the Exchange hub transport server to the TFS Administration and they will be able to enter it in the TFS Administration Console in the appropriate spot.  The TFS Administrator will want to monitor the event logs for any error messages after this has been enabled in TFS to make sure that the e-mail delivery TFS jobs that run periodically when there are new e-mail alerts complete successfully.

Using an Office 365 Hosted Exchange Instance

If you happen to be using Office 365 for your Exchange instance, then you will have to setup a local SMTP Relay.  Here are a few online resources for how to do that:

Ed Blankenship



Creating E-Mail Alerts for Team Members in TFS



In TFS 2005, TFS 2008, and TFS 2010, the alerting system has always been based on a “self-subscription” model which means if you want an e-mail alert then you need to create it for yourself.  This could be problematic if new team members didn’t know about the self-subscription model.  Now, you could use the Alerts Explorer from the TFS Power Tools to create e-mail alerts for other people but then those alerts are actually owned by the person creating them and not able to be managed, edited, or disabled for the person they are intended.  There are other potential workarounds that people have discussed for any of the TFS versions I mentioned above.  A good question on Stack Overflow has some discussion as well.

Team Foundation Service Preview LogoIn the latest builds of the Team Foundation Service Preview (which ultimately will be features we will see in the next version of TFS – TFS 11), we can now see that administrators are able to create team alerts that help the scenario I described above.  Managing personal and team alerts are exposed in Team Web Access.  Notice in this Work Item alert, the new [Me] value that is available for the filter clauses.

Creating a Team Work Item Alert in TFS

You can also create other types of alerts like Build Alerts and Code Review Alerts.

Creating a Team Build Alert in TFS

image

What I also noticed is that administrators can view & troubleshoot other user’s e-mail alerts that they have created including personal alerts.  That was particularly troublesome for TFS Administration in the past but should help out quite a bit for user’s who report problems in the future.  An administrator can now even help craft the appropriate e-mail alert for the user using the right filters and grouping of clauses which I find to be the most commonly reported issues with creating alerts.

Administering TFS Alerts for Other Users

Ed Blankenship



Replacing Compare and Diff Tools for TFS Version Control



Even though the TFS product team is planning to completely replace the awful source compare experience in the next version of TFS, I need something for use with prior versions of Visual Studio including Visual Studio 2010.  The new version inside of Visual Studio 11 is pretty awesome.  I have actually decided on Code Compare Pro by Devart for my legacy versions.  They have both a free version and a Pro version that includes a 30-day trial.

During the installation, you can specify whether you want to integrate Code Compare with the TFS tools and when you do that, it adds the relevant settings automatically to your Visual Studio options for TFS Version Control.  That’s classy and a nice touch for the installer.  BTW – this is the exact way you would do this manually if you have a different compare tool that you like better.  There are plenty out there…

Code Compare Options Set for Compare and Merge in TFS for Visual Studio Options Dialog

This now allows you to use your new specified tool anytime you would do a compare or merge operation even from the Windows Explorer Shell Extensions plug-in from the TFS Power Tools.  It will even allow for a three-way merge & diff experience which can be quite helpful at times if you are in need of it.

Code Compare Pro Compare Diff with TFS Version Control

Ed Blankenship



Using the Related Twitter Accounts Tag in the Tweet Button



If you have a site like ours, you might want to give people the opportunity to share your content socially.  One of the ways you can do that is using the Tweet Button for Twitter.  It’s actually super easy to implement.

One of the things you might also do is to specify “related Twitter accounts” that a user might be interested in.  You would normally include your account in the “via” tag but you can give Twitter the chance to suggest additional users for a person to follow whenever they share some of your account.  In my case, I may want to give people a chance to follow the account for Imaginet, the company I work for, @justimaginet.  You do this by specifying the “data-related” tag in your hyperlink.  You can specify as many accounts as you want but they are really just suggestions to Twitter.  Take a look at the documentation mentioned below about if you want to specify multiple accounts.

Here’s an example of what I used to update the itemTemplate.blogtemplate file for my dasBlog site.

<div class="twitter-badge">
    <a href="https://twitter.com/share" class="twitter-share-button" 
        data-url="<%PermalinkUrl()|edsquared%>"
        data-text="<%ItemTitleText()|edsquared%>" data-count="horizontal" 
        data-via="<%ItemAuthorTwitterAccount()|edsquared%>"
        data-related="justimaginet:Imaginet - Microsoft ALM Partner of the Year">Tweet</a>
</div>

Give it a try out by visiting our blog site and using one of the Tweet buttons to share the content to your followers:  http://www.edsquared.com

If you are wanting to research this a little more, here’s the official documentation from Twitter:

Related accounts

Using the related field you can suggest accounts for a user to follow once they have sent a Tweet using your Tweet Button. These suggested accounts and their basic information are shown on the last page of the Share Box flow.

Only two accounts are displayed and by default the via user is shown first with the first related account shown afterwards. If the user is a follower of the via user the Share Box will instead show the first two related accounts the user isn't a follower of. No accounts are displayed if the user follows all of the suggested accounts (via and related).

You can add your own summary of a related user by adding some text after their screen name, separated using a colon. For example, to add a summary The Javascript API to the related user @anywhere you would use:

data-related="anywhere:The Javascript API"

The summary is shown above the related user and is in addition to the default information like the bio and verified status. Summaries should not include commas or colons and can only be added to related accounts.

Tweet Button - Twitter Share Dialog

You can provide multiple related accounts by comma separating entries in the data-related value:

data-related="anywhere:The Javascript API,sitestreams,twitter:The official account"

You learn something every day…

Ed Blankenship

Posted in


Awarded as Microsoft MVP for 2012



Microsoft Most Valuable Professional (MVP) LogoI’m really happy to have been awarded again for 2012 as a Microsoft Most Valuable Professional in Visual Studio ALM & TFS!  This will be my fifth year as a Microsoft MVP and it’s always an honor to work with each of my colleagues in the MVP community.  Very much looking forward to the MVP Summit coming up next month and continuing to help out where I can in the ALM community.  Thanks to everyone who have helped me in the past few years and congratulations to all of the other new & repeat awardees of the Microsoft MVP award for this year.

I wish everyone a great new year in 2012!

Ed Blankenship



Integrating Red Gate SmartAssembly Into TFS 2010 Build



Updates – I plan on making updates to this blog article from time to time as I learn more and changes are made to TFS & SmartAssembly to smooth out some of the rough edges.  Come back again for the latest & greatest!

I really like tools that provide assistance with the release management & maintenance cycles of ALM.  I think some of the features really add a particular shine to your application.  It’s something that I’m currently writing an article about but I wanted to share how to integrate one of those tools into your Team Foundation Server 2010 Build Process.  This first tool to be reviewed is Red Gate’s SmartAssembly product.Red Gate SmartAssembly

SmartAssembly is a product that can help you out with obfuscation if you need it but I primarily want to focus on two of its other major features:

  • Automated Error Reporting – When an exception occurs, the end user can be prompted to send back the exception details so that the development team can review those details.  This can also work with server-side & web applications without requiring end user prompting.
  • Feature Usage Reporting – This is essentially telemetry for your application to figure out how your users are using the application so that you can make good decisions in the future about where to invest for future releases.  It does this by sending back anonymous data for users who opt-in at runtime.  It will even automatically send back data about the machine the software is being run like the operating system.  This can be extremely useful data to product managers.

You don’t have to worry about any of the details because once you run your assemblies through SmartAssembly, it instruments all of the necessary functionality automatically for you.  If you acquire the Professional edition, you can customize the reporting experience including the ability to host your own web server to accept the error & feature usage reports.

Aside:  Too many teams & companies have blindly adopted obfuscation for their assemblies in the past without taking into consideration the true “total cost” of obfuscating your applications.  I’m all for obfuscation where it makes sense to protect IP as long as the value of the protection of that IP is worth more than the extra cost, resources, and maintenance complexity to truly support an obfuscated product.  Each team & company is going to have to make that decision based on the resources available and the value of the IP to be protected  – just don’t go into it blindly.

FYI – PreEmptive’s Dotfuscator tool is a competing product line with a similar feature set that I hope to be covering in a future blog post.

Ignoring obfuscation, these two features are absolutely great for gaining visibility about your application once it has been released.  For all of those teams that aren’t traditional software vendors but building applications for internal use, these are great features for those applications as well.  Software engineering teams building internal applications are very much in need of the same type of information as ISVs about how their internal “customers” are interacting with their applications.  Internal applications don’t necessarily need obfuscation but they can definitely benefit from automated error & feature usage reporting!

One part that I absolutely love about SmartAssembly is that even though the tool instruments and changes your assembly, it also provides the ability to produce a set of matching symbols (.PDBs) that are extremely important for several scenarios in TFS, the Visual Studio ALM family of tools, as well as basic debugging.

I am going to be spending some time in this blog article to walkthrough how to integrate SmartAssembly into your automated TFS build process so that your teams can take advantage of these features.  I am going to take the approach of not creating any custom workflow activities for this particular effort.  Jim Lamb has a good discussion about when to make customizations to the MSBuild file (essentially the Visual Studio project file) and when to make your customizations in the Windows Workflow-based build process template.  As much as I very much prefer customizing my build process templates using custom workflow activities, in this case I choose to do a little customization of both without using any custom workflow activities.  I would much rather have done this using only native Windows Workflow activities but I’ll talk more about that a little later.

Disclaimer:  As a Microsoft MVP, I have been a part of the Friends of Red Gate group for the last four years and I have been provided Not For Resale licenses of the Red Gate family of products though I reserve the right to offer unbiased opinions and criticisms.  I was not paid for these contributions.  However, I may or may not get a complimentary round the next time I see the Red Gaters at the pub in Cambridge. Smile

Works on My Machine LogoWorks on My Machine Disclaimer:  Everything in this blog article works on my machine when I wrote it.  I have the latest version of SmartAssembly and TFS 2010 installed & configured correctly.  I’ve done my best to make this as reusable as possible for most team’s scenarios but I can’t tell you that it will work for you.  Hopefully it gets you started on the right path though!  Please don’t contact me and let me know that my code killed your cat.  I feel for you… I do – I just can’t do anything about it.  You’ve been warned.  I take the same approach that Scott does with blog contributions.

Configuring SmartAssembly for Team Use

SmartAssembly has actually been designed out of the box to handle the single-developer team scenario.  If you are using TFS, you are likely not a single-developer team so you’ll want to a few things to get SmartAssembly setup for use with a team.  The architecture for SmartAssembly can best be described with this architecture diagram:

Smart Assembly Architecture Diagram
Sourcehttp://www.red-gate.com/products/dotnet-development/smartassembly/team-package

You’ll need to get the Professional edition of SmartAssembly since it allows you to store everything in a shared SQL Server database.  One nice thing is that each developer who will need to interact with error & feature usage reports only needs a Developer edition license instead of a full Professional edition license.  You’ll need to install & configure the Professional edition on each of your build servers.  You might as well go ahead and create a build agent tag called “SmartAssembly” to indicate which build agents in your build farm are hosted on servers that have SmartAssembly installed.

When you first start SmartAssembly, you will want to setup the desktop machines & build servers to use the same SQL connection settings for the shared SmartAssembly database.  I even like to use the friendly TFS DNS names that I already have setup for my particular TFS environment.  Remember that if you are using the limited use license of SQL that is included with TFS, you won’t be able to house the SmartAssembly database on that instance.  You’ll need to purchase a legitimate SQL Server license.  It’s a great time to upgrade to the SQL Enterprise edition if you can for TFS!  TFS will definitely take advantage of several of the features.

It is pretty easy to setup from there:

Configuring SmartAssembly Database Connection 

Be sure to also indicate that you want to use relative paths.  Relative paths will be very important when you are using it in a team environment with Team Foundation Server.

BTW, if you need to setup SmartAssembly to use SQL Authentication instead of Windows Authentication, you can do that using this particular article. You do this by basically updating the settings configuration file available on a Windows 7 machine at C:\ProgramData\Red Gate\SmartAssembly\SmartAssembly.settings.

Creating & Storing the SmartAssembly Configuration File in Version Control

I am going to make this easy by just using a quick Windows Forms application however you are able to process any type of assembly including Silverlight apps, ASP.NET web applications, class libraries, etc. using SmartAssembly.

You will want to compile your assembly at least once and then start a new SmartAssembly project.  It actually doesn’t matter where the source & destination location of the assembly is set to in the configuration but you might want to pick a location that all of the developers will be using.  Don’t worry about the build server locations because we will override those later in the build process!  To keep it simple, I’m only going to enable the following features in my SmartAssembly configuration file:

  • Automated Error Reporting,
  • Feature Usage Reporting, and
  • Generate Debugging Information

You can research more on the other options that are available but I am going to keep this walkthrough very simple.  Once you are satisfied with your settings, click the “Save As…” button and save the configuration file in the same folder as your Visual Studio project file.  I even like to include the file in my Visual Studio project so that I can work with it and check it into the version control repository along with the rest of my project.  The SmartAssembly configuration file has a “.saproj” file extension.

Visual Studio Project with Smart Assembly Configuration File

The next thing you might want to do is open the configuration file using the XML Editor in Visual Studio to verify all of the settings look correct. You can use the “Open With…” context menu command from the Solution Explorer window to help you out.

Using the Open With Command in Visual Studio Solution Explorer

The main thing you want to do is be very mindful of using relative file paths everywhere in the configuration file since the location of the source code location changes on the build server & developer machines.  For example, TFS Build allows you to have multiple build agents running on any build server.  I might have three build agents on a build server which means three builds could be running at any given time on the build server.  You isolate each build agent on a build server by setting the working directory to something that will be a unique value.  The default setting is $(SystemDrive)\Builds\$(BuildAgentId)\$(BuildDefinitionName) but I usually change it to $(SystemDrive)\Builds\$(BuildAgentId)\$(BuildDefinitionId) to give me a few extra characters since we also have path length limitations to go up against.

SNAGHTML5088658

Defining Custom MSBuild Properties

At this point, we are going to define a few custom MSBuild properties that we are going to use to trigger the SmartAssembly functionality.  The table lists the properties I am going to define in this process.

Property Name Value(s) Description
TfsBuild True, False Indicates whether this build is occurring using TFS.
RunSmartAssembly True, False Indicates whether the SmartAssembly processing should occur after compilation.
SmartAssemblyConfigurationFileRelativePath <Relative File Path> Stores the relative path location to the .saproj configuration file for the project.

Modifying the Visual Studio Project Files

For many of the common project types, Visual Studio project files are in fact actually MSBuild scripts under the covers.  What we are going to do is add some custom functionality at the end of the project file that we will later “turn on” during the build process.  You could modify this so that you could “turn on” the functionality at development time locally but this additional script excerpt will leave it turned off during normal development.

To edit a Visual Studio Project file, you can “unload” the project from the context menu in Solution Explorer and then double-click it to open it in a new editor document window.  You will add the following excerpt close to the bottom of your Visual Studio project file just before the final </Project> ending tag. In my case it is a .csproj file.

<!-- Red Gate SmartAssembly Custom Post-Compile Processing for TFS Builds -->
<UsingTask TaskName="SmartAssembly.MSBuild.Tasks.Build" AssemblyName="SmartAssembly.MSBuild.Tasks, Version=6.0.0.0, Culture=neutral, PublicKeyToken=7f465a1c156d4d57" Condition="'$(TfsBuild)' == 'True' and '$(RunSmartAssembly)' == 'True'" />
<PropertyGroup Condition="'$(TfsBuild)' == 'True' and '$(RunSmartAssembly)' == 'True'">
  <!-- Uncomment this next line if the configuration file is not located in the same directory and uses the same name as the project. -->
  <!--<SmartAssemblyConfigurationFileRelativePath>SmartAssemblyConfigurationFileName.saproj</SmartAssemblyConfigurationFileRelativePath>-->
  <!-- This will set the default name of the configuration file to the same name as the project name if the property is not defined elsewhere. -->
  <SmartAssemblyConfigurationFileRelativePath Condition="'$(SmartAssemblyConfigurationFileRelativePath)' == ''">$(ProjectName).saproj</SmartAssemblyConfigurationFileRelativePath>
</PropertyGroup>
<Target Name="AfterBuild" Condition="'$(TfsBuild)' == 'True' and '$(RunSmartAssembly)' == 'True'">
  <!-- Archiving the original compiled assembly and matching debugging symbols file. -->
  <Message Text="Archiving the original compiled assembly and matching debugging symbols file." />
  <Copy SourceFiles="@(_DebugSymbolsOutputPath)" DestinationFolder="$(OutDir)Original" Condition="'$(_DebugSymbolsProduced)' == 'true' and '$(CopyBuildOutputToOutputDirectory)' == 'true' and '$(SkipCopyBuildProduct)' != 'true'" />
  <Copy SourceFiles="@(MainAssembly)" DestinationFolder="$(OutDir)Original" Condition="'$(CopyBuildOutputToOutputDirectory)' == 'true' and '$(SkipCopyBuildProduct)' != 'true'" />
  <!-- Process Assembly through SmartAssembly -->
  <SmartAssembly.MSBuild.Tasks.Build ProjectFile="$(SmartAssemblyConfigurationFileRelativePath)" Input="@(MainAssembly)" Output="@(MainAssembly)" OverwriteAssembly="True" />
</Target>

It is a modified version of the snippet from the SmartAssembly help documentation for integrating with MSBuild:  http://www.red-gate.com/supportcenter/Content/SmartAssembly/help/6.5/SA_UsingSmartAssemblyWithMSBuild.  You’ll see a little later where we are going to “turn on” the functionality by editing the TFS build process template.  If you named your configuration file the same name as the project name and stored it in the same location in version control you actually don’t need to modify anything in the snippet at all.

Notice that the snippet keeps the original copies of the assemblies and matching symbols (.PDB) file so that they later get copied to the TFS build’s drop folder.  It is copying the original assembly and matching symbols into another subdirectory named “Original” instead of just outputting the SmartAssembly instrumented assembly & matching symbols to a subfolder called “Obfuscated”, “Instrumented”, or “Protected.”  I used to use the latter approach (as some people suggest) but if you are also compiling installers, it is useful to create an installer during specific builds that include the original assemblies instead of the instrumented ones.  In my installer definition (like a WiX file) I’ll just refer to the regular location and it will pickup whatever version the build process created.  If I want an installer to have the original assemblies then I just queue a new build and will set the SmartAssembly process parameter to false for that build.  I don’t have to do anything additional in my WiX definition files to handle this scenario. 

Another side effect you get by using this approach is that if your build process runs any automated tests, static code analysis, test impact analysis, etc., then it will use the instrumented versions of the assemblies as the target of the tests and other post-processing tools!  There are several ways to skin this particular cat but I have fallen back to this approach after a few years of dealing with these issues.

Modifying the Build Process Template in Windows Workflow Foundation

Technically, we could just hard-code the extra MSBuild process parameters that we need using the default TFS build process template on the Process tab of the build definition editor window:

Setting Additional MSBuild Property Values in TFS 2010 Build Definition Editor

If you are okay with this approach then you don’t really need to go any further.  However, we could make this a richer experience for people who will edit and queue these builds from day to day.  This is where we can go through and create a custom process template.

The first thing you will want to do is create a new build process template to start your customizations.  I have included mine for download at the end of this blog post but you may want to walk along.  I usually start by creating a copy of the default build process template available from TFS.  If you aren’t familiar with the basics of this particular process, I would highly suggest going through the walkthrough in either of these books:

You can then change your build definition over to the newly copied build process template using the following combo box.

Selecting a New TFS Build Process Template

If you click on the hyperlink, it will take you to the location in Source Control Explorer where you can get the latest version into your workspace and then open the build process template file for editing in the Windows Workflow Foundation Designer.

Defining Build Definition Process Parameters

The first thing we can do is specify a new build process parameter that is exposed to the end user of the builds by going to the “Arguments” tab in the lower left-hand corner of the Workflow designer.

Arguments Tab for Windows Workflow Designer

I am going to create a Boolean process parameter simply named “RunSmartAssembly” and set the default value to False.  This isn’t an MSBuild property but a workflow process parameter that will be exposed to the end user when they are queuing a new build or when editing the build definition.

Creating New TFS Build Process Parameter

This next step is just to make things that much nicer.  We can give the TFS Build system some additional metadata to make sure the parameter is exposed to the end user in a nice fashion.  There are more details about the process parameter metadata field in either of the book chapters mentioned above in case you would like to learn more!  You edit the collection information for the Metadata parameter that is already defined in the default build process template.  (It’s two above the parameter we created in the previous screenshot.)  Just click the ellipsis button in the default value field column to open up the metadata editor window.

TFS Build Process Parameter Metadata Editor

Fill out the details as indicated above and save your build process template. You won’t see the changes immediately if you were to go back to the build definition editor because we haven’t checked-in the build process template back to the version control repository yet.

Verify SmartAssembly is Installed on Build Server

Whenever I architect a build that requires the use of a custom tool and it isn’t stored in version control (or even if it is but someone forgot to add that workspace mapping) I usually want to add a check in the build process to make sure that the tools are actually available to the build server.  If the check doesn’t locate the tool I have it give a nice build error.

Add an If workflow activity inside the Build Agent Scope activity (labeled “Run on Agent”) but before the section that starts the compilation.  It doesn’t exactly matter where as long as you get them in the agent scope but before any type of compilation begins.  I am going to set my condition to something like the following:

RunSmartAssembly AndAlso Not System.IO.File.Exists(String.Format("{0}\{1}\{2}", Environment.GetFolderPath(Environment.SpecialFolder.ProgramFiles), "Red Gate\SmartAssembly 6", "SmartAssembly.exe"))

You can then add a Write Build Error activity with an appropriate message to indicate that SmartAssembly was not found.  It should look something along the lines of this following example.

Verifying SmartAssembly is Installed on TFS Build Server

Appending Additional MSBuild Properties

We can now work on passing in the additional MSBuild properties.  I’m going to do this in two steps.  The first step is to append the TfsBuild MSBuild property to the pre-defined workflow variable that is used for this purpose named MSBuildArguments.  I’m going to do this immediately after the workflow activities we added for the previous step using another native primitive workflow activity:  Assign.  It’s a super simple activity that is great for this particular purpose.  The assignment expression that I am going to use for the Value parameter is:

String.Format("{0} {1}", MSBuildArguments, " /p:TfsBuild=True")

image

After that, we will add another If activity where the conditional will be set to the RunSmartAssembly workflow parameter we created earlier.  We will also add add another Assign activity and append our remaining MSBuild property to pass into the compilation process.  You can use this assignment expression for the Value parameter of the Assign activity:

String.Format("{0} {1}", MSBuildArguments, " /p:RunSmartAssembly=True")

The final sequence looks similar to the following screenshot.

image

You may be asking “Why did we define the $(TfsBuild) MSBuild property when we could have just used the $(RunSmartAssembly) property?” That’s a great question… You don’t need it if you aren’t going to do any additional customization. However, in general, I like to always define the $(TfsBuild) MSBuild property so that you could customize the project files to modify the conditions based on whether it is occurring during a TFS Build or if it’s occurring on a developer’s machine. It’s quite handy when you need it.

Notice that we are also performing all of the SmartAssembly processing steps before the Source Server Indexing and Symbol Server Publishing phase of the build process so that both the original symbols and the symbols that match the instrumented assemblies are published correctly to Symbol Server and have the appropriate indexing for Source Server support included in those symbols.  That will be extremely useful later whenever you need to debug against either the original or instrumented assemblies in the future.  You can also open IntelliTrace log files & take advantage of Test Impact Analysis if you keep obfuscation turned off in the SmartAssembly configuration.

Finale

That’s it!  Just save the changes to your build process template and check the file into the version control repository so it can now be used by your build definitions.  Be sure to set your new custom workflow parameter to True and then queue a new build!

Setting Custom SmartAssembly Process Parameter

You’ll now notice that it runs correctly even if you have defined for your build process to compile multiple build configurations (i.e. Debug | x86, Release | AnyCPU, etc.)

Potential Improvement Areas

  • Licensing & Activation for Build Servers – Unfortunately, the way SmartAssembly is licensed you have to purchase a license for each of the build servers you might have and activate the software on those build servers.  The accompanying side effect is that the developer licenses are cheaper.
    This can be problematic in a TFS environment where you might have a build farm that has one build controller with 20 build servers that have three agents on each of those build servers.  It’s not that SmartAssembly would be used at the same time on all 60 of those build agents but you also don’t know which build agent will be reserved for a particular build at any given time.  I have resorted to using the build agent tagging feature of TFS Build to handle making sure particular builds only reserve an agent with SmartAssembly configured & activated.  However, this causes a complete underuse of the hardware resources available in a build farm. 
    I would rather tool vendors achieve their revenue targets by increasing the per-user license fee because and specifically for users who benefit from the advantages that the particular tool brings to them. This licensing model if very similar to how the Visual Studio & third-party components licensing model works.  Microsoft and other third-party component vendors give you the ability to install and use the their tools on a build server without charge.
    I consider build agent machines throw-away machines.  They should remain completely clean but don’t need to be backed up or monitored.  I usually will have a virtual machine base image that has everything already installed & ready to go so that I can add/remove to the build farm “pool” as needed.  I even prefer to throw away machines after 30 days and bring new build agents online to ensure the whole build farm is kept as clean as possible.  When you have tools that require activation & licensing, this scenario quickly becomes problematic.  This leads me to another potential area for improvement.
  • Installation on Build Servers – If you know me well, this is a slightly less critical criticism than the first bullet point but also a pretty big pet peeve of mine. Smile  If you make tools, please don’t require them to be installed on the build server. It’s another thing that has to be kept up to date on potentially many machines and in a base system image.  I would rather be able to check them into a known version control folder and then have the build servers download the latest version during the build process.  There is even a supported mechanism in TFS Build that allows the build controllers & agents to watch for custom assemblies & tools and whenever it notices a new version of those assemblies then it gracefully updates all of the machines in the build farm automatically.  This allows team members to focus & introduce changes to the tools using version control instead of having to update the base image of the build server every time there is a new update.
    You also benefit from having full auditing of what exact tools version were used to produce a specific set of assemblies.  That allows you to potentially recreate a build you created a year ago by simply specifying what version of the source code (including build tools) to use during that build process.
  • Native Workflow Activity for TFS 2010 Build Process Templates -  The process I described in this blog article is definitely much more difficult than what it could be.  Instead of introducing customizations in the MSBuild-portion of the TFS build process, I much rather prefer dropping in a native workflow activity after the compilation process.  SmartAssembly unfortunately doesn’t have a custom TFS build workflow activity at this time.  I would love to see one that allowed me to specify multiple assembly inputs for each build configuration that occurs in the build process and then the appropriate SmartAssembly configuration file for each of the assemblies.  You can do some nice things with it to really make this process super easy.
  • Database Endpoint Instead of a Web Service Layer – SmartAssembly requires the entire team to have access to the centralized database to manage the automated error & feature usage reports.  The software makes direct database calls instead of going through a service layer is which is very different from the way that tools built for TFS are designed in general.  This can be problematic especially if you have TFS setup for your team to be able to access remotely over HTTPS (port 443) without the use of a VPN.  Several IT organizations,really don’t want to open their database ports or even give access to production database instances.  My suggestion would be to have an intermediate service layer that can “integrate” with the existing TFS IIS web sites.  This allows the tool’s service layer to piggy back on the existing infrastructure already setup for TFS.  If you have an SSL certificate and HTTPS configured, then you can take advantage of it.  If you have load balancing setup for scalability, then you could potentially leverage that as well!  We did this with our Notion Timesheet for TFS tools and one of the benefits we end up getting is that we are able to access the service layer from anywhere we can access TFS including over the Public Internet.  No worries about giving people access to the SQL Server instance as well.
  • Source Server Support – This isn’t necessarily a TFS-specific topic but really something for anyone using build servers & Source Server indexing.  When you compile on a build server, the location of the source code is included in the symbol information.  Your developers will normally not download the source code to the same location as other developers and particularly not the same location that the build server does since that changes depending on what TFS build agent is used on a build server for any particular TFS build.  Source Server Indexing helps to combat this particular problem by replacing the physical location with the location in the version control repository including the branch and version of the code used.  SmartAssembly has a feature that allows you to review details of stack trace, object values, etc. when you open an error report.  However, it doesn’t use the Source Server information even if it is stored in the symbol files.  This is particularly a problem when you are in a TFS environment and using automated builds.  SmartAssembly just ignores those additional streams in the symbols file.  SmartAssembly should use the Source Server information if it exists in the symbols to pull the appropriate version of source code from the version control repository.  (Red Gate Support Ticket Number:  F0041570)
  • Additional ALM Integration with TFS – There are so many different areas where SmartAssembly could shine if it had some additional ALM-specific integration with TFS!

Download Process Template

If you are interested in downloading the completely customized version of the build process template, I have included a link to it below.

Download SmartAssembly Process Template

 

 

Take care,

Ed Blankenship