Automatyczne migrowanie skryptów programu PowerShell z modułu AzureRM do modułu Az programu PowerShell

Artykuł
02/11/2025

W tym artykule dowiesz się, jak za pomocą modułu Az.Tools.Migration programu PowerShell automatycznie uaktualnić skrypty programu PowerShell i moduły skryptów z modułu AzureRM do modułu Az programu PowerShell. Aby uzyskać dodatkowe opcje migracji, zobacz Migrate Azure PowerShell from AzureRM to Az.

Ostrzeżenie

Moduł AzureRM PowerShell został oficjalnie wycofany z użycia z dniem 29 lutego 2024 r. Zaleca się migrowanie użytkowników z modułu AzureRM do modułu Az programu PowerShell w celu zapewnienia ciągłej obsługi i aktualizacji.

Choć moduł AzureRM może nadal działać, nie jest już utrzymywany ani obsługiwany, więc dalsze jego używanie odbywa się na własne ryzyko i według uznania użytkownika. Zapoznaj się z naszymi zasobami migracji , aby uzyskać wskazówki dotyczące przejścia do modułu Az.

Wymagania

Zaktualizuj istniejące skrypty programu PowerShell do najnowszej wersji modułu AzureRM PowerShell (6.13.1).
Zainstaluj moduł Az.Tools.Migration programu PowerShell.
```
Install-Module -Name Az.Tools.Migration
```

Krok 1. Generowanie planu uaktualniania

Polecenie cmdlet New-AzUpgradeModulePlan służy do generowania planu aktualizacji w celu migracji skryptów i modułów do modułu Az w programie PowerShell. To polecenie cmdlet nie wprowadza żadnych zmian w istniejących skryptach. Użyj parametru FilePath do określania wartości docelowej określonego skryptu lub parametru DirectoryPath do określania wartości docelowej dla wszystkich skryptów w określonym folderze.

Notatka

Polecenie cmdlet New-AzUpgradeModulePlan nie wykonuje planu, generuje tylko kroki uaktualniania.

Poniższy przykład generuje plan dla wszystkich skryptów w folderze C:\Scripts. Parametr OutVariable jest określony, więc wyniki są zwracane i jednocześnie przechowywane w zmiennej o nazwie 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

Jak pokazano w poniższych danych wyjściowych, plan uaktualniania zawiera szczegóły określonego pliku i punktów przesunięcia, które wymagają zmian podczas przechodzenia z modułu AzureRM do poleceń cmdlet programu PowerShell Az.

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
...

Przed przeprowadzeniem uaktualnienia należy sprawdzić plan pod kątem problemów. Poniższy przykład zwraca listę skryptów i elementów w tych skryptach, które uniemożliwią ich automatyczne uaktualnianie.

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

Elementy wyświetlane w poniższych danych wyjściowych nie zostaną automatycznie uaktualnione bez ręcznego rozwiązywania problemów.

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            :

Krok 2. Wykonanie uaktualnienia

Ostrożność

Nie ma funkcji cofania. Zawsze upewnij się, że masz kopię zapasową skryptów i modułów programu PowerShell, które próbujesz uaktualnić.

Po zaakceptowaniu planu przystępujesz do uaktualnienia za pomocą polecenia cmdlet Invoke-AzUpgradeModulePlan. Określ SaveChangesToNewFiles dla wartości parametru FileEditMode, aby zapobiec zmianom wprowadzanym w oryginalnych skryptach. W przypadku korzystania z tego trybu, aktualizacja jest wykonywana przez utworzenie kopii każdego skryptu z docelowym dołączeniem _az_upgraded do nazw plików.

Ostrzeżenie

Polecenie cmdlet Invoke-AzUpgradeModulePlan jest groźne, gdy określona jest opcja -FileEditMode ModifyExistingFiles! Modyfikuje skrypty i funkcje zgodnie z planem uaktualniania modułu wygenerowany przez polecenie cmdlet New-AzUpgradeModulePlan. W przypadku opcji niedestrukcyjnej określ -FileEditMode SaveChangesToNewFiles zamiast tego.

# 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
...

Jeśli zostaną zwrócone jakiekolwiek błędy, możesz przyjrzeć się bliżej wynikom błędów, używając następującego polecenia:

# 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            :

Ograniczenia

Operacje we/wy plików używają domyślnego kodowania. Nietypowe sytuacje kodowania plików mogą powodować problemy.
Polecenia cmdlet modułu AzureRM przekazane jako argumenty do makiet testów jednostkowych Pester nie są wykrywane.

Jak zgłaszać problemy

Zgłoś opinie i problemy dotyczące modułu Az.Tools.Migration programu PowerShell, używając zgłoszenia na GitHubie w repozytorium azure-powershell-migration.

Następne kroki

Aby dowiedzieć się więcej na temat modułu Az programu PowerShell, zobacz dokumentację programu Azure PowerShell

Udostępnij za pośrednictwem