# 機能設計書 230-Set-DbaStartupParameter

## 概要

本ドキュメントは、SQL Serverの起動パラメータをWindowsレジストリで変更するdbatools PowerShellコマンドレット「Set-DbaStartupParameter」の機能設計書である。

### 本機能の処理概要

Set-DbaStartupParameterは、SQL Serverサービス開始時に使用される起動パラメータを変更するコマンドレットである。masterデータベースファイルのパス、エラーログの場所、トレースフラグ、シングルユーザーモードなど、様々な起動オプションを設定できる。

**業務上の目的・背景**：SQL Serverの起動パラメータは、トラブルシューティング、システムデータベースファイルの移動、パフォーマンス最適化などの場面で変更が必要になる。緊急時のシングルユーザーモード起動や、特定のトレースフラグの有効化など、本機能により手動でのレジストリ編集を不要にする。

**機能の利用シーン**：
- シングルユーザーモードでの緊急メンテナンス
- トレースフラグの有効化
- システムデータベースファイルの移動
- エラーログ格納場所の変更
- 起動設定のバックアップと復元

**主要な処理内容**：
1. 現在の起動パラメータの取得（Get-DbaStartupParameter）
2. 新しいパラメータ文字列の構築
3. パス検証（オンラインインスタンスの場合）
4. WMI経由でのレジストリ更新
5. 変更結果の出力

**関連システム・外部連携**：SQL Server WMI、Windowsレジストリを使用。

**権限による制御**：ターゲットサーバーへの管理者権限およびWMI接続権限が必要。

## 関連画面

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

## 機能種別

サーバー設定変更（レジストリ更新）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 | - |
| Credential | PSCredential | No | WMI接続用Windows資格情報 | - |
| MasterData | string | No | masterデータファイルパス | パス検証あり |
| MasterLog | string | No | masterログファイルパス | パス検証あり |
| ErrorLog | string | No | エラーログパス | パス検証あり |
| TraceFlag | string[] | No | 有効化するトレースフラグ | カンマ区切り |
| CommandPromptStart | switch | No | コマンドプロンプト起動フラグ | - |
| MinimalStart | switch | No | 最小起動フラグ | - |
| MemoryToReserve | int | No | 予約メモリ（MB） | - |
| SingleUser | switch | No | シングルユーザーモード | - |
| SingleUserDetails | string | No | シングルユーザー接続先 | - |
| NoLoggingToWinEvents | switch | No | Windowsイベントログ無効化 | - |
| StartAsNamedInstance | switch | No | 名前付きインスタンス起動 | - |
| DisableMonitoring | switch | No | 監視無効化 | - |
| IncreasedExtents | switch | No | エクステント増加 | - |
| TraceFlagOverride | switch | No | トレースフラグ上書き | - |
| StartupConfig | object | No | 起動設定オブジェクト | Get-DbaStartupParameterの出力 |
| Offline | switch | No | オフラインモード | パス検証スキップ |
| Force | switch | No | 強制実行 | - |
| EnableException | switch | No | 例外有効化フラグ | - |

### 入力データソース

- PowerShellコマンドライン入力
- Get-DbaStartupParameterからのStartupConfigオブジェクト

## 出力仕様

### 出力データ

Get-DbaStartupParameterの出力に追加プロパティを付与したオブジェクト:

| 項目名 | 型 | 説明 |
|--------|-----|------|
| CommandPromptStart | bool | コマンドプロンプト起動フラグ |
| DisableMonitoring | bool | 監視無効化フラグ |
| ErrorLog | string | エラーログパス |
| IncreasedExtents | bool | エクステント増加フラグ |
| MasterData | string | masterデータファイルパス |
| MasterLog | string | masterログファイルパス |
| MemoryToReserve | int | 予約メモリ（MB） |
| MinimalStart | bool | 最小起動フラグ |
| NoLoggingToWinEvents | bool | Windowsイベントログ無効化フラグ |
| ParameterString | string | 完全なパラメータ文字列 |
| SingleUser | bool | シングルユーザーモード |
| SingleUserDetails | string | シングルユーザー接続先 |
| StartAsNamedInstance | bool | 名前付きインスタンス起動フラグ |
| TraceFlags | string | トレースフラグ（カンマ区切り） |
| OriginalStartupParameters | string | 変更前のパラメータ文字列 |
| Notes | string | 再起動必要の通知メッセージ |

### 出力先

PowerShellパイプライン（標準出力）

## 処理フロー

### 処理シーケンス

```
1. beginブロック
   └─ 昇格権限チェック

2. 各SqlInstanceに対するループ
   └─ SQL Server接続（Offlineでない場合）
   └─ 現在の起動パラメータ取得

3. StartupConfig適用または個別パラメータ処理
   └─ PSBoundParametersからの値コピー

4. パラメータ文字列の構築
   └─ MasterData (-d)
   └─ ErrorLog (-e)
   └─ MasterLog (-l)
   └─ オプションフラグ (-c, -f, -g, -m, -n, -s, -x, -E)
   └─ TraceFlags (-T)

5. パス検証（オンライン時）
   └─ Test-DbaPathで各パスを検証
   └─ 検証失敗時はエラー

6. WMI経由での更新
   └─ Invoke-ManagedComputerCommand実行
   └─ StartupParameters設定

7. 結果の出力
   └─ 更新後の起動パラメータ取得
   └─ OriginalStartupParametersプロパティ追加
   └─ 再起動必要メッセージ追加
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[昇格権限チェック]
    B --> C[各SqlInstanceに対してループ]
    C --> D{Offline指定?}
    D -->|No| E[SQL Server接続]
    D -->|Yes| F[接続スキップ]
    E --> G{接続成功?}
    G -->|No| H[Offline=true設定]
    G -->|Yes| I[現在パラメータ取得]
    H --> I
    F --> I
    I --> J{StartupConfig指定?}
    J -->|Yes| K[StartupConfig適用]
    J -->|No| L[個別パラメータ処理]
    K --> M[パラメータ文字列構築]
    L --> M
    M --> N{パス検証必要?}
    N -->|Yes| O[Test-DbaPath実行]
    N -->|No| P[ShouldProcess確認]
    O --> Q{検証成功?}
    Q -->|No| R[エラー終了]
    Q -->|Yes| P
    P -->|No| S[スキップ]
    P -->|Yes| T[WMI更新]
    T --> U{成功?}
    U -->|No| V[エラー出力]
    U -->|Yes| W[結果出力]
    W --> X{次のインスタンス?}
    S --> X
    V --> X
    R --> X
    X -->|Yes| C
    X -->|No| Y[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 昇格権限必須 | 管理者権限での実行が必要 | 常時 |
| BR-002 | パス必須項目 | MasterData, ErrorLog, MasterLogは必須値 | 常時 |
| BR-003 | オンラインパス検証 | オンライン時はパスの検証を実行 | Offline=false時 |
| BR-004 | Forceでパス検証スキップ | -Forceでオフライン時もパス設定可能 | Force=true時 |
| BR-005 | 再起動必要 | 変更は再起動後に有効 | 常時 |
| BR-006 | TraceFlagOverride | 指定時は既存トレースフラグを置換 | TraceFlagOverride=true時 |
| BR-007 | StartupConfig優先 | StartupConfig指定時はTraceFlagOverride自動有効 | StartupConfig指定時 |

### 計算ロジック

起動パラメータフラグの対応:
- -c: CommandPromptStart
- -f: MinimalStart
- -g{N}: MemoryToReserve
- -m[details]: SingleUser
- -n: NoLoggingToWinEvents
- -s: StartAsNamedInstance
- -x: DisableMonitoring
- -E: IncreasedExtents
- -T{N}: TraceFlag

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

本機能はデータベース操作を行わない。Windowsレジストリを直接編集する。

### レジストリ更新

WMI（SQL Server Managed Computer）を経由してSQL Serverサービスの起動パラメータを更新する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ElevationRequired | 管理者権限なし | 管理者として実行 |
| - | ConnectionFailed | SQL Server接続失敗 | 資格情報を確認 |
| - | PathNotReachable | パス検証失敗 | 有効なパスを指定 |
| - | MasterDataRequired | MasterData値なし | 必須パラメータを指定 |
| - | ErrorLogRequired | ErrorLog値なし | 必須パラメータを指定 |
| - | MasterLogRequired | MasterLog値なし | 必須パラメータを指定 |
| - | WMIFailed | WMI操作失敗 | 権限とWMIサービスを確認 |

### リトライ仕様

リトライ処理は実装されていない。エラー発生時はStop-Functionで処理を停止。

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

WMI操作はトランザクションサポートなし。設定は即座にレジストリに書き込まれるが、SQL Server再起動後に有効になる。

## パフォーマンス要件

特に定義されていない。レジストリ変更は軽量な操作である。

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

- ターゲットサーバーへの管理者権限が必要
- 不正なパス設定はSQL Server起動失敗を引き起こす可能性
- シングルユーザーモードは他のユーザーを排除するため注意が必要

## 備考

- 参考: https://msdn.microsoft.com/en-us/library/ms190737(v=sql.105).aspx
- 変更後は必ずSQL Serverサービスを再起動する必要がある
- Get-DbaStartupParameterで事前に設定をバックアップ可能
- WhatIfとConfirmパラメータをサポート（ConfirmImpact = High）

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造とパラメータ文字列の形式を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaStartupParameter.ps1 | `public/Set-DbaStartupParameter.ps1` | 出力オブジェクトの構造（136-160行目の.OUTPUTSセクション） |

**読解のコツ**: Get-DbaStartupParameterの出力にOriginalStartupParametersとNotesが追加される構造。

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

beginとprocessブロック内のメイン処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaStartupParameter.ps1 | `public/Set-DbaStartupParameter.ps1` | beginブロック（241-244行目） |
| 2-2 | Set-DbaStartupParameter.ps1 | `public/Set-DbaStartupParameter.ps1` | processブロック（245-466行目） |

**主要処理フロー**:
1. **248-260行目**: SQL Server接続とOfflineモード処理
2. **262-268行目**: 現在の起動パラメータ取得
3. **274-286行目**: StartupConfigまたは個別パラメータの処理
4. **288-368行目**: パラメータ文字列の構築
5. **429-443行目**: ScriptBlockによるWMI更新

#### Step 3: パラメータ文字列構築ロジックを理解する

各オプションフラグの設定処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaStartupParameter.ps1 | `public/Set-DbaStartupParameter.ps1` | 必須パス設定（290-368行目） |
| 3-2 | Set-DbaStartupParameter.ps1 | `public/Set-DbaStartupParameter.ps1` | オプションフラグ設定（370-424行目） |

**主要処理フロー**:
- **290-308行目**: MasterDataパス設定と検証
- **310-327行目**: ErrorLogパス設定と検証
- **329-346行目**: MasterLogパス設定と検証
- **370-400行目**: 各種スイッチパラメータの設定
- **401-424行目**: TraceFlagの処理（追加/上書き）

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

```
Set-DbaStartupParameter
    │
    ├─ Test-ElevationRequirement
    │
    ├─ Connect-DbaInstance (Offlineでない場合)
    │
    ├─ Get-DbaStartupParameter
    │      └─ 現在の起動パラメータ取得
    │
    ├─ Test-DbaPath (オンライン時)
    │      └─ MasterData, ErrorLog, MasterLogパス検証
    │
    └─ Invoke-ManagedComputerCommand
           └─ WMIによるStartupParameters更新
           └─ Get-DbaStartupParameter (結果取得)
```

### データフロー図

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

SqlInstance ─────────┐
MasterData ──────────┤
MasterLog ───────────┤
ErrorLog ────────────┼──▶ Get-DbaStartupParameter
TraceFlag ───────────┤    (現在設定取得)
SingleUser ──────────┤         │
その他オプション ────┤         ▼
StartupConfig ───────┘    パラメータ文字列構築
                              │
                              ▼
                         Test-DbaPath
                         (オンライン時)
                              │
                              ▼
                         Invoke-ManagedComputerCommand
                         (WMI更新)
                              │
                              ▼
                         Get-DbaStartupParameter
                         (更新後取得)
                              │
                              ▼
                         + OriginalStartupParameters
                         + Notes ──▶ 出力オブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaStartupParameter.ps1 | `public/Set-DbaStartupParameter.ps1` | ソース | メインコマンドレット実装 |
| Get-DbaStartupParameter.ps1 | `public/Get-DbaStartupParameter.ps1` | ソース | 現在の起動パラメータ取得 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パスアクセス可能性検証 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Invoke-ManagedComputerCommand.ps1 | `private/functions/Invoke-ManagedComputerCommand.ps1` | ソース | WMIコマンド実行 |
