Processos de validação e importação

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019 | TFS 2018

Este artigo orienta você pela preparação necessária para obter uma importação para Azure DevOps Services pronto para execução. Se você encontrar erros durante o processo, consulte Solucionar problemas de erros de importação e migração.

Observação

  • Visual Studio Team Services (VSTS) agora está Azure DevOps Services.
  • Com o lançamento do Azure DevOps Server 2019, o Serviço de Importação de Banco de Dados TFS foi renomeado como a ferramenta de migração de dados para o Azure DevOps. Essa alteração inclui o TfsMigrator (Migrator) se tornando a ferramenta de migração de dados. Esse serviço funciona exatamente o mesmo que o antigo serviço de importação. Se você estiver executando uma versão mais antiga do Azure DevOps Server local com a identidade visual do TFS, ainda poderá usar esse recurso para migrar para o Azure DevOps desde que tenha atualizado para uma das versões do servidor com suporte.
  • Antes de iniciar as tarefas de importação, verifique se você está executando uma versão com suporte do Azure DevOps Server.

Recomendamos que você use o guia de migração passo a passo para prosseguir com sua importação. Os links de guia para documentação técnica, ferramentas e práticas recomendadas.

Pré-requisitos

  • Você deve configurar um locatário do Azure Active Directory conforme descrito Azure AD Sincronização do Connect: fazer uma alteração na configuração padrão. A ferramenta de migração de dados configura um link para seu locatário do Azure Active Directory quando sua organização Azure DevOps Services é criada como parte do início do processo de importação.

    Ao sincronizar sua Active Directory local com o Azure Active Directory, os membros da sua equipe poderão usar as mesmas credenciais para autenticar e seus administradores de Azure DevOps Services poderão aproveitar seus grupos do Active Directory para definir permissões em seu Azure DevOps Services Organização. Para configurar a sincronização, você deseja usar a tecnologia Azure AD Connect.

Validar uma coleção

Depois de confirmar que está executando a versão mais recente do Azure DevOps Server, sua próxima etapa é validar cada coleção que você deseja migrar para Azure DevOps Services.

A etapa de validação examina vários aspectos de sua coleção, incluindo, mas não se limitando a tamanho, ordenação, identidade e processos.

Execute a validação usando a ferramenta de migração de dados. Para iniciar, baixe a ferramenta, copie o arquivo zip para uma de suas camadas de aplicativo Azure DevOps Server e descompacte-o. Você também pode executar a ferramenta em um computador diferente sem Azure DevOps Server instalado, desde que o computador possa se conectar ao banco de dados de configuração da instância de Azure DevOps Server. Um exemplo é mostrado aqui.

  1. Abra uma janela do Prompt de Comando no servidor e insira um comando cd para alterar para o diretório onde a ferramenta de migração de dados é armazenada. Tire alguns instantes para examinar o conteúdo da ajuda fornecido com a ferramenta.

    a. Para exibir a ajuda e as diretrizes de nível superior, execute o seguinte comando:

     Migrator /help
    

    b. Exiba o texto da ajuda para o comando:

     Migrator validate /help 
    
  2. Como essa é sua primeira vez validando uma coleção, vamos mantê-la simples. Seu comando deve ter a seguinte estrutura:

     Migrator validate /collection:{collection URL} /tenantDomainName:{name}
    

    Onde {name} fornece o nome do locatário do Azure Active Directory. Por exemplo, para ser executado no defaultCollection e no locatário fabrikam , o comando seria semelhante a:

     Migrator validate /collection:http://localhost:8080/DefaultCollection /tenantDomainName:fabrikam.OnMicrosoft.com
    
  3. Para executar a ferramenta de um computador diferente do Azure DevOps Server, você precisa do parâmetro /connectionString. O parâmetro de cadeia de conexão aponta para o banco de dados de configuração Azure DevOps Server. Por exemplo, se o comando validar estiver sendo executado pela corporação Fabrikam, o comando será semelhante a:

     Migrator validate /collection:http://fabrikam:8080/DefaultCollection /tenantDomainName:fabrikam.OnMicrosoft.com /connectionString:"Data Source=fabrikam;Initial Catalog=Configuration;Integrated Security=True"
    

    Importante

    A ferramenta de migração de dados não edita nenhum dado ou estrutura na coleção. Ele lê a coleção apenas para identificar problemas.

  4. Depois que a validação for concluída, você poderá exibir os arquivos de log e os resultados.

    Captura de tela dos resultados e logs de validação na janela Prompt de Comando.

    Durante a validação, você receberá um aviso se alguns de seus pipelines contiverem regras de retenção por pipeline. Azure DevOps Services usa um modelo de retenção baseado em projeto e não dá suporte a políticas de retenção por pipeline. Se você prosseguir com a migração, as políticas não serão levadas para a versão hospedada. Em vez disso, as políticas de retenção padrão no nível do projeto serão aplicadas. Retenha builds importantes para você, para evitar a perda deles.

Depois que todas as validações passarem, você poderá passar para a próxima etapa do processo de importação. Se a ferramenta de migração de dados sinalizar erros, você precisará corrigi-los antes de prosseguir. Para obter diretrizes sobre como corrigir erros de validação, consulte Solucionar problemas de erros de importação e migração.

Importar arquivos de log

Ao abrir o diretório de log, você observará vários arquivos de log.

O arquivo de log principal é chamado DataMigrationTool.log. Ele contém detalhes sobre tudo o que foi executado. Para facilitar o foco em áreas específicas, um log é gerado para cada operação de validação principal.

Por exemplo, se o TfsMigrator relatar um erro na etapa "Validando Processos de Projeto", você poderá abrir o arquivo ProjectProcessMap.log para exibir tudo o que foi executado para essa etapa em vez de ter que rolar pelo log inteiro.

Você deve examinar o arquivo TryMatchOobProcesses.log somente se estiver tentando importar seus processos de projeto para usar o modelo herdado. Se você não quiser usar o modelo herdado, poderá ignorar esses erros, pois eles não impedirão que você importe para Azure DevOps Services.

Gerar arquivos de importação

Até agora, você já executou a validação da ferramenta de migração de dados na coleção e ela está retornando um resultado de "Todas as validações de coleção aprovadas". Antes de colocar uma coleção offline para migrá-la, você precisa gerar os arquivos de importação. Ao executar o prepare comando, você gera dois arquivos de importação:

  • IdentityMapLog.csv: descreve o mapa de identidade entre o Active Directory e o Azure Active Directory (Azure AD).
  • import.json: exige que você preencha a especificação de importação que deseja usar para iniciar sua migração.

O comando prepare

O prepare comando ajuda a gerar os arquivos de importação necessários. Essencialmente, esse comando examina a coleção para encontrar uma lista de todos os usuários para preencher o log de mapa de identidade, IdentityMapLog.csve tenta se conectar a Azure AD para localizar a correspondência de cada identidade. Para fazer isso, sua empresa precisa usar a ferramenta Azure Active Directory Connect (anteriormente conhecida como ferramenta de Sincronização de Diretório, ferramenta sincronização de diretório ou ferramenta de DirSync.exe).

Se a sincronização de diretório estiver configurada, a ferramenta de migração de dados deverá ser capaz de localizar as identidades correspondentes e marcá-las como Ativas. Se não encontrar uma correspondência, a identidade será marcada como Histórico no log do mapa de identidade e você precisará investigar por que o usuário não está incluído na sincronização de diretórios. O arquivo de especificação de importação, import.json, deve ser preenchido antes da importação.

Ao contrário do validate comando, preparerequer uma conexão com a Internet, pois ele precisa se conectar a Azure AD para preencher o arquivo de log do mapa de identidade. Se sua instância de Azure DevOps Server não tiver acesso à Internet, você precisará executar a ferramenta de um computador que tenha. Contanto que você possa encontrar um computador com uma conexão de intranet com sua instância de Azure DevOps Server e uma conexão com a Internet, você pode executar esse comando. Para obter ajuda com o prepare comando, execute o seguinte comando:

Migrator prepare /help

Incluídos na documentação da ajuda estão instruções e exemplos para executar o Migrator comando da própria instância Azure DevOps Server e de um computador remoto. Se você estiver executando o comando de uma das camadas de aplicativo da instância Azure DevOps Server, seu comando deverá ter a seguinte estrutura:

Migrator prepare /collection:{collection URL} /tenantDomainName:{name} /region:{region}
Migrator prepare  /collection:{collection URL} /tenantDomainName:{name} /region:{region} /connectionString:"Data Source={sqlserver};Initial Catalog=Configuration;Integrated Security=True"

O parâmetro connectionString é um ponteiro para o banco de dados de configuração da instância de Azure DevOps Server. Por exemplo, se o prepare comando estiver sendo executado pela corporação Fabrikam, o comando será semelhante a:

Migrator prepare /collection:http://fabrikam:8080/DefaultCollection /tenantDomainName:fabrikam.OnMicrosoft.com /region:{region} /connectionString:"Data Source=fabrikam;Initial Catalog=Configuration;Integrated Security=True"

Quando a ferramenta de migração de dados executa o prepare comando, ela executa uma validação completa para garantir que nada tenha mudado com sua coleção desde a última validação completa. Se novos problemas forem detectados, nenhum arquivo de importação será gerado.

Logo após o comando começar a ser executado, uma janela de entrada Azure AD será exibida. Você precisa entrar com uma identidade que pertença ao domínio de locatário especificado no comando. Verifique se o locatário Azure AD especificado é aquele com o qual você deseja que sua futura organização seja apoiada. Em nosso exemplo da Fabrikam, um usuário inseriria credenciais semelhantes às mostradas na captura de tela a seguir.

Importante

Não use um locatário de Azure AD de teste para uma importação de teste e seu locatário de Azure AD de produção para a execução de produção. O uso de um locatário de Azure AD de teste pode resultar em problemas de importação de identidade quando você começa a execução de produção com o locatário de Azure AD de produção da sua organização.

Captura de tela da janela de entrada do Azure AD.

Quando você executa o prepare comando com êxito na ferramenta de migração de dados, a janela de resultados exibe um conjunto de logs e dois arquivos de importação. No diretório de log, você encontrará uma pasta de logs e dois arquivos:

  • import.json é o arquivo de especificação de importação. Recomendamos que você tenha tempo para preenchê-lo.
  • IdentityMapLog.csv contém o mapeamento gerado do Active Directory para Azure AD identidades. Examine-o quanto à integridade antes de iniciar uma importação.

Os dois arquivos são descritos com mais detalhes nas próximas seções.

O arquivo de especificação de importação

A especificação de importação, import.json, é um arquivo JSON que fornece configurações de importação. Ele inclui o nome da organização desejado, as informações da conta de armazenamento e outras informações. A maioria dos campos é preenchida automaticamente e alguns campos exigem sua entrada antes de tentar uma importação.

Captura de tela de um arquivo de especificação de importação recém-gerado.

Os campos exibidos e as ações necessárias do arquivo import.json são descritos na tabela a seguir:

Campo Descrição Ação necessária
Fonte Informações sobre o local e os nomes dos arquivos de dados de origem que são usados para importação. Nenhuma ação é necessária. Examine as informações das ações de subcampo a seguir.
Location A chave de assinatura de acesso compartilhado para a conta de armazenamento do Azure que hospeda o DACPAC (pacote de aplicativo de camada de dados). Nenhuma ação é necessária. Esse campo será abordado em uma etapa posterior.
Arquivos Os nomes dos arquivos que contêm dados de importação. Nenhuma ação é necessária. Examine as informações das ações de subcampo a seguir.
DACPAC Um arquivo DACPAC que empacota o banco de dados de coleta a ser usado para trazer os dados durante a importação. Nenhuma ação é necessária. Em uma etapa posterior, você gerará esse arquivo usando sua coleção e, em seguida, o carregará em uma conta de armazenamento do Azure. Você precisará atualizar o arquivo com base no nome usado ao gerá-lo posteriormente nesse processo.
Destino Propriedades da nova organização para a qual importar. Nenhuma ação é necessária. Examine as informações das ações de subcampo a seguir.
Nome O nome da organização a ser criada durante a importação. Forneça um nome. O nome pode ser alterado rapidamente posteriormente após a conclusão da importação.
Observação: não crie uma organização com esse nome antes de executar a importação. A organização será criada como parte do processo de importação.
ImportType O tipo de importação que você deseja executar. Nenhuma ação é necessária. Em uma etapa posterior, você selecionará o tipo de importação a ser executado.
Dados de validação Informações necessárias para ajudar a impulsionar sua experiência de importação. A seção "ValidationData" é gerada pela ferramenta de migração de dados. Ele contém informações necessárias para ajudar a impulsionar sua experiência de importação. Não edite os valores nesta seção ou sua importação pode falhar ao iniciar.

Depois de concluir o processo anterior, você deverá ter um arquivo semelhante ao seguinte:

Captura de tela de um arquivo de especificação de importação parcialmente concluído.

Na imagem anterior, observe que o planejador da importação fabrikam adicionou o nome da organização fabrikam-import e o CUS selecionado (Central Estados Unidos) como a região para importação. Outros valores foram deixados como devem ser modificados pouco antes de o planejador colocar a coleção offline para a migração.

Observação

As importações de execução a seco têm uma 'dryrun' acrescentada automaticamente ao final do nome da organização. Isso pode ser alterado após a importação.

Regiões do Azure com suporte para importação

Azure DevOps Services está disponível em várias regiões do Azure. No entanto, nem todas as regiões em que Azure DevOps Services está disponível têm suporte para importação. A tabela a seguir lista as regiões do Azure que você pode selecionar para importação. Também está incluído o valor que você precisa colocar no arquivo de especificação de importação para direcionar essa região para importação.

Região geográfica Região do Azure Importar valor de especificação
Estados Unidos Central Estados Unidos CUS
Europa Europa Ocidental WEU
Reino Unido Sul do Reino Unido Uks
Austrália Leste da Austrália EAU
América do Sul Sul do Brasil Sbr
Pacífico Asiático Sul da Índia MA
Pacífico Asiático Sudeste da Ásia (Singapura) SEA
Canadá Centro do Canadá CC

O log do mapa de identidade

O log de mapa de identidade é igualmente importante para os dados reais que você migrará para Azure DevOps Services. À medida que você está examinando o arquivo, é importante entender como a importação de identidade opera e o que os resultados potenciais podem implicar. Quando você importa uma identidade, ela pode se tornar ativa ou histórica. Identidades ativas podem entrar em Azure DevOps Services, mas identidades históricas não podem.

Identidades ativas

Identidades ativas referem-se a identidades que serão usuários em Azure DevOps Services pós-importação. Em Azure DevOps Services, essas identidades são licenciadas e são exibidas como usuários na organização. As identidades são marcadas como ativas na coluna Status de Importação Esperada no arquivo de log do mapa de identidade.

Identidades históricas

As identidades históricas são mapeadas como tal na coluna Status de Importação Esperada no arquivo de log do mapa de identidade. Identidades sem uma entrada de linha no arquivo também se tornam históricas. Um exemplo de uma identidade sem uma entrada de linha pode ser um funcionário que não trabalha mais em uma empresa.

Ao contrário das identidades ativas, identidades históricas:

  • Não tenha acesso a uma organização após a migração.
  • Não tenho licenças.
  • Não apareça como usuários na organização. Tudo o que persiste é a noção do nome dessa identidade na organização, para que seu histórico possa ser pesquisado posteriormente. Recomendamos que você use identidades históricas para usuários que não trabalham mais na empresa ou que não precisarão de mais acesso à organização.

Observação

Depois que uma identidade é importada como histórica, ela não pode se tornar ativa.

Entender o arquivo de log do mapa de identidade

O arquivo de log do mapa de identidade é semelhante ao exemplo mostrado aqui:

Captura de tela de um arquivo de log de mapa de identidade gerado pela ferramenta de migração de dados.

As colunas no arquivo de log do mapa de identidade são descritas na tabela a seguir:

Observação

Você e seu administrador de Azure AD precisarão investigar os usuários marcados como Não Encontrados (Verificar Azure AD Sync) para entender por que eles não fazem parte da sincronização do Azure AD Connect.

Coluna Descrição
Active Directory: Usuário (Azure DevOps Server) O nome de exibição amigável usado pela identidade em Azure DevOps Server. Esse nome facilita a identificação de qual usuário a linha do mapa está referenciando.
Active Directory: Identificador de Segurança O identificador exclusivo da identidade Active Directory local no Azure DevOps Server. Esta coluna é usada para identificar usuários na coleção.
Azure Active Directory: Usuário de Importação Esperado (Azure DevOps Services) O endereço de entrada esperado do usuário em breve a ser ativo correspondente ou Não Encontrado (Verificar Azure AD Sync), indicando que a identidade não foi encontrada durante a sincronização do Azure Active Directory e será importada como histórica.
Status de importação esperado O status de importação de usuário esperado: Ativo se houver uma correspondência entre o Active Directory e o Azure Active Directory ou Histórico se não houver uma correspondência.
Data de validação A última vez que o log do mapa de identidade foi validado.

Ao ler o arquivo, observe se o valor na coluna Status de Importação Esperado é Ativo ou Histórico. O Active indica que é esperado que a identidade nessa linha seja mapeada corretamente na importação e se torne ativa. Histórico significa que as identidades se tornarão históricas na importação. É importante examinar o arquivo de mapeamento gerado quanto à integridade e à correção.

Importante

Sua importação falhará se ocorrerem grandes alterações na sincronização de ID de segurança do Azure AD Connect entre tentativas de importação. Você pode adicionar novos usuários entre execuções secas e fazer correções para garantir que as identidades históricas importadas anteriormente se tornem ativas. No entanto, não há suporte para a alteração de um usuário existente que foi importado anteriormente como ativo. Isso fará com que a importação falhe. Um exemplo de alteração pode estar concluindo uma importação de execução seca, excluindo uma identidade de seu Azure AD que foi importado ativamente, recriando um novo usuário em Azure AD para essa mesma identidade e, em seguida, tentando outra importação. Nesse caso, uma importação de identidade ativa será tentada entre o Active Directory e a identidade de Azure AD recém-criada, mas causará uma falha na importação.

  1. Comece revisando as identidades correspondentes corretamente. Todas as identidades esperadas estão presentes? Os usuários são mapeados para a identidade de Azure AD correta?

    Se algum valor for mapeado incorretamente ou precisar ser alterado, entre em contato com o administrador do Azure AD para verificar se a identidade Active Directory local faz parte da sincronização para Azure AD e foi configurada corretamente. Para obter mais informações, consulte Integrar suas identidades locais ao Azure Active Directory.

  2. Em seguida, examine as identidades rotuladas como históricas. Essa rotulagem implica que não foi possível encontrar uma identidade de Azure AD correspondente, por nenhum dos seguintes motivos:

    • A identidade não foi configurada para sincronização entre Active Directory local e Azure AD.
    • A identidade ainda não foi preenchida em seu Azure AD (por exemplo, há um novo funcionário).
    • A identidade não existe em sua instância de Azure AD.
    • O usuário que possui essa identidade não trabalha mais na empresa.

Para resolver os três primeiros motivos, você precisa configurar a identidade de Active Directory local pretendida para sincronizar com Azure AD. Para obter mais informações, consulte Integrar suas identidades locais ao Azure Active Directory. Você deve configurar e executar Azure AD Connect para que as identidades sejam importadas como ativas no Azure DevOps Services.

Você pode ignorar o quarto motivo, pois os funcionários que não estão mais na empresa devem ser importados como históricos.

Identidades históricas (pequenas equipes)

Observação

A estratégia de importação de identidade proposta nesta seção deve ser considerada apenas por equipes pequenas.

Se Azure AD Connect não tiver sido configurado, você observará que todos os usuários no arquivo de log do mapa de identidade serão marcados como históricos. Executar uma importação dessa forma faz com que todos os usuários sejam importados como históricos. Recomendamos que você configure Azure AD Connect para garantir que os usuários sejam importados como ativos.

Executar uma importação com todas as identidades históricas tem consequências que precisam ser consideradas com cuidado. Ele deve ser considerado apenas por equipes com um pequeno número de usuários e para o qual o custo de configuração Azure AD Connect é considerado muito alto.

Para importar todas as identidades como histórico, siga as etapas descritas nas seções posteriores. Quando você enfileira uma importação, a identidade usada para enfileirar a importação é inicializada na organização como o proprietário da organização. Todos os outros usuários são importados como históricos. Os proprietários da organização podem adicionar os usuários de volta usando sua identidade de Azure AD. Os usuários adicionados são tratados como novos usuários. Eles não possuem nenhuma de suas histórias, e não há nenhuma maneira de re-pai desta história para o Azure AD identidade. No entanto, os usuários ainda podem pesquisar seu histórico de pré-importação pesquisando seu <nome> de usuário do Active Directory de domínio><.

A ferramenta de migração de dados exibirá um aviso se detectar o cenário de identidades históricas completas. Se você decidir seguir esse caminho de migração, precisará consentir na ferramenta com as limitações.

Assinaturas do Visual Studio

A ferramenta de migração de dados não pode detectar assinaturas do Visual Studio (anteriormente conhecidas como benefícios do MSDN) quando gera o arquivo de log do mapa de identidade. Em vez disso, recomendamos que você aplique o recurso de atualização de licença automática após a importação. Enquanto as contas corporativas dos usuários estiverem vinculadas corretamente, Azure DevOps Services aplicará automaticamente seus benefícios de assinatura do Visual Studio em sua primeira entrada após a importação. Você nunca é cobrado por licenças atribuídas durante a importação, portanto, isso pode ser tratado com segurança posteriormente.

Você não precisará repetir uma importação de execução seca se as assinaturas do Visual Studio dos usuários não forem atualizadas automaticamente no Azure DevOps Services. A vinculação de assinatura do Visual Studio ocorre fora do escopo de uma importação. Desde que sua conta corporativa esteja vinculada corretamente antes ou depois da importação, as licenças dos usuários são atualizadas automaticamente na próxima entrada. Depois que suas licenças forem atualizadas com êxito, na próxima vez que você executar uma importação, os usuários serão atualizados automaticamente em sua primeira entrada na organização.

Preparar para importação

Agora, você já tem tudo pronto para ser executado na importação. Você precisa agendar o tempo de inatividade com sua equipe para colocar a coleção offline para a migração. Quando você tiver concordado em um momento para executar a importação, precisará carregar no Azure os ativos necessários gerados e uma cópia do banco de dados. Esse processo tem cinco etapas:

Etapa 1: coloque a coleção offline e desanexe-a.

Observação

Se a ferramenta de migração de dados exibir um aviso de que você não pode usar o método DACPAC, será necessário executar a importação usando o método SQL Azure VM (máquina virtual). Ignore as etapas 2 a 5 nesse caso e siga as instruções fornecidas em Importar grandes coleções e, em seguida, continue a determinar o tipo de importação.

Etapa 2: Gerar um arquivo DACPAC da coleção que você vai importar.
Etapa 3: Carregar o arquivo DACPAC e importar arquivos para uma conta de armazenamento do Azure.
Etapa 4: Gerar uma chave SAS para a conta de armazenamento.
Etapa 5: concluir a especificação de importação.

Observação

Antes de realizar uma importação de produção, é altamente recomendável que você conclua uma importação de execução seca. Com uma execução seca, você pode validar que o processo de importação funciona para sua coleção e que não há formas de dados exclusivas presentes que possam causar uma falha na importação de produção.

Etapa 1: Desanexar sua coleção

Desanexar a coleção é uma etapa crucial no processo de importação. Os dados de identidade da coleção residem no banco de dados de configuração da instância Azure DevOps Server enquanto a coleção está anexada e online. Quando uma coleção é desanexada da instância de Azure DevOps Server, ela usa uma cópia desses dados de identidade e os empacota com a coleção para transporte. Sem esses dados, a parte de identidade da importação não pode ser executada. É recomendável manter a coleção desanexada até que a importação seja concluída, pois não há uma maneira de importar as alterações que ocorreram durante a importação.

Se você estiver fazendo uma importação de execução a seco (teste), recomendamos que você reanexe sua coleção depois de fazer backup dela para importação, pois não se preocupará em ter os dados mais recentes para esse tipo de importação. Para evitar o tempo offline completamente, você também pode optar por empregar um desanexamento offline para execuções secas.

É importante pesar o custo de optar por incorrer em tempo de inatividade zero para uma corrida seca. Ele requer fazer backups da coleção e do banco de dados de configuração, restaurá-los em uma instância do SQL e, em seguida, criar um backup desanexado. Uma análise de custo pode provar que levar apenas algumas horas de tempo de inatividade para fazer diretamente o backup desanexado é melhor a longo prazo.

Etapa 2: Gerar um arquivo DACPAC

Os DACPACs oferecem um método rápido e relativamente fácil para mover coleções para Azure DevOps Services. No entanto, depois que um tamanho de banco de dados de coleção excede um determinado limite, os benefícios de usar um DACPAC começam a diminuir.

Observação

Se a ferramenta de migração de dados exibir um aviso de que você não pode usar o método DACPAC, você precisará executar a importação usando o método SQL Azure VM (máquina virtual) fornecido em Importar grandes coleções.

Se a ferramenta de migração de dados não exibir um aviso, use o método DACPAC descrito nesta etapa.

O DACPAC é um recurso do SQL Server que permite que as alterações de banco de dados sejam empacotadas em um único arquivo e implantadas em outras instâncias do SQL. Um arquivo DACPAC também pode ser restaurado diretamente para Azure DevOps Services, para que você possa usá-lo como o método de empacotamento para obter os dados da sua coleção na nuvem. Use a ferramenta SqlPackage.exe para gerar o arquivo DACPAC. A ferramenta é incluída como parte do SQL Server Data Tools (SSDT).

Várias versões da ferramenta SqlPackage.exe são instaladas com o SSDT. As versões são armazenadas em pastas com nomes como 120, 130 e 140. Quando você usa SqlPackage.exe, é importante usar a versão certa para preparar o DACPAC.

  • As importações do TFS 2018 precisam usar a versão SqlPackage.exe da pasta 140 ou superior.

Se você instalou o SSDT para Visual Studio, encontrará sua versão SqlPackage.exe em um dos seguintes caminhos de pasta:

  • Se você instalou o SSDT e o integrou a uma instalação existente do Visual Studio, o caminho da pasta SqlPackage.exe será semelhante ao C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\130\.
  • Se você instalou o SSDT como uma instalação autônoma, o caminho da pasta SqlPackage.exe será semelhante a C:\Program Files (x86)\Microsoft Visual. Studio\2017\SQL\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\130\.
  • Se você já tiver uma instalação de SQL Server, talvez SqlPackage.exe já esteja presente e o caminho da pasta será semelhante ao %PROGRAMFILES%\Microsoft SQL Server\130\DAC\bin\.

Ambas as versões do SSDT que você pode baixar de SQL Server Data Tools incluem as pastas 130 e 140 e suas versões SqlPackage.exe.

Ao gerar um DACPAC, tenha duas considerações em mente: o disco no qual o DACPAC será salvo e o espaço em disco no computador que está gerando o DACPAC. Você deseja garantir que você tenha espaço em disco suficiente para concluir a operação.

À medida que ele cria o pacote, SqlPackage.exe armazena temporariamente dados de sua coleção no diretório temporário na unidade C do computador do qual você está iniciando a solicitação de empacotamento.

Você pode achar que a unidade C é muito pequena para dar suporte à criação de um DACPAC. Você pode estimar a quantidade de espaço que precisará procurando a maior tabela do banco de dados de coleção. OS DACPACs são criados uma tabela por vez. O requisito máximo de espaço para executar a geração é aproximadamente equivalente ao tamanho da maior tabela do banco de dados da coleção. Se você estiver salvando o DACPAC gerado para a unidade C, também precisará levar em conta o tamanho do banco de dados de coleta, conforme relatado no arquivo DataMigrationTool.log de uma execução de validação.

O arquivo DataMigrationTool.log fornece uma lista das maiores tabelas da coleção sempre que o comando validar é executado. Para obter um exemplo de tamanhos de tabela para uma coleção, consulte a saída a seguir. Compare o tamanho da tabela maior com o espaço livre na unidade que hospeda seu diretório temporário.

Importante

Antes de continuar gerando um arquivo DACPAC, verifique se sua coleção está desanexada.

[Info   @08:23:59.539] Table name                               Size in MB
[Info   @08:23:59.539] dbo.tbl_Content                          38984
[Info   @08:23:59.539] dbo.tbl_LocalVersion                     1935
[Info   @08:23:59.539] dbo.tbl_Version                          238
[Info   @08:23:59.539] dbo.tbl_FileReference                    85
[Info   @08:23:59.539] dbo.Rules                                68
[Info   @08:23:59.539] dbo.tbl_FileMetadata                     61

Verifique se a unidade que hospeda seu diretório temporário tem pelo menos tanto espaço livre. Se isso não ocorrer, você precisará redirecionar o diretório temporário definindo uma variável de ambiente.

SET TEMP={location on disk}

Outra consideração é onde os dados DACPAC são salvos. Apontar o local de salvamento para uma unidade remota distante pode resultar em tempos de geração muito mais longos. Se uma unidade rápida, como uma SSD (unidade de estado sólido) estiver disponível localmente, recomendamos que você direcione a unidade como o local de salvamento do DACPAC. Caso contrário, é sempre mais rápido usar um disco que está no computador em que o banco de dados de coleção reside em vez de uma unidade remota.

Agora que você identificou o local de destino para o DACPAC e garantiu que você tem espaço suficiente, é hora de gerar o arquivo DACPAC.

Abra uma janela do Prompt de Comando e vá para o local SqlPackage.exe. Para gerar o DACPAC, substitua os valores de espaço reservado pelos valores necessários e execute o seguinte comando:

SqlPackage.exe /sourceconnectionstring:"Data Source={database server name};Initial Catalog={Database Name};Integrated Security=True" /targetFile:{Location & File name} /action:extract /p:ExtractAllTableData=true /p:IgnoreUserLoginMappings=true /p:IgnorePermissions=true /p:Storage=Memory
  • Fonte de dados: a instância SQL Server que hospeda seu banco de dados de coleção Azure DevOps Server.
  • Catálogo Inicial: o nome do banco de dados de coleção.
  • targetFile: o local no disco e o nome do arquivo DACPAC.

Um comando de geração DACPAC em execução na própria camada de dados Azure DevOps Server é mostrado no exemplo a seguir:

SqlPackage.exe /sourceconnectionstring:"Data Source=localhost;Initial Catalog=Foo;Integrated Security=True" /targetFile:C:\DACPAC\Foo.dacpac /action:extract /p:ExtractAllTableData=true /p:IgnoreUserLoginMappings=true /p:IgnorePermissions=true /p:Storage=Memory

A saída do comando é um arquivo DACPAC gerado do banco de dados de coleção Foo chamado Foo.dacpac.

Configurar sua coleção para importação

Depois que o banco de dados de coleção for restaurado em sua VM do Azure, configure um logon do SQL para permitir que Azure DevOps Services se conectem ao banco de dados para importar os dados. Esse logon permite apenas o acesso de leitura a um único banco de dados.

Para iniciar, abra SQL Server Management Studio na VM e abra uma nova janela de consulta no banco de dados a ser importado.

Defina a recuperação do banco de dados como simples:

ALTER DATABASE [<Database name>] SET RECOVERY SIMPLE;

Crie um logon SQL para o banco de dados e atribua esse logon ao 'TFSEXECROLE':

USE [<database name>]
CREATE LOGIN <pick a username> WITH PASSWORD = '<pick a password>'
CREATE USER <username> FOR LOGIN <username> WITH DEFAULT_SCHEMA=[dbo]
EXEC sp_addrolemember @rolename='TFSEXECROLE', @membername='<username>'

Seguindo nosso exemplo da Fabrikam, os dois comandos SQL seriam semelhantes aos seguintes:

ALTER DATABASE [Foo] SET RECOVERY SIMPLE;

USE [Foo]
CREATE LOGIN fabrikam WITH PASSWORD = 'fabrikamimport1!'
CREATE USER fabrikam FOR LOGIN fabrikam WITH DEFAULT_SCHEMA=[dbo]
EXEC sp_addrolemember @rolename='TFSEXECROLE', @membername='fabrikam'

Observação

Habilite SQL Server e autenticação do Windows modo em SQL Server Management Studio na VM. Se você não habilitar o modo de autenticação, a importação falhará.

Configurar o arquivo de especificação de importação para direcionar a VM

Atualize o arquivo de especificação de importação para incluir informações sobre como se conectar à instância de SQL Server. Abra o arquivo de especificação de importação e faça as seguintes atualizações:

  1. Remova o parâmetro DACPAC do objeto de arquivos de origem.

    A especificação de importação antes da alteração é mostrada no seguinte código:

    Captura de tela da especificação de importação antes da alteração.

    A especificação de importação após a alteração é mostrada no seguinte código:

    Captura de tela da especificação de importação após a alteração.

  2. Preencha os parâmetros necessários e adicione o objeto de propriedades a seguir dentro do objeto de origem no arquivo de especificação.

    "Properties":
    {
        "ConnectionString": "Data Source={SQL Azure VM Public IP};Initial Catalog={Database Name};Integrated Security=False;User ID={SQL Login Username};Password={SQL Login Password};Encrypt=True;TrustServerCertificate=True" 
    }
    

Seguindo o exemplo da Fabrikam, depois de aplicar as alterações, a especificação de importação será semelhante à seguinte:

Captura de tela da especificação de importação que faz referência a uma VM SQL Azure.

Sua especificação de importação agora está configurada para usar uma VM SQL Azure para importação. Prossiga com o restante das etapas de preparação para importar para Azure DevOps Services. Após a conclusão da importação, exclua o logon do SQL ou gire a senha. A Microsoft não retém as informações de logon após a conclusão da importação.

Etapa 3: Carregar o arquivo DACPAC

Observação

Se você estiver usando o método de VM SQL Azure, precisará fornecer apenas a cadeia de conexão. Você não precisa carregar nenhum arquivo e pode ignorar esta etapa.

Seu DACPAC deve ser colocado em um contêiner de armazenamento do Azure. Isso pode ser um contêiner existente ou um criado especificamente para o esforço de migração. É importante garantir que o contêiner seja criado na região certa.

Azure DevOps Services está disponível em várias regiões. Quando você estiver importando para essas regiões, é fundamental colocar seus dados na região correta para garantir que a importação possa começar com êxito. Seus dados devem ser colocados na mesma região para a qual você importará. Colocar os dados em qualquer outro lugar fará com que a importação não seja capaz de iniciar. A tabela a seguir lista as regiões aceitáveis para criar sua conta de armazenamento e carregar seus dados.

Região de importação desejada Região da conta de armazenamento
Central Estados Unidos Central Estados Unidos
Europa Ocidental Europa Ocidental
Reino Unido Sul do Reino Unido
Leste da Austrália Leste da Austrália
Sul do Brasil Brazil South
Sul da Índia Sul da Índia
Canadá Central Canadá Central
Pacífico Asiático (Singapura) Pacífico Asiático (Singapura)

Embora Azure DevOps Services esteja disponível em várias regiões nos EUA, apenas a região do Estados Unidos Central aceita novas Azure DevOps Services. Você não pode importar seus dados para outras regiões do Azure dos EUA no momento.

Você pode criar um contêiner de blob a partir do portal do Azure. Depois de criar o contêiner, você precisará carregar o arquivo DACPAC de coleção.

Depois que a importação for concluída, você poderá excluir o contêiner de blob e a conta de armazenamento que acompanha. Para fazer isso, você pode usar ferramentas como o AzCopy ou qualquer outra ferramenta do Gerenciador de Armazenamento do Azure, como Gerenciador de Armazenamento do Azure.

Observação

Se o arquivo DACPAC for maior que 10 GB, recomendamos que você use o AzCopy. O AzCopy tem suporte de upload multithread para uploads mais rápidos.

Etapa 4: Gerar uma chave SAS

Uma chave SAS (assinatura de acesso compartilhado) fornece acesso delegado aos recursos em uma conta de armazenamento. A chave permite que você dê à Microsoft o nível mais baixo de privilégio necessário para acessar seus dados para executar a importação.

A maneira recomendada de gerar uma chave SAS é usar Gerenciador de Armazenamento do Azure. Com Gerenciador de Armazenamento, você pode criar facilmente chaves SAS no nível do contêiner. Isso é essencial, pois a ferramenta de migração de dados não dá suporte a chaves SAS no nível da conta.

Observação

Não gere uma chave de SAS do portal do Azure. as chaves SAS geradas por portal do Azure têm escopo de conta e não funcionam com a ferramenta de migração de dados.

Depois de instalar Gerenciador de Armazenamento, você pode gerar uma chave SAS fazendo o seguinte:

  1. Abra o Gerenciador de Armazenamento.

  2. Adicione uma conta.

  3. Selecione Usar um nome e uma chave da conta de armazenamento e selecione Conectar.

    Captura de tela do painel Conectar ao Armazenamento do Azure.

  4. No painel Anexar Armazenamento Externo , insira o nome da conta de armazenamento, forneça uma de suas duas chaves de acesso primárias e selecione Conectar.

    Captura de tela do painel Anexar Armazenamento Externo para inserir informações para se conectar à conta de armazenamento.

  5. No painel esquerdo, expanda Contêineres de Blob, clique com o botão direito do mouse no contêiner que armazena seus arquivos de importação e selecione Obter Assinatura de Acesso Compartilhado.

    Captura de tela do comando para selecionar o contêiner para criar uma chave SAS.

  6. Para o tempo de expiração, defina a data de validade para sete dias no futuro.

    Definir as propriedades necessárias e criar a chave SAS

  7. Em Permissões para sua chave SAS, selecione as caixas de seleção Leitura e Lista . Permissões de gravação e exclusão não são necessárias.

    Observação

    • Copie e armazene essa chave SAS para colocar em seu arquivo de especificação de importação na próxima etapa.
    • Trate essa chave SAS como um segredo. Ele fornece acesso aos seus arquivos no contêiner de armazenamento.

Etapa 5: Concluir a especificação de importação

No início do processo, você preencheu parcialmente o arquivo de especificação de importação geralmente conhecido como import.json. Neste ponto, você tem informações suficientes para concluir todos os campos restantes, exceto para o tipo de importação. O tipo de importação será abordado posteriormente, na seção de importação.

No arquivo de especificação import.json , em Source, conclua os seguintes campos:

  • Local: cole a chave SAS gerada do script e copiada na etapa anterior.
  • Dacpac: verifique se o arquivo, incluindo a extensão de arquivo .dacpac , tem o mesmo nome que o arquivo DACPAC que você carregou na conta de armazenamento.

Usando o exemplo fabrikam, o arquivo de especificação de importação final deve ser semelhante ao seguinte:

Captura de tela do arquivo de especificação de importação concluído.

Restringir o acesso somente a IPs Azure DevOps Services

É altamente recomendável restringir o acesso à sua conta de Armazenamento do Azure a apenas IPs de Azure DevOps Services. Você faz isso permitindo conexões somente do conjunto de IPs Azure DevOps Services envolvidos no processo de importação do banco de dados de coleção. Os IPs que precisam ter acesso à sua conta de armazenamento dependem da região para a qual você está importando. Use a opção IpList para obter a lista de IPs que precisam ter acesso concedido.

Incluídos na documentação de ajuda estão instruções e exemplos para executar o Migrator da própria instância do Azure DevOps Server e de um computador remoto. Se você estiver executando o comando de uma das camadas de aplicativo da instância Azure DevOps Server, seu comando deverá ter a seguinte estrutura:

Migrator IpList /collection:{CollectionURI} /tenantDomainName:{name} /region:{region}

Observação

Como alternativa, você também pode usar Marcas de Serviço no lugar de intervalos de IP explícitos. As Marcas de Serviço do Azure são uma maneira conveniente para os clientes gerenciarem sua configuração de rede para permitir o tráfego de serviços específicos do Azure. Os clientes podem facilmente permitir o acesso adicionando o nome da marca azuredevops aos seus grupos de segurança de rede ou firewalls por meio do portal ou programaticamente.

Determinar o tipo de importação

As importações podem ser enfileiradas como uma execução a seco ou uma execução de produção. O parâmetro ImportType determina o tipo de importação:

  • DryRun: use uma execução seca para fins de teste. O sistema exclui execuções secas após 21 dias.
  • ProductionRun: Use uma execução de produção quando quiser manter a importação resultante e usar a organização em tempo integral em Azure DevOps Services após a conclusão da importação.

Dica

Sempre recomendamos que você conclua uma importação a seco primeiro.

Arquivo de especificação de importação concluído com tipo de importação

Organizações de execução a seco

As importações de execução a seco ajudam as equipes a testar a migração de suas coleções. Espera-se que as organizações não permaneçam por aí para sempre, mas existam por um curto período de tempo. Na verdade, antes que uma migração de produção possa ser executada, todas as organizações de execução seca concluídas precisarão ser excluídas. Todas as organizações de execução a seco têm uma existência limitada e são excluídas automaticamente após um período de tempo definido. Informações sobre quando a organização será excluída são incluídas no email de sucesso que você deve receber após a conclusão da importação. Lembre-se de tomar nota dessa data e planejar adequadamente.

A maioria das organizações de execução a seco tem 15 dias antes de serem excluídas. As organizações de execução a seco também poderão ter uma expiração de 21 dias se mais de 100 usuários tiverem uma licença básica ou maior no momento da importação. Após o período de tempo especificado, a organização de execução a seco é excluída. Você pode repetir as importações de execução a seco quantas vezes precisar antes de fazer uma migração de produção. Você precisa excluir todas as execuções secas anteriores antes de tentar uma nova. Quando sua equipe estiver pronta para executar uma migração de produção, você precisará excluir manualmente a organização de execução a seco.

Para obter mais informações sobre atividades pós-importação, consulte o artigo pós-importação .

Se você encontrar problemas de importação, confira Solucionar problemas de importação e migração.

Executar uma importação

Sua equipe agora está pronta para iniciar o processo de execução de uma importação. Recomendamos que você comece com uma importação de execução a seco bem-sucedida antes de tentar uma importação de execução de produção. Com as importações de execução a seco, você pode ver com antecedência a aparência de uma importação, identificar possíveis problemas e obter experiência antes de ir para sua execução de produção.

Observação

Se você precisar repetir uma importação concluída de execução de produção para uma coleção, como no caso de uma reversão, entre em contato com Azure DevOps Services Suporte ao Cliente antes de enfileirar outra importação.

Observação

Os administradores do Azure podem impedir que os usuários criem novas organizações do Azure DevOps. Se a Azure AD política de locatário estiver ativada, sua importação não será concluída. Antes de começar, verifique se a política não está definida ou se há uma exceção para o usuário que está executando a migração. Para obter mais informações, consulte Restringir a criação da organização por meio de Azure AD política de locatário.

Observação

Azure DevOps Services não dá suporte a políticas de retenção por pipeline e elas não serão levadas para a versão hospedada.

Considerações sobre planos de reversão

Uma preocupação comum para as equipes que estão fazendo uma execução final de produção é qual será seu plano de reversão se algo der errado com a importação. É por isso que é altamente recomendável fazer uma execução seca para garantir que você seja capaz de testar as configurações de importação fornecidas à ferramenta de migração de dados para o Azure DevOps.

A reversão para a execução final de produção é bastante simples. Antes de enfileirar a importação, desanexe a coleção de projetos de equipe do Azure DevOps Server ou do Team Foundation Server, o que a tornará indisponível para os membros da equipe. Se, por qualquer motivo, você precisar reverter a execução de produção e colocar o servidor local novamente online para os membros da equipe, você poderá fazer isso. Basta anexar a coleção de projetos de equipe local novamente e informar à sua equipe que ela continuará funcionando normalmente enquanto sua equipe se reagrupa para entender possíveis falhas.

Enfileirar uma importação

Importante

Antes de continuar, verifique se sua coleção foi desanexada antes de gerar um arquivo DACPAC ou carregar o banco de dados de coleção em uma VM SQL Azure. Se você não concluir esta etapa, a importação falhará. Caso sua importação falhe, consulte Solucionar problemas de erros de importação e migração.

Inicie uma importação usando o comando de importação da ferramenta de migração de dados. O comando de importação usa um arquivo de especificação de importação como entrada. Ele analisa o arquivo para garantir que os valores fornecidos sejam válidos e, se bem-sucedidos, ele enfileira uma importação para Azure DevOps Services. O comando de importação requer uma conexão com a Internet, mas não requer uma conexão com sua instância de Azure DevOps Server.

Para começar, abra uma janela do Prompt de Comando e altere os diretórios para o caminho para a ferramenta de migração de dados. Recomendamos que você tire um momento para examinar o texto de ajuda fornecido com a ferramenta. Execute o seguinte comando para ver as diretrizes e a ajuda para o comando de importação:

Migrator import /help

O comando para enfileirar uma importação terá a seguinte estrutura:

Migrator import /importFile:{location of import specification file}

Aqui está um exemplo de um comando de importação concluído:

Migrator import /importFile:C:\DataMigrationToolFiles\import.json

Depois que a validação for aprovada, você será solicitado a entrar no Azure AD. É importante entrar com uma identidade que seja membro do mesmo locatário Azure AD que o arquivo de log do mapa de identidade foi criado. O usuário que entra se torna o proprietário da organização importada.

Observação

Cada locatário Azure AD é limitado a cinco importações por período de 24 horas. Somente importa a contagem enfileirada com esse limite.

Quando sua equipe inicia uma importação, uma notificação por email é enviada ao usuário que enfileira a importação. Cerca de 5 a 10 minutos depois que ele enfileira a importação, sua equipe pode ir à organização para verificar o status. Após a conclusão da importação, sua equipe será direcionada para entrar e uma notificação por email será enviada ao proprietário da organização.