Sunday, June 29, 2014

Switching from SVN to TFS - via Visual Studio Online

At work we've been using SVN for source control and we were using as our hosting provider until they evaporated into thin air last week.  Apparently, they had a weak password....critical mistake.  It was rather scary to realize that the code you thought was safe could so quickly be gone. Thankfully, I had recent pulls of all our SVN repositories on my laptop.   

I viewed this tragedy as an opportunity to move over to Visual Studio Online, which is the cloud version of Team Foundation Server.  I'd been using this service for a few personal projects. It's free for teams of up to five and you can't beat free for a price. 

It became apparent rather quickly that there are several decisions that must be made when setting up a TFS team project. Do you use one team project for each VS solution that you want in source control?  What project management template do you use - Agile vs. Scrum?  Honestly, after using SVN for so long it felt a little daunting.  Not everything SVN equates in the world of TFS.

As I started migrating code across from SVN to TFS, I tried to keep track of the decision points and lessons learned.  

Visual Studio Online 

TFS = ALM = More than Source Control
TFS is more than just source control.  TFS is also an ALM (Application Life-cycle Management system).  Microsoft has put together a set of documentations on CodePlex designed to quickly bring you up to speed. 

SVN convention is to use three directories (trunk, tags, and branch) to manage your branching workflow.  TFS convention seems to be to use a main folder in place of trunk.  Branches derive from main, much like in SVN, however, there is not an equivalent concept of tags.  TFS provides a label (which could be thought of as a weak tag) and it really just serves as a marker commit chain.  On the upside, TFS provides a very cool feature called Shelvesets, essentially allowing a commit to source control that doesn't go directly back into the branch of code your working from.

Information sourced from 

One or Many - Team Projects 
My first attempt at setting things up in TFS mimicked what I did with SVN and I started creating team projects for every SVN repository that I had.  However, work planning often spans project boundaries, making a team project for every set of source code a less than ideal solution.  

The takeaway is this
    • Having one team project provides greater flexibility than having several
    • Team projects at this point in time cannot be renamed 
    • Within one team project renaming and reorganize is simple
    • Work areas provide separation for project planning
    • Within one team project, separate teams can be created as needed
Information sourced from 

External Dependencies
At first, it was not obvious to me how to manage several separate, sometimes interconnected projects in TFS.  In SVN, every solution was committed to its own repository.  If there was a dependency between projects, it was simple to use tags with an external dependency to compose interdependent projects together.

In TFS the recommendation is to use binaries for external dependencies.  There are two ways to do this. Commit the dependency .dll's along with the source code or the fancy new method of using a local NuGet server.  Microsoft's ALM quick-start leans in favor of  using a local NuGet server if possible. If you do go the route of including the dependencies in a folder within the project, make sure it gets checked in. The .dll's are excluded from source control by default.

Information sourced from 

Removing a Team Project
After switching to one team project to manage all our code, I realized that I wanted to delete all the single team projects I had created.  This at this point, cannot be done through the online management portal.  A simple command line argument can be used to safely remove old team projects.

Information sourced from

Setting up Builds, Dropping to TFS server
TFS in Visual Studio Online has an integrated build server.  This has varying levels of usefulness depending on your project.  One of the build drop options is to drop it directly onto the TFS server.  This is a nice feature, which hopefully in the future will allow for some way to publicly expose the drops for external project stakeholders.

Information sourced from
Team Foundation Service updates - Oct 29

Scrum Vs. Agile
Previous to TFS, we managed our work backlog through emails, notes on scratch paper and verbal banter.  Needless to say, anything is probably an improvement to that.  We'd tried several things, but in reality we found that we never used our tools, simply because they were so separate from VS, where we needed them.  VS 2013 has very nice integration with Visual Studio Online, which has solved this issue for us.

When setting up a team project, you are asked to choose a process template.  Several templates are presented, among them templates for Agile and Scrum.  Not knowing a whole lot about either methodology, I ended up choosing the Scrum process template based the following two blog posts.

Agile vs Scrum process templates - TFS
Scrum for Everyone

While we are not currently using the project management tools to their full potential, I'm sure thatas we learn more about the methodology the tools will give us more value.

The Verdict
Microsoft is providing a great service at a great price.  The holistic approach of providing project management tools along with source control makes sense.  Currently there are a few week points. SharePoint via Office 365 doesn't integrate well with Visual Studio Online. And there is no simple built-in way to provide external stakeholders with code drops from automated builds. However, I'm sure as the product matures MS will continue to integrate and innovate to continue providing value.  

Saturday, June 14, 2014

Uncle Bob's Advice on Clean Code

Several years ago, I read Robert C. Martin's book, Clean Code: A Handbook of Agile Software Craftmanship and I was inspired to write cleaner, higher quality code.

Uncle Bob has created a video series that goes beyond the material covered in his book. Recently, in an effort to better grasp all of the SOLID principles, I started watching the video series from the beginning. The format is entertaining and the material is thought provoking.

The basis of episode 1 "Clean Code," (and for that matter, the entire series), is that code is written for humans. Code has to be maintained. After code is written, it is read over and over again during maintenance. While it may be subjective as to what clean code actually looks like, Uncle Bob makes many strong arguments about what makes code maintainable.

So far I've watched four episodes and I've been thoroughly entertained and inspired. I'm amazed at how much I have learned.  The second episode talks about code, space, class and function names. The third and forth episodes dig into functions.  Here is a short outline of episodes three and four to give you an idea of what the video contains:

After a brief astronomy lesson, Uncle Bob starts appearing in all varying places all over the world talking about functions.  A set of guidelines for writing functions is given.  For example, functions shouldn't have more than three parameters and functions shouldn't take a Boolean as a parameter. He gives solid arguments as to why that is. If the pointy haired boss threw something like that into a requirement document, you'd probably be inclined to question the sanity of his reasoning.  Thankfully, it's coming from Uncle Bob, who's time in the industry has served as a proving ground for his reasoning on clean code.

If you haven't ever read the book Clean Code, check it out.  If you have, check out the videos...They offer a deeper dive into the material in a very entertaining package.

Saturday, June 7, 2014

NuGet - Failed to initialize the PowerShell Host.

While loading AutoMapper from NuGet, I encountered the following error.

Failed to initialize the PowerShell host. If your PowerShell execution policy setting is set to AllSigned, open the Package Manager Console to initialize the host first.

A little searching yielded the following post.

The trick is to close Visual Studio, open PowerShell as an administrator, then change the execution policy to something less restrictive.  Then re-open Visual Studio, and re-attempt the NuGet install. I've noticed if I don't leave PowerShell running when I do this, it doesn't work.  Notice that the magic PowerShell command is "Set-ExecutionPolicy" Unrestricted

I had to iterate on this a few times, and to get AutoMapper to install I had to go all the way down to Unrestricted.  After updating I changed it back to AllSigned...

Tuesday, June 3, 2014

Generating Help Documentation from XML Comments in .Net

Everyone seems to agree that using XML comments/documentation in code is the best way to keep code documents maintainable.

I've been working on a project, diligently filling in XML documentation on the public classes and methods in our API.  I knew I'd read plenty of articles on the web that described how documentation should be in one place and how a tool should be used to help generate documentation from the code base.  However, I had not dug into the actual implementation surrounding how to accomplish this utopia in a project.

After a few searches, the following became evident.
  • There is not a tool from Microsoft to transform the XML documents from code into something useful like a help file or website. 
  • However...
    • Microsoft used to have one called Sandcastle, development stopped a few years back.  
    • Development continues as an open source project called Sandcastle Help File Builder
      • Sandcastle Help File Builder provides
        • VS integration.
        • Command line
        • GUI
  • Doxygen is a great option for several languages, including C#
    • Doxygen can technically be used with VB.Net, but currently the links to any working scripts to get that functioning seem to be broken.
    • Doxygen provides
      • Command line
      • GUI
With that information, I was able to make an informed decision as to what tool I'd use on my current project. I ended up going with Sandcastle.  Like most new things, it takes some getting used to.  The documentation for how to use Sandcastle Help File Builder is top notch, so I won't go into detail.  The integration with Visual Studio is great, as it makes all the configuration feel somewhat familiar.  If you're looking for a documentation tool for your project, I'd recommend checking it out.

General XML Comment References:
MSDN Magazine June 2002
MSDN Magaize May 2009
C# Programming Guide
XML Comment Cheat Sheet