# 機能設計書 122-Get-DbaExtendedProperty

## 概要

本ドキュメントは、SQL Serverオブジェクトに付与された拡張プロパティ（メタデータ・ドキュメント情報）を取得するGet-DbaExtendedProperty機能の設計仕様を記載する。

### 本機能の処理概要

Get-DbaExtendedPropertyは、SQL Serverデータベースやその他のオブジェクトに付与されたカスタムメタデータ、ドキュメント、ビジネス説明などの拡張プロパティを取得する機能である。

**業務上の目的・背景**：拡張プロパティは、データベーススキーマ内にオブジェクトのドキュメント、バージョン情報、ビジネスルール、コンプライアンス情報を直接格納するために使用される。DBAや開発者は、これらの情報を活用して、レガシーシステムの理解、コンプライアンス監査、データベースドキュメント生成を行う。本機能により、既存のメタデータを効率的に発見・抽出できる。

**機能の利用シーン**：
- データベースドキュメント監査の実施
- コンプライアンスタグが付与されたオブジェクトの検索
- レガシーシステムの理解のための既存メタデータ発見
- ドキュメント生成レポートの作成
- オブジェクト間のメタデータ比較

**主要な処理内容**：
1. SqlInstance指定時はGet-DbaDatabaseでデータベースオブジェクトを取得
2. InputObjectで受け取ったSMOオブジェクトのExtendedPropertiesコレクションにアクセス
3. Name指定時は該当する名前でフィルタリング
4. 各拡張プロパティにComputerName、InstanceName等のメタ情報を付加して出力

**関連システム・外部連携**：SQL Server SMO (Server Management Objects) を使用。他のdbatoolsコマンドからのパイプライン入力をサポート。

**権限による制御**：対象オブジェクトへのアクセス権限が必要。データベースレベルの拡張プロパティにはdb_owner相当、サーバーレベルにはsysadmin相当の権限が推奨。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コンソール/ターミナル | 主画面 | コマンド実行と結果表示 |

## 機能種別

データ取得(SELECT) / メタデータ参照

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows/SQL認証対応 |
| Database | string[] | No | フィルタリング対象データベース名 | 複数指定可 |
| Name | string[] | No | 取得する拡張プロパティ名（エイリアス: Property） | 複数指定可 |
| InputObject | psobject[] | No | パイプラインから受け取るSMOオブジェクト | ValueFromPipeline |
| EnableException | switch | No | 例外を直接スローするか | - |

### 入力データソース

- SQL Serverインスタンスへの接続パラメータ
- 他のdbatoolsコマンドからのパイプライン入力（Get-DbaDbTable、Get-DbaDbStoredProcedure等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| ParentName | string | 拡張プロパティを所有するオブジェクト名 |
| Type | string | 親オブジェクトの型名(Database, Table, StoredProcedure等) |
| Name | string | 拡張プロパティの名前 |
| Value | string | 拡張プロパティの値 |
| Server | object | 親SQL Serverへの接続オブジェクト |

### 出力先

- PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.ExtendedProperty + NoteProperty拡張）
- コンソール出力（Select-DefaultViewでComputerName, InstanceName, SqlInstance, ParentName, Type, Name, Valueを表示）

## 処理フロー

### 処理シーケンス

```
1. SqlInstance指定時はGet-DbaDatabaseでInputObjectを生成
   └─ IsAccessibleなデータベースのみ対象

2. 各InputObjectをループ処理
   └─ ExtendedPropertiesコレクションを取得

3. ExtendedPropertiesがnullまたは空の場合
   └─ Verboseメッセージを出力してスキップ

4. Name指定時はプロパティをフィルタリング
   └─ Where-Object Name -in $Name

5. ComputerName, InstanceName, SqlInstanceを再構築
   └─ オブジェクトに情報がない場合はGet-ConnectionParentで取得

6. 各プロパティにNotePropertyを追加して出力
   └─ Select-DefaultViewで表示プロパティを制御
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaDatabase実行]
    B -->|No| D[InputObject使用]
    C --> D
    D --> E{InputObjectループ}
    E -->|各オブジェクト| F[ExtendedProperties取得]
    F --> G{プロパティあり?}
    G -->|No| H[Verbose出力、スキップ]
    G -->|Yes| I{Name指定?}
    H --> E
    I -->|Yes| J[Nameでフィルタ]
    I -->|No| K[接続情報再構築]
    J --> K
    K --> L{各プロパティループ}
    L -->|各プロパティ| M[NoteProperty追加]
    M --> N[Select-DefaultView出力]
    N --> L
    L -->|終了| E
    E -->|全オブジェクト完了| O[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | アクセス可能DBのみ | IsAccessibleがtrueのデータベースのみ処理 | SqlInstance指定時 |
| BR-002 | SMO依存 | ExtendedPropertiesコレクションを持つSMOオブジェクトのみ対応 | 全てのInputObject |
| BR-003 | 接続情報再構築 | オブジェクトに接続情報がない場合、Get-ConnectionParentで取得 | 接続情報欠損時 |

### 計算ロジック

特になし（データ取得のみ）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 拡張プロパティ取得 | sys.extended_properties | SELECT | SMO経由でアクセス |

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

#### sys.extended_properties（SMO経由）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, value | オブジェクトに関連付けられた拡張プロパティ | SMO ExtendedPropertiesコレクション経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 情報メッセージ | 拡張プロパティが存在しない | Verboseレベルでメッセージ出力 |

### リトライ仕様

リトライ処理なし。拡張プロパティが存在しない場合は単にスキップ。

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

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

## パフォーマンス要件

- SMOオブジェクトのプロパティアクセスのため、通常は高速に完了
- 大量のオブジェクトをパイプラインで処理する場合は順次処理

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

- 対象オブジェクトへのアクセス権限が必要
- SqlCredentialによる認証情報の安全な受け渡し
- Windows認証、SQL認証、Active Directory認証に対応

## 備考

- 全てのプロパティを表示するには`Select-Object *`を使用
- 他のdbatoolsコマンド（Get-DbaDbTable、Get-DbaDbStoredProcedure等）からパイプライン入力可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaExtendedProperty.ps1 | `public/Get-DbaExtendedProperty.ps1` | 関数の全体構造とパラメータ定義 |

**主要処理フロー**:
1. **100-110行目**: パラメータ定義（SqlInstance, SqlCredential, Database, Name, InputObject）
2. **112-114行目**: SqlInstance指定時にGet-DbaDatabaseでInputObject生成
3. **116-122行目**: ExtendedPropertiesコレクション取得とnullチェック
4. **124-126行目**: Nameパラメータによるフィルタリング
5. **129-148行目**: 接続情報の再構築ロジック
6. **150-159行目**: NoteProperty追加とSelect-DefaultView出力

**読解のコツ**:
- InputObjectは様々なSMOオブジェクト型を受け入れるため、共通のExtendedPropertiesコレクションにアクセスする汎用的な設計
- Get-ConnectionParent関数は親サーバーオブジェクトを取得する内部関数
- Add-Member -Forceで既存プロパティを上書きする可能性あり

#### Step 2: テストコードで動作を確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaExtendedProperty.Tests.ps1 | `tests/Get-DbaExtendedProperty.Tests.ps1` | 期待される動作とパラメータ検証 |

**主要処理フロー**:
- **29-38行目**: テストデータベース作成と拡張プロパティ追加
- **55-69行目**: 各種シナリオでの拡張プロパティ取得テスト

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

```
Get-DbaExtendedProperty
    │
    ├─ Get-DbaDatabase (SqlInstance指定時)
    │      └─ Connect-DbaInstance
    │
    ├─ $object.ExtendedProperties (SMOコレクションアクセス)
    │
    ├─ Get-ConnectionParent (接続情報取得)
    │      └─ @@SERVERNAME クエリ
    │
    └─ Select-DefaultView (出力フォーマット)
```

### データフロー図

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

SqlInstance    ───▶  Get-DbaDatabase          ───▶
                           │
InputObject    ───▶  ExtendedProperties取得   ───▶
(パイプライン)              │
                     Nameフィルタリング       ───▶
                           │
                     接続情報再構築           ───▶
                           │
                     NoteProperty追加         ───▶  ExtendedProperty
                           │                       + メタ情報
                     Select-DefaultView       ───▶  パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaExtendedProperty.ps1 | `public/Get-DbaExtendedProperty.ps1` | ソース | メイン関数定義 |
| Get-DbaExtendedProperty.Tests.ps1 | `tests/Get-DbaExtendedProperty.Tests.ps1` | テスト | 単体・統合テスト |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
