# 機能設計書 249-Test-DbaManagementObject

## 概要

本ドキュメントは、特定のSQL Server Management Objects（SMO）ライブラリバージョンがターゲットコンピュータにインストールされているかを検証する機能 `Test-DbaManagementObject` の設計仕様を記載する。

### 本機能の処理概要

この機能は、指定されたバージョンのMicrosoft.SqlServer.SmoアセンブリがGlobal Assembly Cache（GAC）に存在するかをチェックする。DBAsが特定のSQL Serverクライアントツールバージョンに依存するスクリプトを実行する前に、必要なSMOライブラリが利用可能であることを確認するのに役立つ。

**業務上の目的・背景**：SMO依存の自動化スクリプトが、クライアントライブラリが欠落または互換性のないシステムに対して実行される際のランタイムエラーを防止する。複数サーバー環境でのSMOライブラリの一貫性を確保し、スクリプト実行の信頼性を向上させる。

**機能の利用シーン**：
- スクリプト実行前のSMOライブラリ存在確認
- 複数サーバーでのクライアントツールバージョン監査
- SQL Server Management Toolsのインストール状態確認
- 自動化スクリプトの前提条件チェック

**主要な処理内容**：
1. 指定されたコンピュータに対してリモート接続
2. GAC（Global Assembly Cache）内のSMOアセンブリを検索
3. 指定されたバージョン番号のアセンブリ存在確認
4. 存在/不存在の結果を出力

**関連システム・外部連携**：Windows GAC（グローバルアセンブリキャッシュ）、Invoke-Command2によるリモート実行。

**権限による制御**：リモートコンピュータへのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面機能マッピングに該当なし |

## 機能種別

診断処理 / インベントリ処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstance[] | No | チェック対象のコンピュータ | デフォルトはローカル |
| Credential | PSCredential | No | リモート接続用資格情報 | - |
| VersionNumber | int[] | Yes | チェックするSMOバージョン番号 | 配列で複数指定可 |
| EnableException | switch | No | 例外のスロー有効化 | - |

### 入力データソース

- PowerShellコマンドライン引数
- パイプライン入力（ComputerName）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SMOアセンブリチェックを実行したコンピュータ名 |
| Version | int | チェックされたSQL Server SMOアセンブリのメジャーバージョン番号 |
| Exists | bool | 指定されたSMOアセンブリバージョンがGACにインストールされているか |

### 出力先

- PowerShellパイプライン出力（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. beginブロックでスクリプトブロック定義
   └─ GAC内のSMOアセンブリ検索ロジック
2. processブロックで各コンピュータ処理
   └─ Invoke-Command2でリモート実行
   └─ 結果の返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[スクリプトブロック定義]
    B --> C{各ComputerNameをループ}
    C --> D[Invoke-Command2]
    D --> E{各VersionNumberをループ}
    E --> F[GAC_MSIL検索]
    F --> G{見つかった?}
    G -->|No| H[GAC_MSIL .NET検索]
    G -->|Yes| I[Exists = true]
    H --> J{見つかった?}
    J -->|No| K[Exists = false]
    J -->|Yes| L[Exists = true]
    I --> M[結果出力]
    K --> M
    L --> M
    M --> E
    E -->|完了| C
    C -->|完了| N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-249-1 | GACパス検索 | 2つのGACパスを順次検索（レガシー、.NET） | 常時 |
| BR-249-2 | バージョン番号マッチ | VersionNumberを含むディレクトリを検索 | 常時 |
| BR-249-3 | デフォルトコンピュータ | ComputerName未指定時はローカルコンピュータ | パラメータなしの場合 |

### バージョン番号と SQL Server バージョンの対応

| バージョン番号 | SQL Server バージョン |
|---------------|---------------------|
| 11 | SQL Server 2012 |
| 12 | SQL Server 2014 |
| 13 | SQL Server 2016 |
| 14 | SQL Server 2017 |
| 15 | SQL Server 2019 |
| 16 | SQL Server 2022 |

### GACパス検索順序

1. `$env:SystemRoot\assembly\GAC_MSIL\Microsoft.SqlServer.Smo`
2. `$env:SystemRoot\Microsoft.NET\assembly\GAC_MSIL\Microsoft.SqlServer.Smo`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| RemoteError | リモートエラー | リモートコンピュータへの接続失敗 | Stop-Functionで処理継続 |

### リトライ仕様

リトライ処理なし。各コンピュータに対してContinueでループを継続。

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

ファイルシステム操作のみのため、トランザクション管理は不要。

## パフォーマンス要件

- Get-ChildItemを使用したディレクトリ検索
- リモート実行のため、ネットワーク遅延の影響を受ける

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

- Windows資格情報を使用したリモート接続
- 管理者権限が必要な場合がある
- CredentialパラメータでWindows認証をサポート

## 備考

- SilentlyContinueエラーアクションでGAC検索の失敗を抑制
- 複数のVersionNumberを配列で指定可能

---

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

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

### 推奨読解順序

#### Step 1: コマンド構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaManagementObject.ps1 | `public/Test-DbaManagementObject.ps1` | パラメータ定義、コメントベースヘルプ |

**読解のコツ**: スクリプトブロックによるリモート実行パターンに注目。

#### Step 2: beginブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaManagementObject.ps1 | `public/Test-DbaManagementObject.ps1` | スクリプトブロックの定義 |

**主要処理フロー**:
1. **63-84行目**: スクリプトブロック定義
2. **64-68行目**: レガシーGACパス検索
3. **66-68行目**: .NET GACパス検索（フォールバック）
4. **70-82行目**: 結果オブジェクト生成

#### Step 3: processブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaManagementObject.ps1 | `public/Test-DbaManagementObject.ps1` | リモート実行処理 |

**主要処理フロー**:
1. **87-93行目**: 各コンピュータに対するInvoke-Command2呼び出し

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

```
Test-DbaManagementObject
    │
    ├─ Invoke-Command2
    │      └─ リモートスクリプトブロック実行
    │
    ├─ Get-ChildItem
    │      ├─ GAC_MSIL（レガシー）検索
    │      └─ GAC_MSIL（.NET）検索
    │
    └─ PSCustomObject出力
           └─ 存在確認結果
```

### データフロー図

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

ComputerName   ───▶ Invoke-Command2 ───▶ リモート実行
                           │
VersionNumber  ───▶ スクリプトブロック ───▶ GAC検索
                           │
                           ▼
                    Get-ChildItem ───▶ アセンブリリスト
                           │
                           ▼
                    存在確認 ───▶ PSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaManagementObject.ps1 | `public/Test-DbaManagementObject.ps1` | ソース | メイン機能実装 |
| Invoke-Command2.ps1 | `private/Invoke-Command2.ps1` | ソース | リモートコマンド実行 |
| Get-DbaManagementObject.ps1 | `public/Get-DbaManagementObject.ps1` | ソース | SMOオブジェクト取得（関連） |
