Navigate in a Complex Windows Workflow

  • Article

Various tasks in Visual Studio require that you modify Windows Workflow files, some of which have complex structures and deeply nested elements. For example, the following kinds of files can be difficult to navigate and modify:

  • Custom templates for Team Foundation Build that are based on the Default Template.

  • Custom templates for Visual Studio Lab Management.

Some topics that explain how to work with such files describe the location of a specific element in a Windows Workflow file in shorthand syntax. This topic explains how to use this syntax to find a specific element that you want to work with.

In this topic

  • Example: "Run MSBuild for Project"

  • Use the Workflow Designer

  • Use the XML Editor

Example: "Run MSBuild for Project"

You create a custom build process by modifying a copy of the Default Template to change how the build process uses MSBuild to compile your code. To make this change, you must modify a property of the Run MSBuild for Project element.

  1. Sequence (Sequence) >

  2. Run On Agent (AgentScope) >

  3. Try Compile, Test, and Associate Changesets and Work Items (TryCatch [Try]) >

  4. Sequence (Sequence) >

  5. Compile, Test, and Associate Changesets and Work Items (Parallel) >

  6. Try Compile and Test (TryCatch [Try]) >

  7. Compile and Test (Sequence) >

  8. For Each Configuration in BuildSettings.PlatformConfigurations (ForEach [Body]) >

  9. Compile and Test for Configuration (Sequence) >

  10. If BuildSettings.HasProjectsToBuild (If [Then]) >

  11. For Each Project in BuildSettings.ProjectsToBuild (ForEach [Body]) >

  12. Try to Compile the Project (TryCatch [Try]) >

  13. Compile the Project (Sequence) >

  14. Run MSBuild for Project ()

This syntax shows you the nested structure that contains the element that you must locate. Each element follows the element that contains it. For example, the Run MSBuild for Project element is contained in the Compile the Project element, which is contained in the Try block of the Try to Compile the Project element.

Use the Workflow Designer

Consider the following aspects of using the Workflow Designer:

  • Advantage: You do not have to worry that you might make schema errors that break your workflow.

  • Advantage: You might be more comfortable with this approach if you prefer to work with a visual model instead of editing code.

  • Disadvantage: Some tasks might take longer with the designer than with a text-based editor.

  • Disadvantage: The Workflow Designer makes your workflow files larger than they would be if you edited them by using the XML Editor.

To open a Windows Workflow file in the Workflow Designer, open Source Control Explorer, find the folder that contains the .xaml file, and then double-click it.

Find text in the Workflow Designer

To find text while using the Workflow Designer, choose Ctrl+F, and then use the Find and Replace dialog box to find the text you are looking for (for example, MSBuild).

To navigate to the Run MSBuild for Project element by using the Workflow Designer, start by focusing on the top levels in the previous example:

  1. Sequence (Sequence) >

  2. Run On Agent (AgentScope) >

  3. Try Compile, Test, and Associate Changesets and Work Items (TryCatch [Try]) >

  4. Sequence (Sequence) >

  5. ...

In the Workflow Designer, make sure that you are looking at a fully collapsed view of the Process element. At the top of the Workflow Designer window, choose Process, and then choose Collapse All. The window now resembles the following view:

Top levels of the Default Template fully collapsed

To start to navigate to the element that you seek, perform either of the following steps in the Run on Agent element:

Two ways to navigate into a workflow element

If you double-click Double-click to view, the result resembles the following view:

Run On Agent activity in isolation

In this view, you can more easily concentrate your attention directly inside the element with which you are working. However, you lose sight of the broader context.

If you choose the ExpandExpand icon instead, the result resembles the following view:

Run On Agent activity in context

In this view, you keep the broader context visible, which can sometimes be helpful. But as you navigate more deeply into the structure, the complexity and size of the view might start to overwhelm you.

Use whichever method best suits your work. Repeat the pattern by starting at the top of the list and working your way through each element until you reach the element that you seek.

Use the XML Editor

Consider the following aspects of using a text-based editor such as the XML Editor:

  • Advantage: You can complete certain tasks more quickly and efficiently. For example, you can quickly make a global change.

  • Advantage: You might prefer this approach if you are comfortable working with code.

  • Disadvantage: You risk making a schema error that breaks your workflow.

  1. In Source Control Explorer, open the folder that contains your workflow.

  2. Near the top of the window, choose the link that appears next to Local Path.

    Windows Explorer appears and displays the contents of the folder.

    Note

    If the Not mapped link appears next to the Local Path label at the top of Source Control Explorer, choose the link to map the server directory to the appropriate directory in your local workspace.

  3. In Windows Explorer, hold down the SHIFT key as you open the shortcut menu for the .xaml file that contains the workflow. Release the SHIFT key, and then choose Copy as Path.

  4. In Visual Studio, open the File menu, and then choose Open, File.

  5. In the Open File dialog box, leave the cursor in the File name box, and then choose CTRL+V to paste the path.

  6. Choose the icon next to the Open button, and then choose Open With.

  7. In the Open With dialog box, choose XML (Text) Editor.

    Tip

    Choose Set as Default if you want to always use the XML (Text) Editor to edit .xaml files such as Windows Workflow files.

    Choose OK.

    The contents of your workflow appear in the XML (Text) editor window.

  8. Use the XML (Text) editor to find (for example, by choosing Ctrl+F) the element, and then make the changes you want.

    Important

    Make sure that none of your changes violate the rules of the workflow schema. Otherwise, the workflow may fail or function incorrectly.

Additional Resources

You can find additional information in the following topics on the Microsoft website: