# 帳票設計書 4-Export-DbaInstance

## 概要

本ドキュメントは、dbatools PowerShellモジュールのExport-DbaInstanceコマンドレットに関する帳票設計書です。SQL Serverインスタンスの完全な構成をT-SQLスクリプトとしてエクスポートし、移行や災害復旧に使用する機能について記載しています。

### 本帳票の処理概要

Export-DbaInstanceは、dbatoolsの複数のエクスポートスクリプトを統合し、SQL Serverインスタンスの再作成または移行に必要なすべてを一括でキャプチャするコマンドレットです。各コンポーネントタイプごとに個別のT-SQLスクリプトファイルを生成し、タイムスタンプ付きのフォルダ構造で整理します。

**業務上の目的・背景**：SQL Serverインスタンスの移行、災害復旧スクリプトの準備、コンプライアンス用の構成ドキュメント化において、手動作業では数時間かかる作業を自動化します。バージョン管理や自動デプロイメントパイプラインとの連携にも最適です。

**帳票の利用シーン**：
1. インスタンス移行時の構成エクスポート（新ハードウェア、クラウド移行）
2. 開発・テスト環境の本番環境同期
3. 災害復旧計画の最新構成スナップショット維持
4. コンプライアンス監査用のセキュリティ設定ドキュメント化
5. 大規模更新前のベースライン構成取得

**主要な出力内容**：
1. データベース復元スクリプト（databases.sql）
2. ログイン定義（logins.sql）
3. SQL Agent構成（sqlagent.sql）
4. sp_configure設定（sp_configure.sql）
5. リンクサーバー、資格情報、その他20種類以上の構成ファイル

**帳票の出力タイミング**：Export-DbaInstanceコマンドを実行した時点で、指定したディレクトリにタイムスタンプ付きサブフォルダが作成され、各種スクリプトファイルが順次生成されます。

**帳票の利用者**：データベース管理者（DBA）、システム管理者、インフラエンジニア、DevOpsエンジニア

## 帳票種別

インスタンス構成エクスポート（T-SQLスクリプト群 / XMLファイル）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | PowerShellコンソール | N/A | Export-DbaInstanceコマンド実行 |
| N/A | タスクスケジューラ | N/A | スケジュール実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | SQL (.sql) / XML (.xml) |
| 用紙サイズ | N/A（スクリプトファイル） |
| 向き | N/A |
| フォルダ名 | {DomainInstanceName}-{yyyyMMddHHmmss} |
| 出力方法 | ディレクトリへの複数ファイル書き込み |
| 文字コード | UTF8（デフォルト） |

### 出力ファイル一覧

| ファイル名 | 対象コンポーネント | 除外パラメータ |
|-----------|------------------|--------------|
| sp_configure.sql | サーバー構成設定 | SpConfigure |
| customererrors.sql | ユーザー定義エラーメッセージ | CustomErrors |
| serverroles.sql | サーバーロール | ServerRoles |
| credentials.sql | SQL資格情報 | Credentials |
| logins.sql | ログイン定義 | Logins |
| dbmail.sql | データベースメール設定 | DatabaseMail |
| regserver.xml | 中央管理サーバー登録 | CentralManagementServer |
| backupdevices.sql | バックアップデバイス | BackupDevices |
| linkedservers.sql | リンクサーバー | LinkedServers |
| servertriggers.sql | サーバートリガー | SystemTriggers |
| databases.sql | データベース復元スクリプト | Databases |
| audits.sql | 監査定義 | Audits |
| auditspecs.sql | 監査仕様 | ServerAuditSpecifications |
| endpoints.sql | エンドポイント | Endpoints |
| policymanagement.sql | ポリシーベース管理 | PolicyManagement |
| resourcegov.sql | リソースガバナー | ResourceGovernor |
| extendedevents.sql | 拡張イベント | ExtendedEvents |
| sqlagent.sql | SQLエージェント構成 | AgentServer |
| replication.sql | レプリケーション設定 | ReplicationSettings |
| userobjectsinsysdbs.sql | システムDBのユーザーオブジェクト | SysDbUserObjects |
| AvailabilityGroups.sql | 可用性グループ | AvailabilityGroups |
| OleDbProvider.sql | OLEDBプロバイダー | OleDbProvider |

## 帳票レイアウト

### レイアウト概要

各スクリプトファイルは実行可能なT-SQL形式で出力されます。

```
┌─────────────────────────────────────┐
│    ヘッダーコメント（オプション）      │
│  (作成日時、dbatools情報等)          │
├─────────────────────────────────────┤
│                                     │
│    T-SQL CREATE/ALTER文             │
│    GO（バッチセパレータ）             │
│                                     │
│    T-SQL CREATE/ALTER文             │
│    GO                               │
│         ...                         │
│                                     │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | コメント | 作成日時・作成者・dbatools情報 | 自動生成 | SQLコメント |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | T-SQL文 | 各オブジェクトのCREATE/ALTER文 | SMOスクリプト生成 | T-SQL | 可変 |
| 2 | バッチセパレータ | GOまたはカスタム区切り | BatchSeparatorパラメータ | 文字列 | N/A |

### フッター部

コマンドは生成されたファイルのFileInfoオブジェクトを返します。

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | FullName | ファイル完全パス | System.IO.FileInfo | 文字列 |
| 2 | Name | ファイル名 | System.IO.FileInfo | 文字列 |
| 3 | Length | ファイルサイズ | System.IO.FileInfo | 整数 |
| 4 | CreationTime | 作成日時 | System.IO.FileInfo | DateTime |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| SqlInstance | 対象SQL Serverインスタンス | Yes |
| Path | 出力ルートディレクトリ | No（デフォルト: DbatoolsExportパス） |
| Exclude | 除外するコンポーネント | No |

### 除外可能コンポーネント

| 値 | 対象 |
|----|------|
| AgentServer | SQLエージェント構成 |
| Audits | 監査 |
| AvailabilityGroups | 可用性グループ |
| BackupDevices | バックアップデバイス |
| CentralManagementServer | CMS登録 |
| Credentials | 資格情報 |
| CustomErrors | ユーザー定義メッセージ |
| DatabaseMail | データベースメール |
| Databases | データベース復元 |
| Endpoints | エンドポイント |
| ExtendedEvents | 拡張イベント |
| LinkedServers | リンクサーバー |
| Logins | ログイン |
| PolicyManagement | ポリシー管理 |
| ReplicationSettings | レプリケーション |
| ResourceGovernor | リソースガバナー |
| ServerAuditSpecifications | 監査仕様 |
| ServerRoles | サーバーロール |
| SpConfigure | sp_configure設定 |
| SysDbUserObjects | システムDBユーザーオブジェクト |
| SystemTriggers | システムトリガー |
| OleDbProvider | OLEDBプロバイダー |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | コンポーネント種別ごとに処理順で出力 | N/A |

### 改ページ条件

スクリプトファイルのため改ページは適用されません。

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| SMO Server オブジェクト | 各種構成情報取得 | N/A |
| sys.server_principals | ログイン情報 | N/A |
| msdb.dbo.sysjobs | SQLエージェントジョブ | N/A |
| master.sys.configurations | sp_configure設定 | N/A |

### 使用するdbatoolsコマンド

| コマンド | 出力ファイル | 用途 |
|---------|-------------|------|
| Export-DbaSpConfigure | sp_configure.sql | サーバー構成 |
| Get-DbaCustomError | customererrors.sql | カスタムエラー |
| Get-DbaServerRole | serverroles.sql | サーバーロール |
| Export-DbaCredential | credentials.sql | 資格情報 |
| Export-DbaLogin | logins.sql | ログイン |
| Get-DbaDbMail* | dbmail.sql | データベースメール |
| Export-DbaRegServer | regserver.xml | CMS |
| Get-DbaBackupDevice | backupdevices.sql | バックアップデバイス |
| Export-DbaLinkedServer | linkedservers.sql | リンクサーバー |
| Get-DbaInstanceTrigger | servertriggers.sql | サーバートリガー |
| Get-DbaDbBackupHistory + Restore-DbaDatabase | databases.sql | DB復元 |
| Get-DbaInstanceAudit | audits.sql | 監査 |
| Get-DbaInstanceAuditSpecification | auditspecs.sql | 監査仕様 |
| Get-DbaEndpoint | endpoints.sql | エンドポイント |
| Get-DbaPbm* | policymanagement.sql | ポリシー管理 |
| Get-DbaRg* | resourcegov.sql | リソースガバナー |
| Export-DbaXESession | extendedevents.sql | 拡張イベント |
| Get-DbaAgent* | sqlagent.sql | SQLエージェント |
| Export-DbaReplServerSetting | replication.sql | レプリケーション |
| Export-DbaSysDbUserObject | userobjectsinsysdbs.sql | システムDBオブジェクト |
| Get-DbaAvailabilityGroup | AvailabilityGroups.sql | 可用性グループ |
| Get-DbaOleDbProvider | OleDbProvider.sql | OLEDBプロバイダー |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| フォルダ名 | DomainInstanceName.replace('\', '$') + '-' + timestamp | N/A | Forceオプション時はタイムスタンプなし |
| 処理時間 | Stopwatch.Elapsed | N/A | ログ出力用 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[Export-DbaInstance実行] --> B{DAC接続必要?}
    B -->|Yes| C[専用管理者接続でConnect]
    B -->|No| D[通常接続でConnect]
    C --> E[出力フォルダ作成]
    D --> E
    E --> F{各コンポーネント処理}
    F --> G[SpConfigure出力]
    G --> H[CustomErrors出力]
    H --> I[ServerRoles出力]
    I --> J[Credentials出力]
    J --> K[Logins出力]
    K --> L[DatabaseMail出力]
    L --> M[CMS出力]
    M --> N[BackupDevices出力]
    N --> O[LinkedServers出力]
    O --> P[SystemTriggers出力]
    P --> Q[Databases出力]
    Q --> R[Audits出力]
    R --> S[AuditSpecs出力]
    S --> T[Endpoints出力]
    T --> U[PolicyManagement出力]
    U --> V[ResourceGovernor出力]
    V --> W[ExtendedEvents出力]
    W --> X[AgentServer出力]
    X --> Y[ReplicationSettings出力]
    Y --> Z[SysDbUserObjects出力]
    Z --> AA[AvailabilityGroups出力]
    AA --> AB[OleDbProvider出力]
    AB --> AC[DAC接続解除]
    AC --> AD[完了メッセージ出力]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 接続エラー | SQL Server接続失敗 | "Failure" | 接続情報・権限を確認 |
| ディレクトリエラー | 出力フォルダ作成失敗 | "Failure" | パス・権限を確認 |
| sp_configureエラー | show advanced options設定失敗 | "Can't set 'show advanced options' to 1 on instance" | sysadmin権限を確認 |
| ファイル書き込みエラー | ファイル出力失敗 | "Can't write to $FilePath" | ディスク容量・権限確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | インスタンス構成量に依存 |
| 目標出力時間 | 数分〜数十分（構成複雑度に依存） |
| 同時出力数上限 | 1インスタンス/セッション |

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

- パスワード取得のためDAC（専用管理者接続）が必要
- ExcludePasswordオプションでパスワードを除外可能
- 資格情報・リンクサーバーにはWindowsリモートレジストリアクセスが必要
- 出力スクリプトには機密情報が含まれる可能性があり、適切なアクセス制御が必須
- sysadmin権限が必要（一部機能）

## 備考

- SQL Server 2005以上対応（MinimumVersion 10）
- PowerShell Coreではポリシー管理のエクスポートは非対応
- -Forceオプションでタイムスタンプなしフォルダ名（上書き用）
- バッチセパレータはformatting.batchseparator設定から取得

---

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

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

### 推奨読解順序

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

各エクスポートコマンドの出力形式を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbaScript.ps1 | `public/Export-DbaScript.ps1` | SMOスクリプト生成の基盤 |
| 1-2 | New-DbaScriptingOption.ps1 | `public/New-DbaScriptingOption.ps1` | スクリプトオプション設定 |

**読解のコツ**: ScriptingOptionsObjectの役割と各プロパティの影響を理解

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaInstance.ps1 | `public/Export-DbaInstance.ps1` | パラメータと全体処理フロー |

**主要処理フロー**:
1. **行203-214**: beginブロック - 初期設定、ScriptingOption初期化
2. **行215-477**: processブロック - 接続、各コンポーネントエクスポート
3. **行479-484**: endブロック - 完了メッセージ

#### Step 3: DAC接続処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaInstance.ps1 | `public/Export-DbaInstance.ps1` | 専用管理者接続ロジック |

**主要処理フロー**:
- **行219-242**: DAC接続必要性判定と接続処理
- **行472-474**: DAC接続解除

#### Step 4: 各コンポーネントエクスポート処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Export-DbaInstance.ps1 | `public/Export-DbaInstance.ps1` | 個別エクスポート処理 |

**主要処理フロー**:
- **行265-270**: SpConfigure（Export-DbaSpConfigure呼び出し）
- **行293-298**: Logins（Export-DbaLogin呼び出し）
- **行348-353**: Databases（Get-DbaDbBackupHistory + Restore-DbaDatabase）
- **行422-435**: AgentServer（複数Get-DbaAgent*コマンド）

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

```
Export-DbaInstance (PowerShell)
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続（DAC対応）
    │
    ├─ Export-DbaSpConfigure
    │      └─ sp_configure設定出力
    │
    ├─ Get-DbaCustomError | Export-DbaScript
    │      └─ カスタムエラー出力
    │
    ├─ Get-DbaServerRole | Export-DbaScript
    │      └─ サーバーロール出力
    │
    ├─ Export-DbaCredential
    │      └─ 資格情報出力
    │
    ├─ Export-DbaLogin
    │      └─ ログイン出力
    │
    ├─ Get-DbaDbMail* | Export-DbaScript
    │      └─ データベースメール出力
    │
    ├─ Export-DbaRegServer
    │      └─ CMS登録出力
    │
    ├─ Get-DbaBackupDevice | Export-DbaScript
    │      └─ バックアップデバイス出力
    │
    ├─ Export-DbaLinkedServer
    │      └─ リンクサーバー出力
    │
    ├─ Get-DbaInstanceTrigger | Export-DbaScript
    │      └─ サーバートリガー出力
    │
    ├─ Get-DbaDbBackupHistory | Restore-DbaDatabase -OutputScriptOnly
    │      └─ データベース復元スクリプト出力
    │
    ├─ Get-DbaInstanceAudit | Export-DbaScript
    │      └─ 監査出力
    │
    ├─ Get-DbaInstanceAuditSpecification | Export-DbaScript
    │      └─ 監査仕様出力
    │
    ├─ Get-DbaEndpoint | Export-DbaScript
    │      └─ エンドポイント出力
    │
    ├─ Get-DbaPbm* (Condition, ObjectSet, Policy)
    │      └─ ポリシー管理出力
    │
    ├─ Get-DbaRg* (ClassifierFunction, ResourcePool, WorkloadGroup, ResourceGovernor)
    │      └─ リソースガバナー出力
    │
    ├─ Get-DbaXESession | Export-DbaXESession
    │      └─ 拡張イベント出力
    │
    ├─ Get-DbaAgent* (JobCategory, Operator, Alert, Proxy, Schedule, Job)
    │      └─ SQLエージェント出力
    │
    ├─ Export-DbaReplServerSetting
    │      └─ レプリケーション設定出力
    │
    ├─ Export-DbaSysDbUserObject
    │      └─ システムDBユーザーオブジェクト出力
    │
    ├─ Get-DbaAvailabilityGroup | Export-DbaScript
    │      └─ 可用性グループ出力
    │
    └─ Get-DbaOleDbProvider | Export-DbaScript
           └─ OLEDBプロバイダー出力
```

### データフロー図

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

SqlInstance           ┌──────────────────┐
    └─────────────────▶│ Connect-DbaInstance │
                       │   (DAC対応)        │
                       └──────────┬─────────┘
                                  │
                                  ▼
                       ┌──────────────────┐          /{exportPath}/
                       │ 各Export/Get     │
                       │ コマンド呼び出し  │────────▶  sp_configure.sql
                       │                  │────────▶  logins.sql
                       │                  │────────▶  credentials.sql
                       │                  │────────▶  sqlagent.sql
                       │                  │────────▶  databases.sql
                       │                  │────────▶  ...20+ファイル
                       └──────────────────┘
                                  │
                                  ▼
                       ┌──────────────────┐
                       │ FileInfo出力     │────────▶  パイプライン出力
                       └──────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaInstance.ps1 | `public/Export-DbaInstance.ps1` | ソース | メインコマンドレット |
| Export-DbaSpConfigure.ps1 | `public/Export-DbaSpConfigure.ps1` | ソース | sp_configureエクスポート |
| Export-DbaLogin.ps1 | `public/Export-DbaLogin.ps1` | ソース | ログインエクスポート |
| Export-DbaCredential.ps1 | `public/Export-DbaCredential.ps1` | ソース | 資格情報エクスポート |
| Export-DbaLinkedServer.ps1 | `public/Export-DbaLinkedServer.ps1` | ソース | リンクサーバーエクスポート |
| Export-DbaScript.ps1 | `public/Export-DbaScript.ps1` | ソース | SMOスクリプト生成基盤 |
| Export-DbaXESession.ps1 | `public/Export-DbaXESession.ps1` | ソース | 拡張イベントエクスポート |
| Export-DbaRegServer.ps1 | `public/Export-DbaRegServer.ps1` | ソース | CMS登録エクスポート |
| Export-DbaReplServerSetting.ps1 | `public/Export-DbaReplServerSetting.ps1` | ソース | レプリケーションエクスポート |
| Export-DbaSysDbUserObject.ps1 | `public/Export-DbaSysDbUserObject.ps1` | ソース | システムDBオブジェクトエクスポート |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続管理 |
| dbatools.psd1 | `dbatools.psd1` | 設定 | モジュールマニフェスト |
