# 画面設計書 258-SQLパラメーター

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `New-DbaSqlParameter` コマンドに関する画面設計書です。このコマンドは、パラメーター化クエリやストアドプロシージャで使用するSqlParameterオブジェクトを作成します。

### 本画面の処理概要

**業務上の目的・背景**：SQLインジェクションを防止し、安全にSQLクエリを実行するためには、パラメーター化クエリの使用が必須です。このコマンドは、`Invoke-DbaQuery` などのコマンドで使用するSqlParameterオブジェクトを簡単に作成できます。データ型、方向（入力/出力）、サイズ、値などの各種プロパティを設定でき、出力パラメーターやテーブル値パラメーター、Always Encryptedにも対応しています。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから `New-DbaSqlParameter` コマンドを実行します。

**主要な操作・処理内容**：
1. Microsoft.Data.SqlClient.SqlParameterオブジェクトを新規作成
2. 指定されたパラメーターに基づいてプロパティを設定
3. 設定済みのSqlParameterオブジェクトを返す

**画面遷移**：CLIコマンドのため画面遷移はありません。出力オブジェクトは `Invoke-DbaQuery` の `-SqlParameter` パラメーターに渡します。

**権限による表示制御**：特に権限は不要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 195 | New-DbaSqlParameter | 主機能 | SQLパラメーターの作成 |
| 180 | Invoke-DbaQuery | 遷移先機能 | パラメーター化クエリの実行 |

## 画面種別

ユーティリティ・オブジェクト生成（CLIコマンド）

## URL/ルーティング

該当なし（PowerShell CLIコマンド）

## 入出力項目

### 入力パラメーター

| パラメーター名 | 型 | 必須 | 説明 |
|---------------|---|-----|------|
| CompareInfo | string | No | 文字列比較ルール（None, IgnoreCase, IgnoreNonSpace等） |
| DbType | string | No | .NETデータ型（AnsiString, Binary, Int32等） |
| Direction | string | No | パラメーター方向（Input, Output, InputOutput, ReturnValue） |
| ForceColumnEncryption | switch | No | Always Encrypted強制 |
| IsNullable | switch | No | NULL許容フラグ |
| LocaleId | int | No | ロケールID |
| Offset | string | No | 値内のオフセット位置 |
| ParameterName | string | No | パラメーター名（@プレフィックス含む） |
| Precision | string | No | 数値精度 |
| Scale | string | No | 小数点以下桁数 |
| Size | int | No | 最大長（-1でMAX） |
| SourceColumn | string | No | DataTableでのソースカラム名 |
| SourceColumnNullMapping | switch | No | ソースカラムNULLマッピング |
| SourceVersion | string | No | DataRowバージョン（Original, Current, Proposed, Default） |
| SqlDbType | string | No | SQL Serverデータ型（NVarChar, Int, DateTime等） |
| SqlValue | object | No | SQL Server固有型での値 |
| TypeName | string | No | ユーザー定義テーブル型名 |
| UdtTypeName | string | No | ユーザー定義型名 |
| Value | object | No | パラメーター値 |
| EnableException | switch | No | 例外を直接スローするかどうか |

### 出力項目

Microsoft.Data.SqlClient.SqlParameter オブジェクト

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ParameterName | string | パラメーター名 |
| SqlDbType | SqlDbType | SQL Serverデータ型 |
| Direction | ParameterDirection | パラメーター方向 |
| Size | int | 最大長 |
| Value | object | パラメーター値 |
| （その他） | 各種 | SqlParameterクラスの全プロパティ |

## 表示項目

CLIコマンドのため、表示項目は返されるSqlParameterオブジェクトのプロパティに依存します。

## イベント仕様

### 1-コマンド実行

コマンド実行時に以下の処理が行われます：

1. `New-Object Microsoft.Data.SqlClient.SqlParameter` でオブジェクト作成
2. 各バインドされたパラメーターについて `Test-Bound` で確認
3. 対応するプロパティに値を設定
4. SqlParameterオブジェクトを返す

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

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

このコマンドはデータベースに接続せず、オブジェクト生成のみを行います。

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|---------------|
| エラー | 設定失敗時 | "Failure" |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| プロパティ設定エラー | Stop-Functionでメッセージ表示 |

## 備考

- Microsoft.Data.SqlClient.SqlParameterを使用（最新のSQL Clientライブラリ）
- 出力パラメーターを使用する場合は `Direction` を "Output" に設定
- テーブル値パラメーターを使用する場合は `SqlDbType` を "Structured"、`TypeName` にテーブル型名を設定
- `-Size -1` でvarchar(max)やnvarchar(max)に対応
- Invoke-DbaQueryとの連携例が.EXAMPLEセクションに記載

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaSqlParameter.ps1 | `public/New-DbaSqlParameter.ps1` | パラメーター定義（行142-168） |
| 1-2 | New-DbaSqlParameter.ps1 | `public/New-DbaSqlParameter.ps1` | ValidateSet属性の値一覧 |

**読解のコツ**: SqlParameterクラスの各プロパティがPowerShellパラメーターとして公開されています。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaSqlParameter.ps1 | `public/New-DbaSqlParameter.ps1` | 関数定義全体（行1-255） |

**主要処理フロー**:
1. **行171**: SqlParameterオブジェクト作成
2. **行173-249**: Test-Boundで各パラメーターをチェックし設定
3. **行250**: オブジェクトを返す

#### Step 3: プロパティ設定パターンを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaSqlParameter.ps1 | `public/New-DbaSqlParameter.ps1` | Test-Boundパターン（行175-249） |

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

```
New-DbaSqlParameter
    │
    ├─ New-Object Microsoft.Data.SqlClient.SqlParameter
    │
    ├─ Test-Bound -ParameterName CompareInfo
    │      └─ $param.CompareInfo = $CompareInfo
    │
    ├─ Test-Bound -ParameterName DbType
    │      └─ $param.DbType = $DbType
    │
    ├─ Test-Bound -ParameterName Direction
    │      └─ $param.Direction = $Direction
    │
    ├─ ... (他のパラメーター)
    │
    └─ $param (オブジェクト返却)
```

### データフロー図

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

ParameterName ───┐
                 │
SqlDbType ───────┼───▶ New SqlParameter
                 │          │
Direction ───────┤          ▼
                 │    プロパティ設定
Size ────────────┤          │
                 │          ▼
Value ───────────┘    SqlParameter ───▶ Invoke-DbaQuery
                                              │
                                              ▼
                                        パラメーター化クエリ実行
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaSqlParameter.ps1 | `public/New-DbaSqlParameter.ps1` | ソース | メイン関数定義 |
| Test-Bound.ps1 | `internal/functions/Test-Bound.ps1` | ソース | パラメーターバインド確認 |
| Stop-Function.ps1 | `internal/functions/flowcontrol/Stop-Function.ps1` | ソース | エラーハンドリング |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | パラメーター使用先 |
