New-PSSessionConfigurationFile
创建用于定义会话配置的文件。
语法
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>]
说明
cmdlet New-PSSessionConfigurationFile
创建一个设置文件,用于定义会话配置和使用会话配置创建的会话环境。
若要在会话配置中使用 文件,请使用 或 Set-PSSessionConfiguration
cmdlet 的 Register-PSSessionConfiguration
Path 参数。
创建的会话配置文件 New-PSSessionConfigurationFile
是用户可读的文本文件,其中包含会话配置属性和值的哈希表。 该文件具有 .pssc
文件扩展名。
的所有参数 New-PSSessionConfigurationFile
都是可选的, Path 参数除外。
如果省略一个参数,则将注释掉会话配置文件中的相应键,已在参数说明中注明的除外。
会话配置(也称为终结点)是本地计算机上的设置集合,这些设置定义连接到计算机的 PowerShell 会话 (PSSessions) 的环境。 所有 PSSession 都 使用会话配置。 若要指定特定的会话配置,请使用创建会话的 cmdlet 的 ConfigurationName 参数,例如 New-PSSession
cmdlet。
session configuration file 可以轻松地定义会话配置,无需复杂的脚本或代码程序集。 文件中的设置与可选的启动脚本和会话配置中的任何程序集一起使用。
有关会话配置和会话配置文件的详细信息,请参阅 about_Session_Configurations 和 about_Session_Configuration_Files。
此 cmdlet 是在 PowerShell 3.0 中引入的。 从 PowerShell 6.0 开始,此 cmdlet 仅在 Windows 平台上可用。 PowerShell 7.3 使此 cmdlet 在所有受支持的平台上可用。
示例
示例 1:创建和使用 NoLanguage 会话
此示例演示如何创建和使用无语言会话的效果。
步骤包括:
- Create新的配置文件。
- 注册配置。
- Create使用 配置的新会话。
- 在该新会话中运行命令。
若要运行此示例中的命令,请使用“以管理员身份运行”选项启动 PowerShell。 运行 cmdlet 需要 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
在此示例中, Invoke-Command
失败,因为 LanguageMode 设置为 NoLanguage。
示例 2:创建和使用 RestrictedLanguage 会话
此示例演示如何创建和使用无语言会话的效果。
步骤包括:
- Create新的配置文件。
- 注册配置。
- Create使用 配置的新会话。
- 在该新会话中运行命令。
若要运行此示例中的命令,请使用“以管理员身份运行”选项启动 PowerShell。 运行 cmdlet 需要 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
在此示例中, 成功, Invoke-Command
因为 LanguageMode 设置为 RestrictedLanguage。
示例 3:更改会话配置文件
此示例演示如何更改名为“ITTasks”的现有会话中使用的会话配置文件。 以前,这些会话只有核心模块和内部 ITTasks 模块。 管理员希望将 PSScheduledJob 模块添加到使用 ITTasks 会话配置创建的会话中。
New-PSSessionConfigurationFile -Path .\New-ITTasks.pssc -ModulesToImport Microsoft*, ITTasks, PSScheduledJob
Set-PSSessionConfiguration -Name ITTasks -Path .\New-ITTasks.pssc
用于 New-PSSessionConfigurationFile
创建导入所需模块的会话配置文件的 cmdlet。 cmdlet Set-PSSessionConfiguration
将当前配置文件替换为新配置文件。 此新配置仅影响更改后创建的新会话。
现有的“ITTasks”会话不受影响。
示例 4:编辑会话配置文件
此示例显示了如何通过编辑配置文件的主动会话配置副本来更改会话配置。 若要修改配置文件的会话配置副本,必须对文件具有完全控制访问权限。 这可能需要更改文件的权限。
在此方案中,我们希望通过编辑活动配置文件来 Select-String
为 cmdlet 添加新别名。
下面的示例代码执行以下步骤进行此更改:
- 获取 ITConfig 会话的配置文件路径。
- 用户使用 Notepad.exe 编辑配置文件以更改 AliasDefinitions 值,如下所示:
AliasDefinitions = @(@{Name='slst';Value='Select-String'})
。 - 测试更新的配置文件。
$ITConfig = Get-PSSessionConfiguration -Name ITConfig
notepad.exe $ITConfig.ConfigFilePath
Test-PSSessionConfigurationFile -Path $ITConfig.ConfigFilePath
True
将 Verbose 参数与 一起使用 Test-PSSessionConfigurationFile
可显示检测到的任何错误。 如果未在文件中检测到错误,则 cmdlet 返回 $True
。
示例 5:Create示例配置文件
此示例演示使用 New-PSSessionConfigurationFile
所有 cmdlet 参数的命令。
包含此示例以显示每个参数对应的正确输入格式。
生成的 SampleFile.pssc 将显示在输出中。
$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'
}
参数
-AliasDefinitions
将指定的别名添加到使用该会话配置的会话中。 输入一个包含以下键的哈希表:
- 名称 - 别名的名称。 此键是必需的。
- 值 - 别名表示的命令。 此键是必需的。
- 说明 - 描述别名的文本字符串。 此键是可选的。
- 选项 - 别名选项。 此键是可选的。 默认值为“None”。 此参数的可接受值为:None、ReadOnly、Constant、Private 或 AllScope。
例如: @{Name='hlp';Value='Get-Help';Description='Gets help';Options='ReadOnly'}
Type: | IDictionary[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-AssembliesToLoad
指定要加载到使用该会话配置的会话中的程序集。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Author
指定会话配置或配置文件的作者。 默认为当前用户。 此参数的值在会话配置文件中可见,但是它不是会话配置对象的属性。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CompanyName
指定创建会话配置或配置文件的公司。 默认值是“未知”。 此参数的值在会话配置文件中可见,但是它不是会话配置对象的属性。
Type: | String |
Position: | Named |
Default value: | Unknown |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Copyright
指定会话配置文件的版权。 此参数的值在会话配置文件中可见,但是它不是会话配置对象的属性。
如果省略此参数, New-PSSessionConfigurationFile
则使用 Author 参数的值生成版权声明。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Description
指定会话配置或会话配置文件的说明。 此参数的值在会话配置文件中可见,但是它不是会话配置对象的属性。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-EnvironmentVariables
将环境变量添加到会话中。 输入一个哈希表,其中的键是环境变量名称,而值是环境变量值。
例如: EnvironmentVariables=@{TestShare='\\Server01\TestShare'}
Type: | IDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ExecutionPolicy
指定使用该会话配置的会话的执行策略。 如果省略此参数,会话配置文件中 ExecutionPolicy 键的值为 Restricted。 有关 PowerShell 中的执行策略的信息,请参阅 about_Execution_Policies。
Type: | ExecutionPolicy |
Accepted values: | Unrestricted, RemoteSigned, AllSigned, Restricted, Default, Bypass, Undefined |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-FormatsToProcess
指定在使用该会话配置的会话中运行的格式设置文件 (.ps1xml)。 此参数的值必须是格式设置文件的完整路径或绝对路径。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Full
指示此操作包括会话配置文件中的所有可能的配置属性。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-FunctionDefinitions
将指定函数添加到使用该会话配置的会话中。 输入一个包含以下键的哈希表:
- 名称 - 函数的名称。 此键是必需的。
- ScriptBlock - 函数体。 输入一个脚本块。 此键是必需的。
- 选项 - 函数选项。 此键是可选的。 默认值为“None”。 此参数的可接受值为:None、ReadOnly、Constant、Private 或 AllScope。
例如: @{Name='Get-PowerShellProcess';ScriptBlock={Get-Process PowerShell};Options='AllScope'}
Type: | IDictionary[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-GroupManagedServiceAccount
使用此会话配置配置会话,以在指定的组托管服务帐户的上下文中运行。 注册此会话配置的计算机必须具有请求 gMSA 密码的权限,才能成功创建会话。 此字段不能与 RunAsVirtualAccount 参数一 起使用。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Guid
为会话配置文件指定唯一标识符。 如果省略此参数, New-PSSessionConfigurationFile
则会为文件生成 GUID。 若要在 PowerShell 中创建新的 GUID,请键入 New-Guid
。
Type: | Guid |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-LanguageMode
确定使用此会话配置的会话中允许 PowerShell 语言的哪些元素。 可以使用此参数来限制特定用户可以在计算机上运行的命令。
此参数的可接受值为:
- FullLanguage - 允许使用所有语言元素。
- ConstrainedLanguage - 不允许包含要评估的脚本的命令。 ConstrainedLanguage 模式限制用户对 Microsoft .NET Framework 类型、对象或方法的访问权限。
- NoLanguage - 用户可以运行 cmdlet 和函数,但不允许使用任何语言元素,例如脚本块、变量或运算符。
- RestrictedLanguage - 用户可以运行 cmdlet 和函数,但不允许使用脚本块或变量,但以下允许的变量除外:
$PSCulture
、$PSUICulture
、$True
、$False
和$Null
。 用户只能使用基本比较运算符 (-eq
、、-gt
-lt
) 。 不允许使用赋值语句、属性引用和方法调用。
LanguageMode 参数的默认值取决于 SessionType 参数的值。
- 空 - NoLanguage
- RestrictedRemoteServer - NoLanguage
- 默认值 - FullLanguage
Type: | PSLanguageMode |
Accepted values: | FullLanguage, RestrictedLanguage, NoLanguage, ConstrainedLanguage |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ModulesToImport
指定自动导入使用该会话配置的会话的模块和管理单元。
默认情况下,仅 将 Microsoft.PowerShell.Core 管理单元导入远程会话,但除非排除 cmdlet,否则用户可以使用 Import-Module
和 Add-PSSnapin
cmdlet 将模块和管理单元添加到会话。
此参数的值中的每个模块或管理单元都可以由字符串表示或以哈希表的形式表示。 模块字符串仅包含模块或管理单元的名称。 模块哈希表可以包含 ModuleName、 ModuleVersion 和 GUID 密钥。 仅 ModuleName 键是必需的。
例如,下面的值由字符串和哈希表组成。 字符串和哈希表的任何组合(采用任何顺序)都是有效的。
'TroubleshootingPack', @{ModuleName='PSDiagnostics'; ModuleVersion='1.0.0.0';GUID='c61d6278-02a3-4618-ae37-a524d40a7f44'}
cmdlet 的 ModulesToImport 参数 Register-PSSessionConfiguration
的值优先于会话配置文件中 ModulesToImport 键的值。
Type: | Object[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MountUserDrive
配置使用此会话配置公开 PSDrive 的 User:
会话。 用户驱动器对于每个连接用户都是唯一的,允许用户在 PowerShell 终结点之间复制数据,即使未公开文件系统提供程序也是如此。 用户驱动器根在 下 $env:LOCALAPPDATA\Microsoft\PowerShell\DriveRoots\
创建。 对于连接到终结点的每位用户,将创建一个具有 $env:USERDOMAIN\$env:USERNAME
名称的文件夹。 对于工作组中的计算机, 的 $env:USERDOMAIN
值为主机名。
用户驱动器中的内容在用户会话中保留,不会自动删除。 默认情况下,用户最多只能将 50MB 的数据存储在用户驱动器中。 这可以使用 UserDriveMaximumSize 参数进行自定义。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Path
指定会话配置文件的路径和文件名。 该文件必须具有 .pssc
文件扩展名。
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PowerShellVersion
指定使用会话配置的会话中 PowerShell 引擎的版本。 此参数的可接受值为:2.0 和 3.0。 如果省略此参数, PowerShellVersion 密钥将被注释掉,最新版本的 PowerShell 将在会话中运行。
cmdlet 的 PSVersion 参数 Register-PSSessionConfiguration
的值优先于会话配置文件中 PowerShellVersion 键的值。
Type: | Version |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-RequiredGroups
为连接到使用此会话配置的会话的用户指定条件访问规则。
输入哈希表以为每个哈希表仅使用 1 个键(“And”或“Or”)来撰写规则列表,并将该值设置为安全组名称数组或其他哈希表。
要求连接用户成为单个组的成员的示例: @{ And = 'MyRequiredGroup' }
要求用户属于组 A 或同时属于组 B 和 C 才能访问终结点的示例: @{ Or = 'GroupA', @{ And = 'GroupB', 'GroupC' } }
Type: | IDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-RoleDefinitions
指定安全组 (或用户) 和角色功能之间的映射。 在创建会话时,用户将被授予对应用于其组成员身份的所有角色功能的访问权限。
输入一个哈希表,其中键是安全组的名称,值是包含应提供给安全组的角色功能列表的哈希表。
例如: @{'Contoso\Level 2 Helpdesk Users' = @{ RoleCapabilities = 'Maintenance', 'ADHelpDesk' }}
Type: | IDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-RunAsVirtualAccount
使用此会话配置将会话配置为作为计算机的 (虚拟) 管理员帐户运行。 此字段不能与 GroupManagedServiceAccount 参数一 起使用。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-RunAsVirtualAccountGroups
指定在使用会话配置的会话作为虚拟帐户运行时要与虚拟帐户关联的安全组。 如果省略,则虚拟帐户属于域控制器上的域管理员和所有其他计算机上的管理员。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SchemaVersion
指定会话配置文件架构的版本。 默认值为“1.0.0.0”。
Type: | Version |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ScriptsToProcess
将指定脚本添加到使用该会话配置的会话中。 请输入脚本的路径和文件名。 此参数的值必须是脚本文件名的完整路径或绝对路径。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionType
指定通过使用该会话配置创建的会话的类型。 默认值为 Default。 此参数的可接受值为:
- 空 - 默认情况下,不会向会话添加任何模块。 使用此 cmdlet 的参数将模块、函数、脚本和其他功能添加到会话。 此选项旨在通过添加所选命令来创建自定义会话。 如果没有将命令添加到空会话中,则该会话将限于表达式,并且可能不可用。
- 默认值 - 将 Microsoft.PowerShell.Core 模块添加到会话。 除非显式禁止此 cmdlet,否则此模块包含
Import-Module
用户可用于导入其他模块的 cmdlet。 - RestrictedRemoteServer。 仅包含以下代理函数:
Exit-PSSession
、、Get-Command
、Get-FormatData
Get-Help
、Measure-Object
、Out-Default
和Select-Object
。 使用此 cmdlet 的参数将模块、函数、脚本和其他功能添加到会话。
Type: | SessionType |
Accepted values: | Empty, RestrictedRemoteServer, Default |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TranscriptDirectory
指定使用此会话配置为会话放置会话脚本的目录。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TypesToProcess
将指定的 .ps1xml
类型文件添加到使用会话配置的会话。 输入类型文件名。 此参数的值必须是类型文件名的完整路径或绝对路径。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UserDriveMaximumSize
指定使用此会话配置的会话中公开的用户驱动器的最大大小。
如果省略,则每个 User:
驱动器根目录的默认大小为 50MB。
此参数应与 MountUserDrive 一起使用。
Type: | Int64 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-VariableDefinitions
将指定变量添加到使用该会话配置的会话中。 输入一个包含以下键的哈希表:
- 名称 - 变量的名称。 此键是必需的。
- 值 - 变量值。 此键是必需的。
例如: @{Name='WarningPreference';Value='SilentlyContinue'}
Type: | Object |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-VisibleAliases
将会话中的别名限制为在此参数的值中指定的别名以及在 AliasDefinition 参数中定义的任何别名。 支持使用通配符。 默认情况下,由 PowerShell 引擎定义的所有别名以及模块导出的所有别名在会话中可见。
例如: VisibleAliases='gcm', 'gp'
当会话配置文件中包含任何 Visible 参数时,PowerShell 会 Import-Module
从会话中删除 cmdlet 及其 ipmo 别名。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | True |
-VisibleCmdlets
将会话中的 cmdlet 限制为在此参数的值中指定的 cmdlet。 支持通配符和模块限定名称。
默认情况下,会话中的模块导出的所有 cmdlet 都在该会话中可见。 使用 SessionType 和 ModulesToImport 参数来确定哪些模块和管理单元已导入到会话中。 如果 ModulesToImport 中没有模块公开 cmdlet,则将尝试自动加载相应的模块。
当会话配置文件中包含任何 Visible 参数时,PowerShell 会 Import-Module
从会话中删除 cmdlet 及其 ipmo 别名。
Type: | Object[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-VisibleExternalCommands
可在会话中执行的外部二进制文件、脚本和命令限制为此参数的值中指定的外部二进制文件、脚本和命令。 支持使用通配符。
默认情况下,会话中不显示任何外部命令。
当会话配置文件中包含任何 Visible 参数时,PowerShell 会 Import-Module
从会话中删除 cmdlet 及其 ipmo 别名。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | True |
-VisibleFunctions
将会话中的函数限制为在此参数的值中指定的函数以及在 FunctionDefinition 参数中定义的任何函数。 支持使用通配符。
默认情况下,会话中的模块导出的所有函数都在该会话中可见。 使用 SessionType 和 ModulesToImport 参数来确定哪些模块和管理单元已导入到会话中。
当会话配置文件中包含任何 Visible 参数时,PowerShell 会 Import-Module
从会话中删除 cmdlet 及其 ipmo 别名。
Type: | Object[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | True |
-VisibleProviders
将会话中的 PowerShell 提供程序限制为此参数的值中指定的提供程序。 支持使用通配符。
默认情况下,会话中的模块导出的所有提供程序都在该会话中可见。 使用 SessionType 和 ModulesToImport 参数确定哪些模块要导入到会话中。
当会话配置文件中包含任何 Visible 参数时,PowerShell 将从 Import-Module
会话中删除 cmdlet 及其 ipmo
别名。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | True |
输入
None
不能通过管道将对象传递给此 cmdlet。
输出
None
此 cmdlet 不返回任何输出。
备注
参数(如 VisibleCmdlets 和 VisibleProviders)不会将项导入会话。 而会从导入到会话中的项中进行选择。 例如,如果 VisibleProviders 参数的值为 Certificate 提供程序,但 ModulesToImport 参数未指定包含证书提供程序的 Microsoft.PowerShell.Security 模块,则证书提供程序在会话中不可见。
New-PSSessionConfigurationFile
在 Path 参数中指定的路径中创建具有 .pssc 文件扩展名的会话配置文件。 使用会话配置文件创建会话配置时,Register-PSSessionConfiguration
cmdlet 会复制配置文件,并将该文件的活动副本保存在目录的$PSHOME
SessionConfig 子目录中。会话配置的 ConfigFilePath 属性包含活动会话配置文件的完全限定路径。 可以随时使用任何文本编辑器修改目录中的活动配置文件
$PSHOME
。 所做的更改会影响使用该会话配置的所有新会话,但不会影响现有会话。在使用已编辑的会话配置文件之前,请使用
Test-PSSessionConfigurationFile
cmdlet 验证配置文件条目是否有效。