# 機能設計書 69-Get-DbaDbccSessionBuffer

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Get-DbaDbccSessionBuffer` コマンドレットの機能設計書です。DBCC INPUTBUFFERまたはDBCC OUTPUTBUFFERコマンドを使用して、セッションの入力バッファまたは出力バッファの内容を取得する機能について、その仕様と実装詳細を記述します。

### 本機能の処理概要

`Get-DbaDbccSessionBuffer` は、SQL ServerのDBCC INPUTBUFFERまたはDBCC OUTPUTBUFFERコマンドを実行し、指定されたセッションが実行しているSQL文や、クライアントに返されるデータを取得するコマンドレットです。

**業務上の目的・背景**：ブロッキングの調査、不審な活動の監視、パフォーマンス問題の原因となっているクエリの特定において、特定のセッションが何を実行しているかを知ることは非常に重要です。本機能により、DBAは複数のセッションを同時に調査し、問題の原因を迅速に特定できます。

**機能の利用シーン**：
- ブロッキングセッションの調査
- 不審な活動の監視
- パフォーマンス問題のクエリ特定
- クライアント接続問題のデバッグ（OutputBuffer使用時）
- 広範なトラブルシューティング（-Allスイッチ使用時）

**主要な処理内容**：
1. SQL Serverインスタンスへの接続
2. セッションID（または全セッション）の取得
3. DBCC INPUTBUFFER または DBCC OUTPUTBUFFER の実行
4. 結果の解析と構造化オブジェクトとしての出力

**関連システム・外部連携**：
- SQL Server インスタンス
- sys.dm_exec_connections（-All使用時）

**権限による制御**：
- DBCC INPUTBUFFER/OUTPUTBUFFERの実行にはALTER SERVER STATE権限が必要
- または対象セッションの所有者権限

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI | 主画面 | PowerShellコマンドラインからの直接実行 |

## 機能種別

データベース診断（読み取り専用）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQL Serverインスタンス | Mandatory, パイプライン入力可 |
| SqlCredential | PSCredential | No | 認証用資格情報 | - |
| Operation | string | No | 操作タイプ（InputBuffer/OutputBuffer）。デフォルト: InputBuffer | ValidateSet |
| SessionId | int[] | No | 対象セッションID | -Allと排他 |
| RequestId | int | No | リクエストID（複数リクエストがある場合） | - |
| All | switch | No | 全ユーザーセッションを対象 | SessionIdと排他 |
| EnableException | switch | No | 例外を有効にするフラグ | - |

### 入力データソース

- SQL Server インスタンスへの接続
- sys.dm_exec_connections（-All使用時）

## 出力仕様

### 出力データ

#### InputBuffer時

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Server名 |
| SessionId | int | セッションID |
| EventType | string | イベントタイプ |
| Parameters | string | パラメータ |
| EventInfo | string | イベント情報（SQL文） |

#### OutputBuffer時

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Server名 |
| SessionId | int | セッションID |
| Buffer | string | 出力バッファ内容（ASCII） |
| HexBuffer | string | 出力バッファ内容（16進数）※デフォルト非表示 |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SessionIdまたは-Allのいずれかが必要
2. クエリテンプレート準備
   └─ DBCC {Operation}(#Operation#) WITH NO_INFOMSGS
3. インスタンス接続
   └─ Connect-DbaInstanceでSQL Server接続
4. セッション特定
   └─ SessionId指定時はそのIDを使用
   └─ -All時はsys.dm_exec_connectionsから全セッション取得
5. 各セッションに対してDBCC実行
   └─ Operation別に結果を解析
6. 結果出力
   └─ Operation別のPSCustomObjectを出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SessionId or All指定?}
    B -->|両方なし| C[Stop-Function]
    B -->|あり| D[クエリテンプレート準備]
    D --> E[インスタンスループ開始]
    E --> F[Connect-DbaInstance]
    F --> G{接続成功?}
    G -->|No| H[Stop-Function]
    G -->|Yes| I{-All指定?}
    I -->|Yes| J[dm_exec_connectionsから全セッション取得]
    I -->|No| K[SessionIdを使用]
    J --> L[セッションループ開始]
    K --> L
    L --> M[DBCC INPUTBUFFER/OUTPUTBUFFER実行]
    M --> N{Operation判定}
    N -->|InputBuffer| O[EventType/Parameters/EventInfo出力]
    N -->|OutputBuffer| P[Buffer/HexBuffer解析・出力]
    O --> Q{次のセッション?}
    P --> Q
    Q -->|Yes| L
    Q -->|No| R{次のインスタンス?}
    R -->|Yes| E
    R -->|No| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | パラメータ排他 | SessionIdと-Allは排他的に使用 | 常時 |
| BR-02 | パラメータ必須 | SessionIdまたは-Allのいずれかが必須 | 常時 |
| BR-03 | Operationデフォルト | Operation未指定時はInputBuffer | Operation未指定時 |
| BR-04 | OutputBuffer解析 | 16進文字列からASCII文字列を抽出 | OutputBuffer時 |
| BR-05 | HexBufferデフォルト非表示 | Select-DefaultViewでHexBufferを除外 | OutputBuffer時 |

### 計算ロジック

OutputBuffer時のバッファ解析:
- 各結果行の文字列から11-59文字目（48文字）が16進数
- 61-77文字目（16文字）がASCII表現
- 非印字文字（'.'）を除去

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| DBCC INPUTBUFFER | なし | 読み取り | セッション入力バッファの取得 |
| DBCC OUTPUTBUFFER | なし | 読み取り | セッション出力バッファの取得 |
| sys.dm_exec_connections | DMV | SELECT | 全セッションID取得（-All時） |

### テーブル別操作詳細

データベースへの書き込みは行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータ不足 | SessionIdと-Allの両方が未指定 | いずれかを指定 |
| - | 接続失敗 | SQL Serverへの接続に失敗 | 接続情報を確認 |
| - | 権限不足 | ALTER SERVER STATE権限がない | 権限を付与 |
| - | セッション不在 | 指定SessionIdが存在しない | SessionIdを確認 |

### リトライ仕様

リトライ処理なし

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

該当なし（読み取り専用操作）

## パフォーマンス要件

- 軽量な診断コマンドのため、即座に完了
- -All使用時は全セッション数に比例

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

- ALTER SERVER STATE権限が必要
- 他のユーザーのセッション情報を閲覧可能
- 機密性の高いクエリ内容が含まれる可能性

## 備考

- DBCC INPUTBUFFER/OUTPUTBUFFERはSQL Server 2005以降で利用可能
- 大量のセッションがある場合は-All使用に注意

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbccSessionBuffer.ps1 | `public/Get-DbaDbccSessionBuffer.ps1` | 183-191行目, 203-210行目: Operation別の出力構造 |

**読解のコツ**: InputBufferとOutputBufferで出力プロパティが異なることに注意。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbccSessionBuffer.ps1 | `public/Get-DbaDbccSessionBuffer.ps1` | 126-137行目: パラメータ定義 |

**主要処理フロー**:
1. **126-137行目**: パラメータ定義（Operation ValidateSet含む）
2. **138-152行目**: begin ブロック - パラメータ検証とクエリ構築
3. **153-258行目**: process ブロック - メイン処理

#### Step 3: 処理ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbccSessionBuffer.ps1 | `public/Get-DbaDbccSessionBuffer.ps1` | Operation分岐と結果解析 |

**主要処理フロー**:
- **139-144行目**: SessionIdと-Allの排他チェック
- **163-173行目**: 特定SessionIdの処理
- **181-191行目**: InputBuffer結果出力
- **193-211行目**: OutputBuffer結果解析・出力
- **213-256行目**: -All時の全セッション処理

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

```
Get-DbaDbccSessionBuffer (public/Get-DbaDbccSessionBuffer.ps1)
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続
    │
    ├─ server.Query() (セッションID指定時)
    │      └─ DBCC INPUTBUFFER/OUTPUTBUFFER
    │
    └─ server.Query() (-All時)
           ├─ SELECT session_id FROM sys.dm_exec_connections
           └─ DBCC INPUTBUFFER/OUTPUTBUFFER (各セッション)
```

### データフロー図

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

SqlInstance ──────▶ Connect-DbaInstance ──┐
                                          │
SessionId ────────▶                       │
    or                                    │
-All ─────────────▶ dm_exec_connections ──┤
                                          │
Operation ────────▶ DBCC選択 ─────────────┤
                                          │
                                          ▼
                   ┌──────────────────────┼──────────────────────┐
                   │                      │                      │
                   ▼                      ▼                      ▼
            DBCC INPUTBUFFER      DBCC OUTPUTBUFFER       -All時複数実行
                   │                      │
                   ▼                      ▼
            PSCustomObject          PSCustomObject
           (EventType等)           (Buffer, HexBuffer)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbccSessionBuffer.ps1 | `public/Get-DbaDbccSessionBuffer.ps1` | ソース | メイン実装ファイル |
| Get-DbaDbccSessionBuffer.Tests.ps1 | `tests/Get-DbaDbccSessionBuffer.Tests.ps1` | テスト | 単体テスト |
