次の方法で共有


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 ファイル名拡張子があり、複数のセッション構成で使用できます。

ファイルのパスを指定する Path パラメーターを除き、New-PSRoleCapabilityFileのすべてのパラメーターは省略可能です。 コマンドレットの実行時にパラメーターを含めない場合、パラメーターの説明に記載されている場合を除き、セッション構成ファイル内の対応するキーはコメント アウトされます。 たとえば、 AssembliesToLoad パラメーターを含めない場合、セッション構成ファイルのそのセクションはコメント アウトされます。

セッション構成でロール機能ファイルを使用するには、まず、有効な PowerShell モジュール フォルダーの RoleCapabilities サブフォルダーにファイルを配置します。 次に、PowerShell セッション構成 (.pssc) ファイルの RoleDefinitions フィールドの名前でファイルを参照します。

このコマンドレットは、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[]
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-AssembliesToLoad

ロール機能ファイルを使用するセッションに読み込むアセンブリを指定します。

型:String[]
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Author

ロール機能ファイルを作成したユーザーを指定します。

型:String
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-CompanyName

ロール機能ファイルを作成した会社を識別します。 既定値は Unknown です。

型:String
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

ロール機能ファイルの著作権を指定します。 このパラメーターを省略すると、 New-PSRoleCapabilityFileAuthor パラメーターの値を使用して著作権ステートメントを生成します。

型:String
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Description

ロール機能ファイルの説明を指定します。

型:String
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-EnvironmentVariables

このロール機能ファイルを公開するセッションの環境変数を指定します。 キーが環境変数名で、値が環境変数値のハッシュ テーブルを入力します。

例: EnvironmentVariables=@{TestShare="\\\\Server01\TestShare"}

型:IDictionary
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-FormatsToProcess

ロール機能ファイルを使用するセッションで実行されるフォーマット ファイル (.ps1xml) を指定します。 このパラメーターの値は、書式設定ファイルの完全パスまたは絶対パスである必要があります。

型:String[]
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-FunctionDefinitions

ロール機能を公開するセッションに、指定した関数を追加します。 ハッシュ テーブルに次のキーを入力します。

  • 名前。 関数名。 このキーは必須です。
  • ScriptBlock。 関数の本体。 スクリプト ブロックを入力します。 このキーは必須です。
  • オプション。 関数のオプション。 このキーはオプションです。 既定値は None です。 このパラメーターに使用できる値は、None、ReadOnly、Constant、Private、または AllScope です。

次に例を示します。

@{Name="Get-PowerShellProcess";ScriptBlock={Get-Process PowerShell};Options="AllScope"}

型:IDictionary[]
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Guid

ロール機能ファイルの一意識別子を指定します。 このパラメーターを省略すると、 New-PSRoleCapabilityFile はファイルの GUID を生成します。 PowerShell で新しい GUID を作成するには、「 [guid]::NewGuid()」と入力します。

型:Guid
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-ModulesToImport

ロール機能ファイルを使用するセッションに自動的にインポートされるモジュールを指定します。 既定では、一覧表示されているモジュール内のすべてのコマンドが表示されます。 VisibleCmdlets または VisibleFunctions で使用する場合、指定したモジュールから表示されるコマンドを制限できます。

このパラメーターの値で使用される各モジュールは、文字列またはハッシュ テーブルで表すことができます。 モジュール文字列は、モジュールの名前のみで構成されます。 モジュール ハッシュ テーブルには、 ModuleNameModuleVersion、および GUID キーを含めることができます。 ModuleName キーのみが必要です。

たとえば、次の値は文字列とハッシュ テーブルで構成されます。 任意の順序での文字列とハッシュ テーブルの組み合わせは有効です。

"TroubleshootingPack", @{ModuleName="PSDiagnostics"; ModuleVersion="1.0.0.0";GUID="c61d6278-02a3-4618-ae37-a524d40a7f44"}

型:Object[]
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-Path

ロール機能ファイルのパスとファイル名を指定します。 ファイルには、ファイル名拡張子 .psrc 必要があります。

型:String
配置:0
規定値:None
必須:True
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-ScriptsToProcess

ロール機能ファイルを使用するセッションに追加するスクリプトを指定します。 スクリプトのパスとファイル名を入力します。 このパラメーターの値は、スクリプト ファイル名の完全パスまたは絶対パスである必要があります。

型:String[]
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-TypesToProcess

ロール機能ファイルを使用するセッションに追加するタイプ ファイル (.ps1xml) を指定します。 ファイル名の種類を入力します。 このパラメーターの値は、型ファイル名の完全パスまたは絶対パスである必要があります。

型:String[]
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-VariableDefinitions

ロール機能ファイルを使用するセッションに追加する変数を指定します。 ハッシュ テーブルに次のキーを入力します。

  • 名前。 変数名。 このキーは必須です。
  • 値。 変数の値。 このキーは必須です。

例: @{Name="WarningPreference";Value="SilentlyContinue"}

型:Object
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-VisibleAliases

セッション内のエイリアスを、このパラメーターの値で指定されたエイリアスに加えて、 AliasDefinition パラメーターで定義したエイリアスに制限します。 ワイルドカード文字がサポートされています。 既定では、PowerShell エンジンによって定義されているすべてのエイリアスと、モジュールがエクスポートするすべてのエイリアスがセッションに表示されます。

たとえば、使用可能なエイリアスを gm と gcm に制限するには、次の構文を使用します。 VisibleAliases="gcm", "gp"

ロール機能ファイルに Visible パラメーターが含まれている場合、PowerShell は、 Import-Module コマンドレットとその ipmo エイリアスをセッションから削除します。

型:String[]
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:True

-VisibleCmdlets

セッションのコマンドレットを、このパラメーターの値に指定されたコマンドレットに制限します。 ワイルドカード文字とモジュール修飾名がサポートされています。

既定では、セッション エクスポート内のモジュールがセッションに表示されるすべてのコマンドレットが表示されます。 SessionType および ModulesToImport パラメーターを使用して、セッションにインポートされるモジュールとスナップインを決定します。 ModulesToImport にモジュールがない場合コマンドレットを公開すると、New-PSRoleCapabilityFileは適切なモジュールの読み込みを試みます。

Visible パラメーターがセッション構成ファイルに含まれている場合、PowerShell は、Import-Module コマンドレットとそのipmoエイリアスをセッションから削除します。

型:Object[]
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:True

-VisibleExternalCommands

セッションで実行できる外部バイナリ、スクリプト、およびコマンドを、このパラメーターの値で指定されたものに制限します。

既定では、このセッションでは外部コマンドは表示されません。

Visible パラメーターがセッション構成ファイルに含まれている場合、PowerShell は、Import-Module コマンドレットとそのipmoエイリアスをセッションから削除します。

型:String[]
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:False

-VisibleFunctions

セッション内の関数を、このパラメーターの値に指定された関数に加えて、 FunctionDefinitions パラメーターで定義した関数に制限します。 ワイルドカード文字がサポートされています。

既定では、セッション内のモジュールによってエクスポートされたすべての関数がそのセッションに表示されます。 SessionType および ModulesToImport パラメーターを使用して、セッションにインポートされるモジュールを決定します。

Visible パラメーターがセッション構成ファイルに含まれている場合、PowerShell は、Import-Module コマンドレットとそのipmoエイリアスをセッションから削除します。

型:Object[]
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:True

-VisibleProviders

セッション内の PowerShell プロバイダーを、このパラメーターの値で指定されたプロバイダーに制限します。 ワイルドカード文字がサポートされています。

既定では、セッション内のモジュールによってエクスポートされたすべてのプロバイダーがセッションに表示されます。 SessionType および ModulesToImport パラメーターを使用して、セッションにインポートされるモジュールを決定します。

Visible パラメーターがセッション構成ファイルに含まれている場合、PowerShell は、Import-Module コマンドレットとそのipmoエイリアスをセッションから削除します。

型:String[]
配置:Named
規定値:None
必須:False
パイプライン入力を受け取る:False
ワイルドカード文字を受け取る:True