# 画面設計書 248-レジストリルート

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Get-DbaRegistryRoot` コマンドに関する画面設計書です。SQL Serverインスタンスの設定が格納されているWindowsレジストリのルートパスを検出する機能を提供します。

### 本画面の処理概要

`Get-DbaRegistryRoot` コマンドは、SQL Server WMIを使用して各SQL Serverインスタンスのレジストリ構成パスを特定し、PowerShellで直接使用可能なレジストリパスを返却する機能を提供します。

**業務上の目的・背景**：SQL Serverの構成設定の一部はWindowsレジストリに格納されており、起動パラメータの変更、トレースフラグの設定、SQL Server Configuration Managerで公開されていない詳細設定の確認などで、直接レジストリにアクセスする必要があることがあります。しかし、SQL Serverのレジストリパスはバージョンやインスタンス名によって異なり（例：MSSQL15.MSSQLSERVER、MSSQL14.SQLEXPRESS等）、手動で特定するのは煩雑です。本コマンドは、WMIを通じて正確なレジストリパスを自動検出し、レジストリ編集作業を効率化します。

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

**主要な操作・処理内容**：
1. SQL Server WMI（ManagedComputerCommand）への接続
2. SQL Serverサービス一覧の取得とフィルタリング
3. 各サービスのAdvancedPropertiesからREGROOTとVSNAMEを抽出
4. レジストリパスの構築と出力

**画面遷移**：CLIコマンドのため画面遷移はありません。出力結果は他のコマンド（Get-DbaProductKey等）で内部的に使用されます。

**権限による表示制御**：対象コンピュータへの接続権限とWMIアクセス権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 145 | Get-DbaRegistryRoot | 主機能 | レジストリルートの取得 |
| - | Invoke-ManagedComputerCommand | 補助機能 | SQL Server WMIコマンド実行 |
| 140 | Get-DbaProductKey | 呼び出し元 | プロダクトキー取得（内部で使用） |

## 画面種別

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

## URL/ルーティング

PowerShellコマンド: `Get-DbaRegistryRoot`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | パイプライン | 説明 |
|-------------|----|----|-------------|------|
| ComputerName | DbaInstanceParameter[] | No | Yes | 対象コンピュータ名（デフォルト: $env:COMPUTERNAME） |
| Credential | PSCredential | No | No | 代替Windows資格情報 |
| EnableException | switch | No | No | 例外を詳細表示するフラグ |

## 表示項目

### 出力オブジェクト（PSCustomObject）

| 項目名 | 型 | 説明 |
|--------|----|----|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名（デフォルトインスタンスは"MSSQLSERVER"） |
| SqlInstance | string | 完全修飾SQL Serverインスタンス名（computer\instance形式） |
| Hive | string | レジストリハイブ（常に"HKLM"） |
| Path | string | ハイブ内のレジストリパス（例: Software\Microsoft\Microsoft SQL Server\MSSQL15.MSSQLSERVER\Setup） |
| RegistryRoot | string | 完全なレジストリパス（例: HKLM:\Software\Microsoft\Microsoft SQL Server\...） |

## イベント仕様

### 1-コマンド実行

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

1. **WMI接続**: `Invoke-ManagedComputerCommand` でSQL Server WMIに接続
2. **サービスフィルタ**: DisplayNameが"SQL Server ("を含むサービスを抽出
3. **プロパティ抽出**: 各サービスのAdvancedPropertiesからREGROOTとVSNAMEを取得
4. **インスタンス名解析**: DisplayNameからインスタンス名を抽出
5. **SqlInstance構築**: フェイルオーバークラスタの場合はVSNAME、それ以外はComputerNameを使用
6. **結果出力**: レジストリパス情報をPSCustomObjectとして出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| コマンド実行 | - | - | データベースアクセスなし（WMI/レジストリメタデータ読み取り） |

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

本コマンドはデータベースへのアクセスを行いません。SQL Server WMIを通じてレジストリパス情報を取得します。

## メッセージ仕様

| メッセージID | レベル | メッセージ内容 | 発生条件 |
|-------------|--------|--------------|----------|
| - | Verbose | Regroot: {regRoot} | レジストリルート情報出力時 |
| - | Verbose | InstanceName: {instanceName} | インスタンス名情報出力時 |
| - | Verbose | VSNAME: {vsname} | 仮想サーバー名情報出力時 |
| - | Error | Can't find instance {instanceName} on {COMPUTERNAME} | インスタンス情報取得失敗時 |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| WMI接続エラー | Invoke-ManagedComputerCommand失敗 | Stop-Functionでエラー記録、続行 |
| インスタンス未検出 | REGROOTが空または取得不可 | Stop-Functionでエラー記録、次のインスタンスへ続行 |

## 備考

- フェイルオーバークラスタインスタンスの場合、VSNAMEに仮想サーバー名が設定される
- デフォルトインスタンスの場合、InstanceNameは"MSSQLSERVER"
- 名前付きインスタンスの場合、SqlInstanceは"ComputerName\InstanceName"形式
- レジストリパスはSQL Serverバージョンによって異なる（MSSQL11=2012, MSSQL15=2019等）
- Get-DbaProductKeyなど他のコマンドから内部的に呼び出される
- REGROOTの値が空の場合、AdvancedPropertiesを文字列として再パース

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaRegistryRoot.ps1 | `public/Get-DbaRegistryRoot.ps1` | 30-41行目: .OUTPUTSセクションで出力プロパティ定義 |
| 1-2 | Get-DbaRegistryRoot.ps1 | `public/Get-DbaRegistryRoot.ps1` | 103-110行目: 出力PSCustomObjectの構造 |

**読解のコツ**: RegistryRootプロパティがPowerShellのレジストリPSドライブ形式（HKLM:\...）で返される点に注目。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaRegistryRoot.ps1 | `public/Get-DbaRegistryRoot.ps1` | 55-61行目: パラメータ定義 |
| 2-2 | Get-DbaRegistryRoot.ps1 | `public/Get-DbaRegistryRoot.ps1` | 63-112行目: processブロックのメインロジック |

**主要処理フロー**:
1. **66-68行目**: Invoke-ManagedComputerCommandでWMIサービス一覧取得
2. **66行目**: Where-Object DisplayName -Match "SQL Server \("でフィルタ
3. **73-74行目**: AdvancedPropertiesからREGROOTとVSNAME取得
4. **75行目**: DisplayNameからインスタンス名抽出（Replace処理）
5. **90-97行目**: SqlInstance構築（VSNAME有無で分岐）
6. **103-110行目**: PSCustomObject出力

#### Step 3: WMIプロパティ解析を理解する

AdvancedPropertiesからの情報抽出ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaRegistryRoot.ps1 | `public/Get-DbaRegistryRoot.ps1` | 73-87行目: REGROOTとVSNAME抽出ロジック |

**主要処理フロー**:
- **73行目**: `$sqlwmi.AdvancedProperties | Where-Object Name -EQ REGROOT` で直接取得試行
- **77-86行目**: 直接取得失敗時の代替パース処理（文字列分割）
- **82-83行目**: "Value="で分割して値を抽出

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

```
Get-DbaRegistryRoot
    │
    └─ Invoke-ManagedComputerCommand
           │
           └─ $wmi.Services (SQL Server WMI)
                  │
                  ├─ Where-Object DisplayName -Match "SQL Server \("
                  │
                  └─ foreach ($sqlwmi in $sqlwmis)
                         │
                         ├─ $sqlwmi.AdvancedProperties (REGROOT)
                         ├─ $sqlwmi.AdvancedProperties (VSNAME)
                         ├─ $sqlwmi.DisplayName (InstanceName)
                         │
                         └─ [PSCustomObject] 出力
```

### データフロー図

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

ComputerName ───▶ Invoke-ManagedComputerCommand
                            │
                            ▼
                    $wmi.Services
                    (SQL Server WMI)
                            │
                            ▼
              Where-Object DisplayName -Match "SQL Server \("
                            │
                            ▼
               AdvancedProperties 抽出
                  ├─ REGROOT
                  └─ VSNAME
                            │
                            ▼
               DisplayName からインスタンス名解析
               "SQL Server (" → ")" を削除
                            │
                            ▼
               SqlInstance 構築
               (VSNAME or ComputerName) + InstanceName
                            │
                            ▼
                      PSCustomObject
              (ComputerName, InstanceName, SqlInstance,
               Hive, Path, RegistryRoot)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaRegistryRoot.ps1 | `public/Get-DbaRegistryRoot.ps1` | ソース | メインコマンド実装 |
| Invoke-ManagedComputerCommand.ps1 | `internal/functions/Invoke-ManagedComputerCommand.ps1` | ソース | SQL Server WMIコマンド実行 |
| Get-DbaProductKey.ps1 | `public/Get-DbaProductKey.ps1` | ソース | 呼び出し元コマンド |
