# 画面設計書 268-ユーザー定義テーブル型

## 概要

本ドキュメントは、dbatoolsのユーザー定義テーブル型取得機能に関する画面設計書です。SQL Serverデータベースからユーザー定義テーブル型（テーブル値パラメータ用のカスタムデータ型）を取得し、スキーマ構造や依存関係を監査できるPowerShellコマンドを定義します。

### 本画面の処理概要

本機能は、SQL Serverデータベースからユーザー定義テーブル型を取得し、その構造、所有者、作成日時などの詳細情報を返すGet-DbaDbUserDefinedTableTypeコマンドを提供します。

**業務上の目的・背景**：ユーザー定義テーブル型は、ストアドプロシージャや関数でテーブル値パラメータとして使用されるスキーマバインドオブジェクトです。データベース変更前の依存関係確認、ドキュメント化、監査において、これらのオブジェクトの把握が重要です。本機能により、複数データベース・インスタンスにわたるユーザー定義テーブル型を効率的に監査できます。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスします。
```powershell
Get-DbaDbUserDefinedTableType -SqlInstance <インスタンス名>
```

**主要な操作・処理内容**：
1. 指定されたSQL Serverインスタンスへの接続
2. データベースオブジェクトの取得
3. 各データベースのUserDefinedTableTypesコレクションにアクセス
4. システムオブジェクトの除外
5. 型名フィルタリング（指定時）
6. SMO UserDefinedTableTypeオブジェクトの出力

**画面遷移**：
- `Connect-DbaInstance`で接続を確立後に実行可能
- `Get-DbaDatabase`からパイプライン入力可能
- 取得結果はSMO UserDefinedTableTypeオブジェクトとして他の処理に渡せる

**権限による表示制御**：
- データベースへの接続権限が必要
- ユーザー定義テーブル型のメタデータへの読み取りアクセス権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 157 | Get-DbaDbUserDefinedTableType | 主機能 | ユーザー定義テーブル型の取得 |

## 画面種別

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

## URL/ルーティング

PowerShellコマンド: `Get-DbaDbUserDefinedTableType`

## 入出力項目

### パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス（パイプライン入力対応） |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Database | object[] | No | 対象データベース（ワイルドカード対応） |
| ExcludeDatabase | object[] | No | 除外するデータベース |
| Type | string[] | No | 取得するユーザー定義テーブル型の名前 |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### 出力オブジェクト（Microsoft.SqlServer.Management.Smo.UserDefinedTableType）

デフォルト表示プロパティ:

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Database | string | データベース名 |
| ID | int | ユーザー定義テーブル型の一意識別子 |
| Name | string | ユーザー定義テーブル型の名前 |
| Columns | ColumnCollection | 定義された列のコレクション |
| Owner | string | 所有者（スキーマ） |
| CreateDate | datetime | 作成日時 |
| IsSystemObject | bool | システムオブジェクトかどうか（常にFalse） |
| Version | int | 内部バージョン番号 |

追加プロパティ（Select-Object * で表示）:
- DefaultSchema: テーブル型のデフォルトスキーマ
- ExtendedProperties: 拡張プロパティ
- Urn: SQL Serverインスタンス内の一意リソース名
- State: オブジェクト状態（Existing, Creating, Pending等）

## イベント仕様

### 1-Get-DbaDbUserDefinedTableType実行

1. SqlInstance指定時はGet-DbaDatabase経由でデータベースオブジェクトを取得
2. 各データベースに対して以下を実行:
   - IsAccessibleチェック（アクセス不可の場合は警告を出力してスキップ）
   - UserDefinedTableTypes.Countチェック（0の場合はメッセージを出力してスキップ）
   - Type指定時は名前でフィルタリング
   - IsSystemObject = trueのオブジェクトをスキップ
   - NotePropertyを追加してSMOオブジェクトを出力

### 2-オブジェクト拡張処理

```powershell
# NotePropertyの追加
Add-Member -Force -InputObject $tabletype -MemberType NoteProperty -Name ComputerName -value $tabletype.Parent.ComputerName
Add-Member -Force -InputObject $tabletype -MemberType NoteProperty -Name InstanceName -value $tabletype.Parent.InstanceName
Add-Member -Force -InputObject $tabletype -MemberType NoteProperty -Name SqlInstance -value $tabletype.Parent.SqlInstance
Add-Member -Force -InputObject $tabletype -MemberType NoteProperty -Name Database -value $db.Name

# デフォルト表示プロパティの設定
$defaults = ('ComputerName', 'InstanceName', 'SqlInstance', 'Database', 'ID', 'Name', 'Columns', 'Owner', 'CreateDate', 'IsSystemObject', 'Version')
Select-DefaultView -InputObject $tabletype -Property $defaults
```

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaDbUserDefinedTableType | SMO Database.UserDefinedTableTypes | 読取 | ユーザー定義テーブル型コレクションの取得 |

本コマンドはSMOオブジェクトのプロパティ読み取りのみを行い、データベースの変更は行いません。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|--------------|---------|
| MSG001 | 警告 | Database $db is not accessible. Skipping. | データベースにアクセス不可 |
| MSG002 | 情報 | No User Defined Table Types exist in the $db database on $instance | ユーザー定義テーブル型が存在しない |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| データベースアクセス不可 | 警告メッセージを出力してスキップ |
| ユーザー定義テーブル型なし | 情報メッセージを出力してスキップ |

## 備考

- システムオブジェクト（IsSystemObject = true）は自動的に除外される
- SMO UserDefinedTableTypeオブジェクトを直接返すため、すべてのSMOプロパティにアクセス可能
- Columnsプロパティでテーブル型の列定義を確認可能
- テーブル値パラメータとして使用されるストアドプロシージャの依存関係確認に有用

---

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

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

### 推奨読解順序

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

SMO UserDefinedTableTypeオブジェクトの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbUserDefinedTableType.ps1 | `public/Get-DbaDbUserDefinedTableType.ps1` | 行52-71の出力プロパティドキュメント |

**読解のコツ**: UserDefinedTableTypeオブジェクトのデフォルト表示プロパティ（ComputerName, InstanceName, SqlInstance, Database, ID, Name, Columns, Owner, CreateDate, IsSystemObject, Version）と追加プロパティを理解します。

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

processブロックでの処理フローを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbUserDefinedTableType.ps1 | `public/Get-DbaDbUserDefinedTableType.ps1` | 行100-136のprocessブロック |

**主要処理フロー**:
1. **101-103行**: SqlInstance指定時のGet-DbaDatabase呼び出し
2. **105行**: 各データベースのループ開始
3. **106-109行**: IsAccessibleチェック
4. **110-113行**: UserDefinedTableTypes.Countチェック
5. **115-119行**: Type指定時のフィルタリング
6. **121-124行**: IsSystemObjectチェック
7. **126-129行**: NotePropertyの追加
8. **131-133行**: デフォルト表示プロパティの設定と出力

#### Step 3: フィルタリングロジックを理解する

Typeパラメータによるフィルタリングを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbUserDefinedTableType.ps1 | `public/Get-DbaDbUserDefinedTableType.ps1` | 行115-119のTypeフィルタリング |

**フィルタリングロジック**:
```powershell
if ($Type) {
    $userDefinedTableTypes = $db.UserDefinedTableTypes | Where-Object Name -in $Type
} else {
    $userDefinedTableTypes = $db.UserDefinedTableTypes
}
```

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

```
Get-DbaDbUserDefinedTableType
    |
    +-- process block
            |
            +-- Test-Bound ('SqlInstance')
            |       |
            |       +-- 指定時: Get-DbaDatabase呼び出し
            |               |
            |               +-- $InputObject = データベースオブジェクト配列
            |
            +-- foreach ($db in $InputObject)
                    |
                    +-- $db.IsAccessible チェック
                    |       |
                    |       +-- false: 警告メッセージ、スキップ
                    |
                    +-- $db.UserDefinedTableTypes.Count チェック
                    |       |
                    |       +-- 0: 情報メッセージ、スキップ
                    |
                    +-- $Type 指定チェック
                    |       |
                    |       +-- 指定あり: Where-Object Name -in $Type
                    |       +-- 指定なし: 全件取得
                    |
                    +-- foreach ($tabletype in $userDefinedTableTypes)
                            |
                            +-- $tabletype.IsSystemObject チェック
                            |       |
                            |       +-- true: スキップ
                            |
                            +-- Add-Member (NoteProperty追加)
                            |       |
                            |       +-- ComputerName, InstanceName, SqlInstance, Database
                            |
                            +-- Select-DefaultView
                                    |
                                    +-- SMO UserDefinedTableType オブジェクト出力
```

### データフロー図

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

SqlInstance/         +------------------+
Database         -->| Get-DbaDatabase  |
                     | (SqlInstance時)  |
                     +--------+---------+
                              |
                              v
InputObject          +------------------+
                 -->| IsAccessible     |
                     | チェック         |
                     +--------+---------+
                              |
                              v
                     +------------------+
                     | UserDefined      |
                     | TableTypes.Count |
                     | チェック         |
                     +--------+---------+
                              |
                              v
Type             -->+------------------+
                     | Type フィルタ    |
                     | (指定時)         |
                     +--------+---------+
                              |
                              v
                     +------------------+
                     | IsSystemObject   |
                     | 除外             |
                     +--------+---------+
                              |
                              v
                     +------------------+
                     | NoteProperty追加 |---> SMO UserDefinedTableType[]
                     | 出力             |
                     +------------------+
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbUserDefinedTableType.ps1 | `public/Get-DbaDbUserDefinedTableType.ps1` | ソース | ユーザー定義テーブル型取得の主要ロジック |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | 依存 | データベースオブジェクト取得 |
