次の方法で共有

about_Pwsh

  • [アーティクル]

簡単な説明

pwsh コマンド-line インターフェイスを使用する方法について説明します。 コマンド-lパラメーターを表示し、構文について説明します。

詳細な説明

Windows PowerShell 5.1 のコマンド-lオプションの詳細については、「 about_PowerShell_exe」を参照してください。

構文

Usage: pwsh[.exe]
    [-Login]
    [[-File] <filePath> [args]]
    [-Command { - | <script-block> [-args <arg-array>]
                  | <string> [<CommandParameters>] } ]
    [[-CommandWithArgs <string>] [<CommandParameters>]]
    [-ConfigurationFile <filePath>]
    [-ConfigurationName <string>]
    [-CustomPipeName <string>]
    [-EncodedCommand <Base64EncodedCommand>]
    [-ExecutionPolicy <ExecutionPolicy>]
    [-InputFormat {Text | XML}]
    [-Interactive]
    [-MTA]
    [-NoExit]
    [-NoLogo]
    [-NonInteractive]
    [-NoProfile]
    [-NoProfileLoadTime]
    [-OutputFormat {Text | XML}]
    [-SettingsFile <filePath>]
    [-SSHServerMode]
    [-STA]
    [-Version]
    [-WindowStyle <style>]
    [-WorkingDirectory <directoryPath>]

pwsh[.exe] -h | -Help | -? | /?

パラメーター

すべてのパラメーターは大文字と小文字-i区別されます。

-File | -f

Fileの値は、-またはファイルパスと省略可能なパラメーターにすることができます。 Fileの値が-の場合、コマンドは標準入力から読み取られます。

これは、パラメーターが存在せず、値がコマンド ラインに存在する場合の既定のパラメーターです。 指定したスクリプトは、新しいセッションのローカル スコープ ("ドット ソース") で実行されるため、スクリプトによって作成される関数と変数は新しいセッションで使用できます。 スクリプト ファイルパスと任意のパラメーターを入力します。 File パラメーター名の後に入力されたすべての文字はスクリプト ファイルパスの後にスクリプト パラメーターが続くものとして解釈されるため、コマンドの最後のパラメーターは File である必要があります。

通常、スクリプトのスイッチ パラメーターは、含めるか省略するかのいずれかです。 たとえば、次のコマンドでは、Get-Script.ps1 スクリプト ファイルの All パラメーターを使用します。-File .\Get-Script.ps1 -All

まれに、switch パラメーターに Boolean 値を指定することが必要になる場合があります。 File パラメーターの値に switch パラメーターに Boolean 値を指定するには、通常、パラメーターの直後にコロンとブール値を指定します(例: -File .\Get-Script.ps1 -All:$False)。

スクリプトに渡されるパラメーターは、(現在のシェルによる解釈の後で) リテラル文字列として渡されます。 たとえば、 cmd.exe で環境変数の値を渡す場合は、 cmd.exe 構文を使用します。 pwsh -File .\test.ps1 -TestParam %windir%

これに対し、cmd.exeでpwsh -File .\test.ps1 -TestParam $env:windirを実行すると、スクリプトは現在のcmd.exe シェルに対して特別な意味を持たないため、リテラル文字列$env:windirを受け取ります。 環境変数参照の$env:windirスタイルCommand パラメーター内で使用できます。これは PowerShell コードとして解釈されるためです。

同様に、Batch スクリプトから同じコマンドを実行する場合は、.\または$PSScriptRootの代わりに%~dp0を使用して、現在の実行ディレクトリ (pwsh -File %~dp0test.ps1 -TestParam %windir%) を表します。 代わりに .\test.ps1 を使用すると、リテラル パスが見つからないため、PowerShell によってエラーがスローされます。 .\test.ps1

Note

File パラメーターは、引数値の配列を想定するパラメーターを使用するスクリプトをサポートできません。 残念ながら、これはネイティブ コマンドが引数値を取得する方法の制限です。 ネイティブ実行可能ファイル ( powershell や pwshなど) を呼び出すと、配列の処理がわからないため、文字列として渡されます。

Fileの値が-の場合、コマンドは標準入力から読み取られます。 リダイレクトされた標準入力なしで pwsh -File - を実行すると、通常のセッションが開始されます。 これは、 File パラメーターをまったく指定しない場合と同じです。 標準入力から読み取ると、入力ステートメントは PowerShell コマンド プロンプトで入力されたかのように、一度に 1 つのステートメントが実行されます。 ステートメントが正しく解析されない場合、ステートメントは実行されません。 プロセス終了コードは、入力内の最後の (実行された) コマンドの状態によって決まります。 通常の終了では、終了コードは常に 0。 スクリプト ファイルが exit コマンドで終了すると、プロセス終了コードは、 exit コマンドで使用される数値引数に設定されます。

-Commandと同様に、スクリプト終了エラーが発生すると、終了コードは1に設定されます。 ただし、 -Commandとは異なり、 Ctrl+C で実行が中断されると 終了コードは 0。 詳細については、about_Automatic_Variablesの$LASTEXITCODEを参照してください。

Note

PowerShell 7.2 の時点では、 File パラメーターは Windows 上の .ps1 ファイルのみを受け入れます。 別のファイルの種類が指定されている場合は、エラーがスローされます。 この動作は Windows 固有です。 他のプラットフォームでは、PowerShell は他の種類のファイルの実行を試みます。

-Command | -c

Command の値には、-、スクリプト ブロック、または文字列を指定できます。 Command の値が-の場合、コマンド テキストは標準入力から読み取られます。

Command パラメーターは、Command に渡された値を ScriptBlock 型として認識できる場合にのみ、実行するスクリプト ブロックを受け入れます。 これは別の PowerShell ホストからpwshを実行する場合に可能です。 ScriptBlock 型は、既存の変数に含まれるか、式から返されるか、または中かっこ ({}) で囲まれたリテラル スクリプト ブロックとして PowerShell ホストによって解析されてから、pwshに渡すことができます。

pwsh -Command {Get-WinEvent -LogName security}

cmd.exeでは、スクリプト ブロック (または ScriptBlock 型) がないため、Command に渡される値は文字列です。 スクリプト ブロックは文字列内に記述できますが、実行される代わりに、一般的な PowerShell プロンプトで入力したのとまったく同じように動作し、スクリプト ブロックの内容が出力されます。

Command に渡された文字列は引き続き PowerShell コードとして実行されるため、スクリプト ブロックの中かっこは、cmd.exeから実行するときに最初の場所では必要ありません。 文字列内で定義されたインライン スクリプト ブロックを実行するには、 call 演算子 & を使用できます。

pwsh -Command "& {Get-WinEvent -LogName security}"

Command の値が文字列の場合、Command は pwsh の最後のパラメーターである必要があります。その後のすべての引数は、実行するコマンドの一部として解釈されるためです。

既存の PowerShell セッション内から呼び出されると、結果は、ライブ オブジェクトではなく逆シリアル化された XML オブジェクトとして親シェルに返されます。 他のシェルの場合、結果は文字列として返されます。

Command の値が-の場合、コマンドは標準入力から読み取られます。 標準入力で Command パラメーターを使用する場合は、標準入力をリダイレクトする必要があります。 次に例を示します。

@'
"in"

"hi" |
  % { "$_ there" }

"out"
'@ | pwsh -NoProfile -Command -

この例を実行すると、次の出力が生成されます。

in
hi there
out

標準入力から読み取ると、PowerShell コマンド プロンプトで入力されたかのように、入力が解析され、一度に 1 つのステートメントが実行されます。 入力コードが正しく解析されない場合、ステートメントは実行されません。 -NoExit パラメーターを使用しない限り、標準入力から読み取る入力がなくなった場合、PowerShell セッションは終了します。

プロセス終了コードは、入力内の最後の (実行された) コマンドの状態によって決まります。 終了コードは、$?が$trueされたとき、または$?が$falseされたときに1されるときに0されます。 最後のコマンドが、 0 または 1以外の終了コードを明示的に設定する外部プログラムまたは PowerShell スクリプトである場合、その終了コードはプロセス終了コードの 1 に変換されます。 同様に、 throw や -ErrorAction Stopなどのスクリプト終了 (runspace-terminating) エラーが発生した場合、または実行が Ctrl+C で中断されると、値 1 が返されます。

特定の終了コードを保持するには、コマンド文字列またはスクリプト ブロックに exit $LASTEXITCODE を追加します。 詳細については、about_Automatic_Variablesの$LASTEXITCODEを参照してください。

-CommandWithArgs | -cwa

これは、7.4 で追加された試験的な機能です。

引数を使用して PowerShell コマンドを実行します。 -Commandとは異なり、このパラメーターは、コマンドで使用できる$argsビルド-in 変数を設定します。

最初の文字列はコマンドです。 空白で区切られた追加の文字列は引数です。

次に例を示します。

pwsh -CommandWithArgs '$args | % { "arg: $_" }' arg1 arg2

この例を実行すると、次の出力が生成されます。

arg: arg1
arg: arg2

Note

引用符を使用して引数を解析するとcmd.exeまたはpowershell.exeから実行すると、この例は失敗します。 それらから実行するには、次のコマンドを使用できます。

REM Quoting required when run from cmd.exe
pwsh -CommandWithArgs "$args | % { ""arg: $_"" }" arg1 arg2

# Quoting required when run from powershell.exe
pwsh -CommandWithArgs '"$args | % { ""arg: $_"" }"' arg1 arg2

-ConfigurationName | -config

PowerShell を実行する構成エンドポイントを指定します。 既定の PowerShell リモート処理エンドポイントや、特定のユーザー ロール機能を持つカスタム エンドポイントなど、ローカル コンピューターに登録されている任意のエンドポイントを指定できます。

例: pwsh -ConfigurationName AdminRoles

-ConfigurationFile

セッション構成 (.pssc) ファイル パスを指定します。 構成ファイルに含まれる構成は、PowerShell セッションに適用されます。

例: pwsh -ConfigurationFile "C:\ProgramData\PowerShell\MyConfig.pssc"

-CustomPipeName

デバッグやその他のクロスプロセス通信に使用される追加の IPC サーバー (名前付きパイプ) に使用する名前を指定します。 これにより、他の PowerShell インスタンスに接続するための予測可能なメカニズムが提供されます。 通常、Enter-PSHostProcessの CustomPipeName パラメーターと共に使用されます。

このパラメーターは、PowerShell 6.2 で導入されました。

次に例を示します。

# PowerShell instance 1
pwsh -CustomPipeName mydebugpipe
# PowerShell instance 2
Enter-PSHostProcess -CustomPipeName mydebugpipe

-EncodedCommand | -e | -ec

Base64-e コード化された文字列バージョンのコマンドを受け入れます。 このパラメーターを使用して、複雑で入れ子になった引用符を必要とするコマンドを PowerShell に送信します。 Base64 表現は、UTF-16LE でエンコードされた文字列である必要があります。

次に例を示します。

$command = 'dir "c:\program files" '
$bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
$encodedCommand = [Convert]::ToBase64String($bytes)
pwsh -encodedcommand $encodedCommand

-ExecutionPolicy | -ex | -ep

現在のセッションの既定の実行ポリシーを設定し、 $env:PSExecutionPolicyPreference 環境変数に保存します。 このパラメーターは、永続的に構成された実行ポリシーを変更しません。

このパラメーターは Windows コンピューターにのみ適用されます。 Windows 以外のプラットフォームでは、パラメーターと指定された値は無視されます。

-InputFormat | -inp | -if

PowerShell に送信されるデータの形式を記述します。 使用できる値は、"Text" (テキスト文字列) と "XML" (シリアル化された CLIXML 形式) です。

-Interactive | -i

ユーザーに対話型プロンプトを表示します。 NonInteractive パラメーターの逆関数。

-Login | -l

Linux および macOS では、/bin/sh を使用してログイン シェルとして PowerShell を起動し、/etc/profile や ~/.profile などのログイン プロファイルを実行します。 Windows では、このスイッチは何も行いません。

重要

このパラメーターは、ログイン シェルとして PowerShell を起動するために最初に指定する必要があります。 このパラメーターは、別の位置で渡される場合は無視されます。

UNIX 上のログイン シェルとして pwsh を設定するには-like オペレーティング システムに次の手順を実行します。

  • pwshへの完全な絶対パスが/etc/shells

    • 通常、このパスは Linux 上の /usr/bin/pwsh や macOS の /usr/local/bin/pwsh のようなものです
    • 一部のインストール方法では、このエントリはインストール時に自動的に追加されます
    • pwshが/etc/shellsに存在しない場合は、エディターを使用して、最後の行のpwshへのパスを追加します。 これには、編集する管理者特権が必要です。

  • chsh ユーティリティを使用して、現在のユーザーのシェルをpwshに設定します。

    chsh -s /usr/bin/pwsh

警告

ログイン シェルとしてpwshを設定することは現在、Linux 用 Windows サブシステム (WSL) ではサポートされていません。ログイン シェルとしてpwshを設定しようとすると、WSL を対話形式で起動できなくなる可能性があります。

-MTA

マルチスレッド アパートメントを使用して PowerShell を起動します。 このスイッチは Windows でのみ使用できます。 Windows 以外のプラットフォームでこのパラメーターを使用すると、エラーが発生します。

-NoExit | -noe

スタートアップ コマンドを実行後、終了しません。

例: pwsh -NoExit -Command Get-Date

-NoLogo | -nol

対話型セッションの起動時にバナーを非表示にします。

-NonInteractive | -noni

このスイッチは、ユーザー入力を必要としないセッションを作成するために使用されます。 これは、スケジュールされたタスクまたは CI/CD パイプラインで実行されるスクリプトに役立ちます。 Read-Hostや確認プロンプトなどの対話型機能を使用しようとすると、ステートメントがハングするのではなく、エラーが終了します。

-NoProfile | -nop

PowerShell プロファイルは読み込まれません。

-NoProfileLoadTime

読み込み時間が 500 ミリ秒を超えると、起動時に表示される PowerShell プロファイルの読み込み時間テキストを非表示にします。

-OutputFormat | -o | -of

PowerShell からの出力の形式を決定します。 使用できる値は、"Text" (テキスト文字列) と "XML" (シリアル化された CLIXML 形式) です。

例: pwsh -o XML -c Get-Date

PowerShell セッション内で呼び出されると、逆シリアル化されたオブジェクトが出力ではなくプレーンな文字列として取得されます。 他のシェルから呼び出されると、出力は CLIXML テキストとして書式設定された文字列データになります。

-SettingsFile | -settings

セッションのシステム-wpowershell.config.json設定ファイルをオーバーライドします。 既定では、system-wide 設定は、$PSHOME ディレクトリ内のpowershell.config.jsonから読み取られます。

これらの設定は、 -ConfigurationName 引数で指定されたエンドポイントでは使用されません。

例: pwsh -SettingsFile c:\myproject\powershell.config.json

-SSHServerMode | -sshs

powerShell を SSH サブシステムとして実行するためにsshd_configで使用されます。 これは、他の用途に対して意図またはサポートされていません。

-STA

シングル スレッド アパートメントを使用して PowerShell を起動します。 これが既定です。 このスイッチは、Windows プラットフォームでのみ使用できます。 Windows 以外のプラットフォームでこのパラメーターを使用すると、エラーが発生します。

-Version | -v

PowerShell のバージョンを表示します。 追加のパラメーターは無視されます。

-WindowStyle | -w

セッションのウィンドウ スタイルを設定します。 使用できる値は、Normal、Minimized、Maximized、Hidden です。 このパラメーターは Windows にのみ適用されます。 Windows 以外のプラットフォームでこのパラメーターを使用すると、エラーが発生します。

-WorkingDirectory | -wd | -wo

起動時に実行することで、最初の作業ディレクトリを設定します。 有効な PowerShell ファイル パスがサポートされています。

ホーム ディレクトリで PowerShell を起動するには、次のコマンドを使用します。 pwsh -WorkingDirectory ~

-Help, -?, /?

pwshのヘルプを表示します。 PowerShell で pwsh コマンドを入力する場合は、スラッシュ (/) ではなく、コマンド パラメーターの先頭にハイフン (-) を付けます。