Desenvolver projetos de armazém no Visual Studio Code

Aplica-se a: ✅ Armazém em Microsoft Fabric

Aprenda a configurar um projeto de base de dados para o Fabric Data Warehouse no Visual Studio Code. Crias um novo projeto, defines objetos de esquema, constróis e validas o projeto, e publicas-no no teu armazém.

Importante

Este recurso está em pré-visualização.

Pré-requisitos

Antes de começar, certifique-se de que:

• Ter acesso a um item de Armazém existente num espaço de trabalho do Fabric com permissões de Colaborador ou superior.
  • Para criar um novo armazém de amostras, consulte Criar um Armazém de amostras em Microsoft Fabric.
• Instala Visual Studio Code na tua estação de trabalho.
• Instala o SDK .NET para construir e publicar projetos de bases de dados.
• Instale duas extensões Visual Studio Code: SQL Database Projects e SQL Server (mssql).
  • Pode instalar as extensões necessárias diretamente a partir do marketplace do Visual Studio Code pesquisando por "SQL Database Projects" ou "SQL Server (mssql)".

Criar um novo projeto de banco de dados

Pode criar um projeto de base de dados do zero ou a partir de um armazém existente.

Opção 1: Criar um novo projeto de base de dados a partir da Paleta de Comandos no Visual Studio Code

1. Abrir Visual Studio Code.

2. Abra a Paleta de Comandos (Ctrl+Shift+P ou Cmd+Shift+P no Mac).

3. Pesquisar por Projetos de Banco de Dados: Novo.

4. Selecione Tipo de Projeto de Base de Dados como SQL Server Base de Dados.

5. Escolha um nome de projeto e selecione o local da pasta local.

6. Escolha Synapse Data Warehouse em Microsoft Fabric como plataforma alvo.

7. Quando solicitado, selecione Sim (recomendado) para um projeto no estilo SDK.

   Importante

   Apenas projetos no estilo SDK são suportados para o Fabric Data Warehouse.

8. Selecione Sim para a pergunta Deseja configurar a compilação do projeto SQL como a configuração de compilação padrão para esta pasta?

9. Selecione Sim para confiar nos autores dos arquivos nesta pasta.

Opção 2: Criar um novo projeto de banco de dados a partir da extensão Projetos de Banco de Dados

1. Em Visual Studio Code, escolha o ícone de extensão Projetos de Base de Dados a partir da barra Activity.

2. No painel Projetos de Banco de Dados , selecione Criar novo.

   

3. Selecione Tipo de Projeto de Base de Dados como SQL Server Base de Dados.

4. Escolha um nome de projeto e selecione o local da pasta local.

5. Escolha Synapse Data Warehouse em Microsoft Fabric como plataforma alvo.

6. Quando solicitado, selecione Sim (recomendado) para um projeto no estilo SDK. Apenas projetos no estilo SDK são suportados para o Fabric Data Warehouse.

7. Selecione Sim para a pergunta Deseja configurar a compilação do projeto SQL como a configuração de compilação padrão para esta pasta?

8. Selecione Sim para confiar nos autores dos arquivos nesta pasta.

Opção 3: Criar um projeto de banco de dados a partir de um depósito existente

1. Primeiro, crie um novo perfil de ligação para o seu armazém no Visual Studio Code.

   1. Selecione a extensão SQL Server na Visual Studio Code a partir da barra Activity.
   2. Forneça um nome de perfil. Escolha Parâmetros.
   3. Introduza o nome do servidor. No portal Fabric, nas Definições do seu armazém, selecione SQL cadeia de ligação e copie a string fornecida. Esta string é o nome do servidor do seu armazém e é diferente do endpoint de análise SQL. É semelhante a <server unique ID>.datawarehouse.fabric.microsoft.com.
   4. Para tipo de autenticação, use Microsoft Entra ID - Universal com suporte a MFA. Autentique com o seu Microsoft Entra ID.
   5. Forneça outras informações como padrão ou desejado e selecione Conectar.

2. No Visual Studio Code, escolha o ícone de extensão Database Projects na Barra de Atividade.

3. Selecione o botão ... de opções no painel Projetos de Banco de Dados e escolha a opção Criar Projeto a partir do Banco de Dados .

   

4. Escolha o seu armazém a partir dos perfis de ligação existentes.

5. Introduza o nome de um projeto e escolha uma pasta de projeto na sua estação de trabalho.

6. Para estrutura de pastas, selecione Esquema/Tipo de objeto (recomendado).

7. Em Incluir permissões no projeto, selecione Não (padrão).

8. Para projeto no estilo SDK, selecione Sim (recomendado).

9. Selecione Sim para a pergunta Deseja configurar a compilação do projeto SQL como a configuração de compilação padrão para esta pasta?

10. O Visual Studio Code extrai ficheiros de projeto de um repositório.

    

11. Após extração bem-sucedida, vê a seguinte notificação: "Extrair ficheiros do projeto: Bem-sucedido. Concluído".

12. Selecione Sim para confiar nos autores dos arquivos nesta pasta.

Novo projeto de banco de dados para seu armazém

O novo projeto de banco de dados para seu depósito é exibido no menu Projetos do Banco de Dados SQL.

A estrutura do seu projeto tem esta aparência:

 | Project Name
 ├── Database References
 ├── SQLCMD Variables
 ├── .vscode/
 └── schema/
     ├── Functions
     ├── Tables
     └── Views

Configurar o projeto de banco de dados

1. Clique com o botão direito do mouse no projeto e selecione Editar arquivo .sqlproj.

   

2. Verifique se o ficheiro contém a versão mais recente da Microsoft. Build.SQL SDK. Por exemplo, altera a versão de Microsoft.Build.Sql para 2.3.0 no .sqlproj ficheiro.

      <Sdk Name="Microsoft.Build.Sql" Version="2.3.0" />
   

3. Verifique a versão mais recente do Microsoft.SqlServer.Dacpacs.FabricDw e adicione uma referência dentro do nó XML Project/ItemGroup. Por exemplo:

      <PackageReference Include="Microsoft.SqlServer.Dacpacs.FabricDw" Version="170.0.4">
          <DatabaseVariableLiteralValue>master</DatabaseVariableLiteralValue>
          <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
      </PackageReference>
   

   Importante

   Se adicionar a referência do pacote sem os metadados DatabaseVariableLiteralValue, a compilação do projeto é bem-sucedida, mas sqlpackage as ações Publish e Script podem falhar assim que o código referenciar objetos no esquema sys, como sys.views. Nesse caso, verá erros como os seguintes:

   Error SQL72033: This deployment may encounter errors during execution because [<schema>].[<procedure>] depends on [sys].[views].[schema_id] and [sys].[views].[schema_id] does not exist in the target database.

   É assim que seu projeto de banco de dados para um depósito deve ficar após as atualizações.

    <?xml version="1.0" encoding="utf-8"?>
    <Project DefaultTargets="Build">
      <Sdk Name="Microsoft.Build.Sql" Version="2.3.0" />
      <PropertyGroup>
        <Name>DatabaseProject715wh</Name>
        <ProjectGuid>{2E278BCC-F118-4DDB-9255-94697F2930B4}</ProjectGuid>
        <DSP>Microsoft.Data.Tools.Schema.Sql.SqlDwUnifiedDatabaseSchemaProvider</DSP>
        <ModelCollation>1033, CI</ModelCollation>
      </PropertyGroup>
      <ItemGroup>
        <None Include=".vscode\tasks.json" />
        <PackageReference Include="Microsoft.SqlServer.Dacpacs.FabricDw" Version="170.0.4">
          <DatabaseVariableLiteralValue>master</DatabaseVariableLiteralValue>
          <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
        </PackageReference>
      </ItemGroup>
      <Target Name="BeforeBuild">
        <Delete Files="$(BaseIntermediateOutputPath)\project.assets.json" />
      </Target>
    </Project>
   

4. Salve seu .sqlproj arquivo. No prompt para recarregar seu projeto de banco de dados, selecione Sim.

Importante

A equipa do Fabric Data Warehouse lança frequentemente novas versões dos pacotes NuGet. Como os valores de versão padrão no .sqlproj ficheiro podem mudar ao longo do tempo, atualize-os no seu projeto local para se manterem alinhados com as versões mais recentes disponíveis no NuGet para a Microsoft. SqlServer.Dacpacs.FabricDw.

Adicionar ou atualizar objetos de banco de dados

Você pode definir ou modificar objetos de banco de dados, como tabelas, exibições, procedimentos armazenados e funções em seu projeto de depósito.

Na pasta de um esquema, por exemplo dbo, adicione, elimine ou faça alterações nas definições T-SQL de objetos no seu armazém de dados. Para modificar um objeto existente, abra o arquivo correspondente .sql e atualize a definição conforme necessário.

Quando você cria o projeto, todos os objetos novos e atualizados são validados e incluídos no arquivo {project folder location}/bin/debug/{project name}.dacpac dacpac gerado.

As alterações feitas aqui são apenas ao projeto da base de dados e não são refletidas no Microsoft Fabric até compilar e publicar o seu projeto.

Construir e validar o projeto

1. Abre o projeto da base de dados se ainda não estiver aberto.

2. Clique com o botão direito no projeto e selecione Construir para construir o projeto da base de dados.

   

3. A build deve ter sucesso. Corrigir quaisquer erros baseados nas mensagens fornecidas na saída do evento de compilação.

Observação

Atualmente, o seu terminal predefinido do Visual Studio Code tem de ser o PowerShell para que o processo de compilação na extensão Projetos de Base de Dados tenha sucesso. Na Paleta de Comandos, escolha Terminal: Selecione Perfil Padrão e depois selecione PowerShell.

Publicar no Fabric Data Warehouse

Depois de construir seu projeto, publique-o em seu armazém de destino. A publicação cria um script para resolver a diferença entre o projeto de banco de dados e o armazém de dados real e executa um script para fazer com que o armazém de dados corresponda ao projeto. Podes implementar o modelo compilado do esquema do armazém num ficheiro .dacpac para um armazém-alvo.

1. Clique com o botão direito do mouse no projeto e selecione Publicar.

2. Escolha Publicar em um servidor SQL existente.

3. Em Selecionar perfil de publicação para carregar, na primeira vez que publicar, escolha Não usar perfil.

   • Guarde opções para publicar o seu armazém num perfil de publicação. Uma notificação do Visual Studio Code dá-lhe a opção de guardar as opções de publicação que usou num ficheiro de perfil de publicação.
   • Reutilize o perfil de publicação no futuro quando publicar o seu projeto no seu armazém. Você pode ter diferentes opções de perfil para diferentes armazéns ou para ambientes diferentes nos seus ambientes de desenvolvimento/teste/aceitação/produção.

4. Escolha o perfil de ligação Fabric Data Warehouse da lista.

5. Escolha o nome do armazém de destino.

6. Na opção Escolher ação , você pode Gerar Script para revisar o script antes de publicar ou publicar o projeto em um depósito. - Na primeira vez que quiser implementar alterações, gere cuidadosamente um script e reveja o T-SQL resultante para aplicar ao warehouse alvo. Gerar o script não faz alterações ao armazém alvo.

   • Se escolheres Publicar, o processo grava as alterações no teu armazém de destino.

   

7. Na notificação Gostaria de salvar as configurações em um perfil (.publish.xml)?, escolha Sim e salve suas opções de perfil de publicação para a próxima vez que precisar publicar.

Definições importantes de implementação para projetos em armazéns

Quando implementa projetos de base de dados para Fabric Data Warehouse, várias definições controlam alterações no esquema e podem afetar a segurança dos dados. Use com cautela.

• BlockOnPossibleDataLoss

  • O que faz: Impede a implementação se houver risco de perda de dados (por exemplo, eliminar uma coluna ou tabela que contenha dados).
  • Recomendação: Sempre definido para True em produção para proteger dados críticos.
  • Atenção: Definir para False permitir a implementação mesmo que os dados possam ser perdidos. Use apenas em ambientes controlados (por exemplo, desenvolvimento/teste).

• DropObjectsNotInSource

  • O que faz: Elimina objetos na base de dados alvo que não estão presentes na fonte do projeto.
  • Recomendação: Uso em ambientes de desenvolvimento/teste para limpar objetos remanescentes.
  • Atenção: Usar DropObjectsNotInSource em produção pode eliminar objetos e dados importantes. Confirma duas vezes antes de ativar.

• PreDeploy para o script de pré-implementação

  • Função
    • Executa scripts SQL personalizados antes da implementação do esquema.
  • Usos comuns
    • Arquiver ou fazer backup dos dados antes de eliminar tabelas
    • Desativar temporariamente restrições ou gatilhos
    • Limpeza de objetos legados
  • Atenção
    • Garante que os scripts são idempotentes e não introduzem alterações de esquema que entrem em conflito com a implementação.

Tip

Quando um processo de implementação ou consulta é idempotente, pode executar o comando várias vezes sem causar problemas lógicos ou falhas. Um comando idempotente também é escrito de forma a poder ser implementado em múltiplas bases de dados sem necessidade de pré-determinar o seu estado.

• PostDeploy para o script pós-implementação

  • O que faz: Executa scripts SQL personalizados após a implementação do esquema.
  • Usos comuns:
    • Consulta ou dados de referência da semente
    • Reativar restrições ou gatilhos
    • Histórico de registo de implementações
  • Atenção: Evite operações pesadas em mesas grandes durante a produção. Garanta que os scripts podem correr várias vezes em segurança, se necessário.

Importante

Revê sempre scripts e definições de implementação antes de publicar. Teste primeiro em ambientes de desenvolvimento ou de teste para evitar perda não intencional de dados. Para mais informações e exemplos, consulte Scripts de pré-implementação e pós-implementação para o Fabric Data Warehouse.

Verificar publicação

Liga-te ao teu armazém e scripta objetos que mudaram, ou verifica executando objetos do catálogo do sistema.

Conteúdo relacionado

• Fluxos de trabalho de desenvolvimento e implantação
• Desenvolver e implantar dependências entre armazéns
• Comece a usar pipelines de implantação do Fabric