# 機能設計書 184-New-DbaClientAlias

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `New-DbaClientAlias` コマンドレットの機能設計書である。このコマンドレットは、Windowsレジストリに SQL Server クライアントエイリアスを作成し、簡略化された接続管理を実現する機能を提供する。

### 本機能の処理概要

本機能は、SQL Serverクライアントエイリアスをレジストリ（HKLM:\SOFTWARE\Microsoft\MSSQLServer\Client\ConnectTo）に作成または更新する。手動でcliconfg.exeを使用する代わりに、PowerShellから自動的にエイリアスを設定でき、複雑なサーバー名やインスタンス名、カスタムポート番号の代わりにシンプルなエイリアス名を使用して接続できるようになる。

**業務上の目的・背景**：SQL Serverへの接続において、サーバー名変更やポート番号変更が発生した場合、アプリケーションの接続文字列を変更するのは運用負荷が高い。クライアントエイリアスを使用することで、接続先の物理的な変更をアプリケーションから隠蔽し、エイリアス設定の変更のみで対応できる。また、複雑な名前付きインスタンスやカスタムポートを使用している環境では、シンプルなエイリアス名での接続が開発者やDBAの作業効率を向上させる。

**機能の利用シーン**：
- 複数ワークステーションへの標準接続設定の展開
- サーバー移行時の接続先切り替え（アプリケーション変更なし）
- 名前付きインスタンスへのシンプルな接続名の提供
- カスタムポート使用時の接続の簡略化
- 開発環境と本番環境の接続先切り替え

**主要な処理内容**：
1. 対象コンピュータへの管理者権限確認
2. レジストリキー（ConnectTo）の存在確認と作成
3. プロトコルに応じた接続文字列の構築
4. レジストリへのエイリアス登録（32ビット/64ビット両対応）
5. 作成されたエイリアスの取得と返却

**関連システム・外部連携**：Windowsレジストリ、SQL Server Native Client、Invoke-Command2によるリモート実行

**権限による制御**：HKLMレジストリへの書き込みには管理者権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 139 | クライアントエイリアス | 主機能 | クライアントエイリアスの作成 |

## 機能種別

構成管理 / レジストリ操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | エイリアスを作成するコンピュータ | デフォルトはローカルコンピュータ |
| Credential | PSCredential | No | リモートコンピュータへのログイン資格情報 | - |
| ServerName | DbaInstanceParameter | Yes | エイリアスが指すSQL Serverインスタンス | パイプラインから入力可能、必須 |
| Alias | string | Yes | 作成するエイリアス名 | 必須 |
| Protocol | string | No | ネットワークプロトコル（TCPIP/NamedPipes） | ValidateSet、デフォルトはTCPIP |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- ユーザー入力（パラメータ指定）
- パイプライン入力（ServerName）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | エイリアスが作成されたコンピュータ名 |
| AliasName | string | 作成されたエイリアス名 |
| ServerName | string | エイリアスが指すSQL Serverインスタンス |
| Protocol | string | 使用されるネットワークプロトコル |
| InstanceName | string | インスタンス名（存在する場合） |
| PipeName | string | NamedPipesプロトコルのパイプ名 |
| Port | int | TCPポート番号（指定されている場合） |

### 出力先

PowerShellパイプライン（Get-DbaClientAliasの戻り値）

## 処理フロー

### 処理シーケンス

```
1. beginブロック処理
   └─ スクリプトブロックの定義（リモート実行用）
2. processブロック処理
   └─ プロトコルに応じたサーバー文字列の構築
3. 各コンピュータへの処理ループ
   └─ 管理者権限の確認（Test-ElevationRequirement）
4. ShouldProcess確認
5. リモートコマンド実行（Invoke-Command2）
   └─ レジストリベースキーの確認/作成
   └─ 32ビット/64ビット両方のレジストリに登録
6. 結果取得
   └─ Get-DbaClientAliasで作成されたエイリアスを取得
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Protocol = TCPIP?}
    B -->|Yes| C["serverstring = DBMSSOCN,ServerName"]
    B -->|No| D["serverstring = DBNMPNTW,\\ServerName\pipe\sql\query"]
    C --> E[各コンピュータを処理]
    D --> E
    E --> F[Test-ElevationRequirement]
    F --> G{管理者権限あり?}
    G -->|No| H[Continue]
    G -->|Yes| I{ShouldProcess?}
    I -->|No| J[スキップ]
    I -->|Yes| K[Invoke-Command2]
    K --> L[レジストリキー確認/作成]
    L --> M[New-ItemProperty でエイリアス登録]
    M --> N[Get-DbaClientAlias でフィルタ]
    N --> O[結果出力]
    J --> O
    H --> O
    O --> P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 管理者権限必須 | HKLMレジストリへの書き込みには管理者権限が必要 | 常時 |
| BR-002 | 既存エイリアス上書き | 同名のエイリアスが存在する場合は上書き | 常時（-Force不要） |
| BR-003 | 32/64ビット両対応 | 64ビット環境では両方のレジストリに登録 | 64ビット環境時 |
| BR-004 | プロトコル形式 | TCPIPはDBMSSOCN、NamedPipesはDBNMPNTW | Protocol指定時 |

### 計算ロジック

| Protocol | ServerString形式 |
|----------|-----------------|
| TCPIP | DBMSSOCN,{ServerName} |
| NamedPipes | DBNMPNTW,\\\\{ServerName}\\pipe\\sql\\query |

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

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

本機能はレジストリ操作のみを行い、直接的なデータベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 権限不足 | 管理者権限なしでHKLMに書き込み試行 | 管理者として実行 |
| - | リモート接続失敗 | リモートコンピュータへの接続失敗 | ネットワーク確認、資格情報確認 |
| - | レジストリアクセス失敗 | レジストリキーの作成/書き込み失敗 | 権限確認、ポリシー確認 |

### リトライ仕様

リトライ処理は実装されていない。

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

レジストリ操作はトランザクション非対応。32ビットと64ビットのレジストリへの書き込みは独立して実行される。

## パフォーマンス要件

- ローカル実行は即座に完了
- リモート実行はネットワーク遅延に依存

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

- HKLMレジストリへの書き込みには管理者権限が必要
- リモート実行にはPSRemotingが有効である必要あり
- 資格情報はPSCredentialで安全に管理
- レジストリ変更はシステム全体に影響

## 備考

- 作成されたエイリアスはすべてのアプリケーションで使用可能
- SQL Server Management Studio、SQLCMD、ADO.NETなどで共通して使用
- WOW6432Nodeは32ビットアプリケーション用

---

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

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

### 推奨読解順序

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

パラメータ定義とスクリプトブロックの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaClientAlias.ps1 | `public/New-DbaClientAlias.ps1` | 87-98行目のparamブロック |

**読解のコツ**: ServerNameはパイプラインから入力可能でMandatory。ProtocolはValidateSetで制限されデフォルトはTCPIP。

#### Step 2: スクリプトブロックを理解する

リモート実行用のスクリプトブロックを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaClientAlias.ps1 | `public/New-DbaClientAlias.ps1` | 100-141行目のbeginブロック内スクリプトブロック |

**主要処理フロー**:
1. **103行目**: レジストリベースキーの定義（通常とWOW6432Node）
2. **109行目**: プロセッサアーキテクチャによる64ビット判定
3. **111-126行目**: レジストリキーの存在確認と作成
4. **139行目**: New-ItemPropertyでエイリアスを登録

#### Step 3: メイン処理を理解する

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

**主要処理フロー**:
- **145-148行目**: Protocolに応じたserverstring構築
- **153行目**: Test-ElevationRequirementで管理者権限確認
- **157行目**: Invoke-Command2でスクリプトブロック実行
- **163行目**: Get-DbaClientAliasで結果取得

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

```
New-DbaClientAlias
    │
    ├─ Test-ElevationRequirement
    │      └─ 管理者権限の確認
    │
    ├─ Invoke-Command2
    │      └─ $scriptBlock（リモート/ローカル実行）
    │             ├─ Test-Path（レジストリキー確認）
    │             ├─ New-Item（レジストリキー作成）
    │             └─ New-ItemProperty（エイリアス登録）
    │
    └─ Get-DbaClientAlias
           └─ 作成されたエイリアスの取得・返却
```

### データフロー図

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

ServerName ───────────▶ serverstring構築
Protocol ─────────────▶ (DBMSSOCN/DBNMPNTW)
Alias ─────────────────────────────────────────────────▶ レジストリキー名
                              │
                              ▼
ComputerName ─────────▶ Invoke-Command2
                              │
                              ▼
                       レジストリ書き込み
                       (HKLM:\...\ConnectTo)
                              │
                              ▼
                       Get-DbaClientAlias ─────────────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaClientAlias.ps1 | `public/New-DbaClientAlias.ps1` | ソース | メイン機能の実装 |
| Get-DbaClientAlias.ps1 | `public/Get-DbaClientAlias.ps1` | ソース | エイリアス取得 |
| Remove-DbaClientAlias.ps1 | `public/Remove-DbaClientAlias.ps1` | ソース | エイリアス削除 |
| Invoke-Command2.ps1 | `private/functions/Invoke-Command2.ps1` | ソース | リモートコマンド実行 |
| Test-ElevationRequirement.ps1 | `private/functions/Test-ElevationRequirement.ps1` | ソース | 管理者権限確認 |
