# 画面設計書 219-DataTable変換

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける「DataTable変換」機能（ConvertTo-DbaDataTable）の画面設計書です。PowerShellオブジェクトを.NET DataTableオブジェクトに変換し、SQL Serverへのバルク操作に使用できる形式に変換する機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：SQL Server管理者やDBAは、PowerShellの出力結果（Get-DbaDatabase、Get-DbaBackupHistoryなど）をSQL Serverテーブルに保存して、カスタムレポートや監視データとして活用する必要があります。ConvertTo-DbaDataTableは、PowerShellオブジェクトを適切なデータ型を持つDataTableに変換し、Write-DbaDataTableでのバルクインサートを可能にします。

**画面へのアクセス方法**：PowerShellコンソールからPowerShellオブジェクトを `ConvertTo-DbaDataTable` にパイプで渡して実行します。

**主要な操作・処理内容**：
1. PowerShellオブジェクトを受け取る
2. オブジェクトのプロパティからDataTableカラムを作成
3. 特殊型（TimeSpan、DbaSize等）を適切な型に変換
4. 各オブジェクトをDataTable行として追加
5. DataTableを出力

**画面遷移**：CLIコマンドのため画面遷移はありません。Write-DbaDataTableと連携して使用します。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 149 | ConvertTo-DbaDataTable | 主機能 | DataTable変換 |
| 349 | Write-DbaDataTable | 連携機能 | DataTableのSQL Serverへのバルクインサート |

## 画面種別

コマンドライン（CLI）実行画面

## URL/ルーティング

```powershell
# 基本使用
Get-Service | ConvertTo-DbaDataTable

# TimeSpan型の変換指定
Get-Process | ConvertTo-DbaDataTable -TimeSpanType TotalSeconds

# サイズ型の変換指定
Get-DbaDatabase -SqlInstance sql2016 | ConvertTo-DbaDataTable -SizeType String
```

## 入出力項目

### パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| InputObject | PSObject[] | Yes | - | 変換するPowerShellオブジェクト |
| TimeSpanType | string | No | TotalMilliseconds | TimeSpan変換タイプ（Ticks/TotalDays/TotalHours/TotalMinutes/TotalSeconds/TotalMilliseconds/String） |
| SizeType | string | No | Int64 | DbaSize変換タイプ（Int64/Int32/String） |
| IgnoreNull | switch | No | $false | nullオブジェクトを除外 |
| Raw | switch | No | $false | 全カラムをstringとして扱う |
| EnableException | switch | No | $false | 例外を有効化 |

## 表示項目

### 出力

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| - | System.Data.DataTable | 変換されたDataTable |

### サポートされるデータ型

| 入力型 | 変換後の型 |
|--------|-----------|
| Int32, Int64, Decimal, Double, Single等 | 元の型を保持 |
| TimeSpan, DbaTimeSpan | TimeSpanTypeに基づく（デフォルト: Int64） |
| DbaSize | SizeTypeに基づく（デフォルト: Int64） |
| DateTime | System.DateTime |
| Boolean, Guid, Char | 元の型を保持 |
| String[], Object[] | カンマ区切り文字列 |
| その他 | System.String |

## イベント仕様

### 1-コマンド実行時

1. beginブロック:
   - DataTableを新規作成
   - カラム管理用変数を初期化
2. processブロック:
   - nullオブジェクトの処理（IgnoreNullに基づく）
   - DataRow型の特別処理（Merge使用）
   - 最初のオブジェクトでカラムを作成:
     - Convert-Type関数でデータ型を判定
     - 特殊型（TimeSpan、DbaSize等）を変換
     - Add-Column関数でDataTableにカラム追加
   - 各プロパティの値をDataRowに設定:
     - 特殊型はConvert-SpecialType関数で変換
     - 配列は カンマ区切り文字列に変換
   - DataRowをDataTableに追加
3. endブロック:
   - DataTableを出力

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

このコマンドはデータベースを更新しません。DataTableオブジェクトの生成のみを行います。

## メッセージ仕様

| 種別 | メッセージ | 発生条件 |
|------|----------|---------|
| Debug | Bound parameters: {params} | 実行開始時 |
| Debug | TimeSpanType = {type} / SizeType = {type} | 実行開始時 |
| InternalComment | Finished. | 処理完了時 |
| エラー | Failed to add property {name} from {object} | プロパティ追加失敗時 |

## 例外処理

| 例外条件 | 動作 |
|---------|------|
| プロパティ追加失敗 | Stop-Functionでエラーを報告 |
| 型変換失敗 | Stringにフォールバック |

## 備考

- Write-DbaDataTableと組み合わせてSQL Serverへのバルクインサートに使用
- Rawパラメータは型検出が失敗する場合のフォールバック
- DbaSize型はByteプロパティを使用してバイト値を取得
- TimeSpan型はTotalMillisecondsがデフォルト（より正確な値）
- 配列型（String[]、Object[]）はカンマ区切り文字列に変換

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ConvertTo-DbaDataTable.ps1 | `public/ConvertTo-DbaDataTable.ps1` | 出力タイプ（行58-74） |

**読解のコツ**: 出力はSystem.Data.DataTableで、入力オブジェクトのプロパティがカラムになります。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ConvertTo-DbaDataTable.ps1 | `public/ConvertTo-DbaDataTable.ps1` | パラメータ定義（行100-120）とConvert-Type関数（行126-213） |

**主要処理フロー**:
1. **行122-323**: beginブロックでDataTable作成と内部関数定義
2. **行126-213**: Convert-Type関数でデータ型判定・変換
3. **行215-263**: Convert-SpecialType関数で特殊型変換
4. **行265-313**: Add-Column関数でカラム追加
5. **行325-433**: processブロックでオブジェクト処理
6. **行434-437**: endブロックでDataTable出力

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

```
ConvertTo-DbaDataTable
    |
    +-- beginブロック
    |      +-- New-Object System.Data.DataTable
    |      +-- Convert-Type関数定義
    |      +-- Convert-SpecialType関数定義
    |      +-- Add-Column関数定義
    |
    +-- processブロック
    |      +-- nullオブジェクト処理
    |      +-- DataRow型の特別処理（Merge）
    |      +-- 最初のオブジェクトでカラム作成
    |      |      +-- Add-Column
    |      |             +-- Convert-Type
    |      |
    |      +-- プロパティ値設定
    |      |      +-- Convert-SpecialType（特殊型）
    |      |
    |      +-- DataTable.Rows.Add()
    |
    +-- endブロック
           +-- DataTable出力
```

### データフロー図

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

InputObject ───────▶ PSObject.Properties取得 ────▶ プロパティ配列
      |
      v
プロパティ ─────────▶ Convert-Type ────────────────▶ 型情報
      |                    |
      |                    +── TimeSpan/DbaTimeSpan → Int64/String
      |                    +── DbaSize → Int64/Int32/String
      |                    +── その他 → System.String
      |
      v
                    Add-Column ───────────────────▶ DataTableカラム
      |
      v
値 ─────────────────▶ Convert-SpecialType ────────▶ 変換済み値
      |
      v
                    DataRow設定 ──────────────────▶ DataTable行
      |
      v
                    DataTable.Rows.Add() ─────────▶ DataTable出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ConvertTo-DbaDataTable.ps1 | `public/ConvertTo-DbaDataTable.ps1` | ソース | メインコマンド実装 |
| Write-DbaDataTable.ps1 | `public/Write-DbaDataTable.ps1` | 連携 | DataTableのバルクインサート |

### サポートされる型の詳細

| カテゴリ | 入力型 | 変換処理 |
|---------|--------|---------|
| 数値型 | Int32, UInt32, Int16, UInt16, Int64, UInt64, Decimal, Single, Double, Byte, SByte | そのまま保持 |
| 日時型 | DateTime | そのまま保持 |
| 論理型 | Boolean | そのまま保持 |
| 識別型 | Guid, Char | そのまま保持 |
| TimeSpan型 | System.TimeSpan, DbaTimeSpan, DbaTimeSpanPretty | TimeSpanTypeに基づいて変換（デフォルト: TotalMilliseconds → Int64） |
| サイズ型 | DbaSize | SizeTypeに基づいて変換（デフォルト: Byte → Int64） |
| 配列型 | String[], Object[] | カンマ区切り文字列に変換 |
| その他 | 上記以外 | System.Stringに変換 |
