Migrate from XAML builds to new builds

TFS 2017 | TFS 2015 | TFS 2013

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 Azure Pipelines, 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 pipeline into a new build pipeline. The migration process is to manually create the new build pipelines 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 pipeline.

3. Create a new build pipeline intended to replace one of your XAML build pipelines.

   1. Create a new build pipeline.

   2. Port your XAML settings.

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

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

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 pipelines.

   Warning

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

Create new build pipelines

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 pipelines in the new build system.

1. Open your project in your web browser

   

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

   • On-premises TFS: http://{your_server}:8080/tfs/DefaultCollection/{your_project}
   • Azure Pipelines: https://dev.azure.com/{your_organization}/{your_project}

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

2. Create a build pipeline (Pipelines tab > Builds)

   

3. Select a template to add commonly used tasks to your build pipeline.
4. Make any necessary changes to your build pipeline to replicate your XAML build pipeline. 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 pipelines, 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 pipeline.

General tab

Source Settings tab

TFVC

The new build pipeline offers you some new options. The specific extra options you'll see depend on the version you're using of TFS or Azure Pipelines. If you're using Azure Pipelines, first make sure to display Advanced settings. See Build TFVC repositories.

Git

The new build pipeline offers you some new options. The specific extra options you'll see depend on the version you're using of TFS or Azure Pipelines. If you're using Azure Pipelines, first make sure to display Advanced settings. See Pipeline options for Git repositories.

Trigger tab

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

• You can potentially create fewer build pipelines to replace a larger number of XAML build pipelines. This is because you can use a single new build pipeline with multiple triggers. And if you're using Azure Pipelines, 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 Azure Pipelines, you can specify the maximum number of parallel jobs 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 Azure Pipelines. See Build pipeline triggers

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

Build Defaults tab

The new build pipeline 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

The new build pipeline offers you some new options. See Build TFVC repositories.

Git

The new build pipeline offers you some new options. See Pipeline options for Git repositories.

Build

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

The new build pipeline 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

See continuous testing and Visual Studio Test task.

Publish Symbols

Advanced

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

• Agent capabilities

• Build number format

Retention Policy tab

The new build pipeline 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 predefined templates. The largest and most current set of templates are available on Azure Pipelines and in our newest version of TFS.

Build

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

• Build your ASP.NET 4 app.

• Build your ASP.NET Core app

• Build your Universal Windows Platform app

• Build your Xamarin app

• C++ apps for Windows

Release

The new build system is tightly integrated with Azure Pipelines. So it's easier then ever to automatically kick off a deployment after a successful build. Learn more:

• Create your first pipeline

• Release pipelines

• Triggers

A few examples include:

• Continuous deployment of your app to an Azure web site

• IIS using deployment groups

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 pipeline. You can check your scripts into version control and customize your build using any of these methods:

• PowerShell scripts (Windows)
• Batch scripts (Windows)
• Command prompt
• Shell scripts (macOS and Linux)

TFS 2017 or newer 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 pipeline 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 Create your first pipeline.

Task groups (TFS 2017 or newer)

In XAML builds, if you change the template, then you also change the behavior of all pipelines 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 pipeline, subsequent changes to the template have no effect on build pipelines.

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 pipelines that use it to automatically be changed.

FAQ

How do I add conditional logic to my build pipeline?

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

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

On Azure Pipelines, 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.