# 画面設計書 168-診断ノートブック

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける診断ノートブック生成機能（New-DbaDiagnosticAdsNotebook）の画面設計書です。Glenn BerryのSQL Server診断クエリをAzure Data Studio用のJupyter Notebook形式に変換する機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：Azure Data Studioで直接実行可能なJupyter Notebook形式（.ipynb）でGlenn Berryの診断クエリを提供します。各クエリには説明を含むMarkdownセルが付随し、パフォーマンストラブルシューティングや健全性監視に必要なコンテキストを提供します。

**画面へのアクセス方法**：PowerShellコマンドラインから `New-DbaDiagnosticAdsNotebook` コマンドレットを実行してアクセスします。

**主要な操作・処理内容**：
1. SQL Serverインスタンスに接続してバージョンを検出、またはTargetVersionパラメータで直接指定
2. バージョンに対応する診断クエリスクリプトを取得
3. 各クエリをMarkdown説明セルとSQLコードセルの組み合わせに変換
4. Jupyter Notebook形式（.ipynb）のJSONファイルを出力

**画面遷移**：本機能は単独のコマンドレットとして動作します。生成されたノートブックはAzure Data Studioで開いて使用します。

**権限による表示制御**：SqlInstance指定時はSQL Serverへの接続権限が必要です。TargetVersion指定時は接続不要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 216 | New-DbaDiagnosticAdsNotebook | 主機能 | 診断ノートブックの生成 |
| 214 | Invoke-DbaDiagnosticQuery | 連携機能 | 診断クエリの実行 |
| 327 | Connect-DbaInstance | 内部呼出 | SQL Serverインスタンスへの接続（バージョン検出時） |

## 画面種別

CLI（コマンドラインインターフェース）- ファイル生成

## URL/ルーティング

PowerShellコマンド: `New-DbaDiagnosticAdsNotebook`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter | No* | 接続先SQL Serverインスタンス（バージョン自動検出） |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 |
| TargetVersion | string | No* | 対象SQL Serverバージョン（2005/2008/2008R2/2012/2014/2016/2016SP2/2017/2019/2022/AzureSQLDatabase） |
| Path | string | Yes | 出力先ファイルパス（.ipynb） |
| IncludeDatabaseSpecific | switch | No | データベース固有クエリを含める |
| EnableException | switch | No | 例外を有効化 |

*SqlInstanceまたはTargetVersionのいずれかが必須

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FullName | string | 生成されたノートブックの完全パス |
| Name | string | ノートブックのファイル名 |
| DirectoryName | string | 出力先ディレクトリパス |
| Length | long | ファイルサイズ（バイト） |
| CreationTime | DateTime | ファイル作成日時 |
| LastWriteTime | DateTime | ファイル最終更新日時 |

## 表示項目

出力はFileInfoオブジェクトとして返され、生成されたノートブックファイルの情報がPowerShellコンソールに表示されます。

## イベント仕様

### 1-コマンド実行

1. **パラメータ検証**（行93-101）: SqlInstanceとTargetVersionの排他チェック
2. **バージョン取得**（行103-138）: SqlInstance指定時はInvoke-DbaQueryでバージョン検出
3. **スクリプト取得**（行140-145）: バージョン対応の診断クエリスクリプトを取得
4. **セル生成**（行147-152）: 各クエリをMarkdownセルとCodeセルに変換
5. **ノートブック構築**（行154-169）: Jupyter Notebook形式のオブジェクト構築
6. **ファイル出力**（行171-172）: JSONファイルとして書き出し、FileInfo返却

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| バージョン検出 | SERVERPROPERTY関数 | SELECT | SQL Serverバージョン情報取得 |
| ノートブック生成 | ファイルシステム | WRITE | .ipynbファイル作成 |

### バージョン検出クエリ

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

## メッセージ仕様

| メッセージタイプ | 条件 | メッセージ内容 |
|-----------------|------|---------------|
| Error | 両パラメータ未指定 | "At least one of $SqlInstance and $TargetVersion must be provided" |
| Error | 両パラメータ指定 | "Cannot provide both $SqlInstance and $TargetVersion" |
| Error | 接続失敗 | "Failure" |
| Error | スクリプト未発見 | "No diagnostic queries available for $TargetVersion = {Version}" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SqlInstanceとTargetVersion両方未指定 | Stop-Functionでエラーメッセージを出力して終了 |
| SqlInstanceとTargetVersion両方指定 | Stop-Functionでエラーメッセージを出力して終了 |
| SQL Server接続失敗 | Stop-Functionでエラーを記録して終了 |
| 対応バージョンのスクリプト未発見 | Stop-Functionでエラーを記録して終了 |

## 備考

- Azure Data Studio用のJupyter Notebook形式（.ipynb）を生成
- ノートブックには各クエリのMarkdown説明とSQLコードセルが含まれる
- kernelspecはSQLを指定（Azure Data StudioのSQL Kernelで実行）
- -IncludeDatabaseSpecificでデータベース固有クエリも含めることが可能
- TargetVersion指定時は接続不要でオフラインでノートブック生成可能

---

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

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

### 推奨読解順序

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

出力されるノートブックのJupyter形式構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaDiagnosticAdsNotebook.ps1 | `public/New-DbaDiagnosticAdsNotebook.ps1` | 行68-80の.OUTPUTSセクション |

**読解のコツ**: 出力はFileInfoオブジェクトであり、ノートブック自体はJSON形式の.ipynbファイルとして保存される点に注目。

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

パラメータ検証とバージョン検出を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDiagnosticAdsNotebook.ps1 | `public/New-DbaDiagnosticAdsNotebook.ps1` | 行82-91のパラメータ定義 |
| 2-2 | New-DbaDiagnosticAdsNotebook.ps1 | `public/New-DbaDiagnosticAdsNotebook.ps1` | 行93-101のパラメータ検証 |

**主要処理フロー**:
1. **行95-97**: SqlInstanceもTargetVersionも未指定時のエラー
2. **行98-101**: 両方指定時のエラー
3. **行103-138**: SqlInstance指定時のバージョン自動検出

#### Step 3: スクリプト取得とセル生成を理解する

診断クエリスクリプトの取得とノートブックセルへの変換を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDiagnosticAdsNotebook.ps1 | `public/New-DbaDiagnosticAdsNotebook.ps1` | 行140-145のスクリプト取得 |
| 3-2 | New-DbaDiagnosticAdsNotebook.ps1 | `public/New-DbaDiagnosticAdsNotebook.ps1` | 行147-152のセル生成ループ |

**主要処理フロー**:
- **行140**: Get-ChildItemでバージョン対応スクリプト取得
- **行149**: Invoke-DbaDiagnosticQueryScriptParserでクエリ解析
- **行150**: Markdownセル（説明）追加
- **行151**: Codeセル（SQLクエリ）追加

#### Step 4: ノートブック出力を理解する

Jupyter Notebook形式のJSON構築とファイル出力を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaDiagnosticAdsNotebook.ps1 | `public/New-DbaDiagnosticAdsNotebook.ps1` | 行154-169のノートブック構造 |
| 4-2 | New-DbaDiagnosticAdsNotebook.ps1 | `public/New-DbaDiagnosticAdsNotebook.ps1` | 行171-172のファイル出力 |

**主要処理フロー**:
- **行154-169**: metadata（kernelspec、language_info）とcellsを持つオブジェクト構築
- **行171**: ConvertTo-JsonでJSON変換し、WriteAllLinesで出力
- **行172**: Get-ChildItemで出力ファイル情報を返却

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

```
New-DbaDiagnosticAdsNotebook
    |
    +-- パラメータ検証 (行93-101)
    |       └── SqlInstance/TargetVersionの排他チェック
    |
    +-- [SqlInstance指定時]
    |       |
    |       +-- Invoke-DbaQuery (行123)
    |       |       └── SERVERPROPERTYでバージョン取得
    |       |
    |       └── バージョン文字列決定 (行129-137)
    |               └── ProductMajorVersion/ProductMinorVersionからマッピング
    |
    +-- Get-ChildItem (行140)
    |       └── 診断クエリスクリプトファイル取得
    |
    +-- Invoke-DbaDiagnosticQueryScriptParser (行149)
    |       └── スクリプト解析
    |
    +-- [セル生成ループ] (行149-152)
    |       |
    |       +-- Markdownセル追加 (行150)
    |       |       └── クエリ名と説明
    |       |
    |       └── Codeセル追加 (行151)
    |               └── SQLクエリテキスト
    |
    +-- オブジェクト構築 (行154-169)
    |       └── Jupyter Notebook形式のハッシュテーブル
    |
    +-- ConvertTo-Json (行171)
    |       └── JSON文字列に変換
    |
    +-- [IO.File]::WriteAllLines (行171)
    |       └── ファイル書き込み
    |
    └── Get-ChildItem (行172)
            └── 出力ファイル情報返却
```

### データフロー図

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

SqlInstance ─────────────────┐
                             │
SqlCredential ───────────────┼──> [バージョン自動検出]
                             │          │
                             │          v
                             │   Invoke-DbaQuery
                             │   (SERVERPROPERTY)
                             │          │
TargetVersion ───────────────┼──────────┴──> TargetVersion決定
                             │                     │
                             │                     v
                             │            Get-ChildItem
                             │   (SQLServerDiagnosticQueries_{Version}.sql)
                             │                     │
                             │                     v
                             │   Invoke-DbaDiagnosticQueryScriptParser
                             │                     │
IncludeDatabaseSpecific ─────┼──────> Where-Object フィルタ
                             │                     │
                             │                     v
                             │            [セル生成ループ]
                             │                     │
                             │            +── Markdownセル（説明）
                             │            └── Codeセル（SQL）
                             │                     │
                             │                     v
                             │            ノートブック構造構築
                             │            (metadata, nbformat, cells)
                             │                     │
                             │                     v
Path ────────────────────────┼──────> ConvertTo-Json
                             │                     │
                             │                     v
                             │            WriteAllLines
                             │                     │
                             │                     v
                             └──────────> FileInfo (.ipynb)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDiagnosticAdsNotebook.ps1 | `public/New-DbaDiagnosticAdsNotebook.ps1` | ソース | 診断ノートブック生成の実装 |
| Invoke-DbaDiagnosticQueryScriptParser.ps1 | `internal/Invoke-DbaDiagnosticQueryScriptParser.ps1` | 内部関数 | スクリプト解析 |
| SQLServerDiagnosticQueries_*.sql | `bin/diagnosticquery/` | スクリプト | Glenn Berry診断クエリ |
