# 画面設計書 242-照合順序取得

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Get-DbaAvailableCollation` コマンドに関する画面設計書です。SQL Serverインスタンスで利用可能な照合順序（Collation）の一覧を取得する機能を提供します。

### 本画面の処理概要

`Get-DbaAvailableCollation` コマンドは、SQL Serverインスタンスがサポートするすべての照合順序を、関連するコードページとロケール情報とともに取得する機能を提供します。

**業務上の目的・背景**：データベース設計において照合順序の選択は、文字列の比較・ソート動作、大文字小文字/アクセント記号の区別、多言語対応などに直接影響します。新規データベース作成時、照合順序変更の検討時、マイグレーション計画時に、利用可能な選択肢を把握することは重要です。本コマンドは、人間が読みやすいコードページ名とロケール名を付加した情報を提供し、DBAが適切な照合順序を選択できるよう支援します。

**画面へのアクセス方法**：PowerShellコンソールまたはPowerShell ISEから `Get-DbaAvailableCollation` コマンドを直接実行します。SqlInstanceパラメータでターゲットを指定します。

**主要な操作・処理内容**：
1. SQL Serverインスタンスへの接続
2. SMO（Server Management Objects）経由で `EnumCollations()` メソッド実行
3. 各照合順序にコードページ名とロケール名の付加
4. 結果のオブジェクト出力（Select-DefaultViewで表示プロパティ選択）

**画面遷移**：CLIコマンドのため画面遷移はありません。出力を他のコマンドにパイプラインで渡すことが可能です。

**権限による表示制御**：SQL Serverへの接続権限（CONNECT権限）のみが必要です。特別な権限は不要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 91 | Get-DbaAvailableCollation | 主機能 | 利用可能照合順序の取得 |
| - | Connect-DbaInstance | 補助機能 | SQL Serverインスタンスへの接続 |
| - | Get-Language | 補助機能 | ロケールIDから表示名取得 |
| - | Get-CodePage | 補助機能 | コードページIDから表示名取得 |

## 画面種別

CLI（コマンドラインインターフェース）/ 一覧取得系

## URL/ルーティング

PowerShellコマンド: `Get-DbaAvailableCollation`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | パイプライン | 説明 |
|-------------|----|----|-------------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | No | SQL Server認証用の資格情報 |
| EnableException | switch | No | No | 例外を詳細表示するフラグ |

## 表示項目

### 出力オブジェクト（Microsoft.SqlServer.Management.Smo.Collation + 拡張プロパティ）

#### デフォルト表示項目

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

#### 追加プロパティ（Select-Object * で取得可能）

| 項目名 | 型 | 説明 |
|--------|----|----|
| BinaryOrder | bool | バイナリソート順序を使用するか |
| BuiltInComparisonStyle | int | 比較スタイル定数 |
| IsCodePageCompatible | bool | コードページ互換性 |
| IsCaseSensitive | bool | 大文字小文字を区別するか |
| IsAccentSensitive | bool | アクセント記号を区別するか |
| IsKanaTypeSensitive | bool | ひらがな/カタカナを区別するか |
| IsWidthSensitive | bool | 全角/半角を区別するか |

## イベント仕様

### 1-コマンド実行

コマンド実行時の処理フロー:

1. **接続処理**: `Connect-DbaInstance` でSQL Serverに接続
2. **照合順序列挙**: `$server.EnumCollations()` でSMO経由で全照合順序取得
3. **情報付加**: 各照合順序オブジェクトにComputerName, InstanceName, SqlInstance, CodePageName, LocaleNameを追加
4. **キャッシュ利用**: コードページ名とロケール名はハッシュテーブルでキャッシュし、重複照合順序の処理を高速化
5. **結果出力**: Select-DefaultViewで指定プロパティを表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| コマンド実行 | - | SELECT | データベースへの書き込みなし（読み取り専用） |

### テーブル別更新項目詳細

本コマンドはデータベースへの更新を行いません。SMOを介してSQL Serverのメタデータを取得するのみです。

## メッセージ仕様

| メッセージID | レベル | メッセージ内容 | 発生条件 |
|-------------|--------|--------------|----------|
| - | Error | Failure | SQL Server接続に失敗した場合 |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| 接続エラー | SQL Serverへの接続失敗 | Stop-Functionでエラー記録、次のインスタンスへ続行 |
| コードページ取得エラー | 無効なコードページID | catchで$nullを設定、処理続行 |
| ロケール取得エラー | 無効なロケールID | catchで$nullを設定、処理続行 |

## 備考

- CONNECT権限のみで実行可能
- コードページ名とロケール名のキャッシュにより、約9倍の高速化を実現（2秒 vs 18秒）
- ロケールID 66577（Japanese_Unicode）はWindowsでサポートされないがSQL Serverでは表示される
- SQL Serverバージョンによってサポートされる照合順序が異なる

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAvailableCollation.ps1 | `public/Get-DbaAvailableCollation.ps1` | 28-52行目: .OUTPUTSセクションで出力プロパティ定義 |
| 1-2 | Get-DbaAvailableCollation.ps1 | `public/Get-DbaAvailableCollation.ps1` | 135行目: Select-DefaultViewで表示プロパティ指定 |

**読解のコツ**: SMO Collationオブジェクトに`Add-Member`で拡張プロパティを追加している点に注目。Select-DefaultViewでデフォルト表示を制御。

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

処理の起点となる関数の構造を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAvailableCollation.ps1 | `public/Get-DbaAvailableCollation.ps1` | 71-77行目: パラメータ定義 |
| 2-2 | Get-DbaAvailableCollation.ps1 | `public/Get-DbaAvailableCollation.ps1` | 118-137行目: processブロックのメインロジック |

**主要処理フロー**:
1. **118-119行目**: SqlInstanceパラメータのforeachループ開始
2. **120-124行目**: Connect-DbaInstanceでSQL Server接続
3. **126行目**: EnumCollations()で照合順序一覧取得
4. **127-132行目**: 各照合順序に拡張プロパティ追加
5. **135行目**: Select-DefaultViewで出力

#### Step 3: ヘルパー関数を理解する

コードページ名とロケール名を取得するキャッシュ付きヘルパー関数を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAvailableCollation.ps1 | `public/Get-DbaAvailableCollation.ps1` | 79-116行目: beginブロックのヘルパー関数 |

**主要処理フロー**:
- **86行目**: ロケールID 66577（Japanese_Unicode）のハードコード対応
- **87行目**: コードページキャッシュ用ハッシュテーブル
- **89-101行目**: Get-LocaleDescription関数 - ロケールID→表示名変換（キャッシュ付き）
- **103-115行目**: Get-CodePageDescription関数 - コードページID→表示名変換（キャッシュ付き）

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

```
Get-DbaAvailableCollation
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ $server.EnumCollations()
    │      └─ SMO経由で照合順序一覧取得
    │
    ├─ Get-CodePageDescription (内部関数)
    │      └─ Get-CodePage (dbatools内部関数)
    │
    ├─ Get-LocaleDescription (内部関数)
    │      └─ Get-Language (dbatools内部関数)
    │
    └─ Select-DefaultView
           └─ 表示プロパティ選択
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ $server オブジェクト
                          │
                          ▼
                 $server.EnumCollations()
                          │
                          ▼
              各 Collation オブジェクトに拡張プロパティ追加
                          │
              ├─ ComputerName, InstanceName, SqlInstance
              ├─ Get-CodePageDescription → CodePageName
              └─ Get-LocaleDescription → LocaleName
                          │
                          ▼
                 Select-DefaultView
                          │
                          ▼
                 Microsoft.SqlServer.Management.Smo.Collation
                 + 拡張プロパティ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAvailableCollation.ps1 | `public/Get-DbaAvailableCollation.ps1` | ソース | メインコマンド実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Select-DefaultView.ps1 | `internal/functions/Select-DefaultView.ps1` | ソース | 表示プロパティ制御 |
