# 機能設計書 640-Get-DbaFilestream

## 概要

本ドキュメントは、dbatools PowerShellモジュールのGet-DbaFilestreamコマンドレットの機能設計書である。このコマンドは、SQL Serverサービスレベルとインスタンスレベルの両方でFileStream構成ステータスを取得し、FileStream機能の設定状況を包括的に確認できる。

### 本機能の処理概要

Get-DbaFilestreamは、SQL Serverサービス構成とインスタンスレベルのsp_configure設定の両方をチェックしてFileStream構成ステータスを取得する。サービスレベルとインスタンスレベル間のFileStream構成の不一致を迅速に特定できるため、FileStream機能問題の一般的な原因を発見するのに役立つ。詳細なアクセスレベル、共有名、構成変更を適用するために再起動が保留中かどうかを返す。

**業務上の目的・背景**：FileStreamはSQL Serverの機能で、大きなバイナリファイル（画像、ドキュメントなど）をファイルシステムに格納しながらSQL Serverで管理できるようにする。しかし、FileStreamの有効化には、Windowsサービスレベルの設定とSQL Serverインスタンスレベルの設定の2つが必要であり、これらが一致していないと機能が正しく動作しない。このコマンドは、両方のレベルの設定を一度に確認し、不一致を発見するのに役立つ。

**機能の利用シーン**：
- FileStream機能のトラブルシューティング
- FileStream設定の監査・ドキュメント化
- インスタンス設定後の構成確認
- 複数サーバーにまたがるFileStream設定の一括確認
- 再起動保留状態の確認

**主要な処理内容**：
1. サービスレベル情報の取得（WMI経由）
2. インスタンスレベル情報の取得（sp_configure経由）
3. 両レベルの設定を比較し、再起動保留状態を判定
4. 結果をPSCustomObjectとして出力

**関連システム・外部連携**：Set-DbaFilestream（FileStream設定変更）、Get-DbaSpConfigure（インスタンス構成取得）と連携

**権限による制御**：WMI接続にはWindows管理者権限、sp_configureクエリにはVIEW SERVER STATE権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン/PowerShellコンソール | 主画面 | コマンド実行および結果表示 |

## 機能種別

データ取得 / 構成確認

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | No | 対象SQL Serverインスタンス。複数指定可、パイプライン入力対応 | なし |
| SqlCredential | PSCredential | No | SQL Server認証用の代替資格情報 | Windows認証、SQL認証、AD認証対応 |
| Credential | PSCredential | No | Windows認証用の代替資格情報（WMI接続用） | なし |
| EnableException | switch | No | 例外を有効にして詳細なエラー情報を取得 | なし |

### 入力データソース

- サービスレベル情報：WMI FilestreamSettingsクラス（root\Microsoft\SQLServer\ComputerManagement*）
- インスタンスレベル情報：sp_configure 'filestream access level'

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なSQL Serverインスタンス名 |
| InstanceAccess | String | インスタンスレベルのFileStreamアクセス（Disabled、T-SQL access enabled、Full access enabled） |
| ServiceAccess | String | サービスレベルのFileStreamアクセス（Disabled〜Full access） |
| ServiceShareName | String | FileStream用のWindowsファイル共有名 |
| InstanceAccessLevel | Int | インスタンスレベルのアクセス数値コード（0-2） |
| ServiceAccessLevel | Int | サービスレベルのアクセス数値コード（0-3） |
| Credential | PSCredential | 使用されたWindows資格情報 |
| SqlCredential | PSCredential | 使用されたSQL Server資格情報 |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. 初期化（beginブロック）
   └─ サービスレベルFS値の定義（0-3）
   └─ インスタンスレベルFS値の定義（0-2）

2. インスタンスごとの処理ループ
   └─ コンピュータ名とインスタンス名を抽出

3. サービスレベル情報取得
   └─ Resolve-DbaNetworkNameでコンピュータ名を解決
   └─ WMIネームスペース（ComputerManagement*）を検索
   └─ FilestreamSettingsクラスをクエリ

4. インスタンスレベル情報取得
   └─ Connect-DbaInstanceで接続（MinimumVersion 10）
   └─ Get-DbaSpConfigureでFilestreamAccessLevelを取得

5. 再起動保留判定
   └─ ConfiguredValueとRunningValueを比較
   └─ 不一致の場合は再起動保留

6. 結果出力
   └─ アクセスレベル値を人間が読める名前に変換
   └─ PSCustomObjectとして出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[アクセスレベル定義]
    B --> C[インスタンスループ]
    C --> D[コンピュータ名取得]
    D --> E{ローカルホスト?}
    E -->|Yes| F[ローカル名使用]
    E -->|No| G[Resolve-DbaNetworkName]
    F --> H[WMIネームスペース検索]
    G --> H
    H --> I[FilestreamSettings取得]
    I --> J{成功?}
    J -->|No| K[Stop-Function -Continue]
    J -->|Yes| L[Connect-DbaInstance]
    K --> C2{次のインスタンス?}
    L --> M{接続成功?}
    M -->|No| N[Stop-Function -Continue]
    M -->|Yes| O[Get-DbaSpConfigure]
    N --> C2
    O --> P[再起動保留判定]
    P --> Q[PSCustomObject出力]
    Q --> C2
    C2 -->|Yes| C
    C2 -->|No| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | サービスレベルアクセス値 | 0=Disabled、1=T-SQL、2=T-SQL+IO、3=T-SQL+IO+Remote | サービス情報表示時 |
| BR-002 | インスタンスレベルアクセス値 | 0=Disabled、1=T-SQL、2=Full | インスタンス情報表示時 |
| BR-003 | 再起動保留判定 | ConfiguredValue != RunningValueの場合は保留 | 両レベル取得後 |
| BR-004 | 最小バージョン要件 | SQL Server 2008（バージョン10）以上が必要 | インスタンス接続時 |

### 計算ロジック

アクセスレベルのマッピング：
```powershell
$idServiceFS = @{
    0 = 'Disabled'
    1 = 'FileStream enabled for T-Sql access'
    2 = 'FileStream enabled for T-Sql and IO streaming access'
    3 = 'FileStream enabled for T-Sql, IO streaming, and remote clients'
}

$idInstanceFS = @{
    0 = 'Disabled'
    1 = 'T-SQL access enabled'
    2 = 'Full access enabled'
}
```

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|------|---------|------|
| サービス構成取得 | WMI FilestreamSettings | WMIクエリ | サービスレベルFileStream設定 |
| インスタンス構成取得 | sp_configure | SELECT | インスタンスレベルFileStream設定 |

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

#### sp_configure（Get-DbaSpConfigure経由）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | ConfiguredValue, RunningValue | Name = 'filestream access level' | Get-DbaSpConfigure内部で実行 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | WMIError | サービスレベル情報取得失敗 | Stop-Function -Continueで次のインスタンスへ |
| - | ConnectionError | SQL Server接続失敗 | Stop-Function -Continueで次のインスタンスへ |
| - | ConfigError | sp_configure取得失敗 | Stop-Function -Continueで次のインスタンスへ |

### リトライ仕様

リトライ機能なし。エラー時は当該インスタンスをスキップして次を処理。

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

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- WMI接続とSQL Server接続の両方が必要なため、ネットワーク遅延の影響を受ける
- 多数のインスタンスを処理する場合、順次処理のため時間がかかる

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

- WMI接続にはWindows管理者アクセスが必要
- SQL Server接続にはVIEW SERVER STATE権限が必要
- Credentialパラメータ（WMI用）とSqlCredentialパラメータ（SQL用）を別々に指定可能
- 出力オブジェクトに資格情報が含まれるため、取り扱いに注意

## 備考

- SQL Server 2008以降でのみ動作（MinimumVersion 10）
- サービスレベルとインスタンスレベルの両方の設定が必要でFileStreamが機能する
- 再起動保留状態の場合、SQL Serverサービスの再起動が必要
- WMIネームスペースはComputerManagement*の最新バージョンを自動検出

---

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

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

### 推奨読解順序

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

アクセスレベル値のマッピングを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaFilestream.ps1 | `public/Get-DbaFilestream.ps1` | 74-86行目のbeginブロック（アクセスレベル定義） |

**読解のコツ**: サービスレベルは0-3の4段階、インスタンスレベルは0-2の3段階。この差異がFileStream設定の複雑さの原因。

#### Step 2: サービスレベル情報取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaFilestream.ps1 | `public/Get-DbaFilestream.ps1` | 88-119行目のサービスレベル情報取得 |

**主要処理フロー**:
1. **94-98行目**: ローカル/リモートに応じたコンピュータ名解決
2. **101-106行目**: WMIネームスペース検索（ComputerManagement*）
3. **113行目**: FilestreamSettings取得

#### Step 3: インスタンスレベル情報取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaFilestream.ps1 | `public/Get-DbaFilestream.ps1` | 121-132行目のインスタンスレベル情報取得 |

**主要処理フロー**:
- **122-123行目**: Connect-DbaInstance（MinimumVersion 10）
- **128-129行目**: Get-DbaSpConfigure呼び出し

#### Step 4: 結果出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaFilestream.ps1 | `public/Get-DbaFilestream.ps1` | 134-157行目の結果処理と出力 |

**主要処理フロー**:
- **134行目**: 再起動保留判定
- **142行目**: RunningValue取得
- **145-156行目**: PSCustomObject作成と出力

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

```
Get-DbaFilestream
    │
    ├─ Resolve-DbaNetworkName
    │      └─ コンピュータ名解決
    │
    ├─ Get-DbaCmObject（2回）
    │      ├─ WMIネームスペース検索
    │      └─ FilestreamSettings取得
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続（MinimumVersion 10）
    │
    ├─ Get-DbaSpConfigure
    │      └─ FilestreamAccessLevel取得
    │
    └─ Select-DefaultView
           └─ 出力プロパティフィルタリング
```

### データフロー図

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

SqlInstance           ───▶ サービスレベル取得
                           (WMI FilestreamSettings)
                                 │
                                 ▼
                           インスタンスレベル取得
                           (sp_configure)
                                 │
                                 ▼
                           再起動保留判定             ───▶ PSCustomObject
                           アクセスレベル変換              - InstanceAccess
                                                          - ServiceAccess
                                                          - ServiceShareName
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaFilestream.ps1 | `public/Get-DbaFilestream.ps1` | ソース | メイン処理ロジック |
| Set-DbaFilestream.ps1 | `public/Set-DbaFilestream.ps1` | ソース | 関連コマンド（FileStream設定変更） |
| Get-DbaSpConfigure.ps1 | `public/Get-DbaSpConfigure.ps1` | ソース | 内部依存（sp_configure取得） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | 内部依存（インスタンス接続） |
| Resolve-DbaNetworkName.ps1 | `functions/Resolve-DbaNetworkName.ps1` | ソース | 内部依存（ネットワーク名解決） |
| Get-DbaCmObject.ps1 | `functions/Get-DbaCmObject.ps1` | ソース | 内部依存（WMI/CIMクエリ） |
