# 機能設計書 348-Get-DbaLinkedServer

## 概要

本ドキュメントは、dbatools PowerShellモジュールのGet-DbaLinkedServer関数の機能設計書である。この関数はSQL Serverインスタンスからリンクサーバー構成と接続詳細を取得する。

### 本機能の処理概要

Get-DbaLinkedServer関数は、1つ以上のSQL Serverインスタンスからリンクサーバー情報を取得し、リモートサーバー名、認証方法、セキュリティ設定などの詳細を提供する。

**業務上の目的・背景**：分散データベースアーキテクチャでは、サーバー間接続の監査、接続問題のトラブルシューティング、コンプライアンスレポートの作成が必要である。この関数は、リンクサーバー構成を迅速に確認し、環境全体の接続状況を把握することを支援する。

**機能の利用シーン**：リンクサーバー構成を監査する場合、接続問題をトラブルシューティングする場合、分散データベースアーキテクチャをドキュメント化する場合、環境のインベントリを作成する場合に使用される。

**主要な処理内容**：
1. SQL Serverインスタンスに接続する
2. サーバーのLinkedServersコレクションを取得する
3. 指定されたフィルタを適用する
4. 追加プロパティ（ComputerName、InstanceName、Impersonate、RemoteUser）を付与する
5. 結果を出力する

**関連システム・外部連携**：SQL Server SMO (LinkedServersコレクション)。

**権限による制御**：リンクサーバー情報を読み取るための適切なSQL Server権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主機能 | PowerShellコマンドラインから直接実行 |

## 機能種別

データ取得（リンクサーバー構成の読み取り）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス | 有効なSQL Serverインスタンス名 |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | 有効なPSCredentialオブジェクト |
| LinkedServer | object[] | No | 取得対象のリンクサーバー名 | リンクサーバー名の配列 |
| ExcludeLinkedServer | object[] | No | 除外するリンクサーバー名 | リンクサーバー名の配列 |
| EnableException | switch | No | 例外処理の動作を制御 | true/false |

### 入力データソース

- SqlInstance: SQL Serverインスタンス指定
- パイプライン入力: ValueFromPipelineによる複数インスタンスの入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | リンクサーバー名 |
| RemoteServer (DataSource) | string | リモートサーバー名またはデータソース |
| ProductName | string | リモートデータソースの製品タイプ |
| Impersonate | boolean/collection | 偽装が有効かどうか |
| RemoteUser | string | リモートユーザーログイン |
| Publisher (DistPublisher) | string | 配布パブリッシャー |
| Distributor | string | ディストリビューターサーバー |
| DateLastModified | DateTime | 最終変更日時 |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.LinkedServer）

## 処理フロー

### 処理シーケンス

```
1. SQL Server接続
   └─ Connect-DbaInstanceで接続

2. リンクサーバー取得
   └─ $server.LinkedServersコレクションを取得

3. フィルタリング
   ├─ LinkedServer指定時: 名前でフィルタ
   └─ ExcludeLinkedServer指定時: 除外フィルタ

4. プロパティ追加
   ├─ ComputerName
   ├─ InstanceName
   ├─ SqlInstance
   ├─ Impersonate (LinkedServerLogins.Impersonate)
   └─ RemoteUser (LinkedServerLogins.RemoteUser)

5. デフォルトビューで出力
   └─ Select-DefaultViewで表示プロパティを設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance]
    B --> C{接続成功?}
    C -->|No| D[エラー出力]
    C -->|Yes| E[LinkedServersコレクション取得]
    E --> F{LinkedServer指定?}
    F -->|Yes| G[名前でフィルタ]
    F -->|No| H[全リンクサーバー]
    G --> I{ExcludeLinkedServer指定?}
    H --> I
    I -->|Yes| J[除外フィルタ]
    I -->|No| K[各リンクサーバーループ]
    J --> K
    K --> L[Add-Memberでプロパティ追加]
    L --> M[Select-DefaultViewで出力]
    M --> N{次のリンクサーバー?}
    N -->|Yes| K
    N -->|No| O[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 複数インスタンスサポート | 配列またはパイプラインで複数インスタンスを処理 | 常に適用 |
| BR-002 | LinkedServerフィルタ | 指定された名前のみを返す | LinkedServer指定時 |
| BR-003 | ExcludeLinkedServerフィルタ | 指定された名前を除外 | ExcludeLinkedServer指定時 |
| BR-004 | 追加プロパティ | SMOオブジェクトにComputerName等を追加 | 常に適用 |
| BR-005 | デフォルトビュー | 指定されたプロパティのみをデフォルト表示 | 常に適用 |

### 計算ロジック

該当なし

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

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

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

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

該当なし（SMO経由の読み取り専用アクセス）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続失敗 | SQL Serverへの接続失敗 | 接続設定を確認 |
| - | 権限不足 | リンクサーバー情報の読み取り権限がない | 適切な権限を付与 |

### リトライ仕様

明示的なリトライ機能はなし。

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

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

## パフォーマンス要件

- SMOのLinkedServersコレクションは接続時に遅延読み込みされる
- 大量のリンクサーバーがある場合は処理時間が増加

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

- 読み取り専用操作のためセキュリティリスクは低い
- リンクサーバーのパスワードは取得されない
- 適切なSQL Server権限が必要

## 備考

- Get-DbaRegServerとの組み合わせで複数サーバーを一括処理可能
- Export-DbaLinkedServerやCopy-DbaLinkedServerへのパイプライン入力として使用可能
- SMOのLinkedServerオブジェクトをそのまま返すため、追加プロパティも利用可能

---

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

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

### 推奨読解順序

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

出力されるLinkedServerオブジェクトの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaLinkedServer.ps1 | `public/Get-DbaLinkedServer.ps1` | 111-119行目のプロパティ追加と出力フォーマットを確認 |

**読解のコツ**: Add-Memberで追加されるプロパティと、Select-DefaultViewで指定されるデフォルト表示プロパティを確認する。

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

関数の入口と主要パラメータを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaLinkedServer.ps1 | `public/Get-DbaLinkedServer.ps1` | 85-93行目のパラメータ定義を確認 |

**主要処理フロー**:
1. **85-93行目**: param()ブロックでパラメータ定義
2. **87-88行目**: SqlInstanceはValueFromPipelineでパイプライン入力をサポート

#### Step 3: 処理ロジックを理解する

processブロック内の主要処理を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaLinkedServer.ps1 | `public/Get-DbaLinkedServer.ps1` | 94-121行目のprocess{}ブロック |

**主要処理フロー**:
- **95-100行目**: Connect-DbaInstanceで接続
- **102行目**: LinkedServersコレクション取得
- **104-108行目**: LinkedServer/ExcludeLinkedServerフィルタリング
- **111-117行目**: Add-Memberでプロパティ追加
- **118行目**: Select-DefaultViewで出力

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

```
Get-DbaLinkedServer
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続
    │
    ├─ $server.LinkedServers
    │      └─ SMO LinkedServersコレクション取得
    │
    ├─ Where-Object
    │      └─ フィルタリング
    │
    ├─ Add-Member
    │      └─ 追加プロパティ付与
    │
    └─ Select-DefaultView
           └─ デフォルト表示設定
```

### データフロー図

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

SqlInstance ──────▶ Connect-DbaInstance ──▶ 接続
                          │
                          ▼
                   $server.LinkedServers ──▶ コレクション
                          │
LinkedServer ────▶ Where-Object ──▶ フィルタリング
ExcludeLinkedServer ──┘   │
                          ▼
                   Add-Member ──▶ プロパティ追加
                          │
                          ▼
                   Select-DefaultView ──▶ LinkedServerオブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaLinkedServer.ps1 | `public/Get-DbaLinkedServer.ps1` | ソース | メイン関数 |
| New-DbaLinkedServer.ps1 | `public/New-DbaLinkedServer.ps1` | ソース | リンクサーバー作成関数 |
| Remove-DbaLinkedServer.ps1 | `public/Remove-DbaLinkedServer.ps1` | ソース | リンクサーバー削除関数 |
| Export-DbaLinkedServer.ps1 | `public/Export-DbaLinkedServer.ps1` | ソース | パイプライン出力先として使用可能 |
| Copy-DbaLinkedServer.ps1 | `public/Copy-DbaLinkedServer.ps1` | ソース | 関連するコピー関数 |
