# 画面設計書 118-サービス管理

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Server関連Windowsサービス管理機能の設計仕様を記述する。

### 本画面の処理概要

本機能群は、SQL Server関連のWindowsサービス（Database Engine、SQL Agent、Reporting Services、Analysis Services、Integration Services等）の取得・開始・停止を行う。WMI/SMOを使用してリモートサーバーのサービスも一括管理できる。

**業務上の目的・背景**：SQL Server環境全体のサービス状態監視、メンテナンスウィンドウでのサービス開始/停止、パッチ適用前後のサービス制御など、日常的な運用管理作業を効率化する。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドレットを実行する。
- `Get-DbaService` - サービス情報の取得
- `Start-DbaService` - サービスの開始
- `Stop-DbaService` - サービスの停止

**主要な操作・処理内容**：
1. SQL Server関連サービスの一覧取得と状態確認
2. サービスタイプ別のフィルタリング（Engine, Agent, SSRS等）
3. 依存関係を考慮したサービス開始順序制御
4. 依存サービスを含めた一括停止
5. サービス起動モードの変更

**画面遷移**：本機能はコマンドラインインターフェースであり、画面遷移は存在しない。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 139 | Get-DbaService | 主機能 | サービス情報取得 |
| 262 | Start-DbaService | 主機能 | サービス開始 |
| 276 | Stop-DbaService | 主機能 | サービス停止 |

## 画面種別

CLIコマンド群（サービス管理）

## URL/ルーティング

```powershell
# サービス取得
Get-DbaService -ComputerName <コンピュータ名>

# サービスタイプ指定で取得
Get-DbaService -ComputerName <コンピュータ名> -Type Engine,Agent

# 詳細プロパティ付き取得
Get-DbaService -ComputerName <コンピュータ名> -AdvancedProperties

# サービス開始
Start-DbaService -ComputerName <コンピュータ名>

# サービス停止
Stop-DbaService -ComputerName <コンピュータ名> [-Force]

# パイプライン
Get-DbaService -ComputerName sql1 -Type Engine | Stop-DbaService -Force
```

## 入出力項目

### Get-DbaService パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|---|------|-------------|------|
| ComputerName | DbaInstanceParameter[] | No | ローカル | 対象コンピュータ |
| InstanceName | string[] | No | - | インスタンス名でフィルタ |
| SqlInstance | DbaInstanceParameter[] | No | - | SqlInstance指定（ComputerName/InstanceNameを上書き） |
| Credential | PSCredential | No | - | 接続資格情報 |
| Type | string[] | No | - | Agent/Browser/Engine/FullText/SSAS/SSIS/SSRS/PolyBase/Launchpad |
| ServiceName | string[] | No | - | サービス名で直接指定 |
| AdvancedProperties | switch | No | $false | 詳細プロパティ（Version, SKU等）を含める |
| EnableException | switch | No | $false | 例外をスローする |

### Start-DbaService / Stop-DbaService パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|---|------|-------------|------|
| ComputerName | DbaInstanceParameter[] | No | ローカル | 対象コンピュータ |
| InstanceName | string[] | No | - | インスタンス名でフィルタ |
| SqlInstance | DbaInstanceParameter[] | No | - | SqlInstance指定 |
| Type | string[] | No | - | サービスタイプフィルタ |
| InputObject | object[] | No | - | パイプライン入力 |
| Timeout | int | No | 60 | タイムアウト秒 |
| Credential | PSCredential | No | - | 接続資格情報 |
| Force | switch | No | $false | 依存サービスも停止（Stop-DbaServiceのみ） |
| WhatIf | switch | No | - | 実行内容をシミュレート |
| Confirm | switch | No | - | 確認プロンプトを表示 |
| EnableException | switch | No | $false | 例外をスローする |

## 表示項目

### Get-DbaService 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | コンピュータ名 |
| ServiceName | string | サービス名 |
| ServiceType | string | サービスタイプ（Engine/Agent等） |
| InstanceName | string | インスタンス名 |
| DisplayName | string | 表示名 |
| StartName | string | サービスアカウント |
| State | string | 状態（Running/Stopped等） |
| StartMode | string | 起動モード（Automatic/Manual/Disabled） |

### AdvancedProperties追加時

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| Version | string | SQL Serverバージョン |
| SPLevel | int | サービスパックレベル |
| SkuName | string | エディション名 |
| Clustered | int | クラスター構成フラグ |
| VSName | string | 仮想サーバー名 |
| SqlInstance | string | SqlInstance（Engine用） |

### Start/Stop-DbaService 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | コンピュータ名 |
| ServiceName | string | サービス名 |
| InstanceName | string | インスタンス名 |
| ServiceType | string | サービスタイプ |
| State | string | 現在の状態 |
| Status | string | 操作結果（Successful/Failed） |
| Message | string | 詳細メッセージ |

## イベント仕様

### 1-Get-DbaService実行

1. SqlInstance指定時はComputerNameとInstanceNameを上書き
2. Resolve-DbaNetworkNameでコンピュータ名解決
3. WMI namespaceにアクセス確認
4. SSRSサービスはGet-DbaReportingServiceで個別取得
5. ComputerManagement名前空間からSqlService照会
6. ServiceIdMapでサービスタイプをマッピング
   - Engine=1, Agent=2, FullText=3/9, SSIS=4, SSAS=5, SSRS=6, Browser=7
   - PolyBase=10/11, Launchpad=12, Unknown=8
7. ServiceNameからInstanceNameを抽出
8. ScriptMethod追加（Stop, Start, Restart, ChangeStartMode）
9. AdvancedProperties時は追加プロパティ取得

### 2-Start-DbaService実行

1. Server ParameterSetならGet-DbaServiceでサービス取得
2. InputObjectでパイプライン入力受付
3. InstanceName/Typeでフィルタ
4. Update-ServiceStatusで開始処理
5. サービス依存関係順で開始

### 3-Stop-DbaService実行

1. Server ParameterSetならGet-DbaServiceでサービス取得
2. InputObjectでパイプライン入力受付
3. Force指定でEngine停止時:
   - 依存サービス（Agent, PolyBase）を追加取得
4. Update-ServiceStatusで停止処理

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

本機能はWindowsサービス管理であり、SQL Serverデータベースへの直接更新は行わない。

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 発生条件 |
|---------------|---------------|---------|
| エラー | Failed to resolve or to connect to $computer | 接続失敗 |
| エラー | No SQL Server services found with current parameters | サービス未検出 |
| エラー | Incorrect mode '$Mode'. Use one of the following values | ChangeStartMode不正 |
| Verbose | Getting SQL Server namespaces on $computer | 名前空間取得 |
| Verbose | Found service $serviceName in namespace $namespace | サービス検出 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| 名前解決失敗 | Stop-Functionでエラー出力、Continue |
| WMIアクセス失敗 | Stop-Functionでエラー出力、Continue |
| サービス未検出 | Stop-Functionでメッセージ出力 |
| 開始/停止タイムアウト | エラー出力 |

## 備考

- ローカル管理者権限が必要
- ServiceIdMapでSQL Serverサービスを識別
- 最新のWMI名前空間を優先使用
- AdvancedPropertiesでSqlServiceAdvancedPropertyを照会
- クラスター環境ではVSName（仮想サーバー名）を使用
- ForceでEngineサービス停止時はAgentとPolyBaseも停止
- ChangeStartModeはAutomatic/Manual/Disabledのみ

---

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

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

### 推奨読解順序

#### Step 1: サービスタイプマッピングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaService.ps1 | `public/Get-DbaService.ps1` | 行168-179: $ServiceIdMap |

**読解のコツ**: SQLServiceTypeの数値IDを人間可読な名前（Engine, Agent等）にマッピング。

#### Step 2: サービス取得処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaService.ps1 | `public/Get-DbaService.ps1` | 行204-248: メイン取得ループ |
| 2-2 | Get-DbaService.ps1 | `public/Get-DbaService.ps1` | 行253-337: プロパティ追加とメソッド追加 |

**主要処理フロー**:
1. **行211-212**: Resolve-DbaNetworkNameとWMI疎通確認
2. **行222-226**: SSRSはGet-DbaReportingServiceで個別取得
3. **行229-248**: ComputerManagement名前空間からSqlService照会
4. **行254-276**: ServiceType, State, StartMode, InstanceNameを決定
5. **行282-303**: ScriptMethod追加（Stop, Start, Restart, ChangeStartMode）

#### Step 3: 開始/停止処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Start-DbaService.ps1 | `public/Start-DbaService.ps1` | 行126-158: 開始処理 |
| 3-2 | Stop-DbaService.ps1 | `public/Stop-DbaService.ps1` | 行138-190: 停止処理 |

**主要処理フロー**:
1. **Start**: Get-DbaServiceで取得、Update-ServiceStatusでstart
2. **Stop**: Force時は依存サービス（Agent, PolyBase）を追加、Update-ServiceStatusでstop

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

```
Get-DbaService
    │
    +-- SqlInstance → ComputerName展開
    │
    +-- foreach ($computer in $ComputerName)
            │
            +-- Resolve-DbaNetworkName
            │
            +-- Get-DbaCmObject (WMI疎通確認)
            │
            +-- Get-DbaReportingService (SSRS)
            │
            +-- Get-DbaCmObject (ComputerManagement)
            │       └─ SqlService照会
            │
            +-- foreach ($service in $services)
            │       │
            │       +-- ServiceIdMapでタイプ変換
            │       │
            │       +-- State/StartMode変換
            │       │
            │       +-- InstanceName抽出
            │       │
            │       +-- ScriptMethod追加
            │       │       ├─ Stop()
            │       │       ├─ Start()
            │       │       ├─ Restart()
            │       │       └─ ChangeStartMode()
            │       │
            │       └── AdvancedProperties
            │               └─ SqlServiceAdvancedProperty照会
            │
            └── Select-DefaultView

Start-DbaService
    │
    +-- Get-DbaService (Server ParameterSet)
    │
    +-- フィルタ (InstanceName, Type)
    │
    └── Update-ServiceStatus (Action=start)

Stop-DbaService
    │
    +-- Get-DbaService (Server ParameterSet)
    │
    +-- フィルタ (InstanceName, Type)
    │
    +-- Force時
    │       └─ 依存サービス追加 (Agent, PolyBase)
    │
    └── Update-ServiceStatus (Action=stop)
```

### データフロー図

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

ComputerName ────────────> Resolve-DbaNetworkName ──────────────>
SqlInstance ─────────────>

Type ────────────────────> WMI SqlService照会 ──────────────────>
InstanceName ────────────>     │
ServiceName ─────────────>     └─ ServiceIdMap変換

AdvancedProperties ──────> SqlServiceAdvancedProperty ──────────> DbaSqlService
                               │
                               ├─ Version/SPLevel/SkuName
                               └─ Clustered/VSName/SqlInstance

InputObject ─────────────> Update-ServiceStatus ────────────────> ServiceStatus
Action (start/stop) ─────>     │                                  ├─ State
Timeout ─────────────────>     └─ タイムアウト制御                 ├─ Status
                                                                   └─ Message
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | ソース | サービス情報取得 |
| Start-DbaService.ps1 | `public/Start-DbaService.ps1` | ソース | サービス開始 |
| Stop-DbaService.ps1 | `public/Stop-DbaService.ps1` | ソース | サービス停止 |
| Restart-DbaService.ps1 | `public/Restart-DbaService.ps1` | ソース | サービス再起動（関連） |
| Get-DbaReportingService.ps1 | `public/Get-DbaReportingService.ps1` | ソース | SSRSサービス取得（依存） |
