New-PSSessionOption

Crea un oggetto che contiene le opzioni avanzate per una sessione PSSession.

Sintassi

New-PSSessionOption
   [-MaximumRedirection <Int32>]
   [-NoCompression]
   [-NoMachineProfile]
   [-Culture <CultureInfo>]
   [-UICulture <CultureInfo>]
   [-MaximumReceivedDataSizePerCommand <Int32>]
   [-MaximumReceivedObjectSize <Int32>]
   [-OutputBufferingMode <OutputBufferingMode>]
   [-MaxConnectionRetryCount <Int32>]
   [-ApplicationArguments <PSPrimitiveDictionary>]
   [-OpenTimeout <Int32>]
   [-CancelTimeout <Int32>]
   [-IdleTimeout <Int32>]
   [-ProxyAccessType <ProxyAccessType>]
   [-ProxyAuthentication <AuthenticationMechanism>]
   [-ProxyCredential <PSCredential>]
   [-SkipCACheck]
   [-SkipCNCheck]
   [-SkipRevocationCheck]
   [-OperationTimeout <Int32>]
   [-NoEncryption]
   [-UseUTF16]
   [-IncludePortInSPN]
   [<CommonParameters>]

Descrizione

Il New-PSSessionOption cmdlet crea un oggetto che contiene opzioni avanzate per una sessione gestita dall'utente (PSSession). È possibile usare l'oggetto come valore del parametro SessionOption dei cmdlet che creano una sessione PSSession, ad esempio New-PSSession, Enter-PSSessione Invoke-Command.

Senza parametri, New-PSSessionOption genera un oggetto contenente i valori predefiniti per tutte le opzioni. Poiché ogni proprietà può essere modificata, è possibile usare l'oggetto risultante come modello e creare oggetti opzione standard per l'organizzazione.

È anche possibile salvare un oggetto SessionOption nella $PSSessionOption variabile di preferenza. I valori di questa variabile stabiliscono nuovi valori predefiniti per le opzioni della sessione. Sono efficaci quando non vengono impostate opzioni di sessione per la sessione e hanno la precedenza sulle opzioni impostate nella configurazione della sessione, ma è possibile eseguirne l'override specificando le opzioni di sessione o un oggetto SessionOption in un cmdlet che crea una sessione. Per altre informazioni sulla variabile di $PSSessionOption preferenza, vedere about_Preference_Variables.

Quando si usa un oggetto SessionOption in un cmdlet che crea una sessione, i valori delle opzioni di sessione hanno la precedenza sui valori predefiniti per le sessioni impostate nella $PSSessionOption variabile preferenza e nella configurazione della sessione. Non hanno tuttavia la precedenza sui valori, sulle quote o sui limiti massimi impostati nella configurazione di sessione. Per altre informazioni sulle configurazioni di sessione, vedere about_Session_Configurations.

Esempio

Esempio 1: Creare un'opzione di sessione predefinita

Questo comando crea un oggetto SessionOption con i valori predefiniti.

New-PSSessionOption

MaximumConnectionRedirectionCount : 5
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         :
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:03:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

Esempio 2: Configurare una sessione usando un oggetto opzione di sessione

In questo esempio viene illustrato come utilizzare un oggetto SessionOption per configurare una sessione.

$pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB
New-PSSession -ComputerName Server01 -SessionOption $pso

Il primo comando crea un nuovo oggetto SessionOption e lo salva nel valore della $pso variabile. Il secondo comando usa il New-PSSession cmdlet per creare una sessione nel computer remoto Server01. Il comando usa l'oggetto SessionOption nel valore della $pso variabile come valore del parametro SessionOption del comando.

Esempio 3: Avviare una sessione interattiva

Questo comando usa il Enter-PSSession cmdlet per avviare una sessione interattiva con il computer Server01.

Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression)

Il valore del parametro SessionOption è un New-PSSessionOption comando con i parametri NoEncryption e NoCompression .

Il New-PSSessionOption comando è racchiuso tra parentesi per assicurarsi che venga eseguito prima del Enter-PSSession comando.

Esempio 4: Modificare un oggetto opzione di sessione

In questo esempio viene illustrato che è possibile modificare l'oggetto SessionOption . Tutte le proprietà hanno valori di lettura/scrittura.

$a = New-PSSessionOption
$a.OpenTimeout

Days              : 0
Hours             : 0
Minutes           : 3
Seconds           : 0
Milliseconds      : 0
Ticks             : 1800000000
TotalDays         : 0.00208333333333333
TotalHours        : 0.05
TotalMinutes      : 3
TotalSeconds      : 180
TotalMilliseconds : 180000

$a.UICulture = (Get-UICulture)
$a.OpenTimeout = (New-Timespan -Minutes 4)
$a.MaximumConnectionRedirectionCount = 1
$a

MaximumConnectionRedirectionCount : 1
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         : en-US
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:04:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

Usare questo metodo per creare un oggetto sessione standard per l'organizzazione e quindi creare versioni personalizzate di tale oggetto per particolari utilizzi.

Esempio 5: Creare una variabile di preferenza

Questo comando crea una $PSSessionOption variabile di preferenza.

$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000

Quando la $PSSessionOption variabile di preferenza viene impostata nella sessione, stabilisce i valori predefiniti per le opzioni nelle sessioni create con i New-PSSessioncmdlet , Enter-PSSessione Invoke-Command .

Per rendere disponibile la $PSSessionOption variabile in tutte le sessioni, aggiungerla alla sessione di PowerShell e al profilo di PowerShell.

Per altre informazioni sulla variabile di $PSSessionOption preferenza, vedere about_Preference_Variables. Per altre informazioni sui profili, vedere about_Profiles.

Esempio 6: Soddisfare i requisiti per una configurazione sessione remota

In questo esempio viene illustrato come usare un oggetto SessionOption per soddisfare i requisiti per una configurazione di sessione remota.

$skipCN = New-PSSessionOption -SkipCNCheck
New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCN

Il primo comando usa il New-PSSessionOption cmdlet per creare un oggetto SessionOption con la proprietà SkipCNCheck . Il comando salva l'oggetto sessione risultante nella $skipCN variabile .

Il secondo comando usa il New-PSSession cmdlet per creare una nuova sessione in un computer remoto. La $skipCN variabile check viene usata nel valore del parametro SessionOption .

Poiché il computer è identificato dal relativo indirizzo IP, il valore del parametro ComputerName non corrisponde ad alcun nome comune nel certificato usato per Secure Sockets Layer (SSL). Di conseguenza, è necessaria l'opzione SkipCNCheck .

Esempio 7: Rendere disponibili argomenti per una sessione remota

In questo esempio viene illustrato come usare il parametro ApplicationArguments del New-PSSessionOption cmdlet per rendere disponibili dati aggiuntivi per la sessione remota.

$team = @{Team="IT"; Use="Testing"}
$TeamOption = New-PSSessionOption -ApplicationArguments $team
$s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption
Invoke-Command -Session $s {$PSSenderInfo.ApplicationArguments}

Name                 Value
----                 -----
Team                 IT
Use                  Testing
PSVersionTable       {CLRVersion, BuildVersion, PSVersion, WSManStackVersion...}

Invoke-Command -Session $s {
  if ($PSSenderInfo.ApplicationArguments.Use -ne "Testing") {
    .\logFiles.ps1
  }
  else {
    "Just testing."
  }
}

Just testing.

Il primo comando crea una tabella hash con due chiavi, Team e Use. Il comando salva la tabella hash nella $team variabile . Per altre informazioni sulle tabelle hash, vedere about_Hash_Tables.

Successivamente, il New-PSSessionOption cmdlet , usando il parametro ApplicationArguments , crea un oggetto SessionOption salvato nella $team variabile . Quando New-PSSessionOption crea l'oggetto opzione di sessione, converte automaticamente la tabella hash nel valore del parametro ApplicationArguments in un PrimitiveDictionary in modo che i dati possano essere trasmessi in modo affidabile alla sessione remota.

Il New-PSSession cmdlet avvia una sessione nel computer Server01. Usa il parametro SessionOption per includere le opzioni nella $teamOption variabile.

Il Invoke-Command cmdlet dimostra che i dati nella $team variabile sono disponibili per i comandi nella sessione remota. I dati sono visualizzati nella proprietà ApplicationArguments della $PSSenderInfo variabile automatica.

L'ultima Invoke-Command mostra come usare i dati.

Parametri

-ApplicationArguments

Specifica un PrimitiveDictionary inviato alla sessione remota. I comandi e gli script nella sessione remota, inclusi gli script di avvio nella configurazione della sessione, possono trovare questo dizionario nella proprietà ApplicationArguments della $PSSenderInfo variabile automatica. È possibile usare questo parametro per inviare dati alla sessione remota.

Per altre informazioni, vedere about_Hash_Tables, about_Session_Configurations e about_Automatic_Variables.

Type:PSPrimitiveDictionary
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CancelTimeout

Determina per quanto tempo PowerShell attende il completamento di un'operazione di annullamento (CTRL+C) prima di terminarlo. Immettere un valore in millisecondi.

Il valore predefinito è 60000 (un minuto). Un valore pari 0 a (zero) non indica alcun timeout. Il comando continua per un periodo illimitato.

Type:Int32
Aliases:CancelTimeoutMSec
Position:Named
Default value:60000
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Culture

Specifica le impostazioni cultura da usare per la sessione. Immettere un nome delle impostazioni cultura in <languagecode2>-<country/regioncode2> formato (ad esempio ja-JP), una variabile che contiene un oggetto CultureInfo o un comando che ottiene un oggetto CultureInfo .

Il valore predefinito è $Nulle le impostazioni cultura impostate nel sistema operativo vengono usate nella sessione.

Type:CultureInfo
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IdleTimeout

Determina per quanto tempo la sessione rimane aperta se il computer remoto non riceve alcuna comunicazione dal computer locale. Ciò include il segnale heartbeat. Alla scadenza dell'intervallo, la sessione si chiude.

Il valore di timeout di inattività è di importanza significativa se si intende disconnettersi e riconnettersi a una sessione. È possibile riconnettersi solo se non si è verificato il timeout della sessione.

Immettere un valore in millisecondi. Il valore minimo è 60000 (1 minuto). Il valore massimo è il valore della proprietà MaxIdleTimeoutms della configurazione della sessione. Il valore predefinito, -1, non imposta un timeout di inattività.

La sessione usa il timeout di inattività impostato nelle opzioni di sessione, se presenti. Se non è impostato nessuno (-1), la sessione usa il valore della proprietà IdleTimeoutMs della configurazione della sessione o del valore di timeout della shell WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout), a qualsiasi valore è più breve.

Se il timeout di inattività impostato nelle opzioni di sessione supera il valore della proprietà MaxIdleTimeoutMs della configurazione della sessione, il comando per creare una sessione ha esito negativo.

Il valore IdleTimeoutMs della configurazione di sessione predefinita di Microsoft.PowerShell è 7200000 di millisecondi (2 ore). Il valore MaxIdleTimeoutMs è 2147483647 di millisecondi (>24 giorni). Il valore predefinito del timeout di inattività della shell WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout) è 7200000 di millisecondi (2 ore).

Il valore di timeout di inattività di una sessione può anche essere modificato durante la disconnessione da una sessione o la riconnessione a una sessione. Per altre informazioni, vedere Disconnect-PSSession e Connect-PSSession.

In Windows PowerShell 2.0 il valore predefinito del parametro IdleTimeout è 240000 (4 minuti).

Type:Int32
Aliases:IdleTimeoutMSec
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IncludePortInSPN

Include il numero di porta nel nome dell'entità servizio (SPN) usato per l'autenticazione Kerberos, HTTP://<ComputerName>:5985ad esempio . Questa opzione consente l'autenticazione di un client che usa un SPN non predefinito su un computer remoto che usa l'autenticazione Kerberos.

L'opzione è progettata per le aziende in cui vengono eseguiti più servizi che supportano l'autenticazione Kerberos con account utente diversi. Ad esempio, un'applicazione IIS che consente l'autenticazione Kerberos può richiedere la registrazione del nome SPN predefinito in un account utente diverso dall'account computer. In questi casi, la comunicazione remota di PowerShell non può usare Kerberos per l'autenticazione perché richiede un NOME SPN registrato nell'account computer. Per risolvere questo problema, gli amministratori possono creare nomi SPN diversi, ad esempio usando Setspn.exe, registrati in account utente diversi e possono distinguerli includendo il numero di porta nel nome SPN.

Per altre informazioni, vedere Panoramica di Setspn.

Questo parametro è stato introdotto in Windows PowerShell 3.0.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaxConnectionRetryCount

Specifica il numero di tentativi che PowerShell tenta di stabilire una connessione a un computer di destinazione se il tentativo corrente non riesce a causa di problemi di rete. Il valore predefinito è 5.

Questo parametro è stato aggiunto per PowerShell versione 5.0.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumReceivedDataSizePerCommand

Specifica il numero massimo di byte che il computer locale può ricevere dal computer remoto in un unico comando. Immettere un valore in byte. Per impostazione predefinita, non esiste alcun limite per le dimensioni dei dati.

Questa opzione ha lo scopo di proteggere le risorse del computer client.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumReceivedObjectSize

Specifica le dimensioni massime di un oggetto che il computer locale può ricevere dal computer remoto. Questa opzione ha lo scopo di proteggere le risorse del computer client. Immettere un valore in byte.

In Windows PowerShell 2.0 l'omissione di questo parametro indica che non esiste alcun limite per le dimensioni degli oggetti. A partire da Windows PowerShell 3.0, se si omette questo parametro, il valore predefinito è 209715200 byte (o 200MB).

Type:Int32
Position:Named
Default value:209715200
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumRedirection

Determina quante volte PowerShell reindirizza una connessione a un URI (Uniform Resource Identifier) alternativo prima che la connessione non riesca. Il valore predefinito è 5. Un valore pari 0 a (zero) impedisce tutto il reindirizzamento.

Questa opzione viene usata nella sessione solo quando il parametro AllowRedirection viene usato nel comando che crea la sessione.

Type:Int32
Position:Named
Default value:5
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-NoCompression

Disattiva la compressione dei pacchetti nella sessione. La compressione usa più cicli del processore, ma rende più veloce la trasmissione.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-NoEncryption

Disattiva la crittografia dei dati.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-NoMachineProfile

Impedisce il caricamento del profilo utente di Windows dell'utente. Di conseguenza, la sessione potrebbe essere creata più velocemente, ma le impostazioni del Registro di sistema specifiche dell'utente, elementi come le variabili di ambiente e i certificati non sono disponibili nella sessione.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OpenTimeout

Determina per quanto tempo il computer client attende che venga stabilita la connessione alla sessione. Se l'intervallo scade, il comando per stabilire la connessione non riesce. Immettere un valore in millisecondi.

Il valore predefinito è 180000 (3 minuti). Un valore pari 0 a (zero) non indica alcun timeout. Il comando continua per un periodo illimitato.

Type:Int32
Aliases:OpenTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OperationTimeout

Determina il tempo massimo di attesa di WinRM per i test di connessione positivi da una connessione dinamica prima di avviare un timeout della connessione. Per altre informazioni su WinRM, vedere la documentazione di Gestione remota Windows.

OperationTimeout non impone un limite di tempo per i comandi o i processi in esecuzione in una sessione remota e non influisce su altri protocolli remoti come SSH.

Il valore predefinito è 180000 (3 minuti). Un valore pari 0 a (zero) non indica alcun timeout.

Type:Int32
Aliases:OperationTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OutputBufferingMode

Determina la modalità di gestione dell'output del comando nelle sessioni disconnesse quando il buffer di output diventa pieno.

Se la modalità di buffering di output non è impostata nella sessione o nella configurazione della sessione, il valore predefinito è Block. Gli utenti possono inoltre modificare questa modalità durante la disconnessione della sessione.

Se si omette questo parametro, il valore dell'oggetto OutputBufferingMode dell'oggetto SessionOption è None. Un valore di Block o Drop esegue l'override dell'opzione di trasporto modalità buffering di output impostata nella configurazione della sessione. I valori validi per questo parametro sono:

  • Block. Quando il buffer di output è pieno, l'esecuzione viene sospesa fino a quando il buffer non viene svuotato.
  • Drop. Quando il buffer di output è pieno, l'esecuzione continua. Man mano che viene salvato il nuovo output, l'output meno recente viene eliminato.
  • None. Non viene specificata alcuna modalità di buffering dell'output.

Per altre informazioni sull'opzione di trasporto in modalità buffer di output, vedere New-PSTransportOption.

Questo parametro è stato introdotto in Windows PowerShell 3.0.

Type:OutputBufferingMode
Accepted values:None, Drop, Block
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyAccessType

Determina quale meccanismo viene usato per risolvere il nome host. I valori validi per questo parametro sono:

  • IEConfig
  • WinHttpConfig
  • AutoDetect
  • NoProxyServer
  • None

Il valore predefinito è None.

Per informazioni sui valori di questo parametro, vedere Enumerazione ProxyAccessType.

Type:ProxyAccessType
Accepted values:None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyAuthentication

Specifica il metodo di autenticazione usato per la risoluzione proxy. I valori validi per questo parametro sono:

  • Basic
  • Digest
  • Negotiate

Il valore predefinito è Negotiate.

Per altre informazioni sui valori di questo parametro, vedere AuthenticationMechanism Enumeration.

Type:AuthenticationMechanism
Accepted values:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:Negotiate
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyCredential

Specifica le credenziali da usare per l'autenticazione proxy. Immettere una variabile contenente un oggetto PSCredential o un comando che ottiene un oggetto PSCredential , ad esempio un Get-Credential comando. Se questa opzione non è impostata, non vengono specificate credenziali.

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SkipCACheck

Specifica che quando si connette tramite HTTPS, il client non convalida che il certificato del server sia firmato da un'autorità di certificazione attendibile .

Usare questa opzione solo quando il computer remoto viene considerato attendibile mediante un altro meccanismo, ad esempio quando il computer remoto fa parte di una rete fisicamente sicura e isolata oppure quando il computer remoto è elencato come host attendibile nella configurazione di Gestione remota Windows.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SkipCNCheck

Specifica che il nome comune del certificato (CN) del server non deve corrispondere al nome host del server. Questa opzione viene usata solo nelle operazioni remote che usano il protocollo HTTPS.

Usare questa opzione solo per i computer attendibili.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SkipRevocationCheck

Non convalida lo stato di revoca del certificato del server.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UICulture

Specifica le impostazioni cultura dell'interfaccia utente da usare per la sessione.

I valori validi includono:

  • Nome delle impostazioni cultura in <languagecode2>-<country/regioncode2> formato, ad esempio ja-JP
  • Variabile contenente un oggetto CultureInfo
  • Comando che ottiene un oggetto CultureInfo , ad esempio Get-Culture

Il valore predefinito è $nulle le impostazioni cultura dell'interfaccia utente impostate nel sistema operativo quando viene creata la sessione.

Type:CultureInfo
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UseUTF16

Indica che questo cmdlet codifica la richiesta in formato UTF16 anziché in formato UTF8.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Input

None

Non è possibile inviare tramite pipe oggetti a questo cmdlet.

Output

PSSessionOption

Note

Se il parametro SessionOption non viene usato in un comando per creare una sessione PSSession, le opzioni di sessione vengono determinate dai valori delle proprietà della $PSSessionOption variabile di preferenza, se impostata. Per altre informazioni sulla $PSSessionOption variabile, vedere about_Preference_Variables.

Le proprietà di un oggetto configurazione di sessione variano in base alle opzioni impostate per la configurazione di sessione e ai valori di queste opzioni. Le configurazioni di sessione che usano un file di configurazione della sessione hanno anche proprietà aggiuntive.