# 画面設計書 134-ネットワーク名解決

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるネットワーク名解決機能の設計仕様を定義する。

### 本画面の処理概要

コンピュータ名、IPアドレス、SQL Serverインスタンス名を入力として、包括的なネットワーク名情報を解決・取得する機能を提供する。

**業務上の目的・背景**：SQL Server接続のトラブルシューティングや接続前の検証において、正確なネットワーク情報の把握が重要となる。特に、Active DirectoryとDNSの設定が一致しない「disjoint domain」環境では、コンピュータ名の解決が複雑になる。本機能は、DNS検索、ICMPテスト、WMI/CIMクエリを組み合わせて、正確なネットワーク接続情報を提供する。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスする
- `Resolve-DbaNetworkName -ComputerName <コンピュータ名>`

**主要な操作・処理内容**：
1. DNSを使用したホスト名解決（GetHostEntry）
2. IPアドレスの逆引き解決（GetHostByAddress）
3. ICMPによる応答IPアドレスの特定
4. WMI/CIMを使用した詳細なコンピュータ情報取得
5. ADドメインとDNSドメインの両方の情報を収集
6. FullComputerName（最も信頼できる名前）の決定

**画面遷移**：CLIベースのため画面遷移は存在しない。多くのdbatoolsコマンドから内部的に呼び出される重要なユーティリティ関数。

**権限による表示制御**：Turboモード以外の場合、対象コンピュータへのWMI/CIMアクセス権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 372 | Resolve-DbaNetworkName | 主機能 | ネットワーク名の解決 |
| - | Get-DbaCmObject | 補助機能 | WMI/CIMオブジェクト取得 |
| - | Invoke-Command2 | 補助機能 | リモートコマンド実行 |

## 画面種別

CLI（コマンドラインインターフェース）

## URL/ルーティング

該当なし（PowerShellコマンドレット）

## 入出力項目

### Resolve-DbaNetworkName

| 項目名 | データ型 | 必須 | 説明 |
|--------|----------|------|------|
| ComputerName | DbaInstanceParameter[] | いいえ | 対象コンピュータ名（デフォルト: ローカルコンピュータ） |
| Credential | PSCredential | いいえ | 接続に使用する資格情報 |
| Turbo | switch | いいえ | DNS解決のみの高速モード |
| EnableException | switch | いいえ | 例外を直接発生させるかどうか |

## 表示項目

### Resolve-DbaNetworkName 出力

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| InputName | string | ユーザーが入力した元の値 |
| ComputerName | string | ホスト名のみ（大文字） |
| IPAddress | string | 応答したIPアドレス（IPv4またはIPv6） |
| DNSHostname | string | DNSから取得したホスト名（小文字） |
| DNSDomain | string | DNSから取得したドメインサフィックス |
| Domain | string | Active Directoryから取得したドメイン名 |
| DNSHostEntry | string | System.Net.Dns.GetHostEntry()が返す完全修飾ドメイン名 |
| FQDN | string | ComputerName.Domain形式の従来表記 |
| FullComputerName | string | OS内で設定された完全なコンピュータ名（ADとDNSで一致する最も信頼できる名前） |

## イベント仕様

### 1-Resolve-DbaNetworkName実行（通常モード）

1. 入力がlocalhostの場合、$env:COMPUTERNAMEを使用
2. .NET Dns.GetHostEntryでホスト名を解決
3. AddressListからIPアドレスを取得（IPv4優先）
4. .NET Dns.GetHostByAddressでIPアドレスを逆引き
5. ICMPで各IPアドレスにPingを送信し、応答するIPを特定
6. 応答したIPが最初のIPと異なる場合、再度逆引き
7. Get-DbaCmObjectでwin32_ComputerSystemから詳細情報取得
8. Invoke-Command2でリモートからDNSドメインを取得
9. 最終的なFullComputerNameを決定

### 2-Resolve-DbaNetworkName実行（Turboモード）

1. DNS解決のみを実行
2. ICMPテストやWMI/CIMクエリをスキップ
3. より高速だが、disjoint domain環境では精度が低下する可能性

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

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

本機能はネットワーク情報を読み取り専用で取得するため、データベースやシステムへの更新は発生しない。

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| Resolve-DbaNetworkName | DNS | READ | DNSクエリ |
| Resolve-DbaNetworkName | win32_ComputerSystem | READ | WMI情報取得 |
| Resolve-DbaNetworkName | IPGlobalProperties | READ | ネットワーク設定取得 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|----------|----------|
| - | Error | DNS name {cName} not found | DNS解決失敗時 |
| - | Debug | Failed to resolve {ipaddress} using .NET.Dns GetHostByAddress | IP逆引き失敗時 |
| - | Verbose | Resolving {cName} using .NET.Dns GetHostEntry | DNS解決実行時 |
| - | Verbose | Resolving {ipaddress} using .NET.Dns GetHostByAddress | IP逆引き実行時 |
| - | Verbose | Unable to get domain name from {ComputerName} | WMIドメイン情報取得失敗時 |
| - | Verbose | Unable to get DNS domain information from {ComputerName} | リモートDNS情報取得失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| DNS解決失敗 | Stop-Functionでエラー記録、処理中止 |
| IP逆引き失敗 | GetHostEntryの結果をフォールバックとして使用 |
| ICMPタイムアウト | 最初のIPアドレスを使用 |
| WMI接続失敗 | DNS情報のみで結果を構築 |
| リモートコマンド実行失敗 | 既存の情報で結果を構築 |

## 備考

- **FullComputerName**はすべての環境で最も信頼できる名前であり、ADとDNSの両方で一致する
- disjoint domain環境ではFQDNとDNSHostEntryが異なる場合がある
- Turboモードは高速だが、非Windows環境では自動的に有効化される
- 設定値`commands.resolve-dbanetworkname.bypass`が有効な場合、入力をそのまま返す
- IPv4アドレスが優先的に使用される（AddressFamilyでソート）

---

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

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

### 推奨読解順序

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

まず、出力されるオブジェクトの各プロパティの意味を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | .OUTPUTSセクションで各プロパティの意味を確認（行59-75） |
| 1-2 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | 行23-32のコメントでプロパティの詳細な定義を確認 |

**読解のコツ**: InputName、ComputerName、DNSHostname、FQDNなど似た名前のプロパティの違いを理解することが重要。特にFullComputerNameがなぜ最も信頼できるかの説明（行33）に注目。

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

処理の起点となる関数のパラメータと内部関数の定義を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | beginブロック内のGet-ComputerDomainName関数（行119-134） |

**主要処理フロー**:
1. **行119-134**: ドメイン名を推測する内部関数
2. **行137-153**: バイパスモード処理
3. **行155-158**: 非Windows環境でのTurbo強制有効化

#### Step 3: メイン処理フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | processブロック内の名前解決ロジック |

**主要処理フロー**:
- **行168-175**: DNS GetHostEntry呼び出しとIPアドレス取得
- **行178-184**: GetHostByAddressによるIP逆引き
- **行186-191**: FQDNの構築
- **行194-204**: 初期結果オブジェクトの構築
- **行205-208**: Turboモード時は即座に結果を返却
- **行212-220**: ICMPによる応答IPの特定
- **行224-246**: 応答IPが異なる場合の再解決
- **行249-284**: WMI/リモートコマンドによる詳細情報取得
- **行287-292**: 最終的なDNSHostEntry解決

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

```
Resolve-DbaNetworkName
    |
    +-- バイパスチェック (Get-DbatoolsConfigValue)
    |
    +-- Test-Windows (非Windows環境検出)
    |
    +-- foreach ($computer in $ComputerName)
            |
            +-- [System.Net.Dns]::GetHostEntry()
            |       +-- DNSホスト名解決
            |
            +-- [System.Net.Dns]::GetHostByAddress()
            |       +-- IP逆引き
            |
            +-- Get-ComputerDomainName()
            |       +-- ドメイン名推測
            |
            +-- [Turboモード終了点]
            |
            +-- [System.Net.NetworkInformation.Ping]
            |       +-- ICMP応答IP特定
            |
            +-- Get-DbaCmObject
            |       +-- win32_ComputerSystem取得
            |
            +-- Invoke-Command2
            |       +-- リモートDNSドメイン取得
            |
            +-- [System.Net.Dns]::GetHostEntry()
                    +-- FullComputerNameの最終解決
```

### データフロー図

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

ComputerName ────────▶ GetHostEntry ────────────────▶ IPAddress[]
    |                        |
    v                        v
              ┌─────────────────────────────────┐
              │     GetHostByAddress (逆引き)    │
              └─────────────────────────────────┘
                             |
                             v
              ┌─────────────────────────────────┐
              │  Get-ComputerDomainName         │
              │  (FQDNとドメイン名推測)          │
              └─────────────────────────────────┘
                             |
             ┌───────────────┼───────────────┐
             │               │               │
      [Turbo]│               │               │[通常]
             v               │               v
      結果出力               │     ┌─────────────────┐
                            │     │  ICMP Ping      │
                            │     │  (応答IP特定)    │
                            │     └─────────────────┘
                            │               |
                            │               v
                            │     ┌─────────────────┐
                            │     │ Get-DbaCmObject │
                            │     │ (WMI情報取得)   │
                            │     └─────────────────┘
                            │               |
                            │               v
                            │     ┌─────────────────┐
                            │     │ Invoke-Command2 │
                            │     │ (リモートDNS)   │
                            │     └─────────────────┘
                            │               |
                            v               v
                    ┌──────────────────────────────┐
                    │  [PSCustomObject] 結果       │
                    │  InputName, ComputerName,    │
                    │  IPAddress, DNSHostname,     │
                    │  DNSDomain, Domain,          │
                    │  DNSHostEntry, FQDN,         │
                    │  FullComputerName            │
                    └──────────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | ネットワーク名解決メインコマンド |
| Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | ソース | WMI/CIMオブジェクト取得ユーティリティ |
| Invoke-Command2.ps1 | `internal/functions/Invoke-Command2.ps1` | ソース | リモートコマンド実行ラッパー |
