about_Session_Configuration_Files

Articolo
04/13/2023

Descrizione breve

Descrive i file di configurazione della sessione, usati in una configurazione di sessione (nota anche come "endpoint") per definire l'ambiente delle sessioni che usano la configurazione di sessione.

Descrizione lunga

Queste informazioni si applicano solo a PowerShell in esecuzione in Windows.

Un "file di configurazione della sessione" è un file di testo con estensione pssc che contiene una tabella hash di proprietà e valori di configurazione della sessione. È possibile usare un file di configurazione della sessione per impostare le proprietà di una configurazione di sessione. In questo modo viene definito l'ambiente di tutte le sessioni di PowerShell che usano tale configurazione di sessione.

I file di configurazione della sessione semplificano la creazione di configurazioni di sessione personalizzate senza usare assembly o script C# complessi.

Una "configurazione di sessione" o "endpoint" è una raccolta di impostazioni del computer locale che determinano quali utenti possono creare sessioni nel computer; quali comandi gli utenti possono eseguire in tali sessioni; e se la sessione deve essere eseguita come account virtuale con privilegi. Per altre informazioni sulle configurazioni di sessione, vedere about_Session_Configurations.

Le configurazioni di sessione sono state introdotte in Windows PowerShell 2.0 e i file di configurazione della sessione sono stati introdotti in Windows PowerShell 3.0. È necessario usare Windows PowerShell 3.0 per includere un file di configurazione della sessione in una configurazione di sessione. Tuttavia, gli utenti di Windows PowerShell 2.0 (e versioni successive) sono interessati dalle impostazioni nella configurazione della sessione.

Creazione di sessioni personalizzate

È possibile personalizzare molte funzionalità di una sessione di PowerShell specificando le proprietà della sessione in una configurazione di sessione. È possibile personalizzare una sessione scrivendo un programma C# che definisce uno spazio di esecuzione personalizzato oppure è possibile usare un file di configurazione della sessione per definire le proprietà delle sessioni create usando la configurazione della sessione. Come regola generale, è più facile usare il file di configurazione della sessione che scrivere un programma C#.

È possibile usare un file di configurazione della sessione per creare elementi come sessioni completamente funzionanti per gli utenti altamente attendibili; sessioni bloccate che consentono l'accesso minimo; sessioni progettate per particolari e che contengono solo i moduli necessari per tali attività; e sessioni in cui gli utenti senza privilegi possono eseguire solo comandi specifici come account con privilegi.

Oltre a questo, è possibile gestire se gli utenti della sessione possono usare elementi del linguaggio di PowerShell, ad esempio blocchi di script, o se possono eseguire solo comandi. È possibile gestire la versione di PowerShell che gli utenti possono eseguire nella sessione; gestire i moduli importati nella sessione; e gestire quali cmdlet, funzioni e alias possono essere eseguiti dagli utenti di sessione. Quando si usa il campo RoleDefinitions, è possibile offrire agli utenti funzionalità diverse nella sessione in base all'appartenenza al gruppo.

Per altre informazioni su RoleDefinitions e su come definire questo valore, vedere l'argomento della Guida per il cmdlet New-PSRoleCapabilityFile.

Creazione di un file di configurazione di sessione

Il modo più semplice per creare un file di configurazione della sessione consiste nell'usare il cmdlet New-PSSessionConfigurationFile. Questo cmdlet genera un file che usa la sintassi e il formato corretti e che verifica automaticamente molti dei valori delle proprietà del file di configurazione.

Per descrizioni dettagliate delle proprietà che è possibile impostare in un file di configurazione della sessione, vedere l'argomento della Guida per il cmdlet New-PSSessionConfigurationFile.

Il comando seguente crea un file di configurazione della sessione che usa i valori predefiniti. Il file di configurazione risultante usa solo i valori predefiniti perché non sono inclusi parametri diversi dal parametro Path (che specifica il percorso del file):

New-PSSessionConfigurationFile -Path .\Defaults.pssc

Per visualizzare il nuovo file di configurazione nell'editor di testo predefinito, usare il comando seguente:

Invoke-Item -Path .\Defaults.pssc

Per creare una configurazione di sessione per le sessioni in cui l'utente può eseguire comandi, ma non usare altri elementi del linguaggio di PowerShell, digitare:

New-PSSessionConfigurationFile -LanguageMode NoLanguage
-Path .\NoLanguage.pssc

Nel comando precedente, l'impostazione del parametro LanguageMode su NoLanguage impedisce agli utenti di eseguire operazioni come la scrittura o l'esecuzione di script o l'uso di variabili.

Per creare una configurazione di sessione per le sessioni in cui gli utenti possono usare solo i cmdlet Get, digitare:

New-PSSessionConfigurationFile -VisibleCmdlets Get-*
-Path .\GetSessions.pssc

Nell'esempio precedente l'impostazione del parametro VisibleCmdlets su Get-* limita gli utenti ai cmdlet con nomi che iniziano con il valore stringa "Get-".

Per creare una configurazione di sessione per le sessioni eseguite con un account virtuale con privilegi anziché le credenziali dell'utente, digitare:

New-PSSessionConfigurationFile -RunAsVirtualAccount
-Path .\VirtualAccount.pssc

Per creare una configurazione di sessione per le sessioni in cui i comandi visibili all'utente vengono specificati in un file delle funzionalità del ruolo, digitare:

New-PSSessionConfigurationFile -RoleDefinitions
@{ 'CONTOSO\User' = @{ RoleCapabilities = 'Maintenance' }}
-Path .\Maintenance.pssc

Uso di un file di configurazione di sessione

È possibile includere un file di configurazione della sessione quando si crea una configurazione di sessione o si aggiunge un file alla configurazione della sessione in un secondo momento.

Per includere un file di configurazione della sessione durante la creazione di una configurazione di sessione, usare il parametro Path del cmdlet Register-PSSessionConfiguration.

Ad esempio, il comando seguente usa il file NoLanguage.pssc quando crea una configurazione di sessione NoLanguage.

Register-PSSessionConfiguration -Name NoLanguage
-Path .\NoLanguage.pssc

All'avvio di una nuova sessione NoLanguage, gli utenti avranno accesso solo ai comandi di PowerShell.

Per aggiungere un file di configurazione di sessione a una configurazione di sessione esistente, usare il cmdlet Set-PSSessionConfiguration e il parametro Path. Ciò influisce su tutte le nuove sessioni create con la configurazione di sessione specificata. Si noti che il cmdlet Set-PSSessionConfiguration modifica la sessione stessa e non modifica il file di configurazione della sessione.

Ad esempio, il comando seguente aggiunge il file NoLanguage.pssc alla configurazione della sessione LockedDown.

Set-PSSessionConfiguration -Name LockedDown
-Path .\NoLanguage.pssc

Quando gli utenti usano la configurazione della sessione LockedDown per creare una sessione, potranno eseguire i cmdlet, ma non potranno creare o usare variabili, assegnare valori o usare altri elementi del linguaggio di PowerShell.

Il comando seguente usa il cmdlet New-PSSession per creare una sessione nel computer Srv01 che usa la configurazione della sessione LockedDown, salvando un riferimento oggetto alla sessione nella variabile $s. L'elenco di controllo di accesso (elenco di controllo di accesso) della configurazione della sessione determina chi può usarlo per creare una sessione.

$s = New-PSSession -ComputerName Srv01
-ConfigurationName LockedDown

Poiché i vincoli NoLanguage sono stati aggiunti alla configurazione della sessione LockedDown, gli utenti nelle sessioni LockedDown potranno eseguire solo comandi e cmdlet di PowerShell. Ad esempio, i due comandi seguenti usano il cmdlet Invoke-Command per eseguire i comandi nella sessione a cui si fa riferimento nella variabile $s. Il primo comando, che esegue il cmdlet Get-UICulture e non usa variabili, ha esito positivo. Il secondo comando, che ottiene il valore della variabile $PSUICulture, ha esito negativo.

Invoke-Command -Session $s {Get-UICulture}
en-US

Invoke-Command -Session $s {$PSUICulture}
The syntax is not supported by this runspace. This might be
because it is in no-language mode.
+ CategoryInfo          : ParserError: ($PSUICulture:String) [],
ParseException
+ FullyQualifiedErrorId : ScriptsNotAllowed

Modifica di un file di configurazione della sessione

Tutte le impostazioni in una configurazione di sessione, ad eccezione di RunAsVirtualAccount e RunAsVirtualAccountGroups, possono essere modificate modificando il file di configurazione della sessione usato dalla configurazione della sessione. A tale scopo, iniziare individuando la copia attiva del file di configurazione della sessione.

Quando si usa un file di configurazione di sessione in una configurazione di sessione, PowerShell crea una copia attiva del file di configurazione della sessione e lo archivia nella directory $pshome\SessionConfig nel computer locale.

Il percorso della copia attiva di un file di configurazione della sessione viene archiviato nella proprietà ConfigFilePath dell'oggetto di configurazione della sessione.

Il comando seguente ottiene il percorso del file di configurazione della sessione per la configurazione della sessione NoLanguage.

(Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath

Questo comando restituisce un percorso di file simile al seguente:

C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\
NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc

È possibile modificare il file pssc in qualsiasi editor di testo. Dopo aver salvato il file, verrà usato da tutte le nuove sessioni che usano la configurazione della sessione.

Se è necessario modificare le impostazioni RunAsVirtualAccount o RunAsVirtualAccountGroups, è necessario annullare la registrazione della configurazione della sessione e registrare nuovamente un file di configurazione della sessione che include i valori modificati.

Test di un file di configurazione della sessione

Usare il cmdlet Test-PSSessionConfigurationFile per testare i file di configurazione della sessione modificati manualmente. È importante: se la sintassi e i valori dei file non sono validi, gli utenti non potranno usare la configurazione di sessione per creare una sessione.

Ad esempio, il comando seguente testa il file di configurazione sessione attivo della configurazione della sessione NoLanguage.

Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\
WindowsPowerShell\v1.0\SessionConfig\
NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc

Se la sintassi e i valori nel file di configurazione sono validi, Test-PSSessionConfigurationFile restituisce True. Se la sintassi e i valori non sono validi, il cmdlet restituisce False.

È possibile usare Test-PSSessionConfigurationFile per testare qualsiasi file di configurazione della sessione, inclusi i file creati dal cmdlet New-PSSessionConfiguration. Per altre informazioni, vedere l'argomento della Guida per il cmdlet Test-PSSessionConfigurationFile.

Rimozione di un file di configurazione di sessione

Non è possibile rimuovere un file di configurazione di sessione da una configurazione di sessione. Tuttavia, è possibile sostituire il file con un nuovo file che usa le impostazioni predefinite. Ciò annulla in modo efficace le impostazioni usate dal file di configurazione originale.

Per sostituire un file di configurazione della sessione, creare un nuovo file di configurazione della sessione che usa le impostazioni predefinite, quindi usare il cmdlet Set-PSSessionConfiguration per sostituire il file di configurazione sessione personalizzato con il nuovo file.

Ad esempio, i comandi seguenti creano un file di configurazione sessione predefinito e quindi sostituiscono il file di configurazione sessione attivo nella configurazione della sessione NoLanguage.

New-PSSessionConfigurationFile -Path .\Default.pssc
Set-PSSessionConfiguration -Name NoLanguage
-Path .\Default.pssc

Al termine di questi comandi, la configurazione della sessione NoLanguage fornirà effettivamente supporto linguistico completo (impostazione predefinita) per tutte le sessioni create con tale configurazione di sessione.

Visualizzazione delle proprietà di una configurazione sessione Gli oggetti di configurazione della sessione che rappresentano le configurazioni di sessione che usano i file di configurazione della sessione hanno proprietà aggiuntive che semplificano l'individuazione e l'analisi della configurazione della sessione. Si noti che il nome del tipo illustrato di seguito include una definizione di visualizzazione formattata. È possibile visualizzare le proprietà eseguendo il cmdlet Get-PSSessionConfiguration e inviando i dati restituiti al cmdlet Get-Member:

Get-PSSessionConfiguration NoLanguage | Get-Member

TypeName: Microsoft.PowerShell.Commands.PSSessionConfigurationCommands
#PSSessionConfiguration

Name                          MemberType     Definition
----                          ----------     ----------
Equals                        Method         bool Equals(System.O...
GetHashCode                   Method         int GetHashCode()
GetType                       Method         type GetType()
ToString                      Method         string ToString()
Architecture                  NoteProperty   System.String Archit...
Author                        NoteProperty   System.String Author...
AutoRestart                   NoteProperty   System.String AutoRe...
Capability                    NoteProperty   System.Object[] Capa...
CompanyName                   NoteProperty   System.String Compan...
configfilepath                NoteProperty   System.String config...
Copyright                     NoteProperty   System.String Copyri...
Enabled                       NoteProperty   System.String Enable...
ExactMatch                    NoteProperty   System.String ExactM...
ExecutionPolicy               NoteProperty   System.String Execut...
Filename                      NoteProperty   System.String Filena...
GUID                          NoteProperty   System.String GUID=0...
ProcessIdleTimeoutSec         NoteProperty   System.String Proces...
IdleTimeoutms                 NoteProperty   System.String IdleTi...
lang                          NoteProperty   System.String lang=e...
LanguageMode                  NoteProperty   System.String Langua...
MaxConcurrentCommandsPerShell NoteProperty   System.String MaxCon...
MaxConcurrentUsers            NoteProperty   System.String MaxCon...
MaxIdleTimeoutms              NoteProperty   System.String MaxIdl...
MaxMemoryPerShellMB           NoteProperty   System.String MaxMem...
MaxProcessesPerShell          NoteProperty   System.String MaxPro...
MaxShells                     NoteProperty   System.String MaxShells
MaxShellsPerUser              NoteProperty   System.String MaxShe...
Name                          NoteProperty   System.String Name=N...
PSVersion                     NoteProperty   System.String PSVersion
ResourceUri                   NoteProperty   System.String Resour...
RunAsPassword                 NoteProperty   System.String RunAsP...
RunAsUser                     NoteProperty   System.String RunAsUser
SchemaVersion                 NoteProperty   System.String Schema...
SDKVersion                    NoteProperty   System.String SDKVer...
OutputBufferingMode           NoteProperty   System.String Output...
SessionType                   NoteProperty   System.String Sessio...
UseSharedProcess              NoteProperty   System.String UseSha...
SupportsOptions               NoteProperty   System.String Suppor...
xmlns                         NoteProperty   System.String xmlns=...
XmlRenderingType              NoteProperty   System.String XmlRen...
Permission                    ScriptProperty System.Object Permis...

Queste proprietà semplificano la ricerca di configurazioni di sessione specifiche. Ad esempio, è possibile usare la proprietà ExecutionPolicy per trovare una configurazione di sessione che supporta le sessioni con i criteri di esecuzione RemoteSigned. Si noti che, poiché la proprietà ExecutionPolicy esiste solo nelle sessioni che usano file di configurazione della sessione, il comando potrebbe non restituire tutte le configurazioni di sessione idonee.

Get-PSSessionConfiguration |
where {$_.ExecutionPolicy -eq "RemoteSigned"}

Il comando seguente ottiene le configurazioni di sessione in cui RunAsUser è l'amministratore di Exchange.

 Get-PSSessionConfiguration |
where {$_.RunAsUser -eq "Exchange01\Admin01"}

Per visualizzare informazioni sulle definizioni di ruolo associate a una configurazione, usare il cmdlet Get-PSSessionCapability. Questo cmdlet consente di determinare i comandi e l'ambiente disponibili per utenti specifici in endpoint specifici.

Note

Le configurazioni di sessione supportano anche un tipo di sessione noto come sessione "vuota". Un tipo di sessione vuoto consente di creare sessioni personalizzate con i comandi selezionati. Se non si aggiungono moduli, funzioni o script a una sessione vuota, la sessione è limitata alle espressioni e potrebbe non essere di uso pratico. La proprietà SessionType indica se si utilizza o meno una sessione vuota.