Migrate from XAML builds to new builds

Last Update: 6/30/2017

Team Services | TFS 2017 RTM | XAML builds

We introduced XAML build automation capabilities based on the Windows Workflow Foundation in Team Foundation Server (TFS) 2010. We released another version of XAML builds in TFS 2013.

After that we sought to expand beyond .NET and Windows and add support for other kinds of apps that are based on operating systems such as macOS and Linux. It became clear that we needed to switch to a more open, flexible, web-based foundation for our build automation engine. In early 2015 in Team Services, and then in TFS 2015, we introduced a simpler task- and script-driven cross-platform build system.

Because the systems are so different, there's no automated or general way to migrate a XAML build definition into a new build definition. The migration process is to manually create the new build definitions that replicate what your XAML builds do.

If you're building standard .NET applications, you probably used our default templates as provided out-of-the-box. In this case the process should be reasonably easy.

If you have customized your XAML templates or added custom tasks, then you'll need to also take other steps including writing scripts, installing extensions, or creating custom tasks.

Overview of the migration effort

Here are the steps to migrate from XAML builds to newer builds:

  1. If you're using a private TFS server, set up agents to run your builds.

  2. To get familiar with the new build system, create a "Hello world" build definition.

  3. Create a new build definition intended to replace one of your XAML build definitions.

    1. Create a new build definition.

    2. Port your XAML settings.

  4. On the General tab, disable the XAML build definition.

  5. Repeat the previous two steps for each of your XAML build definitions.

  6. Take advantage of new build features and learn more about the kinds of apps you can build.

  7. Learn how to customize, and if necessary extend your system.

  8. When you no longer need the history and artifacts from your XAML builds, delete the XAML builds, and then the XAML build definitions.

    WARNING

    After you delete the XAML builds and definitions, you cannot get them back.

Create new build definitions

If you're building a standard .NET app, you're probably using one of the out-of-the-box build templates such as TfvcTemplate.12.xaml or GitTemplate.12.xaml. In this case, it will probably just take you a few clicks to create build definitions in the new build system.

  1. Open your team project in your web browser ▼

    Browse to team project

    (If you don't see your team project listed on the home page, select Browse.)

    • On-premises TFS: http://{your_server}:8080/tfs/DefaultCollection/{your_team_project}
    • Visual Studio Team Services: https://{your_account}.visualstudio.com/DefaultCollection/{your_team_project}

    The TFS URL doesn't work for me. How can I get the correct URL?

  2. Create a build definition (Build & Release tab > Builds) ▼

    Build tab

  3. Select a template to add the commonly used tasks to your build definition:
    • TFS 2017 RTM: Visual Studio template
    • Team Services: .NET Desktop template
  4. Make any necessary changes to your build definition to replicate your XAML build definition. The tasks added by the template should simply work in many cases. But if you changed process parameters or other settings in your XAML build definitions, below are some pointers to get you started replicating those changes.

Port your XAML settings

In each of the following sections we show the XAML user interface, and then provide a pointer to the place where you can port the setting into your new build definition.

General tab

xaml build general tab

XAML setting TFS 2017 RTM equivalent Team Services equivalent
Build definition name You can change it whenever you save the definition.

When editing the definition: On the Tasks tab, in left pane click Process, and the Name field appears in right pane.

In the Builds hub (Mine or All Definitions tab), open the action menu and choose Rename.

Description (optional) Not supported. Not supported.
Queue processing Not yet supported. As a partial alternative, disable the triggers. Not yet supported. As an alternative, disable the triggers.

Source Settings tab

TFVC

xaml build source settings tfvc

XAML setting TFS 2017 RTM equivalent Team Services equivalent
Source Settings tab On the Repository tab specify your mappings with Active paths as Map and Cloaked paths as Cloak. On the Tasks tab, in left pane click Get sources. Specify your workspace mappings with Active paths as Map and Cloaked paths as Cloak.

The new build definition offers you some new options. The specific extra options you'll see depend on the version you're using of TFS or Team Services. If you're using Team Services, first make sure to display Advanced settings. See Build definition respository: TFVC.

Git

xaml build source settings git tfs

XAML setting TFS 2017 RTM equivalent Team Services equivalent
Source Settings tab On the Repository tab specify the repository and default branch. On the Tasks tab, in left pane click Get sources. Specify the repository and default branch.

The new build definition offers you some new options. The specific extra options you'll see depend on the version you're using of TFS or Team Services. If you're using Team Services, first make sure to display Advanced settings. See Build definition repository: Git.

Trigger tab

xaml build trigger tab

XAML setting TFS 2017 RTM and Team Services equivalent
Trigger tab On the Triggers tab, select the trigger you want to use: CI, scheduled, or gated.

The new build definition offers you some new options. For example:

  • You can potentially create fewer build definitions to replace a larger number of XAML build definitions. This is because you can use a single new build definition with multiple triggers. And if you're using Team Services, then you can add multiple scheduled times.

  • The Rolling builds option is replaced by the Batch changes option. You can't specify minimum time between builds. But if you're using Team Services, you can specify the maximum number of concurrent builds per branch.

  • If your code is in TFVC, you can add folder path filters to include or exclude certain sets of files from triggering a CI build.

  • If your code is in TFVC and you're using the gated check-in trigger, you've got the option to also run CI builds or not. You can also use the same workspace mappings as your repository settings, or specify different mappings.

  • If your code is in Git, then you specify the branch filters directly on the Triggers tab. And you can add folder path filters to include or exclude certain sets of files from triggering a CI build.

The specific extra options you'll see depend on the version you're using of TFS or Team Services. See Build definition triggers

We don't yet support the Build even if nothing has changed since the previous build option.

Build Defaults tab

xaml build build defaults tab

XAML process parameter TFS 2017 RTM equivalent Team Services equivalent
Build controller On the General tab, select the default agent queue. On the Options tab, select the default agent queue.
Staging location On the Tasks tab, specify arguments to the Copy Files and Publish Build Artifacts tasks. See Build artifacts. On the Tasks tab, specify arguments to the Copy Files and Publish Build Artifacts tasks. See Build artifacts.

The new build definition offers you some new options. For example:

  • You don't need a controller, and the new agents are easier to set up and maintain. See Build and release agents.

  • You can exactly specify which sets of files you want to publish as build artifacts. See Build artifacts.

Process tab

TF Version Control

xaml source settings git tfs

XAML process parameter TFS 2017 RTM equivalent Team Services equivalent
Clean workspace On the Repository tab, open the Clean menu, and then select true. On the Tasks tab, in left pane click Get sources. Display Advanced settings, and then select Clean. (We plan to change move this option out of advanced settings.)
Get version You can't specify a changeset in the build definition, but you can specify one when you manually queue a build. You can't specify a changeset in the build definition, but you can specify one when you manually queue a build.
Label Sources On the Repository tab, select an option from the Label sources menu. Tasks tab, in left pane click Get sources. Select one of the Tag sources options. (We plan to change the name of this to Label sources.)

The new build definition offers you some new options. See Build definition repository.

Git

xaml source settings git tfs

XAML process parameter TFS 2017 RTM equivalent Team Services equivalent
Clean repository Repository tab, open Clean menu, select true. On the Tasks tab, in left pane click Get sources. Show Advanced settings, and then select Clean. (We plan to change move this option out of advanced settings.)
Checkout override You can't specify a commit in the build definition, but you can specify one when you manually queue a build. You can't specify a commit in the build definition, but you can specify one when you manually queue a build.

The new build definition offers you some new options. See Build definition repository.

Build

xaml source settings git tfs

On the Build tab (TFS 2017) or the Tasks tab (Team Services), after you select the Visual Studio Build task, you'll see the arguments that are equivalent to the XAML build parameters.

XAML process parameter TFS 2017 RTM, Team Services equivalent argument
Projects Solution
Configurations Platform, Configuration. See Visual Studio Build: How do I build multiple configurations for multiple platforms?
Clean build Clean
Output location The Visual Studio Build task builds and outputs files in the same way you do it on your dev machine, in the local workspace. We give you full control of publishing artifacts out of the local workspace on the agent. See Artifacts in Team Build.
Advanced, MSBuild arguments MSBuild Arguments
Advanced, MSBuild platform Advanced, MSBuild Architecture
Advanced, Perform code analysis Use an MSBuild argument such as/p:RunCodeAnalysis=true
Advanced, post- and pre-build scripts You can run one or more scripts at any point in your build process by adding one or more instances of the PowerShell, Batch, and Command tasks. For example, see Use a PowerShell script to customize your build process.
IMPORTANT

In the Visual Studio Build arguments, on the Visual Studio Version menu, make sure to select version of Visual Studio that you're using.

The new build definition offers you some new options. See Visual Studio Build.

Learn more: Visual Studio Build task (for building solutions), MSBuild task (for building individual projects).

Test

xaml source settings git tfs

See Get started with continuous testing and Visual Studio Test task.

Publish Symbols

xaml source settings git tfs

XAML process parameter TFS 2017 RTM, Team Services equivalent
Path to publish symbols Click the Publish Symbols task and then copy the path into the Path to publish symbols argument.

Advanced

xaml source settings git tfs

XAML process parameter TFS 2017 RTM equivalent Team Services equivalent
Maximum agent execution time None On the Options tab you can specify Build job timeout in minutes.
Maximum agent reservation wait time None None
Name filter, Tag comparison operator, Tags filter A build process asserts demands that are matched with agent capabilities. See Agent capabilities. A build process asserts demands that are matched with agent capabilities. See Agent capabilities.
Build number format On the General tab, copy your build number format into the Build number format field. On the General tab, copy your build number format into the Build number format field.
Create work item on failure On the Options tab, select this check box. On the Options tab, enable this option.
Update work items with build number None On the Options tab you can enable Automatically link new work in this build.

The new build definition offers you some new options. See:

Retention Policy tab

xaml build retention policy tab

XAML process parameter TFS 2017 RTM, Team Services equivalent
Retention Policy tab On the Retention tab specify the policies you want to implement.

The new build definition offers you some new options. See Build and release retention policies.

Build and release different kinds of apps

In XAML builds you had to create your own custom templates to build different types of apps. In the new build system you can pick from a set of pre-defined templates. The largest and most current set of templates are available on Team Services and in our newest version of TFS.

Build

Here are a few examples of the kinds of apps you can build:

Release

The new Team Build is tightly integrated with Release Management. So it's easier then ever to automatically kick off a deployment after a successful build. Learn more:

A few examples include:

Other apps and tasks

For more examples of apps you can build and deploy, see Build and deploy your app.

For a complete list of our build, test, and deployment tasks, see Build and release tasks.

Customize your tasks

In XAML builds you created custom XAML tasks. In the new builds, you've got a range of options that begin with easier and lighter-weight approaches.

Get tasks from the Marketplace

Visual Studio Marketplace offers hundreds of extensions that you can install to add tasks that extend your build and deployment capabilities.

Write a script

A major feature of the new build system is its emphasis on using scripts to customize your build process. You can check your scripts into version control and customize your build using any of these methods:

TIP

If you're using TFS 2017 or newer, you can write a short PowerShell script directly inside your build definition.

inline powershell script TFS 2017 RTM inline PowerShell script

For all these tasks we offer a set of built-in variables, and if necessary, you can define your own variables. See Build variables.

Write a custom task

If necessary, you can write your own custom extensions to custom tasks for your builds and releases.

Reuse patterns

In XAML builds you created custom XAML templates. In the new builds, it's easier to create reusable patterns.

Create a template

If you don't see a template for the kind of app you can start from an empty definition and add the tasks you need. After you've got a pattern that you like, you can clone it or save it as a template directly in your web browser. See CI/CD Hello world.

Task groups (TFS 2017 or newer)

In XAML builds, if you change the template, then you also change the behavior of all definitions based on it. In the new build system, templates don't work this way. Instead, a template behaves as a traditional template. After you create the build definition, subsequent changes to the template have no effect on build definitions.

If you want to create a reusable and automatically updated piece of logic, then create a task group. You can then later modify the task group in one place and cause all the definitions that use it to automatically be changed.

Q&A

How do I add conditional logic to my build process?

Although the new build definitions are essentially linear, we do give you control of the conditions under which a task runs.

On TFS 2015 and TFS 2017: You can select Enabled, Continue on error, or Always run.

On Team Services you can specify one of four built-in choices to control when a task is run. If you need more control, you can specify custom conditions. For example:

and(failed(), in(variables['Build.Reason'], 'IndividualCI', 'BatchedCI'), startsWith(variables['Build.SourceBranch'], 'refs/heads/features/'))

See Specify conditions for running a task.