Ithy - Transitioning from Get-MsolUser to Microsoft Graph PowerShell

Key Highlights of the Migration

Microsoft Graph PowerShell is the recommended replacement: The MSOnline and Azure AD PowerShell modules are being retired, and Microsoft Graph PowerShell is the official successor for managing Microsoft Entra ID (formerly Azure AD).
Cmdlet naming convention changes: Microsoft Graph PowerShell cmdlets generally follow a Get-Mg, Set-Mg, etc., naming convention, replacing the older Get-Msol or Get-AzureAD prefixes.
Functionality may require different approaches: While there are direct cmdlet replacements, some functionalities previously available as properties on a single object (like errors from Get-MsolUser) might require separate cmdlets or API calls in Microsoft Graph PowerShell.

Understanding the Shift to Microsoft Graph PowerShell

Microsoft has been actively transitioning its administrative tools and APIs towards the Microsoft Graph. This includes the deprecation and eventual retirement of the legacy MSOnline and Azure AD PowerShell modules. The recommended path forward for managing Microsoft Entra ID is to use the Microsoft Graph PowerShell SDK.

The move to Microsoft Graph offers a unified endpoint for accessing data and intelligence across Microsoft 365 services. While this provides enhanced capabilities and a more consistent experience, it requires adapting existing scripts and workflows that rely on the older modules.

One common task performed with the MSOnline module was retrieving user information using the Get-MsolUser cmdlet. The user's query specifically asks how to replace a command structure like Get-MsolUser -UserPrincipalName $cpa.EmailAddress[$i] -ErrorAction Stop with its Microsoft Graph equivalent.

Why the Change?

The primary reason for this transition is to standardize access to Microsoft 365 data and services through a single API: Microsoft Graph. This approach provides several benefits, including:

A unified programming model across Microsoft 365.
Access to a wider range of data and insights.
Improved security and performance.
Regular updates and new features aligned with the Graph API.

While the legacy modules served their purpose, the Microsoft Graph PowerShell SDK represents the future of Microsoft 365 automation and administration.

Identifying the Microsoft Graph Equivalent Cmdlet

The direct equivalent to the Get-MsolUser cmdlet in Microsoft Graph PowerShell is Get-MgUser. This follows the new naming convention where 'Msol' or 'AzureAD' prefixes are replaced with 'Mg'.

Finding the Right Cmdlet

Microsoft provides a cmdlet map that helps in finding the corresponding Microsoft Graph PowerShell cmdlets for the deprecated Azure AD and MSOnline cmdlets. This map is an essential resource during the migration process.

Based on the cmdlet map, Get-MsolUser is indeed replaced by Get-MgUser.

To use Get-MgUser to retrieve a user by their User Principal Name (UPN), you would typically use the -UserId parameter. This parameter accepts the user's object ID or UPN.

Translating the Command Structure

The original command Get-MsolUser -UserPrincipalName $cpa.EmailAddress[$i] -ErrorAction Stop does two main things:

Retrieves a user based on their User Principal Name provided by $cpa.EmailAddress[$i].
Uses -ErrorAction Stop to halt the script execution if an error occurs during the cmdlet execution.

Replacing the UserPrincipalName Parameter

In Get-MgUser, the equivalent parameter for specifying the user is -UserId. So, the first part of the translation is straightforward:

Get-MgUser -UserId $cpa.EmailAddress[$i]

It's important to ensure that $cpa.EmailAddress[$i] contains a valid User Principal Name or the user's object ID.

Here's an image illustrating the concept of getting user information in Microsoft 365, which Get-MgUser facilitates:

Displaying user information using PowerShell

Displaying user information using PowerShell

Handling Error Action

The -ErrorAction Stop parameter in PowerShell is a common parameter that controls how the cmdlet responds to a non-terminating error. This parameter is still available and functions similarly with Microsoft Graph PowerShell cmdlets.

Therefore, you can directly include -ErrorAction Stop in your Get-MgUser command:

Get-MgUser -UserId $cpa.EmailAddress[$i] -ErrorAction Stop

This ensures that your script will stop if the Get-MgUser cmdlet encounters an error, such as the user not being found.

Considering Permissions

A critical aspect when working with Microsoft Graph PowerShell is understanding and granting the necessary permissions. Unlike the legacy modules where permissions were often broader, Microsoft Graph follows a principle of least privilege. You need to connect to the Microsoft Graph with the appropriate scopes (permissions) to perform specific actions.

For Get-MgUser, you typically need the User.Read.All or User.ReadWrite.All permission, depending on the specific properties you are trying to retrieve or modify. When you connect using Connect-MgGraph, you can specify the required scopes:

Connect-MgGraph -Scopes "User.Read.All"

If you don't have the necessary permissions, the Get-MgUser cmdlet will likely return an access denied error.

Addressing Potential Differences and Complexities

While the direct replacement for Get-MsolUser for retrieving user information is Get-MgUser, there are some nuances and scenarios where a simple one-to-one translation might not be sufficient.

Retrieving Specific Properties

In the MSOnline module, Get-MsolUser often returned a wide range of user properties by default. In Microsoft Graph PowerShell, you might need to explicitly select the properties you require using the -Property parameter for efficiency, especially when dealing with a large number of users.

For example, to get the DisplayName and UserPrincipalName:

Get-MgUser -UserId $cpa.EmailAddress[$i] -Property DisplayName, UserPrincipalName

Handling Provisioning Errors

The original Get-MsolUser cmdlet had the ability to easily report on user provisioning errors using properties like Errors or the -HasErrorsOnly parameter. In Microsoft Graph, this information is exposed through the serviceProvisioningErrors property on the user object. However, accessing this might require expanding the property or making additional calls.

Here's an example of how you might access provisioning errors using the Graph API (which the PowerShell SDK interacts with):

# This is a conceptual example and might require adjustment based on specific needs
$user = Get-MgUser -UserId $cpa.EmailAddress[$i] -Property serviceProvisioningErrors
if ($user.ServiceProvisioningErrors) {
    $user.ServiceProvisioningErrors | ForEach-Object {
        Write-Error "Provisioning Error: $($_.Message)"
    }
}

Retrieving provisioning errors was a point of concern during the transition, as the direct equivalent wasn't immediately obvious or as straightforward as with Get-MsolUser. However, the functionality is available through the Graph API and accessible via the PowerShell SDK.

Working with Paging

When retrieving a large number of users, both modules employ paging. However, the implementation details might differ. Be mindful of how to handle pagination in your scripts when migrating to ensure you retrieve all necessary results.

Filtering and Searching

Filtering and searching for users in Microsoft Graph PowerShell is done using OData query parameters, which can be different from the filtering syntax used in the MSOnline module. The -Filter and -Search parameters in Get-MgUser utilize this syntax.

Here's an image related to filtering with Get-MgUser, highlighting the need for parameters like ConsistencyLevel for certain advanced queries:

Filtering with Get-MgUser

Filtering with Get-MgUser, illustrating the need for parameters like ConsistencyLevel

Practical Migration Steps

Migrating scripts from the MSOnline module to Microsoft Graph PowerShell involves several steps:

Install the Microsoft Graph PowerShell SDK: Ensure you have the necessary module installed. You can install it from the PowerShell Gallery using Install-Module Microsoft.Graph.
Analyze existing scripts: Identify all instances where MSOnline or Azure AD cmdlets are used.
Find equivalent Graph cmdlets: Use the Microsoft cmdlet map and the Find-MgGraphCommand cmdlet to find the corresponding Microsoft Graph PowerShell cmdlets.
Understand parameter changes: Note the differences in parameter names and how to achieve the same functionality.
Review required permissions: Determine the necessary Microsoft Graph permissions for each cmdlet used in your script.
Connect to Microsoft Graph: Update your connection method to use Connect-MgGraph with the appropriate scopes.
Rewrite and test scripts: Rewrite the sections of your scripts that use the old cmdlets and thoroughly test them in your environment.

Using Find-MgGraphCommand

The Find-MgGraphCommand cmdlet is very useful for discovering Microsoft Graph PowerShell cmdlets based on their functionality or the legacy cmdlet they replace. For example, to find cmdlets related to users:

Find-MgGraphCommand -Command 'Get-MsolUser'

This will help you identify the Get-MgUser cmdlet and potentially other related cmdlets.

Referring to Documentation and Examples

The Microsoft Graph PowerShell documentation is continuously updated and provides detailed information on cmdlets, parameters, and examples. Referencing this documentation is crucial during the migration process.

Online communities and forums like Microsoft Q&A and Reddit's PowerShell and sysadmin communities are also valuable resources for finding solutions to specific migration challenges and learning from others' experiences.

Example of a Migrated Script Snippet

Let's consider a simple loop that iterates through a list of UPNs and retrieves user information using the legacy module:

$userList = @("user1@contoso.com", "user2@contoso.com")
for ($i = 0; $i -lt $userList.Length; $i++) {
    try {
        $user = Get-MsolUser -UserPrincipalName $userList[$i] -ErrorAction Stop
        Write-Host "Found user: $($user.DisplayName)"
    } catch {
        Write-Error "Error retrieving user: $($userList[$i]) - $($_.Exception.Message)"
    }
}

Here's how you might rewrite this using Microsoft Graph PowerShell:

# Connect to Microsoft Graph with necessary scope
Connect-MgGraph -Scopes "User.Read.All"

$userList = @("user1@contoso.com", "user2@contoso.com")
for ($i = 0; $i -lt $userList.Length; $i++) {
    try {
        $user = Get-MgUser -UserId $userList[$i] -ErrorAction Stop
        Write-Host "Found user: $($user.DisplayName)"
    } catch {
        Write-Error "Error retrieving user: $($userList[$i]) - $($_.Exception.Message)"
    }
}

This example demonstrates the direct replacement of the cmdlet and parameter. However, for more complex scenarios involving filtering, selecting specific properties, or handling errors, the translated code might be more involved.

Comparing Cmdlets: MSOnline vs. Microsoft Graph PowerShell

The following table provides a comparison of some common MSOnline cmdlets and their Microsoft Graph PowerShell equivalents:

MSOnline Cmdlet	Microsoft Graph PowerShell Cmdlet	Description
`Get-MsolUser`	`Get-MgUser`	Retrieves user information.
`Set-MsolUser`	`Update-MgUser`	Modifies user properties.
`New-MsolUser`	`New-MgUser`	Creates a new user.
`Remove-MsolUser`	`Remove-MgUser`	Deletes a user.
`Get-MsolGroup`	`Get-MgGroup`	Retrieves group information.
`Add-MsolGroupMember`	`New-MgGroupMember` (often with `-DirectoryObjectId`)	Adds a member to a group.
`Set-MsolUserLicense`	`Set-MgUserLicense`	Manages user licenses.
`Get-MsolSubscription`	`Get-MgSubscribedSku` or `Get-MgDirectorySubscription` (in beta)	Retrieves subscription information.

This table is not exhaustive but highlights the general pattern of cmdlet replacement. Always refer to the official Microsoft documentation for the most up-to-date information and detailed usage of each cmdlet.

Visualizing the Transition

Understanding the transition from legacy modules to Microsoft Graph PowerShell can be aided by visual resources. The following video provides an overview of migrating from Microsoft Entra ID Graph and MSOnline to Microsoft Graph:

A Microsoft Mechanics video discussing the transition to Microsoft Graph

This video from Microsoft Mechanics provides valuable insights into the reasons behind the migration and the benefits of using Microsoft Graph PowerShell. It can help administrators visualize the process and understand the new landscape of managing Microsoft Entra ID.

Frequently Asked Questions

What is the retirement date for the MSOnline and Azure AD PowerShell modules?

While initial retirement dates were announced, Microsoft has extended support for these modules to allow users more time to migrate. However, it is strongly recommended to migrate as soon as possible as they are no longer actively developed and may eventually stop functioning. Always refer to official Microsoft communications for the latest retirement timelines.

Do I need to reinstall PowerShell to use Microsoft Graph PowerShell?

No, you typically do not need to reinstall PowerShell itself. The Microsoft Graph PowerShell SDK is a module that you install into your existing PowerShell environment using the Install-Module cmdlet.

How do I handle authentication with Microsoft Graph PowerShell?

Authentication with Microsoft Graph PowerShell is typically done using the Connect-MgGraph cmdlet. You can authenticate interactively or using service principals and certificates for automation scenarios. You will need to grant appropriate API permissions in Microsoft Entra ID for your application or user.

Are all functionalities from MSOnline available in Microsoft Graph PowerShell?

Microsoft has been working to achieve parity between the legacy modules and Microsoft Graph PowerShell. While most common functionalities are available, some less common or deprecated features might have different implementations or might not have a direct one-to-one equivalent. It's important to test your scripts thoroughly after migration.

Can I use both MSOnline and Microsoft Graph PowerShell modules in the same script?

While technically possible in some cases (depending on the specific cmdlets and versions), it is generally not recommended. This can lead to conflicts and make your scripts harder to manage and troubleshoot. The best practice is to fully migrate to Microsoft Graph PowerShell.