Usar projetos SQL no estilo SDK com a extensão Projetos do Banco de Dados SQL (Visualização)

Artigo
07/04/2024

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

Nota

Microsoft.Build.Sql está atualmente em visualização.

Criar um projeto de banco de dados no estilo SDK

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

Projeto em branco

Na visualização Projetos de Banco de Dados, selecione o botão Novo Projeto e insira um nome de projeto na entrada de texto exibida. Na caixa de diálogo Selecionar uma pasta exibida, escolha um diretório para a pasta, .sqlproj o arquivo e outros conteúdos do projeto para residir.

Por padrão, a seleção para projeto no estilo SDK (Visualização) é marcada. Quando a caixa de diálogo é concluída, o projeto vazio é aberto e visível na visualização Projetos de Banco de Dados para edição.

A partir de uma base de dados existente

Na visualização Projeto, selecione o botão Criar projeto do banco de dados e conecte-se a um SQL Server. Uma vez estabelecida a conexão, selecione um banco de dados na lista de bancos de dados disponíveis e defina o nome do projeto. Selecione uma estrutura de destino da extração.

Por padrão, a seleção para projeto no estilo SDK (Visualização) é marcada. Quando a caixa de diálogo é concluída, o novo projeto é aberto e contém 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 no estilo SDK são concluídas da mesma forma que o formato de projeto SQL anterior. Para obter mais informações sobre esse processo, consulte Criar e publicar um projeto.

Para criar um projeto SQL no estilo SDK a partir da linha de comando no Windows, macOS ou Linux, use o seguinte comando:

dotnet build

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

Capacidades do projeto

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

Plataforma de destino

A propriedade da plataforma de destino está contida na DSP tag no .sqlproj arquivo sob o <PropertyGroup> item. A plataforma de destino é usada durante a compilação do projeto para validar o suporte para recursos incluídos no projeto e é adicionada .dacpac ao arquivo como uma propriedade. Por padrão, durante a implantação, a plataforma de destino é verificada em relação ao banco de dados de destino para garantir a compatibilidade. Se a plataforma de destino não for suportada pelo banco de dados de destino, a implantação falhará 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:

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 bases de dados

A validação do modelo de banco de dados em tempo de compilação pode ser estendida 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 podem fazer referência a .sqlproj outro projeto SQL ou a um .dacpac arquivo, representando outro banco de dados ou mais componentes do mesmo banco de dados.

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
- Definição de referência: <DatabaseSqlCmdVariable>SomeOtherDatabase</DatabaseSqlCmdVariable>
- Exemplo de uso: SELECT * FROM [$(SomeOtherDatabase)].dbo.Table1
ServerSqlCmdVariable: o valor é o nome da variável usada para fazer referência ao servidor onde reside o banco de dados. usado com DatabaseSqlCmdVariable, quando o banco de dados está em outro servidor.
- Definiçã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 usado no projeto SQL, semelhante a DatabaseSqlCmdVariable mas a referência a outro banco de dados é um valor literal
- Definiçã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 ArtifactReference item com o Include atributo definido para o caminho do .dacpac arquivo.

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

Referências de pacotes

As referências de pacote são usadas para fazer referência a pacotes NuGet que contêm um .dacpac arquivo e são usadas para estender o modelo de banco de dados em tempo de compilação da mesma forma que uma referência de banco de dados.

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

  <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 a seguir DacpacName pode ser especificado para selecionar um .dacpac de um pacote que contém vários .dacpac arquivos.

  <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 e são usadas para substituir tokens em objetos e scripts SQL durante .dacpac a .sqlproj implantação. O exemplo a seguir de um arquivo de projeto SQL define uma variável chamada EnvironmentName que está disponível para uso nos 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 deployment. Por exemplo, o comando a seguir implanta o AdventureWorks.dacpac e define o valor da EnvironmentName variável como production.

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

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

Os scripts pré e pós-implantação são scripts SQL incluídos no projeto a ser executado durante a implantação. Os scripts pré/pós-implantação estão incluídos no mas não são compilados ou validados com o .dacpac modelo de objeto de banco de dados. Um script de pré-implantação é executado antes que o modelo de banco de dados seja aplicado e um script de pós-implantação é executado depois que o modelo de banco de dados é aplicado. O exemplo a seguir de um arquivo de projeto SQL adiciona o arquivo populate-app-settings.sql como script pós-implantação.

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

Partilhar via