For an endeavor to count as an exploration, you can’t know exactly where you are going or what you will see until you get there. Even so, you are motivated by a strong hunch that there is fruitful territory “out there somewhere.” A true embodiment of the mysterious cone of uncertainty, at the beginning of such a journey you have very little confidence in your estimate of how long the work will take. As you strike out toward the tempting pool of water in the distance, sometimes you feel tremendous hope about the outcome, and sometimes you begin to fear you are approaching a mirage. One might easily assume that technical writers don’t get to have this kind of adventure. But I think many in our business would agree that we get to face both the delight and the discomfort of an empty page that has an uncertain future. Sometimes the journey requires us to foray into the realm of visual information, one that we verbal folks sometimes find a bit daunting in and of itself.

Take “Manage Build Information and Control Verbosity,” which I published last week. My initial goal was to simply tease out and clarify the key pieces of information needed to develop a build process that does not overload your system or your users with information.  The main piece was a fairly simple table that articulates the effect of each possible verbosity setting. I already had this table written, so the topic should have been fairly short and sweet to produce.  But there were a few loose threads I noticed that left questions in my mind. To follow one of them, I met briefly with one of the developers and drew a rough sketch on the whiteboard:

The sketch was not complete (and the handwriting was horrible!), and yet it also ventured outside the initial scope I planned for this topic. Even so, had an intuition that this larger context might be somehow helpful to customers, especially those new to our product. So I decided to invest more time and pressed on with more research, after which I developed this rough Visio draft for our artist:

While my optimism about the potential value of the outcome was increasing, I was a little worried about whether a reasonably complete and fully accurate diagram would fit into the MDSN format. I met in person with our artist and she showed a surprising and wonderfully cheerful attitude about helping me tame this beast. She sent me this draft:

This was a great first production draft, but there were lots of changes still needed, which I documented in OneNote, as you can see above. As I marked up the changes, I could see that this vision was looking more like a pool of water and less like a mirage as it came into sharper focus.

The end result:

You’ll notice in this final version of the image that I’ve begun to leverage some personas (Julia and Roberto) that I set up for our team a few months ago. At some point in the future I may blog a bit more about them.  Regardless, you can expect to see a lot more of these people in action, working through what I hope will be realistic and illustrative examples.

I hope the investment in the image proves to be worth the cost in terms of value to customers. But of course its ultimate success, and that of the topic (Manage Build Information and Control Verbosity) depends not on what I think, but on what you think. So in closing, as I often say, I look forward to hearing your feedback!

Andy

I would not normally bother to blog about content restructuring; but in fact, with this release I’m expanding coverage into some details that in the past have received shallow or no coverage at all. Our wing of the MSDN library now offers several new topics to help you understand and work with fundamental build process capabilities in the newly retitled Define Your Build Process.

Some of these topics include (or link to) more detailed explanations that I hope will be helpful:

• Specify Build Triggers and Reasons
• Use Your Build System to Work with Tests
• Manage Build Information and Control Verbosity
• Work with Build Workspaces

Some of this information was already published in multiple places, but is now consolidated:

• Work with Build Numbers
• Publish Symbol Data

I hope you find this material useful and its design to be efficient in giving you knowledge you need to do your job. As always, I welcome your feedback.

Andy

Preview of “Understand and Work with Build Workspaces”

During the build process, the build agent compiles and does other work with your source files. Before the build agent can do this work, it downloads the files from folders on your version control server into a local working directory. To facilitate downloading these files, the build agent creates a version control workspace, which maps the folders on the server to the local folders in the working directory for the build agent.

Before the build process starts

You set the working directory for each build agent in your build system. For more information, see Create and Work with Build Agents.

When you create your build definition, on the Workspace tab, you specify the folders that contain the files that you want to download and how these folders should be mapped to local folders on the build agent.

During the build process

The build process passes your workspace specifications to the CreateWorkspace workflow activity to create a workspace in its working directory.

The build process uses the DownloadFiles activity to download the files into the workspace. After this step, the build agent can start work (such as compilation) on these files.

Design a Workspace for Your Build Definition

When you design the workspace for your build definition, you should follow some best practices.

Include all required folders.

Make sure that you include all folders that contain files that your build process requires. For example, if you add another solution to the Items to Build field on the Process tab, you may need to add another mapping to the workspace.

Include only required folders.

Map with a Status of Active only the folders that your build process needs. If a subfolder of a mapped folder contains files not required by the build process, make sure to map it with a Status value of Cloaked. In many situations, when you create a build definition, the root folder of team project is mapped in the workspace. This configuration results in the build agent downloading all the files in the version control folder of your team project. If this folder contains lots of data, your build could waste build system resources and slow down your build process by downloading large amounts of data that it does not need.

When you remove items from the Items to Build field on the Process tab, look for mappings that you can remove from the workspace.

Use the $(SourceDir) token to map a server folder to a local folder in the ..\Sources subdirectory.

In most cases, the best location for the source files on the build agent is under the ..\Sources subdirectory in the working directory. You can specify this location by using the $(SourceDir) token in the Build Agent Folder box.

Be aware of how the workspace affects a build definition that is triggered by check-ins.

If you have set the Trigger of the build definition to Continuous Integration, Rolling builds, or Gated Check-in, the server folders that you map are bound to the build process. For example, if a developer checks in changes to a folder that is mapped in the workspace of a build definition that has a Gated Check-in trigger, those changes will be blocked until the build process is complete.

For more information about triggers, see Understand and Work with Build Triggers and Reasons.

Build Definition Workspace Example

Roberto, the build engineer, created the Storefront Nightly build definition.

This build definition builds two solutions: $/Core/Controllers/Controllers.sln and $/Core/Viewers/Viewers.sln. As a result, it must map the two folders that contain these solutions, the projects that they contain, and all the other files that they require.

To improve build process efficiency, Roberto excludes a folder that contains documentation files that his build process does not require: $/Core/Viewers/Docs.

The solutions depend on some binaries in a component library from another company. These binaries are protected by a proprietary mechanism that requires them to be located in a specific physical folder: c:\adatum\widgets.

Copy Data Among Workspaces

You can save time by copying mappings from one workspace to another.

To copy mappings from one of your workspaces

1. Click Copy Existing Workspace.

2. In the Select a Workspace to Copy dialog box, copy the mappings from the workspace.

To copy mappings from another build definition workspace or another team member’s workspace

1. Perform one of the following steps:

   • To copy mappings from another build definition workspace, open the build definition, and then click the Workspace tab.
   • To copy mappings from another team member’s workspace, ask the team member to open the File menu, click Source Control, and then click Workspaces. Select the workspace, and then click Edit.

2. Right-click a row in the Working folders table, and then click Select All.

3. Right-click a row in the Working folders table, and then click Copy.

4. Create a text file, paste the contents of the Clipboard into the text file, and then save it.

5. Create a build definition, or modify an existing build definition that is the target of the mappings that you are copying.

   For more information, see Create a Basic Build Definition or Edit a Build Definition.

6. On the Workspace tab, right-click a row in the Working folders table, and then click Paste.

7. As necessary, adapt the mappings for use by the build agent. In particular, make sure that the value in the Build Agent Folder box is correct and includes the $(SourceDir) token as appropriate.

For More Information

You define the build agent workspace when you create a build definition. For more information, see Create a Basic Build Definition.

A built agent workspace is basically the same mechanism as the version control workspace that a developer uses to work with source files in a team project. You can copy mappings between a version control workspace and a build agent workspace. For more information about version control workspaces, see Set Up your Development Machine to Work with your Team's Project.

Key strategies

I hope you find the above information to be useful and that it works better because it leverages the following strategies.

Explain key concepts in one place: This topic and others in the set will provide support to the other topics that support higher-level goals. For example, this topic provides background material that you can leverage whether you are managing a build agent, creating a simple build definition, or developing a customized build process template.

Emphasize best practices and avoid step-by-step guidance for trivial tasks: This goal can be elusive, so while I may not always hit it perfectly for every audience, I know its importance warrants that I continue to aim for it. As a Team Foundation Build customer you probably can figure out how to navigate a simple UI such as the workspace tab of the build definition editor. But even many advanced users still initially require an explanation of how a build workspace needs to be thought about and managed, especially when dealing with a large and complex codebase.

Use graphics to convey complex concepts and illustrate examples of success: Graphics are generally expensive, and there are additional costs to create and maintain them within the MSDN library system. So I don’t like to sprinkle them like candy into my topics just to make them look more approachable. That said, I know how daunting it is for a reader to face a wall of text about some complicated system. So with each major chunk of information I produce, I lift my hands from the keyboard and think for a moment about what kind of visual might do a better job of offering the information I’m about to type. I spend an extra moment doing so when I need to convey complex concepts or model how the product appears when it is being used successfully.

Offer links to peripheral information at the bottom when possible: Links are powerful tools that can serve a variety of purposes. But they can also distract attention and make material less readable. When a link goes to important but peripheral information, I try to offer it at the bottom of the topic to avoid distraction.

Feedback

As always, I welcome your thoughts and feedback about the content and the strategies, or any other suggestions for improving Team Foundation Build content.

The wait is over; now you can save about 15 steps and just download the template: CustomOutputDirImport.xaml. To use the template, after downloading it, you will need to check it in to version control and register it. For more information, see Register a Build Process Template with the System.

Andy

Easily asked, but not necessarily easily answered. In this article I hope to help you quickly understand the quality indicators available in Team Foundation Build and how you can use them to answer your own questions about the quality of your completed builds. I also aim to begin filling a subtle gap in the recently published details about the AssociateChangesetsAndWorkItems activity.

Three indicators of the quality of a completed build

Your Team Foundation Build system provides three primary indicators about how good a completed build is:

• Build status (automatic)
• “Build goodness” (automatic)
• Build quality (manual)

How build status and “build goodness” are evaluated

Before we explore all three indicators in detail, I think it will help for you to first see how the system generally evaluates the two automatic indicators:

These outcomes in the build...				Result in these quality indicators...
Result of code compilation Evaluated by the MSBuild activity Recorded in IBuildDetail CompilationStatus property	Result of tests Evaluated by the MSTest activity Recorded in IBuildDetail TestStatus property	Result of other steps in the build process Did all post-compilation and post-test steps in the Default Template (DefaultTemplate.xaml) succeed?		Build status	Build goodness
Succeeded	Succeeded	Yes		Succeeded	Good
Succeeded	Succeeded	No		Partially Succeeded	Good
Succeeded	Unknown or Failed	Yes or No		Partially Succeeded	Bad
Unknown or Failed	Succeeded, Unknown, or Failed	Yes or No		Failed	Bad

There are a few exceptions that can cause the build to be evaluated differently than is shown in the above table.  They are covered in the details below.

Build Status

Build status is the most prominent indicator of build quality in your build system.  You see it in both the build explorer and the build results window.

How build status is determined

Build status is evaluated in the Default Template (DefaultTemplate.xaml). In a build based on DefaultTemplate.xaml, build status is determined as follows:

• Succeeded
  • The MSBuild activity did not record a value of Failed in the IBuildDetail CompilationStatus property.
  • The MSTest activity did not record a value of Failed in the IBuildDetail TestStatus property.
  • Various other activities did not fail. These activities include, but may not be restricted to gathering test impact data (GetImpactedTests activity) and publishing symbol data (PublishSymbols activity).
• Partially Succeeded
  • The MSBuild activity did not record a value of Failed in the IBuildDetail CompilationStatus property.
  • One of the following occurred:
    • The MSTest activity recorded a value of Failed in the IBuildDetail TestStatus property and Fail Build on Test Failure was not selected when Automated Tests were specified in the build.
    • One of various other activities failed. These activities include, but may not be restricted to gathering test impact data (GetImpactedTests activity) and publishing symbol data (PublishSymbols activity).
• Failed
  • One of the following occurred:
    • The MSBuild activity recorded a value of Failed in the IBuildDetail CompilationStatus property.
    • The MSTest activity recorded a value of Failed in the IBuildDetail TestStatus property and Fail Build on Test Failure was selected when Automated Tests were specified in the the build.

If you develop a custom build process template, you can use the SetBuildProperties activity to force the build status to be whatever value you want based on your own workflow logic. If you use this approach, then the logic described above is disabled for any builds based on your custom build process template.

The build status for each build is stored in the data warehouse via the IBuildDetail Status property.

The effect of build status

Build status is displayed in the build results window and in Build Explorer. This indicator is used by the system to determine which retention policy to apply to a completed build.  For more information, see Create a Basic Build Definition.

“Build goodness” (or “last good build”)

I actually made up the phrase, “build goodness” because nowhere in the product does this phrase appear.  But as you will see, the concept behind build goodness is important.

How build goodness is determined

Build goodness is evaluated by Team Foundation Server internal logic, and thus cannot be customized. The rule is simple.  The build is “good” if both the IBuildDetail CompilationStatus property and the IBuildDetail TestStatus property are set to “Succeeded”. Otherwise, the build is “bad”.

Unlike build status, there is no attribute of a completed build in which build goodness is indicated.  Rather, a reference to last good build is recorded in the  IBuildDefinition LastGoodBuildLabel and  LastGoodBuildUri properties.

The effect of build goodness on the AssociateChangesetsAndWorkItems activity

Build goodness has one very important effect, which is that it is used by the AssociateChangesetsAndWorkItems activity to determine which completed builds are associated with recent changesets and their associated work items. Specifically, the AssociateChangesetsAndWorkItems activity:

1. Attempts to locate the last good completed build from the same build definition. If the last good build is located, it continues to the next step.  Otherwise, it stops here.
2. Compiles a list of all the changesets applied to items mapped in the workspace defined in the build definition.
3. Associates the changesets, along with any work items to which they are linked, with the completed build.

Build quality

Build quality is simply a string that someone on your team uses to characterize the quality of the completed build. 

How build quality is determined

You manually set this value, as explained in Rate the Quality of a Completed Build. You can also customize the list of build quality values, as explained in Add or Remove Build Quality Values.

The effect of build quality

Build quality is displayed at the top of the build results window of a completed build.  It is also displayed and can be used to filter the view in Build Explorer.

Closing

This post is the result of one of several key concept article ideas that crystalized in my mind as I researched and wrote Team Foundation Build Activities. I also want to express my thanks to Ed Blankenship, whose comment inspired me to write this blog post.  He promptly pointed out a subtle gap in the section on AssociateChangesetsAndWorkItems, a gap that I hope this article partly fills.

I aim to blog additional experimental drafts such as this one, and then eventually publish the material on MSDN. Is this kind of information helpful?  Is the above explanation of how the AssociateChangesetsAndWorkItems activity works sufficient?  Or would you like to see the behavior laid out in more detail with examples and graphics? As always, I welcome your feedback.

Andy

But suppose you need your build process to run some custom process against the binaries after building the code. Or to publish some documentation to a web server. My anecdotal experience from monitoring various virtual user groups has left me with the impression is that specialized build processes are the norm rather than the rule.

If you are one of these customers, here is my holiday present to you, hot off the presses:

Team Foundation Build Activities

This article describes in detail the Team Foundation Build Activities, which are the fundamental components of the build process. I wrote this topic with hopes of making it as easy as possible for you to create your own custom build process.

Floor wax and dessert topping

As I researched this content, I saw two major use patterns: reference and usage guide. A reference answers questions such as: What does this activity do?  What is this property for? But I also wanted to help the developer working from the other side of the equation, focused on a specific goal they have in mind.  So the answer to whether I should structure the content as a reference or as a usage guide was: both; both a floor wax and a dessert topping.

Reference: How do I work this?

I know that many readers need the answer the question best expressed by the Talking Heads: “How do I work this?” So in the topic you will find an alphabetical list that contains a link to information about each activity.

Usage guide: How do I get there from here?

Whenever I get an opportunity to spend some time writing code, I hope for but often don’t get a goal-oriented guide to the classes, methods, functions, or whatever set of constructs I’m working with. So in the topic I offer a list of goals. I also organized the material by goal to support easier reading from end to end.

Leaves a shine? Tastes great? Other?

One other major design decision I made was to use a minimalist approach wherever possible. I enumerate the properties in lightweight bulleted lists instead of tables. I am intentionally inconsistent, abbreviating sections that cover simple activities. When I need to point to a deeply embedded element in the workflow, I use a terse but hopefully easily traversed format (as described in Navigate in a Complex Windows Workflow).

How does the format of Team Foundation Build Activities work for you? Any information not covered that you need? As always, I welcome your feedback.

Andy

My generation was the first to spend teen years with video games. Many an afternoon I walked with my friend to the mall, where we sought out a darkened cacophonous arcade. A stout man in a blue uniform changed our dollars to quarters from a money changer on his belt, and away we went to blow up asteroids, gobble energy pellets, and make ultimately futile attempts to save cities from thermonuclear destruction.

If you grew up with the first wave of video games too, you must see The King of Kong. One of the best documentary films I’ve ever seen, it is both moving and funny. At 17:30, the protagonist's son shrieks, “Don’t play! Don’t play!  Stop playing Donkey Koooooong!” Can’t think of a better illustration of the work/life/game balance problem.

When I worked in Silicon Valley, my co-workers and I enjoyed many a beer-bash Friday blowing each other up in the Marathon arena.  Now that I’m at Microsoft, a few friends have given me a hard time for not having an Xbox. But I agreed with my wife to delay buying in; too much going on in our lives: children, a couple of moves across the country, working for Microsoft, etc.

The Kinect barges into our house

So for years we’ve had no video games in our home, and yet as with cars and toy guns, you can try to withhold these things, but your son will find them somehow anyway. Mostly it happened when family or friends brought out a Wii.  It was great entertainment watching him laugh, jump around, and dance with his little legs. I wanted to play together. When Microsoft introduced the Kinect at the annual company meeting, I finally saw what I hoped would come: Xbox casual family games. But I hadn’t dreamed the outcome would be so innovative and compelling. I ordered one that day.

Flash forward a few months to today, and already the Xbox Kinect has disrupted our lives in ways that are both wonderful and sometimes not so much.  One big challenge that everyone should know about is that you must have at least 7-8 feet, but ideally about 10 feet of empty floor space in front of the Kinect.  In our small TV room, a large entertainment center holds an old-school CRT TV.  So to accommodate the Kinect, we had to downsize, replacing a sectional couch with a few chairs that can be pushed to the side.

We also are talking about ways manage video game sessions in various contexts: weeknights, when company comes, etc. Sometimes the Xbox takes control of the evening and must be reined in.  And yet I’m delighted that delaying introducing video games into my son’s life seems to have had the effect we hoped for.  He actually does a decent job of detaching from it all by himself; after an hour or so, he often walks away to build something with his toys or play with his train set.

The Kinect scores

When I introduced my son to the Kinect, he immediately got it. He has since said a few times, voice choking with emotion, how a video game is all he ever wanted. (I guess he forgets that only a few months ago his baby sister was all he wanted.) It has been a blast watching him immediately grasp the simple interface then jump, swat, and steer with such intensity and delight. His friends now want to come to our house and lament that they have only a Wii.

As for the Kinect games themselves, they are pretty much everything I’d hoped they would be.  Kinect Adventures is the perfect introduction to full-motion gaming.  You use your whole body to hit or kick a ball, jump and duck past obstacles, and even surf through the clouds. The simple interface, forgiving physics, and fun diversions of Joy Ride makes it a perfect experience for making young children feel like they are in the “driver’s seat”, although it must be played standing up.

I think what got my wife to partly forgive the intrusion of the Xbox is Dance Central, which stands out as the coolest game in terms of full-body motion.  The whole idea that swinging a white nun chuck around is like dancing now seems so silly.  Dance Central offers beginner-level moves, but you can quickly ramp up to harder dances. The on-screen dancer’s limbs light up in red to show you where you even subtle mistakes on any part of your body, and thus help you learn the moves. The announcer offers both praise and critiques in fun ways. It feels really good to spend that precious 1 hour or so of free time after the kids go to bed dancing instead of sitting on the sectional watching TV.

I do use the Xbox controller too. Halo? Nah, not right now. I spin up Galaga or Time Pilot. Somehow playing these vintage games after a virtual river raft adventure feels just right to me. (And I get to play for free; no quarters needed!) I can’t imagine replacing the classic joystick and Fire button with a Kinect interface. And yet, I keep dreaming of ideas for how to the Kinect could be used in all kinds of new ways and expanded into new markets.

I don’t know when I’ll have time to explore these ideas further. But for now, I can’t remember ever feeling this proud of a Microsoft consumer product. So pull out a tape measure, check floor space in your TV room, and then go check it out: http://www.xbox.com/kinect!

While it is not much to look at in the conventional sense, the command prompt is truly a thing of beauty if you love speed and efficiency. (Want to see more? Behold this gallery: command prompt.)

“Healthy laziness” at the keyboard

I love a good shortcut and I believe this is “healthy laziness”; that is, the urge to find ways to reduce or even eliminate time spent on menial tasks. I want to conserve time and energy for analysis (solving problems in my code), creativity (designing something), or for just being able to get home in time for diner.

Back in the day, I used the command prompt a lot more.  When I first started using Windows 3.1, I think I actually recall feeling relieved that I wouldn’t have to boot DOS in order to get work done quickly.  There is something so satisfying about blasting through a task, fingers never leaving the keyboard to reach for the mouse.  In response, your computer rolls those cool cryptic messages upward across a black window.

Another great example of this kind of bliss can be found by using keyboard shortcuts, the most powerful of which are sometimes obscure.  Need a calculator?  Press START+R, in the Run dialog box type “calc”, and press ENTER. To maximize the vertical screen real estate of a window in Windows 7 or Windows Server 2008 R2, press START+SHIFT+UP_ARROW. Want to put all the windows away, press START+D.  How far can you go in your day without reaching for the mouse? I think this is fun stuff, and it saves wear and tear on my mouse arm and hand.

How the VS command prompt can augment the Visual Studio IDE

You don’t have to be an Emacs command-line purist to enjoy the benefits of the command prompt. While I was researching Control Where the Build System Places Your Binaries, I repeatedly needed to test the outcome of a few changes to a few files. For this kind of scenario, you can’t test the outcome of your work locally. Essentially you must:

1. Tweak various XML files such as a build process template XAML file and a few VS code project files.
2. Check in the modified files.
3. Queue your build.
4. View your build results.
5. Return to step 1 as many times as needed until your build process functions the way you want.

At first I used only the Visual Studio IDE for many cycles of this task. I started to get tired of having to click through the same UI over and over again. It then occurred to me that I could use the command prompt to save some time.

tf checkin /noprompt (check in all the stuff I’ve changed)

When you use the IDE to check-in files, you have to open the window, view the files that have changed, make sure they are selected, and then click the button. But when you are repeatedly changing only a few files and you know you simply want to upload them all, you can simply issue this command:

tf checkin /noprompt

Of course, before you do this you should first really be sure that you really know all the files you’ve changed. Not sure?  Well, simply type:

tf checkin

to get a list of the files you’ve changed.

tfsbuild start (queue a build)

Immediately after I checked in my changes, I didn’t even need to leave the command prompt.  I simply entered the following command:

tfsbuild start http://contoso-team:8080/tfs/defaultcollection Test "Build My Utilities"

With the tf checkin and the tfsbuild start command invocations stored in the command history buffer, each time I modified a set of files, I was only a five keystrokes away (including the ALT+Tab to switch from the IDE to the command prompt) from testing the latest changes I made.

A few tips for newbs

A few tips that might help if you have not had much experience with the Visual Studio command prompt:

• Launch the Visual Studio Command prompt: Click Start, click All Programs, click Microsoft Visual Studio 2010, click Visual Studio Tools, and then click Visual Studio Command Prompt (2010).
• Select a workspace for version control commands: In Visual Studio, the Workspace drop-down menu at the top of Source Control Explorer is what determines the workspace you are working in. But in the command prompt, the current directory is what determines the workspace you are working in.
• Get the team project collection URL: Some commands (such as tfsbuild start) require this data, and you can quickly get it in Visual Studio by going to Team Explorer, right-clicking the team project collection, and then clicking Properties.  The URL appears in the Properties pane.
• Cycle through the command history buffer: Press the up and down arrow keys to re-use commands you have already entered.
• Auto-complete file or directory names: when a file name or directory is an argument, type a few letters of and then press the Tab key one or more times to cycle through the names that match the letters you typed.
• Get help with a command: Use the /? argument to get brief help within the command line window (e.g., tf checkin /?).  For tf.exe (version control) commands, you can use the msdn argument to display the MSDN help about a command (e.g. tf msdn checkin).

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:

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.

If you see any issues or omissions, please let me know. (I’ve already spotted the broken internal link in step 1; the fix is slated to be published in the next month or so.)

Andy