# 機能設計書 177-Invoke-DbatoolsRenameHelper

## 概要

本ドキュメントは、dbatools PowerShellモジュールのInvoke-DbatoolsRenameHelper関数の機能設計を定義する。非推奨のdbatoolsコマンド名とパラメータ名を現在の同等名に置換してPowerShellスクリプトを更新する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：dbatoolsモジュールは継続的に進化しており、コマンド名やパラメータ名が時間とともにリネームされてきた。この関数は、古いdbatools命名規則を使用しているPowerShellスクリプトファイルを自動的にスキャンし、200以上の非推奨コマンド名と数十のパラメータリネームを検出して更新する。Get-SqlMaxMemoryからGet-DbaMaxMemoryへ、Copy-SqlLoginからCopy-DbaLoginへなどの手動置換作業を一括で処理できる。

**機能の利用シーン**：
- 既存の自動化スクリプトを最新のdbatools命名規則に移行
- レガシーPowerShellコードのモダナイゼーション
- 大量のスクリプトファイルの一括更新
- デプロイメント前のスクリプト標準化

**主要な処理内容**：
1. パラメータリネームマッピングの読み込み
2. コマンドリネームマッピングの読み込み
3. 各ファイルに対してSelect-Stringでパターンマッチ
4. マッチした場合、正規表現で置換
5. 指定エンコーディングでファイル保存
6. 置換結果をPSCustomObjectとして出力

**関連システム・外部連携**：特になし。ファイルシステム操作のみ。

**権限による制御**：ファイルへの読み書き権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面機能マッピングに登録なし |

## 機能種別

スクリプト移行 / 開発支援

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| InputObject | FileInfo[] | Yes | スキャン・更新対象のPowerShellスクリプトファイル | Mandatory, ValueFromPipeline |
| Encoding | string | No | 出力ファイルのエンコーディング（デフォルト: UTF8） | ValidateSet |
| EnableException | switch | No | 例外をスローするか | - |

### 入力データソース

- Get-ChildItemからパイプラインで渡されるファイルオブジェクト
- 直接指定されたFileInfoオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Path | string | 更新されたファイルの完全パス |
| Pattern | string | 検出された非推奨名 |
| ReplacedWith | string | 置換後の現在の名前 |

### 出力先

- 標準出力（パイプライン）にPSCustomObjectを出力
- 対象ファイルを直接上書き保存

## 処理フロー

### 処理シーケンス

```
1. beginブロック: リネームマッピング定義
   ├─ パラメータリネームハッシュテーブル（13項目）
   └─ コマンドリネームハッシュテーブル（200+項目）

2. processブロック: 各ファイル処理
   ├─ パラメータリネームチェック
   │   ├─ Select-Stringでパターン検索
   │   ├─ ShouldProcess確認
   │   ├─ Get-Content -Rawでファイル読み込み
   │   ├─ 正規表現で置換
   │   └─ Set-Contentで保存・結果出力
   │
   └─ コマンドリネームチェック
       ├─ Select-Stringでパターン検索
       ├─ ShouldProcess確認
       ├─ Get-Content -Rawでファイル読み込み
       ├─ 正規表現で置換
       └─ Set-Contentで保存・結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[リネームマッピング読み込み]
    B --> C{ファイルループ}
    C -->|次のFile| D[パラメータリネームループ]
    D -->|次のParam| E{Select-String<br/>パターンマッチ?}
    E -->|No| D
    E -->|Yes| F{ShouldProcess?}
    F -->|No| D
    F -->|Yes| G[Get-Content -Raw]
    G --> H[正規表現置換]
    H --> I[Set-Content]
    I --> J[PSCustomObject出力]
    J --> D
    D -->|完了| K[コマンドリネームループ]
    K -->|次のCmd| L{Select-String<br/>パターンマッチ?}
    L -->|No| K
    L -->|Yes| M{ShouldProcess?}
    M -->|No| K
    M -->|Yes| N[Get-Content -Raw]
    N --> O[正規表現置換]
    O --> P[Set-Content]
    P --> Q[PSCustomObject出力]
    Q --> K
    K -->|完了| C
    C -->|完了| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-177-01 | デフォルトエンコーディング | UTF8がデフォルト | Encoding未指定時 |
| BR-177-02 | 単語境界マッチ | \bで単語境界をマッチして部分置換を防止 | 常時 |
| BR-177-03 | パラメータ優先 | パラメータリネームを先に処理 | 常時 |
| BR-177-04 | 複数置換 | 同一ファイルで複数パターンがマッチ可能 | 常時 |

### 計算ロジック

正規表現置換:
```powershell
$content = ((Get-Content -Path $file -Raw) -Replace "\b$($name.Key)\b", $name.Value).Trim()
```

## データベース操作仕様

データベース操作なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | FileNotFound | 指定ファイルが存在しない | パスを確認 |
| - | AccessDenied | ファイルへの書き込み権限なし | 権限を確認 |

### リトライ仕様

リトライ機能なし。

## トランザクション仕様

ファイル単位での処理。アトミック性は保証されない。

## パフォーマンス要件

- 各パターンに対してSelect-Stringを実行するため、大量ファイル・大量パターンでは時間がかかる
- 200+コマンドと13パラメータのチェックが各ファイルに対して実行される

## セキュリティ考慮事項

- ファイルへの読み書き権限が必要
- 信頼できるソースのファイルのみを対象とすること

## 備考

- WhatIfサポートで事前確認可能
- パラメータリネーム: ExcludeAllSystemDb → ExcludeSystem など
- コマンドリネーム: Get-SqlMaxMemory → Get-DbaMaxMemory など

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

リネームマッピングのハッシュテーブル構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbatoolsRenameHelper.ps1 | `public/Invoke-DbatoolsRenameHelper.ps1` | 74-93行目: パラメータリネーム定義 |
| 1-2 | Invoke-DbatoolsRenameHelper.ps1 | `public/Invoke-DbatoolsRenameHelper.ps1` | 95-311行目: コマンドリネーム定義 |

**読解のコツ**: Key（旧名）→Value（新名）のマッピングを理解する。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbatoolsRenameHelper.ps1 | `public/Invoke-DbatoolsRenameHelper.ps1` | 関数全体の流れを把握 |

**主要処理フロー**:
1. **74-93行目**: パラメータリネームマッピング定義
2. **95-311行目**: コマンドリネームマッピング定義
3. **313-345行目**: 各ファイルに対する置換処理

#### Step 3: 置換処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbatoolsRenameHelper.ps1 | `public/Invoke-DbatoolsRenameHelper.ps1` | 317-329行目: パラメータリネーム処理 |
| 3-2 | Invoke-DbatoolsRenameHelper.ps1 | `public/Invoke-DbatoolsRenameHelper.ps1` | 331-343行目: コマンドリネーム処理 |

**主要処理フロー**:
- **318行目**: Select-Stringでパターン検索
- **320行目**: 正規表現置換
- **321行目**: Set-Contentで保存
- **322-326行目**: PSCustomObject出力

### プログラム呼び出し階層図

```
Invoke-DbatoolsRenameHelper
    │
    ├─ beginブロック
    │      ├─ $paramrenames = @{ ... }  (13項目)
    │      └─ $commandrenames = @{ ... } (200+項目)
    │
    └─ processブロック
           │
           ├─ パラメータリネームループ
           │      ├─ Select-String
           │      ├─ Get-Content -Raw
           │      ├─ -Replace "\b$key\b"
           │      └─ Set-Content
           │
           └─ コマンドリネームループ
                  ├─ Select-String
                  ├─ Get-Content -Raw
                  ├─ -Replace "\b$key\b"
                  └─ Set-Content
```

### データフロー図

```
[入力]                          [処理]                              [出力]

InputObject ─────────▶ ファイルループ
(FileInfo[])                    │
                                ▼
                    ┌───────────┴───────────┐
                    ▼                       ▼
            パラメータリネーム        コマンドリネーム
                    │                       │
                    ▼                       ▼
              Select-String           Select-String
                    │                       │
            ┌───────┴───────┐       ┌───────┴───────┐
            ▼               ▼       ▼               ▼
         マッチ          非マッチ  マッチ          非マッチ
            │               │       │               │
            ▼               │       ▼               │
         置換・保存         │    置換・保存         │
            │               │       │               │
            ▼               │       ▼               │
      PSCustomObject        │  PSCustomObject       │
            │               │       │               │
            └───────────────┴───────┴───────────────┘
                                    │
                                    ▼
                              パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbatoolsRenameHelper.ps1 | `public/Invoke-DbatoolsRenameHelper.ps1` | ソース | メイン関数 |
