# 機能設計書 517-Set-DbaAgentJobStep

## 概要

本ドキュメントは、SQL Server Agentジョブステップのプロパティを変更するdbatools関数「Set-DbaAgentJobStep」の機能設計書である。

### 本機能の処理概要

Set-DbaAgentJobStepは、既存のSQL Server Agentジョブステップのプロパティを変更、または-Forceパラメータで新規ステップを作成する機能を提供する。

**業務上の目的・背景**：SQL Server Agentジョブはステップ単位で処理を実行する。デプロイメント時のコマンド変更、環境間でのデータベースコンテキスト更新、リトライ設定の調整、成功/失敗時のフロー変更など、運用中にステッププロパティを変更するニーズは多い。本機能により、SSMSでの手動編集を省略し、複数サーバー・複数ジョブへの一括変更が可能になる。

**機能の利用シーン**：
- デプロイメント時のジョブステップコマンド更新
- 環境間でのデータベースコンテキスト変更
- リトライ設定の調整
- 成功/失敗時のフロー変更
- サブシステム（T-SQL, PowerShell, SSIS等）の変更
- 出力ファイル設定
- プロキシアカウントの割り当て

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続
2. 対象ジョブとステップの取得
3. 存在確認（-Force時は新規作成）
4. 各種プロパティの検証と設定
5. SMO Alter()メソッドによる変更のコミット

**関連システム・外部連携**：SQL Server JobServer.Jobs、JobSteps、ProxyAccounts、Databases

**権限による制御**：sysadmin権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio - Job Step Properties | 参照画面 | ジョブステッププロパティの確認・編集 |
| - | PowerShell Console | 主画面 | コマンド実行インターフェース |

## 機能種別

データ更新・作成操作 (UPDATE/INSERT)

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証資格情報 | - |
| Job | object[] | No | 対象ジョブ名 | - |
| StepName | string | No | 対象ステップ名 | - |
| NewName | string | No | 新しいステップ名 | - |
| Subsystem | string | No | サブシステム | ActiveScripting, AnalysisCommand, AnalysisQuery, CmdExec, Distribution, LogReader, Merge, PowerShell, QueueReader, Snapshot, Ssis, TransactSql |
| SubsystemServer | string | No | サブシステムサーバー | AnalysisXxx系で必須 |
| Command | string | No | 実行コマンド | - |
| CmdExecSuccessCode | int | No | CmdExec成功コード | - |
| OnSuccessAction | string | No | 成功時アクション | QuitWithSuccess, QuitWithFailure, GoToNextStep, GoToStep |
| OnSuccessStepId | int | No | 成功時移動先ステップID | OnSuccessAction=GoToStep時のみ |
| OnFailAction | string | No | 失敗時アクション | QuitWithSuccess, QuitWithFailure, GoToNextStep, GoToStep |
| OnFailStepId | int | No | 失敗時移動先ステップID | OnFailAction=GoToStep時のみ |
| Database | string | No | 実行データベース | 存在するデータベース |
| DatabaseUser | string | No | データベースユーザー | 存在するユーザー |
| RetryAttempts | int | No | リトライ回数 | - |
| RetryInterval | int | No | リトライ間隔（分） | - |
| OutputFileName | string | No | 出力ファイルパス | - |
| Flag | string[] | No | ステップフラグ | AppendAllCmdExecOutputToJobHistory, AppendToJobHistory, AppendToLogFile, AppendToTableLog, LogToTableWithOverwrite, None, ProvideStopProcessEvent |
| ProxyName | string | No | プロキシアカウント名 | - |
| InputObject | Server[] | No | パイプラインからのサーバーオブジェクト | - |
| EnableException | switch | No | 例外処理を有効化 | - |
| Force | switch | No | ステップが存在しない場合に新規作成 | - |

### 入力データソース

- Connect-DbaInstanceからのパイプライン入力
- SQL Server JobServer.Jobs[$j].JobStepsコレクション

## 出力仕様

### 出力データ

Microsoft.SqlServer.Management.Smo.Agent.JobStep オブジェクト

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | ステップ名 |
| ID | int | ステップID |
| Subsystem | string | サブシステム |
| Command | string | 実行コマンド |
| DatabaseName | string | データベース名 |
| DatabaseUserName | string | データベースユーザー |
| CommandExecutionSuccessCode | int | 成功コード |
| OnSuccessAction | string | 成功時アクション |
| OnSuccessStep | int | 成功時移動先ステップ |
| OnFailAction | string | 失敗時アクション |
| OnFailStep | int | 失敗時移動先ステップ |
| RetryAttempts | int | リトライ回数 |
| RetryInterval | int | リトライ間隔 |
| OutputFileName | string | 出力ファイル |
| ProxyName | string | プロキシ名 |
| JobStepFlags | string | ステップフラグ |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.Agent.JobStep）

## 処理フロー

### 処理シーケンス

```
1. 初期設定（beginブロック）
   ├─ Forceフラグによる確認プロンプト制御
   ├─ OnSuccessStepId/OnFailStepIdパラメータ検証
   └─ AnalysisXxx系サブシステムのサーバー必須検証

2. インスタンス接続（processブロック）
   └─ Connect-DbaInstanceで接続

3. 各サーバー・ジョブの処理
   ├─ ActiveScripting + SQL Server 2016以上: エラー
   ├─ ジョブ存在確認
   ├─ ステップ存在確認
   │   ├─ 存在しない + Forceなし: エラー
   │   └─ 存在しない + Force: New-DbaAgentJobStepで作成
   └─ 既存ステップ: そのまま使用

4. 各プロパティの設定
   ├─ NewName → Rename()
   ├─ Subsystem, SubsystemServer, Command
   ├─ CmdExecSuccessCode
   ├─ OnSuccessAction, OnSuccessStepId
   ├─ OnFailAction, OnFailStepId
   ├─ Database, DatabaseUser
   ├─ RetryAttempts, RetryInterval
   ├─ OutputFileName
   ├─ ProxyName
   └─ Flag

5. 変更のコミット
   ├─ ShouldProcess確認
   ├─ Alter()メソッド呼び出し
   └─ ステップオブジェクトを返却

6. 完了処理（endブロック）
   └─ 完了メッセージ出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[beginブロック: パラメータ検証]
    B --> C{OnSuccessStepId + OnSuccessAction != GoToStep?}
    C -->|Yes| D[エラー: パラメータ不整合]
    C -->|No| E{OnFailStepId + OnFailAction != GoToStep?}
    E -->|Yes| D
    E -->|No| F{AnalysisXxx + SubsystemServer未指定?}
    F -->|Yes| D
    F -->|No| G[processブロック]
    G --> H[各SqlInstanceをループ]
    H --> I[Connect-DbaInstance]
    I --> J[InputObjectに追加]
    J --> K[各サーバーをループ]
    K --> L{ActiveScripting + SQL 2016以上?}
    L -->|Yes| M[エラー: サポートなし]
    L -->|No| N[各ジョブをループ]
    N --> O{ジョブ存在?}
    O -->|No| P[エラー: ジョブ不存在]
    O -->|Yes| Q{ステップ存在?}
    Q -->|No| R{Force?}
    R -->|No| S[エラー: ステップ不存在]
    R -->|Yes| T[New-DbaAgentJobStepで作成]
    Q -->|Yes| U[既存ステップを使用]
    T --> V[各プロパティを設定]
    U --> V
    V --> W[ShouldProcess確認]
    W --> X[Alter実行]
    X --> Y[ステップオブジェクト出力]
    Y --> Z{次のジョブ?}
    Z -->|Yes| N
    Z -->|No| AA{次のサーバー?}
    AA -->|Yes| K
    AA -->|No| AB[endブロック: 完了メッセージ]
    AB --> AC[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | OnSuccessStepId制約 | OnSuccessAction=GoToStep以外でOnSuccessStepIdは使用不可 | OnSuccessStepId >= 1 |
| BR-002 | OnFailStepId制約 | OnFailAction=GoToStep以外でOnFailStepIdは使用不可 | OnFailStepId >= 1 |
| BR-003 | AnalysisXxxサーバー必須 | AnalysisScripting/AnalysisCommand/AnalysisQuery サブシステムはSubsystemServerが必須 | 該当Subsystem使用時 |
| BR-004 | ActiveScripting非サポート | SQL Server 2016以上ではActiveScriptingは使用不可 | VersionMajor >= 13 |
| BR-005 | ステップ自動作成 | -Force指定時、存在しないステップを自動作成 | Force + ステップ未存在 |
| BR-006 | データベース存在確認 | Database指定時、対象サーバーにデータベースが存在する必要がある | Database指定時 |
| BR-007 | ユーザー存在確認 | DatabaseUser指定時、データベースにユーザーが存在する必要がある | DatabaseUser指定時 |
| BR-008 | プロキシ存在確認 | ProxyName指定時、サーバーにプロキシが存在する必要がある | ProxyName指定時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ステップ更新 | msdb.dbo.sysjobsteps | UPDATE | ステッププロパティの更新 |
| ステップ作成 | msdb.dbo.sysjobsteps | INSERT | 新規ステップ作成（-Force時） |

### テーブル別操作詳細

#### msdb.dbo.sysjobsteps

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE/INSERT | step_name | StepName/NewName | - |
| UPDATE/INSERT | subsystem | Subsystem指定値 | - |
| UPDATE/INSERT | command | Command指定値 | - |
| UPDATE/INSERT | database_name | Database指定値 | - |
| UPDATE/INSERT | database_user_name | DatabaseUser指定値 | - |
| UPDATE/INSERT | on_success_action | OnSuccessAction | - |
| UPDATE/INSERT | on_fail_action | OnFailAction | - |
| UPDATE/INSERT | retry_attempts | RetryAttempts | - |
| UPDATE/INSERT | retry_interval | RetryInterval | - |
| UPDATE/INSERT | output_file_name | OutputFileName | - |
| UPDATE/INSERT | proxy_id | ProxyName対応ID | - |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | OnSuccessStepIdとOnSuccessActionの不整合 | OnSuccessAction=GoToStepを指定 |
| - | Stop-Function | OnFailStepIdとOnFailActionの不整合 | OnFailAction=GoToStepを指定 |
| - | Stop-Function | AnalysisXxxでSubsystemServer未指定 | SubsystemServerを指定 |
| - | Stop-Function | SQL 2016以上でActiveScripting使用 | 別のサブシステムを使用 |
| - | Stop-Function | ジョブが存在しない | ジョブ名を確認 |
| - | Stop-Function | ステップが存在しない（Forceなし） | -Forceを追加またはステップ名を確認 |
| - | Stop-Function | データベースが存在しない | データベース名を確認 |
| - | Stop-Function | ユーザーが存在しない | ユーザー名を確認 |
| - | Stop-Function | プロキシが存在しない | プロキシ名を確認 |
| - | Stop-Function | ステップ作成/変更失敗 | エラーメッセージを確認 |

### リトライ仕様

リトライ機能なし。エラー発生時は-Continueにより次の処理を継続。

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

SMOのAlter()メソッドによる暗黙的トランザクション。各ステップの更新は個別のトランザクション。

## パフォーマンス要件

特に定義なし。

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

- sysadmin権限が必要
- プロキシアカウントを使用する場合、適切な資格情報が必要
- WhatIf/Confirmパラメータによる事前確認が可能

## 備考

- SQL Server 2000以上に対応
- ActiveX scripting (ActiveScripting) は SQL Server 2016で非推奨
- 複数サーバー・複数ジョブ・複数ステップの一括変更に対応

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Microsoft.SqlServer.Management.Smo.Agent.JobStep | SMO | ジョブステップオブジェクトのプロパティとメソッド |

**読解のコツ**: JobStepにはSubsystem、Command、OnSuccessAction、OnFailActionなど多くのプロパティがあり、Rename()とAlter()メソッドで変更を反映する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaAgentJobStep.ps1 | `public/Set-DbaAgentJobStep.ps1` | 関数定義、パラメータ、ブロック構造 |

**主要処理フロー**:
1. **203-233行目**: CmdletBinding属性とパラメータ定義
2. **235-256行目**: beginブロック - パラメータ検証
3. **258-428行目**: processブロック - メイン処理
4. **430-433行目**: endブロック - 完了メッセージ

#### Step 3: パラメータ検証を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaAgentJobStep.ps1 | `public/Set-DbaAgentJobStep.ps1` | beginブロックの検証ロジック |

**主要処理フロー**:
- **238-242行目**: OnSuccessStepIdとOnSuccessActionの検証
- **244-248行目**: OnFailStepIdとOnFailActionの検証
- **250-255行目**: AnalysisXxxとSubsystemServerの検証

#### Step 4: ステップ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaAgentJobStep.ps1 | `public/Set-DbaAgentJobStep.ps1` | processブロックのステップ処理 |

**主要処理フロー**:
- **273-275行目**: ActiveScripting + SQL 2016以上の検証
- **277-297行目**: ジョブ/ステップ存在確認と自動作成
- **305-406行目**: 各プロパティの設定
- **408-421行目**: Alter実行と結果出力

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

```
Set-DbaAgentJobStep
    │
    ├─ Connect-DbaInstance
    │
    ├─ JobServer.Jobs[$j] (ジョブ取得)
    │
    ├─ Job.JobSteps (ステップ検索)
    │
    ├─ New-DbaAgentJobStep (-Force時)
    │
    ├─ JobStep.Rename() (名前変更時)
    │
    ├─ Databases[$Database] (DB検証)
    │
    ├─ ProxyAccounts[$ProxyName] (プロキシ検証)
    │
    └─ JobStep.Alter() (コミット)
```

### データフロー図

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

SqlInstance ─────────▶ Connect-DbaInstance
      │                        │
Job名 ──────────────▶ ジョブ取得
      │                        │
StepName ───────────▶ ステップ取得/作成
      │                ├─ 存在: 既存を使用
      │                └─ 不存在+Force: 新規作成
      │                        │
各種パラメータ ────────▶ プロパティ設定
      │                ├─ Subsystem, Command
      │                ├─ OnSuccessAction, OnFailAction
      │                ├─ Database, DatabaseUser
      │                ├─ RetryAttempts, RetryInterval
      │                ├─ OutputFileName, Flag
      │                └─ ProxyName
      │                        │
      ▼                        ▼
                         Alter()
                              │
                              ▼
                   JobStep ───▶ [JobStepオブジェクト出力]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaAgentJobStep.ps1 | `public/Set-DbaAgentJobStep.ps1` | ソース | メイン関数 |
| New-DbaAgentJobStep.ps1 | `public/New-DbaAgentJobStep.ps1` | ソース | ステップ作成（-Force時） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
