Converter um projeto SQL original em um projeto no estilo SDK

Aplica-se a:SQL ServerBase de Dados SQL do AzureAzure SQL Managed InstanceBase de dados SQL no Microsoft Fabric

Criar um novo projeto SQL no estilo SDK é uma tarefa rápida. No entanto, se já tiveres projetos SQL, podes convertê-los em projetos SQL ao estilo SDK para tirar partido das novas funcionalidades.

Depois de converter o projeto, pode usar as novas funcionalidades do projeto ao estilo SDK, tais como:

• Suporte multiplataforma para compilações
• Formato simplificado de ficheiro de projeto
• Referências de pacotes

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

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

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

• A extensão SQL Database Projects no Visual Studio Code
• DevOps de bases de dados no SQL Server Management Studio (SSMS)
• A linha de comando
• O SQL Server Data Tools, em estilo SDK (pré-visualização), 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. Desta forma, você pode reverter para o projeto original, se necessário.

No Explorador de Ficheiros, crie uma cópia do ficheiro .sqlproj do projeto que pretende converter, com .original acrescentado à extensão do ficheiro. Por exemplo, MyProject.sqlproj torna-se MyProject.sqlproj.original.

Etapa 2: Criar um arquivo de .dacpac a partir 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. Utilize o Explorador de Ficheiros para localizar 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 ficheiro para comparar e validar a sua conversão mais tarde.

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

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

Obrigatório: adicione a referência do SDK

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

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

Necessário: remova importações de destino de compilação desnecessárias

Os projetos SQL originais fazem referência a vários alvos e propriedades de construção em declarações Import. Com exceção dos itens <Import/> que adicionaste explicitamente, que é uma alteração única e deliberada, remove as linhas que começam com <Import ...>. Exemplos a remover caso estejam presentes no 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" />
...

Necessá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 este item do ficheiro do projeto.

Exemplo a remover caso esteja presente no seu .sqlproj:

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

Obrigatório: Remover itens de compilação incluídos por padrão

Os 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 do tipo SDK, quaisquer ficheiros .sql na árvore de pastas do projeto (**/*.sql) são incluídos por defeito. Remova os ficheiros .sql especificados nos itens <Build Include="...." /> relativos a esses ficheiros para evitar problemas de desempenho na compilação.

Remova linhas como as seguintes do ficheiro 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 ficheiros que não estão na árvore de pastas do projeto SQL
• <PreDeploy Include="..." /> ou <PostDeploy Include="..." /> itens, porque esses nós ditam comportamentos específicos desses ficheiros
• Itens que não sejam ficheiros .sql, como ficheiros .publish.xml em itens <None Include="..." />, ficheiros .refactorlog.xml em itens <RefactorLog Include="..." /> ou ficheiros .xsd em itens <Build Include="..." />

Opcional: Remover referências ao SSDT

O SSDT (SQL Server Data Tools) original exigia conteúdo extra no arquivo de projeto para detetar 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 compilação padrão

Os projetos SQL originais incluem dois blocos grandes para as definições de Release e Debug build, enquanto nos projetos SQL ao estilo SDK o SDK conhece os padrões dessas opções. Se você não tiver personalizações nas configurações de compilação, 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>

As propriedades do projeto na referência listam as propriedades disponíveis e seus valores padrão.

Etapa 4: Arquivos de solução

Seu arquivo de projeto pode ser referenciado em um arquivo de solução (.sln). Se tiver um ficheiro de solução, atualize-o para referenciar o novo ficheiro de projeto ao estilo SDK. Se não tiver um ficheiro de solução, pode saltar esta secção e avançar para o Passo 5.

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

Se o ficheiro de solução contiver apenas o projeto SQL, é mais fácil remover o ficheiro de solução e criar um novo ficheiro de solução com o projeto ao 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 ficheiro de solução contiver vários projetos, atualize o ficheiro de solução para referenciar o novo ficheiro de projeto ao 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 do projeto, encontrado no elemento <ProjectGuid> do ficheiro de projeto. Se tiveres um ficheiro de solução com o teu projeto, não precisas de alterar 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. No Explorador de Ficheiros, 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 ficheiro para comparar e validar a sua conversão mais tarde.

Etapa 6: Verifique 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 base de dados entre os dois .dacpac ficheiros. Alternativamente, use a utilidade de linha de comandos DacpacVerify para comparar os dois .dacpac ficheiros, incluindo os seus scripts pré/pós-implementação e definições do projeto.

Podes 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 exige especificar os caminhos de 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

Podes usar a ferramenta de comparação de esquemas para comparar objetos nos .dacpac ficheiros.

Quando fazes a comparação de esquemas, não devem aparecer resultados. 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 aos projetos de banco de dados SQL
• Referências de pacotes dos projetos SQL