# 画面設計書 51-Service Broker

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるService Broker管理機能の設計仕様を記載したものです。Service Brokerのキューおよびサービスの情報取得機能を提供します。

### 本画面の処理概要

本機能は、SQL ServerのService Broker構成情報を取得・監査するためのPowerShellコマンド群を提供します。Service Brokerは、SQL Server内部および外部アプリケーション間の信頼性の高い非同期メッセージング基盤であり、本機能によりDBAはその構成状態を効率的に把握できます。

**業務上の目的・背景**：Service Brokerは、SQL Serverの分散アプリケーション開発において重要な役割を果たすメッセージキューイングシステムです。データベース管理者は、アプリケーションのメッセージング設定を監査し、問題のトラブルシューティングを行い、コンプライアンスや移行計画のためにメッセージング構成を文書化する必要があります。本機能は、これらの管理タスクを自動化し、複数インスタンス・データベースにわたるService Broker構成の一元的な可視化を実現します。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします:
- `Get-DbaDbServiceBrokerQueue` - Service Brokerキューの取得
- `Get-DbaDbServiceBrokerService` - Service Brokerサービスの取得

**主要な操作・処理内容**：
1. SQL Serverインスタンスへの接続確立
2. 指定データベースのService Brokerキュー/サービス情報の列挙
3. システムオブジェクトのフィルタリング（オプション）
4. 結果オブジェクトへのインスタンス情報の付加
5. デフォルト表示プロパティの選択と出力

**画面遷移**：本機能はCLIコマンドであり、他のdbatools機能との連携が可能です。Get-DbaDatabase からパイプライン入力を受け取ることができ、取得した情報は他のコマンドへパイプで渡すことができます。

**権限による表示制御**：Service Broker情報へのアクセスには、対象データベースへの接続権限およびService Brokerメタデータの参照権限が必要です。データベースがアクセス不可の場合、警告メッセージが表示されスキップされます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 109 | Get-DbaDbServiceBrokerQueue | 主機能 | Service Brokerキューの取得 |
| 110 | Get-DbaDbServiceBrokerService | 補助機能 | Service Brokerサービスの取得 |

## 画面種別

一覧取得（CLI出力）

## URL/ルーティング

PowerShellコマンドとして以下のコマンドレット名でアクセス:
- `Get-DbaDbServiceBrokerQueue`
- `Get-DbaDbServiceBrokerService`

## 入出力項目

### Get-DbaDbServiceBrokerQueue パラメータ

| パラメータ名 | 必須 | 型 | 説明 |
|-------------|------|-----|------|
| SqlInstance | No | DbaInstanceParameter[] | 対象SQL Serverインスタンス |
| SqlCredential | No | PSCredential | 認証用資格情報 |
| Database | No | object[] | 対象データベース（ワイルドカード対応） |
| ExcludeDatabase | No | object[] | 除外データベース |
| ExcludeSystemQueue | No | switch | システムキューを除外 |
| EnableException | No | switch | 例外を有効化 |

### Get-DbaDbServiceBrokerService パラメータ

| パラメータ名 | 必須 | 型 | 説明 |
|-------------|------|-----|------|
| SqlInstance | No | DbaInstanceParameter[] | 対象SQL Serverインスタンス |
| SqlCredential | No | PSCredential | 認証用資格情報 |
| Database | No | object[] | 対象データベース |
| ExcludeDatabase | No | object[] | 除外データベース |
| ExcludeSystemService | No | switch | システムサービスを除外 |
| EnableException | No | switch | 例外を有効化 |

## 表示項目

### Get-DbaDbServiceBrokerQueue 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLサーバーインスタンス名 |
| SqlInstance | string | フルインスタンス名 |
| Database | string | データベース名 |
| Schema | string | キューのスキーマ |
| QueueID | int | キューのオブジェクトID |
| CreateDate | DateTime | 作成日時 |
| DateLastModified | DateTime | 最終更新日時 |
| Name | string | キュー名 |
| ProcedureName | string | アクティベーションプロシージャ名 |
| ProcedureSchema | string | アクティベーションプロシージャのスキーマ |

### Get-DbaDbServiceBrokerService 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLサーバーインスタンス名 |
| SqlInstance | string | フルインスタンス名 |
| Database | string | データベース名 |
| Owner | string | サービスの所有者 |
| ServiceID | int | サービスのオブジェクトID |
| Name | string | サービス名 |
| QueueSchema | string | 関連キューのスキーマ |
| QueueName | string | 関連キュー名 |

## イベント仕様

### 1-キュー情報取得

1. `Get-DbaDatabase`を使用してデータベース情報を取得
2. 各データベースのアクセス可能性をチェック
3. `$db.ServiceBroker.Queues`コレクションからキュー情報を列挙
4. `ExcludeSystemQueue`指定時はシステムオブジェクトをフィルタ
5. インスタンス情報をNotePropertyとして付加
6. `Select-DefaultView`でデフォルト表示プロパティを適用

### 2-サービス情報取得

1. `Get-DbaDatabase`を使用してデータベース情報を取得
2. 各データベースのアクセス可能性をチェック
3. `$db.ServiceBroker.Services`コレクションからサービス情報を列挙
4. `ExcludeSystemService`指定時はシステムオブジェクトをフィルタ
5. インスタンス情報をNotePropertyとして付加
6. `Select-DefaultView`でデフォルト表示プロパティを適用

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaDbServiceBrokerQueue | sys.service_queues | SELECT | キュー情報の読み取り（SMO経由） |
| Get-DbaDbServiceBrokerService | sys.services | SELECT | サービス情報の読み取り（SMO経由） |

### テーブル別更新項目詳細

本機能は読み取り専用であり、データベースの更新は行いません。SMO経由でService Brokerメタデータを参照します。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| MSG-001 | 警告 | Database $db is not accessible. Skipping. | データベースにアクセスできない場合 |
| MSG-002 | 情報 | No Service Broker Queues exist in the $db database on $instance | キューが存在しない場合 |
| MSG-003 | 情報 | No Service Broker Services exist in the $db database on $instance | サービスが存在しない場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| データベースアクセス不可 | 警告メッセージを出力し、当該データベースをスキップ |
| Service Brokerオブジェクトなし | 情報メッセージを出力し、次のデータベースへ処理を継続 |
| 接続エラー | EnableException指定時は例外をスロー、未指定時は警告メッセージ |

## 備考

- Service Brokerはバージョン8（SQL Server 2000）では利用不可、SQL Server 2005以降で利用可能
- システムキュー/サービスはSQL Serverが内部使用のために自動作成するオブジェクト
- 本機能は読み取り専用であり、Service Broker構成の変更機能は提供しない

---

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

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

### 推奨読解順序

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

Service Broker関連のSMOオブジェクト構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SMO ServiceBrokerQueue | Microsoft.SqlServer.Management.Smo | キュープロパティ（Name, Schema, ProcedureName等） |
| 1-2 | SMO ServiceBrokerService | Microsoft.SqlServer.Management.Smo | サービスプロパティ（Name, QueueName等） |

**読解のコツ**: SMOのServiceBrokerオブジェクトはDatabaseオブジェクトのServiceBrokerプロパティからアクセスします。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbServiceBrokerQueue.ps1 | `public/Get-DbaDbServiceBrokerQueue.ps1` | キュー取得のメインロジック |
| 2-2 | Get-DbaDbServiceBrokerService.ps1 | `public/Get-DbaDbServiceBrokerService.ps1` | サービス取得のメインロジック |

**主要処理フロー (Get-DbaDbServiceBrokerQueue)**:
1. **行108-110**: SqlInstance指定時にGet-DbaDatabase経由でデータベースオブジェクト取得
2. **行112-120**: データベースのアクセス可能性チェックとキュー存在確認
3. **行122-134**: キューの列挙、フィルタリング、プロパティ付加、出力

#### Step 3: 共通処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | データベースオブジェクト取得 |
| 3-2 | Select-DefaultView | 内部関数 | デフォルト表示プロパティの選択 |

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

```
Get-DbaDbServiceBrokerQueue
    |
    +-- Get-DbaDatabase (SqlInstance指定時)
    |       |
    |       +-- Connect-DbaInstance
    |
    +-- $db.ServiceBroker.Queues (SMOアクセス)
    |
    +-- Add-Member (プロパティ付加)
    |
    +-- Select-DefaultView (出力整形)

Get-DbaDbServiceBrokerService
    |
    +-- Get-DbaDatabase (SqlInstance指定時)
    |       |
    |       +-- Connect-DbaInstance
    |
    +-- $db.ServiceBroker.Services (SMOアクセス)
    |
    +-- Add-Member (プロパティ付加)
    |
    +-- Select-DefaultView (出力整形)
```

### データフロー図

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

SqlInstance      ------>  Connect-DbaInstance
                                |
                                v
Database/        ------>  Get-DbaDatabase
ExcludeDatabase               |
                              v
                         ServiceBroker
                         .Queues/.Services
                              |
ExcludeSystemQueue/  ------->|
ExcludeSystemService        v
                         フィルタリング
                              |
                              v
                         Add-Member
                         (インスタンス情報付加)
                              |
                              v
                         Select-DefaultView  ----->  ServiceBrokerQueue/
                                                     ServiceBrokerService
                                                     オブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbServiceBrokerQueue.ps1 | `public/Get-DbaDbServiceBrokerQueue.ps1` | ソース | キュー情報取得コマンド |
| Get-DbaDbServiceBrokerService.ps1 | `public/Get-DbaDbServiceBrokerService.ps1` | ソース | サービス情報取得コマンド |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
