# 画面設計書 162-プロセス管理

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるプロセス管理機能（Get-DbaProcess/Stop-DbaProcess）の画面設計書です。SQL Serverで実行中のプロセスとセッションの詳細情報を取得し、必要に応じてプロセスを終了（KILL）する機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：SQL Serverの運用においてアクティブな接続の監視と管理は重要な業務です。ブロッキングの解消、暴走クエリの停止、不正なアプリケーション接続の特定、データベースアクセスの監査など、多岐にわたる運用タスクに対応します。本機能は、複数のシステムビュー（DMV）からの情報を統合し、包括的なセッション情報を提供するとともに、問題のあるプロセスを安全に終了させる機能を備えています。

**画面へのアクセス方法**：PowerShellコマンドラインから `Get-DbaProcess` または `Stop-DbaProcess` コマンドレットを実行してアクセスします。Get-DbaProcessの出力をStop-DbaProcessにパイプで渡すことで、対象を確認してから終了させる安全なワークフローが可能です。

**主要な操作・処理内容**：
1. SQL Serverインスタンスに接続し、sys.dm_exec_sessions/connections/endpointsを結合クエリ
2. SMOのEnumProcessesメソッドでプロセス一覧を取得
3. ログイン名、ホスト名、プログラム名、データベース、SPID等でフィルタリング
4. 最終実行クエリ、ネットワーク情報、認証方式等の詳細情報を付加
5. 必要に応じてKILLコマンドでプロセスを終了

**画面遷移**：Get-DbaProcessの出力はStop-DbaProcessにパイプで渡すことができ、連携した操作が可能です。

**権限による表示制御**：VIEW SERVER STATE権限が必要です。sysadmin権限があれば全プロセスの詳細情報を取得可能。ALTER ANY CONNECTION権限があればプロセス終了が可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 139 | Get-DbaProcess | 主機能 | プロセスの取得 |
| 236 | Stop-DbaProcess | 主機能 | プロセスの停止 |
| 327 | Connect-DbaInstance | 内部呼出 | SQL Serverインスタンスへの接続 |

## 画面種別

CLI（コマンドラインインターフェース）- 監視・管理

## URL/ルーティング

PowerShellコマンド: `Get-DbaProcess`, `Stop-DbaProcess`

## 入出力項目

### Get-DbaProcess 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 |
| Spid | int[] | No | 取得対象のセッションID |
| ExcludeSpid | int[] | No | 除外するセッションID |
| Database | string[] | No | データベースでフィルタリング |
| Login | string[] | No | ログイン名でフィルタリング |
| Hostname | string[] | No | ホスト名でフィルタリング |
| Program | string[] | No | プログラム名でフィルタリング |
| ExcludeSystemSpids | switch | No | システムSPID(1-50)を除外 |
| Intersect | switch | No | フィルタ条件をAND結合（デフォルトはOR） |
| EnableException | switch | No | 例外を有効化 |

### Stop-DbaProcess 入力パラメータ

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

*SqlInstanceまたはInputObjectのいずれかが必須

### 出力項目（Get-DbaProcess）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Spid | int | セッションID（SPID） |
| Login | string | ログイン名 |
| LoginTime | DateTime | ログイン日時 |
| Host | string | クライアントホスト名 |
| Database | string | 接続中のデータベース |
| BlockingSpid | int | ブロック元のSPID |
| Program | string | クライアントアプリケーション名 |
| Status | string | セッション状態（sleeping/running等） |
| Command | string | 実行中のT-SQLコマンド |
| Cpu | int | CPU時間（ミリ秒） |
| MemUsage | int | メモリ使用量（ページ単位） |
| LastRequestStartTime | DateTime | 最終リクエスト開始日時 |
| LastRequestEndTime | DateTime | 最終リクエスト終了日時 |
| MinutesAsleep | int | 最終リクエスト終了からの経過分 |
| ClientNetAddress | string | クライアントIPアドレス |
| NetTransport | string | ネットワークトランスポート |
| EncryptOption | string | 暗号化設定 |
| AuthScheme | string | 認証スキーム（NTLM/Kerberos等） |
| NetPacketSize | int | ネットワークパケットサイズ |
| ClientVersion | int | クライアントライブラリバージョン |
| HostProcessId | int | クライアント側のプロセスID |
| IsSystem | bool | システムセッションフラグ |
| EndpointName | string | エンドポイント名 |
| IsDac | bool | 専用管理者接続フラグ |
| LastQuery | string | 最終実行クエリテキスト |

### 出力項目（Stop-DbaProcess）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | string | SQL Serverインスタンス名 |
| Spid | int | 終了したセッションID |
| Login | string | ログイン名 |
| Host | string | ホスト名 |
| Database | string | データベース名 |
| Program | string | プログラム名 |
| Status | string | 常に"Killed" |

## 表示項目

Get-DbaProcessはSelect-DefaultViewにより主要プロパティのみがデフォルト表示されます。全プロパティを表示するには `Select-Object *` を使用します。

## イベント仕様

### 1-Get-DbaProcess実行

1. **SQL Server接続**（行150-154）: Connect-DbaInstanceでSQL Serverに接続
2. **追加情報クエリ実行**（行156-182）: sys.dm_exec_sessions/connections/endpointsを結合したクエリ実行
3. **EnumProcesses呼び出し**（行186）: SMOメソッドでプロセス一覧取得
4. **フィルタリング処理**（行188-234）: 各種条件でプロセスをフィルタリング
5. **プロパティ付加**（行260-281）: Add-Memberで追加情報を付加して出力

### 2-Stop-DbaProcess実行

1. **対象プロセス取得**（行130-135）: InputObjectがなければGet-DbaProcessで取得
2. **自己セッション除外**（行147-149）: 自分自身のセッションはスキップ
3. **KillProcess実行**（行153-154）: SMOのKillProcessメソッドで終了
4. **結果出力**（行155-163）: 終了したプロセス情報をオブジェクトとして出力

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| プロセス取得 | sys.dm_exec_sessions | SELECT | セッション情報の参照 |
| プロセス取得 | sys.dm_exec_connections | SELECT | 接続情報の参照 |
| プロセス取得 | sys.endpoints | SELECT | エンドポイント情報の参照 |
| プロセス終了 | - | KILL | 指定SPIDのセッション終了 |

### テーブル別更新項目詳細

#### sys.dm_exec_sessions（参照のみ）

| 操作 | 項目（カラム名） | 取得条件 | 備考 |
|-----|-----------------|----------|------|
| SELECT | session_id, login_time, host_process_id, client_version等 | 全セッション | 詳細情報取得用 |

## メッセージ仕様

| メッセージタイプ | 条件 | メッセージ内容 |
|-----------------|------|---------------|
| Warning | 自己セッション終了試行時 | "Skipping spid {spid} because you cannot use KILL to kill your own process." |
| Error | 接続失敗時 | "Failure" - ConnectionError |
| Error | 終了失敗時 | "Couldn't kill spid {spid}." |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server接続失敗 | Stop-Functionでエラーを記録し、次のインスタンスの処理を継続 |
| 自己セッション終了試行 | 警告メッセージを出力してスキップ |
| KILL失敗 | Stop-Functionでエラーを記録して継続 |
| 不正なInputObject | Stop-Functionでエラーを出力して処理終了 |

## 備考

- Get-DbaProcessとStop-DbaProcessをパイプで連携させることで、確認してから終了する安全なワークフローが構築可能
- システムSPID（1-50）は -ExcludeSystemSpids で除外可能
- SQL Server 2005以降で追加情報（LastQuery等）が取得可能（行178-182）
- ブロッキングチェーンの調査には -Spid パラメータで指定SPIDとそれをブロックしているSPIDの両方が返される

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造とDMVから取得する情報の関係を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaProcess.ps1 | `public/Get-DbaProcess.ps1` | 行72-109の.OUTPUTS セクションで出力プロパティを確認 |

**読解のコツ**: SMO Process オブジェクトにAdd-Memberで追加プロパティを付加している点に注目。

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

Get-DbaProcessの主要処理フローを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaProcess.ps1 | `public/Get-DbaProcess.ps1` | 行133-146のパラメータ定義 |
| 2-2 | Get-DbaProcess.ps1 | `public/Get-DbaProcess.ps1` | 行156-176のDMVクエリ |

**主要処理フロー**:
1. **行150-154**: Connect-DbaInstanceで接続
2. **行156-176**: セッション詳細情報を取得するSQLクエリ（sys.dm_exec_sessions/connections/endpoints結合）
3. **行186**: EnumProcesses()でプロセス一覧取得

#### Step 3: フィルタリング処理を理解する

各種条件によるフィルタリング処理の実装を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaProcess.ps1 | `public/Get-DbaProcess.ps1` | 行188-234のフィルタリングロジック |

**主要処理フロー**:
- **行188-209**: -Intersectフラグによる条件結合方式の切り替え（AND/OR）
- **行211-229**: 各フィルタ条件の適用
- **行232-238**: システムSPID除外とExcludeSpid処理

#### Step 4: Stop-DbaProcess処理を理解する

プロセス終了処理の実装を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Stop-DbaProcess.ps1 | `public/Stop-DbaProcess.ps1` | 行127-169のプロセス終了処理 |

**主要処理フロー**:
- **行130-135**: InputObjectがなければGet-DbaProcessを呼び出し
- **行147-149**: 自己セッション保護
- **行153-154**: KillProcess()メソッドでセッション終了

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

```
Get-DbaProcess
    |
    +-- Connect-DbaInstance (行150)
    |       └── SQL Serverへの接続確立
    |
    +-- server.Query() (行179)
    |       └── DMV結合クエリ実行
    |
    +-- server.EnumProcesses() (行186)
    |       └── SMOプロセス一覧取得
    |
    +-- フィルタリング処理 (行188-238)
    |       +-- Where-Object (複数)
    |       └── 条件による絞り込み
    |
    └-- Add-Member & Select-DefaultView (行260-281)
            └── プロパティ付加と出力

Stop-DbaProcess
    |
    +-- Get-DbaProcess (行134)
    |       └── InputObjectがない場合の取得
    |
    +-- 自己セッションチェック (行147)
    |       └── 自分のSPIDをスキップ
    |
    └-- server.KillProcess() (行154)
            └── セッション終了
```

### データフロー図

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

SqlInstance ─────────────┐
                         │
Login/Hostname/Program ──┼──> Connect-DbaInstance
                         │         │
                         │         v
                         │    DMVクエリ実行 ──────> 追加セッション情報
                         │         │
                         │         v
                         │    EnumProcesses() ───> SMOプロセスオブジェクト
                         │         │
                         │         v
                         └──> フィルタリング
                                   │
                                   v
                              Add-Member
                                   │
                                   v
                              出力オブジェクト ──> [Stop-DbaProcess]
                                                        │
                                                        v
                                                   KillProcess()
                                                        │
                                                        v
                                                   終了確認出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaProcess.ps1 | `public/Get-DbaProcess.ps1` | ソース | プロセス取得の実装 |
| Stop-DbaProcess.ps1 | `public/Stop-DbaProcess.ps1` | ソース | プロセス終了の実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
