# 機能設計書 76-Add-DbaExtendedProperty

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Add-DbaExtendedProperty` コマンドレットに関する機能設計書です。このコマンドは、SQL Serverオブジェクトに拡張プロパティを追加し、メタデータの保存やドキュメント化を行います。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverオブジェクト（データベース、テーブル、ビュー、ストアドプロシージャなど）にカスタムメタデータを付与することで、ドキュメント化、バージョン管理、ビジネスコンテキストの記録、コンプライアンスタグの追加が可能になります。拡張プロパティはシステムカタログに保存され、オブジェクトのパフォーマンスには影響しません。

**機能の利用シーン**：
- データベースオブジェクトのバージョン情報管理
- テーブル・列の業務説明の追加
- データ分類やコンプライアンスタグの付与
- オブジェクト所有者や最終更新者の記録
- カスタムメタデータによるオブジェクト管理

**主要な処理内容**：
1. 対象オブジェクトの取得（直接指定またはパイプライン入力）
2. SMOを使用したExtendedPropertyオブジェクトの作成
3. プロパティの名前と値の設定
4. Create()メソッドによるプロパティの永続化
5. 結果オブジェクトの出力

**関連システム・外部連携**：SQL Server Management Objects (SMO)を使用して拡張プロパティを管理

**権限による制御**：対象オブジェクトに対するALTER権限が必要

## 関連画面

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

## 機能種別

メタデータ管理 / オブジェクト属性追加

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | Database指定時に使用 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | Windows/SQL認証対応 |
| Database | string[] | No | 対象データベース名 | ワイルドカード対応 |
| Name | string | Yes | 拡張プロパティ名 | Propertyエイリアス |
| Value | string | Yes | 拡張プロパティ値 | - |
| InputObject | psobject[] | No | 対象オブジェクト | パイプライン入力対応 |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- PowerShellコマンドライン引数
- パイプライン入力（Get-Dba*コマンドからの出力）

### 対応オブジェクトタイプ

- Aggregate
- Assembly
- Column
- Constraint
- Contract
- Database
- Event Notification
- Filegroup
- Function
- Index
- Logical File Name
- Message Type
- Parameter
- Partition Function
- Partition Scheme
- Procedure
- Queue
- Remote Service Binding
- Route
- Rule
- Schema
- Service
- Synonym
- Table
- Trigger
- Type
- View
- Xml Schema Collection

## 出力仕様

### 出力データ

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

### 出力先

- PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.ExtendedProperty + カスタムプロパティ）

## 処理フロー

### 処理シーケンス

```
1. processブロック：入力ソースの決定
   └─ SqlInstance指定時：Get-DbaDatabase経由でデータベースオブジェクト取得
   └─ InputObject指定時：パイプライン入力をそのまま使用
2. 各オブジェクトに対する処理
   └─ サーバー接続情報の取得（ComputerName、InstanceName、SqlInstance）
   └─ 接続情報がない場合はGet-ConnectionParentで取得
3. ShouldProcessによる確認
4. ExtendedPropertyオブジェクトの作成
   └─ New-Object Microsoft.SqlServer.Management.Smo.ExtendedProperty
   └─ Create()メソッドの呼び出し
5. カスタムプロパティの追加とSelect-DefaultViewによる出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaDatabase実行]
    C --> D[InputObjectに設定]
    B -->|No| D
    D --> E[各オブジェクトループ]
    E --> F[接続情報取得]
    F --> G{ComputerName等取得済み?}
    G -->|No| H[Get-ConnectionParentで取得]
    G -->|Yes| I{ShouldProcess?}
    H --> I
    I -->|No| J[スキップ]
    I -->|Yes| K[ExtendedProperty作成]
    K --> L[Create実行]
    L --> M{成功?}
    M -->|No| N[Stop-Function]
    M -->|Yes| O[カスタムプロパティ追加]
    O --> P[Select-DefaultView出力]
    P --> Q{次のオブジェクト?}
    J --> Q
    N --> Q
    Q -->|Yes| E
    Q -->|No| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-76-01 | 一意性 | 同一オブジェクトに同名のプロパティは作成不可 | 常時 |
| BR-76-02 | 汎用入力 | Get-Dba*コマンドからの出力を受け入れ可能 | InputObject経由 |
| BR-76-03 | DB直接 | SqlInstance+Databaseでデータベースに直接追加可能 | SqlInstance指定時 |
| BR-76-04 | 確認 | ConfirmImpactがMediumに設定 | 常時 |

### 計算ロジック

- 特になし（SMOのCreate()メソッドを呼び出すのみ）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Create() | sys.extended_properties | INSERT | 拡張プロパティの追加 |

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

#### sys.extended_properties

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | パラメータのName値 | プロパティ名 |
| INSERT | value | パラメータのValue値 | プロパティ値 |
| INSERT | class | オブジェクトタイプに基づく | 自動設定 |
| INSERT | major_id/minor_id | オブジェクトIDに基づく | 自動設定 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| DuplicateError | 重複エラー | 同名のプロパティが既に存在 | Stop-Functionでメッセージ表示 |
| PermissionError | 権限エラー | ALTER権限がない | Stop-Functionでメッセージ表示 |
| ObjectError | オブジェクトエラー | 対象オブジェクトが無効 | Stop-Functionでメッセージ表示 |

### リトライ仕様

- リトライ機能なし（手動で再実行が必要）

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

- SMOのCreate()メソッドが内部でトランザクションを管理

## パフォーマンス要件

- 実行は即時完了
- 拡張プロパティはオブジェクトのパフォーマンスに影響しない

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

- 対象オブジェクトに対するALTER権限が必要
- SqlCredentialパラメータで安全な認証情報の受け渡しをサポート
- ConfirmImpact = 'Medium'により確認プロンプトが表示される場合がある

## 備考

- SQL Server 2005以降で使用可能
- 拡張プロパティはSQL Server Management Studioでも表示可能
- 著者: Chrissy LeMaire (@cl)

---

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

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

### 推奨読解順序

#### Step 1: コマンドの全体構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Add-DbaExtendedProperty.ps1 | `public/Add-DbaExtendedProperty.ps1` | 対応オブジェクトタイプのリスト、パラメータ定義 |

**読解のコツ**: InputObjectが非常に汎用的で、様々なSMOオブジェクトを受け入れる点に注目。

#### Step 2: processブロック - 入力ソースの決定

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Add-DbaExtendedProperty.ps1 | `public/Add-DbaExtendedProperty.ps1` | 139-141行目：SqlInstance指定時のGet-DbaDatabase呼び出し |

**主要処理フロー**:
1. **139-141行目**: SqlInstance指定時はGet-DbaDatabase経由でデータベースオブジェクト取得
2. **143行目**: 各オブジェクトに対するループ開始

#### Step 3: processブロック - 接続情報の取得

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Add-DbaExtendedProperty.ps1 | `public/Add-DbaExtendedProperty.ps1` | 145-165行目：サーバー接続情報の再構築 |

**読解のコツ**: InputObjectが汎用的なため、ComputerName等のプロパティがない場合は`Get-ConnectionParent`で取得する。

#### Step 4: processブロック - ExtendedProperty作成

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Add-DbaExtendedProperty.ps1 | `public/Add-DbaExtendedProperty.ps1` | 167-178行目：SMO ExtendedPropertyの作成と出力 |

**主要処理フロー**:
- **168行目**: New-ObjectでExtendedPropertyオブジェクト作成
- **169行目**: Create()メソッドでデータベースに保存
- **170-175行目**: Add-Memberでカスタムプロパティを追加
- **177行目**: Select-DefaultViewで整形出力

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

```
Add-DbaExtendedProperty
    │
    ├─ Get-DbaDatabase (SqlInstance指定時)
    │      └─ データベースオブジェクト取得
    │
    ├─ Get-ConnectionParent (内部関数)
    │      └─ サーバー接続情報の取得
    │
    ├─ New-Object Microsoft.SqlServer.Management.Smo.ExtendedProperty
    │      └─ 拡張プロパティオブジェクト作成
    │
    ├─ ExtendedProperty.Create()
    │      └─ データベースへの永続化
    │
    ├─ Add-Member
    │      └─ カスタムプロパティ追加
    │
    ├─ Select-DefaultView
    │      └─ 出力整形
    │
    └─ Stop-Function (dbatools内部関数)
           └─ エラーハンドリング
```

### データフロー図

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

SqlInstance ───▶ Get-DbaDatabase ──────▶ InputObject
                        │
InputObject ────▶ 各オブジェクトループ ──▶ $object
                        │
Name ───────────▶ ExtendedProperty ─────▶ $prop
    │            作成                    │
Value ──────────▶ Create() ─────────────┘
                        │
                 Add-Member ──────────────▶ カスタムプロパティ
                        │
                 Select-DefaultView ──────▶ 出力
                                              │
                                              ├─ ComputerName
                                              ├─ InstanceName
                                              ├─ SqlInstance
                                              ├─ ParentName
                                              ├─ Type
                                              ├─ Name
                                              └─ Value
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Add-DbaExtendedProperty.ps1 | `public/Add-DbaExtendedProperty.ps1` | ソース | メインコマンド実装 |
| Add-DbaExtendedProperty.Tests.ps1 | `tests/Add-DbaExtendedProperty.Tests.ps1` | テスト | Pester v5テストファイル |
| Get-DbaExtendedProperty.ps1 | `public/Get-DbaExtendedProperty.ps1` | ソース | 拡張プロパティ取得 |
| Set-DbaExtendedProperty.ps1 | `public/Set-DbaExtendedProperty.ps1` | ソース | 拡張プロパティ更新 |
| Remove-DbaExtendedProperty.ps1 | `public/Remove-DbaExtendedProperty.ps1` | ソース | 拡張プロパティ削除 |
