Microsoft-hosted agents

VSTS

If your build and release definitions are in VSTS, then you've got a convenient option to build and deploy using a Microsoft-hosted agent. When you use a Microsoft-hosted agent, we take care of the maintenance and upgrades. So for many teams this is the simplest way to build and deploy. You can try it first and see if it works for your build or deployment. If not, you can set up a self-hosted agent.

Tip

You can try a Microsoft-hosted agent for no charge. If your build or release doesn't succeed, the issues will be reported in the logs.

Use a Microsoft-hosted agent

To use a Microsoft-hosted agent pool, first decide which queue to use:

If your development team uses... ...then choose this queue
Visual Studio 2017 Hosted VS2017
Development tools on Ubuntu Hosted Linux
Docker containers Hosted Linux or Hosted VS2017
.NET Core Hosted Linux (optimal) or Hosted VS2017
Development tools on macOS Hosted macOS (see notes below)
Visual Studio 2013 or Visual Studio 2015 Hosted

Then, while editing your build definition, on the Options or General tab or Process step, for the Agent queue, select the queue you decided on.

Notes on choosing Hosted macOS:

  • This option affects where your data is stored. Learn more
  • For manual selection of tool versions on this Microsoft-hosted agent, see Q & A below.

Software

Software on Microsoft-hosted agents is updated once each month.

Capabilities and limitations

Microsoft-hosted agents:

Microsoft-hosted agents do not offer:

If Microsoft-hosted agents don't meet your needs, then you can deploy your own self-hosted agents.

Avoid hard-coded references

When you use a Microsoft-hosted agent, you should always use variables to construct any references to resources used by your build. We recommend that you avoid making hard-coded presumptions about resources provided by Microsoft-hosted agents (for example, the drive letter or folder that contains the repository).

Q & A

I can't select a Microsoft-hosted agent and I can't queue my build or deployment. How do I fix this?

By default, all project contributors in an account have access to the Microsoft-hosted agents. But, your account administrator may limit the access of Microsoft-hosted agents to select users or projects. Ask the owner of your VSTS account to grant you permission to use a Microsoft-hosted agent. See agent queue security.

I need more agents. What can I do?

A: All VSTS accounts are provided with a single agent and a limited number of free minutes each month. If you need more minutes, or need to run more than one build or release job concurrently, then you can buy concurrent jobs.

I'm looking for the Microsoft-hosted XAML build controller. Where did it go?

The Microsoft-hosted XAML build controller is no longer supported. If you have an account in which you still need to run XAML builds, you should set up a self-hosted build server and a self-hosted build controller.

How can I manually select versions of tools on the Hosted macOS agent?

  • Xamarin

    To manually select a Xamarin SDK version to use on the Hosted macOS agent, before your Xamarin build task, execute this command line as part of your build, replacing the Mono version number 5.4.1 as needed (also replacing '.' characters with underscores: '_'). Choose the Mono version that is associated with the Xamarin SDK version that you need.

    /bin/bash -c "sudo $AGENT_HOMEDIRECTORY/scripts/select-xamarin-sdk.sh 5_4_1"

    Mono versions associated with Xamarin SDK versions on the Hosted macOS agent can be found here.

    Note that this command does not select the Mono version beyond the Xamarin SDK. To manually select a Mono version, see instructions below.

  • Xcode

    If you use the Xcode task included with VSTS and TFS, you can select a version of Xcode in that task's properties. Otherwise, to manually set the Xcode version to use on the Hosted macOS agent, before your xcodebuild build task, execute this command line as part of your build, replacing the Xcode version number 8.3.3 as needed:

    /bin/bash -c "sudo xcode-select -s /Applications/Xcode_8.3.3.app/Contents/Developer"

    Xcode versions on the Hosted macOS agent can be found here.

  • Mono

    To manually select a Mono version to use on the Hosted macOS agent, before your Mono build task, execute this script in each phase of your build, replacing the Mono version number 5.4.1 as needed:

    SYMLINK=5_4_1
    MONOPREFIX=/Library/Frameworks/Mono.framework/Versions/$SYMLINK
    echo "##vso[task.setvariable variable=DYLD_FALLBACK_LIBRARY_PATH;]$MONOPREFIX/lib:/lib:/usr/lib:$DYLD_LIBRARY_FALLBACK_PATH"
    echo "##vso[task.setvariable variable=PKG_CONFIG_PATH;]$MONOPREFIX/lib/pkgconfig:$MONOPREFIX/share/pkgconfig:$PKG_CONFIG_PATH"
    echo "##vso[task.setvariable variable=PATH;]$MONOPREFIX/bin:$PATH"
    

Tip

We recommend that you migrate your XAML builds to new builds.