SQL 项目包引用

2025-04-23

适用于：SQL ServerAzure SQL 数据库Azure SQL 托管实例Microsoft Fabric SQL 数据库

SQL 项目中的包引用使你可以从其他项目或 NuGet 包中引用数据库对象。通过包引用添加到项目的数据库对象可以是同一数据库的一部分、同一服务器上的不同数据库或者不同服务器上的不同数据库。

注意

包引用是新开发中引用数据库对象的建议方法。仅 SDK 样式 SQL 项目中支持引用 NuGet 包。

数据库对象包引用

包引用是将数据库对象作为数据库引用添加到 SQL 项目的几个方法之一。包引用可以包含同一数据库的对象、同一服务器上的不同数据库或者不同服务器上的不同数据库。包引用可用于将数据库分解为更小、更易于管理的项目，这有助于缩短在迭代本地开发期间生成项目所需的时间。

SQL 项目文件示例和语法

包引用通过 .sqlproj 文件中的条目添加到 SQL 项目中，类似于 C# 项目。当包引用指向同一服务器上的不同数据库时，包引用中包含一个 <DatabaseSqlCmdVariable> 元素。当包引用指向不同服务器上的不同数据库时，包引用中也包含一个 <ServerSqlCmdVariable> 元素。对同一数据库的包引用不包括 <ServerSqlCmdVariable> 或 <DatabaseSqlCmdVariable> 元素。

以下示例包含对 Contoso.AdventureWorks.SalesLT 包的包引用，作为同一数据库的数据库引用，其中包中的对象成为 SQL 项目中数据库模型的一部分：

...
  <ItemGroup>
    <PackageReference Include="Contoso.AdventureWorks.SalesLT" Version="1.1.0" />
  </ItemGroup>
</Project>

以下示例包括对 Contoso.AdventureWorks 包的包引用作为同一服务器上其他数据库 (AdventureWorks) 的数据库应用，其中包中的对象成为 SQL 项目中数据库模型的一部分。

...
  <ItemGroup>
    <PackageReference Include="Contoso.AdventureWorks" Version="1.1.0">
      <DatabaseSqlCmdVariable>AdventureDB</DatabaseSqlCmdVariable>
      <DacpacName>AdventureWorks</DacpacName>
    </PackageReference>
  </ItemGroup>
  <ItemGroup>
    <SqlCmdVariable Include="AdventureDB">
      <DefaultValue>AdventureWorks</DefaultValue>
      <Value>$(SqlCmdVar__1)</Value>
    </SqlCmdVariable>
  </ItemGroup>
</Project>

在此示例中，AdventureWorks .dacpac 文件作为包 Contoso.AdventureWorks 版本 1.1.0 发布到 NuGet 源。该 <DatabaseSqlCmdVariable> 元素指定包中对象所在的同一服务器上数据库的名称，并将用于在三部分命名中指示此引用。 SQLCMD 变量AdventureDB用于在部署时设置数据库名称，并在项目中与此示例查询类似：

SELECT * FROM [$(AdventureDB)].dbo.Customers;

该 <DacpacName> 元素指定包引用的文件的名称 .dacpac ，而不指定文件扩展名或路径。该 <DacpacName> 元素是可选的，仅在文件的名称 .dacpac 与包的名称不同时才是必需的。

系统数据库

SQL 系统数据库（master、msdb）发布在 NuGet.org 上作为数据库引用包。这些包中包含系统数据库的架构，可用作 SQL 项目中的包引用。系统会对系统数据库包进行版本控制，使其与它们关联的 SQL Server 版本保持一致。例如，SQL Server 2022 的 master 系统数据库包为 Microsoft.SqlServer.Dacpacs.Master 版本 160.2.1，可以作为包引用添加到 SQL 项目：

...
  <ItemGroup>
    <PackageReference Include="Microsoft.SqlServer.Dacpacs.Master" Version="160.2.1" />
  </ItemGroup>
</Project>

次要版本更改反映了缺陷修复和 SQL Server 版本中架构的次要更改。

可用的系统数据库包为：

打包 dacpac NuGet 包

数据库引用包是包含 .dacpac 文件的 NuGet 包。 NuGet 包可以发布到 NuGet 源（例如 Azure Artifacts），以便在 SQL 项目中使用。创建此包的过程与为其他类型的项目创建 NuGet 包的过程相同。有关详细信息，请参阅使用 dotnet CLI 创建包。

若要将 .sqlproj 文件打包为 NuGet 包，请使用命令行中的 dotnet pack 命令。默认情况下，dotnet pack 命令从 .sqlproj 文件夹中的 bin/Debug 文件创建 NuGet 包。

可通过 <PropertyGroup> 文件中的 .sqlproj 元素内的属性指定包元数据。例如，以下属性指定包 ID、版本、说明、作者和公司：

<PackageId>Contoso.AdventureWorks.SalesLT</PackageId>
<Version>1.0.0</Version>
<Description>AdventureWorks database SalesLT objects</Description>
<Authors>DevTeam</Authors>
<Company>Contoso Outdoors</Company>

dotnet pack 命令创建的 .nupkg 文件可以发布到 NuGet 源，以便在 SQL 项目中使用。这些数据库对象可由有权访问包的任何人查看，因此应考虑选择公共或专用源位置。有关详细信息，请参阅使用专用包源进行托管。

引用包时，如果包中的 PackageId 不同于 .dacpac 文件的名称，则在使用包时需要在包引用中包含 <DacpacName> 元素。

扩展代码分析规则包引用

包引用还可用于引用作为代码分析扩展性一部分开发的更多代码分析规则。代码分析规则包的包引用类似于数据库对象包的包引用。以下示例演示对自定义代码分析规则包的包引用：

<ItemGroup>
  <PackageReference Include="Your.CustomCode.AnalysisRules" Version="1.2.3" />
</ItemGroup>

所引用的包应在 NuGet 源上可用，例如 NuGet.org、Azure Artifacts 或本地源。引用包含代码分析规则的包时，规则将自动包含在 SQL 项目中，并在项目属性 RunSqlCodeAnalysis 设置为 true 时进行评估。可以禁用或提升规则，以在项目属性中单独返回错误。

通过