Condividi tramite

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 della sessione nel computer locale.

Usare il parametro Name per identificare la configurazione di sessione da modificare. Usare gli altri parametri per specificare nuovi valori per le proprietà della configurazione di sessione. Per eliminare un valore di 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 della 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 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 (PSSessions) che si connettono al computer locale. Ogni PSSession usa una configurazione sessione. La configurazione della sessione determina le funzionalità della sessione PSSession, ad esempio i moduli disponibili nella sessione, i cmdlet autorizzati a eseguire, la modalità lingua, le quote e i timeout. Il descrittore di sicurezza della configurazione della sessione determina chi può usare la configurazione della 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 cmdlet o il Get-PSSessionConfiguration provider WSMan. Per altre informazioni sul provider WSMan, digitare Get-Help WSMan.

Esempio

Esempio 1: Create e modificare una configurazione di sessione

In questo esempio viene illustrato come aggiungere e rimuovere uno script di avvio da una configurazione.

Il primo comando crea la configurazione di AdminShell . 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 su 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 viene Set-PSSessionConfiguration modificato lo script di avvio nella configurazione della sessione di 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 della pipeline (|) invia i risultati del comando a Format-List, che visualizza tutte le proprietà dell'oggetto di configurazione in un elenco. Quindi, usando 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 di sessione. Gli utenti del computer locale possono usare la configurazione della sessione per creare una sessione di loopback locale nello stesso computer, ma gli utenti remoti vengono negati l'accesso.
  • Remote. rimuove le voci Deny_All e Network_Deny_All dai descrittori di protezione della configurazione di 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 essi 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 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 della 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 di configurazione di sessione definito 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 la conferma dell'utente 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 utente e riavvia il servizio WinRM senza richiedere. Al riavvio del servizio viene applicata la modifica alla configurazione.

Per evitare il riavvio e la richiesta 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 possono essere inviati a questo computer in qualsiasi singolo comando remoto. Immettere le dimensioni dei dati in megabyte (MB). Il valore predefinito è 50.

Se viene definito un limite di dimensioni dati nel tipo di configurazione specificato nel parametro ConfigurationTypeName , viene usato il limite nel tipo di configurazione. Valore del parametro ignorato.

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

-MaximumReceivedObjectSizeMB

Specifica i limiti sulla quantità di dati che possono essere inviati a questo computer in qualsiasi 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. Valore del parametro 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 in aggiunta 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 di 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 il prompt per riavviare il servizio.

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

Per riavviare il servizio WinRM senza richiedere, 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 sessione (.pssc), ad esempio uno 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 avere almeno Execute(Invoke) l'autorizzazione per la configurazione.

Per usare il descrittore di sicurezza predefinito per la configurazione, immettere una stringa vuota ("") o un valore di $Null. Il valore predefinito è l'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. A meno che non sia 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 questo parametro viene usato, il cmdlet apre un foglio di proprietà che consente di creare un nuovo SDDL per la configurazione della sessione. Il foglio delle proprietà viene visualizzato dopo aver eseguito il comando e quindi riavviare il Set-PSSessionConfiguration 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 terminante, 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 dell'appartamento del modulo di threading da usare. I valori accettabili sono:

  • Unknown
  • MTA
  • STA
Type:ApartmentState
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. A meno che non sia 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 solo un processo per ospitare tutte le sessioni avviate dallo stesso utente e usare la stessa configurazione della 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 l'esito in caso di 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 eseguire la pipe degli 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 di configurazione e il provider WSMan non supporta il Rename-Item cmdlet. Per modificare il nome di una configurazione di sessione, usare il cmdlet per eliminare la configurazione e quindi usare il Unregister-PSSessionConfigurationRegister-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 sessione predefinita, usare il Unregister-PSSessionConfiguration cmdlet per eliminare la configurazione 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.