# 画面設計書 137-インスタンス非表示

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverインスタンス非表示（Hide Instance）設定管理機能の設計仕様を定義する。

### 本画面の処理概要

SQL Serverインスタンスの「Hide Instance」設定の取得、有効化、無効化を行う機能群を提供する。

**業務上の目的・背景**：Hide Instanceは、SQL Server Browserサービスによるインスタンス列挙リクエストへの応答を停止することで、ネットワークスキャンツールからインスタンスを隠すセキュリティ機能である。セキュリティ強化環境において、攻撃対象面を減らすためにインスタンスの存在を隠蔽する目的で使用される。Hide Instanceが有効な場合、クライアントは正確なポート番号を指定するか、SQL Serverエイリアスを使用して接続する必要がある。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスする
- `Get-DbaHideInstance` - インスタンス非表示設定の取得
- `Enable-DbaHideInstance` - インスタンス非表示の有効化
- `Disable-DbaHideInstance` - インスタンス非表示の無効化

**主要な操作・処理内容**：
1. 現在のHide Instance設定状態の確認
2. インスタンス非表示の有効化（レジストリ値を$trueに設定）
3. インスタンス非表示の無効化（レジストリ値を$falseに設定）
4. 設定変更は即座に新しい接続に反映（サービス再起動不要）

**画面遷移**：CLIベースのため画面遷移は存在しない。

**権限による表示制御**：Windows管理者権限が必要。対象サーバーへのリモートPowerShell接続権限およびレジストリ変更権限が必要となる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 334 | Get-DbaHideInstance | 主機能 | インスタンス非表示設定の取得 |
| 330 | Enable-DbaHideInstance | 主機能 | インスタンス非表示の有効化 |
| 328 | Disable-DbaHideInstance | 主機能 | インスタンス非表示の無効化 |
| - | Resolve-DbaNetworkName | 補助機能 | ネットワーク名の解決 |
| - | Invoke-ManagedComputerCommand | 補助機能 | WMI経由のサービス情報取得 |

## 画面種別

CLI（コマンドラインインターフェース）

## URL/ルーティング

該当なし（PowerShellコマンドレット）

## 入出力項目

### Get-DbaHideInstance

| 項目名 | データ型 | 必須 | 説明 |
|--------|----------|------|------|
| SqlInstance | DbaInstanceParameter[] | いいえ | 対象SQLインスタンス（デフォルト: localhost） |
| Credential | PSCredential | いいえ | 接続に使用するWindows資格情報 |
| EnableException | switch | いいえ | 例外を直接発生させるかどうか |

### Enable-DbaHideInstance / Disable-DbaHideInstance

| 項目名 | データ型 | 必須 | 説明 |
|--------|----------|------|------|
| SqlInstance | DbaInstanceParameter[] | いいえ | 対象SQLインスタンス（デフォルト: localhost） |
| Credential | PSCredential | いいえ | 接続に使用するWindows資格情報 |
| EnableException | switch | いいえ | 例外を直接発生させるかどうか |
| WhatIf | switch | いいえ | 実行予定の操作を表示 |
| Confirm | switch | いいえ | 実行前に確認を求める |

## 表示項目

### 共通出力プロパティ

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| HideInstance | bool | インスタンス非表示の有効/無効状態（$true=非表示、$false=表示） |

## イベント仕様

### 1-Get-DbaHideInstance実行

1. Test-ElevationRequirementで管理者権限を確認
2. Resolve-DbaNetworkNameでコンピュータ名を解決
3. Invoke-ManagedComputerCommandでWMIサービス情報を取得
4. レジストリからHideInstance値を読み取り
5. 結果をハッシュテーブルで返却し、PSCustomObjectに変換

### 2-Enable-DbaHideInstance実行

1. localhostの場合、Test-ElevationRequirementで管理者権限を確認
2. Resolve-DbaNetworkNameでコンピュータ名を解決
3. Invoke-ManagedComputerCommandでWMIサービス情報を取得
4. レジストリパスを特定
5. ShouldProcess確認後、HideInstance値を$trueに設定
6. 変更後の値を読み取って結果を返却
7. 設定変更が即座に有効になる旨のCriticalメッセージを出力

### 3-Disable-DbaHideInstance実行

1. localhostの場合、Test-ElevationRequirementで管理者権限を確認
2. Resolve-DbaNetworkNameでコンピュータ名を解決
3. Invoke-ManagedComputerCommandでWMIサービス情報を取得
4. レジストリパスを特定
5. ShouldProcess確認後、HideInstance値を$falseに設定
6. 変更後の値を読み取って結果を返却
7. 設定変更が即座に有効になる旨のCriticalメッセージを出力

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

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

本機能はWindowsレジストリを更新するため、データベースへの直接的な更新は発生しない。

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| Get-DbaHideInstance | Windowsレジストリ | READ | SuperSocketNetLib\HideInstance値の読み取り |
| Enable-DbaHideInstance | Windowsレジストリ | UPDATE | HideInstance値を$trueに設定 |
| Disable-DbaHideInstance | Windowsレジストリ | UPDATE | HideInstance値を$falseに設定 |

### レジストリ更新詳細

#### HKLM\{REGROOT}\MSSQLServer\SuperSocketNetLib

| 操作 | 項目（レジストリ値） | 更新値 | 備考 |
|-----|---------------------|--------|------|
| Enable | HideInstance | $true | インスタンスを非表示に |
| Disable | HideInstance | $false | インスタンスを表示 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|----------|----------|
| - | Critical | HideInstance was successfully set on {computer} for the {instance} instance. The change takes effect immediately for new connections. | Enable成功時 |
| - | Critical | HideInstance was successfully disabled on {computer} for the {instance} instance. The change takes effect immediately for new connections. | Disable成功時 |
| - | Error | Issue resolving {instance} | 名前解決失敗時 |
| - | Error | Failed to access {instance} | WMI接続失敗時 |
| - | Error | Can't find instance {vsname} on {instance} | インスタンス検出失敗時 |
| - | Error | Failed to connect to {computer} using PowerShell remoting | リモート接続失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| 管理者権限不足 | Test-ElevationRequirementで検出、警告表示して処理継続 |
| インスタンス名解決失敗 | Turboモードでの解決を試行、失敗時は処理中止 |
| WMI接続失敗 | エラー記録して次のインスタンスへ継続 |
| レジストリルート特定失敗 | 処理中止 |
| PowerShellリモーティング失敗 | エラー記録して次のインスタンスへ継続 |

## 備考

- HideInstanceの設定変更はサービス再起動なしで即座に有効
- インスタンスを非表示にしても、正確なポート番号やSQL Serverエイリアスを知っていれば接続可能
- SQL Server Browserサービスが停止している場合、この設定は実質的に無意味
- SQL Server Configuration Managerのネットワーク構成プロトコルプロパティと同等の設定

---

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

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

### 推奨読解順序

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

まず、コマンドが返すオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaHideInstance.ps1 | `public/Get-DbaHideInstance.ps1` | .OUTPUTSセクションで出力プロパティ定義（行32-41） |
| 1-2 | Enable-DbaHideInstance.ps1 | `public/Enable-DbaHideInstance.ps1` | 出力プロパティ定義（行46-55） |

**読解のコツ**: 3つのコマンドはほぼ同じ出力構造を持つ。HideInstanceプロパティはブール値で出力される。

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

処理の起点となるファイル・関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaHideInstance.ps1 | `public/Get-DbaHideInstance.ps1` | processブロックの構造と名前解決 |

**主要処理フロー**:
1. **行63**: 管理者権限確認
2. **行66-70**: Resolve-DbaNetworkNameによる名前解決（エラー時Turboフォールバック）
3. **行77-83**: Invoke-ManagedComputerCommandでWMIサービス情報取得

#### Step 3: レジストリ操作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaHideInstance.ps1 | `public/Get-DbaHideInstance.ps1` | スクリプトブロック内のレジストリ操作（行121-131） |
| 3-2 | Enable-DbaHideInstance.ps1 | `public/Enable-DbaHideInstance.ps1` | HideInstance値の設定（行133） |

**主要処理フロー**:
- **Get行122**: レジストリパス構築（$regPath）
- **Get行123**: HideInstance値の読み取り
- **Get行126-130**: ハッシュテーブルで結果構築（HideInstance = $true判定）
- **Enable行133**: Set-ItemPropertyでHideInstance=$trueを設定
- **Disable行133**: Set-ItemPropertyでHideInstance=$falseを設定

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

```
Get-DbaHideInstance
    |
    +-- Test-ElevationRequirement
    |
    +-- Resolve-DbaNetworkName
    |       +-- FullComputerName取得
    |
    +-- Invoke-ManagedComputerCommand
    |       +-- $wmi.Services（SQL Serverサービス情報）
    |
    +-- Invoke-Command2 (スクリプトブロック)
            +-- Get-ItemProperty (レジストリ読み取り)
            +-- ハッシュテーブル結果返却

Enable/Disable-DbaHideInstance
    |
    +-- Test-ElevationRequirement (localhost時)
    |
    +-- Resolve-DbaNetworkName
    |
    +-- Invoke-ManagedComputerCommand
    |
    +-- ShouldProcess確認
    |
    +-- Invoke-Command2 (スクリプトブロック)
            +-- Set-ItemProperty (HideInstance設定)
            +-- Get-ItemProperty (設定確認)
            +-- PSCustomObject結果返却
```

### データフロー図

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

SqlInstance ────────▶ Resolve-DbaNetworkName ────────▶ FullComputerName
    |                        |
Credential ─────────────────▶ |
                              v
                     Invoke-ManagedComputerCommand
                              |
                              v
                     WMI Services情報取得
                              |
                              v
                     レジストリパス特定
                     (REGROOT\MSSQLServer\
                      SuperSocketNetLib)
                              |
                              v
                    ┌─────────────────────────┐
                    │   Invoke-Command2       │
                    │   (リモートスクリプト)   │
                    │                         │
       [Get] ──────▶│  Get-ItemProperty      │────▶ ハッシュテーブル
                    │  HideInstance           │       (PSCustomObject変換)
                    │  ($true/$false判定)     │
                    │                         │
    [Enable] ──────▶│  Set-ItemProperty      │────▶ PSCustomObject
                    │  HideInstance=$true    │       + Criticalメッセージ
                    │                         │
   [Disable] ──────▶│  Set-ItemProperty      │────▶ PSCustomObject
                    │  HideInstance=$false   │       + Criticalメッセージ
                    └─────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaHideInstance.ps1 | `public/Get-DbaHideInstance.ps1` | ソース | インスタンス非表示設定取得コマンド |
| Enable-DbaHideInstance.ps1 | `public/Enable-DbaHideInstance.ps1` | ソース | インスタンス非表示有効化コマンド |
| Disable-DbaHideInstance.ps1 | `public/Disable-DbaHideInstance.ps1` | ソース | インスタンス非表示無効化コマンド |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | ネットワーク名解決ユーティリティ |
