This post provides walkthroughs that discuss the use of SQL Server Database Projects (.sqlproj files) with Team Foundation Build in Team Foundation Server 2013. The scenarios addressed are:

Configuring a Build

This walkthrough covers the process of configuring a scheduled build using Team Foundation Build in TFS 2013 and Visual Studio 2013.

Prerequisites

  1. A build service should be installed and configured for your TFS instance. If a build service has not been installed or configured for your TFS instance, then install a build service by following the instructions at http://msdn.microsoft.com/en-us/library/ee259687.aspx.
  2. The version of Visual Studio that is used by your organization to develop the SQL Server Database Project should be installed on the build machine. If Visual Studio has not been installed, or if the installed version is different than the one used to develop the SQL Server Database Project, then install Visual Studio by following the instructions at http://msdn.microsoft.com/en-us/library/e2h7fzkw.aspx.
  3. The version of SQL Server Data Tools that is used by your organization to develop the SQL Server Database Project should be installed on the build machine. If you have not already done so, we recommend updating to the latest version of SQL Server Data Tools by following the instructions at http://msdn.microsoft.com/en-us/data/hh297027. This is because significant changes have been made to SQL Server Data Tools since the RTM version of Visual Studio 2013. Updating will ensure that you have all of the latest features and fixes. Note: Visual Studio 2013 includes SQL Server Data Tools. In Visual Studio 2013, you can check for updates to SQL Server Data Tools by using the Tools > Extensions and Updates dialog. You can find the installed version of SQL Server Data Tools by looking at the Help > About Microsoft Visual Studio dialog.

Creating a New Build Definition

  1. Follow the instructions found at the http://msdn.microsoft.com/en-us/library/ms181716.aspx to create a new build definition. Note: When selecting the solution or project to be built, you can choose either the SQL Server Database Project (.sqlproj file) itself or a solution (.sln file) that contains the SQL Server Database Project.
  2. Your build definition should now appear in the Team Explorer – Builds page (Keyboard: Ctrl+0, B) under All Build Definitions.
  3. Right-click on your build and then click on Edit Build Definition... in the context-menu.
  4. Click on the Process tab and find the Build process parameters grid.
  5. Expand the Advanced node in the Build section to reveal the MSBuild arguments field.
  6. Insert /p:VisualStudioVersion=12.0 in the MSBuild arguments field.
  7. Click File and then click Save to save the build definition.
  8. To verify that the new build definition works correctly, queue a new build by following the instructions at http://msdn.microsoft.com/en-us/library/ms181722.aspx.

Configuring Unit Tests

Once Team Foundation Build is configured to build your database project, Team Foundation Build can also execute your database unit tests after every build. By default, Team Foundation Build will attempt to execute unit test projects it finds in the build output, but some additional configuration is necessary to get database unit tests working correctly. This walkthrough covers the process of configuring unit test execution using Team Foundation Build in TFS 2013 and Visual Studio 2013.

Prepare Login Credentials

  1. When executing database unit tests, Team Foundation Build will connect to an instance of SQL Server. Decide which SQL Server instance Team Foundation Build will use for unit testing. If you already have a working SQL Server database unit test project, then you can find the connection information used by that project in the SQL Server Test Configuration dialog:
    1. In the Solution Explorer tree (Keyboard: Ctrl+Alt+L), locate your database unit test project and right click on it.
    2. In the context menu, click on SQL Server Test Configuration...
    3. Click Edit Connection… to view the connection information.
  2. Decide which credentials Team Foundation Build will use to connect to SQL Server. If you already have logins for unit testing that use SQL Server authentication and have sufficient permissions, then you may be able to re-use those credentials. Documentation on the permissions required for database unit tests can be found at http://msdn.microsoft.com/en-us/library/jj889462.aspx#DatabaseUnitTestingPermissions. Note that the permissions required depend on the options selected and features used in the database project and unit test. For example, a unit test that deploys a database project that contains a SQLCLR assembly requires a login that is a member of the sysadmin role.
  3. If you need to create a new login, choose whether to create a SQL Server authentication login or a Windows authentication login for the Windows account under which Team Foundation Build executes. To create a new login, follow the instructions at http://technet.microsoft.com/en-us/library/aa337562.aspx
    Note: Certain considerations apply when choosing between SQL Server authentication and Windows authentication.
    Windows Authentication– Team Foundation Build can use Windows Authentication for SQL Server login only when Team Foundation Build and SQL Server are running on the same machine, or when both the Team Foundation Build and SQL Server machines are joined to the same domain.
    To find the Windows account under which Team Foundation Build executes, look in the Team Foundation Server Administration Console’s Build Configuration tab.
    If the Team Foundation Build service runs as NT AUTHORITY\NETWORK SERVICE, a login in SQL Server can be created using the pattern DOMAIN\TFS_BUILD_SERVER_NAME$. For example, if the Team Foundation Build server is named BldSrvr1 and both it and the target SQL Server are joined to the domain CONTOSO, then a Windows authentication login in SQL Server for CONTOSO\BldSrvr1$ would allow the Team Foundation Build service to login. For production environments, Microsoft advises against configuring a SQL Server login for NT AUTHORITY\NETWORK SERVICE, and instead suggests that you create a domain account specifically for Team Foundation Build.
    SQL Server Authentication– Provided that SQL Server is configured to allow SQL Server Authentication, Team Foundation Build can use a SQL Server Authentication login. Instructions on enabling SQL Server Authentication are available at http://msdn.microsoft.com/en-us/library/ms188670.aspx.
    When using SQL Server Authentication, a common practice is to store the password as part of the connection string, but Microsoft recommends against storing the password to a production database in your code.
    TFS Administration Console

    The Team Foundation Server Administration Console’s Build Configuration tab displays which Windows user account the Build Service executes under.

Configuring Test Execution

  1. If you do not already have a database unit test project, instructions on creating a unit test project are available at http://msdn.microsoft.com/en-us/library/jj851203.aspx. Follow the instructions at http://msdn.microsoft.com/en-us/library/ms181407.aspx to check in the new unit test project.
  2. Follow the instructions at http://msdn.microsoft.com/en-us/library/jj851221.aspx to configure SQL Server unit test execution. Additional documentation regarding connection strings is available at http://msdn.microsoft.com/en-us/library/jj851219.aspx.
  3. If your build definition contains multiple Configurations (for example, both x86|Release and Any CPU|Release), then it is recommended that you not attempt to have the database unit test deploy the database. Instead, follow the steps in Publish Option 4 documented below to create a customized build process template to deploy your database.
  4. If you configured your database unit test to deploy the database, you will need to modify the unit test to set an environment variable named VisualStudioVersion. This change is necessary because the deployment mechanism used by the database unit test relies on the VisualStudioVersion environment variable, and Team Foundation Build does not automatically set the variable. If your database unit test settings are not configured to deploy the database, modifying the unit test to set the environment variable is not necessary. Note: The value of VisualStudioVersion should be set to 12.0, which corresponds to Visual Studio 2013. Setting this environment variable in this way will limit the execution of database unit tests solely to Visual Studio 2013.
    1. In the Solution Explorer tree (Keyboard: Ctrl+Alt+L), locate the file SqlDatabaseSetup under your unit test project and open it.
    2. If your unit test project is written in VB, insert the following code in the class: 
      Shared Sub New() 
	Environment.SetEnvironmentVariable("VisualStudioVersion", "12.0") 
End Sub
    3. If, instead, your unit test project is written in C#, insert the following code in the class: 
      static SqlDatabaseSetup()
{
	Environment.SetEnvironmentVariable("VisualStudioVersion", "12.0"); 
}
  5. If you want your database unit test to deploy the database to LocalDB\ProjectsV12, you will need to add a pre-test script to your build to create the instance. Running this command multiple times is safe.
    1. Identify the path to SqlLocalDB.exe on the build server. By default, the latest version of SQL Server Data Tools installs SqlLocalDB.exe to: 
      %ProgramFiles%\Microsoft SQL Server\120\Tools\Binn\SqlLocalDB.exe
      Earlier versions of SQL Server Data Tools installed SqlLocalDB.exe to: 
      %ProgramFiles%\Microsoft SQL Server\110\Tools\Binn\SqlLocalDB.exe
      In the case of Visual Studio Online, the version installed at the time of publish of this blog post uses the latter path.
    2. In the Solution Explorer tree (Keyboard: Ctrl+Alt+L), locate your database unit test project and right click on it.
    3. In the context menu, click on Add New Item...
    4. In the Add New Item dialog, click on Visual C# Items and then click on Text File.
    5. Type a filename ending with .cmd into the Name field. For example, SetupLocalDB.cmd.
    6. In the Solution Explorer tree (Keyboard: Ctrl+Alt+L), locate the file you created in the previous step and double click on it to open the file.
    7. Enter the following text in the file, being sure to enter the path to SqlLocalDB.exe as found in step A. 
      "%ProgramFiles%\Microsoft SQL Server\120\Tools\Binn\SqlLocalDB.exe" create ProjectsV12 -s
    8. In the Solution Explorer tree (Keyboard: Ctrl+Alt+L), right click on the file you just edited.
    9. In the context menu, click on Properties.
    10. In the Properties grid, change the Copy to Output Directory field to Copy always.
    11. Click on File and then Save All to save the changes to your solution.
    12. Check-in the changes to your solution. Instructions on checking-in changes are available at http://msdn.microsoft.com/en-us/library/ms181407.aspx.
    13. In the Team Explorer – Builds page (Keyboard: Ctrl+0, B), find your build in the list of All Build Definitions.
    14. Right-click on your build and then click on Edit Build Definition... in the context-menu.
    15. Click on the Process tab and find the Build process parameters grid.
    16. Expand the Advanced node in the Test section to reveal the Pre-test script path field.
    17. Enter the following text in the Pre-test script path field, being sure to replace the file name with the name you chose in a previous step. 
      $(TF_BUILD_BINARIESDIRECTORY)\SetupLocalDB.cmd
    18. If the Output location field in the Build section is set to PerProject, then insert the name of the project or solution file listed in the Projects field into the path. For example, if the Projects field contains YourApp\ContosoApp.sln then the resulting path should look similar to: 
      $(TF_BUILD_BINARIESDIRECTORY)\ContosoApp\SetupLocalDB.cmd
    19. Click File and then click Save to save the changes to your build definition.
  6. If you are using SQL Server Authentication, modify the app.config file to store the connection password. Note: Microsoft recommends that you do not store the password to a production database in your code.
    1. In the Solution Explorer tree (Keyboard: Ctrl+Alt+L), locate a file named app.config inside of your database unit test project and double-click on the file to open it.
    2. In the app.config file, locate the Execution Context and Privileged Context lines that look similar to this:
    3. Modify these lines by inserting the password into the connection string, such that the result looks similar to this:
  7. If you have configured the database unit test to deploy the database, then you need to modify the path to the database project stored in your app.config file. This is necessary because Team Foundation Build uses a different directory structure than Visual Studio when executing unit tests.
    1. In the Solution Explorer tree (Keyboard: Ctrl+Alt+L), locate a file named app.config inside of your database unit test project and double-click on the file to open it.
    2. In the app.config file, locate the Database Deployment line that looks similar to this:
    3. If your app.config file does not contain a Database Deployment line then proceed to step 6.
    4. If your Team Foundation Server Team Project uses Git as the source control provider, then identify the relative path to the database project from the Git repository path.
      1. In the Team Explorer – Connect page (Keyboard: Ctrl+0, C), find your Team Project in the list of Team Projects.
      2. Hover your mouse cursor over your Team Project. A tooltip will appear that shows (among other things) the Repository Path.
      3. The relative path from the Team Project repository to the database project is the path to the database project (the .sqlproj file) without the Repository Path. For example, if your database project resides on disk at C:\GitRepo\YourTeamProject\YourApp\DB\DBProject\DBProject.sqlproj and the Team Project repository path is C:\GitRepo\YourTeamProject, then the relative path is YourApp\DB\DBProject\DBProject.sqlproj
      4. Open Notepad (Keyboard: Win+R, notepad, Enter) and type or paste into the window the relative path you found in the previous step.
      5. In the Team Explorer – Builds page (Keyboard: Ctrl+0, B), find your build in the list of All Build Definitions.
      6. Right-click on your build and then click on Edit Build Definition... in the context-menu.
      7. Click on the Process tab and find the Output location setting in the Build section. If the Output location setting is Single Folder, then return to the Notepad window and insert ..\src\ in front of the relative path you entered previously. Alternately, return to the Notepad window and insert ..\..\src\ in front of the the relative path you entered previously. For example, if the relative path you found was YourApp\DB\DBProject\DBProject.sqlproj and your Output location setting is Per Project, then the final path in your Notepad window should be ..\..\src\YourApp\DB\DBProject\DBProject.sqlproj
    5. If, on the other hand, your Team Foundation Server Team Project uses Team Foundation Version Control, then identify the relative path from the mapped source location to the database project.
      1. In the Team Explorer – Builds page (Keyboard: Ctrl+0, B), find your build in the list of All Build Definitions.
      2. Right-click on your build and then click on Edit Build Definition... in the context-menu.
      3. Click on the Source Settings tab and examine the Working folders mappings. These settings describe the mapping from the Team Foundation Server source control folder to the build agent's hard drive. When the build occurs, the selected folders under TFS source control are downloaded to the build agent's hard drive according to the mapping.
      4. Locate the row whose Source Control Folder contains your database project (.sqlproj file) and determine the relative path to your project from the mapped Source Control Folder. For example, if your database project is in TFS source control at $/YourTeamProject/YourApp/DB/DBProject/DBProject.sqlproj and your Source Settings tab mapping row maps the Source Control Folder $/YourTeamProject/YourApp, then the relative path is DB\DBProject\DBProject.sqlproj.
      5. Open Notepad (Keyboard: Win+R, notepad, Enter) and type or paste into the window the relative path you found in the previous step.
      6. From the same row in the Source Settings tab find the Build Agent Folder. Copy the Build Agent Folder and paste it into the Notepad Window in front of the relative path you found previously, followed by a \ character. For example, if your Notepad window contains DB\DBProject\DBProject.sqlproj and the Build Agent Folder is ($SourceDir)\AppBuild, then the modified path in your Notepad window should be ($SourceDir)\AppBuild\DB\DBProject\DBProject.sqlproj
      7. If the path in your Notepad window starts with ($SourceDir) then return to the Visual Studio build definition window and click on the Process tab. On that tab, find the Output location setting in the Build section. If the Output location setting is Single Folder, then replace ($SourceDir) in your Notepad window with ..\src\. Alternately, replace ($SourceDir) in your Notepad window with ..\..\src\. For example, if your Notepad window contains ($SourceDir)\AppBuild\DB\DBProject\DBProject.sqlproj and your Output location setting is Per Project, then the final path in your Notepad window should be ..\..\src\AppBuild\DB\DBProject\DBProject.sqlproj
    6. Return to the app.config file and modify the Database Deployment line by replacing the quoted value with the content of your Notepad file. For example, your app.config file might look like this:
      And after editing it might look like this:
    7. Save (Keyboard: Ctrl+S) your app.config file.
  8. [Optional] Database unit test projects store test execution settings in their app.config file. Consequently, every test execution uses the same settings. It may be the case, though, that Team Foundation Build requires different settings to execute your unit test than the settings required for developers to execute the unit test locally. In this scenario, you can create config files for individual users or machines. The steps below document how to do this by modifying the app.config file and adding a [machine].sqlunittest.config or a [user].sqlunittest.config file to the project.
    1. In the Solution Explorer tree (Keyboard: Ctrl+Alt+L), locate a file named app.config inside of your database unit test project and right-click on it.
    2. In the context menu, click on Copy.
    3. In the Solution Explorer tree (Keyboard: Ctrl+Alt+L), locate your database unit test project and right-click on it.
    4. In the context menu, click on Paste.
    5. A file named app - Copy.config should appear in the Solution Explorer tree.
    6. Right-click on the file app - Copy.config and click on Rename in the context menu.
    7. The name of your file determines where it will be used. If you want the settings to be applied when the database unit test is run by a specific user, then name the file [UserName].sqlunittest.config. Alternately, if you want the settings to be applied when the database unit test is run on a specific computer, then name the file [ComputerName].sqlunittest.config. For example, to have settings that are applied when the database unit test is run by a user whose user name is jdoe, name the file jdoe.sqlunittest.config.
    8. Double click on the renamed sqlunittest.config file to open it.
    9. In the sqlunittest.config file, delete everything except the section that starts with the element named SqlUnitTesting_VS2013. The resulting edited file should look similar to this:
    10. Edit the connection strings and database project path in the sqlunittest.config file as needed for the specified user or machine.
    11. In the Solution Explorer tree (Keyboard: Ctrl+Alt+L), locate the file named app.config inside of your database unit test project and double click on the file to open it.
    12. Locate the element named SqlUnitTesting_VS2013 and modify it by inserting an attribute named AllowConfigurationOverride with the value true. The resulting line should look like this:
  9. Click on File and then Save All to save the changes to your solution.
  10. Check-in the changes to your solution. Instructions on checking-in changes are available at http://msdn.microsoft.com/en-us/library/ms181407.aspx.

Configuring Test Execution in the Build Definition

  1. In the Team Explorer – Builds page (Keyboard: Ctrl+0, B), find your build in the list of All Build Definitions.
  2. Right-click on your build and then click on Edit Build Definition... in the context-menu.
  3. Click on the Process tab and find the Build process parameters grid.
  4. Expand the Advanced node in the Build section to reveal the MSBuild arguments field.
  5. Append /p:VisualStudioVersion=12.0 to the end of the MSBuild arguments field.
  6. Expand the Test Source node to reveal the Test sources spec field.
  7. Ensure that the name of your unit test project will be found by the Test sources spec pattern.
  8. Expand the Advanced node in the Test section to reveal the Disable tests field. Ensure that the Disable tests field is set to false.
  9. Click File and then click Save to save the build definition.

Automatically Publishing a Database Project after a Successful Build

Publishing a database project will update the schema of a target database to match the schema defined in the database project. In some application lifecycle management processes, it is desirable to automatically publish a database project as part of a daily or continuous integration build. Automatic publishing can be accomplished in multiple ways using Team Foundation Build. This document describes prerequisites applicable to all scenarios, and several common methods for achieving automatic publishing (in ascending order of difficulty).

Prerequisite – SQL Server Login Credentials

Team Foundation Build will need to connect to an instance of SQL Server in order to deploy your database project. Decide what credentials Team Foundation Build will use to connect to SQL Server. If you already have a login that uses SQL Server authentication and has sufficient permissions to deploy the database project, then you can re-use those credentials. Documentation on the minimum permissions required to create or deploy a database project can be found at http://msdn.microsoft.com/en-us/library/jj889462(v=vs.103).aspx#DatabaseCreationAndDeploymentPermissions. Note that the permissions required depend on the options selected and features used in the database project. For example, a database project that deploys a SQLCLR assembly to the target SQL Server requires a login that is a member of sysadmin role.

Otherwise, choose whether to create a SQL Server authentication login or a Windows authentication login for the Windows account under which Team Foundation Build executes, and create a login by following the instructions at http://technet.microsoft.com/en-us/library/aa337562.aspx

Notes:

  • You can find the account under which Team Foundation Build executes in the Team Foundation Server Administration Console’s Build Configuration tab.
    TFS Administration Console

    The Team Foundation Server Administration Console’s Build Configuration tab displays which Windows user account the Build Service executes under.

  • It may be necessary to use a SQL Server authentication login if either the SQL Server instance or the Team Foundation Build server are not part of a domain.
  • If the Team Foundation Build service runs as NT AUTHORITY\NETWORK SERVICE, a login in SQL Server can be created using the pattern DOMAIN\TFS_BUILD_SERVER_NAME$. For example, if the Team Foundation Build server is named BldSrvr1 and both it and the target SQL Server are joined to the domain CONTOSO, then a Windows authentication login in SQL Server for CONTOSO\BldSrvr1$ would allow the Team Foundation Build service to login. For production environments, Microsoft recommends against configuring a SQL Server login for NT AUTHORITY\NETWORK SERVICE, and instead suggests that you create a domain account specifically for Team Foundation Build.

Recommendation – Prepare a Publish Profile file

For any deployment option described in this section, you will need to specify the target database for deployment. You can either tell the system where to deploy the new database schema by using a Publish Profile (a publish.xml file) or, in some cases, you can use individual parameters to specify the connection information. A Publish Profile is recommended because it normally simplifies re-use. If you want to use a Publish Profile (a publish.xml file), follow these steps to create one:

  1. Right-click on the SQL Server Database Project tree node in the Solution Explorer tree and click on Publish… in the context menu.
  2. The Publish Database dialog allows you to configure a connection to a SQL Server database. Follow the instructions at http://msdn.microsoft.com/en-us/library/hh272687(v=vs.103).aspx to configure and test your connection.
  3. In the Publish Database dialog, click Save Profile As… to save the profile as a publish.xml file.
  4. Your Publish Profile file should now appear in Solution Explorer as a node under the SQL Server Database Project. Right-click on the Publish Profile file and click on Properties in the context menu.
  5. In the Properties grid, change the Copy to Output Directory value to Copy always. This will place the Publish Profile file into the output directory, making it easy to reference as an argument. Note: If you do not want the Publish Profile file included in the Output Directory, you can skip this step and leave the Copy to Output Directory value set to Do not copy. In this case, you can use the environment variable TF_BUILD_SOURCESDIRECTORY to specify the path to the Publish Profile file in the source code. Instructions regarding the use of this environment variable can be found at http://msdn.microsoft.com/en-us/library/hh850448.aspx.
  6. Follow the instructions at http://msdn.microsoft.com/en-us/library/ms181407.aspx to check in the new file and the modified SQL Server Database Project file.

Publish Option 1: Setting MSBuild arguments in the Build Definition

The default build processes in Team Foundation Build use a component named MSBuild to compile SQL Server Database Projects. MSBuild has an option that, when enabled, tells MSBuild to publish the SQL Server Database Project after a successful build.

The approach outlined below will configure Team Foundation Build to always pass arguments to MSBuild that tell it to publish the database project. This approach is straightforward, but it is not appropriate in some situations:

  • The solution you are building contains more than one SQL Server Database Project, or you intend to add another SQL Server Database Project to the solution in the future. This will not work because you will need to specify target database information for each project individually, but the default build definition process uses the same set of arguments for each project.
  • The solution you are building contains projects other than the SQL Server Database Project you want to publish, or you intend to add such a project to the solution in the future, and those other projects should not or cannot be published. This will not work because the default build definition process uses the same set of arguments for each project, and MSBuild should not attempt to publish those projects.
  • You are unable or do not want to use a Publish Profile file. This will not work because the MSBuild publish task requires a Publish Profile file.
  • You want to deploy the schema to more than one target database. This will not work because the MSBuild publish argument accepts only one Publish Profile file.
  • You are using a non-default build process that does not use MSBuild or does not have a configuration setting for MSBuild arguments.

If this option is appropriate for your build, follow these steps to pass the appropriate arguments to MSBuild.

  1. In the Team Explorer – Builds page (Keyboard: Ctrl+0, B), find your build in the list of All Build Definitions.
  2. Right-click on your build and then click on Edit Build Definition… in the context-menu.
  3. Click on the Process tab and find the Build process parameters grid.
  4. Expand the Advanced node to reveal the MSBuild arguments field.
  5. In the MSBuild arguments field, add the following: 
    /t:Build;Publish /p:SqlPublishProfilePath=your_file_name.publish.xml
  6. Click File and then click Save to save the build definition.

Notes:

  • If you would like to generate a deployment script without executing it on the target database, append the argument /p:UpdateDatabase=false to the MSBuild arguments field
  • Additional MSBuild arguments for the publish task are available. See documentation here: http://msdn.microsoft.com/en-us/library/microsoft.data.tools.schema.tasks.sql.sqlpublishtask(v=vs.103).aspx
    Build Definition Process

    The Build process parameters grid in the Build Definition tab contains the MSBuild arguments field under Build > Advanced. In this case, a file called myserverprofile.publish.xml contains the connection information for the target database.

Publish Option 2: Calling SqlPackage.exe as a Post-Build Script

SQL Server Data Tools includes a command-line utility named SqlPackage.exe that can be used to publish a database, and TFS 2013’s default build process includes a Post-build script field that can be used to execute SqlPackage.exe.

The approach outlined below will configure Team Foundation Build to call SqlPackage.exe after building. This approach is straightforward, but it is not appropriate in some situations:

  • Your solution contains multiple SQL Server Database Projects that you want to deploy. This will not work because you will need to call SqlPackage.exe for each database project individually, but the Post-build script field allows only one call to SqlPackage.exe.
  • Your build definition contains multiple Configurations (for example, both x86|Release and Any CPU|Release). This will not work because the path needed in the Post-build script argument is different for each configuration.
  • You want to deploy the schema to more than one target database. This will not work because you will need to call SqlPackage.exe for each target database individually, but the Post-build script field allows only one call to SqlPackage.exe.
  • You already use the Post-build script path for a different purpose.
  • You are using a build process other than the TFS 2013 default build process or your build process does not contain a Post-build script field.

If this option is appropriate for your build, follow these steps to call SqlPackage.exe after a build.

  1. Verify that SqlPackage.exe has been installed on the build server. SqlPackage.exe is a command-line utility that is included with SQL Server Data Tools. By default, on a 64-bit version of Windows the latest version of SQL Server Data Tools installs it in this location: 
    C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\120\SqlPackage.exe
  2. Find the file name for the .dacpac file output by your SQL Server Database Project. You will use this name in later steps. By default, the output name matches the project name.
    1. In Solution Explorer, right-click on your SQL Server Database Project and click Properties in the context menu.
    2. In the Properties tab, click on the Build tab. The field Build output file name contains the string you will need.
  3. In the Team Explorer – Builds page (Keyboard: Ctrl+0, B), find your build in the list of All Build Definitions.
  4. Right-click on your build and then click on Edit Build Definition… in the context-menu.
  5. Click on the Process tab and find the Build process parameters grid.
  6. Expand the Advanced node to reveal the Post-build script path and Post-build script arguments fields.
  7. Put the path to SqlPackage.exe that you found in Step 1 into the Post-build script path field.
  8. If you are using a Publish Profile file, then in the Post-build script arguments field, enter: 
    /a:Publish /pr:$(TF_BUILD_BINARIESDIRECTORY)\your_file_name.publish.xml /sf:$(TF_BUILD_BINARIESDIRECTORY)\your_dacpac_name.dacpac
    Note: If you have set the Output location field to PerProject, then you will need to insert the name of the Solution file or project being built into the path to the Publish Profile and the dacpac file, like so: 
    /a:Publish /pr:$(TF_BUILD_BINARIESDIRECTORY)\YourProject\your_file_name.publish.xml /sf:$(TF_BUILD_BINARIESDIRECTORY)\YourProject\your_dacpac_name.dacpac
  9. If you are not using a Publish Profile file, then in the Post-build script arguments field, enter: 
    /a:Publish /tcs:"Data Source=YourSQLServer;Integrated Security=true;Initial Catalog=YourTargetDatabase;Pooling=false" /sf:$(TF_BUILD_BINARIESDIRECTORY)\your_dacpac_name.dacpac
    Note: If you have set the Output location field to PerProject, then you will need to insert the name of the Solution file or project being built into the dacpac file path, like so: 
    /a:Publish /tcs:"Data Source=YourSQLServer;Integrated Security=true;Initial Catalog=YourTargetDatabase;Pooling=false" /sf:$(TF_BUILD_BINARIESDIRECTORY)\YourProject\your_dacpac_name.dacpac
  10. If you would like to generate a deployment script without executing it on the target database, use the argument /a:Script instead of /a:Publish and append the argument /OutputPath:$(TF_BUILD_DROPLOCATION)\DeploymentScript.sql.
  11. Click File and then click Save to save the build definition.

Note: Additional SqlPackage.exe arguments are available. See documentation here: http://msdn.microsoft.com/en-us/library/hh550080(v=vs.103).aspx

Build Process Parameters
The Build process parameters grid contains the Post-build script path and arguments fields under Build > Advanced. In this case, a file called myserverprofile.publish.xml contains the connection information for the target database.

Publish Option 3: Calling SqlPackage.exe from a Batch File

SQL Server Data Tools includes a command-line utility named SqlPackage.exe that can be used to publish a database, and TFS 2013’s default build process includes a Post-build script field that can be used to execute a batch file.

The approach outlined below will configure Team Foundation Build to call a batch file after building, and the batch file will in turn call SqlPackage.exe. This approach is not appropriate in some situations:

  • Your build definition contains multiple Configurations (for example, both x86|Release and Any CPU|Release). This will not work because the path to the Post-build script is different for each configuration.
  • You already use the Post-build script path for a different purpose.
  • You are using a build process other than the TFS 2013 default build process or your build process does not contain a Post-build script field.

If this option is appropriate for your build, follow these steps:

  1. Verify that SqlPackage.exe has been installed on the build server. SqlPackage.exe is a command-line utility that is included with SQL Server Data Tools. By default, on a 64-bit version of Windows the latest version of SQL Server Data Tools installs it in this location: 
    C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\120\SqlPackage.exe
  2. Find the file name(s) for the .dacpac file(s) output by your SQL Server Database Project(s). You will use the name(s) in later steps. By default, the output name matches the project name.
    1. In Solution Explorer, right-click on your SQL Server Database Project and click Properties in the context menu.
    2. In the Properties tab, click on the Build tab. The field Build output file name contains the string you will need.
  3. Open Notepad (Keyboard: Win+r, notepad, Enter)
  4. If you are using a Publish Profile (publish.xml) file, then enter the following text all on one line: 
    "C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\120\SqlPackage.exe" /a:Publish /pr:%TF_BUILD_BINARIESDIRECTORY%\your_file_name.publish.xml /sf:%TF_BUILD_BINARIESDIRECTORY%\your_dacpac_name.dacpac
    Note: If you have set the Output location field to PerProject, then you will need to insert the name of the Solution file or project being built into the paths, like so: 
    "C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\120\SqlPackage.exe" /a:Publish /pr:%TF_BUILD_BINARIESDIRECTORY%\YourProject\your_file_name.publish.xml /sf:%TF_BUILD_BINARIESDIRECTORY%\YourProject\your_dacpac_name.dacpac
  5. If you are not using a Publish Profile file, then enter the following text, all on one line: 
    "C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\120\SqlPackage.exe" /a:Publish /tcs:"Data Source=YourSQLServer;Integrated Security=true;Initial Catalog=YourTargetDatabase;Pooling=false" /sf:%TF_BUILD_BINARIESDIRECTORY%\your_dacpac_name.dacpac
    Note: If you have set the Output location field to PerProject, then you will need to insert the name of the Solution file or project being built into the path, like so: 
    "C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\120\SqlPackage.exe" /a:Publish /tcs:"Data Source=YourSQLServer;Integrated Security=true;Initial Catalog=YourTargetDatabase;Pooling=false" /sf:%TF_BUILD_BINARIESDIRECTORY%\YourProject\your_dacpac_name.dacpac
  6. If you would like to generate a deployment script without executing it on the target database, use the argument /a:Script instead of /a:Publish and append the argument /OutputPath:%TF_BUILD_DROPLOCATION%\DeploymentScript.sql.
  7. Repeat step 4 or step 5 for each SQL Server Database Project and target database. Place each call to SqlPackage.exe on its own new line.
  8. Click File and then click Save. Name the save file your_name_here.cmd and make note of its location.
  9. In Solution Explorer, right-click on your SQL Server Database Project and click on Add and then Existing Item...
  10. In the Add Existing Item dialog, navigate to and select the batch file you created (your_name_here.cmd).
  11. Note: If you have multiple SQL Server Database Projects in a single solution, it is not necessary to add this batch file to each project – only one copy is necessary. Also, it is not required that the batch file be added to a SQL Server Database Project. It’s sufficient to simply add the batch file somewhere under source control, provided that it is in a folder that is part of the set of Working folders defined on the Source Settings tab of the Team Foundation Build definition.
  12. Your batch file should now appear in Solution Explorer as a node under the SQL Server Database Project. Right-click on the batch file and click on Properties in the context menu.
  13. In the Properties grid, change the Copy to Output Directory value to Copy always. This will place the batch file into the output directory, making it easy to reference as an argument. Note: If you do not want the batch file included in the Output Directory, you can skip this step and leave the Copy to Output Directory value set to Do not copy. In this case, in subsequent steps you will need to use the environment variable TF_BUILD_SOURCESDIRECTORY to specify the path to the batch file in the source code. Instructions regarding the use of this environment variable can be found at http://msdn.microsoft.com/en-us/library/hh850448.aspx.
  14. Follow the instructions at http://msdn.microsoft.com/en-us/library/ms181407.aspx to check in the new file and the modified SQL Server Database Project file.
  15. In the Team Explorer – Builds page (Keyboard: Ctrl+0, B), find your build in the list of All Build Definitions.
  16. Right-click on your build and then click on Edit Build Definition… in the context-menu.
  17. Click on the Process tab and find the Build process parameters grid.
  18. Expand the Advanced node to reveal the Post-build script path field.
  19. In the Post-build script path field, enter: 
    $(TF_BUILD_BINARIESDIRECTORY)\your_name_here.cmd
    Note: If you have set the Output location field to PerProject, then you will need to insert the name of the Solution file or project being built into the path, like so: 
    $(TF_BUILD_BINARIESDIRECTORY)\YourProject\your_name_here.cmd
  20. Click File and then click Save to save the build definition.

Note: Additional SqlPackage.exe arguments are available. See documentation here: http://msdn.microsoft.com/en-us/library/hh550080(v=vs.103).aspx

Build Definition Process
The Build process parameters grid contains the Post-build script path under Build > Advanced. In this case, a file called your_name_here.cmd calls SqlPackage.exe in order to publish the SQL Server Database Project.

Publish Option 4: Modifying the Build Process Template

In Team Foundation Build, build processes are Windows Workflow (XAML) files. The Windows Workflow file used for your build can be customized to call SqlPackage.exe. This option provides the greatest flexibility at the cost of greater complexity.

  1. Follow the instructions at http://msdn.microsoft.com/en-us/library/dd647551.aspx to create a custom template and Workflow project for your build definition.
  2. Verify that SqlPackage.exe has been installed on the build server. SqlPackage.exe is a command-line utility that is included with SQL Server Data Tools. By default, on a 64-bit version of Windows the latest version of SQL Server Data Tools installs it in this location: 
    C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\120\SqlPackage.exe
  3. Find the file name(s) for the .dacpac file(s) output by your SQL Server Database Project(s). You will use the name(s) in later steps. By default, the output name matches the project name.
    1. In Solution Explorer, right-click on your SQL Server Database Project and click Properties in the context menu.
    2. In the Properties tab, click on the Build tab. The field Build output file name contains the string you will need.
  4. Open your Templates solution that you created as part of Step 1 in Visual Studio.
  5. In Solution Explorer locate CustomTemplate.xaml, and open it by double-clicking on it.
  6. You will need to locate an appropriate place in the Workflow process after the build has been performed to execute SqlPackage.exe. If your custom template is derived from the default TFS 2013 build process template, then a reasonable place in the process is inside of Overall build process>Run on agent>Try>Compile, Test and Publish, immediately after the activity Run optional script after MSBuild.
  7. Open the Toolbox window (Keyboard: Ctrl+Alt+X) and find RunScript under Team Foundation Build Activities.
  8. Drag and drop RunScript from the Toolbox into the appropriate place in the Workflow.
  9. In the Workflow, right-click on the new RunScript action and click on Properties in the context menu.
  10. In the Properties grid, set the DisplayName field to Run SqlPackage.exe.
  11. In the Properties grid, set the FilePath field to: 
    "C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\120\SqlPackage.exe"
  12. Find the path to your dacpac file within the Team Foundation Build working directory. This path will vary depending on your build process and build configuration. For example, if your build is based on the default process template, has an Output location field value of PerProject, and has multiple target configurations, then a resulting path might look similar to: 
    $(TF_BUILD_BINARIESDIRECTORY)\Release\YourProject\your_dacpac_name.dacpac
    If you're uncertain of the correct path, you can consult the MSBuild log file from a successful build to find the path.
    1. In the Team Explorer – Builds page (Keyboard: Ctrl+0, B), find a successful build in the My Builds list.
    2. Double click on the build to open it.
    3. Click on View Log.
    4. Scroll down through the log and click on MSBuild Log File.
    5. Search (Keyboard: Ctrl+F) the document for the name of your database unit test project assembly (for example, DBProjectUnitTests.dll). You should find a line similar to this: 
      Copying file from "obj\Release\DBProjectUnitTests.dll" to "C:\Builds\2\SomeTeamProject\SampleBuildDefinition\bin\Release\DBProject\DBProjectUnitTests.dll".
      The italicized portion of the above line (C:\Builds\2\SomeTeamProject\SampleBuildDefinition\bin) should be replaced by the environment variable TF_BUILD_BINARIESDIRECTORY before use, as it will vary depending on the build agent. The bolded portion of the above line (\Release\DBProject\) is not included in the environment variable, so you will need to insert that into the path used in the subsequent steps.
  13. If you are using a Publish Profile (publish.xml) file, then in the Properties grid, set the Arguments field to: 
    "/a:Publish /pr:$(TF_BUILD_BINARIESDIRECTORY)\your_file_name.publish.xml /sf: $(TF_BUILD_BINARIESDIRECTORY)\your_dacpac_name.dacpac"
    Note: Edit the path in the above example to match the path structure for your build process, as you found in the previous step.
  14. If you are not using a Publish Profile file, then in the Properties grid, set the Arguments field to: 
    "/a:Publish /tcs:""Data Source=YourSQLServer;Integrated Security=true;Initial Catalog=YourTargetDatabase;Pooling=false"" /sf:$(TF_BUILD_BINARIESDIRECTORY)\your_dacpac_name.dacpac"
    Note: Edit the path in the above example to match the path structure for your build process, as you found in the previous step.
  15. If you would like to generate a deployment script without executing it on the target database, use the argument /a:Script instead of /a:Publish and append the argument /OutputPath:$(TF_BUILD_DROPLOCATION)\DeploymentScript.sql.
  16. Repeat steps 8 through 15 for each SQL Server Database Project, configuration and target database.
  17. Follow the instructions at http://msdn.microsoft.com/en-us/library/ms181407.aspx to check in the custom build process template.
  18. If you have not already done so, follow the instructions at http://msdn.microsoft.com/en-us/library/dd647551.aspx to configure your build to use the customized build process.

Automatically Publishing a Database Project that Includes Deployment Contributors

Deployment contributors are custom .NET classes that can modify or interact with the publishing of a database schema. The SQL Server Database Project deployment engine will search for deployment contributors in the same directory as the deployment code. This section details approaches to using deployment contributors with Team Foundation Build.

Manually Place the Deployment Contributor in the Program Files directory

Some deployment contributors almost never change after having been written. In this case, manually placing the deployment contributor assemblies into the Program Files directory on the build server is a good option.

  1. Verify that SqlPackage.exe has been installed on the build server. SqlPackage.exe is a command-line utility that is included with SQL Server Data Tools. By default, on a 64-bit version of Windows the latest version of SQL Server Data Tools installs it in this location: 
    C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\120\SqlPackage.exe
  2. Place a copy of the deployment contributor assemblies into the same directory as SqlPackage.exe.
  3. Follow the instructions in the previous section of this document to configure automatic publishing after a build.

Execute SqlPackage.exe from a Temporary Directory

Suppose that you have a solution that contains both a SQL Server Database Project and a separate project that contains a deployment contributor, and you want Team Foundation Build to compile both, and then to publish the database project using the freshly-built deployment contributor. In this case it is probably not possible for Team Foundation Build to copy the deployment contributor into the directory where deployment contributors normally reside, because most organizations do not allow Team Foundation Build to execute under an account with Administrator permissions.

A workaround for this scenario is to copy both the deployment contributor and the SqlPackage.exe code into a temporary directory, and then have Team Foundation Build call that copy of SqlPackage.exe. This works because the code that performs SQL Server Database Project deployment loads extensions from its own directory – the directory in which it is executing.

The steps below will walk you through creating a batch file to execute SqlPackage.exe from a temporary directory.

  1. Verify that SqlPackage.exe has been installed on the build server. SqlPackage.exe is a command-line utility that is included with SQL Server Data Tools. By default, on a 64-bit version of Windows the latest version of SQL Server Data Tools installs it in this location: 
    C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\120\SqlPackage.exe
  2. Find the file name(s) for the .dacpac file(s) output by your SQL Server Database Project(s). You will use the name(s) in later steps. By default, the output name matches the project name.
    1. In Solution Explorer, right-click on your SQL Server Database Project and click Properties in the context menu.
    2. In the Properties tab, click on the Build tab. The field Build output file name contains the string you will need.
  3. Find the name(s) of the deployment contributor assemblies.
  4. Open Notepad (Keyboard: Win+r, notepad, Enter)
  5. Enter the following text: 
    md %TF_BUILD_BUILDDIRECTORY%\%TF_BUILD_BUILDNUMBER%\DEPLOY
xcopy /s /h /r /y /i %TF_BUILD_BINARIESDIRECTORY% %TF_BUILD_BUILDDIRECTORY%\%TF_BUILD_BUILDNUMBER%\DEPLOY
xcopy /s /h /r /y /i " C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\120" %TF_BUILD_BUILDDIRECTORY%\%TF_BUILD_BUILDNUMBER%\DEPLOY
%TF_BUILD_BUILDDIRECTORY%\%TF_BUILD_BUILDNUMBER%\DEPLOY\sqlpackage.exe /a:Script /pr:%TF_BUILD_BINARIESDIRECTORY%\your_file_name.publish.xml /sf:%TF_BUILD_BINARIESDIRECTORY%\your_dacpac_name.dacpac /OutputPath:%TF_BUILD_DROPLOCATION%\DeploymentScript.sql /p:AdditionalDeploymentContributors=your_contributor_id /p:AdditionalDeploymentContributorArguments=your_contributor_arg=value
%TF_BUILD_BUILDDIRECTORY%\%TF_BUILD_BUILDNUMBER%\DEPLOY\sqlpackage.exe /a:Publish /pr:%TF_BUILD_BINARIESDIRECTORY%\your_file_name.publish.xml /sf:%TF_BUILD_BINARIESDIRECTORY%\your_dacpac_name.dacpac /p:AdditionalDeploymentContributors=your_contributor_id /p:AdditionalDeploymentContributorArguments=your_contributor_arg=value
rmdir /S /Q %TF_BUILD_BUILDDIRECTORY%\%TF_BUILD_BUILDNUMBER%
  6. Edit the text, substituting the correct path to the directory containing SqlPackage.exe in line 3, and the name(s) of your Publish Profile and dacpac files in the subsequent lines. If you have multiple deployment database projects or target databases, copy the lines of text that execute SqlPackage.exe for each such database project or target database.
  7. If you have set the Output location field to PerProject, then you will need to insert the name of the Solution file or project being built into the paths, like so: 
    /pr:%TF_BUILD_BINARIESDIRECTORY%\YourProject\your_file_name.publish.xml /sf:%TF_BUILD_BINARIESDIRECTORY%\YourProject\your_dacpac_name.dacpac
  8. Click File and then click Save. Name the save file your_name_here.cmd and make note of its location.
  9. In Solution Explorer, right-click on your SQL Server Database Project and click on Add and then Existing Item....
  10. In the Add Existing Item dialog, navigate to and select the batch file you created (your_name_here.cmd).
  11. Note: If you have multiple SQL Server Database Projects in a single solution, it is not necessary to add this batch file to each project – only one copy is necessary. Also, it is not required that the batch file be added to a SQL Server Database Project. It’s sufficient to simply add the batch file somewhere under source control, provided that it is in a folder that is part of the set of Working folders defined on the Source Settings tab of the Team Foundation Build definition.
  12. Your batch file should now appear in Solution Explorer as a node under the SQL Server Database Project. Right-click on the batch file and click on Properties in the context menu.
  13. In the Properties grid, change the Copy to Output Directory value to Copy always. This will place the batch file into the output directory, making it easy to reference as an argument. Note: If you do not want the batch file included in the Output Directory, you can skip this step and leave the Copy to Output Directory value set to Do not copy. In this case, in subsequent steps you will need to use the environment variable TF_BUILD_SOURCESDIRECTORY to specify the path to the batch file in the source code. Instructions regarding the use of this environment variable can be found at http://msdn.microsoft.com/en-us/library/hh850448.aspx.
  14. Follow the instructions at http://msdn.microsoft.com/en-us/library/ms181407.aspx to check in the new file and the modified SQL Server Database Project file.
  15. In the Team Explorer – Builds page (Keyboard: Ctrl+0, B), find your build in the list of All Build Definitions.
  16. Right-click on your build and then click on Edit Build Definition… in the context-menu.
  17. Click on the Process tab and find the Build process parameters grid.
  18. Expand the Advanced node to reveal the Post-build script path field.
  19. In the Post-build script path field, enter: 
    $(TF_BUILD_BINARIESDIRECTORY)\your_name_here.cmd
    Note: If you have set the Output location field to PerProject, then you will need to insert the name of the Solution file or project being built into the path, like so: 
    $(TF_BUILD_BINARIESDIRECTORY)\YourProject\your_name_here.cmd
  20. Click File and then click Save to save the build definition.

Note: Additional SqlPackage.exe arguments are available. See documentation here: http://msdn.microsoft.com/en-us/library/hh550080(v=vs.103).aspx

Special Considerations for Visual Studio Online

Microsoft provides a hosted Team Foundation Build service as part of Visual Studio Online. In general, configuration in Visual Studio Online is the same as an on-premise Team Foundation Server, but the following special considerations apply when using the Visual Studio Online build service:

  • Visual Studio Online's hosted build controller has certain restrictions, for example restrictions on execution time and available software, that might make the hosted build controller unsuitable for your needs. See http://www.visualstudio.com/en-us/get-started/hosted-build-controller-vs.aspx for documentation on applicable restrictions.
  • The default process template for new builds in Visual Studio Online is from Team Foundation Server 2012. Several scenarios in this walkthrough assume you will use the default template from Team Foundation Server 2013. In Visual Studio Online, you can select the process template TfvcTemplate.12.xaml (in the case of Team Foundation Version Control) or GitTemplate.12.xaml (in the case of Git), which correspond to the default templates from TFS 2013.
  • The version of SQL Server Data Tools installed on the Visual Studio Online hosted build agent might not match the version used in your development environment. New releases of SSDT are not immediately installed on the Visual Studio Online hosted build agents, but are rather installed as part of the regular update cadence for Visual Studio Online. While new versions of SSDT do maintain backwards compatibility, you may be unable to use the new features of SSDT until the new version is installed on the hosted build agent.
  • At the time of publishing this blog post in late July 2014, Visual Studio Online's hosted build agents do not have the latest version of SSDT, but availability of the latest version of SSDT is targeted for August 2014. The version of SSDT currently installed on Visual Studio Online's hosted build agents does not support SQL Server 2014 as a target platform. Also, until the latest version of SSDT is installed on the hosted build agents, the path to SqlPackage.exe on the Visual Studio Online hosted build agents will be different than the path specified in the other sections of this post. It is: 
    C:\Program Files\Microsoft SQL Server\110\DAC\bin
  • Database deployment to LocalDB using Integrated Authentication is supported on Visual Studio Online. Database deployment to other SQL Server instances, whether performed as a post-build activity or as part of a database unit test, requires the use of SQL Authentication when running in Visual Studio Online. No built-in mechanism is available in Visual Studio Online by which you can provide the SQL Authentication credentials other than by storing them as part of the connection string. Microsoft recommends against storing the password to a production database in your code.
  • Visual Studio Online allows you to connect an on-premises build controller to the hosted TFS instance, so that you can control the build environment. See http://msdn.microsoft.com/library/ee330987#hosted for information about using an on-premises build controller.