Crea e registra una nuova configurazione di sessione.

Sintassi

Register-PSSessionConfiguration [-AssemblyName] <string> [-ConfigurationTypeName] <string> [-ApplicationBase <string>] [-Name] <string> [-Force] [-MaximumReceivedDataSizePerCommandMB <double>] [-MaximumReceivedObjectSizeMB <double>] [-NoServiceRestart] [-ProcessorArchitecture <string>] [-SecurityDescriptorSDDL <string>] [-ShowSecurityDescriptorUI] [-StartupScript <string>] [-ThreadApartmentState {<STA> | <MTA> | <Unknown>}] [-ThreadOptions {<Default> | <UseNewThread> | <ReuseThread> | <UseCurrentThread>}] [-Confirm] [-WhatIf] [<CommonParameters>]

Descrizione

Il cmdlet Register-PSSessionConfiguration crea e registra una nuova configurazione di sessione nel computer locale. Si tratta di un cmdlet avanzato progettato per essere utilizzato da amministratori di sistema per gestire le configurazioni di sessione personalizzate degli utenti.

Ogni sessione remota di Windows PowerShell utilizza una configurazione di sessione. Quando gli utenti creano una sessione per la connessione al computer, possono selezionare una configurazione o utilizzare le configurazioni predefinite registrate quando si abilita la comunicazione remota di Windows PowerShell. Gli utenti possono inoltre impostare la variabile di preferenza $PSSessionConfigurationName che specifica una configurazione predefinita per le sessioni create nella sessione corrente.

La configurazione di sessione configura l'ambiente per la sessione. È possibile definire la configurazione con un assembly che implementa una nuova classe di configurazione e con uno script in esecuzione nella sessione. La configurazione determina i comandi disponibili nella sessione e può includere impostazioni per la protezione del computer, ad esempio quelle che limitano la quantità di dati che la sessione può ricevere in modalità remota in un solo oggetto o comando. È inoltre possibile specificare un descrittore di sicurezza che determina le autorizzazioni richieste per utilizzare la configurazione.

Parametri

-ApplicationBase <string>

Specifica il percorso del file di assembly (*.dll) specificato nel valore del parametro AssemblyName. Utilizzare questo parametro quando il valore del parametro AssemblyName non include un percorso. Il valore predefinito è la directory corrente.

Obbligatorio?

false

Posizione?

named

Valore predefinito

Current directory

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-AssemblyName <string>

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

Questo parametro è obbligatorio quando viene specificato il parametro ConfigurationTypeName.

Obbligatorio?

true

Posizione?

2

Valore predefinito

nessuno

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-ConfigurationTypeName <string>

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

Per specificare il file di assembly (con estensione dll) che implementa il tipo di configurazione, utilizzare i parametri AssemblyName e AssemblyBase.

La creazione di un tipo consente di controllare più aspetti della configurazione di sessione, ad esempio l'attivazione o la disattivazione dell'esposizione di certi parametri dei cmdlet o l'impostazione dei limiti delle dimensioni di dati e oggetti che gli utenti non possono ignorare.

Se si omette questo parametro, la classe DefaultRemotePowerShellConfiguration viene utilizzata per la configurazione di sessione.

Obbligatorio?

true

Posizione?

3

Valore predefinito

System.Management.Automation.Remoting.PSSessionConfiguration

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-Force

Elimina tutti i prompt degli utenti e riavvia il servizio Gestione remota Windows senza richieste. Con il riavvio del servizio la modifica della configurazione diventa effettiva.

Per impedire un riavvio ed eliminare il prompt di riavvio, utilizzare il parametro NoServiceRestart.

Obbligatorio?

false

Posizione?

named

Valore predefinito

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-MaximumReceivedDataSizePerCommandMB <double>

Limita la quantità di dati che è possibile inviare a questo computer in qualsiasi singolo comando remoto. Immettere le dimensioni dei dati in megabyte (MB). L'impostazione predefinita è 50 MB.

Se viene stabilito un limite per le dimensioni dei dati nel tipo di configurazione specificato nel parametro ConfigurationTypeName, viene utilizzato il limite nel tipo di configurazione e il valore di questo parametro viene ignorato.

Obbligatorio?

false

Posizione?

named

Valore predefinito

50

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-MaximumReceivedObjectSizeMB <double>

Limita la quantità di dati che è possibile inviare a questo computer in qualsiasi singolo oggetto. Immettere le dimensioni dei dati in megabyte (MB). L'impostazione predefinita è 10 MB.

Se viene stabilito un limite per le dimensioni di un 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.

Obbligatorio?

false

Posizione?

named

Valore predefinito

10

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-Name <string>

Specifica un nome per la configurazione di sessione. Questo parametro è obbligatorio.

Obbligatorio?

true

Posizione?

1

Valore predefinito

nessuno

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-NoServiceRestart

Non riavvia il servizio Gestione remota Windows ed elimina il prompt per riavviare il servizio.

Per impostazione predefinita, quando si immette un comando Register-PSSessionConfiguration, viene richiesto di riavviare il servizio Gestione remota Windows per rendere effettiva la nuova configurazione di sessione. Finché il servizio Gestione remota Windows non viene riavviato, la nuova configurazione di sessione non è effettiva.

Per riavviare il servizio Gestione remota Windows senza visualizzare alcun prompt, utilizzare il parametro Force. Per riavviare manualmente il servizio Gestione remota Windows, utilizzare il cmdlet Restart-Service.

Obbligatorio?

false

Posizione?

named

Valore predefinito

False

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-ProcessorArchitecture <string>

Specifica un'architettura del processore per la configurazione. Questo valore determina se viene avviata una versione a 32 o 64 bit del processo che ospita Windows PowerShell quando viene utilizzata la configurazione. I valori validi sono x86, AMD64 e IA64.

L'impostazione predefinita è determinata dall'architettura del processore del computer che ospita la configurazione di sessione.

Obbligatorio?

false

Posizione?

named

Valore predefinito

The processor architecture of the host computer.

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-SecurityDescriptorSDDL <string>

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

Questa stringa determina le autorizzazioni necessarie per utilizzare la nuova configurazione di sessione. Per utilizzare 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, si consideri l'utilizzo del parametro ShowSecurityDescriptorUI al posto di questo parametro. Non è possibile utilizzare entrambi i parametri nello stesso comando.

Se si omette questo parametro, la radice SDDL per il servizio Gestione remota Windows viene utilizzata per questa configurazione. Per visualizzare o modificare la radice SDDL, utilizzare il provider WS-Management. Ad esempio "Get-Item wsman:\localhost\service\rootSDDL". Per ulteriori informazioni sul provider WS-Management, digitare "Get-Help wsman".

Obbligatorio?

false

Posizione?

named

Valore predefinito

The value of the root SDDL

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-ShowSecurityDescriptorUI

Visualizza una finestra delle proprietà che consente di creare l'SDDL per la configurazione di sessione. La finestra delle proprietà viene visualizzata dopo l'immissione del comando Register-PSSessionConfiguration, dopodiché viene riavviato il servizio Gestione remota Windows.

Durante l'impostazione delle autorizzazioni per la configurazione, ricordare che gli utenti devono disporre almeno dell'autorizzazione "Execute(Invoke)" per utilizzare la configurazione di sessione in una sessione.

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

Obbligatorio?

false

Posizione?

named

Valore predefinito

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-StartupScript <string>

Specifica il percorso completo di uno script di Windows PowerShell. Lo script specificato viene eseguito nella nuova sessione che utilizza la configurazione di sessione.

È possibile utilizzare lo script per configurare ulteriormente la sessione. Se lo script genera un errore (anche un errore non fatale), la sessione non viene creata e il comando New-PSSession dell'utente ha esito negativo.

Obbligatorio?

false

Posizione?

named

Valore predefinito

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-ThreadApartmentState <ApartmentState>

Determina lo stato dell'apartment dei thread nella sessione. I valori validi sono STA, MTA e Unknown. Il valore predefinito è Unknown.

Obbligatorio?

false

Posizione?

named

Valore predefinito

Unknown

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-ThreadOptions <PSThreadOptions>

Definisce la modalità di creazione e utilizzo dei thread quando viene eseguito un comando nella sessione. I valori validi sono Default, ReuseThread, UseCurrentThread e UseNewThread. Il valore predefinito è UseCurrentThread.

Obbligatorio?

false

Posizione?

named

Valore predefinito

UseCurrentThread

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-Confirm

Chiede una conferma prima di eseguire il comando.

Obbligatorio?

false

Posizione?

named

Valore predefinito

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

-WhatIf

Descrive ciò che accadrebbe se si eseguisse il comando senza eseguirlo realmente.

Obbligatorio?

false

Posizione?

named

Valore predefinito

Accettare input da pipeline?

false

Accettare caratteri jolly?

false

<CommonParameters>

Questo cmdlet supporta i parametri comuni -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Per ulteriori informazioni, vedere about_Commonparameters.

Input e output

Il tipo di input è il tipo degli oggetti che è possibile reindirizzare al cmdlet. Il tipo restituito è il tipo degli oggetti restituiti dal cmdlet.

Input

Nessuno

Non è possibile reindirizzare l'input a questo cmdlet.

Output

Microsoft.WSMan.Management.WSManConfigContainerElement

Note

Per eseguire questo cmdlet in Windows Vista, Windows Server 2008 e nelle versioni successive di Windows, è necessario avviare Windows PowerShell con l'opzione "Esegui come amministratore".

Questo cmdlet genera un XML che rappresenta una configurazione del plug-in di WS-Management e invia l'XML a WS-Management che registra il plug-in nel computer locale ("new-item wsman:\localhost\plugin").

Esempio 1

C:\PS>register-pssessionConfiguration -name NewShell -applicationBase c:\MyShells\ -assemblyName MyShell.dll -configurationTypeName MyClass

Descrizione
-----------
Questo comando registra la configurazione di sessione NewShell. Utilizza i parametri ApplicationName e ApplicationBase per specificare il percorso del file MyShell.dll che specifica i cmdlet e i provider nella configurazione di sessione. Utilizza inoltre il parametro ConfigurationTypeName per specificare una nuova classe che configuri ulteriormente la sessione.

Per utilizzare questa configurazione, gli utenti dovrebbero digitare "new-pssession -configurationname newshell".






Esempio 2

C:\PS>register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1

Descrizione
-----------
Questo comando registra la configurazione MaintenanceShell nel computer locale. Viene utilizzato il parametro StartupScript per specificare lo script Maintenance.ps1.

Quando un utente utilizza un comando New-PSSession e seleziona la configurazione MaintenanceShell, viene eseguito lo script Maintenance.ps1 nella nuova sessione. Lo script può configurare la sessione, includendo l'importazione di moduli, l'aggiunta di snap-in di Windows PowerShell e l'impostazione dei criteri di esecuzione per la sessione. Se lo script genera errori, inclusi quelli non fatali, il comando New-PSSession ha esito negativo.






Esempio 3

C:\PS>$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)"

C:\PS> register-pssessionconfiguration -name AdminShell -securityDescriptorSDDL $sddl -maximumReceivedObjectSizeMB 20 -startupScript c:\scripts\AdminShell.ps1

Descrizione
-----------
In questo esempio viene effettuata la registrazione della configurazione di sessione AdminShell. 

Il primo comando consente di salvare un SDDL personalizzato nella variabile $sddl. 

Con il secondo comando si registra la nuova shell. Con il comando si utilizza il parametro SecurityDescritorSDDL per specificare l'SDDL nel valore della variabile $sddl e il parametro MaximumReceivedObjectSizeMB per aumentare il limite relativo alle dimensioni dell'oggetto. Viene inoltre utilizzato il parametro StartupScript per specificare uno script che configuri la sessione.

In alternativa all'utilizzo del parametro SecurityDescriptorSDDL, è possibile utilizzare il parametro ShowSecurityDescriptorUI che visualizza una finestra delle proprietà utilizzabile per impostare le autorizzazioni per la configurazione di sessione. Quando si fa clic su "OK" nella finestra delle proprietà, lo strumento genera un SDDL per la configurazione di sessione.






Esempio 4

C:\PS>$s = register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1

C:\PS> $s

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

Name                      Type                 Keys
----                      ----                 ----
MaintenanceShell          Container            {Name=MaintenanceShell}


C:\PS> $s.getType().fullname
TypeName: Microsoft.WSMan.Management.WSManConfigContainerElement


C:\PS> $s | format-list -property *

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


C:\PS> dir wsman:\localhost\plugin

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

Descrizione
-----------
In questo esempio viene indicato che un comando Register-PSSessionConfiguration restituisce WSManConfigContainerElement. Viene inoltre illustrato come trovare gli elementi del contenitore nell'unità WSMan:.

Con il primo comando si utilizza il cmdlet Register-PSSessionConfiguration per registrare la configurazione MaintenanceShell. Viene salvato l'oggetto restituito dal cmdlet nella variabile $s.

Con il secondo comando viene visualizzato il contenuto della variabile $s. 

Con il terzo comando si utilizza il metodo GetType e la relativa proprietà FullName per visualizzare il nome del tipo dell'oggetto restituito da Register-PSSessionConfiguration.

Con il quarto comando si utilizza il cmdlet Format-List per visualizzare tutte le proprietà dell'oggetto restituito da Register-PSSessionConfiguration in un elenco. La proprietà PSPath mostra che l'oggetto viene archiviato in una directory dell'unità WSMan:.

Con il quinto comando si utilizza il cmdlet Get-ChildItem per visualizzare gli elementi nel percorso WSMan:\LocalHost\PlugIn. Sono incluse la nuova configurazione MaintenanceShell e le due configurazioni predefinite fornite con Windows PowerShell.






Esempio 5

C:\PS>register-pssessionconfiguration -name WithProfile -startupScript add-profile.ps1

# Add-Profile.ps1

. c:\users\admin01\documents\windowspowershell\profile.ps1

Descrizione
-----------
Con questo comando viene creata e registrata la configurazione di sessione WithProfile nel computer locale. Con il comando si utilizza il parametro StartupScript per indicare a Windows PowerShell di eseguire lo script specificato in qualsiasi sessione che utilizza la configurazione di sessione.

Viene inoltre visualizzato il contenuto dello script specificato, Add-Profile.ps1. Lo script contiene un singolo comando che utilizza il dot sourcing per eseguire il profilo CurrentUserAllHosts dell'utente nell'ambito corrente della sessione.

Per ulteriori informazioni sui profili, vedere about_Profiles. Per ulteriori informazioni sul dot sourcing, vedere about_Scopes.






Vedere anche




Argomenti della Guida