Migrar o Azure PowerShell do AzureRM para o AzMigrate Azure PowerShell from AzureRM to Az

O módulo Az tem paridade de recursos com o AzureRM, mas usa nomes de cmdlets menores e mais consistentes.The Az module has feature parity with AzureRM, but uses shorter and more consistent cmdlet names. Os scripts gravados para os cmdlets do AzureRM não funcionarão automaticamente com o novo módulo.Scripts written for the AzureRM cmdlets won't automatically work with the new module. Para facilitar a transição, o Az oferece ferramentas para permitir a execução de seus scripts existentes usando o AzureRM.To make the transition easier, Az offers tools to allow you to run your existing scripts using AzureRM. A migração para um novo conjunto de comandos nem sempre é conveniente, mas este artigo ajudará você a começar a realizar a transição para o novo módulo.No migration to a new command set is ever convenient, but this article will help you get started on transitioning to the new module.

Para ver a lista completa de alterações da falha entre o AzureRM e o Az, confira as alterações completas do AzureRM para o Az.To see the full list of breaking changes between AzureRM and Az, see the full changes from AzureRM to Az.

Verifique se os scripts existentes funcionam com a última versão do AzureRMEnsure existing scripts work with the latest AzureRM release

Antes de executar qualquer etapa de migração, verifique quais versões do AzureRM estão instaladas em seu sistema.Before taking any migration steps, check which versions of AzureRM are installed on your system. Esse procedimento permite que você verifique se os scripts já estão em execução na última versão e se você sabe quais versões do AzureRM precisam ser desinstaladas.Doing so allows you to make sure scripts are already running on the latest release, and let you know which versions of AzureRM must be uninstalled.

Para verificar qual versão do AzureRM você instalou, execute o comando:To check which version(s) of AzureRM you have installed, run the command:

Get-InstalledModule -Name AzureRM -AllVersions

A última versão disponível do AzureRM é a 6.13.1.The latest available release of AzureRM is 6.13.1. Se você não tiver essa versão instalada, os scripts existentes poderão precisar de modificação adicional para trabalhar com o módulo Az, além do que foi descrito aqui e na lista de alterações da falha.If you don't have this version installed, your existing scripts may need additional modification to work with the Az module beyond what's described here and in the breaking changes list.

Se os scripts não funcionarem com o AzureRM 6.13.1, atualize-os de acordo com o guia de migração do AzureRM 5.x para o 6.x.If your scripts don't work with AzureRM 6.13.1, update them according to the AzureRM 5.x to 6.x migration guide. Se você usar uma versão anterior do módulo AzureRM, haverá guias de migração disponíveis para cada versão principal.If you use an earlier version of the AzureRM module, there are migration guides available for each major version.

Desinstalar o AzureRMUninstall AzureRM

Não há nenhuma garantia de que o módulo Az seja compatível com as instalações existentes do AzureRM no PowerShell 5.1 para Windows.The Az module is not guaranteed to be compatible with any existing AzureRM installs in PowerShell 5.1 for Windows. Antes de instalar o módulo Az, desinstale o AzureRM.Before you install the Az module, uninstall AzureRM.

Importante

Se não estiver pronto para remover o módulo AzureRM do sistema, instale o módulo Az para o PowerShell Core 6.x ou posterior.If you're not ready to remove the AzureRM module from your system, you can install the Az module for PowerShell Core 6.x or later instead. O PowerShell Core e o PowerShell 5.1 para Windows usam bibliotecas de módulo diferentes e, portanto, não haverá nenhum conflito.PowerShell Core and PowerShell 5.1 for Windows use different module libraries, so there will be no conflicts. Você ainda poderá habilitar aliases no PowerShell Core.You can still enable aliases in PowerShell Core.

Instalar o módulo Az do Azure PowerShellInstall the Azure PowerShell Az module

A primeira etapa é instalar o módulo Az em sua plataforma.The first step is to install the Az module on your platform. Quando você instala o Az, é recomendável desinstalar o AzureRM.When you install Az, it's recommended that you uninstall AzureRM. Nas etapas a seguir, você aprenderá como continuar executando seus scripts existentes e habilitar a compatibilidade para os nomes de cmdlet antigos.In the following steps, you'll learn how to keep running your existing scripts and enable compatibility for old cmdlet names.

Para instalar o módulo Az do Azure PowerShell, siga as instruções descritas em Instalar o módulo Az.To install the Azure PowerShell Az module, follow the instructions in Install the Az module.

Observação

Nesta altura, o ideal é executar o cmdlet Uninstall-AzureRM fornecido no módulo Az, apenas para ter certeza de que todas as versões do AzureRM foram desinstaladas e não causarão conflitos.At this point, you might want to run the Uninstall-AzureRM cmdlet provided in the Az module, just to make sure that all versions of AzureRM have been uninstalled and won't cause conflicts.

Habilitar aliases de compatibilidade do AzureRMEnable AzureRM compatibility aliases

Com o AzureRM desinstalado e seus scripts funcionando com a versão mais recente do AzureRM, a próxima etapa é habilitar o modo de compatibilidade para o módulo Az.With AzureRM uninstalled and your scripts working with the latest AzureRM version, the next step is to enable the compatibility mode for the Az module. A compatibilidade é habilitada com o comando:Compatibility is enabled with the command:

Enable-AzureRmAlias -Scope CurrentUser

Os aliases permitem a capacidade de usar nomes de cmdlets antigos com o módulo Az instalado.Aliases enable the ability to use old cmdlet names with the Az module installed. Esses aliases são gravados no perfil do escopo selecionado.These aliases are written to the profile for the selected scope. Se não existir nenhum perfil, um perfil será criado.If no profile exists, one is created. Ao usar um -Scope mais abrangente que CurrentUser, as permissões apropriadas serão necessárias para criar ou atualizar o arquivo de perfil correspondente.When using a -Scope broader than CurrentUser, the appropriate permissions are required to create or update the corresponding profile file.

Importante

Somente os nomes dos cmdlets são convertidos em alias – os nomes dos módulos não.Only cmdlet names are aliased - module names aren't! Se você estiver usando #Requires, Import-Module, listas de dependência em um .psd1 ou nomes de cmdlets totalmente qualificados, migre-os neste momento seguindo o processo descrito na lista de alterações da falha referente a nomes de módulos.If you're using #Requires, Import-Module, dependency lists in a .psd1, or fully-qualified cmdlet names, make sure that you migrate them at this point by following the process outlined in the breaking changes list regarding module names.

Aviso

Você pode usar outro -Scope para este comando, mas isso não é recomendado.You can use a different -Scope for this command, but it's not recommended. Os aliases são gravados no perfil do usuário do escopo escolhido, portanto, mantenha-os habilitados para um escopo o mais limitado possível.Aliases are written to the user profile for the selected scope, so keep enabling them to as limited a scope as possible. A habilitação de aliases em todo o sistema pode causar problemas para outros usuários que têm o AzureRM instalado em seu escopo local.Enabling aliases system-wide can cause issues for other users who have AzureRM installed in their local scope.

Após habilitar o modo de alias, execute seus scripts novamente para confirmar que eles ainda funcionam conforme o esperado.Once the alias mode is enabled, run your scripts again to confirm that they still function as expected. Alguns nomes de parâmetros foram alterados, adicionados ou se tornaram obrigatórios para o módulo Az.Some parameter names have been changed, added, or made required by the Az module. Os tipos de saída dos cmdlets também podem ter sido alterados.Output types of cmdlets may have changed as well. Essas alterações são detalhadas na lista de alterações da falha.These changes are detailed in the breaking changes list.

Atualizar cmdlets, módulos e parâmetrosUpdate cmdlets, modules, and parameters

Com os scripts atualizados e em execução com aliases, você pode aproveitar seu tempo para atualizá-los para usar os novos cmdlets e aproveitar outras alterações, como novos recursos.With scripts updated and running under aliases, you can take your time to update them to use the new cmdlets and take advantage of other changes like new features. Para a maioria dos scripts, você só precisará atualizar os nomes dos cmdlets seguindo o novo esquema de nomeação de cmdlets do Az.For most scripts, you will only need to update cmdlet names, following the new cmdlet naming scheme in Az. Também poderá haver outras alterações que você precise fazer para que os scripts funcionem, dependendo do que eles fazem e de quais recursos do Azure PowerShell eles utilizam.There may also be some other changes that you need to make in order to have your scripts work, depending on what they do and which Azure PowerShell features they take advantage of.

Por exemplo, os cmdlets do Armazenamento de Blobs foram completamente reformulados para usar um novo modelo assíncrono, de modo que os scripts que os utilizarem exigirão mais trabalho para serem atualizados do que aqueles em que apenas as alterações relevantes foram nomes dos cmdlets.For example, the Blob Storage cmdlets have been completely reworked to use a new asynchronous model, so scripts using them will take more work to update than those where the only relevant changes were cmdlet names.

Mesmo que você precise fazer apenas pequenas alterações simples nos scripts até este ponto – ou que eles funcionam mesmo sem modificações adicionais quando os aliases são habilitados, leia a lista completa das alterações da falha no Az 1.0.0 para verificar se você não depende do comportamento 'transparente' de aliases, que poderá desaparecer após a alteração dos nomes dos cmdlets e a desabilitação de aliases.Even if you've only had to make small, simple changes to your scripts up to this point - or they even work without additional modification when aliases are enabled - read the full list of breaking changes in Az 1.0.0 to make sure that you're not relying on 'transparent' behavior of aliases which could disappear after you change cmdlet names and disable aliases.

Desabilitar aliasesDisable aliases

Depois que você concluir a migração e não depender mais do comportamento de nome alternativo, será recomendável que você desabilite os aliases.Once you've completed your migration and are no longer relying on aliasing behavior, it's recommended that you disable aliases. Isso é feito com o cmdlet Disable-AzureRmAlias.This is done with the Disable-AzureRmAlias cmdlet.

Importante

Ao executar esse cmdlet lembre-se de invocá-lo para cada -Scope para o qual Enable-AzureRmAlias foi invocado; caso contrário, ainda poderá haver scripts no sistema dependentes do comportamento de nome alternativo.When running this cmdlet, make sure that you invoke it for each -Scope that Enable-AzureRmAlias was invoked for, otherwise there may still be scripts on your system relying on the aliasing behavior.