Tutorial: iniciar a partir de um banco de dados existente
Aplica-se a: 
SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure
Os projetos SQL contêm arquivos declarativos (instrução CREATE) para todos os objetos em um banco de dados, como tabelas, exibições e procedimentos armazenados. Esses arquivos podem ser usados para criar novos bancos de dados, atualizar bancos de dados existentes ou até mesmo apenas para rastrear o banco de dados no controle do código-fonte. Muitas vezes, começamos com um projeto SQL quando temos um banco de dados existente e queremos criar objetos no projeto SQL que correspondam ao banco de dados com o mínimo de esforço.
Algumas ferramentas de projetos SQL incluem uma única etapa para criar um novo projeto SQL a partir de um banco de dados existente. Outras ferramentas exigem algumas etapas para criar um novo projeto SQL e, em seguida, importar objetos de um banco de dados existente. Com exceção das instruções do Visual Studio (SQL Server Data Tools), o guia se concentra em projetos SQL no estilo SDK.
Com a opção 1 neste tutorial, você:
Etapa 1: criar um novo projeto SQL a partir de um banco de dados existente Etapa 2: criar o projeto SQL
Com a opção 2 neste tutorial, você:
- Etapa 1: criar um novo projeto SQL vazio
- Etapa 2: importar objetos de um banco de dados existente
- Etapa 3: compilar o projeto SQL
Pré-requisitos
- SDK do .NET 8
- Visual Studio 2022 Community, Professional ou Enterprise
- SQL Server Data Tools, estilo SDK (versão prévia) instalado no Visual Studio 2022
- SqlPackage CLI
# install SqlPackage CLI
dotnet tool install -g Microsoft.SqlPackage
# install SqlPackage CLI
dotnet tool install -g Microsoft.SqlPackage
# install Microsoft.Build.Sql.Templates
dotnet new install Microsoft.Build.Sql.Templates
Observação
Para concluir o tutorial, você precisa acessar uma instância do SQL do Azure ou do SQL Server. Você pode desenvolver localmente de graça com a edição do SQL Server Developer no Windows ou em contêineres.
Opção 1: criar um novo projeto SQL a partir de um banco de dados existente
Etapa 1: criar um projeto SQL a partir de um banco de dados existente
No pesquisador de objetos do SQL Server no Visual Studio, clique com o botão direito do mouse no banco de dados do qual você deseja criar um projeto e selecione Criar Novo Projeto....
Na caixa de diálogo Criar Novo Projeto, forneça um nome de projeto, que não precisa corresponder a um nome de banco de dados. Verifique e modifique o local do projeto conforme necessário. As configurações de importação padrão importam os objetos para pastas por esquema e, em seguida, por tipo de objeto. Você pode modificar as configurações de importação para alterar a estrutura de pastas ou incluir permissões nos objetos que estão sendo importados. Inicie a importação.
Enquanto a importação prossegue, o progresso é exibido como mensagens na caixa de diálogo Importar banco de dados. Quando a importação é concluída, os objetos importados ficam visíveis no Gerenciador de Soluções e os logs são armazenados em um arquivo no diretório do projeto em Import Schema Logs. Selecione Concluir.
A opção 1 não está disponível para a linha de comando. Em vez disso, use a opção 2.
Na exibição do pesquisador de objetos de banco de dados no VS Code ou no Azure Data Studio, selecione um banco de dados a partir do qual você deseja criar um projeto. Clique com o botão direito do mouse no banco de dados e selecione Criar projeto por meio de banco de dados.
No Azure Data Studio, a caixa de diálogo Criar projeto por meio de banco de dados requer que o nome e o local do projeto sejam selecionados. As configurações de importação padrão importam os objetos para pastas por esquema e, em seguida, por tipo de objeto. Você pode selecionar uma estrutura de pastas diferente ou incluir permissões nos objetos que estão sendo importados antes de selecionar Criar.
No VS Code, os prompts de comando solicitam um nome e um local do projeto. As configurações de importação padrão importam os objetos para pastas por esquema e, em seguida, por tipo de objeto. Você pode selecionar uma estrutura de pastas diferente ou incluir permissões nos objetos que estão sendo importados antes do início da importação.
Abra a visualização Projetos de Banco de Dados para ver o novo projeto e as definições de objeto importado.
A opção 1 não está disponível para a linha de comando. Em vez disso, use a opção 2.
Etapa 2: compilar o projeto SQL
O processo de build valida as relações entre objetos e a sintaxe em relação à plataforma de destino especificada no arquivo de projeto. A saída do artefato do processo de build é um arquivo .dacpac, que pode ser usado para implantar o projeto em um banco de dados de destino e contém o modelo compilado do esquema de banco de dados.
No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Compilar.
A janela de saída é aberta automaticamente para exibir o processo de build. Se houver erros ou avisos, eles serão exibidos na janela de saída. Em uma compilação bem-sucedida, o artefato de compilação (arquivo .dacpac) é criado, sua localização é incluída na saída da compilação (o padrão é bin\Debug\projectname.dacpac).
A opção 1 não está disponível para a linha de comando. Em vez disso, use a opção 2.
Na exibição Projetos de Banco de Dados do VS Code ou do Azure Data Studio, clique com o botão direito do mouse no nó do projeto e selecione Compilar.
A janela de saída é aberta automaticamente para exibir o processo de build. Se houver erros ou avisos, eles serão exibidos na janela de saída. Em uma compilação bem-sucedida, o artefato de compilação (arquivo .dacpac) é criado, sua localização é incluída na saída da compilação (o padrão é bin/Debug/projectname.dacpac).
A opção 1 não está disponível para a linha de comando. Em vez disso, use a opção 2.
Opção 2: criar um novo projeto SQL vazio e importar objetos de um banco de dados existente
Como alternativa, as etapas de criação do projeto e importação de objetos podem ser feitas separadamente.
Etapa 1: criar um novo projeto SQL vazio
Começamos nosso projeto criando um novo projeto de banco de dados SQL antes de importar nossos objetos para ele.
Selecione Arquivo, Novo e, em seguida, Projeto.
Na caixa de diálogo Novo Projeto, use o termo SQL Server na caixa de pesquisa. O resultado principal deve ser Projeto de Banco de Dados do SQL Server.
Selecione Avançar para prosseguir para a próxima etapa. Forneça um nome de projeto, que não precisa corresponder a um nome de banco de dados. Verifique e modifique o local do projeto conforme necessário.
Selecione Criar para criar o cluster. O projeto vazio será aberto e ficará visível no Gerenciador de Soluções para edição.
Selecione Arquivo, Novo e, em seguida, Projeto.
Na caixa de diálogo Novo Projeto, use o termo SQL Server na caixa de pesquisa. O resultado principal deve ser Projeto de Banco de Dados do SQL Server, estilo SDK (versão prévia).
Selecione Avançar para prosseguir para a próxima etapa. Forneça um nome de projeto, que não precisa corresponder a um nome de banco de dados. Verifique e modifique o local do projeto conforme necessário.
Selecione Criar para criar o cluster. O projeto vazio será aberto e ficará visível no Gerenciador de Soluções para edição.
Na exibição Projetos de Banco de Dados do VS Code ou do Azure Data Studio, selecione o botão Novo Projeto.
O primeiro prompt determina qual modelo de projeto usar, principalmente com base no fato de a plataforma de destino ser SQL Server ou SQL do Azure. Se solicitada a seleção de uma versão específica do SQL, escolha a versão que corresponde ao banco de dados de destino, mas se a versão do banco de dados de destino for desconhecida, escolha a versão mais recente, pois o valor pode ser modificado posteriormente.
Insira um nome de projeto na entrada de texto exibida, que não precisa corresponder a um nome de banco de dados.
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.
Quando perguntado se deseja criar um projeto no estilo SDK (versão prévia), selecione Sim.
Depois de concluído, o projeto vazio será aberto e ficará visível na exibição Projetos de banco de dados para edição.
Com os modelos .NET para projetos Microsoft.Build.Sql instalados, você pode criar um novo projeto de banco de dados SQL na linha de comando. A opção -n especifica o nome do projeto e a opção -tp especifica a plataforma de destino do projeto.
Use a opção -h para ver todas as opções disponíveis.
# install Microsoft.Build.Sql.Templates
dotnet new sqlproject -n MyDatabaseProject
Etapa 2: importar objetos de um banco de dados existente
No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Importar –> Banco de Dados.... Se essa opção estiver desabilitada, seu projeto de banco de dados poderá ter objetos criados nele. Você pode excluir os objetos ou criar um novo projeto.
Na caixa de diálogo Importar banco de dados, selecione a conexão com o banco de dados do qual deseja importar objetos. Se você se conectou ao banco de dados no Pesquisador de Objetos do SQL Server, ele estará presente na lista do histórico.
As configurações de importação padrão importam os objetos para pastas por esquema e, em seguida, por tipo de objeto. Você pode modificar as configurações de importação para alterar a estrutura de pastas ou incluir permissões nos objetos que estão sendo importados. Inicie a importação.
Enquanto a importação prossegue, o progresso é exibido como mensagens na caixa de diálogo Importar banco de dados. Quando a importação é concluída, os objetos importados ficam visíveis no Gerenciador de Soluções e os logs são armazenados em um arquivo no diretório do projeto em Import Schema Logs. Selecione Concluir para retornar ao projeto.
Usaremos a CLI do SqlPackage para importar objetos de um banco de dados existente para o novo projeto de banco de dados SQL que criamos no Visual Studio na etapa 1. O comando SqlPackage a seguir importa o esquema de um banco de dados para uma pasta MyDatabaseProject organizada por esquema aninhado e pastas de tipo de objeto.
sqlpackage /a:Extract /ssn:localhost /sdn:MyDatabase /tf:MyDatabaseProject /p:ExtractTarget=SchemaObjectType
Quando essas pastas são colocadas em uma pasta de projeto de banco de dados SQL no estilo SDK, elas são incluídas automaticamente no projeto sem a necessidade de importá-las ou modificar o arquivo de projeto SQL.
Observação
A extensão de Projetos do Banco de Dados SQL no VS Code não oferece suporte à importação de objetos de um banco de dados para um projeto. Use a extensão de Projetos do Banco de Dados SQL no Azure Data Studio para importar objetos de um banco de dados ou siga a opção 1 para criar um novo projeto de um banco de dados existente no VS Code.
Na extensão de Projetos do Banco de Dados SQL do Azure Data Studio, abra a exibição Projetos de Banco de Dados. Clique com o botão direito do mouse no nó e selecione Atualizar projeto por meio do banco de dados.
Na caixa de diálogo Atualizar banco de dados, selecione a conexão com o banco de dados do qual deseja importar objetos. Se você se conectou ao banco de dados na exibição Conexões, ele estará presente na lista do histórico.
Selecione Exibir alterações na comparação de esquema para revisar e escolha um subconjunto de objetos para importar ou Aplicar todas as alterações para importar todos os objetos.
A CLI do SqlPackage pode ser usada para extrair o esquema de um banco de dados existente para um arquivo .dacpac ou arquivos individuais .sql. O comando SqlPackage a seguir extrai o esquema de um banco de dados para arquivos .sql organizados por esquema aninhado e pastas de tipo de objeto.
sqlpackage /a:Extract /ssn:localhost /sdn:MyDatabase /tf:MyDatabaseProject /p:ExtractTarget=SchemaObjectType
Quando essas pastas são colocadas em uma pasta de projeto de banco de dados SQL no estilo SDK, elas são incluídas automaticamente no projeto sem a necessidade de importá-las ou modificar o arquivo de projeto SQL.
Etapa 3: compilar o projeto SQL
O processo de build valida as relações entre objetos e a sintaxe em relação à plataforma de destino especificada no arquivo de projeto. A saída do artefato do processo de build é um arquivo .dacpac, que pode ser usado para implantar o projeto em um banco de dados de destino e contém o modelo compilado do esquema de banco de dados.
No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Compilar.
A janela de saída é aberta automaticamente para exibir o processo de build. Se houver erros ou avisos, eles serão exibidos na janela de saída. Em uma compilação bem-sucedida, o artefato de compilação (arquivo .dacpac) é criado, sua localização é incluída na saída da compilação (o padrão é bin\Debug\projectname.dacpac).
No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Compilar.
A janela de saída é aberta automaticamente para exibir o processo de build. Se houver erros ou avisos, eles serão exibidos na janela de saída. Em uma compilação bem-sucedida, o artefato de compilação (arquivo .dacpac) é criado, sua localização é incluída na saída da compilação (o padrão é bin\Debug\projectname.dacpac).
Na exibição Projetos de Banco de Dados do VS Code ou do Azure Data Studio, clique com o botão direito do mouse no nó do projeto e selecione Compilar.
A janela de saída é aberta automaticamente para exibir o processo de build. Se houver erros ou avisos, eles serão exibidos na janela de saída. Em uma compilação bem-sucedida, o artefato de compilação (arquivo .dacpac) é criado, sua localização é incluída na saída da compilação (o padrão é bin/Debug/projectname.dacpac).
Os projetos de banco de dados SQL podem ser criados a partir da linha de comando usando o comando dotnet build.
dotnet build
# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj
A saída do build inclui quaisquer erros ou avisos e os arquivos específicos e números de linha onde eles ocorrem. Em uma compilação bem-sucedida, o artefato de compilação (arquivo .dacpac) é criado, sua localização é incluída na saída da compilação (o padrão é bin/Debug/projectname.dacpac).