Merge branch 'master' into brucepay_DirMirror

Author: Bruce Payette

WindowsCompatibility/WindowsCompatibility.psd1

@@ -14,7 +14,7 @@ Author = 'PowerShell'
 CompanyName = 'Microsoft Corporation'
 Copyright = 'Copyright (c) Microsoft Corporation. All rights reserved'
 Description = @'
-This module Provides compatibility utilities that allow PowerShell Core sessions to
+This module provides compatibility utilities that allow PowerShell Core sessions to
 invoke commands that are only available in Windows PowerShell. These utilities help you
 to discover available modules, import those modules through proxies and then use the module
 commands much as if they were native to PowerShell Core.
@@ -30,11 +30,12 @@ FunctionsToExport = @(
     'Copy-WinModule',
     'Add-WindowsPSModulePath'
 )
+AliasesToExport = @('Add-WinPSModulePath')
 PrivateData = @{
     PSData = @{
         Tags = @('Compatibility', 'Core')
         LicenseUri = 'https://opensource.org/licenses/MIT'
-        ProjectUri = 'https://github.com/PowerShell/WindowsPowerShellCompatibilityPack'
+        ProjectUri = 'https://github.com/PowerShell/WindowsCompatibility'
         ReleaseNotes = @'
 This is the first release of this module with the basic commands:
     Initialize-WinSession

WindowsCompatibility/WindowsCompatibility.psm1

@@ -87,11 +87,13 @@ $CompatibleModules = @(
 # Module-scope variable to hold the active compatibility session name
 $SessionName = $null
 
+# The computer name to use if one isn't provided.
+$SessionComputerName = 'localhost'
+
 # Specifies the default configuration to connect to when creating the compatibility session
-$DefaultConfigurationName = 'Microsoft.PowerShell'
+$SessionConfigurationName = 'Microsoft.PowerShell'
 
-# Specifies the default name of the computer on which to create the compatibility session
-$DefaultComputerName = 'localhost'
+Set-Alias -Name Add-WinPSModulePath -Value Add-WindowsPSModulePath
 
 # Location Changed handler that keeps the compatibility session PWD in sync with the parent PWD
 # This only applies on localhost.
@@ -123,17 +125,16 @@ function Initialize-WinSession
         # If you don't want to use the default compatibility session, use
         # this parameter to specify the name of the computer on which to create
         # the compatibility session.
-        # (Defaults to 'localhost')
         [Parameter(Mandatory=$false,Position=0)]
         [String]
         [Alias("Cn")]
-            $ComputerName = $script:DefaultComputerName,
+            $ComputerName,
 
         # Specifies the configuration to connect to when creating the compatibility session
         # (Defaults to 'Microsoft.PowerShell')
         [Parameter()]
         [String]
-            $ConfigurationName = $script:DefaultConfigurationName,
+            $ConfigurationName,
 
         # The credential to use when connecting to the target machine/configuration
         [Parameter()]
@@ -154,6 +155,25 @@ function Initialize-WinSession
     }
 
     Write-Verbose -Verbose:$verboseFlag "Initializing the compatibility session on host '$ComputerName'."
+
+    if ($ComputerName)
+    {
+        $script:SessionComputerName = $ComputerName
+    }
+    else
+    {
+        $ComputerName = $script:SessionComputerName
+    }
+
+    if ($ConfigurationName)
+    {
+        $script:SessionConfigurationName = $ConfigurationName
+    }
+    else
+    {
+        $ConfigurationName = $script:SessionConfigurationName
+    }
+
     if ($Credential)
     {
         $script:SessionName = "wincompat-$ComputerName-$($Credential.UserName)"
@@ -162,13 +182,14 @@ function Initialize-WinSession
     {
         $script:SessionName = "wincompat-$ComputerName-$([environment]::UserName)"
     }
+
     Write-Verbose -Verbose:$verboseFlag "The compatibility session name is '$script:SessionName'."
 
     $session = Get-PSSession | Where-Object {
         $_.ComputerName      -eq $ComputerName -and
         $_.ConfigurationName -eq $ConfigurationName -and
         $_.Name              -eq $script:SessionName
-    }
+        } | Select-Object -First 1
 
     # Deal with the possibilities of multiple sessions. This might arise
     # from the user hitting ctrl-C. We'll make the assumption that the
@@ -206,16 +227,17 @@ function Initialize-WinSession
         {
             $newPSSessionParameters.EnableNetworkAccess = $true
         }
-        Write-Verbose -Verbose:$verboseFlag "Creating a new compatibility session."
-        $session = New-PSSession @newPSSessionParameters
+
+        Write-Verbose -Verbose:$verboseFlag "Created new compatibiilty session on host '$computername'"
+        $session = New-PSSession @newPSSessionParameters | Select-Object -First 1
         if ($session.ComputerName -eq "localhost")
         {
             Invoke-Command $session { Set-Location $using:PWD }
         }
     }
     else
     {
-        Write-Verbose -Verbose:$verboseFlag "Reusing the existing compatibility session."
+        Write-Verbose -Verbose:$verboseFlag "Reusing the existing compatibility session; 'host = $script:SessionComputerName'."
     }
 
     if ($PassThru)
@@ -244,34 +266,30 @@ function Add-WinFunction
         # If you don't want to use the default compatibility session, use
         # this parameter to specify the name of the computer on which to create
         # the compatibility session.
-        # (Defaults to 'localhost')
         [Parameter()]
         [String]
         [Alias("Cn")]
-            $ComputerName = $script:DefaultComputerName,
+            $ComputerName,
 
         # Specifies the configuration to connect to when creating the compatibility session
         # (Defaults to 'Microsoft.PowerShell')
         [Parameter()]
         [String]
-            $ConfigurationName = $script:DefaultConfigurationName,
+            $ConfigurationName,
 
         # The credential to use when creating the compatibility session
         # using the target machine/configuration
         [Parameter()]
         [PSCredential]
             $Credential
     )
-
     # Make sure the session is initialized
     [void] $PSBoundParameters.Remove('Name')
     [void] $PSBoundParameters.Remove('ScriptBlock')
 
-    Initialize-WinSession @PSBoundParameters
-
-    $localSessionName = $script:SessionName
+    # the session variable will be captured in the closure
+    $session = Initialize-WinSession @PSBoundParameters -PassThru
     $wrapper = {
-        $session = Get-PSsession -Name $localSessionName
         Invoke-Command -Session $session -Scriptblock $ScriptBlock -ArgumentList $args
     }
     Set-item function:Global:$Name $wrapper.GetNewClosure();
@@ -291,17 +309,16 @@ function Invoke-WinCommand
         # If you don't want to use the default compatibility session, use
         # this parameter to specify the name of the computer on which to create
         # the compatibility session.
-        # (Defaults to 'localhost')
         [Parameter()]
         [String]
         [Alias("cn")]
-            $ComputerName = $script:DefaultComputerName,
+            $ComputerName,
 
         # Specifies the configuration to connect to when creating the compatibility session
         # (Defaults to 'Microsoft.PowerShell')
         [Parameter()]
         [String]
-            $ConfigurationName = $script:DefaultConfigurationName,
+            $ConfigurationName,
 
         # The credential to use when connecting to the compatibility session.
         [Parameter()]
@@ -338,16 +355,15 @@ function Get-WinModule
         # If you don't want to use the default compatibility session, use
         # this parameter to specify the name of the computer on which to create
         # the compatibility session.
-        # (Defaults to 'localhost')
         [Alias("cn")]
         [String]
-            $ComputerName = $script:DefaultComputerName,
+            $ComputerName,
 
         # Specifies the configuration to connect to when creating the compatibility session
         # (Defaults to 'Microsoft.PowerShell')
         [Parameter()]
         [String]
-            $ConfigurationName = $script:DefaultConfigurationName,
+            $ConfigurationName,
 
         # The credential to use when creating the compatibility session
         # using the target machine/configuration
@@ -413,17 +429,16 @@ function Import-WinModule
         # If you don't want to use the default compatibility session, use
         # this parameter to specify the name of the computer on which to create
         # the compatibility session.
-        # (Defaults to 'localhost')
         [Parameter()]
         [String]
         [Alias("cn")]
-            $ComputerName = $script:DefaultComputerName,
+            $ComputerName,
 
         # Specifies the configuration to connect to when creating the compatibility session
         # (Defaults to 'Microsoft.PowerShell')
         [Parameter()]
         [String]
-            $ConfigurationName = $script:DefaultConfigurationName,
+            $ConfigurationName,
 
         # Prefix to prepend to the imported command names
         [Parameter()]
@@ -516,10 +531,10 @@ function Import-WinModule
         }
         if ($noClobberNames)
         {
-            $importModuleParameters.PassThru = $true 
-            foreach ($name in $noClobberNames) 
-            { 
-                $module = Import-Module -Name $name -NoClobber @importModuleParameters 
+            $importModuleParameters.PassThru = $true
+            foreach ($name in $noClobberNames)
+            {
+                $module = Import-Module -Name $name -NoClobber @importModuleParameters
                 # Hack using private reflection to keep the proxy module from shadowing the real module.
                 $null = [PSModuleInfo].
                     GetMethod('SetName',[System.Reflection.BindingFlags]'Instance, NonPublic').
@@ -552,17 +567,16 @@ function Compare-WinModule
         # If you don't want to use the default compatibility session, use
         # this parameter to specify the name of the computer on which to create
         # the compatibility session.
-        # (Defaults to 'localhost')
         [Parameter()]
         [String]
         [Alias("cn")]
-            $ComputerName = $script:DefaultComputerName,
+            $ComputerName,
 
         # Specifies the configuration to connect to when creating the compatibility session
         # (Defaults to 'Microsoft.PowerShell')
         [Parameter()]
         [String]
-            $ConfigurationName = $script:DefaultConfigurationName,
+            $ConfigurationName,
 
         # If needed, use this parameter to specify credentials for the compatibility session
         [Parameter()]
@@ -613,17 +627,16 @@ function Copy-WinModule
         # If you don't want to use the default compatibility session, use
         # this parameter to specify the name of the computer on which to create
         # the compatibility session.
-        # (Defaults to 'localhost')
         [Parameter()]
         [String]
         [Alias("cn")]
-            $ComputerName = $script:DefaultComputerName,
+            $ComputerName,
 
         # Specifies the configuration to connect to when creating the compatibility session
         # (Defaults to 'Microsoft.PowerShell')
         [Parameter()]
         [String]
-            $ConfigurationName = $script:DefaultConfigurationName,
+            $ConfigurationName,
 
         # If needed, use this parameter to specify credentials for the compatibility session
         [Parameter()]
@@ -720,7 +733,6 @@ function Copy-WinModule
 
 function Add-WindowsPSModulePath
 {
-
     if ($PSVersionTable.PSEdition -eq 'Core' -and -not $IsWindows)
     {
         throw "This cmdlet is only supported on Windows"
@@ -731,10 +743,24 @@ function Add-WindowsPSModulePath
         return
     }
 
-    $WindowsPSModulePath = [System.Environment]::GetEnvironmentVariable("psmodulepath", [System.EnvironmentVariableTarget]::Machine)
-    if (-not ($env:PSModulePath).Contains($WindowsPSModulePath))
+    $paths =  @(
+        $Env:PSModulePath -split [System.IO.Path]::PathSeparator
+        "${Env:UserProfile}\Documents\WindowsPowerShell\Modules"
+        "${Env:ProgramFiles}\WindowsPowerShell\Modules"
+        "${Env:WinDir}\system32\WindowsPowerShell\v1.0\Modules"
+        [System.Environment]::GetEnvironmentVariable('PSModulePath',
+            [System.EnvironmentVariableTarget]::Machine) -split [System.IO.Path]::PathSeparator
+    )
+
+    $pathTable = [ordered] @{}
+    foreach ($path in $paths)
     {
-        $env:PSModulePath += ";${env:userprofile}\Documents\WindowsPowerShell\Modules;${env:programfiles}\WindowsPowerShell\Modules;${WindowsPSModulePath}"
+        if ($pathTable[$path])
+        {
+            continue
+        }
+        $pathTable[$path] = $true
     }
 
+    $Env:PSModulePath = $pathTable.Keys -join [System.IO.Path]::PathSeparator
 }

docs/Module/Import-WinModule.md

@@ -23,9 +23,16 @@ Import-WinModule [[-Name] <String[]>] [-Exclude <String[]>] [-ComputerName <Stri
 
 This command allows you to import proxy modules from a local or remote session.
 These proxy modules will allow you to invoke cmdlets that are not directly supported in this version of PowerShell.
+
 There are commands in the Windows PowerShell core modules that don't exist natively in PowerShell Core.
 If these modules are imported, proxies will only be created for the missing commands.
-Commands that already exist in PowerShell core will not be overridden.
+Commands that already exist in PowerShell Core will not be overridden.
+The modules subject to this restriction are:
+
+- Microsoft.PowerShell.Management
+- Microsoft.PowerShell.Utility
+- Microsoft.PowerShell.Security
+- Microsoft.PowerShell.Diagnostics
 
 By default, when executing, the current compatibility session is used,
 or, in the case where there is no existing session, a new default session will be created.