# 画面設計書 104-TCPポート設定

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL ServerのTCPポート管理機能（Get-DbaTcpPort、Set-DbaTcpPort）の設計仕様を記載する。

### 本画面の処理概要

SQL ServerインスタンスのTCPポート設定を取得・変更するためのコマンドラインインターフェースを提供する。ネットワーク構成情報の詳細取得や、セキュリティ強化のためのポート変更を自動化できる。

**業務上の目的・背景**：SQL Serverはデフォルトでポート1433を使用するが、セキュリティ上の理由から変更することが推奨される。また、名前付きインスタンスは動的ポートを使用することがあり、ファイアウォール設定やクライアント接続設定のために実際のポートを確認する必要がある。本機能により、複数インスタンスのポート設定を一括確認・変更でき、ネットワーク構成の標準化やセキュリティ監査が効率化される。

**画面へのアクセス方法**：PowerShellコンソールから `Get-DbaTcpPort` または `Set-DbaTcpPort` コマンドを実行する。

**主要な操作・処理内容**：
1. TCPポートの取得（Get-DbaTcpPort）：現在のTCPポート番号とIPアドレスを取得
2. 詳細情報取得（-All）：全IPアドレスの構成詳細（静的/動的ポート、有効/無効）を取得
3. IPv6除外（-ExcludeIpv6）：IPv4アドレスのみに絞り込み
4. TCPポートの設定（Set-DbaTcpPort）：指定ポートを静的ポートとして設定
5. サービス再起動（-Force）：設定変更後に自動でサービスを再起動

**画面遷移**：Get-DbaTcpPortの結果を確認後、Set-DbaTcpPortで変更を適用する流れ。Central Management Serverからパイプ入力で複数インスタンスを処理可能。

**権限による表示制御**：Get-DbaTcpPortはSQL Server接続権限で実行可能。Set-DbaTcpPortはネットワーク構成変更権限（通常はsysadmin）が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 369 | Get-DbaTcpPort | 主機能 | TCPポートの取得 |
| 374 | Set-DbaTcpPort | 主機能 | TCPポートの設定 |

## 画面種別

コマンドラインインターフェース（取得・設定）

## URL/ルーティング

PowerShellコマンド実行

## 入出力項目

### Get-DbaTcpPort パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 必須 | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | 任意 | SQL認証情報 |
| Credential | PSCredential | 任意 | Windows認証情報 |
| All | Switch | 任意 | 全IP詳細情報を取得 |
| ExcludeIpv6 | Switch | 任意 | IPv6を除外 |
| EnableException | Switch | 任意 | 例外を有効にする |

### Set-DbaTcpPort パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 必須 | 対象SQL Serverインスタンス |
| Credential | PSCredential | 任意 | Windows認証情報 |
| Port | int[] | 必須 | 設定するポート番号（1-65535） |
| IpAddress | IpAddress[] | 任意 | 特定IPアドレスのみ設定 |
| Force | Switch | 任意 | サービス自動再起動 |
| EnableException | Switch | 任意 | 例外を有効にする |

## 表示項目

### Get-DbaTcpPort 出力プロパティ（デフォルト）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| IPAddress | string | IPアドレス |
| Port | int | TCPポート番号 |

### Get-DbaTcpPort 出力プロパティ（-All指定時）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Name | string | 構成名（IPAll, IP1, IP2等） |
| Active | bool | アクティブ状態 |
| Enabled | bool | 有効状態 |
| IpAddress | string | IPアドレス |
| TcpDynamicPorts | string | 動的ポート範囲 |
| TcpPort | string | 静的TCPポート |
| IsUsed | bool | 使用中フラグ |

## イベント仕様

### 1-Get-DbaTcpPort実行（デフォルト）

1. "TCP:$instance"形式でConnect-DbaInstance実行
2. sys.dm_exec_connectionsからlocal_net_addressとlocal_tcp_portを取得
3. PSCustomObjectとして出力

### 2-Get-DbaTcpPort実行（-All指定時）

1. Get-DbaNetworkConfigurationでネットワーク構成取得
2. TcpIpAddressesからIPアドレス情報を展開
3. ListenAllとEnabled状態からIsUsedを計算
4. 各IPアドレスについてPSCustomObject生成
5. ExcludeIpv6指定時はIPv4のみフィルタ

### 3-Set-DbaTcpPort実行

1. IpAddress指定なしの場合：Set-DbaNetworkConfigurationでIPAllを設定
2. IpAddress指定ありの場合：
   - Get-DbaNetworkConfigurationで現在設定取得
   - 該当IPアドレスの設定を更新
   - TcpDynamicPortsを空に設定（静的ポート化）
   - Set-DbaNetworkConfigurationで適用
3. Force指定時：Restart-DbaServiceでサービス再起動

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaTcpPort | sys.dm_exec_connections | SELECT | 現在接続のポート情報取得 |
| Get-DbaTcpPort -All | - | WMI読取 | ネットワーク構成の読み取り |
| Set-DbaTcpPort | - | WMI更新 | ネットワーク構成の更新 |

### テーブル別更新項目詳細

#### ネットワーク構成（Set-DbaNetworkConfiguration経由）

| 操作 | 項目 | 更新値・取得条件 | 備考 |
|-----|-----|-----------------|------|
| UPDATE | TcpDynamicPorts | '' (空文字) | 動的ポートを無効化 |
| UPDATE | TcpPort | 指定ポート番号 | 静的ポートを設定 |
| UPDATE | Enabled | true | IPアドレスを有効化 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|--------------|----------|
| MSG001 | エラー | "Failed to collect network configuration from $computerName for instance $instanceName." | ネットワーク構成取得失敗時 |
| MSG002 | 警告 | "IP address $ip not found, skipping." | 指定IPアドレスが見つからない場合 |
| MSG003 | エラー | "-IpAddress switch cannot be used with a collection of serveraddresses" | 複数インスタンスでIpAddress指定時 |
| MSG004 | エラー | "Issue restarting $instance on $computerFullName" | サービス再起動失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Functionでエラー出力し、Continueで次のインスタンスへ |
| ネットワーク構成取得失敗 | Stop-Functionでエラー出力し、Continueで次のインスタンスへ |
| サービス再起動失敗 | Stop-Functionでエラー出力し、Continueで次のインスタンスへ |
| IPアドレス不明 | 警告出力してスキップ |

## 備考

- ポート変更はサービス再起動まで反映されない（-Force指定で自動再起動）
- IPv6アドレスの正規表現パターンでフィルタリング可能
- 複数ポートをカンマ区切りで設定可能（Set-DbaTcpPort）
- Get-DbaTcpPortのデフォルトはsys.dm_exec_connectionsから取得
- -All指定時はGet-DbaNetworkConfiguration経由でWMIから取得

---

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

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

### 推奨読解順序

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

ネットワーク構成オブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaTcpPort.ps1 | `public/Get-DbaTcpPort.ps1` | 出力オブジェクトの構造（行127-138, 164-172）を確認 |

**読解のコツ**: -All指定の有無で出力形式が異なることを理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaTcpPort.ps1 | `public/Get-DbaTcpPort.ps1` | param()ブロック（行103-112）でパラメータ定義を確認 |
| 2-2 | Set-DbaTcpPort.ps1 | `public/Set-DbaTcpPort.ps1` | param()ブロック（行83-92）でパラメータ定義を確認 |

**主要処理フロー**:
1. **行115**: -All指定時の処理分岐
2. **行152-162**: sys.dm_exec_connectionsからポート取得
3. **行164-172**: デフォルト出力オブジェクト生成

#### Step 3: 詳細取得ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaTcpPort.ps1 | `public/Get-DbaTcpPort.ps1` | -All時のGet-DbaNetworkConfiguration呼び出し（行117） |

**主要処理フロー**:
- **行117**: Get-DbaNetworkConfiguration -OutputType Full
- **行122-138**: TcpIpAddresses展開とIsUsed計算
- **行143-147**: IPv4正規表現フィルタ

#### Step 4: ポート設定ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaTcpPort.ps1 | `public/Set-DbaTcpPort.ps1` | IPAll設定とIP個別設定の分岐（行111-150） |

**主要処理フロー**:
- **行111-114**: IPAll設定（Set-DbaNetworkConfiguration -StaticPortForIPAll）
- **行117-138**: IP個別設定の構成変更
- **行140-148**: Force時のサービス再起動

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

```
Get-DbaTcpPort
    │
    ├─ (デフォルト)
    │      │
    │      ├─ Connect-DbaInstance ("TCP:$instance")
    │      │
    │      └─ $server.Query(sys.dm_exec_connections)
    │
    └─ (-All指定時)
           │
           ├─ Get-DbaNetworkConfiguration -OutputType Full
           │
           ├─ TcpIpAddresses展開
           │      └─ IsUsed計算
           │
           └─ IPv6フィルタ（ExcludeIpv6時）

Set-DbaTcpPort
    │
    ├─ (IPAll設定)
    │      └─ Set-DbaNetworkConfiguration -StaticPortForIPAll
    │
    ├─ (IP個別設定)
    │      │
    │      ├─ Get-DbaNetworkConfiguration
    │      │
    │      ├─ 構成オブジェクト変更
    │      │
    │      └─ Set-DbaNetworkConfiguration
    │
    └─ (Force時)
           └─ Restart-DbaService -Type Engine
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ───────▶ SMO Server Object
                           │
                           ▼
                    (デフォルト)
                    sys.dm_exec_connections
                           │
                           ▼
                    local_net_address, local_tcp_port
                           │
                           ▼
                    PSCustomObject ───────▶ ポート情報

                    (-All指定時)
                    Get-DbaNetworkConfiguration
                           │
                           ▼
                    TcpIpAddresses展開 ───────▶ 詳細ネットワーク情報
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaTcpPort.ps1 | `public/Get-DbaTcpPort.ps1` | ソース | TCPポート取得コマンド |
| Set-DbaTcpPort.ps1 | `public/Set-DbaTcpPort.ps1` | ソース | TCPポート設定コマンド |
| Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | ソース | ネットワーク構成取得 |
| Set-DbaNetworkConfiguration.ps1 | `public/Set-DbaNetworkConfiguration.ps1` | ソース | ネットワーク構成設定 |
| Restart-DbaService.ps1 | `public/Restart-DbaService.ps1` | ソース | サービス再起動 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
