# 画面設計書 130-ネットワーク設定

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるネットワーク設定管理機能の設計仕様を定義する。SQL Serverのネットワークプロトコル、TCP/IP設定、SSL証明書構成をSQL Server構成マネージャー相当の情報としてスクリプト化し、ネットワーク接続のトラブルシューティング、セキュリティ監査、コンプライアンスレポートを支援する。

### 本画面の処理概要

**業務上の目的・背景**：SQL Serverのネットワーク構成は、接続性とセキュリティに直接影響する。共有メモリ、名前付きパイプ、TCP/IPプロトコルの状態、ポート構成、IPアドレスバインディング、SSL証明書設定などの情報は、接続問題のトラブルシューティング、ファイアウォールルールの設定、セキュリティ監査に不可欠である。本機能群は、SQL Server WMIとWindowsレジストリを照会して、構成マネージャーと同等の情報をPowerShellで取得・変更する。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドレットを実行してアクセスする。
```powershell
Get-DbaNetworkConfiguration -SqlInstance <インスタンス名>
Set-DbaNetworkConfiguration -SqlInstance <インスタンス名> -EnableProtocol TcpIp
```

**主要な操作・処理内容**：
1. **Get-DbaNetworkConfiguration**: SQL WMI ManagedComputerオブジェクトを使用してサーバープロトコル情報を取得。レジストリからSSL証明書、暗号化設定、SPN設定を取得
2. **Set-DbaNetworkConfiguration**: プロトコルの有効化/無効化、ポート設定の変更、IPアドレスバインディングの構成を実行

**画面遷移**：本機能はCLIコマンドであり、GUI画面遷移は存在しない。Get-DbaNetworkConfigurationで現状確認後、Set-DbaNetworkConfigurationで設定変更を行う流れが一般的。

**権限による表示制御**：
- ターゲットサーバーへの管理者権限が必要
- PowerShellリモーティング権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 368 | Get-DbaNetworkConfiguration | 主機能 | ネットワーク設定の取得 |
| 373 | Set-DbaNetworkConfiguration | 主機能 | ネットワーク設定の変更 |

## 画面種別

CLI（コマンドラインインターフェース） - 複数コマンドレット

## URL/ルーティング

PowerShellコマンドレット:
- `Get-DbaNetworkConfiguration`
- `Set-DbaNetworkConfiguration`

## 入出力項目

### Get-DbaNetworkConfiguration パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | - | SQL Serverインスタンス |
| Credential | PSCredential | No | - | Windows資格情報 |
| OutputType | string | No | Full | 出力タイプ（Full/ServerProtocols/TcpIpProperties/TcpIpAddresses/Certificate） |
| EnableException | switch | No | $false | 例外を有効化 |

### Set-DbaNetworkConfiguration パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | - | SQL Serverインスタンス |
| Credential | PSCredential | No | - | Windows資格情報 |
| EnableProtocol | string | No | - | 有効化するプロトコル（SharedMemory/NamedPipes/TcpIp） |
| DisableProtocol | string | No | - | 無効化するプロトコル |
| DynamicPortForIPAll | switch | No | $false | 動的ポートを使用 |
| StaticPortForIPAll | int[] | No | - | 静的ポート番号 |
| IpAddress | string[] | No | - | リッスンするIPアドレス |
| RestartService | switch | No | $false | サービスを再起動 |
| InputObject | object[] | No | - | Get-DbaNetworkConfigurationの出力 |
| EnableException | switch | No | $false | 例外を有効化 |
| WhatIf | switch | No | - | 実行内容のプレビュー |
| Confirm | switch | No | - | 実行前の確認 |

## 表示項目

### Get-DbaNetworkConfiguration 出力プロパティ（Full）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | SQL Serverインスタンス名 |
| SharedMemoryEnabled | bool | 共有メモリプロトコル有効 |
| NamedPipesEnabled | bool | 名前付きパイププロトコル有効 |
| TcpIpEnabled | bool | TCP/IPプロトコル有効 |
| TcpIpProperties | object | TCP/IPプロパティ（Enabled, KeepAlive, ListenAll） |
| TcpIpAddresses | object[] | IPアドレス構成の配列 |
| Certificate | object | SSL証明書情報 |
| SuitableCertificate | object[] | SQL Server暗号化に適した証明書の配列 |
| Advanced | object | 詳細設定（ForceEncryption, HideInstance, AcceptedSPNs, ExtendedProtection） |

### Set-DbaNetworkConfiguration 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | SQL Serverインスタンス名 |
| Changes | string[] | 適用された変更の配列 |
| RestartNeeded | bool | サービス再起動が必要か |
| Restarted | bool | サービスが再起動されたか |
| Exception | Exception | エラー発生時の例外 |

## イベント仕様

### 1-ネットワーク設定取得（Get-DbaNetworkConfiguration）

SQL Serverのネットワーク構成を取得する。

**処理フロー**:
1. `Resolve-DbaComputerName`でコンピュータ名を解決
2. `Test-ElevationRequirement`で管理者権限を確認
3. `Invoke-Command2`でリモートスクリプトブロックを実行
4. スクリプトブロック内:
   - Microsoft.SqlServer.SqlWmiManagementアセンブリをロード
   - ManagedComputerオブジェクトを作成・初期化
   - ServerProtocolsからSm（共有メモリ）、Np（名前付きパイプ）、Tcp（TCP/IP）を取得
   - TCP/IPのProtocolPropertiesからEnabled, KeepAlive, ListenOnAllIPsを取得
   - IPAddressesからIPn（個別IP）とIPAll（全IP）の構成を取得
   - サービス情報からServiceAccount、REGROOT、VSNAMEを取得
   - レジストリからAcceptedSPNs、Certificate、ExtendedProtection、ForceEncryption、HideInstanceを取得
   - Cert:\LocalMachine\Myから適格な証明書を検索
5. OutputTypeに応じて出力オブジェクトを構築

### 2-ネットワーク設定変更（Set-DbaNetworkConfiguration）

SQL Serverのネットワーク構成を変更する。

**処理フロー**:
1. ShouldProcessで変更確認
2. パラメータに応じてWMIスクリプトブロックを実行
3. EnableProtocol/DisableProtocolでプロトコルの有効/無効を切り替え
4. DynamicPortForIPAll/StaticPortForIPAllでポート設定を変更
5. IpAddressで特定IPへのバインディングを設定
6. RestartServiceが指定された場合、SQL Serverサービスを再起動
7. 変更内容と再起動状態を出力

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

本機能はSQL Serverデータベースには直接アクセスしない。SQL WMIとWindowsレジストリを取得・変更する。

### 操作別影響一覧

| 操作（イベント） | 対象リソース | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaNetworkConfiguration | SQL WMI ManagedComputer | READ | サーバープロトコル情報の読み取り |
| Get-DbaNetworkConfiguration | Windows Registry | READ | SSL証明書・暗号化設定の読み取り |
| Get-DbaNetworkConfiguration | Cert:\LocalMachine\My | READ | ローカルマシン証明書の読み取り |
| Set-DbaNetworkConfiguration | SQL WMI ManagedComputer | UPDATE | サーバープロトコル設定の変更 |
| Set-DbaNetworkConfiguration | SQL Server Service | UPDATE | サービスの再起動 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|---------|---------|
| - | Error | "Failed to collect network configuration from $($instance.ComputerName) for instance $($instance.InstanceName)." | ネットワーク設定取得失敗 |
| - | Error | "Failed to collect network configuration from ... No data was found for this instance, so skipping." | インスタンスが見つからない |
| - | Error | "Failed to collect certificate information from ..." | 証明書情報取得失敗 |
| - | Verbose | "regRoot = '$regRoot' / vsname = '$vsname'" | レジストリパス取得時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| Invoke-Command2失敗 | Stop-Functionでエラーを出力し、次のインスタンスの処理を継続 |
| インスタンス未検出 | Stop-Functionでエラーを出力し、次のインスタンスの処理を継続 |
| レジストリアクセス失敗 | 文字列メッセージを返して続行 |
| 証明書情報取得失敗 | Stop-Functionでエラーを出力 |

## 備考

- OutputTypeのオプション：
  - Full: 完全なネットワーク構成
  - ServerProtocols: プロトコル有効/無効状態のみ
  - TcpIpProperties: TCP/IPプロパティのみ
  - TcpIpAddresses: IPアドレス構成のみ
  - Certificate: SSL証明書情報のみ
- 適格な証明書の条件：
  - DigitalSignatureとKeyEnciphermentのキー使用法
  - RSA 2048ビット以上
  - SHA256以上の署名アルゴリズム
  - Server Authentication拡張キー使用法
  - 有効期間内
  - ホスト名に一致するDNS名
- ネットワーク設定の変更はSQL Serverサービスの再起動が必要

---

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

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

### 推奨読解順序

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

出力オブジェクトのプロパティ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | 行264-277のPSCustomObjectで出力構造を確認 |
| 1-2 | Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | 行156-160, 164-171, 175-179で各サブオブジェクトの構造を確認 |
| 1-3 | Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | 行208-227でCertificateとAdvancedオブジェクトの構造を確認 |

**読解のコツ**: OutputTypeパラメータによって出力形式が大きく異なる点に注意。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | processブロック（行281-385） |

**主要処理フロー**:
1. **284行**: Resolve-DbaComputerNameでコンピュータ名解決
2. **285行**: Test-ElevationRequirementで管理者権限確認
3. **286行**: Invoke-Command2でリモートスクリプトブロック実行
4. **291-294行**: インスタンス存在確認
5. **296-380行**: OutputTypeに応じた出力オブジェクト構築

#### Step 3: リモートスクリプトブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | スクリプトブロック（行139-278） |

**主要処理フロー**:
1. **147-149行**: SqlWmiManagementアセンブリロードとManagedComputer作成
2. **150行**: インスタンス名でServerProtocolsを取得
3. **152-154行**: Sm, Np, Tcpプロトコルを取得
4. **156-160行**: TCP/IPプロパティを取得
5. **162-179行**: IPアドレス構成を取得（IPn + IPAll）
6. **181-197行**: サービス情報とレジストリパスを取得
7. **198-233行**: レジストリから証明書と詳細設定を取得
8. **235-262行**: 適格な証明書を検索

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

```
Get-DbaNetworkConfiguration
    |
    +-- Resolve-DbaComputerName
    |
    +-- Test-ElevationRequirement
    |
    +-- Invoke-Command2
           |
           +-- [リモートスクリプトブロック]
                  |
                  +-- LoadWithPartialName (SqlWmiManagement)
                  |
                  +-- ManagedComputer.Initialize()
                  |
                  +-- ServerProtocols取得
                  |      +-- Sm (SharedMemory)
                  |      +-- Np (NamedPipes)
                  |      +-- Tcp (TCP/IP)
                  |
                  +-- ProtocolProperties取得
                  |      +-- Enabled, KeepAlive, ListenOnAllIPs
                  |
                  +-- IPAddresses取得
                  |      +-- IPn (個別IP)
                  |      +-- IPAll
                  |
                  +-- Services取得
                  |      +-- ServiceAccount
                  |      +-- AdvancedProperties (REGROOT, VSNAME)
                  |
                  +-- レジストリ取得
                  |      +-- AcceptedSPNs
                  |      +-- Certificate
                  |      +-- ExtendedProtection
                  |      +-- ForceEncryption
                  |      +-- HideInstance
                  |
                  +-- Cert:\LocalMachine\My検索
                  |      +-- 適格な証明書フィルタリング
                  |
                  +-- PSCustomObject構築
```

### データフロー図

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

SqlInstance ───────────> Resolve-DbaComputerName ─────────>
                                |
                                v
                        Test-ElevationRequirement ────────>
                                |
                                v
                        Invoke-Command2 ──────────────────>
                        (リモート実行)
                                |
                                v
                        ManagedComputer ──────────────────>
                                |
                        +-------+-------+
                        |       |       |
                        v       v       v
                    Sm      Np      Tcp
                        |       |       |
                        +-------+-------+
                                |
                                v
                        TcpIpProperties ──────────────────>
                                |
                                v
                        TcpIpAddresses ───────────────────>
                        (IPn + IPAll)
                                |
                                v
                        レジストリ取得 ───────────────────>
                        (Certificate, Advanced)
                                |
                                v
                        SuitableCertificate検索 ──────────>
                                |
                                v
OutputType ────────────> 出力オブジェクト構築 ────────────> 出力
                        (Full/ServerProtocols/etc.)

[出力オブジェクト - Full]
    ComputerName, InstanceName, SqlInstance,
    SharedMemoryEnabled, NamedPipesEnabled, TcpIpEnabled,
    TcpIpProperties, TcpIpAddresses, Certificate,
    SuitableCertificate, Advanced
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | ソース | ネットワーク設定取得 |
| Set-DbaNetworkConfiguration.ps1 | `public/Set-DbaNetworkConfiguration.ps1` | ソース | ネットワーク設定変更 |
| Resolve-DbaComputerName.ps1 | `internal/functions/Resolve-DbaComputerName.ps1` | 内部関数 | コンピュータ名解決 |
| Test-ElevationRequirement.ps1 | `internal/functions/Test-ElevationRequirement.ps1` | 内部関数 | 管理者権限確認 |
| Invoke-Command2.ps1 | `internal/functions/Invoke-Command2.ps1` | 内部関数 | リモートコマンド実行 |
