MSOnline 模块 - 安装和故障排除

PowerShell 的 MSOnline 模块提供了方便的 API 来自动管理 Azure AD 资源（例如用户和许可证）。

安装它非常简单。而且失败的情况也相当频繁。

这篇文章将带您了解安装 MSOnline 模块期间最常见的错误。

要大大简化混合 Office 365 管理并节省大量时间，请查看 Easy365Manager：

如何安装 MSOnline 模块

要安装 MSOnline 模块，请在管理模式下启动 PowerShell 64 位并运行以下命令：

Install-Module MSOnline

如果一切顺利，您的 MSOnline 模块将从 PSGallery 检索并在一分钟内安装（取决于 Internet 带宽）。

但是，如果运行此命令的结果是完全失败，那么请继续阅读。

以下部分将介绍 MSOnline 模块不适合您的最典型原因。

检查您是否正在运行 PowerShell 5.1 或更高版本

如果整个地基都坏了，那么检查房子的各个角落就是浪费时间。

如果您运行的是 Windows Server 2012 R2 或更早版本，或者如果您运行的是 Windows 10 或更早版本的早期版本，请花几秒钟检查您的 PowerShell 版本：

PS C:\> $PSVersionTable.PSVersion

Major  Minor  Build  Revision
-----  -----  -----  --------
5      1      18362  628

假设您运行的是 PowerShell 5.0 或更早版本；确保升级。阅读本文，了解如何在系统上安装 PowerShell 5.1 的说明。

检查您的套餐提供商

从 PSGallery 安装模块时，您将使用包提供程序来检索模块代码。软件包提供程序提供了一种自动安装和更新代码的简单方法。

PSGallery 依赖于两个包提供程序：NuGet 和 PowerShellGet。使用 Get-PackageProvider 命令检查这些的可用性：

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

如果您的系统中缺少 NuGet，请使用 Install-PackageProvider cmdlet 安装它：

Install-PackageProvider NuGet

检查您是否以管理员身份运行

在提升的 PowerShell 提示符中运行脚本本身并不是必需的。但是，在非提升提示中安装模块会将模块放置在您的用户配置文件中。

在用户配置文件中存储 PowerShell 模块可能是需要的，也可能不是，但它肯定会导致模块加载方面的混乱。我将在这篇文章中进一步介绍这一点。

如果有疑问，请使用以下两行检查您的管理员状态：

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

如果输出为“true”，则当前提示会提升。

在模块“PowerShellGet”中找到“Install-Module”命令，但无法加载该模块

有时您可能会看到类似于以下内容的错误消息：

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

这意味着您的 PowerShell 执行策略正在阻止脚本的执行。

使用以下命令检查您的执行策略：

PS C:\> Get-ExecutionPolicy -List

        Scope ExecutionPolicy
        ----- ---------------
MachinePolicy       Undefined
   UserPolicy       Undefined
      Process       Undefined
  CurrentUser      Restricted
 LocalMachine      Restricted

上面的输出表明您不允许运行脚本，这需要更改。

至少，使用以下命令将当前进程设置为允许执行远程签名脚本：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

如果您不想每次启动新的 PowerShell 控制台时都运行此命令，则可以根据您的性格将范围设置为 CurrentUser 或 LocalMachine。

软件包“MSOnline”下载失败

某些情况可能会导致此错误消息：

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

此错误是由于 Microsoft 在 2020 年 3 月底左右在 PSGallery 上禁用 TLS 1.0 和 1.1 支持而导致的。

这可以通过启用 TLS 1.2 来解决：

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

运行此命令后，从 PSGallery 重试安装。

PackageManagement\Install-Package ：名称为“Get-MsolUser”的命令已可用

如果 MSOnline 模块中的命令与系统上的现有命令冲突，您将看到类似于以下内容的错误消息：

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

错误消息非常清楚：要解决此问题，请使用 -AllowClobber 开关。这将允许 MSOnline 模块命令覆盖系统上已存在的任何命令：

Install-Module MSOnline -AllowClobber

PowerShell 模块并行安装

PowerShell 模块可以并排安装在不同位置。

一般来说，在系统上安装 PowerShell 模块时，您会针对两个不同的文件夹：

• 从非提升 PowerShell 控制台安装模块会将模块放置在您的用户配置文件中：

  • $env:UserProfile\Documents\WindowsPowerShell\Modules

    • （如果不是英语，请将“文档”替换为本地化名称）

这意味着您可以将 MSOnline 版本 1.0 和 1.1.166.0 安装在您的用户配置文件中，将版本 1.1.183.8 和 1.1.183.57 安装在程序文件中。正如这里所看到的情况：

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

现在，10,000 美元的问题当然是：

PowerShell 模块加载顺序是什么？

要了解 PowerShell 模块加载顺序，必须首先检查模块路径变量 $env:PSModulePath。在我的系统上，它看起来类似于：

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 Server0\Tools\PowerShell\Modules\;
C:\Program Files (x86)\Microsoft SQL Server0\Tools\PowerShell\Modules\;
C:\Program Files\SharePoint Online Management Shell\

（前两个模块路径是最有趣的，因为这是我们转储从 PSGallery 安装的模块的地方）。

默认情况下，PowerShell 将在找到该模块的模块路径的第一个文件夹中加载该模块的最高版本号。

我们来做一个小测试：

我们在两个不同的文件夹中安装了四个版本的 MSOnline：

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.166.0\MSOnline.psd1
MSOnline 1.0        C:\Users\SOGP50\Documents\WindowsPowerShell\Modules\MSOnline.0\MSOnline.psd1
MSOnline 1.1.183.57 C:\Program Files\WindowsPowerShell\Modules\MSOnline.1.183.57\MSOnline.psd1
MSOnline 1.1.183.8  C:\Program Files\WindowsPowerShell\Modules\MSOnline.1.183.8\MSOnline.psd1

我们通过运行以下命令显式加载 MSOnline 模块：

Import-Module MSOnline

PS 模块路径中的第一个文件夹是：“C:\Users\SOGP50\Documents\WindowsPowerShell\Modules”。

第一个路径中的最高 MSOnline 版本是 1.1.166.0。

如果我们检查为 MSOnline 模块生成的文件句柄（例如使用 Process Explorer），我们可以确认情况确实如此：

花点时间让它深入理解：

即使我刚刚使用提升的提示安装了最新的 MSOnline 模块，我的用户配置文件中的旧 MSOnline 版本仍在加载。

因此，如果您想控制加载的版本，请务必整理不同版本的模块！