# 機能設計書 310-Stop-DbaXESession

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Stop-DbaXESession` コマンドレットの機能設計を記述する。このコマンドレットは、SQL Serverインスタンス上で実行中の拡張イベント(Extended Events)セッションを停止する機能を提供する。

### 本機能の処理概要

`Stop-DbaXESession` は、診断データを収集中またはSQL Serverのアクティビティを監視中のアクティブな拡張イベントセッションを停止するコマンドレットである。特定のセッションを名前で停止、全ユーザーセッションを一括停止、またはパイプライン入力で停止対象を指定できる。

**業務上の目的・背景**：XEセッションはディスク容量、メモリ、CPUサイクルを消費する可能性がある。本機能により、不要になったセッションを停止してリソース使用量を削減したり、トラブルシューティング後のクリーンアップを行ったりできる。重要なシステムセッションを保護しながら、ユーザー作成セッションのみを安全に停止できる。

**機能の利用シーン**：
- 実行中のXEセッションを停止してリソースを解放したい場合
- トラブルシューティングセッションを終了したい場合
- 全ユーザーセッションを一括で停止したい場合
- Get-DbaXESessionでフィルタリングしたセッションを停止したい場合
- メンテナンス前に監視セッションを停止したい場合

**主要な処理内容**：
1. 対象セッションの取得（Get-DbaXESession）
2. セッションフィルタリング（Session指定またはAllSessions）
3. AllSessions時はシステムセッションを除外
4. ShouldProcess確認後、Stopメソッドでセッション停止
5. 停止後、更新されたセッション情報を出力

**関連システム・外部連携**：Get-DbaXESession でセッション一覧を取得し、SMOのStopメソッドでセッションを停止。

**権限による制御**：sysadmin権限が必要。システムセッションは自動的に保護される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 84 | XEセッション管理 | 補助機能 | 拡張イベントセッションの停止 |

## 機能種別

状態変更処理（STOP）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes（ParameterSet: Session/All） | 接続先SQLインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証資格情報 | - |
| Session | object[] | Yes（ParameterSet: Session） | 停止対象セッション名 | - |
| AllSessions | switch | Yes（ParameterSet: All） | 全ユーザーセッション停止 | - |
| InputObject | Microsoft.SqlServer.Management.XEvent.Session[] | Yes（ParameterSet: Object） | パイプライン入力セッション | - |
| WhatIf | switch | No | 実行せずに動作を表示 | - |
| Confirm | switch | No | 実行前に確認 | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- ユーザー指定のセッション名
- Get-DbaXESessionからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQLインスタンスのコンピューター名 |
| InstanceName | String | SQLインスタンス名 |
| SqlInstance | String | 完全修飾インスタンス名 |
| Name | String | セッション名 |
| State | String | セッション状態（Created/Started/Stopped/Altered） |
| IsRunning | Boolean | 実行中フラグ（停止後はfalse） |
| StartTime | DateTime | セッション開始日時（停止後はnull） |
| DefinitionFileLocation | String | XML定義ファイルパス |
| MaxMemory | Int | 最大メモリ（MB） |
| EventRetentionMode | String | イベント保持モード |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Management.XEvent.Session）

## 処理フロー

### 処理シーケンス

```
1. パラメータセット判定
2. InputObject処理 または SqlInstance処理
3. セッションフィルタリング
   └─ Session指定: 名前でフィルタ
   └─ AllSessions: システムセッション除外
4. ShouldProcess確認
5. Stop-XESessions内部関数呼び出し
   └─ 実行中チェック（既に停止済みは警告）
   └─ Stop()呼び出し
6. Get-DbaXESession で更新されたセッション情報を出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{InputObject指定?}
    B -->|Yes| C{ShouldProcess?}
    B -->|No| D[各インスタンスを処理]
    C -->|Yes| E[Stop-XESessions]
    C -->|No| F[終了]
    D --> G[Get-DbaXESession]
    G --> H{Session指定?}
    H -->|Yes| I[名前でフィルタ]
    H -->|No| J{AllSessions?}
    J -->|Yes| K[システムセッション除外]
    I --> L{ShouldProcess?}
    K --> L
    L -->|Yes| E
    L -->|No| F
    E --> M[各セッションを処理]
    M --> N{IsRunning?}
    N -->|Yes| O[xe.Stop]
    N -->|No| P[警告: 既に停止]
    O --> Q{成功?}
    Q -->|Yes| R[Get-DbaXESession出力]
    Q -->|No| S[Stop-Function]
    P --> R
    R --> M
    S --> M
    M --> T{次のセッション?}
    T -->|Yes| M
    T -->|No| F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-310-01 | システムセッション保護 | system_health、telemetry_xevents、AlwaysOn_healthは対象外 | AllSessions使用時 |
| BR-310-02 | 停止済みセッションのスキップ | 既に停止済みのセッションは警告のみ | 常時 |
| BR-310-03 | 更新情報出力 | 停止後はGet-DbaXESessionで最新状態を取得して出力 | 常時 |

### 計算ロジック

- システムセッションリスト: `@('AlwaysOn_health', 'system_health', 'telemetry_xevents')`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 停止 | XEセッション | ALTER STATE | 拡張イベントセッション停止 |

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

#### 拡張イベントセッション

| 操作 | 項目 | 更新値・取得条件 | 備考 |
|-----|-----|-----------------|------|
| ALTER | State | STOP | SMO Stop()経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | StopError | セッション停止失敗 | Stop-Functionで継続 |
| - | AlreadyStopped | セッションが既に停止 | 警告メッセージ出力 |

### リトライ仕様

なし

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

なし（各セッションを個別に停止）

## パフォーマンス要件

- セッション数に比例した処理時間

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

- sysadmin権限が必要
- システムセッションは自動的に保護される

## 備考

- Get-DbaXESession と組み合わせて柔軟なフィルタリングが可能
- Start-DbaXESession と対になるコマンドレット

---

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

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

### 推奨読解順序

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

出力オブジェクト（停止後のSessionオブジェクト）の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Stop-DbaXESession.ps1 | `public/Stop-DbaXESession.ps1` | OUTPUTSセクション（53-77行目） |

**読解のコツ**: 出力はMicrosoft.SqlServer.Management.XEvent.Sessionオブジェクト。停止後の状態が反映される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Stop-DbaXESession.ps1 | `public/Stop-DbaXESession.ps1` | begin ブロック（117-140行目） |
| 2-2 | Stop-DbaXESession.ps1 | `public/Stop-DbaXESession.ps1` | process ブロック（143-164行目） |

**主要処理フロー**:
1. **119-140行目**: Stop-XESessions内部関数
2. **144-147行目**: InputObject処理
3. **149-163行目**: SqlInstance処理

#### Step 3: 内部関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Stop-DbaXESession.ps1 | `public/Stop-DbaXESession.ps1` | Stop-XESessions関数（119-140行目） |

**主要処理フロー**:
- **126行目**: IsRunningチェック
- **130行目**: Stop()呼び出し
- **136行目**: 既に停止の場合は警告
- **138行目**: Get-DbaXESessionで更新情報取得

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

```
Stop-DbaXESession
    │
    ├─ Get-DbaXESession
    │
    ├─ Where-Object（Session/AllSessionsフィルタ）
    │
    └─ Stop-XESessions（内部関数）
           │
           ├─ $Pscmdlet.ShouldProcess
           │
           ├─ $xe.Stop()
           │
           └─ Get-DbaXESession（更新情報取得）
```

### データフロー図

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

InputObject ─────────────▶ ShouldProcess確認
                                  │
SqlInstance ─────────────▶ Get-DbaXESession
      │                          │
      ▼                          ▼
Session Filter ──────────▶ Where-Object Name -in
      │                          │
AllSessions Filter ──────▶ Where-Object Name -notin システムセッション
                                  │
                                  ▼
                          Stop-XESessions
                                  │
                                  ▼
                          IsRunning確認
                                  │
          ┌───────────────────────┼───────────────────────┐
          │                                                │
          ▼                                                ▼
     Running                                         Not Running
          │                                                │
          ▼                                                ▼
     xe.Stop()                                       警告メッセージ
          │                                                │
          └────────────────────┬───────────────────────────┘
                               │
                               ▼
                          Get-DbaXESession ─────────────▶ Session Object
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Stop-DbaXESession.ps1 | `public/Stop-DbaXESession.ps1` | ソース | メインコマンドレット |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | ソース | セッション取得（依存先） |
| Start-DbaXESession.ps1 | `public/Start-DbaXESession.ps1` | ソース | 対になるセッション開始コマンド |
