# 機能設計書 656-Copy-DbaExtendedStoredProcedure

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Copy-DbaExtendedStoredProcedure` 関数の機能設計を記述するものである。本機能はカスタム拡張ストアドプロシージャ（XP）とその関連DLLファイルをSQL Serverインスタンス間でコピーするコマンドレットである。

### 本機能の処理概要

**業務上の目的・背景**：
拡張ストアドプロシージャ（XP）は、DLLベースのプロシージャで外部コードを呼び出すことによりSQL Serverの機能を拡張する。レガシー統合、カスタムサーバー操作、特殊な処理タスクなどに使用される。本機能は、これらのカスタムXPをソースサーバーから複数の宛先サーバーに移行することで、サーバー統合やディザスタリカバリ環境の構築を支援する。

**機能の利用シーン**：
- SQL Server移行時のXP移行
- ディザスタリカバリ環境の構築
- 開発環境から本番環境へのXP展開
- 複数サーバーでのXP標準化

**主要な処理内容**：
1. ソースサーバーへの接続とカスタムXPの列挙
2. 各宛先サーバーへの接続と既存XPの確認
3. DLLファイルのコピー（可能な場合）
4. sp_addextendedproc による XP の作成
5. 処理結果の出力

**関連システム・外部連携**：
- SQL Server システムプロシージャ（sp_addextendedproc, sp_dropextendedproc, sp_helpextendedproc）
- ファイルシステム操作（DLLファイルのコピー）
- UNCパスを使用したリモートファイルアクセス

**権限による制御**：
- SQL Serverへの sysadmin 権限が必要
- DLLファイルコピーのためのファイルシステムアクセス権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI (PowerShell) | 主画面 | コマンドライン実行によるXPコピー |

## 機能種別

データ移行処理（INSERT/UPDATE/DELETE） / ファイル操作処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | ソースSQL Serverインスタンス | 必須 |
| SourceSqlCredential | PSCredential | No | ソース接続用資格情報 | - |
| Destination | DbaInstanceParameter[] | Yes | 宛先SQL Serverインスタンス（複数可） | 必須 |
| DestinationSqlCredential | PSCredential | No | 宛先接続用資格情報 | - |
| ExtendedProcedure | string[] | No | コピー対象のXP名 | - |
| ExcludeExtendedProcedure | string[] | No | 除外するXP名 | - |
| DestinationPath | string | No | DLLコピー先パス | - |
| Force | switch | No | 既存XPの上書き | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- PowerShellコマンドラインからのパラメータ入力
- SQL Serverシステムカタログからのプロシージャ情報
- ファイルシステムからのDLLファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | 処理日時 |
| SourceServer | string | ソースサーバー名 |
| DestinationServer | string | 宛先サーバー名 |
| Name | string | XP名 |
| Type | string | オブジェクトタイプ（常に"Extended Stored Procedure"） |
| Status | string | 処理結果（Successful/Skipped/Failed/"Successful (DLL not copied)"） |
| Notes | string | 補足情報 |
| Schema | string | スキーマ名 |

### 出力先

PowerShellパイプライン（MigrationObject型として出力）

## 処理フロー

### 処理シーケンス

```
1. 初期化処理（beginブロック）
   └─ ソースサーバーへの接続
   └─ sys.proceduresからカスタムXPの列挙
   └─ Forceオプション確認

2. メイン処理（processブロック）
   └─ 各宛先サーバーに対して処理
       └─ 宛先サーバーへの接続
       └─ 宛先のXP一覧取得
       └─ Binnパスの取得
       └─ 各XPの処理
           └─ フィルタ適用（include/exclude）
           └─ 既存チェック
           └─ Forceの場合は既存削除
           └─ DLLファイルコピー試行
           └─ sp_addextendedproc実行
           └─ 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ソースサーバー接続]
    B --> C{接続成功?}
    C -->|No| D[エラー終了]
    C -->|Yes| E[カスタムXP列挙]
    E --> F[各宛先サーバーをループ]
    F --> G[宛先サーバー接続]
    G --> H{接続成功?}
    H -->|No| I[スキップして次へ]
    H -->|Yes| J[宛先XP一覧取得]
    J --> K[各XPをループ]
    K --> L{include/excludeフィルタ?}
    L -->|除外| M[次のXPへ]
    L -->|対象| N{宛先に存在?}
    N -->|No| O[DLL情報取得]
    N -->|Yes| P{Force?}
    P -->|No| Q[Skipped出力]
    P -->|Yes| R[既存XP削除]
    R --> O
    O --> S[DLLコピー試行]
    S --> T[sp_addextendedproc実行]
    T --> U{成功?}
    U -->|Yes| V[Successful出力]
    U -->|No| W[Failed出力]
    V --> X{次のXP?}
    W --> X
    Q --> X
    X -->|Yes| K
    X -->|No| Y{次の宛先?}
    Y -->|Yes| F
    Y -->|No| Z[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | システムXP除外 | is_ms_shipped = 0 のXPのみ対象 | XP列挙時 |
| BR-002 | DLLコピー試行 | UNCパスでDLLコピーを試行、失敗時は警告のみ | DLL処理時 |
| BR-003 | 既存スキップ | Force未指定時は既存XPをスキップ | 宛先チェック時 |
| BR-004 | 最小バージョン要件 | SQL Server 2005以上 | インスタンス接続時 |

### 計算ロジック

- UNCパス生成: `\\{ComputerName}\{LocalPath}` 形式で ``:`` を ``$`` に置換

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| XP列挙 | sys.procedures | SELECT | カスタムXP一覧取得 |
| XP削除 | master..sysobjects | DELETE（間接） | sp_dropextendedproc実行 |
| XP作成 | master..sysobjects | INSERT（間接） | sp_addextendedproc実行 |
| DLL情報取得 | - | SELECT | sp_helpextendedproc実行 |

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

#### sys.procedures

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, schema_id, object_id | type = 'X' AND is_ms_shipped = 0 | カスタムXPのみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | ソース/宛先サーバーへの接続失敗 | Stop-Function |
| - | DLLコピーエラー | DLLファイルのコピー失敗 | 警告出力、XP作成は続行 |
| - | XP削除エラー | 既存XPの削除失敗 | Failed出力、次のXPへ |
| - | XP作成エラー | sp_addextendedproc失敗 | Failed出力、次のXPへ |
| - | DLLパス不明 | DLLパスを特定できない | Failed出力、スキップ |

### リトライ仕様

自動リトライは実装されていない。

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

- 各XPの操作は個別に実行される
- ロールバック機能は提供されない

## パフォーマンス要件

- XPの数に比例した処理時間
- DLLコピーはネットワーク帯域に依存
- 複数宛先への並列処理は未実装

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

- sysadmin権限が必要
- DLLファイルへのファイルシステムアクセス権限が必要
- UNCパスを使用したリモートファイルアクセス
- OS/SQLバージョン間のDLL互換性に注意

## 備考

- 異なるOS/SQLバージョン間ではDLLの再コンパイルが必要な場合がある
- DLLコピー失敗時もXP作成は試行される（元のパスを使用）
- SupportsShouldProcessによるWhatIf/Confirm対応

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaExtendedStoredProcedure.ps1 | `public/Copy-DbaExtendedStoredProcedure.ps1` | 207-216行目: $copyXPStatus オブジェクト定義 |

**読解のコツ**: MigrationObject型として出力され、Select-DefaultViewでプロパティが選択される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaExtendedStoredProcedure.ps1 | `public/Copy-DbaExtendedStoredProcedure.ps1` | 111-124行目: パラメータ定義 |
| 2-2 | Copy-DbaExtendedStoredProcedure.ps1 | `public/Copy-DbaExtendedStoredProcedure.ps1` | 126-163行目: beginブロック |

**主要処理フロー**:
1. **127-132行目**: ソースサーバー接続
2. **137-149行目**: カスタムXP取得SQL
3. **151-156行目**: XPクエリ実行

#### Step 3: DLL処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaExtendedStoredProcedure.ps1 | `public/Copy-DbaExtendedStoredProcedure.ps1` | 182-200行目: Binnパス取得 |
| 3-2 | Copy-DbaExtendedStoredProcedure.ps1 | `public/Copy-DbaExtendedStoredProcedure.ps1` | 289-318行目: DLLコピー処理 |

**主要処理フロー**:
- **185行目**: $destServer.RootDirectory + "\Binn"
- **299-300行目**: UNCパス生成
- **302-306行目**: Test-Path と Copy-Item

#### Step 4: XP作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Copy-DbaExtendedStoredProcedure.ps1 | `public/Copy-DbaExtendedStoredProcedure.ps1` | 321-343行目: sp_addextendedproc実行 |

**主要処理フロー**:
- **322行目**: sp_addextendedproc SQL生成
- **327行目**: クエリ実行
- **329-331行目**: 結果ステータス設定

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

```
Copy-DbaExtendedStoredProcedure
    │
    ├─ begin ブロック
    │      ├─ Connect-DbaInstance（ソース）
    │      └─ sys.procedures クエリ
    │
    └─ process ブロック
           └─ 各宛先サーバーをループ
                  │
                  ├─ Connect-DbaInstance（宛先）
                  │
                  ├─ sys.procedures クエリ（宛先）
                  │
                  ├─ RootDirectory取得（Binnパス）
                  │
                  └─ 各XPをループ
                         │
                         ├─ フィルタ適用
                         │
                         ├─ 既存チェック
                         │      └─ Force時: sp_dropextendedproc
                         │
                         ├─ sp_helpextendedproc（DLLパス取得）
                         │
                         ├─ Copy-Item（DLLコピー）
                         │
                         └─ sp_addextendedproc（XP作成）
```

### データフロー図

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

Source ─────────┐
                ├──▶ Connect-DbaInstance（ソース）
SourceSqlCred ──┤            │
                │            ▼
                │    sys.procedures クエリ
                │    (type='X', is_ms_shipped=0)
                │            │
Destination ────┤            ▼
                ├──▶ 各宛先サーバーをループ
DestinationSql ─┤            │
                │            ▼
ExtendedProc ───┤    フィルタ適用 + 既存チェック
                │            │
ExcludeExtProc ─┤            ▼
                │    ┌───────┴───────┐
Force ──────────┤    │ Force?      │
                │    └───────┬───────┘
                │    Yes│         │No
                │       ▼         │
                │    sp_drop      │
                │       │         │
                │       ▼         ▼
                │    DLLコピー試行
                │    (UNCパス)
                │       │
                │       ▼
                │    sp_addextendedproc
                │       │
                │       ▼
                └────────────────────────────────▶ MigrationObject
                                                  (Successful/Skipped/Failed)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaExtendedStoredProcedure.ps1 | `public/Copy-DbaExtendedStoredProcedure.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
