New-PSRoleCapabilityFile
创建一个文件,用于定义要通过会话配置公开的一组功能。
语法
New-PSRoleCapabilityFile
[-Path] <String>
[-Guid <Guid>]
[-Author <String>]
[-Description <String>]
[-CompanyName <String>]
[-Copyright <String>]
[-ModulesToImport <Object[]>]
[-VisibleAliases <String[]>]
[-VisibleCmdlets <Object[]>]
[-VisibleFunctions <Object[]>]
[-VisibleExternalCommands <String[]>]
[-VisibleProviders <String[]>]
[-ScriptsToProcess <String[]>]
[-AliasDefinitions <IDictionary[]>]
[-FunctionDefinitions <IDictionary[]>]
[-VariableDefinitions <Object>]
[-EnvironmentVariables <IDictionary>]
[-TypesToProcess <String[]>]
[-FormatsToProcess <String[]>]
[-AssembliesToLoad <String[]>]
[<CommonParameters>]
说明
该 New-PSRoleCapabilityFile
cmdlet 创建一个文件,该文件定义一组用户功能,这些功能可通过会话配置文件公开。 这包括确定哪些 cmdlet、函数和脚本可供用户使用。 功能文件是一个可读文本文件,其中包含会话配置属性和值的哈希表。 该文件具有 .psrc 文件扩展名,可供多个会话配置使用。
的所有参数 New-PSRoleCapabilityFile
都是可选的, Path 参数除外,该参数指定文件的路径。 如果在运行 cmdlet 时未包含参数,则会话配置文件中的相应密钥将被注释掉,参数说明中另有说明的情况除外。 例如,如果未包含 AssembliesToLoad 参数,则会注释掉会话配置文件的该部分。
若要在会话配置中使用角色功能文件,请先将该文件放在有效 PowerShell 模块文件夹的 RoleCapabilities 子文件夹中。 然后在 PowerShell 会话配置 (.pssc) 文件中的 RoleDefinitions 字段中按名称引用文件。
此 cmdlet 是在 Windows PowerShell 5.0 中引入的。
示例
示例 1:Create空白角色功能文件
此示例创建一个新的角色功能文件,该文件使用默认 (空白) 值。 稍后可以在文本编辑器中编辑该文件,以更改这些配置设置。
New-PSRoleCapabilityFile -Path ".\ExampleFile.psrc"
示例 2:Create允许用户重启服务和任何 VDI 计算机的角色功能文件
此示例创建一个示例角色功能文件,使用户能够重启与特定名称模式匹配的服务和计算机。 通过将 ValidatePattern 参数设置为正则表达式 VDI\d+
来定义名称筛选。
$roleParameters = @{
Path = ".\Maintenance.psrc"
Author = "User01"
CompanyName = "Fabrikam Corporation"
Description = "This role enables users to restart any service and restart any VDI computer."
ModulesToImport = "Microsoft.PowerShell.Core"
VisibleCmdlets = "Restart-Service", @{
Name = "Restart-Computer"
Parameters = @{ Name = "ComputerName"; ValidatePattern = "VDI\d+" }
}
}
New-PSRoleCapabilityFile @roleParameters
参数
-AliasDefinitions
将指定的别名添加到使用角色功能文件的会话。 输入一个包含以下键的哈希表:
- 名称: 别名的名称。 此键是必需的。
- Value。 别名所表示的命令。 此键是必需的。
- 说明。 描述别名的文本字符串。 此键是可选的。
- 选项。 别名选项。 此键是可选的。 默认值为 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: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Copyright
指定角色功能文件的版权。 如果省略此参数, New-PSRoleCapabilityFile
则使用 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 |
-FormatsToProcess
指定在使用角色功能文件的 .ps1xml
会话中运行的 () 格式化文件。
此参数的值必须是格式化文件的完整路径或绝对路径。
Type: | String[] |
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 |
-Guid
指定角色功能文件的唯一标识符。 如果省略此参数, New-PSRoleCapabilityFile
则会为文件生成 GUID。 若要在 PowerShell 中创建新的 GUID,请键入 [guid]::NewGuid()
。
Type: | Guid |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ModulesToImport
指定自动导入到使用角色功能文件的会话中的模块。 默认情况下,列出的模块中的所有命令都是可见的。 与 VisibleCmdlet 或 VisibleFunctions 一起使用时,可以限制指定模块中可见的命令。
此参数的值中使用的每个模块都可以由字符串或哈希表表示。 模块字符串仅包含模块的名称。 模块哈希表可以包含 ModuleName、 ModuleVersion 和 GUID 密钥。 仅 ModuleName 键是必需的。
例如,下面的值由字符串和哈希表组成。 字符串和哈希表的任何组合(采用任何顺序)都是有效的。
"TroubleshootingPack", @{ModuleName="PSDiagnostics"; ModuleVersion="1.0.0.0";GUID="c61d6278-02a3-4618-ae37-a524d40a7f44"}
Type: | Object[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Path
指定角色功能文件的路径和文件名。 文件必须具有 .psrc
文件扩展名。
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
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 |
-TypesToProcess
指定要添加到使用角色功能文件的会话 (.ps1xml
) 的类型文件。 输入类型文件名。 此参数的值必须是文件名类型的完整路径或绝对路径。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-VariableDefinitions
指定要添加到使用角色功能文件的会话的变量。 输入一个包含以下键的哈希表:
- 名称: 变量的名称。 此键是必需的。
- Value。 变量值。 此键是必需的。
例如: @{Name="WarningPreference";Value="SilentlyContinue"}
Type: | Object |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-VisibleAliases
将会话中的别名限制为此参数的值中指定的别名,以及在 AliasDefinition 参数中定义的任何别名。 支持使用通配符。 默认情况下,由 PowerShell 引擎定义的所有别名以及模块导出的所有别名在会话中可见。
例如,若要将可用别名限制为 gm 和 gcm,请使用以下语法: 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, New-PSRoleCapabilityFile
则尝试加载相应的模块。
当会话配置文件中包含任何 Visible 参数时,PowerShell 会 Import-Module
从会话中删除 cmdlet 及其 ipmo
别名。
Type: | Object[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | True |
-VisibleExternalCommands
可在会话中执行的外部二进制文件、脚本和命令限制为此参数的值中指定的二进制文件、脚本和命令。
默认情况下,此会话中不显示任何外部命令。
当会话配置文件中包含任何 Visible 参数时,PowerShell 会 Import-Module
从会话中删除 cmdlet 及其 ipmo
别名。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-VisibleFunctions
将会话中的函数限制为此参数的值中指定的函数,以及你在 FunctionDefinitions 参数中定义的任何函数。 支持使用通配符。
默认情况下,会话中的模块导出的所有函数在该会话中可见。 使用 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 |