# 機能設計書 151-Get-DbaTraceFlag

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Get-DbaTraceFlag` コマンドレットの機能設計を記述する。本機能は、SQL Serverインスタンスで現在有効化されているグローバルトレースフラグを取得するための機能である。

### 本機能の処理概要

SQL Serverインスタンスに接続し、現在有効化されているグローバルトレースフラグの一覧を取得して、構造化されたオブジェクトとして出力する機能である。

**業務上の目的・背景**：SQL Serverのトレースフラグは、サーバーの動作を変更する重要な設定である。本番環境における構成監査、複数環境間での設定比較、パフォーマンス問題のトラブルシューティング、コンプライアンス要件の確認などにおいて、トレースフラグの状態を把握することが不可欠である。手動での確認は煩雑であり、複数インスタンスを一括で確認する自動化が求められる。

**機能の利用シーン**：
- 本番環境の定期的な構成監査
- 開発環境と本番環境のトレースフラグ設定比較
- パフォーマンス問題発生時の設定確認
- SQL Server移行前後の設定差異検出
- セキュリティ監査でのサーバー構成ドキュメント作成

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続確立
2. SMOのEnumActiveGlobalTraceFlagsメソッドを使用したトレースフラグ情報の取得
3. 特定のトレースフラグ番号でのフィルタリング（オプション）
4. PSCustomObjectへの変換と出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) を使用してSQL Serverインスタンスと連携する。

**権限による制御**：SQL Serverへの接続権限およびDBCC TRACESTATUS実行権限が必要。VIEW SERVER STATE権限が要求される場合がある。

## 関連画面

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

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

## 機能種別

データ取得（SELECT / 読み取り専用）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス。パイプライン入力対応 | 有効なインスタンス名形式 |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 | 有効なPSCredentialオブジェクト |
| TraceFlag | int[] | No | 取得対象のトレースフラグ番号の配列 | 正の整数値 |
| EnableException | switch | No | 例外を直接スローするかどうか | - |

### 入力データソース

- ユーザー入力（コマンドラインパラメータ）
- パイプライン入力（SqlInstance）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| TraceFlag | int | トレースフラグ番号 |
| Global | bool | グローバルフラグかどうか |
| Session | bool | セッションフラグかどうか（デフォルト非表示） |
| Status | int | ステータス値（1=有効、0=無効） |

### 出力先

- PowerShellパイプライン（PSCustomObject）
- コンソール出力（デフォルト表示プロパティ）

## 処理フロー

### 処理シーケンス

```
1. パラメータの受け取り
   └─ SqlInstance、SqlCredential、TraceFlag、EnableExceptionの受け取り

2. インスタンスごとの処理ループ
   └─ 各SqlInstanceに対して順次処理

3. SQL Server接続
   └─ Connect-DbaInstanceを使用して接続確立

4. トレースフラグ取得
   └─ server.EnumActiveGlobalTraceFlags()メソッドの呼び出し

5. 結果フィルタリング
   └─ TraceFlagパラメータが指定されている場合、該当フラグのみ抽出

6. オブジェクト出力
   └─ 各トレースフラグ情報をPSCustomObjectとしてパイプラインに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ受け取り]
    B --> C{SqlInstanceループ}
    C --> D[Connect-DbaInstance]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function でエラー出力]
    F --> C
    E -->|Yes| G[EnumActiveGlobalTraceFlags]
    G --> H{トレースフラグ存在?}
    H -->|No| I[Verbose メッセージ出力]
    I --> C
    H -->|Yes| J{TraceFlagフィルタ指定?}
    J -->|Yes| K[指定フラグでフィルタ]
    K --> L[PSCustomObject出力]
    J -->|No| L
    L --> M{次のフラグ?}
    M -->|Yes| L
    M -->|No| C
    C -->|完了| N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 接続エラー継続 | 接続エラー時は次のインスタンスへ処理を継続 | 複数インスタンス指定時 |
| BR-002 | 空結果の処理 | トレースフラグが有効でない場合はVerboseメッセージのみ | 全インスタンス |
| BR-003 | デフォルト表示 | Sessionプロパティはデフォルト表示から除外 | 常時 |

### 計算ロジック

特になし（単純なデータ取得機能）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| トレースフラグ取得 | システムメタデータ | SELECT | SMO経由でDBCC TRACESTATUSを実行 |

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

本機能はSMOのEnumActiveGlobalTraceFlagsメソッドを使用し、内部的にDBCC TRACESTATUS(-1)を実行してトレースフラグ情報を取得する。直接的なテーブル操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverインスタンスへの接続失敗 | 次のインスタンスへ継続、警告メッセージ出力 |

### リトライ仕様

リトライは実装されていない。接続エラー時は警告メッセージを出力し、次のインスタンスの処理へ継続する。

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

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

## パフォーマンス要件

- 各インスタンスへの接続とトレースフラグ取得は通常1秒未満で完了
- 複数インスタンス指定時は順次処理

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

- SQL Server接続には適切な認証情報が必要
- VIEW SERVER STATE権限が推奨される
- Windows認証、SQL Server認証、Active Directory認証に対応

## 備考

- トレースフラグのドキュメント: https://docs.microsoft.com/en-us/sql/t-sql/database-console-commands/dbcc-traceon-trace-flags-transact-sql
- 関連コマンド: Enable-DbaTraceFlag, Disable-DbaTraceFlag

---

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

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

### 推奨読解順序

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

本機能の出力はPSCustomObjectである。SMOから取得したトレースフラグ情報を加工して出力する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaTraceFlag.ps1 | `public/Get-DbaTraceFlag.ps1` | 102-110行目の出力オブジェクト構造を確認 |

**読解のコツ**: PSCustomObjectのプロパティ定義と、Select-DefaultViewによるデフォルト表示プロパティの制御を確認する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaTraceFlag.ps1 | `public/Get-DbaTraceFlag.ps1` | 関数全体の構造、パラメータ定義を確認 |

**主要処理フロー**:
1. **73-80行目**: パラメータ定義（SqlInstance、SqlCredential、TraceFlag、EnableException）
2. **82-113行目**: processブロック内のメイン処理ロジック
3. **83行目**: foreachによるインスタンスループ開始
4. **84-88行目**: Connect-DbaInstanceによる接続確立とエラーハンドリング

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaTraceFlag.ps1 | `public/Get-DbaTraceFlag.ps1` | トレースフラグ取得とフィルタリングロジック |

**主要処理フロー**:
- **90行目**: `$server.EnumActiveGlobalTraceFlags()` でSMO経由のトレースフラグ取得
- **92-95行目**: 空結果の判定とVerboseメッセージ出力
- **97-99行目**: TraceFlagパラメータによるフィルタリング
- **101-111行目**: 結果のオブジェクト変換と出力

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

```
Get-DbaTraceFlag
    │
    ├─ Connect-DbaInstance
    │      └─ SMO Server オブジェクト生成
    │
    ├─ $server.EnumActiveGlobalTraceFlags()
    │      └─ 内部的に DBCC TRACESTATUS(-1) 実行
    │
    └─ Select-DefaultView
           └─ デフォルト表示プロパティの設定
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ SMO Server
                         │
SqlCredential ──────────┘
                         │
                         ▼
              EnumActiveGlobalTraceFlags()
                         │
                         ▼
TraceFlag ───▶ Where-Object フィルタ
                         │
                         ▼
              PSCustomObject 生成 ───▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaTraceFlag.ps1 | `public/Get-DbaTraceFlag.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理ユーティリティ |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | ログ出力ユーティリティ |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1` | ソース | デフォルト表示プロパティ設定 |
