# 機能設計書 334-Get-DbaHideInstance

## 概要

本ドキュメントは、SQL ServerインスタンスのHide Instance設定をWindowsレジストリから取得する機能「Get-DbaHideInstance」の設計仕様を記載する。

### 本機能の処理概要

Get-DbaHideInstanceは、SQL ServerインスタンスのHide Instance設定をWindowsレジストリから取得する機能である。このセキュリティ設定は、SQL Server Browserサービスのブロードキャストリクエストに対してインスタンスが応答するかどうかを制御する。

**業務上の目的・背景**：Hide Instance設定は、セキュリティ強化策としてSQL Serverインスタンスをネットワーク検出から隠蔽するために使用される。有効にすると、SQL Server Browserサービスのブロードキャストリクエストに応答しなくなり、ネットワーク検出ツールからインスタンスが見えなくなる。DBはこの設定を使用して、未認可のSQL Server発見を防ぎ、攻撃対象を縮小する。本機能は、この設定の現在の状態を確認するために使用される。

**機能の利用シーン**：
- セキュリティ監査でインスタンスの隠蔽設定を確認する際
- セキュリティベースライン準拠を検証する際
- インスタンス検出の問題をトラブルシューティングする際
- 環境間でセキュリティ設定を比較する際

**主要な処理内容**：
1. 対象コンピュータへの接続とインスタンス情報の取得
2. WMI経由でSQL Serverサービス情報の取得
3. レジストリパス（REGROOT）の特定
4. PowerShellリモーティングでレジストリのHideInstance値を取得
5. 結果をカスタムオブジェクトとして出力

**関連システム・外部連携**：
- Windows WMI (SQL Server Configuration Manager)
- Windows レジストリ
- PowerShell Remoting

**権限による制御**：
- Windowsの管理者権限が必要（RunAs admin）
- SQL Server権限は不要（レジストリへの直接アクセス）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン | 主画面 | PowerShellコンソールからの実行 |

## 機能種別

情報取得 / セキュリティ設定確認

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス（デフォルト: localhost） | パイプライン入力可能 |
| Credential | PSCredential | No | リモートコンピュータ接続用のWindows資格情報 | - |
| EnableException | switch | No | 例外を直接スローする | - |

### 入力データソース

- Windows レジストリ（HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\{REGROOT}\MSSQLServer\SuperSocketNetLib）
- SQL Server WMI プロバイダー

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| HideInstance | bool | インスタンスが隠蔽されているか（true: 隠蔽、false: 可視） |

### 出力先

パイプライン出力（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. 管理者権限チェック
   └─ Test-ElevationRequirement で権限確認

2. ホスト名解決
   └─ Resolve-DbaNetworkName でネットワーク名を解決

3. WMI経由でサービス情報取得
   └─ Invoke-ManagedComputerCommand でSQL Serverサービス情報取得

4. レジストリパスの特定
   └─ AdvancedProperties から REGROOT と VSNAME を取得

5. レジストリ値の取得
   └─ Invoke-Command2 でリモートレジストリアクセス

6. 結果出力
   └─ PSCustomObject としてパイプラインに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[管理者権限チェック]
    B --> C{権限あり?}
    C -->|No| D[エラー/警告]
    C -->|Yes| E[Resolve-DbaNetworkName]
    E --> F{解決成功?}
    F -->|No| G[Stop-Function]
    F -->|Yes| H[Invoke-ManagedComputerCommand]
    H --> I{WMI成功?}
    I -->|No| J[Stop-Function]
    I -->|Yes| K[REGROOT/VSNAME取得]
    K --> L{値が空?}
    L -->|Yes| M[別の取得方法を試行]
    L -->|No| N[ScriptBlock定義]
    M --> N
    N --> O[Invoke-Command2 でレジストリ読み取り]
    O --> P{成功?}
    P -->|No| Q[Stop-Function]
    P -->|Yes| R[PSCustomObject作成]
    R --> S[出力]
    S --> T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 管理者権限必須 | 本関数は管理者権限（RunAs admin）で実行する必要がある | 常に |
| BR-002 | レジストリパス | REGROOT\MSSQLServer\SuperSocketNetLib\HideInstance から値を取得 | 常に |
| BR-003 | デフォルトインスタンス | SqlInstance未指定時は localhost を使用 | SqlInstance省略時 |

### 計算ロジック

- HideInstance = (レジストリ値 HideInstance) -eq $true

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

本機能はSQL Serverへのデータベース接続を行わない。Windowsレジストリから直接情報を取得する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 権限エラー | 管理者権限なし | Test-ElevationRequirementで事前チェック |
| - | 名前解決エラー | ホスト名解決失敗 | Stop-Function で処理継続 |
| - | WMIエラー | WMIアクセス失敗 | Stop-Function で処理継続 |
| - | レジストリエラー | レジストリアクセス失敗 | Stop-Function で処理継続 |
| - | リモーティングエラー | PowerShellリモーティング失敗 | Stop-Function で処理継続 |

### リトライ仕様

リトライは行わない。

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

本機能はデータ変更を行わないため、トランザクション管理は不要。

## パフォーマンス要件

- リモートコンピュータへのWMI/レジストリアクセスのため、ネットワーク遅延に依存
- 通常は数秒以内に完了

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

- 管理者権限が必要
- リモートアクセス時はPowerShellリモーティングを使用
- Credential パラメータで別の資格情報を指定可能

## 備考

- SQL Server認証ではなく、Windows認証のみ対応
- Enable-DbaHideInstance で設定を有効化、Disable-DbaHideInstance で無効化可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaHideInstance.ps1 | `public/Get-DbaHideInstance.ps1` | 出力オブジェクト構造（32-41行目の.OUTPUTS） |

**読解のコツ**: レジストリパスの構造を理解することが重要。REGROOTはインスタンスごとに異なる値を持つ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaHideInstance.ps1 | `public/Get-DbaHideInstance.ps1` | パラメータ定義（53-59行目） |

**主要処理フロー**:
1. **60-63行目**: foreach ループ開始と管理者権限チェック
2. **65-71行目**: ネットワーク名の解決
3. **77-83行目**: WMI経由でサービス情報取得
4. **85-119行目**: REGROOT、VSNAME、インスタンス名の取得
5. **121-141行目**: リモートレジストリアクセスと結果出力

#### Step 3: レジストリアクセスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaHideInstance.ps1 | `public/Get-DbaHideInstance.ps1` | ScriptBlock定義（121-132行目） |

**主要処理フロー**:
- **122行目**: レジストリパスの構築
- **123行目**: Get-ItemPropertyでHideInstance値取得
- **126-130行目**: ハッシュテーブルで結果を返却

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

```
Get-DbaHideInstance
    │
    ├─ Test-ElevationRequirement
    │      └─ 管理者権限チェック
    │
    ├─ Resolve-DbaNetworkName
    │      └─ コンピュータ名の解決
    │
    ├─ Invoke-ManagedComputerCommand
    │      └─ WMI経由でSQL Serverサービス情報取得
    │           └─ $wmi.Services（SQL Server Configuration Manager）
    │
    └─ Invoke-Command2
           └─ PowerShellリモーティングでレジストリアクセス
                └─ Get-ItemProperty（HideInstance値取得）
```

### データフロー図

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

SqlInstance ──▶ Resolve-DbaNetworkName
                    │
                    ▼
               Invoke-ManagedComputerCommand
                    │
                    ├─ REGROOT取得
                    ├─ VSNAME取得
                    ├─ InstanceName取得
                    │
                    ▼
               Invoke-Command2
                    │
                    └─ Registry::HKEY_LOCAL_MACHINE
                          \{REGROOT}\MSSQLServer\SuperSocketNetLib
                          \HideInstance
                              │
                              ▼
                         PSCustomObject ──▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaHideInstance.ps1 | `public/Get-DbaHideInstance.ps1` | ソース | メイン関数 |
| Enable-DbaHideInstance.ps1 | `public/Enable-DbaHideInstance.ps1` | ソース | Hide Instance設定有効化 |
| Disable-DbaHideInstance.ps1 | `public/Disable-DbaHideInstance.ps1` | ソース | Hide Instance設定無効化 |
| Test-ElevationRequirement.ps1 | `private/functions/Test-ElevationRequirement.ps1` | ソース | 管理者権限チェック |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | ネットワーク名解決 |
| Invoke-ManagedComputerCommand.ps1 | `private/functions/Invoke-ManagedComputerCommand.ps1` | ソース | WMIアクセス |
| Invoke-Command2.ps1 | `private/functions/Invoke-Command2.ps1` | ソース | PowerShellリモーティング |
