Everything you wanted to know about custom build processes (but were afraid to ask)

  • Article

Classic career success principal: under-promise and over-deliver. In that sense, the above title is a bad idea. But today I’m turning the old saw on its head to direct your attention to a topic we published yesterday: Control Where the Build System Places Your Binaries. I’m hopeful this material veers into some fruitful territory, but I know that there is a lot of important ground still to cover when it comes to custom build processes. And in future publications of MSDN, more material is on the way.

But for today my goal is to spark a conversation about this topic in particular, and in general about the best ways for our content to support your success in using Team Foundation Build.

Control where the build system places your binaries

As I researched this topic, I aimed to find a basic and common goal for a relatively simple custom build process. However, I felt it was equally important to illuminate a scenario that included techniques that are generally useful across the long tail of custom build process scenarios.

I settled on the goal of controlling where the build system drops the compiled binaries. The default build process (defined in DefaultTemplate.xaml) drops the compiled binaries from all code projects into a single directory:

Default flow

However, you might want to organize the binaries into a more granular and organized directory structure.  And so yesterday we published a topic that covers to how to create a custom build process that drops your binaries where you want them. But we also aim to teach some techniques that I hope are generally useful when you are creating many kinds of customized build processes.

Here it is:

Control Where the Build System Places Your Binaries

I already know of a few minor tweaks I need to make to the article.  But I have several big questions on my mind about which structures, formats, and techniques would best support you.

Windows Workflow shorthand syntax

DefaultTemplate.xaml contains a complex structure with deeply nested elements. In the topic, I need to direct you to the 2nd invocation of the MSBuild activity, which is where your code projects actually get compiled.  This activity is embedded 14 levels deep. So I use the following “shorthand syntax” to help you locate the activity:

  1. Sequence >
  2. Run on Agent >
  3. Try Compile, Test, and Associate Changesets and Work Items [Try] >
  4. Sequence >
  5. Compile, Test, and Associate Changesets and Work Items >
  6. Try Compile and Test [Try] >
  7. Compile and Test >
  8. For Each Configuration in BuildSettings.PlatformConfigurations [Body] >
  9. Compile and Test for Configuration >
  10. If BuildSettings.HasProjectsToBuild [Then] >
  11. For Each Project in BuildSettings.ProjectsToBuild >
  12. Try to Compile the Project [Try] >
  13. Compile the Project >
  14. Run MSBuild for Project

(Next month I will refine the shorthand syntax to use an ordered list as I do above instead of a Code block.) I then offer a link to a generic support topic: Navigate in a Complex Windows Workflow. I used this technique in lieu embedding 14 additional steps within the procedure.

How well does this technique work for you?

Conceptual vs. step-by-step art

I wanted make crystal clear the high-level concepts such as: the default process, the custom process, how the key pieces come together. So I spent a good bit of time on conceptual art at the expense of step-by-step screenshots.

Were the conceptual art pieces clear?  Did they help accelerate you through the learning curve? Do you need a screenshot for each step? 

I’m open to adding more screenshots to this kind of guidance in the future, but I’m wondering how much they are needed (there is some cost to adding them), and somewhat worried about making the topic harder to read by making it more bloated and cluttered. Would you want them for every step, or perhaps only now and then to show you are on the right track, with an emphasis on displaying the trickier parts of the task?

Conciseness vs. completeness

As a writer, I find one of the most interesting challenges to be determining the right level of detail to offer. Getting this right is especially tricky when serving an audience with diverse backgrounds, levels of experience, technical capabilities, etc. In this topic, I tried to leave out the most obvious instructions (for example, launching Source Control Explorer).  I also tried to support more advanced users with a couple of “Overview of the steps that you follow” sections.

What do you think? Too many details, or did I leave out some that you needed? Were the “Overview of the steps…” sections helpful at all in accelerating your learning curve, or did they get in the way?

Note: I would love to leverage JavaScript to hide some detailed steps in order to accelerate skimming the topic , especially for advanced readers. I used this technique when I used to cover SharePoint Designer.  For example: Use JavaScript to enable formatting of Data View UI controls. This kind of tool is not available on MSDN, but I’m looking into it.

Customization patterns

In the topic we cover some customization patterns on both the Windows Workflow and the MSBuild sides of the fence. I list the patterns we cover at the top of the topic. Did we cover these patterns well? Are there some other patterns that you would like to see covered?

Don’t be shy

In fact, I have seen no shyness in the TF Build community when it comes to asking tough questions and sharing opinions. This is goodness. I want to channel some of that energy into improving our content. I’d love to hear your specific opinions on the above questions and also your general thoughts and ideas about what content is most sorely needed to make you more successful in working with Team Foundation Build.