数据库引用概述

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

SQL 项目中的数据库引用使你能够通过链接到另一个项目、.dacpac 文件或已发布的 NuGet 包来合并项目中未包含的对象。 添加到项目的数据库对象可以是同一数据库的一部分、同一服务器上的不同数据库或不同服务器上的不同数据库。 对于SQL Server开发，请使用数据库引用链接到同一服务器上的另一个数据库进行三部分命名，或链接到不同服务器上的不同数据库进行跨数据库查询。 对于具有不同组中大量对象的数据库，请使用数据库引用将数据库分解为更小、更易于管理的项目。 较小的项目大小有助于提高性能，并减少在迭代本地开发期间生成项目所需的时间。

SQL 项目文件示例和语法

通过文件中的条目 .sqlproj 在项目中包括数据库引用，类似于 C# 项目。 使用 SQLCMD 语法引用 SQL 项目对象中的数据库名称。 当数据库引用指向同一服务器上的其他数据库时，请在项目引用中包含一个 <DatabaseSqlCmdVariable> 元素。 当数据库引用指向另一台服务器上的其他数据库时，还应在项目引用中包含一个 <ServerSqlCmdVariable> 元素。 对同一数据库的数据库引用不包括 <ServerSqlCmdVariable> 或 <DatabaseSqlCmdVariable> 元素。

若要在 SQL 脚本中包含对数据库引用的特定引用，请使用项目文件中命名的 SQLCMD 变量来指定数据库名称。 例如，以下 SQL 脚本引用 Warehouse 数据库中的表：

SELECT ProductId,
       StorageLocation,
       BinNumber
FROM [$(Warehouse)].[Production].[ProductInventory];

项目文件包含与 $(Warehouse) SQLCMD 变量对应的数据库引用，并包含 <DatabaseSqlCmdVariable>Warehouse</DatabaseSqlCmdVariable>。

同一数据库中的三部分命名方式

当 SQL 项目中的某个对象引用同一数据库中的另一个对象时，即使这些对象是通过数据库引用纳入的，也无需使用三部分命名。 但是，SQL 项目包含数据库名称的自动 SQLCMD 变量，可以在 SQL 脚本中使用该变量来引用项目的数据库，而无需硬编码名称。 如果需要三部分命名，请在 $(DatabaseName) SQL 脚本中使用以引用数据库。 例如，以下 SQL 脚本引用项目数据库中的表：

UPDATE [$(DatabaseName)].[SalesLT].[Customer]
SET [SalesPerson] = 'John Doe',
    [ModifiedDate] = GETDATE()
WHERE [CustomerId] = @CustomerId;

数据库文本值

在某些情况下，可能需要对 SQL 对象中的数据库引用中的数据库名称使用文本（非变量）值。 可以将 .sqlproj 文件配置为为数据库名称指定文本值，而不是使用 SQLCMD 变量。 用于指定文本值的元素为 <DatabaseLiteralValue>。 如果使用此元素，请不要使用该 <DatabaseSqlCmdVariable> 元素。 在 <DatabaseLiteralValue> 元素中，指定数据库名称的字面值。 例如，在 SQL 脚本中使用数据库引用 <DatabaseVariableLiteralValue>WarehouseDB</DatabaseVariableLiteralValue> ，如下所示：

SELECT ProductId,
       StorageLocation,
       BinNumber
FROM [WarehouseDB].[Production].[ProductInventory];

项目参考

在此示例中，向同一数据库中的名为 AdventureWorksSalesLT.sqlproj 的 SQL 项目添加项目引用。

  <ItemGroup>
    <ProjectReference Include="..\AdventureWorks\AdventureWorksSalesLT.sqlproj">
      <Name>AdventureWorksSalesLT</Name>
      <Project>{d703fc7a-bc47-4aef-9dc5-cf01094ddb37}</Project>
      <Private>True</Private>
      <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
    </ProjectReference>
  </ItemGroup>

Dacpac 包引用

有关 SQL 项目中的包引用的详细信息，请参阅 SQL 项目包引用。

以下示例展示了对 SQL Server 2022 的 master系统数据库的包引用：

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

Dacpac 项目引用

在 SDK 样式项目中进行新开发时，不要直接引用 .dacpac 工件文件。 请改用 NuGet 包引用。

在原始 SQL 项目中，可通过使用 <ArtifactReference> 项在 .sqlproj 文件中指定 .dacpac 文件引用。 以下示例展示了对同一服务器上不同项目中 .dacpac 文件的 .dacpac 项目引用：

  <ItemGroup>
    <ArtifactReference Include="..\AdventureWorks\Warehouse\bin\Release\Warehouse.dacpac">
      <HintPath>..\AdventureWorks\Warehouse\bin\Release\Warehouse.dacpac</HintPath>
      <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
      <DatabaseSqlCmdVariable>Warehouse</DatabaseSqlCmdVariable>
    </ArtifactReference>
  </ItemGroup>

添加和使用项目引用

添加项目引用

  <ItemGroup>
    <ProjectReference Include="..\Contoso\WorldWideImporters.sqlproj">
      <Name>WorldWideImporters</Name>
      <Project>{d703fc7a-bc47-4aef-9dc5-cf01094ddb37}</Project>
      <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
      <ServerSqlCmdVariable>WWIServer</ServerSqlCmdVariable>
      <DatabaseSqlCmdVariable>WorldWideImporters</DatabaseSqlCmdVariable>
    </ProjectReference>
  </ItemGroup>

CREATE VIEW dbo.WorldWide_Products
AS
SELECT ProductID, ProductName, SupplierID
FROM [$(WWIServer)].[$(WorldWideImporters)].[Purchasing].[Suppliers]

  <ItemGroup>
    <ProjectReference Include="..\Contoso\WorldWideImporters.sqlproj">
      <Name>WorldWideImporters</Name>
      <Project>{d703fc7a-bc47-4aef-9dc5-cf01094ddb37}</Project>
      <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
      <ServerSqlCmdVariable>WWIServer</ServerSqlCmdVariable>
      <DatabaseSqlCmdVariable>WorldWideImporters</DatabaseSqlCmdVariable>
    </ProjectReference>
  </ItemGroup>

CREATE VIEW dbo.WorldWide_Products
AS
SELECT ProductID, ProductName, SupplierID
FROM [$(WWIServer)].[$(WorldWideImporters)].[Purchasing].[Suppliers]

  <ItemGroup>
    <ProjectReference Include="..\Contoso\WorldWideImporters.sqlproj">
      <Name>WorldWideImporters</Name>
      <Project>{d703fc7a-bc47-4aef-9dc5-cf01094ddb37}</Project>
      <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
      <ServerSqlCmdVariable>WWIServer</ServerSqlCmdVariable>
      <DatabaseSqlCmdVariable>WorldWideImporters</DatabaseSqlCmdVariable>
    </ProjectReference>
  </ItemGroup>

CREATE VIEW dbo.WorldWide_Products
AS
SELECT ProductID, ProductName, SupplierID
FROM [$(WWIServer)].[$(WorldWideImporters)].[Purchasing].[Suppliers]

使用项目引用进行构建

使用数据库引用生成 SQL 项目可能需要额外的配置，以确保引用的对象在生成过程中可用。 例如，如果要在持续集成（CI）管道中生成项目，则需要设置类似于本地开发环境的生成代理环境。

• SQL 项目中的 .dacpac 引用要求 .dacpac 在生成代理上的位置与项目文件中指定的相对文件路径相同。
• SQL 项目中的项目引用要求被引用的项目存在于生成代理上，并且其相对文件路径与项目文件中指定的相对路径一致，同时还必须能够在生成代理上成功生成。
• 在 Visual Studio 中的原始 SQL 项目里创建的系统数据库引用要求生成代理上已安装 Visual Studio。
• SQL 项目中的 NuGet 包引用要求将包发布到 NuGet 源，该源也被设置为构建代理的包源。

使用项目引用进行发布

发布从带有数据库引用的项目构建的 .dacpac 时，无需额外步骤。 .dacpac 文件包含引用的对象和项目文件中指定的 SQLCMD 变量。

对于对同一数据库中的对象的数据库引用，引用的项目中的对象包含在 .dacpac 文件中，但默认情况下不包括在部署中。 若要在部署中包含对象，请使用 SqlPackage 命令行工具中的 /p:IncludeCompositeObjects=true 选项。 例如，以下命令使用 AdventureWorks 选项部署 /p:IncludeCompositeObjects=true 项目，以包含对 AdventureWorks 的数据库引用中的对象：

sqlpackage /Action:Publish /SourceFile:AdventureWorks.dacpac /TargetConnectionString:{connection_string_here} /p:IncludeCompositeObjects=true

当您部署包含对其他数据库的引用的 .dacpac 文件时（这些数据库位于同一服务器或不同服务器上），请将项目文件中指定的 SQLCMD 变量设置为目标环境的正确值。 使用 /vSqlPackage 命令行工具中的选项在部署过程中设置 SQLCMD 变量值。 例如，以下命令将 WorldWideImporters 变量设置为 WorldWideImporters 并将 WWIServer 变量设置为 localhost：

sqlpackage /Action:Publish /SourceFile:AdventureWorks.dacpac /TargetConnectionString:{connection_string_here} /v:WorldWideImporters=WorldWideImporters /v:WWIServer=localhost

相关内容

• SQL 项目包引用
• SQL 项目系统对象
• SQLCMD 变量概述