New-PSRoleCapabilityFile

  • 參考
模組:
Microsoft.PowerShell.Core

建立檔案，定義要透過會話組態公開的一組功能。

Syntax

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

Description

Cmdlet New-PSRoleCapabilityFile 會建立一個檔案，定義可透過會話組態檔公開的一組使用者功能。 這包括判斷哪些 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。 此參數可接受的值為：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

將會話中的函式限制為此參數值中指定的函式，以及您在 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