# 機能設計書 80-Disable-DbaTraceFlag

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Disable-DbaTraceFlag` コマンドレットに関する機能設計書です。このコマンドは、SQL Serverインスタンスでグローバルに有効化されているトレースフラグを無効化します。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのトレースフラグは、サーバーの動作を変更する診断・構成オプションです。トラブルシューティングやテストで一時的に有効化したトレースフラグを、作業完了後に無効化する必要があります。本機能は、DBCC TRACEOFFコマンドを使用してメモリ内のグローバルトレースフラグを無効化します。

**機能の利用シーン**：
- トラブルシューティング完了後のトレースフラグ無効化
- テスト環境での診断フラグのリセット
- 本番環境での一時的なフラグ変更のロールバック
- SQL Server再起動なしでのトレースフラグ管理

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続
2. 現在有効なトレースフラグの取得（Get-DbaTraceFlag）
3. 指定されたトレースフラグの有効状態確認
4. DBCC TRACEOFF コマンドの実行
5. 結果ステータスの出力

**関連システム・外部連携**：Get-DbaTraceFlagコマンドを使用して現在の状態を確認

**権限による制御**：ALTER SETTINGS権限またはsysadminロールのメンバーシップが必要

## 関連画面

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

## 機能種別

構成管理 / トレースフラグ管理 / DBCC操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力対応 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | Windows/SQL認証対応 |
| TraceFlag | int[] | Yes | 無効化するトレースフラグ番号 | 複数指定可能 |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- PowerShellコマンドライン引数
- パイプライン入力（SqlInstance）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SourceServer | string | SQL Serverのコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| TraceFlag | int | トレースフラグ番号 |
| Status | string | 操作結果（Successful/Skipped/Failed） |
| Notes | string | 追加情報またはエラーメッセージ |
| DateTime | DbaDateTime | 操作実行日時 |

### 出力先

- PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. processブロック：各インスタンスの処理
   └─ Connect-DbaInstanceでサーバー接続
2. 現在のトレースフラグ取得
   └─ Get-DbaTraceFlagで有効フラグ一覧取得
3. 各トレースフラグの処理
   └─ TraceFlagInfo オブジェクトの初期化
   └─ 有効状態の確認
4. 有効でない場合
   └─ Status = Skipped、警告メッセージ出力
5. 有効な場合
   └─ ShouldProcess確認
   └─ DBCC TRACEOFF実行
   └─ 結果に基づきStatus設定
6. 結果オブジェクトの出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[インスタンスループ]
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function]
    D -->|Yes| F[Get-DbaTraceFlag]
    F --> G[各TraceFlagループ]
    G --> H[TraceFlagInfoオブジェクト初期化]
    H --> I{フラグ有効?}
    I -->|No| J[Status = Skipped]
    J --> K[警告メッセージ]
    K --> L[オブジェクト出力]
    I -->|Yes| M{ShouldProcess?}
    M -->|No| N{次のTraceFlag?}
    M -->|Yes| O[DBCC TRACEOFF実行]
    O --> P{成功?}
    P -->|No| Q[Status = Failed]
    P -->|Yes| R[Status = Successful]
    Q --> S[Stop-Function]
    S --> L
    R --> L
    L --> N
    N -->|Yes| G
    N -->|No| T{次のインスタンス?}
    T -->|Yes| B
    T -->|No| U[終了]
    E --> T
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-80-01 | 事前確認 | 無効化前に現在の状態を確認 | 常時 |
| BR-80-02 | 非アクティブスキップ | 既に無効なフラグはスキップ | フラグ未有効時 |
| BR-80-03 | メモリのみ | 起動パラメータは変更しない | 常時 |
| BR-80-04 | グローバル影響 | -1オプションで全セッションに影響 | 常時 |

### 計算ロジック

- 特になし（DBCC TRACEOFFを実行するのみ）

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|------|---------|------|
| DBCC TRACEOFF | グローバルトレースフラグ | メモリ操作 | フラグの無効化 |

### DBCC TRACEOFFの動作

- `DBCC TRACEOFF (flag, -1)`: グローバルスコープでトレースフラグを無効化
- `-1`オプションにより、現在および将来のすべてのセッションに影響

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverに接続できない | Stop-Functionで処理継続 |
| ExecutionError | 実行エラー | DBCC TRACEOFF実行失敗 | Status = Failed、エラー情報をNotesに格納 |
| NotRunning | スキップ | 指定フラグが有効でない | Status = Skipped、警告メッセージ表示 |

### リトライ仕様

- リトライ機能なし（手動で再実行が必要）

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

- トランザクション不要（メモリ操作のみ）

## パフォーマンス要件

- 実行は即時完了
- トレースフラグの無効化による影響はフラグの種類に依存

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

- ALTER SETTINGS権限またはsysadminロールが必要
- SqlCredentialパラメータで安全な認証情報の受け渡しをサポート
- ConfirmImpact = 'Low'により確認プロンプトはデフォルトで表示されない

## 備考

- メモリ内のトレースフラグのみ無効化（起動パラメータは変更しない）
- 永続的な変更にはSet-DbaStartupParameterを使用
- 著者: Garry Bargsley (@gbargsley)

---

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

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

### 推奨読解順序

#### Step 1: コマンドの全体構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Disable-DbaTraceFlag.ps1 | `public/Disable-DbaTraceFlag.ps1` | シンプルなコマンド構造、Get-DbaTraceFlagとの連携 |

**読解のコツ**: 事前にGet-DbaTraceFlagで現在の状態を確認し、無効化対象を検証する点に注目。

#### Step 2: processブロック - メイン処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Disable-DbaTraceFlag.ps1 | `public/Disable-DbaTraceFlag.ps1` | 79-122行目：インスタンスループとトレースフラグループ |

**主要処理フロー**:
1. **80行目**: インスタンスループ開始
2. **82-86行目**: Connect-DbaInstanceによる接続
3. **88行目**: Get-DbaTraceFlagで現在の状態取得
4. **90行目**: トレースフラグループ開始
5. **91-99行目**: TraceFlagInfoオブジェクト初期化

#### Step 3: processブロック - 状態確認と実行

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Disable-DbaTraceFlag.ps1 | `public/Disable-DbaTraceFlag.ps1` | 100-120行目：状態確認とDBCC TRACEOFF実行 |

**主要処理フロー**:
- **100-106行目**: フラグが有効でない場合のスキップ処理
- **107行目**: ShouldProcess確認
- **108-116行目**: DBCC TRACEOFF実行とエラーハンドリング
- **117-118行目**: 成功時のStatus設定

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

```
Disable-DbaTraceFlag
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ Get-DbaTraceFlag
    │      └─ 現在有効なトレースフラグ取得
    │
    ├─ $server.Query("DBCC TRACEOFF")
    │      └─ トレースフラグ無効化
    │
    └─ Stop-Function (dbatools内部関数)
           └─ エラーハンドリング
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ $server
                        │
TraceFlag ──────▶ Get-DbaTraceFlag ────▶ $current
                        │
                 状態確認 ─────────────▶ 有効/無効判定
                        │
                    ┌───┴───┐
                    │       │
                 無効    有効
                    │       │
                 Skipped  DBCC TRACEOFF
                    │       │
                    └───┬───┘
                        │
                 結果オブジェクト ─────▶ PSCustomObject
                                              │
                                              ├─ SourceServer
                                              ├─ InstanceName
                                              ├─ SqlInstance
                                              ├─ TraceFlag
                                              ├─ Status
                                              ├─ Notes
                                              └─ DateTime
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Disable-DbaTraceFlag.ps1 | `public/Disable-DbaTraceFlag.ps1` | ソース | メインコマンド実装 |
| Disable-DbaTraceFlag.Tests.ps1 | `tests/Disable-DbaTraceFlag.Tests.ps1` | テスト | Pester v5テストファイル |
| Enable-DbaTraceFlag.ps1 | `public/Enable-DbaTraceFlag.ps1` | ソース | トレースフラグ有効化（対になるコマンド） |
| Get-DbaTraceFlag.ps1 | `public/Get-DbaTraceFlag.ps1` | ソース | トレースフラグ取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続関数 |
