# 機能設計書 367-Get-DbaNetworkActivity

## 概要

本ドキュメントは、SQL Serverホストコンピュータのネットワークトラフィック統計を取得するための dbatools コマンド `Get-DbaNetworkActivity` の機能設計を記述する。

### 本機能の処理概要

`Get-DbaNetworkActivity` は、ターゲットコンピュータ上の全ネットワークインターフェースについて、リアルタイムのネットワークトラフィック統計（受信/送信/合計バイト数、帯域幅）を取得するコマンドである。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題において、ネットワークがボトルネックになることがある。特に、大量データ転送、バックアップ操作、レプリケーション時にネットワーク帯域の使用状況を確認する必要がある。Windows Performance Monitorを手動で確認する方法は非効率であり、複数サーバーのネットワーク状況を一括で監視することができない。

**機能の利用シーン**：
- SQL Server接続遅延のトラブルシューティング
- バックアップ/リストア操作時のネットワーク帯域監視
- データ移行前のネットワークキャパシティ確認
- レプリケーションパフォーマンス問題の診断

**主要な処理内容**：
1. コンピュータ名からインスタンス部分を分離
2. ターゲットコンピュータ名の解決（Resolve-DbaNetworkName）
3. CIMセッションの確立（WSMan優先、失敗時DCOM）
4. Win32_PerfFormattedData_Tcpip_NetworkInterface CIMクラスの照会
5. 帯域幅の人間可読フォーマット変換
6. 結果のフォーマットと出力

**関連システム・外部連携**：Windows CIM/WMI（Win32_PerfFormattedData_Tcpip_NetworkInterface）

**権限による制御**：対象コンピュータのローカル管理者権限が必要

## 関連画面

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

## 機能種別

情報取得 / パフォーマンス監視

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | string[] | No | 対象コンピュータ名（デフォルト: ローカル） | パイプライン対応 |
| Credential | PSCredential | No | 接続資格情報 | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- Windows CIM: Win32_PerfFormattedData_Tcpip_NetworkInterface

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | コンピュータ名 |
| NIC | String | ネットワークインターフェース名 |
| BytesReceivedPersec | UInt64 | 毎秒受信バイト数 |
| BytesSentPersec | UInt64 | 毎秒送信バイト数 |
| BytesTotalPersec | UInt64 | 毎秒合計バイト数 |
| Bandwidth | String | 帯域幅（人間可読形式: 10Gb, 1Gb等） |

### 出力先

PowerShellパイプライン（Win32_PerfFormattedData_Tcpip_NetworkInterface）

## 処理フロー

### 処理シーケンス

```
1. Begin ブロック
   └─ ComputerNameからインスタンス部分を分離（\で分割）
   └─ DCOMセッションオプションの準備

2. Process ブロック - 各ComputerNameに対して
   └─ Resolve-DbaNetworkName でコンピュータ名を解決
       └─ 解決失敗: 警告出力・スキップ
   └─ CIMセッション確立（WSMan優先）
       └─ WSMan失敗: DCOMにフォールバック
   └─ Win32_PerfFormattedData_Tcpip_NetworkInterface取得
   └─ 動的プロパティの追加:
       ├─ ComputerName (ScriptProperty)
       └─ Bandwidth (ScriptProperty): CurrentBandwidthの変換
   └─ Select-DefaultViewで出力整形
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ComputerName分離]
    B --> C[各ComputerNameループ]
    C --> D[Resolve-DbaNetworkName]
    D --> E{解決成功?}
    E -->|No| F[警告: 接続失敗]
    F --> C
    E -->|Yes| G[WSManでCIMSession作成]
    G --> H{WSMan成功?}
    H -->|No| I[DCOMでCIMSession作成]
    H -->|Yes| J[NIC情報取得]
    I --> K{DCOM成功?}
    K -->|No| L[警告: Session作成失敗]
    L --> C
    K -->|Yes| J
    J --> M[ComputerName/Bandwidth追加]
    M --> N[各NIC出力]
    N --> C
    C --> O{次のComputer?}
    O -->|Yes| C
    O -->|No| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ローカル管理者必須 | 対象コンピュータのローカル管理者権限が必要 | 常に |
| BR-02 | WSMan優先 | WSMan接続を優先、失敗時DCOMにフォールバック | CIMSession作成時 |
| BR-03 | インスタンス分離 | ComputerName\Instance形式の場合、コンピュータ名部分のみ使用 | 常に |

### 計算ロジック

帯域幅変換:
```
10000000000 → '10Gb'
1000000000  → '1Gb'
100000000   → '100Mb'
10000000    → '10Mb'
1000000     → '1Mb'
100000      → '100Kb'
default     → 'Low'
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | SQLデータベースへの操作なし |

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

SQLデータベースへの操作なし（Windows CIM照会のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | コンピュータ名解決失敗 | ネットワーク接続確認 |
| - | セッションエラー | WSMan/DCOM両方失敗 | リモート管理設定確認 |
| - | 権限エラー | ローカル管理者権限なし | 適切な資格情報を指定 |

### リトライ仕様

WSMan失敗時にDCOMにフォールバック（自動リトライ）

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

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

## パフォーマンス要件

特に定義なし。CIM照会のためネットワーク遅延に依存。

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

- ローカル管理者権限が必要
- 資格情報はPSCredentialオブジェクトで安全に取り扱う
- ネットワークトラフィック情報の露出に注意

## 備考

- スナップショット情報であり、継続的な監視には繰り返し実行が必要
- 仮想NICも含めて全てのネットワークインターフェースが出力される
- CurrentBandwidthはインターフェースの最大帯域幅を示す

---

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

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

### 推奨読解順序

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

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

**主要処理フロー**:
- **79-81行目**: ComputerNameパラメータ（ValueFromPipeline、エイリアス定義）

#### Step 2: Beginブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaNetworkActivity.ps1 | `public/Get-DbaNetworkActivity.ps1` | beginブロック（86-89行目）で初期化処理を確認 |

**主要処理フロー**:
- **87行目**: ComputerNameを\で分割してインスタンス部分を除去
- **88行目**: DCOMセッションオプションの準備

#### Step 3: CIMセッション確立を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaNetworkActivity.ps1 | `public/Get-DbaNetworkActivity.ps1` | processブロック（92-100行目）でCIMセッション確立を確認 |

**主要処理フロー**:
- **96行目**: WSManでCIMSession作成試行
- **97-99行目**: WSMan失敗時にDCOMでリトライ

#### Step 4: NIC情報取得と出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaNetworkActivity.ps1 | `public/Get-DbaNetworkActivity.ps1` | processブロック（101-106行目）でNIC取得と動的プロパティ追加を確認 |

**主要処理フロー**:
- **103行目**: Get-CimInstanceでNIC情報取得
- **104行目**: ComputerNameスクリプトプロパティ追加
- **105行目**: Bandwidthスクリプトプロパティ追加（switch文で変換）
- **106行目**: Select-DefaultViewで出力整形

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

```
Get-DbaNetworkActivity
    │
    ├─ Resolve-DbaNetworkName (コンピュータ名解決)
    │
    ├─ New-CimSession -Protocol WSMan
    │      └─ 失敗時: New-CimSession -SessionOption DCOM
    │
    ├─ Get-CimInstance -ClassName Win32_PerfFormattedData_Tcpip_NetworkInterface
    │
    ├─ Add-Member -MemberType ScriptProperty (ComputerName)
    │
    ├─ Add-Member -MemberType ScriptProperty (Bandwidth)
    │
    └─ Select-DefaultView
```

### データフロー図

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

ComputerName ───────────▶ Resolve-DbaNetworkName
        │                       │
        │                       ▼
        │                CIMSession確立
        │                       │
        │                       ▼
        └───────────▶ Win32_PerfFormattedData取得
                                │
                                ▼
                         動的プロパティ追加 ───────▶ CIM Object
                                                   (NIC, BytesReceived, Bandwidth)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaNetworkActivity.ps1 | `public/Get-DbaNetworkActivity.ps1` | ソース | メインコマンド実装 |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | コンピュータ名解決 |
| Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | ソース | ネットワーク構成取得（関連コマンド） |
