New-PSRoleCapabilityFile

  • 参考
模块:
Microsoft.PowerShell.Core

创建一个文件，用于定义一组要通过会话配置公开的功能。

语法

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：创建空白角色功能文件

此示例将创建一个使用默认（空白）值的新角色功能文件。 稍后可以在文本编辑器中编辑该文件以更改这些配置设置。

New-PSRoleCapabilityFile -Path ".\ExampleFile.psrc"

示例 2：创建角色功能文件，允许用户重启服务和任何 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

将指定的别名添加到使用角色功能文件的会话。 输入一个包含以下键的哈希表：

  • 名称. 别名的名称。 此键是必需的。
  • 值。 别名所表示的命令。 此键是必需的。
  • 描述。 描述别名的文本字符串。 此键是可选的。
  • 选项。 别名选项。 此键是可选的。 默认值为无。 此参数的可接受值为：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

标识创建角色功能文件的公司。 默认值为 Unknown。

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

指定要添加到使用角色功能文件的会话的变量。 输入一个包含以下键的哈希表：

  • 名称. 变量的名称。 此键是必需的。
  • 值。 变量值。 此键是必需的。

例如：@{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

将会话中的函数限制为在此参数的值中指定的函数以及在 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