Usar projetos SQL no estilo SDK com a extensão Projetos de Banco de Dados SQL (versão prévia)

Este artigo apresenta o Microsoft.Build.Sql para projetos SQL em estilo de SDK na extensão de Projetos de Banco de Dados SQL no Azure Data Studio ou no Visual Studio Code. Os projetos SQL no estilo SDK são especialmente vantajosos para aplicativos enviados por meio de pipelines ou em ambientes multiplataforma. O comunicado inicial está disponível no TechCommunity.

Observação

O Microsoft.Build.Sql está atualmente em versão prévia.

Criar um projeto de banco de dados no estilo SDK

Você pode criar um projeto de banco de dados no estilo SDK de um projeto em branco ou de um banco de dados existente.

Projeto em branco

Na exibição Projetos de banco de dados, selecione o botão Novo Projeto e insira um nome para o projeto no espaço para entrada de texto exibido. Na caixa de diálogo Selecionar uma Pasta exibida, selecione um diretório para a pasta do projeto, o arquivo .sqlproj e outros conteúdos.

Por padrão, a seleção para o projeto no estilo SDK (versão prévia) é marcada. Quando a caixa de diálogo estiver preenchida, o projeto vazio será aberto e ficará visível na exibição Projetos de banco de dados para edição.

De um banco de dados existente

Na exibição Projeto, clique no botão Criar um projeto com base no banco de dados e conecte-se a um SQL Server. Depois que a conexão for estabelecida, selecione um banco de dados na lista de bancos de dados disponíveis e defina o nome do projeto. Selecione uma estrutura de destino para a extração.

Por padrão, a seleção para o projeto no estilo SDK (versão prévia) é marcada. Quando a caixa de diálogo estiver preenchida, o novo projeto será aberto e conterá scripts SQL para o conteúdo do banco de dados selecionado.

Criar e publicar

Nas interfaces do Azure Data Studio e do Visual Studio Code, a criação e a publicação de um projeto SQL em estilo de SDK é concluída da mesma forma que no formato anterior de projeto SQL. Para obter mais informações sobre esse processo, confira Compilar e publicar um projeto.

Para compilar um projeto SQL com estilo SDK na linha de comando no Windows, macOS ou Linux, use o seguinte comando:

dotnet build

O arquivo .dacpac resultante da compilação de um projeto SQL em estilo de SDK é compatível com ferramentas associadas à estrutura do aplicativo da camada de dados (.dacpac, .bacpac), incluindo SqlPackage e sql-action do GitHub.

Recursos do projeto

Em projetos SQL, há vários recursos que podem ser especificados no arquivo .sqlproj que afetam o modelo de banco de dados no momento da compilação ou da implantação do projeto. As seções a seguir descrevem alguns desses recursos disponíveis para projetos Microsoft.Build.Sql.

Plataforma de destino

A propriedade da plataforma de destino está contida na marca DSP do arquivo .sqlproj sob o item <PropertyGroup>. A plataforma de destino é usada durante a compilação do projeto para validar o suporte aos recursos incluídos nele e é adicionada ao arquivo .dacpac como uma propriedade. Por padrão, durante a implantação, a plataforma de destino é verificada com relação ao banco de dados de destino para garantir a compatibilidade. A implantação falhará se a plataforma de destino não for compatível com o banco de dados de destino, a menos que uma opção de publicação de substituição seja especificada.

<Project DefaultTargets="Build">
  <Sdk Name="Microsoft.Build.Sql" Version="0.1.12-preview" />
  <PropertyGroup>
    <Name>AdventureWorks</Name>
    <DSP>Microsoft.Data.Tools.Schema.Sql.SqlAzureV12DatabaseSchemaProvider</DSP>
  </PropertyGroup>

As configurações válidas para a plataforma de destino são as seguintes:

  • Microsoft.Data.Tools.Schema.Sql.Sql120DatabaseSchemaProvider
  • Microsoft.Data.Tools.Schema.Sql.Sql130DatabaseSchemaProvider
  • Microsoft.Data.Tools.Schema.Sql.Sql140DatabaseSchemaProvider
  • Microsoft.Data.Tools.Schema.Sql.Sql150DatabaseSchemaProvider
  • Microsoft.Data.Tools.Schema.Sql.Sql160DatabaseSchemaProvider
  • Microsoft.Data.Tools.Schema.Sql.SqlAzureV12DatabaseSchemaProvider
  • Microsoft.Data.Tools.Schema.Sql.SqlDwDatabaseSchemaProvider
  • Microsoft.Data.Tools.Schema.Sql.SqlServerlessDatabaseSchemaProvider
  • Microsoft.Data.Tools.Schema.Sql.SqlDwUnifiedDatabaseSchemaProvider

Referências de banco de dados

A validação do modelo de banco de dados no tempo de compilação pode ser estendida para além do conteúdo do projeto SQL por meio de referências de banco de dados. As referências de banco de dados especificadas no arquivo .sqlproj podem ser relativas a outro projeto SQL ou a um arquivo .dacpac, representando outro banco de dados ou mais componentes do mesmo.

Os seguintes atributos estão disponíveis para referências de banco de dados que representam outro banco de dados:

  • DatabaseSqlCmdVariable: o valor é o nome da variável usada para fazer referência ao banco de dados
    • Configuração de referência: <DatabaseSqlCmdVariable>SomeOtherDatabase</DatabaseSqlCmdVariable>
    • Exemplo de uso: SELECT * FROM [$(SomeOtherDatabase)].dbo.Table1
  • ServerSqlCmdVariable: o valor é o nome da variável que é usada para referenciar o servidor em que o banco de dados reside. Usado com DatabaseSqlCmdVariable quando o banco de dados está em outro servidor.
    • Configuração de referência: <ServerSqlCmdVariable>SomeOtherServer</ServerSqlCmdVariable>
    • Exemplo de uso: SELECT * FROM [$(SomeOtherServer)].[$(SomeOtherDatabase)].dbo.Table1
  • DatabaseVariableLiteralValue: o valor é o nome literal do banco de dados conforme usado no projeto SQL, semelhante a DatabaseSqlCmdVariable, mas a referência a outro banco de dados é um valor literal
    • Configuração de referência: <DatabaseVariableLiteralValue>SomeOtherDatabase</DatabaseVariableLiteralValue>
    • Exemplo de uso: SELECT * FROM [SomeOtherDatabase].dbo.Table1

Em um arquivo de projeto SQL, uma referência de banco de dados é especificada como um item ArtifactReference com o atributo Include definido para o caminho do arquivo .dacpac.

  <ItemGroup>
    <ArtifactReference Include="SampleA.dacpac">
      <DatabaseSqlCmdVariable>DatabaseA</DatabaseSqlCmdVariable>
    </ArtifactReference>
  </ItemGroup>
</Project>

Referências de pacote

Referências de pacote são usadas para referenciar pacotes NuGet que contêm um arquivo .dacpac e são usadas para estender o modelo de banco de dados no tempo de compilação de maneira semelhante a uma referência de banco de dados.

O exemplo a seguir de um arquivo de projeto SQL faz referência ao pacote Microsoft.SqlServer.Dacpacs do banco de dados master.

  <ItemGroup>
    <PackageReference Include="Microsoft.SqlServer.Dacpacs" Version="160.0.0" />
  </ItemGroup>
</Project>

Além dos atributos disponíveis para referências de banco de dados, o atributo DacpacName a seguir pode ser especificado para selecionar um .dacpac de um pacote que contém diversos arquivos .dacpac.

  <ItemGroup>
    <PackageReference Include="Microsoft.SqlServer.Dacpacs" Version="160.0.0">
      <DacpacName>msdb</DacpacName>
    </PackageReference>
  </ItemGroup>
</Project>

Variáveis SQLCMD

As variáveis SQLCMD podem ser definidas no arquivo .sqlproj e são usadas para substituir tokens em scripts e objetos SQL durante a .dacpac implantação. O exemplo a seguir de um arquivo de projeto SQL define uma variável EnvironmentName que está disponível para uso em objetos e scripts do projeto.

  <ItemGroup>
    <SqlCmdVariable Include="EnvironmentName">
      <DefaultValue>testing</DefaultValue>
      <Value>$(SqlCmdVar__1)</Value>
    </SqlCmdVariable>
  </ItemGroup>
</Project>
IF '$(EnvironmentName)' = 'testing'
BEGIN
    -- do something
END

Quando um projeto SQL compilado (.dacpac) é implantado, o valor da variável é substituído pelo valor especificado no comando de implantação. Por exemplo, o comando a seguir implanta AdventureWorks.dacpac e define o valor da variável EnvironmentName como production.

SqlPackage /Action:Publish /SourceFile:AdventureWorks.dacpac /TargetConnectionString:{connection_string_here} /v:EnvironmentName=production

Scripts de pré/pós-implantação

Os scripts de pré/pós-implantação são scripts SQL incluídos no projeto para serem executados durante a implantação. Eles estão incluídos em .dacpac, mas não são compilados ou validados com o modelo de objeto de banco de dados. Um script de pré-implantação é executado antes da aplicação do modelo de banco de dados e um script de pós-implantação é executado após a aplicação. O exemplo a seguir de um arquivo de projeto SQL adiciona o arquivo populate-app-settings.sql como um script de pós-implantação.

  <ItemGroup>
    <PostDeploy Include="populate-app-settings.sql" />
  </ItemGroup>
</Project>

Próximas etapas