# 機能設計書 369-Get-DbaTcpPort

## 概要

本ドキュメントは、SQL ServerインスタンスのTCPポート番号を取得するための dbatools コマンド `Get-DbaTcpPort` の機能設計を記述する。

### 本機能の処理概要

`Get-DbaTcpPort` は、指定されたSQL Serverインスタンスが使用しているTCPポート番号を取得するコマンドである。デフォルトではポート番号のみを返し、-Allオプションで詳細なネットワーク構成（IPアドレス、静的/動的ポート設定）を取得できる。

**業務上の目的・背景**：SQL Serverの接続問題をトラブルシューティングする際、インスタンスが使用しているTCPポートを確認することは基本的な診断ステップである。特に、名前付きインスタンスやカスタムポート設定を使用している環境では、ポート番号の確認が重要となる。ファイアウォール設定の確認や、Central Management Server登録時のポート確認にも使用される。

**機能の利用シーン**：
- SQL Server接続問題のトラブルシューティング
- ファイアウォールルール作成時のポート確認
- 複数インスタンスのポート設定監査
- Central Management Server登録情報の確認

**主要な処理内容**：
1. -Allオプションの場合:
   - Get-DbaNetworkConfigurationでネットワーク構成取得
   - TcpIpAddressesから各IPの設定を抽出
   - ListenAll/Enabledに基づくIsUsed判定
2. デフォルトの場合:
   - TCP:プレフィックス付きでSQL Server接続
   - sys.dm_exec_connectionsから現在の接続情報取得
   - local_net_address, local_tcp_portを出力

**関連システム・外部連携**：SQL Server DMV（sys.dm_exec_connections）、Get-DbaNetworkConfiguration

**権限による制御**：SQL Serverへの接続権限が必要。-All使用時は管理者権限も必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIツール | 主機能 | PowerShellコンソールから実行 |

## 機能種別

情報取得 / ネットワーク構成確認

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | ターゲットSQL Serverインスタンス | パイプライン対応 |
| SqlCredential | PSCredential | No | SQL Server接続資格情報 | - |
| Credential | PSCredential | No | コンピュータ接続資格情報 | -All使用時 |
| All | switch | No | 詳細ネットワーク構成を取得 | - |
| ExcludeIpv6 | switch | No | IPv6アドレスを除外 | -Allと共に使用 |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- SQL Server DMV: sys.dm_exec_connections
- Get-DbaNetworkConfiguration（-All使用時）

## 出力仕様

### 出力データ（デフォルト）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | コンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全インスタンス名 |
| IPAddress | String | 接続先IPアドレス |
| Port | Int | TCPポート番号 |

### 出力データ（-All）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | コンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全インスタンス名 |
| Name | String | 構成名（IPAll, IP1, IP2等） |
| Active | Boolean | IPアドレスがアクティブか |
| Enabled | Boolean | IPアドレスが有効か |
| IpAddress | String | IPアドレス |
| TcpDynamicPorts | String | 動的ポート設定 |
| TcpPort | String | 静的ポート設定 |
| IsUsed | Boolean | 実際に使用されているか |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. Process ブロック - 各SqlInstanceに対して
   └─ -All指定の場合:
       └─ Get-DbaNetworkConfiguration -OutputType Full
       └─ TcpIpAddressesを展開
       └─ IsUsed判定（ListenAll && IPAll || !ListenAll && Enabled）
       └─ IPAddress順でソート
       └─ -ExcludeIpv6: IPv4のみフィルタリング
   └─ デフォルトまたは-All失敗時:
       └─ Connect-DbaInstance -SqlInstance "TCP:$instance"
       └─ sys.dm_exec_connections照会
       └─ local_net_address, local_tcp_port取得
       └─ Select-DefaultViewで出力整形
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[各SqlInstanceループ]
    B --> C{-All指定?}
    C -->|Yes| D[Get-DbaNetworkConfiguration]
    D --> E[TcpIpAddresses展開]
    E --> F[IsUsed判定]
    F --> G{-ExcludeIpv6?}
    G -->|Yes| H[IPv4フィルタ]
    G -->|No| I[全IP出力]
    H --> I
    C -->|No| J[Connect-DbaInstance TCP:]
    J --> K[dm_exec_connections照会]
    K --> L[Port情報出力]
    I --> B
    L --> B
    B --> M{次のInstance?}
    M -->|Yes| B
    M -->|No| N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | TCP接続 | デフォルトモードではTCP:プレフィックスで接続 | -All未指定時 |
| BR-02 | IsUsed判定 | ListenAll=TrueならIPAll、FalseならEnabled=TrueのIPが使用中 | -All時 |
| BR-03 | IPv4フィルタ | 正規表現でIPv4形式を検出 | -ExcludeIpv6時 |
| BR-04 | フォールバック | -AllでNetworkConfiguration取得失敗時、T-SQL方式にフォールバック | -All時 |

### 計算ロジック

IsUsed判定:
```powershell
$isIPAll = $netConf.TcpIpProperties.ListenAll -and $ip.Name -eq 'IPAll'
$isIPnEnabled = -not $netConf.TcpIpProperties.ListenAll -and $ip.Enabled
$isUsed = $isIPAll -or $isIPnEnabled
```

IPv4正規表現:
```powershell
$octet = '(?:0?0?[0-9]|0?[1-9][0-9]|1[0-9]{2}|2[0-5][0-5]|2[0-4][0-9])'
[regex]$ipv4 = "^(?:$octet\.){3}$octet$"
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 読取 | sys.dm_exec_connections | SELECT | 接続情報取得（デフォルトモード） |

### テーブル別操作詳細

#### sys.dm_exec_connections

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | local_net_address | session_id = @@SPID | 現在の接続のIPアドレス |
| SELECT | local_tcp_port | session_id = @@SPID | 現在の接続のTCPポート |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Server接続失敗 | 接続情報確認 |
| - | NetworkConfig失敗 | Get-DbaNetworkConfiguration失敗 | T-SQLにフォールバック |

### リトライ仕様

-All失敗時、デフォルト方式（T-SQL）にフォールバック

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

読み取り専用操作のため、トランザクション管理は不要

## パフォーマンス要件

特に定義なし。

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

- SQL Server接続権限が必要
- -All使用時は管理者権限も必要
- 資格情報はPSCredentialオブジェクトで安全に取り扱う

## 備考

- SQL Server 2005 (v9) 以上が必要（sys.dm_exec_connections使用）
- TCP接続のみサポート（Named Pipes等は対象外）
- WMI接続が不安定な場合はT-SQL方式が使用される

---

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

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

### 推奨読解順序

#### Step 1: パラメータ定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaTcpPort.ps1 | `public/Get-DbaTcpPort.ps1` | paramブロック（102-112行目）でパラメータ構造を確認 |

**主要処理フロー**:
- **104-105行目**: SqlInstanceパラメータ（Mandatory, ValueFromPipeline）
- **108行目**: Allスイッチ
- **110行目**: ExcludeIpv6スイッチ（エイリアス: Ipv4）

#### Step 2: -Allモードを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaTcpPort.ps1 | `public/Get-DbaTcpPort.ps1` | processブロック（115-149行目）で-Allモードを確認 |

**主要処理フロー**:
- **117行目**: Get-DbaNetworkConfiguration -OutputType Full
- **122-126行目**: TcpIpAddressesのループとIsUsed判定
- **143-146行目**: IPv4正規表現によるフィルタリング

#### Step 3: デフォルトモードを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaTcpPort.ps1 | `public/Get-DbaTcpPort.ps1` | processブロック（151-175行目）でデフォルトモードを確認 |

**主要処理フロー**:
- **155行目**: Connect-DbaInstance -SqlInstance "TCP:$instance"
- **161行目**: sys.dm_exec_connectionsクエリ
- **164-172行目**: PSCustomObject出力構築

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

```
Get-DbaTcpPort
    │
    ├─ -All モード
    │      │
    │      └─ Get-DbaNetworkConfiguration -OutputType Full
    │             └─ TcpIpAddresses展開
    │
    └─ デフォルトモード
           │
           ├─ Connect-DbaInstance -SqlInstance "TCP:$instance"
           │
           └─ $server.Query("SELECT local_net_address, local_tcp_port
                             FROM sys.dm_exec_connections
                             WHERE session_id = @@SPID")
```

### データフロー図

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

SqlInstance ────────────▶ -All判定
                                │
                    ┌───────────┴───────────┐
                    │                       │
                    ▼                       ▼
          Get-DbaNetworkConfiguration   TCP接続 + T-SQL
                    │                       │
                    ▼                       ▼
          TcpIpAddresses展開         dm_exec_connections
                    │                       │
                    └───────────┬───────────┘
                                │
                                ▼
                         PSCustomObject
                         (Port, IPAddress)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaTcpPort.ps1 | `public/Get-DbaTcpPort.ps1` | ソース | メインコマンド実装 |
| Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | ソース | ネットワーク構成取得（-All時に使用） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
