A2.1 スクリプトの骨格

新しい .ps1 を作るとき、処理を書く前にこの形を貼ります。中身が何であれ、この4層は変わりません。

そのまま貼れる形

#Requires -Version 5.1
[CmdletBinding()]
param(
	[Parameter(Mandatory)]
	[string]$Path,

	[string]$OutFile,

	[switch]$Force
)

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

# 既定値は param() の外で入れる（理由は下の callout）
if (-not $OutFile) { $OutFile = Join-Path $PSScriptRoot 'result.csv' }

try {
	Write-Verbose "対象: $Path"

	if (-not (Test-Path -LiteralPath $Path)) {
		throw "パスが見つかりません: $Path"
	}

	# ここに処理を書く
	Write-Host "処理しました: $Path"

	exit 0
}
catch {
	Write-Host "失敗しました: $($_.Exception.Message)" -ForegroundColor Red
	Write-Host $_.ScriptStackTrace
	exit 1
}

実行結果

PS> .\skeleton.ps1 -Path C:\work
処理しました: C:\work
exit=0

PS> .\skeleton.ps1 -Path X:\nope
失敗しました: パスが見つかりません: X:\nope
at <ScriptBlock>, C:\work\skeleton.ps1: line 19
exit=1

各行が何をしているか

Join-Path : Cannot bind argument to parameter 'Path' because it is an empty string.
At C:\work\skeleton.ps1:6 char:31
+     [string]$OutFile = (Join-Path $PSScriptRoot 'result.csv')
+                                  ~~~~~~~~~~~~~

A2.2 ログ出力

人が見ていない時間に動くスクリプトでは、ログが唯一の手がかりです。Write-Host だけだと画面が閉じた瞬間に消えます。

Write-Log 関数

$LogPath = Join-Path $PSScriptRoot 'run.log'

function Write-Log {
	[CmdletBinding()]
	param(
		[Parameter(Mandatory, ValueFromPipeline)]
		[string]$Message,

		[ValidateSet('INFO', 'WARN', 'ERROR')]
		[string]$Level = 'INFO'
	)
	process {
		$line = '{0} [{1}] {2}' -f (Get-Date -Format 'yyyy-MM-dd HH:mm:ss'), $Level, $Message
		Add-Content -LiteralPath $LogPath -Value $line -Encoding UTF8
		switch ($Level) {
			'ERROR' { Write-Host $line -ForegroundColor Red }
			'WARN'  { Write-Host $line -ForegroundColor Yellow }
			default { Write-Host $line }
		}
	}
}

使い方と実行結果

Write-Log '処理を開始しました'
Write-Log '対象が見つかりません' -Level WARN
'パイプでも渡せます' | Write-Log

2026-08-25 00:24:32 [INFO] 処理を開始しました
2026-08-25 00:24:32 [WARN] 対象が見つかりません
2026-08-25 00:24:32 [INFO] パイプでも渡せます

同じ内容が run.log にも残ります。画面とファイルの両方に出るのが要点です。

この形にしている理由

ログを日ごとに分ける

$LogPath = Join-Path $PSScriptRoot ('run-{0}.log' -f (Get-Date -Format 'yyyyMMdd'))

1行変えるだけです。古いログの削除まで入れるなら次の形にします。

# 30 日より古いログを消す
Get-ChildItem -LiteralPath $PSScriptRoot -Filter 'run-*.log' |
	Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-30) } |
	Remove-Item -WhatIf

注意-WhatIf を付けたまま貼ってあります。出力を見て納得してから外してください。

A2.3 引数の検証

引数のチェックを if で書くと、本体の先頭が検証コードで埋まります。PowerShell では属性で宣言すると、本体に入る前に弾かれます。

使える検証属性

[CmdletBinding()]
param(
	[Parameter(Mandatory)]
	[ValidateNotNullOrEmpty()]
	[string]$Name,

	[ValidateSet('Dev', 'Stg', 'Prod')]
	[string]$Env = 'Dev',

	[ValidateRange(1, 100)]
	[int]$Count = 10,

	[ValidateScript({ Test-Path -LiteralPath $_ -PathType Container })]
	[string]$Dir = '.',

	[ValidatePattern('^\d{4}-\d{2}-\d{2}$')]
	[string]$Date = '2026-08-25'
)

違反したときのメッセージ

いずれも本体は1行も実行されません。

PS> .\validate.ps1 -Name t -Env Hoge
Cannot validate argument on parameter 'Env'. The argument "Hoge" does not
belong to the set "Dev,Stg,Prod" specified by the ValidateSet attribute.

PS> .\validate.ps1 -Name t -Count 999
Cannot validate argument on parameter 'Count'. The 999 argument is greater
than the maximum allowed range of 100.

PS> .\validate.ps1 -Name t -Dir X:\nope
Cannot validate argument on parameter 'Dir'. The " Test-Path -LiteralPath $_
-PathType Container " validation script for the argument with value "X:\nope"
did not return a result of True.

PS> .\validate.ps1 -Name t -Date 2026/08/25
Cannot validate argument on parameter 'Date'. The argument "2026/08/25" does
not match the "^\d{4}-\d{2}-\d{2}$" pattern.

使い分け

引数どうしの関係を見る

「A を指定したなら B も要る」のような条件は属性では書けません。パラメータセットを使います。

[CmdletBinding(DefaultParameterSetName = 'ByName')]
param(
	[Parameter(Mandatory, ParameterSetName = 'ByName')]
	[string]$Name,

	[Parameter(Mandatory, ParameterSetName = 'ById')]
	[int]$Id
)

# どちらが使われたか
switch ($PSCmdlet.ParameterSetName) {
	'ByName' { "名前で検索: $Name" }
	'ById'   { "ID で検索: $Id" }
}

-Name と -Id を同時に指定するとエラーになり、どちらも指定しないと -Name を対話で聞かれます。

A2.4 ファイル処理の定型

ファイル操作は書き方の選択肢が多く、既定値が版で違うところです。迷わないよう、そのまま使える形だけを並べます。

読む

# 行の配列として読む
$lines = Get-Content -LiteralPath $Path -Encoding UTF8

# 1つの文字列として読む（JSON・XML はこちら）
$text = Get-Content -LiteralPath $Path -Raw -Encoding UTF8

# JSON として読む
$obj = Get-Content -LiteralPath $Path -Raw -Encoding UTF8 | ConvertFrom-Json

# CSV として読む（値はすべて文字列になる）
$rows = Import-Csv -LiteralPath $Path -Encoding UTF8

# 巨大なファイルを1行ずつ（メモリに載せない）
Get-Content -LiteralPath $Path -Encoding UTF8 | ForEach-Object {
	# $_ が1行
}

書く

# 上書き
Set-Content -LiteralPath $Path -Value $text -Encoding UTF8

# 追記
Add-Content -LiteralPath $Path -Value $line -Encoding UTF8

# JSON として書く（-Depth を必ず指定する）
$obj | ConvertTo-Json -Depth 10 | Set-Content -LiteralPath $Path -Encoding UTF8

# CSV として書く
$rows | Export-Csv -LiteralPath $Path -Encoding UTF8 -NoTypeInformation

パスを組み立てる

# 連結（区切りの重複を吸収してくれる）
$full = Join-Path $Dir 'sub' | Join-Path -ChildPath 'file.txt'

# 分解
Split-Path $full -Parent      # 親フォルダ
Split-Path $full -Leaf        # file.txt
Split-Path $full -LeafBase    # file        <- pwsh 7 のみ
Split-Path $full -Extension   # .txt        <- pwsh 7 のみ

# スクリプト自身の場所を基準にする
$data = Join-Path $PSScriptRoot 'data'

5.1では -LeafBase と -Extension がありません。[System.IO.Path]::GetFileNameWithoutExtension($full) で代用します。

存在を確かめる

# あるかどうか
if (Test-Path -LiteralPath $Path) { }

# ファイルであること（フォルダを除く）
if (Test-Path -LiteralPath $Path -PathType Leaf) { }

# フォルダであること
if (Test-Path -LiteralPath $Path -PathType Container) { }

# 無ければ作る（親フォルダごと）
if (-not (Test-Path -LiteralPath $Dir)) {
	$null = New-Item -ItemType Directory -Path $Dir -Force
}

一覧する

# フォルダ直下のファイルだけ
Get-ChildItem -LiteralPath $Dir -File

# 再帰して拡張子で絞る
Get-ChildItem -LiteralPath $Dir -Recurse -File -Filter '*.log'

# 複数の拡張子（-Include には -Recurse が要る）
Get-ChildItem -Path $Dir -Recurse -Include '*.log', '*.txt'

# 更新日で絞る
Get-ChildItem -LiteralPath $Dir -Recurse -File |
	Where-Object { $_.LastWriteTime -gt (Get-Date).AddDays(-7) }

安全に消す・移す

# まず -WhatIf で確認する
Get-ChildItem -LiteralPath $Dir -Filter '*.tmp' | Remove-Item -WhatIf

# 納得したら外す
Get-ChildItem -LiteralPath $Dir -Filter '*.tmp' | Remove-Item

# 1件ずつ確認しながら
Get-ChildItem -LiteralPath $Dir -Filter '*.tmp' | Remove-Item -Confirm

推奨削除とリネームは必ず -WhatIf を付けた状態で書き始めます。出力を見てから外す手順にすると、対象の取り違えに気づけます。

A2.5 外部コマンド呼び出し

robocopy git node のような exe は、失敗しても例外になりません。try/catch だけでは失敗を見逃します。

ラッパー関数

function Invoke-External {
	param(
		[Parameter(Mandatory)][string]$Command,
		[string[]]$Arguments = @()
	)

	if (-not (Get-Command $Command -ErrorAction SilentlyContinue)) {
		throw "コマンドが見つかりません: $Command"
	}

	$output = & $Command @Arguments 2>&1

	if ($LASTEXITCODE -ne 0) {
		throw ("{0} が終了コード {1} で失敗しました`n{2}" -f $Command, $LASTEXITCODE, ($output -join "`n"))
	}

	return $output
}

実行結果

PS> Invoke-External 'cmd.exe' @('/c', 'echo hello')
hello

PS> Invoke-External 'cmd.exe' @('/c', 'exit 3')
cmd.exe が終了コード 3 で失敗しました

PS> Invoke-External 'nosuchcmd.exe'
コマンドが見つかりません: nosuchcmd.exe

3つの要点

JSON を返すコマンドを受け取る

$json = Invoke-External 'gh' @('api', 'repos/owner/name')
$repo = $json -join "`n" | ConvertFrom-Json
$repo.full_name

$output は行の配列なので、ConvertFrom-Json に渡す前に -join で1つの文字列に戻します。

A2.6 配布用の一式

自分だけが使うなら .ps1 1つで足ります。人に渡す・タスクに登録するなら、周辺のファイルが要ります。

フォルダの形

mytool\
├── mytool.ps1        本体
├── mytool.cmd        ダブルクリック用のランチャー
├── config.json       設定（コードと分ける）
├── README.md         使い方
└── logs\             実行ログの出力先

cmd ランチャー

.ps1 はダブルクリックしても実行されません。同名の .cmd を添えます。

@echo off
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0mytool.ps1" %*
pause

注意この .cmd は SJIS ＋ CRLF で保存します。UTF-8 で保存すると日本語のメッセージが化けます。

設定をコードから分ける

$ConfigPath = Join-Path $PSScriptRoot 'config.json'

$Config = if (Test-Path -LiteralPath $ConfigPath) {
	Get-Content -LiteralPath $ConfigPath -Raw -Encoding UTF8 | ConvertFrom-Json
} else {
	# 既定値。config.json が無くても動く
	[PSCustomObject]@{
		TargetDir = 'C:\work'
		RetentionDays = 30
	}
}

Write-Verbose "対象: $($Config.TargetDir)"

設定を外に出すと、渡した相手がスクリプト本体を編集せずに済みます。既定値を持たせておけば config.json が無くても動きます。

タスクスケジューラに登録する

$action = New-ScheduledTaskAction `
	-Execute 'powershell.exe' `
	-Argument '-NoProfile -ExecutionPolicy Bypass -File "C:\tools\mytool\mytool.ps1"' `
	-WorkingDirectory 'C:\tools\mytool'

$trigger = New-ScheduledTaskTrigger -Daily -At '03:00'

Register-ScheduledTask -TaskName 'MyTool 日次実行' `
	-Action $action -Trigger $trigger -Description '日次のログ集計'

渡す前の確認