# 画面設計書 275-エラー取得

## 概要

本ドキュメントは、dbatoolsモジュールのエラー取得機能（Get-DbatoolsError）に関する画面設計書です。

### 本画面の処理概要

dbatoolsコマンドの実行失敗時に発生したエラー情報を取得し、詳細なトラブルシューティングを支援するPowerShellコマンドを提供します。

**業務上の目的・背景**：SQL Server管理業務において、dbatoolsコマンドがエラーで失敗した場合、その原因を特定するために詳細なエラー情報が必要です。本機能により、PowerShellのグローバルエラーコレクションからdbatools関連のエラーのみをフィルタリングして取得し、例外メッセージ、スタックトレース、呼び出し情報などの診断詳細を確認できます。サポートリクエストの作成やバグレポートの際にも有用な情報を提供します。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから`Get-DbatoolsError`コマンドを実行します。

**主要な操作・処理内容**：
1. 最新のdbatoolsエラーの取得（デフォルト）
2. 直近N件のエラーの取得（First）
3. 最古のN件のエラーの取得（Last）
4. スキップ機能付きのエラー取得
5. 全てのdbatoolsエラーの取得（All）

**画面遷移**：CLIベースのため画面遷移は存在しません。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 157 | Get-DbatoolsError | 主機能 | dbatoolsエラーの取得 |

## 画面種別

コマンドラインインターフェース（CLI）

## URL/ルーティング

PowerShellコマンドレット
- `Get-DbatoolsError`

## 入出力項目

### Get-DbatoolsError

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| First | int | No | 直近N件のエラーを取得（デフォルト: 1） |
| Last | int | No | 最古N件のエラーを取得 |
| Skip | int | No | 直近N件をスキップ |
| All | switch | No | 全てのdbatoolsエラーを取得 |

## 表示項目

### Get-DbatoolsError出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| CategoryInfo | ErrorCategoryInfo | エラーカテゴリ分類（ConnectionError、PermissionDenied等） |
| ErrorDetails | ErrorDetails | 追加のエラー詳細情報 |
| Exception | Exception | 発生した.NET例外オブジェクト |
| FullyQualifiedErrorId | string | 完全修飾エラーID（dbatoolsを含む） |
| InvocationInfo | InvocationInfo | エラー発生箇所の詳細（ファイル、行、コマンド名） |
| PipelineIterationInfo | ReadOnlyCollection | パイプライン反復情報 |
| PSMessageDetails | string | PowerShellメッセージ詳細 |
| ScriptStackTrace | string | スクリプトのスタックトレース |
| TargetObject | object | エラー発生時に処理されていたオブジェクト |

## イベント仕様

### 1-エラー取得

Get-DbatoolsErrorコマンド実行時、グローバルエラーコレクション($global:error)からFullyQualifiedErrorIdに"dbatools"を含むエラーをフィルタリングして取得します。

**処理詳細**：
1. パラメータが未指定の場合、First=1をデフォルト設定
2. Allパラメータ指定時はFirst=エラー総数に設定
3. $global:errorをパイプライン処理
4. FullyQualifiedErrorIdに"dbatools"を含むエラーをフィルタリング
5. First、Last、Skipパラメータに従って選択
6. 指定されたプロパティを選択して出力

## データベース更新仕様

### 操作別データベース影響一覧

本機能はSQL Serverデータベースに対する直接的な操作は行いません。PowerShellのグローバルエラーコレクションを参照するのみです。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | N/A | SELECT（メモリ内） | エラーレコードの読み取りのみ |

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| （なし） | 本コマンドは特別なメッセージを出力しません | - |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| エラーが存在しない | 空の結果を返却 |
| パラメータの組み合わせが不正 | PowerShell標準のパラメータ検証 |

## 備考

- $global:errorコレクションはセッション内の全エラーを保持
- FullyQualifiedErrorIdに"dbatools"を含むエラーのみをフィルタリング
- Get-DbatoolsLogの-Errorsパラメータとは異なり、$global:errorを使用
- 詳細な例外情報はException.InnerExceptionでさらに掘り下げ可能
- Select-Object *で全プロパティを確認可能

---

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

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

### 推奨読解順序

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

エラー情報はPowerShell標準のErrorRecord型で表現され、$global:errorコレクションに格納されています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbatoolsError.ps1 | `public/Get-DbatoolsError.ps1` | 出力されるErrorRecordの構造を理解（37-52行目） |

**読解のコツ**: ErrorRecordはPowerShell標準型であり、dbatoolsの独自型ではありません。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbatoolsError.ps1 | `public/Get-DbatoolsError.ps1` | エラー取得のメインロジック |

**主要処理フロー**:
1. **77-79行目**: パラメータ未指定時にFirst=1をデフォルト設定
2. **81-83行目**: Allパラメータ時にFirst=エラー総数に設定
3. **85行目**: $global:errorをフィルタリングしてプロパティ選択

#### Step 3: フィルタリングロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbatoolsError.ps1 | `public/Get-DbatoolsError.ps1` | FullyQualifiedErrorIdによるフィルター（85行目） |

**主要処理フロー**:
- **85行目**: Where-Object FullyQualifiedErrorId -match dbatools

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

```
Get-DbatoolsError
    │
    └─ $global:error
           │
           ├─ Where-Object FullyQualifiedErrorId -match dbatools
           │
           └─ Select-Object -First $First -Last $Last -Skip $Skip
                  │
                  └─ -Property CategoryInfo, ErrorDetails, Exception, ...
```

### データフロー図

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

First/Last/Skip ───────▶ $global:error ───────────────────▶ ErrorRecord[]
                              │
All ───────────────────▶ First = $error.Count
                              │
                              ├─ Where-Object (dbatools filter)
                              │
                              └─ Select-Object (property selection)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbatoolsError.ps1 | `public/Get-DbatoolsError.ps1` | ソース | エラー取得コマンド |
| Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | ソース | ログ取得（関連機能、-Errorsパラメータ） |
