# 機能設計書 337-Get-DbaInstanceProperty

## 概要

本ドキュメントは、SQL Serverインスタンスの包括的な構成プロパティを取得する機能「Get-DbaInstanceProperty」の設計仕様を記載する。

### 本機能の処理概要

Get-DbaInstancePropertyは、SQL ServerのInformation、UserOptions、Settingsコレクションからすべてのインスタンスレベル構成プロパティをSMO経由で取得する機能である。デフォルトファイルパス、メモリ構成、セキュリティオプション、ユーザーデフォルトなどのサーバー設定の完全なインベントリを標準化された形式で提供する。

**業務上の目的・背景**：構成監査、コンプライアンスレポート、環境比較、構成関連の問題のトラブルシューティングに不可欠な機能である。複数のインスタンス間で設定を比較したり、特定の構成プロパティを監査したりする際に、一貫したフォーマットで情報を取得できる。

**機能の利用シーン**：
- 構成監査でサーバー設定を確認する際
- コンプライアンスレポートのために設定をドキュメント化する際
- 環境間（開発/テスト/本番）で設定を比較する際
- 構成関連の問題をトラブルシューティングする際
- 特定のプロパティ（DefaultFile、MaxWorkerThreads、LoginModeなど）を確認する際

**主要な処理内容**：
1. SQL Serverインスタンスへの接続
2. Information、UserOptions、Settingsの3つのコレクションからプロパティを取得
3. フィルタリング（InstanceProperty、ExcludeInstancePropertyパラメータ）
4. 各プロパティにメタデータ（ComputerName、InstanceName、SqlInstance、PropertyType）を追加
5. 結果をパイプラインに出力

**関連システム・外部連携**：
- SQL Server SMO (Server Management Objects)

**権限による制御**：
- 基本的なサーバー情報を表示するには、SQL Serverへの接続権限が必要
- 一部のプロパティはsysadmin権限が必要な場合がある

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン | 主画面 | PowerShellコンソールからの実行 |

## 機能種別

情報取得 / 構成監査

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可能 |
| SqlCredential | PSCredential | No | SQL Server接続用の資格情報 | - |
| InstanceProperty | object[] | No | 取得するプロパティ名（ワイルドカード対応） | - |
| ExcludeInstanceProperty | object[] | No | 除外するプロパティ名（ワイルドカード対応） | - |
| EnableException | switch | No | 例外を直接スローする | - |

### 入力データソース

- SQL Server SMO Server.Information.Properties
- SQL Server SMO Server.UserOptions.Properties
- SQL Server SMO Server.Settings.Properties

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | プロパティ名 |
| Value | object | プロパティの現在値 |
| PropertyType | string | プロパティのコレクション種別（Information/UserOption/Setting） |

### 出力先

パイプライン出力（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. インスタンス接続
   └─ Connect-DbaInstance で接続

2. Informationプロパティ取得
   └─ $server.Information.Properties を取得
   └─ フィルタリング適用
   └─ 各プロパティを出力

3. UserOptionsプロパティ取得
   └─ $server.UserOptions.Properties を取得
   └─ フィルタリング適用
   └─ 各プロパティを出力

4. Settingsプロパティ取得
   └─ $server.Settings.Properties を取得
   └─ フィルタリング適用
   └─ 各プロパティを出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance]
    B --> C{接続成功?}
    C -->|No| D[Stop-Function]
    C -->|Yes| E[Information.Propertiesを処理]

    E --> F{InstanceProperty指定?}
    F -->|Yes| G[名前でフィルタ]
    F -->|No| H{ExcludeProperty指定?}
    G --> H
    H -->|Yes| I[除外フィルタ]
    H -->|No| J[各プロパティをループ]
    I --> J

    J --> K[Add-Member ComputerName]
    K --> L[Add-Member PropertyType=Information]
    L --> M[Select-DefaultView]
    M --> N[パイプライン出力]

    N --> O[UserOptions.Propertiesを処理]
    O --> P[同様のフィルタ・出力処理]
    P --> Q[Settings.Propertiesを処理]
    Q --> R[同様のフィルタ・出力処理]
    R --> S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 3コレクション取得 | Information、UserOptions、Settingsの3つのコレクションから取得 | 常に |
| BR-002 | PropertyType識別 | 各プロパティにソースコレクションを示すPropertyTypeを付与 | 常に |
| BR-003 | フィルタ適用順 | InstancePropertyで絞り込み、その後ExcludeInstancePropertyで除外 | フィルタ指定時 |

### 計算ロジック

特になし

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

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

本機能はSMO経由でサーバープロパティを取得するのみで、直接のデータベースクエリは行わない。

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

本機能は読み取り専用操作のみを行う。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Function で処理継続 |
| InformationError | 取得エラー | Informationプロパティ取得失敗 | Stop-Function で処理継続 |
| UserOptionsError | 取得エラー | UserOptionsプロパティ取得失敗 | Stop-Function で処理継続 |
| SettingsError | 取得エラー | Settingsプロパティ取得失敗 | Stop-Function で処理継続 |

### リトライ仕様

リトライは行わない。

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

本機能はデータ変更を行わないため、トランザクション管理は不要。

## パフォーマンス要件

プロパティ数に依存するが、通常は即座に完了する。

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

- サーバー構成情報が表示されるため、機密情報として扱う
- 一部のセキュリティ関連プロパティ（LoginMode等）が含まれる

## 備考

- SQL Server全バージョンに対応（MinimumVersion指定なし）
- 取得されるプロパティはSQL Serverバージョンによって異なる場合がある

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaInstanceProperty.ps1 | `public/Get-DbaInstanceProperty.ps1` | 出力オブジェクト構造（40-53行目の.OUTPUTS） |

**読解のコツ**: 出力オブジェクトは元のSMOプロパティオブジェクトに追加プロパティを付与したもの。PropertyTypeによって元のコレクションを識別できる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaInstanceProperty.ps1 | `public/Get-DbaInstanceProperty.ps1` | パラメータ定義（91-98行目） |

**主要処理フロー**:
1. **99-105行目**: インスタンス接続
2. **107-125行目**: Informationプロパティの処理
3. **127-145行目**: UserOptionsプロパティの処理
4. **147-165行目**: Settingsプロパティの処理

#### Step 3: 各コレクションの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaInstanceProperty.ps1 | `public/Get-DbaInstanceProperty.ps1` | Information処理（107-125行目） |
| 3-2 | Get-DbaInstanceProperty.ps1 | `public/Get-DbaInstanceProperty.ps1` | UserOptions処理（127-145行目） |
| 3-3 | Get-DbaInstanceProperty.ps1 | `public/Get-DbaInstanceProperty.ps1` | Settings処理（147-165行目） |

**主要処理フロー（各コレクション共通）**:
- **$server.{Collection}.Properties**: プロパティコレクション取得
- **Where-Object Name -In $InstanceProperty**: 名前フィルタリング
- **Where-Object Name -NotIn $ExcludeInstanceProperty**: 除外フィルタリング
- **Add-Member PropertyType**: コレクション種別の付与

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

```
Get-DbaInstanceProperty
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Serverへの接続
    │
    ├─ $server.Information.Properties
    │      └─ サーバー情報プロパティの取得
    │
    ├─ $server.UserOptions.Properties
    │      └─ ユーザーオプションプロパティの取得
    │
    ├─ $server.Settings.Properties
    │      └─ 設定プロパティの取得
    │
    ├─ Add-Member
    │      └─ カスタムプロパティの追加
    │
    └─ Select-DefaultView
           └─ 表示プロパティの設定
```

### データフロー図

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

SqlInstance ──▶ Connect-DbaInstance
                    │
          ┌────────┴────────┐
          │                 │
          ▼                 ▼
    Information      UserOptions
    Properties       Properties
          │                 │
          │      Settings   │
          │      Properties │
          │          │      │
          └────┬─────┴──────┘
               │
               ▼
          フィルタリング
          (InstanceProperty)
          (ExcludeInstanceProperty)
               │
               ▼
          Add-Member
          (PropertyType追加)
               │
               ▼
          Select-DefaultView ──▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaInstanceProperty.ps1 | `public/Get-DbaInstanceProperty.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1` | ソース | デフォルト表示設定 |
