# 機能設計書 236-Stop-DbaProcess

## 概要

本ドキュメントは、dbatools PowerShellモジュールのStop-DbaProcess関数に関する機能設計書です。この関数はSQL Serverプロセス（SPID）を終了し、ブロッキングの解決、暴走クエリの停止、接続のクリーンアップを行います。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverでブロッキング状況が発生した場合、リソースを大量消費するクエリが実行されている場合、アプリケーションやユーザーからの放棄された接続をクリーンアップする必要がある場合に、特定のプロセスを終了する手段を提供します。

**機能の利用シーン**：ブロッキング状況の解決時、暴走クエリの停止時、特定ログインの全接続切断時、特定ホスト・プログラムからの接続終了時、データベースメンテナンス前のユーザー切断時に使用されます。

**主要な処理内容**：
1. 対象プロセスの特定（SPID、ログイン、ホスト名、プログラム、データベースで絞り込み）
2. 自身のセッションの除外（自分自身をKILLすることを防止）
3. 除外SPIDの適用
4. KillProcess()メソッドによるプロセス終了
5. 終了結果をオブジェクトとして返却

**関連システム・外部連携**：SQL Server Management Objects (SMO)を使用してプロセスを終了します。

**権限による制御**：ALTER ANY CONNECTION権限が必要です。

## 関連画面

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

## 機能種別

プロセス管理処理（Process Management / KILL Command）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter | Yes* | 対象SQL Serverインスタンス | ParameterSet "Server"で必須 |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 | - |
| Spid | int[] | No | 終了する特定のSPID | - |
| ExcludeSpid | int[] | No | 除外するSPID | - |
| Database | string[] | No | 対象データベース名 | - |
| Login | string[] | No | 対象ログイン名 | - |
| Hostname | string[] | No | 対象ホスト名 | - |
| Program | string[] | No | 対象プログラム名 | - |
| InputObject | object[] | Yes* | Get-DbaProcessからのパイプライン入力 | ParameterSet "Process"で必須 |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- PowerShellコマンドライン引数
- Get-DbaProcessからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | string | SQL Serverインスタンス名 |
| Spid | int | 終了されたSPID |
| Login | string | ログイン名 |
| Host | string | ホスト名 |
| Database | string | データベース名 |
| Program | string | プログラム名 |
| Status | string | ステータス（常に"Killed"） |

### 出力先

- パイプラインにPSCustomObjectとして出力

## 処理フロー

### 処理シーケンス

```
1. プロセス取得
   └─ InputObject未指定時はGet-DbaProcessで取得
2. 各プロセスの処理
   ├─ 親サーバーオブジェクトの確認
   ├─ 自セッションチェック（自分自身はスキップ）
   ├─ ShouldProcess確認
   └─ KillProcess()実行
3. 結果出力
   └─ 成功時はPSCustomObjectを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{InputObject指定?}
    B -->|No| C[Get-DbaProcessで取得]
    B -->|Yes| D[InputObject使用]
    C --> E[各セッションをループ]
    D --> E
    E --> F{親サーバーあり?}
    F -->|No| G[エラー終了]
    F -->|Yes| H{自セッション?}
    H -->|Yes| I[警告・スキップ]
    H -->|No| J{ShouldProcess?}
    J -->|No| K[次のセッション]
    J -->|Yes| L[KillProcess実行]
    L --> M{成功?}
    M -->|Yes| N[結果オブジェクト出力]
    M -->|No| O[エラー処理・Continue]
    N --> K
    O --> K
    I --> K
    K --> P{次のセッションあり?}
    P -->|Yes| E
    P -->|No| Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 自セッション保護 | 自分自身のSPIDはKILLできない | 常時 |
| BR-002 | 除外SPID優先 | ExcludeSpid指定時は該当SPIDをスキップ | ExcludeSpid指定時 |
| BR-003 | パイプライン入力 | Get-DbaProcessからの入力を受け付け | InputObject指定時 |
| BR-004 | フィルタ適用 | Spid、Login、Hostname、Program、Databaseでフィルタ | 各パラメータ指定時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| プロセス終了 | - | KILL | SMO KillProcess()メソッド経由 |

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

#### sys.dm_exec_sessions（参照・SMO経由）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| KILL | session_id | 指定されたSPID | KillProcess()で終了 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidData | データエラー | パイプライン入力が不正 | Get-DbaProcessからの入力を確認 |
| KillError | 終了エラー | プロセス終了失敗 | 権限・SPID存在確認 |

### リトライ仕様

リトライ処理は実装されていません。エラー発生時はStop-Functionで処理を継続（Continue）します。

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

KILLコマンドは即時実行されます。対象セッションのアクティブなトランザクションはロールバックされます。

## パフォーマンス要件

- プロセス終了は即時実行
- 複数SPID指定時は順次処理

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

- ALTER ANY CONNECTION権限が必要
- SqlCredential使用時はSecureStringで資格情報を保護
- ShouldProcess対応で誤操作を防止

## 備考

- Get-DbaProcessと組み合わせて使用することを推奨
- 自分自身のセッションをKILLしようとすると警告が表示されスキップされます

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Stop-DbaProcess.ps1 | `public/Stop-DbaProcess.ps1` | パラメータ定義（112-125行目） |
| 1-2 | Stop-DbaProcess.ps1 | `public/Stop-DbaProcess.ps1` | 出力オブジェクト構造（155-163行目） |

**読解のコツ**: ParameterSetによりServerモード（直接指定）とProcessモード（パイプライン入力）の2つの使用方法があります。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Stop-DbaProcess.ps1 | `public/Stop-DbaProcess.ps1` | process block（127-169行目） |

**主要処理フロー**:
1. **128行目**: Test-FunctionInterruptで中断確認
2. **130-135行目**: InputObject未指定時はGet-DbaProcessで取得
3. **137-143行目**: 親サーバーオブジェクト確認
4. **145-150行目**: 自セッションチェック（警告・スキップ）
5. **152-166行目**: ShouldProcess確認とKillProcess実行
6. **155-163行目**: 成功時の結果オブジェクト生成

#### Step 3: 関連コマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaProcess.ps1 | `public/Get-DbaProcess.ps1` | 入力元となる機能 |

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

```
Stop-DbaProcess
    │
    ├─ Test-FunctionInterrupt
    │      └─ 中断確認
    │
    ├─ Get-DbaProcess (条件付き)
    │      └─ 対象プロセス取得
    │
    └─ sourceserver.KillProcess(spid)
           └─ KILL $spid 実行
```

### データフロー図

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

SqlInstance ──────┐
                  │
Spid ─────────────┤
                  │
Login ────────────┤
                  ├──▶ Stop-DbaProcess ─────────────────▶ PSCustomObject
Hostname ─────────┤         │                              (SqlInstance,
                  │         ├─ Get-DbaProcess               Spid,
Program ──────────┤         │     └─ 対象プロセス取得        Login,
                  │         │                               Host,
Database ─────────┤         └─ KillProcess                  Database,
                  │               └─ KILL実行               Program,
InputObject ──────┘                                         Status)

[SQL Server] ◄───── SMO KillProcess ─────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Stop-DbaProcess.ps1 | `public/Stop-DbaProcess.ps1` | ソース | メイン関数実装 |
| Get-DbaProcess.ps1 | `public/Get-DbaProcess.ps1` | ソース | 入力元となる機能 |
| Test-FunctionInterrupt.ps1 | `private/functions/Test-FunctionInterrupt.ps1` | ソース | 中断確認ヘルパー |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理ヘルパー |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | メッセージ出力ヘルパー |
| Stop-DbaProcess.Tests.ps1 | `tests/Stop-DbaProcess.Tests.ps1` | テスト | 単体テスト |
