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
、セッション構成ファイルを通じて公開できる一連のユーザー機能を定義するファイルを作成します。 これには、ユーザーが使用できるコマンドレット、関数、スクリプトの決定が含まれます。 機能ファイルは、セッション構成のプロパティと値のハッシュ テーブルを含む、人間が判読できるテキスト ファイルです。 ファイルには .psrc ファイル名拡張子があり、複数のセッション構成で使用できます。
のすべてのパラメーター New-PSRoleCapabilityFile
は、ファイルのファイル パスを指定する Path パラメーターを除き、省略可能です。 コマンドレットの実行時にパラメーターを含めなかった場合、パラメーターの説明に記載されている場合を除き、セッション構成ファイル内の対応するキーはコメントアウトされます。 たとえば、 AssembliesToLoad パラメーターを含まない場合、セッション構成ファイルのそのセクションはコメント アウトされます。
セッション構成でロール機能ファイルを使用するには、まず、有効な PowerShell モジュール フォルダーの RoleCapabilities サブフォルダーにファイルを配置します。 次に、PowerShell セッション構成 (.pssc) ファイルの RoleDefinitions フィールドの名前でファイルを参照します。
このコマンドレットは、Windows PowerShell 5.0 で導入されました。
例
例 1: 空のロール機能ファイルをCreateする
この例では、既定の (空白の) 値を使用する新しいロール機能ファイルを作成します。 ファイルは後でテキスト エディターで編集して、これらの構成設定を変更できます。
New-PSRoleCapabilityFile -Path ".\ExampleFile.psrc"
例 2: ユーザーがサービスと VDI コンピューターを再起動できるようにする役割機能ファイルをCreateする
この例では、ユーザーが特定の名前パターンに一致するサービスとコンピューターを再起動できるようにするサンプルロール機能ファイルを作成します。 名前のフィルター処理は、 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
ロール機能ファイルを作成した会社を識別します。 既定値は Unknown です。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Copyright
ロール機能ファイルの著作権を指定します。 このパラメーターを省略すると、 New-PSRoleCapabilityFile
Author パラメーターの値を使用して copyright ステートメントが生成されます。
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
ロール機能ファイルを使用するセッションに自動的にインポートされるモジュールを指定します。 既定では、一覧表示されているモジュール内のすべてのコマンドが表示されます。 VisibleCmdlets または 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 はコマンドレットとそのエイリアスをipmo
セッションから削除Import-Module
します。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | True |
-VisibleCmdlets
セッションのコマンドレットを、このパラメーターの値に指定されたコマンドレットに制限します。 ワイルドカード文字とモジュール修飾名がサポートされています。
既定では、セッション エクスポート内のモジュールがセッションに表示されるすべてのコマンドレットが表示されます。 SessionType および ModulesToImport パラメーターを使用して、どのモジュールとスナップインをセッションにインポートするかを決定します。 ModulesToImport にコマンドレットを公開するモジュールがない場合は、New-PSRoleCapabilityFile
適切なモジュールの読み込みを試みます。
セッション構成ファイルに Visible パラメーターが含まれている場合、PowerShell はコマンドレットとそのエイリアスをipmo
セッションから削除Import-Module
します。
Type: | Object[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | True |
-VisibleExternalCommands
セッションで実行できる外部バイナリ、スクリプト、およびコマンドを、このパラメーターの値で指定されたものに制限します。
既定では、このセッションでは外部コマンドは表示されません。
セッション構成ファイルに Visible パラメーターが含まれている場合、PowerShell はコマンドレットとそのエイリアスをipmo
セッションから削除Import-Module
します。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-VisibleFunctions
セッション内の関数を、このパラメーターの値で指定された関数と、 FunctionDefinitions パラメーターで定義した関数に制限します。 ワイルドカード文字がサポートされています。
既定では、セッション内のモジュールによってエクスポートされたすべての関数がそのセッションに表示されます。 SessionType パラメーターと ModulesToImport パラメーターを使用して、セッションにインポートされるモジュールを決定します。
セッション構成ファイルに Visible パラメーターが含まれている場合、PowerShell はコマンドレットとそのエイリアスをipmo
セッションから削除Import-Module
します。
Type: | Object[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | True |
-VisibleProviders
セッション内の PowerShell プロバイダーを、このパラメーターの値で指定されたプロバイダーに制限します。 ワイルドカード文字がサポートされています。
既定では、セッション内のモジュールによってエクスポートされたすべてのプロバイダーがセッションに表示されます。 SessionType パラメーターと ModulesToImport パラメーターを使用して、セッションにインポートされるモジュールを決定します。
セッション構成ファイルに Visible パラメーターが含まれている場合、PowerShell はコマンドレットとそのエイリアスをipmo
セッションから削除Import-Module
します。
Type: | String[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | True |