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>] 说明
cmdlet New-PSRoleCapabilityFile 创建一个文件，该文件定义一组可通过会话配置文件公开的用户功能。 这包括确定哪些 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。 变量值。 此键是必需的。
- 选项。 变量选项。 此键是可选的。 默认值为 None。 此参数的可接受值为：None、ReadOnly、Constant、Private 或 AllScope。
例如： @{Name="WarningPreference";Value="SilentlyContinue";Options="AllScope"}
| 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 |