# 機能設計書 92-Get-DbaClientAlias

## 概要

本ドキュメントは、WindowsレジストリからSQL Serverクライアントエイリアスを取得するGet-DbaClientAliasコマンドの機能設計書である。

### 本機能の処理概要

Get-DbaClientAliasは、ローカルまたはリモートコンピュータのWindowsレジストリからSQL Server Native Clientが使用するクライアントエイリアス定義を取得する機能である。

**業務上の目的・背景**：クライアントエイリアスはSQL Serverインスタンスへの接続を簡素化し、アプリケーションからサーバー名やポート番号を抽象化するために使用される。本機能は複数のワークステーションやサーバーにおけるエイリアス構成を監査し、環境間での設定の一貫性を確認するために必要とされる。

**機能の利用シーン**：複数環境でのクライアントエイリアス構成の監査、マイグレーション前のエイリアス設定確認、非標準ポートを使用するSQL Serverへの接続設定の文書化、およびアプリケーション接続のトラブルシューティング時に利用される。

**主要な処理内容**：
1. 指定されたコンピュータへのリモート接続（またはローカル実行）
2. 32ビットおよび64ビットのレジストリパスを検索
3. SQL Server Native Clientのエイリアス定義を取得
4. プロトコル（TCP/IPまたは名前付きパイプ）を識別
5. 結果をPSCustomObjectとして出力

**関連システム・外部連携**：Windowsレジストリ（HKLM:\SOFTWARE\Microsoft\MSSQLServer\Client\ConnectTo および HKLM:\SOFTWARE\WOW6432Node\Microsoft\MSSQLServer\Client\ConnectTo）からデータを取得する。Invoke-Command2を使用してリモートコンピュータでスクリプトブロックを実行する。

**権限による制御**：対象コンピュータのレジストリへの読み取り権限が必要。リモートコンピュータの場合はPowerShellリモーティングの権限も必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドラインインターフェース | 主画面 | PowerShellコンソールまたはスクリプトから実行 |

## 機能種別

データ取得（Windowsレジストリからの読み取り専用操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | 対象コンピュータ名（デフォルトはローカルコンピュータ） | パイプライン入力可能、複数指定可能 |
| Credential | PSCredential | No | リモートコンピュータへのアクセス用代替認証情報 | - |
| EnableException | Switch | No | 例外処理を有効化 | - |

### 入力データソース

Windowsレジストリの以下のパスからデータを取得：
- `HKLM:\SOFTWARE\Microsoft\MSSQLServer\Client\ConnectTo`（64ビット）
- `HKLM:\SOFTWARE\WOW6432Node\Microsoft\MSSQLServer\Client\ConnectTo`（32ビット）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | エイリアスが構成されているコンピュータ名 |
| NetworkLibrary | String | ネットワークプロトコル（TCP/IP または Named Pipes） |
| ServerName | String | 対象サーバー名またはインスタンス名 |
| AliasName | String | レジストリで定義されたエイリアス名 |
| AliasString | String | プロトコルプレフィックスを含む完全なレジストリ値 |
| Architecture | String | レジストリハイブのアーキテクチャ（32-bit または 64-bit） |

### 出力先

PowerShellパイプラインに直接出力される

## 処理フロー

### 処理シーケンス

```
1. Begin処理：スクリプトブロックの定義
   └─ レジストリアクセス用のスクリプトブロックを作成
2. Process処理：各コンピュータに対してループ処理
   └─ Invoke-Command2でスクリプトブロックを実行
3. レジストリパスの検証
   └─ 32ビットと64ビットの両方のパスをチェック
4. エイリアス定義の読み取り
   └─ Get-ItemPropertyでレジストリ値を取得
5. プロトコルの識別と結果出力
   └─ DBMSSOCN=TCP/IP, DBNMPNTW=Named Pipes
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[スクリプトブロック定義]
    B --> C{各ComputerNameをループ}
    C --> D[Invoke-Command2実行]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function でエラー]
    F --> C
    E -->|Yes| G{各レジストリパスをチェック}
    G --> H{パスが存在?}
    H -->|No| G
    H -->|Yes| I[ConnectToキーを取得]
    I --> J{各エイリアスをループ}
    J --> K[プロトコル識別]
    K --> L[PSCustomObject作成]
    L --> J
    J -->|完了| G
    G -->|完了| C
    C -->|完了| M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-92-1 | プロトコル識別 | DBMSSOCNはTCP/IP、DBNMPNTWはNamed Pipesとして識別 | エイリアス値解析時 |
| BR-92-2 | アーキテクチャ判定 | WOW6432Nodeパスは32-bit、それ以外は64-bit | レジストリパス判定時 |
| BR-92-3 | サーバー名抽出 | プロトコルプレフィックス（DBMSSOCN,/DBNMPNTW,）を除去 | ServerName生成時 |

### 計算ロジック

該当なし

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

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

本機能はSQL Serverデータベースに直接アクセスしない。Windowsレジストリのみを参照する。

### テーブル別操作詳細

該当なし（レジストリアクセスのみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | リモートコンピュータへの接続失敗 | Stop-Functionでエラーを記録し、次のコンピュータに継続 |
| - | レジストリアクセスエラー | レジストリパスが存在しない | continueで次のパスをチェック |

### リトライ仕様

リトライ機構は実装されていない。

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

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

## パフォーマンス要件

特になし。レジストリアクセスは軽量な操作である。

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

- レジストリへの読み取り権限が必要
- リモートアクセスにはPowerShellリモーティングの権限が必要
- Credentialによる代替認証情報の使用をサポート

## 備考

- SQL Serverクライアントがインストールされていないコンピュータでは結果が返らない可能性がある
- 32ビットと64ビットの両方のエイリアスを同時に取得可能

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaClientAlias.ps1 | `public/Get-DbaClientAlias.ps1` | 117-124行目のPSCustomObject定義 |

**読解のコツ**: PSCustomObjectでは@{}構文でプロパティを定義している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaClientAlias.ps1 | `public/Get-DbaClientAlias.ps1` | 関数全体の構造（begin/process） |

**主要処理フロー**:
1. **72-128行目**: begin ブロック - スクリプトブロックの定義
2. **73-127行目**: スクリプトブロック内でレジストリアクセス処理を定義
3. **84行目**: 32ビットと64ビットのベースキー定義
4. **86-126行目**: 各レジストリパスをチェックしてエイリアスを取得

#### Step 3: リモート実行を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaClientAlias.ps1 | `public/Get-DbaClientAlias.ps1` | 129-136行目のprocess ブロック |

**主要処理フロー**:
- **131-132行目**: Invoke-Command2でリモートまたはローカルのスクリプトブロック実行

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

```
Get-DbaClientAlias
    │
    ├─ begin (スクリプトブロック定義)
    │      │
    │      ├─ Test-Path (レジストリパス確認)
    │      ├─ Get-Item (レジストリキー取得)
    │      └─ Get-ItemPropertyValue (レジストリ値取得)
    │
    └─ process
           └─ Invoke-Command2 (リモート実行)
                  └─ スクリプトブロック実行
```

### データフロー図

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

ComputerName   ───▶ Invoke-Command2     ───▶ リモート接続
                           │
                           ▼
                    レジストリアクセス
                    (32-bit & 64-bit)
                           │
                           ▼
                    エイリアス解析
                    (プロトコル識別)
                           │
                           ▼
                    PSCustomObject  ───▶ エイリアス情報
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaClientAlias.ps1 | `public/Get-DbaClientAlias.ps1` | ソース | メイン機能実装 |
| Invoke-Command2.ps1 | `private/functions/Invoke-Command2.ps1` | ソース | リモートコマンド実行 |
