# 機能設計書 351-Test-DbaLinkedServerConnection

## 概要

本ドキュメントは、SQL Serverインスタンス上に構成されたリンクサーバーの接続テストを行う `Test-DbaLinkedServerConnection` コマンドの機能設計書である。

### 本機能の処理概要

本機能は、指定されたSQL Serverインスタンス上のすべてのリンクサーバーに対して接続テストを実行し、各リンクサーバーの接続状態を検証する。

**業務上の目的・背景**：分散クエリやデータ連携を行う環境では、リンクサーバーの可用性が業務継続性に直結する。リンクサーバー構成後の初期検証、定期的なヘルスチェック、障害発生時のトラブルシューティングにおいて、接続状態を迅速に確認する必要がある。本機能により、複数のリンクサーバーの状態を一括で検証でき、運用効率が向上する。

**機能の利用シーン**：
- リンクサーバー構成直後の接続確認
- 定期メンテナンス時のヘルスチェック
- クロスサーバークエリ失敗時の原因切り分け
- ネットワーク変更後の疎通確認

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続を確立
2. インスタンス上のリンクサーバーコレクションを取得
3. 各リンクサーバーに対してSMOのTestConnection()メソッドを実行
4. 接続結果（成功/失敗）とエラー詳細を収集し、オブジェクトとして出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) を使用してリンクサーバーの接続テストを実行する。リンクサーバーの接続先はSQL Server、Oracle、OLE DBプロバイダー経由の各種データソースを含む。

**権限による制御**：リンクサーバーの情報取得にはサーバーレベルの参照権限が必要。接続テスト実行にはリンクサーバーへのアクセス権限が必要となる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | PowerShellコンソール | 主画面 | コマンド実行および結果表示 |

## 機能種別

データ検証 / 接続テスト

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス。パイプライン入力可能 | DbaInstance型への変換 |
| SqlCredential | PSCredential | No | 代替認証情報。SQL認証、Windows認証、AD認証対応 | 有効な資格情報オブジェクト |
| EnableException | Switch | No | 例外を直接スローするか、警告メッセージとして処理するかの制御 | - |

### 入力データソース

- パイプライン経由でのSqlInstanceオブジェクト入力
- Get-DbaLinkedServer からの出力オブジェクト（LinkedLiveプロパティを持つオブジェクト）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverが稼働するコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なSQL Serverインスタンス名（computer\instance形式） |
| Name | String | リンクサーバー名 |
| DataSource | String | リンクサーバーのデータソースまたは接続文字列 |
| Connectivity | Boolean | 接続テスト結果（true: 成功、false: 失敗） |
| Result | String | 接続テスト結果メッセージ（"Success" または エラー詳細） |

### 出力先

- PowerShellパイプライン（PSCustomObject）
- 型名: Dataplat.Dbatools.Validation.LinkedServerResult

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstanceパラメータの必須チェック

2. インスタンスループ処理開始
   └─ 各SqlInstanceに対して以下を実行

3. リンクサーバーコレクション取得
   ├─ LinkedLiveプロパティがある場合: パイプライン入力からLinkedServerを取得
   └─ それ以外: Connect-DbaInstanceで接続し、LinkedServersプロパティを取得

4. 各リンクサーバーに対するテスト実行
   ├─ TestConnection()メソッドを呼び出し
   ├─ 成功時: result = "Success", connectivity = true
   └─ 失敗時: エラーメッセージを取得, connectivity = false

5. 結果オブジェクト生成・出力
   └─ LinkedServerResultオブジェクトをパイプラインに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SqlInstanceを順次処理]
    B --> C{LinkedLiveプロパティあり?}
    C -->|Yes| D[パイプラインからLinkedServer取得]
    C -->|No| E[Connect-DbaInstanceで接続]
    E --> F{接続成功?}
    F -->|No| G[エラー出力して次へ]
    F -->|Yes| H[LinkedServers取得]
    D --> I[各LinkedServerをテスト]
    H --> I
    I --> J[TestConnection実行]
    J --> K{テスト成功?}
    K -->|Yes| L[Result = Success]
    K -->|No| M[エラーメッセージ取得]
    L --> N[LinkedServerResultオブジェクト生成]
    M --> N
    N --> O{次のLinkedServerあり?}
    O -->|Yes| I
    O -->|No| P{次のInstanceあり?}
    P -->|Yes| B
    P -->|No| Q[終了]
    G --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パイプライン入力対応 | LinkedLiveプロパティを持つオブジェクトは直接LinkedServerを参照 | Get-DbaLinkedServerからのパイプライン入力時 |
| BR-002 | 接続エラー継続 | インスタンス接続失敗時は警告を出力して次のインスタンスに進む | 複数インスタンス指定時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| リンクサーバーテスト | sys.servers | SELECT (SMO経由) | リンクサーバー情報取得 |

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

#### sys.servers (SMO経由)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | is_linked = 1 | リンクサーバーのみ取得 | SMO LinkedServersコレクション |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverインスタンスへの接続失敗 | Stop-Functionで警告、次のインスタンスへ継続 |
| TestConnectionFailed | テストエラー | リンクサーバーへの接続テスト失敗 | 内部例外メッセージを結果に格納 |

### リトライ仕様

リトライ処理は実装されていない。接続エラー発生時は結果オブジェクトにエラー情報を格納して処理継続。

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

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

## パフォーマンス要件

- 各リンクサーバーのTestConnection()は同期実行
- 大量のリンクサーバーが存在する場合は順次処理となる

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

- SqlCredentialパラメータによる代替認証のサポート
- Windows認証、SQL認証、Active Directory認証に対応
- リンクサーバーへのアクセス権限が必要

## 備考

- SQL Server 2000以降で動作
- Express Editionでも利用可能

---

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

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

### 推奨読解順序

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

出力オブジェクトの型定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | LinkedServerResult.cs | `bin/projects/dbatools/dbatools/Validation/LinkedServerResult.cs` | 出力オブジェクトの構造定義 |

**読解のコツ**: C#クラスで定義されたプロパティがPowerShellオブジェクトとして出力される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaLinkedServerConnection.ps1 | `public/Test-DbaLinkedServerConnection.ps1` | 関数全体の処理フロー |

**主要処理フロー**:
1. **77-83行目**: パラメータ定義（SqlInstance, SqlCredential, EnableException）
2. **85-96行目**: インスタンスループとリンクサーバーコレクション取得
3. **98-110行目**: 各リンクサーバーのテスト実行と結果出力

#### Step 3: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Connect-DbaInstance | `public/Connect-DbaInstance.ps1` | SQL Server接続処理 |

**主要処理フロー**:
- Connect-DbaInstanceでSMOサーバーオブジェクトを取得
- LinkedServersプロパティからリンクサーバーコレクションにアクセス

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

```
Test-DbaLinkedServerConnection
    │
    ├─ Connect-DbaInstance
    │      └─ SMO Server接続
    │
    └─ LinkedServer.TestConnection()
           └─ OLE DB接続テスト
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ ServerオブジェクトA
                         │
                         ▼
              LinkedServersコレクション取得
                         │
                         ▼
              各LinkedServer.TestConnection()
                         │
                         ▼
              LinkedServerResultオブジェクト ───▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaLinkedServerConnection.ps1 | `public/Test-DbaLinkedServerConnection.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| LinkedServerResult.cs | `bin/projects/dbatools/dbatools/Validation/` | ソース | 出力型定義 |
