# 機能設計書 91-Get-DbaAvailableCollation

## 概要

本ドキュメントは、SQL Serverインスタンスから使用可能な照合順序（Collation）一覧を取得するGet-DbaAvailableCollationコマンドの機能設計書である。

### 本機能の処理概要

Get-DbaAvailableCollationは、SQL Serverインスタンスでサポートされているすべての照合順序を取得し、詳細なロケールおよびコードページ情報を含む形式で返却する機能である。

**業務上の目的・背景**：データベースを新規作成する際や、照合順序の変更が必要な場合、または異なる照合順序を持つ環境間でのマイグレーション計画時に、利用可能な照合順序の一覧と詳細情報が必要となる。本機能はDBAが照合順序の選択を情報に基づいて判断できるよう、コードページ名やロケール名などの人間が読みやすい情報を付加して提供する。

**機能の利用シーン**：新規データベースの作成前に適切な照合順序を選択する場合、既存データベースの照合順序を他のインスタンスと比較する場合、マイグレーション時に照合順序の互換性を確認する場合、および複数言語対応のデータベース設計時にロケール情報を確認する場合に利用される。

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続を確立
2. SMOのEnumCollations()メソッドを使用して利用可能な照合順序を列挙
3. 各照合順序に対してコードページ名とロケール名の詳細情報を付加
4. コンピュータ名、インスタンス名、SQL Serverインスタンス名などのメタデータを追加
5. 結果をパイプラインに出力

**関連システム・外部連携**：SQL Server SMO (Server Management Objects)を使用してインスタンスから情報を取得する。内部でGet-LanguageおよびGet-CodePage関数を使用してロケールおよびコードページの詳細情報を取得する。

**権限による制御**：SQL Serverへの接続権限（CONNECT権限）のみが必要である。VIEW SERVER STATE等の追加権限は不要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドラインインターフェース | 主画面 | PowerShellコンソールまたはスクリプトから実行 |

## 機能種別

データ取得（SELECT相当の読み取り専用操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス | パイプライン入力可能、複数指定可能 |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows認証、SQL認証、AD認証をサポート |
| EnableException | Switch | No | 例外処理を有効化し、try/catchで捕捉可能にする | - |

### 入力データソース

SQL Serverインスタンスに接続し、SMOのEnumCollations()メソッドを通じてシステムメタデータからデータを取得する。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverホストのコンピュータ名 |
| InstanceName | String | SQL Serverサービス名 |
| SqlInstance | String | 完全なSQL Serverインスタンス名 |
| Name | String | 照合順序名（例：SQL_Latin1_General_CP1_CI_AS） |
| CodePage | Int32 | コードページ識別子（例：1252） |
| CodePageName | String | コードページのエンコーディング名（例：iso-8859-1） |
| LocaleID | Int32 | ロケール識別子（LCID） |
| LocaleName | String | ロケール/言語名（例：English_United States） |
| Description | String | SQL Serverの照合順序説明 |

### 出力先

PowerShellパイプラインに直接出力される（コンソール表示、変数への格納、他のコマンドへのパイプ等）

## 処理フロー

### 処理シーケンス

```
1. Begin処理：キャッシュ用ハッシュテーブルの初期化
   └─ ロケールおよびコードページのキャッシュ用変数を初期化
2. Process処理：各SqlInstanceに対してループ処理
   └─ Connect-DbaInstanceでSQL Serverに接続
3. EnumCollations()で照合順序を列挙
   └─ SMOを使用してインスタンスの照合順序一覧を取得
4. 各照合順序に対してメタデータを付加
   └─ コードページ名、ロケール名を取得してプロパティとして追加
5. Select-DefaultViewで結果を整形して出力
   └─ 既定のプロパティのみ表示
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[キャッシュ初期化]
    B --> C{各SqlInstanceをループ}
    C --> D[Connect-DbaInstance]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function でエラー]
    F --> C
    E -->|Yes| G[EnumCollations 実行]
    G --> H{各Collationをループ}
    H --> I[コードページ名取得]
    I --> J[ロケール名取得]
    J --> K[NotePropertyとして追加]
    K --> H
    H -->|完了| L[Select-DefaultView で出力]
    L --> C
    C -->|完了| M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-91-1 | 接続権限チェック | CONNECT権限のみでデータ取得可能 | すべての実行時 |
| BR-91-2 | キャッシュによるパフォーマンス最適化 | 同一のコードページ/ロケールIDは再取得せずキャッシュを使用 | 重複するID検出時 |
| BR-91-3 | 特殊ロケール対応 | Japanese_Unicode等のWindowsで非サポートのロケールは事前定義 | LocaleID=66577の場合 |

### 計算ロジック

キャッシュ機構により、重複するコードページIDおよびロケールIDに対する名前解決を最適化（テストで約9倍の高速化を実現）。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 照合順序取得 | システムメタデータ | SELECT | SMO EnumCollations()経由でシステム情報を取得 |

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

本機能はSMO経由でSQL Serverのシステムメタデータにアクセスするのみであり、直接的なテーブル操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Functionでエラーを記録し、次のインスタンスに継続 |
| - | ロケール取得エラー | Get-Language失敗 | $nullを返却してキャッシュに登録 |
| - | コードページ取得エラー | Get-CodePage失敗 | $nullを返却してキャッシュに登録 |

### リトライ仕様

リトライ機構は実装されていない。接続エラー時は次のインスタンスに継続する。

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

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

## パフォーマンス要件

キャッシュ機構により、多数の照合順序取得時のパフォーマンスを最適化（約9倍の高速化）。

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

- SQL Serverへの最小権限（CONNECT権限のみ）で動作
- SqlCredentialによる代替認証情報の使用をサポート
- Windows認証、SQL認証、Active Directory認証をサポート

## 備考

- SQL Server 2000以降のすべてのバージョンをサポート
- パイプライン入力および複数インスタンスの一括処理が可能

---

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

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

### 推奨読解順序

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

出力されるオブジェクトはSMOのCollationオブジェクトに追加プロパティを付与したものである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAvailableCollation.ps1 | `public/Get-DbaAvailableCollation.ps1` | 127-132行目のAdd-Memberで追加されるプロパティを確認 |

**読解のコツ**: Add-Memberコマンドで動的にプロパティが追加される点に注目。-Forceは既存プロパティを上書きする。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAvailableCollation.ps1 | `public/Get-DbaAvailableCollation.ps1` | 関数全体の構造（begin/process/end） |

**主要処理フロー**:
1. **79-116行目**: begin ブロック - キャッシュ用のハッシュテーブルと内部関数を定義
2. **118-137行目**: process ブロック - 各SqlInstanceに対する処理
3. **119-124行目**: Connect-DbaInstanceでSQL Serverに接続
4. **126行目**: EnumCollations()で照合順序一覧を取得
5. **127-133行目**: 各照合順序にメタデータを付加

#### Step 3: 内部関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAvailableCollation.ps1 | `public/Get-DbaAvailableCollation.ps1` | 89-101行目のGet-LocaleDescription関数 |
| 3-2 | Get-DbaAvailableCollation.ps1 | `public/Get-DbaAvailableCollation.ps1` | 103-115行目のGet-CodePageDescription関数 |

**主要処理フロー**:
- **89-101行目**: Get-LocaleDescription - ロケールIDから表示名を取得してキャッシュ
- **103-115行目**: Get-CodePageDescription - コードページIDからエンコーディング名を取得してキャッシュ

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

```
Get-DbaAvailableCollation
    │
    ├─ Connect-DbaInstance (接続確立)
    │      └─ SQL Server SMO接続
    │
    ├─ $server.EnumCollations() (照合順序列挙)
    │
    ├─ Get-CodePageDescription (内部関数)
    │      └─ Get-CodePage (dbatools内部関数)
    │
    └─ Get-LocaleDescription (内部関数)
           └─ Get-Language (dbatools内部関数)
```

### データフロー図

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

SqlInstance    ───▶ Connect-DbaInstance  ───▶ SMO Server オブジェクト
                           │
                           ▼
                    EnumCollations()
                           │
                           ▼
                    メタデータ付加
                    (Add-Member)
                           │
                           ▼
              Select-DefaultView ───▶ Collation オブジェクト配列
                                      (追加プロパティ付き)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAvailableCollation.ps1 | `public/Get-DbaAvailableCollation.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続機能 |
| Get-Language.ps1 | `private/functions/Get-Language.ps1` | ソース | ロケール名取得 |
| Get-CodePage.ps1 | `private/functions/Get-CodePage.ps1` | ソース | コードページ名取得 |
