# 機能設計書 695-Restart-DbaService

## 概要

本ドキュメントは、SQL Server関連のWindowsサービスを再起動するdbatools PowerShellコマンド `Restart-DbaService` の機能設計書です。

### 本機能の処理概要

`Restart-DbaService` は、複数のコンピューターにまたがるSQL Server関連サービスを、サービス依存関係と再起動順序を自動的に管理しながら再起動する機能です。制御された停止と再起動のシーケンスを実行し、Database Engine再起動時にSQL Agentなどの依存サービスを適切に処理します。

**業務上の目的・背景**：SQL Server設定変更やパッチ適用後にはサービスの再起動が必要になることがあります。複数のインスタンスや複数のサーバーにまたがるサービス再起動を、依存関係を考慮しながら安全に実行することで、メンテナンスウィンドウの効率化とダウンタイムの最小化を実現します。

**機能の利用シーン**：
- 設定変更後のサービス再起動
- メンテナンスウィンドウでの計画的なサービス再起動
- パッチ適用後のサービス再起動
- トラブルシューティングでのサービス再起動

**主要な処理内容**：
1. 対象サービスの取得（Get-DbaService呼び出しまたはパイプライン入力）
2. Force指定時は依存サービス（Agent, PolyBase, Launchpad）を自動追加
3. サービスの停止処理（Update-ServiceStatus -Action stop）
4. 停止成功したサービスの再起動処理（Update-ServiceStatus -Action restart）
5. 処理結果の出力

**関連システム・外部連携**：Windows Service Control Manager、SQL Server関連Windowsサービス

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

## 関連画面

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

## 機能種別

サービス管理 / 操作実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | 再起動対象のコンピューター名 | Serverパラメータセット、デフォルト$env:COMPUTERNAME |
| InstanceName | string[] | No | 特定のSQL Serverインスタンス名でフィルタリング | なし |
| SqlInstance | DbaInstanceParameter[] | No | コンピューター名とインスタンス名の組み合わせで指定 | Serverパラメータセット |
| Credential | PSCredential | No | 代替資格情報でコンピューターに接続 | なし |
| Type | string[] | No | サービスタイプでフィルタリング（Agent, Browser, Engine, FullText, SSAS, SSIS, SSRS, PolyBase, Launchpad） | ValidateSet |
| InputObject | object[] | Yes (Service) | Get-DbaServiceからのサービスオブジェクト | パイプライン入力、Serviceパラメータセット |
| Timeout | int | No | 各サービス操作のタイムアウト秒数 | デフォルト60秒、0で無限待機 |
| Force | switch | No | Engineサービス再起動時に依存サービスを自動的に含める | なし |
| EnableException | switch | No | 例外を有効にし、try/catchでのキャッチを可能にする | なし |
| WhatIf | switch | No | 実行せずに処理内容を表示 | なし |
| Confirm | switch | No | 実行前に確認プロンプトを表示 | なし |

### 入力データソース

- Get-DbaServiceから取得したサービスオブジェクト
- パイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | サービスが実行されているコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名 |
| ServiceName | string | Windowsサービス名 |
| ServiceType | string | サービスタイプ（Engine, Agent, Browser等） |
| Status | string | 再起動操作の結果（Successful, Failed） |

### 出力先

PowerShellパイプライン (PSCustomObject)

## 処理フロー

### 処理シーケンス

```
1. begin ブロック
   ├─ processArray初期化
   └─ Serverパラメータセットの場合、Get-DbaServiceでサービス取得

2. process ブロック
   └─ InputObjectをprocessArrayに追加

3. end ブロック
   ├─ InstanceName/Typeでフィルタリング
   ├─ Force指定時
   │   └─ 各Engineサービスに対して依存サービス（Agent, PolyBase, Launchpad）を追加
   ├─ ShouldProcess確認
   ├─ Update-ServiceStatus -Action stop で停止
   ├─ 停止失敗サービスを先に出力
   ├─ 停止成功サービスに対してUpdate-ServiceStatus -Action restart
   └─ 再起動結果を出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Serverパラメータセット?}
    B -->|Yes| C[Get-DbaServiceでサービス取得]
    B -->|No| D[パイプラインからInputObject受信]
    C --> D
    D --> E[processArrayにサービス追加]
    E --> F[InstanceName/Typeでフィルタリング]
    F --> G{Force指定?}
    G -->|Yes| H{Engineサービスあり?}
    H -->|Yes| I[依存サービス追加]
    H -->|No| J{ShouldProcess?}
    G -->|No| J
    I --> J
    J -->|No| K[終了]
    J -->|Yes| L[Update-ServiceStatus stop]
    L --> M{停止失敗あり?}
    M -->|Yes| N[失敗サービス出力]
    N --> O{停止成功あり?}
    M -->|No| O
    O -->|Yes| P[Update-ServiceStatus restart]
    O -->|No| K
    P --> Q[再起動結果出力]
    Q --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 権限要件 | ローカル管理者権限が必要 | 常時 |
| BR-002 | 依存サービス自動追加 | Force指定時、EngineサービスにAgent, PolyBase, Launchpadを追加 | Force指定時 |
| BR-003 | 停止優先 | まず全サービスを停止してから再起動 | 常時 |
| BR-004 | 失敗サービス先行出力 | 停止失敗したサービスを先に出力 | 常時 |
| BR-005 | タイムアウト | デフォルト60秒、0で無限待機 | 常時 |

### 計算ロジック

依存サービス追加ロジック（Force指定時）:
```powershell
foreach ($dependentService in @("Agent", "PolyBase", "Launchpad")) {
    if (!($processArray | Where-Object { $_.ServiceType -eq $dependentService -and $_.InstanceName -eq $service.InstanceName -and $_.ComputerName -eq $service.ComputerName })) {
        # 依存サービスを追加
    }
}
```

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

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

本機能はデータベースを直接操作しませんが、SQL Serverサービスの再起動によりデータベース接続が一時的に中断されます。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | サービス操作 | SQL Serverサービスの停止と再起動 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | サービス停止失敗 | サービス停止がタイムアウトまたはエラー | Forceスイッチで依存サービスも停止 |
| N/A | サービス開始失敗 | サービス開始がタイムアウトまたはエラー | サービスのイベントログを確認 |
| N/A | 権限エラー | ローカル管理者権限がない場合 | 適切な資格情報でCredentialパラメータを使用 |
| N/A | サービス未検出 | 指定条件に一致するサービスがない | パラメータ条件を確認 |

### リトライ仕様

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

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

サービス操作はトランザクション的ではありません。停止と再起動は順次実行されます。

## パフォーマンス要件

- デフォルトタイムアウト: 60秒
- 複数サービスの停止と再起動は順次処理

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

- 対象コンピューターでのローカル管理者権限が必要
- Credentialパラメータによる代替資格情報のサポート
- ShouldProcess/Confirmによる実行前確認

## 備考

- サービスが既に停止している場合、再起動は実行されません
- 停止失敗したサービスは再起動されません
- Force指定時の依存サービス追加は同一インスタンス・コンピューターのサービスのみ

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaService出力 | (Get-DbaService参照) | ServiceName, ServiceType, InstanceName, ComputerName などのプロパティ構造 |

**読解のコツ**: Restart-DbaServiceは Get-DbaService から取得したサービスオブジェクトを処理します。

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

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

**主要処理フロー**:
1. **107-125行目**: パラメータ定義（2つのパラメータセット: Server, Service）
2. **126-137行目**: begin ブロック - Serverパラメータセットの場合にGet-DbaService呼び出し
3. **138-141行目**: process ブロック - InputObjectをprocessArrayに追加
4. **142-191行目**: end ブロック - メイン処理
5. **143行目**: フィルタリング処理
6. **144-167行目**: Force指定時の依存サービス追加
7. **169-186行目**: サービス停止と再起動処理

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaService.ps1 | `public/Get-DbaService.ps1` | サービス情報取得 |
| 3-2 | Update-ServiceStatus.ps1 | `private/functions/Update-ServiceStatus.ps1` | 実際のサービス操作 |

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

```
Restart-DbaService
    │
    ├─ Get-DbaService (135行目, Serverパラメータセット)
    │      └─ サービス情報を取得
    │
    ├─ Get-DbaService (164行目, Force時の依存サービス取得)
    │      └─ 依存サービス情報を取得
    │
    └─ Update-ServiceStatus (170-186行目)
           ├─ -Action stop: サービス停止
           └─ -Action restart: サービス再起動
```

### データフロー図

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

ComputerName ───▶ Get-DbaService ───▶ サービスオブジェクト
                         │
InstanceName ───▶ フィルタリング
                         │
Type ───────────▶        │
                         ▼
InputObject ─────────▶ processArray
                         │
                         ▼
Force ───────────▶ 依存サービス追加
                         │
                         ▼
                  Update-ServiceStatus (stop) ───▶ 停止結果
                         │
                         ▼ (成功のみ)
                  Update-ServiceStatus (restart) ───▶ 再起動結果
                         │
                         ▼
                  PSCustomObject
                  (ComputerName, InstanceName,
                   ServiceName, ServiceType, Status)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Restart-DbaService.ps1 | `public/Restart-DbaService.ps1` | ソース | メイン機能実装 |
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | ソース | サービス情報取得 |
| Update-ServiceStatus.ps1 | `private/functions/Update-ServiceStatus.ps1` | ソース | サービス操作実行 |
| Restart-DbaService.Tests.ps1 | `tests/Restart-DbaService.Tests.ps1` | テスト | テストコード |
