Visão geral das referências de banco de dados

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Banco de Dados SQL no Microsoft Fabric

As referências de banco de dados em projetos SQL permitem que você incorpore objetos que não estão incluídos em um projeto vinculando-se a outro projeto, arquivo .dacpac ou pacote NuGet publicado. Os objetos de banco de dados adicionados a um projeto podem fazer parte do mesmo banco de dados, de um banco de dados diferente no mesmo servidor ou de um banco de dados diferente em um servidor diferente. Para o desenvolvimento do SQL Server, as referências de banco de dados podem ser usadas para vincular a outro banco de dados no mesmo servidor para nomenclatura de três partes ou para vincular a um banco de dados diferente em um servidor diferente para consultas entre bancos de dados. Para bancos de dados com um número grande de objetos em grupos distintos, as referências de banco de dados podem ser usadas para dividir um banco de dados em projetos menores e mais gerenciáveis. O tamanho menor do projeto pode ajudar a melhorar o desempenho e reduzir o tempo necessário para criar um projeto durante o desenvolvimento local iterativo.

Exemplo e sintaxe do arquivo de projeto SQL

As referências de banco de dados são incluídas em um projeto por meio de entradas no arquivo .sqlproj, semelhantes aos projetos C#. Quando uma referência de banco de dados é para um banco de dados diferente no mesmo servidor, um elemento <DatabaseSqlCmdVariable> é incluído na referência do projeto. Quando uma referência de banco de dados é para um banco de dados diferente em um servidor diferente, um elemento <ServerSqlCmdVariable> também é incluído na referência do projeto. As referências de banco de dados para o mesmo banco de dados não incluem elementos <ServerSqlCmdVariable> ou <DatabaseSqlCmdVariable>.

A inclusão de uma referência específica à referência de banco de dados nos scripts SQL usa variáveis SQLCMD nomeadas no arquivo de projeto para especificar o nome do banco de dados. Por exemplo, o seguinte script SQL faz referência a uma tabela no banco de dados Warehouse:

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

Uma referência de banco de dados correspondente à variável SQLCMD $(Warehouse) é incluída no arquivo de projeto e contém <DatabaseSqlCmdVariable>Warehouse</DatabaseSqlCmdVariable>.

Referências do projeto

Neste exemplo, uma referência de projeto é adicionada a um projeto SQL AdventureWorksSalesLT.sqlproj que faz parte do mesmo banco de dados.

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

Referências do pacote dacpac

Mais informações sobre referências de pacote em projetos SQL podem ser encontradas no artigo Referências de pacote de projetos SQL.

Uma referência de pacote para o banco de dados do sistema master para SQL 2022 é mostrada no exemplo a seguir:

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

Referências de artefatos dacpac

As referências a um arquivo de artefato .dacpac diretamente não são recomendadas para novos desenvolvimentos em projetos no estilo SDK. Em vez disso, use referências de pacote NuGet.

Em projetos SQL originais, as referências de arquivo .dacpac são especificadas no arquivo .sqlproj com um item <ArtifactReference>. O exemplo a seguir mostra uma referência de artefato .dacpac a um arquivo .dacpacem um projeto diferente no mesmo 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>

Adicionar e usar referências de projeto

Adicionar uma referência ao projeto

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

Criar com referências de projeto

A criação de um projeto SQL com referências de banco de dados pode exigir configuração extra para garantir que os objetos referenciados estejam disponíveis durante o processo de compilação. Por exemplo, se um projeto estiver sendo criado em um pipeline de CI (integração contínua), o ambiente do agente de build precisará ser configurado de forma semelhante ao ambiente de desenvolvimento local.

• As referências .dacpac no projeto SQL exigem que o .dacpac esteja presente no agente de build no mesmo caminho de arquivo relativo especificado no arquivo de projeto.
• As referências de projeto no projeto SQL exigem que o projeto referenciado esteja presente no agente de build no mesmo caminho de arquivo relativo especificado no arquivo de projeto e seja capaz de criar com êxito no agente de build.
• as referências de banco de dados do sistema criadas em projetos SQL originais no Visual Studio exigem que o agente de build tenha o Visual Studio instalado.
• As referências de pacote NuGet no projeto SQL exigem que o pacote seja publicado em um feed NuGet que também seja definido como uma fonte de pacote para o agente de build.

Publicar com referências de projeto

A publicação de um projeto .dacpac com referências de banco de dados não requer etapas extras. O arquivo .dacpac contém os objetos referenciados e as variáveis SQLCMD especificadas no arquivo de projeto.

Para referências de banco de dados a objetos no mesmo banco de dados, os objetos do projeto referenciado são incluídos no arquivo .dacpac, mas não são incluídos na implantação por padrão. Para incluir os objetos na implantação, use a opção /p:IncludeCompositeObjects=true na ferramenta de linha de comando SqlPackage. Por exemplo, o comando a seguir implanta o projeto AdventureWorks com a opção /p:IncludeCompositeObjects=true para incluir os objetos de referências de banco de dados no AdventureWorks:

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

Quando você implanta um arquivo .dacpac com referências de banco de dados em um banco de dados diferente (no mesmo servidor ou em um servidor diferente), as variáveis SQLCMD especificadas no arquivo de projeto devem ser definidas com os valores corretos para o ambiente de destino. A definição dos valores da variável SQLCMD durante a implantação é feita com a opção /v na ferramenta de linha de comando SqlPackage. Por exemplo, o comando a seguir define a variável WorldWideImporters como WorldWideImporters e a variável WWIServer como localhost:

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

Conteúdo relacionado

• Visão geral das referências de pacotes de projetos SQL
• Visão geral das variáveis SQLCMD