# 画面設計書 138-Filestream

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Server FILESTREAM機能の設定管理機能の設計仕様を定義する。

### 本画面の処理概要

SQL ServerインスタンスのFILESTREAM機能の取得、有効化、無効化を行う機能群を提供する。

**業務上の目的・背景**：FILESTREAMは、SQL Server内のBLOBデータ（ドキュメント、画像、動画など）をファイルシステム上に保存しながら、データベーストランザクションの整合性を維持する機能である。大容量バイナリデータを効率的に管理し、ストリーミングアクセスを可能にする。本機能は、FILESTREAMの設定状態確認、有効化・無効化をプログラマティックに行うことで、複数インスタンスへの一括設定や構成管理自動化を実現する。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスする
- `Get-DbaFilestream` - FILESTREAM設定の取得
- `Enable-DbaFilestream` - FILESTREAMの有効化
- `Disable-DbaFilestream` - FILESTREAMの無効化

**主要な操作・処理内容**：
1. サービスレベルとインスタンスレベルの両方のFILESTREAM設定状態を確認
2. 3つのアクセスレベルから選択して有効化（T-SQLのみ、I/Oストリーミング、リモートクライアント）
3. FILESTREAM機能の無効化
4. 設定変更後のSQL Serverサービス再起動（-Forceオプション）

**画面遷移**：CLIベースのため画面遷移は存在しない。

**権限による表示制御**：Windows管理者権限およびSQL Server接続権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 640 | Get-DbaFilestream | 主機能 | Filestreamの取得 |
| 627 | Enable-DbaFilestream | 主機能 | Filestreamの有効化 |
| 626 | Disable-DbaFilestream | 主機能 | Filestreamの無効化 |
| - | Connect-DbaInstance | 補助機能 | SQL Server接続 |
| - | Get-DbaSpConfigure | 補助機能 | sp_configure設定の取得 |
| - | Set-DbaSpConfigure | 補助機能 | sp_configure設定の変更 |
| - | Restart-DbaService | 補助機能 | サービス再起動 |
| - | Get-DbaWsfcNode | 補助機能 | クラスターノード取得 |

## 画面種別

CLI（コマンドラインインターフェース）

## URL/ルーティング

該当なし（PowerShellコマンドレット）

## 入出力項目

### Get-DbaFilestream

| 項目名 | データ型 | 必須 | 説明 |
|--------|----------|------|------|
| SqlInstance | DbaInstance[] | いいえ | 対象SQLインスタンス |
| SqlCredential | PSCredential | いいえ | SQL認証用資格情報 |
| Credential | PSCredential | いいえ | Windows認証用資格情報 |
| EnableException | switch | いいえ | 例外を直接発生させるかどうか |

### Enable-DbaFilestream

| 項目名 | データ型 | 必須 | 説明 |
|--------|----------|------|------|
| SqlInstance | DbaInstance[] | はい | 対象SQLインスタンス |
| SqlCredential | PSCredential | いいえ | SQL認証用資格情報 |
| Credential | PSCredential | いいえ | Windows認証用資格情報 |
| FileStreamLevel | string/int | いいえ | アクセスレベル（TSql/1、TSqlIoStreaming/2、TSqlIoStreamingRemoteClient/3）デフォルト: 1 |
| ShareName | string | いいえ | リモートアクセス用の共有名 |
| Force | switch | いいえ | 確認なしでサービス再起動を実行 |
| EnableException | switch | いいえ | 例外を直接発生させるかどうか |
| WhatIf | switch | いいえ | 実行予定の操作を表示 |
| Confirm | switch | いいえ | 実行前に確認を求める |

### Disable-DbaFilestream

| 項目名 | データ型 | 必須 | 説明 |
|--------|----------|------|------|
| SqlInstance | DbaInstance[] | はい | 対象SQLインスタンス |
| SqlCredential | PSCredential | いいえ | SQL認証用資格情報 |
| Credential | PSCredential | いいえ | Windows認証用資格情報 |
| Force | switch | いいえ | 確認なしでサービス再起動を実行 |
| EnableException | switch | いいえ | 例外を直接発生させるかどうか |
| WhatIf | switch | いいえ | 実行予定の操作を表示 |
| Confirm | switch | いいえ | 実行前に確認を求める |

## 表示項目

### Get-DbaFilestream 出力（デフォルトビュー）

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| InstanceAccess | string | インスタンスレベルのアクセス設定（Disabled/T-SQL access enabled/Full access enabled） |
| ServiceAccess | string | サービスレベルのアクセス設定 |
| ServiceShareName | string | FILESTREAMの共有名 |

### 追加プロパティ（Select-Object * で取得可能）

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| InstanceAccessLevel | int | インスタンスレベルのアクセスコード（0-2） |
| ServiceAccessLevel | int | サービスレベルのアクセスコード（0-3） |
| Credential | PSCredential | 使用したWindows資格情報 |
| SqlCredential | PSCredential | 使用したSQL資格情報 |

## イベント仕様

### 1-Get-DbaFilestream実行

1. 各インスタンスについて処理を開始
2. localhostでない場合、Resolve-DbaNetworkNameでコンピュータ名を解決
3. Get-DbaCmObjectでWMI名前空間からFilestreamSettingsを取得（サービスレベル）
4. Connect-DbaInstanceでSQL Serverに接続（最小バージョン: SQL Server 2008）
5. Get-DbaSpConfigureでFilestreamAccessLevel設定を取得（インスタンスレベル）
6. サービスレベルとインスタンスレベルの設定を結合して出力

### 2-Enable-DbaFilestream実行

1. beginブロックでFileStreamLevelを数値に変換
2. ShareName指定時、レベル2以上が必要かチェック
3. Connect-DbaInstanceでSQL Serverに接続
4. ShouldProcess確認後、処理を実行
5. クラスター環境の場合、各ノードでSet-FileSystemSettingを実行
6. スタンドアロンの場合、対象サーバーでSet-FileSystemSettingを実行
7. Set-DbaSpConfigureでFilestreamAccessLevelを設定（レベル3の場合は2に変換）
8. Forceオプション時、Restart-DbaServiceでサービスを再起動
9. Get-DbaFilestreamで最終設定状態を返却

### 3-Disable-DbaFilestream実行

1. Connect-DbaInstanceでSQL Serverに接続
2. ShouldProcess確認後、処理を実行
3. Set-DbaSpConfigureでFilestreamAccessLevelを0に設定
4. クラスター環境の場合、各ノードでSet-FileSystemSettingを実行（レベル0）
5. スタンドアロンの場合、対象サーバーでSet-FileSystemSettingを実行（レベル0）
6. Forceオプション時、Restart-DbaServiceでサービスを再起動
7. Get-DbaFilestreamで最終設定状態を返却

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

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

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| Get-DbaFilestream | FilestreamSettings (WMI) | SELECT | サービスレベル設定取得 |
| Get-DbaFilestream | sp_configure | SELECT | インスタンスレベル設定取得 |
| Enable-DbaFilestream | sp_configure | UPDATE | FilestreamAccessLevelの設定 |
| Enable-DbaFilestream | FilestreamSettings (WMI) | UPDATE | サービスレベル設定変更 |
| Disable-DbaFilestream | sp_configure | UPDATE | FilestreamAccessLevelを0に設定 |
| Disable-DbaFilestream | FilestreamSettings (WMI) | UPDATE | サービスレベル設定を無効化 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|----------|----------|
| - | Warning | No ComputerManagement was found on {computer}. Service level information may not be collected. | WMI名前空間が見つからない |
| - | Warning | {result} | Force指定なしで設定変更時 |
| - | Error | Filestream must be at least level 2 when using ShareName | レベル2未満でShareName指定時 |
| - | Error | Failure | 接続エラー時 |
| - | Error | Issue collecting service-level information on {computer} for {instance} | サービスレベル情報取得失敗 |
| - | Error | Issue collection instance-level configuration on {instance} | インスタンスレベル情報取得失敗 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| SQL Server接続失敗 | ConnectionErrorカテゴリでStop-Functionを呼び出し、処理継続 |
| WMI名前空間が見つからない | 警告メッセージを表示、サービスレベル情報なしで継続 |
| サービスレベル情報取得失敗 | エラー記録して次のインスタンスへ継続 |
| sp_configure設定失敗 | エラー記録して処理継続 |
| 最小バージョン不足（SQL 2008未満） | 接続エラーとして処理 |

## 備考

- FILESTREAMはSQL Server 2008以降でサポート（MinimumVersion 10）
- FILESTREAMアクセスレベル：
  - **0**: 無効
  - **1 (TSql)**: T-SQLアクセスのみ
  - **2 (TSqlIoStreaming)**: T-SQLとI/Oストリーミングアクセス
  - **3 (TSqlIoStreamingRemoteClient)**: T-SQL、I/Oストリーミング、リモートクライアントアクセス
- サービスレベル（WMI）とインスタンスレベル（sp_configure）の両方を設定する必要がある
- 設定変更はSQL Serverサービスの再起動後に有効
- クラスター環境では全ノードで個別に設定が必要
- 再起動保留中の場合、ConfiguredValueとRunningValueが異なる

---

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

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

### 推奨読解順序

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

まず、コマンドが返すオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaFilestream.ps1 | `public/Get-DbaFilestream.ps1` | .OUTPUTSセクションで出力プロパティ定義（行38-55） |
| 1-2 | Get-DbaFilestream.ps1 | `public/Get-DbaFilestream.ps1` | beginブロックでのアクセスレベル定義（行74-86） |

**読解のコツ**: $idServiceFSと$idInstanceFSのハッシュテーブルで数値から説明文への変換マッピングを理解する。

#### Step 2: 2レベル構造を理解する

FILESTREAMはサービスレベルとインスタンスレベルの2層構造。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaFilestream.ps1 | `public/Get-DbaFilestream.ps1` | サービスレベル情報取得（行93-119） |
| 2-2 | Get-DbaFilestream.ps1 | `public/Get-DbaFilestream.ps1` | インスタンスレベル情報取得（行121-132） |

**主要処理フロー**:
1. **行101-106**: WMI名前空間からFilestreamSettings取得
2. **行113**: インスタンス名でフィルタリング
3. **行123**: Connect-DbaInstance（MinimumVersion 10）
4. **行128-129**: Get-DbaSpConfigureでFilestreamAccessLevel取得

#### Step 3: Enable処理フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Enable-DbaFilestream.ps1 | `public/Enable-DbaFilestream.ps1` | レベル変換とクラスター対応（行103-152） |

**主要処理フロー**:
- **行103-115**: FileStreamLevelの文字列→数値変換
- **行129-132**: ShareNameはレベル2以上必須チェック
- **行143-152**: クラスター環境対応（Get-DbaWsfcNode使用）
- **行155-157**: sp_configure設定（レベル3は2に変換）
- **行165-167**: Forceオプションでのサービス再起動

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

```
Get-DbaFilestream
    |
    +-- foreach ($instance in $SqlInstance)
            |
            +-- Resolve-DbaNetworkName (リモート時)
            |
            +-- Get-DbaCmObject (WMI)
            |       +-- FilestreamSettings取得
            |       +-- サービスレベル設定
            |
            +-- Connect-DbaInstance (MinimumVersion 10)
            |
            +-- Get-DbaSpConfigure
            |       +-- FilestreamAccessLevel
            |       +-- インスタンスレベル設定
            |
            +-- [PSCustomObject] 結果出力

Enable-DbaFilestream
    |
    +-- beginブロック: レベル変換
    |
    +-- foreach ($instance in $SqlInstance)
            |
            +-- Connect-DbaInstance
            |
            +-- ShouldProcess確認
            |
            +-- クラスター判定 (IsClustered)
            |       +-- Get-DbaWsfcNode
            |       +-- 各ノードでSet-FileSystemSetting
            |
            +-- Set-DbaSpConfigure (FilestreamAccessLevel)
            |
            +-- Restart-DbaService (Force時)
            |
            +-- Get-DbaFilestream (結果取得)

Disable-DbaFilestream
    |
    +-- foreach ($instance in $SqlInstance)
            |
            +-- Connect-DbaInstance
            |
            +-- ShouldProcess確認
            |
            +-- Set-DbaSpConfigure (FilestreamAccessLevel = 0)
            |
            +-- クラスター判定
            |       +-- 各ノードでSet-FileSystemSetting (0)
            |
            +-- Restart-DbaService (Force時)
            |
            +-- Get-DbaFilestream (結果取得)
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ────────▶ $server
    |                       |
SqlCredential ─────────────▶ |
    |                       v
Credential ────────▶ Get-DbaCmObject (WMI)
                           │
                           v
                    ┌─────────────────┐
                    │ サービスレベル   │
                    │ FilestreamSettings│
                    │ - AccessLevel    │
                    │ - ShareName      │
                    └─────────────────┘
                           +
                    ┌─────────────────┐
                    │インスタンスレベル│
                    │ sp_configure     │
                    │ FilestreamAccess │
                    │ Level            │
                    └─────────────────┘
                           │
                           v
                    ┌──────────────────────┐    ┌───────────────────┐
                    │  [PSCustomObject]    │───▶│ FILESTREAM設定情報 │
                    │  InstanceAccess      │    └───────────────────┘
                    │  ServiceAccess       │
                    │  ServiceShareName    │
                    └──────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaFilestream.ps1 | `public/Get-DbaFilestream.ps1` | ソース | FILESTREAM設定取得コマンド |
| Enable-DbaFilestream.ps1 | `public/Enable-DbaFilestream.ps1` | ソース | FILESTREAM有効化コマンド |
| Disable-DbaFilestream.ps1 | `public/Disable-DbaFilestream.ps1` | ソース | FILESTREAM無効化コマンド |
| Get-DbaSpConfigure.ps1 | `public/Get-DbaSpConfigure.ps1` | ソース | sp_configure設定取得 |
| Set-DbaSpConfigure.ps1 | `public/Set-DbaSpConfigure.ps1` | ソース | sp_configure設定変更 |
| Restart-DbaService.ps1 | `public/Restart-DbaService.ps1` | ソース | サービス再起動 |
| Get-DbaWsfcNode.ps1 | `public/Get-DbaWsfcNode.ps1` | ソース | クラスターノード取得 |
