Condividi tramite

Register-PSSessionConfiguration

  • Riferimento
Modulo:
Microsoft.PowerShell.Core

Crea e registra una nuova configurazione di sessione.

Sintassi

Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-SessionType <PSSessionType>]
        [-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

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 adminShell .

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:

  • Disabilitati. disabilita la configurazione di sessione. Non può essere usato per l'accesso remoto o locale 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.

Tipo:PSSessionConfigurationAccessMode
Valori accettati:Disabled, Local, Remote
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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.

Tipo:String
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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 .

Tipo:String
Posizione:1
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-ConfigurationTypeName

Specifica il nome completo del tipo microsoft .NET Framework 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 oppure 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.

Tipo:String
Posizione:2
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-Confirm

Richiede conferma prima di eseguire il cmdlet.

Tipo:SwitchParameter
Alias:cf
Posizione:Named
Valore predefinito:False
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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 .

Tipo:SwitchParameter
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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.

Tipo:Nullable<T>[Double]
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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 usato il limite nel tipo di configurazione e il valore di questo parametro viene ignorato.

Tipo:Nullable<T>[Double]
Posizione:Named
Valore predefinito:10
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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.

Tipo:Object[]
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-Name

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

Tipo:String
Posizione:0
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:True
Accettare caratteri jolly:False

-NoServiceRestart

Lo scopo di questo parametro è impedire il riavvio del servizio WinRM . Questa funzionalità non è implementata.

Questa funzionalità è stata implementata in PowerShell 7.5.0-preview.4, ma non è previsto il ripristino della porta di questa modifica a Windows PowerShell 5.1.

Tipo:SwitchParameter
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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.

Tipo:String
Posizione:Named
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:False
Accettare caratteri jolly: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.

Tipo:String
Alias:PA
Valori accettati:x86, amd64
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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.

Tipo:Version
Alias:PowerShellVersion
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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.

Tipo:PSCredential
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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.

Tipo:String
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-SessionType

Specifica il tipo di sessione che viene creato usando la configurazione di sessione. I valori validi per questo parametro sono:

  • Vuoto. Nessun modulo viene aggiunto alla sessione per impostazione predefinita. Usare i parametri di questo cmdlet per aggiungere moduli, funzioni, script o altre funzionalità alla sessione.
  • Predefinito. Aggiunge Microsoft.PowerShell.Core alla sessione. Questo modulo include il Import-Module cmdlet che gli utenti possono usare per importare altri moduli, a meno che non si impedisca esplicitamente il cmdlet.
  • RestrictedRemoteServer. Include solo i cmdlet seguenti: Exit-PSSession, Get-Command, Get-FormatData, Get-Help, Measure-ObjectOut-Default, e Select-Object. Usare uno script o un assembly oppure le chiavi nel file di configurazione della sessione per aggiungere moduli, funzioni, script e altre funzionalità alla sessione.

Il valore predefinito è Default.

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

Questo parametro è stato introdotto in PowerShell 3.0.

Tipo:PSSessionType
Valori accettati:DefaultRemoteShell, Workflow
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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 delle opzioni di sessione non possono superare i valori massimi impostati nella configurazione della sessione.

Questo parametro è stato introdotto in PowerShell 3.0.

Tipo:PSSessionTypeOption
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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.

Tipo:SwitchParameter
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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.

Tipo:String
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-ThreadApartmentState

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

  • Sconosciuto
  • MTA
  • STA
Tipo:ApartmentState
Valori accettati:STA, MTA, Unknown
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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:

  • Predefiniti
  • RiutilizzoThread
  • UseCurrentThread
  • UseNewThread

Il valore predefinito è UseCurrentThread.

Per altre informazioni, vedere Enumerazione PSThreadOptions.

Tipo:PSThreadOptions
Valori accettati:Default, UseNewThread, ReuseThread, UseCurrentThread
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-TransportOption

Specifica l'opzione di trasporto.

Questo parametro è stato introdotto in PowerShell 3.0.

Tipo:PSTransportOption
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly: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.

Tipo:SwitchParameter
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-WhatIf

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

Tipo:SwitchParameter
Alias:wi
Posizione:Named
Valore predefinito:False
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

Input

None

Non è possibile inviare tramite pipe oggetti a questo cmdlet.

Output

WSManConfigContainerElement

Note

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.