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


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.


Comments (7)

  1. Girish says:

    Very nice. Long overdue though. Thank you very much for this wonderful blog post.

  2. BHardister says:

    Hi Andy, tried posting before signing in and it didn't appear to work. Sorry if this is a duplicate.

    Thanks for the posting! Here's my feedback…

    Windows Workflow shorthand syntax


    I think a picture of the activity in the context of the workflow designer provides the best map directions. What is most needed is the full hierarchical chart that we can refere to as a reference.

    Conceptual vs. step-by-step art


    Yes, please add more screen shots! Please use a screen shot to illustrate every step! Not only does this reduce the abiguity of the textual procedures, but when things don't work, the screen shot shows exactly what was done as part of a successfully executed procedure.  I almost always have to use other blog postings because MSDN library entries do not include the screen shots I need so that I can make sure I'm following the steps correctly. I can't emphasize this enough.

    Conciseness vs. completeness


    I think the approach here is super!  I love being able to go with the high-level steps and only jump into the details if I don't understand something or when something goes wrong

    Other Comments


    • Thank you for including an alternative that doesn't require updates to every single project in the solution!
    • PLEASE provide a download or full code block of the completed CustomOutputDirInline.xaml file

    Keep 'm comin.

  3. AndyLewis says:

    Bob, thanks for your detailed responses! This kind of feedback can really help me calibrate future content.

    I do have a question about your comments on the shorthand syntax. You suggest offering a full hierarchy outline, I agree that seems like potentially helpful material.  I'll consider that idea for possible future publication.

    But you seem to also be suggesting that a screenshot would be better than the shorthand syntax.  On MSDN I'm constrained to 675×480 pixels per graphic.  But even if I didn't have this constraint, I can't imagine how showing a screenshot of an activity nested 14 levels deep (as is the case with the MSBuild activity in this article) would work.  But if you are seeing an angle that I'm not thinking of, I'd love to hear it!  Can you post a screenshot somewhere and point us to it?

    Thanks again for your feedback.  As you stated so well yourself: "Keep 'm coming"!

    Andy

  4. Darrell Sveistrup says:

    Try to sperate the drop folder by project and got this error

    Illegal characters in path.

    Skipped execution of Revert Workspace because of BuildReason Manual

    Copy Files to Drop Location

    TF270003: Failed to copy. Ensure the source directory C:Builds1TOF ProgramAutoBuild.SampleDeploymentSolutionBinaries exists and that you have the appropriate permissions.

  5. AndyLewis says:

    Darrell: Really sorry about the delay in in your comment getting seen, posted. Blog is having technical difficulties. Just off the top of my head, I'm wondering if drop folder perms are an issue.  Here is an article that covers this area: msdn.microsoft.com/…/bb778394.aspx. I hope it helps.

  6. please provide a download for this topic says:

    should have been in the box fro the start. good work.

  7. Todd Taylor says:

    Thank you for the article, Andy.  I'm in the process of switching from TFS 2008 to TFS 2010 at work and it's a bit frustrating as to how little documentation there is available regarding build customization.  Your article is the first I found that has been helpfull.

    I was able to follow the steps in the article and my solution appears to be building each project in separate folders.  However, in my VS.NET solution, I have a mix of Windows Form apps, Windows Services, and several ASP.NET web applications.  The ASP.NET web applications don't seem to like the new build process.  When I look in the folders for the web applications, only the referenced assemblies are there as opposed to a published web site files (ASPX, CSS, etc.).   Should I not be using separate drop folders for web applications?