Set-PSSessionConfiguration

  • Riferimento
Modulo:
Microsoft.PowerShell.Core

Cambia le proprietà di una configurazione di sessione registrata.

Sintassi

Set-PSSessionConfiguration
   [-Name] <String>
   [-ApplicationBase <String>]
   [-RunAsCredential <PSCredential>]
   [-ThreadApartmentState <ApartmentState>]
   [-ThreadOptions <PSThreadOptions>]
   [-AccessMode <PSSessionConfigurationAccessMode>]
   [-UseSharedProcess]
   [-StartupScript <String>]
   [-MaximumReceivedDataSizePerCommandMB <Double>]
   [-MaximumReceivedObjectSizeMB <Double>]
   [-SecurityDescriptorSddl <String>]
   [-ShowSecurityDescriptorUI]
   [-Force]
   [-NoServiceRestart]
   [-PSVersion <Version>]
   [-SessionTypeOption <PSSessionTypeOption>]
   [-TransportOption <PSTransportOption>]
   [-ModulesToImport <Object[]>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Set-PSSessionConfiguration
   [-Name] <String>
   [-AssemblyName] <String>
   [-ApplicationBase <String>]
   [-ConfigurationTypeName] <String>
   [-RunAsCredential <PSCredential>]
   [-ThreadApartmentState <ApartmentState>]
   [-ThreadOptions <PSThreadOptions>]
   [-AccessMode <PSSessionConfigurationAccessMode>]
   [-UseSharedProcess]
   [-StartupScript <String>]
   [-MaximumReceivedDataSizePerCommandMB <Double>]
   [-MaximumReceivedObjectSizeMB <Double>]
   [-SecurityDescriptorSddl <String>]
   [-ShowSecurityDescriptorUI]
   [-Force]
   [-NoServiceRestart]
   [-PSVersion <Version>]
   [-SessionTypeOption <PSSessionTypeOption>]
   [-TransportOption <PSTransportOption>]
   [-ModulesToImport <Object[]>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Set-PSSessionConfiguration
   [-Name] <String>
   [-RunAsCredential <PSCredential>]
   [-ThreadApartmentState <ApartmentState>]
   [-ThreadOptions <PSThreadOptions>]
   [-AccessMode <PSSessionConfigurationAccessMode>]
   [-UseSharedProcess]
   [-StartupScript <String>]
   [-MaximumReceivedDataSizePerCommandMB <Double>]
   [-MaximumReceivedObjectSizeMB <Double>]
   [-SecurityDescriptorSddl <String>]
   [-ShowSecurityDescriptorUI]
   [-Force]
   [-NoServiceRestart]
   [-TransportOption <PSTransportOption>]
   -Path <String>
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Descrizione

Questo cmdlet è disponibile solo nella piattaforma Windows.

Il Set-PSSessionConfiguration cmdlet modifica le proprietà delle configurazioni di sessione nel computer locale.

Usare il parametro Name per identificare la configurazione della sessione da modificare. Usare gli altri parametri per specificare nuovi valori per le proprietà della configurazione di sessione. Per eliminare un valore della proprietà dalla configurazione e usare il valore predefinito, immettere una stringa vuota ("") o un valore per $Null il parametro corrispondente.

A partire da PowerShell 3.0, è possibile usare un file di configurazione della sessione per definire una configurazione di sessione. Questa funzionalità fornisce un metodo semplice e individuabile per impostare e modificare le proprietà di sessioni che usano la configurazione di sessione. Per specificare un file di configurazione della sessione, usare il parametro Path di Set-PSSessionConfiguration. Per informazioni sui file di configurazione della sessione, vedere about_Session_Configuration_Files. Per informazioni su come creare e modificare un file di configurazione della sessione, vedere il New-PSSessionConfigurationFile cmdlet .

Le configurazioni di sessione definiscono l'ambiente delle sessioni remote (PSSession) che si connettono al computer locale. Ogni SESSIONE PSSession usa una configurazione di sessione. La configurazione della sessione determina le funzionalità della sessione PSSession, ad esempio i moduli disponibili nella sessione, i cmdlet che possono essere eseguiti, la modalità lingua, le quote e i timeout. Il descrittore di sicurezza della configurazione della sessione determina chi può usare la configurazione di sessione per connettersi al computer locale. Per altre informazioni sulle configurazioni di sessione, vedere about_Session_Configurations.

Per visualizzare le proprietà di una configurazione di sessione, usare il Get-PSSessionConfiguration cmdlet o il provider WSMan. Per altre informazioni sul provider WSMan, digitare Get-Help WSMan.

Esempio

Esempio 1: Creare e modificare una configurazione di sessione

Questo esempio illustra come aggiungere e rimuovere uno script di avvio da una configurazione.

Il primo comando crea la configurazione di Amministrazione Shell. Il secondo comando aggiunge lo AdminConfig.ps1 script alla configurazione. La modifica è effettiva quando si riavvia WinRM. Il terzo comando rimuove lo AdminConfig.ps1 script dalla configurazione.

Register-PSSessionConfiguration -Name "AdminShell" -AssemblyName "C:\Shells\AdminShell.dll" -ConfigurationTypeName "AdminClass"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript "AdminConfig.ps1"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript $Null

Esempio 2: Visualizzare i risultati

Questo esempio aumenta il valore della proprietà MaximumReceivedObjectSizeMB a 20. Questo comando richiede anche di riavviare il servizio WinRM . La modifica non è effettiva fino al riavvio del servizio WinRM .

Set-PSSessionConfiguration -Name "IncObj" -MaximumReceivedObjectSizeMB 20

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\IncObj\InitializationParameters

ParamName                       ParamValue
---------                       ----------
psmaximumreceivedobjectsizemb   20

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run the command "restart-service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

Esempio 3: Visualizzare i risultati in modi diversi

In questo esempio, Set-PSSessionConfiguration modifica lo script di avvio nella configurazione della sessione maintenanceShell in Maintenance.ps1. L'output mostra la modifica e chiede di riavviare il servizio WinRM . La risposta è y (sì).

Get-PSSessionConfiguration ottiene la configurazione della sessione di MaintenanceShell . L'operatore pipeline (|) invia i risultati del comando a Format-List, che visualizza tutte le proprietà dell'oggetto di configurazione in un elenco. Usando quindi il provider WSMan, vengono visualizzati i parametri di inizializzazione per la configurazione di MaintenanceShell . Get-ChildItem ottiene gli elementi figlio nel nodo InitializationParameters per il plug-in MaintenanceShell . Per altre informazioni sul provider WSMan, digitare Get-Help wsman.

Set-PSSessionConfiguration -Name "MaintenanceShell" -StartupScript "C:\ps-test\Maintenance.ps1"

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell\InitializationParameters

ParamName            ParamValue
---------            ----------
startupscript        c:\ps-test\Mainte...

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run
the command "restart-service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

Get-PSSessionConfiguration MaintenanceShell | Format-List -Property *

xmlns            : http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration
Name             : MaintenanceShell
Filename         : %windir%\system32\pwrshplugin.dll
SDKVersion       : 1
XmlRenderingType : text
lang             : en-US
PSVersion        : 2.0
startupscript    : c:\ps-test\Maintenance.ps1
ResourceUri      : http://schemas.microsoft.com/powershell/MaintenanceShell
SupportsOptions  : true
ExactMatch       : true
Capability       : {Shell}
Permission       :

Get-ChildItem WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters

ParamName     ParamValue
---------     ----------
PSVersion     2.0
startupscript c:\ps-test\Maintenance.ps1

Parametri

-AccessMode

Abilita e disabilita la configurazione di sessione e determina se può essere usata per le sessioni locali o remote nel computer. I valori validi per questo parametro sono:

  • Disabled. disabilita la configurazione di sessione. Non può essere usata per l'accesso locale o remoto al computer. Questo valore imposta la proprietà Enabled della configurazione della sessione (WSMan:\<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled) su False.
  • Local. Aggiunge una voce Network_Deny_All al descrittore di sicurezza della configurazione della sessione. Gli utenti del computer locale possono usare la configurazione di sessione per creare una sessione di loopback locale nello stesso computer, ma agli utenti remoti viene negato l'accesso.
  • Remote. Rimuove Deny_All e Network_Deny_All voci dai descrittori di sicurezza della configurazione della sessione. Gli utenti dei computer locali e remoti possono usare la configurazione di sessione per creare sessioni ed eseguire comandi nel computer.

Il valore predefinito è Remote.

Altri cmdlet possono eseguire l'override del valore di questo parametro in un secondo momento. Ad esempio, il Enable-PSRemoting cmdlet abilita tutte le configurazioni di sessione nel computer e consente l'accesso remoto a tali configurazioni e il Disable-PSRemoting cmdlet consente solo l'accesso locale a tutte le configurazioni di sessione nel computer.

Questo parametro è stato introdotto in PowerShell 3.0.

Type:PSSessionConfigurationAccessMode
Accepted values:Disabled, Local, Remote
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ApplicationBase

Specifica il percorso del file di assembly (*.dll) specificato nel valore del parametro AssemblyName .

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

-AssemblyName

Specifica il nome dell'assembly. Questo cmdlet crea una configurazione di sessione basata su una classe definita in un assembly.

Immettere il nome file o il percorso completo di un file di assembly .dll che definisce una configurazione di sessione. Se si immette solo il nome del file, è possibile immettere il percorso nel valore del parametro ApplicationBase .

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ConfigurationTypeName

Specifica il tipo della configurazione di sessione definita nell'assembly nel parametro AssemblyName . Il tipo specificato deve implementare la classe System.Management.Automation.Remoting.PSSessionConfiguration .

Questo parametro è obbligatorio quando si specifica un nome di assembly.

Type:String
Position:2
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Confirm

Richiede conferma prima di eseguire il cmdlet.

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

-Force

Elimina tutte le richieste dell'utente e riavvia il servizio WinRM senza richiedere conferma. Al riavvio del servizio viene applicata la modifica alla configurazione.

Per impedire un riavvio e eliminare il prompt di riavvio, usare il parametro NoServiceRestart .

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

-MaximumReceivedDataSizePerCommandMB

Specifica il limite per la quantità di dati che è possibile inviare al computer in un singolo comando remoto. Immettere le dimensioni dei dati in megabyte (MB). Il valore predefinito è 50.

Se viene definito un limite di dimensioni dei dati nel tipo di configurazione specificato nel parametro ConfigurationTypeName , viene usato il limite nel tipo di configurazione. Il valore di questo parametro viene ignorato.

Type:Nullable<T>[Double]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumReceivedObjectSizeMB

Specifica i limiti relativi alla quantità di dati che possono essere inviati al computer in un singolo oggetto. Immettere le dimensioni dei dati in megabyte. Il valore predefinito è 10.

Se viene definito un limite di dimensioni dell'oggetto nel tipo di configurazione specificato nel parametro ConfigurationTypeName , viene usato il limite nel tipo di configurazione. Il valore di questo parametro viene ignorato.

Type:Nullable<T>[Double]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ModulesToImport

Specifica i moduli e gli snap-in che vengono importati automaticamente nelle sessioni che usano la configurazione di sessione. Immettere i nomi dei moduli e degli snap-in.

Per impostazione predefinita, solo il modulo Microsoft.PowerShell.Core viene importato nelle sessioni, ma a meno che i cmdlet non siano esclusi, è possibile usare i Import-Module cmdlet e Add-PSSnapin per aggiungere moduli e snap-in alla sessione.

I moduli specificati in questo valore di parametro vengono importati oltre ai moduli specificati nel file di configurazione della sessione (New-PSSessionConfigurationFile). Le impostazioni nel file di configurazione della sessione, tuttavia, possono nascondere i comandi esportati dai moduli o impedire agli utenti di usarli.

I moduli specificati in questo valore di parametro sostituiscono l'elenco dei moduli specificati con il parametro ModulesToImport del Register-PSSessionConfiguration cmdlet.

Questo parametro è stato introdotto in PowerShell 3.0.

Type:Object[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

Specifica il nome della configurazione di sessione da modificare.

Non è possibile usare questo parametro per modificare il nome della configurazione di sessione.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-NoServiceRestart

Non riavvia il servizio WinRM e elimina la richiesta di riavvio del servizio.

Per impostazione predefinita, quando si esegue Set-PSSessionConfigurationviene richiesto di riavviare il servizio WinRM per rendere effettiva la nuova configurazione di sessione. Fino al riavvio del servizio WinRM , la nuova configurazione di sessione non è valida.

Per riavviare il servizio WinRM senza chiedere conferma, usare il parametro Force . Per riavviare manualmente il servizio WinRM , usare il Restart-Service cmdlet .

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

-Path

Specifica il percorso di un file di configurazione della sessione (.pssc), ad esempio quello creato dal New-PSSessionConfigurationFile cmdlet . Se si omette il percorso, l'impostazione predefinita è la directory corrente.

Per informazioni su come modificare un file di configurazione della sessione, vedere l'argomento della Guida per il New-PSSessionConfigurationFile cmdlet .

Questo parametro è stato introdotto in PowerShell 3.0.

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

-PSVersion

Specifica la versione di PowerShell nelle sessioni che usano questa configurazione di sessione.

Il valore di questo parametro ha la precedenza sul valore della chiave PowerShellVersion nel file di configurazione della sessione.

Questo parametro è stato introdotto in PowerShell 3.0.

Type:Version
Aliases:PowerShellVersion
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RunAsCredential

Specifica le credenziali per i comandi nella sessione. Per impostazione predefinita, i comandi vengono eseguiti con le autorizzazioni dell'utente corrente.

Questo parametro è stato introdotto in PowerShell 3.0.

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

-SecurityDescriptorSddl

Specifica una stringa Security Descriptor Definition Language (SDDL) diversa per la configurazione.

Questa stringa determina le autorizzazioni necessarie per usare la nuova configurazione di sessione. Per usare una configurazione di sessione in una sessione, gli utenti devono disporre almeno Execute(Invoke) dell'autorizzazione per la configurazione.

Per usare il descrittore di sicurezza predefinito per la configurazione, immettere una stringa vuota ("") o un valore .$Null Il valore predefinito è il file SDDL radice nell'unità WSMan: .

Se il descrittore di sicurezza è complesso, è consigliabile usare il parametro ShowSecurityDescriptorUI anziché questo. Non è possibile usare entrambi i parametri nello stesso comando.

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

-SessionTypeOption

Specifica le opzioni specifiche del tipo per la configurazione della sessione. Immettere un oggetto opzioni del tipo di sessione, ad esempio l'oggetto PSWorkflowExecutionOption restituito dal New-PSWorkflowExecutionOption cmdlet.

Le opzioni delle sessioni che usano la configurazione di sessione sono determinate dai valori delle opzioni della sessione e dalle opzioni della configurazione di sessione. Se non specificato, le opzioni impostate nella sessione, ad esempio con il New-PSSessionOption cmdlet , hanno la precedenza sulle opzioni impostate nella configurazione della sessione. Tuttavia, i valori di opzione della sessione non possono superare i valori massimi impostati nella configurazione di sessione.

Questo parametro è stato introdotto in PowerShell 3.0.

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

-ShowSecurityDescriptorUI

Quando si usa questo parametro, il cmdlet apre una finestra delle proprietà che consente di creare un nuovo SDDL per la configurazione della sessione. La finestra delle proprietà viene visualizzata dopo l'esecuzione del Set-PSSessionConfiguration comando e quindi il riavvio del servizio WinRM .

Quando si impostano le autorizzazioni per la configurazione, tenere presente che gli utenti devono avere almeno Execute(Invoke) l'autorizzazione per usare la configurazione della sessione in una sessione.

Non è possibile usare il parametro SecurityDescriptorSDDL e questo parametro nello stesso comando.

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

-StartupScript

Specifica lo script di avvio per la configurazione. Immettere il percorso completo di uno script di PowerShell. Lo script specificato viene eseguito nella nuova sessione che usa la configurazione di sessione.

Per eliminare uno script di avvio da una configurazione di sessione, immettere una stringa vuota ("") o un valore di $Null.

È possibile usare uno script di avvio per configurare ulteriormente la sessione utente. Se lo script genera un errore, anche un errore non irreversibile, la sessione non viene creata e il New-PSSession comando non riesce.

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

-ThreadApartmentState

Specifica lo stato apartment del modulo di threading da usare. I valori accettabili sono:

  • Unknown
  • MTA
  • STA
Type:ApartmentState
Accepted values:STA, MTA, Unknown
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ThreadOptions

Specifica l'impostazione delle opzioni del thread nella configurazione. Questa impostazione definisce il modo in cui i thread vengono creati e usati quando viene eseguito un comando nella sessione. I valori validi per questo parametro sono:

  • Default
  • ReuseThread
  • UseCurrentThread
  • UseNewThread

Il valore predefinito è UseCurrentThread.

Per altre informazioni, vedere Enumerazione PSThreadOptions.

Type:PSThreadOptions
Accepted values:Default, UseNewThread, ReuseThread, UseCurrentThread
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TransportOption

Specifica le opzioni di trasporto per la configurazione della sessione. Immettere un oggetto opzioni di trasporto, ad esempio l'oggetto WSManConfigurationOption restituito dal New-PSTransportOption cmdlet.

Le opzioni delle sessioni che usano la configurazione di sessione sono determinate dai valori delle opzioni della sessione e dalle opzioni della configurazione di sessione. Se non specificato, le opzioni impostate nella sessione, ad esempio con il New-PSSessionOption cmdlet , hanno la precedenza sulle opzioni impostate nella configurazione della sessione. Tuttavia, i valori di opzione della sessione non possono superare i valori massimi impostati nella configurazione di sessione.

Questo parametro è stato introdotto in PowerShell 3.0.

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

-UseSharedProcess

Usare un solo processo per ospitare tutte le sessioni avviate dallo stesso utente e che usano la stessa configurazione di sessione. Per impostazione predefinita, ogni sessione è ospitata in un processo.

Questo parametro è stato introdotto in PowerShell 3.0.

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

-WhatIf

Mostra gli effetti dell'esecuzione del cmdlet. Il cmdlet non viene eseguito.

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

Input

None

Non è possibile inviare tramite pipe oggetti a questo cmdlet.

Output

WSManConfigLeafElement

Note

Questo cmdlet è disponibile solo nelle piattaforme Windows.

Per eseguire questo cmdlet, avviare PowerShell usando l'opzione Esegui come amministratore .

Il Set-PSSessionConfiguration cmdlet non modifica il nome della configurazione e il provider WSMan non supporta il Rename-Item cmdlet. Per modificare il nome di una configurazione di sessione, usare il Unregister-PSSessionConfiguration cmdlet per eliminare la configurazione e quindi usare il Register-PSSessionConfiguration cmdlet per creare e registrare una nuova configurazione di sessione.

È possibile usare il Set-PSSessionConfiguration cmdlet per modificare le configurazioni predefinite Microsoft.PowerShell e Microsoft.PowerShell32 di sessione. Non sono protette. Per ripristinare la versione originale di una configurazione di sessione predefinita, usare il Unregister-PSSessionConfiguration cmdlet per eliminare la configurazione di sessione predefinita e quindi usare il Enable-PSRemoting cmdlet per ripristinarlo.

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.

È possibile usare i comandi nell'unità WSMan: per modificare le proprietà delle configurazioni di sessione. Tuttavia, non è possibile usare l'unità WSMan: in PowerShell 2.0 per modificare le proprietà di configurazione della sessione introdotte in PowerShell 3.0, ad esempio OutputBufferingMode. I comandi di Windows PowerShell 2.0 non generano un errore, ma sono inefficaci. Per modificare le proprietà introdotte in PowerShell 3.0, usare l'unità WSMan: in PowerShell 3.0 o versione successiva.