# 画面設計書 240-インストール日取得

## 概要

本ドキュメントは、dbatools PowerShell モジュールの `Get-DbaInstanceInstallDate` コマンドに関する設計書です。このコマンドは、SQL Server インスタンスのインストール日時を取得し、コンプライアンス監査やインフラストラクチャ追跡に必要な情報を提供します。

### 本画面の処理概要

**業務上の目的・背景**：SQL Server のインストール日を把握することは、ライセンス管理、コンプライアンス監査、ハードウェアリフレッシュサイクルの追跡において重要です。本コマンドは、システムテーブルを照会して SQL Server がいつインストールされたかを特定し、オプションで Windows OS のインストール日も取得します。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから `Get-DbaInstanceInstallDate` コマンドを実行します。パイプライン入力として SQL Server インスタンスを受け取ることも可能です。

**主要な操作・処理内容**：
1. SQL Server インスタンスに接続
2. sys.server_principals（SQL 2005+）または dbo.sysservers（SQL 2000）からインストール日を取得
3. IncludeWindows 指定時は WMI で Windows インストール日も取得
4. 結果をパイプラインに出力

**画面遷移**：CLI コマンドのため画面遷移は存在しませんが、出力結果は他のコマンドにパイプライン接続可能です。

**権限による表示制御**：SQL Server への接続権限が必要です。IncludeWindows 使用時は Windows サーバーへの WMI アクセス権限も必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 316 | Get-DbaInstanceInstallDate | 主機能 | インスタンスインストール日の取得 |
| 90 | Connect-DbaInstance | 補助機能 | SQL Server インスタンスへの接続 |

## 画面種別

CLI コマンド（情報取得）

## URL/ルーティング

PowerShell コマンド: `Get-DbaInstanceInstallDate`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | SQL Server インスタンス |
| SqlCredential | PSCredential | No | SQL Server 認証情報 |
| Credential | PSCredential | No | Windows 認証情報（WMI 用） |
| IncludeWindows | switch | No | Windows インストール日も取得 |
| EnableException | switch | No | 例外を有効化 |

### 出力項目（デフォルト）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| SqlInstallDate | DbaDateTime | SQL Server インストール日 |

### 出力項目（IncludeWindows 指定時）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| SqlInstallDate | DbaDateTime | SQL Server インストール日 |
| WindowsInstallDate | DbaDateTime | Windows インストール日 |

## 表示項目

Select-DefaultView により、IncludeWindows の指定有無に応じて表示プロパティが変更されます。

## イベント仕様

### 1-コマンド実行

1. SQL Server インスタンスへの接続
2. SQL Server バージョン判定:
   - バージョン 9 以上: sys.server_principals から SA アカウント（SID 0x010100000000000512000000）の create_date を取得
   - バージョン 9 未満: dbo.sysservers から schemadate を取得
3. 取得失敗時は dbo.sysservers でリトライ
4. IncludeWindows 指定時:
   - Get-DbaCmObject で Win32_OperatingSystem.InstallDate を取得
5. 結果をパイプラインに出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| インストール日取得 | sys.server_principals | SELECT | SA アカウント作成日取得 |
| インストール日取得（旧） | dbo.sysservers | SELECT | スキーマ日付取得 |

### テーブル別更新項目詳細

このコマンドは読み取り専用であり、データベースの更新は行いません。

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| Verbose | "Getting Install Date for: $instance" | 処理開始時 |
| Verbose | "Trying again to get Install Date for: $instance" | リトライ時 |
| Error | "Failure" | SQL Server 接続エラー |
| Error | "Failed to connect to: $WindowsServerName" | Windows 接続エラー |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server 接続失敗 | Stop-Function で警告、次のインスタンスへ続行 |
| sys.server_principals 取得失敗 | dbo.sysservers でリトライ |
| Windows 接続失敗 | Stop-Function で警告、次のインスタンスへ続行 |

## 備考

- SQL Server 2005 以降: sys.server_principals から SA アカウント（well-known SID）の create_date を使用
- SQL Server 2000: dbo.sysservers の schemadate を使用
- SA アカウントの SID: 0x010100000000000512000000（well-known SID）
- sys.server_principals から取得失敗時は自動的に dbo.sysservers でリトライ
- DbaDateTime 型は書式化された日時表示を提供
- IncludeWindows は Windows サーバーへの WMI アクセス（Get-DbaCmObject）を使用
- Central Management Server からのパイプライン入力をサポート

---

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

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

### 推奨読解順序

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

出力される PSCustomObject の構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaInstanceInstallDate.ps1 | `public/Get-DbaInstanceInstallDate.ps1` | 行131-136: 出力オブジェクト構造 |

**読解のコツ**: IncludeWindows の有無で出力プロパティが変わる構造を確認する。

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

処理の起点となるファイル・関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaInstanceInstallDate.ps1 | `public/Get-DbaInstanceInstallDate.ps1` | 関数全体の構造と処理フロー |

**主要処理フロー**:
1. **行99-103**: 接続処理
2. **行105-108**: SQL Server 2005+ 用クエリ
3. **行109-112**: SQL Server 2000 用クエリ
4. **行114-118**: フォールバックリトライ
5. **行123-128**: Windows インストール日取得（IncludeWindows 時）
6. **行131-143**: 出力オブジェクト生成

#### Step 3: バージョン判定とフォールバックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaInstanceInstallDate.ps1 | `public/Get-DbaInstanceInstallDate.ps1` | 行105-118: バージョン判定とフォールバック |

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

```
Get-DbaInstanceInstallDate
    │
    ├─ Connect-DbaInstance (行100)
    │      └─ SQL Server SMO 接続
    │
    ├─ バージョン判定 (行105)
    │      ├─ VersionMajor >= 9
    │      │      └─ sys.server_principals クエリ
    │      └─ VersionMajor < 9
    │             └─ dbo.sysservers クエリ
    │
    ├─ フォールバック (行114-118)
    │      └─ dbo.sysservers クエリ（リトライ）
    │
    └─ Get-DbaCmObject (行125)
           └─ Win32_OperatingSystem.InstallDate
```

### データフロー図

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

SqlInstance ───────────▶ Connect-DbaInstance ───────────▶ Server Object
                               │
                         バージョン判定
                               │
                         sys.server_principals or
                         dbo.sysservers クエリ ─────────────▶ SqlInstallDate
                               │
IncludeWindows ────────▶ Get-DbaCmObject ──────────────────▶ WindowsInstallDate
                               │
                         Select-DefaultView ────────────────▶ PSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaInstanceInstallDate.ps1 | `public/Get-DbaInstanceInstallDate.ps1` | ソース | メインコマンド実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続処理 |
