1. 全体方針と対象読者

2種類の読者を1つの資料でカバーする

この資料は読者を2種類想定しています。どちらもプログラミングの基礎（変数・条件分岐・繰り返し・関数）は理解している前提です。違いは「その経験が JavaScript かどうか」だけです。

別々の資料を作ると保守が二重になるため、本文は JS 経験者向けに書き、JS 以外の経験者が引っかかる箇所だけ補足枠を添える方式にします。

本文を書くときの4原則

• 原則1DOS の例を必ず添える — 「cmd ではこう書いていた」が分かると、PowerShell の書き方が「何を解決したのか」として理解できる
• 原則2JavaScript (Node.js) の例を随時添える — 読者Aの既知の知識に接続する。特に配列・オブジェクト・非同期の扱いで効く
• 原則3「なぜそうなっているか」を先に書く — BOM や CRLF のような「決まりごと」は、理由を知らないと必ず忘れる
• 原則4動かせる短いコードで終わる — 各節の最後に、コピペして即実行できる5行以内の例を置く
• 原則5バージョン差はバッジで示す — 5.1 と 7 で違う箇所に pwsh 7 5.1 を付ける

補足枠に書くこと・書かないこと

読者がプログラミングの基礎を持っている前提になったことで、補足枠の中身も絞り込めます。書くのは PowerShell と Windows に固有の事情だけです。

バージョンバッジの使い方

本資料は Windows PowerShell 5.1 と PowerShell 7 (pwsh) の両方を対象にします。読者の環境がどちらか分からないため、差がある箇所だけをその場でバッジで示します。

1ファイルの構成テンプレート

全ファイルで同じ骨格にすることで、読者が「どこに何が書いてあるか」を予測できるようにします。

2. ファイル構成とロードマップ

全12ファイル・4部構成

ファイル一覧

読む順序の依存関係

• 01 → 02 → 03 は順番必須。環境が整わないと以降が動かせない
• 04・05 は PowerShell の核心。ここだけは飛ばさせない
• 06〜09 は独立性が高く、必要な順に読んでよい
• 10 は 05 まで終わっていれば着手可能

3. 基礎編（01〜05）の詳細

01. 背景

DOS/cmd の限界 → Bash の強み → PowerShell が必要だった理由 → 設計思想 → 他言語との立場、の4章構成。SVG図4枚で、テキストパイプとオブジェクトパイプの違いを視覚化済み。

02. ファイル形式と文字コード

この資料で最初に「決まりごと」が出てくる章です。理由を説明せずに規則だけ書くと必ず忘れられるので、文字コードの仕組みから入ります。

02.2 が本資料で最も重要な節

注意3行目に注目してください。Shift-JIS の ps1 は 5.1 では動くが 7 では壊れます。「今まで動いていたスクリプトが pwsh に変えた途端に文字化けする」典型的な原因がこれです。02.2 ではこの逆転を必ず扱います。

03. 実行環境と実行ポリシー

04. 変数・型・演算子

読者Aの既知知識に最も接続しやすい章。全節で JS のコードを左、PowerShell を右に並べます。

# JavaScript                    # PowerShell
const name = "PS";              $name = "PS"
const arr = [1, 2, 3];          $arr = @(1, 2, 3)
const obj = { a: 1 };           $obj = @{ a = 1 }
arr.filter(x => x > 1);         $arr | Where-Object { $_ -gt 1 }
`${name} version`;              "$name version"

• 04.1 変数と型 — $ 記法、型推論、明示的な型指定
• 04.2 文字列 — 単一引用符と二重引用符の違い（展開の有無）、ヒアストリング
• 04.3 比較演算子 — -eq／-gt と、既定で大小文字を区別しない落とし穴
• 04.4 配列とハッシュテーブル
• 04.5 $null・真偽値・型変換の癖

05. パイプラインとオブジェクト

• 05.1 パイプに流れるのはオブジェクト — 01 の復習から入る
• 05.2 Get-Member で中身を覗く — この1つを覚えるだけで自習できるようになる
• 05.3 Where-Object／ForEach-Object／Select-Object
• 05.4 Sort-Object／Group-Object／Measure-Object
• 05.5 Cmdlet の命名規則（動詞-名詞）と Get-Command での探し方

4. 実践編（06〜09）の詳細

06. 制御構文と関数

• 06.1 if／foreach／while／switch — JS との構文差
• 06.2 関数定義、param()、既定値、パイプライン入力の受け取り
• 06.3 戻り値の落とし穴 — 関数内の出力がすべて戻り値になる、配列が潰れる問題
• 06.4 スコープ（$script:／$global:）

07. ファイル・テキスト操作

08. エラー処理とデバッグ

• 08.1 終了エラーと非終了エラーの違い — PowerShell 固有の概念
• 08.2 try/catch/finally と -ErrorAction Stop
• 08.3 終了コード、$LASTEXITCODE、外部コマンドの失敗検知
• 08.4 Write-Verbose／ブレークポイント／Set-PSDebug

09. 実務パターン集

ここまでの知識を組み合わせた「そのまま使える」スクリプト集。各パターンは50行以内に収め、写経できる長さにします。

• 09.1 ログファイルの集計（日付フィルタ ＋ Group-Object）
• 09.2 ファイルの一括リネーム（正規表現、ドライラン付き）
• 09.3 フォルダの同期・バックアップ
• 09.4 タスクスケジューラからの実行（cmd ランチャー、ログ出力）
• 09.5 外部コマンド・Node.js スクリプトの呼び出しと戻り値の受け取り

5. 発展編（11・12）の詳細

本編を書き終えてから足した理由

当初の構成は 01〜10 の3部構成でした。11・12 は本編を一通り書き終えたあとに追加したもので、性格が本編とは違います。

• 全員には要らない。01〜10 を読めば業務の大半は書けます。11・12 は「PowerShell だけでは届かない場面」に限った話です
• 順番に依存しない。11 と 12 の間に前後関係はありません。必要なほうだけ読めます
• 踏む罠が本編より深い。実行時にしか分からない制約（型の再定義、COM の解放漏れ）が中心です

11. C# を埋め込む — Add-Type

全7節。すべてのコードを 5.1 と 7 の両方で実行して確認しています。

• 11.1 なぜ C# を書くのか — まず PowerShell で書き、遅いと実測してから使う
• 11.2 Add-Type -TypeDefinition の基本
• 11.3 5.1 と 7 でコンパイラが違う — csc.exe (.NET Framework) と Roslyn (.NET)
• 11.4 同じ型を2回定義できない — キャッシュキーはソース文字列そのもの
• 11.5 Win32 API を呼ぶ — -MemberDefinition と DllImport
• 11.6 使いどころの見極め
• 11.7 事前にコンパイルして exe を配る — csc.exe を直接使う

12. Office と COM を操作する

全5節。Word・Excel・PowerPoint の COM を実際に動かして確認しています。

• 12.1 COM とは何か — New-Object -ComObject。VBA のオブジェクトモデルがそのまま使える
• 12.2 Office ファイルの PDF 化 — 3種すべて成功。引数の順序が Word と Excel で逆
• 12.3 後始末 — Quit() だけではプロセスが残る。ReleaseComObject と try/finally
• 12.4 COM を使わない選択肢 — ImportExcel・CSV との使い分け
• 12.5 実例 — このリポジトリの build-pptx.ps1 が踏んだ罠

6. 勉強会の進行案

全5回・1回90分

各回の進行表は受講者が見るものなので README の4章「勉強会で使う場合」 に置いています。ここでは主催する側の準備だけを扱います。

1回あたりの時間配分

事前準備（主催側）

• 必須第2回までに実行ポリシーの扱いを社内ルールとして確認しておく。参加者の PC で RemoteSigned に変更できないと以降が進まない
• 必須ハンズオン用のサンプルデータ（ログファイル、リネーム対象フォルダ）を配布形式で用意
• 必須参加者に PowerShell 7 (pwsh) を導入してもらう。5.1 は Windows 標準で入っているが、両対応で進めるため 7 も揃える。導入手順は 03 章で扱う
• 任意各回の資料を事前配布し、読んできた前提で解説時間を短縮する運用も可能

決定事項

7. 付録（A1・A2・A3）の詳細

本編との役割の違い

A1. 逆引き — 4つの入口

資料には Cmdlet 76種が12章に散らばっています。「あのコマンドはどの章だったか」を引けるようにします。

複数の章にまたがる Cmdlet（実測）

全 69 種のうち 21 種が3章以上に登場します。4章以上のものを挙げます。

残り 48 種は 1〜2 章にのみ登場します。横断する 21 種だけでも索引の価値があることが数字で確認できました。

A2. テンプレ集 — 09 との違い

ここが設計上もっとも重要な判断です。09 と重複させません。

A3. モジュール — 導入せずに書いた付録

全4節。業務で効くものだけを8本選び、うち4本を詳しく扱います。網羅は目的にしていません。

• A3.1 選ぶときの判断基準 — 提供元・最終更新日・5.1／7 の両対応・依存の重さ
• A3.2 リストと概要 — 8本の一覧。外したものとその理由も書く
• A3.3 詳細 — PSScriptAnalyzer／ImportExcel／SecretManagement＋SecretStore／Pester
• A3.4 導入と運用 — -Scope CurrentUser、Save-Module でのオフライン配布、#Requires -Modules

README への反映

README の逆引き索引（17項目）は残します。役割を分けます。

8. 資料のビルドと運用

ここから先は資料を作る側の手順です。読むだけなら必要ありません。

HTML を編集したら再生成が必要

実行方法

# 0) 章を増減・改題したときに実行する2本
.\src\scripts\nav\build-nav.ps1      # 各章フッターの前後リンク
.\src\scripts\index\build-index.ps1  # A1.2 のコマンド索引

# 1) SVG 図を PNG に書き出す（構造 JSON も同時に出力される）
.\src\scripts\figures\capture-figures.ps1

# 2) pptx を生成する（-Prefix で1章だけも可）
.\src\scripts\pptx\build-pptx.ps1 -Prefix 05 -Pdf -Images

# 3) GitHub 用の Markdown を生成する
.\src\scripts\markdown\build-markdown.ps1

いずれも同名の .cmd をダブルクリックしても実行できます。

Markdown 版について

GitHub は .html をレンダリングしないため、同じ内容の .md を HTML から生成しています。リポジトリ上で読むときはこちらを使ってください。

章を追加したときの手順

1. docs/NN-タイトル.html を作る
2. build-nav.ps1 を実行してフッターの前後リンクを作り直す（手で書かない）
3. 構成案 の状態を作成済に更新する（一覧表と詳細見出しの2箇所）
4. 共有環境の targets.ts に追記する
5. このページの章カードと逆引き索引に追加する
6. build-index.ps1 を実行して A1.2 のコマンド索引を作り直す。未登録の Cmdlet があると警告が出るので、スクリプト内の $Purpose に追記する
7. 新しい Cmdlet が出たなら A1.1 と A1.4 も見直す

出力物の置き場所

生成物はすべて tmp/ にあります。消しても HTML から作り直せます。