Uso di JEAUsing JEA

Questo articolo illustra i vari modi in cui è possibile connettersi e usare un endpoint JEA.This article describes the various ways you can connect to and use a JEA endpoint.

Uso interattivo di JEAUsing JEA interactively

Se si esegue il test della configurazione JEA oppure se gli utenti devono eseguire attività semplici, è possibile usare JEA allo stesso modo di una normale sessione di comunicazione remota di PowerShell.If you're testing your JEA configuration or have simple tasks for users, you can use JEA the same way you would a regular PowerShell remoting session. Per le attività di comunicazione remota complesse, è consigliabile usare la comunicazione remota implicita.For complex remoting tasks, it's recommended to use implicit remoting. La comunicazione remota implicita consente agli utenti di operare con gli oggetti dati in locale.Implicit remoting allows users to operate with the data objects locally.

Per usare JEA in modo interattivo, sono necessari:To use JEA interactively, you need:

  • Il nome del computer a cui si è connessi (può essere il computer locale)The name of the computer you're connecting to (can be the local machine)
  • Il nome dell'endpoint JEA registrato nel computerThe name of the JEA endpoint registered on that computer
  • Le credenziali che hanno accesso all'endpoint JEA nel computerCredentials that have access to the JEA endpoint on that computer

Con queste informazioni a disposizione, è possibile avviare una sessione JEA usando i cmdlet New-PSSession o Enter-PSSession.Given that information, you can start a JEA session using the New-PSSession or Enter-PSSession cmdlets.

$nonAdminCred = Get-Credential
Enter-PSSession -ComputerName localhost -ConfigurationName JEAMaintenance -Credential $nonAdminCred

Se l'account utente corrente ha accesso all'endopoint JEA, è possibile omettere il parametro Credential .If the current user account has access to the JEA endpoint, you can omit the Credential parameter.

Quando il prompt di PowerShell diventa [localhost]: PS> indica che si sta interagendo con la sessione remota JEA.When the PowerShell prompt changes to [localhost]: PS> you know that you're now interacting with the remote JEA session. È possibile eseguire Get-Command per verificare i comandi disponibili.You can run Get-Command to check which commands are available. Contattare l'amministratore per verificare se sono presenti eventuali limitazioni per i parametri disponibili o per i valori dei parametri consentiti.Consult with your administrator to learn if there are any restrictions on the available parameters or allowed parameter values.

Tenere presente che le sessioni JEA operano in modalità NoLanguage.Remember, JEA sessions operate in NoLanguage mode. È possibile che alcuni dei metodi con cui si usa generalmente PowerShell non siano disponibili.Some of the ways you typically use PowerShell may not be available. Ad esempio, non è possibile usare variabili per archiviare i dati o controllare le proprietà degli oggetti restituiti dai cmdlet.For instance, you can't use variables to store data or inspect the properties on objects returned from cmdlets. L'esempio seguente illustra due approcci per ottenere gli stessi comandi per lavorare in modalità NoLanguage.The following example shows two approaches to get the same commands to work in NoLanguage mode.

# Using variables is prohibited in NoLanguage mode. The following will not work:
# $vm = Get-VM -Name 'SQL01'
# Start-VM -VM $vm

# You can use pipes to pass data through to commands that accept input from the pipeline
Get-VM -Name 'SQL01' | Start-VM

# You can also wrap subcommands in parentheses and enter them inline as arguments
Start-VM -VM (Get-VM -Name 'SQL01')

# You can also use parameter sets that don't require extra data to be passed in
Start-VM -VMName 'SQL01'

Per chiamate di comandi più complesse che rendono difficile questo approccio, è consigliabile usare la comunicazione remota implicita o creare funzioni personalizzate che eseguono il wrapping della funzionalità desiderata.For more complex command invocations that make this approach difficult, consider using implicit remoting or creating custom functions that wrap the functionality you require.

Uso di JEA con comunicazione remota implicitaUsing JEA with implicit remoting

PowerShell ha un modello di comunicazione remota implicita che consente di importare cmdlet del proxy da un computer remoto e usarli come comandi locali.PowerShell has an implicit remoting model that lets you import proxy cmdlets from a remote machine and interact with them as if they were local commands. La comunicazione remota implicita è descritta in questo Hey, Scripting Guy!Implicit remoting is explained in this Hey, Scripting Guy! post di blog indirizzato agli autori di script.blog post. La comunicazione remota implicita è utile quando si usa JEA perché consente di usare i cmdlet JEA in una modalità di linguaggio completa.Implicit remoting is useful when working with JEA because it allows you to work with JEA cmdlets in a full language mode. È possibile usare il completamento tramite TAB, le variabili, modificare oggetti e usare anche script locali per automatizzare le operazioni in un endpoint JEA.You can use tab completion, variables, manipulate objects, and even use local scripts to automate tasks against a JEA endpoint. Ogni volta che si chiama un comando proxy, i dati vengono inviati all'endpoint JEA nel computer remoto ed eseguiti nel computer.Anytime you invoke a proxy command, the data is sent to the JEA endpoint on the remote machine and executed there.

La comunicazione remota implicita importa i cmdlet da una sessione di PowerShell esistente.Implicit remoting works by importing cmdlets from an existing PowerShell session. Facoltativamente, è possibile anteporre ai sostantivi di ogni cmdlet del proxy una stringa a scelta.You can optionally choose to prefix the nouns of each proxy cmdlet with a string of your choosing. Il prefisso consente di distinguere i comandi per il sistema remoto.The prefix allows you to distinguish the commands that are for the remote system. Un modulo di script temporaneo che contiene tutti i comandi proxy verrà creato e importato per la durata della sessione PowerShell locale.A temporary script module containing all the proxy commands is created and imported for the duration of your local PowerShell session.

# Create a new PSSession to your JEA endpoint
$jeasession = New-PSSession -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance'

# Import the entire PSSession and prefix each imported cmdlet with "JEA"
Import-PSSession -Session $jeasession -Prefix 'JEA'

# Invoke "Get-Command" on the remote JEA endpoint using the proxy cmdlet
Get-JEACommand

Importante

Alcuni sistemi potrebbero non essere in grado di importare un'intera sessione JEA a causa di vincoli nei cmdlet JEA predefiniti.Some systems may not be able to import an entire JEA session due to constraints in the default JEA cmdlets. Per evitare questo problema, importare dalla sessione JEA solo i comandi necessari, specificando in modo esplicito i loro nomi nel parametro -CommandName.To get around this, only import the commands you need from the JEA session by explicitly providing their names to the -CommandName parameter. Un futuro aggiornamento risolverà il problema con l'importazione di intere sessioni JEA nei sistemi interessati.A future update will address the issue with importing entire JEA sessions on affected systems.

Se non si riesce a importare una sessione JEA a causa dei vincoli JEA nei parametri predefiniti, seguire questa procedura per filtrare i comandi predefiniti dal set importato.If you're unable to import a JEA session because of JEA constraints on the default parameters, follow the steps below to filter out the default commands from the imported set. Sebbene sia possibile continuare a usare alcuni comandi, ad esempio Select-Object, verrà usata solo la versione installata nel computer anziché la versione importata dalla sessione JEA remota.You can continue use commands like Select-Object, but you'll just use the local version installed on your computer instead of the one imported from the remote JEA session.

# Create a new PSSession to your JEA endpoint
$jeasession = New-PSSession -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance'

# Get a list of all the commands on the JEA endpoint
$commands = Invoke-Command -Session $jeasession -ScriptBlock { Get-Command }

# Filter out the default cmdlets
$jeaDefaultCmdlets = 'Clear-Host', 'Exit-PSSession', 'Get-Command', 'Get-FormatData', 'Get-Help', 'Measure-Object', 'Out-Default', 'Select-Object'
$filteredCommands = $commands.Name | Where-Object { $jeaDefaultCmdlets -notcontains $_ }

# Import only commands explicitly added in role capabilities and prefix each imported cmdlet with "JEA"
Import-PSSession -Session $jeasession -Prefix 'JEA' -CommandName $filteredCommands

È anche possibile salvare i cmdlet proxy da una comunicazione remota implicita tramite Export-PSSession.You can also persist the proxied cmdlets from implicit remoting using Export-PSSession. Per altre informazioni sulla comunicazione remota implicita, vedere la documentazione relativa a Import-PSSession e Import-Module.For more information about implicit remoting, see the documentation for Import-PSSession and Import-Module.

Uso di JEA a livello di codiceUsing JEA programmatically

JEA può anche essere usato in sistemi di automazione e applicazioni utente, ad esempio app di supporto tecnico interno e siti Web.JEA can also be used in automation systems and in user applications, such as in-house helpdesk apps and websites. L'approccio è uguale a quello per la creazione di app che comunicano con endpoint di PowerShell senza vincoli.The approach is the same as that for building apps that talk to unconstrained PowerShell endpoints. Assicurarsi che il programma sia progettato per funzionare con le limitazioni imposte da JEA.Ensure the program is designed to work with limitation imposed by JEA.

Per attività semplici e singole, è possibile usare Invoke-Command per eseguire comandi in una sessione JEA.For simple, one-off tasks, you can use Invoke-Command to run commands in a JEA session.

Invoke-Command -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance' -ScriptBlock { Get-Process; Get-Service }

Per verificare i comandi disponibili durante la connessione a una sessione JEA, eseguire Get-Command e scorrere i risultati per vedere i parametri consentiti.To check which commands are available for use when you connect to a JEA session, run Get-Command and iterate through the results to check for the allowed parameters.

$allowedCommands = Invoke-Command -ComputerName 'SERVER01' -ConfigurationName 'JEAMaintenance' -ScriptBlock { Get-Command }
$allowedCommands | Where-Object { $_.CommandType -in 'Function', 'Cmdlet' } | Format-Table Name, Parameters

Se si compila un'app C#, è possibile creare uno spazio di esecuzione di PowerShell che si connette a una sessione JEA specificando il nome della configurazione in un oggetto WSManConnectionInfo.If you're building a C# app, you can create a PowerShell runspace that connects to a JEA session by specifying the configuration name in a WSManConnectionInfo object.

// using System.Management.Automation;
var computerName = "SERVER01";
var configName   = "JEAMaintenance";
// See https://docs.microsoft.com/dotnet/api/system.management.automation.pscredential
var creds        = // create a PSCredential object here

WSManConnectionInfo connectionInfo = new WSManConnectionInfo(
    false,                 // Use SSL
    computerName,          // Computer name
    5985,                  // WSMan Port
    "/wsman",              // WSMan Path
                           // Connection URI with config name
    string.Format(CultureInfo.InvariantCulture, "http://schemas.microsoft.com/powershell/{0}", configName),
    creds);                // Credentials

// Now, use the connection info to create a runspace where you can run the commands
using (Runspace runspace = RunspaceFactory.CreateRunspace(connectionInfo))
{
    // Open the runspace
    runspace.Open();

    using (PowerShell ps = PowerShell.Create())
    {
        // Set the PowerShell object to use the JEA runspace
        ps.Runspace = runspace;

        // Now you can add and invoke commands
        ps.AddCommand("Get-Command");
        foreach (var result in ps.Invoke())
        {
            Console.WriteLine(result);
        }
    }

    // Close the runspace
    runspace.Close();
}

Uso di JEA con PowerShell DirectUsing JEA with PowerShell Direct

Hyper-V in Windows 10 e in Windows Server 2016 offre PowerShell Direct, una funzionalità che consente agli amministratori di Hyper-V di gestire le macchine virtuali con PowerShell, indipendentemente dalla configurazione di rete o dalle impostazioni di gestione remota della macchina virtuale.Hyper-V in Windows 10 and Windows Server 2016 offers PowerShell Direct, a feature that allows Hyper-V administrators to manage virtual machines with PowerShell regardless of the network configuration or remote management settings on the virtual machine.

È possibile usare PowerShell Direct con JEA per concedere a un amministratore di Hyper-V accesso limitato alla macchina virtuale.You can use PowerShell Direct with JEA to give a Hyper-V administrator limited access to your VM. Ciò può essere utile se si perde la connettività di rete alla macchina virtuale ed è necessario un amministratore del datacenter per correggere le impostazioni di rete.This can be useful if you lose network connectivity to your VM and need a datacenter admin to fix the network settings.

Per usare JEA in PowerShell Direct non è richiesta alcuna configurazione aggiuntiva.No additional configuration is required to use JEA over PowerShell Direct. Tuttavia, il sistema operativo guest in esecuzione nella macchina virtuale deve essere Windows 10, Windows Server 2016 o versioni successive.However, the guest operating system running inside the virtual machine must be Windows 10, Windows Server 2016, or higher. L'amministratore di Hyper-V può connettersi all'endpoint JEA usando i parametri -VMName o -VMId nei cmdlet di PSRemoting:The Hyper-V admin can connect to the JEA endpoint by using the -VMName or -VMId parameters on PSRemoting cmdlets:

# Entering a JEA session using PowerShell Direct when the VM name is unique
Enter-PSSession -VMName 'SQL01' -ConfigurationName 'NICMaintenance' -Credential 'localhost\JEAformyHoster'

# Entering a JEA session using PowerShell Direct using VM ids
$vm = Get-VM -VMName 'MyVM' | Select-Object -First 1
Enter-PSSession -VMId $vm.VMId -ConfigurationName 'NICMaintenance' -Credential 'localhost\JEAformyHoster'

Si consiglia di creare un account utente dedicato con i diritti minimi necessari per gestire il sistema per l'uso da parte di un amministratore di Hyper-V.It's recommended you create a dedicated user account with the minimum rights needed to manage the system for use by a Hyper-V administrator. Tenere presente che anche un utente senza privilegi può accedere per impostazione predefinita a un computer Windows e usare PowerShell senza vincoli.Remember, even an unprivileged user can sign into a Windows machine by default, including using unconstrained PowerShell. Ciò consente all'utente di visualizzare il file system e altre informazioni sull'ambiente del sistema operativo.That allows them to browse the file system and learn more about your OS environment. Per limitare l'accesso di un amministratore di Hyper-V a una macchina virtuale tramite PowerShell Direct con JEA, è necessario negare i diritti di accesso locale all'account JEA dell'amministratore di Hyper-V.To lock down a Hyper-V administrator and limit them to only access a VM using PowerShell Direct with JEA, you must deny local logon rights to the Hyper-V admin's JEA account.