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.

Observação

As referências de projeto e as referências do pacote NuGet são os métodos recomendados para referências de banco de dados em novos desenvolvimentos. Não há suporte para a referência a pacotes NuGet em projetos SQL originais.

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

Para adicionar uma referência de projeto a um projeto SQL no Visual Studio, clique com o botão direito do mouse no nó Referências no projeto no Gerenciador de Soluções e selecione Adicionar Referência de Banco de Dados.

A caixa de diálogo Adicionar Referência de Banco de Dados apresenta opções para adicionar uma referência a:

• um projeto SQL da mesma solução
• um banco de dados do sistema (de arquivos .dacpac incluídos automaticamente no Visual Studio)
• Qualquer arquivo de aplicativo da camada de dados (.dacpac) no sistema de arquivos local

A caixa de diálogo também fornece uma lista suspensa para selecionar entre os seguintes locais de referência:

• mesmo banco de dados
• banco de dados diferente, mesmo servidor
• banco de dados diferente, servidor diferente

Para adicionar uma referência de projeto a um projeto SQL, adicione um item <ItemGroup> ao arquivo .sqlproj com um item de referência apropriado para cada referência de banco de dados. Por exemplo, a seguinte referência de projeto é adicionada a um projeto SQL para fazer referência ao projeto WorldWideImporters em um banco de dados diferente em um servidor diferente:

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

A referência do projeto é usada em uma definição de exibição de exemplo no projeto SQL:

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

Para adicionar uma referência de banco de dados a um projeto SQL na extensão Projetos do Banco de Dados SQL, clique com o botão direito do mouse no nó Referências de Banco de Dados no projeto na exibição Projetos de Banco de Dados e selecione Adicionar Referência de Banco de Dados.

Os tipos de referência disponíveis são:

• bancos de dados do sistema
• aplicativo da camada de dados (.dacpac)
• aplicativo da camada de dados publicado (.nupkg)
• project

A extensão também solicita a seleção dos seguintes locais de referência:

• mesmo banco de dados
• banco de dados diferente, mesmo servidor
• banco de dados diferente, servidor diferente

Para adicionar uma referência de projeto a um projeto SQL, adicione um item <ItemGroup> ao arquivo .sqlproj com um item de referência apropriado para cada referência de banco de dados. Por exemplo, a seguinte referência de projeto é adicionada a um projeto SQL para fazer referência ao projeto WorldWideImporters em um banco de dados diferente em um servidor diferente:

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

A referência do projeto é usada em uma definição de exibição de exemplo no projeto SQL:

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