# 機能設計書 424-Get-DbaPbmStore

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Get-DbaPbmStore`コマンドレットに関する機能設計書である。このコマンドレットは、SQL ServerのPolicy-Based Management（PBM）のストアオブジェクトを取得する機能を提供する。

### 本機能の処理概要

`Get-DbaPbmStore`は、SQL ServerインスタンスからPolicy-Based Managementのストアオブジェクト（PolicyStore）を取得するコマンドレットである。PolicyStoreはPBMの基盤となるオブジェクトであり、ポリシー、条件、カテゴリなどすべてのPBMコンポーネントへのプログラム的アクセスを提供する。

**業務上の目的・背景**：Policy-Based Managementの各種機能（ポリシー、条件、オブジェクトセットなど）を操作するためには、まずPBMストアオブジェクトを取得する必要がある。本機能は、PBM関連の他のコマンドレット（Get-DbaPbmCondition、Get-DbaPbmPolicy、Get-DbaPbmObjectSetなど）の基盤として機能し、DMF（Declarative Management Framework）のポリシーストアへの接続を確立する。

**機能の利用シーン**：
- PBM関連コマンドのパイプライン入力として使用する場合
- PBMストアのプロパティを直接確認する場合
- 複数インスタンスのPBMストアを一括取得する場合
- スクリプトや自動化処理でPBMコンポーネントにアクセスする場合

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続する（MinimumVersion 10）
2. SqlStoreConnectionオブジェクトを作成する
3. PolicyStoreオブジェクトを作成する
4. インスタンス識別情報を付加して結果を出力する

**関連システム・外部連携**：SQL Server Declarative Management Framework（DMF）と連携し、Microsoft.SqlServer.Management.DMF名前空間のオブジェクトを使用する。

**権限による制御**：SQL Serverインスタンスへの接続権限が必要である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio - Policy Management | 参照画面 | SSMS上でのPolicy-Based Managementへのアクセスに相当 |

## 機能種別

データ取得 / 基盤機能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス。パイプライン入力可能。 | 有効なSQL Server接続文字列 |
| SqlCredential | PSCredential | No | 代替資格情報。Windows認証、SQL Server認証、AD認証をサポート。 | 有効なPSCredentialオブジェクト |
| EnableException | switch | No | 例外をスローするモードを有効化。 | なし |

### 入力データソース

- SQL Serverインスタンス直接指定（SqlInstanceパラメータ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名（コンピュータ\インスタンス形式） |

### 追加プロパティ（Select-Object *でアクセス可能）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlStoreConnection | object | 基礎となるSQLストア接続オブジェクト |
| ConnectionContext | object | SQL接続コンテキスト |
| Properties | object | SMOオブジェクトプロパティコレクション |
| Urn | string | ストアのUniform Resource Name |
| Parent | object | 親オブジェクト参照 |
| DomainInstanceName | string | ドメインインスタンス名 |
| Metadata | object | メタデータ情報 |
| IdentityKey | object | オブジェクトのアイデンティティキー |
| Name | string | ストアオブジェクトのName プロパティ |

### 出力先

- PowerShellパイプライン（標準出力）
- Microsoft.SqlServer.Management.DMF.PolicyStoreオブジェクトとして出力

## 処理フロー

### 処理シーケンス

```
1. beginブロック
   └─ Add-PbmLibrary関数を呼び出し、PBM関連ライブラリをロード
2. processブロック
   ├─ Test-FunctionInterruptでの中断チェック
   ├─ PowerShell Core / Linux / macOS環境チェック（非サポートの場合は処理停止）
   └─ 各SqlInstanceの処理
       ├─ Connect-DbaInstanceで接続（MinimumVersion 10）
       ├─ SqlStoreConnectionオブジェクトの作成
       ├─ PolicyStoreオブジェクトの作成
       ├─ インスタンス識別情報の追加
       └─ Select-DefaultViewで出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Add-PbmLibrary]
    B --> C{Test-FunctionInterrupt?}
    C -->|Yes| Z[終了]
    C -->|No| D{PowerShell Core?}
    D -->|Yes| E[Stop-Function]
    E --> Z
    D -->|No| F[各インスタンスを処理]
    F --> G[Connect-DbaInstance]
    G --> H{接続成功?}
    H -->|No| I[Stop-Function -Continue]
    I --> J{次のインスタンス?}
    H -->|Yes| K[SqlStoreConnection作成]
    K --> L[PolicyStore作成]
    L --> M[Add-Member でプロパティ追加]
    M --> N[Select-DefaultView で出力]
    N --> J
    J -->|Yes| F
    J -->|No| Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | PowerShell Core非サポート | PowerShell Core / Linux / macOSでは実行不可 | PSEditionが"Core"の場合 |
| BR-002 | 最低バージョン要件 | SQL Server 2008（Version 10）以降が必要 | すべての実行 |

### 計算ロジック

特になし（基盤機能のため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| PBMストア接続 | msdb（PBM関連テーブル） | 接続のみ | PolicyStoreオブジェクトの初期化 |

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

直接的なテーブル操作は行わない。PolicyStoreオブジェクトの作成時にPBM関連のメタデータが読み込まれる。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | PowerShell Core / Linux / macOS環境で実行 | Windows PowerShellで実行する |
| - | ConnectionError | SQL Server接続失敗 | 接続情報を確認する |
| - | ConnectionError | SQL Server 2005以前のバージョン | SQL Server 2008以降を使用する |

### リトライ仕様

リトライ処理は実装されていない。エラー時は-Continue オプションで次のインスタンスの処理を継続する。

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

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

## パフォーマンス要件

特に規定なし。接続確立とオブジェクト作成のみの軽量処理。

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

- SQL Server認証、Windows認証、Azure AD認証をサポート
- 接続資格情報はPSCredentialオブジェクトで安全に管理
- MFAサポートが必要な場合はConnect-DbaInstanceの事前使用を推奨

## 備考

- SQL Server 2008以降（Version 10以上）が必要
- DMF（Declarative Management Framework）はPolicy-Based Managementの旧称
- 他のPBM関連コマンド（Get-DbaPbmCondition、Get-DbaPbmPolicy等）の基盤として使用される

---

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

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

### 推奨読解順序

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

PolicyStoreオブジェクトの構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaPbmStore.ps1 | `public/Get-DbaPbmStore.ps1` | .OUTPUTSセクション（35-55行目）で出力オブジェクトの構造を理解 |

**読解のコツ**: Microsoft.SqlServer.Management.DMF.PolicyStoreはSMOのDMF名前空間に属するオブジェクトである。DMFはPolicy-Based Managementの旧称であり、内部的にはDMFという名称が使用されている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaPbmStore.ps1 | `public/Get-DbaPbmStore.ps1` | パラメータ定義（67-73行目）で入力の受け取り方を確認 |

**主要処理フロー**:
1. **74-76行目**: beginブロックでAdd-PbmLibraryを呼び出し
2. **77-82行目**: processブロックでの環境チェック
3. **83-98行目**: インスタンスごとの処理

#### Step 3: PolicyStoreオブジェクト作成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaPbmStore.ps1 | `public/Get-DbaPbmStore.ps1` | オブジェクト作成ロジック（84-91行目） |

**主要処理フロー**:
- **85行目**: Connect-DbaInstanceで接続（MinimumVersion 10を指定）
- **86行目**: SqlStoreConnectionオブジェクトの作成
- **88行目**: PolicyStoreオブジェクトの作成（コメントでDMFの説明あり）
- **93-95行目**: インスタンス識別プロパティの追加
- **97行目**: Select-DefaultViewで出力プロパティを制限

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

```
Get-DbaPbmStore
    │
    ├─ Add-PbmLibrary
    │      └─ PBMライブラリのロード
    │
    ├─ Test-FunctionInterrupt
    │      └─ 中断チェック
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続（MinimumVersion 10）
    │
    ├─ New-Object SqlStoreConnection
    │      └─ ストア接続オブジェクト作成
    │
    ├─ New-Object PolicyStore
    │      └─ ポリシーストアオブジェクト作成
    │
    └─ Select-DefaultView
           └─ 出力プロパティの制限
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ───────▶ Server Object
                            │
                            ▼
              ConnectionContext.SqlConnectionObject
                            │
                            ▼
                  New-Object SqlStoreConnection
                            │
                            ▼
                   New-Object PolicyStore
                            │
                            ▼
                  Add-Member（インスタンス情報）
                            │
                            ▼
                    Select-DefaultView ───────▶ PolicyStore
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPbmStore.ps1 | `public/Get-DbaPbmStore.ps1` | ソース | メイン機能の実装 |
| Add-PbmLibrary.ps1 | `private/Add-PbmLibrary.ps1` | ソース | PBMライブラリのロード |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Select-DefaultView.ps1 | `private/Select-DefaultView.ps1` | ソース | 出力プロパティの制限 |
| Get-DbaPbmCondition.ps1 | `public/Get-DbaPbmCondition.ps1` | ソース | 本機能を利用するコマンド |
| Get-DbaPbmPolicy.ps1 | `public/Get-DbaPbmPolicy.ps1` | ソース | 本機能を利用するコマンド |
| Get-DbaPbmObjectSet.ps1 | `public/Get-DbaPbmObjectSet.ps1` | ソース | 本機能を利用するコマンド |
