Skip to content

Commit 8caca68

Browse files
denreadenrea
authored
Merge pull request #36351 from dzsquared/sqlproj-jan2026
project ref article
2 parents 27f6637 + afe7b9d commit 8caca68

3 files changed

Lines changed: 120 additions & 1 deletion

File tree

‎docs/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8711,6 +8711,8 @@ items:
87118711
href: tools/sql-database-projects/concepts/database-references.md
87128712
- name: Package references
87138713
href: tools/sql-database-projects/concepts/package-references.md
8714+
- name: Project references
8715+
href: tools/sql-database-projects/concepts/project-references.md
87148716
- name: Pre/post deployment scripts
87158717
href: tools/sql-database-projects/concepts/pre-post-deployment-scripts.md
87168718
- name: Schema comparison

‎docs/tools/sql-database-projects/concepts/project-references.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
title: Project References Overview
3+
description: Learn about dependencies between SQL projects and other projects, including database references and .NET project references.
4+
author: dzsquared
5+
ms.author: drskwier
6+
ms.reviewer: maghan, randolphwest
7+
ms.date: 01/21/2026
8+
ms.service: sql
9+
ms.subservice: sql-database-projects
10+
ms.topic: concept-article
11+
ai-usage: ai-assisted
12+
---
13+
14+
# Project references overview
15+
16+
[!INCLUDE [SQL Server Azure SQL Database Azure SQL Managed Instance FabricSQLDB](../../../includes/applies-to-version/sql-asdb-asdbmi-fabricsqldb.md)]
17+
18+
With project references in SQL database projects, you can create dependencies between your SQL project and other projects. There are two primary types of project references:
19+
20+
- **Database references** - Dependencies between SQL projects or references to `.dacpac` files and NuGet packages that provide database object definitions.
21+
- **.NET project references** - References from .NET projects to SQL projects for scenarios like integration testing, deployment automation, and code generation.
22+
23+
When you understand when and how to use each type of reference, you can structure your database development workflow effectively.
24+
25+
## Database references
26+
27+
Database references allow a SQL project to incorporate objects from another SQL project, a `.dacpac` file, or a published NuGet package. These references are used when your database objects depend on objects defined elsewhere, such as tables in a shared schema or system database objects.
28+
29+
A basic database reference to another SQL project in the same solution looks like this:
30+
31+
```xml
32+
<ItemGroup>
33+
<ProjectReference Include="..\Database1\Database1.sqlproj" />
34+
</ItemGroup>
35+
```
36+
37+
Database references support three relationship types:
38+
39+
- **Same database** - Objects from the referenced project become part of the same database model.
40+
- **Different database, same server** - Reference objects using three-part naming with a SQLCMD variable for the database name.
41+
- **Different database, different server** - Reference objects using four-part naming with SQLCMD variables for both server and database names.
42+
43+
For detailed information about configuring database references, including examples for each relationship type and guidance on building and publishing projects with references, see [Database references overview](database-references.md).
44+
45+
## .NET project references
46+
47+
.NET projects can reference SQL projects to integrate database development with application code. This reference type is useful when your .NET application needs access to the SQL project's build output (the `.dacpac` file) for testing, deployment, or code generation purposes.
48+
49+
### Use cases
50+
51+
Common scenarios for referencing a SQL project from a .NET project include:
52+
53+
- **Integration tests** - Test projects that deploy the database schema to a test container or local instance before running tests.
54+
- **Deployment automation** - Console applications or tools that programmatically deploy the `.dacpac` to target environments.
55+
- **Model code generation** - Applications that generate code based on the database schema defined in the SQL project.
56+
57+
### Configure the project reference
58+
59+
When you add a project reference from a .NET project to a SQL project, you must include the `ReferenceOutputAssembly="false"` attribute. This attribute tells the .NET build process to treat the SQL project as a build dependency without attempting to reference it as a .NET assembly.
60+
61+
```xml
62+
<ItemGroup>
63+
<ProjectReference Include="..\Database1\Database1.sqlproj" ReferenceOutputAssembly="false" />
64+
</ItemGroup>
65+
```
66+
67+
The `ReferenceOutputAssembly="false"` setting is required because SQL projects produce a `.dacpac` file as their primary output, not a .NET assembly. Without this attribute, the .NET build process attempts to load the `.dacpac` as an assembly and fails with an error similar to:
68+
69+
```output
70+
error CS0009: Metadata file 'Database1.dacpac' could not be opened -- Unknown file format.
71+
```
72+
73+
### Access the DACPAC in your .NET project
74+
75+
After you configure the project reference, the SQL project builds before your .NET project. The `.dacpac` file is available in the SQL project's output directory (typically `bin/Debug` or `bin/Release`).
76+
77+
To access the `.dacpac` programmatically in your .NET code, reference the file path relative to your project structure. For example, in an integration test that uses Testcontainers to create a SQL Server instance:
78+
79+
```csharp
80+
// Path to the dacpac file built by the referenced SQL project
81+
var dacpacPath = Path.Combine(
82+
Directory.GetCurrentDirectory(),
83+
"..", "..", "..", "..",
84+
"Database1", "bin", "Debug",
85+
"Database1.dacpac");
86+
87+
// Use DacFx to deploy the dacpac to your test database
88+
var dacServices = new DacServices(connectionString);
89+
using var dacpac = DacPackage.Load(dacpacPath);
90+
dacServices.Deploy(dacpac, "TestDatabase");
91+
```
92+
93+
### Copy the dacpac to the output directory
94+
95+
For easier access to the `.dacpac` file, configure your .NET project to copy it to the output directory during build. Add the following configuration to your `.csproj` file:
96+
97+
```xml
98+
<ItemGroup>
99+
<None Include="..\Database1\bin\$(Configuration)\Database1.dacpac"
100+
CopyToOutputDirectory="PreserveNewest"
101+
Link="Database1.dacpac" />
102+
</ItemGroup>
103+
```
104+
105+
This configuration copies the `.dacpac` file to your .NET project's output directory, so you can reference it using a simpler path:
106+
107+
```csharp
108+
var dacpacPath = Path.Combine(
109+
AppContext.BaseDirectory,
110+
"Database1.dacpac");
111+
```
112+
113+
## Related content
114+
115+
- [Database references overview](database-references.md)
116+
- [SQL projects package references](package-references.md)
117+
- [SQL projects system objects](system-objects.md)

‎docs/tools/sql-database-projects/sql-projects-tools.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ These tools provide a graphical interface for SQL projects, a T-SQL editor, and
4646
| Publish options/properties | Yes | Yes | Yes |
4747
| [Target platform](concepts/target-platform.md) can be updated | Yes | Yes | Yes |
4848
| [SQLCMD variables](concepts/sqlcmd-variables.md) | Yes | Yes | Yes |
49-
| [Project references](concepts/database-references.md) | Yes | Yes | Yes |
49+
| [Project references](concepts/project-references.md) | Yes | Yes | Yes |
5050
| [Dacpac references](concepts/database-references.md) | Yes | Yes | Yes |
5151
| [Package references](concepts/package-references.md) | Yes | No | No |
5252
| Publish profile creation | Yes | Yes | Yes |

0 commit comments

Comments
 (0)