New-PSSessionConfigurationFile

Syntax

New-PSSessionConfigurationFile
   [-Path] <String>
   [-SchemaVersion <Version>]
   [-Guid <Guid>]
   [-Author <String>]
   [-Description <String>]
   [-CompanyName <String>]
   [-Copyright <String>]
   [-SessionType <SessionType>]
   [-TranscriptDirectory <String>]
   [-RunAsVirtualAccount]
   [-RunAsVirtualAccountGroups <String[]>]
   [-MountUserDrive]
   [-UserDriveMaximumSize <Int64>]
   [-GroupManagedServiceAccount <String>]
   [-ScriptsToProcess <String[]>]
   [-RoleDefinitions <IDictionary>]
   [-RequiredGroups <IDictionary>]
   [-LanguageMode <PSLanguageMode>]
   [-ExecutionPolicy <ExecutionPolicy>]
   [-PowerShellVersion <Version>]
   [-ModulesToImport <Object[]>]
   [-VisibleAliases <String[]>]
   [-VisibleCmdlets <Object[]>]
   [-VisibleFunctions <Object[]>]
   [-VisibleExternalCommands <String[]>]
   [-VisibleProviders <String[]>]
   [-AliasDefinitions <IDictionary[]>]
   [-FunctionDefinitions <IDictionary[]>]
   [-VariableDefinitions <Object>]
   [-EnvironmentVariables <IDictionary>]
   [-TypesToProcess <String[]>]
   [-FormatsToProcess <String[]>]
   [-AssembliesToLoad <String[]>]
   [-Full]
   [<CommonParameters>]

Beschreibung

Das New-PSSessionConfigurationFile Cmdlet erstellt eine Datei mit Einstellungen, die eine Sitzungskonfiguration und die Umgebung von Sitzungen definieren, die mithilfe der Sitzungskonfiguration erstellt werden. Um die Datei in einer Sitzungskonfiguration zu verwenden, verwenden Sie den Path-Parameter der Register-PSSessionConfiguration Oder Set-PSSessionConfiguration Cmdlets.

Die Sitzungskonfigurationsdatei, die erstellt wird, New-PSSessionConfigurationFile ist eine lesbare Textdatei, die eine Hashtabelle der Sitzungskonfigurationseigenschaften und -werte enthält. Die Datei hat eine .pssc Dateinamenerweiterung.

Alle Parameter sind New-PSSessionConfigurationFile optional, mit Ausnahme des Path-Parameters . Wenn Sie einen Parameter weglassen, wird der entsprechende Schlüssel in der Sitzungskonfigurationsdatei auskommentiert, es sei denn, er wurde in der Parameterbeschreibung angegeben.

Eine Sitzungskonfiguration, auch als Endpunkt bezeichnet, ist eine Sammlung von Einstellungen auf dem lokalen Computer, die die Umgebung für PowerShell-Sitzungen (PSSessions) definieren, die eine Verbindung mit dem Computer herstellen. Alle PSSessions verwenden eine Sitzungskonfiguration . Verwenden Sie zum Angeben einer bestimmten Sitzungskonfiguration den ConfigurationName-Parameter von Cmdlets, die eine Sitzung erstellen, z. B. das New-PSSession Cmdlet.

Eine Sitzungskonfigurationsdatei erleichtert das Definieren einer Sitzungskonfiguration ohne komplexe Skripts oder Codeassemblys. Die Einstellungen in der Datei werden mit dem optionalen Startskript und allen Assemblys in der Sitzungskonfiguration verwendet.

Weitere Informationen zu Sitzungskonfigurationen und Sitzungskonfigurationsdateien finden Sie unter about_Session_Configurations und about_Session_Configuration_Files.

Dieses Cmdlet wurde in PowerShell 3.0 eingeführt. Ab PowerShell 6.0 war dieses Cmdlet nur auf der Windows-Plattform verfügbar. PowerShell 7.3 hat dieses Cmdlet auf allen unterstützten Plattformen verfügbar gemacht.

Beispiele

Beispiel 1: Erstellen und Verwenden einer NoLanguage-Sitzung

In diesem Beispiel wird gezeigt, wie Sie eine No-Language-Sitzung erstellen und die Effekte verwenden.

Dazu müssen folgende Schritte ausgeführt werden:

1. Erstellen Sie eine neue Konfigurationsdatei.
2. Registrieren Sie die Konfiguration.
3. Erstellen Sie eine neue Sitzung, die die Konfiguration verwendet.
4. Führen Sie Befehle in dieser neuen Sitzung aus.

Um die Befehle in diesem Beispiel auszuführen, starten Sie PowerShell mithilfe der Option "Als Administrator ausführen". Diese Option ist erforderlich, um das Register-PSSessionConfiguration Cmdlet auszuführen.

New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode NoLanguage
Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name NoLanguage -Force
$NoLanguageSession = New-PSSession -ComputerName Srv01 -ConfigurationName NoLanguage
Invoke-Command -Session $NoLanguageSession -ScriptBlock {
  if ((Get-Date) -lt '1January2099') {'Before'} else {'After'}
}

The syntax is not supported by this runspace. This might be because it is in no-language mode.
    + CategoryInfo          : ParserError: (if ((Get-Date) ...') {'Before'}  :String) [], ParseException
    + FullyQualifiedErrorId : ScriptsNotAllowed
    + PSComputerName        : localhost

In diesem Beispiel schlägt der Invoke-Command Fehler fehl, da der LanguageMode auf "NoLanguage" festgelegt ist.

Beispiel 2: Erstellen und Verwenden einer RestrictedLanguage-Sitzung

In diesem Beispiel wird gezeigt, wie Sie eine No-Language-Sitzung erstellen und die Effekte verwenden.

Dazu müssen folgende Schritte ausgeführt werden:

1. Erstellen Sie eine neue Konfigurationsdatei.
2. Registrieren Sie die Konfiguration.
3. Erstellen Sie eine neue Sitzung, die die Konfiguration verwendet.
4. Führen Sie Befehle in dieser neuen Sitzung aus.

Um die Befehle in diesem Beispiel auszuführen, starten Sie PowerShell mithilfe der Option "Als Administrator ausführen". Diese Option ist erforderlich, um das Register-PSSessionConfiguration Cmdlet auszuführen.

New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode RestrictedLanguage
Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name RestrictedLanguage -Force
$RestrictedSession = New-PSSession -ComputerName Srv01 -ConfigurationName RestrictedLanguage
Invoke-Command -Session $RestrictedSession -ScriptBlock {
  if ((Get-Date) -lt '1January2099') {'Before'} else {'After'}
}

Before

In diesem Beispiel wird der Invoke-Command Vorgang erfolgreich ausgeführt, da " LanguageMode " auf "RestrictedLanguage" festgelegt ist.

Beispiel 3: Ändern einer Sitzungskonfigurationsdatei

In diesem Beispiel wird gezeigt, wie Sie die Sitzungskonfigurationsdatei ändern, die in einer vorhandenen Sitzung mit dem Namen "ITTasks" verwendet wird. Zuvor hatten diese Sitzungen nur die Kernmodule und ein internes ITTasks-Modul . Der Administrator möchte das PSScheduledJob-Modul zu Sitzungen hinzufügen, die mithilfe der ITTasks-Sitzungskonfiguration erstellt wurden.

New-PSSessionConfigurationFile -Path .\New-ITTasks.pssc -ModulesToImport Microsoft*, ITTasks, PSScheduledJob
Set-PSSessionConfiguration -Name ITTasks -Path .\New-ITTasks.pssc

Das New-PSSessionConfigurationFile Cmdlet zum Erstellen einer Sitzungskonfigurationsdatei, die die erforderlichen Module importiert. Das Set-PSSessionConfiguration Cmdlet ersetzt die aktuelle Konfigurationsdatei durch die neue. Diese neue Konfiguration wirkt sich nur auf neue Sitzungen aus, die nach der Änderung erstellt wurden. Vorhandene "ITTasks"-Sitzungen sind nicht betroffen.

Beispiel 4: Bearbeiten einer Sitzungskonfigurationsdatei

In diesem Beispiel wird veranschaulicht, wie Sie eine Sitzungskonfiguration durch Bearbeiten der aktiven Sitzungskonfigurationskopie der Konfigurationsdatei ändern können. Um die Sitzungskonfigurationskopie der Konfigurationsdatei zu ändern, müssen Sie vollzugriff auf die Datei haben. Dies erfordert möglicherweise, dass Sie die Berechtigungen für die Datei ändern.

In diesem Szenario möchten wir einen neuen Alias für das Select-String Cmdlet hinzufügen, indem wir die aktive Konfigurationsdatei bearbeiten.

Der folgende Beispielcode führt die folgenden Schritte aus, um diese Änderung vorzunehmen:

1. Rufen Sie den Konfigurationsdateipfad für die ITConfig-Sitzung ab.
2. Der Benutzer bearbeitet die Konfigurationsdatei mithilfe von Notepad.exe, um den AliasDefinitions-Wert wie folgt zu ändern: AliasDefinitions = @(@{Name='slst';Value='Select-String'})
3. Testen Sie die aktualisierte Konfigurationsdatei.

$ITConfig = Get-PSSessionConfiguration -Name ITConfig
notepad.exe $ITConfig.ConfigFilePath
Test-PSSessionConfigurationFile -Path $ITConfig.ConfigFilePath

True

Verwenden Sie den Verbose-Parameter , Test-PSSessionConfigurationFile um alle erkannten Fehler anzuzeigen. Das Cmdlet gibt zurück $True , wenn in der Datei keine Fehler erkannt werden.

Beispiel 5: Erstellen einer Beispielkonfigurationsdatei

Dieses Beispiel zeigt einen New-PSSessionConfigurationFile Befehl, der alle Cmdlet-Parameter verwendet. Er wurde angegeben, um das richtige Eingabeformat für jeden Parameter zu zeigen.

Die resultierende SampleFile.pssc wird in der Ausgabe angezeigt.

$configSettings = @{
    Path = '.\SampleFile.pssc'
    SchemaVersion = '1.0.0.0'
    Author = 'User01'
    Copyright = '(c) Fabrikam Corporation. All rights reserved.'
    CompanyName = 'Fabrikam Corporation'
    Description = 'This is a sample file.'
    ExecutionPolicy = 'AllSigned'
    PowerShellVersion = '3.0'
    LanguageMode = 'FullLanguage'
    SessionType = 'Default'
    EnvironmentVariables = @{TESTSHARE='\\Test2\Test'}
    ModulesToImport = @{ModuleName='PSScheduledJob'; ModuleVersion='1.0.0.0'; GUID='50cdb55f-5ab7-489f-9e94-4ec21ff51e59'},'PSDiagnostics'
    AssembliesToLoad = 'System.Web.Services','FSharp.Compiler.CodeDom.dll'
    TypesToProcess = 'Types1.ps1xml','Types2.ps1xml'
    FormatsToProcess = 'CustomFormats.ps1xml'
    ScriptsToProcess = 'Get-Inputs.ps1'
    AliasDefinitions = @{Name='hlp';Value='Get-Help';Description='Gets help.';Options='AllScope'},
        @{Name='Update';Value='Update-Help';Description='Updates help';Options='ReadOnly'}
    FunctionDefinitions = @{Name='Get-Function';ScriptBlock={Get-Command -CommandType Function};Options='ReadOnly'}
    VariableDefinitions = @{Name='WarningPreference';Value='SilentlyContinue'}
    VisibleAliases = 'c*','g*','i*','s*'
    VisibleCmdlets = 'Get*'
    VisibleFunctions = 'Get*'
    VisibleProviders = 'FileSystem','Function','Variable'
    RunAsVirtualAccount = $true
    RunAsVirtualAccountGroups = 'Backup Operators'
}
New-PSSessionConfigurationFile @configSettings
Get-Content SampleFile.pssc

@{

# Version number of the schema used for this document
SchemaVersion = '1.0.0.0'

# ID used to uniquely identify this document
GUID = '1caeff7f-27ca-4360-97cf-37846f594235'

# Author of this document
Author = 'User01'

# Description of the functionality provided by these settings
Description = 'This is a sample file.'

# Company associated with this document
CompanyName = 'Fabrikam Corporation'

# Copyright statement for this document
Copyright = '(c) Fabrikam Corporation. All rights reserved.'

# Session type defaults to apply for this session configuration. Can be 'RestrictedRemoteServer' (recommended), 'Empty', or 'Default'
SessionType = 'Default'

# Directory to place session transcripts for this session configuration
# TranscriptDirectory = 'C:\Transcripts\'

# Whether to run this session configuration as the machine's (virtual) administrator account
RunAsVirtualAccount = $true

# Groups associated with machine's (virtual) administrator account
RunAsVirtualAccountGroups = 'Backup Operators'

# Scripts to run when applied to a session
ScriptsToProcess = 'Get-Inputs.ps1'

# User roles (security groups), and the role capabilities that should be applied to them when applied to a session
# RoleDefinitions = @{ 'CONTOSO\SqlAdmins' = @{ RoleCapabilities = 'SqlAdministration' }; 'CONTOSO\SqlManaged' = @{ RoleCapabilityFiles = 'C:\RoleCapability\SqlManaged.psrc' }; 'CONTOSO\ServerMonitors' = @{ VisibleCmdlets = 'Get-Process' } }

# Language mode to apply when applied to a session. Can be 'NoLanguage' (recommended), 'RestrictedLanguage', 'ConstrainedLanguage', or 'FullLanguage'
LanguageMode = 'FullLanguage'

# Execution policy to apply when applied to a session
ExecutionPolicy = 'AllSigned'

# Version of the PowerShell engine to use when applied to a session
PowerShellVersion = '3.0'

# Modules to import when applied to a session
ModulesToImport = @{
    'GUID' = '50cdb55f-5ab7-489f-9e94-4ec21ff51e59'
    'ModuleName' = 'PSScheduledJob'
    'ModuleVersion' = '1.0.0.0' }, 'PSDiagnostics'

# Aliases to make visible when applied to a session
VisibleAliases = 'c*', 'g*', 'i*', 's*'

# Cmdlets to make visible when applied to a session
VisibleCmdlets = 'Get*'

# Functions to make visible when applied to a session
VisibleFunctions = 'Get*'

# Providers to make visible when applied to a session
VisibleProviders = 'FileSystem', 'Function', 'Variable'

# Aliases to be defined when applied to a session
AliasDefinitions = @{
    'Description' = 'Gets help.'
    'Name' = 'hlp'
    'Options' = 'AllScope'
    'Value' = 'Get-Help' }, @{
    'Description' = 'Updates help'
    'Name' = 'Update'
    'Options' = 'ReadOnly'
    'Value' = 'Update-Help' }

# Functions to define when applied to a session
FunctionDefinitions = @{
    'Name' = 'Get-Function'
    'Options' = 'ReadOnly'
    'ScriptBlock' = {Get-Command -CommandType Function} }

# Variables to define when applied to a session
VariableDefinitions = @{
    'Name' = 'WarningPreference'
    'Value' = 'SilentlyContinue' }

# Environment variables to define when applied to a session
EnvironmentVariables = @{
    'TESTSHARE' = '\\Test2\Test' }

# Type files (.ps1xml) to load when applied to a session
TypesToProcess = 'Types1.ps1xml', 'Types2.ps1xml'

# Format files (.ps1xml) to load when applied to a session
FormatsToProcess = 'CustomFormats.ps1xml'

# Assemblies to load when applied to a session
AssembliesToLoad = 'System.Web.Services', 'FSharp.Compiler.CodeDom.dll'

}

Parameter

-AliasDefinitions

-AssembliesToLoad

-Author

-CompanyName

-Copyright

-Description

-EnvironmentVariables

-ExecutionPolicy

-FormatsToProcess

-Full

-FunctionDefinitions

-GroupManagedServiceAccount

-Guid

-LanguageMode

-ModulesToImport

-MountUserDrive

-Path

-PowerShellVersion

-RequiredGroups

-RoleDefinitions

-RunAsVirtualAccount

-RunAsVirtualAccountGroups

-SchemaVersion

-ScriptsToProcess

-SessionType

-TranscriptDirectory

-TypesToProcess

-UserDriveMaximumSize

-VariableDefinitions

-VisibleAliases

-VisibleCmdlets

-VisibleExternalCommands

-VisibleFunctions

-VisibleProviders

Eingaben

None

Sie können keine Objekte an dieses Cmdlet weiterleiten.

Ausgaben

None

Dieses Cmdlet gibt keine Ausgabe zurück.

Hinweise

• Parameter wie VisibleCmdlets und VisibleProviders importieren keine Elemente in die Sitzung. Stattdessen treffen sie ihre Auswahl unter den Elementen, die in die Sitzung importiert wurden. Wenn beispielsweise der Wert des VisibleProviders-Parameters der Zertifikatanbieter ist, aber der ModulesToImport-Parameter nicht das Microsoft.PowerShell.Security-Modul angibt, das den Zertifikatanbieter enthält, ist der Zertifikatanbieter in der Sitzung nicht sichtbar.

• New-PSSessionConfigurationFile erstellt eine Sitzungskonfigurationsdatei mit der Dateinamenerweiterung PSSC im Pfad, den Sie im Parameter "Path " angeben. Wenn Sie die Sitzungskonfigurationsdatei zum Erstellen einer Sitzungskonfiguration verwenden, kopiert das Register-PSSessionConfiguration Cmdlet die Konfigurationsdatei und speichert eine aktive Kopie der Datei im Unterverzeichnis SessionConfig des $PSHOME Verzeichnisses.

  Die ConfigFilePath-Eigenschaft der Sitzungskonfiguration enthält den vollqualifizierten Pfad der aktiven Sitzungskonfigurationsdatei. Sie können die aktive Konfigurationsdatei im $PSHOME Verzeichnis jederzeit mithilfe eines beliebigen Text-Editors ändern. Die Änderungen, die Sie vornehmen, betreffen alle neuen Sitzungen, die diese Sitzungskonfiguration verwenden, aber nicht bereits vorhandene Sitzungen.

  Verwenden Sie vor der Verwendung einer bearbeiteten Sitzungskonfigurationsdatei das Test-PSSessionConfigurationFile Cmdlet, um zu überprüfen, ob die Konfigurationsdateieinträge gültig sind.

Ähnliche Themen

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration
• Get-PSSessionConfiguration
• Register-PSSessionConfiguration
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• WSMan-Anbieter
• about_Session_Configurations
• about_Session_Configuration_Files