# 機能設計書 214-Save-DbaDiagnosticQueryScript

## 概要

本ドキュメントは、Glenn Berry氏のSQL Server診断クエリスクリプトをダウンロードするSave-DbaDiagnosticQueryScript関数の機能設計書です。

### 本機能の処理概要

Save-DbaDiagnosticQueryScriptは、Glenn Berry氏のウェブサイトから最新バージョンのSQL Server Diagnostic Information Queriesをダウンロードします。これらのDMVベースのスクリプトは、DBAがSQL Serverの健全性を評価し、パフォーマンスのボトルネックを特定し、Azure SQL Database、Managed Instanceを含むすべてのSQL Serverバージョンにわたる包括的なシステム情報を収集するための必須ツールです。

**業務上の目的・背景**：Glenn Berry氏のDiagnostic Information Queriesは、SQL Serverのパフォーマンス監視とトラブルシューティングにおいて業界標準のツールセットです。dbatoolsモジュールには診断クエリが事前インストールされていますが、Glenn Berry氏は定期的にスクリプトを更新しているため、最新版へのアップデートが必要になります。本機能は、複数のSQL Serverバージョン向けのスクリプトを一括でダウンロードし、バージョン固有のファイル名で保存します。

**機能の利用シーン**：
- Invoke-DbaDiagnosticQueryで使用する最新のスクリプトを取得する場合
- インターネット接続のあるデバイスで事前にスクリプトをダウンロードし、オフライン環境で使用する場合
- 特定のSQL Serverバージョン向けのスクリプトを取得する場合

**主要な処理内容**：
1. Glenn Berry氏のリソースページからDropboxリンクを抽出
2. 各SQL Serverバージョンのスクリプトを識別
3. ファイルをダウンロードし、バージョン固有のファイル名で保存
4. ダウンロードしたファイル情報を出力

**関連システム・外部連携**：
- Glenn Berry氏のリソースページ（https://glennsqlperformance.com/resources/）
- Dropbox（スクリプトファイルのホスティング）

**権限による制御**：指定されたパスへの書き込み権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIインターフェース | 主画面 | コマンドライン実行 |

## 機能種別

ファイルダウンロード / ユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | System.IO.FileInfo | No | ダウンロード先ディレクトリ | デフォルト: マイドキュメント、存在するディレクトリ |
| EnableException | switch | No | 例外を有効化 | スイッチ型 |

### 入力データソース

- Glenn Berry氏のリソースページ（Webスクレイピング）
- DropboxダウンロードURL

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FileInfo | System.IO.FileInfo | ダウンロードした各ファイルの情報 |

### 出力先

- 指定されたPathディレクトリ
- ファイル名形式: SQLServerDiagnosticQueries_{バージョン}.sql

## 処理フロー

### 処理シーケンス

```
1. パス検証
   └─ 指定ディレクトリの存在確認

2. リソースページ取得
   └─ Glenn Berry氏のリソースページをダウンロード

3. Dropbox URLの抽出
   └─ 正規表現でDropbox .sql URLを検出

4. バージョン情報の解析
   └─ URLからSQL Serverバージョンを抽出

5. ファイルダウンロード
   └─ 各URLからファイルをダウンロード、保存

6. ファイル情報の出力
   └─ Get-ChildItemで保存ファイル情報を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Path存在?}
    B -->|No| C[エラー終了]
    B -->|Yes| D[リソースページ取得]

    D --> E{取得成功?}
    E -->|No| F[プロキシ設定で再試行]
    F --> G{再試行成功?}
    G -->|No| C
    G -->|Yes| H[Dropbox URL抽出]
    E -->|Yes| H

    H --> I{URL発見?}
    I -->|No| C
    I -->|Yes| J[重複URL除去]

    J --> K[バージョン情報解析]
    K --> L[URLごとにループ]

    L --> M[ファイルダウンロード]
    M --> N[ファイル保存]
    N --> O[FileInfo出力]
    O --> P{次のURL?}
    P -->|Yes| L
    P -->|No| Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトパス | Path未指定時はマイドキュメントフォルダ | Path未指定 |
| BR-002 | URLパターン | Dropbox URLの両形式（新旧）をサポート | 常時 |
| BR-003 | バージョン識別 | URLからSQL Server年号とSP/R2情報を抽出 | 常時 |
| BR-004 | Azure対応 | Azure SQL Database/Managed Instance用スクリプトも取得 | 常時 |
| BR-005 | ファイル命名 | SQLServerDiagnosticQueries_{バージョン}.sql形式 | 常時 |
| BR-006 | dl=0→dl=1変換 | Dropbox URLのダウンロードパラメータを変換 | 常時 |

### 計算ロジック

該当なし

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

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

該当なし（データベース操作なし）

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パス未存在 | 指定Pathが存在しない | エラーメッセージ出力、処理終了 |
| - | ページ取得失敗 | リソースページへのアクセス失敗 | プロキシ設定で再試行後、エラー終了 |
| - | 空コンテンツ | リソースページが空 | エラーメッセージ出力 |
| - | URL未発見 | ページ構造変更でURLが見つからない | エラーメッセージ出力 |
| - | ダウンロード失敗 | ファイルダウンロードに失敗 | エラーメッセージ出力 |

### リトライ仕様

- リソースページ取得失敗時、デフォルトプロキシ設定で1回リトライ

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

該当なし（ファイルシステム操作）

## パフォーマンス要件

- 複数ファイルを順次ダウンロード
- ネットワーク帯域に依存

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

- HTTPSでリソースページとDropboxにアクセス
- プロキシ認証のサポート

## 備考

- System.Web アセンブリを追加読み込み（URLデコード用）
- Glenn Berry氏のサイト構造変更時は処理調整が必要
- 対応バージョン: SQL Server 2008〜最新、Azure SQL Database、Azure SQL Managed Instance

---

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

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

### 推奨読解順序

#### Step 1: パラメータとエントリーポイントを理解する

関数の入口と検証ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Save-DbaDiagnosticQueryScript.ps1 | `public/Save-DbaDiagnosticQueryScript.ps1` 56-65行目 | パラメータ定義、デフォルト値 |

**読解のコツ**: PathパラメータのデフォルトはEnvironment::GetFolderPath("mydocuments")で、マイドキュメントフォルダになります。

#### Step 2: リソースページ取得処理を理解する

Webページ取得のロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Save-DbaDiagnosticQueryScript.ps1 | `public/Save-DbaDiagnosticQueryScript.ps1` 62-88行目 | パス検証、ページ取得、プロキシフォールバック |

**主要処理フロー**:
1. **62-65行目**: パス存在確認
2. **67-68行目**: System.Webアセンブリ読み込み
3. **69-83行目**: リソースページ取得（プロキシフォールバック付き）
4. **85-88行目**: 空コンテンツチェック

#### Step 3: URL抽出とバージョン解析を理解する

正規表現によるURL抽出とバージョン識別を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Save-DbaDiagnosticQueryScript.ps1 | `public/Save-DbaDiagnosticQueryScript.ps1` 90-200行目 | 正規表現パターン、バージョン抽出ロジック |

**主要処理フロー**:
- **94-95行目**: Dropbox URLの正規表現パターン
- **99行目**: dl=0→dl=1変換
- **105-143行目**: URLからSQLバージョン抽出（複数パターン対応）
- **149行目**: 重複URL除去
- **152-200行目**: バージョン情報オブジェクト構築

#### Step 4: ダウンロード処理を理解する

ファイルダウンロードと出力を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Save-DbaDiagnosticQueryScript.ps1 | `public/Save-DbaDiagnosticQueryScript.ps1` 209-223行目 | ダウンロード実行、ファイル出力 |

**主要処理フロー**:
- **211-214行目**: &amp;→&変換（HTMLエンティティ対策）
- **216行目**: ファイル名生成
- **217行目**: Invoke-TlsWebRequestでダウンロード
- **218行目**: Get-ChildItemでFileInfo出力

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

```
Save-DbaDiagnosticQueryScript
    │
    ├─ Test-Path (パス検証)
    │
    ├─ Add-Type (System.Web読み込み)
    │
    ├─ Invoke-TlsWebRequest (ページ/ファイル取得)
    │      └─ プロキシ設定フォールバック
    │
    ├─ [regex]::Matches (URL抽出)
    │
    ├─ [System.Web.HttpUtility]::UrlDecode (URLデコード)
    │
    ├─ Write-ProgressHelper (進捗表示)
    │
    └─ Get-ChildItem (ファイル情報出力)
```

### データフロー図

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

Path              ───▶ リソースページ取得   ───▶
                            │
                            ▼
                  ───▶ URL正規表現抽出     ───▶
                            │
                            ▼
                  ───▶ バージョン解析       ───▶
                            │
                            ▼
                  ───▶ ファイルダウンロード ───▶ System.IO.FileInfo[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Save-DbaDiagnosticQueryScript.ps1 | `public/Save-DbaDiagnosticQueryScript.ps1` | ソース | メイン関数 |
| Invoke-TlsWebRequest.ps1 | `private/functions/Invoke-TlsWebRequest.ps1` | ソース | TLS対応Webリクエスト |
| Write-ProgressHelper.ps1 | `private/functions/Write-ProgressHelper.ps1` | ソース | 進捗表示ヘルパー |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理 |
