Register-PSSessionConfiguration

Crea e registra una nuova configurazione di sessione.

Sintassi

Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-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>]
Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-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>]
Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-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 Register-PSSessionConfiguration cmdlet crea e registra una nuova configurazione di sessione nel computer locale. Si tratta di un cmdlet avanzato che è possibile usare per creare sessioni personalizzate per gli utenti remoti.

Ogni sessione di PowerShell (PSSession) usa una configurazione di sessione, nota anche come endpoint. Quando gli utenti creano una sessione che si connette al computer, possono selezionare una configurazione di sessione o usare la configurazione di sessione predefinita registrata quando si abilita la comunicazione remota di PowerShell. Gli utenti possono anche impostare la variabile di preferenza $PSSessionConfigurationName, che specifica una configurazione predefinita per le sessioni remote create nella sessione corrente.

La configurazione di sessione definisce l'ambiente per la sessione remota. La configurazione può determinare quali comandi ed elementi del linguaggio sono disponibili nella sessione e può includere le impostazioni che proteggono il computer, ad esempio quelle che limitano la quantità di dati che la sessione può ricevere in remoto in un singolo oggetto o comando. Il descrittore di sicurezza della configurazione della sessione determina quali utenti dispongono dell'autorizzazione per usare la configurazione della sessione.

È possibile definire gli elementi di configurazione usando un assembly che implementa una nuova classe di configurazione e uno script che viene eseguito nella sessione. A partire da PowerShell 3.0, è anche possibile usare un file di configurazione della sessione per definire la configurazione della sessione.

Per informazioni sulle configurazioni di sessione, vedere about_Session_Configurations. Per informazioni sui file di configurazione della sessione, vedere about_Session_Configuration_Files.

Esempio

Esempio 1: Registrare una nuova configurazione di sessione diShell

In questo esempio viene registrata la configurazione della sessione di NewShell . I parametri AssemblyName e ApplicationBase specificano il percorso del file MyShell.dll , che specifica i cmdlet e i provider nella configurazione della sessione. Il parametro ConfigurationTypeName specifica la classe di configurazione da usare dall'assembly.

$sessionConfiguration = @{
    Name='NewShell'
    ApplicationBase='c:\MyShells\'
    AssemblyName='MyShell.dll'
    ConfigurationTypeName='MyClass'
}
Register-PSSessionConfiguration @sessionConfiguration

Per usare questa configurazione, digitare New-PSSession -ConfigurationName newshell.

Esempio 2: Registrare una configurazione di sessione di MaintenanceShell

In questo esempio viene registrata la configurazione della sessione MaintenanceShell nel computer locale. Il parametro StartupScript specifica lo Maintenance.ps1 script.

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

Quando un utente usa un New-PSSession comando e seleziona la configurazione di MaintenanceShell , lo Maintenance.ps1 script viene eseguito nella nuova sessione. Lo script può configurare la sessione. Sono inclusi l'importazione di moduli e l'impostazione dei criteri di esecuzione per la sessione. Se lo script genera errori, inclusi errori non irreversibili, il New-PSSession comando ha esito negativo.

Esempio 3: Registrare una configurazione di sessione

In questo esempio viene registrata la configurazione della sessione di Amministrazione Shell.

La $sessionParams variabile è una tabella hash contenente tutti i valori dei parametri. Questa tabella hash viene passata al cmdlet usando lo splatting di PowerShell. Il Register-PSSessionConfiguration comando usa il parametro SecurityDescritorSDDL per specificare l'SDDL nel valore della $sddl variabile e il parametro MaximumReceivedObjectSizeMB per aumentare il limite di dimensioni dell'oggetto. Usa anche il parametro StartupScript per specificare uno script che configura la sessione.

$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FASA;GWGX;;;WD)"
$sessionParams = @{
    Name="AdminShell"
    SecurityDescriptorSDDL=$sddl
    MaximumReceivedObjectSizeMB=20
    StartupScript="C:\scripts\AdminShell.ps1"
}
Register-PSSessionConfiguration @sessionParams

Esempio 4: Restituire un elemento contenitore di configurazione

Questo esempio illustra come registrare la configurazione di MaintenanceShell . Register-PSSessionConfiguration restituisce un oggetto WSManConfigContainerElement archiviato nella $s variabile . Format-List visualizza tutte le proprietà dell'oggetto restituito. La proprietà PSPath mostra che l'oggetto viene archiviato in una directory dell'unità WSMan: . Get-ChildItem (alias dir) visualizza gli elementi nel WSMan:\LocalHost\PlugIn percorso. Questi includono la nuova configurazione di MaintenanceShell e le due configurazioni predefinite fornite con PowerShell.

$s = Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1
$s | Format-List -Property *
dir WSMan:\LocalHost\Plugin

PSPath            : Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell
PSParentPath      : Microsoft.WSMan.Management\WSMan::localhost\Plugin
PSChildName       : MaintenanceShell
PSDrive           : WSMan
PSProvider        : Microsoft.WSMan.Management\WSMan
PSIsContainer     : True
Keys              : {Name=MaintenanceShell}
Name              : MaintenanceShell
TypeNameOfElement : Container

Name                      Type                 Keys
----                      ----                 ----
MaintenanceShell          Container            {Name=MaintenanceShell}
microsoft.powershell      Container            {Name=microsoft.powershell}
microsoft.powershell32    Container            {Name=microsoft.powershell32}

Esempio 5: Registrare una configurazione di sessione con uno script di avvio

In questo esempio viene creata e registrata la configurazione della sessione WithProfile . Il parametro StartupScript indica a PowerShell di eseguire lo script specificato per qualsiasi sessione che usa la configurazione della sessione.

Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1

Lo script contiene un singolo comando che usa dot source per eseguire il profilo CurrentUserAllHosts dell'utente nell'ambito corrente della sessione.

Per altre informazioni sui profili, vedere about_Profiles. Per altre informazioni sull'origine dei punti, vedere about_Scopes.

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.
  • Locale. Consente agli utenti del computer locale di usare la configurazione di sessione per creare una sessione di loopback locale nello stesso computer, ma nega l'accesso agli utenti remoti.
  • Remoto. consente agli utenti locali e remoti di 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 consente l'accesso remoto a tutte le configurazioni di sessione, il Enable-PSSessionConfiguration cmdlet abilita le configurazioni di sessione e il cmdlet impedisce l'accesso Disable-PSRemoting remoto a tutte le configurazioni di sessione.

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 . Usare questo parametro quando il valore del parametro AssemblyName non include un percorso. Il valore predefinito è la directory corrente.

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

-AssemblyName

Specifica il nome di un file di assembly (*.dll) in cui è definito il tipo di configurazione. È possibile specificare il percorso del .dll in questo parametro o nel valore del parametro ApplicationBase .

Questo parametro è obbligatorio quando si specifica il parametro ConfigurationTypeName .

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

-ConfigurationTypeName

Specifica il nome completo del tipo di Microsoft .NET Framework che viene usato per questa configurazione. Il tipo specificato deve implementare la classe System.Management.Automation.Remoting.PSSessionConfiguration .

Per specificare il file di assembly (*.dll) che implementa il tipo di configurazione, specificare i parametri AssemblyName e ApplicationBase .

La creazione di un tipo consente di controllare più aspetti della configurazione della sessione, ad esempio esporre o nascondere determinati parametri dei cmdlet o impostare limiti di dimensioni dei dati e dimensioni degli oggetti che gli utenti non possono ignorare.

Se si omette questo parametro, la classe DefaultRemotePowerShellConfiguration viene usata per la configurazione della sessione.

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 tutti i prompt degli utenti e riavvia il servizio WinRM senza chiedere conferma. Al riavvio del servizio viene applicata la modifica alla configurazione.

Per evitare un riavvio e eliminare il prompt di riavvio, specificare il parametro NoServiceRestart .

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

-MaximumReceivedDataSizePerCommandMB

Specifica un limite per la quantità di dati che è possibile inviare al computer in un singolo comando remoto. Immettere le dimensioni dei dati in megabyte (MB). L'impostazione predefinita è 50 MB.

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 e 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 un limite per la quantità di dati che è possibile inviare al computer in un singolo oggetto. Immettere le dimensioni dei dati in megabyte. Il valore predefinito è 10 MB.

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

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

-ModulesToImport

Specifica i moduli importati automaticamente in sessioni che usano la configurazione di sessione.

Per impostazione predefinita, solo Microsoft.PowerShell.Core viene importato nelle sessioni. A meno che i cmdlet non siano esclusi, è possibile usare Import-Module per aggiungere moduli alla sessione.

I moduli specificati in questo valore di parametro vengono importati oltre ai moduli specificati dal parametro SessionType e quelli elencati nella chiave ModulesToImport 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.

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 un nome per la configurazione di sessione. Questo parametro è obbligatorio.

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 un Register-PSSessionConfiguration comando, viene 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 richiedere conferma, specificare 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 e il nome file di un file di configurazione sessione (con estensione pssc), ad esempio uno creato da New-PSSessionConfigurationFile. Se si omette il percorso, l'impostazione predefinita è la directory corrente.

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

-ProcessorArchitecture

Determina se viene avviata una versione a 32 bit o a 64 bit del processo di PowerShell nelle sessioni che usano questa configurazione di sessione. I valori accettabili per questo parametro sono: x86 (32 bit) e AMD64 (64 bit). Il valore predefinito è determinato dall'architettura del processore del computer che ospita la configurazione di sessione.

È possibile usare questo parametro per creare una sessione a 32 bit in un computer a 64 bit. I tentativi di creare un processo a 64 bit in un computer a 32 bit non riescono.

Type:String
Aliases:PA
Accepted values:x86, amd64
Position:Named
Default value:None
Required:False
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) 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 dell'autorizzazione Execute (Invoke) per la configurazione.

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

Se si omette questo parametro, per questa configurazione viene usato il file SDDL radice per il servizio WinRM . Per visualizzare o modificare l'SDDL radice, usare il provider WSMan. Ad esempio, Get-Item wsman:\localhost\service\rootSDDL. Per altre informazioni sul provider WSMan, digitare Get-Help wsman.

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 usando 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

Indica che questo cmdlet visualizza una finestra delle proprietà che consente di creare lo SDDL per la configurazione della sessione. La finestra delle proprietà viene visualizzata dopo aver immesso il Register-PSSessionConfiguration comando e quindi riavviare il servizio WinRM .

Quando si impostano le autorizzazioni per la configurazione, tenere presente che gli utenti devono avere almeno l'autorizzazione Execute (Invoke) per usare la configurazione di 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 il percorso completo di uno script di PowerShell. Lo script specificato viene eseguito nella nuova sessione che usa la configurazione di sessione.

È possibile usare lo script per configurare anche la sessione. 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:

  • Sconosciuto
  • MTA
  • STA
Type:ApartmentState
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ThreadOptions

Specifica la modalità di creazione e utilizzo dei thread durante l'esecuzione di un comando nella sessione. I valori validi per questo parametro sono:

  • Default
  • RiutilizzoThread
  • 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 l'opzione di trasporto.

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

WSManConfigContainerElement

Note

Questo cmdlet è disponibile solo nelle piattaforme Windows.

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

Questo cmdlet genera codice XML che rappresenta una configurazione plug-in di Servizi Web per la gestione (WS-Management) e invia il codice XML a WS-Management, che registra il plug-in nel computer locale (New-Item wsman:\localhost\plugin).

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.