# 機能設計書 366-Get-DbaInstanceProtocol

## 概要

本ドキュメントは、SQL Serverインスタンスのネットワークプロトコル構成を取得するための dbatools コマンド `Get-DbaInstanceProtocol` の機能設計を記述する。

### 本機能の処理概要

`Get-DbaInstanceProtocol` は、ターゲットコンピュータからSQL Serverインスタンスのネットワークプロトコル（TCP/IP、Named Pipes、Shared Memory、VIA）の構成と状態を取得するコマンドである。クライアントプロトコルではなく、サーバー側のプロトコル設定を対象とする。

**業務上の目的・背景**：SQL Server接続問題のトラブルシューティングにおいて、サーバー側のネットワークプロトコル設定を確認することは必須である。SQL Server Configuration Managerを使用した手動確認は非効率であり、複数サーバー・複数インスタンスの構成を一括で監査することができない。また、セキュリティハードニングの一環として、不要なプロトコルを特定し無効化する必要がある。

**機能の利用シーン**：
- SQL Server接続問題のトラブルシューティング
- セキュリティ監査でのプロトコル設定確認
- 不要なプロトコル（VIA等）の特定と無効化
- 複数インスタンスのプロトコル構成標準化確認

**主要な処理内容**：
1. ターゲットコンピュータ名の解決（Resolve-DbaNetworkName）
2. SQL Server WMI名前空間の検出（ComputerManagement*）
3. ServerNetworkProtocol CIMクラスの照会
4. Enable()/Disable()メソッドの動的追加
5. 結果のフォーマットと出力

**関連システム・外部連携**：SQL Server WMI Provider（root\Microsoft\SQLServer\ComputerManagement*）

**権限による制御**：対象コンピュータのローカル管理者権限が必要

## 関連画面

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

## 機能種別

情報取得 / 構成管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | 対象コンピュータ名（デフォルト: ローカル） | パイプライン対応 |
| Credential | PSCredential | No | 接続資格情報 | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- SQL Server WMI Provider: root\Microsoft\SQLServer\ComputerManagement*\ServerNetworkProtocol

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | コンピュータ名（PSComputerNameのエイリアス） |
| InstanceName | String | SQL Serverインスタンス名 |
| DisplayName | String | プロトコル表示名（TCP/IP、Named Pipes等） |
| Name | String | プロトコル技術名 |
| MultiIP | Boolean | 複数IP構成サポート |
| IsEnabled | Boolean | プロトコルが有効かどうか |

### 出力先

PowerShellパイプライン（WMI ServerNetworkProtocol オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. Process ブロック - 各ComputerNameに対して
   └─ Resolve-DbaNetworkName でコンピュータ名を解決
       └─ 解決失敗: 警告出力・スキップ
   └─ ComputerManagement名前空間の検出
       └─ SELECT * FROM __NAMESPACE WHERE Name Like 'ComputerManagement%'
   └─ ServerNetworkProtocolが存在する名前空間を特定
       └─ 各名前空間でServerNetworkProtocol照会
   └─ 最新の名前空間からServerNetworkProtocol取得
   └─ 動的メソッドの追加:
       ├─ Enable() (ScriptMethod): Invoke-CimMethod SetEnable
       └─ Disable() (ScriptMethod): Invoke-CimMethod SetDisable
   └─ Select-DefaultViewで出力整形
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[各ComputerNameループ]
    B --> C[Resolve-DbaNetworkName]
    C --> D{解決成功?}
    D -->|No| E[警告: 接続失敗]
    E --> B
    D -->|Yes| F[WMI名前空間検索]
    F --> G{名前空間取得成功?}
    G -->|No| H[エラー: 名前空間なし]
    H --> B
    G -->|Yes| I[ServerNetworkProtocol存在確認]
    I --> J{存在する名前空間?}
    J -->|No| K[エラー: プロトコルなし]
    K --> B
    J -->|Yes| L[最新名前空間選択]
    L --> M[ServerNetworkProtocol取得]
    M --> N{取得成功?}
    N -->|No| O[警告出力]
    O --> B
    N -->|Yes| P[Enable/Disable追加]
    P --> Q[各プロトコル出力]
    Q --> B
    B --> R{次のComputer?}
    R -->|Yes| B
    R -->|No| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ローカル管理者必須 | 対象コンピュータのローカル管理者権限が必要 | 常に |
| BR-02 | SQL 2005以上 | ComputerManagement名前空間はSQL Server 2005以上で利用可能 | 常に |
| BR-03 | 名前空間選択 | ServerNetworkProtocolが存在する最新の名前空間を使用 | 複数名前空間存在時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 読取 | WMI ServerNetworkProtocol | SELECT (WMI) | サーバープロトコル構成取得 |
| 更新 | WMI ServerNetworkProtocol | SetEnable/SetDisable | Enable()/Disable()メソッド実行時 |

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

SQLデータベースへの操作なし（WMI経由）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | 名前空間取得失敗 | ネットワーク接続確認 |
| - | WMIエラー | ComputerManagement名前空間なし | SQL Server 2005以上をインストール |
| - | 権限エラー | ローカル管理者権限なし | 適切な資格情報を指定 |

### リトライ仕様

リトライ処理は実装されていない

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

WMI操作のため、SQLトランザクションは使用しない

## パフォーマンス要件

特に定義なし。WMI照会のためネットワーク遅延に依存。

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

- ローカル管理者権限が必要
- 資格情報はPSCredentialオブジェクトで安全に取り扱う
- Enable()/Disable()はSQL Serverの再起動が必要な場合がある

## 備考

- SQL Server 2005以上が必要
- Enable()/Disable()メソッドの戻り値は0が成功
- プロトコル変更後、SQL Serverサービスの再起動が必要な場合がある
- 複数インスタンスがある場合、各インスタンスのプロトコルが出力される

---

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

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

### 推奨読解順序

#### Step 1: パラメータ定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaInstanceProtocol.ps1 | `public/Get-DbaInstanceProtocol.ps1` | paramブロック（76-83行目）でパラメータ構造を確認 |

**主要処理フロー**:
- **78-80行目**: ComputerNameパラメータ（ValueFromPipeline、エイリアス定義）

#### Step 2: 名前空間検出と選択を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaInstanceProtocol.ps1 | `public/Get-DbaInstanceProtocol.ps1` | processブロック（85-114行目）で名前空間検出ロジックを確認 |

**主要処理フロー**:
- **91-104行目**: ComputerManagement名前空間の取得（エラーハンドリング付き）
- **107行目**: ServerNetworkProtocolが存在する名前空間のフィルタリング

#### Step 3: プロトコル取得と拡張を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaInstanceProtocol.ps1 | `public/Get-DbaInstanceProtocol.ps1` | processブロック（115-134行目）でプロトコル取得と動的メンバー追加を確認 |

**主要処理フロー**:
- **119行目**: Get-DbaCmObjectでServerNetworkProtocol取得
- **121行目**: Enableスクリプトメソッド追加
- **122行目**: Disableスクリプトメソッド追加
- **123行目**: Select-DefaultViewで出力整形

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

```
Get-DbaInstanceProtocol
    │
    ├─ Resolve-DbaNetworkName (コンピュータ名解決)
    │
    ├─ Get-DbaCmObject -Namespace root\Microsoft\SQLServer
    │      └─ __NAMESPACE照会
    │
    ├─ Get-DbaCmObject -ClassName ServerNetworkProtocol (存在確認)
    │
    ├─ Get-DbaCmObject -ClassName ServerNetworkProtocol (データ取得)
    │
    ├─ Add-Member -MemberType ScriptMethod (Enable)
    │
    ├─ Add-Member -MemberType ScriptMethod (Disable)
    │
    └─ Select-DefaultView
```

### データフロー図

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

ComputerName ───────────▶ Resolve-DbaNetworkName
                                │
                                ▼
                         WMI名前空間検索
                                │
                                ▼
                         名前空間フィルタリング
                                │
                                ▼
                         ServerNetworkProtocol取得
                                │
                                ▼
                         動的メソッド追加 ───────▶ WMI Object
                                                   (InstanceName, DisplayName, IsEnabled)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaInstanceProtocol.ps1 | `public/Get-DbaInstanceProtocol.ps1` | ソース | メインコマンド実装 |
| Get-DbaClientProtocol.ps1 | `public/Get-DbaClientProtocol.ps1` | ソース | クライアントプロトコル取得（関連コマンド） |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | コンピュータ名解決 |
| Get-DbaCmObject.ps1 | `private/Get-DbaCmObject.ps1` | ソース | WMI/CIMオブジェクト取得 |
