# 画面設計書 98-インスタンスプロトコル

## 概要

本ドキュメントはdbatools PowerShellモジュールにおけるインスタンスプロトコル取得機能（Get-DbaInstanceProtocol）の画面設計書です。

### 本画面の処理概要

**業務上の目的・背景**：
SQL Serverのネットワークプロトコル設定は、接続性とセキュリティに直接影響する重要な構成要素です。本機能は、WMI ComputerManagement名前空間を通じてSQL Serverのネットワークプロトコル（TCP/IP、名前付きパイプ、共有メモリ、VIA）の構成とステータスを取得します。これにより、接続問題のトラブルシューティング、セキュリティコンプライアンスのための構成監査、複数インスタンスでのプロトコル設定管理が効率的に行えます。取得したプロトコルオブジェクトにはEnable()とDisable()メソッドが含まれ、SQL Server構成マネージャーを使用せずに直接プロトコル状態を管理できます。

**画面へのアクセス方法**：
PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Get-DbaInstanceProtocol -ComputerName <コンピュータ名>`

**主要な操作・処理内容**：
1. **WMI名前空間検出**：root\Microsoft\SQLServer\ComputerManagement* 名前空間を検出
2. **プロトコル情報取得**：ServerNetworkProtocolクラスからプロトコル設定を取得
3. **Enable/Disableメソッド追加**：取得オブジェクトにプロトコル有効化/無効化メソッドを追加
4. **複数コンピュータ対応**：パイプラインで複数コンピュータを一括処理

**画面遷移**：
本機能は接続トラブルシューティングやセキュリティ監査の起点として使用される。取得したプロトコルオブジェクトに対してEnable()/Disable()を呼び出すことで、プロトコル状態を変更できる。

**権限による表示制御**：
- 対象コンピュータへのローカル管理者権限が必要
- WMI ComputerManagement名前空間へのアクセス権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 366 | Get-DbaInstanceProtocol | 主機能 | インスタンスプロトコルの取得 |

## 画面種別

CLI（コマンドラインインターフェース）/ ネットワーク・管理

## URL/ルーティング

PowerShellコマンド:
- `Get-DbaInstanceProtocol`

## 入出力項目

### Get-DbaInstanceProtocol パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| ComputerName | DbaInstanceParameter[] | いいえ | 対象のコンピュータ（デフォルト: $env:COMPUTERNAME） |
| Credential | PSCredential | いいえ | コンピュータ接続用の資格情報 |
| EnableException | switch | いいえ | 例外を有効化 |

## 表示項目

### 出力（WMI ServerNetworkProtocol）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverを実行しているコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| DisplayName | string | プロトコルの表示名（TCP/IP, Named Pipes, Shared Memory, VIA） |
| Name | string | SQL Server WMIで認識されるプロトコル名 |
| MultiIP | bool | 複数IP構成をサポートするかどうか |
| IsEnabled | bool | プロトコルが有効かどうか |

### 利用可能なメソッド

| メソッド名 | 戻り値 | 説明 |
|-----------|--------|------|
| Enable() | int | プロトコルを有効化（成功時は0を返す） |
| Disable() | int | プロトコルを無効化（成功時は0を返す） |

### プロトコルタイプ一覧

| プロトコル名 | DisplayName | 説明 |
|-------------|-------------|------|
| Sm | Shared Memory | 同一コンピュータ上での接続用 |
| Np | Named Pipes | 同一ネットワーク上での接続用 |
| Tcp | TCP/IP | 最も一般的なリモート接続プロトコル |
| Via | VIA | 仮想インターフェースアダプタ（廃止予定） |

## イベント仕様

### 1-プロトコル情報取得処理

1. Resolve-DbaNetworkNameでコンピュータ名を解決
2. WMI名前空間root\Microsoft\SQLServerにクエリ
3. ComputerManagement*名前空間を検出
4. ServerNetworkProtocolクラスが存在する最新の名前空間を選択
5. ServerNetworkProtocolクラスからプロトコル情報を取得
6. Enable()とDisable()スクリプトメソッドを追加
7. Select-DefaultViewでデフォルト表示プロパティを設定して出力

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

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

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| プロトコル取得 | WMI ServerNetworkProtocol | READ | WMIからの読み取り |
| Enable()呼び出し | SQL Server構成 | UPDATE | プロトコル有効化（サービス再起動が必要） |
| Disable()呼び出し | SQL Server構成 | UPDATE | プロトコル無効化（サービス再起動が必要） |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 |
|-------------|------|---------------|
| MSG001 | 情報 | Getting SQL Server namespace on {computer} |
| MSG002 | 情報 | Successfully retrieved namespaces from {Computer}. Total found: {count} |
| MSG003 | エラー | Failed to retrieve ComputerManagement namespace |
| MSG004 | 情報 | Successfully retrieved ServerNetworkProtocol data from {Computer} |
| MSG005 | エラー | Failed to retrieve Network Protocol data |
| MSG006 | エラー | No ComputerManagement namespaces found |
| MSG007 | 情報 | Getting Cim class ServerNetworkProtocol in Namespace {instanceName} on {Computer} |
| MSG008 | 警告 | Issue gathering ServerNetworkProtocol data on {Computer} |
| MSG009 | 警告 | No ComputerManagement Namespace on {Computer}. Please note that this function is available from SQL 2005 up. |
| MSG010 | 警告 | Failed to connect to {Computer} |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| 名前解決失敗 | 警告メッセージを出力し、処理を継続 |
| WMI名前空間取得失敗 | Stop-Functionでエラー出力し、処理を継続 |
| プロトコルデータ取得失敗 | Stop-Functionでエラー出力し、処理を継続 |
| 名前空間が見つからない | Stop-Functionでエラー出力し、処理を継続 |
| ServerNetworkProtocol取得失敗 | 警告メッセージを出力 |

## 備考

- SQL Server 2005以降が必要（ComputerManagement WMI名前空間が利用可能）
- ローカル管理者権限が必要
- Enable()/Disable()の変更を反映するにはSQL Serverサービスの再起動が必要
- VIAプロトコルはSQL Server 2012以降で廃止予定
- 複数インスタンスがある場合、最新のComputerManagement名前空間が使用される

---

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

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

### 推奨読解順序

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

WMI ServerNetworkProtocolオブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaInstanceProtocol.ps1 | `public/Get-DbaInstanceProtocol.ps1` | 33-51行目の.OUTPUTSセクション |

**読解のコツ**: WMIプロパティ名とSelect-DefaultViewでのエイリアス変換を理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaInstanceProtocol.ps1 | `public/Get-DbaInstanceProtocol.ps1` | 77-83行目のparamブロック |

**主要処理フロー**:
- **78-80行目**: ComputerNameはパイプライン入力対応、デフォルトはローカルコンピュータ

#### Step 3: WMI名前空間検出を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaInstanceProtocol.ps1 | `public/Get-DbaInstanceProtocol.ps1` | 85-104行目 |

**主要処理フロー**:
- **86行目**: Resolve-DbaNetworkNameでコンピュータ名解決
- **91行目**: root\Microsoft\SQLServer名前空間を指定
- **93-100行目**: Get-DbaCmObjectでComputerManagement*名前空間をクエリ

#### Step 4: プロトコル情報取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaInstanceProtocol.ps1 | `public/Get-DbaInstanceProtocol.ps1` | 105-127行目 |

**主要処理フロー**:
- **107行目**: ServerNetworkProtocolが存在する名前空間を検出（降順ソートで最新を取得）
- **119行目**: Get-DbaCmObjectでServerNetworkProtocolクラスを取得
- **121-122行目**: Enable()とDisable()スクリプトメソッドを追加
- **123行目**: Select-DefaultViewでプロパティ名をエイリアス変換して出力

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

```
Get-DbaInstanceProtocol
    │
    ├─ Resolve-DbaNetworkName
    │      └─ コンピュータ名解決
    │
    ├─ Get-DbaCmObject (名前空間クエリ)
    │      └─ root\Microsoft\SQLServer
    │             └─ ComputerManagement* 検出
    │
    ├─ Get-DbaCmObject (プロトコルチェック)
    │      └─ ServerNetworkProtocol存在確認
    │
    ├─ Get-DbaCmObject (プロトコル取得)
    │      └─ ServerNetworkProtocolクラス取得
    │
    ├─ Add-Member (Enable/Disable追加)
    │      ├─ Enable(): Invoke-CimMethod SetEnable
    │      └─ Disable(): Invoke-CimMethod SetDisable
    │
    └─ Select-DefaultView
           └─ プロパティ名エイリアス変換
```

### データフロー図

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

ComputerName ────────────▶ Resolve-DbaNetworkName
                                  │
                          ┌───────▼───────┐
                          │ root\Microsoft│
                          │ \SQLServer    │
                          └───────────────┘
                                  │
                          ┌───────▼───────┐
                          │ Computer      │
                          │ Management*   │
                          │ 名前空間検出  │
                          └───────────────┘
                                  │
                          ┌───────▼───────┐
                          │ ServerNetwork │
                          │ Protocol存在  │
                          │ チェック      │
                          └───────────────┘
                                  │
                          ┌───────▼───────┐
                          │ Get-DbaCmObject │
                          │ (Protocol取得) │
                          └───────────────┘
                                  │
                          ┌───────▼───────┐
                          │ Add-Member    │
                          │ Enable()/     │
                          │ Disable()     │
                          └───────────────┘
                                  │
                          ┌───────▼───────┐
                          │Select-Default │
                          │     View      │
                          └───────────────┘
                                  │
                                  ▼
                      [WMI ServerNetworkProtocol]
                      + Enable() method
                      + Disable() method
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaInstanceProtocol.ps1 | `public/Get-DbaInstanceProtocol.ps1` | ソース | インスタンスプロトコル取得 |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | ネットワーク名解決 |
| Get-DbaCmObject.ps1 | `internal/functions/Get-DbaCmObject.ps1` | ソース | WMI/CIMオブジェクト取得 |
