# 機能設計書 543-Export-DbaCredential

## 概要

本ドキュメントは、SQL Server資格情報を実行可能なT-SQL CREATE CREDENTIALスクリプトにエクスポートするPowerShell関数`Export-DbaCredential`の機能設計書である。

### 本機能の処理概要

Export-DbaCredentialは、SQL Server資格情報をT-SQLファイルにエクスポートし、別のインスタンスで資格情報を再作成できるCREATE CREDENTIAL文を生成する。デフォルトでは復号化されたパスワードを含むため、サーバー間での資格情報移行に最適である。

**業務上の目的・背景**：SQL Server資格情報は、プロキシアカウント、外部データソースアクセス、Azure Blob Storageへのバックアップ等で使用される重要なセキュリティオブジェクトである。サーバー移行時やディザスタリカバリ時に資格情報を正確に再作成する必要があるが、パスワードは暗号化されているため通常の方法では取得できない。本機能により、パスワードを含む完全な資格情報定義をエクスポートし、ターゲット環境で再作成可能にする。

**機能の利用シーン**：
- SQL Serverインスタンスの移行時に資格情報を移行
- ディザスタリカバリ手順の一環として資格情報をバックアップ
- 複数環境（開発・テスト・本番）間での資格情報の同期
- セキュリティ監査のための資格情報定義のドキュメント化

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続（パスワード取得時はDAC接続）
2. 資格情報オブジェクトの取得
3. パスワードの復号化（ExcludePassword未指定時）
4. CREATE CREDENTIAL T-SQL文の生成
5. ファイルへの出力またはパイプライン出力

**関連システム・外部連携**：パスワード復号化にはリモートWindowsレジストリアクセスが必要（PowerShellリモーティング使用）。

**権限による制御**：パスワードを含むエクスポートにはsysadmin権限が必要。DAC（Dedicated Administrator Connection）を使用。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | なし（CLI専用機能） | - | PowerShellコマンドラインから実行 |

## 機能種別

帳票出力 / セキュリティ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | 有効なPSCredential |
| Credential | PSCredential | No | OS接続用資格情報（パスワード復号化用） | 有効なPSCredential |
| Path | string | No | 出力ディレクトリパス | デフォルト: DbatoolsExport |
| FilePath | string | No | 出力ファイルフルパス | Pathを上書き |
| Identity | string[] | No | エクスポート対象の資格情報名 | - |
| ExcludePassword | switch | No | パスワードを除外 | - |
| Append | switch | No | 既存ファイルに追記 | - |
| Passthru | switch | No | パイプラインに出力 | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- SQL Server sys.credentials システムビュー
- Get-DecryptedObjectによる復号化されたパスワード（ExcludePassword未指定時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FullName | string | エクスポートファイルのフルパス |
| Name | string | ファイル名 |
| Length | long | ファイルサイズ（バイト） |
| LastWriteTime | DateTime | 最終更新日時 |
| Directory | DirectoryInfo | 親ディレクトリ |

### 出力先

- ファイル出力: 指定されたPath/FilePathへのSQLスクリプトファイル
- Passthru: PowerShellパイプラインへのT-SQL文字列

## 処理フロー

### 処理シーケンス

```
1. エクスポートディレクトリ検証
   └─ Test-ExportDirectory
2. インスタンスループ
   └─ 各SqlInstanceに対して処理
3. 接続確立
   └─ パスワード含む場合はDAC接続、そうでなければ通常接続
4. 資格情報取得
   └─ ExcludePassword: サーバーから直接取得
   └─ パスワード含む: Get-DecryptedObject使用
5. Identityフィルタリング
   └─ 指定された資格情報名でフィルタ
6. T-SQL生成
   └─ CREATE CREDENTIAL文の構築
7. 出力
   └─ Passthru: パイプライン出力
   └─ ファイル: Set-Content/Add-Content
8. DAC接続クローズ
   └─ Disconnect-DbaInstance
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[エクスポートディレクトリ検証]
    B --> C{Linux/macOS?}
    C -->|Yes| D[未サポートエラー]
    C -->|No| E[インスタンスループ]
    E --> F{ExcludePassword?}
    F -->|Yes| G[通常接続]
    F -->|No| H[DAC接続]
    G --> I[資格情報取得]
    H --> I
    I --> J{Identity指定?}
    J -->|Yes| K[フィルタリング]
    J -->|No| L[全資格情報]
    K --> L
    L --> M[CREATE CREDENTIAL文生成]
    M --> N{Passthru?}
    N -->|Yes| O[パイプライン出力]
    N -->|No| P{Append?}
    P -->|Yes| Q[Add-Content]
    P -->|No| R[Set-Content]
    Q --> S[ファイル情報出力]
    R --> S
    O --> T{DAC開いた?}
    S --> T
    T -->|Yes| U[Disconnect-DbaInstance]
    T -->|No| V[次のインスタンス]
    U --> V
    V --> W{全インスタンス完了?}
    W -->|No| E
    W -->|Yes| X[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-543-01 | プラットフォーム制限 | Linux/macOSでは実行不可 | 常時 |
| BR-543-02 | DAC必須 | パスワード取得にはDAC接続が必要 | ExcludePassword未指定時 |
| BR-543-03 | SQL 2005以上 | MinimumVersion 9が必要 | 常時 |
| BR-543-04 | 暗号化プロバイダ対応 | Cryptographic Providerの資格情報は特別処理 | MappedClassType判定 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 資格情報取得 | sys.credentials | SELECT | 資格情報定義の読み取り |

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

#### sys.credentials

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, identity, mapped_class_type | 全資格情報 | 読み取り専用 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Server接続失敗 | 接続情報を確認 |
| - | プラットフォームエラー | Linux/macOSで実行 | Windowsで実行 |
| - | ファイル書き込みエラー | 出力パスに書き込み不可 | パス権限を確認 |

### リトライ仕様

リトライ機能なし。エラー時は次のインスタンスの処理を継続。

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

読み取り専用操作のためトランザクション不要。

## パフォーマンス要件

特に定義なし。DAC接続は1インスタンスにつき1接続のみ可能な点に注意。

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

- パスワードを含むエクスポートは機密情報を含む
- 出力ファイルの適切なアクセス制御が必要
- ExcludePasswordオプションでセキュリティレビュー用出力が可能
- DAC接続にはsysadmin権限が必要

## 備考

- Linux/macOSはサポート対象外
- SQL Server 2005以上が必要
- DAC接続はインスタンスあたり1接続のみ

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbaCredential.ps1 | `public/Export-DbaCredential.ps1` | 87-99行目のパラメータ定義 |

#### Step 2: 接続処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaCredential.ps1 | `public/Export-DbaCredential.ps1` | 111-136行目の接続処理 |

**主要処理フロー**:
- **115行目**: ExcludePasswordによるDAC必要性判定
- **118行目**: 既存DAC接続の検出
- **127行目**: DAC接続の確立（DedicatedAdminConnectionパラメータ）

#### Step 3: 資格情報取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaCredential.ps1 | `public/Export-DbaCredential.ps1` | 138-156行目 |

**読解のコツ**: ExcludePassword時はサーバーオブジェクトから直接取得、パスワード含む場合はGet-DecryptedObject使用。

#### Step 4: T-SQL生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Export-DbaCredential.ps1 | `public/Export-DbaCredential.ps1` | 166-176行目 |

**主要処理フロー**:
- **167行目**: QUOTENAMEでの名前エスケープ
- **171-174行目**: 暗号化プロバイダ対応のSQL構築
- **175行目**: CREATE CREDENTIAL文の構築

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

```
Export-DbaCredential
    │
    ├─ Test-ExportDirectory
    │
    ├─ Connect-DbaInstance
    │      └─ DedicatedAdminConnection (パスワード取得時)
    │
    ├─ Get-DecryptedObject (パスワード取得時)
    │
    ├─ Get-ExportFilePath
    │
    ├─ Set-Content / Add-Content
    │
    └─ Disconnect-DbaInstance (DAC使用時)
```

### データフロー図

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

SqlInstance       ───▶ Connect-DbaInstance     ───▶ SMO Server Object
    │                                                      │
    ▼                                                      ▼
sys.credentials   ───▶ Get-DecryptedObject     ───▶ Credential + Password
    │                                                      │
    ▼                                                      ▼
Credential Info   ───▶ Build CREATE CREDENTIAL ───▶ T-SQL String
    │                                                      │
    ▼                                                      ▼
                  ───▶ Set-Content             ───▶ FileInfo Object
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaCredential.ps1 | `public/Export-DbaCredential.ps1` | ソース | メイン関数実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続（DAC対応） |
| Get-DecryptedObject.ps1 | `private/functions/Get-DecryptedObject.ps1` | ソース | 暗号化オブジェクト復号化 |
| Test-ExportDirectory.ps1 | `private/functions/Test-ExportDirectory.ps1` | ソース | エクスポートディレクトリ検証 |
| Get-ExportFilePath.ps1 | `private/functions/Get-ExportFilePath.ps1` | ソース | ファイルパス生成 |
