# 機能設計書 373-Set-DbaNetworkConfiguration

## 概要

本ドキュメントは、dbatools PowerShellモジュールのSet-DbaNetworkConfigurationコマンドの機能設計を定義する。このコマンドはSQL Serverのネットワークプロトコル設定（TCP/IP、名前付きパイプ、共有メモリ）をWMI経由で変更する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのネットワーク設定変更は、従来SQL Server Configuration Managerを使用して手動で行う必要があった。特に動的ポートから静的ポートへの変更、TCP/IPの有効化、マルチホームサーバーでの特定IPアドレス設定などは、ファイアウォールルールやリモート接続のために頻繁に必要となる作業である。この作業を自動化することで、複数サーバーへの一貫した設定適用と人的ミスの削減を実現する。

**機能の利用シーン**：
- 動的ポートから静的ポートへの切り替え（ファイアウォール設定のため）
- TCP/IPプロトコルの有効化によるリモート接続の許可
- 名前付きインスタンスのカスタムポート設定
- マルチホームサーバーでの特定IPアドレスへのリスニング設定
- Get-DbaNetworkConfigurationで取得した設定オブジェクトの編集と適用

**主要な処理内容**：
1. 現在のネットワーク構成の取得（Get-DbaNetworkConfiguration）
2. 指定されたアクションに基づく構成オブジェクトの変更
3. WMI経由でのリモート設定適用
4. オプションでのSQL Serverサービス再起動

**関連システム・外部連携**：
- SQL Server WMI Provider（Microsoft.SqlServer.SqlWmiManagement）
- Windows Remote Management (WinRM) / PowerShell Remoting
- SQL Serverサービス（Restart-DbaService）

**権限による制御**：ターゲットサーバー上での管理者権限が必要。Credentialパラメータによる代替資格情報の指定が可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン/PowerShell | 主画面 | コマンド実行とパラメータ指定 |

## 機能種別

設定変更 / CRUD操作（更新）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes (NonPipeline) | 対象SQL Serverインスタンス | - |
| Credential | PSCredential | No | リモート接続用の代替資格情報 | - |
| EnableProtocol | string | No | 有効化するプロトコル | ValidateSet: SharedMemory, NamedPipes, TcpIp |
| DisableProtocol | string | No | 無効化するプロトコル | ValidateSet: SharedMemory, NamedPipes, TcpIp |
| DynamicPortForIPAll | switch | No | すべてのIPで動的ポートを使用 | - |
| StaticPortForIPAll | int[] | No | すべてのIPで静的ポートを使用 | - |
| IpAddress | string[] | No | リッスンするIPアドレスを指定 | 形式: "192.168.1.10" または "192.168.1.10:1433" |
| RestartService | switch | No | 設定変更後にサービスを自動再起動 | - |
| InputObject | object[] | Yes (Pipeline) | Get-DbaNetworkConfigurationからの入力 | - |
| EnableException | switch | No | 例外処理の有効化 | - |
| WhatIf | switch | No | 実行せずに動作確認 | - |
| Confirm | switch | No | 確認プロンプトの表示（ConfirmImpact=High） | - |

### 入力データソース

- SqlInstanceパラメータ: ユーザー指定
- InputObject: Get-DbaNetworkConfiguration（-OutputType Fullが必要）からのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Changes | string[] | 適用された設定変更の配列 |
| RestartNeeded | bool | サービス再起動が必要かどうか |
| Restarted | bool | サービスが正常に再起動されたかどうか |
| Exception | System.Exception | WMI操作中にエラーが発生した場合の例外オブジェクト |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. Begin ブロック: WMI操作用スクリプトブロックの定義
   └─ SqlWmiManagement アセンブリのロード
   └─ ManagedComputerオブジェクトの初期化
   └─ 各プロトコル設定の比較と変更適用

2. Process ブロック: メインの処理ループ
   └─ パラメータ検証（アクションが1つのみか確認）
   └─ SqlInstance指定の場合
      └─ Get-DbaNetworkConfigurationで現在の設定を取得
      └─ 指定アクションに応じた設定オブジェクトの変更
   └─ 各設定オブジェクトに対するWMI適用
      └─ ShouldProcessによる確認
      └─ Invoke-Command2でリモート実行
      └─ サービス再起動（RestartService指定時）
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{アクション指定あり?}
    B -->|No| C[エラー: アクション必須]
    B -->|Yes| D{複数アクション?}
    D -->|Yes| E[エラー: 単一アクションのみ]
    D -->|No| F[Get-DbaNetworkConfiguration]
    F --> G{取得成功?}
    G -->|No| H[Stop-Function]
    G -->|Yes| I{アクション種別}
    I -->|EnableProtocol| J[プロトコル有効化]
    I -->|DisableProtocol| K[プロトコル無効化]
    I -->|DynamicPortForIPAll| L[動的ポート設定]
    I -->|StaticPortForIPAll| M[静的ポート設定]
    I -->|IpAddress| N[IPアドレス設定]
    J --> O[InputObjectに追加]
    K --> O
    L --> O
    M --> O
    N --> O
    O --> P{ShouldProcess確認}
    P -->|No| Q[スキップ]
    P -->|Yes| R[Invoke-Command2でWMI操作]
    R --> S{変更あり?}
    S -->|Yes| T{RestartService?}
    S -->|No| U[結果出力]
    T -->|Yes| V[Restart-DbaService]
    T -->|No| W[警告: 再起動必要]
    V --> U
    W --> U
    H --> X[次のインスタンス]
    Q --> X
    U --> X
    X --> Y{次あり?}
    Y -->|Yes| F
    Y -->|No| Z[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 単一アクション制限 | EnableProtocol, DisableProtocol, DynamicPortForIPAll, StaticPortForIPAll, IpAddressは同時に1つのみ指定可能 | SqlInstance使用時 |
| BR-002 | アクション必須 | SqlInstance指定時は少なくとも1つのアクションが必要 | SqlInstance使用時 |
| BR-003 | TCP/IP自動有効化 | DynamicPortForIPAll, StaticPortForIPAll, IpAddress使用時はTCP/IPが自動的に有効化される | 該当アクション使用時 |
| BR-004 | ListenAll自動設定 | DynamicPortForIPAll, StaticPortForIPAll使用時はListenAllがtrueに設定される | 該当アクション使用時 |
| BR-005 | サービス再起動必須 | ネットワーク設定変更はサービス再起動後に有効となる | 常に |

### 計算ロジック

特になし

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

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

本コマンドはSQL Serverデータベースへの直接アクセスは行わない。WMIを通じたネットワーク設定の変更のみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidArgument | アクションが指定されていない | Stop-Functionでメッセージ表示 |
| - | InvalidArgument | 複数アクションが同時指定 | Stop-Functionでメッセージ表示 |
| - | ConnectionError | ネットワーク構成の取得失敗 | Stop-Functionで継続 |
| - | WMIError | WMI操作中の例外 | 出力オブジェクトにExceptionを含め、Stop-Function |
| - | ServiceRestartError | サービス再起動失敗 | 警告を出力して継続 |

### リトライ仕様

リトライ機構は実装されていない。

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

トランザクション管理は行わない（各設定変更は即座にWMI経由で適用される）。

## パフォーマンス要件

- WMI操作はリモートで実行される
- 設定変更後のサービス再起動は数十秒を要する可能性がある

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

- ターゲットサーバー上での管理者権限が必要（Test-ElevationRequirement）
- Credentialパラメータによる代替資格情報のサポート
- ShouldProcess/Confirmによる誤操作防止
- TCP/IP無効化は全リモート接続を遮断するため警告

## 備考

- 設定変更はサービス再起動後に有効となる
- Get-DbaNetworkConfigurationで-OutputType Fullを使用すると詳細なプロパティ編集が可能
- 詳細なプロパティ説明: https://docs.microsoft.com/en-us/sql/tools/configuration-manager/sql-server-network-configuration

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaNetworkConfiguration.ps1 | `public/Set-DbaNetworkConfiguration.ps1` | **481-488行目**: 出力PSCustomObjectの構造定義 |

**読解のコツ**: 出力にはChanges配列が含まれ、適用された各変更の説明が格納される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaNetworkConfiguration.ps1 | `public/Set-DbaNetworkConfiguration.ps1` | **123-147行目**: パラメータ定義とParameterSet |

**主要処理フロー**:
1. **123行目**: CmdletBinding属性でShouldProcess、ConfirmImpact=Highを設定
2. **125-126行目**: SqlInstanceパラメータ（NonPipelineセット、必須）
3. **130-134行目**: EnableProtocol, DisableProtocol（ValidateSet）
4. **143-144行目**: InputObjectパラメータ（Pipelineセット、必須）

#### Step 3: Beginブロック - WMIスクリプトブロック

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaNetworkConfiguration.ps1 | `public/Set-DbaNetworkConfiguration.ps1` | **149-314行目**: WMI操作用スクリプトブロック |

**主要処理フロー**:
- **162行目**: SqlWmiManagementアセンブリのロード
- **163-164行目**: ManagedComputerオブジェクトの初期化
- **172行目**: ServerProtocolsの取得
- **175-202行目**: SharedMemory, NamedPipes, TcpIpの有効/無効化
- **233-303行目**: IPアドレス毎の設定変更

#### Step 4: Processブロック - アクション処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaNetworkConfiguration.ps1 | `public/Set-DbaNetworkConfiguration.ps1` | **316-326行目**: パラメータ検証 |
| 4-2 | Set-DbaNetworkConfiguration.ps1 | `public/Set-DbaNetworkConfiguration.ps1` | **335-398行目**: 各アクションの処理 |
| 4-3 | Set-DbaNetworkConfiguration.ps1 | `public/Set-DbaNetworkConfiguration.ps1` | **400-474行目**: IpAddress設定処理 |
| 4-4 | Set-DbaNetworkConfiguration.ps1 | `public/Set-DbaNetworkConfiguration.ps1` | **479-527行目**: WMI適用とサービス再起動 |

**主要処理フロー**:
- **317-320行目**: アクション未指定時のエラー
- **322-325行目**: 複数アクション指定時のエラー
- **330行目**: Get-DbaNetworkConfigurationで現在設定取得
- **359-377行目**: DynamicPortForIPAll処理（TcpDynamicPorts='0'、TcpPort=''）
- **379-398行目**: StaticPortForIPAll処理（TcpDynamicPorts=''、TcpPort=port）
- **493行目**: Invoke-Command2でWMI操作実行
- **511行目**: Restart-DbaServiceでサービス再起動

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

```
Set-DbaNetworkConfiguration
    │
    ├─ Get-DbaNetworkConfiguration
    │      └─ 現在のネットワーク設定取得
    │
    ├─ Resolve-DbaComputerName
    │      └─ コンピュータ名の解決
    │
    ├─ Test-ElevationRequirement
    │      └─ 管理者権限の確認
    │
    ├─ Invoke-Command2
    │      └─ リモートWMI操作
    │             ├─ ManagedComputer.Initialize
    │             ├─ ServerProtocols設定
    │             └─ IPAddresses設定
    │
    └─ Restart-DbaService (オプション)
           └─ SQL Serverサービス再起動
```

### データフロー図

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

SqlInstance ──────────────▶ Get-DbaNetworkConfiguration ──▶ 現在設定
    │                              │
    ▼                              ▼
EnableProtocol等 ─────────▶ 設定オブジェクト変更
                                   │
                                   ▼
                           Invoke-Command2 ─────────────▶ WMI適用
                                   │
                                   ▼
RestartService ───────────▶ Restart-DbaService ─────────▶ 再起動
                                   │
                                   ▼
                           PSCustomObject ──────────────▶ 結果出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaNetworkConfiguration.ps1 | `public/Set-DbaNetworkConfiguration.ps1` | ソース | メイン機能実装 |
| Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | ソース | 現在設定取得の依存関数 |
| Restart-DbaService.ps1 | `public/Restart-DbaService.ps1` | ソース | サービス再起動の依存関数 |
