# 機能設計書 129-Get-DbaLocaleSetting

## 概要

本ドキュメントは、SQL Serverホストコンピュータからレジストリ経由でWindowsロケール設定を取得するGet-DbaLocaleSetting機能の設計仕様を記載する。

### 本機能の処理概要

Get-DbaLocaleSettingは、リモートコンピュータのWindowsレジストリからControl Panel\Internationalキーの値を読み取り、ロケール設定（日付形式、通貨記号、数値書式等）を取得する機能である。

**業務上の目的・背景**：SQL Serverの動作は、Windowsの地域設定に依存する部分がある（日付/時刻のフォーマット、通貨表示、数値書式、照合順序など）。DBAは、SQL Serverインストール前や問題発生時に、サーバーの地域設定を確認する必要がある。本機能により、複数サーバーの地域設定を一括で監査できる。

**機能の利用シーン**：
- SQL Server環境全体の地域設定監査
- インストール前の地域設定確認
- ロケール関連問題のトラブルシューティング
- サーバー間の設定整合性確認

**主要な処理内容**：
1. コンピュータ名の解決（Resolve-DbaNetworkName）
2. CIMセッションの確立（WSMan優先、フォールバックでDCOM）
3. レジストリキーHKCU\Control Panel\Internationalの値名一覧を取得
4. 各値を読み取ってプロパティとして返却

**関連システム・外部連携**：CIM/WMI (StdRegProv)、Windowsレジストリ

**権限による制御**：対象コンピュータへのローカル管理者権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コンソール/ターミナル | 主画面 | コマンド実行と結果表示 |

## 機能種別

データ取得(SELECT) / システム設定監査

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | string[] | No | 対象コンピュータ名（エイリアス: cn, host, Server）（デフォルト: $env:COMPUTERNAME） | ValueFromPipeline |
| Credential | PSCredential | No | リモートコンピュータへのWindows資格情報 | - |
| EnableException | switch | No | 例外を直接スローするか | - |

### 入力データソース

- コンピュータ名
- Windowsレジストリ（HKEY_CURRENT_USER\Control Panel\International）

## 出力仕様

### 出力データ

動的に取得されるプロパティ。以下は代表的なもの：

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | 対象コンピュータ名 |
| Locale | string | ロケールコード（例: "00000410"） |
| LocaleName | string | ロケール名（例: "it-IT"） |
| sLanguage | string | 言語略称（例: "ITA"） |
| sCurrency | string | 通貨記号（例: "€"） |
| sLongDate | string | 長い日付形式 |
| sShortDate | string | 短い日付形式 |
| sTimeFormat | string | 時刻形式 |
| sShortTime | string | 短い時刻形式 |
| sDecimal | string | 小数点記号 |
| sList | string | リスト区切り文字 |
| iDigits | string | 小数点以下桁数 |
| iCountry | string | 国/地域識別子 |
| iDate | string | 日付形式（0=M/D/Y, 1=D/M/Y, 2=Y/M/D） |
| iTime | string | 時刻形式（0=12時間, 1=24時間） |
| sAM | string | 午前記号 |
| sPM | string | 午後記号 |
| sThousand | string | 千位区切り文字 |

### 出力先

- PowerShellパイプライン（PSCustomObject）
- コンソール出力

## 処理フロー

### 処理シーケンス

```
1. beginブロックで初期化
   └─ コンピュータ名からインスタンス部分を除去してユニーク化
   └─ CIMセッションオプション（DCom）を準備
   └─ レジストリキー名、名前空間、クラス名を定義

2. 各ComputerNameをループ処理
   └─ プロパティハッシュテーブル初期化

3. Resolve-DbaNetworkNameでコンピュータ名を解決
   └─ FullComputerNameを取得

4. CIMセッションを確立
   └─ WSManを優先、失敗時はDComにフォールバック

5. StdRegProv.enumvaluesでレジストリ値名一覧を取得
   └─ HKEY_CURRENT_USER (0x80000001)

6. 各値名に対してStdRegProv.GetSTRINGvalueで値を取得
   └─ propsハッシュテーブルに追加

7. PSCustomObjectとして出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[コンピュータ名正規化]
    B --> C{ComputerNameループ}
    C -->|各コンピュータ| D[Resolve-DbaNetworkName]
    D --> E{解決成功?}
    E -->|No| F[Warning出力]
    F --> C
    E -->|Yes| G[CIMセッション作成（WSMan）]
    G --> H{成功?}
    H -->|No| I[CIMセッション作成（DCom）]
    H -->|Yes| J[enumvaluesでキー一覧取得]
    I --> K{成功?}
    K -->|No| L[Warning出力]
    L --> C
    K -->|Yes| J
    J --> M{値名ループ}
    M -->|各値名| N[GetSTRINGvalueで値取得]
    N --> O[propsに追加]
    O --> M
    M -->|終了| P[PSCustomObject出力]
    P --> C
    C -->|全コンピュータ完了| Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | インスタンス名除去 | コンピュータ名に\が含まれる場合、\以前の部分のみ使用 | 入力処理時 |
| BR-002 | WSMan優先 | CIMセッションはWSManを優先、失敗時はDComにフォールバック | セッション確立時 |
| BR-003 | HKEY_CURRENT_USER | 現在のユーザーのロケール設定を取得（2147483649 = 0x80000001） | レジストリアクセス時 |

### 計算ロジック

特になし（レジストリ値をそのまま返却）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | データベースアクセスなし（レジストリのみ） |

### レジストリアクセス詳細

#### HKEY_CURRENT_USER\Control Panel\International

| 操作 | CIMメソッド | 引数 | 備考 |
|-----|-------------|------|------|
| 値名一覧取得 | enumvalues | hDefKey=2147483649, sSubKeyName="Control Panel\International" | 全ての値名を取得 |
| 値取得 | GetSTRINGvalue | hDefKey=2147483649, sSubKeyName="Control Panel\International", sValueName=各値名 | 文字列として取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 名前解決失敗 | Resolve-DbaNetworkName失敗 | Warning出力して次のコンピュータへ |
| - | CIMセッション失敗 | WSManもDComも失敗 | Warning出力して次のコンピュータへ |

### リトライ仕様

- CIMセッション: WSMan失敗時はDComで1回リトライ

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

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

## パフォーマンス要件

- CIMセッション確立に若干の遅延あり（特にDComフォールバック時）
- 複数コンピュータは順次処理

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

- 対象コンピュータへのローカル管理者権限が必要
- Credentialパラメータで代替Windows資格情報を指定可能
- HKEY_CURRENT_USERへのアクセス（接続ユーザーのレジストリハイブ）

## 備考

- 返却されるプロパティはコンピュータの設定によって異なる
- 全てのプロパティを確認するには`Select-Object *`を使用
- SQL Serverインスタンス名（例: server\instance）を指定した場合、サーバー名部分のみ使用

---

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

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

### 推奨読解順序

#### Step 1: 初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaLocaleSetting.ps1 | `public/Get-DbaLocaleSetting.ps1` | beginブロックの初期化処理 |

**主要処理フロー**:
1. **105-106行目**: コンピュータ名の正規化（インスタンス名除去、ユニーク化）
2. **107行目**: DCom用CIMセッションオプション準備
3. **108-111行目**: レジストリアクセス用定数定義

**読解のコツ**:
- `$_.split("\")[0]`でインスタンス名部分を除去
- `[UInt32]$CIMHiveCU = 2147483649`はHKEY_CURRENT_USERの数値表現

#### Step 2: CIMセッション確立を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaLocaleSetting.ps1 | `public/Get-DbaLocaleSetting.ps1` | processブロックのCIMセッション処理 |

**主要処理フロー**:
- **116行目**: Resolve-DbaNetworkNameでコンピュータ名解決
- **119-120行目**: WSManでCIMセッション作成を試行
- **121-123行目**: 失敗時はDComでCIMセッション作成

#### Step 3: レジストリ読み取りを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaLocaleSetting.ps1 | `public/Get-DbaLocaleSetting.ps1` | レジストリ値取得処理 |

**主要処理フロー**:
- **126-127行目**: Invoke-CimMethod enumvaluesで値名一覧取得
- **129-131行目**: 各値名に対してGetSTRINGvalueで値取得
- **133行目**: PSCustomObjectとして出力

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

```
Get-DbaLocaleSetting
    │
    ├─ コンピュータ名正規化
    │      └─ インスタンス名除去、ユニーク化
    │
    ├─ Resolve-DbaNetworkName (コンピュータ名解決)
    │
    ├─ New-CimSession (WSMan)
    │      └─ 失敗時: New-CimSession (DCom)
    │
    ├─ Invoke-CimMethod enumvalues
    │      └─ StdRegProv (レジストリ値名一覧)
    │
    └─ Invoke-CimMethod GetSTRINGvalue
           └─ StdRegProv (各値の取得)
```

### データフロー図

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

ComputerName   ───▶  インスタンス名除去        ───▶
                           │
                     Resolve-DbaNetworkName   ───▶
                           │
                     New-CimSession           ───▶  CIMセッション
                           │
                     enumvalues               ───▶  値名リスト
                           │
                     GetSTRINGvalue           ───▶  各値
                           │
                     PSCustomObject           ───▶  パイプライン出力
                                                   (ComputerName,
                                                    Locale, LocaleName,
                                                    sLanguage, sCurrency,
                                                    sLongDate, ...)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaLocaleSetting.ps1 | `public/Get-DbaLocaleSetting.ps1` | ソース | メイン関数定義 |
| Get-DbaLocaleSetting.Tests.ps1 | `tests/Get-DbaLocaleSetting.Tests.ps1` | テスト | 単体・統合テスト |
| Resolve-DbaNetworkName.ps1 | `functions/Resolve-DbaNetworkName.ps1` | ソース | コンピュータ名解決 |
