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.Sql120DatabaseSchemaProviderMicrosoft.Data.Tools.Schema.Sql.Sql130DatabaseSchemaProviderMicrosoft.Data.Tools.Schema.Sql.Sql140DatabaseSchemaProviderMicrosoft.Data.Tools.Schema.Sql.Sql150DatabaseSchemaProviderMicrosoft.Data.Tools.Schema.Sql.Sql160DatabaseSchemaProviderMicrosoft.Data.Tools.Schema.Sql.SqlAzureV12DatabaseSchemaProviderMicrosoft.Data.Tools.Schema.Sql.SqlDwDatabaseSchemaProviderMicrosoft.Data.Tools.Schema.Sql.SqlServerlessDatabaseSchemaProviderMicrosoft.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
- Configuração de referência:
- 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
- Configuração de referência:
- 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
- Configuração de referência:
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>