# 画面設計書 139-クライアントエイリアス

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverクライアントエイリアス管理機能の設計仕様を定義する。

### 本画面の処理概要

SQL Serverクライアントエイリアスの取得、作成、削除を行う機能群を提供する。

**業務上の目的・背景**：クライアントエイリアスは、実際のSQL Serverインスタンス名やポート番号を抽象化し、簡易な名前で接続できるようにする機能である。サーバー移行時に接続文字列を変更せずに新サーバーへリダイレクトしたり、カスタムポートを使用するインスタンスへの接続を簡素化したりする場合に使用される。本機能は、cliconfg.exe（SQL Server Client Network Utility）をコマンドラインから操作可能にし、複数ワークステーションへの一括設定や構成管理自動化を実現する。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスする
- `Get-DbaClientAlias` - クライアントエイリアスの取得
- `New-DbaClientAlias` - クライアントエイリアスの作成
- `Remove-DbaClientAlias` - クライアントエイリアスの削除

**主要な操作・処理内容**：
1. 32ビット・64ビット両方のレジストリからエイリアス情報を取得
2. TCP/IPまたはNamed Pipesプロトコルでエイリアスを作成
3. 既存のエイリアスを削除

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

**権限による表示制御**：Windows管理者権限が必要（レジストリHKLMへのアクセス）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 92 | Get-DbaClientAlias | 主機能 | クライアントエイリアスの取得 |
| 184 | New-DbaClientAlias | 主機能 | クライアントエイリアスの作成 |
| 200 | Remove-DbaClientAlias | 主機能 | クライアントエイリアスの削除 |
| - | Invoke-Command2 | 補助機能 | リモートコマンド実行 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

### Get-DbaClientAlias

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

### New-DbaClientAlias

| 項目名 | データ型 | 必須 | 説明 |
|--------|----------|------|------|
| ComputerName | DbaInstanceParameter[] | いいえ | 対象コンピュータ（デフォルト: ローカルコンピュータ） |
| Credential | PSCredential | いいえ | 接続に使用するWindows資格情報 |
| ServerName | DbaInstanceParameter | はい | エイリアスが指す実際のサーバー名/インスタンス |
| Alias | string | はい | 作成するエイリアス名 |
| Protocol | string | いいえ | プロトコル（TCPIP/NamedPipes）デフォルト: TCPIP |
| EnableException | switch | いいえ | 例外を直接発生させるかどうか |
| WhatIf | switch | いいえ | 実行予定の操作を表示 |
| Confirm | switch | いいえ | 実行前に確認を求める |

### Remove-DbaClientAlias

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

## 表示項目

### Get-DbaClientAlias 出力

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ComputerName | string | エイリアスが設定されているコンピュータ名 |
| NetworkLibrary | string | ネットワークプロトコル（TCP/IP または Named Pipes） |
| ServerName | string | エイリアスが指す実際のサーバー名（プロトコルプレフィックス除去済み） |
| AliasName | string | エイリアス名 |
| AliasString | string | 完全なレジストリ値（プロトコルプレフィックス付き） |
| Architecture | string | レジストリのアーキテクチャ（32-bit または 64-bit） |

### Remove-DbaClientAlias 出力

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ComputerName | string | エイリアスが削除されたコンピュータ名 |
| Architecture | string | レジストリのアーキテクチャ |
| Alias | string | 削除されたエイリアス名 |
| Status | string | 結果ステータス（"Removed"） |

## イベント仕様

### 1-Get-DbaClientAlias実行

1. 各コンピュータに対してInvoke-Command2でリモートスクリプトブロックを実行
2. 32ビット（WOW6432Node）と64ビットのレジストリパスを検索
3. HKLM:\SOFTWARE\Microsoft\MSSQLServer\Client\ConnectTo から値を取得
4. DBMSSOCNプレフィックスはTCP/IP、DBNMPNTWプレフィックスはNamed Pipesと判定
5. プロトコルプレフィックスを除去したServerNameと元のAliasStringを返却

### 2-New-DbaClientAlias実行

1. Protocolパラメータに基づいてserverstring を構築
   - TCPIP: "DBMSSOCN,{ServerName}"
   - NamedPipes: "DBNMPNTW,\\{ServerName}\pipe\sql\query"
2. Test-ElevationRequirementで管理者権限を確認
3. ShouldProcess確認後、リモートスクリプトブロックを実行
4. 32ビット・64ビット両方のレジストリに対して処理
5. Clientキー、ConnectToキーが存在しない場合は作成
6. New-ItemPropertyでエイリアスを登録
7. Get-DbaClientAliasで作成されたエイリアスを返却

### 3-Remove-DbaClientAlias実行

1. Test-ElevationRequirementで管理者権限を確認
2. ShouldProcess確認後、リモートスクリプトブロックを実行
3. 32ビット・64ビット両方のレジストリを検索
4. 指定されたエイリアスが存在する場合、Remove-ItemPropertyで削除
5. 削除結果をPSCustomObjectで返却

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

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

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

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| Get-DbaClientAlias | Windowsレジストリ | READ | ConnectToキーからエイリアス読み取り |
| New-DbaClientAlias | Windowsレジストリ | INSERT/UPDATE | エイリアスプロパティの作成/更新 |
| Remove-DbaClientAlias | Windowsレジストリ | DELETE | エイリアスプロパティの削除 |

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

#### HKLM:\SOFTWARE\Microsoft\MSSQLServer\Client\ConnectTo（64-bit）
#### HKLM:\SOFTWARE\WOW6432Node\Microsoft\MSSQLServer\Client\ConnectTo（32-bit）

| 操作 | 項目（プロパティ名） | 値の形式 | 備考 |
|-----|---------------------|----------|------|
| New | {AliasName} | DBMSSOCN,{ServerName} | TCP/IPの場合 |
| New | {AliasName} | DBNMPNTW,\\{ServerName}\pipe\sql\query | Named Pipesの場合 |
| Remove | {AliasName} | (削除) | プロパティを削除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|----------|----------|
| - | Warning | Registry key ({fullKey}) does not exist on {ComputerName} | レジストリキーが存在しない |
| - | Error | Failure | リモートコマンド実行失敗 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| 管理者権限不足 | Test-ElevationRequirementで検出、処理継続 |
| リモート接続失敗 | Stop-Functionでエラー記録、次のコンピュータへ継続 |
| レジストリキー不存在 | 警告表示して処理継続 |

## 備考

- エイリアスは32ビットと64ビットの両方のレジストリに登録される
- TCP/IPエイリアスの形式: "DBMSSOCN,サーバー名,ポート番号"
- Named Pipesエイリアスの形式: "DBNMPNTW,\\サーバー名\pipe\sql\query"
- ServerNameにはインスタンス名（server\instance）やカスタムポート（server,1433）を指定可能
- cliconfg.exe（SQL Server Client Network Utility）と同等の機能を提供
- Get-DbaClientAliasの出力をパイプラインでRemove-DbaClientAliasに渡すことで一括削除が可能

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaClientAlias.ps1 | `public/Get-DbaClientAlias.ps1` | .OUTPUTSセクションで出力プロパティ定義（行33-44） |
| 1-2 | Get-DbaClientAlias.ps1 | `public/Get-DbaClientAlias.ps1` | スクリプトブロック内のPSCustomObject構築（行117-124） |

**読解のコツ**: DBMSSOCNはTCP/IP、DBNMPNTWはNamed Pipesのプロトコルプレフィックス。

#### Step 2: レジストリパスを理解する

エイリアスが保存されるレジストリパスを把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaClientAlias.ps1 | `public/Get-DbaClientAlias.ps1` | basekeys定義（行84） |

**主要処理フロー**:
1. **行84**: 32ビット(WOW6432Node)と64ビットの2つのベースキーを定義
2. **行93-94**: Client キーの存在確認
3. **行99-100**: ConnectTo キーの存在確認

#### Step 3: プロトコル文字列の構築を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaClientAlias.ps1 | `public/New-DbaClientAlias.ps1` | プロトコル文字列の構築（行145-149） |

**主要処理フロー**:
- **行145-146**: TCP/IPの場合は"DBMSSOCN,{ServerName}"
- **行147-148**: Named Pipesの場合は"DBNMPNTW,\\{ServerName}\pipe\sql\query"

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

```
Get-DbaClientAlias
    |
    +-- beginブロック: スクリプトブロック定義
    |       +-- Get-ItemPropertyValue内部関数
    |       +-- レジストリパス定義（32-bit, 64-bit）
    |
    +-- processブロック
            |
            +-- foreach ($computer in $ComputerName)
                    |
                    +-- Invoke-Command2 (スクリプトブロック)
                            +-- 各レジストリパスを検索
                            +-- ConnectToキーからプロパティ取得
                            +-- プロトコル判定とPSCustomObject返却

New-DbaClientAlias
    |
    +-- beginブロック: スクリプトブロック定義
    |
    +-- processブロック
            |
            +-- serverstring構築（TCPIP/NamedPipes）
            |
            +-- foreach ($computer in $ComputerName)
                    |
                    +-- Test-ElevationRequirement
                    |
                    +-- ShouldProcess確認
                    |
                    +-- Invoke-Command2 (スクリプトブロック)
                    |       +-- Clientキー作成（存在しない場合）
                    |       +-- ConnectToキー作成（存在しない場合）
                    |       +-- New-ItemPropertyでエイリアス登録
                    |
                    +-- Get-DbaClientAlias (結果取得)

Remove-DbaClientAlias
    |
    +-- beginブロック: スクリプトブロック定義
    |
    +-- processブロック
            |
            +-- foreach ($computer in $ComputerName)
                    |
                    +-- Test-ElevationRequirement
                    |
                    +-- ShouldProcess確認
                    |
                    +-- Invoke-Command2 (スクリプトブロック)
                            +-- 各レジストリパスを検索
                            +-- エイリアスが存在する場合Remove-ItemProperty
                            +-- PSCustomObject結果返却
```

### データフロー図

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

ComputerName ───────▶ Invoke-Command2 ──────────────▶ リモートスクリプト
    |                       |                              実行
Credential ────────────────▶ |
                            v
                    ┌─────────────────────────┐
                    │   レジストリアクセス     │
                    │   (32-bit + 64-bit)     │
                    │                         │
    [Get] ─────────▶│  Get-ItemProperty      │────▶ PSCustomObject
                    │  各AliasNameを取得      │       (エイリアス情報)
                    │  プロトコル判定         │
                    │                         │
ServerName ────────▶│                         │
Alias ─────────────▶│                         │
Protocol ──────────▶│  serverstring構築       │
    [New] ─────────▶│  New-ItemProperty      │────▶ Get-DbaClientAlias
                    │  32-bit/64-bit両方登録  │       (作成結果)
                    │                         │
Alias ─────────────▶│                         │
    [Remove] ──────▶│  Remove-ItemProperty   │────▶ PSCustomObject
                    │  32-bit/64-bitから削除  │       (削除結果)
                    └─────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaClientAlias.ps1 | `public/Get-DbaClientAlias.ps1` | ソース | クライアントエイリアス取得コマンド |
| New-DbaClientAlias.ps1 | `public/New-DbaClientAlias.ps1` | ソース | クライアントエイリアス作成コマンド |
| Remove-DbaClientAlias.ps1 | `public/Remove-DbaClientAlias.ps1` | ソース | クライアントエイリアス削除コマンド |
