You are on page 1of 91

Visual Studio ALM Rangers

Visual Studio 2010


Database Projects
Guidance Document
2010/10/12
Visual Studio ALM Rangers
Microsoft Corporation

Visual Studio ALM Rangers


This content was created by the Visual Studio ALM Rangers, whose members come from the Visual Studio
Product Team, Microsoft Services, Microsoft Most Valued Professionals (MVPs), and Visual Studio
Community Leads.
Visual Studio 2010 Database Projects Guidance Document -

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of
the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a
commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the
date of publication.
This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS
TO THE INFORMATION IN THIS DOCUMENT.
Microsoft grants you a license to this document under the terms of the Creative Commons
Attribution 3.0 License. All other rights are reserved.
2010 Microsoft Corporation.
Microsoft, Active Directory, Excel, Internet Explorer, SQL Server, Visual Studio, and Windows are trademarks of the Microsoft
group of companies.
All other trademarks are property of their respective owners.

Copyright 2010 Microsoft Corporation Page 2


Visual Studio 2010 Database Projects Guidance Document -

Contents
Table of Figures................................................................................................................................................................................. 6
Contributors...................................................................................................................................................................................... 7
Reviewers ......................................................................................................................................................................................... 7
Introduction ...................................................................................................................................................................................... 8
Overview...................................................................................................................................................................................... 8
Visual Studio ALM Rangers .......................................................................................................................................................... 8
General guidance .............................................................................................................................................................................. 9
Objectives .................................................................................................................................................................................... 9
Introduction ................................................................................................................................................................................. 9
Differentiation: Database Projects vs. Database Application Projects (DAC)............................................................................. 11
Common Scenario...................................................................................................................................................................... 11
General overview....................................................................................................................................................................... 14
Database Projects Functional Pillars ..................................................................................................................................... 14
Database Project Overview........................................................................................................................................................ 15
Database Project Feature Availability ........................................................................................................................................ 15
Database Features in Visual Studio 2010 Professional vs. Premium..................................................................................... 15
Transact-SQL Code Authoring .................................................................................................................................................... 16
Database Project Extensibility.................................................................................................................................................... 17
Offline Schema Development .................................................................................................................................................... 18
Solution & Project Management Section........................................................................................................................................ 29
Objectives .................................................................................................................................................................................. 29
Introduction ............................................................................................................................................................................... 29
Qualities of an Effective Solution Structure ............................................................................................................................... 29
Logical Solution and Project Types............................................................................................................................................. 29
Visual Studio Database Project solution................................................................................................................................ 30
Server Project........................................................................................................................................................................ 30
Shared Source Project ........................................................................................................................................................... 30
Functional Component Project ............................................................................................................................................. 31
Solution & Project Management SDLC Scenarios ...................................................................................................................... 32
Large Development Teams.................................................................................................................................................... 32
Shared Code - Contracts & Dependencies ............................................................................................................................ 32
Source Code Control and Configuration Management................................................................................................................... 37
Objectives .................................................................................................................................................................................. 37
Introduction ............................................................................................................................................................................... 37
Database Source Code Management before Visual Studio Database Projects ..................................................................... 37
Conclusion............................................................................................................................................................................. 38
Database Source Code management in the world of Visual Studio Database Projects ........................................................ 38
Maintain multiple active releases concurrently (Branching): .................................................................................................... 39
Hands on Labs ............................................................................................................................................................................ 41

Copyright 2010 Microsoft Corporation Page 3


Visual Studio 2010 Database Projects Guidance Document -
Integrating External Changes with the Project System................................................................................................................... 42
Objectives .................................................................................................................................................................................. 42
Introduction ............................................................................................................................................................................... 42
External Change Management................................................................................................................................................... 43
Principles.................................................................................................................................................................................... 44
Complex data movement........................................................................................................................................................... 45
Unsupported objects ................................................................................................................................................................. 45
CLR Assemblies...................................................................................................................................................................... 46
Hands on Labs ............................................................................................................................................................................ 46
Build and Deploy Automation with Visual Studio Database Projects ............................................................................................. 47
Objectives .................................................................................................................................................................................. 47
Introduction ............................................................................................................................................................................... 47
Building Database Projects interactively.................................................................................................................................... 47
Database Project Model Validation....................................................................................................................................... 47
Database Project Model Compilation ................................................................................................................................... 50
Database Project Properties ................................................................................................................................................. 51
Adding Pre/Post deployment Events .................................................................................................................................... 51
Integration of Project but not build related files................................................................................................................... 53
Automating Building Database Projects with Team Build.......................................................................................................... 54
When to Use Continuous Integration ................................................................................................................................... 54
When to Use Scheduled Build ............................................................................................................................................... 55
Why have two builds?........................................................................................................................................................... 55
Deployment Options ............................................................................................................................................................. 56
How to create a team build................................................................................................................................................... 59
Deploying to a Database ............................................................................................................................................................ 61
Build and deployment process on multi-environment settings................................................................................................. 62
Other Automation topics ........................................................................................................................................................... 66
Automating Database deployments using VSDBCMD and WiX............................................................................................. 66
Deployment Configuration and Pre/Post Deployment Script: ................................................................................................... 69
Pre/Post Scripts and Re-runnability ...................................................................................................................................... 70
Hands on Labs ............................................................................................................................................................................ 74
References ................................................................................................................................................................................. 74
Database Testing and Deployment Verification ............................................................................................................................. 75
Objectives .................................................................................................................................................................................. 75
Introduction ............................................................................................................................................................................... 75
Database and Data Access Layer Testing ................................................................................................................................... 75
Failing Fast / Find bugs early ................................................................................................................................................. 76
Automating Testing.................................................................................................................................................................... 76
Why it is Important ............................................................................................................................................................... 76
Limitations............................................................................................................................................................................. 77

Copyright 2010 Microsoft Corporation Page 4


Visual Studio 2010 Database Projects Guidance Document -
Configuring Projects for Unit Testing ......................................................................................................................................... 77
Grouping test projects by business functionality .................................................................................................................. 77
Grouping test projects by technical functionality ................................................................................................................. 78
Quickly Creating a Test Project for Stored Procedure Testing .............................................................................................. 78
Data Generation Plans and Test Projects .............................................................................................................................. 82
Data Generation and Reference Databases............................................................................................................................... 83
Creating the right plans for the tests .................................................................................................................................... 83
Using Reference Data............................................................................................................................................................ 85
Creating Meaningful Data versus Random Data ................................................................................................................... 86
Combining Actual Data with Anonymous Data ..................................................................................................................... 86
Performance and load testing............................................................................................................................................... 86
Integrating Testing into the Build.......................................................................................................................................... 86
When not to use Data Generation Plans............................................................................................................................... 87
Custom Data Generators....................................................................................................................................................... 87
Verifying Deployment ................................................................................................................................................................ 87
Finding model drifts .............................................................................................................................................................. 88
Rolling Back Deployment ........................................................................................................................................................... 89
Hands on Labs ............................................................................................................................................................................ 89
References ...................................................................................................................................................................................... 89
Appendix......................................................................................................................................................................................... 90
Enable Database Project Trace .................................................................................................................................................. 90
References ...................................................................................................................................................................................... 91
General Links.............................................................................................................................................................................. 91

Copyright 2010 Microsoft Corporation Page 5


Visual Studio 2010 Database Projects Guidance Document -

Table of Figures
Figure 1 - Common scenario for the database lifecycle.................................................................................................................. 13
Figure 2 - Solution and schema view in Visual Studio 2010 ............................................................................................................ 14
Figure 3 - Visual Studio Database Project Support Matrix .............................................................................................................. 15
Figure 4 - Integrated IntelliSense enhances authoring experiences ............................................................................................... 16
Figure 4 - Project System and Feature Extensions .......................................................................................................................... 17
Figure 5 - Database Project Extensibility......................................................................................................................................... 18
Figure 6 - Database changes throughout the database lifecycle .................................................................................................... 19
Figure 7 – Multitier Scenario: Customer.css ................................................................................................................................... 21
Figure 8 – Multitier Scenario: Database schema changes .............................................................................................................. 22
Figure 9 – Multitier Scenario: Database schema changes being idempotent................................................................................. 23
Figure 10 – Multitier Scenario: Resulting Customer table .............................................................................................................. 24
Figure 11 - Table script for a new deployed database .................................................................................................................... 25
Figure 12 – Sample table script for a changed database ................................................................................................................ 26
Figure 13 - Database Deployment Flow.......................................................................................................................................... 27
Figure 14 - Using Partial Projects in Visual Studio Database Projects............................................................................................. 34
Figure 15 - Using Composite Projects in Visual Studio Database Projects ...................................................................................... 35
Figure 17 - Source controlled database project structure before Visual Studio Database projects ............................................... 37
Figure 17 - Sample simple Team Branching model ......................................................................................................................... 39
Figure 18 - Behavior in old project using the validation database.................................................................................................. 48
Figure 19 - Certain validation error are only caught at deployment time ...................................................................................... 49
Figure 20 - Adding target elements for deployment events ........................................................................................................... 52
Figure 21 - Deployment output messages example........................................................................................................................ 52
Figure 22 - Configuring database project deployment options ...................................................................................................... 56
Figure 23 - Enabling unit tests for deployment............................................................................................................................... 57
Figure 24 - Changing build deployment options ............................................................................................................................. 58
Figure 25 - Specifying deployment options..................................................................................................................................... 59
Figure 26 - Completing the build definition .................................................................................................................................... 60
Figure 27 - Specifying build tests to run.......................................................................................................................................... 60
Figure 28 - Database deployment flow........................................................................................................................................... 61
Figure 29 - Creating a build that can be deployed to any environment ......................................................................................... 63
Figure 30 - Server Team Build ......................................................................................................................................................... 64
Figure 31 - Using VSDBCMD with a drop location to automate builds ........................................................................................... 65
Figure 32 - Dependency diagram for the deployment.................................................................................................................... 68
Figure 33 - Sequencing of deployment scripts in the build process................................................................................................ 70
Figure 34 - Output of VSDBCMD compare ...................................................................................................................................... 71
Figure 35 – Re-runnable table script example ................................................................................................................................ 71
Figure 36 - Script pre-filtering and post-filtering for similar solution types.................................................................................... 73
Figure 37 - Unit tests can be easily created from Visual Studios context menus............................................................................ 79
Figure 38 - Selecting the artifacts will generate Transact-SQL stubs as well as .NET code for execution....................................... 79
Figure 39 - Tests can be configured to prepare for execution, validation, and preparation environment..................................... 80
Figure 40 – Adding additional test types to the test solution ......................................................................................................... 81

Copyright 2010 Microsoft Corporation Page 6


Visual Studio 2010 Database Projects Guidance Document -

Contributors

Shishir Abhyanker Microsoft , Senior Development Engineer II | Visual Studio ALM Range
Chris Burrows Microsoft, SENIOR CONSULTANT
David V Corbin MVP
Larry Guger MVP, Visual Studio ALM Ranger
Barclay Hill Microsoft, Senior Program Manager, Visual Studio for BizApps
Bob Leithiser Microsoft, PRINCIPAL CONSULTANT
Pablo Rincon Microsoft, Software Development Engineer | Visual Studio ALM Range
Scott Sharpe Microsoft, SENIOR Software Development Engineer | Visual Studio ALM
Ranger
Jens K. Süßmeyer Microsoft, Senior Consultant | Visual Studio ALM Ranger
LeRoy Tuttle Microsoft, Senior Development Engineer | Visual Studio ALM Range
Ryan Frazier Microsoft, Senior Consultant

Reviewers

Visual Studio ALM Rangers Visual Studio ALM Core and Extended Rangers
Christian Bitter Microsoft, Consultant
Regis Gimenis Microsoft, Principal Consultant
Rob Jarrat Microsoft, Senior Consultant II
Bijan Javidi Microsoft, Principal Architect, Visual Studio ALM Ranger Lead
Willy-Peter Schaub Microsoft, Solution Architect, Visual Studio ALM Ranger
Mathias Olausson Visual Studio ALM Ranger

Copyright 2010 Microsoft Corporation Page 7


Visual Studio 2010 Database Projects Guidance Document -

Introduction
Overview
Welcome to the Visual Studio 2010 Database Projects Guidance.
This guidance discusses scenarios and approaches of using the
Database Projects in Visual Studio 2010 to help you use the tools more This guidance should be used in
effectively and maximize their value to your organization. conjunction with documentation that
accompanies the product and Microsoft
Developer Network (MSDN) at
The documentation on MSDN provides a basic understanding of Visual
Studio Database Projects and how to use them. What it sometimes
http://msdn.microsoft.com
lacks is guidance and recommendations, taken from real-world
experience, about the best way to use the technology. Occasionally you will also encounter features or limitations in the
product or the platform which require you to implement a custom process in order to achieve the desired goal. This guidance is
designed to complement the information on MSDN, helping you to use Visual Studio Database Projects more efficiently

The scenarios used in this document include common scenarios such as reverse engineering an existing solution or starting a
new solution from scratch. These scenarios are challenges that any analyst, architect, or developer faces in real life. The
intention is not to give you an in-depth tour of the product features, but to present you with common scenarios, practical
guidance, and checklists.

Visual Studio ALM Rangers


This content was created in a Visual Studio ALM Rangers project. Visual Studio ALM Rangers is a group with members from the
Visual Studio Product group, Microsoft Services, Microsoft Most Valued Professionals (MVP) and Visual Studio Community
Leads. Their mission is to provide out of band solutions to missing features and guidance.
This guide targets the Microsoft “200-300 level” users of database projects. The target group is considered to be intermediate
to advanced users of database projects who have in-depth understanding of the product features in a real-world environment.
Parts of this guide may be useful to the database projects novices and experts but users at these skill levels are not the focus of
this content.

Copyright 2010 Microsoft Corporation Page 8


Visual Studio 2010 Database Projects Guidance Document -

General guidance

Objectives

 Provide you with a quick introduction to the philosophy of the product


 Provide a general overview of the topics presented in the document
 Suggest where to start, depending on your area of interest.

Introduction

Visual Studio Database Projects are now a standard project template of Visual Studio and give you the ability to integrate the
management of your database development efforts into the same processes and workflows that organizations have established
for other Visual Studio project types. This creates a more holistic ALM process for their organizations.

Caution
Don’t confuse the new Visual Studio Database Projects located in the project dialog box under Database projects >
SQL Server 200x (appropriate version) with the legacy database projects located under Other project types >
Database > Database project which represent in general only a collection of non-coupled .sql script files. Database
Projects (.dbproj) succeeds the earlier Database Project (.dbp) and are the only Database Project in 2010. Database
Projects (.dbproj) in earlier versions of Visual Studio were only included in Visual Studio 2005 Team Edition for
Database Professionals and Visual Studio Team System 2008 Database Edition.

This document is organized into five topic areas. Each area is aligned to the database lifecycle you will encounter during your
project.
The topic areas for Visual Studio 2010 Database Projects Guidance are:

 Solution and Project Management: The out-of-the box experience for creating and managing your Visual Studio
Database Project Solutions and Project files. Solution and Project Management addresses most functional
requirements for a small team of developers or simple database configurations. However, a deliberate solution and
project structure will go a long way to improve productivity and successful adoption within an Enterprise
environment. This topic area will show you how to set up your project and which project types you will need.

 Source Code Control and Configuration Management: Source control is a vital part of the application lifecycle.
Maintaining different versions of code for the purpose of support can get complicated if you do not plan accordingly.
Concurrent versioning, source code branching, and merging are vital tools to manage the change of your application,
including the database schema. This section will describe how you can apply the recommendations for source control,
branching, and merging to your database project.

 External Changes with the Project System: Honoring source control and declarative database development should be
your first principle, but there are situations where you struggle with how to incorporate changes without breaking
these rules and without leaving the managed database model world. This topic will show you why those principles are
so important and how to decide if you need an alternative way.

Copyright 2010 Microsoft Corporation Page 9


Visual Studio 2010 Database Projects Guidance Document -
 Build and Deployment: Build can be not only the step before the actual deployment; build can also be a recurring
step in your deployment to maintain project integrity and quality. This topic shows you how to integrate the database
build in your development workflow and how different ways of deployment can improve your application
deployment process, including manual verification processes to an automated installer based experience with WiX
(Windows Installer XML).

 Database Testing Verification: Visual Studio Unit Testing has a great way to ensure code quality with automated tests
during your database lifecycle process. This section will show how easy this important part of database development
can be created and plugged in to your development.

Copyright 2010 Microsoft Corporation Page 10


Visual Studio 2010 Database Projects Guidance Document -

Differentiation: Database Projects vs. Database Application Projects (DAC)

Starting with Visual Studio 2010, a new project type, the SQL Server Data-tier Application project (DAC), was introduced along
with the Database Projects. Although the purpose of both project types is to deploy a database schema to a server, they are
different in semantics and handling. This guidance will cover only the Database Projects, not the functionality of DAC Projects.
To make it easier for you to choose the appropriate project, depending on the scenario you have, we have outlined the
application lifecycle for a DAC project and summarized the major differences between DAC and Database Projects.

A typical lifecycle of a DAC would be:

 The DAC is created and developed or imported from an existing DAC package or reverse-engineered from an existing
database within Visual Studio 2010 or SQL Server Management Studio.
 After finishing the development, the developer creates a DAC package, which is a portable XML file. The file defines
all of the objects and support server selection policies that specify conditions that an instance of SQL Server must
meet to host a DAC.
 The database administrator deploys the DAC package, using SSMS, to an instance of SQL Server that is running SQL
Server 2008 R2, or to SQL Azure.
 A copy of the DAC package is stored in the MSDB database for further reference and archiving purposes.
 When changes happen to the schema of the DAC project and a new DAC package is created, it is again deployed to
the server. If data already existed in the database with the old schema, it has to be migrated and imported into the
new schema of the database.

The major differences between the two project types are:

 DAC packages can be only deployed to SQL Server instances that are running SQL Server 2008 R2, or to SQL Azure
 A DAC only supports a subset of the SQL Server objects which can be found in the MSDN reference “Features
1
Supported in Data-tier Applications”
 A DAC package cannot upgrade an existing database; it will always deploy a new database with the changed schema.
When you have deployed the new database schema to the server, you will have to make sure that the old data is
migrated to the new database.
 DAC projects directly include specific instance level objects like Server principal that typically adhere to the
requirement of the consuming application.
 DAC projects support server selection policies that specify conditions that an instance of SQL Server must meet to
host a DAC.
 When DAC projects are deployed to the server, they form a DAC instance which can be easily controlled through a
special functionality in SQL Server Management Studio (SSMS).

In common DAC projects are intended for and targeted to small database projects. For example, they can be simply used by an
ISV to populate a common standard schema to a server. If databases do not change often and you do not need any features or
objects which are not supported by DAC they might be a good choice for having a standardized deployment schema. More
2
about the DAC can be found in the MSDN reference “Data-tier Application Overview.”

Common Scenario

This guidance document presents best practices in the context of a common scenario. The common scenario assumes an
organization that contains a small IT organization with a dedicated database application development team and a database
administrator. Although this scenario exists to help understand how you can apply this guidance to your own organization it

1
http://msdn.microsoft.com/en-us/library/ee362013(v=VS.100).aspx
2
http://msdn.microsoft.com/en-us/library/ee362011(v=VS.100).aspx

Copyright 2010 Microsoft Corporation Page 11


Visual Studio 2010 Database Projects Guidance Document -
does not preclude the guidance from being beneficial if your organization differs from this scenario. For this scenario we will
3
mainly use the Adventure Works sample database that can be found at the SQL Server Samples section on Codeplex :
 Organization:
o IT team develops and supports the company’s Web-based sales system.
o Employs a dedicated Database Application Development Team.
o Employs a database administrator to support the company’s database infrastructure.
o Employs a Sustaining Operations Team to maintain and support the company’s internal and external
systems.
 Organization’s Visual Studio Solution:
o Visual Studio Web Project
o Visual Studio Data Access Project
o Visual Studio Database Server Project
o Visual Studio Database Project (Main App DB)
o Visual Studio Database Project (Reference Database)
 Organization has multiple environments in different active directory domains: DEV, TEST, PROD
 Organization maintains three concurrent versions of their applications:
o DEV (Version N+1) – A development environment that represents the next version of the application,
o TEST (Version N) – A test environment that contains the next version of the application that will be moved
into production,
o PROD (Version N-1) – A production environment that contains the current released version of their
application.
 Organization uses Microsoft Team Foundation Server to source control their solution.
 Organization branches source code by iteration or version.
 Organization uses automated testing to verify builds of the application, including database unit tests.
 Organization uses Microsoft Team Foundation Server Team Build to automate application build and deployments
o Development application environment is updated through continuous integration Team Builds.
o Test application environment is updated through scheduled Team Builds.
o Production application environment is updated through a controlled deployment executed be the
operations team after build has been approved by the larger team and stakeholders.

Consider the following diagram, which depicts this fictitious organization and shows the relationship between their
environments, actors, and process flow.

3
http://www.codeplex.com/SqlServerSamples

Copyright 2010 Microsoft Corporation Page 12


Figure 1 - Common scenario for the database lifecycle
General overview

Database Projects Functional Pillars

Visual Studio Database Projects provide three main categories of functionality:

Manage Database Change


 Versioning of your database schema – Full fidelity
offline development of your database schema within a
full featured project system with source control
integration (SCC)
 Incremental Deployment - Deploy your database
schema to multiple databases updating only the
schema that differs from your source code.
 Data and Schema Compare - Compare schemas and
data between databases, database projects, and
dbschema (primary output artifact of building a
database project).
 Schema Refactoring – Make common iterative changes
to your database schema within the development cycle
with more confidence.

Manage Database Quality


 Dependency validation and visualization – Validate
your project during design and at build to ensure
consistency and integrity of your database schema.
 Static Code Analysis – Find design, performance, and
naming issues in your database schema code.
 Unit Testing and Data Generation – Create Database
Unit Tests similar to what is available to the application
developer, but with Data Generation capabilities to
test and verify your deployed database schema with
data.

Integration of Database Development Life Cycle


(DDLC) with Application Lifecycle (ALM)
 A single IDE - The process and developer experience for
Database Projects are consistent and similar to other
Visual Studio projects bringing the data tier developer
into the team based development lifecycle. Figure 2 - Solution and schema view in Visual Studio 2010
 Project Build integration with MSBuild and Team Build
 Source Control integration with Microsoft Team
Foundation Server
Visual Studio 2010 Database Projects Guidance Document -

Database Project Overview

Visual Studio 2010 Premium provides capabilities to manage application and database change. Database Projects enable you
to:
 Maintain your database code offline in Database Projects.
 Manage database artifacts using same/similar gestures as application code.
 Manage database code along with your application’s source code in a common source repository.
 Develop all your code in an integrated development environment.
 Reduce effort in integrating database change between source code and target databases.

Database Project Feature Availability

 The core Database Project system is available in Visual Studio 2010 Professional. This allows developers who use
Visual Studio 2010 Professional to load, edit, build, and deploy database projects that were created by using Visual
Studio 2010 Premium or Ultimate.
 Visual Studio 2010 Premium and Ultimate include advanced database tooling to help manage database change.

Database Features in Visual Studio 2010 Professional vs. Premium

Database Projects are part of the professional developer tools in Visual Studio 2010. Database Projects and its features are
available in two Visual Studio editions allowing development and deployment teams to select the appropriate version for the
needs and use Database Projects throughout the whole database lifecycle.

The following graphic represents which products provide specific database features.

Figure 3 - Visual Studio Database Project Support Matrix

Copyright 2010 Microsoft Corporation Page 15


Visual Studio 2010 Database Projects Guidance Document -
* Professional SKU licensees may only execute existing Unit Tests, Static Code Analysis rules and Data Generation plans. These
unit tests, SCA rules and DGen plans must have been implemented by a developer using the Premium or Ultimate SKU.
The features are available through multiple Visual Studio 2010 products to allow teams to utilize database projects to manage
their database change in a mixed Visual Studio 2010 environment. This allows team members who only have Visual Studio Pro
to build and deploy database projects. Team members needing advanced database tooling like Schema Refactoring have access
to these features through a Visual Studio 2010 Premium or Ultimate license. The database project features in Visual Studio
2010 Premium and Ultimate are the same for 2010, but other features are only accessible through the Ultimate version of
Visual Studio.

Depending on your organization’s needs and on your specific separation of duties in your project, you can choose which version
of Visual Studio that is appropriate to your responsibilities.

The following matrix describes which database project features are available in which Visual Studio 2010 editions and how they
behave. Specifically, where it reads “Execute Only” means you do not have the ability to modify the artifact (for example a Unit
Test) but you may run it and obtain the output.

Feature Visual Studio 2010 Professional Visual Studio 2010


Premium and Ultimate
Schema Compare 
Data Compare 
Database Unit Tests Execute Only 
Transact-SQL Refactoring Execute Only 
Transact-SQL Static Code Analysis Execute Only 
Data Generation Execute Only 
Team Foundation Server Build  
Integration
Command line deploy (VSDBCMD)  

Transact-SQL Code Authoring


The Database Project system provides enhanced Transact-SQL code authoring and editing experiences. The Database Project
provides a Transact-SQL Editor with IntelliSense and code snippets. The Transact-SQL Debugger is also available from within
Database Projects. Now the Transact-SQL code authoring experience is as rich as that found in SQL Server Management Studio
(SSMS), but also these great features are available for online and offline database development.

Figure 4 - Integrated IntelliSense enhances authoring experiences

Copyright 2010 Microsoft Corporation Page 16


Visual Studio 2010 Database Projects Guidance Document -

Database Project Extensibility

Database Projects are an extensible database development ecosystem. The following extension points are available:
 Database Schema Providers (DSP)
o SQL Server 2000/2005/2008 – In Visual Studio 2008 Team System Database Edition
o SQL Server 2005/2008/2008 R2 – In Visual Studio 2010
o Providers are publicly extensible in Visual Studio 2010
4
 Oracle DSP Provider by Quest Software provides for Visual Studio 2010
 Database Project Build and Deployment Extensibility
o Build and Deployment Extensibility allow you to integrate external tools more tightly into your development
process, producing new artifacts, and customizing deployment plans.
o Database Project Build and Deploy publicly extensible in Visual Studio 2010.
 Database Project Feature Extensibility
o Contextual feature extensibility support per DSP provider.
o Project Feature publicly extensible in Visual Studio 2010.
 Feature Extensibility
o Ability to extend existing tools and features.
o Publicly extensible in Visual Studio 2008 Team System Database Edition GDR and later versions.

Figure 5 - Project System and Feature Extensions

4
http://toadextensions.com/index.jspa

Copyright 2010 Microsoft Corporation Page 17


Visual Studio 2010 Database Projects Guidance Document -

Figure 6 - Database Project Extensibility

5
More information on extensibility can be found in the MSDN article “Extending the Database Features of Visual Studio”

Offline Schema Development

Historically, in many organizations, database development follows a different process than other software development
processes. For example, when most of you have developed a database you make changes directly to a live development
database and (hopefully) capture those changes either in script or in a document for later reference; the website that uses the
database is iterated on by the ASP.NET developers with the source being checked into some source code control system. When
the website is ready to move to a QA environment it is built and XCopy deployed to the QA environment. The database
changes must also be migrated so the database administrator or developer uses the script they incrementally created or
creates the change script based on the changes defined in their change document and begins stepping through all the changes
to update the QA environment's database. The development and XCopy deployment of the website application are in sharp
contrast to the manual approach taken to update the database.
The differences in development and
The differences in development and deployment techniques deployment techniques between
between application and database development is largely attributed application and database development
to the existence of data and operational state that inherently resides is largely attributed to the existence of
in all live databases. The operational state includes configuration of data and operational state that
the database, database schema, security settings, permissions and inherently resides in all live databases.
data. To change the operational state of the database requires some
knowledge of the existing state and the change is often additive in
nature. The existence of data complicates the database change process because the data is often migrated, transformed, or
reloaded when changes are introduced by application development efforts that affect the shape of the database's tables or
other data schemas. Throughout this change process, production quality data and operational state must be protected against
changes that may jeopardize its integrity, value, and usefulness to the organization.

Given the constraints that data introduces, the need to manage database state in general, and specific tools required to effect
database change, organizations often struggle with integrating database development processes into their larger Application
Lifecycle Management (ALM) strategies. This has given rise to segmented and often fragmented application development
workflow processes which ultimately reduce the organization's collaboration, efficiency and agility.
These fragmented processes typically originate in the area of Software Configuration Management (SCM). If you compare
database development and application development SCM practices, the key difference is the existence of state that must be
managed for databases. To manage this state, change scripts must be developed that not only identify the desired schema and
state of the database, but also any modifications and transformations necessary to move the database (and its data) from the
existing state to the new desired future state at the time of deployment or release. Conversely, for application development in
general, there is usually not a significant amount of existing state and the application is often simply replaced with the new
version at the time of release.

5
http://msdn.microsoft.com/en-us/library/aa833285.aspx

Copyright 2010 Microsoft Corporation Page 18


Visual Studio 2010 Database Projects Guidance Document -
Visual Studio 2010 provides a Database Project and tools necessary
to effectively manage database change in a manner which easily Offline Schema Development enables
integrates into their organization's existing SCM processes. Visual a repeatable, flexible, process driven
Studio 2010 provides a disconnected, declarative database Database Development Life Cycle
development environment based on a model representation of the (DDLC) process
database where the source code defines the database, options, and
schema. Transact-SQL script (source code) in Database Projects is
the primary artifact and is managed and versioned throughout the development cycle in the same respect as artifacts for other
Visual Studio Projects. This is Offline Schema Development and enables a repeatable, flexible, process driven Database
Development Life Cycle (DDLC)

Although many organizations maintain an exhaustive archive of change scripts for their database so that they can upgrade from
version N to version N+1, these scripts are hard to maintain and require unnecessary steps if you compare the single steps with
the aggregated actions needed to occur. In the next illustration you see a table being versioned through a couple of releases. A
new column “description” is added to the schema with a data type of VARCHAR and a length of 25 and later changed to the
length of 100.

Figure 7 - Database changes throughout the database lifecycle

In the past, and without declarative database schemas, moving from version 1 to version 3 could be accomplished by the
following task:

 Provide change scripts from version 1 to version 2 and from version 2 to version 3 to apply the changes. With this
option you are free to either upgrade a database with version 1 or with version 2 but have the additional overhead of
changing the schema twice with the following statements:

o ALTER TABLE dbo.Auction ADD description VARCHAR(25)


o ALTER TABLE dbo.Auction ALTER COLUMN description VARCHAR(100)

 Provide change scripts from version 1 to version 2, from version 2 to version 3 and from version 1 to version 3 directly.
This boils down the change of the actual column to one statement only:

o ALTER TABLE dbo.Auction ADD description VARCHAR(100)

But this actually forces you to maintain even more change scripts for all possible combinations of source and target
versions.

Compared to the mentioned steps and with declarative database development, the only state you will have to persist and
handle is the most current. Changes will be calculated from the actual and the new model and be applied to the database.

Copyright 2010 Microsoft Corporation Page 19


Visual Studio 2010 Database Projects Guidance Document -
Adoption of Database Projects may require a mental shift (old
habits are hard to break) for some developers or at least a change in
process or workflows. Developers who have developed database
Adoption of Visual Studio Database
applications where the production database represents the current Projects may require a mental shift for
version of the database will need to adopt a source code based some developers or at least a change
approach where source code becomes the vehicle to which change in process or workflows.
is made to databases. In Visual Studio Database Projects, the project
and the source code is the "One Version of the Truth" for the database schema and is managed using SCM workflows likely
already being used by the developer or organization for other portions of their application stack. For the data, the production
database remains its "One Version of the Truth" as it should be.

Offline Schema Development is an approach to database development that focuses on creating and maintaining the database
using source code in an environment that is disconnected from an actual database. The source code is developed without
defining the implementation details of modifying an existing database. Instead, the schema is declared in source code and the
source code is versioned throughout the development lifecycle. The database schema is modeled in the project system and
includes the data object structures like tables and views as well as programmability objects, such as stored procedures and
functions.

SIDE NOTE
Database Projects comprehends almost all objects and syntax. Very few objects and syntax meaningful only to the database
engine at runtime have been excluded.

Visual Studio Database Projects enables an Offline Schema Development environment by providing:

 A Database Project (.dbproj) designed to manage database development.


 Declarative SQL syntax support where the schema is defined in the domain language of the database.
 Schema model representation of the database schema where source can be round-tripped from source to model and
back again.
 Schema model interfaces providing programmatic model interaction to database tooling and designers.
 Interpretation and validation of SQL syntax and schema dependencies ensuring integrity of the source without
executing it against a database.
 Schema comparison engine that compares your source with a target database to generate an update script.
 Compiled versions of database schema enabling deferred deployment and script generation (.dbschema file).
 .dbschema files can be deployed to different environments that have different configurations.

The following scenario will demonstrate the points that are described in the previous list. In this scenario we will track a
multitier application over three development iterations/release cycles without using Visual Studio Database Projects. In this
scenario, a simple class represents the application tier and a table represents the data tier.
In version 1 the application developer defines a simple class called Customer. The database developer defines a simple table
called Customer.
In version 2, the team has realized that they will very likely have more than one customer named Tom Smith and decide that a
means to uniquely identify a customer is required in addition to the customer’s name. The application developer adds an Id
member to their class. The database developer adds an Id column and primary key to the table. While the application
developer can simply update their class and check it in, the database developer must write alter statements to add the new
column and primary key. The database developer’s code no longer represents the true shape of the Customer table. The true
shape of the Customer table exists in the current development DB and is possibly spread over two scripts: Some in the original
table create script and some in the database update script. The database developer makes the changes and checks the new file

Copyright 2010 Microsoft Corporation Page 20


Visual Studio 2010 Database Projects Guidance Document -
in. Side Note: For simplicity, in this scenario we will disregard data motion that is required to push the change out to the
database.
In version 3 the team needs to further differentiate their customers and decides to add a property to their customers to identify
the customers they want to keep and expand business with. To implement this, the application developer adds a new member
to their class called IsKeyCustomer and checks in. The database developer adds another file and writes another alter statement
to add the new column to the Customer table. The database developer updates the development database and the change
script and checks in.
At the end of version 3 we end up with project artifacts that look similar to the following:

Figure 8 – Multitier Scenario: Customer.css

Copyright 2010 Microsoft Corporation Page 21


Visual Studio 2010 Database Projects Guidance Document -

Figure 9 – Multitier Scenario: Database schema changes

Copyright 2010 Microsoft Corporation Page 22


Visual Studio 2010 Database Projects Guidance Document -
Take a look at the change script. The change script consists of all the changes together in one SQL file. Change scripts typically
validate an expected schema condition before each change. You will often need data motion scripts before some changes can
be completed on tables with existing data. To make sure that your script is idempotent on every database version, you will have
to put some extra work in here, as shown following illustration:

Figure 10 – Multitier Scenario: Database schema changes being idempotent

There are a number of problems with maintaining a database schema change script: It's a manual and time consuming; error
prone; complexity increases as time goes on and number of version changes grow; development team agility increases the
maintenance cost of change script; and it's really not a scalable process. Moreover, you must instantiate your database schema
by running the full set of scripts against a live database to view or reference your objects. This introduces a dependency on the
development database as the "truth" of the databases schema instead of the source code. This also requires making changes
twice, once in the development database and again in the change script.

Copyright 2010 Microsoft Corporation Page 23


Visual Studio 2010 Database Projects Guidance Document -
Now let's go through the same scenario using a Visual Studio Database Project. There are no changes in behavior for the
application developer so I will only call out the actions of the database developer.
1. In version 1 the database developer defines a simple table called Customers.
2. In version 2 the database developer adds the Id column and primary key to the Customer Table definition.
3. In version 3 the database developer adds the IsKeyCustomer column to the Customer table definition.
At the end of version 3 we end up with database source that looks similar to the following:

Figure 11 – Multitier Scenario: Resulting Customer table

The database developer defines the shape of the object for the version of the application, not how to mutate the existing object
in the database engine to the desired shape. You may be asking yourself: How does this get deployed against a database that
already contains the customer table? This is where the deployment engine comes in to play. As mentioned previously, the
deployment engine will take the compiled version of your schema and compare it against a database deployment target. The
differencing engine will produce the necessary scripts to update the target schema to match the version you are deploying from
the project. The following example shows update scripts from the previous scenario that were generated by the deployment
engine.
When deploying to an empty database, the deployment engine will generate the full script (excerpt provided):

Copyright 2010 Microsoft Corporation Page 24


Visual Studio 2010 Database Projects Guidance Document -

Figure 12 - Table script for a new deployed database

Copyright 2010 Microsoft Corporation Page 25


Visual Studio 2010 Database Projects Guidance Document -
When deploying to an existing version of the database, for example, a production environment running version 1.0, it will
produce the following update script:

Figure 13 – Sample table script for a changed database

You can deploy your project's schema to multiple databases that have different schema versions to integrate the schema
defined in your project. The following graphic depicts what happens at the time of deployment.

Copyright 2010 Microsoft Corporation Page 26


Visual Studio 2010 Database Projects Guidance Document -

Figure 14 - Database Deployment Flow

At the time of deployment, the schema model that is defined by your project and the schema model that is defined by the
target database are compared. The deployment engine then creates a deployment plan based on the difference of the model
comparison.

SIDE NOTE
Beginning with Visual Studio 2008 GDR, the deployment engine is also accessible through an additional command line tool
called VSDBCMD.exe. This tool makes it easier to do schema comparison and deployments in production environments or
environments where Visual Studio cannot by installed or where installed Visual Studio instances do not have access to the
production environment.

Copyright 2010 Microsoft Corporation Page 27


Visual Studio 2010 Database Projects Guidance Document -

The deployment plan is executed against the target database or the


deployment plan is deployed to script. This demonstrates how the The source controlled version of your
target database change script creation is deferred to the time of project represents the truth of the
deployment. This enables you to build your schema once and database schema and the "compiled"
deploy it many times. The source controlled version of your project .dbschema file is a blueprint of your
represents the truth of the database schema and the "compiled" schema at a specific point in time.
.dbschema file is a blueprint of your schema at a specific point in
time. The .dbschema file is also mobile and can be included in the
application release payload and deployed along with the rest of the application stack.

Going back to the Version 1 to Version 3 scenario, this would mean that it does not matter which version you apply your
upgrade to, being either version 1 or 2. The engine will produce the script to bring the database to version 3 being the current
source of truth. Not only that, once going to version 3, the engine could even produce a deployment script to downgrade the
database from version 3 to version 2 again.

RECOMMENDATION
It is recommended that you test your deployments during development and integration. Testing the deployment ahead of time
will provide you with an understanding of what the deployment engine will do against a target database instance. For more
information, see the Testing and Deployment section of this document.

An easy way to verify your development this is to deploy to script, review it, and then run it against a test environment. You
can also test deploying your project against a test database instance and schema compare the test instance with production or
development. Testing ahead of time will also provide you the confidence needed to eventually automate the execution of your
deployments. If you have multiple environments such as: DEV, TEST, INT, ACCEPT, PPE, or PROD, you will want to deploy to
these environments to mimic the promotion of schema deployments before an actual deployment to production takes place.
The section Testing and deployment verification will cover that part in detail.

Copyright 2010 Microsoft Corporation Page 28


Visual Studio 2010 Database Projects Guidance Document -

Solution & Project Management Section

Objectives
 Enable core Enterprise SDLC scenarios
 Utilizing prescriptive solution/project structures & settings

Introduction

The out-of-the box experience for creating and managing your Visual Studio Database Solutions and Project files addresses
most functional requirements that a small team of developers need, provided that your primary goal is focused on individual
developer productivity. However, within an Enterprise environment, the complexity of the application, the number of
developers who contribute to the project, and the sophistication of SDLC processes may all contribute to an erosion of the
benefits gained.

Qualities of an Effective Solution Structure


A well thought out, deliberate strategy for organizing and managing Solutions can help address these potential pitfalls, and
even accelerate team development. An effective approach should address these key issues:

 Functional component separation – The developer should not have to have first-hand and low-level knowledge of the
code in order to identify objects to code against. The internal solution structure itself should guide functional
discoverability, and lend itself to multiple developers working on, sharing, and consuming discrete components.

 Independent quality gates and developer accountability – The solution should enable each functional component to
be built and verified independently from one another, by the individual developer, without the strict requirement of a
full regression or integration test pass. At the same time, continuous integration builds and deployment of the full
solution should be enabled against incremental changes.

 Discrete change control and dependency management – The structure of the solution should lend itself to flexible
source control branching/integration strategies, as well as enabling dependencies from external code, or publishing
code to be shared across other projects.

 Solution stability that spans releases – The solution structure should be relatively stable from release to release. The
introduction of new business features or functional components should not force you to do wide-scale code
refactoring or prompt you to revisit your build definitions or release strategy.

Logical Solution and Project Types


For consistency across applications and development teams, guidelines should be established around when to create a solution
or project, for what purpose, and how it should be consumed. While not all are explicitly defined in Visual Studio databases,
the following logical solution and project types should be considered when establishing these guidelines:

Copyright 2010 Microsoft Corporation Page 29


Visual Studio 2010 Database Projects Guidance Document -
Visual Studio Database Project solution

This should represent the database tier of an application, including all related components that would be deployed on or used
to validate the SQL Server infrastructure, such as SSIS, SQLCLR, data movement scripts, unit tests, etc.

 Single source branch - The Visual Studio database Solution should reside entirely within a given source code branch,
so that it is represented as a single unit.

 External and build dependencies – Sequence and dependencies of constituent projects are set here. Cross-solution
Visual Studio database dependencies should be managed at the solution level as well; such as collecting static copies
of external DBSCHEMA files.

 Environment selection – Configuration files and parameters should be set at the solution level.

Server Project

Whether the application is built for a single server, or multiple servers, this type project should be used to standardize server
settings and defaults, and server-level objects.
 Consolidate in solution folder – For ease of identification, and to put them out of view during code development, all
server projects can be moved into a dedicated solution folder.

 Multi-server configuration – Larger or distributed applications may require deployment onto multiple SQL Server
instances. Consistency of configuration can be achieved by using Server Projects as templates.

Shared Source Project


A key feature of Visual Studio databases is the ability to leverage code that has been developed for other projects, or that has
been fully and independently regressed earlier in the release cycle. The objects in this type of project will later be consumed as
either as a Composite Project or via Partial Project Files.

 Relatively static code base – Objects in this type of project are to be used as libraries for other projects; hence they
should be made up of relatively mature and stable code.

 Resolve static code analysis warnings – You should resolve all code analysis warnings in this project before
consuming the project or code elsewhere. Otherwise, you will see redundant errors and warnings in the other
projects that must be addressed in the shared source project.

 Build but don’t deploy to production - The solution settings for this project should be set to do a build and deploy in
a DEBUG configuration for testing purposes, but this type of project should never deploy in production in a RELEASE
configuration. This code will deploy to production when referenced from another project.

 Independent unit tests – Where practical, units tests should be run and other quality gates held against this project
to validate it before propagating issues to other projects.

 Domain data population – Reference tables and post-deploy scripts to populate domain data should be consolidated
into separate projects for subsequent reuse and consistency across subordinate projects

Copyright 2010 Microsoft Corporation Page 30


Visual Studio 2010 Database Projects Guidance Document -
Functional Component Project
When the foundational components are defined within the individual Server Projects and Shared Source Projects, you need a
deployable container to pull these all together. This type of project correlates to your out-of-the-box Visual Studio database
project, separated by functional application boundaries.

 Deployable unit – The output of this project is what you will deploy into production.

 Consumes cross-project references – This type of project should add functionality or value on top of an established
code base. Cross-database references and shared code libraries are consumed here.

 Observes application functional boundaries – Hopefully, it is possible to align business feature requirements to one
or just a few functional component projects. This will really help contain the regression surface for a given release.

For example, suppose two or more different applications or workflows where accessing the same database. If you
were to implement the respectively needed stored procedures, views, and tables within separate projects, then you
could modify, build, regress, and deploy a single project with low risk to other projects.
 Functional Test boundary – When multiple developers are working on the same code base, it is important to validate
and express code quality at a grain less than the total solution. Functional Test cases should be focused and scoped
to this type of project, such that incremental code changes and a local IDE build can be readily regressed pre-check-in.

For a specific developer, you would ideally want to have the minimum scope of change necessary during a given
check-in. That is, the change would be contained in a functional area. Using this type of project structure mitigates
the need to merge source-code, and reduces possible regressions that would impact other developers that are
concurrently working on other areas.

Copyright 2010 Microsoft Corporation Page 31


Visual Studio 2010 Database Projects Guidance Document -

Solution & Project Management SDLC Scenarios


When you have organized your solution into these logical project types, you are better positioned to address logistical concerns
that come with Enterprise solutions and development teams.

Large Development Teams


The size of the development team is usually a good indicator of the size of the Visual Studio database solution and the number
of objects therein. Sound solution management practices tend to re-enforce the proliferation of objects in the solution. The
logical project types presented above afford these practices for increasing developer productivity:

 Unload projects that you are not working on. This assumes that you have already decomposed your large solution
into granular Share Source Projects and Functional Component Projects. Source control synchronization, solution
load times, Visual Studio database memory footprint, static code analysis runtime, and build/deploy duration can
negatively impact developer productivity.

 Limit scope of changes to a single project and database schema at a time. Assuming good functional separation
within the solution, multiple developers can more easily work in parallel if they each focus on a single project and
where practical, a single database schema at a time. This implies that the solution was originally set up for schema-
wise (not object type) organization of objects.

 Apply local quality gates & accountability. Build-time validations and unit tests should all pass within a local IDE
build before check-in. This is not practical if every developer needs to sync and build all components every time, so it
is imperative that you unload unaffected projects to avoid unintended consequences. This will also mitigate source
code merge conflicts for project-level and build and environment settings.

Shared Code - Contracts & Dependencies


For any given release, you do not want the liability of a possible code change anywhere in the solution causing a regression
across the whole solution. In the same light, you want to isolate stable, reusable code, so that it can be shared out to other
projects, solutions, and teams.

Copyright 2010 Microsoft Corporation Page 32


Visual Studio 2010 Database Projects Guidance Document -
Publishing contracts for shared components

If you are going to be responsible for components that other teams/projects will take dependencies on, then you need the
ability to manage the scope of those dependencies, and the latitude that you have for revising these components in the future.
A key consideration to keep in mind is the issue of balancing breaking changes against the need to maintain backwards
compatibility with ‘subscribers’ of the shared contract.
The artifacts that you shared out are in effect, a published contract that varies in scope and version control flexibility.

 DBSCHEMA files for cross-solution contracts – Consider internal vs. external partner’s use of this file. Some partners
may want to consume the entire project (both private and public objects), where for others, you may want to edit the
DBSCHEMA file to remove all but references to public-facing stored procedures. This is the most discrete means of
publishing and consuming a shared contract, and the only one available outside of a solution structure. Backwards
compatibility can be tied to a versioned release or a source code branch. Further information can be found in the
6
MSDN topic “Starting Team Development of Databases that Reference Other Databases”

NOTE
This is the same pattern that you would leverage for consuming references to external objects in the master or msdb databases
via the DBSCHEMA files that ship with the product.

6
http://msdn.microsoft.com/en-us/library/dd193279.aspx

Copyright 2010 Microsoft Corporation Page 33


Visual Studio 2010 Database Projects Guidance Document -

 Partial Project Files for cross-project contracts – Library utility functions, common instrumentation, auditing, and
logging, as well as shared domain tables and data population scripts, and replication publisher articles should be
shared out as a manifest defined by partial project files. More information about partial project can be found in the
following MSDN documentation:

7
o “Walkthrough: Partition a Database Project by Using Partial Projects”
8
o “How to: Import and Export Partial Database Projects”
9
o “Starting Team Development of Large Databases”

NOTE
You can share out the same files as needed by subscribers in multiple partial project file definitions or DBSCHEMA files. Use this
option when you want to deny the subscriber any latitude in changing the defined objects.

Figure 15 - Using Partial Projects in Visual Studio Database Projects

7
http://msdn.microsoft.com/en-us/library/dd193248.aspx
8
http://msdn.microsoft.com/en-us/library/dd172128.aspx
9
http://msdn.microsoft.com/en-us/library/dd193405.aspx#LimitationsOfPartialProjects

Copyright 2010 Microsoft Corporation Page 34


Visual Studio 2010 Database Projects Guidance Document -
 Composite Projects for feature teams – As division of labor and accountability, separate feature teams or developers
are responsible for delivery of a Functional Component Project to be consumed by other projects. This is the most
transparent means of publishing and consuming a shared contract. Backwards compatibility is tied to source code
branching strategy and cadence. More on that can be found in the MSDN documentation “Walkthrough: Partition a
10 11
Database Project by Using Composite Projects” and “Uses and Limitations of Composite Projects”

Figure 16 - Using Composite Projects in Visual Studio Database Projects

Consuming contracts for shared components

The key issue to resolve is whether you want to be tied to version control or not. Do you want to take a dependency upon a
fixed release version that has passed related quality gates, or do you want to be subject to end-to-end stabilization. You
consume shared code by taking a reference upon a DBSCHEMA file or project file, or by including a partial project file manifest.

 Integration cadence – For large or multiple feature teams working concurrently on several components, you must
assume that each component may stabilize independently. If you want to control which dependencies you take, and
when you take them (to enable your own component’s stabilization), then you should consume a fixed DBSCHEMA
file. If you need a tighter level of integration, then you should take a dependency at the Shared Component or
Functional Component project level.

 Accountability for published component quality – This is really publisher responsibility, but you should insist that the
published component (by whatever means) is clean with respect to build errors and static analysis warnings/errors.
Additionally, where practical, the publisher should own unit tests and other measures of code quality.

Note: When you take a reference to a project or partial project file, any issues that occur within those components
will appear to be problems with your project. You can suppress these errors and warnings from within your project,
but the only time you would want to do that is if you don’t have any influence or control over the reference source.

10
http://msdn.microsoft.com/en-us/library/dd193415.aspx
11
http://msdn.microsoft.com/en-us/library/dd193405.aspx#LimitationsOfCompositeProjects

Copyright 2010 Microsoft Corporation Page 35


Visual Studio 2010 Database Projects Guidance Document -

Hands on Labs

To get more insight to the topics, the HOL document will let you deep dive into the following topic:

 Refactoring a VSDB Solution to Leverage Shared Code

Copyright 2010 Microsoft Corporation Page 36


Visual Studio 2010 Database Projects Guidance Document -

Source Code Control and Configuration Management

Objectives

 Describe how Database Projects do the following:


o Integrate with source code control
o Provide configuration to target multiple environments
o Support the database development and change management process

Introduction

Source code control and maintaining different versions of code have been both complex and necessary before having the
offline development approach of Visual Studio Database Projects. To illustrate that and give you a good understanding of the
different paradigm in Database Projects, let’s take a look first at the way database code used to be maintained before Visual
Studio’s offline schema development environment and then give you the benefits of Database Projects in comparison.

Database Source Code Management before Visual Studio Database Projects

In the world before Visual Studio Database projects, the following was the most common approach to database source code
management.

1. Individual SQL scripts for various objects put in their respective object folders, as shown in the following example:

Figure 17 - Source controlled database project structure before Visual Studio Database projects

Copyright 2010 Microsoft Corporation Page 37


Visual Studio 2010 Database Projects Guidance Document -
2. SQL Script has to be written based on the state of target database where The SQL Script has to be deployed.
Therefore, if the Stored Procedure already exists on the target database and if you want to modify that stored
procedure, then the stored procedure script must be written with the ALTER PROCEDURE or IF EXISTS (…) DROP
PROCEDURE and Re-Create Procedure. The same procedure applies for TABLE. If the table does not exist on the target
database, then CREATE TABLE Scripts has to be written. If the table exists on the target, then ALTER TABLE scripts
have to be written.

Caution
The above statement only covers the difference in schemas, if you have data to preserve from several releases or
have dependent objects using the object in subject to change this would cause additional actions to be taken and
scripts to be written and maintained. More about this can be found in the section “Offline Schema Development.”

If you are not using any Add-in with SSMS, the developer or the database administrator has to create code against the database
server and make sure it compiles and works. Then developers have to take additional steps to put this code in source code, and
have to write the change and migration mentioned previously and check it in to source control.

Because database source code management is dependent upon state of target database, when you leverage this model for
multiple releases you really can’t use source code branching in a true sense from a Source Code Control Management
perspective. This differs from the methodology used in regular code project where you can XCopy deploy source code, or in
particular the resulting assemblies, to the execution folder replacing the existing runtime libraries. The fact that you need to
preserve data in the existing database, preventing you from building the database from scratch, means that you either have to
invest a large amount of time to find the differences for deployment, when migrating from one branch to another, or you have
to create various permutations of scripts from and to different branches within your source control system.

Database Source Code management in the world of Visual Studio Database Projects

Visual Studio Database Projects have changed the way database


source code is managed. If you are a database developer and
develop C# code or any .NET programming then you may not find Offline schema model development
anything different in the way Database Projects manage database enabled to use VSTF features
source code. Database Projects has intended to work the same Branching and Merging seamlessly for
way C# or any .NET code has been structured and managed in the database code as similar as any other
C#/.NET projects within Visual Studio solutions files. .NET code.
One important feature in Database Projects is that developers
generally aren’t required to write database code based on the
state of target database where it’s going to be deployed. Database Projects produce the deployment by using its schema
comparison engine at deployment time. This really helps the way in which database code is integrated and managed in source
code control. The declarative nature of the Visual Studio database lets you use the Visual Studio Team Foundation features
Branching and Merging seamlessly for database code just like you would with any other .NET code.

Copyright 2010 Microsoft Corporation Page 38


Visual Studio 2010 Database Projects Guidance Document -

Maintain multiple active releases concurrently (Branching):

Source control is sometime boiled down to the fact that you store different version of source code of one branch only, so that
you can roll back to any past version for observation or to roll back to a specific release. For bigger projects with different
versions to maintain (such as an ISV scenario, where different customer have different version of the source code deployed)
you find yourself limited to one version only. Because many of you are already familiar with one version only for developing
code, the same paradigm applies to database code as well. That is where branching and merging of source code kicks in:

Branching is a common term used in source code control management systems. It provides isolation and enables teams to work
simultaneously on multiple versions of code. You can find guidance about how Visual Studio Team Foundation Servers enables
12
branching and how to use it from the MSDN article “Using Source Code Control in Team Foundation” as well as in the
13
branching guide from the ALM Rangers “Microsoft Team Foundation Server Branching Guidance”

Branching may be a new concept for database developers and database administrators who are not familiar with managing
source code in Visual Studio projects and solutions. Visual Studio Database Projects provide integrated database code
management and development experience with source code control.
13
You can find various branching strategies in “Microsoft Team Foundation Server Branching Guidance”

In terms of branching, Source Control Management typically involves:

 Branching database schema to create an isolated area based on a stable or milestone state of database
schema (such as the last successful build). During a branch operation, the source branch (where the
database is taken from) is called the parent branch and the target branch, the resulting isolated copy, is the
child branch. For example, Single Team Branching Model

Nightly Build
(Early Validation)

V1.1 FT3
3 4 5 8

V1.1
1 2 6 7

Production

Figure 18 - Sample simple Team Branching model

 DEV - The DEV branch is isolating all new development activity whether it is for feature development, bug
fixing for next release (vNext), or integration of breaking changes. This area is designed to isolate, contain, and
stabilize new development activities.
 MAIN – The MAIN branch is used for final stabilization (QA) of all integrated features prior to releasing vNext.
MAIN should be kept as stable as possible.

 Within a branch, developers can make the changes to the Database Project, which is isolated from other branches.
 Developers can perform bi-directional merging of changes between two branches that share a parent/child
relationship. Merging from a parent branch to a child branch is called forward integration. Merging from a child

12
http://msdn.microsoft.com/en-us/library/ms364074(VS.80).aspx
13
http://branchingguidance.codeplex.com/

Copyright 2010 Microsoft Corporation Page 39


Visual Studio 2010 Database Projects Guidance Document -
branch to a parent branch is called reverse integration. On occasion, a merge can be made between two branches
that do not have a merge relationship (such as parent/child branch relationship). Such a merge is called a baseless
merge. A baseless merge creates a merge relationship between the source and target branches.
 Referring to the branching and merging guidelines of the ALM Rangers, in each of the branching plans, we start with a
Main branch. The main branch is intended to contain a stable database. Development branches are full child branches
of Main.
 We recommend frequently synchronizing the Main branch with each of the child Development branches. This is
accomplished by doing regular forward integration (FI) merges from the Main branch to its child Development
branches.
 On the other hand, we recommend only doing reverse integration (RI) (merging the database from a child
Development branch back to the Main branch) when the database in the source branch is stable and has passed
Quality Assurance (QA) quality gates.
 Keeping the Main branch synchronized with the Development branches helps avoid the “big bang” merge problem,
where many changes from the Main branch are merged into a child Development branch. This causes many merge
conflicts that must be resolved before completing the merge.

NOTE
While branching database project or adding a database project first time in Source Control, you do not need to version
following files:
 <ProjectName>.dbmdl – This file is the cached project model. It should not be source controlled. You always need
read/write access to this file while the project is open in the IDE. The cache should be rebuilt for each developer on
the team.
 <ProjectName>.dbproj.user – This file is the user project settings like deployment settings for isolated
development environments. Each developer should have their own settings files.
 Sql Folder – This folder under the database project will contain build outputs. Files in this directory need
to read/write on each build/deploy.
 Obj Folder - This folder under the database project will contain temporary build outputs. Files in this
directory need to read/write on each build/deploy.

RECOMMENDATION

Make sure any database references get version control so any .dbschema file referenced by database projects does get
branched or added in to source control.
Because database reference are not part of database project, when you open database project solution, it does not get latest of
.dbschema file of a referenced database. Therefore, you have to take the most recent version of the referenced .dbschema file
to often make solution the compile.

Copyright 2010 Microsoft Corporation Page 40


Visual Studio 2010 Database Projects Guidance Document -
Often when changes are made to a file in the source branch of a merge, they can be automatically merged with the
corresponding file in the target branch. Merge conflicts arise when changes are made to the same file in both the source and
target branches that are involved in the merge. When these changes are in different sections of the file, these merge conflicts
can be resolved automatically by the tool (AutoMerge). Sometimes the person doing the merge may know whether to override
the target file (take from source) or to ignore the source (keeping the target version). There are times, however, where
resolving merge conflicts requires manual intervention. In these situations, Team Foundation Server will display a three-way
merge conflict resolution window that shows the conflicting change. The user can view the database code in the source file, the
target file, and the resulting merged file. In Visual Studio® 2010, conflict resolution is now a non-modal operation. From here,
the user can select specific lines of the database code from the target or source files (or both) to be merged into the final result.

Caution
While merging database projects from one release to another understand which files are XML structured. Merge
cautiously, using any file comparison tool. Files like dbproj, dbschema, .sqlpermission are XML structured files. Usually
merging XML file imposes difficulties because most of the time, elements get restructured in source and target files.

Hands on Labs

We provide you with a couple of scenarios in the Hands on Lab (HOL) document, which will show you how to handle database
source control management with different branches. The HOL consists of the following scenarios:

 Single Team Branching Model


 Multiple Team Branching Model

Copyright 2010 Microsoft Corporation Page 41


Visual Studio 2010 Database Projects Guidance Document -

Integrating External Changes with the Project System

Objectives

The goals of the Integrating External Changes Section are to:

 Provide insight into how project system interacts with source control and deployment
 Outline techniques that can be used to manage complex data movement scenarios
 Handle SQL objects that the project system doesn’t support

Introduction

Visual Studio Database Projects represent a major evolution in database development. It has three primary capabilities that are
designed to make database development more like traditional development with a programming language.

 Visual Studio Database Projects eliminates the version control issues that were required previously. (see the
section “Offline Schema Development”)
 Visual Studio Database Projects tools have a robust deployment engine that can be used to deploy database
projects as packages instead of a collection of manually managed scripts.
 Visual Studio Database Projects tools also include advanced database tooling for Unit Testing, Refactoring, and
Schema/Data comparisons.

Database Projects, however, is a maturing product and despite its powerful features there are times when you need to step
outside of the project system in order to get the full advantage of Database projects features. This can be due to limitations in
the target database system, where certain operations cannot be covered from the deployment engine automatically for all
scenarios or due to the limitations that not all operations or objects are modeled within the project system.

To illustrate that, the section will cover the following topics:

 Complex Data Movement


 Unsupported Objects

Copyright 2010 Microsoft Corporation Page 42


Visual Studio 2010 Database Projects Guidance Document -

External Change Management

External changes come in two flavors.

 Changes to the database or database schema that happen outside of the Database Project’s schema model
 Code artifacts that are not part of the Database or Database Server Project.

The schema model, which materializes as the .dbschema file, is the blueprint of a database schema and allows comparison with
other models during deployment. The database and server projects, which materialize as file shredded artifacts in the project
system, are the mechanism for integrating with source code control.

It is not necessarily a bad thing to have external changes. When the


Database or Server Project doesn’t support a particular object you will First of all, it is not necessarily a bad
have to manage this externally. When you want finer control of data thing to have external changes. When
movement during deployment you often find yourself fighting the the database or server project doesn’t
project system and this drives you to work with objects outside of the support a particular object you will have
schema model or outside of the database project. to manage this externally.

There are three principles to which the scenarios try to adhere. These principles are in place to preserve as much of the
existing source control and deployment functionality as possible. In addition, the scenarios try to maintain the IDE experience in
a way that is natural to development. In order to use the project system efficiently, database development should use these
principles as the main pillars for ease of development, maintainability, and deployment.

Copyright 2010 Microsoft Corporation Page 43


Visual Studio 2010 Database Projects Guidance Document -

Principles

 Avoid Object Management in Pre and Post scripts: If the Database Project System supports an object, but you don’t
like the deployment decisions, this is when you may want to manage those objects in Pre and Post scripts. However,
this is a slippery slope that can quickly lead to managing all of the objects in the Pre and Post scripts. Once you leave
the path of putting the objects in source control, the project system might not be able to track all dependencies which
might let you run into issues at deployment time. An example for this would be to create an index on a column in a
post deployment script which isn´t modeled by Database Project system. If there is already an index modeled with the
same name, this can break the deployment as the Build process cannot find the duplicate names.

 Honor Source Control: There is a tendency for database developers to view the production database as the source
control master. This is absolutely counter to application lifecycle management and invalidates the Refactoring and
Unit Testing capabilities. The Database Project allows you to circumvent this principle by default. When you create a
project the ‘Generate DROP statements for objects that are in the target database but not in the project’ is OFF.
This has interesting side effects. When you deploy, you cannot guarantee that objects outside of the project system
will work with the code that you have tested. A simple way to test this is to drop or alter a foreign key relationship
and then change the name of the column that the foreign key was based on. The natural inclination is to exclude the
foreign key file artifact from the project system and then change the name of the column in the table definition. But
with “Generate DROP statements for objects that are in the target database but not in the project” OFF, the
deployment engine simply alters the table and the deployment fails because of the existing foreign key relationship.
And then you are tempted to start managing objects in Pre and Post scripts.

IMPORTANT
There is a discrete option beginning with Visual Studio 2010 to drop indexes and constraints only. You should make
sure that your models are in sync and avoid deleting operational indexes that are defined by database administrators.
In addition, make sure that the model you use for testing adheres with the production system.

 Preserve the IDE experience: There are many situations where it is tempting to create a state of the structure in the
project system that is not what you want to deploy. You will see this in Complex Data Movement. While there is
nothing ‘technically’ wrong with this approach, it opens the door to a lot of source control mischief. This is because
the changes you will need to make to Honor Source Control are based on the long-running sequence of your
development cycle. In most cases you have to return to the project system after you have deployed to production
and alter the project. A good example for this is if you need to migrate data from one version to the other before you
actually deploy the database schema change. Although this can be necessary, you should try to adhere wherever
possible to the data movement capabilities of the deployment tools with Visual Studio Database Projects.

RECOMMENDATION
While reading the principles you might have noticed that they are closely connected to each other and that they all adhere to
the same statement. Use the model as your primary source of truth and make sure that almost every artifact and change is
recognized by the model to make the lives of developers, testers, and database administrators easier and prevent unexpected
surprises for you.

Copyright 2010 Microsoft Corporation Page 44


Visual Studio 2010 Database Projects Guidance Document -

Complex data movement

One of the major challenges in external change management is data. In comparison to .NET assemblies, which are easy to
deploy when a new version comes out, the challenge for databases is to change the schema while preserving the data that is
already in the database.
While this is typically all done behind the scenes during the deployment time and possible data loss can be prevented because
the switch "Block incremental deployment if data loss might occur" is ON by default, you might want to be prepared for this
beforehand.
There can even be situations where the limitation of the SQL Server syntax and implementation might force you to go the extra
mile before you actually deploy the schema changes, for example, changing a NULLable field to be NOT NULLable, while filling
in meaningful instead of default values for the change attribute.

One option for this would be to hook in a PreDeployment Script gathering meaningful data for the column that changed to be
NOT NULLable after deployment. This script would make sure that the constraint rule would be fulfilled during deployment
time. As described later in this topic and being one of the major challenges, we prepared an HOL for you. We consider different
ways to solve the problems, compare the different techniques, and give you the chance to pick the right option in your special
situation.

Unsupported objects

While you read the list of unsupported objects through the version history of Database Projects you will notice that only a few
objects that aren’t supported yet remain. With the introduction of Server Projects, a big step was made. It is now possible to
cover almost the whole database environment. Nevertheless, some objects are not supported yet. The following list
summarizes the unsupported objects:

 Relational artifacts
o Session/Global TEMPORARY TABLE – Local is supported
o CREATE RESOURCE POOL
o CREATE WORKLOAD GROUP
o CREATE FULL TEXT STOPLIST (formerly known as noisewords)
o SQL Jobs
o Replication

 Non-relational artifacts
o SQL Server Reporting Services Reports (SSRS)
o Integration Services Packages (SSIS)
o Analysis Service definitions (SSAS) [MODEL, DMX,MDX]

 Object Options Not Supported


o Change Data Capture
NOTE
Change Tracking is supported in Visual Studio 2010. Change Data Capture is not supported in that schema
modifications are blocked by deployment verification.

Copyright 2010 Microsoft Corporation Page 45


Visual Studio 2010 Database Projects Guidance Document -

o Replicated Tables – Not supported in that schema modifications are blocked by deployment verification.
o FOR REPLICATION on STORED PROCEDURES – SPROCS for replication created by SQL Server for replication
are not supported.
o WITH CHECK/WITH NOCHECK on CONSTRAINTS

NOTE
Constraints are handled by deployment options. In GDR and GDR2 they were always deployed WITH CHECK
(through SQL Default). In Visual Studio 2010 going forward they are deployed with WITH NO CHECK and,
optionally, with WITH CHECK at end of deployment.

o Non SQL Server Linked Servers with 3-Part Names – Oracle, Excel, etc.
o TABLE – LOCK ESCALATION
o INDEX OPTIONS – MAXDOP, DROP_EXISTING, SORT_IN_TEMPDB

Although this is a very short list of objects not being modeled in your database project, you might find yourself in a situation
having one of these objects types in your production ecosystem with the need to support it. The HOLs will cover one of the
unsupported objects (SQLJobs) and show you how to maintain and handle them during development and deployment time

CLR Assemblies

Introduced with SQL Server 2005 and being the mid- and long term replacement of extended procedures, this object type will
gain more and more importance throughout the current and next versions of SQL Server. More information about integrating
14
CLR artifacts in SQL Server can found be found in the MSDN reference “Introduction to SQL Server CLR Integration”. While
being a different project type itself, being created and built externally to the Database Project, the project system will definitely
need to have knowledge of the existence of the SQLCLR assembly and if changes happen to the object, many dependencies can
exist. Therefore, it is necessary to keep track of the relationships to objects and the building order during a full deployment or
incremental deployment when a schema changes occurs. Starting with a limited support in the first releases of Database
Projects, SQLCLR assemblies are now native artifacts. SQLCLR assemblies can now include the .NET projects with project
references, which makes it easier for the project system to realize any changes that happened and honor the dependency tree.

For those working with SQLCLR or planning to include CLR assemblies in the project system, we created an HOL giving you some
practical exercise on how to build and manage these kinds of artifacts.

Hands on Labs

To get more insight to the topics, the HOL document will let you deep dive into the following topics:

 Complex data movement


 Supporting unmanaged objects

14
http://msdn.microsoft.com/en-us/library/ms254498.aspx

Copyright 2010 Microsoft Corporation Page 46


Visual Studio 2010 Database Projects Guidance Document -

Build and Deploy Automation with Visual Studio Database Projects

Objectives

 How Database Projects are built and deployed in different scenarios ranging from local interactive builds to multi-
environment, automated deployments.
 Insight into how to handle specific scenarios not currently covered by Database Projects and the most common tasks
and gotchas related to build and deployment.
 Show the process throughout development, build, and deployment.

Introduction

Packaging and deployment of database code has been traditionally a complex and manual process that requires a great deal of
coordination between developers and database administrators.
This process usually involves identifying the SQL objects that are needed on a given target database and creating update scripts
to “patch” the database to bring it up to date with the latest SQL code. In most cases, these database update scripts are created
manually by developers and carefully reviewed by database administrators to ensure that the changes will not have any
adverse impact.
In organizations that use multiple test environments, such as our common scenario that is mentioned in the general guidance
document (Development, verification test, acceptance test, performance, etc.) and where good builds are promoted from one
environment to the next, the process of syncing new development code with various databases in different states becomes
even more complicated. This happens because a single update script is not enough to reconcile the expected as well as the
unexpected differences in all the environments.

Database Projects have been designed from the ground up to simplify the database build and the deployment workflow.
Database Projects allow developers to write their code without caring about the existing state, but rather focus on the desired
shape of their database schema

Building Database Projects interactively

Building Database Projects in Visual Studio is no different from building any other type of project. The same build options
available for other types of projects, such as C#, are available for Database Projects. However, the “build” process that takes
place behind the scenes is specific for this type of project like other special projects.

Database Project Model Validation

Prior to the release of Visual Studio Team System 2008 Database Edition GDR R2, a design database was used to store and
validate the database project's schema model. The design database was dynamically created when you opened a database
project (.dbproj). The project system stored the schema model in this design database (SQL 2005 Express by default) behind
the project system. As you versioned your database schema, changes were validated against this live database instance and
any errors would be reported immediately through the error list in Visual Studio. For example, if you tried to use a variable that
was not defined you would get an error immediately in the error list. Here is an example of this error in Visual Studio 2008
Database Edition:

Copyright 2010 Microsoft Corporation Page 47


Visual Studio 2010 Database Projects Guidance Document -

Figure 19 - Behavior in old project using the validation database

IMPORTANT
Beginning with the release of the GDR R2 and moving forward in Visual Studio 2010, the product no longer uses a live
design database to store and validate the database schema model from the project system. Instead, the database
schema model is stored in a SQL CE database and validation is performed by the product's validation engine against
an in-memory model of the database schema.

This is a substantial change in the product's architecture and enables many scenarios that were not possible with the previous
architecture. Database schema models are implemented by Database Schema Providers (DSP) and are extensible. So, if we’re
working in a SQL Server environment we may be using a SQL100 DSP or if we’re working in an Oracle environment we may be
using an ORA11 DSP. This architecture allows DSP models to be added and serviced without requiring a major release for the
development environment. Moreover, the model can now be compiled into a single .dbschema file and used by other project
features and shared with other development teams. Read more about the data service provider extensibility in the article
15
Extending the Database Features of Visual Studio .
In this model based architecture we’re working in a completely disconnected database development environment. Connection
to a live database from the project system is limited and only available when intending to import, compare, or deploy changes
to a target database instance. As we develop our database schema, validation runs interactively, based on changes occurring
throughout the project system as well as on-idle, while we’re not actively making schema changes.

15
http://msdn.microsoft.com/en-us/library/aa833285.aspx

Copyright 2010 Microsoft Corporation Page 48


Visual Studio 2010 Database Projects Guidance Document -
Validating the schema is a resource-intensive process and focused on validating all top level objects, any references between
objects, and most dependencies between objects and their composing children objects. There are additional validations that
run to catch common design time mistakes, but not all mistakes.

KEEP IN MIND
Schema validation is not as granular as in the previous architecture. The most significant difference between the GDR
and previous version in terms of validation is the lack of validation of programmability object bodies (functions and
stored procedures). Within the body of programmability, objects validation is kept to minimum so as not to impact
the performance of the developer's interactive user experience. Most of the validation that is performed within the
bodies of statements is to ensure all objects referenced and their children can be fully resolved. The code is parsed
and interpreted, but not everything is validated completely. In fact, the example above would not be caught at design
time, but rather, at deploy time in GDR. In Visual Studio 2010, the Database Project has expanded its design time
validation and now catches undeclared variables.

The following scenario also shows a deployment failure based on the same issue:

Figure 20 - Certain validation error are only caught at deployment time

RECOMMENDATION
Given this change, you see how important it is to do trial deployments to ensure that errors that can only be found at
deployment are caught before making production deployments. Typically, we will do this many times during development as
we implement unit tests for the database schema.

Copyright 2010 Microsoft Corporation Page 49


Visual Studio 2010 Database Projects Guidance Document -

Additionally, deploying to a sandbox database will help to build


confidence in deployments to other environments. This is also done in
Additionally, deploying to a sandbox
many environments during integration. For example, the integration
database can be created or updated at the end of each day or after
database will help to build confidence
check-ins trigger build and deploy when using continuous in deployments to other environments.
integration. Custom static code analysis rule may also be implemented The key is to deploy early and often to
to check for undefined variables at design time, if necessary. The key is validate the deployments.
to deploy early and often to validate the deployments.

Database Project Model Compilation

You can simply compile a database project by selecting “Build <project name>” from the Build menu in Visual Studio.
When we compile the database project the database model is fully validated, serialized, and then the .dbschema is produced.

The compilation flow can be described as follows:


1) Database project is loaded into memory (Build output: Loading project files…)
2) Database project model is built (Build output: Building the project model and resolving object interdependencies...)
a. The offline schema model is recreated from cache (if present) or constructed from .sql files in the project.
b. The schema model is resolved and all dependencies are checked.
3) Database project is built (Build output: Validating the project model...)
a. The offline schema model is validated (this is a model-wide validation).
b. Project settings are processed and copied to the output path.
c. Referenced schema models copied to the output path.
4) .dbschema is generated (Build output: Writing model to <projectname>.dbschema...)
a. The schema model is serialized and packaged into the .dbschema file.
b. The deployment manifest is created.
c. If static code analysis is enabled on build, then it will run. Note: If static code analysis is run manually, it will
trigger the build (steps 1-4).

The result of building a Database Project is a number of artifacts created in its output. Here is a summary of these artifacts and
their description:

- .dbschema file – This file is a serialized XML representation of the schema model. It represents the blueprint of the
database.
- .deploymanifest file - This file is a manifest containing all of the project-level configuration information that is
required to enable deployment without also needing the database project file (.dbproj). The manifest is an XML file
with a structure that is very similar to an MSBuild project file.
- Pre and Post deployment scripts – These separate files are scripts that run before or after the scripts that create or
update the target (deployment scripts). You can have only one pre-deployment script and one post-deployment
script, but you can include other scripts from within these scripts.

NOTE
No comparison with a target database is performed when you build only the database project. This allows you to build a
database project once and then deploy it as many times as necessary. The differential or upgrade script is created at the time
of deployment and is specific to each target.

Copyright 2010 Microsoft Corporation Page 50


Visual Studio 2010 Database Projects Guidance Document -
Database Project Properties

The behavior of the build process is defined by the Database Project properties. Many properties are common to other Visual
Studio project types, such as the output directory (OutDir), and many of them are unique to Database Projects.
Project settings are common to all build configurations in a database project. A summary of the project settings and how they
16
influence the Build can be found here: “An Overview of Database Project Settings” .

Adding Pre/Post deployment Events

Visual Studio makes it relatively easy to hook in to pre- and post-build events by using the Build Events tab within a project’s
property pages. This is done to perform actions before or after a database project is built. This may be helpful in scenarios such
as the following examples:

 To copy assets (.sql files) between projects to ensure synchronization.


 To run a separate tool to update application models.

However, the notion of build is separate from deployment and when using database projects we frequently need to do
something at deployment time. Therefore we need a way to hook into pre- and post-deployment events, which may be helpful
in scenarios such as the following:

 To trigger a SQL Agent job to perform database maintenance.


 To trigger an SSIS package to initiate an ETL process.

How To: Add Pre- and Post-Deployment Events to Your Project

While deployment events are not exposed directly through the project property pages, the standard MSBuild framework
already defines these events, and we can manually update the project file to hook into them.

CLARIFICATION
Don’t confuse the Pre-/Post deployment scripts with the Pre- /Post deployment events. The Pre- /post deployment
scripts are integrated in the native project system of Database Projects, whereas, whereas the Pre- /Post deployment
event are part of the general project ecosystem. They can be both used together and are NOT mutually exclusive.

16
http://msdn.microsoft.com/en-us/library/aa833291.aspx

Copyright 2010 Microsoft Corporation Page 51


Visual Studio 2010 Database Projects Guidance Document -

The steps are simple and straight-forward:

1. Unload the project, by right-clicking the project node inside Solution Explorer and selecting the “Unload Project”
option.

RECOMMENDATION
Project files are XML based and therefore can be messed up easily. If you are not familiar with editing project files, we
suggest you to create a copy of the file in the file system first to make sure you have a working copy as your
insurance.

2. This will dim the project node inside Solution Explorer and mark it (unavailable). Now we can right-click it again and
select the “Edit <your project file name>.dbproj” option. This will load the project file inside the XML editor.

3. Next we have to add the target elements for the PreDeployEvent and PostDeployEvent, as shown below:

Figure 21 - Adding target elements for deployment events


4. After we make the changes, save and close the project file. Then reload the project by right- clicking the project node
again and choosing the “Reload Project” option. Note: If the editor is still open, we’ll be asked if it can be saved and
closed. The project will reload only after confirmation.

5. Now we can test if our pre- and post-deployment events are firing by deploying the project. If everything works we
should see the pre- and post-event messages in the output window as shown below on lines 9 and 14:

Figure 22 - Deployment output messages example

Copyright 2010 Microsoft Corporation Page 52


Visual Studio 2010 Database Projects Guidance Document -
6. Now we can attach custom actions to the project’s pre- and post-deployment events.

NOTE
When creating these events, it is important to remember that MSBuild creates a dependency chain for these events. The result
is that deployment is dependent upon successful completion of the pre-deploy event. Likewise, the post-deploy event is
dependent upon a successful deployment.

Integration of Project but not build related files

In some specific scenarios you may want to create or import SQL files in your project without making them part of the build
process. To accomplish this, just set the object property “Build Action” as “Not in Build”. This will exclude the file from the build
process (no build errors or warnings will be raised) and exclude the files from the resulting .dbschema. This means that the
contents of the file will not be deployed.

Finally, there are several warnings and errors that may arise when a database is imported into a new Database Project. Here is
some advice on how to fix the most common warnings and errors you may encounter:

Error / Warning How to fix


Code references to machine and other Domain or machine specific logins must be handled through post
accounts/logins deployment scripts. If you plan to deploy to more the one environment the
logins that are specific to one environment should be removed or set
WITHOUT LOGIN on users.
Permissions are granted to invalid users Update Database.sqlpermissions to correct invalid users.
If further changes are required use refactoring to make sure that
permissions are in sync with existing users.
Any view, stored procedure or function with Add a reference to the Database Project for the referenced database or its
cross database or cross server usage will fails to .DBschema file.
build (database A uses database B objects If you reference a .DBSchema file, make sure it includes the latest schema
within the same or different server) changes, otherwise build may fail if a referenced object is missing.
In addition, database references are case- sensitive.
A SQL command/file compiles correctly in SQL This is not a common case, but sometimes found while reverse engineering
Server but it fails to compile in Visual Studio an existing database (XML, XQuery, etc.). Use tracing to find the offending
SQL statement or statements. You may have to normalize or substitute the
expression when necessary. Tracing of operations can be turned on by
adding registry keys. More about adding registry keys can be found in the
Appendix section “Enable Database Project Trace.”
Issues resolving 3 part names Database Project does not support self-referencing 3-part names, but it does
“TSD4001: Invalid object name DB reference support the use of variables and literals to resolve references to external
17
not resolved…” databases.

17
http://blogs.msdn.com/bahill/archive/2009/08/26/using-self-referencing-or-local-3-part-names.aspx

Copyright 2010 Microsoft Corporation Page 53


Visual Studio 2010 Database Projects Guidance Document -

Automating Building Database Projects with Team Build

As the pace of development gets quicker, we are being asked to deliver higher quality products faster. This means that just like
.NET code, we need to start thinking about how we can apply agile development principles to building and deploying database
code. While the pace gets quicker, we don´t want to multiply our efforts to fulfill the new needs. That is where build
automation kicks in.

Team Build is a component of Team Foundation Server that allows development teams to control the how their application is
built and to automate it. Within Team Build there are five ways in which a build can be started. Starting a build is also known as
a trigger. These triggers are:

 Manual: Builds will need to be manually started.


 Continuous Integration: Builds will start each time a check-in occurs. For more information, see Setting Up
18
Continuous Integration with Team Build .
 Rolling builds: Builds only occur after a check-in has occurred and several minutes have passed. For more
19
information, see Setting Up Continuous Integration with Team Build .
 Gated Check-in: Builds are only checked into source code control after a build has been successful. For more
20
information, see Define a Build to Validate Changes Before Check-in .
 Scheduled: Builds are started at a specific time. There is the option to determine if the build will occur even if a
check-in hasn’t been made. For more information, see How To: Set Up a Scheduled Build in Visual Studio Team
21
Foundation Server .

So which one of these options do I choose to implement to trigger a build for a database project?
The answer is that in most major projects both a Continuous Integration and Scheduled builds are configured. Let’s talk about
each of these and why they are both important when to helping developing database code.

When to Use Continuous Integration

Before explaining when to use Continuous Integration (CI), let’s have a quick
recap of what CI is. CI is the practice of integrating, building, and testing an Continuous integration builds;
individual’s changes each time they check in with the existing code repository. the more often, the better.
Some benefits of CI include:
 detecting build breaks
 spotting integration and deployment issues early
 execution of specific tests
 automated code promotion
 identification of deployment issues.
 automation of redundant tasks
 increased stakeholder visibility into project progression
 automated code metrics reporting
22
More about the concept of continuous build integration can be found here: “Continuous Integration”

18
http://msdn.microsoft.com/en-us/library/bb668957.aspx
19
http://msdn.microsoft.com/en-us/library/bb668957.aspx
20
http://msdn.microsoft.com/en-us/library/dd787631.aspx
21
http://msdn.microsoft.com/en-us/library/bb668975.aspx
22
http://martinfowler.com/articles/continuousIntegration.html

Copyright 2010 Microsoft Corporation Page 54


Visual Studio 2010 Database Projects Guidance Document -
So why would we use CI as part of a database project?

The short answer is that we want to take advantage of the benefits listed above. However, implementing CI for a database
team is not that easy. Even though teams have been able to get CI working for application code, they continue to struggle with
how to integrate their database components into their CI process.
Databases pose a challenge in that they are stateful. CI works well for stateless applications where the previous version of the
application in the integration or staging environment can simply be replaced with each new CI build. However, databases
often must be upgraded to the current version to preserve existing data in the database. This requires each new CI build of the
application’s databases to be incrementally updated to include the necessary changes for each version.
At the end of the day, the reason why you would want to use CI for database projects is to ensure that integration
environments and the source code repository is in sync after each successful check-in, build, and deployment cycle.
To learn more about Continuous Integration please see the MSDN Library Article: “How To: Set Up a Continuous Integration
23
Build in Visual Studio Team Foundation Server” .

When to Use Scheduled Build

The other type of build that is ordinarily created as a part of a modern development team is a scheduled build. So what is a
scheduled build? A scheduled build is a build that is started at a specific time in the future on a planned timetable. Normally,
this scheduled build is defined to run on a time where the project activity is low, usually on a nightly basis. As a result, the
scheduled build is sometimes referred to as a Nightly build.
In contrast to the CI build, the scheduled build more closely mimics what will be deployed into production. The nightly build is
configured to either:
 drop and recreate the database if it is a database project that has not yet been released to production

-or-

 upgrade a copy of the production database.

Why have two builds?

There are significant differences between the scheduled and the CI build execute time or duration. The CI build is normally
defined to be a quick verification to ensure that integration issues are quickly identified through incrementally updating the
integration environment. Whereas the nightly builds are designed to be a longer running action, it is possible that running
additional, exhaustive functional integration tests, or having realistic values, determines how much time a production upgrade
would need. The nightly builds however would still have to run on a time frequency that would allow development teams to
quickly correct issues as they are identified.

23
http://msdn.microsoft.com/en-us/library/bb668971.aspx

Copyright 2010 Microsoft Corporation Page 55


Visual Studio 2010 Database Projects Guidance Document -
Deployment Options

To configure the options for how your database project will be deployed, you need to access the properties of your database
24
project. This is done via the deployment tab in the project properties.

Figure 23 - Configuring database project deployment options

On the deployment tab, the following options should be highlighted:


25
 Configure Deployment Settings for – This setting allows you to configure different settings for different environments.
The options available are:
o My Project Settings – Indicates that the settings will be shared with the whole team.
26
o Isolated Development environment – Indicates that these settings are just for the individual developer and are
not shared with the rest of the team members.
 Deploy Action – Details what occurs when the deployment action is called. The options are:
o Create a deployment script – A deployment SQL file is created as the deployment step and then no further
action is taken.
o Create a deployment script and deploy the database - Create a SQL script and also deploy the script to the
database based on the configuration settings identified in the deployment configuration file.
 Deployment Configuration – This details the configuration file that will be used to when deploying the database. During
unit testing, this file can be override via the AllowConfigurationOverride in the app.config file. The motivation for
using this override is when:
o Multiple developers will be running unit testing and they have their own local databases.
o A build box that runs unit testing and has a different testing database is used.

24
http://msdn.microsoft.com/en-us/library/aa833291.aspx
25
http://msdn.microsoft.com/en-us/library/dd193254.aspx
26
http://msdn.microsoft.com/en-us/library/dd193409.aspx

Copyright 2010 Microsoft Corporation Page 56


Visual Studio 2010 Database Projects Guidance Document -
 If you wish to use this feature, follow these steps:
o In the app.config file of the unit test project enter the <DatabaseUnitTesting
AllowConfigurationOverride="true" >
o Create a new .config file in the unit test project. The file must be called either:
 <machine name> .dbunittest.config
 <username>. dbunittest.config
o Include the <DatabaseUnitTesting> and define the connection strings as desired.
o Open up the local.testsettings and click the deployment tab.
o Click the deployment item and enable the deployment item.
o Add in the config file.

Figure 24 - Enabling unit tests for deployment

When the unit tests are run, the config file is deployed to the testing folder and utilized for the testing based on the following
precedence:
1. Is AllowConfigurationOverride set to true in app.config?
a. No - The app.config will be used.
b. Yes - Look for the override sections.
2. When unit test is run, it checks to see if override:
a. exists for machine (<machinename>.dbunittest.config>)
b. exists for user (<username>.dbunittest.config>)
3. If neither of the .config file exist and the AllowConfigurationOverride is set to true, the test will fail.

Copyright 2010 Microsoft Corporation Page 57


Visual Studio 2010 Database Projects Guidance Document -
How to Configure the Deployment Options

To change how the database will be deployed as part of a build you need to follow these steps:

1. Select the Deployment Tab from the Project Properties.

Figure 25 - Changing build deployment options

2. Select the “My Project Settings” from the screen above. There are two options that appear in the drop-down list
(show below). The isolated development environment allows you configure settings for a local “Sandbox”
development environment. This allows you to specify settings that are isolated to your own development
environment. The “My Project” settings are used to specify the settings that are common across the team for
example the database configuration settings for use on the build box.

3. This ensures that you are configuring the deployment settings for the database project.
4. Click Edit next to the Deployment Configuration screen.

5. The Deployment Configuration options are displayed.


a. For the Continuous Integration build ensure that the “Always re-create database” options is not
selected. With CI builds, it is important to ensure speed of the build. Speed ensures timely feedback on
changes to the developer. By removing the need to delete and recreate the database, potentially
expensive operations are also removed from the build.
b. The goal of the nightly build is to replicate what the production deployment will be like. There are two
types of projects:
i. Green field projects (projects where the database doesn’t exist) ensure that the “Always re-
create database” option is selected. This means that the build will recreate the database
every time and replicates what the deployment will be like into the production environment.

Copyright 2010 Microsoft Corporation Page 58


Visual Studio 2010 Database Projects Guidance Document -
ii. Brown field projects (projects where the production database currently exists) ensure that
the “Always re-create database” is not selected. In addition, a copy of the production
database should be used as the target database and restored from a known state before the
deployment of the database deployment occurs. This helps identify potential issues that
could occur when the database is promoted to a production environment.

Figure 26 - Specifying deployment options

How to create a team build


Whilst most of the steps about how to create a team build is covered in the Hands on Lab. The following are the high level
steps:
1. Create a new Build Definition via the Team Explorer Build Folder.

Copyright 2010 Microsoft Corporation Page 59


Visual Studio 2010 Database Projects Guidance Document -
2. Complete the build definition and define the build process.

Figure 27 - Completing the build definition

3. In the process tab, select which tests you wish to run as part of the build.

Figure 28 - Specifying build tests to run

4. Save and queue the new build to test.

The Hands on Lab show you how to configure Team Build to automate the build process.

Copyright 2010 Microsoft Corporation Page 60


Visual Studio 2010 Database Projects Guidance Document -

Deploying to a Database

After schema files (.dbschema) are generated, they can be used by Visual Studio databases to compare and deploy to existing
databases. This can be done from the IDE and from the command line. But before we jump into the details of how to
implement automated scenarios, let’s take a look at what happens behind the scenes when the “compare” operation takes
place.
Here is how the compare operation works:
1) Models of both the database project (represented by .dbschema) and the target database are created.
2) These two models are compared and a delta is calculated. This delta contains all the changes required in the target
database to bring it up to date with the project.
3) The delta is applied on the target database by the deployment engine. If the delta is not applied, a SQL delta script is
generated.

Figure 29 - Database deployment flow

To compare and deploy in an automated fashion, Database Projects have targets for MSBuild as well as a command line utility
called VSDBCMD, which we cover in the next sections.
VSDBCMD can be fed with a .dbschema file and a database to generate an incremental “delta” SQL script with all the SQL
statements that are required to get the database in sync with the .dbschema.

Copyright 2010 Microsoft Corporation Page 61


Visual Studio 2010 Database Projects Guidance Document -

PREREQUISITES
To use VSDBCMD, the machine that is running the command line utility needs to have some prerequisites installed.
Some of the prerequisites have to be installed, like the .NET Framework 4, and others will just need to be copied
along with the command line utility. For more information about the prerequisites, refer to the MSDN reference
27
“How to: Prepare a Database for Deployment From a Command Prompt by Using VSDBCMD.EXE.”

Here is a sample that compares a .dbschema file with a database to generate an incremental script:

VSDBCMD.exe /a:Deploy /cs:"Data Source=MyServerName;Integrated


Security=True;Pooling=False" /dsp:Sql
/model:c:\AdventureWorks\AdventureWorks.dbschema /p:TargetDatabase=
AdventureWorks /p:SqlCommandVariablesFile=
c:\AdventureWorks\Properties\Database.sqlcmdvars /manifest:
c:\AdventureWorks\AdventureWorks.deploymanifest /script: c:\
AdventureWorks\AdventureWorks.sql

Even though applying changes to the database directly from VSDBCMD is possible, there are certain circumstances where you
want to check the incremental script first and run it later. Therefore VSDBCMD is able to only create the scripts for an
incremental deployment. This two-step approach where you create delta script and later execute it is beneficial in many
scenarios that we will describe briefly.
The resulting SQL script can be simply executed on the target database that is running a SQLCMD command in the
corresponding server:

sqlcmd –ic:\AdventureWorks\AdventureWorks.sql

In addition, VSDBCMD can compare and deploy to the target database in a single shot by using the “/dd” parameter. Just add:
/dd:+ to deploy the script directly.
The full command line reference for VSDBCMD can be found in the Command-Line Reference for VSDBCMD.EXE (Deployment
28
and Schema Import .

At this point we have all the pieces to implement a basic end-to- end build and deployment automation. Please refer to the
deployment Hands on Lab to learn more.

The following section builds on these concepts to explain how to support multi environment deployments.

Build and deployment process on multi-environment settings

Covered in this section:


 Multi environment/server and build promotion scenario

27
http://msdn.microsoft.com/en-us/library/dd193258.aspx
28
http://msdn.microsoft.com/en-us/library/dd193283.aspx

Copyright 2010 Microsoft Corporation Page 62


Visual Studio 2010 Database Projects Guidance Document -
 How to build once and deploy many times
 Generating differencing scripts to deploy on multiple targets

Depending on how your development organization works, you may have one or more test environments used to stage builds
for different verification purposes.
It is not uncommon for IT teams at Microsoft to use six or seven test environments with multiple database servers. Builds are
usually promoted from one environment to the next if they meet certain quality criteria. This landscape results in multiple
databases in different states or maturity. For example, a build is deployed on environment A, but if its quality isn’t good
enough, it will not get promoted to environment B, leaving all databases in environment A and B out of sync. Of course this
scenario can be multiplied by the number of environment you have. The following diagram illustrates a typical build promotion
landscape for a small Microsoft IT project.
A common challenge is how to create a build that can be easily deployed to any environment without having to worry about
the fact that not all environments look the same.

Figure 30 - Creating a build that can be deployed to any environment

Most IT teams at Microsoft make a conscious distinction between the build and deployment processes. In general, the build
process compiles all the Visual Studio projects and solutions and generates what is referred to as a drop (also called a “build”).
Drops come in different shapes, some are just collections of files and some are packaged using different technologies.
The deployment process is all about consuming the contents of the drop and pushing all the necessary changes to all the
servers included in the target environment.

Copyright 2010 Microsoft Corporation Page 63


Visual Studio 2010 Database Projects Guidance Document -

Figure 31 - Server Team Build

As we just described in the previous section, although it is possible, to perform the entire build and deployment process, using
Team Build, for example, and run it in a single action, it is not an option when multiple test environments are in use and builds
need some kind of blessing before they are installed on certain environments. In this context, build and deployment become
clearly two different processes.
Microsoft Team Foundation Server Team Build is a common build automation system to run the build process in which default
output on the drop location includes the .dbschema file, deployment manifest, deployment options, and pre- and post-
deployment scripts.

Copyright 2010 Microsoft Corporation Page 64


Visual Studio 2010 Database Projects Guidance Document -

Figure 32 - Using VSDBCMD with a drop location to automate builds


These files are all that is needed to create a simple deployment script with MSBuild, .BAT or any other scripting language. The
basic algorithm of the deployment script is:
1) Run VSDBCMD.exe using the drop location and the target database as input. Redirect the resulting delta script to a
known location.
2) Run the delta script using SQLCMD (or use the VSDBCMD /dd:+ option to deploy the script automatically).

For details, review the associated Hands on Lab.


If your environments have a large number of servers, you may want to consider copying the contents of the deployment scripts
and running the deployment scripts locally. This will allow for parallel execution and produce faster schema compare times. You
can do this manually or, ideally, in an automated fashion using PowerShell, or similar utility, to copy the drop and perform
remote execution on your servers.

You may have noticed that the build-deployment sequence described previously involves generating delta scripts and running
them on the fly. This may or may not be desired depending on how your development organization works.
Database administrators sometimes own certain environments and will not let anything run on a database unless they can
examine closely all the SQL statements that will be executed. To support those scenarios you can Pre-Generate the delta scripts,
which basically means to move the schema compare operation from the deployment process to the build process.
The idea is to have the team build do the following:

1. Compile the Visual Studio database projects


2. Run a schema compare against the following;

Copyright 2010 Microsoft Corporation Page 65


Visual Studio 2010 Database Projects Guidance Document -
a. The environment database and generate a delta script.

BE AWARE
The disadvantage is that the build process (build machine, etc.) will need to connect to all the databases or possibly
all the environments in order to create an environment-agnostic promotable build. This affects its performance and
potentially creates traffic on the environment DBs during build time. If you don´t want to risk that, use the following
option mentioned.

b. The target model file and generate a delta script

KEEP IN MIND
Since Visual Studio 2008 GDR, Database projects provides a new feature that allows importing databases into .DBSchema files.
This can be used to import the environment databases into schema files. TeamBuild and even VSDBCMD can later compare
these schema files with the ones built from source control to pre-generate incremental scripts. This is particularly useful in
cases where the build server and the databases live in different sub-networks or domains and cannot see each other.

3. Create a drop that contains delta scripts that can be executed directly by the deployment script.

The benefit of this approach is that all the delta scripts are readily available in the drop for database administrators and any
other stakeholders to review.

Not only database administrators should be cautious of checking the deployment artifacts first. It is also in the interest of
developers and testers to be sure that the assumed schema from the operational database during development and test time
matches with the schema found at deployment time. It is therefore very important to find these model drifts before actually
changing the production database. The section about deployment verification in the testing and deployment section will cover
that in detail and explain how to check drifting before the actual deployment in a Hands on Lab.

Other Automation topics


Automating Database deployments using VSDBCMD and WiX

VSDBCMD does a very good job of deploying a database schema and it is relatively easy to script your deployments in the
scripting tool of your choice. But if you want a more complete installation experience you will want to use Windows Installer.
Windows Installer gives you the benefits of packaging all your developed artifacts like source code and database schemas
together, versioning your deployment releases, making them discoverable via WMI/MOM, running software prerequisite
checks prior to installation, handling environment configuration settings that are related to your database and offer the ability
to handle errors and design a setup workflow.

We will walk you through a fairly advanced scenario in the following pages. But before we begin, we should mention that
Windows Installer XML (WiX) is an XML language for creating Windows Installer *. msi files. This is not a WiX tutorial. Instead
we focus on the integration points between Database Projects and WiX. If you are unfamiliar with WiX and Windows Installer
SDK, we recommend going through one of the online tutorials before you practice what is presented here. Alex Shevchuk has a
29
good tutorial that I refer to when I want to figure out a new corner of WiX and Windows Installer.

29
http://blogs.technet.com/alexshev/pages/from-msi-to-wix.aspx

Copyright 2010 Microsoft Corporation Page 66


Visual Studio 2010 Database Projects Guidance Document -

For this example we are going to use some very lightweight Database Projects. The size and complexity of the project schemas
are not, in our experience, relevant to the intricacies of installation. More important is the solution structure and the
collaboration between the various project types. We will cover all the caveats in the least amount of complexity needed to
make you concentrate on the common understanding und physics of WiX. The following projects will be used (also in the HOL)
to walk you through the functionality:

 Customers is a simple customer database with a handful of table views and stored procedures.
 Sales is a simple order taking database that references the Customers database.
 CustomerServer is a server project that manages linked servers and Sql agent jobs.
 CustomersCLR is SqlCLR project that defines some custom types for the Customers database.
 Both Sales and Customers refer to system objects, and have a reference to master.dbschema.

Copyright 2010 Microsoft Corporation Page 67


Visual Studio 2010 Database Projects Guidance Document -
Here is a quick list of the integration points that will trip you up when it comes time to package this all together in an install.

 The master.dbschema needs to be part of the install or you will run the risk of VSDBCMD failing.
 The Customers.dbschema needs to be part of the install for the Sales database for the same reason.
 CustomersServer database has to be installed before Customers. The Customers database needs to be installed
before Sales. It is in CustomersServer that we enable CLR support a server wide setting that belongs in a Server
Project instead of a Database Project.
 Before we deploy the CustomerServer project we will want to stop the SQLAgent service from running and then start
it back up. Avoid creating a SQL job that refers to a non-existent database which will fail.
 Both Customers and Sales database need to expose their data and log paths so that they can be set at the time of
install.

Figure 33 - Dependency diagram for the deployment

In addition, we need to package up the redistributables for VSDBCMD and install them prior to installing all of the databases.

We have already given you an overview of the possible functionality and the semantics of WiX installer projects, and a deep
dive in creating your own installer projects based on this scenario. The dependencies in the preceding illustration can be seen in
detail in the HOL section for WiX deployment of this guidance.

Copyright 2010 Microsoft Corporation Page 68


Visual Studio 2010 Database Projects Guidance Document -

Deployment Configuration and Pre/Post Deployment Script:


Database Projects offer a series of files to control the deployment configuration. These files, located under the Properties folder
in the Database Project, contain a series of variables that will determine how the deployment behaves.
Here are the files and their purpose:

File name Description

Database.sqlcmdvars Contains the names and values for SQLCMD variables, which are used when you deploy the
project. You define one or more .sqlcmdvars files and associate each solution configuration
with one .sqlcmdvars file. For more information, see How to: Define Variables for Database
Projects.

Database.sqldeployment Contains deployment-specific settings, such as database name and target connection string.
You define one or more .sqldeployment files and associate each solution configuration with
one .sqldeployment file. For information about how to configure these properties, see How to:
Configure Deployment Settings for Database and Server Projects and How to: Configure
Properties for Deployment Details.

30
More information about the options can be found in the MSDN reference “Property Files in Database and Server Projects.”

30
http://msdn.microsoft.com/en-us/library/dd193289.aspx

Copyright 2010 Microsoft Corporation Page 69


Visual Studio 2010 Database Projects Guidance Document -
Pre/Post Scripts and Re-runnability
Most organizations that adopt Database Projects have a number of existing non-schema scripts that are used for various
purposes such as seeding the database or addressing specific scenarios.
After a database is imported into a new Database Project, these scripts can be placed manually as pre- or post-deployment
scripts, depending on when they need to be executed during deployment. Database Projects keep track of these scripts by
adding references to them in the Script.PreDeployment.sql and Script.PostDeployment.sql files located under the Scripts folder.
Here is a Script.PreDeployment.sql sample. The referenced file is highlighted.

When the project is compiled, the contents of all the scripts referenced in the Pre and Post files are written to a new set of
Script.PreDeployment.sql and Script.PostDeployment.sql files. The files are located in the project output along with the
.DBSchema file.

Figure 34 - Sequencing of deployment scripts in the build process

Copyright 2010 Microsoft Corporation Page 70


Visual Studio 2010 Database Projects Guidance Document -
During the deployment operation, the contents of pre- and post- deployment scripts generated by the build are appended in
the resulting delta script before and after the code generated by the compare. It is important to note that they are not
modified during the deployment, and the contents are appended to the beginning and post pended at the end of the delta
script, as-is.

Figure 35 - Output of VSDBCMD compare

When you perform multiple deployments to the same database on a given environment, the pre and post scripts will be re-
executed. To prevent undesired consequences, all the scripts must be re-runnable or idempotent. This means that all scripts
should be designed so that any re-executions will not leave the database in an inconsistent state. For example, if the script is
inserting data on a table it should check for the existence of the data before trying to insert it a second time.
Here is an example of a re-runnable script:

Figure 36 – Re-runnable table script example

RECOMMENDATION
Prepare your custom scripts from the beginning to be idempotent, so no matter which state the database to upgrade is in, the
scripts will have the same effect and will achieve the same end result.

Copyright 2010 Microsoft Corporation Page 71


Visual Studio 2010 Database Projects Guidance Document -
In some cases, teams have large amounts of legacy non-re-runnable scripts which cannot be made re-runnable in one shot
without a significant effort. Some teams may even need several releases to make all their legacy SQL scripts re-runnable, which
leads to a situation where some scripts are re-runnable and some are not, but all of them need to be executed at least once.
Although it is not an ideal situation, it is possible to deal with non-re-runnable scripts by selecting the pre and post scripts that
will be compiled and placed in the build output. This is done by adding and removing references in the
Script.PreDeployment.sql and Script.PostDeployment.sql files.

Copyright 2010 Microsoft Corporation Page 72


Visual Studio 2010 Database Projects Guidance Document -
Consider the following scenario, based on how a team at Microsoft dealt with this situation.
The team created approximately thirty Database Projects to host existing databases. The databases were imported from the
production environment. All the existing schema code, previously in source control, was discarded with the exception of
thousands of data manipulation files that were added to the projects as Pre and Post files. The vast majority of these Pre and
Post files were not re-runnable.
When the projects were built they included all the pre and post files. This was appropriate for deploying to an environment for
the first time, but it would cause severe database corruption in subsequent deployments. They needed a solution that would
allow them to create builds with all the PRE and POST files (for new environments with no data) and builds with only the new
PRE and POST re-runnable files (for subsequent deployments).
This problem was solved by committing to write any new PRE and POST files following the re-runnability guidelines. In addition,
the team developed a routine that crawls the database projects located in source control to find the PRE and POST files that
were checked in (modified or created) after certain given date and only add a reference to those files in the
Scripts.PreDeployment and Scripts.PostDeployment files. The routine was integrated into TeamBuild, and caused the build to
create an output with all the PRE and POST scripts if no reference date was provided. (This build is used for the first deployment
to a new environment.) An output with only the new or modified PRE and POST files was created if a date was provided. This
date is used for all the subsequent drops.
The reference date can be passed as a Team Build parameter or configured in the build workflow itself, if needed.

Figure 37 - Script pre-filtering and post-filtering for similar solution types


Similar types of solutions can be created based on different criteria to filter pre and post scripts.

Copyright 2010 Microsoft Corporation Page 73


Visual Studio 2010 Database Projects Guidance Document -

Hands on Labs

To get more insight to the topics, the HOL document will let you deep dive into the following topics:

 WiX installer creation for database projects


 Integration of TeamBuild
 Building and deploying outside team build

References

To learn more about excluding objects use the following references:


31
- Customize Database Build and Deployment by Using Build and Deployment Contributors (MSDN)
32
- Walkthrough: Extend Database Project Deployment to Modify the Deployment Plan References
- Offline Schema Development: http://blogs.msdn.com/bahill/archive/2009/03/02/offline-schema-development.aspx
- Deploying your Database Project without VSTSDB installed:
http://blogs.msdn.com/bahill/archive/2009/02/21/deploying-your-database-project-without-vstsdb-installed.aspx
- Managing data motion during your deployments (Part 1):
http://blogs.msdn.com/bahill/archive/2009/03/30/managing-data-motion-during-your-deployments-part-1.aspx
- Managing data motion during your deployments (Part 2):
http://blogs.msdn.com/bahill/archive/2009/07/02/managing-data-motion-during-your-deployments-part-2.aspx
- Visual Studio database Continuous Integration: http://blogs.msdn.com/bahill/archive/2009/07/31/come-visit-revisit-
the-beer-house-continuous-integration.aspx
- Customize Database Build and Deployment by Using Build and Deployment Contributors:
http://msdn.microsoft.com/en-us/library/ee461505(VS.100).aspx
- Reference Configure Deployment Settings for Database and Server Projects http://msdn.microsoft.com/en-
us/library/dd193254.aspx

31
- http://msdn.microsoft.com/en-us/library/ee461505(VS.100).aspx
32
- : http://msdn.microsoft.com/en-us/library/ee461507(VS.100).aspx

Copyright 2010 Microsoft Corporation Page 74


Visual Studio 2010 Database Projects Guidance Document -

Database Testing and Deployment Verification


Objectives

The goals of the Database Testing and Deployment Verification Section are to:

 Provide insight into how to unit test a database with the Visual Studio database tools.
 Outline techniques that can be used to verify that a database application has been successfully deployed.

Introduction

Unit testing is well documented and practiced for many years now. However, unit testing database code is still relatively new
with few tools to support it. In the past it has been up to individual developers to test their code either manually or through
the data access layer. Both of these mechanisms have short comings; they take too long, the test data is inconsistent and/or
key database functions like triggers and functions are not adequately tested.
Visual Studio Database Projects provides tools that support testing your databases. Visual Studio introduced a number of new
tools with Database Projects to simplify how developers and testers can test their application. Included with Database Projects
are unit testing tools for stored procedures, functions, and most of aspects of database. Using the additional testing tools in
Visual Studio, there are data generation tools with support for performance testing over both load and data volume.

This section will cover:


 Configuring projects for unit testing.
 Automating the testing including test data.
 Verification of database deployments.

Throughout this section, the guidance will highlight what is and is not supported by tools. When scenarios are not supported, it
will provide guidance for techniques that are used internally at Microsoft by various teams and in the field by Microsoft
partners and customers.

Database and Data Access Layer Testing

Testing data access has traditionally been a difficult endeavor. The approach used for data access layer design and
implementation may vary widely from one architecture to another. The variety of technologies available for data access is
incredibly varied; however, the options that are available can be divided into two primary approaches. One approach is to use
code that is written in the application by using object relation mapping technologies such as NHibernate or Entity Framework.
The other approach uses code in the database in the form of stored procedures, views, and functions. In either case some form
of code is written that retrieves data from the database tables and shapes it into a form that is consumed by the application.
Regardless of the approach taken to data access, the database tools available in Visual Studio can help test the data access
layer.

Copyright 2010 Microsoft Corporation Page 75


Visual Studio 2010 Database Projects Guidance Document -
Failing Fast / Find bugs early

Like any other code, unit testing the database code enables early feedback into
the development cycle. Finding bugs that are introduced during the initial
It has been suggested that
development using unit tests speeds the overall development time and keeps finding and repairing bugs
defects from making their way further into the process. It has been suggested during the development and
that finding and repairing bugs during the development and test cycle is an order test cycle is an order of
of magnitude cheaper than finding and fixing them once the product has been magnitude cheaper than
released. finding and fixing them once
the product has been
released.
A suite of unit tests will also assist in preventing bugs from being introduced later
in the development cycle as unit tests are regularly run against changing code
and finding bugs that may be introduced to existing functionality.

Depth of Coverage
Unit tests that target the database functionality directly, such as stored procedures or triggers, provide a depth and breadth of
coverage that can be difficult to achieve when testing through the data tier of an application. By executing a database function
directly, it is easier to target specific actions invoked by triggers or by calls to additional programmability objects. This way, you
can test their behavior immediately and determine the effects of the data-related code, avoiding the impact of business logic
that might change the data. This includes business logic that operates either before or after the interaction with the database.

Automating Testing
Why it is Important
Automated testing enables quick and early feedback on the state of the code base. Using automated tests that provide good
code coverage enable confidence that the continued evolution of the application code is still providing the correct functionality
as the application evolves. Note the value that these tests continually add throughout the lifecycle of the application as
regression tests against ever-changing code.

RECOMMENDATION
As a general rule you should strive to achieve full automation for all testing. Fully automated tests enable easier and more
reliable regression testing. The automated tests are run more frequently than manual tests and eventually become less costly
than manual testing.

The challenges with investing the time that may be required to automate tests must be balanced with the return on investment
(ROI) created by the application of the test runs. If the code under test is continually changing such that the test must be
continually modified to keep up with the changes, it may be a better investment to proceed with manual tests until the code
stabilizes. Another consideration when assessing the ROI is how long the code base is expected to live. If the application under
development is a temporary solution, the investment in automated test suites may not be realized for a short term project. Yet
another consideration is the impact of a specific are code should it malfunction or calculate the wrong results. This may
necessitate more automation or manual testing depending on the nature of the impact.

Copyright 2010 Microsoft Corporation Page 76


Visual Studio 2010 Database Projects Guidance Document -
Limitations

There are limitations to how much can be effectively covered using automated data tests. The time that execution takes can
often be the limiting factor. Unlike pure unit tests written against application code, database tests often require redeployment
of databases along with the generation of the data required to make testing the database both possible and meaningful.
Creating a database along with populating it can take considerable time as the size of the database and data increases.
To effectively use data generation plans during the development cycle only, re-create the database and rerun the data
generation plans when either the database or the data generation plan have changed to support the code under development.
For this reason it is better to exclude the recreation and deployment of a database and generation plan from the execution of a
test project.
Manually run the database deployment and data generation plans as needed, based on changes in either. If any of the tests
alter the data, run the tests within a transaction and roll back the transaction at the end of the test. This will keep the database
in a consistent state and will not require rerunning either the database creation or the data generation for each test run.

While generating deterministic and realistic data is important, you will have to wait if you want to do the following:

 Generate data upon every test run randomly using different seed values.
 Generate data upon every test run using the same seed values.
 Use a reference database to pull realistic or scrambled data (due to security reasons) using the build in data bound
generators.

Each option has its advantages and disadvantages in terms of determinism, speed, breadth and depth of realistic data
distribution, and use for use case and code coverage. However, it has to be decided per situation. In most testing cases you
would prefer to create the reference data once and pull it from the external data store to fill the actual schema for testing.

Configuring Projects for Unit Testing

For detailed descriptions of the test types available for unit testing databases refer to the following MSDN documentation
33
“Verifying Database Code by Using Unit Tests.”
Database unit tests are contained in the same type of Visual Studio projects as any other test types, whether they are unit tests,
performance tests or Web tests. This can present opportunities as well as confusion regarding the number of projects that are
required for testing, how many projects should be used for testing, and how to group the tests in projects.
When a deployment or a data generation plan fails, all tests in the project are marked as failed tests. This approach has been
taken under the assumption that if deployment or data generation plan fails then there is a problem with the database and no
tests should be executed or that their results be fully trusted. In the case that other tests types reside in the same project and
would not be affected by the failure they would still be flagged as failed tests giving incorrect results.
The two primary approaches to categorizing and organizing your tests are:

 business functionality
 technical functionality

Regardless of the categorization selected, if the database tests are meant to be executed by the developer as part of their unit
testing strategy, they should be easy and quick to run or they will not be effective. Lengthy tests are better suited to be
executed as part of scheduled builds on the team’s build server.

Grouping test projects by business functionality

33
http://msdn.microsoft.com/en-us/library/dd172118(VS.100).aspx

Copyright 2010 Microsoft Corporation Page 77


Visual Studio 2010 Database Projects Guidance Document -
When grouping tests by business functionality it is easier to isolate the required data generation plans to a specific area under
test. This can keep the data generation plans simpler to create and maintain as well as isolate testing by functional areas that
align with user stories or functional definitions.
Grouping projects by business functionality can also be advantageous when development teams work in feature teams or
members of the team tend to work in feature areas rather than working in distinct layers of the applications. For example,
some team members work in the user interface layer while other team members are the data access layer developers.
When developing applications using a feature-driven approach, keeping the same team members contained within their own
test projects helps to minimize project conflicts across teams at the source control level. In addition, targeting data generation
plans for specific business functionality is easier when a single team is working on a given area.

Grouping test projects by technical functionality

Grouping by technical functionality encompasses aspects such as load testing and performance testing. These types of tests
often have very different requirements for the test data as well as order of process to determine bottle necks.
Grouping projects in this manner may also map better to large teams that work in a horizontal fashion within an application. In
other words, if teams are organized into data access teams, service teams, and interface teams, structuring the test projects
according to team structure can lead to easier collaboration and minimize project conflicts.
For medium-sized development efforts, dividing the tests into business functionality is the recommended approach to leverage
data generation plans. The exception to this recommendation is for stress and load tests in which case the data generation
plans will be significantly different.

Quickly Creating a Test Project for Stored Procedure Testing

The Schema View can be used to quickly create unit tests for stored procedures. To do this, on the View menu, choose
Database Schema view. Next, expand the schema to the level of the Stored Procedures. Then, right-click a stored procedure
and select “Create Unit Tests.”

The wizard then guides you through the steps to do the following:
 Create a new test project or add tests to an existing project.
 Select which stored procedures for which you wish to create tests.
 Select the options for database deployment, creation, and data generation.

Copyright 2010 Microsoft Corporation Page 78


Visual Studio 2010 Database Projects Guidance Document -

Figure 38 - Unit tests can be easily created from Visual Studios context menus

Figure 39 - Selecting the artifacts will generate Transact-SQL stubs as well as .NET code for execution

Copyright 2010 Microsoft Corporation Page 79


Visual Studio 2010 Database Projects Guidance Document -

Figure 40 - Tests can be configured to prepare for execution, validation, and preparation environment

NOTE
The test project that is created is a standard Visual Studio test project and any of the other types of tests provided by Visual
Studio can be added to this project. The guidance around this is that the database projects are put in their own project. This
allows them to be isolated when they are built as part of a CI build that is searching for tests based on assembly names. This
practice may also beneficial where segmentation of your test assemblies for other layers of your application provides better
test case isolation.

Copyright 2010 Microsoft Corporation Page 80


Visual Studio 2010 Database Projects Guidance Document -

Figure 41 – Adding additional test types to the test solution

Copyright 2010 Microsoft Corporation Page 81


Visual Studio 2010 Database Projects Guidance Document -
Data Generation Plans and Test Projects

Data generation plans are used to create test data that conforms to developer defined data using data generators. Data
generation plans should be developed to create data in a repeatable manner that will support testing against the database
using multiple testing methods. A single data generation plan for a specific business functional area should be support the
following:
- data integrity tests
- data access testing using database unit tests
- application integration tests
- black box user interface tests

Creating a data generation plan to support multiple testing methods broadens the applicability of the data, enables reuse of the
data, and increases the scenarios that can be supported by a single data generation plan. Taking this approach may result in
more complex plans because the data may need to support multiple different test cases and scenarios. This is why the plans
should be scoped to a single functional area.
Data generation plans can be incorporated into test projects using configuration settings in the app.config file that is associated
with the test project. A sample configuration section is shown here:

<DatabaseUnitTesting>
<DatabaseDeployment DatabaseProjectFileName="\<project folder>\<project name>.dbproj"
Configuration="Debug" />
<DataGeneration DataGenerationFileName="\<project folder>\Data Generation Plans\<plan name>.dgen"
ClearDatabase="true" />
<ExecutionContext
Provider="System.Data.SqlClient"
ConnectionString="Data Source=.;Initial Catalog=<target DB>;Integrated
Security=True;Pooling=False"
CommandTimeout="30" />
<PrivilegedContext
Provider="System.Data.SqlClient"
ConnectionString="Data Source=.;Initial Catalog=<target DB>;Integrated
Security=True;Pooling=False"
CommandTimeout="30" />
</DatabaseUnitTesting>

Defining a DatabaseUnitTesting section in the app.config file of a test project enables tests that access the target database
(<target DB>) to be repeatable, based on the data generation plan being executed prior to each test run.

NOTE
Keep in mind that only one data generation plan can be associated with any given test project. This limitation is a driving factor
in keeping data generation plans, as well as test projects, focused on a single functional area of the application. This can greatly
impact both the data generation plan and the tests that are included in the test project.

Copyright 2010 Microsoft Corporation Page 82


Visual Studio 2010 Database Projects Guidance Document -

Consider how the data needs to be structured as well as the approach to structuring your test projects as outlined above when
you determine how to coordinate the two. Refer to the section on data generation plans later in this document for further
guidance on structuring your plans and how they may impact the test execution.

o Visual Studio Database Unit Testing Strengths:


 Easy to get up and running
 Data can be deterministic
 Common case tests are already provided
 Easy to group multiple test scenarios into a single database call
 Leverages SQL, which makes them easier to write for database developers
o Visual Studio Database Unit Testing Weaknesses:
 No in product support for data driven tests Different assert approaches within the same framework
can be non-intuitive. For example, some asserts are conducted using SQL to test the results while
others leverage the asserts using the testing framework.
o Reference database versus test database:
 Pros and Cons of a read-only database for sourcing data.
 Pros and Cons of re-creating a database prior to testing.
 Testing against a database under development, managing change.
 Using labels to create a known version.

Data Generation and Reference Databases

Data generation plans play a key factor in supporting repeatable tests that rely on the database. However data generation
plans are not suitable for all scenarios and must be structured in certain ways to be effective. With the different type of data
generation options along with the ability to create custom data generators, the possibilities can be over whelming when you
first try to create meaningful data generation plans. This section will provide guidance about how to best leverage data
generation plans for both local and automated database tests. It will also provide insight into how to structure and divide data
generation and test execution into separate execution plans.

Creating the right plans for the tests

Data generation plans are easiest to develop if they are created along with the tests. It can be difficult to understand what data
will be required for any given test before the test is written. Often specific data scenarios will be required that are not evident
until the tests are being developed. To best accommodate this, aligning the data generation plans with a specific logical area
that aligns with both business functionality and data base schema can be the most effective.
For example, if you are developing a banking application it may be easiest to establish data generation plans that focus on just
customer management, a separate plan that focuses on account transactions, another plan that focuses on application meta
data management, and so on. This approach keeps the data generation plans more manageable as the data dependencies are
minimized. This approach also provides a broad enough set of data to accommodate most of the tests for that functional area
of the application and database. Minimizing dependencies should be a goal of defining the boundaries of the data to be
generated in a plan. Single plans that generate data for an entire database can be extremely difficult to coordinate but on the
other hand, provide satisfying data, when that database is large or complex.

Copyright 2010 Microsoft Corporation Page 83


Visual Studio 2010 Database Projects Guidance Document -

Copyright 2010 Microsoft Corporation Page 84


Visual Studio 2010 Database Projects Guidance Document -
Using Reference Data

Reference data exists in virtually every database. This data is often configured on database creation using scripts that write the
data to static reference tables. This data consists of things like lists of countries and data types such as account types, user
types, etc.
This data is usually captured in custom SQL scripts that are part of the post-install scripts within a database project.
The other source of reference data will come from production databases. This can often be the case when working with an
existing database rather than creating a new database from scratch.
If the database creation includes reference data creation such as post deployment scripts, the execution of a data generation
plan may or may not impact that data. When defining your data generation plan execution, one of the options that must be
chosen is whether to preserve the existing data in the database or deleted it all. Unfortunately, at this time, there is no ability
to selectively choose which tables to clear and which to leave. If you choose to clear the database then you will most likely find
at some point that you still require the reference data while clearing the transactional tables.

RECOMMENDATION
The easiest way to support this is to also maintain a reference database that contains the source data. To re-capture this data
in your test database if your reference data is captured using post deployment scripts is to deploy the database twice.

1. The first deployment is only required when the reference data that is required for your test changes, either
structurally (database schema) or functionally (the contents of the data). This first deployment should target a
common known database location, either locally or on a network server and serve as a read-only source.

2. The second deployment is used in conjunction with a data generation plan that clears the database. Within the data
generation plan, the reference data is re-populated from the first database using a Sequential Databound Generator
on the required columns in the table. This Generator will select the contents from the reference database, resulting
in the reference data being re-populated in the test database.

IMPORTANT
Prior to Visual Studio 2010 if Identity columns are used the generation plans will result in the keys being off by 1 due to the way
re-seeding identity columns is implemented in SQL Server. This problem has been resolved in Visual Studio 2010.

If the reference database is a copy of production or previous data, the first deployment is not required and the target of the
Sequential Databound Generator will be a copy of the production data.

RECOMMENDATION
34
When using either the Sequential Databound Generator or the Data Bound Generator you may choose to write your SQL
statement to explicitly target the column that you are targeting, for example Select City From Addresses. Alternatively, you can
simplify things by using a “Select * From Addresses” statement. Using this approach, the data generation plan will
automatically filter the resulting columns to those with a coercible data type for your target column. Although this may be
slightly easier and faster to write it may result in data generation plan execution performance degradation if the source table
has either many columns or many rows or both.

34
http://msdn.microsoft.com/en-us/library/dd193262(VS.100).aspx

Copyright 2010 Microsoft Corporation Page 85


Visual Studio 2010 Database Projects Guidance Document -
Creating Meaningful Data versus Random Data

The best practice is to leverage the data generators that are supplied with Visual Studio for generating random data. Although
the data may be meaningless, in most cases the generators will exercise a very wide variety of data contents as well as value
limits such as string lengths and numeric capacities. These values will often uncover bugs that may not be detected using
typical business values.
In many cases the actual content of the database is irrelevant as long as it is consistent. For example, if a particular test is to
select data and then ensure that it is the correct data based on known database contents, the actual values may be irrelevant.
In these cases the default values populated by a data generation plan may be fine. However, in many cases there may be the
requirement to ensure that data takes a specific form. Using the AdventureWorks database as an example, there are many
columns that have constraints on the type of data that may be contained, such as on the characters ‘M’ or ‘F’ for the Gender
columns. In these cases you have a couple of options. The first option is to simply exclude that column from the data
generation plan. This is easy but may not meet your needs. The other option is to switch from the default String generator to
use a “Regular Expression” generator. Using regular expressions provides a simple means to specify the permitted contents of
the rows for the column.
Other options include leveraging Data Bound Generators, or custom generators to construct the data in the manner of your
choosing. Custom generators are discussed later in this guide.

Combining Actual Data with Anonymous Data

Real world data contains structure and relationships as well as demonstrates a degree of heuristics that can be extremely
difficult to simulate but may be required for robust testing. At the same time real world data may also contain sensitive
information that should not be accessible outside of the production environment.

By combining a copy of production data that has been scrubbed of sensitive information while preserving reusable data along
with generated data, a very complex and encompassing set of test data can be achieved. Using a combination of data bound
columns as well as generated data columns may come close to achieving the quality and structure of real world data while
maintaining data security.

Performance and load testing

Although performance and load testing is not part of the scope of this guidance it should be noted that data generation plans
can be leveraged very effectively for generating large quantities of data that can be used to automatically create and populate a
database with a known quantity of data. Unlike certain other tests that check quality of data or rely on data shaped in a specific
manner, the data generation plans should be focused much more on quantity. These types of generation plans are typically not
used in any other tests and do not require the same data quality as other data tests.
Using a data generation plan for generating large amounts of data can be particularly useful when running tests to determine
the impact of index changes and query optimization. This approach ensures that the data remains the same over changes to
the database or query structures.

 Best practices around monitoring of specific values within a table

Integrating Testing into the Build


Refer to the Build and Deploy Automation with Visual Studio Database Projects section of this guide for details on integrating
tests into the build system, especially the topic “How to create a team build.”

Copyright 2010 Microsoft Corporation Page 86


Visual Studio 2010 Database Projects Guidance Document -
When not to use Data Generation Plans

- Data generation plans may not be well suited for end-to-end black box testing by humans because the system-
generated data can be difficult to read or understand.
- Data generation plans do not work well for database structures that contain cyclical references, for example,
Employee tables references department which references Employee to identify the manager.

Custom Data Generators

Custom data generators are extensibility mechanisms for providing the generation of any type of data content required to meet
your needs. Leverage custom generators when there are specific needs that must be met for automated or manual testing that
the default generators and reference databases cannot meet. Develop custom generators to be flexible and configurable to
support running in different environments such as the developer workstation as well as a build server.
Look at leveraging custom generators for the following scenarios:

- A service or unsupported data source exists that provides sample data.


- A custom generator can be reused across different data sources, multiple tables, columns, or projects.

Detailed instructions about how to develop custom data generators can be found in the MSDN reference “An Overview of Data
35
Generator Extensibility” .

Verifying Deployment

In addition to executing server based builds and tests the build server should be configured to deploy the database to known
locations to verify the correctness of the deployment scripts. The build server leverages the schema compare capabilities in the
vsdbcmd command line tool or uses the database project properties.
Pre-deployment validation can be performed using the /p:VerifyDeployment switch to ensure that the target database will not
present any issues when attempting an upgrade deployment.
Once a database has been deployed, the deployed database can be compared to the database project schema to ensure that
the deployed database does match the expected end result. When performing these comparisons, take careful note whether
the “DropObjectsNotInSource” flag has been set. If this flag has not been set, then a schema compare may fail an equal
comparison if objects in the database, that are no longer represented in the database project model, were not removed. This
flag can be found in the project deployment option properties pages or by using the /p: DropObjectsNotInSource command line
switch.
These techniques may be used in an automated build and test routine or to validate manual deployments.
For further details about how to compare database schemas refer to the MSDN reference “How to: Compare Database
36
Schemas” .

35
http://msdn.microsoft.com/en-us/library/aa833172(VS.100).aspx
36
http://msdn.microsoft.com/en-us/library/aa833435(VS.100).aspx

Copyright 2010 Microsoft Corporation Page 87


Visual Studio 2010 Database Projects Guidance Document -
Finding model drifts

Database developers know that the database project should be the only version of truth. Having said this, many of you might
think back of situations where you didn´t find the expected schema during deployment of database changes to a production
environment. That can be based on many reasons. The most frequent cause is database administrators or operations making
changes out of band from the database project. Having the database in their control, they tend to do hotfixes, apply additional
indexes, do minor database schema changes, etc.
The problem with that is that at the same time, you are doing your testing, planning of maintenance window, and sanity checks
for upgrading the database. Let’s say you are planning version1+1, etc., on the basis of version 1, which was deployed before.
As the database administrator modifies version 1, version 1* will be the production master. When you try to deploy your
database schema of version1+1 to the production database, you might find the deployment engine doing additional work that
you didn’t estimate during your testing. The result is that either upgrade deployments fails or it takes longer than expected, as
indexes have to be dropped and recreated, etc.

SIDE NOTE
Using the new deployment engine of Database Projects, the tension with model drifts has eased a bit, because the differential
deployment script is created by comparing the production database with the supplied model right before the actual
deployment. This makes it easier to directly interfere with changes and inspect the deployment script before applying.
Nevertheless, model drifts are a still a significant issue and should be found before the actual deployment to the database
occurs.

Even though the deployment engine VSDBCMD has some new deployment options to drop existing indexes and constraints
created in the target database and not being in the source (because the setting for DropConstraintsNotInSource and
DropIndexesNotInSource is set to true by default), you probably don´t want to upset the database administrator after the
deployment by letting him see that all his fine-tuned indexes have gone away. Therefore, a good recommendation is to find the
differences of your model before planning the deployment and acknowledge a freeze window with the administrator where
after that no changes will be applied to the database. Beginning with the freeze window, let him create a model from the
database using the VSDBCMD and the import functionality and pass that over to you. Determine if you need to import any
changes in your project using the database schema comparison feature of Database Projects and make sure that you tests will
run also against this merged database project.

RECOMMENDATION
Negotiate some milestones in your deployment with the database administrator to make sure that the model you are building
your tests on is almost the same as used in production. This will lower the risk of having problems during the deployment and
gives you a way to build a deterministic and exact deployment time plan.

Copyright 2010 Microsoft Corporation Page 88


Visual Studio 2010 Database Projects Guidance Document -

At the time of your real deployment, take the model which was sent to you by the admin and compare it again with the current
production database. If anything changed since then and you therefore have a model drift, you can negotiate on the next steps
and estimate the risk of applying the changes to the database by e.g. generating a .sql differential script.
This is a very important and essential part of your deployment strategy and success. We have created an HOL for the practice
which will show you how to use and instrument the deployment utilities in your daily process.

Rolling Back Deployment

Rolling back a deployment on an existing database can be done in some cases when transactional deployment is chosen as a
deployment option. Unfortunately, some cases can´t be covered because some statements in SQL Server aren’t transactional,
such as changing file groups and properties of the database. In addition, if you choose to drop the database before creation,
there is no way to get the previous database back within a transactional scope. Another situation is that you probably do not
want to roll back a big data motion activity in any case when restoring a database backup would only cost a fraction of time
than waiting for the rollback.
If you still need the old database in case that the deployment fails, you might want to make sure that the production database
is backed up before the actual deployment. Using the Visual Studio tools you can ensure this by setting the deployment flag
within VSDBCMD (/p:BackupDatabaseBeforeChanges) to true. This setting can be found in the project deployment option
properties within the Database Project or by using the switch on the command line with VSDBCMD.

For further details on the available properties for VSDBCMD refer to the MSDN reference Command-Line Reference for
37
VSDBCMD.EXE (Deployment and Schema Import) .

Hands on Labs

To give you a deeper understanding of this section and let you dive in practically, we have provided you with the following HOL
scenarios:

 Basic creation of unit tests


 Advanced creation of unit tests using data generation plans
 Checking databases before deployment to find model drifting

References
- How Do I: Generate Test Data using Visual Studio Team System Database Edition?
http://msdn.microsoft.com/en-us/teamsystem/cc501309.aspx
- Apply Test-Driven Development to your Database Projects http://msdn.microsoft.com/en-
au/magazine/cc164243.aspx
- Database Unit Testing with Team Edition for Database Professionals
http://msdn.microsoft.com/en-au/bb381703(VS.80).aspx
- Agile Database Development – Scott Ambler http://www.ambysoft.com/books/agileDatabaseTechniques.html

37
http://msdn.microsoft.com/en-us/library/dd193283.aspx

Copyright 2010 Microsoft Corporation Page 89


Visual Studio 2010 Database Projects Guidance Document -

Appendix

Enable Database Project Trace


You enable tracing for database projects by running the reg file in the product directory. To enable tracing:

1. Open registry file located in the product directory. %Program Files%\Microsoft Visual Studio
10.0\VSTSDB\Tracing.reg
2. Edit the file and save a copy of it to your temp directory. Set TraceSwitch = 00000001, TraceToLogFile=
00000001, DisplayCallStack= 00000001, LogDir = “c:\\Temp\\VSTSDB”
3. Add the entry to the registry by double-clicking the new file from your temp directory.
4. Restart Visual Studio if it is open. All instances of Visual Studio must be closed before logging set will
become active for the next instance of Visual Studio.

You should find the log directory and log added for each session of database project usage. When an error occurs,
you should have a complete log entry for the error, including the stack.
The Tracing.reg file should look like the following before adding to registry.
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\10.0\VSTSDB\Tracing]
"LogDir"=“c:\\Temp\\VSTSDBTRACE”
"PrefixTime"=dword:00000001
"PrefixPid"=dword:00000001
"PrefixThreadId"=dword:00000001
"TraceSwitch"=dword:00000001
"TraceToLogFile"=dword:00000001
"TraceToDebugOutput"=dword:00000000
"DisplayCallStack"=dword:00000001
"UniqueLogFile"=dword:00000001
"EventIdsToTrace"

Copyright 2010 Microsoft Corporation Page 90


Visual Studio 2010 Database Projects Guidance Document -

References
General Links
Visual Studio ALM Rangers Site
http://msdn.microsoft.com/en-us/teamsystem/ee358786.aspx
http://www.tinyurl.com/almrangers

Team System Widgets


http://www.teamsystemwidgets.com

Videos for Team System


http://msdn.microsoft.com/en-ca/vsts2008/bb507749.aspx?wt.slv=topsectionsee

MSDN Web Site


http://msdn.microsoft.com/en-us/default.aspx

Copyright 2010 Microsoft Corporation Page 91