Microsoft VSTS/TFS Plugin
This topic describes using a CI tool plugin to interact with Deploy. However, as a preferred alternative starting with version 9.0, you can utilize a wrapper script to bootstrap XL CLI commands on your Unix or Windows-based Continuous Integration (CI) servers without having to install the XL CLI executable itself. The script is stored with your project YAML files and you can execute XL CLI commands from within your CI tool scripts. For details, see the following topics:
About the plugin
As of version 7.0.0 the Team Foundation Server 2015 Deploy plugin has been renamed to the Visual Studio Team Services (VSTS)/ Team Foundation Server (TFS) Deploy plugin.
The Deploy extension for Visual Studio Team Services (VSTS) provides automated deployment functionality through a Deploy build task for Microsoft TFS 2015, Microsoft TFS 2017, and Visual Studio Team Services (VSTS), which is also known as Visual Studio Online.
The plugin provides custom build activities to interface with Deploy, a sample build template, and an editor to help you modify the build script with custom build actions.
The build template extends a default build template with a Deploy-specific part that packages your software in a Deploy deployment package (DAR file), uploads the DAR file to a Deploy server, and deploy the software to an environment with Deploy. You can reuse these custom activities in your own variants of the build template.
Reference links:
- Visual Studio Team Services Plugin Reference
- The Deploy plugin on the Visual Studio Marketplace
- Introduction to the Team Foundation Server XAML plugin for the Deploy plugin for TFS 2010, TFS 2012, and TFS 2013
Requirements
- Team Foundation Server 2015 Update 2, Team Foundation Server 2017, or Visual Studio Team Services (VSTS)
- Deploy version 5.1.0 and later
If you are using TFS 2015 or TFS 2015 Update 1, the Team Foundation Server 2015 version of the plugin is still available.
Supported versions
| VSTS/TFS versions | Plugin |
|---|---|
| TFS 2010, 2012, 2013 | Team Foundation Server XAML plugin |
| TFS 2015 or TFS 2015 Update 1 | Team Foundation Server 2015 version of the plugin |
| TFS 2015 Update 2, 2017, VSTS | Visual Studio Team Services (VSTS)/ Team Foundation Server (TFS) plugin |
Features
- Create a deployment package (DAR file)
- Import a deployment package into Deploy
- Upload a deployment package to TFS
- Version a deployment package
- Deploy an imported package to a specified environment
Install the Deploy build task
Before using the Deploy build task for TFS 2015, TFS 2017 or Visual Studio Team Services, ensure that you have installed the build task as described in Install a build task in TFS.
Also, ensure that you are not searching for the custom activities used for XAML builds. For information about custom activities, see the documentation on the Deploy plugin for earlier versions of TFS.
You can use the Visual Studio Marketplace to install the Deploy extension in VSTS.
Using the Deploy build task
After you install the Deploy build task, it is available in the Deploy category. In your build definition, add a new task and search for the Deploy task.
Ensure that the task is added after the build steps that create the artifacts you want to package.
The task has the following options:
Manifest path
Set the Manifest Path to the TFS path of the manifest to be included. Example: $/MyApplication/src/deployit-manifest.xml. The deployment package will be created based on the information that is present in the manifest file indicated in this option.
The manifest path is a TFS path, not a local path, so that any TFS Build Agent can download and package the manifest and perform an automated deployment. Click ... to use the file explorer to select the manifest file.
Deploy endpoint
An endpoint is a pointer to a Deploy instance. Select the instance that you want to use from the Deploy Endpoint list.
If this is the first task you are configuring, you must add a new endpoint. If you have other build definitions that use Deploy tasks, you can select an endpoint that is already defined.
For information about adding a Deploy endpoint, see Add an endpoint in Team Foundation Server 2015.
Publish artifacts to TFS
To upload the artifact after a DAR file is generated, select Publish the artifacts to TFS. This allows Microsoft Release Management to pick up the artifact for further processing.
Version
If Version is selected, the version in the manifest file will be updated. You do not need to set a placeholder in the manifest. The build task will process the manifest file, search for the version attribute, and set its value to the build number.
You can define the build number format on the General tab of the build definition. If you want to assign a different value as the package version, set the Version value override under Advanced options.
Deploy
Select Deploy to configure the build task to trigger a deployment for the imported package. Additional options will appear.
When you select this, extra options are shown. By selecting it, you are setting your build task to trigger a deployment for the just imported package.
In Target Environment box, enter the name of the environment to use for deployment, without the Environments root. Example: Production/PROD01.
If you want Deploy to roll back the deployment if it fails, select Rollback on deployment failure.
Advanced options
Use the Advanced options selection to override the default values of certain parameters.
Output Folder
By default, the folder where the DAR file is created is the build staging folder. If you want the DAR file to be placed in a different location, specify the path in Output Folder.
Package root folder
Each time a package is created, relative paths are collected from the manifest file. In the build task, each relative path has a build staging folder as a root. If your deployment files are located elsewhere, specify the root path to be used in the Package root folder box.
Version value override
If Version is selected, the version in the manifest file will be updated. By default, the build number is used. To override this, set the Version value override to a custom value.