Add SkipEditionCheck switch docs, update CompatiblePSEditions docs

gallery/concepts/module-psedition-support.md

@@ -9,14 +9,25 @@ title:  Modules with compatible PowerShell Editions
 Starting with version 5.1, PowerShell is available in different editions which denote varying
 feature sets and platform compatibility.
 
-- **Desktop Edition:** Built on .NET Framework and provides compatibility with scripts and modules
-  targeting versions of PowerShell running on full footprint editions of Windows such as Server
-  Core and Windows Desktop.
-- **Core Edition:** Built on .NET Core and provides compatibility with scripts and modules
-  targeting versions of PowerShell running on reduced footprint editions of Windows such as Nano
-  Server and Windows IoT.
+- **Desktop Edition:** Built on .NET Framework, applies to Windows PowerShell v4.0 and below as well
+  as Windows PowerShell 5.1 on Windows Desktop, Windows Server, Windows Server Core and most other
+  Windows editions.
+- **Core Edition:** Built on .NET Core, applies to PowerShell Core 6.0 and above as well as
+  Windows PowerShell 5.1 on reduced footprint Windows Editions such as Windows IoT and Windows
+  Nanoserver.
 
-The running edition of PowerShell is shown in the PSEdition property of `$PSVersionTable`.
+In PowerShell 5.1 and above, the edition of the running PowerShell session can be retrieved from the
+`$PSEdition` automatic variable:
+
+```powershell
+$PSEdition
+```
+
+```output
+Core
+```
+
+Edition information is also present in the PSEdition property of `$PSVersionTable`:
 
 ```powershell
 $PSVersionTable
@@ -92,6 +103,143 @@ Desktop
 Core
 ```
 
+## Edition-compatibility for PowerShell modules that ship as part of Windows
+
+For most modules, the `CompatiblePSEditions` field is purely informational;
+PowerShell module tooling allows users to filter on this field, but does not perform
+checks on it itself.
+
+In PowerShell 6.1 and above however, for modules that ship as part of Windows in the Windows
+PowerShell system module directory (`%windir%\System32\WindowsPowerShell\v1.0\Modules`),
+the `CompatiblePSEditions` field is checked by PowerShell. This is so that Windows PowerShell modules
+that have been validated as compatible with PowerShell Core will work normally, while modules
+that are not yet compatible will be ignored or stopped from importing
+(preventing unpredictable compatibility issues later).
+
+> [!NOTE]
+> Any module you write will not have the `CompatiblePSEditions` field checked.
+> Edition-checking only occurs on Windows PowerShell modules that ship as part of Windows
+> in the `%windir%\System32\WindowsPowerShell\v1.0\Modules` directory.
+
+For `Import-Module`, the `CompatiblePSEditions` check means a Core-incompatible module will fail
+to load in PowerShell Core 6.1 and above:
+
+```powershell
+Import-Module BitsTransfer
+```
+
+```output
+Import-Module : Module 'C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\BitsTransfer\BitsTransfer.psd1' does not support current PowerShell edition 'Core'. Its supported editions are 'Desktop'. Use 'Import-Module -SkipEditionCheck' to ignore the compatibility of this module.
+At line:1 char:1
++ Import-Module BitsTransfer
++ ~~~~~~~~~~~~~~~~~~~~~~~~~~
++ CategoryInfo          : ResourceUnavailable: (C:\WINDOWS\system32\u2026r\BitsTransfer.psd1:String) [Import-Module], InvalidOperationException
++ FullyQualifiedErrorId : Modules_PSEditionNotSupported,Microsoft.PowerShell.Commands.ImportModuleCommand
+```
+
+With `Get-Module`, the `CompatiblePSEditions` check means edition-incompatible modules are not
+returned or displayed by default:
+
+```powershell
+Get-Module -ListAvailable BitsTransfer
+```
+
+```output
+```
+
+In both cases, you can bypass this with the `-SkipEditionCheck` switch parameter:
+
+```powershell
+Import-Module -SkipEditionCheck AppLocker -PassThru
+```
+
+```output
+
+ModuleType Version    Name                                ExportedCommands
+---------- -------    ----                                ----------------
+Manifest   2.0.0.0    AppLocker                           {Get-AppLockerFileInformation, Get-AppLockerPolicy, New-AppLocker…
+
+```
+
+```powershell
+Get-Module -ListAvailable BitsTransfer
+```
+
+```output
+
+
+    Directory: C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules
+
+ModuleType Version    Name                                PSEdition ExportedCommands
+---------- -------    ----                                --------- ----------------
+Manifest   2.0.0.0    BitsTransfer                        Desk      {Add-BitsFile, Complete-BitsTransfer, Get-BitsTransfer,…
+
+```
+
+However, if you import a module that is not marked as compatible with PowerShell Core,
+be aware that errors due to an incompatibility could occur at a later stage
+(the module may even import successfully and only fail while executing a command):
+
+```powershell
+Import-Module -SkipEditionCheck BitsTransfer
+```
+
+```output
+Import-Module : Could not load type 'System.Management.Automation.PSSnapIn' from assembly 'System.Management.Automation, Version=6.2.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35'.
+At line:1 char:1
++ Import-Module -SkipEditionCheck BitsTransfer
++ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++ CategoryInfo          : NotSpecified: (:) [Import-Module], TypeLoadException
++ FullyQualifiedErrorId : System.TypeLoadException,Microsoft.PowerShell.Commands.ImportModuleCommand
+```
+
+Changes to formatting in PowerShell Core 6.1 and above mean you will be informed about how
+PowerShell interprets the `CompatiblePSEditions` field under the `PSEdition` format table header:
+
+```powershell
+Get-Module -ListAvailable
+```
+
+```output
+
+    Directory: C:\Users\me\Documents\PowerShell\Modules
+
+ModuleType Version    Name                                PSEdition ExportedCommands
+---------- -------    ----                                --------- ----------------
+Script     1.3.1      Az.Accounts                         Core,Desk {Disable-AzDataCollection, Disable-AzContextAutosave, E…
+Script     4.4.0      Pester                              Desk      {Describe, Context, It, Should…}
+Script     1.0.0      WindowsCompatibility                Core      {Initialize-WinSession, Add-WinFunction, Invoke-WinComm…
+
+    Directory: C:\Program Files\PowerShell\Modules
+
+ModuleType Version    Name                                PSEdition ExportedCommands
+---------- -------    ----                                --------- ----------------
+Script     1.2.2      PackageManagement                   Desk      {Find-Package, Get-Package, Get-PackageProvider, Get-Pa…
+Script     2.0.1      PowerShellGet                       Desk      {Find-Command, Find-DSCResource, Find-Module, Find-Role…
+
+...
+
+    Directory: C:\program files\powershell\6-preview\Modules
+
+ModuleType Version    Name                                PSEdition ExportedCommands
+---------- -------    ----                                --------- ----------------
+Manifest   6.1.0.0    CimCmdlets                          Core      {Get-CimAssociatedInstance, Get-CimClass, Get-CimInstan…
+Manifest   1.2.2.0    Microsoft.PowerShell.Archive        Desk      {Compress-Archive, Expand-Archive}
+Manifest   6.1.0.0    Microsoft.PowerShell.Diagnostics    Core      {Get-WinEvent, New-WinEvent}
+
+...
+
+    Directory: C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules
+
+ModuleType Version    Name                                PSEdition ExportedCommands
+---------- -------    ----                                --------- ----------------
+Manifest   1.0.0.0    BitLocker                           Core,Desk {Unlock-BitLocker, Suspend-BitLocker, Resume-BitLocker,…
+Script     3.0        Dism                                Core,Desk {Add-AppxProvisionedPackage, Add-WindowsDriver, Add-Win…
+
+...
+
+```
+
 ## Targeting multiple editions
 
 Module authors can publish a single module targeting to either or both PowerShell editions (Desktop

reference/6/Microsoft.PowerShell.Core/Get-Module.md

@@ -8,6 +8,7 @@ online version: http://go.microsoft.com/fwlink/?LinkId=821486
 schema: 2.0.0
 title: Get-Module
 ---
+
 # Get-Module
 
 ## SYNOPSIS
@@ -16,30 +17,27 @@ Gets the modules that have been imported or that can be imported into the curren
 ## SYNTAX
 
 ### Loaded (Default)
-
 ```
 Get-Module [[-Name] <String[]>] [-FullyQualifiedName <ModuleSpecification[]>] [-All] [<CommonParameters>]
 ```
 
 ### Available
-
 ```
 Get-Module [[-Name] <String[]>] [-FullyQualifiedName <ModuleSpecification[]>] [-All] [-ListAvailable]
- [-PSEdition <String>] [-Refresh] [<CommonParameters>]
+ [-PSEdition <String>] [-SkipEditionCheck] [-Refresh] [<CommonParameters>]
 ```
 
 ### PsSession
-
 ```
 Get-Module [[-Name] <String[]>] [-FullyQualifiedName <ModuleSpecification[]>] [-ListAvailable]
- [-PSEdition <String>] [-Refresh] -PSSession <PSSession> [<CommonParameters>]
+ [-PSEdition <String>] [-SkipEditionCheck] [-Refresh] -PSSession <PSSession> [<CommonParameters>]
 ```
 
 ### CimSession
-
 ```
-Get-Module [[-Name] <String[]>] [-FullyQualifiedName <ModuleSpecification[]>] [-ListAvailable] [-Refresh]
- -CimSession <CimSession> [-CimResourceUri <Uri>] [-CimNamespace <String>] [<CommonParameters>]
+Get-Module [[-Name] <String[]>] [-FullyQualifiedName <ModuleSpecification[]>] [-ListAvailable]
+ [-SkipEditionCheck] [-Refresh] -CimSession <CimSession> [-CimResourceUri <Uri>] [-CimNamespace <String>]
+ [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -495,33 +493,6 @@ Accept pipeline input: True (ByValue)
 Accept wildcard characters: False
 ```
 
-### -PSEdition
-
-Gets the modules that support specified edition of PowerShell.
-
-The acceptable values for this parameter are:
-
-- Desktop
-- Core
-
-The Get-Module cmdlet checks **CompatiblePSEditions** property of **PSModuleInfo** object for the specified value and returns only those modules that have it set.
-
-> [!NOTE]
-> - **Desktop Edition:** Built on .NET Framework and provides compatibility with scripts and modules targeting versions of PowerShell running on full footprint editions of Windows such as Server Core and Windows Desktop.
-> - **Core Edition:** Built on .NET Core and provides compatibility with scripts and modules targeting versions of PowerShell running on reduced footprint editions of Windows such as Nano Server and Windows IoT.
-
-```yaml
-Type: String
-Parameter Sets: Available, PsSession
-Aliases:
-
-Required: False
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### -PSSession
 
 Gets the modules in the specified user-managed PowerShell session (**PSSession**).
@@ -569,9 +540,58 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### CommonParameters
+### -PSEdition
+
+Gets the modules that support specified edition of PowerShell.
+
+The acceptable values for this parameter are:
+
+- Desktop
+- Core
+
+The Get-Module cmdlet checks **CompatiblePSEditions** property of **PSModuleInfo** object for the specified value and returns only those modules that have it set.
+
+> [!NOTE]
+> - **Desktop Edition:** Built on .NET Framework, applies to Windows PowerShell 5.1 and below on most Windows editions.
+> - **Core Edition:** Built on .NET Core, applies to PowerShell Core 6.0 and above, as well as some editions of Windows PowerShell 5.1 built for Windows IoT and Windows Nanoserver.
+>
+> The edition of the current PowerShell session can be found with the `$PSEdition` variable.
+
+```yaml
+Type: String
+Parameter Sets: Available, PsSession
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -SkipEditionCheck
+
+Skips the check of the `CompatiblePSEditions` field.
+
+By default, Get-Module will omit modules in the `%windir%\System32\WindowsPowerShell\v1.0\Modules`
+directory that do not specify `Core` in the `CompatiblePSEditions` field.
+When this switch is set, modules without `Core` will be included, so that modules under the
+Windows PowerShell module path that are incompatible with PowerShell Core will be returned.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: Available, PsSession, CimSession
+Aliases:
 
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS