Migración automática de scripts de PowerShell de AzureRM al módulo Az de PowerShell

En este artículo, aprenderá a usar el módulo Az.Tools.Migration de PowerShell para actualizar automáticamente los scripts y los módulos de scripts de PowerShell de AzureRM al módulo Az de PowerShell. Para conocer opciones de migración adicionales, consulte Migración de Azure PowerShell de AzureRM a Az.

Advertencia

El módulo AzureRM PowerShell ha quedado oficialmente obsoleto a partir del 29 de febrero de 2024. Se recomienda a los usuarios migrar de AzureRM al módulo Az PowerShell para seguir recibiendo soporte técnico y actualizaciones.

Aunque el módulo AzureRM puede seguir funcionando, ya no recibirá mantenimiento ni soporte técnico, lo que significa que su uso continuado queda a discreción y riesgo del usuario. Consulte nuestros recursos de migración para ver una guía sobre la transición al módulo Az.

Requisitos

  • Actualice los scripts de PowerShell existentes a la versión más reciente del módulo AzureRM de PowerShell (6.13.1).

  • Instale el módulo Az.Tools.Migration de PowerShell.

    Install-Module -Name Az.Tools.Migration
    

Paso 1: Generación de un plan de actualización

Use el cmdlet New-AzUpgradeModulePlan para generar un plan de actualización para migrar los scripts y los módulos al módulo Az de PowerShell. Este cmdlet no realiza ningún cambio en los scripts existentes. Use el parámetro FilePath para establecer como destino un script específico o el parámetro DirectoryPath para todos los scripts de una carpeta determinada.

Nota

El cmdlet New-AzUpgradeModulePlan no ejecuta el plan, solo genera los pasos de actualización.

En el ejemplo siguiente se genera un plan para todos los scripts de la carpeta C:\Scripts . Se especifica el parámetro OutVariable para que los resultados se devuelvan y se almacenen simultáneamente en una variable llamada Plan .

# Generate an upgrade plan for all the scripts and module files in the specified folder and save it to a variable.
New-AzUpgradeModulePlan -FromAzureRmVersion 6.13.1 -ToAzVersion latest -DirectoryPath 'C:\Scripts' -OutVariable Plan

Como se muestra en la siguiente salida, en el plan de actualización se detallan el archivo y los puntos de desplazamiento específicos que requieren cambios al pasar de los cmdlets de AzureRM a los del módulo Az de PowerShell.

Order Location                                                   UpgradeType     PlanResult             Original
----- --------                                                   -----------     ----------             --------
1     compute-create-dockerhost.ps1:59:24                        CmdletParameter ReadyToUpgrade         ExtensionName
2     compute-create-dockerhost.ps1:59:1                         Cmdlet          ReadyToUpgrade         Set-AzureRmVM...
3     compute-create-dockerhost.ps1:54:1                         Cmdlet          ReadyToUpgrade         New-AzureRmVM
4     compute-create-dockerhost.ps1:51:1                         Cmdlet          ReadyToUpgrade         Add-AzureRmVM...
5     compute-create-dockerhost.ps1:47:1                         Cmdlet          ReadyToUpgrade         Add-AzureRmVM...
6     compute-create-dockerhost.ps1:46:1                         Cmdlet          ReadyToUpgrade         Set-AzureRmVM...
7     compute-create-dockerhost.ps1:45:1                         Cmdlet          ReadyToUpgrade         Set-AzureRmVM...
8     compute-create-dockerhost.ps1:44:13                        Cmdlet          ReadyToUpgrade         New-AzureRmVM...
9     compute-create-dockerhost.ps1:40:8                         Cmdlet          ReadyToUpgrade         New-AzureRmNe...
10    compute-create-dockerhost.ps1:36:8                         Cmdlet          ReadyToUpgrade         New-AzureRmNe...
11    compute-create-dockerhost.ps1:31:16                        Cmdlet          ReadyToUpgrade         New-AzureRmNe...
12    compute-create-dockerhost.ps1:26:15                        Cmdlet          ReadyToUpgrade         New-AzureRmNe...
13    compute-create-dockerhost.ps1:22:8                         Cmdlet          ReadyToUpgrade         New-AzureRmPu...
14    compute-create-dockerhost.ps1:18:9                         Cmdlet          ReadyToUpgrade         New-AzureRmVi...
15    compute-create-dockerhost.ps1:15:17                        Cmdlet          ReadyToUpgrade         New-AzureRmVi...
16    compute-create-dockerhost.ps1:12:1                         Cmdlet          ReadyToUpgrade         New-AzureRmRe...
17    compute-create-windowsvm-quick.ps1:18:3                    CmdletParameter ReadyToUpgrade         ImageName
18    compute-create-windowsvm-quick.ps1:14:1                    Cmdlet          ReadyToUpgrade         New-AzureRmVM
19    compute-create-windowsvm-quick.ps1:11:1                    Cmdlet          ReadyToUpgrade         New-AzureRmRe...
20    compute-create-wordpress-mysql.ps1:59:24                   CmdletParameter ReadyToUpgrade         ExtensionName
...

Antes de realizar la actualización, debe ver los resultados del plan para detectar posibles problemas. En el ejemplo siguiente se devuelve una lista de los scripts y los elementos de esos scripts que impedirán que se actualicen automáticamente.

# Filter plan results to only warnings and errors
$Plan | Where-Object PlanResult -ne ReadyToUpgrade | Format-List

Si no se corrigen antes manualmente estos problemas, los elementos que aparecen en la siguiente salida no se actualizarán de forma automática.

Order                  : 42
UpgradeType            : CmdletParameter
PlanResult             : ErrorParameterNotFound
PlanSeverity           : Error
PlanResultReason       : Parameter was not found in Get-AzResource or it's aliases.
SourceCommand          : CommandReference
SourceCommandParameter : CommandReferenceParameter
Location               : devtestlab-add-marketplace-image-to-lab.ps1:14:74
FullPath               : C:\Scripts\devtestlab-add-marketplace-image-to-lab.ps1
StartOffset            : 556
Original               : ResourceNameEquals
Replacement            :

Paso 2: Realización de la actualización

Precaución

No hay operación de deshacer. Asegúrese siempre de que tiene una copia de seguridad de los scripts y los módulos de PowerShell que intenta actualizar.

Una vez que esté satisfecho con el plan, la actualización se realiza con el cmdlet Invoke-AzUpgradeModulePlan . Especifique SaveChangesToNewFiles para el valor del parámetro FileEditMode para impedir que se realicen cambios en los scripts originales. Al usar este modo, la actualización se realiza mediante la creación de una copia de cada script del destino con _az_upgraded anexado a los nombres de archivo.

Advertencia

El cmdlet Invoke-AzUpgradeModulePlan es destructivo cuando se especifica la opción -FileEditMode ModifyExistingFiles. Modifica los scripts y las funciones implementadas según el plan de actualización de módulos generado por el cmdlet New-AzUpgradeModulePlan. Para la opción no destructiva, especifique -FileEditMode SaveChangesToNewFiles en su lugar.

# Execute the automatic upgrade plan and save the results to a variable.
Invoke-AzUpgradeModulePlan -Plan $Plan -FileEditMode SaveChangesToNewFiles -OutVariable Results
Order Location                                                   UpgradeType     UpgradeResult    Original
----- --------                                                   -----------     -------------    --------
1     compute-create-dockerhost.ps1:59:24                        CmdletParameter UpgradeCompleted ExtensionName
2     compute-create-dockerhost.ps1:59:1                         Cmdlet          UpgradeCompleted Set-AzureRmVMExtens...
3     compute-create-dockerhost.ps1:54:1                         Cmdlet          UpgradeCompleted New-AzureRmVM
4     compute-create-dockerhost.ps1:51:1                         Cmdlet          UpgradeCompleted Add-AzureRmVMSshPub...
5     compute-create-dockerhost.ps1:47:1                         Cmdlet          UpgradeCompleted Add-AzureRmVMNetwor...
6     compute-create-dockerhost.ps1:46:1                         Cmdlet          UpgradeCompleted Set-AzureRmVMSource...
7     compute-create-dockerhost.ps1:45:1                         Cmdlet          UpgradeCompleted Set-AzureRmVMOperat...
8     compute-create-dockerhost.ps1:44:13                        Cmdlet          UpgradeCompleted New-AzureRmVMConfig
9     compute-create-dockerhost.ps1:40:8                         Cmdlet          UpgradeCompleted New-AzureRmNetworkI...
10    compute-create-dockerhost.ps1:36:8                         Cmdlet          UpgradeCompleted New-AzureRmNetworkS...
11    compute-create-dockerhost.ps1:31:16                        Cmdlet          UpgradeCompleted New-AzureRmNetworkS...
12    compute-create-dockerhost.ps1:26:15                        Cmdlet          UpgradeCompleted New-AzureRmNetworkS...
13    compute-create-dockerhost.ps1:22:8                         Cmdlet          UpgradeCompleted New-AzureRmPublicIp...
14    compute-create-dockerhost.ps1:18:9                         Cmdlet          UpgradeCompleted New-AzureRmVirtualN...
15    compute-create-dockerhost.ps1:15:17                        Cmdlet          UpgradeCompleted New-AzureRmVirtualN...
16    compute-create-dockerhost.ps1:12:1                         Cmdlet          UpgradeCompleted New-AzureRmResource...
17    compute-create-windowsvm-quick.ps1:18:3                    CmdletParameter UpgradeCompleted ImageName
18    compute-create-windowsvm-quick.ps1:14:1                    Cmdlet          UpgradeCompleted New-AzureRmVM
19    compute-create-windowsvm-quick.ps1:11:1                    Cmdlet          UpgradeCompleted New-AzureRmResource...
20    compute-create-wordpress-mysql.ps1:59:24                   CmdletParameter UpgradeCompleted ExtensionName
...

Si se devuelven errores, puede examinar con más detalle los resultados del error con el siguiente comando:

# Filter results to show only errors
$Results | Where-Object UpgradeResult -ne UpgradeCompleted | Format-List
Order                  : 42
UpgradeType            : CmdletParameter
UpgradeResult          : UnableToUpgrade
UpgradeSeverity        : Error
UpgradeResultReason    : Parameter was not found in Get-AzResource or it's aliases.
SourceCommand          : CommandReference
SourceCommandParameter : CommandReferenceParameter
Location               : devtestlab-add-marketplace-image-to-lab.ps1:14:74
FullPath               : C:\Scripts\devtestlab-add-marketplace-image-to-lab.ps1
StartOffset            : 556
Original               : ResourceNameEquals
Replacement            :

Limitaciones

  • Las operaciones de E/S de archivos usan la codificación predeterminada. Las situaciones inusuales de codificación de archivos pueden causar problemas.
  • No se detectan los cmdlets de AzureRM que se pasan como argumentos a las instrucciones ficticias de pruebas unitarias de Pester.

Notificación de problemas

Informe de los comentarios y problemas relacionados con el módulo Az.Tools.Migration de PowerShell mediante un problema de GitHub en el repositorio azure-powershell-migration.

Pasos siguientes

Para más información sobre el módulo Az de PowerShell, consulte la documentación de Azure PowerShell.