# バッチ設計書 41-sdk-task.sh

## 概要

本ドキュメントは、Arcade SDKタスク実行スクリプト（sdk-task.sh）の設計仕様を記載したものです。このスクリプトは、.NETビルドインフラストラクチャであるArcade SDKの各種タスクをLinux/macOS環境で実行するための汎用的なタスクランナーです。

### 本バッチの処理概要

このバッチは、Arcade SDKパッケージ内のSdkTasksディレクトリに定義されたタスクプロジェクトを実行します。MSBuildを使用して指定されたタスクのリストアおよび実行を行い、ビルドパイプラインにおける様々な自動化タスクを統一的に呼び出すことができます。

**業務上の目的・背景**：.NETプロジェクトのビルドプロセスでは、パッケージ署名、NuGetパッケージの発行、SBOM（Software Bill of Materials）生成など、様々な補助タスクが必要です。これらのタスクを個別に管理するのではなく、Arcade SDKという共通のフレームワークで統一的に管理・実行することで、ビルドプロセスの標準化とメンテナンス性の向上を実現します。

**バッチの実行タイミング**：CI/CDパイプラインの各ステージで必要に応じて実行されます。例えば、ビルド後のパッケージ署名、リリース前のパッケージ発行など、特定のビルドフェーズで手動または自動トリガーにより実行されます。

**主要な処理内容**：
1. コマンドライン引数を解析し、実行するタスク名と各種オプションを取得
2. tools.shを読み込み、Arcadeツールセットを初期化
3. 指定されたタスクに対応するプロジェクトファイルを取得
4. リストアオプションが指定されている場合、依存関係をリストア
5. タスクを実行（MSBuildのExecuteターゲットを呼び出し）
6. バイナリログを出力（オプションで無効化可能）

**前後の処理との関連**：tools.shに依存し、InitializeToolset関数でArcade SDKのセットアップを行います。パイプラインのビルドステップ後に実行されることが多く、ビルド成果物に対する後処理を行います。

**影響範囲**：Arcade SDKタスクの実行結果に応じて、パッケージ署名、成果物の発行、SBOMの生成などが行われます。CI/CD環境ではAzure DevOpsの変数やログ出力にも影響を与えます。

## バッチ種別

ツール実行 / SDKタスクランナー

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（CI/CDパイプライン内で必要時） |
| 実行時刻 | パイプラインの進行に応じて |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | CI/CDパイプラインのステップとして実行 / 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Arcade SDKのインストール | NuGetパッケージとしてArcade SDKがリストア済みであること |
| tools.shの存在 | 同一ディレクトリにtools.shが存在すること |
| .NET SDKのインストール | dotnet CLIが利用可能であること |
| タスクプロジェクトの存在 | SdkTasksディレクトリに対象タスクのプロジェクトが存在すること |

### 実行可否判定

- `--task`パラメータが指定されていない場合はエラー終了
- 指定されたタスクに対応するプロジェクトファイルが存在しない場合はエラー終了

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --task | string | Yes | なし | 実行するArcade SDKタスクの名前 |
| --restore | flag | No | false | 依存関係のリストアを実行する |
| --verbosity | string | No | minimal | MSBuildの詳細度（q/m/n/d/diag） |
| --excludeCIBinarylog / -nobl | flag | No | false | バイナリログ出力を無効化 |
| --noWarnAsError | flag | No | false | 警告をエラーとして扱わない |
| --help | flag | No | false | ヘルプメッセージを表示 |
| その他 | string | No | なし | MSBuildに直接渡されるパラメータ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| global.json | JSON | SDKバージョンやツールセットの設定 |
| SdkTasksプロジェクト | .proj | Arcade SDKタスク定義ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| バイナリログ | .binlog | MSBuildのバイナリログ（オプション） |
| 標準出力 | テキスト | タスク実行結果とログ |
| 終了コード | 整数 | 0: 成功、1以上: エラー |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | {task名}.binlog または {task名}.{target}.binlog |
| 出力先 | $log_dir（artifacts/log/$configuration） |
| 文字コード | バイナリ（.binlog形式） |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数の解析
   └─ --task, --restore, --verbosity等のオプションを解析
2. スクリプトルートの解決
   └─ シンボリックリンクを辿って実際のパスを取得
3. tools.shの読み込み
   └─ Arcade共通ツール関数をインポート
4. ツールセットの初期化
   └─ InitializeToolset関数を呼び出し
5. タスク名の検証
   └─ --taskパラメータが指定されているか確認
6. タスクプロジェクトの取得
   └─ GetSdkTaskProject関数でプロジェクトパスを取得
7. タスクプロジェクトの存在確認
   └─ ファイルが存在しない場合はエラー終了
8. リストアの実行（オプション）
   └─ --restoreが指定されている場合、Restoreターゲットを実行
9. タスクの実行
   └─ Executeターゲットを呼び出してタスクを実行
10. 終了処理
    └─ 終了コード0で正常終了
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[引数解析]
    B --> C[tools.sh読み込み]
    C --> D[ツールセット初期化]
    D --> E{--task指定あり?}
    E -->|なし| F[エラー: MissingTask]
    E -->|あり| G[タスクプロジェクト取得]
    G --> H{プロジェクト存在?}
    H -->|なし| I[エラー: UnknownTask]
    H -->|あり| J{--restore指定?}
    J -->|あり| K[Restoreターゲット実行]
    K --> L[Executeターゲット実行]
    J -->|なし| L
    L --> M[終了コード0で終了]
    F --> N[終了コード1で終了]
    I --> N
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | - | - | このバッチはデータベース操作を行いません |

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

このバッチはデータベース操作を行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | MissingTask | --taskパラメータが未指定 | --taskパラメータを指定して再実行 |
| 1 | UnknownTask | 指定されたタスクのプロジェクトが存在しない | 正しいタスク名を指定するか、Arcade SDKをリストア |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（スクリプト自体ではリトライなし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

1. エラーメッセージを確認し、タスク名が正しいか確認
2. Arcade SDKが正しくリストアされているか確認
3. --restoreオプションを指定して再実行
4. バイナリログを確認して詳細なエラー原因を調査

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | タスクごとに異なる |
| 目標処理時間 | タスクごとに異なる（数秒〜数分） |
| メモリ使用量上限 | MSBuildの設定に依存 |

## 排他制御

同一タスクの同時実行は推奨されません。CI環境ではノード再利用（node_reuse）がfalseに設定され、ビルドプロセス間の干渉を防ぎます。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 暗黙的 | MSBuildの標準出力による |
| 進捗ログ | 処理中 | MSBuildの詳細度に応じたログ |
| 終了ログ | バッチ終了時 | 暗黙的（終了コードで判断） |
| エラーログ | エラー発生時 | Write-PipelineTelemetryErrorによるAzure DevOps形式のエラー |
| バイナリログ | 処理完了時 | $log_dir/{task}.binlog |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | Azure DevOpsパイプラインのタスク失敗通知 |
| 処理時間 | タスクごとに設定 | パイプラインのタイムアウト設定に依存 |

## 備考

- このスクリプトはArcade SDKフレームワークの一部として提供されており、.NETリポジトリ全体で共通して使用されます
- CI環境では`ci=true`が自動的に設定され、パイプライン向けのログ出力が有効になります
- バイナリログはデフォルトで有効ですが、`--nobl`オプションで無効化できます
