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

## はじめに

このガイドラインは、dbatoolsのコードベースを効率的に理解するための手引きです。
PowerShellに精通していないエンジニアでも、段階的に学習できるよう構成されています。

**対象読者:**
- プロジェクトに新規参画するエンジニア
- 他言語からの経験者
- コードレビューを行う担当者

**プロジェクト概要:**
dbatoolsは、SQL Serverの管理・自動化を行うPowerShellモジュールです。約700のコマンドを提供し、SQL Server 2000からSQL Server 2022、Azure SQL Databaseまで幅広いバージョンをサポートしています。

---

## 1. 言語基礎

> このセクションでは、PowerShellの基本構文と概念を解説します。

### 1.1 プログラム構造

PowerShell関数は `function` キーワードで定義され、コメントベースのヘルプ、パラメータブロック、処理ブロック（Begin/Process/End）で構成されます。

```powershell
# ファイル: public/Get-DbaDatabase.ps1:1-14
function Get-DbaDatabase {
    <#
    .SYNOPSIS
        Retrieves database objects and metadata from SQL Server instances with advanced filtering and usage analytics.

    .DESCRIPTION
        Retrieves detailed database information from one or more SQL Server instances...
    #>
```

dbatoolsでは、各公開コマンドは1ファイル1関数の構造で、ファイル名が関数名と一致します。

### 1.2 データ型と変数

PowerShellでは変数は `$` で始まり、型指定は省略可能です。

```powershell
# ファイル: public/Get-DbaDatabase.ps1:217-242
param (
    [parameter(Mandatory, ValueFromPipeline)]
    [DbaInstanceParameter[]]$SqlInstance,
    [PSCredential]$SqlCredential,
    [string[]]$Database,
    [string[]]$ExcludeDatabase,
    [switch]$EnableException
)
```

**主要な型:**
- `[string]` - 文字列
- `[int]` - 整数
- `[switch]` - ブール型フラグ（引数なしで使用）
- `[PSCredential]` - 認証情報
- `[DbaInstanceParameter]` - dbatools独自のSQL Serverインスタンス型

### 1.3 制御構造

```powershell
# 条件分岐
if ($ExcludeUser -and $ExcludeSystem) {
    Stop-Function -Message "You cannot specify both ExcludeUser and ExcludeSystem." -Continue -EnableException $EnableException
}

# ループ処理 - ファイル: public/Get-DbaDatabase.ps1:254-259
foreach ($instance in $SqlInstance) {
    try {
        $server = Connect-DbaInstance -SqlInstance $instance -SqlCredential $SqlCredential
    } catch {
        Stop-Function -Message "Failure" -Category ConnectionError -ErrorRecord $_ -Target $instance -Continue
    }
}
```

### 1.4 関数/メソッド定義

PowerShell関数は3つのブロックで構成されます：

```powershell
function Get-DbaDatabase {
    param ( ... )

    begin {
        # 初期化処理（1回だけ実行）
        if ($ExcludeUser -and $ExcludeSystem) {
            Stop-Function -Message "..." -Continue -EnableException $EnableException
        }
    }

    process {
        # パイプライン入力ごとに実行
        if (Test-FunctionInterrupt) { return }
        foreach ($instance in $SqlInstance) {
            # 主処理
        }
    }

    end {
        # 終了処理（1回だけ実行）
    }
}
```

### 1.5 モジュール/インポート

```powershell
# ファイル: dbatools.psm1:1-6
#requires -Version 3.0
param(
    [Collections.IDictionary]
    [Alias('Options')]
    $Option = @{ }
)
```

モジュールは `dbatools.psm1` をエントリーポイントとし、`dbatools.psd1` マニフェストファイルで依存関係と公開関数を定義します。

---

## 2. プロジェクト固有の概念

> このセクションでは、dbatools特有の概念を解説します。

### 2.1 フレームワーク固有の概念

#### SMO (SQL Server Management Objects)

dbatoolsはSQL Server管理にSMOライブラリを使用します。SMOはオブジェクト操作、スクリプト生成、プロパティアクセスに使用されます。

```powershell
# SMOを使用したデータベースアクセス
$server = Connect-DbaInstance -SqlInstance $instance
foreach ($db in $server.Databases) {
    # SMOオブジェクトのプロパティにアクセス
    $db.Name
    $db.RecoveryModel
}
```

#### Connect-DbaInstance

すべてのSQL Server操作の基盤となる接続コマンドです。

```powershell
# ファイル: public/Connect-DbaInstance.ps1:1-15
function Connect-DbaInstance {
    <#
    .SYNOPSIS
        Creates a persistent SQL Server Management Object (SMO) connection for database operations.

    .DESCRIPTION
        This command creates a reusable SQL Server Management Object (SMO) that serves as the foundation
        for most dbatools operations.
    #>
}
```

### 2.2 プロジェクト独自のパターン

#### EnableException パターン

エラーハンドリングの標準パターンです。デフォルトでは警告メッセージを表示し、`-EnableException` 指定時は例外をスローします。

```powershell
# ファイル: public/Get-DbaDatabase.ps1:100-103
.PARAMETER EnableException
    By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
    This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting.
    Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch.
```

#### Stop-Function / Test-FunctionInterrupt パターン

gracefulに関数を終了するためのパターンです。

```powershell
# ファイル: private/functions/flowcontrol/Stop-Function.ps1:2-12
function Stop-Function {
    <#
    .SYNOPSIS
        Function that interrupts a function.

    .DESCRIPTION
        Function that interrupts a function.
        This function is a utility function used by other functions to reduce error catching overhead.
        It is designed to allow gracefully terminating a function with a warning by default and also allow opt-in into terminating errors.
    #>
}

# 使用例
if (Test-FunctionInterrupt) { return }
```

#### Test-Bound パターン

パラメータが指定されたかをチェックするヘルパー関数です。

```powershell
# ファイル: private/functions/flowcontrol/Test-Bound.ps1:1-55
function Test-Bound {
    <#
    .SYNOPSIS
        Helper function that tests if a parameter was bound.
    #>
    param (
        [string[]]$ParameterName,
        [switch]$Not,
        [switch]$And
    )
}

# 使用例
if (Test-Bound "Day") {
    # Day パラメータが指定された場合の処理
}
```

---

## 3. 命名規則

> このセクションでは、プロジェクト全体で使用される命名規則を解説します。

### 3.1 ファイル・ディレクトリ命名

| パターン | 意味 | 例 |
|---------|------|-----|
| `<Verb>-Dba<Noun>.ps1` | 公開コマンド | `Get-DbaDatabase.ps1`, `Backup-DbaDatabase.ps1` |
| `<Verb>-Dba<Noun>.Tests.ps1` | テストファイル | `Get-DbaDatabase.Tests.ps1` |
| `*.ps1` (private/) | 内部関数 | `Test-Bound.ps1`, `Stop-Function.ps1` |

### 3.2 クラス・関数・変数命名

| プレフィックス/サフィックス | 意味 | 例 |
|---------------------------|------|-----|
| `Dba` | dbatools公開コマンド | `Get-DbaDatabase`, `Connect-DbaInstance` |
| `$splat<Purpose>` | スプラット変数（3+パラメータ時） | `$splatConnection`, `$splatBackup` |
| `$TestConfig` | テスト設定変数 | `$TestConfig.instance2`, `$TestConfig.SqlCredential` |
| `dbatoolsci_` | テストリソースのプレフィックス | `dbatoolsci_testdb`, `dbatoolsci_user_12345` |

### 3.3 プログラム分類一覧

| 分類 | 動詞 | 説明 | 例 |
|-----|------|-----|-----|
| 取得 | Get- | オブジェクト情報の取得 | `Get-DbaDatabase`, `Get-DbaLogin` |
| 作成 | New- | 新規オブジェクトの作成 | `New-DbaDatabase`, `New-DbaLogin` |
| 設定 | Set- | オブジェクトのプロパティ変更 | `Set-DbaDbRecoveryModel` |
| 削除 | Remove- | オブジェクトの削除 | `Remove-DbaDatabase`, `Remove-DbaLogin` |
| コピー | Copy- | サーバー間でのオブジェクトコピー | `Copy-DbaDatabase`, `Copy-DbaLogin` |
| バックアップ | Backup- | バックアップ操作 | `Backup-DbaDatabase` |
| リストア | Restore- | リストア操作 | `Restore-DbaDatabase` |
| テスト | Test- | 検証・テスト操作 | `Test-DbaConnection`, `Test-DbaLastBackup` |
| 接続 | Connect- | 接続の確立 | `Connect-DbaInstance` |

---

## 4. ディレクトリ構造

> このセクションでは、プロジェクトのディレクトリ構造を解説します。

```
dbatools-development/
├── dbatools.psd1          # モジュールマニフェスト
├── dbatools.psm1          # モジュールエントリーポイント
├── CLAUDE.md              # スタイルガイド
├── CONTRIBUTING.md        # 貢献ガイド
├── public/                # 公開コマンド (約700ファイル)
│   ├── Get-DbaDatabase.ps1
│   ├── Backup-DbaDatabase.ps1
│   └── ...
├── private/               # 内部関数
│   ├── functions/         # ヘルパー関数
│   │   ├── flowcontrol/   # フロー制御関数
│   │   ├── configuration/ # 設定関数
│   │   └── tabcompletion/ # タブ補完関数
│   ├── configurations/    # 設定ファイル
│   ├── dynamicparams/     # 動的パラメータ
│   ├── scripts/           # 起動スクリプト
│   └── testing/           # テストヘルパー
├── tests/                 # Pesterテスト (約700ファイル)
├── bin/                   # バイナリ・リソースファイル
│   ├── typealiases.ps1    # 型エイリアス
│   ├── XEtemplates/       # 拡張イベントテンプレート
│   └── ...
├── xml/                   # 型・フォーマット定義
├── en-us/                 # ヘルプファイル
├── opt/                   # オプショナル機能
└── .github/               # GitHub設定
    ├── prompts/           # AIプロンプト
    └── workflows/         # CI/CDワークフロー
```

### 各ディレクトリの役割

| ディレクトリ | 役割 | 主要ファイル |
|-------------|------|-------------|
| `public/` | 公開コマンド（エクスポートされる関数） | `Get-DbaDatabase.ps1`, `Connect-DbaInstance.ps1` |
| `private/functions/` | 内部ヘルパー関数 | `Stop-Function.ps1`, `Test-Bound.ps1` |
| `private/functions/flowcontrol/` | フロー制御関数 | `Test-FunctionInterrupt.ps1` |
| `private/configurations/` | モジュール設定 | `configuration.ps1` |
| `tests/` | Pester v5テスト | `*.Tests.ps1` |
| `bin/` | バイナリ・静的リソース | `typealiases.ps1`, `dbatools.xml` |

---

## 5. アーキテクチャ

> このセクションでは、プロジェクトのアーキテクチャパターンを解説します。

### 5.1 全体アーキテクチャ

dbatoolsは**モジュラーモノリス**アーキテクチャを採用しています。単一のPowerShellモジュールとして配布されますが、内部は機能ごとに整理されています。

```
┌─────────────────────────────────────────────────────────────┐
│                     dbatools Module                          │
├─────────────────────────────────────────────────────────────┤
│  dbatools.psd1 (Manifest)                                   │
│    ├── RequiredModules: dbatools.library                    │
│    └── FunctionsToExport: [約700コマンド]                    │
├─────────────────────────────────────────────────────────────┤
│  dbatools.psm1 (Entry Point)                                │
│    ├── Import dbatools.library (SMO, etc.)                  │
│    ├── Load private/functions/*                             │
│    └── Load public/*                                        │
├─────────────────────────────────────────────────────────────┤
│  Public Commands (public/)                                   │
│    ├── Get-*, Set-*, New-*, Remove-*                        │
│    ├── Copy-*, Backup-*, Restore-*                          │
│    └── Test-*, Connect-*, Invoke-*                          │
├─────────────────────────────────────────────────────────────┤
│  Private Functions (private/)                                │
│    ├── Flow Control (Stop-Function, Test-Bound)             │
│    ├── Configuration Management                              │
│    └── Helper Utilities                                      │
├─────────────────────────────────────────────────────────────┤
│  External Dependency                                         │
│    └── dbatools.library (SMO, .NET Libraries)               │
└─────────────────────────────────────────────────────────────┘
```

### 5.2 レイヤー構成

| レイヤー | 責務 | 代表的なファイル |
|---------|------|-----------------|
| マニフェスト | モジュール定義・依存関係 | `dbatools.psd1` |
| エントリーポイント | 初期化・読み込み | `dbatools.psm1` |
| 公開コマンド | ユーザー向け機能 | `public/Get-DbaDatabase.ps1` |
| 内部関数 | 共通処理・ヘルパー | `private/functions/Stop-Function.ps1` |
| 設定 | モジュール設定管理 | `private/configurations/` |
| 外部ライブラリ | SMO/ADO.NET | `dbatools.library` モジュール |

### 5.3 データフロー

```
[ユーザー入力]
    │
    ▼
[公開コマンド] (例: Get-DbaDatabase)
    │
    ├── [Connect-DbaInstance] ─── SQL Server接続
    │         │
    │         ▼
    │   [SMO Server Object]
    │
    ├── [内部関数呼び出し]
    │   ├── Test-Bound (パラメータチェック)
    │   ├── Stop-Function (エラー処理)
    │   └── Test-FunctionInterrupt (中断チェック)
    │
    └── [パイプライン出力]
          │
          ▼
    [PSCustomObject / SMO Object]
```

---

## 6. 主要コンポーネント

> このセクションでは、主要なコンポーネントとその連携を解説します。

### 6.1 エントリーポイント

```powershell
# ファイル: dbatools.psm1:1-35
#requires -Version 3.0
param(
    [Collections.IDictionary]
    [Alias('Options')]
    $Option = @{ }
)

$script:start = [DateTime]::Now

# パフォーマンス測定関数
function Write-ImportTime {
    param (
        [string]$Text,
        $Timestamp = ([DateTime]::now)
    )
    # インポート時間を記録
}
```

モジュール読み込み時に:
1. dbatools.library (SMO) を読み込み
2. private/functions/ の内部関数を読み込み
3. public/ の公開コマンドを読み込み
4. 設定とTEPP（タブ補完）を初期化

### 6.2 ビジネスロジック

公開コマンドが主要なビジネスロジックを含みます。

```powershell
# ファイル: public/Get-DbaDatabase.ps1:244-299
begin {
    # パラメータ検証
    if ($ExcludeUser -and $ExcludeSystem) {
        Stop-Function -Message "You cannot specify both ExcludeUser and ExcludeSystem." -Continue -EnableException $EnableException
    }
}
process {
    if (Test-FunctionInterrupt) { return }

    foreach ($instance in $SqlInstance) {
        try {
            $server = Connect-DbaInstance -SqlInstance $instance -SqlCredential $SqlCredential
        } catch {
            Stop-Function -Message "Failure" -Category ConnectionError -ErrorRecord $_ -Target $instance -Continue
        }

        # データベース情報の取得と出力
    }
}
```

### 6.3 データアクセス

SMO (SQL Server Management Objects) を介したデータアクセス:

```powershell
# SMO経由のデータベースアクセス
$server = Connect-DbaInstance -SqlInstance $instance
foreach ($db in $server.Databases) {
    [PSCustomObject]@{
        ComputerName = $server.ComputerName
        InstanceName = $server.ServiceName
        SqlInstance  = $server.DomainInstanceName
        Name         = $db.Name
        Status       = $db.Status
        RecoveryModel = $db.RecoveryModel
    }
}

# T-SQL経由のデータアクセス（DMV等）
$querylastused = "SELECT MAX(last_user_seek) ... FROM sys.dm_db_index_usage_stats"
$server.Query($querylastused)
```

### 6.4 ユーティリティ/共通機能

```powershell
# ファイル: private/functions/flowcontrol/Test-Bound.ps1
# パラメータバインドチェック
if (Test-Bound "Day") {
    # Day パラメータが指定された場合
}

# ファイル: private/functions/flowcontrol/Stop-Function.ps1
# エラー処理と関数終了
Stop-Function -Message "Error occurred" -EnableException $EnableException

# ファイル: bin/typealiases.ps1
# 型エイリアス定義
$TypeAliasTable = @{
    DbaInstance              = "Dataplat.Dbatools.Parameter.DbaInstanceParameter"
    DbaInstanceParameter     = "Dataplat.Dbatools.Parameter.DbaInstanceParameter"
    dbasize                  = "Dataplat.Dbatools.Utility.Size"
}
```

---

## 7. よく使われるパターン

> このセクションでは、コード内で頻出するパターンを解説します。

### パターン一覧

| パターン | 説明 | 出現頻度 | 代表的なファイル |
|---------|------|---------|-----------------|
| EnableException | エラーハンドリング切り替え | 高 | 全公開コマンド |
| スプラット（Splat） | 3+パラメータ時のハッシュテーブル | 高 | 全コード |
| パイプライン出力 | 即座にオブジェクト出力 | 高 | 全公開コマンド |
| Test-Bound | パラメータバインドチェック | 中 | 複合パラメータを持つコマンド |
| Stop-Function | gracefulな関数終了 | 高 | 全公開コマンド |

### 各パターンの詳細

#### パターン1: EnableException パターン

**目的:** ユーザーフレンドリーなエラー処理と高度なスクリプティングの両立

```powershell
# ファイル: public/Get-DbaDatabase.ps1:100-103, 239
param (
    [switch]$EnableException
)

# エラー発生時
Stop-Function -Message "Failure" -Category ConnectionError -ErrorRecord $_ -Target $instance -Continue -EnableException $EnableException
```

**解説:** デフォルトでは警告メッセージを表示して処理を継続。`-EnableException` 指定時は例外をスローし、try/catchでキャッチ可能。

#### パターン2: スプラット（Splat）パターン

**目的:** 可読性向上と行継続のバックティック回避

```powershell
# ファイル: CLAUDE.md - スプラットルール
# 1-2パラメータ: 直接指定
$database = Get-DbaDatabase -SqlInstance $instance -Name "master"

# 3+パラメータ: スプラット使用（必須）
$splatConnection = @{
    SqlInstance     = $instance
    SqlCredential   = $TestConfig.SqlCredential
    Database        = $dbName
    EnableException = $true
    Confirm         = $false
}
$result = New-DbaDatabase @splatConnection
```

**解説:** ハッシュテーブルの等号は垂直に揃える。変数名は `$splat<Purpose>` 形式。

#### パターン3: パイプライン出力パターン

**目的:** メモリ効率とストリーミング処理

```powershell
# 正しい例 - 即座に出力
foreach ($db in $server.Databases) {
    [PSCustomObject]@{
        ComputerName = $server.ComputerName
        Database     = $db.Name
    }
}

# 間違い - 結果をコレクションに蓄積
$results = New-Object System.Collections.ArrayList
foreach ($db in $server.Databases) {
    $results.Add([PSCustomObject]@{...})
}
$results  # 最後にまとめて出力
```

**解説:** パイプラインに即座に出力することで、大量データでもメモリ効率良く処理できる。

#### パターン4: Test-FunctionInterrupt パターン

**目的:** 関数の graceful な中断

```powershell
# ファイル: public/Get-DbaDatabase.ps1:252
process {
    if (Test-FunctionInterrupt) { return }

    foreach ($instance in $SqlInstance) {
        # 処理
    }
}
```

**解説:** `Stop-Function` で設定されたフラグをチェックし、必要に応じて処理を中断。

---

## 8. 業務フロー追跡の実践例

> このセクションでは、実際の業務フローをコードで追跡する方法を解説します。

### 8.1 フロー追跡の基本手順

1. エントリーポイントを特定（公開コマンド）
2. 処理の流れを追跡（Connect-DbaInstance -> SMO操作）
3. データの変換を確認（SMO -> PSCustomObject）
4. 最終的な出力を確認（パイプライン出力）

### 8.2 フロー追跡の実例

#### 例1: データベース一覧取得フロー (Get-DbaDatabase)

**概要:** SQL Serverインスタンスからデータベース情報を取得

**処理フロー:**
```
Get-DbaDatabase → Connect-DbaInstance → SMO.Server.Databases → PSCustomObject出力
```

**詳細な追跡:**

1. **パラメータ検証** (`public/Get-DbaDatabase.ps1:244-250`)
   ```powershell
   begin {
       if ($ExcludeUser -and $ExcludeSystem) {
           Stop-Function -Message "You cannot specify both ExcludeUser and ExcludeSystem." -Continue -EnableException $EnableException
       }
   }
   ```

2. **中断チェック** (`public/Get-DbaDatabase.ps1:252`)
   ```powershell
   process {
       if (Test-FunctionInterrupt) { return }
   ```

3. **SQL Server接続** (`public/Get-DbaDatabase.ps1:254-259`)
   ```powershell
   foreach ($instance in $SqlInstance) {
       try {
           $server = Connect-DbaInstance -SqlInstance $instance -SqlCredential $SqlCredential
       } catch {
           Stop-Function -Message "Failure" -Category ConnectionError -ErrorRecord $_ -Target $instance -Continue
       }
   ```

4. **データベース情報取得とフィルタリング** (SMO経由)
   ```powershell
   foreach ($db in $server.Databases) {
       # フィルタリング条件適用
       # パイプラインへ出力
   }
   ```

#### 例2: テスト実行フロー (Pester)

**概要:** コマンドのテスト実行

**処理フロー:**
```
Invoke-Pester → BeforeAll(セットアップ) → It(テスト実行) → AfterAll(クリーンアップ)
```

**詳細な追跡:**

1. **テストヘッダー** (`tests/Backup-DbaDatabase.Tests.ps1:1-6`)
   ```powershell
   #Requires -Module @{ ModuleName="Pester"; ModuleVersion="5.0" }
   param(
       $ModuleName  = "dbatools",
       $CommandName = "Backup-DbaDatabase",
       $PSDefaultParameterValues = $TestConfig.Defaults
   )
   ```

2. **セットアップ** (`tests/Backup-DbaDatabase.Tests.ps1:56-69`)
   ```powershell
   BeforeAll {
       $PSDefaultParameterValues["*-Dba*:EnableException"] = $true
       $DestBackupDir = "$($TestConfig.Temp)\$CommandName-$(Get-Random)"
       $null = New-Item -Type Container -Path $DestBackupDir
       $PSDefaultParameterValues.Remove("*-Dba*:EnableException")
   }
   ```

3. **テスト実行** (`tests/Backup-DbaDatabase.Tests.ps1:82-94`)
   ```powershell
   Context "Properly backups all databases" {
       BeforeAll {
           $results = Backup-DbaDatabase -SqlInstance $TestConfig.InstanceCopy1
       }

       It "Should return a database name, specifically master" {
           $results.DatabaseName | Should -Contain "master"
       }
   }
   ```

### 8.3 フロー追跡チェックリスト

- [ ] エントリーポイント（public/のコマンド）を特定したか
- [ ] Connect-DbaInstance の呼び出しを確認したか
- [ ] SMOオブジェクトの操作を把握したか
- [ ] Stop-Function / Test-FunctionInterrupt のエラーハンドリングを確認したか
- [ ] パイプライン出力形式を確認したか

---

## 9. 設計書の参照順序

> このセクションでは、プロジェクト理解のための設計書参照順序を案内します。

### 9.1 目的別ロードマップ

#### 全体像を把握したい場合
1. `readme.md` - プロジェクト概要
2. `CLAUDE.md` - スタイルガイドと規約
3. `CONTRIBUTING.md` - プロジェクト構造と貢献方法

#### 特定機能を理解したい場合
1. `public/<command>.ps1` - コマンドのソースコード
2. コマンド内の `.SYNOPSIS`, `.DESCRIPTION` - 機能説明
3. `tests/<command>.Tests.ps1` - テストケースから使用例を把握

#### 改修作業を行う場合
1. `CLAUDE.md` - スタイルガイド（必須）
2. `tests/CLAUDE.md` - テストスタイルガイド
3. `.github/prompts/` - 追加のガイドライン

### 9.2 ドキュメント一覧

| ドキュメント | 概要 | 参照タイミング |
|-------------|------|---------------|
| `readme.md` | プロジェクト概要、使用方法 | 初回参照 |
| `CLAUDE.md` | PowerShellスタイルガイド | コード作成時 |
| `CONTRIBUTING.md` | 貢献ガイド、プロジェクト構造 | 開発参加時 |
| `tests/CLAUDE.md` | Pesterテストガイド | テスト作成時 |
| `.github/prompts/style.md` | テストスタイル詳細 | テスト作成時 |

---

## 10. トラブルシューティング

> このセクションでは、コードリーディング時によくある問題と解決法を解説します。

### よくある疑問と回答

#### Q: `Stop-Function` と `return` の違いは？
A: `Stop-Function` はエラーメッセージを出力し、`-EnableException` に応じて警告または例外をスロー。その後 `return` で関数を終了する必要があります。`Test-FunctionInterrupt` と組み合わせて使用。

#### Q: `$PSItem` と `$_` の違いは？
A: 同じものです。dbatoolsでは可読性のため `$PSItem` を推奨。

#### Q: スプラット変数はなぜ必要？
A: バックティック（`）による行継続はdbatoolsで禁止。3つ以上のパラメータ時はスプラット必須。

#### Q: テストの `$TestConfig` はどこで定義？
A: `private/testing/Get-TestConfig.ps1` で定義。テスト環境のSQL Serverインスタンス情報を保持。

### デバッグのヒント

1. **詳細ログの有効化:**
   ```powershell
   Import-Module dbatools -Option Debug
   ```

2. **モジュール読み込み時間の確認:**
   ```powershell
   $script:dbatools_ImportPerformance
   ```

3. **テストのローカル実行:**
   ```powershell
   Import-Module .\dbatools.psm1
   $TestConfig = Get-TestConfig
   Invoke-Pester -Path tests\Get-DbaDatabase.Tests.ps1
   ```

---

## 付録

### A. 用語集

| 用語 | 説明 |
|-----|------|
| SMO | SQL Server Management Objects - SQL Server管理用の.NETライブラリ |
| DAC | Dedicated Admin Connection - SQL Serverの専用管理者接続 |
| TDE | Transparent Data Encryption - データベース暗号化機能 |
| DMV | Dynamic Management Views - SQL Serverの動的管理ビュー |
| TEPP | Tab Expansion Plus Plus - タブ補完機能 |
| Pester | PowerShellのテストフレームワーク |
| OTBS | One True Brace Style - ブレース配置スタイル |
| Splat | ハッシュテーブルをパラメータとして展開する技法 |

### B. ファイル一覧

| ファイル/ディレクトリ | 説明 | 主な内容 |
|---------------------|------|---------|
| `dbatools.psd1` | モジュールマニフェスト | バージョン、依存関係、エクスポート関数 |
| `dbatools.psm1` | モジュールエントリーポイント | 初期化、関数読み込み |
| `public/` | 公開コマンド | 約700のPowerShellコマンド |
| `private/` | 内部関数 | ヘルパー、設定、フロー制御 |
| `tests/` | Pesterテスト | 各コマンドのテストファイル |
| `bin/` | リソースファイル | 型エイリアス、テンプレート |

### C. 参考資料

- [dbatools公式ドキュメント](https://docs.dbatools.io)
- [dbatools GitHub](https://github.com/dataplat/dbatools)
- [PowerShell公式ドキュメント](https://docs.microsoft.com/en-us/powershell/)
- [Pester公式ドキュメント](https://pester.dev)
- [SMO (SQL Server Management Objects)](https://docs.microsoft.com/en-us/sql/relational-databases/server-management-objects-smo/)
