Microsoft TFS plugin
This topic describes using a CI tool plugin to interact with Deploy.
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
The 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) Deploy plugin.
To support the use of Deploy from a TFS installation, this 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 Deploy build actions.
The build template extends the default build template with a Deploy specific part that packages your software into a Deploy DAR archive, uploads it to a specified Deploy server, and deploys the software to a specified environment using 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 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 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 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 Deploy enabled workflow in such a project, so other projects can use it or clone from it.
Custom activities
The Deploy enabled build workflow uses custom activities to drive 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 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.
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 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.
- Open the TFS Administration console (Start Menu > All Programs > Microsoft Visual Studio Team Foundation Server 2013 > Team Foundation Server Administration Console).
- On the Build Configuration screen, find the Build Controller for the project that is going to use Deploy, and click Properties.
- 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.
- "Get" that project, go to the indicated directory, add the Deploy TFS XAML plugin DLLs, and check them in.
In the BuildProcessTemplates directory of your team project, add the provided 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 Deploy enabled build template
If you want to write your own 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 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 Deploy, placing the Deploy-generated package ID into PackageID. |
CreateDeploymentTask | Instructs 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 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 a Deploy enabled build template.
The Deploy TFS XAML plugin contains a build template that is derived from the standard TFS default build template. A Deploy part is added to the template that combines the build artifacts with a manifest and uploads the package to a 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.
- In Visual Studio, go to your project's build definitions (Team Explorer > Connect to your team project > select Builds).
- Click New Build Definition or right-click one of the current build definitions and select Edit Build definition.
- Go to the Process screen, find Build process template, and click Show Details. The location of the currently used build definition is shown.
- This location is inside a TFS-controlled repository. Get the latest version, add the Deploy build template to the same directory, and check it in.
- You can select the Deploy-enabled build definition for your project.
- Enter the Deploy-specific build parameters under the new Deploy and Deploy Configuration headers (and others as required).
These 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 Deploy try to roll back a failed deployment.
- Target Environment: Where to deploy to if the build was successful. This must be a predefined Deploy environment specified by its name, without the 'Environment/' prefix.
- Deploy credentials: The username and password to use by default when trying to connect to Deploy.
- Deploy Server URL: Where Deploy can be found.
The settings you enter here will be used by all builds of the project, except the Deploy credentials, which can be overridden when queuing a build manually.
Hide Deploy user credentials
The build agent must have the credentials to connect to 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 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.