# 画面設計書 222-拡張プロパティ

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける拡張プロパティ管理機能の設計仕様を定義する。SQL Serverオブジェクトに対するメタデータ・ドキュメント・カスタム属性の追加・取得・更新・削除機能を提供するCLIインターフェースである。

### 本画面の処理概要

本機能は、SQL Serverの拡張プロパティ（Extended Properties）を管理する。拡張プロパティは、データベースオブジェクト（テーブル、列、ストアドプロシージャ、ビューなど）にカスタムメタデータを付与するSQL Serverの機能であり、オブジェクトの説明、バージョン情報、ビジネスルール、コンプライアンスタグなどを格納できる。

**業務上の目的・背景**：データベースの自己文書化（Self-Documentation）は、大規模システムの保守性向上に不可欠である。拡張プロパティを活用することで、データベーススキーマ内に直接ドキュメントを埋め込み、SSMS（SQL Server Management Studio）やスクリプトから容易にアクセスできる。本機能は、手動で`sp_addextendedproperty`等を実行する煩雑さを解消し、PowerShellによる一括操作・自動化を実現する。コンプライアンス監査、データカタログ構築、レガシーシステム理解などの場面で活用される。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行することでアクセスする。
- `Get-DbaExtendedProperty` - 拡張プロパティの取得
- `Add-DbaExtendedProperty` - 拡張プロパティの追加
- `Set-DbaExtendedProperty` - 拡張プロパティの更新
- `Remove-DbaExtendedProperty` - 拡張プロパティの削除

**主要な操作・処理内容**：
1. データベースレベルおよびオブジェクトレベルの拡張プロパティ取得
2. 任意のSQL Serverオブジェクトへの拡張プロパティ追加
3. 既存拡張プロパティの値更新
4. 不要な拡張プロパティの削除
5. パイプライン処理による複数オブジェクトへの一括適用

**画面遷移**：本機能はCLIコマンドであり、画面遷移は存在しない。ただし、`Get-DbaDbTable`や`Get-DbaDbStoredProcedure`等の出力を`Get-DbaExtendedProperty`や`Add-DbaExtendedProperty`にパイプラインで渡すワークフローが一般的。

**権限による表示制御**：SQL Serverへの接続権限および対象オブジェクトへのVIEW DEFINITION権限が必要。拡張プロパティの追加・更新・削除にはALTER権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Get-DbaExtendedProperty | 主機能 | 拡張プロパティの取得と一覧表示 |
| - | Add-DbaExtendedProperty | 主機能 | 新規拡張プロパティの作成 |
| - | Set-DbaExtendedProperty | 主機能 | 既存拡張プロパティの値更新 |
| - | Remove-DbaExtendedProperty | 主機能 | 拡張プロパティの削除 |
| - | Get-DbaDatabase | 関連機能 | データベースオブジェクトの取得 |
| - | Get-DbaDbTable | 関連機能 | テーブルオブジェクトの取得 |
| - | Get-DbaDbStoredProcedure | 関連機能 | ストアドプロシージャオブジェクトの取得 |
| - | Connect-DbaInstance | 関連機能 | SQL Serverインスタンスへの接続確立 |

## 画面種別

CLIコマンド（PowerShell関数）

## URL/ルーティング

PowerShellコマンドレット：
- `Get-DbaExtendedProperty`
- `Add-DbaExtendedProperty`
- `Set-DbaExtendedProperty`
- `Remove-DbaExtendedProperty`

## 入出力項目

### Get-DbaExtendedProperty パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 条件付き | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| Database | string[] | No | 対象データベース名 |
| Name | string[] | No | 取得する拡張プロパティ名（フィルタ） |
| InputObject | psobject[] | No | パイプライン入力（任意のSMOオブジェクト） |
| EnableException | switch | No | 例外処理モードの切り替え |

### Add-DbaExtendedProperty パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 条件付き | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| Database | string[] | No | 対象データベース名 |
| Name | string | Yes | 追加する拡張プロパティ名 |
| Value | string | Yes | 拡張プロパティの値 |
| InputObject | psobject[] | No | パイプライン入力（任意のSMOオブジェクト） |
| EnableException | switch | No | 例外処理モードの切り替え |

### Set-DbaExtendedProperty パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| InputObject | ExtendedProperty[] | Yes | 更新対象の拡張プロパティオブジェクト |
| Value | string | Yes | 新しい値 |
| EnableException | switch | No | 例外処理モードの切り替え |

### Remove-DbaExtendedProperty パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| InputObject | ExtendedProperty[] | Yes | 削除対象の拡張プロパティオブジェクト |
| EnableException | switch | No | 例外処理モードの切り替え |

## 表示項目

### Get-DbaExtendedProperty 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| ParentName | string | 親オブジェクト名 |
| Type | string | 親オブジェクトの型名 |
| Name | string | 拡張プロパティ名 |
| Value | string | 拡張プロパティの値 |

### Add-DbaExtendedProperty 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| ParentName | string | 親オブジェクト名 |
| Type | string | 親オブジェクトの型名 |
| Name | string | 拡張プロパティ名 |
| Value | string | 拡張プロパティの値 |

### Set-DbaExtendedProperty 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | 拡張プロパティ名 |
| Value | string | 更新後の値 |

### Remove-DbaExtendedProperty 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| ParentName | string | 親オブジェクト名 |
| PropertyType | string | プロパティの型 |
| Name | string | 削除された拡張プロパティ名 |
| Status | string | 処理結果（Dropped） |

## イベント仕様

### 1-Get（取得）処理

拡張プロパティを取得する処理フロー：

1. SqlInstance指定時はGet-DbaDatabase経由でデータベースオブジェクトを取得
2. InputObject（任意のSMOオブジェクト）のExtendedPropertiesコレクションにアクセス
3. Name指定時はフィルタリング
4. 各プロパティにComputerName/InstanceName/SqlInstance/ParentName/Typeを付加
5. Select-DefaultViewで整形して出力

### 2-Add（追加）処理

拡張プロパティを追加する処理フロー：

1. SqlInstance指定時はGet-DbaDatabase経由でデータベースオブジェクトを取得
2. 各InputObjectに対して：
   - 接続情報の取得（Get-ConnectionParent経由）
   - New-Object Microsoft.SqlServer.Management.Smo.ExtendedPropertyで新規オブジェクト作成
   - Create()メソッドでSQL Serverに保存
3. 追加した拡張プロパティオブジェクトを返却

### 3-Set（更新）処理

拡張プロパティの値を更新する処理フロー：

1. パイプライン入力から拡張プロパティオブジェクトを受け取る
2. Valueプロパティを新しい値に設定
3. Alter()メソッドで変更をSQL Serverに反映
4. Refresh()で最新状態を取得
5. 更新されたオブジェクトを返却

### 4-Remove（削除）処理

拡張プロパティを削除する処理フロー：

1. パイプライン入力から拡張プロパティオブジェクトを受け取る
2. Get-ConnectionParent -Databaseでデータベースオブジェクトを取得
3. sp_dropextendedpropertyを実行して削除
4. 削除結果をPSCustomObjectで返却

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaExtendedProperty | sys.extended_properties | SELECT | 拡張プロパティの読み取り |
| Add-DbaExtendedProperty | sys.extended_properties | INSERT | 拡張プロパティの追加 |
| Set-DbaExtendedProperty | sys.extended_properties | UPDATE | 拡張プロパティの更新 |
| Remove-DbaExtendedProperty | sys.extended_properties | DELETE | 拡張プロパティの削除 |

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

#### sys.extended_properties（システムカタログ）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | Name パラメータ値 | sp_addextendedproperty経由 |
| INSERT | value | Value パラメータ値 | sql_variant型 |
| UPDATE | value | 新しいValue | SMO Alter()経由 |
| DELETE | - | name条件で削除 | sp_dropextendedproperty経由 |

## メッセージ仕様

| 種別 | メッセージID | メッセージ内容 | 発生条件 |
|------|-------------|---------------|---------|
| Verbose | - | No extended properties exist in the $object on $instance | 拡張プロパティが存在しない場合 |
| Error | - | Failed to add extended property $Name with a value of '$Value' to $object.Name | 追加失敗時 |
| Error | - | Failure | 一般的な処理失敗時 |
| System | - | Updating value from '$old' to '$Value' | Set処理時のログ |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionで処理中断、エラーメッセージ表示 |
| 拡張プロパティ追加失敗 | Stop-Functionでエラー表示、処理継続 |
| 拡張プロパティ更新失敗 | Stop-Functionでエラー表示、Continue処理 |
| 拡張プロパティ削除失敗 | Stop-Functionでエラー表示、Continue処理 |
| 親オブジェクトにExtendedPropertiesがない | Verbose警告、次のオブジェクトへ |

## 備考

- 対応オブジェクト型：Database, Table, Column, View, StoredProcedure, Function, Index, Schema, Trigger, 他多数
- SMOのExtendedPropertyクラスを使用
- 削除時はsp_dropextendedpropertyを直接呼び出し
- WhatIf/Confirmサポートあり（Add/Set/Remove）
- パイプライン処理により大量オブジェクトへの一括適用が可能

---

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

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

### 推奨読解順序

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

拡張プロパティ操作で使用されるSMOオブジェクト構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaExtendedProperty.ps1 | `public/Get-DbaExtendedProperty.ps1` | 出力型ExtendedPropertyの構造、追加プロパティ |
| 1-2 | Add-DbaExtendedProperty.ps1 | `public/Add-DbaExtendedProperty.ps1` | SMO ExtendedPropertyオブジェクトの生成方法 |

**読解のコツ**: SMOのExtendedPropertyクラスはParentプロパティで親オブジェクトを参照する。Add-Memberで追加されるComputerName等のカスタムプロパティに注目。

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

Get処理のInputObject汎用性を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaExtendedProperty.ps1 | `public/Get-DbaExtendedProperty.ps1` | 111-114行目のSqlInstance/InputObject分岐 |
| 2-2 | Add-DbaExtendedProperty.ps1 | `public/Add-DbaExtendedProperty.ps1` | 139-141行目の同様の分岐処理 |

**主要処理フロー**:
1. **112-113行目**: SqlInstance指定時はGet-DbaDatabase経由でInputObject生成
2. **116行目**: foreachでInputObjectを走査
3. **117行目**: $object.ExtendedPropertiesでコレクション取得

#### Step 3: 接続情報の取得ロジックを理解する

汎用InputObjectからサーバー情報を取得するロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaExtendedProperty.ps1 | `public/Get-DbaExtendedProperty.ps1` | 128-148行目のComputerName/InstanceName/SqlInstance取得 |

**主要処理フロー**:
- **129-131行目**: オブジェクトから直接プロパティ取得を試行
- **133-147行目**: 取得できない場合はGet-ConnectionParent経由でサーバー情報取得
- **134-135行目**: @@SERVERNAME クエリでサーバー名を確定

#### Step 4: CRUD操作を理解する

追加・更新・削除の各操作を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Add-DbaExtendedProperty.ps1 | `public/Add-DbaExtendedProperty.ps1` | 167-169行目のNew-ObjectとCreate() |
| 4-2 | Set-DbaExtendedProperty.ps1 | `public/Set-DbaExtendedProperty.ps1` | 81-85行目のValue設定とAlter()/Refresh() |
| 4-3 | Remove-DbaExtendedProperty.ps1 | `public/Remove-DbaExtendedProperty.ps1` | 73-84行目のsp_dropextendedproperty実行 |

**主要処理フロー（Add）**:
- **168行目**: `New-Object Microsoft.SqlServer.Management.Smo.ExtendedProperty ($object, $Name, $Value)`
- **169行目**: `$prop.Create()` でSQL Serverに永続化

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

```
Get-DbaExtendedProperty
    |
    +-- Get-DbaDatabase（SqlInstance指定時）
    |       +-- Connect-DbaInstance
    |
    +-- Get-ConnectionParent（サーバー情報取得）
    |
    +-- Select-DefaultView（出力整形）

Add-DbaExtendedProperty
    |
    +-- Get-DbaDatabase（SqlInstance指定時）
    |       +-- Connect-DbaInstance
    |
    +-- Get-ConnectionParent（サーバー情報取得）
    |
    +-- New-Object ExtendedProperty
    |
    +-- ExtendedProperty.Create()

Set-DbaExtendedProperty
    |
    +-- ExtendedProperty.Value = $Value
    |
    +-- ExtendedProperty.Alter()
    |
    +-- ExtendedProperty.Refresh()

Remove-DbaExtendedProperty
    |
    +-- Get-ConnectionParent -Database
    |
    +-- $db.Invoke("sp_dropextendedproperty")
```

### データフロー図

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

【Get処理】
SMOオブジェクト -------> ExtendedProperties -------> Add-Member -------> カスタム出力
(Table/SP/View等)       コレクション取得            プロパティ追加       (PSCustomObject)

【Add処理】
SMOオブジェクト -------> New ExtendedProperty -------> Create() -------> ExtendedProperty
+ Name/Value           オブジェクト生成              SQL Server保存      オブジェクト

【Set処理】
ExtendedProperty -------> Value更新 -------> Alter() -------> ExtendedProperty
オブジェクト             プロパティ設定     SQL Server反映   更新済みオブジェクト

【Remove処理】
ExtendedProperty -------> sp_dropextendedproperty -------> PSCustomObject
オブジェクト             システムストアド実行            結果オブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaExtendedProperty.ps1 | `public/Get-DbaExtendedProperty.ps1` | ソース | 拡張プロパティ取得機能 |
| Add-DbaExtendedProperty.ps1 | `public/Add-DbaExtendedProperty.ps1` | ソース | 拡張プロパティ追加機能 |
| Set-DbaExtendedProperty.ps1 | `public/Set-DbaExtendedProperty.ps1` | ソース | 拡張プロパティ更新機能 |
| Remove-DbaExtendedProperty.ps1 | `public/Remove-DbaExtendedProperty.ps1` | ソース | 拡張プロパティ削除機能 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得（依存） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立（依存） |
