# 機能設計書 374-Set-DbaTcpPort

## 概要

本ドキュメントは、dbatools PowerShellモジュールのSet-DbaTcpPortコマンドの機能設計を定義する。このコマンドはSQL ServerインスタンスのTCPポート設定を変更する機能を提供し、Set-DbaNetworkConfigurationのラッパーとして動作する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのセキュリティ強化やネットワークセグメンテーション要件を満たすために、デフォルトポート1433から別のポートへの変更が頻繁に求められる。SQL Server Configuration Managerでの手動設定は時間がかかり、複数サーバーへの一貫した設定適用が困難である。本コマンドは、TCPポート設定変更に特化したシンプルなインターフェースを提供する。

**機能の利用シーン**：
- セキュリティ強化のためのデフォルトポートからの移行
- 名前付きインスタンスへのカスタムポート割り当て
- 組織のネットワークポリシーに準拠したポート設定
- マルチホームサーバーでの特定IPアドレスへのポート設定

**主要な処理内容**：
1. 対象インスタンスの特定とIPアドレスの検証
2. Set-DbaNetworkConfiguration（IPAll指定時）または直接のネットワーク構成変更
3. 動的ポートの無効化と静的ポートの設定
4. オプションでのサービス自動再起動

**関連システム・外部連携**：
- Set-DbaNetworkConfiguration（内部で呼び出し）
- Get-DbaNetworkConfiguration（IPアドレス指定時）
- Restart-DbaService（Force指定時）

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス（パイプライン入力可） | - |
| Credential | PSCredential | No | リモート接続用の代替資格情報 | - |
| Port | int[] | Yes | 設定するTCPポート番号 | ValidateRange: 1-65535 |
| IpAddress | IpAddress[] | No | 特定のIPアドレスにのみポートを設定 | - |
| Force | switch | No | 設定変更後にサービスを自動再起動 | - |
| EnableException | switch | No | 例外処理の有効化 | - |
| WhatIf | switch | No | 実行せずに動作確認 | - |
| Confirm | switch | No | 確認プロンプトの表示（ConfirmImpact=High） | - |

### 入力データソース

- SqlInstanceパラメータ: ユーザー指定またはパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | Void | 本コマンドはパイプラインに出力を返さない |

### 出力先

コンソール（Set-DbaNetworkConfigurationの内部出力）

## 処理フロー

### 処理シーケンス

```
1. Process ブロック: メインの処理ループ
   └─ Test-FunctionInterrupt確認
   └─ IpAddress='0.0.0.0'の場合はnullに変換
   └─ IpAddress指定時の複数インスタンス制限チェック
   └─ 各インスタンスに対する処理
      └─ IpAddress未指定の場合
         └─ Set-DbaNetworkConfiguration -StaticPortForIPAllを呼び出し
      └─ IpAddress指定の場合
         └─ Get-DbaNetworkConfigurationで現在設定取得
         └─ TCP/IP有効化、ListenAll無効化
         └─ 対象IPアドレスの設定変更
         └─ Set-DbaNetworkConfigurationで適用
         └─ Force指定時はRestart-DbaServiceを呼び出し
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{FunctionInterrupt?}
    B -->|Yes| C[終了]
    B -->|No| D{IpAddress='0.0.0.0'?}
    D -->|Yes| E[IpAddress=null]
    D -->|No| F{IpAddress指定かつ複数インスタンス?}
    E --> F
    F -->|Yes| G[エラー: 単一インスタンスのみ]
    F -->|No| H[インスタンスループ開始]
    H --> I{IpAddress指定?}
    I -->|No| J[Set-DbaNetworkConfiguration -StaticPortForIPAll]
    I -->|Yes| K[Get-DbaNetworkConfiguration]
    K --> L{取得成功?}
    L -->|No| M[Stop-Function]
    L -->|Yes| N[TCP/IP有効化、ListenAll無効化]
    N --> O[対象IPアドレス設定変更]
    O --> P[ShouldProcess確認]
    P -->|No| Q[スキップ]
    P -->|Yes| R[Set-DbaNetworkConfiguration適用]
    R --> S{Force指定?}
    S -->|Yes| T[Restart-DbaService]
    S -->|No| U[次のインスタンス]
    J --> U
    M --> U
    Q --> U
    T --> U
    U --> V{次あり?}
    V -->|Yes| H
    V -->|No| C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 単一インスタンス制限 | IpAddress指定時は単一インスタンスのみ指定可能 | IpAddress使用時 |
| BR-002 | '0.0.0.0'変換 | IpAddress='0.0.0.0'はnullとして扱われる（IPAll設定と同等） | IpAddress='0.0.0.0' |
| BR-003 | 動的ポート無効化 | 静的ポート設定時は動的ポートが自動的に無効化される | 常に |
| BR-004 | サービス再起動必須 | ポート設定変更はサービス再起動後に有効となる | 常に |
| BR-005 | TCP/IP自動有効化 | IpAddress指定時はTCP/IPが自動的に有効化される | IpAddress使用時 |

### 計算ロジック

- 複数ポート指定時はカンマ区切りの文字列に変換（例: "1433,1434"）

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

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

本コマンドはSQL Serverデータベースへの直接アクセスは行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidArgument | IpAddress指定で複数インスタンス | Stop-Functionでメッセージ表示 |
| - | ConnectionError | ネットワーク構成の取得失敗 | Stop-Functionで継続 |
| - | IPNotFound | 指定IPアドレスが存在しない | 警告を出力してスキップ |
| - | ServiceRestartError | サービス再起動失敗 | Stop-Functionで継続 |

### リトライ仕様

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

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

トランザクション管理は行わない。

## パフォーマンス要件

- Set-DbaNetworkConfigurationの性能に依存
- サービス再起動は数十秒を要する可能性がある

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

- ターゲットサーバー上での管理者権限が必要
- Credentialパラメータによる代替資格情報のサポート
- ShouldProcess/Confirmによる誤操作防止
- ポート範囲は1-65535で制限

## 備考

- Set-DbaNetworkConfigurationのラッパー関数として実装
- IpAddress未指定時はIPAll設定を使用
- 設定変更はサービス再起動後に有効となる

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaTcpPort.ps1 | `public/Set-DbaTcpPort.ps1` | **81-92行目**: パラメータ定義 |

**主要処理フロー**:
1. **81行目**: CmdletBinding属性でShouldProcess、ConfirmImpact=Highを設定
2. **83-84行目**: SqlInstanceパラメータ（Mandatory、ValueFromPipeline）
3. **86-88行目**: Portパラメータ（Mandatory、ValidateRange 1-65535）
4. **89行目**: IpAddressパラメータ
5. **90行目**: Forceスイッチ

#### Step 2: Processブロック - IPAll設定

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaTcpPort.ps1 | `public/Set-DbaTcpPort.ps1` | **94-114行目**: メイン処理 |

**主要処理フロー**:
- **95-97行目**: Test-FunctionInterruptの確認
- **99-101行目**: IpAddress='0.0.0.0'の変換
- **103-106行目**: IpAddress指定時の複数インスタンス制限
- **111-113行目**: IpAddress未指定時のSet-DbaNetworkConfiguration -StaticPortForIPAll呼び出し

#### Step 3: Processブロック - 特定IPアドレス設定

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaTcpPort.ps1 | `public/Set-DbaTcpPort.ps1` | **115-149行目**: IPアドレス指定時の処理 |

**主要処理フロー**:
- **117行目**: Get-DbaNetworkConfiguration -OutputType Full呼び出し
- **122-124行目**: TCP/IP有効化、ListenAll無効化
- **125-134行目**: 対象IPアドレスの設定変更ループ
- **137行目**: Set-DbaNetworkConfigurationで適用
- **140-148行目**: Force指定時のRestart-DbaService呼び出し

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

```
Set-DbaTcpPort
    │
    ├─ Test-FunctionInterrupt
    │      └─ 割り込み確認
    │
    ├─ [IpAddress未指定時]
    │      └─ Set-DbaNetworkConfiguration -StaticPortForIPAll
    │
    └─ [IpAddress指定時]
           ├─ Get-DbaNetworkConfiguration -OutputType Full
           │      └─ 現在設定取得
           │
           ├─ Set-DbaNetworkConfiguration (パイプライン)
           │      └─ 設定適用
           │
           └─ Restart-DbaService (Force時)
                  └─ サービス再起動
```

### データフロー図

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

SqlInstance, Port ─────────▶ IpAddress判定
    │                              │
    ├─ [IPAll]                     ▼
    │      └──────────────▶ Set-DbaNetworkConfiguration
    │                        -StaticPortForIPAll
    │
    └─ [特定IP]
           └──────────────▶ Get-DbaNetworkConfiguration
                                   │
                                   ▼
                           設定オブジェクト変更
                                   │
                                   ▼
                           Set-DbaNetworkConfiguration
                                   │
                                   ▼
                           [Force時] Restart-DbaService
```

### 関連ファイル一覧

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