Compartir a través de

Introducción a las referencias de base de datos

  • Artículo

Se aplica a: SQL Server Azure SQL Database Azure SQL Managed Instance Base de datos de Azure SQL de 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 agregados 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 otro servidor. Para el desarrollo de SQL Server, las referencias de base de datos se pueden usar para vincular a otra base de datos del mismo servidor para la nomenclatura de tres partes, o para vincular a una base de datos diferente en otro servidor para consultas entre bases de datos. En el caso de bases de datos con un gran número de objetos en grupos distintos, las referencias de base de datos se pueden usar para dividir una base de datos en proyectos más pequeños y manejables. Un menor tamaño de los proyectos puede ayudar a mejorar el rendimiento y reducir el tiempo necesario para compilar un proyecto durante el desarrollo local iterativo.

Captura de pantalla de un ejemplo de proyecto SQL que hace referencia un dacpac, un paquete NuGet y un proyecto para referencias de base de datos.

Nota:

Las referencias de proyecto y las referencias de paquetes NuGet son los métodos recomendados para las referencias de base de datos en el nuevo desarrollo. Los proyectos SQL originales no admiten la referencia a paquetes NuGet.

Ejemplo y sintaxis del archivo de proyecto SQL

Las referencias de base de datos se incluyen en un proyecto mediante entradas en el archivo .sqlproj, de manera similar a los proyectos en C#. Cuando una referencia de base de datos se realiza a una base de datos diferente del mismo servidor, se incluye un elemento <DatabaseSqlCmdVariable> en la referencia del proyecto. Cuando una referencia de base de datos se realiza a una base de datos diferente de otro servidor, también se incluye un elemento <ServerSqlCmdVariable> en la referencia del proyecto. Las referencias de base de datos a la misma base de datos no incluyen elementos <ServerSqlCmdVariable> ni <DatabaseSqlCmdVariable> .

La inclusión de una referencia específica a la referencia de base de datos en los scripts SQL usa variables SQLCMD con nombre 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]

Una referencia de base de datos correspondiente a la variable SQLCMD $(Warehouse) se incluye en el archivo de proyecto y contiene <DatabaseSqlCmdVariable>Warehouse</DatabaseSqlCmdVariable>.

Referencias de proyecto

En este ejemplo, se agrega una referencia de proyecto a un proyecto SQL 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 paquete dacpac

Encontrará más información sobre las referencias de paquetes en proyectos SQL en el artículo Referencias de paquete de proyectos de SQL.

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

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

Referencias de artefacto dacpac

No se recomienda realizar referencias a un archivo de artefacto .dacpac directamente para nuevo desarrollo en proyectos de estilo SDK. En su lugar, use referencias de paquete NuGet.

En proyectos SQL originales, las referencias de archivo .dacpac se especifican en el archivo .sqlproj con 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

Para agregar una referencia de proyecto a un proyecto SQL en Visual Studio, haga clic con el botón derecho en el nodo Referencias del proyecto en el Explorador de soluciones y seleccione Agregar referencia de base de datos.

Captura de pantalla del cuadro de diálogo de Visual Studio para referencias de base de datos.

El cuadro de diálogo Agregar referencia de base de datos presenta opciones para agregar una referencia a:

  • un proyecto SQL de la misma solución
  • una base de datos del sistema (de archivos .dacpac incluidos automáticamente con Visual Studio)
  • cualquier archivo de aplicación de capa de datos (.dacpac) en el sistema de archivos local

El cuadro de diálogo también proporciona una lista desplegable para seleccionar de entre las siguientes ubicaciones de referencia:

  • misma base de datos
  • base de datos diferente, mismo servidor
  • base de datos diferente, servidor diferente

Para agregar una referencia de proyecto a un proyecto SQL, agregue un elemento <ItemGroup> al archivo .sqlproj con un elemento de referencia adecuado para cada referencia de base de datos. Por ejemplo, la siguiente referencia de proyecto se agrega a un proyecto SQL para hacer referencia al proyecto WorldWideImporters en una base de datos diferente de otro servidor:

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

La referencia del proyecto se usa en una definición de vista de muestra en el proyecto SQL:

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

Para agregar una referencia de base de datos a un proyecto SQL en la extensión Proyectos de base de datos de SQL, haga clic con el botón derecho en el nodo Referencias de base de datos del proyecto en la vista Proyectos de base de datos y seleccione Agregar referencia de base de datos.

Captura de pantalla del cuadro de diálogo Agregar referencia de Azure Data Studio.

Los tipos de referencia disponibles son:

  • base de datos del sistema
  • aplicación de capa de datos (.dacpac)
  • aplicación de capa de datos publicada (.nupkg)
  • proyecto

La extensión también solicita que seleccione de entre las siguientes ubicaciones de referencia:

  • misma base de datos
  • base de datos diferente, mismo servidor
  • base de datos diferente, servidor diferente

Para agregar una referencia de proyecto a un proyecto SQL, agregue un elemento <ItemGroup> al archivo .sqlproj con un elemento de referencia adecuado para cada referencia de base de datos. Por ejemplo, la siguiente referencia de proyecto se agrega a un proyecto SQL para hacer referencia al proyecto WorldWideImporters en una base de datos diferente de otro servidor:

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

La referencia del proyecto se usa en una definición de vista de muestra en el proyecto SQL:

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 un proyecto se está compilando en una canalización de integración continua (CI), el entorno del agente de compilación debe configurarse de forma 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 referenciado esté presente en el agente de compilación en la misma ruta de archivo relativa que se especifica en el archivo del proyecto y sea capaz de compilar 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 archivo .dacpac con referencias de base de datos en una base de datos diferente (en el mismo servidor o en un servidor diferente), las variables SQLCMD especificadas en el archivo de proyecto deben configurarse con los valores correctos para el entorno de destino. La configuración de los valores de las variables SQLCMD durante la implementación se realiza con la opción /v en 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