Converter um projeto SQL original em um projeto no estilo SDK

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

Criar um novo projeto SQL no estilo SDK é uma tarefa rápida. No entanto, se você tiver projetos SQL existentes, poderá convertê-los em projetos SQL no estilo SDK para aproveitar os novos recursos.

Depois de converter o projeto, você pode usar os novos recursos do projeto no estilo SDK, como:

suporte de compilação multiplataforma
formato de arquivo de projeto simplificado
referências de pacote

Para concluir a conversão com cuidado, iremos:

Criar um backup do arquivo de projeto original.
Criar um arquivo .dacpac do projeto original para comparação.
Modificar o arquivo de projeto para um projeto no estilo do SDK.
Criar um arquivo .dacpac do projeto modificado para comparação.
Verifique se os arquivos .dacpac são os mesmos.

Não há suporte para projetos no estilo SDK no SSDT (SQL Server Data Tools) no Visual Studio. Depois de convertido, você deve usar um dos seguintes para criar ou editar o projeto:

a linha de comando
a extensão de Projetos de Banco de Dados SQL no Visual Studio Code
a extensão de Projetos de Banco de Dados SQL no Azure Data Studio
as Ferramentas de Dados do SQL Server, estilo SDK (versão prévia) no Visual Studio 2022

Note

Você pode descobrir que seu projeto SQL contém personalização que estende as alterações necessárias além dessas etapas. Além deste artigo, o repositório GitHub do DacFx pode ser usado para entender as alterações necessárias para atualizar de um projeto SQL original para projetos SQL no estilo SDK.

Prerequisites

SDK DO .NET 8

Etapa 1: criar um backup do arquivo de projeto original

Antes de converter o projeto, crie um backup do arquivo de projeto original. Dessa forma, você pode reverter para o projeto original, se necessário.

No explorador de arquivos, crie uma cópia do arquivo .sqlproj para o projeto que você deseja converter com .original anexado ao final da extensão do arquivo. Por exemplo, MyProject.sqlproj se tornará MyProject.sqlproj.original.

Etapa 2: criar um arquivo `.dacpac` do projeto original para comparação

Abra o projeto no Visual Studio 2022. O arquivo .sqlproj ainda está no formato original, portanto, você o abre no SQL Server Data Tools original.

Compile o projeto no Visual Studio clicando com o botão direito do mouse no nó do banco de dados no Gerenciador de Soluções e selecionando Compilar.

Para criar um arquivo .dacpac a partir do projeto original, você deve usar o SQL Server Data Tools (SSDT) original no Visual Studio. Abra o arquivo de projeto no Visual Studio 2022 com o SQL Server Data Tools original instalado.

Compile o projeto no Visual Studio clicando com o botão direito do mouse no nó do banco de dados no Gerenciador de Soluções e selecionando Compilar.

Abra a pasta do projeto no VS Code ou no Azure Data Studio. Na exibição Projetos de Banco de Dados do VS Code ou do Azure Data Studio, clique com o botão direito do mouse no nó do projeto e selecione Compilar.

Os projetos de banco de dados SQL podem ser criados a partir da linha de comando usando o comando dotnet build.

dotnet build

# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj

O processo de compilação cria um arquivo .dacpac na pasta bin\Debug do projeto por padrão. Usando o explorador de arquivos, localize o .dacpac criado pelo processo de build e copie-o para uma nova pasta fora do diretório do projeto como original_project.dacpac. Usamos esse arquivo .dacpac para comparação para validar nossa conversão posteriormente.

Etapa 3: modificar o arquivo de projeto para um projeto no estilo do SDK

Modificar o arquivo de projeto é um processo manual, melhor executado em um editor de texto. Abra o arquivo .sqlproj no um editor de texto e faça as seguintes alterações:

Obrigatório: adicionar a referência do SDK

Dentro do elemento de projeto, adicione um item Sdk para referenciar Microsoft.Build.Sql e a versão mais recente do https://www.nuget.org/packages/Microsoft.build.sql em que #.#.# está incluído no snippet abaixo.

<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build" ToolsVersion="4.0">
  <Sdk Name="Microsoft.Build.Sql" Version="#.#.#" />
...

Obrigatório: remover importações de destino de build desnecessárias

Os projetos SQL originais fazem referência a vários alvos e propriedades de compilação em declarações de Import. Exceto para itens <Import/> que você adicionou explicitamente, que é uma mudança única e deliberada, remova as linhas que começam com <Import ...>. Exemplos a serem removidos se presentes em seu .sqlproj:

...
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
<Import Condition="..." Project="...\Microsoft.Data.Tools.Schema.SqlTasks.targets"/>
<Import Condition="'$(SQLDBExtensionsRefPath)' != ''" Project="$(SQLDBExtensionsRefPath)\Microsoft.Data.Tools.Schema.SqlTasks.targets" />
<Import Condition="'$(SQLDBExtensionsRefPath)' == ''" Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\SSDT\Microsoft.Data.Tools.Schema.SqlTasks.targets" />
...

Obrigatório: remover pasta Propriedades

Os projetos SQL originais têm uma entrada para uma pasta Properties que representava o acesso às propriedades do projeto no gerenciador de soluções. Este item precisa ser removido do arquivo de projeto.

Exemplo para remover se estiver presente em seu .sqlproj:

<ItemGroup>
  <Folder Include="Properties" />
</ItemGroup>

Obrigatório: Remova itens de build incluídos por padrão

Projetos SQL originais listam todos os arquivos .sql que representam objetos de banco de dados explicitamente no arquivo de projeto como itens <Build Include="..." />. Em projetos SQL no estilo SDK, todos os arquivos .sql na árvore de pastas do projeto (**/*.sql) são incluídos por padrão, portanto, a remoção dos itens de <Build Include="...." /> para esses arquivos é necessária para evitar problemas de desempenho de build.

Linhas que devem ser removidas do arquivo de projeto, por exemplo:

  <Build Include="SalesLT/Products.sql" />
  <Build Include="SalesLT/SalesLT.sql" />
  <Build Include="SalesLT/Categories.sql" />
  <Build Include="SalesLT/CategoriesProductCount.sql" />

Você não deve remover os itens <PreDeploy Include="..." /> ou <PostDeploy Include="..." />, pois esses nós determinam o comportamento específico para esses arquivos. Você também não deve remover itens <Build Include="..." /> para arquivos que não estão na árvore de pastas do projeto SQL.

Opcional: remover referências do SSDT

O SSDT (SQL Server Data Tools) original exigia conteúdo extra no arquivo de projeto para detectar a instalação do Visual Studio. Essas linhas são desnecessárias em projetos SQL no estilo SDK e podem ser removidas:

  <PropertyGroup>
    <VisualStudioVersion Condition="'$(VisualStudioVersion)' == ''">11.0</VisualStudioVersion>
    <!-- Default to the v11.0 targets path if the targets file for the current VS version is not found -->
    <SSDTExists Condition="Exists('$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\SSDT\Microsoft.Data.Tools.Schema.SqlTasks.targets')">True</SSDTExists>
    <VisualStudioVersion Condition="'$(SSDTExists)' == ''">11.0</VisualStudioVersion>
  </PropertyGroup>

Opcional: remover configurações de build padrão

Os projetos SQL originais incluem dois blocos grandes para as configurações de Compilação de Release e Compilação de Debug, enquanto, nos projetos SQL no estilo SDK, os padrões para essas opções são conhecidos pelo SDK. Se você não tiver personalizações nas configurações de build, considere remover estes blocos:

  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <OutputPath>bin\Release\</OutputPath>
    <BuildScriptName>$(MSBuildProjectName).sql</BuildScriptName>
    <TreatWarningsAsErrors>False</TreatWarningsAsErrors>
    <DebugType>pdbonly</DebugType>
    <Optimize>true</Optimize>
    <DefineDebug>false</DefineDebug>
    <DefineTrace>true</DefineTrace>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <OutputPath>bin\Debug\</OutputPath>
    <BuildScriptName>$(MSBuildProjectName).sql</BuildScriptName>
    <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
    <DebugSymbols>true</DebugSymbols>
    <DebugType>full</DebugType>
    <Optimize>false</Optimize>
    <DefineDebug>true</DefineDebug>
    <DefineTrace>true</DefineTrace>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>

A referência de propriedades do projeto lista as propriedades disponíveis e seus padrões.

Etapa 4: Arquivos de solução

O arquivo de projeto pode ser referenciado em um arquivo de solução (.sln). Se você tiver um arquivo de solução, deverá atualizá-lo para fazer referência ao novo arquivo de projeto no estilo SDK. Se você não tiver um arquivo de solução, poderá ignorar esta seção e prosseguir para a Etapa 5.

Opção 1: criar um novo arquivo de solução

Para um arquivo de solução que contém apenas o projeto SQL, é mais simples remover o arquivo de solução e criar um novo arquivo de solução com o projeto no estilo SDK.

dotnet new sln --name MySolution
dotnet sln MySolution.sln add MyDatabaseProject\MyDatabaseProject.sqlproj

Opção 2: Editar o arquivo de solução

Quando um arquivo de solução contém vários projetos, você deve atualizar o arquivo de solução para fazer referência ao novo arquivo de projeto no estilo SDK. Você pode editar o arquivo de solução em um editor de texto e alterar a referência do projeto para o novo arquivo de projeto no estilo SDK. A referência do projeto no arquivo de solução deve ter esta aparência:

Project("{PROJECT_TYPE_GUID}") = "MyDatabaseProject", "MyDatabaseProject\MyDatabaseProject.sqlproj", "{PROJECT_GUID}"
EndProject

O valor PROJECT_TYPE_GUID para um projeto Microsoft.Build.Sql é 42EA0DBD-9CF1-443E-919E-BE9C484E4577, e o PROJECT_GUID é um identificador exclusivo para o projeto encontrado no elemento <ProjectGuid> do arquivo do projeto. Se você tiver um arquivo de solução com seu projeto, o PROJECT_GUID valor não será necessário para ser alterado e poderá permanecer o mesmo que no arquivo de projeto original. É necessário alterar o valor PROJECT_TYPE_GUID para o GUID do tipo de projeto Microsoft.Build.Sql.

Etapa 5: Criar um `.dacpac` arquivo do projeto modificado para comparação

O projeto SQL não é mais compatível com o Visual Studio 2022. Para construir ou editar o projeto, você deve usar um dos seguintes:

a linha de comando
a extensão de Projetos de Banco de Dados SQL no Visual Studio Code
a extensão de Projetos de Banco de Dados SQL no Azure Data Studio
as Ferramentas de Dados do SQL Server, estilo SDK (versão prévia) no Visual Studio 2022

O arquivo de projeto agora está no formato estilo SDK, mas para abri-lo no Visual Studio 2022, você deve ter as Ferramentas de Dados do SQL Server, estilo SDK (versão prévia) instaladas. Abra o projeto no Visual Studio 2022 com o SQL Server Data Tools, estilo SDK (versão prévia) instalado.

Os projetos de banco de dados SQL podem ser criados a partir da linha de comando usando o comando dotnet build.

dotnet build

# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj

O processo de compilação cria um arquivo .dacpac na pasta bin\Debug do projeto por padrão. Usando o explorador de arquivos, localize o .dacpac criado pelo processo de build e copie-o para uma nova pasta fora do diretório do projeto. Usamos esse arquivo .dacpac para comparação para validar nossa conversão posteriormente.

Etapa 6: Verificar se os `.dacpac` arquivos são os mesmos

Para verificar se a conversão foi bem-sucedida, compare os arquivos .dacpac criados a partir dos projetos originais e modificados. As funcionalidades de comparação de esquemas nos projetos SQL permitem visualizar a diferença entre os modelos de banco de dados dos dois arquivos .dacpac. Como alternativa, o utilitário de linha de comando DacpacVerify pode ser usado para comparar os dois arquivos .dacpac, incluindo seus scripts pré/pós-implantação e configurações de projeto.

O DacpacVerify está disponível para instalação como ferramenta .NET . Para instalar a ferramenta, execute o seguinte comando:

dotnet tool install --global Microsoft.DacpacVerify --prerelease

A sintaxe para DacpacVerify é especificar o caminho do arquivo para dois arquivos .dacpac como dacpacverify <source DACPAC path> <target DACPAC path>. Para comparar os dois arquivos .dacpac, execute o seguinte comando:

DacpacVerify original_project.dacpac modified_project.dacpac

Você pode usar a ferramenta de comparação de esquema no Visual Studio ou no Azure Data Studio para comparar objetos nos arquivos .dacpac.

Inicie o Visual Studio sem um projeto carregado. Vá para Ferramentas>SQL Server>Nova Comparação de Esquemas. Selecione o arquivo original .dacpac como origem e o arquivo modificado .dacpac como destino. Para obter mais informações sobre como usar a Comparação de Esquemas no Visual Studio, consulte usando a comparação de esquemas para comparar diferentes definições de banco de dados.

A comparação de esquema gráfico ainda não está disponível na versão prévia de projetos SQL no estilo SDK no Visual Studio. Use o Azure Data Studio para comparar esquemas.

A comparação de esquemas não está disponível no Visual Studio Code. Use o Azure Data Studio ou o Visual Studio para comparar esquemas.

No Azure Data Studio, instale a extensão de Comparação de Esquemas SQL Server se ela ainda não estiver instalada. Inicie uma nova comparação de esquemas na paleta de comandos abrindo a paleta de comandos com Ctrl/Cmd+Shift+P e digitando Schema Compare.

Selecione o arquivo original .dacpac como origem e o arquivo modificado .dacpac como destino.

A comparação de esquemas gráficos está disponível no Visual Studio e no Azure Data Studio.

Quando a comparação de esquemas é executada, nenhum resultado deve ser exibido. A falta de diferenças indica que os projetos originais e modificados são equivalentes, produzindo o mesmo modelo de banco de dados no arquivo .dacpac.

Note

A comparação de arquivos .dacpac pela comparação de esquemas não valida scripts de pré/pós-implantação, refactorlog ou outras configurações de projeto. Ela apenas valida o modelo de banco de dados. Usar o utilitário de linha de comando DacpacVerify é a maneira recomendada de validar que os dois arquivos .dacpac são equivalentes.

Comentários

Esta página foi útil?

Last updated on 2025-09-25