New-PSSessionConfigurationFile

New-PSSessionConfigurationFile
    [-Path] <String>
    [-SchemaVersion <Version>]
    [-Guid <Guid>]
    [-Author <String>]
    [-CompanyName <String>]
    [-Copyright <String>]
    [-Description <String>]
    [-PowerShellVersion <Version>]
    [-SessionType <SessionType>]
    [-ModulesToImport <Object[]>]
    [-AssembliesToLoad <String[]>]
    [-VisibleAliases <String[]>]
    [-VisibleCmdlets <String[]>]
    [-VisibleFunctions <String[]>]
    [-VisibleProviders <String[]>]
    [-AliasDefinitions <Hashtable[]>]
    [-FunctionDefinitions <Hashtable[]>]
    [-VariableDefinitions <Object>]
    [-EnvironmentVariables <Object>]
    [-TypesToProcess <String[]>]
    [-FormatsToProcess <String[]>]
    [-LanguageMode <PSLanguageMode>]
    [-ExecutionPolicy <ExecutionPolicy>]
    [-ScriptsToProcess <String[]>]
    [<CommonParameters>]

Das Cmdlet New-PSSessionConfigurationFile 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 Parameter Path der cmdlets Register-PSSessionConfiguration oder Set-PSSessionConfiguration.

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

Alle Parameter von New-PSSessionConfigurationFile sind optional, mit Ausnahme des Path-Parameters. Wenn Sie einen Parameter weglassen, wird der entsprechende Schlüssel in der Sitzungskonfigurationsdatei auskommentiert, mit Ausnahme der Angabe in der Parameterbeschreibung.

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 eine Sitzungskonfiguration verwenden. Um eine bestimmte Sitzungskonfiguration anzugeben, verwenden Sie den ConfigurationName Parameter von Cmdlets, die eine Sitzung erstellen, z. B. das Cmdlet New-PSSession.

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.

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

Die Schritte umfassen:

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 cmdlet Register-PSSessionConfiguration auszuführen.

New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode NoLanguage
Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name NoLanguage -Force
$NoLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName NoLanguage
Invoke-Command -Session $NoLanguage -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 die Invoke-Command fehl, da die LanguageMode- auf NoLanguagefestgelegt ist.

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

Die Schritte umfassen:

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 cmdlet Register-PSSessionConfiguration auszuführen.

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

Before

In diesem Beispiel ist die Invoke-Command erfolgreich, da die LanguageMode- auf RestrictedLanguagefestgelegt ist.

In diesem Beispiel wird gezeigt, wie Sie die Sitzungskonfigurationsdatei ändern, die in einer vorhandenen Sitzung mit dem Namen "ITTasks" verwendet wird. Bisher 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 Cmdlet New-PSSessionConfigurationFile zum Erstellen einer Sitzungskonfigurationsdatei, die die erforderlichen Module importiert. Das Cmdlet Set-PSSessionConfiguration 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.

In diesem Beispiel wird gezeigt, wie Sie eine Sitzungskonfiguration ändern, indem Sie die aktive Sitzungskonfigurationskopie der Konfigurationsdatei bearbeiten. 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 Cmdlet Select-String 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 wert AliasDefinitions 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 parameter Verbose mit Test-PSSessionConfigurationFile, um alle erkannten Fehler anzuzeigen. Das Cmdlet gibt $True zurück, wenn in der Datei keine Fehler erkannt werden.

Dieses Beispiel zeigt einen New-PSSessionConfigurationFile-Befehl, der alle Cmdlet-Parameter verwendet. Es ist enthalten, um das richtige Eingabeformat für jeden Parameter anzuzeigen.

Das 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'
}
New-PSSessionConfigurationFile @configSettings
Get-Content SampleFile.pssc

@{

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

# ID used to uniquely identify this session configuration
GUID = 'f7039ffa-7e54-4382-b358-a393c75c30d3'

# Specifies the execution policy for this session configuration
ExecutionPolicy = 'AllSigned'

# Specifies the language mode for this session configuration
LanguageMode = 'FullLanguage'

# Initial state of this session configuration
SessionType = 'Default'

# Environment variables defined in this session configuration
EnvironmentVariables = @{
    TESTSHARE='\\Test2\Test'
}

# Author of this session configuration
Author = 'User01'

# Company associated with this session configuration
CompanyName = 'Fabrikam Corporation'

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

# Description of the functionality provided by this session configuration
Description = 'This is a sample file.'

# Version of the PowerShell engine used by this session configuration
PowerShellVersion = '3.0'

# Modules that will be imported
ModulesToImport = @{
    ModuleVersion='1.0.0.0'
    ModuleName='PSScheduledJob'
    GUID='50cdb55f-5ab7-489f-9e94-4ec21ff51e59'
}, 'PSDiagnostics'

# Assemblies that will be loaded in this session configuration
AssembliesToLoad = 'System.Web.Services', 'FSharp.Compiler.CodeDom.dll'

# Aliases visible in this session configuration
VisibleAliases = 'c*', 'g*', 'i*', 's*'

# Cmdlets visible in this session configuration
VisibleCmdlets = 'Get*'

# Functions visible in this session configuration
VisibleFunctions = 'Get*'

# Providers visible in this session configuration
VisibleProviders = 'FileSystem', 'Function', 'Variable'

# Aliases defined in this session configuration
AliasDefinitions = @(
@{
    Description='Gets help.'
    Name='hlp'
    Options='AllScope'
    Value='Get-Help'
},
@{
    Description='Updates help'
    Name='Update'
    Options='ReadOnly'
    Value='Update-Help'
}
)

# Functions defined in this session configuration
FunctionDefinitions = @(
@{
    Name='Get-Function'
    Options='ReadOnly'
    ScriptBlock={Get-Command -CommandType Function}
}
)

# Variables defined in this session configuration
VariableDefinitions = @(
@{
    Value='SilentlyContinue'
    Name='WarningPreference'

# Type files (.ps1xml) that will be loaded in this session configuration
TypesToProcess = 'C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\Types1.ps1xml', 'C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\Types2.ps1xml'

# Format files (.ps1xml) that will be loaded in this session configuration
FormatsToProcess = 'C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\CustomFormats.ps1xml'

# Specifies the scripts to execute after the session is configured
ScriptsToProcess = 'C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\Get-Inputs.ps1'
}

In diesem Beispiel wird der Befehl New-PSSessionConfigurationFile angezeigt, der alle Cmdlet-Parameter verwendet. Es ist enthalten, um das richtige Eingabeformat für jeden Parameter anzuzeigen.

Das resultierende SampleFile.pssc wird in der Ausgabe angezeigt.

Dieses Cmdlet unterstützt die allgemeinen Parameter -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction und -WarningVariable. Weitere Informationen findest du unter about_CommonParameters.

Sie können keine Objekte über die Pipeline an dieses Cmdlet übergeben.

Dieses Cmdlet generiert keine Ausgabe.

• Parameter wie VisibleCmdlets und VisibleProvidersimportieren keine Elemente in die Sitzung. Stattdessen wählen sie aus den in die Sitzung importierten Elementen aus. Wenn beispielsweise der Wert des VisibleProviders Parameter der Zertifikatanbieter ist, aber der parameter ModulesToImport parameter nicht das Microsoft.PowerShell.Security Modul mit dem Zertifikatanbieter angibt, 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 Verzeichnis des $PSHOME Verzeichnisses.

  Die ConfigFilePath- Eigenschaft der Sitzungskonfiguration enthält den vollqualifizierten Pfad der aktiven Sitzungskonfigurationsdatei. Sie können die aktive Konfigurationsdatei im verzeichnis $PSHOME jederzeit mithilfe eines beliebigen Text-Editors ändern. Die Änderungen, die Sie vornehmen, wirken sich auf alle neuen Sitzungen aus, die die Sitzungskonfiguration verwenden, jedoch nicht auf vorhandene Sitzungen.

  Bevor Sie eine bearbeitete Sitzungskonfigurationsdatei verwenden, verwenden Sie das Cmdlet Test-PSSessionConfigurationFile, um zu überprüfen, ob die Konfigurationsdateieinträge gültig sind.