# 機能設計書 157-Get-DbatoolsError

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Get-DbatoolsError` コマンドレットの機能設計を記述する。本機能は、dbatoolsコマンドの失敗に関する詳細なエラー情報を取得するための機能である。

### 本機能の処理概要

PowerShellグローバルエラーコレクションからdbatools関連のエラーのみをフィルタリングして取得し、トラブルシューティングに必要な詳細情報を提供する機能である。

**業務上の目的・背景**：dbatoolsコマンドの実行中にエラーが発生した場合、原因を特定するために詳細なエラー情報が必要である。標準のPowerShellエラー変数（$Error）には全てのエラーが含まれるため、dbatools固有のエラーを特定するのが困難である。本機能は、dbatools関連のエラーのみを抽出し、包括的な診断情報（例外メッセージ、スタックトレース、呼び出し情報）を提供する。

**機能の利用シーン**：
- dbatoolsコマンド失敗後のエラー原因調査
- SQL Server接続問題のトラブルシューティング
- 権限エラーの診断
- バッチ処理失敗時のエラーパターン分析
- サポートチケット作成時のエラー情報収集

**主要な処理内容**：
1. グローバルエラーコレクション（$global:error）からエラーを取得
2. FullyQualifiedErrorIdで"dbatools"を含むエラーをフィルタリング
3. 指定された数のエラーを選択（First/Last/Skip/All）
4. 診断に有用なプロパティを選択して出力

**関連システム・外部連携**：PowerShellエラーハンドリングシステム

**権限による制御**：特別な権限は不要。

## 関連画面

本機能はコマンドライン機能であり、直接的な関連画面は存在しない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | - |

## 機能種別

診断・トラブルシューティング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| First | int | No | 最新から指定数のエラーを取得 | 正の整数 |
| Last | int | No | 最古から指定数のエラーを取得 | 正の整数 |
| Skip | int | No | 最新から指定数のエラーをスキップ | 0以上の整数 |
| All | switch | No | 全てのdbatools関連エラーを取得 | - |

### 入力データソース

- ユーザー入力（コマンドラインパラメータ）
- グローバルエラーコレクション（$global:error）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| CategoryInfo | ErrorCategoryInfo | エラーカテゴリ分類 |
| ErrorDetails | ErrorDetails | 追加のエラー詳細情報 |
| Exception | Exception | 元となる.NET例外 |
| FullyQualifiedErrorId | string | 完全修飾エラーID |
| InvocationInfo | InvocationInfo | エラー発生時の呼び出し情報 |
| PipelineIterationInfo | ReadOnlyCollection[int] | パイプライン位置情報 |
| PSMessageDetails | string | PowerShellメッセージ詳細 |
| ScriptStackTrace | string | スクリプトのスタックトレース |
| TargetObject | object | エラー発生時の対象オブジェクト |

### 出力先

- PowerShellパイプライン（ErrorRecord）
- コンソール出力

## 処理フロー

### 処理シーケンス

```
1. パラメータ確認
   └─ First/Last/Skip/Allのいずれも指定なし → First=1

2. All判定
   └─ All指定時 → First = $global:error.Count

3. エラーフィルタリング
   └─ $global:error から FullyQualifiedErrorId -match "dbatools" で抽出

4. 選択処理
   └─ Select-Object -First -Last -Skip でエラーを選択

5. プロパティ選択
   └─ 診断用プロパティを選択して出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{パラメータ指定?}
    B -->|なし| C[First = 1]
    B -->|あり| D{All指定?}
    C --> D
    D -->|Yes| E[First = error.Count]
    D -->|No| F[指定値を使用]
    E --> G[$global:error取得]
    F --> G
    G --> H[FullyQualifiedErrorId フィルタ]
    H --> I[Select-Object First/Last/Skip]
    I --> J[プロパティ選択]
    J --> K[出力]
    K --> L[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルト1件 | パラメータ未指定時は最新1件を取得 | パラメータ未指定時 |
| BR-002 | dbatoolsフィルタ | FullyQualifiedErrorIdに"dbatools"を含むエラーのみ | 常時 |
| BR-003 | All展開 | All指定時は全エラー数をFirstに設定 | All指定時 |

### 計算ロジック

- **フィルタ条件**: `FullyQualifiedErrorId -match "dbatools"`

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

本機能はデータベースにアクセスしない。

## エラー処理

### エラーケース一覧

本機能自体はエラーを発生させない。エラーが存在しない場合は空結果を返す。

### リトライ仕様

リトライは実装されていない。

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

本機能は読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- エラーコレクションのフィルタリングは即時完了
- 大量のエラーが存在する場合でも数ミリ秒で完了

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

- エラー情報にはセンシティブな情報（接続文字列、パス等）が含まれる可能性がある
- ログファイルや画面共有時は注意が必要

## 備考

- 関連コマンド: Get-DbatoolsLog
- ErrorRecordの全プロパティを取得するには `Select-Object *` を使用

---

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

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

### 推奨読解順序

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

本機能はPowerShell標準のErrorRecordオブジェクトを出力する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbatoolsError.ps1 | `public/Get-DbatoolsError.ps1` | 36-52行目の.OUTPUTSセクションで出力構造を確認 |

**読解のコツ**: System.Management.Automation.ErrorRecordの主要プロパティを理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbatoolsError.ps1 | `public/Get-DbatoolsError.ps1` | 69-75行目のパラメータ定義 |

**主要処理フロー**:
1. **69-75行目**: パラメータ定義（First, Last, Skip, All）
2. **76-86行目**: processブロックのメイン処理

#### Step 3: コア処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbatoolsError.ps1 | `public/Get-DbatoolsError.ps1` | 76-86行目のメイン処理 |

**主要処理フロー**:
- **77-79行目**: パラメータ未指定時のデフォルト設定（First=1）
- **81-83行目**: All指定時の処理（First = error.Count）
- **85行目**: フィルタリング、選択、プロパティ選択のパイプライン処理

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

```
Get-DbatoolsError
    │
    ├─ Test-Bound
    │      └─ パラメータ指定チェック
    │
    ├─ $global:error
    │      └─ グローバルエラーコレクション
    │
    ├─ Where-Object
    │      └─ FullyQualifiedErrorId フィルタ
    │
    └─ Select-Object
           ├─ -First -Last -Skip
           └─ -Property (診断プロパティ)
```

### データフロー図

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

First ──────┐
Last ───────┼──▶ パラメータ検証
Skip ───────┤
All ────────┘
               │
               ▼
        $global:error
               │
               ▼
        Where-Object
        (dbatools フィルタ)
               │
               ▼
        Select-Object
        (-First -Last -Skip)
               │
               ▼
        Select-Object
        (-Property 診断情報)
               │
               ▼
        ErrorRecord ───▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbatoolsError.ps1 | `public/Get-DbatoolsError.ps1` | ソース | メイン機能実装 |
| Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | ソース | ログ取得（関連コマンド） |
| Test-Bound.ps1 | `private/functions/Test-Bound.ps1` | ソース | パラメータバインドチェック |
