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>] 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"}
| 類型: | IDictionary[] |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-AssembliesToLoad
指定要載入至使用角色功能檔案之會話的元件。
| 類型: | String[] |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-Author
指定建立角色功能檔案的使用者。
| 類型: | String |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-CompanyName
識別建立角色功能檔案的公司。 預設值為 Unknown。
| 類型: | String |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-Copyright
指定角色功能檔案的著作權。 如果您省略此參數，New-PSRoleCapabilityFile請使用 Author 參數的值來產生著作權聲明。
| 類型: | String |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-Description
指定角色功能檔案的描述。
| 類型: | String |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-EnvironmentVariables
指定公開此角色功能檔案之會話的環境變數。 輸入哈希表，其中索引鍵是環境變數名稱，而值是環境變數值。
例如：EnvironmentVariables=@{TestShare="\\\\Server01\TestShare"}
| 類型: | IDictionary |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-FormatsToProcess
指定在使用角色功能檔案之會話中執行的格式化檔案 （.ps1xml）。
此參數的值必須是格式化檔案的完整或絕對路徑。
| 類型: | String[] |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-FunctionDefinitions
將指定的函式新增至公開角色功能的會話。 輸入具有下列索引鍵的哈希表：
- 名稱. 函式的名稱。 需要此金鑰。
- ScriptBlock。 函式主體。 輸入腳本區塊。 需要此金鑰。
- 選項。 函式選項。 此金鑰是選擇性的。 預設值是 None。 此參數可接受的值為：None、ReadOnly、Constant、Private 或 AllScope。
例如：
@{Name="Get-PowerShellProcess";ScriptBlock={Get-Process PowerShell};Options="AllScope"}
| 類型: | IDictionary[] |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-Guid
指定角色功能檔案的唯一標識碼。 如果您省略此參數， New-PSRoleCapabilityFile 則會產生檔案的 GUID。 若要在 PowerShell 中建立新的 GUID，請輸入 [guid]::NewGuid()。
| 類型: | Guid |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-ModulesToImport
指定自動匯入至使用角色功能檔案之會話的模組。 根據預設，列出模組中的所有命令都會顯示。 與 VisibleCmdlet 或 VisibleFunctions 搭配使用時，可以從指定的模組中看到的命令可以受到限制。
此參數值中使用的每個模組都可以以字串或哈希表來表示。 模組字串只包含模組的名稱。 模組哈希表可以包含 ModuleName、 ModuleVersion和 GUID 金鑰。 只需要 ModuleName 金鑰。
例如，下列值是由字串和哈希表所組成。 字串和哈希表的任何組合，依任何順序都是有效的。
"TroubleshootingPack", @{ModuleName="PSDiagnostics"; ModuleVersion="1.0.0.0";GUID="c61d6278-02a3-4618-ae37-a524d40a7f44"}
| 類型: | Object[] |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-Path
指定角色功能檔案的路徑和檔名。 檔案必須具有 .psrc 擴展名。
| 類型: | String |
| Position: | 0 |
| 預設值: | None |
| 必要: | True |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-ScriptsToProcess
指定要新增至使用角色功能檔案之會話的腳本。 輸入文稿的路徑和檔名。 此參數的值必須是腳本檔名的完整或絕對路徑。
| 類型: | String[] |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-TypesToProcess
指定類型檔案 （.ps1xml） 以新增至使用角色功能檔案的會話。 輸入類型檔名。 此參數的值必須是類型檔名的完整或絕對路徑。
| 類型: | String[] |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-VariableDefinitions
指定要新增至使用角色功能檔案之會話的變數。 輸入具有下列索引鍵的哈希表：
- 名稱. 變數的名稱。 需要此金鑰。
- 值。 變數值。 需要此金鑰。
例如：@{Name="WarningPreference";Value="SilentlyContinue"}
| 類型: | Object |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-VisibleAliases
將會話中的別名限制為此參數值中指定的別名，以及您在 AliasDefinition 參數中定義的任何別名。 支援使用萬用字元。 根據預設，PowerShell 引擎所定義的所有別名，以及模組匯出的所有別名都會顯示在會話中。
例如，若要將可用的別名限制為 gm 和 gcm，請使用下列語法： VisibleAliases="gcm", "gp"
當角色功能檔案中包含任何 Visible 參數時，PowerShell 會從會話中移除 Import-Module Cmdlet 及其 ipmo 別名。
| 類型: | String[] |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | True |
-VisibleCmdlets
將會話中的 Cmdlet 限制為此參數值中指定的 Cmdlet。 支援通配符和模組限定名稱。
根據預設，會話匯出模組的所有 Cmdlet 都會顯示在會話中。 使用 SessionType 和 ModulesToImport 參數來判斷哪些模組和嵌入式管理單元會匯入會話。 如果 ModulesToImport 中沒有模塊公開 Cmdlet，New-PSRoleCapabilityFile則嘗試載入適當的模組。
當會話組態檔中包含任何 Visible 參數時，PowerShell 會從會話中移除 Import-Module Cmdlet 及其 ipmo 別名。
| 類型: | Object[] |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | True |
-VisibleExternalCommands
將會話中可執行的外部二進位檔、腳本和命令限制為此參數值中指定的專案。
根據預設，此會話中不會顯示任何外部命令。
當會話組態檔中包含任何 Visible 參數時，PowerShell 會從會話中移除 Import-Module Cmdlet 及其 ipmo 別名。
| 類型: | String[] |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-VisibleFunctions
將會話中的函式限制為此參數值中指定的函式，以及您在 FunctionDefinitions 參數中 定義的任何函 式。 支援使用萬用字元。
根據預設，會話中模組匯出的所有函式都會在該會話中顯示。 使用 SessionType 和 ModulesToImport 參數來判斷哪些模組會匯入會話。
當會話組態檔中包含任何 Visible 參數時，PowerShell 會從會話中移除 Import-Module Cmdlet 及其 ipmo 別名。
| 類型: | Object[] |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | True |
-VisibleProviders
將會話中的PowerShell提供者限制為此參數值中指定的提供者。 支援使用萬用字元。
根據預設，會話中模組匯出的所有提供者都會顯示在會話中。 使用 SessionType 和 ModulesToImport 參數來判斷哪些模組會匯入會話。
當會話組態檔中包含任何 Visible 參數時，PowerShell 會從會話中移除 Import-Module Cmdlet 及其 ipmo 別名。
| 類型: | String[] |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | True |
