# 機能設計書 372-Resolve-DbaNetworkName

## 概要

本ドキュメントは、dbatools PowerShellモジュールのResolve-DbaNetworkNameコマンドの機能設計を定義する。このコマンドはSQL Server接続のトラブルシューティングや検証のために、包括的なネットワーク名解決と詳細なネットワーク情報の取得を行う。

### 本機能の処理概要

**業務上の目的・背景**：SQL Server接続問題の診断において、正確なネットワーク情報の把握は不可欠である。DNS、Active Directory、およびコンピュータ設定間の不一致（disjoint domain環境など）は接続エラーの一般的な原因であり、これらの問題を特定するための統合的なツールが必要とされる。従来のpingやnslookupでは得られない詳細な情報を提供することで、接続問題の迅速な解決を支援する。

**機能の利用シーン**：
- SQL Server接続前のネットワーク構成検証
- 接続エラー発生時のトラブルシューティング
- マルチホーム環境やdisjoint domain環境での名前解決確認
- 登録済みサーバーリストのネットワーク情報一括取得

**主要な処理内容**：
1. DNS名前解決（GetHostEntry）によるIPアドレス取得
2. 逆引きDNSルックアップによるFQDN取得
3. ICMPピングによる応答IPアドレスの特定
4. WMI/CIMクエリによるリモートコンピュータ情報の取得
5. 包括的なネットワーク情報オブジェクトの構築

**関連システム・外部連携**：
- DNS（System.Net.Dns）
- ICMP（System.Net.NetworkInformation.Ping）
- WMI/CIM（Get-DbaCmObject、Invoke-Command2）
- Windows Remote Management (WinRM)

**権限による制御**：リモートコンピュータへのWMI/CIMアクセスには適切な権限が必要。Turboモード使用時はDNS解決のみで権限不要。

## 関連画面

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

## 機能種別

データ連携 / 診断・検証

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | 解決対象のコンピュータ名、IPアドレス、またはSQL Serverインスタンス | デフォルト: $env:COMPUTERNAME |
| Credential | PSCredential | No | リモート接続用の代替資格情報 | - |
| Turbo | switch | No | DNS解決のみの高速モード | Alias: FastParrot |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- ComputerNameパラメータ: ユーザー指定、パイプライン入力、またはGet-DbaRegServerからの入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| InputName | string | ユーザーが入力した元の値 |
| ComputerName | string | ホスト名のみ（大文字） |
| IPAddress | string | 応答したIPアドレス（IPv4またはIPv6） |
| DNSHostname | string | DNS解決からのホスト名（小文字） |
| DNSDomain | string | DNSからのドメインサフィックス |
| Domain | string | Active Directoryドメイン名 |
| DNSHostEntry | string | GetHostEntryによる完全修飾ドメイン名 |
| FQDN | string | ComputerName.Domain形式の従来表記 |
| FullComputerName | string | OS内で設定された完全コンピュータ名（最も信頼性の高い値） |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. Begin ブロック: ヘルパー関数の定義
   └─ Get-ComputerDomainName関数の定義（FQDN/ComputerNameからドメイン名を推測）

2. Process ブロック: メインの処理ループ
   └─ バイパス設定の確認
   └─ 非Windowsクライアントの場合はTurboモードを強制
   └─ 各コンピュータに対する処理
      └─ DNS名前解決（GetHostEntry）
      └─ IPアドレスの逆引き（GetHostByAddress）
      └─ 初期結果オブジェクトの構築
      └─ Turboモードの場合はここで出力して終了
      └─ ICMPピングで応答IPを特定
      └─ WMI/CIMクエリでリモート情報取得
      └─ 最終結果オブジェクトの出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{バイパス設定?}
    B -->|Yes| C[バイパス結果を出力]
    B -->|No| D{非Windowsクライアント?}
    D -->|Yes| E[Turboモード強制]
    D -->|No| F[通常処理開始]
    E --> F
    F --> G[DNS GetHostEntry]
    G --> H{解決成功?}
    H -->|No| I[Stop-Function]
    H -->|Yes| J[逆引きDNS GetHostByAddress]
    J --> K[初期結果オブジェクト構築]
    K --> L{Turboモード?}
    L -->|Yes| M[結果出力]
    L -->|No| N[ICMPピングテスト]
    N --> O{異なるIP応答?}
    O -->|Yes| P[再度逆引きDNS]
    O -->|No| Q[WMI/CIMクエリ]
    P --> Q
    Q --> R[Domain情報更新]
    R --> S[DNSドメイン取得]
    S --> T[DNSHostEntry更新]
    T --> M
    I --> U[次のコンピュータ]
    M --> U
    U --> V{次あり?}
    V -->|Yes| F
    V -->|No| W[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | FullComputerName優先 | 信頼性の観点からFullComputerNameの使用を推奨 | 常に |
| BR-002 | Turbo自動有効化 | 非WindowsクライアントではTurboモードが自動的に有効化 | 非Windowsクライアント時 |
| BR-003 | IPv4優先 | DNS解決結果はIPv4を優先してソート | 常に |
| BR-004 | disjoint domain対応 | ADとDNSが一致しない環境にも対応 | 常に |

### 計算ロジック

特になし

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

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

本コマンドはSQL Serverデータベースへの直接アクセスは行わない。ネットワーク名前解決のみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | DNSResolutionError | DNS名前解決に失敗 | Stop-Functionで継続、対象コンピュータをスキップ |
| - | WMIQueryError | WMI/CIMクエリ失敗 | 警告を出力して継続、部分的な結果を返す |
| - | RemoteAccessError | リモートコンピュータへのアクセス失敗 | 警告を出力して継続 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- ICMPピングタイムアウト: 1000ミリ秒
- Turboモード: WMI/CIMクエリをスキップして高速化
- 複数コンピュータ処理: 順次処理（並列処理なし）

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

- Credentialパラメータによる代替資格情報のサポート
- WMI/CIMアクセスには適切な権限が必要
- Turboモードでは認証不要（DNS解決のみ）

## 備考

- FQDNが"ComputerName.Domain"形式と一致しないケースがある（disjoint domain環境）
- FullComputerNameはADとDNSの両方で唯一の一致点であり、最も正確な値

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | **139-150行目**: バイパスモード時の出力オブジェクト構造 |
| 1-2 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | **194-204行目**: 通常モードの初期出力オブジェクト構造 |

**読解のコツ**: InputName, ComputerName, IPAddress等9つのプロパティがすべての解決方法の基本構造となる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | **109-117行目**: パラメータ定義 |

**主要処理フロー**:
1. **111-112行目**: ComputerNameパラメータ（ValueFromPipeline、デフォルト: $env:COMPUTERNAME）
2. **113行目**: Credentialパラメータ
3. **114-115行目**: Turboスイッチ（Alias: FastParrot）

#### Step 3: Beginブロック - ヘルパー関数

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | **118-135行目**: Get-ComputerDomainName関数 |

**主要処理フロー**:
- **119-134行目**: FQDNとComputerNameからドメイン名を推測するロジック
- FQDNにドットが含まれるかどうかで分岐

#### Step 4: Processブロック - 名前解決処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | **136-153行目**: バイパスモードとWindows判定 |
| 4-2 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | **167-175行目**: DNS名前解決（GetHostEntry） |
| 4-3 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | **177-184行目**: 逆引きDNS（GetHostByAddress） |
| 4-4 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | **211-220行目**: ICMPピングテスト |
| 4-5 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | **248-268行目**: WMI/CIMクエリ |

**主要処理フロー**:
- **170行目**: System.Net.Dns::GetHostEntryによる名前解決
- **171行目**: AddressFamilyでソート（IPv4優先）
- **180行目**: GetHostByAddressで逆引き
- **212行目**: System.Net.NetworkInformation.Pingオブジェクト作成
- **213行目**: 1000ミリ秒タイムアウト
- **259行目**: Get-DbaCmObjectでwin32_ComputerSystem取得
- **271行目**: Invoke-Command2でDNSサフィックス取得

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

```
Resolve-DbaNetworkName
    │
    ├─ Get-DbatoolsConfigValue (バイパス確認)
    │
    ├─ Test-Windows (クライアントOS判定)
    │
    ├─ [System.Net.Dns]::GetHostEntry
    │      └─ DNS名前解決
    │
    ├─ [System.Net.Dns]::GetHostByAddress
    │      └─ 逆引きDNS
    │
    ├─ System.Net.NetworkInformation.Ping
    │      └─ ICMP接続テスト
    │
    ├─ Get-DbaCmObject
    │      └─ WMI win32_ComputerSystem取得
    │
    └─ Invoke-Command2
           └─ リモートDNSサフィックス取得
```

### データフロー図

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

ComputerName ─────────────▶ DNS GetHostEntry ─────────────▶ IPAddress
                                    │
                                    ▼
                           GetHostByAddress ─────────────▶ FQDN
                                    │
                                    ▼
                           (Turboモード終了)
                                    │
                                    ▼
                           ICMPピング ─────────────────▶ 応答IP
                                    │
                                    ▼
                           WMI/CIM ─────────────────────▶ Domain, DNSDomain
                                    │
                                    ▼
                           PSCustomObject ─────────────▶ 包括的結果出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | メイン機能実装 |
| Resolve-DbaNetworkName.Tests.ps1 | `tests/Resolve-DbaNetworkName.Tests.ps1` | テスト | ユニットテスト |
