# 画面設計書 216-スクリプトエクスポート

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける「スクリプトエクスポート」機能（Export-DbaScript）の画面設計書です。SQL Server Management Objects (SMO)からT-SQL CREATE スクリプトを生成し、マイグレーションやデプロイメントに使用できるSQLファイルを出力する機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：SQL Server管理者やDBAは、テーブル、ストアドプロシージャ、ジョブ、ログインなどのデータベースオブジェクトをスクリプト化して、環境間のマイグレーションやバックアップ目的で使用する必要があります。手動でのスクリプト作成は手間がかかり、エラーが発生しやすいため、SMOのスクリプト機能を活用して自動化します。

**画面へのアクセス方法**：PowerShellコンソールから他のdbatools Get-*コマンドの出力を `Export-DbaScript` にパイプで渡して実行します。

**主要な操作・処理内容**：
1. dbatools Get-*コマンドからSMOオブジェクトを受け取る
2. SMO Scripterを使用してT-SQL CREATEスクリプトを生成
3. ファイルに出力またはPassthruで文字列として返す
4. バッチセパレータ（GO）の挿入
5. カスタムScriptingOptionsによる出力制御

**画面遷移**：CLIコマンドのため画面遷移はありません。Get-DbaLogin、Get-DbaAgentJob、Get-DbaDatabase、Get-DbaDbTableなど多数のコマンドからパイプライン入力を受け付けます。

**権限による表示制御**：対象オブジェクトへの読み取り権限が必要です。LinkedServer、Credential、Loginなどはパスワードが出力されない制限があります。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 218 | Export-DbaScript | 主機能 | SMOオブジェクトのスクリプト出力 |
| 372 | New-DbaScriptingOption | 補助機能 | スクリプティングオプション作成 |

## 画面種別

コマンドライン（CLI）実行画面

## URL/ルーティング

```powershell
# 基本使用
Get-DbaAgentJob -SqlInstance sql2016 | Export-DbaScript

# ファイル指定
Get-DbaAgentJob -SqlInstance sql2016 | Export-DbaScript -FilePath C:\temp\export.sql

# 文字列として取得
Get-DbaAgentJob -SqlInstance sql2016 | Export-DbaScript -Passthru
```

## 入出力項目

### パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| InputObject | object[] | Yes | - | SMOオブジェクト（Get-Dba*コマンドから） |
| Path | string | No | Path.DbatoolsExport | スクリプト出力先ディレクトリ |
| FilePath | string | No | - | 出力ファイルパス |
| Encoding | string | No | UTF8 | 文字エンコーディング（ASCII/BigEndianUnicode/Byte/String/Unicode/UTF7/UTF8/Unknown） |
| ScriptingOptionsObject | ScriptingOptions | No | - | カスタムスクリプティングオプション |
| BatchSeparator | string | No | Formatting.BatchSeparator（GO） | バッチセパレータ |
| NoPrefix | switch | No | $false | プレフィックスコメントを抑制 |
| Passthru | switch | No | $false | 文字列として返す |
| NoClobber | switch | No | $false | 既存ファイルの上書きを禁止 |
| Append | switch | No | $false | 既存ファイルに追記 |
| EnableException | switch | No | $false | 例外を有効化 |

## 表示項目

### 出力（ファイルモード）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| Name | string | 出力ファイル名 |
| FullName | string | 出力ファイルのフルパス |
| Directory | DirectoryInfo | ディレクトリオブジェクト |
| CreationTime | datetime | ファイル作成日時 |
| LastWriteTime | datetime | 最終更新日時 |
| Length | long | ファイルサイズ（バイト） |
| Extension | string | 拡張子（.sql） |

### 出力（Passthruモード）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| - | string | T-SQLスクリプト文字列 |

## イベント仕様

### 1-コマンド実行時

1. Test-ExportDirectoryでパスを検証
2. 各InputObjectに対して:
   - オブジェクトタイプを確認（Microsoft.SqlServer.*であること）
   - 親サーバーオブジェクトを取得
   - SMO Scripterを初期化
   - ScriptingOptionsObjectが指定された場合は適用
3. NoPrefixでない場合、プレフィックスコメントを生成
   - 実行ユーザー、日時、dbatools情報を含む
4. Passthruの場合:
   - scripter.EnumScript()でスクリプトを生成
   - BatchSeparatorを挿入
   - 文字列として出力
5. ファイル出力の場合:
   - NoClobberで既存ファイルチェック
   - プレフィックスを出力
   - scripter.EnumScript()でスクリプトを生成
   - BatchSeparatorを挿入
   - Out-Fileでファイル出力
   - FileInfoを返す

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

このコマンドはデータベースを更新しません。SMOオブジェクトの読み取りとファイル出力のみを行います。

## メッセージ仕様

| 種別 | メッセージ | 発生条件 |
|------|----------|---------|
| エラー | InputObject is of type {typename} which is not a SQL Management Object | SMOオブジェクト以外の入力時 |
| エラー | Failed to find valid SMO server object in input | 親サーバーオブジェクトが見つからない場合 |
| エラー | File already exists. If you want to overwrite it remove the -NoClobber parameter | NoClobberで既存ファイルがある場合 |
| 警告 | Support for {shorttype} is limited at this time. No passwords... | LinkedServer/Credential/Login入力時 |
| 警告 | Support for Configuration is limited at this time | Configuration入力時 |
| 警告 | Setting ScriptBatchTerminator to true and also having BatchSeparator as empty... | ScriptBatchTerminatorとBatchSeparator不整合時 |
| Verbose | Writing (maybe empty) prefix to file {scriptPath} | プレフィックス出力時 |
| Verbose | Exporting {object} | オブジェクト出力時 |
| Verbose | Exported {object} on {server} to {scriptPath} | 出力完了時 |

## 例外処理

| 例外条件 | 動作 |
|---------|------|
| SMOオブジェクト以外の入力 | Stop-Functionでエラーを報告、次のオブジェクトに継続 |
| 親サーバーオブジェクト未発見 | Stop-Functionでエラーを報告、次のオブジェクトに継続 |
| ファイル既存（NoClobber） | Stop-Functionでエラーを報告、次のオブジェクトに継続 |
| スクリプト生成エラー | Stop-Functionでエラーを報告 |

## 備考

- サポートされるInputObjectはMicrosoft.SqlServer.*で始まるSMOオブジェクト
- LinkedServer、Credential、Loginのパスワードは出力されない
- デフォルトのBatchSeparatorは「GO」（Formatting.BatchSeparator設定）
- プレフィックスには実行ユーザー、日時、dbatools情報が含まれる
- Appendパラメータで複数オブジェクトを1つのファイルに統合可能
- ScriptingOptionsObjectでスクリプト生成の詳細を制御可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbaScript.ps1 | `public/Export-DbaScript.ps1` | 出力タイプ（FileInfo/String）（行70-90） |
| 1-2 | New-DbaScriptingOption.ps1 | `public/New-DbaScriptingOption.ps1` | ScriptingOptionsオブジェクト（行11-26） |

**読解のコツ**: Export-DbaScriptはPassthruパラメータによって出力タイプが変わります。通常はFileInfo、Passthru時はString。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaScript.ps1 | `public/Export-DbaScript.ps1` | パラメータ定義（行161-177）とbegin/processブロック |

**主要処理フロー**:
1. **行178-206**: beginブロックでユーザー情報取得、ScriptingOptions保存
2. **行210-218**: InputObjectのタイプ検証（Microsoft.SqlServer.*）
3. **行240-251**: 親サーバーオブジェクトの取得
4. **行257-261**: SMO Scripterの初期化
5. **行263-267**: 出力パスの決定
6. **行269-290**: プレフィックスの生成と出力
7. **行292-347**: スクリプト生成と出力（Passthru/ファイル）
8. **行349-352**: FileInfoの返却

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

```
Export-DbaScript
    |
    +-- Test-ExportDirectory
    |      +-- 出力ディレクトリ検証
    |
    +-- オブジェクトタイプ検証
    |      +-- Microsoft.SqlServer.*チェック
    |
    +-- 親サーバーオブジェクト取得
    |      +-- Urn.Type == "Server"まで遡る
    |
    +-- New-Object Microsoft.SqlServer.Management.Smo.Scripter
    |      +-- SMO Scripter初期化
    |
    +-- Get-ExportFilePath
    |      +-- 出力ファイルパス生成
    |
    +-- scripter.EnumScript($object)
    |      +-- T-SQLスクリプト生成
    |
    +-- Out-File / Out-String
    |      +-- ファイル/文字列出力
    |
    +-- Get-ChildItem
           +-- FileInfo返却
```

### データフロー図

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

Get-DbaAgentJob ─────▶ InputObject検証 ───────────▶ SMOオブジェクト
      |
      v
                    親Server取得 ──────────────────▶ Serverオブジェクト
      |
      v
                    Scripter初期化 ────────────────▶ Scripterオブジェクト
      |
      v
                    EnumScript() ──────────────────▶ T-SQLスクリプト
      |
      v
Passthru? ─────────▶ Yes: Out-String ──────────────▶ 文字列出力
      |
      +── No ──────▶ Out-File ─────────────────────▶ .sqlファイル
                           |
                           +── Get-ChildItem ──────▶ FileInfo出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaScript.ps1 | `public/Export-DbaScript.ps1` | ソース | メインコマンド実装 |
| New-DbaScriptingOption.ps1 | `public/New-DbaScriptingOption.ps1` | ソース | スクリプティングオプション作成 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | 呼び出し元例 | ジョブ取得 |
| Get-DbaLogin.ps1 | `public/Get-DbaLogin.ps1` | 呼び出し元例 | ログイン取得 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | 呼び出し元例 | データベース取得 |
| Get-DbaDbTable.ps1 | `public/Get-DbaDbTable.ps1` | 呼び出し元例 | テーブル取得 |
