MSOnline Module – Installation and Troubleshooting

MSOnline installation troubleshooting

The MSOnline module for PowerShell offers a convenient API to automate the management of Azure AD resources like users and licenses.

Installing it is pretty straightforward. And failure is quite frequent.

This post will take you through the most common errors seen during the installation of the MSOnline module.

To greatly simplify hybrid Office 365 management and save tons of time, take a look at Easy365Manager:

How to Install the MSOnline Module

To install the MSOnline module, launch PowerShell 64 bit in administrative mode and run the following command:

Install-Module MSOnline

Your MSOnline module is retrieved from the PSGallery and installed within a minute (subject to Internet bandwidth) if everything works out well.

If, however, the result of running this command is a complete and utter failure, then continue reading.

The following sections will cover the most typical reasons why the MSOnline module is not working out for you.

Check That You’re Running PowerShell 5.1 or Later

It’s a waste of time to examine all corners of your house if it’s the whole foundation that’s broken.

If you’re running Windows Server 2012 R2 or earlier or if you’re running an early release of Windows 10 or earlier, spend a few seconds to check your PowerShell version:

PS C:\> $PSVersionTable.PSVersion
Major  Minor  Build  Revision
-----  -----  -----  --------
5      1      18362  628

Suppose you’re running PowerShell 5.0 or earlier; make sure to upgrade. Read this article for instructions on how to install PowerShell 5.1 on your system.

Check Your Package Providers

When installing modules from the PSGallery, you’re using package providers to retrieve the module code. Package providers offer an easy way to install and update code automatically.

PSGallery is dependent on two package providers, NuGet and PowerShellGet. Check the availability of these using the Get-PackageProvider command:

PS C:\> Get-PackageProvider
Name                     Version          DynamicOptions
----                     -------          --------------
msi                      3.0.0.0          AdditionalArguments
msu                      3.0.0.0
NuGet                    3.0.0.1          Destination, ExcludeVersion, Scope, SkipDependencies, Headers,
                                          FilterOnTag, Contains, AllowPrereleaseVersions, ConfigFile, SkipValidate
PowerShellGet            1.0.0.1          PackageManagementProvider, Type, Scope, AllowClobber, SkipPublisherCheck,
                                          InstallUpdate, NoPathUpdate, Filter, Tag, Includes, DscResource, ...
Programs                 3.0.0.0          IncludeWindowsInstaller, IncludeSystemComponent

If NuGet is missing from your system install it using the Install-PackageProvider cmdlet:

Install-PackageProvider NuGet

Check That You’re Running as Administrator

Running your script in an elevated PowerShell prompt is not a requirement as such. However, installing modules in a non-elevated prompt will place the modules in your user profile.

Storing PowerShell modules in your user profile may or may not be desired, but it can definitely lead to confusion regarding module loading. I’ll cover that further down this post.

If in doubt, check your admin status using these two lines:

$currentPrincipal = New-Object Security.Principal.WindowsPrincipal([Security.Principal.WindowsIdentity]::GetCurrent())
$currentPrincipal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

If the output is ‘true’, the current prompt is elevated.

The ‘Install-Module’ command was found in the module ‘PowerShellGet’, but the module could not be loaded

Sometimes you may see an error message similar to this:

Install-Module : The 'Install-Module' command was found in the module 'PowerShellGet', but the module
  could not be loaded. For more information, run 'Import-Module PowerShellGet'.
At line:1 char:1
+ Install-Module MSOnline
+ ~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (Install-Module:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CouldNotAutoloadMatchingModule

This means that your PowerShell execution policy is blocking the execution of scripts.

Check your execution policy using the following command:

PS C:\> Get-ExecutionPolicy -List
        Scope ExecutionPolicy
        ----- ---------------
MachinePolicy       Undefined
   UserPolicy       Undefined
      Process       Undefined
  CurrentUser      Restricted
 LocalMachine      Restricted

The above output indicates that you’re not allowed to run scripts, and this needs to change.

As a bare minimum, set the current process to allow execution of remote signed scripts using the following command:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

If you don’t want to run this every time you start a new PowerShell console, you can set the scope to CurrentUser or LocalMachine, depending on your temperament.

Package ‘MSOnline’ failed to download

Some cases may lead to this error message:

WARNING: Source Location 'https://www.powershellgallery.com/api/v2/package/MSOnline/1.1.183.57' is not valid.
PackageManagement\Install-Package : Package 'MSOnline' failed to download.
At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.0.0.1\PSModule.psm1:1772 char:21
+ ...          $null = PackageManagement\Install-Package @PSBoundParameters
+                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ResourceUnavailable: (C:\Users\adm.ad...\MSOnline.nupkg:String) [Install-Package], Exception
    + FullyQualifiedErrorId : PackageFailedInstallOrDownload,Microsoft.PowerShell.PackageManagement.Cmdlets.InstallPackage

This error is caused by Microsoft disabling TLS 1.0 and 1.1 support on the PSGallery around the end of March 2020.

This can be resolved by enabling TLS 1.2:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

After running this command, retry your installation from the PSGallery.

PackageManagement\Install-Package : A command with name ‘Get-MsolUser’ is already available

If commands in the MSOnline module are conflicting with existing commands on your system, you’ll see an error message similar to this:

**PackageManagement\Install-Package : A command with name 'Get-MsolUser' is already available on this system.
  This module 'MSOnline' may override the existing commands. If you still want to install this module 'MSOnline',
  use -AllowClobber parameter.**

The error message is quite clear: To solve this issue, use the -AllowClobber switch. This will allow the MSOnline module commands to override any commands already existing on your system:

Install-Module MSOnline -AllowClobber

PowerShell Module Side-by-Side Installation

PowerShell modules can be installed side by side and in different locations.

In general, you’re targeting two different folders when installing PowerShell modules on your system:

  • Installing modules from a non-elevated PowerShell console will place modules in your user profile:
    • $env:UserProfile\Documents\WindowsPowerShell\Modules
      • (replace ‘Documents’ with the localized name if non-English)
  • Installing modules from an elevated PowerShell console will place modules in Program files:
    • $env:ProgramFiles\WindowsPowerShell\Modules

This means you can, e.g., have MSOnline version 1.0 and 1.1.166.0 installed in your user profile AND version 1.1.183.8 and 1.1.183.57 installed in program files. As is exactly the case seen here:

PS C:\> Get-Module -ListAvailable -Name MSOnline

    Directory: C:\Users\SOGP50\Documents\WindowsPowerShell\Modules

ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Manifest   1.1.166.0  MSOnline                            {Get-MsolDevice, Remove-MsolDevice, ...}
Manifest   1.0        MSOnline                            {Get-MsolDevice, Remove-MsolDevice, ...}

    Directory: C:\Program Files\WindowsPowerShell\Modules

ModuleType Version    Name                                ExportedCommands
---------- -------    ----                                ----------------
Manifest   1.1.183.57 MSOnline                            {Get-MsolDevice, Remove-MsolDevice, ...}
Manifest   1.1.183.8  MSOnline                            {Get-MsolDevice, Remove-MsolDevice, ...}

And now, the 10,000 $ question is, of course: 

What is the PowerShell Module Load Order?

To understand the PowerShell module load order, you must first examine the module path variable, $env:PSModulePath. On my system, it looks similar to this:

PS C:\> $env:PSModulePath
C:\Users\JaneDoe\Documents\WindowsPowerShell\Modules;
C:\Program Files\WindowsPowerShell\Modules;
C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\;
C:\Program Files (x86)\Microsoft SQL Server\120\Tools\PowerShell\Modules\;
C:\Program Files (x86)\Microsoft SQL Server\130\Tools\PowerShell\Modules\;
C:\Program Files\SharePoint Online Management Shell\

(The first two module paths are the most interesting as this is where we dump modules that we install from PSGallery).

By default, PowerShell will load the highest version number of the module in the first folder in the module path where the module is found.

Let’s do a small test:

We have four versions of MSOnline installed in two different folders:

PS C:\> Get-Module -ListAvailable -Name MSOnline | ft Name,Version,Path
Name     Version    Path
----     -------    ----
MSOnline 1.1.166.0  C:\Users\SOGP50\Documents\WindowsPowerShell\Modules\MSOnline\1.1.166.0\MSOnline.psd1
MSOnline 1.0        C:\Users\SOGP50\Documents\WindowsPowerShell\Modules\MSOnline\1.0\MSOnline.psd1
MSOnline 1.1.183.57 C:\Program Files\WindowsPowerShell\Modules\MSOnline\1.1.183.57\MSOnline.psd1
MSOnline 1.1.183.8  C:\Program Files\WindowsPowerShell\Modules\MSOnline\1.1.183.8\MSOnline.psd1

We load the MSOnline module explicitly by running the following command:

Import-Module MSOnline

The first folder in the PS module path is: ‘C:\Users\SOGP50\Documents\WindowsPowerShell\Modules’.

The highest MSOnline version in the first path is 1.1.166.0.

And if we check the filehandles generated for the MSOnline module, e.g., using Process Explorer, we can confirm this to be the case:

MSOnline PowerShell Module

Take a moment to let it sink in:

Even though I just installed the latest MSOnline module using an elevated prompt, the older MSOnline version in my user profile is still getting loaded.

So make sure to tidy up different versions of your modules if you want to control what versions are getting loaded!

How to Manage Office 365 From Active Directory

If you’re looking for ways to further speed up your work, take a look at Easy365Manager.

Easy365Manager consolidates Active Directory and Office 365 administration by extending user properties with two new tabs:

Easy365Manager user properties
Easy365Manager user properties

As an example, check out how easy it is to enable an Office 365 mailbox by assigning an Office 365 license:

Create an Office 365 mailbox using Easy365Manager

Easy365Manager can be installed and configured on any machine with AD Users & Computers in just a few minutes and is a real time saver.

You can even remove your last on-premises Exchange Server.

For a complete list of features, read this.

Download the fully functional 30-day trial here.

Did you like this post? Maybe your friends will too!