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>]

Description

Cmdleten New-PSSessionConfigurationFile skapar en fil med inställningar som definierar en sessionskonfiguration och miljön för sessioner som skapas med hjälp av sessionskonfigurationen. Om du vill använda filen i en sessionskonfiguration använder du parametern Register-PSSessionConfiguration Path för cmdletarna eller Set-PSSessionConfiguration .

Sessionskonfigurationsfilen som New-PSSessionConfigurationFile skapar är en textfil som kan läsas av människor och som innehåller en hash-tabell med egenskaperna och värdena för sessionskonfigurationen. Filen har filnamnstillägget .pssc .

Alla parametrar i New-PSSessionConfigurationFile är valfria, förutom parametern Path . Om du utelämnar en parameter kommenteras motsvarande nyckel i sessionskonfigurationsfilen ut, förutom där anges i parameterbeskrivningen.

En sessionskonfiguration, även kallad en slutpunkt, är en samling inställningar på den lokala datorn som definierar miljön för PowerShell-sessioner (PSSessioner) som ansluter till datorn. Alla PSSessioner använder en sessionskonfiguration. Om du vill ange en viss sessionskonfiguration använder du parametern ConfigurationName för cmdletar som skapar en session, till exempel cmdleten New-PSSession .

En sessionskonfigurationsfil gör det enkelt att definiera en sessionskonfiguration utan komplexa skript eller kodsammansättningar. Inställningarna i filen används med det valfria startskriptet och eventuella sammansättningar i sessionskonfigurationen.

Mer information om sessionskonfigurationer och sessionskonfigurationsfiler finns i about_Session_Configurations och about_Session_Configuration_Files.

Den här cmdleten introducerades i PowerShell 3.0. Från och med PowerShell 6.0 var den här cmdleten endast tillgänglig på Windows-plattformen. PowerShell 7.3 gjorde den här cmdleten tillgänglig på alla plattformar som stöds.

Exempel

Exempel 1: Skapa och använda en NoLanguage-session

Det här exemplet visar hur du skapar och effekterna av att använda en session utan språk.

Stegen är följande:

1. Skapa en ny konfigurationsfil.
2. Registrera konfigurationen.
3. Skapa en ny session som använder konfigurationen.
4. Kör kommandon i den nya sessionen.

Om du vill köra kommandona i det här exemplet startar du PowerShell med alternativet Kör som administratör. Det här alternativet krävs för att köra cmdleten Register-PSSessionConfiguration .

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

I det här exemplet Invoke-Command misslyckas eftersom LanguageMode är inställt på NoLanguage.

Exempel 2: Skapa och använda en RestrictedLanguage-session

Det här exemplet visar hur du skapar och effekterna av att använda en session utan språk.

Stegen är följande:

1. Skapa en ny konfigurationsfil.
2. Registrera konfigurationen.
3. Skapa en ny session som använder konfigurationen.
4. Kör kommandon i den nya sessionen.

Om du vill köra kommandona i det här exemplet startar du PowerShell med alternativet Kör som administratör. Det här alternativet krävs för att köra cmdleten Register-PSSessionConfiguration .

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

I det här exemplet Invoke-Command lyckas eftersom LanguageMode är inställt på RestrictedLanguage.

Exempel 3: Ändra en sessionskonfigurationsfil

Det här exemplet visar hur du ändrar sessionskonfigurationsfilen som används i en befintlig session med namnet "ITTasks". Tidigare hade dessa sessioner bara kärnmodulerna och en intern ITTasks-modul . Administratören vill lägga till MODULen PSScheduledJob i sessioner som skapats med hjälp av ITTasks-sessionskonfigurationen.

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

Cmdleten New-PSSessionConfigurationFile för att skapa en sessionskonfigurationsfil som importerar de moduler som krävs. Cmdleten Set-PSSessionConfiguration ersätter den aktuella konfigurationsfilen med den nya. Den här nya konfigurationen påverkar bara nya sessioner som skapats efter ändringen. Befintliga ITTasks-sessioner påverkas inte.

Exempel 4: Redigera en sessionskonfigurationsfil

Det här exemplet visar hur du ändrar en sessionskonfiguration genom att redigera den aktiva sessionskonfigurationskopian av konfigurationsfilen. Om du vill ändra sessionskonfigurationskopian av konfigurationsfilen måste du ha fullständig åtkomst till filen. Detta kan kräva att du ändrar behörigheterna för filen.

I det här scenariot vill vi lägga till ett nytt alias för cmdleten Select-String genom att redigera den aktiva konfigurationsfilen.

Exempelkoden nedan utför följande steg för att göra den här ändringen:

1. Hämta konfigurationsfilens sökväg för ITConfig-sessionen.
2. Användaren redigerar konfigurationsfilen med hjälp av Notepad.exe för att ändra värdet AliasDefinitions enligt följande: AliasDefinitions = @(@{Name='slst';Value='Select-String'}) .
3. Testa den uppdaterade konfigurationsfilen.

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

True

Använd den utförliga parametern med Test-PSSessionConfigurationFile för att visa eventuella fel som identifieras. Cmdleten returnerar $True om inga fel identifieras i filen.

Exempel 5: Skapa en exempelkonfigurationsfil

Det här exemplet visar ett New-PSSessionConfigurationFile kommando som använder alla cmdlet-parametrar. Det ingår för att visa rätt indataformat för varje parameter.

Den resulterande SampleFile.pssc visas i utdata.

$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'

}

Parametrar

-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

Indata

None

Du kan inte skicka objekt till den här cmdleten.

Utdata

None

Den här cmdleten returnerar inga utdata.

Kommentarer

• Parametrar, till exempel VisibleCmdlets och VisibleProviders, importerar inte objekt till sessionen. I stället väljer de bland de objekt som importeras till sessionen. Om till exempel värdet för parametern VisibleProviders är certifikatprovidern, men parametern ModulesToImport inte anger modulen Microsoft.PowerShell.Security som innehåller certifikatprovidern, visas inte certifikatprovidern i sessionen.

• New-PSSessionConfigurationFile skapar en sessionskonfigurationsfil som har filnamnstillägget .pssc i sökvägen som du anger i parametern Sökväg . När du använder sessionskonfigurationsfilen för att skapa en sessionskonfiguration Register-PSSessionConfiguration kopierar cmdleten konfigurationsfilen och sparar en aktiv kopia av filen i underkatalogen SessionConfig i $PSHOME katalogen.

  Egenskapen ConfigFilePath för sessionskonfigurationen innehåller den fullständigt kvalificerade sökvägen för den aktiva sessionskonfigurationsfilen. Du kan när som helst ändra den aktiva konfigurationsfilen $PSHOME i katalogen med valfri textredigerare. De ändringar som du gör påverkar alla nya sessioner som använder sessionskonfigurationen, men inte befintliga sessioner.

  Innan du använder en redigerad sessionskonfigurationsfil använder du cmdleten Test-PSSessionConfigurationFile för att kontrollera att konfigurationsfilposterna är giltiga.

Relaterade länkar

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