# 機能設計書 694-Get-DbaService

## 概要

本ドキュメントは、ローカルまたはリモートコンピューターからSQL Server関連のWindowsサービス情報を取得するdbatools PowerShellコマンド `Get-DbaService` の機能設計書です。

### 本機能の処理概要

`Get-DbaService` は、1台以上のコンピューターからSQL Server関連のWindowsサービスに関する詳細情報を取得する機能です。Database Engine、SQL Agent、Reporting Services、Analysis Services、Integration Servicesなど、SQL Serverの各コンポーネントのサービス情報を統合的に取得できます。

**業務上の目的・背景**：SQL Server環境において、サービスの状態管理は日常運用の基本です。複数のサーバーにまたがるサービスの状態確認、トラブルシューティング、一括サービス操作など、従来は手動で行っていた作業を自動化・効率化します。返されるサービスオブジェクトにはStart()、Stop()、Restart()、ChangeStartMode()などのメソッドが組み込まれており、別途サービス管理コマンドを使用する必要がありません。

**機能の利用シーン**：
- SQL Server環境のインベントリ管理
- サービス問題のトラブルシューティング
- メンテナンスウィンドウでの複数サーバー一括サービス操作
- サービスアカウントや起動モードの確認・変更
- クラスター環境でのサービス状態確認

**主要な処理内容**：
1. 対象コンピューターへの接続とネットワーク名解決
2. WMI名前空間からSQL Serverサービス情報を取得
3. サービスタイプ、インスタンス名によるフィルタリング
4. サービス状態コードの文字列変換
5. オブジェクトへのスクリプトメソッド追加（Start, Stop, Restart, ChangeStartMode）
6. 拡張プロパティの取得（AdvancedPropertiesスイッチ指定時）

**関連システム・外部連携**：WMI/CIM (root\Microsoft\SQLServer\ComputerManagement名前空間)、SQL Server関連Windowsサービス

**権限による制御**：対象コンピューターでのローカル管理者権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | コマンドライン | 主画面 | PowerShellコンソールからの直接実行 |

## 機能種別

データ取得 / サービス管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | SQL Serverサービスを取得する対象コンピューター。パイプライン入力対応 | 指定なしの場合は$env:COMPUTERNAME |
| InstanceName | string[] | No | 特定のSQL Serverインスタンス名でフィルタリング | Searchパラメータセット |
| SqlInstance | DbaInstanceParameter[] | No | コンピューター名とインスタンス名の組み合わせで指定 | Searchパラメータセット |
| Credential | PSCredential | No | 代替資格情報でコンピューターに接続 | なし |
| Type | string[] | No | サービスタイプでフィルタリング（Agent, Browser, Engine, FullText, SSAS, SSIS, SSRS, PolyBase, Launchpad） | ValidateSet |
| ServiceName | string[] | No | 特定のWindowsサービス名を直接指定 | ServiceNameパラメータセット |
| AdvancedProperties | switch | No | バージョン、SP、SKU名、クラスター情報などの追加プロパティを取得 | なし |
| EnableException | switch | No | 例外を有効にし、try/catchでのキャッチを可能にする | なし |

### 入力データソース

- WMI名前空間 (root\Microsoft\SQLServer\ComputerManagementXX)
- SqlService WMIクラス
- SqlServiceAdvancedProperty WMIクラス（AdvancedProperties指定時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | サービスをホストしているコンピューター名 |
| ServiceName | string | Windowsサービス名（例：MSSQLSERVER, SQLSERVERAGENT） |
| ServiceType | string | サービスタイプ（Engine, Agent, FullText, SSIS, SSAS, SSRS, Browser, PolyBase, Launchpad, Unknown） |
| InstanceName | string | サービスに関連付けられたSQL Serverインスタンス名 |
| DisplayName | string | サービスの表示名 |
| StartName | string | サービスを実行するユーザーアカウント |
| State | string | サービスの現在の状態（Stopped, Start Pending, Stop Pending, Running） |
| StartMode | string | サービスの起動モード（Unknown, Automatic, Manual, Disabled） |

### AdvancedProperties指定時の追加出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Version | string | SQL Serverのバージョン番号 |
| SPLevel | int | サービスパックレベル |
| SkuName | string | SQL ServerエディションSKU名 |
| Clustered | string | クラスター化されているかどうか |
| VSName | string | クラスター化されている場合の仮想サーバー名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名（Engineサービスのみ） |

### 出力先

PowerShellパイプライン (Microsoft.SqlServer.Management.Smo.Wmi.SqlService)

## 処理フロー

### 処理シーケンス

```
1. begin ブロック
   ├─ SqlInstance指定時はComputerNameを抽出
   ├─ ServiceIdMap（サービスタイプID変換用）を定義
   └─ 検索条件句を構築（Type/ServiceNameに基づく）

2. process ブロック
   └─ 各ComputerNameに対してループ
      ├─ Resolve-DbaNetworkName でコンピューター名を解決
      ├─ WMI名前空間の存在確認
      ├─ SSRS以外のType指定時はGet-DbaReportingServiceを呼び出し
      ├─ WMI ComputerManagement名前空間を検索・取得
      ├─ SqlServiceクラスからサービス情報を取得
      ├─ サービスタイプ、状態、起動モードを文字列に変換
      ├─ インスタンス名を解析・設定
      ├─ スクリプトメソッドを追加（Stop, Start, Restart, ChangeStartMode）
      ├─ AdvancedProperties指定時は追加プロパティを取得
      └─ Select-DefaultViewで既定表示プロパティを設定して出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ解析・検索条件構築]
    B --> C{ComputerNameループ}
    C --> D[コンピューター名解決]
    D --> E{解決成功?}
    E -->|No| F[警告出力・スキップ]
    F --> C
    E -->|Yes| G{Type=SSRSまたは未指定?}
    G -->|Yes| H[Get-DbaReportingService呼び出し]
    G -->|No| I[WMI名前空間検索]
    H --> I
    I --> J[SqlServiceクラスからサービス取得]
    J --> K{各サービスループ}
    K --> L[プロパティ変換・追加]
    L --> M{インスタンス名フィルター?}
    M -->|Yes| N{マッチする?}
    N -->|No| K
    N -->|Yes| O[スクリプトメソッド追加]
    M -->|No| O
    O --> P{AdvancedProperties?}
    P -->|Yes| Q[追加プロパティ取得]
    P -->|No| R[出力サービス配列に追加]
    Q --> R
    R --> K
    K --> S[Select-DefaultViewで出力]
    S --> C
    C --> T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 権限要件 | ローカル管理者権限が必要 | 常時 |
| BR-002 | サービスタイプ変換 | SQLServiceTypeをサービスタイプ名に変換 | 常時 |
| BR-003 | 状態変換 | 数値状態コードを文字列に変換（1=Stopped, 2=Start Pending, 3=Stop Pending, 4=Running） | 常時 |
| BR-004 | 起動モード変換 | 数値モードを文字列に変換（1=Unknown, 2=Automatic, 3=Manual, 4=Disabled） | 常時 |
| BR-005 | インスタンス名解析 | サービス名からインスタンス名を抽出（$区切り） | 常時 |
| BR-006 | 名前空間選択 | 最新のComputerManagement名前空間を使用 | 常時 |

### 計算ロジック

サービスタイプID変換マップ:
```powershell
$ServiceIdMap = @(
    @{ Name = "Engine"; Id = 1 },
    @{ Name = "Agent"; Id = 2 },
    @{ Name = "FullText"; Id = 3, 9 },
    @{ Name = "SSIS"; Id = 4 },
    @{ Name = "SSAS"; Id = 5 },
    @{ Name = "SSRS"; Id = 6 },
    @{ Name = "Browser"; Id = 7 },
    @{ Name = "PolyBase"; Id = 10, 11 },
    @{ Name = "Launchpad"; Id = 12 },
    @{ Name = "Unknown"; Id = 8 }
)
```

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

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

本機能はデータベースを直接操作せず、WMI経由でWindowsサービスのメタデータを読み取り専用で取得します。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | SELECT (WMI) | SqlService WMIクラスからの読み取り |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | コンピューター名解決失敗または接続不可 | コンピューター名の確認、ネットワーク接続確認 |
| N/A | 権限エラー | ローカル管理者権限がない場合 | 適切な資格情報でCredentialパラメータを使用 |
| N/A | WMI名前空間不在 | SQL Serverがインストールされていない | SQL Serverのインストール状態を確認 |

### リトライ仕様

明示的なリトライ機能は実装されていません。

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

読み取り専用操作のため、トランザクション制御は適用されません。

## パフォーマンス要件

特定のパフォーマンス要件は定義されていません。AdvancedPropertiesを指定すると追加のWMIクエリが発生するため、処理時間が増加します。

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

- 対象コンピューターでのローカル管理者権限が必要
- Credentialパラメータによる代替資格情報のサポート
- サービスアカウント情報（StartName）が出力に含まれる

## 備考

- 返されるオブジェクトにはStop()、Start()、Restart()、ChangeStartMode()メソッドが含まれる
- SqlInstance パラメータ使用時は ComputerName と InstanceName は無視される
- SSRSサービスは Get-DbaReportingService で別途取得される

---

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

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

### 推奨読解順序

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

SQL Serverサービス情報は、WMI SqlService クラスから取得されます。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SqlService WMIクラス | (WMI root\Microsoft\SQLServer) | ServiceName, SQLServiceType, State, StartMode などのプロパティ構造 |

**読解のコツ**: WMI SqlService クラスのプロパティは Microsoft ドキュメントで確認できます。SQLServiceTypeは数値で、ServiceIdMapで文字列に変換されます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaService.ps1 | `public/Get-DbaService.ps1` | メイン関数の構造、パラメータ定義 |

**主要処理フロー**:
1. **141-159行目**: パラメータ定義（2つのパラメータセット: Search, ServiceName）
2. **161-203行目**: begin ブロック - ServiceIdMap定義と検索条件構築
3. **204-349行目**: process ブロック - メイン処理
4. **254-257行目**: プロパティ変換（ComputerName, ServiceType, State, StartMode）
5. **282-303行目**: スクリプトメソッド追加（Stop, Start, Restart, ChangeStartMode）
6. **305-334行目**: AdvancedProperties取得処理

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Resolve-DbaNetworkName | (内部関数) | コンピューター名解決 |
| 3-2 | Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | WMI/CIMクエリの実行 |
| 3-3 | Get-DbaReportingService | (内部関数) | SSRSサービス取得 |

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

```
Get-DbaService
    │
    ├─ Resolve-DbaNetworkName (212行目)
    │      └─ コンピューター名を解決
    │
    ├─ Get-DbaCmObject (213, 230, 239, 307行目)
    │      └─ WMI名前空間とクラスからオブジェクト取得
    │
    ├─ Get-DbaReportingService (224行目)
    │      └─ SSRSサービス情報を取得
    │
    ├─ Stop-DbaService (スクリプトメソッド, 284行目)
    ├─ Start-DbaService (スクリプトメソッド, 286行目)
    ├─ Restart-DbaService (スクリプトメソッド, 289行目)
    ├─ Set-ServiceStartMode (スクリプトメソッド, 301行目)
    │
    └─ Select-DefaultView (344行目)
           └─ 既定表示プロパティの設定
```

### データフロー図

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

ComputerName ───▶ Resolve-DbaNetworkName ───▶ 解決済みコンピューター名
                         │
                         ▼
InstanceName ───▶ フィルター条件構築
                         │
Type ───────────▶        │
                         ▼
                  Get-DbaCmObject
                  (SqlService WMI) ───▶ サービス一覧
                         │
                         ▼
                  プロパティ変換・追加
                  スクリプトメソッド追加
                         │
                         ▼
AdvancedProperties ───▶ 追加プロパティ取得
                         │
                         ▼
                  Select-DefaultView ───▶ SqlService オブジェクト
                                          (ComputerName, ServiceName,
                                           ServiceType, InstanceName,
                                           DisplayName, StartName,
                                           State, StartMode)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | ソース | メイン機能実装 |
| Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | ソース | WMI/CIMオブジェクト取得 |
| Stop-DbaService.ps1 | `public/Stop-DbaService.ps1` | ソース | サービス停止（メソッドから呼び出し） |
| Start-DbaService.ps1 | `public/Start-DbaService.ps1` | ソース | サービス開始（メソッドから呼び出し） |
| Restart-DbaService.ps1 | `public/Restart-DbaService.ps1` | ソース | サービス再起動（メソッドから呼び出し） |
| Get-DbaService.Tests.ps1 | `tests/Get-DbaService.Tests.ps1` | テスト | ユニット・統合テスト |
