Converter um projeto SQL original em um projeto no estilo SDK

Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada de SQL do AzureBanco de dados SQL no Microsoft Fabric

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

Após converter o projeto, você pode usar as novas funcionalidades do projeto no estilo SDK, tais como:

• Suporte a compilações multiplataforma
• Formato simplificado de arquivo de projeto
• Referências de pacote

Para completar a conversão com cuidado, siga estes passos:

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

SQL Server Data Tools (SSDT) no Visual Studio não suporta projetos no estilo SDK. Depois de converter o projeto, use uma das seguintes ferramentas para construir ou editar o projeto:

• A extensão SQL Database Projects no Visual Studio Code
• DevOps de Banco de Dados no SQL Server Management Studio (SSMS)
• A linha de comando
• SQL Server Data Tools no estilo SDK (versão prévia) no Visual Studio 2022

Prerequisites

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 do projeto que você deseja converter, com .original anexado à 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

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 compilação e copie-o para uma nova pasta fora do diretório do projeto com o nome original_project.dacpac. Use este .dacpac arquivo para comparar e validar sua conversão depois.

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. Remova esse item do arquivo do 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, quaisquer .sql arquivos na árvore de pastas do projeto (**/*.sql) são incluídos por padrão. Remova os .sql arquivos especificados nos <Build Include="...." /> itens desses arquivos para evitar problemas de desempenho na compilação.

Remova linhas como as seguintes do arquivo do projeto:

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

Não remova:

• <Build Include="..." /> itens para .sql arquivos que não estão na árvore de pastas do projeto SQL
• <PreDeploy Include="..." /> ou <PostDeploy Include="..." /> itens, porque esses nós ditam comportamento específico para esses arquivos
• Itens que não são arquivos .sql, como arquivos .publish.xml em itens <None Include="..." />, arquivos .refactorlog.xml em itens <RefactorLog Include="..." /> ou arquivos .xsd em itens <Build Include="..." />

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

Projetos SQL originais incluem dois blocos grandes para configurações de Release e Debug build, enquanto em projetos SQL no estilo SDK o SDK conhece os padrões dessas opções. 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, atualize-o para referenciar o novo arquivo de projeto no estilo SDK. Se você não tiver um arquivo de solução, ignore esta seção e vá para a Etapa 5.

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

Se o arquivo de solução contém apenas o projeto SQL, é mais fácil 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

Se o arquivo de solução contiver múltiplos projetos, atualize o arquivo de solução para referenciar o 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 de PROJECT_TYPE_GUID para um projeto Microsoft.Build.Sql é 42EA0DBD-9CF1-443E-919E-BE9C484E4577. O PROJECT_GUID é um identificador único para o projeto encontrado no elemento do arquivo <ProjectGuid> do projeto. Se você tem um arquivo de solução com seu projeto, não precisa mudar o PROJECT_GUID valor. Altere o valor de 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

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 compilação e copie-o para uma nova pasta fora do diretório do projeto. Use este .dacpac arquivo para comparar e validar sua conversão depois.

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. Use as capacidades de comparação de esquemas dos projetos SQL para visualizar a diferença nos modelos de banco de dados entre os dois .dacpac arquivos. Alternativamente, use a ferramenta de linha de comando DacpacVerify para comparar os dois .dacpac arquivos, incluindo seus scripts pré/pós-implantação e configurações do projeto.

Você pode instalar o DacpacVerify como uma ferramenta dotnet. 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 para comparar objetos nos .dacpac arquivos.

Quando você faz a comparação de esquemas, 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.

Conteúdo relacionado

• O que são projetos de banco de dados SQL?
• Introdução a projetos de banco de dados SQL
• referências de pacote de projetos SQL