# 機能設計書 152-Get-DbaUptime

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Get-DbaUptime` コマンドレットの機能設計を記述する。本機能は、SQL ServerインスタンスおよびそのホストとなるWindowsサーバーの稼働時間（アップタイム）情報を取得するための機能である。

### 本機能の処理概要

SQL Serverインスタンスとホストサーバーの稼働時間を取得し、起動日時・稼働時間（TimeSpan）・フォーマット済み文字列を含む包括的な情報を提供する機能である。

**業務上の目的・背景**：システム安定性の監視、予期しない再起動の検出、コンプライアンスレポートの作成において、SQL Serverとホストサーバーのアップタイム情報は重要な指標である。手動での確認は複数の異なるコマンドを実行する必要があり、複数サーバーの監視を効率化するための自動化が求められる。

**機能の利用シーン**：
- 日次・週次のシステム稼働状況レポート作成
- 予期しない再起動の検出とアラート
- SLA遵守状況の確認
- 定期メンテナンス後の稼働確認
- サーバー移行前後の安定性比較

**主要な処理内容**：
1. SQL Serverインスタンスへの接続とtempdb作成日時（SQL Server起動時刻）の取得
2. Windowsサーバーへの接続と最終起動時刻の取得（CIM/WMI経由）
3. 現在時刻との差分計算による稼働時間の算出
4. TimeSpanオブジェクトとフォーマット済み文字列の両方を出力

**関連システム・外部連携**：SQL Server Management Objects (SMO)、CIM (Common Information Model) / WMI (Windows Management Instrumentation) を使用してSQL ServerおよびWindowsサーバーと連携する。

**権限による制御**：SQL Serverへの接続権限（tempdb参照）、Windowsサーバーへのリモート管理権限（CIM/WMI）が必要。

## 関連画面

本機能はコマンドライン機能であり、直接的な関連画面は存在しない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | - |

## 機能種別

データ取得・計算処理（稼働時間の算出）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス。パイプライン入力対応 | 有効なインスタンス名形式 |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 | 有効なPSCredentialオブジェクト |
| Credential | PSCredential | No | Windowsサーバーへの接続用資格情報（CIM/WMI用） | 有効なPSCredentialオブジェクト |
| EnableException | switch | No | 例外を直接スローするかどうか | - |

### 入力データソース

- ユーザー入力（コマンドラインパラメータ）
- パイプライン入力（SqlInstance）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | WindowsサーバーのFQDN |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlServer | string | SQL Serverフルネーム |
| SqlStartTime | DateTime | SQL Server起動日時（tempdb作成日時） |
| SqlUptime | TimeSpan | SQL Server稼働時間 |
| SinceSqlStart | string | SQL Server稼働時間（"X days Y hours Z minutes A seconds"形式） |
| WindowsBootTime | DateTime | Windows最終起動日時 |
| WindowsUptime | TimeSpan | Windows稼働時間 |
| SinceWindowsBoot | string | Windows稼働時間（"X days Y hours Z minutes A seconds"形式） |

### 出力先

- PowerShellパイプライン（PSCustomObject）
- コンソール出力

## 処理フロー

### 処理シーケンス

```
1. 現在時刻の取得
   └─ UTC時刻として取得し、基準時刻として使用

2. インスタンスごとの処理ループ
   └─ 各SqlInstanceに対して順次処理

3. SQL Server接続
   └─ Connect-DbaInstanceを使用して接続確立

4. SQL Server起動時刻取得
   └─ tempdbデータベースの作成日時を取得

5. SQL Server稼働時間計算
   └─ 現在時刻との差分をTimeSpanとして算出

6. Windowsサーバー名解決
   └─ Resolve-DbaNetworkNameでFQDN取得

7. Windows起動時刻取得
   └─ Get-DbaOperatingSystem経由でLastBootTime取得
   └─ 失敗時はCIM DCOM経由でフォールバック

8. Windows稼働時間計算
   └─ 現在時刻との差分をTimeSpanとして算出

9. オブジェクト出力
   └─ 全情報をPSCustomObjectとして出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[現在時刻取得 UTC]
    B --> C{SqlInstanceループ}
    C --> D[Connect-DbaInstance]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function]
    F --> C
    E -->|Yes| G[tempdb.CreateDate取得]
    G --> H[SQL Uptime計算]
    H --> I[Resolve-DbaNetworkName]
    I --> J[Get-DbaOperatingSystem]
    J --> K{LastBootTime取得成功?}
    K -->|No| L[CIM DCOM フォールバック]
    L --> M{DCOM成功?}
    M -->|No| N[Stop-Function]
    N --> C
    M -->|Yes| O[Windows Uptime計算]
    K -->|Yes| O
    O --> P[PSCustomObject出力]
    P --> C
    C -->|完了| Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 接続エラー継続 | 接続エラー時は次のインスタンスへ処理を継続 | 複数インスタンス指定時 |
| BR-002 | CIMフォールバック | Get-DbaOperatingSystem失敗時はCIM DCOMで再試行 | Windows情報取得失敗時 |
| BR-003 | UTC基準計算 | 稼働時間はUTC基準で計算 | 常時 |

### 計算ロジック

- **SQL Server稼働時間**: `現在時刻(UTC) - tempdb.CreateDate(UTC)`
- **Windows稼働時間**: `現在時刻(UTC) - LastBootTime(UTC)`
- **フォーマット**: `"{Days} days {Hours} hours {Minutes} minutes {Seconds} seconds"`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| SQL Server起動時刻取得 | tempdb.sys.databases | SELECT | SMO経由でtempdb作成日時を取得 |

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

#### tempdb.sys.databases

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | create_date | tempdbデータベースのレコード | SQL Server起動時に再作成されるため起動時刻と同一 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | SQL接続エラー | SQL Serverインスタンスへの接続失敗 | Stop-Functionで警告、次インスタンスへ継続 |
| WMIError | CIM/WMI接続エラー | Windowsサーバーへのリモート接続失敗 | DCOMフォールバック後、失敗なら継続 |

### リトライ仕様

- Windows情報取得: WinRM/WSMAN失敗時にCIM DCOMで自動リトライ

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

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

## パフォーマンス要件

- SQL Server接続とtempdb情報取得は通常1秒未満
- Windows情報取得はネットワーク状況により数秒かかる場合あり
- 複数インスタンス指定時は順次処理

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

- SQL Server接続には適切な認証情報が必要
- Windows CIM/WMI接続にはリモート管理権限が必要
- Credentialパラメータで別途Windows認証情報を指定可能

## 備考

- tempdbはSQL Server起動時に再作成されるため、その作成日時がSQL Server起動時刻となる
- 関連コマンド: Get-DbaOperatingSystem, Resolve-DbaNetworkName

---

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

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

### 推奨読解順序

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

本機能の出力はPSCustomObjectで、SQL ServerとWindowsの両方のアップタイム情報を含む。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaUptime.ps1 | `public/Get-DbaUptime.ps1` | 127-137行目の出力オブジェクト構造を確認 |

**読解のコツ**: TimeSpanオブジェクト（SqlUptime, WindowsUptime）と文字列フォーマット（SinceSqlStart, SinceWindowsBoot）の両方が提供される点に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaUptime.ps1 | `public/Get-DbaUptime.ps1` | 関数全体の構造、beginブロックの現在時刻取得 |

**主要処理フロー**:
1. **71-78行目**: パラメータ定義
2. **80-82行目**: beginブロックで現在時刻(UTC)を取得
3. **83-139行目**: processブロックのメイン処理

#### Step 3: SQL Server情報取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaUptime.ps1 | `public/Get-DbaUptime.ps1` | 96-106行目のSQL Server起動時刻取得と稼働時間計算 |

**主要処理フロー**:
- **103行目**: `$server.Databases["tempdb"].CreateDate` でSQL Server起動時刻取得
- **104行目**: `New-TimeSpan` で稼働時間を計算
- **105行目**: フォーマット済み文字列の生成

#### Step 4: Windows情報取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaUptime.ps1 | `public/Get-DbaUptime.ps1` | 107-125行目のWindows起動時刻取得とフォールバック処理 |

**主要処理フロー**:
- **107行目**: `Resolve-DbaNetworkName` でサーバー名解決
- **111行目**: `Get-DbaOperatingSystem` でLastBootTime取得
- **115-124行目**: 失敗時のCIM DCOMフォールバック処理

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

```
Get-DbaUptime
    │
    ├─ Connect-DbaInstance
    │      └─ SMO Server オブジェクト生成
    │
    ├─ $server.Databases["tempdb"].CreateDate
    │      └─ SQL Server起動時刻取得
    │
    ├─ Resolve-DbaNetworkName
    │      └─ サーバー名FQDN解決
    │
    ├─ Get-DbaOperatingSystem
    │      └─ CIM経由でLastBootTime取得
    │
    └─ New-CimSession (フォールバック)
           └─ DCOM経由でWin32_OperatingSystem取得
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ SMO Server
                         │
                         ▼
              tempdb.CreateDate 取得
                         │
                         ▼
              SQL Uptime 計算 ───────────────────┐
                                                  │
Credential ───▶ Resolve-DbaNetworkName            │
                         │                        │
                         ▼                        │
              Get-DbaOperatingSystem              │
                   │   │                          │
            成功   │   │ 失敗                     │
                   │   ▼                          │
                   │  CIM DCOM                    │
                   │   │                          │
                   ▼   ▼                          │
              Windows Uptime 計算                 │
                         │                        │
                         ▼                        ▼
              PSCustomObject 生成 ◀───────────────┘
                         │
                         ▼
                  パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaUptime.ps1 | `public/Get-DbaUptime.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立 |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | サーバー名解決 |
| Get-DbaOperatingSystem.ps1 | `public/Get-DbaOperatingSystem.ps1` | ソース | Windows OS情報取得 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理ユーティリティ |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | ログ出力ユーティリティ |
