# 機能設計書 225-Set-DbaExtendedProperty

## 概要

本ドキュメントは、SQL Serverデータベースオブジェクトの拡張プロパティの値を更新するdbatools PowerShellコマンドレット「Set-DbaExtendedProperty」の機能設計書である。

### 本機能の処理概要

Set-DbaExtendedPropertyは、SQL Serverデータベースオブジェクトに設定された既存の拡張プロパティ（Extended Property）の値を更新するコマンドレットである。拡張プロパティはデータベース、テーブル、ビュー、ストアドプロシージャ、関数、カラム、インデックスなど、様々なオブジェクトにカスタムメタデータを格納するために使用される。

**業務上の目的・背景**：拡張プロパティは、アプリケーションのバージョン番号、ドキュメント、ビジネスルールなどのカスタムメタデータをデータベースオブジェクトと共に保存するために広く使用されている。これらの値を効率的に更新する機能は、アプリケーションのバージョン管理やドキュメント保守に不可欠である。

**機能の利用シーン**：
- アプリケーションのバージョン番号の更新
- データベースドキュメントの更新
- 設定値やビジネスルールの変更
- 複数オブジェクトに対する一括メタデータ更新

**主要な処理内容**：
1. Get-DbaExtendedPropertyからのパイプライン入力受け取り
2. 新しい値の設定
3. SMOのAlter()メソッドによる変更適用
4. 更新後のオブジェクト返却

**関連システム・外部連携**：SQL Server Management Objects (SMO) を介してSQL Serverと連携する。

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

## 関連画面

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

## 機能種別

メタデータ更新（UPDATE操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| InputObject | Microsoft.SqlServer.Management.Smo.ExtendedProperty[] | Yes | 更新対象の拡張プロパティオブジェクト | Get-DbaExtendedPropertyからの入力 |
| Value | string | Yes | 設定する新しい値 | - |
| EnableException | switch | No | 例外有効化フラグ | - |

### 入力データソース

- Get-DbaExtendedPropertyからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | 拡張プロパティの名前 |
| Value | string | 更新後の値 |
| ID | int | 拡張プロパティのID |
| Parent | object | 親オブジェクト |
| State | string | SMOオブジェクトの状態 |
| Urn | string | Uniform Resource Name |
| Properties | collection | SQL Serverオブジェクトプロパティコレクション |

### 出力先

PowerShellパイプライン（標準出力）- Microsoft.SqlServer.Management.Smo.ExtendedPropertyオブジェクト

## 処理フロー

### 処理シーケンス

```
1. パイプライン入力の受け取り
   └─ Get-DbaExtendedPropertyからExtendedPropertyオブジェクトを受け取る

2. 各拡張プロパティに対する処理ループ
   └─ ShouldProcess確認

3. 値の更新
   └─ $object.Value = $Value

4. 変更の適用
   └─ $object.Alter()

5. オブジェクトの更新確認
   └─ $object.Refresh()

6. 結果の出力
   └─ 更新後のExtendedPropertyオブジェクトを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パイプライン入力受け取り]
    B --> C[各ExtendedPropertyに対してループ]
    C --> D{ShouldProcess確認}
    D -->|No| E[スキップ]
    D -->|Yes| F[Valueプロパティ設定]
    F --> G[Alter実行]
    G --> H{成功?}
    H -->|No| I[エラー出力・継続]
    H -->|Yes| J[Refresh実行]
    J --> K[オブジェクト出力]
    K --> L{次のオブジェクト?}
    E --> L
    I --> L
    L -->|Yes| C
    L -->|No| M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パイプライン専用 | Get-DbaExtendedPropertyからのパイプライン入力のみ対応 | 常時 |
| BR-002 | 既存プロパティ更新のみ | 新規作成は不可、既存プロパティの値更新のみ | 常時 |
| BR-003 | 即時反映 | 変更はAlter()で即座に反映 | 常時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 値更新 | sys.extended_properties | UPDATE | SMO Alter()による値変更 |

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

#### sys.extended_properties

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | value | 指定された新しい値 | sql_variant型 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Failure | Alter()実行失敗 | 権限を確認、対象オブジェクト状態を確認 |
| - | InvalidInput | 無効なInputObject | Get-DbaExtendedPropertyから取得したオブジェクトを使用 |

### リトライ仕様

リトライ処理は実装されていない。エラー発生時はStop-Functionで処理を停止し、-Continueにより次のオブジェクトに進む。

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

SMOのAlter()メソッドにより個別にコミットされる。各拡張プロパティの更新は独立したトランザクションで実行される。

## パフォーマンス要件

特に定義されていない。拡張プロパティの更新は軽量な操作である。

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

- 対象オブジェクトに対するALTER権限が必要
- 親オブジェクトの所有者権限でも更新可能

## 備考

- 拡張プロパティの新規作成にはAdd-DbaExtendedPropertyを使用
- 削除にはRemove-DbaExtendedPropertyを使用
- WhatIfとConfirmパラメータをサポート

---

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

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

### 推奨読解順序

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

SMOのExtendedPropertyオブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaExtendedProperty.ps1 | `public/Set-DbaExtendedProperty.ps1` | 出力オブジェクトの構造（41-57行目の.OUTPUTSセクション） |

**読解のコツ**: InputObjectの型がMicrosoft.SqlServer.Management.Smo.ExtendedPropertyであることに注目。

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

processブロック内のシンプルな処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaExtendedProperty.ps1 | `public/Set-DbaExtendedProperty.ps1` | processブロック（77-91行目） |

**主要処理フロー**:
1. **78行目**: 各InputObjectに対するforeachループ
2. **79行目**: ShouldProcess確認（変更前後の値を表示）
3. **81-84行目**: Valueプロパティ設定、Alter()、Refresh()
4. **85行目**: オブジェクト出力

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

```
Set-DbaExtendedProperty
    │
    ├─ パイプライン入力
    │      └─ Get-DbaExtendedPropertyからのExtendedPropertyオブジェクト
    │
    ├─ $object.Value = $Value (プロパティ設定)
    │
    ├─ $object.Alter() (SMOメソッド)
    │      └─ 変更の適用
    │
    └─ $object.Refresh() (SMOメソッド)
           └─ オブジェクト状態の更新
```

### データフロー図

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

Get-DbaExtendedProperty
        │
        ▼
InputObject ────────┐
Value ──────────────┼──▶ foreach ($object in $InputObject)
                    │         │
                    │         ▼
                    │    ShouldProcess確認
                    │         │
                    │         ▼
                    │    $object.Value = $Value
                    │         │
                    │         ▼
                    │    $object.Alter()
                    │         │
                    │         ▼
                    │    $object.Refresh()
                    │         │
                    │         ▼
                    └──▶ ExtendedPropertyオブジェクト
                         (Name, Value更新済み)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaExtendedProperty.ps1 | `public/Set-DbaExtendedProperty.ps1` | ソース | メインコマンドレット実装 |
| Get-DbaExtendedProperty.ps1 | `public/Get-DbaExtendedProperty.ps1` | ソース | 拡張プロパティ取得（入力元） |
| Add-DbaExtendedProperty.ps1 | `public/Add-DbaExtendedProperty.ps1` | ソース | 拡張プロパティ新規作成（関連機能） |
| Remove-DbaExtendedProperty.ps1 | `public/Remove-DbaExtendedProperty.ps1` | ソース | 拡張プロパティ削除（関連機能） |
