Visual Studio 2010 Database Projects Guidance Document

Visual Studio ALM Rangers

Visual Studio 2010 Database Projects

Guidance Document

2010/10/12

Visual Studio ALM Rangers

Microsoft Corporation

Visual Studio ALM RangersThis 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 -

Copyright 2010 Microsoft Corporation Page 2

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 CommonsAttribution 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.



ContentsTable 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



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



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



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



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



This guidance should be used in conjunction with documentation that accompanies the product and Microsoft Developer Network (MSDN) at http://msdn.microsoft.com

Introduction

OverviewWelcome to the Visual Studio 2010 Database Projects Guidance.This guidance discusses scenarios and approaches of using theDatabase Projects in Visual Studio 2010 to help you use the tools more effectively and maximize their value to your organization.

The documentation on MSDN provides a basic understanding of Visual Studio Database Projects and how to use them. What it sometimes 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 RangersThis 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.



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 andproject 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.



Build and Deployment: Build can be not only the step before the actual deployment; build can also be a recurringstep 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.



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

Supported in Data-tier Applications”1

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 ismigrated 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 about the DAC can be found in the MSDN reference “Data-tier Application Overview.”2

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).aspx2 http://msdn.microsoft.com/en-us/library/ee362011(v=VS.100).aspx



does not preclude the guidance from being beneficial if your organization differs from this scenario. For this scenario we will mainly use the Adventure Works sample database that can be found at the SQL Server Samples section on Codeplex3:

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 Projecto Visual Studio Data Access Projecto Visual Studio Database Server Projecto 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

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.

Figure 2 - Solution and schema view in Visual Studio 2010

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 applicationdeveloper, 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.

Project Build integration with MSBuild and Team Build Source Control integration with Microsoft Team

Foundation Server



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 useVisual 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



* 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 2010Premium 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



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 Editiono SQL Server 2005/2008/2008 R2 – In Visual Studio 2010o Providers are publicly extensible in Visual Studio 2010

Oracle DSP Provider by Quest Software provides for Visual Studio 20104

Database Project Build and Deployment Extensibilityo 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 Extensibilityo Contextual feature extensibility support per DSP provider.o Project Feature publicly extensible in Visual Studio 2010.

Feature Extensibilityo 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



The differences in development and deployment techniques between application and database development is largely attributed to the existence of data and operational state that inherently resides in all live databases.

Figure 6 - Database Project Extensibility

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

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. Whenthe 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 deployment techniques between application and database development is largely attributed to the existence of data and operational state that inherently resides in all live databases. The operational state includes configuration of the database, database schema, security settings, permissions and 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



Offline Schema Development enables a repeatable, flexible, process driven Database Development Life Cycle (DDLC) process

Visual Studio 2010 provides a Database Project and tools necessary to effectively manage database change in a manner which easily integrates into their organization's existing SCM processes. Visual Studio 2010 provides a disconnected, declarative database development environment based on a model representation of the 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.



Adoption of Visual Studio Database Projects may require a mental shift for some developers or at least a change in process or workflows.

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 applications where the production database represents the current version of the database will need to adopt a source code based approach where source code becomes the vehicle to which change 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 thesource 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



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



Figure 9 – Multitier Scenario: Database schema changes



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.



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):



Figure 12 - Table script for a new deployed database



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.



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.



The source controlled version of your project represents the truth of the database schema and the "compiled" .dbschema file is a blueprint of your schema at a specific point in time.

The deployment plan is executed against the target database or the deployment plan is deployed to script. This demonstrates how the target database change script creation is deferred to the time of deployment. This enables you to build your schema once and deploy it many times. The source controlled version of your project represents the truth of the database schema and the "compiled" .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 ordevelopment. 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.



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 StructureA 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. Theintroduction 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 TypesFor 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:



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 ProjectA 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



Functional Component ProjectWhen 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 databaseproject, 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.



Solution & Project Management SDLC ScenariosWhen 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 TeamsThe 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 & DependenciesFor 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.



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 MSDN topic “Starting Team Development of Databases that Reference Other Databases”6

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



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:

o “Walkthrough: Partition a Database Project by Using Partial Projects”7

o “How to: Import and Export Partial Database Projects”8

o “Starting Team Development of Large Databases”9

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.aspx8 http://msdn.microsoft.com/en-us/library/dd172128.aspx9 http://msdn.microsoft.com/en-us/library/dd193405.aspx#LimitationsOfPartialProjects



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 Database Project by Using Composite Projects”10 and “Uses and Limitations of Composite Projects”11

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.aspx11 http://msdn.microsoft.com/en-us/library/dd193405.aspx#LimitationsOfCompositeProjects



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



Source Code Control and Configuration Management

Objectives

Describe how Database Projects do the following:o Integrate with source code controlo 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 VisualStudio’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



Offline schema model development enabled to use VSTF features Branching and Merging seamlessly for database code as similar as any other .NET code.

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 anything different in the way Database Projects manage database source code. Database Projects has intended to work the same way C# or any .NET code has been structured and managed in the C#/.NET projects within Visual Studio solutions files.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.



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 branching and how to use it from the MSDN article “Using Source Code Control in Team Foundation”12 as well as in the branching guide from the ALM Rangers “Microsoft Team Foundation Server Branching Guidance”13

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. You can find various branching strategies in “Microsoft Team Foundation Server Branching Guidance”13

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

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).aspx13 http://branchingguidance.codeplex.com/

V1.1 FT3

V1.1

Nightly Build(Early Validation)

Production

1 2

3 4 5

6 7

8



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 fileto often make solution the compile.



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



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



First of all, 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 have to manage this externally.

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 have to manage this externally. When you want finer control of data movement during deployment you often find yourself fighting the project system and this drives you to work with objects outside of the schema model or outside of the database project.

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.



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.



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 extramile 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 artifactso Session/Global TEMPORARY TABLE – Local is supportedo CREATE RESOURCE POOL o CREATE WORKLOAD GROUPo CREATE FULL TEXT STOPLIST (formerly known as noisewords)o SQL Jobso Replication

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

Object Options Not Supportedo 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.



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 ESCALATIONo 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 CLR artifacts in SQL Server can found be found in the MSDN reference “Introduction to SQL Server CLR Integration”.14 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



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:



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’reworking 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 Extending the Database Features of Visual Studio15.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 changesto 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.




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.



Additionally, deploying to a sandbox database will help to build confidence in deployments to other environments. The key is to deploy early and often to validate the deployments.

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



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 influence the Build can be found here: “An Overview of Database Project Settings” 16.

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’sproperty 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 frameworkalready 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.




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 events4. 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



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 accounts/logins

Domain or machine specific logins must be handled through post 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 cross database or cross server usage will fails to build (database A uses database B objects within the same or different server)

Add a reference to the Database Project for the referenced database or its .DBschema file.If you reference a .DBSchema file, make sure it includes the latest schema 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 Server but it fails to compile in Visual Studio

This is not a common case, but sometimes found while reverse engineering 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“TSD4001: Invalid object name DB reference not resolved…”

Database Project does not support self-referencing 3-part names, but it does support the use of variables and literals to resolve references to external databases. 17

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



Continuous integration builds;the more often, the better.

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

Continuous Integration with Team Build18. Rolling builds: Builds only occur after a check-in has occurred and several minutes have passed. For more

information, see Setting Up Continuous Integration with Team Build19. Gated Check-in: Builds are only checked into source code control after a build has been successful. For more

information, see Define a Build to Validate Changes Before Check-in20. 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 Foundation Server21.

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 individual’s changes each time they check in with the existing code repository. 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

More about the concept of continuous build integration can be found here: “Continuous Integration”22

18 http://msdn.microsoft.com/en-us/library/bb668957.aspx19 http://msdn.microsoft.com/en-us/library/bb668957.aspx20 http://msdn.microsoft.com/en-us/library/dd787631.aspx21 http://msdn.microsoft.com/en-us/library/bb668975.aspx22 http://martinfowler.com/articles/continuousIntegration.html



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 Build in Visual Studio Team Foundation Server”23.

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



Deployment Options

To configure the options for how your database project will be deployed, you need to access the properties of your database project.24 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: Configure Deployment Settings for25 – 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.o Isolated Development environment26 – 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.aspx25 http://msdn.microsoft.com/en-us/library/dd193254.aspx26 http://msdn.microsoft.com/en-us/library/dd193409.aspx



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.



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.



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 buildWhilst 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.



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.



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.



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 “How to: Prepare a Database for Deployment From a Command Prompt by Using VSDBCMD.EXE.”27

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 and Schema Import28.

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.aspx28 http://msdn.microsoft.com/en-us/library/dd193283.aspx



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 areusually 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 promotionlandscape 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.



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.



Figure 32 - Using VSDBCMD with a drop location to automate buildsThese 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;



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 topicsAutomating 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 good tutorial29 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



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.



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.



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.

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




Pre/Post Scripts and Re-runnabilityMost 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



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.



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.



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 typesSimilar types of solutions can be created based on different criteria to filter pre and post scripts.



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:- Customize Database Build and Deployment by Using Build and Deployment Contributors (MSDN)31

- Walkthrough: Extend Database Project Deployment to Modify the Deployment Plan References32

- 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



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.



It has been suggested that finding and repairing bugs during the development and test cycle is an order of magnitude cheaper than finding and fixing them once the product has been released.

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 development using unit tests speeds the overall development time and keeps defects from making their way further into the process. It has been suggested that finding and repairing bugs during the development and test cycle is an order of magnitude cheaper than 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 CoverageUnit 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 TestingWhy it is ImportantAutomated 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 becontinually 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.



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 “Verifying Database Code by Using Unit Tests.” 33

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



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.



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



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.



Figure 41 – Adding additional test types to the test solution



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" />

<PrivilegedContextProvider="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.



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.





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

When using either the Sequential Databound Generator or the Data Bound Generator34 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



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 ofthe 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 BuildRefer 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.”



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 meetyour 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 Generator Extensibility”35.

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 Schemas”36.

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



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.



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 VSDBCMD.EXE (Deployment and Schema Import)37.

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 Professionalshttp://msdn.microsoft.com/en-au/bb381703(VS.80).aspx

- Agile Database Development – Scott Ambler http://www.ambysoft.com/books/agileDatabaseTechniques.html




Appendix

Enable Database Project TraceYou 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"



References

General LinksVisual Studio ALM Rangers Sitehttp://msdn.microsoft.com/en-us/teamsystem/ee358786.aspxhttp://www.tinyurl.com/almrangers

Team System Widgetshttp://www.teamsystemwidgets.com

Videos for Team Systemhttp://msdn.microsoft.com/en-ca/vsts2008/bb507749.aspx?wt.slv=topsectionsee

MSDN Web Sitehttp://msdn.microsoft.com/en-us/default.aspx

Documents

Visual Studio 2010 Database Projects Guidance Document