Public/Get-GraphLegacyMapping.ps1
|
function Get-GraphLegacyMapping { <# .SYNOPSIS Resolves an AzureAD or MSOnline PowerShell command to its current Microsoft Graph PowerShell SDK equivalent. .DESCRIPTION AzureAD and MSOnline are retired; this cmdlet exists to help you migrate a script that still calls them. Get-GraphLegacyMapping looks up the legacy command name in the official AzureAD/MSOnline -> Microsoft Graph command mapping published by the Microsoft Graph PowerShell SDK team (MgLegacyCommandMapping.json), then reuses the same catalog lookup engine behind Get-GraphMapping -Cmdlet to fill in the resolved command's endpoint, HTTP method, module and (with -IncludeDetails) permissions -- none of that enrichment logic is duplicated here. Most legacy commands map to exactly one current command. A small number map to two, usually near-duplicate operations (for example an "Include"/"Exclude" policy pair); in that case Get-GraphLegacyMapping returns one record per candidate rather than guessing, and every record's Status is 'AmbiguousMapped'. This is a different question from Get-GraphMapping: Get-GraphMapping never accepts an AzureAD/MSOnline command name, and Get-GraphLegacyMapping does not resolve current Microsoft Graph command names (use Get-GraphMapping -Cmdlet for that). GraphShell never calls the Microsoft Graph API, AzureAD, or MSOnline, and does not require a connection to either. .PARAMETER Command A legacy AzureAD or MSOnline cmdlet name, for example "Get-AzureADUser" or "Get-MsolUser". .PARAMETER IncludeDetails Also load permissions, output type and documentation link for the resolved command from the matching catalog detail shard (same behavior as Get-GraphMapping -IncludeDetails). .EXAMPLE Get-GraphLegacyMapping -Command "Get-AzureADUser" Resolves to Get-MgUser, together with its endpoint(s), module and API version(s). .EXAMPLE Get-GraphLegacyMapping -Command "Get-MsolDirSyncProvisioningError" Returns more than one record (Status 'AmbiguousMapped') because the official source lists this legacy command under three different current commands. .EXAMPLE Get-GraphLegacyMapping -Command "Get-DoesNotExist" Warns and returns nothing: the name is not in the official legacy mapping. .OUTPUTS GraphShell.LegacyMapping #> [CmdletBinding()] [OutputType('GraphShell.LegacyMapping')] param( [Parameter(Mandatory, Position = 0, ValueFromPipelineByPropertyName)] [Alias('LegacyCommand', 'Name')] [ValidateNotNullOrEmpty()] [string]$Command, [switch]$IncludeDetails ) process { $legacyIndex = Get-GraphLegacyIndex if (-not $legacyIndex) { Write-Warning "GraphShell legacy command data is not available in this installation. Run scripts/sync-graph-legacy-mapping.ps1, or update GraphShell to a version that includes it." return } $candidates = $null if (-not $legacyIndex.ByLegacyCommand.TryGetValue($Command, [ref]$candidates)) { Write-Warning "GraphShell found no AzureAD/MSOnline -> Microsoft Graph mapping for '$Command'. It may already be a current Microsoft Graph command -- try Get-GraphMapping -Cmdlet instead." return } $status = if ($candidates.Count -gt 1) { 'AmbiguousMapped' } else { 'Mapped' } $renameIndex = Get-GraphRenameIndex $emitted = 0 foreach ($graphCommand in $candidates) { $mappings = Resolve-GraphCmdletMapping -Cmdlet $graphCommand -RenameIndex $renameIndex -IncludeDetails:$IncludeDetails if (-not $mappings -or $mappings.Count -eq 0) { $emitted++ [pscustomobject]@{ PSTypeName = 'GraphShell.LegacyMapping' LegacyCommand = $Command GraphCommand = $graphCommand Module = $null ModuleName = $null Method = $null Endpoint = $null ApiVersion = $null Permissions = $null Status = 'MappedCommandNotInCatalog' } continue } foreach ($mapping in $mappings) { $emitted++ [pscustomobject]@{ PSTypeName = 'GraphShell.LegacyMapping' LegacyCommand = $Command GraphCommand = $mapping.Cmdlet Module = $mapping.Module ModuleName = $mapping.ModuleName Method = $mapping.Method Endpoint = $mapping.Endpoint ApiVersion = $mapping.ApiVersion Permissions = $mapping.Permissions Status = $status } } } if ($emitted -eq 0) { Write-Warning "GraphShell found a legacy mapping for '$Command' but could not resolve any of the target command(s) in the current catalog." } } } |