diff --git a/ISERemoteTab.psd1 b/ISERemoteTab.psd1 index d0fe127..80ec2fe 100644 Binary files a/ISERemoteTab.psd1 and b/ISERemoteTab.psd1 differ diff --git a/ISERemoteTab.psm1 b/ISERemoteTab.psm1 index 4e6434d..1d6a0f4 100644 --- a/ISERemoteTab.psm1 +++ b/ISERemoteTab.psm1 @@ -1,5 +1,4 @@ -#requires -version 4.0 - -. $psScriptroot\New-ISERemoteTab.ps1 -. $psScriptroot\New-ISERemoteTabForm.ps1 - + +#dot source the module functions +. $psScriptroot\Functions\New-ISERemoteTab.ps1 +. $psScriptroot\Functions\New-ISERemoteTabForm.ps1 diff --git a/New-ISERemoteTab.ps1 b/New-ISERemoteTab.ps1 deleted file mode 100644 index 4a11808..0000000 --- a/New-ISERemoteTab.ps1 +++ /dev/null @@ -1,220 +0,0 @@ -#requires -version 4.0 -#requires -module ISE - -Function New-ISERemoteTab { - -[cmdletbinding(DefaultParameterSetName="Credential")] - -Param( -[Parameter( - Position = 0, - Mandatory, - HelpMessage = "Enter the name of a remote computer", - ValueFromPipeline, - ValueFromPipelineByPropertyName -)] -[ValidateNotNullorEmpty()] -[Alias("cn")] -[string[]]$Computername, - -[Parameter(ParameterSetName="Credential")] -[Alias("RunAs","cred","c")] -[ValidateNotNullorEmpty()] -[System.Management.Automation.Credential()]$Credential = [System.Management.Automation.PSCredential]::Empty, - -[Parameter(ParameterSetName="Prompt")] -[switch]$PromptForCredential, - -[ValidateSet("Basic","CredSSP", "Default", "Digest", "Kerberos", "Negotiate", "NegotiateWithImplicitCredential","None")] -[Alias('auth','am')] -[string]$Authentication, - -[ValidateNotNullOrEmpty()] -[Alias("thumb")] -[string]$CertificateThumbprint, - -[ValidateNotNullOrEmpty()] -[string]$ConfigurationName, - -[ValidateNotNullOrEmpty()] -[ValidateRange(1, 2147483647)] -[int32]$Port, - -[System.Management.Automation.Remoting.PSSessionOption]$SessionOption, - -[Switch]$UseSSL, - -[ValidateScript({ -if (Test-Path $_) { - $True -} -else { - Throw "Cannot validate path $_" -} -})] -[string]$Profile - -) - -Begin { - Write-Verbose "Starting: $($MyInvocation.Mycommand)" - Write-Verbose "Using parameter Set: $($pscmdlet.ParameterSetName)" - Write-Verbose "PSBoundParameters" - Write-Verbose ($PSBoundParameters | Out-String) - - #disable PowerShell profiles in new ISE tabs which speeds up the process - #thanks for Tobias Weltner for the guidance on this. - Write-Verbose "Temporarily disabling PowerShell profiles in new tabs" - $type = ([Microsoft.Windows.PowerShell.Gui.Internal.MainWindow].Assembly.GetTypes()).Where({ $_.Name -eq 'PSGInternalHost' }) - $currentField = $type.GetField('current', 'NonPublic,Static') - $noprofileField = $type.GetField('noProfile', 'NonPublic,Instance') - $pshost = $currentField.GetValue($type) - $noprofileField.SetValue($pshost,$True) - - #dynamically build the Enter-PSSession Commmand - $cmdstring = "Enter-PSSession -computername {0}" - - if ($credential.username -AND $pscmdlet.ParameterSetName -eq "credential") { - #export credential to a temporary local file because each new tab is a new session - $credPath = [System.IO.Path]::GetTempFileName() - Write-Verbose "Exporting credential for $($credential.username) to $credpath" - $credential | Export-Clixml -Path $credpath - $cmdstring+= " -credential (Import-Clixml -path $credpath)" - } - - #export session option to cliXML so that it can be read into the scriptblock - if ($SessionOption) { - $optPath = [System.IO.Path]::GetTempFileName() - Write-Verbose "Exporting session options to $optPath" - $sessionOption | Export-Clixml -Path $optPath - $cmdstring += " -SessionOption (Import-cliXML -path $optPath)" - } - - if ($Authentication) {$cmdstring += " -authentication $Authentication"} - if ($CertificateThumbprint) {$cmdstring += " -CertificateThumbprint $CertificateThumbprint"} - if ($ConfigurationName) {$cmdstring += " -configurationname $ConfigurationName"} - if ($Port) {$cmdstring += " -Port $Port"} - if ($UseSSL) {$cmdstring += " -UseSSL"} - -} #begin - -Process { - - Write-Verbose "PSBoundParameters in Process" - Write-Verbose ($PSBoundParameters | Out-String) - - #copy bound parameters to a new hashtable - $testParams = $PSBoundParameters - - #remove invalid parameters - if ($profile) { - #remove profile parameter since Test-WSMan won't recognize it - $testParams.remove("profile") | Out-Null - } - if ($SessionOption) { - $testParams.remove("sessionoption") | Out-Null - } - if ($PromptForCredential) { - $testParams.remove("promptforCredential") | Out-Null - } - -#Using the ForEach() method to eke out a little bit better performance -#when processing multiple computer names -($Computername).Foreach({ - $computer = $_ - Write-Verbose "Processing: $computer" - #insert each computername - $cmd = $cmdstring -f $computer - - #insert the current computer nto the parameters for Test-WSMan - $testParams.Computername = $computer - - #remove configurationname from Test-WSMan - $testparams.Remove("ConfigurationName") | Out-Null - - #Verify Computer is accessible with Test-WSMan - Try { - - Test-WSMan @testParams -ErrorAction Stop | Out-Null - - $newtab = $psise.powershelltabs.Add() - #change the tab name - $newTab.DisplayName = $Computer.ToUpper() - if ($ConfigurationName){$newtab.DisplayName += " $ConfigurationName"} - - #wait for new tab to be created - Do { - Start-Sleep -Milliseconds 10 - } until ($newTab.CanInvoke) - - if ($PromptForCredential) { - Write-Verbose "Prompting for credential" - $NewTab.invoke("`$cred = Get-Credential -message 'Enter a credential for $($newtab.DisplayName)' -username $env:userdomain\$env:username") - Do { - Start-Sleep -Milliseconds 10 - } until ($newTab.CanInvoke) - - $cmd+= ' -credential $cred' - - } #if prompt for credential - - Write-Verbose "Executing: $cmd" - $newtab.Invoke($cmd) - - Do { - #wait until ready - start-Sleep -Milliseconds 10 - } until ($newTab.CanInvoke) - - #run some initial commands in each remote session - if ($profile) { - Write-Verbose "Launching commands from $profile" - #get contents of profile script where there are words but no comments - Get-Content $profile | where {$_ -match "\w+" -AND $_ -notmatch "#"} | - foreach { - Write-Verbose "[$($newTab.Displayname)] Invoking $_" - $newTab.Invoke($_) - #wait for command to complete - Do { - Start-Sleep -Milliseconds 10 - } until ($newTab.CanInvoke) - - } #foreach command - } #if profile script - else { - $newtab.Invoke("clear-host") - - } - } #Try - Catch { - Write-Warning "Can't create remote tab to $computer. $($_.exception.Message)." - } - }) #foreach computer - -} #process - -End { - - #re-enable PowerShell profiles - Write-Verbose "Re-enabling PowerShell ISE profiles" - $noprofileField.SetValue($pshost,$False) - - #delete credential file if it exists - if ($credpath -AND (Test-Path -path $credPath)) { - Write-Verbose "Deleting $credpath" - del $credPath -Force - } - - #delete session option file if it exists - if ($optpath -AND (Test-Path -path $optPath)) { - Write-Verbose "Deleting $optpath" - del $optPath -Force - } - Write-Verbose "Ending: $($MyInvocation.Mycommand)" - -} #end - -} #end function - -#define an alias -Set-Alias -Name nrt -Value New-ISERemoteTab diff --git a/README.md b/README.md index 34d8167..2f858eb 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,67 @@ -# New-ISERemoteTab +# ISERemoteTab + +![PSGallery Version](https://img.shields.io/powershellgallery/v/ISERemoteTab.png?style=for-the-badge&logo=powershell&label=PowerShell%20Gallery)![PSGallery Downloads](https://img.shields.io/powershellgallery/dt/ISERemoteTab.png?style=for-the-badge&label=Downloads) The module includes a PowerShell function to add new remote tabs in the PowerShell ISE. The default behavior of adding remote tabs in the ISE is very basic and offers no flexibility like specifying an alternate port. This module was created to address those limitations. This command will create one or more remote tabs in the PowerShell ISE. You could use this to programmatically to open multiple remote tabs. - PS C:\> New-ISERemoteTab -Computername $c -Credential globomantics\administrator -Authentication Default +After importing the module into the ISE be sure to read help and examples. All commands must be run in the PowerShell ISE. + +## Basic Usage + +The default behavior is to open tabs with your current credentials using [New-ISEREmoteTab](docs/New-ISERemoteTab.md). + +```powershell +New-ISERemotetab localhost +``` + +But you can specify a single credential for all remote connections, or prompt for a credential for each connection. You might need this if some of the machines require different credentials. + +```powershell +New-ISERemoteTab -Computername $c -Credential company\administrator -Authentication Default +``` + +You can also specify a VMName to use PowerShell Direct and connect to a Hyper-V virtual machine. You will need to include parameters with this option. + +```powershell +New-ISEREmoteTab -vmname srv1 -credential $admin +``` + +The original function was first demonstrated at . + +## Form Front-End + +The module also includes a second function ([New-ISEREmoteTabForm](docs/New-ISERemoteTabForm.md)) to generate a WPF form to enter remote tab information. You can enter a single computer or multiple names separated by commas. + +![Remote ISE Tab](images/remoteIsetab_thumb.png "Remote Tab Form") + +The form should handle everything except additional PSSessionOptions. If you require that level of control, you will need to use `New-ISEREmoteTab`. If you check the box for `Use VMName`, incompatible form controls will be disabled. + +_You will need to manually close the form._ + +## Profile Scripts + +Normally, you do not have a traditional PowerShell profile script when you enter a remote PSSession. But you have the option to specify a profile script that will be executed in the remote session in place of a regular profile script. The form will look in your current session for a variable called `ISERemoteProfile` which is the path to a ps1 file with your remote profile script. -The default behavior is to open tabs with your current credentials. But you can specify a single credential for all remote connections, or prompt for a credential for each connection. You might need this if some of the machines require different credentials. +You can set this in your PowerShell ISE Profile script or you can use the `Save script setting` checkbox to store the current file in the variable. -The original function is described in greater detail at http://bit.ly/1lpMoNj. +Note that this variable is only for the length of your PowerShell session and does NOT update your ISE profile. In your PowerShell ISE profile script you can add lines like this to create a menu shortcut and define a default remote profile script: -This version of the module includes a second function (New-ISERemoteForm) to generate a WPF form to enter remote tab information. -You can enter a single computer or multiple names separated by commas. +```powershell +Import-Module ISERemoteTab -![Alt Remote ISE Tab](http://jdhitsolutions.com/blog/wp-content/uploads/2016/05/remoteIsetab_thumb.png "Remote Tab Form") +$Display = "New Remote ISE Tab" +$Action = {New-ISEREmoteForm} +$Shortcut = "Ctrl+Shift+T" +$ISERemoteProfile = "C:\Scripts\RemoteProfile.ps1" -In your PowerShell ISE profile script you can add lines like this to create a menu shortcut: +$psise.CurrentPowerShellTab.AddOnsMenu.Submenus.Add($Display,$Action,$shortcut) | Out-Null +``` - Import-Module ISERemoteTab +A sample profile script, [SampleRemoteProfile.ps1](SampleRemoteProfile.ps1), is included with this module. - $Display = "New Remote ISE Tab" - $Action = {New-ISEREmoteForm} - $Shortcut = "Ctrl+Shift+T" - $ISERemoteProfile = "C:\Scripts\RemoteProfile.ps1" +## Deprecation Notice - $psise.CurrentPowerShellTab.AddOnsMenu.Submenus.Add($Display,$Action,$shortcut) | Out-Null +This module should be considered in maintenance-mode. The PowerShell ISE should be considered deprecated. I will try to address bug fixes, but do not expect any other changes or enhancements to this module. If you like the concept of separate remoting sessions, you can achieve similar results with [Windows Terminal](https://docs.microsoft.com/en-us/windows/terminal/get-started). -After importing the module into the ISE be sure to read help and examples. diff --git a/SampleRemoteProfile.ps1 b/SampleRemoteProfile.ps1 index da085f7..a7832a9 100644 --- a/SampleRemoteProfile.ps1 +++ b/SampleRemoteProfile.ps1 @@ -1,7 +1,22 @@ #this is a sample remote profile script -#each command must be a one-liner. Do not use block comments. + +#how long has this session been running? +$initiated = Get-Date + +Function prompt { + #display the session runtime without the milliseconds + $ts = ((Get-Date) - $initiated).ToString().split(".")[0] + # Write-Host ">$ts< " -ForegroundColor yellow -nonewline + Write-Host "$ts " -NoNewline -ForegroundColor Red -BackgroundColor Yellow + "PS $($executionContext.SessionState.Path.CurrentLocation)--> " +} + Set-Location -path 'C:\' Clear-Host +Write-Host "Connected to " -nonewline +Write-Host "$env:Computername" -ForegroundColor Red -BackgroundColor Yellow -NoNewline +Write-Host " as $($env:userdomain)\$($env:username)" + $PSVersionTable diff --git a/changelog.md b/changelog.md new file mode 100644 index 0000000..af840f7 Binary files /dev/null and b/changelog.md differ diff --git a/changelog.txt b/changelog.txt deleted file mode 100644 index 322dffd..0000000 Binary files a/changelog.txt and /dev/null differ diff --git a/docs/ISERemoteTab.md b/docs/ISERemoteTab.md index 2bc852f..4a62be4 100644 --- a/docs/ISERemoteTab.md +++ b/docs/ISERemoteTab.md @@ -6,17 +6,17 @@ Locale: en-US --- # ISERemoteTab Module + ## Description + A PowerShell ISE module to make it easier to create remote tabs. ## ISERemoteTab Cmdlets + ### [New-ISERemoteTab](New-ISERemoteTab.md) + This function will let you create remote tabs in the ISE that supports many of the same parameters you would get with Enter-PSSession. ### [New-ISERemoteForm](New-ISERemoteForm.md) -This function creates a WPF entry form that serves as a front end to New-ISERemoteTab. - - - - +This function creates a WPF entry form that serves as a front end to New-ISERemoteTab. diff --git a/docs/New-ISERemoteForm.md b/docs/New-ISERemoteForm.md index 07b337f..e2be727 100644 --- a/docs/New-ISERemoteForm.md +++ b/docs/New-ISERemoteForm.md @@ -4,61 +4,46 @@ schema: 2.0.0 --- # New-ISERemoteForm + ## SYNOPSIS -Create a WPF front end for New-ISERemoteTab. + +Create a WPF front-end for New-ISERemoteTab. ## SYNTAX -``` +```yaml New-ISERemoteForm [-CommonParameters] ``` ## DESCRIPTION -Run this command to create a WPF form to create one or more remote ISE tabs using the New-ISERemoteTab function. The form should handle everything except additional PSSessionOptions. - -The form will look in your current session for a variable called ISERemoteProfile which should be the path to a ps1 file with your remote profile script. -You can set this in your PowerShell ISE Profile script or you can use the Save script setting checkbox to store the current file in the variable. -Note that this variable is only for the length of your PowerShell session. -This does NOT update your ISE profile. -In your PowerShell ISE profile script you can add lines like this to create a menu shortcut and define a default remote profile script: - - Import-Module ISERemoteTab - $Display = "New Remote ISE Tab" - $Action = {New-ISEREmoteForm} - $Shortcut = "Ctrl+Shift+T" - $ISERemoteProfile = "C:\Scripts\RemoteProfile.ps1" - $psise.CurrentPowerShellTab.AddOnsMenu.Submenus.Add($Display,$Action,$shortcut) | Out-Null +Run this command to create a WPF form to create one or more remote ISE tabs using the New-ISERemoteTab function. The form should handle everything except additional PSSessionOptions. If you require that level of control, you will need to use New-ISEREmoteTab. If you check the box for "Use VMName", incompatible form controls will be disabled. You will need to manually close the form. ## EXAMPLES -### -------------------------- EXAMPLE 1 -------------------------- -``` +### EXAMPLE 1 + +```powershell PS C:\> New-ISERemoteForm ``` ## PARAMETERS + ### None + ## INPUTS + ### None + ## OUTPUTS + ### None + ## NOTES -NAME : New-ISERemoteTabForm -LAST UPDATED: July 10, 2016 -AUTHOR : Jeff Hicks \(@JeffHicks\) Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ -**************************************************************** -DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED -THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK. -IF YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, -DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING. -**************************************************************** - ## RELATED LINKS -[New-ISERemoteTab]() - +[New-ISERemoteTab](New-ISRemoteTab.md) diff --git a/docs/New-ISERemoteTab.md b/docs/New-ISERemoteTab.md index 967a2f7..09ec1a6 100644 --- a/docs/New-ISERemoteTab.md +++ b/docs/New-ISERemoteTab.md @@ -1,83 +1,108 @@ --- external help file: ISERemoteTab-help.xml +Module Name: ISERemoteTab schema: 2.0.0 --- # New-ISERemoteTab + ## SYNOPSIS + Create remote tabs in the PowerShell ISE. ## SYNTAX -### Credential +### ComputerCredential (Default) + +```yaml +New-ISERemoteTab -Computername [-Credential ] [-Authentication ] [-CertificateThumbprint ] [-ConfigurationName ] [-Port ] [-SessionOption ] [-UseSSL] [-ProfileScript ] [] ``` -New-ISERemoteTab [-Computername] [-Credential ] [-Authentication ] - [-CertificateThumbprint ] [-ConfigurationName ] [-Port ] - [-SessionOption ] [-UseSSL] [-Profile ] + +### ComputerPrompt + +```yaml +New-ISERemoteTab [-Computername ] [-PromptForCredential] [-Authentication ] [-CertificateThumbprint ] [-ConfigurationName ] [-Port ] [-SessionOption ] [-UseSSL] [-ProfileScript ] [] ``` -### Prompt +### VMPrompt + +```yaml +New-ISERemoteTab [-VMName ] [-PromptForCredential] [-ConfigurationName ] [-ProfileScript ] [] ``` -New-ISERemoteTab [-Computername] [-PromptForCredential] [-Authentication ] - [-CertificateThumbprint ] [-ConfigurationName ] [-Port ] - [-SessionOption ] [-UseSSL] [-Profile ] + +### VMCredential + +```yaml +New-ISERemoteTab [-VMName ] [-Credential ] [-ConfigurationName ] [-ProfileScript ] [] ``` ## DESCRIPTION + This command will create one or more remote tabs in the PowerShell ISE. You could use this to programmatically to open multiple remote tabs. The default behavior is to open tabs with your current credentials. But you can specify a single credential for all remote connections, or prompt for a credential for each connection. You might need this if some of the machines require different credentials. The command also supports additional parameters from Enter-PSSession. Be aware that if you specify multiple machines and one of these parameters, such as UseSSL, that parameter will apply to all remote connections. +You can also specify a VMName instead of a computername to use PowerShell Direct. This is the equivalent of running Enter-PSSession with the VmName parameter. You will need to specify a credential when using this option. + +Important: You must be in the PowerShell ISE to run this command. + ## EXAMPLES -### -------------------------- EXAMPLE 1 -------------------------- -``` +### EXAMPLE 1 + +```powershell PS C:\> New-ISERemoteTab chi-dc01 ``` Create a new remote tab for computer CHI-DC01 with default settings. -### -------------------------- EXAMPLE 2 -------------------------- -``` +### EXAMPLE 2 + +```powershell PS C:\> Get-Content c:\work\chi.txt | New-ISERemoteTab -credential mydomain\administrator ``` Create remote tabs for each computer in the list using alternate credentials. -This is also the type of command that you could put in your ISE profile script to autocreate remote tabs. +This is also the type of command that you could put in your ISE profile script to auto-create remote tabs. -### -------------------------- EXAMPLE 3 -------------------------- -``` +### EXAMPLE 3 + +```powershell PS C:\> New-ISERemoteTab dmz-srv01,dmz-srv02,dmz-srv03 -prompt ``` Create remote tabs for each computer and prompt for a unique set of credentials for each. -### -------------------------- EXAMPLE 4 -------------------------- -``` +### EXAMPLE 4 + +```powershell PS C:\> New-ISERemoteTab dmz-srv01 -Credential domain\administrator -Authentication CredSSP ``` Create a remote tab for dmz-srv01 with alternate credentials using CredSSP for authentication. -### -------------------------- EXAMPLE 5 -------------------------- -``` -PS C:\> New-ISERemoteTab dmz-srv01 -ConfigurationName Microsoft.Powershell32 +### EXAMPLE 5 + +```powershell +PS C:\> New-ISERemoteTab -vmname srv01 -ConfigurationName PowerShell.7 -credential $admin ``` -Create a remote tab for dmz-srv01 using the 32-bit configuration settings. The display name for this tab would be "dmz-srv01 Microsoft.Powershell32". +Create a remote tab for SRV01 virtual machine using the PowerShell.7 session configuration. -### -------------------------- EXAMPLE 6 -------------------------- -``` +### EXAMPLE 6 + +```powershell PS C:\> New-ISERemoteTab chi-core01,chi-core02 -profile c:\scripts\remote.ps1 ``` Create remote tabs for computers CHI-CORE01 and CHI-CORE02. Upon connection remotely run the commands in the local file c:\scripts\remote.ps1. -### -------------------------- EXAMPLE 7 -------------------------- -``` +### EXAMPLE 7 + +```powershell PS C:\> import-csv s:\computers.csv | where { test-wsman $_.computername -ErrorAction SilentlyContinue} | Out-GridView -Title "Select computers" -OutputMode Multiple | New-ISERemoteTab -Profile S:\RemoteProfile.ps1 ``` @@ -86,173 +111,215 @@ This list is then piped to Out-Gridview so that you can select one or more compu ## PARAMETERS -### -Computername -The name of the server to connect. -This parameter has an alias of CN. +### -Authentication + +Specifies the mechanism that is used to authenticate the user's credentials. +Valid values are "Default", "Basic", "Credssp", "Digest", "Kerberos", "Negotiate", and "NegotiateWithImplicitCredential". ```yaml -Type: String[] -Parameter Sets: (All) -Aliases: cn +Type: String +Parameter Sets: ComputerCredential, ComputerPrompt +Aliases: auth, am +Accepted values: Basic, CredSSP, Default, Digest, Kerberos, Negotiate, NegotiateWithImplicitCredential, None -Required: true -Position: 1 +Required: False +Position: Named Default value: none -Accept pipeline input: true (ByPropertyName, ByValue) +Accept pipeline input: False Accept wildcard characters: False ``` -### -Credential -A PSCredential or user name to be used for all specified computers. -Note that if you specify a credential, it will temporarily be exported to disk so that each new PowerShell tab can re-use it. -The file is deleted at the end of the command. - - -```yaml -Type: Object -Parameter Sets: Credential -Aliases: RunAs, cred, c - -Required: false -Position: named -Default value: [System.Management.Automation.PSCredential]::Empty -Accept pipeline input: false -Accept wildcard characters: false -``` +### -CertificateThumbprint -### -PromptForCredential -Use this parameter if you want to prompt for a credential for each connection. -No credential information is written to disk. +Specifies the digital public key certificate \(X509\) of a user account that has permission to perform this action. +Enter the certificate thumbprint of the certificate. ```yaml -Type: SwitchParameter -Parameter Sets: Prompt -Aliases: +Type: String +Parameter Sets: ComputerCredential, ComputerPrompt +Aliases: thumb Required: False Position: Named -Default value: False +Default value: none Accept pipeline input: False Accept wildcard characters: False ``` -### -Authentication -Specifies the mechanism that is used to authenticate the user's credentials. -Valid values are "Default", "Basic", "Credssp", "Digest", "Kerberos", "Negotiate", and "NegotiateWithImplicitCredential". +### -Computername + +The name of the server to connect. +This parameter has an alias of CN. ```yaml -Type: String -Parameter Sets: (All) -Aliases: auth, am +Type: String[] +Parameter Sets: ComputerCredential +Aliases: cn -Required: false -Position: named +Required: True +Position: Named Default value: none -Accept pipeline input: false -Accept wildcard characters: false +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False ``` -### -CertificateThumbprint -Specifies the digital public key certificate \(X509\) of a user account that has permission to perform this action. -Enter the certificate thumbprint of the certificate. - ```yaml -Type: String -Parameter Sets: (All) -Aliases: thumb +Type: String[] +Parameter Sets: ComputerPrompt +Aliases: cn -Required: false -Position: named +Required: False +Position: Named Default value: none -Accept pipeline input: false -Accept wildcard characters: false +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False ``` ### -ConfigurationName + Specifies the session configuration that is used for the interactive session. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: -Required: false -Position: named +Required: False +Position: Named Default value: none -Accept pipeline input: false -Accept wildcard characters: false +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +A PSCredential or user name to be used for all specified computers. +Note that if you specify a credential, it will temporarily be exported to disk so that each new PowerShell tab can re-use it. +The file is deleted at the end of the command. + +```yaml +Type: PSCredential +Parameter Sets: ComputerCredential, VMCredential +Aliases: RunAs + +Required: False +Position: Named +Default value: [System.Management.Automation.PSCredential]::Empty +Accept pipeline input: False +Accept wildcard characters: False ``` ### -Port + Specifies the network port on the remote computer used for this command. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 \(the WinRM port for HTTP\) and 5986 \(the WinRM port for HTTPS\). ```yaml Type: Int32 -Parameter Sets: (All) -Aliases: +Parameter Sets: ComputerCredential, ComputerPrompt +Aliases: -Required: false -Position: named +Required: False +Position: Named Default value: 0 -Accept pipeline input: false -Accept wildcard characters: false +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProfileScript + +Specify the path to a profile script file. + +hNormally, you do not have a traditional PowerShell profile script when you enter a remote PSSession. But you have the option to specify a profile script that will be executed in the remote session in place of a regular profile script. The form will look in your current session for a variable called ISERemoteProfile which is the path to a ps1 file with your remote profile script. + +You can set this in your PowerShell ISE Profile script or you can use the Save script setting checkbox to store the current file in the variable. + +Note that this variable is only for the length of your PowerShell session and does NOT update your ISE profile. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PromptForCredential + +Use this parameter if you want to prompt for a credential for each connection. +No credential information is written to disk. + +```yaml +Type: SwitchParameter +Parameter Sets: ComputerPrompt, VMPrompt +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False ``` ### -SessionOption + Sets advanced options for the session. Enter a SessionOption object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. ```yaml Type: PSSessionOption -Parameter Sets: (All) -Aliases: +Parameter Sets: ComputerCredential, ComputerPrompt +Aliases: -Required: false -Position: named +Required: False +Position: Named Default value: none -Accept pipeline input: false -Accept wildcard characters: false +Accept pipeline input: False +Accept wildcard characters: False ``` ### -UseSSL + Uses the Secure Sockets Layer \(SSL\) protocol to establish a connection to the remote computer. By default, SSL is not used. ```yaml Type: SwitchParameter -Parameter Sets: (All) -Aliases: +Parameter Sets: ComputerCredential, ComputerPrompt +Aliases: -Required: false -Position: named +Required: False +Position: Named Default value: false -Accept pipeline input: false -Accept wildcard characters: false +Accept pipeline input: False +Accept wildcard characters: False ``` -### -Profile -The path to a local file with PowerShell commands to be executed remotely upon connection. Each command in the script must be on a single line. This is a way to run a profile script in the remote session. Here is an profile script example: - # Sample remote profile script - cd c:\\ - cls - Get-WMIObject -class Win32_OperatingSystem | Select @{Name="OS";Expression = {$_.Caption}},@{Name="PSVersion";Expression = {$PSVersionTable.PSVersion}} +### -VMName -Do not use any block comments in your remote profile script. See examples for additional help. +Specify the name of Nyper-V virtual machines that you will connect to using PowerShell Direct. ```yaml Type: String -Parameter Sets: (All) -Aliases: +Parameter Sets: VMPrompt, VMCredential +Aliases: -Required: false -Position: named -Default value: none -Accept pipeline input: false -Accept wildcard characters: false +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 ### [string] @@ -262,25 +329,14 @@ Accept wildcard characters: false ### none ## NOTES -Last Updated: July 10, 2016 -Author : Jeff Hicks \(http://twitter.com/JeffHicks\) -Version : 1.5.0 Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ - -**************************************************************** -DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED -THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK. -IF YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, -DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING. -**************************************************************** - ## RELATED LINKS [Enter-PSSession]() -[Test-WSMan]() -[New-ISERemoteForm]() +[Test-WSMan]() +[New-ISERemoteForm](New-ISERemoteForm.md) diff --git a/en-US/ISERemoteTab-help.xml b/en-US/ISERemoteTab-help.xml index 8e32fb7..f402913 100644 --- a/en-US/ISERemoteTab-help.xml +++ b/en-US/ISERemoteTab-help.xml @@ -1,433 +1,673 @@ - - - - -New-ISERemoteForm -New -ISERemoteForm -Create a WPF front end for New-ISERemoteTab. - - - -Run this command to create a WPF form to create one or more remote ISE tabs using the New-ISERemoteTab function. The form should handle everything except additional PSSessionOptions. - -The form will look in your current session for a variable called ISERemoteProfile which should be the path to a ps1 file with your remote profile script. You can set this in your PowerShell ISE Profile script or you can use the Save script setting checkbox to store the current file in the variable. Note that this variable is only for the length of your PowerShell session. This does NOT update your ISE profile. - -In your PowerShell ISE profile script you can add lines like this to create a menu shortcut and define a default remote profile script: - - -Import-Module ISERemoteTab -$Display = "New Remote ISE Tab" -$Action = {New-ISEREmoteForm} -$Shortcut = "Ctrl+Shift+T" -$ISERemoteProfile = "C:\Scripts\RemoteProfile.ps1" -$psise.CurrentPowerShellTab.AddOnsMenu.Submenus.Add($Display,$Action,$shortcut) | Out-Null - - -New-ISERemoteForm - - -None - - - - - - -None - - - - - - - -NAME : New-ISERemoteTabForm -LAST UPDATED: July 10, 2016 -AUTHOR : Jeff Hicks (@JeffHicks) - - -Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ - -************************************************************ -DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED -THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK. IF -YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, -DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING. -************************************************************ - - - --------------------------- EXAMPLE 1 -------------------------- -PS C:\> New-ISERemoteForm - - - - - -New-ISERemoteTab - - - - - -New-ISERemoteTab -New -ISERemoteTab -Create remote tabs in the PowerShell ISE. - - - -This command will create one or more remote tabs in the PowerShell ISE. You could use this to programmatically to open multiple remote tabs. The default behavior is to open tabs with your current credentials. But you can specify a single credential for all remote connections, or prompt for a credential for each connection. You might need this if some of the machines require different credentials. - -The command also supports additional parameters from Enter-PSSession. - -Be aware that if you specify multiple machines and one of these parameters, such as UseSSL, that parameter will apply to all remote connections. - - -New-ISERemoteTab -Computername -The name of the server to connect. This parameter has an alias of CN. - - -String[] -String[] - -none - -Credential -A PSCredential or user name to be used for all specified computers. Note that if you specify a credential, it will temporarily be exported to disk so that each new PowerShell tab can re-use it. The file is deleted at the end of the command. - - -Object -Object - -[System.Management.Automation.PSCredential]::Empty - -Authentication -Specifies the mechanism that is used to authenticate the user's credentials. Valid values are "Default", "Basic", "Credssp", "Digest", "Kerberos", "Negotiate", and "NegotiateWithImplicitCredential". - - -String -String - -none - -CertificateThumbprint -Specifies the digital public key certificate (X509) of a user account that has permission to perform this action. Enter the certificate thumbprint of the certificate. - - -String -String - -none - -ConfigurationName -Specifies the session configuration that is used for the interactive session. - - -String -String - -none - -Port -Specifies the network port on the remote computer used for this command. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). - - -Int32 -Int32 - -0 - -SessionOption -Sets advanced options for the session. Enter a SessionOption object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. - - -PSSessionOption -PSSessionOption - -none - -UseSSL -Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used. - - -SwitchParameter - -false - -Profile -The path to a local file with PowerShell commands to be executed remotely upon connection. Each command in the script must be on a single line. This is a way to run a profile script in the remote session. Here is an profile script example: # Sample remote profile script cd c:\ cls Get-WMIObject -class Win32_OperatingSystem | Select @{Name="OS";Expression = {$_.Caption}},@{Name="PSVersion";Expression = {$PSVersionTable.PSVersion}} - -Do not use any block comments in your remote profile script. See examples for additional help. - - -String -String - - - - -New-ISERemoteTab -Computername -The name of the server to connect. This parameter has an alias of CN. - - -String[] -String[] - -none - -Authentication -Specifies the mechanism that is used to authenticate the user's credentials. Valid values are "Default", "Basic", "Credssp", "Digest", "Kerberos", "Negotiate", and "NegotiateWithImplicitCredential". - - -String -String - -none - -CertificateThumbprint -Specifies the digital public key certificate (X509) of a user account that has permission to perform this action. Enter the certificate thumbprint of the certificate. - - -String -String - -none - -ConfigurationName -Specifies the session configuration that is used for the interactive session. - - -String -String - -none - -Port -Specifies the network port on the remote computer used for this command. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). - - -Int32 -Int32 - -0 - -SessionOption -Sets advanced options for the session. Enter a SessionOption object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. - - -PSSessionOption -PSSessionOption - -none - -UseSSL -Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used. - - -SwitchParameter - -false - -Profile -The path to a local file with PowerShell commands to be executed remotely upon connection. Each command in the script must be on a single line. This is a way to run a profile script in the remote session. Here is an profile script example: # Sample remote profile script cd c:\ cls Get-WMIObject -class Win32_OperatingSystem | Select @{Name="OS";Expression = {$_.Caption}},@{Name="PSVersion";Expression = {$PSVersionTable.PSVersion}} - -Do not use any block comments in your remote profile script. See examples for additional help. - - -String -String - - - -PromptForCredential -Use this parameter if you want to prompt for a credential for each connection. No credential information is written to disk. - - -SwitchParameter - -False - - - -Computername -The name of the server to connect. This parameter has an alias of CN. - - -String[] -String[] - -none - -Credential -A PSCredential or user name to be used for all specified computers. Note that if you specify a credential, it will temporarily be exported to disk so that each new PowerShell tab can re-use it. The file is deleted at the end of the command. - - -Object -Object - -[System.Management.Automation.PSCredential]::Empty - -PromptForCredential -Use this parameter if you want to prompt for a credential for each connection. No credential information is written to disk. - - -SwitchParameter -SwitchParameter - -False - -Authentication -Specifies the mechanism that is used to authenticate the user's credentials. Valid values are "Default", "Basic", "Credssp", "Digest", "Kerberos", "Negotiate", and "NegotiateWithImplicitCredential". - - -String -String - -none - -CertificateThumbprint -Specifies the digital public key certificate (X509) of a user account that has permission to perform this action. Enter the certificate thumbprint of the certificate. - - -String -String - -none - -ConfigurationName -Specifies the session configuration that is used for the interactive session. - - -String -String - -none - -Port -Specifies the network port on the remote computer used for this command. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). - - -Int32 -Int32 - -0 - -SessionOption -Sets advanced options for the session. Enter a SessionOption object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. - - -PSSessionOption -PSSessionOption - -none - -UseSSL -Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used. - - -SwitchParameter -SwitchParameter - -false - -Profile -The path to a local file with PowerShell commands to be executed remotely upon connection. Each command in the script must be on a single line. This is a way to run a profile script in the remote session. Here is an profile script example: # Sample remote profile script cd c:\ cls Get-WMIObject -class Win32_OperatingSystem | Select @{Name="OS";Expression = {$_.Caption}},@{Name="PSVersion";Expression = {$PSVersionTable.PSVersion}} - -Do not use any block comments in your remote profile script. See examples for additional help. - - -String -String - -none - - -[string] - - - - - - -none - - - - - - - -Last Updated: July 10, 2016 -Author : Jeff Hicks (http://twitter.com/JeffHicks) -Version : 1.5.0 - -Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ - -************************************************************ -DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED -THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK. IF -YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, -DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING. -************************************************************ - - - --------------------------- EXAMPLE 1 -------------------------- -PS C:\> New-ISERemoteTab chi-dc01 -Create a new remote tab for computer CHI-DC01 with default settings. - - - --------------------------- EXAMPLE 2 -------------------------- -PS C:\> Get-Content c:\work\chi.txt | New-ISERemoteTab -credential mydomain\administrator -Create remote tabs for each computer in the list using alternate credentials. This is also the type of command that you could put in your ISE profile script to autocreate remote tabs. - - - --------------------------- EXAMPLE 3 -------------------------- -PS C:\> New-ISERemoteTab dmz-srv01,dmz-srv02,dmz-srv03 -prompt -Create remote tabs for each computer and prompt for a unique set of credentials for each. - - - --------------------------- EXAMPLE 4 -------------------------- -PS C:\> New-ISERemoteTab dmz-srv01 -Credential domain\administrator -Authentication CredSSP -Create a remote tab for dmz-srv01 with alternate credentials using CredSSP for authentication. - - - --------------------------- EXAMPLE 5 -------------------------- -PS C:\> New-ISERemoteTab dmz-srv01 -ConfigurationName Microsoft.Powershell32 -Create a remote tab for dmz-srv01 using the 32-bit configuration settings. The display name for this tab would be "dmz-srv01 Microsoft.Powershell32". - - - --------------------------- EXAMPLE 6 -------------------------- -PS C:\> New-ISERemoteTab chi-core01,chi-core02 -profile c:\scripts\remote.ps1 -Create remote tabs for computers CHI-CORE01 and CHI-CORE02. Upon connection remotely run the commands in the local file c:\scripts\remote.ps1. - - - --------------------------- EXAMPLE 7 -------------------------- -PS C:\> import-csv s:\computers.csv | where { test-wsman $_.computername -ErrorAction SilentlyContinue} | Out-GridView -Title "Select computers" -OutputMode Multiple | New-ISERemoteTab -Profile S:\RemoteProfile.ps1 -Import a list of computers and filter those that respond to Test-WSMan. This list is then piped to Out-Gridview so that you can select one or more computers to connect to using a remote profile script and current credentials. - - - - -Enter-PSSession - - -Test-WSMan - - -New-ISERemoteForm - - - - - + + + + + New-ISERemoteForm + New + ISERemoteForm + + Create a WPF front-end for New-ISERemoteTab. + + + + Run this command to create a WPF form to create one or more remote ISE tabs using the New-ISERemoteTab function. The form should handle everything except additional PSSessionOptions. If you require that level of control, you will need to use New-ISEREmoteTab. If you check the box for "Use VMName", incompatible form controls will be disabled. You will need to manually close the form. + + + + New-ISERemoteForm + + + + + None + + + + + + + + + None + + + + + + None + + + + + + + + + + None + + + + + + + + + Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ + + + + + -------------------------- EXAMPLE 1 -------------------------- + PS C:\> New-ISERemoteForm + + + + + + + + New-ISERemoteTab + + + + + + + New-ISERemoteTab + New + ISERemoteTab + + Create remote tabs in the PowerShell ISE. + + + + This command will create one or more remote tabs in the PowerShell ISE. You could use this to programmatically to open multiple remote tabs. The default behavior is to open tabs with your current credentials. But you can specify a single credential for all remote connections, or prompt for a credential for each connection. You might need this if some of the machines require different credentials. + The command also supports additional parameters from Enter-PSSession. + Be aware that if you specify multiple machines and one of these parameters, such as UseSSL, that parameter will apply to all remote connections. + You can also specify a VMName instead of a computername to use PowerShell Direct. This is the equivalent of running Enter-PSSession with the VmName parameter. You will need to specify a credential when using this option. + Important: You must be in the PowerShell ISE to run this command. + + + + New-ISERemoteTab + + Authentication + + Specifies the mechanism that is used to authenticate the user's credentials. Valid values are "Default", "Basic", "Credssp", "Digest", "Kerberos", "Negotiate", and "NegotiateWithImplicitCredential". + + + Basic + CredSSP + Default + Digest + Kerberos + Negotiate + NegotiateWithImplicitCredential + None + + String + + String + + + none + + + CertificateThumbprint + + Specifies the digital public key certificate (X509) of a user account that has permission to perform this action. Enter the certificate thumbprint of the certificate. + + String + + String + + + none + + + Computername + + The name of the server to connect. This parameter has an alias of CN. + + String[] + + String[] + + + none + + + ConfigurationName + + Specifies the session configuration that is used for the interactive session. + + String + + String + + + none + + + Credential + + A PSCredential or user name to be used for all specified computers. Note that if you specify a credential, it will temporarily be exported to disk so that each new PowerShell tab can re-use it. The file is deleted at the end of the command. + + PSCredential + + PSCredential + + + [System.Management.Automation.PSCredential]::Empty + + + Port + + Specifies the network port on the remote computer used for this command. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). + + Int32 + + Int32 + + + 0 + + + ProfileScript + + Specify the path to a profile script file. + hNormally, you do not have a traditional PowerShell profile script when you enter a remote PSSession. But you have the option to specify a profile script that will be executed in the remote session in place of a regular profile script. The form will look in your current session for a variable called ISERemoteProfile which is the path to a ps1 file with your remote profile script. + You can set this in your PowerShell ISE Profile script or you can use the Save script setting checkbox to store the current file in the variable. + Note that this variable is only for the length of your PowerShell session and does NOT update your ISE profile. + + String + + String + + + None + + + SessionOption + + Sets advanced options for the session. Enter a SessionOption object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. + + PSSessionOption + + PSSessionOption + + + none + + + UseSSL + + Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used. + + + SwitchParameter + + + false + + + + New-ISERemoteTab + + Authentication + + Specifies the mechanism that is used to authenticate the user's credentials. Valid values are "Default", "Basic", "Credssp", "Digest", "Kerberos", "Negotiate", and "NegotiateWithImplicitCredential". + + + Basic + CredSSP + Default + Digest + Kerberos + Negotiate + NegotiateWithImplicitCredential + None + + String + + String + + + none + + + CertificateThumbprint + + Specifies the digital public key certificate (X509) of a user account that has permission to perform this action. Enter the certificate thumbprint of the certificate. + + String + + String + + + none + + + Computername + + The name of the server to connect. This parameter has an alias of CN. + + String[] + + String[] + + + none + + + ConfigurationName + + Specifies the session configuration that is used for the interactive session. + + String + + String + + + none + + + Port + + Specifies the network port on the remote computer used for this command. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). + + Int32 + + Int32 + + + 0 + + + ProfileScript + + Specify the path to a profile script file. + hNormally, you do not have a traditional PowerShell profile script when you enter a remote PSSession. But you have the option to specify a profile script that will be executed in the remote session in place of a regular profile script. The form will look in your current session for a variable called ISERemoteProfile which is the path to a ps1 file with your remote profile script. + You can set this in your PowerShell ISE Profile script or you can use the Save script setting checkbox to store the current file in the variable. + Note that this variable is only for the length of your PowerShell session and does NOT update your ISE profile. + + String + + String + + + None + + + PromptForCredential + + Use this parameter if you want to prompt for a credential for each connection. No credential information is written to disk. + + + SwitchParameter + + + False + + + SessionOption + + Sets advanced options for the session. Enter a SessionOption object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. + + PSSessionOption + + PSSessionOption + + + none + + + UseSSL + + Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used. + + + SwitchParameter + + + false + + + + New-ISERemoteTab + + ConfigurationName + + Specifies the session configuration that is used for the interactive session. + + String + + String + + + none + + + Credential + + A PSCredential or user name to be used for all specified computers. Note that if you specify a credential, it will temporarily be exported to disk so that each new PowerShell tab can re-use it. The file is deleted at the end of the command. + + PSCredential + + PSCredential + + + [System.Management.Automation.PSCredential]::Empty + + + ProfileScript + + Specify the path to a profile script file. + hNormally, you do not have a traditional PowerShell profile script when you enter a remote PSSession. But you have the option to specify a profile script that will be executed in the remote session in place of a regular profile script. The form will look in your current session for a variable called ISERemoteProfile which is the path to a ps1 file with your remote profile script. + You can set this in your PowerShell ISE Profile script or you can use the Save script setting checkbox to store the current file in the variable. + Note that this variable is only for the length of your PowerShell session and does NOT update your ISE profile. + + String + + String + + + None + + + VMName + + Specify the name of Nyper-V virtual machines that you will connect to using PowerShell Direct. + + String + + String + + + None + + + + New-ISERemoteTab + + ConfigurationName + + Specifies the session configuration that is used for the interactive session. + + String + + String + + + none + + + ProfileScript + + Specify the path to a profile script file. + hNormally, you do not have a traditional PowerShell profile script when you enter a remote PSSession. But you have the option to specify a profile script that will be executed in the remote session in place of a regular profile script. The form will look in your current session for a variable called ISERemoteProfile which is the path to a ps1 file with your remote profile script. + You can set this in your PowerShell ISE Profile script or you can use the Save script setting checkbox to store the current file in the variable. + Note that this variable is only for the length of your PowerShell session and does NOT update your ISE profile. + + String + + String + + + None + + + PromptForCredential + + Use this parameter if you want to prompt for a credential for each connection. No credential information is written to disk. + + + SwitchParameter + + + False + + + VMName + + Specify the name of Nyper-V virtual machines that you will connect to using PowerShell Direct. + + String + + String + + + None + + + + + + Authentication + + Specifies the mechanism that is used to authenticate the user's credentials. Valid values are "Default", "Basic", "Credssp", "Digest", "Kerberos", "Negotiate", and "NegotiateWithImplicitCredential". + + String + + String + + + none + + + CertificateThumbprint + + Specifies the digital public key certificate (X509) of a user account that has permission to perform this action. Enter the certificate thumbprint of the certificate. + + String + + String + + + none + + + Computername + + The name of the server to connect. This parameter has an alias of CN. + + String[] + + String[] + + + none + + + ConfigurationName + + Specifies the session configuration that is used for the interactive session. + + String + + String + + + none + + + Credential + + A PSCredential or user name to be used for all specified computers. Note that if you specify a credential, it will temporarily be exported to disk so that each new PowerShell tab can re-use it. The file is deleted at the end of the command. + + PSCredential + + PSCredential + + + [System.Management.Automation.PSCredential]::Empty + + + Port + + Specifies the network port on the remote computer used for this command. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). + + Int32 + + Int32 + + + 0 + + + ProfileScript + + Specify the path to a profile script file. + hNormally, you do not have a traditional PowerShell profile script when you enter a remote PSSession. But you have the option to specify a profile script that will be executed in the remote session in place of a regular profile script. The form will look in your current session for a variable called ISERemoteProfile which is the path to a ps1 file with your remote profile script. + You can set this in your PowerShell ISE Profile script or you can use the Save script setting checkbox to store the current file in the variable. + Note that this variable is only for the length of your PowerShell session and does NOT update your ISE profile. + + String + + String + + + None + + + PromptForCredential + + Use this parameter if you want to prompt for a credential for each connection. No credential information is written to disk. + + SwitchParameter + + SwitchParameter + + + False + + + SessionOption + + Sets advanced options for the session. Enter a SessionOption object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. + + PSSessionOption + + PSSessionOption + + + none + + + UseSSL + + Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used. + + SwitchParameter + + SwitchParameter + + + false + + + VMName + + Specify the name of Nyper-V virtual machines that you will connect to using PowerShell Direct. + + String + + String + + + None + + + + + + [string] + + + + + + + + + + none + + + + + + + + + Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ + + + + + -------------------------- EXAMPLE 1 -------------------------- + PS C:\> New-ISERemoteTab chi-dc01 + + Create a new remote tab for computer CHI-DC01 with default settings. + + + + -------------------------- EXAMPLE 2 -------------------------- + PS C:\> Get-Content c:\work\chi.txt | New-ISERemoteTab -credential mydomain\administrator + + Create remote tabs for each computer in the list using alternate credentials. This is also the type of command that you could put in your ISE profile script to auto-create remote tabs. + + + + -------------------------- EXAMPLE 3 -------------------------- + PS C:\> New-ISERemoteTab dmz-srv01,dmz-srv02,dmz-srv03 -prompt + + Create remote tabs for each computer and prompt for a unique set of credentials for each. + + + + -------------------------- EXAMPLE 4 -------------------------- + PS C:\> New-ISERemoteTab dmz-srv01 -Credential domain\administrator -Authentication CredSSP + + Create a remote tab for dmz-srv01 with alternate credentials using CredSSP for authentication. + + + + -------------------------- EXAMPLE 5 -------------------------- + PS C:\> New-ISERemoteTab -vmname srv01 -ConfigurationName PowerShell.7 -credential $admin + + Create a remote tab for SRV01 virtual machine using the PowerShell.7 session configuration. + + + + -------------------------- EXAMPLE 6 -------------------------- + PS C:\> New-ISERemoteTab chi-core01,chi-core02 -profile c:\scripts\remote.ps1 + + Create remote tabs for computers CHI-CORE01 and CHI-CORE02. Upon connection remotely run the commands in the local file c:\scripts\remote.ps1. + + + + -------------------------- EXAMPLE 7 -------------------------- + PS C:\> import-csv s:\computers.csv | where { test-wsman $_.computername -ErrorAction SilentlyContinue} | Out-GridView -Title "Select computers" -OutputMode Multiple | New-ISERemoteTab -Profile S:\RemoteProfile.ps1 + + Import a list of computers and filter those that respond to Test-WSMan. This list is then piped to Out-Gridview so that you can select one or more computers to connect to using a remote profile script and current credentials. + + + + + + Enter-PSSession + + + + Test-WSMan + + + + New-ISERemoteForm + + + + + \ No newline at end of file diff --git a/functions/New-ISERemoteTab.ps1 b/functions/New-ISERemoteTab.ps1 new file mode 100644 index 0000000..699d63f --- /dev/null +++ b/functions/New-ISERemoteTab.ps1 @@ -0,0 +1,254 @@ + +Function New-ISERemoteTab { + + [cmdletbinding(DefaultParameterSetName = "ComputerCredential")] + [alias("nrt")] + [OutputType("None")] + + Param( + [Parameter( + Position = 0, + Mandatory, + HelpMessage = "Enter the name of a remote computer", + ValueFromPipeline, + ValueFromPipelineByPropertyName, + ParameterSetName = "ComputerCredential" + )] + [Parameter(ParameterSetName = "ComputerPrompt")] + [ValidateNotNullorEmpty()] + [Alias("cn")] + [string[]]$Computername, + + [Parameter( + ParameterSetName = "VMCredential", + HelpMessage = "Specifies the name of a virtual machine. The connection will be made using PowerShell Direct." + )] + [Parameter(ParameterSetName = "VMPrompt")] + [string]$VMName, + + [Parameter(ParameterSetName = "ComputerCredential")] + [Parameter(ParameterSetName = "VMCredential")] + [Alias("RunAs")] + [ValidateNotNullorEmpty()] + [PSCredential]$Credential, + + [Parameter(ParameterSetName = "ComputerPrompt")] + [Parameter(ParameterSetName = "VMPrompt")] + [switch]$PromptForCredential, + + [Parameter(ParameterSetName = "ComputerPrompt")] + [Parameter(ParameterSetName = "ComputerCredential")] + [ValidateSet("Basic", "CredSSP", "Default", "Digest", "Kerberos", "Negotiate", "NegotiateWithImplicitCredential", "None")] + [Alias('auth', 'am')] + [string]$Authentication, + + [Parameter(ParameterSetName = "ComputerPrompt")] + [Parameter(ParameterSetName = "ComputerCredential")] + [ValidateNotNullOrEmpty()] + [Alias("thumb")] + [string]$CertificateThumbprint, + + [ValidateNotNullOrEmpty()] + [string]$ConfigurationName, + + [Parameter(ParameterSetName = "ComputerPrompt")] + [Parameter(ParameterSetName = "ComputerCredential")] + [ValidateNotNullOrEmpty()] + [ValidateRange(1, 2147483647)] + [int32]$Port, + + [Parameter(ParameterSetName = "ComputerPrompt")] + [Parameter(ParameterSetName = "ComputerCredential")] + [System.Management.Automation.Remoting.PSSessionOption]$SessionOption, + + [Parameter(ParameterSetName = "ComputerPrompt")] + [Parameter(ParameterSetName = "ComputerCredential")] + [Switch]$UseSSL, + + [ValidateScript( { + if (Test-Path $_) { + $True + } + else { + Throw "Cannot validate path $_" + } + })] + [string]$ProfileScript + ) + + Begin { + Write-Verbose "Starting: $($MyInvocation.Mycommand)" + Write-Verbose "Using parameter Set: $($pscmdlet.ParameterSetName)" + Write-Verbose "PSBoundParameters" + Write-Verbose ($PSBoundParameters | Out-String) + + #disable PowerShell profiles in new ISE tabs which speeds up the process + #thanks for Tobias Weltner for the guidance on this. + Write-Verbose "Temporarily disabling PowerShell profiles in new ISE tabs" + $type = ([Microsoft.Windows.PowerShell.Gui.Internal.MainWindow].Assembly.GetTypes()).Where( { $_.Name -eq 'PSGInternalHost' }) + $currentField = $type.GetField('current', 'NonPublic,Static') + $noprofileField = $type.GetField('noProfile', 'NonPublic,Instance') + $pshost = $currentField.GetValue($type) + $noprofileField.SetValue($pshost, $True) + + #dynamically build the Enter-PSSession Commmand as a string so that it can + #be invoked + if ($pscmdlet.ParameterSetName -like "VM*") { + $cmdstring = "Enter-PSSession -VMName {0}" + } + else { + $cmdstring = "Enter-PSSession -computername {0}" + } + + if ($credential.username -AND $pscmdlet.ParameterSetName -like "*credential") { + #export credential to a temporary local file because each new tab is a new session + $credPath = [System.IO.Path]::GetTempFileName() + Write-Verbose "Exporting credential for $($credential.username) to $credpath" + $credential | Export-Clixml -Path $credpath + $cmdstring += " -credential (Import-Clixml -path $credpath)" + } + + #export session option to cliXML so that it can be read into the scriptblock + if ($SessionOption) { + $optPath = [System.IO.Path]::GetTempFileName() + Write-Verbose "Exporting session options to $optPath" + $sessionOption | Export-Clixml -Path $optPath + $cmdstring += " -SessionOption (Import-cliXML -path $optPath)" + } + + if ($Authentication) { $cmdstring += " -authentication $Authentication" } + if ($CertificateThumbprint) { $cmdstring += " -CertificateThumbprint $CertificateThumbprint" } + if ($ConfigurationName) { $cmdstring += " -configurationname $ConfigurationName" } + if ($Port) { $cmdstring += " -Port $Port" } + if ($UseSSL) { $cmdstring += " -UseSSL" } + + } #begin + + Process { + + Write-Verbose "PSBoundParameters in Process" + Write-Verbose ($PSBoundParameters | Out-String) + + #copy bound parameters to a new hashtable + $testParams = $PSBoundParameters + + #remove invalid parameters + if ($ProfileScript) { + #remove profile parameter since Test-WSMan won't recognize it + [void]$testParams.remove("profilescript") + } + if ($SessionOption) { + [void]$testParams.remove("sessionoption") + } + if ($PromptForCredential) { + [void]$testParams.remove("promptforCredential") + } + + #Using the ForEach() method to eke out a little bit better performance + #when processing multiple computer names + if ($pscmdlet.ParameterSetName -like "VM*") { + if ($Credential -OR $PromptForCredential) { + $Remote = $VMName + } + else { + Write-Warning "You must specify a credential when connecting to a VM." + #bail out + Return + } + } + else { + $remote = $Computername + } + ($Remote).Foreach( { + $computer = $_.ToUpper() + Write-Verbose "Processing: $computer" + #insert each computername + $cmd = $cmdstring -f $computer + + Try { + if ($psise.powershelltabs.displayname -contains $computer) { + Throw "A tab with computername [$($computer.toUpper())] is already open." + } + $newtab = $psise.powershelltabs.Add() + #change the tab name + $newTab.DisplayName = $Computer.ToUpper() + if ($ConfigurationName) { + $newtab.DisplayName += " $ConfigurationName" + } + + #wait for new tab to be created + Do { + Start-Sleep -Milliseconds 10 + } until ($newTab.CanInvoke) + + if ($PromptForCredential) { + Write-Verbose "Prompting for credential" + $NewTab.invoke("`$cred = Get-Credential -message 'Enter a credential for $($newtab.DisplayName)'") + Do { + Start-Sleep -Milliseconds 10 + } until ($newTab.CanInvoke) + + $cmd += ' -credential $cred' + + } #if prompt for credential + + Write-Verbose "Executing: $cmd" + #need to verify the Enter-PSSession command was successful + $newtab.Invoke($cmd) + do { + Start-Sleep -Milliseconds 50 + } Until ($newtab.CanInvoke) + + Write-Verbose $newtab.ConsolePane.Text + if ($newtab.ConsolePane.Text -notmatch 'error') { + Do { + #wait until ready + Start-Sleep -Milliseconds 10 + } until ($newTab.CanInvoke) + + #run some initial commands in each remote session + if ($ProfileScript) { + Write-Verbose "Launching commands from $profile" + $profilecontent = Get-Content -Path $ProfileScript -Raw + $sb = [scriptblock]::Create($profilecontent) + [void]$newtab.Invoke($sb) + + } #if profile script + else { + $newtab.Invoke("clear-host") + } + } + else { + Write-Warning $newtab.ConsolePane.text + } + } #Try + Catch { + Write-Warning "Can't create remote tab to $computer. $($_.exception.Message)." + } + }) #foreach computer + + } #process + + End { + + #re-enable PowerShell profiles + Write-Verbose "Re-enabling PowerShell ISE profiles" + $noprofileField.SetValue($pshost, $False) + + #delete credential file if it exists + if ($credpath -AND (Test-Path -Path $credPath)) { + Write-Verbose "Deleting $credpath" + Remove-Item $credPath -Force + } + + #delete session option file if it exists + if ($optpath -AND (Test-Path -Path $optPath)) { + Write-Verbose "Deleting $optpath" + Remove-Item $optPath -Force + } + Write-Verbose "Ending: $($MyInvocation.Mycommand)" + + } #end + +} #end function + diff --git a/New-ISERemoteTabForm.ps1 b/functions/New-ISERemoteTabForm.ps1 similarity index 54% rename from New-ISERemoteTabForm.ps1 rename to functions/New-ISERemoteTabForm.ps1 index 4ff3fae..793de93 100644 --- a/New-ISERemoteTabForm.ps1 +++ b/functions/New-ISERemoteTabForm.ps1 @@ -3,23 +3,24 @@ Function New-ISERemoteForm { - -[cmdletbinding()] -Param() - -Add-Type -AssemblyName PresentationFramework -Add-Type -AssemblyName PresentationCore -Add-Type -AssemblyName WindowsBase - -#define the form XAML -[xml]$xaml=@" - + Title="New Remote ISE Tab" Height="350" Width="525"> @@ -27,16 +28,17 @@ Add-Type -AssemblyName WindowsBase - + + +