# 画面設計書 100-sp_configure設定

## 概要

本ドキュメントはdbatools PowerShellモジュールにおけるsp_configure設定機能（Get-DbaSpConfigure、Set-DbaSpConfigure、Copy-DbaSpConfigure、Export-DbaSpConfigure、Import-DbaSpConfigure）の画面設計書です。

### 本画面の処理概要

**業務上の目的・背景**：
SQL Serverのsp_configure設定は、インスタンスレベルの重要な構成パラメータを制御します。メモリ設定、並列処理、セキュリティオプションなどの設定を適切に管理することは、パフォーマンスとセキュリティの両面で重要です。本機能群は、sp_configure設定の取得、変更、コピー、エクスポート、インポートを提供し、構成監査、コンプライアンスチェック、複数環境間での設定一貫性確保を効率的に行えます。デフォルト値との比較機能により、カスタマイズされた設定を素早く特定できます。

**画面へのアクセス方法**：
PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Get-DbaSpConfigure -SqlInstance <インスタンス名>`
- `Set-DbaSpConfigure -SqlInstance <インスタンス名> -Name <設定名> -Value <値>`
- `Copy-DbaSpConfigure -Source <ソース> -Destination <宛先>`
- `Export-DbaSpConfigure -SqlInstance <インスタンス名> -FilePath <パス>`
- `Import-DbaSpConfigure -SqlInstance <インスタンス名> -FilePath <パス>`

**主要な操作・処理内容**：
1. **設定取得**：すべてのsp_configure設定とデフォルト値比較を取得
2. **設定変更**：特定の設定値を変更（範囲検証付き）
3. **設定コピー**：ソースインスタンスから宛先インスタンスへ設定をコピー
4. **設定エクスポート**：設定をファイル（SQL/CSV）に保存
5. **設定インポート**：ファイルから設定をインポート

**画面遷移**：
Get-DbaSpConfigureで取得した設定オブジェクトをSet-DbaSpConfigureにパイプラインで渡すことで、複数設定の一括変更が可能。

**権限による表示制御**：
- 設定取得にはSQL Serverインスタンスへの接続権限が必要
- 設定変更にはALTER SETTINGS権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 57 | Get-DbaSpConfigure | 主機能 | sp_configure設定の取得 |
| 59 | Set-DbaSpConfigure | 主機能 | sp_configure設定の変更 |
| 55 | Copy-DbaSpConfigure | 補助機能 | sp_configure設定のコピー |
| 56 | Export-DbaSpConfigure | 補助機能 | sp_configure設定のエクスポート |
| 58 | Import-DbaSpConfigure | 補助機能 | sp_configure設定のインポート |

## 画面種別

CLI（コマンドラインインターフェース）/ 構成管理

## URL/ルーティング

PowerShellコマンド:
- `Get-DbaSpConfigure`
- `Set-DbaSpConfigure`
- `Copy-DbaSpConfigure`
- `Export-DbaSpConfigure`
- `Import-DbaSpConfigure`

## 入出力項目

### Get-DbaSpConfigure パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | はい | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | SQL Server接続用の資格情報 |
| Name | string[] | いいえ | 取得する設定名（表示名またはSMOプロパティ名） |
| ExcludeName | string[] | いいえ | 除外する設定名 |
| EnableException | switch | いいえ | 例外を有効化 |

### Set-DbaSpConfigure パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | いいえ | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | SQL Server接続用の資格情報 |
| Name | string[] | いいえ | 変更する設定名 |
| Value | int | いいえ | 新しい設定値 |
| InputObject | object[] | いいえ | Get-DbaSpConfigureからの入力オブジェクト |
| WhatIf | switch | いいえ | 実行内容のプレビュー |
| Confirm | switch | いいえ | 確認プロンプト |
| EnableException | switch | いいえ | 例外を有効化 |

## 表示項目

### Get-DbaSpConfigure 出力

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | SMOプロパティ名（例：MaxServerMemory） |
| DisplayName | string | sp_configure表示名（例：max server memory (MB)） |
| Description | string | 設定の説明 |
| IsAdvanced | bool | 詳細オプションかどうか |
| IsDynamic | bool | 動的設定か（再起動不要）どうか |
| MinValue | int | 最小許容値 |
| MaxValue | int | 最大許容値 |
| ConfiguredValue | int | 現在の構成値（再起動後有効になる場合あり） |
| RunningValue | int | 現在の実行値 |
| DefaultValue | int | SQL Serverデフォルト値 |
| IsRunningDefaultValue | bool | 実行値がデフォルト値と一致するか |

### Set-DbaSpConfigure 出力

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| ConfigName | string | 変更した設定名 |
| PreviousValue | int | 変更前の値 |
| NewValue | int | 変更後の値 |

### 主要なsp_configure設定例

| 設定名（DisplayName） | SMOプロパティ名 | 説明 |
|----------------------|----------------|------|
| max server memory (MB) | MaxServerMemory | SQL Serverが使用できる最大メモリ |
| min server memory (MB) | MinServerMemory | SQL Serverが確保する最小メモリ |
| cost threshold for parallelism | CostThresholdForParallelism | 並列処理のコストしきい値 |
| max degree of parallelism | MaxDegreeOfParallelism | 最大並列度 |
| xp_cmdshell | XPCmdShellEnabled | xp_cmdshellの有効/無効 |
| clr enabled | IsSqlClrEnabled | CLR統合の有効/無効 |
| show advanced options | ShowAdvancedOptions | 詳細オプションの表示 |
| remote admin connections | RemoteDacConnectionsEnabled | リモートDAC接続の有効/無効 |

## イベント仕様

### 1-設定取得処理（Get-DbaSpConfigure）

1. Connect-DbaInstanceでSQL Server接続
2. $server.Configuration.Propertiesで全設定を取得
3. NameパラメータとExcludeNameパラメータでフィルタリング
4. Get-SqlDefaultSpConfigureでバージョン別デフォルト値を取得
5. 各設定について現在値とデフォルト値を比較
6. 結果オブジェクトを出力

### 2-設定変更処理（Set-DbaSpConfigure）

1. SqlInstance指定時はGet-DbaSpConfigureで設定オブジェクトを取得
2. 現在値と新しい値が同じ場合はスキップ
3. 値が有効範囲（MinValue〜MaxValue）外の場合はエラー
4. $configobject.Property.ConfigValue = $valueで値を設定
5. $server.Configuration.Alter()で変更を適用
6. IsDynamic = falseの場合は再起動が必要な旨を警告

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 設定取得 | sys.configurations | SELECT | 構成値の読み取り |
| 設定変更 | sys.configurations | UPDATE | 構成値の変更 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 |
|-------------|------|---------------|
| MSG001 | エラー | Failure（接続エラー時） |
| MSG002 | エラー | Unable to gather configuration properties {instance} |
| MSG003 | エラー | Value to set is the same as the existing value. No work being performed. |
| MSG004 | エラー | Value out of range for {configuration} ({minValue} <-> {maxValue}) |
| MSG005 | 情報 | Adjusting server configuration {configuration} from {currentConfigValue} to {value}. |
| MSG006 | 警告 | Configuration setting {configuration} has been set, but restart of SQL Server is required |
| MSG007 | エラー | Unable to change config setting |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Functionでエラー出力し、処理を継続 |
| 構成プロパティ取得失敗 | Stop-Functionでエラー出力し、処理を継続 |
| 同じ値への変更 | Stop-Functionで警告し、処理を継続 |
| 範囲外の値 | Stop-Functionでエラー出力し、処理を継続 |
| 設定変更失敗 | Stop-Functionでエラー出力し、処理を継続 |

## 備考

- Get-DbaSpConfigureはSMOのConfiguration.Propertiesを使用
- 表示名（DisplayName）とSMOプロパティ名（Name）の両方でフィルタリング可能
- 動的設定（IsDynamic = true）は即座に反映、静的設定はSQL Server再起動が必要
- Get-SqlDefaultSpConfigureでバージョン別のデフォルト値を取得
- Set-DbaSpConfigureは最小値・最大値の範囲チェックを実施

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造と、表示名とSMOプロパティ名のマッピングを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaSpConfigure.ps1 | `public/Get-DbaSpConfigure.ps1` | 50-76行目の.OUTPUTSセクション |
| 1-2 | Get-DbaSpConfigure.ps1 | `public/Get-DbaSpConfigure.ps1` | 115-217行目の$smoNameマッピングテーブル |

**読解のコツ**: $smoNameハッシュテーブルでsp_configure表示名とSMOプロパティ名の対応を理解する。

#### Step 2: 設定取得ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaSpConfigure.ps1 | `public/Get-DbaSpConfigure.ps1` | 105-113行目のparamブロック |
| 2-2 | Get-DbaSpConfigure.ps1 | `public/Get-DbaSpConfigure.ps1` | 219-278行目のprocessブロック |

**主要処理フロー**:
- **222行目**: Connect-DbaInstanceでSQL Server接続
- **229行目**: $server.Configuration.Propertiesで全設定取得
- **234-240行目**: Name/ExcludeNameでフィルタリング
- **243行目**: Get-SqlDefaultSpConfigureでデフォルト値取得
- **249-250行目**: 現在値とデフォルト値の比較
- **256-276行目**: 出力オブジェクト生成

#### Step 3: 設定変更ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaSpConfigure.ps1 | `public/Set-DbaSpConfigure.ps1` | 92-102行目のparamブロック |
| 3-2 | Set-DbaSpConfigure.ps1 | `public/Set-DbaSpConfigure.ps1` | 103-150行目のprocessブロック |

**主要処理フロー**:
- **104-106行目**: SqlInstance指定時はGet-DbaSpConfigureで取得
- **118-120行目**: 現在値と同じ場合はスキップ
- **123-125行目**: 範囲チェック
- **129-130行目**: 値を設定してAlter()で適用
- **142-144行目**: 静的設定の場合は再起動警告

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

```
Get-DbaSpConfigure
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ $server.Configuration.Properties
    │      └─ 全sp_configure設定取得
    │
    ├─ フィルタリング（Name/ExcludeName）
    │      └─ 表示名またはSMOプロパティ名でマッチ
    │
    ├─ Get-SqlDefaultSpConfigure
    │      └─ バージョン別デフォルト値取得
    │
    └─ 比較・出力
           └─ IsRunningDefaultValue計算

Set-DbaSpConfigure
    │
    ├─ Get-DbaSpConfigure（SqlInstance指定時）
    │      └─ 設定オブジェクト取得
    │
    ├─ 検証
    │      ├─ 現在値と同じ？
    │      └─ 範囲チェック（MinValue〜MaxValue）
    │
    ├─ $configobject.Property.ConfigValue = $value
    │      └─ 値を設定
    │
    ├─ $server.Configuration.Alter()
    │      └─ 変更を適用
    │
    └─ IsDynamic判定
           └─ 静的設定なら再起動警告
```

### データフロー図

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

SqlInstance ─────────────▶ Connect-DbaInstance
                                  │
                          ┌───────▼───────┐
                          │ $server.      │
                          │ Configuration │
                          │ .Properties   │
                          └───────────────┘
                                  │
                          ┌───────▼───────┐
                          │ フィルタリング │
                          │ (Name/        │
                          │  ExcludeName) │
                          └───────────────┘
                                  │
                          ┌───────▼───────┐
                          │ Get-SqlDefault│
                          │ SpConfigure   │
                          │ (デフォルト値)│
                          └───────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────┐
        ▼                         ▼                         ▼
  ConfiguredValue           RunningValue            DefaultValue
        │                         │                         │
        └─────────────────────────┼─────────────────────────┘
                                  ▼
                          ┌───────────────┐
                          │ 比較          │
                          │ (IsRunning    │
                          │ DefaultValue) │
                          └───────────────┘
                                  │
                                  ▼
                          [PSCustomObject]

--- Set処理 ---

InputObject ─────────────▶ 検証
  (or SqlInstance)               │
                          ┌──────▼──────┐
                          │ 同じ値？    │──▶ スキップ
                          └─────────────┘
                                  │
                          ┌──────▼──────┐
                          │ 範囲内？    │──▶ エラー
                          └─────────────┘
                                  │
                          ┌──────▼──────┐
                          │ ConfigValue │
                          │ = $value    │
                          └─────────────┘
                                  │
                          ┌──────▼──────┐
                          │ Alter()     │
                          └─────────────┘
                                  │
                          ┌──────▼──────┐
                          │ IsDynamic?  │──▶ 警告
                          └─────────────┘
                                  │
                                  ▼
                          [PSCustomObject]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaSpConfigure.ps1 | `public/Get-DbaSpConfigure.ps1` | ソース | sp_configure設定取得 |
| Set-DbaSpConfigure.ps1 | `public/Set-DbaSpConfigure.ps1` | ソース | sp_configure設定変更 |
| Copy-DbaSpConfigure.ps1 | `public/Copy-DbaSpConfigure.ps1` | ソース | sp_configure設定コピー |
| Export-DbaSpConfigure.ps1 | `public/Export-DbaSpConfigure.ps1` | ソース | sp_configure設定エクスポート |
| Import-DbaSpConfigure.ps1 | `public/Import-DbaSpConfigure.ps1` | ソース | sp_configure設定インポート |
| Get-SqlDefaultSpConfigure.ps1 | `internal/functions/Get-SqlDefaultSpConfigure.ps1` | ソース | バージョン別デフォルト値取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立 |
