# 機能設計書 192-New-DbaDiagnosticAdsNotebook

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`New-DbaDiagnosticAdsNotebook`機能の設計仕様を記載する。この機能は、Glenn Berryの診断クエリをAzure Data Studio用のJupyter Notebook形式に変換して出力する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのパフォーマンス監視やトラブルシューティングにおいて、Glenn Berryの診断クエリは業界標準として広く使用されている。本機能は、これらのクエリをAzure Data Studioで直接実行可能なJupyter Notebook形式に変換することで、DBAの作業効率を向上させる。バージョン固有のクエリを自動的に選択し、説明付きのノートブックを生成する。

**機能の利用シーン**：
- SQL Serverのヘルスチェック実施前の準備作業
- パフォーマンストラブルシューティング用の診断ツール作成
- 定期的な監視レポート用のノートブック生成
- オフライン環境用の診断スクリプト準備

**主要な処理内容**：
1. SqlInstanceまたはTargetVersionパラメータに基づいてSQL Serverバージョンを特定
2. バージョンに対応する診断クエリSQLファイルを特定
3. 診断クエリスクリプトをパースしてクエリ情報を抽出
4. Jupyter Notebook形式（.ipynb）のJSON構造を構築
5. 各クエリをMarkdownセルとCodeセルのペアとして配置
6. 指定パスにノートブックファイルを出力

**関連システム・外部連携**：Azure Data Studio（Jupyter Notebook実行環境）、Glenn Berryの診断クエリスクリプト群。

**権限による制御**：SqlInstance指定時はSQL Serverへの接続権限が必要。ファイル出力先への書き込み権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 168 | 診断ノートブック | 主機能 | Azure Data Studio診断ノートブックの作成 |

## 機能種別

帳票出力 / ファイル生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter | No | SQL Serverインスタンス名（バージョン自動検出用） | TargetVersionと排他 |
| SqlCredential | PSCredential | No | SQL Server認証情報 | - |
| TargetVersion | string | No | 対象SQL Serverバージョン | ValidateSet制限 |
| Path | string | Yes | 出力ファイルパス（.ipynb） | Mandatory |
| IncludeDatabaseSpecific | switch | No | データベース固有クエリを含める | - |
| EnableException | switch | No | 例外をスローするかどうか | - |

**TargetVersionの有効値**：2005, 2008, 2008R2, 2012, 2014, 2016, 2016SP2, 2017, 2019, 2022, AzureSQLDatabase

### 入力データソース

- パラメータ入力: SqlInstance、TargetVersion、Path
- 内部リソース: `$script:PSModuleRoot/bin/diagnosticquery/SQLServerDiagnosticQueries_*.sql`

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FileInfo | System.IO.FileInfo | 作成されたノートブックファイルの情報 |

### 出力先

指定パスへのJupyter Notebook（.ipynb）ファイル出力。

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   ├─ SqlInstanceとTargetVersionの排他チェック
   └─ 少なくとも1つが指定されているかチェック
2. バージョン特定
   ├─ TargetVersion指定時: そのまま使用
   └─ SqlInstance指定時: クエリでバージョン情報取得
       ├─ ProductMajorVersion/ProductMinorVersion取得
       ├─ Azure SQL判定（Edition = "SQL Azure"）
       └─ SP2特別処理（2016のみ）
3. 診断クエリファイル特定
   └─ SQLServerDiagnosticQueries_{Version}.sql検索
4. クエリパース
   └─ Invoke-DbaDiagnosticQueryScriptParserでパース
5. Notebookセル構築
   ├─ DBSpecificフィルタリング
   ├─ Markdownセル（タイトル+説明）生成
   └─ Codeセル（SQLクエリ）生成
6. Notebook JSON構造構築
   ├─ metadata（kernelspec, language_info）
   ├─ nbformat: 4, nbformat_minor: 2
   └─ cells配列
7. ファイル出力
   └─ ConvertTo-Json → WriteAllLines
8. FileInfo返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance/TargetVersion両方指定?}
    B -->|Yes| C[エラー終了]
    B -->|No| D{どちらか指定?}
    D -->|No| C
    D -->|Yes| E{TargetVersion指定?}
    E -->|Yes| F[TargetVersionを使用]
    E -->|No| G[SQL Serverに接続してバージョン取得]
    G --> H{Azure SQL?}
    H -->|Yes| I[TargetVersion = AzureSQLDatabase]
    H -->|No| J[バージョンマップから取得]
    J --> K{2016 SP2?}
    K -->|Yes| L[TargetVersion += SP2]
    K -->|No| M[TargetVersionを設定]
    I --> N[診断クエリファイル検索]
    L --> N
    M --> N
    F --> N
    N --> O{ファイル存在?}
    O -->|No| C
    O -->|Yes| P[クエリスクリプトパース]
    P --> Q[Notebookセル生成]
    Q --> R[JSON構造構築]
    R --> S[ファイル出力]
    S --> T[FileInfo返却]
    T --> U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 排他パラメータ | SqlInstanceとTargetVersionは同時指定不可 | 常時 |
| BR-002 | 必須パラメータ | SqlInstanceまたはTargetVersionのいずれかは必須 | 常時 |
| BR-003 | DBSpecificフィルタ | IncludeDatabaseSpecific未指定時はサーバーレベルクエリのみ | 常時 |
| BR-004 | バージョンマップ | ProductMajorVersion.ProductMinorVersionからバージョン名に変換 | SqlInstance指定時 |
| BR-005 | SP2特別処理 | SQL 2016のSP2は別バージョンとして扱う | SQL 2016かつSP2の場合 |

### 計算ロジック

**バージョンマッピング**:
| ProductMajorVersion.ProductMinorVersion | TargetVersion |
|----------------------------------------|---------------|
| 9.0 | 2005 |
| 10.0 | 2008 |
| 10.50 | 2008R2 |
| 11.0 | 2012 |
| 12.0 | 2014 |
| 13.0 | 2016 |
| 14.0 | 2017 |
| 15.0 | 2019 |
| 16.0 | 2022 |

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| バージョン取得 | - | SELECT | SERVERPROPERTY関数によるメタデータ取得 |

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

#### バージョン情報取得クエリ

```sql
SELECT SERVERPROPERTY('ProductMajorVersion') AS ProductMajorVersion,
       SERVERPROPERTY('ProductMinorVersion') AS ProductMinorVersion,
       SERVERPROPERTY('ProductLevel') AS ProductLevel,
       SERVERPROPERTY('Edition') AS Edition
```

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | SqlInstanceとTargetVersion両方未指定 | いずれか1つを指定 |
| - | Stop-Function | SqlInstanceとTargetVersion両方指定 | いずれか1つのみ指定 |
| - | Stop-Function | SQL Server接続失敗 | 接続情報を確認 |
| - | Stop-Function | 該当バージョンの診断クエリファイルなし | サポートバージョンを確認 |

### リトライ仕様

本機能にリトライ機能はない。

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

データベースへの書き込み操作がないため、トランザクション処理は不要。

## パフォーマンス要件

特になし。ファイル出力のため、大量の診断クエリでも処理時間は軽微。

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

- SqlCredentialで認証情報を安全に渡す
- 出力ファイルには機密情報は含まれない（クエリ定義のみ）
- 実行時のクエリ結果は含まれないため、データ漏洩リスクはない

## 備考

- Glenn Berryの診断クエリは定期的に更新されるため、dbatoolsのバージョンアップで新しいクエリが追加される
- 生成されるノートブックはAzure Data StudioまたはJupyter環境で実行可能

---

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

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

### 推奨読解順序

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

Jupyter Notebook（.ipynb）のJSON構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Jupyter Notebook Format | - | nbformat 4のcells、metadata構造 |

**読解のコツ**: .ipynbファイルはJSON形式で、cells配列にmarkdownセルとcodeセルが格納される。

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

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

**主要処理フロー**:
1. **92-101行目**: パラメータ検証（排他チェック）
2. **103-138行目**: バージョン特定処理
3. **140-145行目**: 診断クエリファイル検索
4. **147-152行目**: クエリパースとセル生成
5. **154-169行目**: Notebook JSON構造構築
6. **171-172行目**: ファイル出力とFileInfo返却

#### Step 3: バージョン特定処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDiagnosticAdsNotebook.ps1 | `public/New-DbaDiagnosticAdsNotebook.ps1` | バージョン判定ロジック |

**主要処理フロー**:
- **104-108行目**: SERVERPROPERTY取得クエリ定義
- **110-120行目**: バージョンマッピング辞書
- **122-127行目**: Invoke-DbaQueryでバージョン情報取得
- **129-137行目**: Azure SQL判定とバージョン変換

#### Step 4: Notebook生成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaDiagnosticAdsNotebook.ps1 | `public/New-DbaDiagnosticAdsNotebook.ps1` | セル生成とJSON構築 |

**主要処理フロー**:
- **149-152行目**: Invoke-DbaDiagnosticQueryScriptParserでパース
- **150行目**: Markdownセル生成（タイトル+説明）
- **151行目**: Codeセル生成（SQLクエリ）
- **154-169行目**: Notebook構造（metadata、cells）構築

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

```
New-DbaDiagnosticAdsNotebook
    │
    ├─ Invoke-DbaQuery
    │      └─ バージョン情報取得
    │
    ├─ Get-ChildItem
    │      └─ 診断クエリファイル検索
    │
    ├─ Invoke-DbaDiagnosticQueryScriptParser
    │      └─ SQLスクリプトパース
    │
    ├─ ConvertTo-Json
    │      └─ Notebook JSON変換
    │
    └─ [IO.File]::WriteAllLines
           └─ ファイル出力
```

### データフロー図

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

SqlInstance ───────────────┐
    または                  │
TargetVersion ─────────────┼──▶ バージョン特定
                           │         │
                           │         ▼
                           │    診断クエリファイル検索
                           │         │
IncludeDatabaseSpecific ───┤         ▼
                           │    クエリパース
                           │         │
                           │         ▼
Path ──────────────────────┼──▶ Notebook JSON生成 ──────────────▶ .ipynb ファイル
                                     │
                                     ▼
                                FileInfo返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDiagnosticAdsNotebook.ps1 | `public/New-DbaDiagnosticAdsNotebook.ps1` | ソース | メイン関数定義 |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | SQLクエリ実行 |
| Invoke-DbaDiagnosticQueryScriptParser.ps1 | `private/functions/Invoke-DbaDiagnosticQueryScriptParser.ps1` | ソース | 診断クエリパーサー |
| SQLServerDiagnosticQueries_*.sql | `bin/diagnosticquery/` | リソース | Glenn Berry診断クエリ群 |
