Microsoft TFS plugin

The XL Deploy plugin for Microsoft Team Foundation Server (TFS) provides automated deployment functionality for TFS 2010, TFS 2012, and TFS 2013.

If you are using VSTS, TFS 2015 Update 2, or TFS 2017, see the Visual Studio Team Services (VSTS)/ Team Foundation Server (TFS) XL Deploy plugin.

To support the use of XL Deploy from a TFS installation, this plugin provides custom build activities to interface with XL Deploy, a sample build template, and an editor to help you modify the build script with custom XL Deploy build actions.

The build template extends the default build template with an XL Deploy specific part that packages your software into an XL Deploy DAR archive, uploads it to a specified XL Deploy server, and deploys the software to a specified environment using XL Deploy. This is achieved using custom activities that you can reuse in your own variants of the build template.

For version-specific information about the TFS plugin, see the Team Foundation Server Plugin Reference.

Features

  • Creating DAR packages
  • Importing a DAR package into XL Deploy
  • Deploy the imported DAR package to a specified environment

Background information about TFS

TFS combines a source control system, a build service, a bug tracking system, and more. The XL Deploy TFS XAML plugin communicates with the build system exclusively.

In TFS, you can have multiple project collections. The examples in this topic use only a single project collection, as different project collections do not communicate to each other.

In TFS, everything that is version-controlled is reference by a TFS path that starts with $/. Example: The MvcMusicStore project root is $/MvcMusicStore.

TFS workflows

A TFS build workflow is defined by an XAML file (XAML is an XML dialect). New TFS team projects receive a default set of XAML files and the XL Deploy TFS XAML plugin provides another set. These XAML files are templates for a TFS build and contain parameters to be set when a build is started.

You can set a build definition from the Team Explorer window by indicating an XAML file to use and entering default values for a specific build. It can be any XAML file anywhere in the project collection. For example, for MvcMusicStore, you may indicate that a build should use $/NerdDinner/BuildDefinitions/NerdDinner_deployit.xaml.

An enterprise can have a kind of “common build infrastructure” project that contains XAML files. Place the XL Deploy enabled workflow in such a project, so other projects can use it or clone from it.

Custom activities

The XL Deploy enabled build workflow uses custom activities to drive XL Deploy. These activities are executable code provided by a number of DLL files, which build agents must be able to find.

The Build Controller defines a TFS path where it looks for DLLs that contain custom activities. Usually that location is also in the common build project. Because it is a TFS location, the build agents know how to get the DLLs. You only have to place the DLLs in that location.

This also makes the DLLs available to Visual Studio, which requires them for the XL Deploy credentials. If Visual Studio does not recognize new DLLs, restart Visual Studio. If you cannot enter default credentials for TFS to use, restart Visual Studio.

After the XAML and DLLs are in place, you can use the custom activities in your customized build flows. Each activity takes some input parameters, and some have output parameters as well.

Note: The Build Controller is used for all projects in the project collection. Do not allow it to point to sample projects such as NerdDinner or MvcMusicStore for custom activities, because this makes all other projects dependent on the sample projects.

Configure TFS

The XL Deploy enabling custom activities and their dependencies are contained in the DLL directory of the plugin. For TFS to find them and use them, add these DLLs to the custom activities collection.

  1. Open the TFS Administration console (Start Menu > All Programs > Microsoft Visual Studio Team Foundation Server 2013 > Team Foundation Server Administration Console).
  2. On the Build Configuration screen, find the Build Controller for the project that is going to use XL Deploy, and click Properties.
  3. The Build Controller Properties screen will show a text box called ‘Version control path to custom assemblies’. This points to a directory inside a TFS-managed project.
  4. “Get” that project, go to the indicated directory, add the XL Deploy TFS XAML plugin DLLs, and check them in.

In the BuildProcessTemplates directory of your team project, add the provided XL Deploy-enabled build template (TfvcTemplate_XLDeploy.12.xaml, DefaultTemplate-WithDeployit.11.1.xaml or ...10.xaml). Set your team project’s build process to use it.

Create your own XL Deploy enabled build template

If you want to write your own XL Deploy enabled build template, you must use the custom activities that come with the TFS XAML plugin. The following activities are available:

Activity Description
GenerateDeployitContext Accepts the DeployitURL, UserName, and Password as input parameters and verifies that the combination is correct. If it is, GenerateDeployitContext outputs a DeployitContext that holds a reference to the server. If the combination is not correct, GenerateDeployitContect fails the build. The DeployitContext is used in all other XL Deploy custom activities except CreatePackage.
CreatePackage Creates a DAR archive from the generated artifacts and optionally outputs the ApplicationName as specified in the manifest. The DAR archive has the filename PackagePath. You can specify the location of the generated artifacts by setting PackageDataRootPath. The manifest will be retrieved from ManifestPath. Values for placeholder replacement can be provided via the Dictionary parameter.
UploadPackage Uploads a package with filename PackagePath to XL Deploy, placing the XL Deploy-generated package ID into PackageID.
CreateDeploymentTask Instructs XL Deploy to initiate a deployment of a given application version onto a given EnvironmentName. Both the ApplicationName and the VersionId must be specified. The plugin checks if the ApplicationName is already deployed on EnvironmentName and can result in either an initial or an upgrade deployment of the VersionId. The resulting XL Deploy task ID is output to TaskId.
TaskController Is the general access route to task handling. It needs a DeployitContext and a TaskId, together with an Action. The Action must be specified as [TaskAction.xxx] where xxx is Start, Abort, Archive, Stop, or Cancel.
WaitForTask Waits for task TaskId until its state is different than Queued, Executing, Aborting, Failing, or Stopping. The final state is output to FinalState. You can specify how often TFS checks the task state by setting RefreshInterval to a .NET Timespan. Example: [TimeSpan.FromSeconds(10)].
GenerateRollbackTask Starts a rollback for task DeploymentTaskId. The ID of the resulting rollback is output to RollbackTaskId.
GetTaskState Gets the task state for a given TaskId.
LogSteps Takes a TaskInfo input parameter and logs the steps according to the specification in the additional parameters ErrorStates, WarningStates, NormalStates. Each of these takes a String containing a comma-separated list of TaskStates; each step in the TaskInfo will be logged at the appropriate level. If not present, ErrorStates will fallback to the single value “FAILED”, WarningStates to “PENDING”, and NormalStates to "" (i.e. no states will be logged at this level).

These activities are located in this XML namespace for TFS 2010:

xmlns:xdw="clr-namespace:XebiaLabs.Deployit.Workflow40;assembly=XebiaLabs.Deployit.Workflow40"

This namespace for TFS 2012:

xmlns:xdw="clr-namespace:XebiaLabs.Deployit.Workflow45;assembly=XebiaLabs.Deployit.Workflow45"

And for TFS 2013:

xmlns:xdw="clr-namespace:XebiaLabs.Deployit.Workflow;assembly=XebiaLabs.XLDeploy.Workflow"

Automatically deploy your application

After the TFS XAML plugin is correctly configured for your TFS build collection, you can auto-deploy built software projects by selecting an XL Deploy enabled build template.

The XL Deploy TFS XAML plugin contains a build template that is derived from the standard TFS default build template. An XL Deploy part is added to the template that combines the build artifacts with a manifest and uploads the package to an XL Deploy instance. This template can be used out of the box or can be used as a basis to set up your own build process.

  1. In Visual Studio, go to your project’s build definitions (Team Explorer > Connect to your team project > select Builds).
  2. Click New Build Definition or right-click one of the current build definitions and select Edit Build definition.
  3. Go to the Process screen, find Build process template, and click Show Details. The location of the currently used build definition is shown.
  4. This location is inside a TFS-controlled repository. Get the latest version, add the XL Deploy build template to the same directory, and check it in.
  5. You can select the XL Deploy-enabled build definition for your project.
  6. Enter the XL Deploy-specific build parameters under the new XL Deploy and XL Deploy Configuration headers (and others as required).

These XL Deploy-related settings have the following meanings:

  • Manifest Path: Set this to the TFS path of the manifest to be included. Example: $/MyApplication/src/deployit-manifest.xml. It is a TFS path, not a local path so any TFS Build Agent can download and package the manifest and do an automated deployment.
  • Rollback on deployment failure: Use this to have XL Deploy try to roll back a failed deployment.
  • Target Environment: Where to deploy to if the build was successful. This must be a predefined XL Deploy environment specified by its name, without the ‘Environment/’ prefix.
  • XL Deploy credentials: The username and password to use by default when trying to connect to XL Deploy.
  • XL Deploy Server URL: Where XL Deploy can be found.

The settings you enter here will be used by all builds of the project, except the XL Deploy credentials, which can be overridden when queuing a build manually.

Hide XL Deploy user credentials

The build agent must have the credentials to connect to XL Deploy. Security dictates that these credentials must not be exposed on casual inspection. The credentials must not be hard-coded in the build template (this would also lead to inflexibility). Setting them as string in build parameters exposes the default values to anyone viewing the build definition, which may not be desirable.

The XL Deploy enabled build template that is included with the TFS XAML plugin solves this issue by using a build process parameter of custom type DeployitCredentials that holds the credentials and by using a custom editor called DeployitCredentialsEditor. The editor uses a password text box for the password, so the value is never exposed.

This is achieved by setting an attribute on the process parameter metadata.

On TFS 2010:

Editor="XebiaLabs.Deployit.Workflow40.DeployitCredentialsEditor, XebiaLabs.Deployit.Workflow40"

On TFS 2012:

Editor="XebiaLabs.Deployit.Workflow45.DeployitCredentialsEditor, XebiaLabs.Deployit.Workflow45"

And TFS 2013:

Editor="XebiaLabs.Deployit.Workflow.DeployitCredentialsEditor, XebiaLabs.XLDeploy.Workflow"

If you do not set the editor, the password remains hidden, but you cannot change the value.