# 画面設計書 234-拡張ストアドプロシージャ

## 概要

本ドキュメントは、dbatools PowerShell モジュールの `Copy-DbaExtendedStoredProcedure` コマンドに関する設計書です。このコマンドは、カスタム拡張ストアドプロシージャ（XP）とその関連 DLL ファイルを SQL Server インスタンス間でコピーするマイグレーション機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：拡張ストアドプロシージャ（Extended Stored Procedure、XP）は、DLL ベースのプロシージャで SQL Server の機能を拡張します。サーバー移行やレプリケーション環境の構築時に、カスタム XP を確実に移行することは重要です。本コマンドは、ソースサーバーからカスタム XP の定義をコピーし、関連する DLL ファイルの移行も試みます。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから `Copy-DbaExtendedStoredProcedure` コマンドを実行します。

**主要な操作・処理内容**：
1. ソース SQL Server インスタンスに接続（最小バージョン: SQL Server 2005）
2. カスタム拡張ストアドプロシージャを検索（is_ms_shipped = 0）
3. ターゲットサーバーに既存の XP があるかチェック
4. Force 指定時は既存 XP を削除
5. DLL ファイルを UNC パス経由でコピー（可能な場合）
6. sp_addextendedproc でターゲットに XP を作成
7. 処理結果をパイプラインに出力

**画面遷移**：CLI コマンドのため画面遷移は存在しませんが、出力結果は他の dbatools コマンドにパイプライン接続可能です。

**権限による表示制御**：ソースおよびターゲットサーバーで sysadmin 権限が必要です。また、Binn ディレクトリへのファイルシステムアクセス権限も必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 656 | Copy-DbaExtendedStoredProcedure | 主機能 | 拡張ストアドプロシージャのコピー |
| 90 | Connect-DbaInstance | 補助機能 | SQL Server インスタンスへの接続 |

## 画面種別

CLI コマンド（コピー・マイグレーション）

## URL/ルーティング

PowerShell コマンド: `Copy-DbaExtendedStoredProcedure`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| 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 | 例外を有効化 |

### 出力項目（MigrationObject）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| DateTime | DbaDateTime | 処理日時 |
| SourceServer | string | ソースサーバー名 |
| DestinationServer | string | ターゲットサーバー名 |
| Name | string | XP 名 |
| Schema | string | スキーマ名 |
| Type | string | "Extended Stored Procedure" |
| Status | string | 処理結果（Successful/Skipped/Failed） |
| Notes | string | 追加情報・エラーメッセージ |

## 表示項目

デフォルト表示プロパティ:
- DateTime
- SourceServer
- DestinationServer
- Name
- Type
- Status
- Notes

## イベント仕様

### 1-コマンド実行

1. ソースサーバーへの接続（最小バージョン: SQL Server 2005）
2. カスタム XP のクエリ実行（type = 'X' AND is_ms_shipped = 0）
3. 各ターゲットサーバーに対して:
   - ターゲットサーバーへの接続
   - 既存 XP のチェック
   - ExtendedProcedure/ExcludeExtendedProcedure によるフィルタリング
4. 各 XP に対して:
   - 既存チェック（Force なしの場合はスキップ）
   - Force 指定時は sp_dropextendedproc で削除
   - DLL パスの取得（sp_helpextendedproc）
   - DLL ファイルの UNC 経由コピー
   - sp_addextendedproc で XP 作成
5. 処理結果をパイプラインに出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| XP 検索 | sys.procedures | SELECT | 拡張ストアドプロシージャの取得 |
| XP 削除 | master.dbo | EXEC sp_dropextendedproc | 既存 XP の削除（Force 時） |
| XP 作成 | master.dbo | EXEC sp_addextendedproc | XP の作成 |
| DLL 情報取得 | master.dbo | EXEC sp_helpextendedproc | DLL パスの取得 |

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

#### ターゲットサーバー（sp_addextendedproc 実行時）

| 操作 | 項目 | 更新値 | 備考 |
|-----|------|-------|------|
| INSERT | XP 定義 | ソースからコピー | master データベースに登録 |

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| Verbose | "No custom Extended Stored Procedures found on source server" | ソースに XP なし |
| Verbose | "Extended Stored Procedure $xpFullName exists at destination. Use -Force to drop and migrate." | 既存 XP（Force なし） |
| Verbose | "Dropping Extended Stored Procedure $xpFullName" | Force 削除時 |
| Verbose | "Copying DLL from $sourceUncPath to $destUncPath" | DLL コピー時 |
| Verbose | "Successfully copied DLL file" | DLL コピー成功 |
| Verbose | "Creating Extended Stored Procedure $xpFullName" | XP 作成時 |
| Warning | "Source DLL not found at expected path" | DLL 未検出 |
| Warning | "Failed to copy DLL file" | DLL コピー失敗 |
| Warning | "Could not determine source or destination Binn paths" | Binn パス不明 |
| Warning | "Extended Stored Procedure created but DLL was not copied" | XP 作成成功・DLL 未コピー |
| Error | "Failure" | 接続エラー |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ソース接続失敗 | Stop-Function で処理停止 |
| ターゲット接続失敗 | Stop-Function で警告、次のターゲットへ続行 |
| XP クエリ失敗 | Stop-Function で処理停止 |
| XP 削除失敗 | Status = "Failed"、次の XP へ続行 |
| DLL コピー失敗 | 警告を出力、XP 作成は続行 |
| XP 作成失敗 | Status = "Failed"、次の XP へ続行 |

## 備考

- SQL Server 2005 以降が必要（最小バージョン 9）
- DLL ファイルの互換性: 異なる Windows/SQL Server バージョン間では DLL の再コンパイルが必要な場合がある
- UNC パスでのファイルコピーには適切なネットワーク権限が必要
- Status 値:
  - Successful: XP と DLL の両方が正常にコピー
  - Successful (DLL not copied): XP 作成成功、DLL コピー失敗
  - Skipped: 既存 XP あり（Force なし）
  - Failed: 処理失敗
- システム XP（is_ms_shipped = 1）は対象外

---

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

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

### 推奨読解順序

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

出力される MigrationObject の構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaExtendedStoredProcedure.ps1 | `public/Copy-DbaExtendedStoredProcedure.ps1` | 行207-216: 出力オブジェクト構造 |

**読解のコツ**: MigrationObject タイプとして出力される PSCustomObject の構造を確認する。

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

処理の起点となるファイル・関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaExtendedStoredProcedure.ps1 | `public/Copy-DbaExtendedStoredProcedure.ps1` | 関数全体の構造と処理フロー |

**主要処理フロー**:
1. **行126-132**: begin ブロック - ソースサーバー接続
2. **行137-149**: カスタム XP を検索する SQL クエリ
3. **行165-173**: ターゲットサーバー接続
4. **行202-261**: 各 XP の処理（既存チェック、削除、作成）
5. **行263-344**: DLL コピーと XP 作成処理

#### Step 3: DLL コピーロジックを理解する

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

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

```
Copy-DbaExtendedStoredProcedure
    │
    ├─ Connect-DbaInstance (Source) (行128)
    │      └─ SQL Server SMO 接続
    │
    ├─ $sourceServer.Query (行152)
    │      └─ カスタム XP 検索クエリ
    │
    ├─ Connect-DbaInstance (Destination) (行170)
    │      └─ SQL Server SMO 接続
    │
    ├─ $destServer.Query (行177)
    │      └─ ターゲット XP 確認クエリ
    │
    ├─ sp_dropextendedproc (行251)
    │      └─ 既存 XP 削除（Force 時）
    │
    ├─ sp_helpextendedproc (行269)
    │      └─ DLL パス取得
    │
    ├─ Copy-Item (行304)
    │      └─ DLL ファイルコピー
    │
    └─ sp_addextendedproc (行322)
           └─ XP 作成
```

### データフロー図

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

Source ────────────────▶ Connect-DbaInstance ───────────▶ Server Object
                               │
                         カスタム XP クエリ
                               │
Destination ───────────────▶ Connect-DbaInstance ─────────▶ Server Object
                               │
ExtendedProcedure ─────────▶ フィルタリング ───────────────▶ 処理対象 XP
ExcludeExtendedProcedure ──▶
                               │
Force ─────────────────────▶ 既存 XP 削除判定
                               │
                         DLL コピー試行
                               │
                         sp_addextendedproc 実行
                               │
                         MigrationObject 生成 ─────────────▶ Pipeline Output
```

### 関連ファイル一覧

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