# 機能設計書 195-New-DbaSqlParameter

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`New-DbaSqlParameter`機能の設計仕様を記載する。この機能は、パラメータ化クエリやストアドプロシージャで使用するSqlParameterオブジェクトを作成する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverに対してパラメータ化クエリを実行する際、SQLインジェクションを防止し、型安全なパラメータ渡しを行うためにSqlParameterオブジェクトが必要となる。本機能は、Invoke-DbaQueryや他のデータアクセス操作で使用可能な、適切に構成されたSqlParameterオブジェクトを生成する。出力パラメータ、テーブル値パラメータ、Always Encrypted対応など、高度なパラメータ機能もサポートする。

**機能の利用シーン**：
- ストアドプロシージャの出力パラメータ取得
- パラメータ化クエリの安全な実行
- テーブル値パラメータを使用したバルク操作
- Always Encrypted列へのデータ挿入

**主要な処理内容**：
1. Microsoft.Data.SqlClient.SqlParameterオブジェクトをNew-Objectで作成
2. Test-Boundで各パラメータの指定を確認
3. 指定されたプロパティを順次設定
4. 構成済みSqlParameterオブジェクトを返却

**関連システム・外部連携**：Microsoft.Data.SqlClient、Invoke-DbaQuery、SQL Server。

**権限による制御**：オブジェクト生成のみのため、特別な権限は不要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 258 | SQLパラメーター | 主機能 | SQLパラメーターの作成 |

## 機能種別

オブジェクト生成 / ユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| CompareInfo | string | No | 文字列比較ルール | ValidateSet |
| DbType | string | No | .NETデータ型 | ValidateSet |
| Direction | string | No | パラメータ方向（Input/Output等） | ValidateSet |
| ForceColumnEncryption | switch | No | Always Encrypted強制 | - |
| IsNullable | switch | No | Null許容 | - |
| LocaleId | int | No | ロケールID | - |
| Offset | string | No | データ開始位置 | - |
| ParameterName | string | No | パラメータ名（@付き） | Alias: Name |
| Precision | string | No | 数値の精度 | - |
| Scale | string | No | 小数点以下桁数 | - |
| Size | int | No | 最大長（-1でMAX） | - |
| SourceColumn | string | No | DataTable列名マッピング | - |
| SourceColumnNullMapping | switch | No | ソース列Null許容フラグ | - |
| SourceVersion | string | No | DataRowのバージョン | ValidateSet |
| SqlDbType | string | No | SQL Server固有データ型 | ValidateSet |
| SqlValue | object | No | SQL Server固有型での値 | - |
| TypeName | string | No | テーブル型名 | - |
| UdtTypeName | string | No | ユーザー定義型名 | - |
| Value | object | No | パラメータ値 | - |
| EnableException | switch | No | 例外をスローするかどうか | - |

### ValidateSetの詳細

**CompareInfo**: None, IgnoreCase, IgnoreNonSpace, IgnoreKanaType, IgnoreWidth, BinarySort2, BinarySort

**DbType**: AnsiString, Binary, Byte, Boolean, Currency, Date, DateTime, Decimal, Double, Guid, Int16, Int32, Int64, Object, SByte, Single, String, Time, UInt16, UInt32, UInt64, VarNumeric, AnsiStringFixedLength, StringFixedLength, Xml, DateTime2, DateTimeOffset

**Direction**: Input, Output, InputOutput, ReturnValue

**SourceVersion**: Original, Current, Proposed, Default

**SqlDbType**: BigInt, Binary, Bit, Char, DateTime, Decimal, Float, Image, Int, Money, NChar, NText, NVarChar, Real, UniqueIdentifier, SmallDateTime, SmallInt, SmallMoney, Text, Timestamp, TinyInt, VarBinary, VarChar, Variant, Xml, Udt, Structured, Date, Time, DateTime2, DateTimeOffset

### 入力データソース

パラメータ入力のみ。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlParameter | Microsoft.Data.SqlClient.SqlParameter | 構成済みSQLパラメータオブジェクト |

### 出力先

PowerShellパイプラインへの出力。

## 処理フロー

### 処理シーケンス

```
1. SqlParameterオブジェクト作成
   └─ New-Object Microsoft.Data.SqlClient.SqlParameter
2. 各プロパティの設定（Test-Boundで指定確認）
   ├─ CompareInfo設定
   ├─ DbType設定
   ├─ Direction設定
   ├─ ForceColumnEncryption設定
   ├─ IsNullable設定
   ├─ LocaleId設定
   ├─ Offset設定
   ├─ ParameterName設定
   ├─ Precision設定
   ├─ Scale設定
   ├─ Size設定
   ├─ SourceColumn設定
   ├─ SourceColumnNullMapping設定
   ├─ SourceVersion設定
   ├─ SqlDbType設定
   ├─ SqlValue設定
   ├─ TypeName設定
   ├─ UdtTypeName設定
   └─ Value設定
3. SqlParameter返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[New-Object SqlParameter]
    B --> C{CompareInfo指定?}
    C -->|Yes| D[CompareInfo設定]
    C -->|No| E{DbType指定?}
    D --> E
    E -->|Yes| F[DbType設定]
    E -->|No| G{Direction指定?}
    F --> G
    G -->|Yes| H[Direction設定]
    G -->|No| I[...他プロパティチェック継続]
    H --> I
    I --> J{Value指定?}
    J -->|Yes| K[Value設定]
    J -->|No| L[SqlParameter返却]
    K --> L
    L --> M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 条件付き設定 | パラメータ指定時のみプロパティを設定 | 常時 |
| BR-002 | エラー伝播 | try-catch内で処理、失敗時はStop-Function | エラー発生時 |

### 計算ロジック

特に計算処理はない。

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

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

データベース操作はない。オブジェクト生成のみ。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | プロパティ設定時のエラー | パラメータ値を確認 |

### リトライ仕様

本機能にリトライ機能はない。

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

データベース操作がないため、トランザクションは関与しない。

## パフォーマンス要件

特になし。単一オブジェクト生成の軽量な操作。

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

- パラメータ化クエリによりSQLインジェクションを防止
- Always Encrypted対応でセンシティブデータの保護が可能
- ForceColumnEncryptionでメタデータ攻撃からの保護

## 備考

- SqlDbTypeを優先使用することで、SQL Server固有の型マッピングが正確に行われる
- Size=-1でvarchar(max)/nvarchar(max)/varbinary(max)に対応
- 出力パラメータ使用時は、Invoke-DbaQuery実行後にValueプロパティから値を取得

---

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

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

### 推奨読解順序

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

Microsoft.Data.SqlClient.SqlParameterクラスの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SqlParameter Class | Microsoft.Data.SqlClient | プロパティ群の構造と用途 |

**読解のコツ**: SqlParameterは.NETのデータアクセス層で使用される標準的なパラメータオブジェクト。Direction、SqlDbType、Valueが最も頻繁に使用される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaSqlParameter.ps1 | `public/New-DbaSqlParameter.ps1` | 関数定義とパラメータ構造 |

**主要処理フロー**:
1. **141-169行目**: param()ブロックでパラメータ定義
2. **171行目**: SqlParameterオブジェクト作成
3. **173-250行目**: Test-Boundで各プロパティ設定
4. **250行目**: SqlParameter返却

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaSqlParameter.ps1 | `public/New-DbaSqlParameter.ps1` | Test-Boundによる条件付き設定 |

**主要処理フロー**:
- **175-177行目**: CompareInfo設定パターン
- **183-185行目**: Direction設定パターン
- **231-233行目**: SqlDbType設定パターン
- **247-249行目**: Value設定パターン

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

```
New-DbaSqlParameter
    │
    ├─ New-Object Microsoft.Data.SqlClient.SqlParameter
    │      └─ SqlParameterオブジェクト作成
    │
    ├─ Test-Bound (内部関数)
    │      └─ パラメータ指定チェック（各プロパティで繰り返し）
    │
    └─ Stop-Function
           └─ エラー時の処理終了
```

### データフロー図

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

ParameterName ─────────────┐
SqlDbType ─────────────────┤
Direction ─────────────────┤
Size ──────────────────────┼──▶ New-DbaSqlParameter ──────────▶ SqlParameter Object
Value ─────────────────────┤           │
その他プロパティ ──────────┘           ├─ Test-Boundでチェック
                                       └─ プロパティ設定
                                              │
                                              ▼
                                       Invoke-DbaQueryで使用可能
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaSqlParameter.ps1 | `public/New-DbaSqlParameter.ps1` | ソース | メイン関数定義 |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | SqlParameter使用先 |
| Test-Bound.ps1 | `private/functions/Test-Bound.ps1` | ソース | パラメータ指定チェック |
