We get a lot of questions from customers for which we answer; use multiple projects (database and/or server). The following canonical examples represent the majority of what customers ask about

Define SQL instance level objects	For example, define Logins or Linked Servers.
Organize my code by SQL schema	For example, one project contains the objects bound to the HumanResources schema and another project contains the objects bound to the Sales schema.
Organize my code by SQL object type	For example, one project has all you tables and another project has all of your stored procedures.
Re-use the code implemented in one project in multiple database designs	For example you have some diagnostics functionality that you re-use in each of your database designs.

An important point is that in each of these cases the developer needs to use two part names when referring to objects declared in another project. A similar sounding but very different question is how to use multiple database projects when the developer wants to use three part names or four part names. That is the topic of another blog post. :)

The good news is that Data Dude makes it easy to implement the T-SQL code for the examples I’ve described above. If you implement C# or VB.NET code in Visual Studio you will find that the mechanics of setting up your solution are analogous to referencing assemblies. Customers seem to get confused with two areas

1. Creating the initial projects with the objects they want and then defining the references between the various projects
2. Deploying multiple projects to a single database.

Before continuing I recommend that you first read this blog post: The pros and cons of Partial Projects and Database Project References for some important background information.

Organize my code by SQL schema

In this walk through I am going to break the AdventureWorks2008 database into projects representing each schema: HumanResources, Person, Production, etc. While it may seem pedantic to do a detailed walk through I find that many developers get stuck at one point or another. So it should be nice to have a relatively complex example that actually works in the end. If you would a walk through of putting together a new, simple database design I suggest you read this White Paper: Collaborative Development with Team System 2008 Database Edition.

These are the steps to the process we’re going to go through

1. Create the Visual Studio solution
2. Import the database definition into the solution
3. Move the schema specific code into each of the projects while leaving any code that refers to multiple schemas in the main project
4. Configure the deployment settings in each project and Deploy

Create the Visual Studio solution

1. Create the Visual Studio solution by creating a new SQL Server 2008 Database Project. Name the project and the solution MyAdventureWorks2008.
2. Next add the projects to the solution for each of the schema in AdventureWorks2008: HumanResources, Person, Production, Purchasing and Sales
1. From the Solution Explorer context menu choose Add \ New Project…
2. Provide the project name and click OK

Import the database definition into the solution

There are several ways to do this

• Import the entire database design into one project then move the source files around using Import Script
• Import the entire database design into one project then move the source files around using Add Existing Item…
• Import only the objects we want into the individual projects using Schema Compare

I think the first option is quicker than using Schema Compare so that’s what I’ll use. In future blog posts I’ll use the alternative methods so you can see how the different approaches compare. Throughout this process I’m going to make changes, resolve any errors in the solution, then make the next change. It’s an incremental “get clean, stay clean” sort of approach.

Move source files into the appropriate projects

The key point to understand here is that we are only moving objects that do not refer to other schema into the individual projects. If an object depends on the HumanResources and Person schemas then we leave that object definition in the MyAdventureWorks2008 project. Foreign keys are the most common example of this sort of object definition.

1. Import the entire database design into the MyAdventureWorks2008 project
1. From Solution Explorer select the MyAdventureWorks2008 project
2. From the context menu choose Import Database Objects and Settings… to import the AdventureWorks2008 database into the project
3. 

As you can see from the following screenshot the import database process persists the .sql scripts into folders and files with the name of the schema. We want to move the objects in each of the schema that have no relationships with other schema into their respective project.

2. Move the objects bound to the HumanResources schema from the MyAdventureWorks2008 project into the HumanResources project

1. Right-click the HumanResources project in Solution Explorer and choose Import Script…
2. Choose Multiple Files and navigate to the Schema Objects folder of the MyAdventureWorks2008 project.
3. Choose the file …\Schema Objects\Database Level Objects\Security\Schemas\HumanResources.schema.sql and everything under …\Schema Objects\Schemas\HumanResources. Click Finish.

Now take a look at the long list of errors in the error list. Yikes, what have we done?

3. Let’s fix the unresolved references to Sql Types first.

1. Add another project to your solution named SqlTypes
2. Using Import Script import the contents of …\Schema Objects\Schemas\dbo\Programmability\Types from your MyAdventureWorks2008 project into your SqlTypes project
3. Build the SqlTypes project. It should build successfully.
4. In your HumanResources project add a Database Reference to the SqlTypes project
1. From the project’s context menu select Add Database Reference…
2. Select the SqlTypes project
3. Click OK

4. Now let’s fix the errors caused by references to objects in other schema. We need to delete these scripts from the HumanResources project. Remove the following files

1. FK_Employee_Person_BusinessEntityID.fkey.sql
2. JobCandidate.fulltextindex.sql
3. vEmployee.view.sql
4. vEmployeeDepartment.view.sql
5. vEmployeeDepartmentHistory.view.sql

At this point all of the errors in the HumanResources project are resolved. We still have a few warnings, however.

5. Add another project to the solution named Diagnostics

6. Using Import Script import the following files from the MyAdventureWorks2008 project into the Diagnostics project. Then build the Diagnostics project. It should build successfully.

• uspLogError.proc.sql
• uspPrintError.proc.sql
• DatabaseLog.table.sql
• ErrorLog.table.sql
• DF_ErrorLog_ErrorTime.defconst.sql
• PK_DatabaseLog_DatabaseLogID.pkey.sql
• PK_ErrorLog_ErrorLogID.pkey.sql

7. Now add a Database Reference from the HumanResources project to the Diagnostics project. At this point you should not have any errors or warnings. Sweet!

8. Now add a Database References from the MyAdventureWorks2008 project to the HumanResources, SqlTypes and Diagnostics projects. You should see a bunch of errors. All of these are because all the objects that we moved to the other project are still defined in the MyAdventureWorks2008 project. Fixing this is basically a search and destroy effort. Look at the errors in the error list and remove each file from the MyAdventureWorks2008 project. When you have no errors you are done. :)

9. Repeat the previous steps for the remainder of the schemas.

When you move the objects bound to the [Sales] schema into the Sales project you will find that the function [dbo].[ufnLeadingZeros] is only used in one place – [Sales].[Customer]. Since it is only used in here I chose to move the function into the [Sales] schema. Arguably it belongs in a utility project with the rest of the functions defined in [dbo] so I can reuse the code in other database designs.

1. In Schema View navigate to the MyAdventureWorks2008 \ Schemas \ dbo \ Programmability \ Functions \ ufnLeadingZeros node
2. Select Refactor \ Move to Schema… from the context menu
3. Select the [Sales] schema

10. At this point I checked the solution into Source Code Control. That was a lot of work!

Configure the deployment settings in each project

In order to actually deploy our database we need to configure a few settings in each project.

From Solution Explorer

1. In the MyAdventureWorks2008 project, open the Database.sqldeployment property file and clear the checkboxes for the DropConstraintsNotInSource and DropIndexesNotInSource settings. We don’t want the constraints and indexes defined in the other projects to be removed when the MyAdventureWorks project is deployed.
2. 
3. In each project, with the exception of the MyAdventureWorks2008 project, open the Database.sqldeployment file located under the Properties node for the project and clear the Deploy database properties checkbox. There is no reason for each project to cause the database settings to be changed.
4. In each project double-click on the Properties node to open the project properties. In the Deploy tab
1. Set the Deploy action setting to Create a deployment script (.sql) and deploy to the database.
2. Set the Target connection setting to the SQL server instance you will deploy the database to
3. Set the Target database name setting to MyAdventureWorks2008.

Deploy

Now attempt to deploy the solution – select Deploy Solution from the solution’s context menu in Solution Explorer. Notice that the Production project fails to deploy and displays the following error in the output window

c:\Projects\MyAdventureWorks\Production\sql\debug\Production.sql(328,0): Error SQL01268: .Net SqlClient Data Provider: Msg 1969, Level 16, State 1, Line 1 Default FILESTREAM filegroup is not available in database 'MyAdventureWorks2008'.

Unfortunately the Data Dude validation engine doesn’t catch this problem at design time. If it had we would have seen an error in the error list. To fix this we have some more code refactoring to do. We’re going to move the definition of the FILESTREAM filegroup and associated file from the MyAdventureWorks project to the Production project.

1. Using the same Import Script technique we used previously, import the following files from MyAdventureWorks2008 into the Production project
1. …\Schema Objects\Database Level Objects\ Storage\Filegroups\DocumentFileStreamGroup.filegroup.sql
2. …\Schema Objects\Database Level Objects\Storage\Files\FileStreamDocuments.sqlfile.sql
2. Remove the files from the MyAdventureWorks2008 project. You will get an error because the Default filestream filegroup is set in the Database.sqlsettings file. Fix the error
1. Open the Database.sqlsettings file for the MyAdventureWorks2008 project
2. For the Default filestream filegroup choose the empty value from the dropdown.
3. Now we have to set the Default filestream filegroup for the Production project.
1. Open the Database.sqlsettings file for the Production project
2. For the Default filestream filegroup choose the value DocumentFilestreamGroup from the dropdown.

Now try to deploy again. It should succeed.

Conclusion

The diagram below describes the solution we have created. The primary purpose of the MyAdventureWorks2008 project is to define referential integrity between tables in the various schema and any application level views that do joins across tables in the various schema. In theory each of the projects other than the MyAdventureWorks project could be re-used in other database designs.

We get a lot of questions on the forum for which the answer is to use partial projects and/or database project references. Before you choose one or the other method to implement your database design it is helpful to understand the pros and cons of each feature. This blog post attempts to give you some insight into these pros and cons.

Inside Data Dude

Before we discuss Partial Projects and Database Project References it is important to understand how the project system behaves. Specifically, it is important to understand how it represents your design internally. The following figure describes how a database or server project named “Foo” is represented. In other words, the figure describes what Data Dude consumes to create the in-memory model of your database design. We refer to the in-memory model as the “Schema Model.” The Schema Model represents four things

1. Your Project Properties \ Project Settings; Project version – SQL 2005, SQL 2008 or DAC and Collation for database model – The model is actually persisted in a SQL Compact database. Since there is not a 1 to 1 mapping between SQL Server collations and SQL Compact collations you have to tell Data Dude which one to use.
2. The database settings you define in the .sqlsettings file
3. The permissions you define in the .sqlpermissions file
4. The objects you declare in your .sql files
5. The XML schema collections you reference in .xsd files

The reason it is important to understand this is because it profoundly affects what happens when you deploy your project. If an object or setting is not in the Schema Model it will not be compared to the target database and added, modified or deleted when you deploy the project.

Partial Projects

Partial projects allow you to share source code files between projects without creating multiple copies of the actual source code. In other words, the same physical file is incorporated directly into the Schema Model for two (or more) projects. See the following figure. In this diagram some files have been exported from project “Foo” and imported into project “Bar.” It’s important to understand that the same physical .sql file(s) is being consumed by each project. The Schema Model for “Bar” does not understand that the source files are being maintained in another project (“Bar”).

This brings us to the Pros and Cons of partial projects

Pros

• When you include code by importing a partial project the T-SQL code is included in the project’s Schema Model.
• When you edit the .sql file the changes are reflected in the Schema Model for the project that owns the .sql file as well as the project(s) importing the file. Deployment is simple because all your objects are defined in one Schema Model.

Cons

• If you add a new file that you want to export you have to
  • Re-create the partial project export
  • Delete the partial project from the project doing the import
  • Re-import the partial project

This is obviously a big pain and is the number one reason people don’t like partial projects. The work around is to define all the objects that you plan to export from a particular project in one .sql file.

• The export/import definition is persisted in a .files file. This file contains links to the original .sql files being exported. These links are file paths so if the file paths change all the links are broken. This can easily happen as projects are checked into source control and then the projects are built using a build system like TFS Build.
• If you perform a refactoring operation on an object that has been imported/exported, the refactoring log is only persisted in the project in which you performed the refactoring operation. The refactoring log is what the deployment component uses to figure out that an object, for example, should be renamed instead of dropped and recreated. For example, if you perform the refactoring operation in the project that does the import, the preservation of intent information is not persisted to the project from which the object is exported. However, the object is renamed in both projects (assuming the Rename refactor operation). The work arounds are a) always perform refactor operations from the project that you will deploy or b) manually copy the specific refactoring element from the refactoring log file into the refactoring log file of the other project.

Database Project References

Database project references allow you to reference T-SQL objects defined in another database or server project. The objects defined in the referenced project are included as [External] objects in the Schema Model of the referencing project. See the following figure.

As the figure indicates, the objects defined in the referenced project are not truly included in the Schema Model for “Foo.” If an object is referenced that is not defined in the Schema Model the validation component tries to find the object’s definition in the [External] set of objects.

Two, Three and Four Part Naming

When you create your database project reference you have to decide if you will be referencing the objects from the referenced project using two part, three part or four part names. You control this behavior by defining Database Reference Variables, as explained in the section below titled Configuring the Database Reference.

Configuring the Database Reference

There are several configuration settings available when defining a database project reference. It’s helpful to understand what each setting actually affects. I’ve included a screenshot of the dialog below.

Database Reference

This is the setting that allows you to point to what you are actually referencing. You have two choices

1. Another project in the current solution
2. A .dbschema file

When you build a database or server project the artifact created is a .dbschema file. It’s important to understand that both choices actually end up pointing to a .dbschema file. Choosing the first option simply looks at the current build output folder setting and automatically figures out the path and filename. In other words, you don’t have to browse for the file. This also means that if you don’t actually build the project you are referencing the database reference is effectively broken. You’ll see a warning icon in Solution Explorer.

Database Reference Variables

Use these settings when you need to use three or four part names. In other words, you are defining a database reference to a project that will be deployed to a different physical database.

1. Define server variable – You are defining a SQLCMD variable and the associated value. You can then use the variable instead of hard coding a server name in your T-SQL code. When you deploy your project you can optionally override the value of the variable.
2. Define database variable – This setting gives you the option of defining a SQLCMD variable representing the database name or choosing the Literal option to indicate that your T-SQL code will be hard coding the name of the database. The most common use of the Literal setting is when referencing the database “master.”

Updating Schema Objects and Scripts

By selecting this option Data Dude will do a search and replace of any server or database names throughout your code with the variables you defined.

Resolution of External Objects

The option Suppress errors caused by unresolved references in the referenced project is the most relevant to topic of this blog post. This option affects how the validation component behaves. Imagine you are defining a reference to a project which in turn references another project (we’ll call it “Third”). Think about the previous explanation of how the Schema Model is populated. When the validation component is validating the [External] objects it will not be able to find objects that are defined in the project “Third.” If you leave this option off you will get errors for the objects defined in “Third.” By setting this option you cause the validation component to not attempt to resolve objects that are referenced from the project being referenced.

Now let’s look at the pros and cons of Database Project References.

Pros

• If an object is added, modified or deleted the Schema Model of the referencing project (“Foo”) will be updated as soon as the referenced project (“Bar”) is built. Remember that the .dbschema file is what is actually referenced.
• Since each project creates its own Schema Model you can improve the overall performance of Visual Studio by breaking your database design up into multiple projects. Note that there is a point of diminishing returns with this technique. All the Schema Models share the same process so memory limitations can become an issue.
• You can provide .dbschema files without providing the associated source code. Thereby preventing someone from making changes to the code of the referenced project.
• You can define references to other projects that define objects within the same database (two part names), a different database (three part names) or even a different server (four part names).
• Code reuse is very easy. Imagine you have one project that implements tables, views, sprocs, etc. for diagnostic or auditing functionality. You can re-use the functionality by referencing it from n other database projects representing various database designs. You have the flexibility to use two, three or four part names.

Cons

• Each project has to be deployed individually and the projects must be deployed in the proper dependency chain order. This is because the objects are only represented in the model for the owning project.
• Since each project must be deployed individually you have to make sure the deployment setting Generate DROP statements for objects that are in the target database but that are not in the database project is not enabled. Otherwise each time you deploy a project all the objects defined in the referenced projects will get dropped from the target database. This setting is defined in the .sqldeployment properties file and it is cleared by default. The implication of this behavior is that if you actually want to remove an object definition from the target database you will have to either recreate the database during deployment or explicitly drop the object using a tool like SSMS.
• Using Schema Compare to compare a database to a project that is part of a composite project (references using two part names) is very difficult. The problem is the model for the database represents the entire database design while the model for the project only contains the objects defined in that particular project. So Schema Compare reports a bunch of update actions for the objects defined in the other projects. If you need to use Schema Compare you have to set the update action for the objects that exist in other projects to Skip so they don’t get dropped from the target database when you do a Write Updates. That can be a lot of work! In order to avoid that I create a Visual Studio configuration (i.e. Release and Debug) named DontDeploy and set the Project Properties \ Deploy \ Deploy action to Create a deployment script (.sql). Then I can easily switch my Visual Studio configuration, do a build that doesn’t actually deploy to the target database and look at each deployment script. Remember that one is created for each project.

Conclusion

Hopefully this is helpful. Let me know if you still have questions on this subject that I haven’t addressed.

The first thing to point out is this functionality is only available in Visual Studio 2010 Professional, Premium and Ultimate SKUs. The second thing to point out is there are actually two implementations of T-SQL IntelliSense in Visual Studio: “Connected” and “Offline.”

Connected IntelliSense

Connected IntelliSense is active whenever you are in a T-SQL editor and are connected to a SQL 2008 instance. Note that SQL 2005 is not supported. The identifiers that are listed in the completion list are enumerated by querying the database that is currently selected in the editor’s toolbar. All SQL Server 2008 types are supported by Connected IntelliSense.

Offline IntelliSense

Offline IntelliSense is active whenever you are in a T-SQL editor and are editing a .sql file that is part of a SQL Database, SQL Server or Data-tier Application Component project. The identifiers that are listed in the completion list are enumerated by querying the in-memory model representing the contents of your project. This in-memory model contains all the objects in your project that are defined and saved to disk. A subset of the SQL Server 2005/2008 types are supported by Offline IntelliSense

• Inline table function
• Login
• Multi Statement Table function
• Scalar Valued function
• Schema
• Stored Procedure
• Table
• User
• User Defined Data Type
• User Defined Table Type
• View

Unlike C# or Visual Basic IntelliSense, T-SQL Offline IntelliSense does not support syntax auto-completion. For example, after type CREATE TABLE Foo, IntelliSense will not auto-complete the remainder of the syntax for defining a table.

The properties defined by database projects can be categorized as

• Project level properties – These properties apply to all Visual Studio configurations (i.e. Release, Debug, etc)
• Configuration level properties – These properties may be configured differently for each Visual Studio configuration (i.e. Release, Debug, etc)
• Isolated development environment properties – These properties are developer specific and are stored in the DBPROJ.USER file. These property settings override the Visual Studio configuration settings when the developer has chosen Isolated development environment from the Project Settings \ Deploy \ Configure deployment settings for configuration option. This allows the developer, for example, to specify a different SQL Server instance for their personal development environment than the one that will be used when the Debug configuration is built and deployed.

Project level properties

The following table describes the properties that apply to all defined project configurations (i.e. Release and Debug).

Configuration level properties

The following table describes the properties that may be assigned unique values for each defined project configurations (i.e. Release or Debug).

Isolated development environment

The purpose of the isolated development environment settings is to individual developers to control database deployment behavior without affecting other team members. These settings are not persisted in the DBPROJ file so they will not be checked into source code control. The following table describes the properties that may be set for the developer’s Isolated development environment. These properties are persisted in the project’s .user file as opposed to the project file itself. When the developer sets Project Settings \ Deploy \ Configure deployment settings for to My isolated development environment the following properties are used for the associated setting instead of the Visual Studio configuration’s properties.

In Visual Studio 2010 DBP projects (also known as database projects) have been replaced by DBPROJ projects (aka SQL Server 2005 or 2008 Database Projects). DBPROJ projects have only been available in Visual Studio Team System 2005 and 2008. Now these project types are available in Visual Studio 2010 Professional, Premium and Ultimate editions.

How do I migrate my DBP projects to Visual Studio 2010?

Refer to this blog post for a tool that will automatically convert your project into a DBPROJ project: Converting .dbp files to .dbproj files

Refer to this MSDN documentation for detailed instructions on doing the conversion by hand: msdn.microsoft.com/en-us/library/ee517378(VS.100).aspx

In Visual Studio 2010 Beta 2 we have introduced a new database project type to support SQL Server Data-tier Applications (DAC). For detailed information on what DACs are please search for information available on SQL’s Books On Line (BOL). I suggest using the search string “SQL Server 2008 R2 SQL Data-tier Application.” As new releases of SQL Server 2008 R2 are made available additional information will be published by the SQL Server team.

IMPORTANT: This is brand new technology from the Visual Studio and SQL teams. In order to deploy a DAC project you will need to target the forthcoming SQL Server 2008 R2 November Customer Technology Preview.

One of the cool things that shipped with the Visual Studio Team System 2008 Database Edition GDR (aka the GDR) is the command line utility VSDBCMD.EXE. By using this utility, you can take the artifacts created by building a Database Project and deploy them to a database instance. If the database doesn’t exist on the instance of SQL Server, it will be created. If the database does exist, it will be altered to look like the source code in your project.

We regularly get questions from developers that are implementing multi-tier applications asking to incorporate database deployment into their WiX based MSI. This blog post describes how you can do that.

An important thing to point out before we get started is that the VSDBCMD.EXE utility has several prerequisites that must be met before the utility will execute successfully. The prerequisites are

• Microsoft .NET Framework 3.5 SP1
• SQL Compact 3.5 – Note that SQL Compact allows you to redistribute the files that VSDBCMD.EXE requires. So you may optionally include these files in your MSI. The specific files required by VSDBCMD.EXE are described in the MSDN documentation for VSDBCMD.EXE.
• SQL 2008 Management Objects

Ensure that these prerequisites are installed on the computers on which you plan to run your MSI.

Development Environment Prerequisites

• Visual Studio Team System 2008 Database Edition GDR R2
• Windows Installer XML (WiX) Toolset (I recommend you download both the tools and the source code)

Overview

I have written this blog post assuming the reader knows very little about WiX authoring. For the experts out there you can skim the information you are already familiar with. Here’s what we’re going to do in the remainder of this blog post.

• Create the Visual Studio Solution
• Implement the WiX Installer
  • Create the source code files in the project
  • Define the directory structure that will be created when the installer runs
  • Define the artifacts from the database project that will get installed
  • Define the artifacts related to VSDBCMD.EXE that will get installed
  • Implement a dialog that will collect the SQL Server instance name and the database name that will be used when the database is installed
  • Implement the overall user interface for the installer
  • Implement the WiX code that executes VSDBCMD.EXE

Note: On operating systems such as Windows Vista or Windows 7, the installer will need to be run using Administrator privileges (aka run with elevated privileges).

Create the Visual Studio Solution

For the purposes of this blog post we will create a new Database project. If you already have a database project you can simply add it to the solution instead of creating a new one.

1. Create a new solution containing a database project: File\New\Project\Database Projects\SQL Server 2008\SQL Server 2008 Database Project
   1. Set the project’s Name to MyDatabase
   2. Set the Solution Name to DatabaseInstaller
   3. Click the OK button
   4. Add a Table to the database project so that something interesting will actually happen when we run our final MSI.
2. Add a WiX project to the DatabaseInstaller Solution: File\Add\New Project\Wix\Wix Project
   1. Set the project’s Name to InstallMyDatabase
3. Add References to the InstallMyDatabase project. These are the DLL’s that contain the actual code for executing the setup user interface.
   1. Right-click on the InstallMyDatabase project’s References node in Solution Explorer and select Add Reference…
   2. Click the Browse tab and specify the DLLs that are named WixUIExtension.dll and WixUtilExtension.dll.
   3. Click the Add button.
   4. Click the OK button.

Implement the WiX installer

Our installer is pretty simple. It will do the following

1. Present the user with a License Agreement dialog
2. Prompt the user for the name of the SQL Server instance he or she wants to install the database on as well as the name of the database. See the screenshot below.
3. Copy the artifacts created by building our database project to the computer
4. Copy  VSDBCMD.EXE utility and its assemblies to the computer
5. Execute VSDBCMD.EXE
6. Exit

Implement the WiX code by doing the following

1. By default the WiX project has a Product.wxs source file. Let’s add two include files so we can keep things organized
   1. Right click on project InstallMyDatabase in Solution Explorer, Select Add\New Item…\WiX Include File
   2. Set the Name for the file to DatabaseArtifacts.wxi. This file will contain the setup authoring for the artifacts created when we build our database project.
   3. Add a second file and Name it VsdbcmdArtifacts.wxi. This file will contain the setup authoring for the VSDBCMD.EXE utility and the files it requires.
2. Define the folder structure that we need to create by adding the following code to the Product.wxs file immediately after the Media element. This code will result in the path “Program Files\MyDatabase\Extensions\SqlServer\2008\DbSchemas” being created on the user’s system.

       <!-- Setup the folder structure for the install -->
       <Directory Id="TARGETDIR" Name="SourceDir">
         <Directory Id="ProgramFilesFolder">
           <Directory Id="INSTALLLOCATION" Name="MyDatabase">
             <Directory Id="Extensions" Name="Extensions">
               <Directory Id="SqlServer" Name="SqlServer">
                 <Directory Id="__2008" Name="2008">
                   <Directory Id="DbSchemas" Name="DbSchemas">
                   </Directory>
                 </Directory>
               </Directory>
             </Directory>
           </Directory>
         </Directory>
       </Directory>

   A couple interesting things to note about the values in the Id attributes for the <Directory> elements; 1) As you will see, WiX turns these values into properties that we can use in our authoring and 2) properties that are UPPERCASED can be overridden from the command line when the MSI is run. I’ll demonstrate this in the section that covers running the MSI we’re building.

3. Now include the two wxi files we created earlier

       <?include $(var.SolutionDir)InstallMyDatabase\DatabaseArtifacts.wxi ?>
       <?include $(var.SolutionDir)InstallMyDatabase\VsdbcmdArtifacts.wxi?>

4. Open the file DatabaseArtifacts.wxi and replace <!-- TODO: Put your code here. –> with the following code

     <DirectoryRef Id="INSTALLLOCATION">
       <Component Id="DatabaseSqlcmd" Guid="PUT-GUID-HERE">
         <File Id="Database.sqlcmdvars" Source="$(var.SolutionDir)MyDatabase\sql\debug\Database.sqlcmdvars" KeyPath="yes"/>
       </Component>
       <Component Id="DatabaseSqldeployment" Guid="PUT-GUID-HERE">
         <File Id="Database.sqldeployment" Source="$(var.SolutionDir)MyDatabase\sql\debug\Database.sqldeployment" KeyPath="yes"/>
       </Component>
       <Component Id="DatabaseSqlsettings" Guid="PUT-GUID-HERE">
         <File Id="Database.sqlsettings" Source="$(var.SolutionDir)MyDatabase\sql\debug\Database.sqlsettings" KeyPath="yes"/>
       </Component>
       <Component Id="DATABASEDBSCHEMA" Guid="PUT-GUID-HERE">
         <File Id="Database1.dbschema" Source="$(var.SolutionDir)MyDatabase\sql\debug\MyDatabase.dbschema" KeyPath="yes"/>
       </Component>
       <Component Id="DatabaseDeploymanifest" Guid="PUT-GUID-HERE">
         <File Id="Database1.deploymanifest" Source="$(var.SolutionDir)MyDatabase\sql\debug\MyDatabase.deploymanifest" KeyPath="yes"/>
       </Component>
       <Component Id="MicrosoftSqlTypesDbschema" Guid="PUT-GUID-HERE">
         <File Id="Microsoft.SqlTypes.dbschema" Source="$(var.SolutionDir)MyDatabase\sql\debug\Microsoft.SqlTypes.dbschema" KeyPath="yes"/>
       </Component>
       <Component Id="PostDeploymentScript" Guid="PUT-GUID-HERE">
         <File Id="Script.PostDeployment.sql" Source="$(var.SolutionDir)MyDatabase\sql\debug\Script.PostDeployment.sql" KeyPath="yes"/>
       </Component>
       <Component Id="PreDeploymentScript" Guid="PUT-GUID-HERE">
         <File Id="Script.PreDeployment.sql" Source="$(var.SolutionDir)MyDatabase\sql\debug\Script.PreDeployment.sql" KeyPath="yes"/>
       </Component>
     </DirectoryRef>

   Complete the code by replacing each instance of PUT-GUID-HERE with your own unique GUIDs. You can launch a GUID generation tool from the Visual Studio Tools menu: Tools\Create GUID. Choose the Registry Format and delete the open and close curly braces “{ }” after you paste the GUIDs into the code.

   Those of you familiar with WiX syntax will understand all the details of this code. For you rookies that don’t feel like reading the WiX documentation, here’s what’s going on:

   <DirectoryRef>	This element “references” the <Directory> element with the matching Id. It tells WiX that the components contained inside will get installed to the folder INSTALLLOCATION.
   <Component>	A component is a group of things that need to be installed as one atomic unit. All or nothing, so to speak. Each <Component> must have it’s own Guid. Guids are how the Windows Installer keeps track of components. It is strongly recommended that each component contain a single <File>. The reason for this recommendation has to do with servicing. If you ever need to create a patch you will reference the component(s) that needs to be serviced.
   $(var.SolutionDir)	A useful variable that is implemented by the WiX compiler’s pre-processor. Saves you from worrying about relative/changing paths.
   KeyPath	This attribute tells the Windows Installer (aka msiexec) to use this file to determine whether or not the component is installed on the system.

5. Open the file VsdbcmdArtifacts.wxi and replace <!-- TODO: Put your code here. –> with the following code

     <!--Make sure we have the correct path to the Data Dude redistributables regardless
     of the OS architecture.-->
     <?if $(var.Platform)=x64 ?>
       <?define SrcArchPath = "C:\Program Files (x86)\Microsoft Visual Studio 9.0\VSTSDB\Deploy\"?>
     <?else?>
       <?define SrcArchPath = "C:\Program Files\Microsoft Visual Studio 9.0\VSTSDB\Deploy\"?>
     <?endif?>
   
     <DirectoryRef Id="INSTALLLOCATION">
       <Component Id="MicrosoftDataSchema" Guid="PUT-GUID-HERE">
         <File Id="Microsoft.Data.Schema.dll" Source="$(var.SrcArchPath)Microsoft.Data.Schema.dll" KeyPath="yes" Checksum="yes"/>
       </Component>
       <Component Id="MicrosoftDataSchemaScriptDom" Guid="PUT-GUID-HERE">
         <File Id="Microsoft.Data.Schema.ScriptDom.dll" Source="$(var.SrcArchPath)Microsoft.Data.Schema.ScriptDom.dll" KeyPath="yes" Checksum="yes"/>
       </Component>
       <Component Id="MicrosoftDataSchemaScriptDomSql" Guid="PUT-GUID-HERE">
         <File Id="Microsoft.Data.Schema.ScriptDom.Sql.dll" Source="$(var.SrcArchPath)Microsoft.Data.Schema.ScriptDom.Sql.dll" KeyPath="yes" Checksum="yes"/>
       </Component>
       <Component Id="MicrosoftDataSchemaSql" Guid="PUT-GUID-HERE">
         <File Id="Microsoft.Data.Schema.Sql.dll" Source="$(var.SrcArchPath)Microsoft.Data.Schema.Sql.dll" KeyPath="yes" Checksum="yes"/>
       </Component>
       <Component Id="Vsdbcmd" Guid="PUT-GUID-HERE">
         <File Id="vsdbcmd.exe" Source="$(var.SrcArchPath)vsdbcmd.exe" KeyPath="yes" Checksum="yes"/>
       </Component>
     </DirectoryRef>
   
     <DirectoryRef Id="SqlServer">
       <Component Id="DatabaseSchemaProvidersExtensionsXml" Guid="PUT-GUID-HERE">
         <File Id="DatabaseSchemaProviders.Extensions.Xml" Source="$(var.SrcArchPath)Extensions\SqlServer\DatabaseSchemaProviders.Extensions.xml" KeyPath="yes"/>
       </Component>
     </DirectoryRef>
   
     <DirectoryRef Id="DbSchemas">
       <Component Id="MicrosoftSqlTypes" Guid="PUT-GUID-HERE">
         <File Id="MicrosoftSqlTypesDbschema" Source="$(var.SrcArchPath)Extensions\SqlServer\2008\DBSchemas\Microsoft.SqlTypes.dbschema" KeyPath="yes"/>
       </Component>
     </DirectoryRef>
   

     <!--Install the Visual Studio 9.0 registry key if it doesn't exist. -->
     <Feature Id="RegistryPreReqs" Title="Registry Prerequisites" Level="1">
       <ComponentRef Id="RegistryEntries"/>
       <Condition Level="0">NOT VISUALSTUDIOREGISTRY</Condition>
     </Feature>
   
     <!--VSDBCMD requires this REGKEY to be installed. Note that this will NOT be true for the Visual Studio 2010 version-->
     <!--HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\9.0-->
   
     <!-- Define the search for the Visual Studio 9.0 registry key -->
     <Property Id="VISUALSTUDIOREGISTRY">
       <RegistrySearch Id="VisualStudio90Registry"
                       Root="HKCU"
                       Key="Software\Microsoft\VisualStudio\9.0"
                       Name="(Default)"
                       Type="raw" />
     </Property>
   
     <!-- Define the Visual Studio 9.0 Registry entry-->
     <DirectoryRef Id="TARGETDIR">
       <Component Id="RegistryEntries" Guid="PUT-GUID-HERE">
         <RegistryKey Root="HKCU"
                      Key="Software\Microsoft\VisualStudio\9.0"
                      Action="create"
                        >
           <RegistryValue Type="string" Name="(Default)" Value="Default Value" KeyPath="no"/>
         </RegistryKey>
       </Component>
     </DirectoryRef>

    

   Just like you did previously, replace each instance of PUT-GUID-HERE with your own GUIDs. There are a few new things to point out in this code

   <?if…	While I was implementing this code I was working on the project on a couple different computers. One was running a 32-bit OS and the other was running a 64-bit OS. Well vsdbcmd.exe and it’s dependencies are installed in under “Program Files“ or “Program Files (x86) depending on the architecture of the OS. So, I took advantage of the WiX’s pre-processor’s conditional logic and predefined variable $(var.Platform) to define my own variable representing the path to the files I needed.
   Checksum	This attribute tells the Windows Installer that the file has a checksum that may be used to validate that the file hasn’t been tampered with. You should always set it to "yes" for executables (dll’s and exe’s).
   <Feature>	In the Windows Installer world a Product is composed of one or more Features. I am using this feature to define a component that I want installed if it does not already exist on the target system. The<ComponentRef> element defines the component I want installed. Specifically, the RegistryEntries component. The feature’s <Condition> element indicates that I want to feature installed the expression (NOT VISUALSTUDIOREGISTRY) evaluates to true.
   VISUALSTUDIOREGISTRY	This is a property that represents the results of the <RegistrySearch>. The attributes of the element define the particular registry key to search for.
   RegistryEntries	This <Component> defines the registry key that will be created assuming the <RegistrySearch> came back empty.

    

6. Now that we have all of our components defined, we need to tell WiX to actually install them. Open the Product.wxs file again and add the following code immediately after the <?include?> elements

       <!-- Define which files to install -->
       <Feature Id="ProductFeature" Title="InstallMyDatabase" Level="1">
         <ComponentRef Id="DatabaseSqlcmd"/>
         <ComponentRef Id="DatabaseSqldeployment"/>
         <ComponentRef Id="DatabaseSqlsettings"/>
         <ComponentRef Id="DATABASEDBSCHEMA"/>
         <ComponentRef Id="DatabaseDeploymanifest"/>
         <ComponentRef Id="MicrosoftSqlTypesDbschema"/>
         <ComponentRef Id="PostDeploymentScript"/>
         <ComponentRef Id="PreDeploymentScript"/>
         <ComponentRef Id="MicrosoftDataSchema"/>
         <ComponentRef Id="MicrosoftDataSchemaScriptDom"/>
         <ComponentRef Id="MicrosoftDataSchemaScriptDomSql"/>
         <ComponentRef Id="MicrosoftDataSchemaSql"/>
         <ComponentRef Id="Vsdbcmd"/>
         <ComponentRef Id="DatabaseSchemaProvidersExtensionsXml"/>
         <ComponentRef Id="MicrosoftSqlTypes"/>
         <ComponentRef Id="RegistryEntries"/>
       </Feature>

   Similar to the registry stuff that I described previously, this code defines a <Feature> which contains <ComponentRef> elements, one for each component that we want to install on the user’s system.

7. At this point you can build your WiX project and run the MSI that is created. Go ahead and build your solution. Open a command shell with elevated privileges (aka Administrator) and change directories to the location of the new MSI. The MSI is placed in <Project Folder>\bin\debug. Execute the MSI using the command line: msiexec /i InstallMyDatabase.msi /l*vx log.txt
   
   The installation will install each of the components onto your system. An entry will also be added to the Add Remove Programs (ARP) list. To uninstall run the command line: msiexec /x InstallMyDatabase.msi /l*vx log.txt
   
8. Our MSI currently doesn’t have an user interface other than a progress bar. What we really want is the typical dialog sequence that shows the user an End User License Agreement (EULA), collects information needed for the install, shows progress then finishes. WiX provides everything we need with the exception of the dialog to capture information about the SQL server and the database name we need to use when we deploy our database. Insert the following code in the Product.wxs file immediately after the <Feature> element we defined previously.

       <!--Define the dialog to get the Server and Database name information from the user-->
       <UI>
         <Dialog Id="DatabaseInformationDialog" Width="370" Height="270" Title="[ProductName] [Setup]" NoMinimize="yes">
           <Control Id="ServerNameLabel" Type="Text" X="45" Y="73" Width="100" Height="15" TabSkip="no" Text="SQL Instance Name:" />
           <Control Id="ServerNameEdit" Type="Edit" X="45" Y="85" Width="220" Height="18" Property="SERVERNAME" Text="{80}" />
           <Control Id="DatabaseNameLabel" Type="Text" X="45" Y="110" Width="100" Height="15" TabSkip="no" Text="Database Name:" />
           <Control Id="DatabaseNameEdit" Type="Edit" X="45" Y="122" Width="220" Height="18" Property="DATABASENAME" Text="{80}" />
           <Control Id="Back" Type="PushButton" X="180" Y="243" Width="56" Height="17" Text="&amp;Back"/>
           <Control Id="Next" Type="PushButton" X="236" Y="243" Width="56" Height="17" Default="yes" Text="&amp;Next"/>
           <Control Id="Cancel" Type="PushButton" X="304" Y="243" Width="56" Height="17" Cancel="yes" Text="Cancel">
             <Publish Event="SpawnDialog" Value="CancelDlg">1</Publish>
           </Control>
           <Control Id="BannerBitmap" Type="Bitmap" X="0" Y="0" Width="370" Height="44" TabSkip="no" Text="WixUI_Bmp_Banner" />
           <Control Id="Description" Type="Text" X="25" Y="23" Width="280" Height="15" Transparent="yes" NoPrefix="yes">
             <Text>”Please enter a SQL instance and database name.”</Text>
           </Control>
           <Control Id="BottomLine" Type="Line" X="0" Y="234" Width="370" Height="0" />
           <Control Id="Title" Type="Text" X="15" Y="6" Width="200" Height="15" Transparent="yes" NoPrefix="yes">
             <Text>{\WixUI_Font_Title}”SQL instance and database information.”</Text>
           </Control>
           <Control Id="BannerLine" Type="Line" X="0" Y="44" Width="370" Height="0" />
         </Dialog>
       </UI>
   

   This code defines a dialog that contains two labels and associated text input controls. When the user enters text into the ServerNameEdit and DatabaseNameEdit text controls it is persisted in the properties SERVERNAME and DATABASENAME, respectively.

9. Now we will define the overall user interface for our installer. I did this by copying the source code from the WixUI_Mondo dialog definition, renaming the Id and customizing it to include my DatabaseInformationDialog dialog. Insert the following code immediately following the <UI> element we just added.

       <!--Define the overall user interface - this is based on the WixUI_Mondo dialog set-->
       <UI Id="MyWixUI">
         <TextStyle Id="WixUI_Font_Normal" FaceName="Tahoma" Size="8" />
         <TextStyle Id="WixUI_Font_Bigger" FaceName="Tahoma" Size="12" />
         <TextStyle Id="WixUI_Font_Title" FaceName="Tahoma" Size="9" Bold="yes" />
   
         <Property Id="DefaultUIFont" Value="WixUI_Font_Normal" />
         <Property Id="WixUI_Mode" Value="Mondo" />
   
         <DialogRef Id="ErrorDlg" />
         <DialogRef Id="FatalError" />
         <DialogRef Id="FilesInUse" />
         <DialogRef Id="MsiRMFilesInUse" />
         <DialogRef Id="PrepareDlg" />
         <DialogRef Id="ProgressDlg" />
         <DialogRef Id="ResumeDlg" />
         <DialogRef Id="UserExit" />
   
         <Publish Dialog="ExitDialog" Control="Finish" Event="EndDialog" Value="Return" Order="999">1</Publish>
   
         <Publish Dialog="WelcomeDlg" Control="Next" Event="NewDialog" Value="LicenseAgreementDlg">1</Publish>
   
         <Publish Dialog="LicenseAgreementDlg" Control="Back" Event="NewDialog" Value="WelcomeDlg">1</Publish>
         <Publish Dialog="LicenseAgreementDlg" Control="Next" Event="NewDialog" Value="DatabaseInformationDialog" Order="2">LicenseAccepted = "1"</Publish>
   
         <Publish Dialog="DatabaseInformationDialog" Control="Next" Event="NewDialog" Value="SetupTypeDlg">1</Publish>
         <Publish Dialog="DatabaseInformationDialog" Control="Back" Event="NewDialog" Value="LicenseAgreementDlg">1</Publish>
   
         <Publish Dialog="SetupTypeDlg" Control="Back" Event="NewDialog" Value="DatabaseInformationDialog">1</Publish>
         <Publish Dialog="SetupTypeDlg" Control="Back" Event="NewDialog" Value="LicenseAgreementDlg">1</Publish>
         <Publish Dialog="SetupTypeDlg" Control="TypicalButton" Event="NewDialog" Value="VerifyReadyDlg">1</Publish>
         <Publish Dialog="SetupTypeDlg" Control="CustomButton" Event="NewDialog" Value="CustomizeDlg">1</Publish>
         <Publish Dialog="SetupTypeDlg" Control="CompleteButton" Event="NewDialog" Value="VerifyReadyDlg">1</Publish>
   
         <Publish Dialog="CustomizeDlg" Control="Back" Event="NewDialog" Value="MaintenanceTypeDlg" Order="1">WixUI_InstallMode = "Change"</Publish>
         <Publish Dialog="CustomizeDlg" Control="Back" Event="NewDialog" Value="SetupTypeDlg" Order="2">WixUI_InstallMode = "InstallCustom"</Publish>
         <Publish Dialog="CustomizeDlg" Control="Next" Event="NewDialog" Value="VerifyReadyDlg">1</Publish>
   
         <Publish Dialog="VerifyReadyDlg" Control="Back" Event="NewDialog" Value="CustomizeDlg" Order="1">WixUI_InstallMode = "InstallCustom"</Publish>
         <Publish Dialog="VerifyReadyDlg" Control="Back" Event="NewDialog" Value="SetupTypeDlg" Order="2">WixUI_InstallMode = "InstallTypical" OR WixUI_InstallMode = "InstallComplete"</Publish>
         <Publish Dialog="VerifyReadyDlg" Control="Back" Event="NewDialog" Value="CustomizeDlg" Order="3">WixUI_InstallMode = "Change"</Publish>
         <Publish Dialog="VerifyReadyDlg" Control="Back" Event="NewDialog" Value="MaintenanceTypeDlg" Order="4">WixUI_InstallMode = "Repair" OR WixUI_InstallMode = "Remove"</Publish>
   
         <Publish Dialog="MaintenanceWelcomeDlg" Control="Next" Event="NewDialog" Value="MaintenanceTypeDlg">1</Publish>
   
         <Publish Dialog="MaintenanceTypeDlg" Control="ChangeButton" Event="NewDialog" Value="CustomizeDlg">1</Publish>
         <Publish Dialog="MaintenanceTypeDlg" Control="RepairButton" Event="NewDialog" Value="VerifyReadyDlg">1</Publish>
         <Publish Dialog="MaintenanceTypeDlg" Control="RemoveButton" Event="NewDialog" Value="VerifyReadyDlg">1</Publish>
         <Publish Dialog="MaintenanceTypeDlg" Control="Back" Event="NewDialog" Value="MaintenanceWelcomeDlg">1</Publish>
       </UI>
   

   
       <UIRef Id="WixUI_Common" />

   I injected my new dialog in the overall sequence changing the LicenseAgreementDlg dialog’s Next button event to open my DatabaseInformationDialog and the Next button in my dialog subsequently launches the SetupTypeDlg. Similarly for the Back button events.

10. Once again you can build and run the MSI at this point. You will see the new dialog we have defined. There is one significant piece still missing, however. That is actually running VSDBCMD.EXE to install our database. To implement this add the following code.

        <!--Define the custom action to build the vsdbcmd.exe command line string-->
        <CustomAction Id="LaunchVsdbcmdCommandLine"
                      Property="LaunchVsdbcmd"
                      Value="&quot;[#vsdbcmd.exe]&quot; /a:Deploy /cs:&quot;Server=[SERVERNAME];Integrated Security=true;&quot; /dsp:Sql /dd+ /model:&quot;[INSTALLLOCATION]Database1.dbschema&quot; /p:TargetDatabase=&quot;[DATABASENAME]&quot; /DeploymentScriptFile:&quot;[INSTALLLOCATION][DATABASENAME].sql&quot;"
                      Execute="immediate"/>
        <!--Define the custom action to execute vsdbcmd.exe-->
        <CustomAction Id="LaunchVsdbcmd" BinaryKey="WixCA" DllEntry="CAQuietExec" Execute="deferred" Return="check" Impersonate="yes"/>
    
        <!--Define when the two custom actions will be executed-->
        <InstallExecuteSequence>
          <Custom Action="LaunchVsdbcmdCommandLine" Before="InstallFiles"/>
          <Custom Action="LaunchVsdbcmd" After="InstallFiles"/>
        </InstallExecuteSequence>

     

    I found this code to be the most difficult part of the whole project to get right. The first custom action’s (LaunchVsdbcmdCommandLine) purpose is to create the command line string that the second custom action (LaunchVsdbcmd) will actually execute. LaunchVsdbcmdCommandLine declares the property LaunchVsdbcmd and sets its Value. The identifiers inside [] are properties that will get bound to their actual values when the custom action is executed. The “#” inside the property references gets expanded to the folder where the files are being installed to (aka INSTALLLOCATION). The second custom action LaunchVsdbcmd uses the property with the name that matches the custom action’s Id as the command line when it invokes the entry point CAQuietExec. The custom action LaunchVsdbcmd knows to do this because the Execute attribute is set to deferred. The <InstallExecuteSequence> element is pretty straightforward. It defines when the Windows Installer will actually execute each custom action. Windows Installer executes a series of “actions.” InstallFiles is one of those actions. I chose this action because I know the user has entered the values for SERVERNAME and DATABASENAME. After this action is complete I know all the files I need are installed on the user’s system.

11. So that’s it. We now have an MSI that will deploy our database when it is run. Use the msiexec command line described earlier to execute the installer. Analyze the log file if the MSI fails for some reason. Any error messages returned by VSDBCMD.EXE will be captured in the log file.

What’s Missing?

There are numerous additional things that you will probably want to do in your MSI. For example, display your own EULA, make the project localizable or check that all of the VSDBCMD.EXE prerequisites exist on the system before attempting to run the utility. I leave the implementation of these additional features to you. If you would like to share your enhancements, implementation(s) or give me feedback on this blog post please attach a comment or send me a note: duke dot kamstra at microsoft dot com.