Walkthrough: Define a Custom Workflow to Deploy a Database from Team Foundation Build

  • Article

Before you can deploy a database project by using Team Foundation Build, you must first define a custom workflow that is configured to deploy a database. You have to define a custom workflow before you can use that workflow definition in a build definition. You define the workflow by using Windows Workflow 4.0. You do not have to be an expert to follow this straightforward procedure.

To complete this walkthrough, you must complete the following tasks:

  1. Create a Build Process Template

  2. Customize the New Template

  3. Check in the Template to Version Control

Required Permissions

To perform the following procedures, you must have the Edit Build Definition permission set to Allow. For more information, see Team Foundation Server Permissions.

Create a Build Process Template

The easiest way to create a build process template is to copy the default template. You can perform that action when you create a build definition. Normally, you would complete the build definition. Because the focus in this walkthrough is on the custom build process template, this walkthrough will not address the other details of defining a new build. For more information about how to define a build for your database project, see How to: Deploy Changes using Team Foundation Build.

To create a custom template

  1. In Team Explorer, click the team project in which you want to create the custom workflow.

  2. On the Build menu, click New Build Definition.

  3. Click the Process tab to see the following diagram.

    Process tab for new build definition

  4. Click Show Details, and then click New.

    The New Build Process Template dialog box appears.

  5. Click Copy an existing XAML file.

  6. In New file name, specify the name of the custom workflow, and then click OK.

    Note

    If you want to reuse an existing XAML file, you can click Select an existing XAML file and then specify the path of the file on your version control server.

  7. In the build definition window, under the Build process file menu, click the hyperlink that contains the name of your template.

    The folder that contains your new template appears in Source Control Explorer.

  8. In the Folders pane, right-click the folder that contains your new template and then click Get Latest Version.

  9. Right-click your new template and then click Check Out for Edit.

    The Check Out dialog box appears.

  10. Click Check Out.

  11. Right-click your new template and then click View.

    The Visual Studio Windows Workflow Designer appears.

    For more information, see either of the following topics:

Customize the New Template

You must add a sequence to the default template to add a deployment step to the end of your build process. You customize the XAML file by using the Windows Workflow Designer. Even if you have not used that designer before, the steps in the following procedure are not especially complex. In brief, you add a sequence to the workflow in which you will deploy your database by using VSDBCMD.EXE if your build succeeded and your tests did not fail.

This sequence contains a single If activity that will deploy your database if your build succeeded and if your tests passed or if you had no tests. To make this definition easier to follow, this section is divided into four procedures:

  1. To add a database deployment sequence to your workflow

  2. To add the If activity

  3. To define the Then Deploy block

  4. To define the Else Skip Deployment block

To add a database deployment sequence to your workflow

  1. In the Windows Workflow Designer, click Collapse All.

    The following diagram appears.

    Initial deployment workflow

  2. Open the Toolbox, expand the Control Flow section, and then drag the Sequence activity over the arrow on the designer that is under Check in Gated Changes for Checked in Shelveset Builds. As you pause over the arrow, a second arrow appears.

  3. Drop the activity between the two arrows, as shown in the following diagram.

    Workflow after dropping a new sequence

  4. Right-click the sequence that you added and then click Properties.

    The Properties window appears.

  5. Set the DisplayName property to Deploy Database.

  6. In the Deploy Database sequence, double-click Double-click to view.

    The designer zooms in on the Deploy Database sequence, as shown in the following diagram.

    Workflow after expanding the deployment sequence

    A navigation channel is available at the top of the designer, as shown in the following diagram.

    Navigation channel in Windows Workflow designer

Next, you add an If activity to the deployment sequence.

To add the If activity

  1. Open the Toolbox, expand the Control Flow section, and drag the If activity onto Drop activity here.

    A warning icon appears on both the Deploy Database sequence and the If activity because you have not yet configured the If activity, as shown in the following diagram.

    Workflow after adding the If activity

  2. Right-click the activity that you added and then click Properties.

    The Properties window appears.

  3. Set the DisplayName property of the If activity to If Build and Tests Succeeded.

  4. Double-click Double-click to view in the If activity.

  5. In Condition, type the following condition.

    BuildDetail.CompilationStatus = BuildPhaseStatus.Succeeded And (BuildDetail.TestStatus = BuildPhaseStatus.Succeeded Or BuildDetail.TestStatus = BuildPhaseStatus.Unknown)

    This condition tests whether the build succeeded and whether the tests either succeeded or no tests ran.

The If Build and Tests Succeeded activity resembles the following diagram.

Workflow after If activity is expanded

Next, you add an Invoke Process activity to the Then part of the If activity.

To define the Then Deploy block

  1. Open the Toolbox, find the InvokeProcess activity in the Team Foundation Build Activities section, and drag it onto Drop activity here in the Then clause.

    A warning icon appears on both the If Build and Tests Succeeded activity and the InvokeProcess activity because you have not yet configured the InvokeProcess activity.

  2. Double-click Double-click to view in the Invoke VSDBCMD activity.

    The activity appears as follows.

    Workflow while defining the Then clause

  3. Set the properties for the InvokeProcess activity by performing the following subtasks:

    1. Right-click the activity that you added and then click Properties.

      The Properties window appears.

    2. Set the DisplayName property of the InvokeProcess activity to Invoke VSDBCMD.

    3. Set the Arguments property to "/a:Deploy /dd+ /dsp:Sql /manifest:DatabaseProjectName.deploymanifest". You must replace DatabaseProjectName with the name of the database project that you want to deploy.

    4. Set the FileName property to the path of VSDBCMD.EXE on your build server. For example, you might specify C:\Program Files\Microsoft Visual Studio 10.0\VSTSDB\Deploy\VSDBCMD.EXE if you installed Visual Studio on your build computer or C:\Deploy\VSDBCMD.EXE if you just copied the Deploy folder to your build computer.

      Important

      In order to deploy your database by using VSDBCMD.EXE, the contents of the Deploy folder must be on your build computer. For more information, see How to: Prepare a Database for Deployment From a Command Prompt by Using VSDBCMD.EXE.

    5. Set the WorkingDirectory property to BuildDetail.DropLocation.

  4. Open the Toolbox, find the WriteBuildMessage activity in the Team Foundation Build Activities section, and drag it onto Drop activity here in the Handle Standard Output section.

    A warning icon appears on both the Invoke VSDBCMD activity and the WriteBuildMessage activity because you have not yet configured the WriteBuildMessage activity.

  5. Set the properties for the WriteBuildMessage activity by performing the following subtasks:

    1. Right-click the activity that you added and then click Properties.

      The Properties window appears.

    2. Set the DisplayName property of the WriteBuildMessage activity to VSDBCMD Output.

    3. Set the Importance property to Microsoft.TeamFoundation.Build.Client.BuildMessageImportance.High.

    4. Set the Message property to stdOutput.

  6. Open the Toolbox, find the WriteBuildError activity in the Team Foundation Build Activities section, and drag it onto Drop activity here in the Handle Error Output section.

    A warning icon appears on both the Invoke VSDBCMD activity and the WriteBuildError activity because you have not yet configured the WriteBuildError activity.

  7. Set the properties for the WriteBuildError activity by performing the following subtasks:

    1. Right-click the activity that you added and then click Properties.

      The Properties window appears.

    2. Set the DisplayName property of the WriteBuildError activity to VSDBCMD Error.

    3. Set the Message property to errOutput.

    4. In the channel at the top of the designer, click If Build and Test Succeeded.

      By doing this, you zoom out one level in the workflow.

At this point, the workflow appears as shown in the following diagram.

Workflow after Then clause is complete

Next, you define the details of the Else activity.

To define the Else Skip Deployment block

  1. Open the Toolbox, find the WriteBuildWarning activity in the Team Foundation Build Activities section, and drag it onto Drop activity here in the Else clause.

    A warning icon appears on both the If Build and Tests Succeeded activity and the WriteBuildWarning activity because you have not yet configured the WriteBuildWarning activity.

  2. Set the DisplayName property of the WriteBuildWarning activity to Deployment Skipped.

  3. Set the Message property to "Database deployment was skipped".

    The warning icons no longer appear because you have configured the workflow activities that you added.

The If activity should now appear as shown in the following diagram.

Complete database deployment workflow

You have updated the build workflow to deploy the specified database project. Now you just have to check in the template to version control so that you can use it in your build process.

Check in the Template to Version Control

Before you can use the workflow in a build definition, you must first check it in to version control. You can also take advantage of the features of version control, such as branching. You can branch your workflow when you branch your project.

  1. Save your workflow and close the designer.

  2. In Source Control Explorer, right-click your new template and then click Check In Pending Changes.

    The Check In dialog box appears.

  3. (Optional) You can specify check-in comments or additional information about the change. For more information, see the following topics:

  4. Click Check In.

Now you can define a build that uses the custom workflow that you built in this walkthrough. For more information, see How to: Deploy Changes using Team Foundation Build.

Next Steps

You should now test your customized template. For more information, see How to: Deploy Changes using Team Foundation Build.

See Also

Tasks

How to: Prepare a Database for Deployment From a Command Prompt by Using VSDBCMD.EXE

How to: Deploy Changes to New or Existing Databases

Concepts

An Overview of Database Build and Deployment