# 画面設計書 97-インスタンストリガー

## 概要

本ドキュメントはdbatools PowerShellモジュールにおけるインスタンストリガー機能（Get-DbaInstanceTrigger、Copy-DbaInstanceTrigger）の画面設計書です。

### 本画面の処理概要

**業務上の目的・背景**：
SQL Serverのサーバーレベルトリガーは、インスタンス全体でのCREATE、ALTER、DROPなどのDDL文やログオンイベントに対して自動的に応答する重要なセキュリティ・監査機能です。本機能群は、サーバーレベルのDDLトリガーの取得と、インスタンス間のコピーを提供します。これにより、セキュリティ監査、変更追跡、不正なスキーマ変更の防止機能の確認・移行が効率的に行えます。

**画面へのアクセス方法**：
PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Get-DbaInstanceTrigger -SqlInstance <インスタンス名>`
- `Copy-DbaInstanceTrigger -Source <ソース> -Destination <宛先>`

**主要な操作・処理内容**：
1. **トリガー取得**：サーバーレベルのDDLトリガー情報（名前、DDLイベント、有効状態、実装タイプ等）を取得
2. **トリガーコピー**：ソースインスタンスから宛先インスタンスへトリガーをコピー
3. **トリガー削除・再作成**：-Force指定時に既存トリガーを削除して再作成

**画面遷移**：
本機能はセキュリティ監査やサーバー移行の起点として使用される。取得したトリガー情報はドキュメント化、比較分析、設定エクスポートなどに活用される。

**権限による表示制御**：
- トリガー情報の取得にはSQL Serverインスタンスへの接続権限が必要
- トリガーの作成・削除にはsysadmin権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 679 | Get-DbaInstanceTrigger | 主機能 | インスタンストリガーの取得 |
| 675 | Copy-DbaInstanceTrigger | 補助機能 | インスタンストリガーのコピー |

## 画面種別

CLI（コマンドラインインターフェース）/ セキュリティ・監査

## URL/ルーティング

PowerShellコマンド:
- `Get-DbaInstanceTrigger`
- `Copy-DbaInstanceTrigger`

## 入出力項目

### Get-DbaInstanceTrigger パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | はい | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | SQL Server接続用の資格情報 |
| EnableException | switch | いいえ | 例外を有効化 |

### Copy-DbaInstanceTrigger パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Source | DbaInstanceParameter | はい | コピー元のSQL Serverインスタンス |
| SourceSqlCredential | PSCredential | いいえ | ソース接続用の資格情報 |
| Destination | DbaInstanceParameter[] | はい | コピー先のSQL Serverインスタンス |
| DestinationSqlCredential | PSCredential | いいえ | 宛先接続用の資格情報 |
| ServerTrigger | object[] | いいえ | コピーするトリガー名 |
| ExcludeServerTrigger | object[] | いいえ | 除外するトリガー名 |
| Force | switch | いいえ | 既存トリガーの上書き |
| WhatIf | switch | いいえ | 実行内容のプレビュー |
| Confirm | switch | いいえ | 確認プロンプト |
| EnableException | switch | いいえ | 例外を有効化 |

## 表示項目

### Get-DbaInstanceTrigger 出力（Microsoft.SqlServer.Management.Smo.Trigger）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| ID | int | トリガーの一意識別子 |
| Name | string | トリガー名 |
| AnsiNullsStatus | bool | ANSI NULLS設定（ON/OFF） |
| AssemblyName | string | CLRアセンブリ名（CLRトリガーの場合） |
| BodyStartIndex | int | トリガー本体の開始文字位置 |
| ClassName | string | CLRクラス名（CLRトリガーの場合） |
| CreateDate | DateTime | 作成日時 |
| DateLastModified | DateTime | 最終更新日時 |
| DdlTriggerEvents | enum | トリガーを起動するDDLイベント（CREATE, ALTER, DROP等） |
| ExecutionContext | enum | 実行セキュリティコンテキスト（Caller/Owner/特定プリンシパル） |
| ExecutionContextLogin | string | トリガーを実行するプリンシパル |
| ImplementationType | enum | 実装タイプ（T-SQL/CLR） |
| IsDesignMode | bool | デザインモードかどうか |
| IsEnabled | bool | トリガーが有効かどうか |
| IsEncrypted | bool | トリガー本体が暗号化されているか |
| IsSystemObject | bool | システムオブジェクトかどうか |
| MethodName | string | CLRメソッド名（CLRトリガーの場合） |
| QuotedIdentifierStatus | bool | QUOTED_IDENTIFIER設定 |
| State | enum | SMOオブジェクトの状態 |
| TextHeader | string | トリガー定義のヘッダーテキスト |
| TextMode | bool | テキストモード設定 |

### Copy-DbaInstanceTrigger 出力

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| SourceServer | string | ソースSQL Serverインスタンス名 |
| DestinationServer | string | 宛先SQL Serverインスタンス名 |
| Name | string | コピーされたトリガー名 |
| Type | string | オブジェクトタイプ（常に "Server Trigger"） |
| Status | string | 結果ステータス（Successful/Skipped/Failed） |
| Notes | string | 追加情報（スキップ理由、エラー詳細等） |
| DateTime | DbaDateTime | コピー操作の実行日時 |

## イベント仕様

### 1-トリガー取得処理（Get-DbaInstanceTrigger）

1. Connect-DbaInstanceでSQL Server接続
2. $server.Triggersからサーバートリガーコレクションを取得
3. 各トリガーにメタ情報（ComputerName, InstanceName, SqlInstance）を追加
4. Select-DefaultViewでデフォルト表示プロパティを設定して出力

### 2-トリガーコピー処理（Copy-DbaInstanceTrigger）

1. ソースインスタンスに接続（MinimumVersion 9 = SQL Server 2005以降）
2. ソースの$sourceServer.Triggersからトリガーコレクションを取得
3. 各宛先インスタンスに対して：
   - バージョン互換性チェック（宛先がソースより低いバージョンは不可）
   - 宛先に同名のトリガーが存在するかチェック
   - 存在する場合：-Force指定なしでスキップ、-Force指定で削除後再作成
   - Script()メソッドでT-SQLを生成
   - CREATE文とENABLE TRIGGER文の前にGOを挿入
   - 分割して実行

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

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

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| トリガー取得 | sys.server_triggers | SELECT | トリガー定義の読み取り |
| トリガーコピー（作成） | sys.server_triggers | INSERT | トリガーの作成 |
| トリガーコピー（削除） | sys.server_triggers | DELETE | 既存トリガーの削除（Force時） |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 |
|-------------|------|---------------|
| MSG001 | エラー | Failure（接続エラー時） |
| MSG002 | エラー | Migration from version {destVersion} to version {sourceVersion} is not supported. |
| MSG003 | 情報 | Server trigger {triggerName} exists at destination. Use -Force to drop and migrate. |
| MSG004 | 情報 | Dropping server trigger {triggerName} |
| MSG005 | エラー | Issue dropping trigger {triggerName} on {destinstance} |
| MSG006 | 情報 | Copying server trigger {triggerName} |
| MSG007 | エラー | Issue creating trigger {triggerName} on {destinstance} |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Functionでエラー出力し、処理を継続（Continue） |
| バージョン非互換 | Stop-Functionでエラー出力、処理終了 |
| トリガー削除失敗 | Status = "Failed"として出力し、処理を継続 |
| トリガー作成失敗 | Status = "Failed"、Notesにエラー詳細を出力 |

## 備考

- SQL Server 2005以降が必要（MinimumVersion 9）
- CLRトリガーの場合はAssemblyName、ClassName、MethodNameが設定される
- バージョン互換性チェックにより、高いバージョンから低いバージョンへの移行は不可
- Script()メソッドで生成されたT-SQLはCREATE文とENABLE TRIGGER文に分割して実行される

---

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

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

### 推奨読解順序

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

SMOトリガーオブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaInstanceTrigger.ps1 | `public/Get-DbaInstanceTrigger.ps1` | 35-66行目の.OUTPUTSセクション |

**読解のコツ**: T-SQLトリガーとCLRトリガーの違い（ImplementationType, AssemblyName等）を理解する。

#### Step 2: トリガー取得ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaInstanceTrigger.ps1 | `public/Get-DbaInstanceTrigger.ps1` | 75-80行目のparamブロック |
| 2-2 | Get-DbaInstanceTrigger.ps1 | `public/Get-DbaInstanceTrigger.ps1` | 82-101行目のprocessブロック |

**主要処理フロー**:
- **85行目**: Connect-DbaInstanceでSQL Server接続
- **90行目**: $server.Triggersでトリガーコレクション取得
- **92-94行目**: Add-Memberでメタ情報追加
- **95行目**: Select-DefaultViewで出力

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaInstanceTrigger.ps1 | `public/Copy-DbaInstanceTrigger.ps1` | 111-123行目のbeginブロック |
| 3-2 | Copy-DbaInstanceTrigger.ps1 | `public/Copy-DbaInstanceTrigger.ps1` | 132-135行目のバージョンチェック |
| 3-3 | Copy-DbaInstanceTrigger.ps1 | `public/Copy-DbaInstanceTrigger.ps1` | 155-178行目の既存トリガーチェックと削除 |
| 3-4 | Copy-DbaInstanceTrigger.ps1 | `public/Copy-DbaInstanceTrigger.ps1` | 180-199行目のトリガー作成 |

**主要処理フロー**:
- **113行目**: MinimumVersion 9でソース接続
- **118行目**: $sourceServer.Triggersでトリガーコレクション取得
- **132-135行目**: 宛先バージョン < ソースバージョンならエラー
- **183-185行目**: Script()でT-SQL生成、GO挿入
- **187-189行目**: クエリを分割して実行

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

```
Get-DbaInstanceTrigger
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    └─ $server.Triggers
           ├─ foreach ($trigger in $server.Triggers)
           │      ├─ Add-Member（ComputerName, InstanceName, SqlInstance）
           │      └─ Select-DefaultView（出力）
           └─ Stop-Function（エラー時）

Copy-DbaInstanceTrigger
    │
    ├─ Connect-DbaInstance (Source, MinimumVersion 9)
    │      └─ ソース接続確立
    │
    └─ foreach ($destinstance in $Destination)
           │
           ├─ Connect-DbaInstance (Destination, MinimumVersion 9)
           │      └─ 宛先接続確立
           │
           ├─ バージョン互換性チェック
           │      └─ 宛先 < ソースならStop-Function
           │
           ├─ 既存トリガーチェック
           │      ├─ Force時：$destServer.Triggers[name].Drop()
           │      └─ 非Force時：スキップ
           │
           └─ トリガー作成
                  ├─ $trigger.Script()
                  ├─ CREATE/ENABLE TRIGGERの前にGO挿入
                  └─ $destServer.Query()で実行
```

### データフロー図

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

SqlInstance ─────────────▶ Connect-DbaInstance
                                  │
                          ┌───────▼───────┐
                          │ $server.      │
                          │  Triggers     │
                          └───────────────┘
                                  │
                          ┌───────▼───────┐
                          │ Add-Member    │
                          │ (メタ情報追加) │
                          └───────────────┘
                                  │
                          ┌───────▼───────┐
                          │Select-Default │
                          │     View      │
                          └───────────────┘
                                  │
                                  ▼
                      [Microsoft.SqlServer.Management.Smo.Trigger]

--- Copy処理 ---

Source ──────────────────▶ Connect-DbaInstance
                                  │
                          ┌───────▼───────┐
                          │ $sourceServer.│
                          │  Triggers     │
                          └───────────────┘
                                  │
Destination ─────────────▶ Connect-DbaInstance
                                  │
                          ┌───────▼───────┐
                          │バージョン     │
                          │ チェック      │
                          └───────────────┘
                                  │
                          ┌───────▼───────┐
                          │既存トリガー   │
                          │ チェック      │
                          └───────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────┐
        ▼                         ▼                         ▼
   存在 & Force             存在 & !Force              存在しない
        │                         │                         │
   Drop()実行                 スキップ                      │
        │                         │                         │
        └─────────────────────────┴─────────────────────────┘
                                  │
                          ┌───────▼───────┐
                          │ Script()      │
                          │ + GO挿入      │
                          │ + Query()実行 │
                          └───────────────┘
                                  │
                                  ▼
                          [MigrationObject]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaInstanceTrigger.ps1 | `public/Get-DbaInstanceTrigger.ps1` | ソース | インスタンストリガー取得 |
| Copy-DbaInstanceTrigger.ps1 | `public/Copy-DbaInstanceTrigger.ps1` | ソース | インスタンストリガーコピー |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立 |
