# 機能設計書 333-Get-DbaConnectedInstance

## 概要

本ドキュメントは、dbatoolsの接続プールにキャッシュされているSQL Serverインスタンス接続を取得する機能「Get-DbaConnectedInstance」の設計仕様を記載する。

### 本機能の処理概要

Get-DbaConnectedInstanceは、現在のPowerShellセッションでアクティブまたはキャッシュされているすべてのSQL Server接続を表示する機能である。接続プールの状態を可視化し、接続管理やトラブルシューティングを支援する。

**業務上の目的・背景**：dbatoolsコマンド（Connect-DbaInstanceなど）でSQL Serverに接続すると、その接続は再利用のために内部キャッシュに保存される。長時間稼働するスクリプトや多数のインスタンスに接続するセッションでは、キャッシュ内の接続状態を把握することが重要である。本機能は、キャッシュ内の接続を可視化し、Disconnect-DbaInstanceでクリーンアップする前の確認や、接続関連の問題のトラブルシューティングを支援する。

**機能の利用シーン**：
- Disconnect-DbaInstanceで接続をクリーンアップする前に、アクティブな接続を確認する際
- 長時間稼働スクリプトで接続プールの状態を監視する際
- 接続関連の問題をトラブルシューティングする際
- 接続プーリングが有効かどうかを確認する際

**主要な処理内容**：
1. 内部接続ハッシュテーブル（$script:connectionhash）をイテレート
2. 各接続からインスタンス名、接続タイプ、プーリング状態を抽出
3. 接続文字列を安全にマスク処理
4. カスタムオブジェクトとしてパイプラインに出力

**関連システム・外部連携**：
- dbatoolsモジュール内部の接続キャッシュ
- SQL Server SMO Server オブジェクト
- System.Data.SqlClient.SqlConnection オブジェクト

**権限による制御**：
特別な権限は不要。現在のセッションのキャッシュ情報のみを表示。

## 関連画面

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

## 機能種別

情報取得 / 接続管理

## 入力仕様

### 入力パラメータ

本関数はパラメータを持たない。

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | パラメータなし | - |

### 入力データソース

- $script:connectionhash（dbatoolsモジュールスコープの接続キャッシュ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | string | SQL Serverインスタンス識別子 |
| ConnectionType | string | 接続オブジェクトの.NET型名 |
| ConnectionObject | object | 実際の接続オブジェクト |
| Pooled | bool | 接続プーリングが有効か |
| ConnectionString | string | マスク処理された接続文字列 |

### 出力先

パイプライン出力（PSCustomObject）

デフォルト表示プロパティ：SqlInstance, ConnectionType, ConnectionObject, Pooled

## 処理フロー

### 処理シーケンス

```
1. 接続ハッシュテーブルのイテレート
   └─ $script:connectionhash.Keys をループ処理

2. インスタンス名の抽出
   └─ DataSourceプロパティまたはNameプロパティから取得

3. プーリング状態の判定
   └─ NonPooledConnectionプロパティを確認

4. 接続文字列のマスク処理
   └─ Hide-ConnectionString関数で機密情報を隠蔽

5. カスタムオブジェクト作成と出力
   └─ Select-DefaultViewで表示プロパティを設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[connectionhash.Keysを取得]
    B --> C{キーが存在?}
    C -->|No| H[終了]
    C -->|Yes| D[接続オブジェクトを取得]
    D --> E{DataSourceあり?}
    E -->|Yes| F[DataSourceをインスタンス名に]
    E -->|No| G[Nameをインスタンス名に]
    F --> I[NonPooledConnectionを確認]
    G --> I
    I --> J{NonPooled?}
    J -->|Yes| K[Pooled = false]
    J -->|No| L[Pooled = true]
    K --> M[接続文字列をマスク]
    L --> M
    M --> N[PSCustomObject作成]
    N --> O[パイプライン出力]
    O --> P{次のキー?}
    P -->|Yes| D
    P -->|No| H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | インスタンス名取得優先順位 | DataSourceプロパティを優先、なければNameプロパティを使用 | すべての接続 |
| BR-002 | プーリング判定 | NonPooledConnectionがtrueの場合はPooled=false | すべての接続 |
| BR-003 | 接続文字列マスク | Hide-ConnectionString関数で資格情報を隠蔽 | すべての接続 |

### 計算ロジック

特になし

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

本機能はデータベースへのアクセスを行わない（キャッシュ情報のみを参照）。

## エラー処理

### エラーケース一覧

本関数は例外処理を含まない。接続ハッシュが空の場合は何も出力しない。

### リトライ仕様

リトライは不要。

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

本機能はデータ変更を行わないため、トランザクション管理は不要。

## パフォーマンス要件

接続キャッシュの参照のみのため、即座に応答する。

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

- 接続文字列は Hide-ConnectionString 関数でマスク処理される
- Select-Object * を使用すると完全な接続文字列が表示される可能性があるため注意

## 備考

- 出力される接続オブジェクトはSMO Serverオブジェクトまたは生のSqlConnectionオブジェクトの場合がある
- Select-Object * でConnectionStringを含むすべてのプロパティを表示可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaConnectedInstance.ps1 | `public/Get-DbaConnectedInstance.ps1` | 出力オブジェクト構造（22-33行目の.OUTPUTS） |

**読解のコツ**: $script:connectionhashはdbatoolsモジュール内部で管理されるハッシュテーブルで、接続文字列をキーとして接続オブジェクトを格納している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaConnectedInstance.ps1 | `public/Get-DbaConnectedInstance.ps1` | 関数全体（47-71行目） |

**主要処理フロー**:
1. **50行目**: connectionhash.Keysのループ開始
2. **51-55行目**: インスタンス名の抽出（DataSourceまたはName）
3. **57-61行目**: プーリング状態の判定
4. **62-68行目**: PSCustomObjectの作成と出力

#### Step 3: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Hide-ConnectionString | `private/Hide-ConnectionString.ps1` | 接続文字列のマスク処理 |
| 3-2 | Select-DefaultView | `private/Select-DefaultView.ps1` | デフォルト表示プロパティの設定 |

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

```
Get-DbaConnectedInstance
    │
    ├─ $script:connectionhash（モジュールスコープ変数参照）
    │
    ├─ Hide-ConnectionString
    │      └─ 接続文字列から資格情報をマスク
    │
    └─ Select-DefaultView
           └─ 表示プロパティを設定
```

### データフロー図

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

$script:connectionhash ──▶ foreach ループ
                              │
                              ├─ インスタンス名抽出
                              │
                              ├─ プーリング判定
                              │
                              ├─ Hide-ConnectionString
                              │
                              ├─ PSCustomObject作成
                              │
                              └─ Select-DefaultView ──▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaConnectedInstance.ps1 | `public/Get-DbaConnectedInstance.ps1` | ソース | メイン関数 |
| Hide-ConnectionString.ps1 | `private/functions/Hide-ConnectionString.ps1` | ソース | 接続文字列マスク |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1` | ソース | デフォルト表示設定 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | 接続キャッシュの生成元 |
| Disconnect-DbaInstance.ps1 | `public/Disconnect-DbaInstance.ps1` | ソース | 接続キャッシュのクリーンアップ |
