Introducción a las referencias de base de datos

Se aplica a:SQL ServerAzure SQL DatabaseInstancia administrada de Azure SQLBase de datos SQL en Microsoft Fabric

Las referencias de base de datos en proyectos SQL le permiten incorporar objetos no incluidos en un proyecto mediante la vinculación a otro proyecto, archivo .dacpac o paquete NuGet publicado. Los objetos de base de datos que agregue a un proyecto pueden formar parte de la misma base de datos, una base de datos diferente en el mismo servidor o una base de datos diferente en un servidor diferente. Para el desarrollo de SQL Server, use referencias a bases de datos para vincularse a otra base de datos en el mismo servidor mediante nombres de tres partes, o a una base de datos distinta en otro servidor para realizar consultas entre bases de datos. En el caso de las bases de datos con un gran número de objetos en grupos distintos, use referencias de base de datos para dividir una base de datos en proyectos más pequeños y administrables. El tamaño de proyecto más pequeño puede ayudar a mejorar el rendimiento y reducir el tiempo necesario para compilar un proyecto durante el desarrollo local iterativo.

Ejemplo y sintaxis del archivo de proyecto SQL

Incluya referencias de base de datos en un proyecto a través de entradas en el .sqlproj archivo, similares a los proyectos de C#. Use la sintaxis SQLCMD para hacer referencia al nombre de la base de datos en objetos de proyecto de SQL. Cuando una referencia de base de datos apunta a una base de datos diferente en el mismo servidor, incluya un <DatabaseSqlCmdVariable> elemento en la referencia del proyecto. Cuando una referencia de base de datos apunta a una base de datos diferente en un servidor diferente, incluya también un <ServerSqlCmdVariable> elemento en la referencia del proyecto. Las referencias de base de datos a la misma base de datos no incluyen elementos <ServerSqlCmdVariable> ni <DatabaseSqlCmdVariable> .

Para incluir una referencia específica a la referencia de base de datos en los scripts SQL, use variables SQLCMD denominadas en el archivo de proyecto para especificar el nombre de la base de datos. Por ejemplo, el siguiente script SQL hace referencia a una tabla de la base de datos Warehouse:

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

El archivo de proyecto incluye una referencia de base de datos correspondiente a la $(Warehouse) variable SQLCMD y contiene <DatabaseSqlCmdVariable>Warehouse</DatabaseSqlCmdVariable>.

Nomenclatura de tres partes de la misma base de datos

Cuando un objeto de un proyecto SQL hace referencia a otro objeto de la misma base de datos, la nomenclatura de tres partes no es necesaria aunque los objetos se incluyan a través de una referencia de base de datos. Sin embargo, los proyectos de SQL incorporan una variable SQLCMD automática para el nombre de la base de datos, que puede usar en scripts SQL para hacer referencia a la base de datos del proyecto sin codificar de forma rígida el nombre. Si es necesario asignar nombres de tres partes, use $(DatabaseName) en los scripts SQL para hacer referencia a la base de datos. Por ejemplo, el siguiente script SQL hace referencia a una tabla de la base de datos del proyecto:

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

Valores literales de base de datos

En algunos casos, es posible que tenga que usar un valor literal (no variable) para el nombre de la base de datos de una referencia de base de datos en los objetos SQL. Puede configurar el .sqlproj archivo para especificar un valor literal para un nombre de base de datos en lugar de usar una variable SQLCMD. El elemento usado para especificar un valor literal es <DatabaseLiteralValue>. Si usa este elemento, no use el <DatabaseSqlCmdVariable> elemento . Dentro del <DatabaseLiteralValue> elemento , especifique el valor literal para el nombre de la base de datos. Por ejemplo, una referencia de base de datos con <DatabaseVariableLiteralValue>WarehouseDB</DatabaseVariableLiteralValue> se usa en un script SQL de la siguiente manera:

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

Referencias de proyecto

En este ejemplo, agregará una referencia de proyecto a un proyecto de SQL denominado AdventureWorksSalesLT.sqlproj que forma parte de la misma base de datos.

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

Referencias de paquetes de Dacpac

Para obtener más información sobre las referencias de paquetes en proyectos SQL, vea Referencias de paquetes de proyectos de SQL.

En el ejemplo siguiente se muestra una referencia de paquete a la base de datos del master sistema para SQL Server 2022:

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

Referencias de artefacto de Dacpac

No utilice referencias directas a un archivo de artefacto .dacpac en desarrollos nuevos en proyectos con formato SDK. En su lugar, use referencias de paquete de NuGet.

En los proyectos SQL originales, se especifican las referencias de archivo .dacpac en el archivo .sqlproj mediante un elemento <ArtifactReference>. En el siguiente ejemplo se muestra una referencia de artefacto .dacpac a un archivo .dacpac de un proyecto diferente en el mismo servidor:

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

Adición y uso de referencias de proyecto

Agregar una referencia de proyecto

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

Compilación con referencias de proyecto

La compilación de un proyecto SQL con referencias de base de datos puede requerir una configuración adicional para garantizar que los objetos a los que se hace referencia están disponibles durante el proceso de compilación. Por ejemplo, si va a compilar un proyecto en una canalización de integración continua (CI), debe configurar el entorno del agente de compilación de manera similar al entorno de desarrollo local.

• Las referencias .dacpac en el proyecto SQL requieren que .dacpac esté presente en el agente de compilación en la misma ruta de archivo relativa que se especifica en el archivo del proyecto.
• Las referencias de proyecto en el proyecto SQL requieren que el proyecto al que se hace referencia esté presente en el agente de compilación en la misma ruta de archivo relativa que se especifica en el archivo del proyecto y pueda compilarse correctamente en el agente de compilación.
• Las referencias de base de datos del sistema creadas en proyectos SQL originales en Visual Studio requieren que el agente de compilación tenga instalado Visual Studio.
• Las referencias de paquetes NuGet en el proyecto SQL requieren que el paquete se publique en un feed NuGet que también esté establecido como origen de paquete para el agente de compilación.

Publicación con referencias de proyecto

La publicación de una compilación .dacpac a partir de un proyecto con referencias de base de datos no requiere pasos adicionales. El archivo .dacpac contiene los objetos a los que se hace referencia y las variables SQLCMD especificadas en el archivo de proyecto.

Para las referencias de base de datos a objetos de la misma base de datos, los objetos del proyecto al que se hace referencia se incluyen en el archivo .dacpac, pero no se incluyen en la implementación de manera predeterminada. Para incluir los objetos en la implementación, use la opción /p:IncludeCompositeObjects=true en la herramienta de línea de comandos SqlPackage. Por ejemplo, el siguiente comando implementa el proyecto AdventureWorks con la opción /p:IncludeCompositeObjects=true para incluir los objetos de las referencias de base de datos a AdventureWorks:

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

Al implementar un .dacpac archivo con referencias de base de datos a una base de datos diferente (en el mismo servidor o en un servidor diferente), establezca las variables SQLCMD especificadas en el archivo de proyecto en los valores correctos para el entorno de destino. Establezca los valores de las variables SQLCMD durante la implementación mediante la /v opción de la herramienta de línea de comandos SqlPackage . Por ejemplo, el siguiente comando configura la variable WorldWideImporters con el valor WorldWideImporters y la variable WWIServer con el valor localhost:

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

Contenido relacionado

• Referencias de paquetes de proyectos SQL
• Objetos del sistema de proyectos SQL
• Introducción a las variables SQLCMD