# 画面設計書 227-ディレクトリ作成

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるディレクトリ作成機能の設計仕様を定義する。SQL Serverサービスアカウントの権限でリモートマシン上にディレクトリを作成する機能を提供するCLIインターフェースである。

### 本画面の処理概要

本機能は、xp_create_subdir拡張ストアドプロシージャを使用して、SQL Serverマシン上にディレクトリを作成する。SQL Serverサービスアカウントがアクセスできるパスにディレクトリを作成できるため、バックアップディレクトリ、ログシッピングパス、データベースファイルの格納場所など、SQL Serverがアクセスする必要があるフォルダの準備に適している。

**業務上の目的・背景**：バックアップ、リストア、データベース作成など、DBA作業ではディレクトリの作成が頻繁に必要となる。しかし、セキュリティ上の理由からファイルサーバーへの直接アクセスが制限されている環境も多い。本機能は、SQL Server経由でディレクトリを作成することで、SQL Serverサービスアカウントがアクセス可能なパスに確実にディレクトリを作成できる。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行することでアクセスする。
- `New-DbaDirectory` - ディレクトリの作成

**主要な操作・処理内容**：
1. 指定パスの存在確認
2. xp_create_subdirによるディレクトリ作成
3. 作成結果の返却
4. ShouldProcess（WhatIf/Confirm）のサポート

**画面遷移**：本機能はCLIコマンドであり、画面遷移は存在しない。バックアップやリストア操作の前処理として使用されることが多い。

**権限による表示制御**：SQL Serverへの接続権限とxp_create_subdir実行権限が必要。また、SQL Serverサービスアカウントが対象パスへの書き込み権限を持っている必要がある。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | New-DbaDirectory | 主機能 | SQL Server経由でのディレクトリ作成 |
| - | Test-DbaPath | 関連機能 | パス存在確認（事前チェック） |
| - | Connect-DbaInstance | 関連機能 | SQL Serverインスタンスへの接続確立 |
| - | Backup-DbaDatabase | 関連機能 | バックアップ前のディレクトリ準備 |
| - | Restore-DbaDatabase | 関連機能 | リストア先ディレクトリの準備 |

## 画面種別

CLIコマンド（PowerShell関数）

## URL/ルーティング

PowerShellコマンドレット：
- `New-DbaDirectory`

## 入出力項目

### New-DbaDirectory パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス |
| Path | string | Yes | 作成するディレクトリのフルパス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| WhatIf | switch | No | 実行せずに動作をシミュレート |
| Confirm | switch | No | 実行前に確認を求める |
| EnableException | switch | No | 例外処理モードの切り替え |

## 表示項目

### New-DbaDirectory 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Server | DbaInstanceParameter | SQL Serverインスタンス名 |
| Path | string | 作成されたディレクトリパス |
| Created | bool | ディレクトリが正常に作成されたか |

## イベント仕様

### 1-ディレクトリ作成処理

ディレクトリを作成する処理フロー：

1. Connect-DbaInstanceでSQL Serverに接続
2. パス内のシングルクォートをエスケープ（''に変換）
3. Test-DbaPathでパスの存在確認
4. パスが既存の場合：
   - Stop-Functionでエラー表示、次のインスタンスへ
5. パスが存在しない場合：
   - ShouldProcessで確認
   - xp_create_subdirを実行
   - 成功時：Created = $true
   - 失敗時：Created = $false、Stop-Functionでエラー
6. 結果をPSCustomObjectで出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| New-DbaDirectory | (なし) | EXEC | xp_create_subdir実行 |

### テーブル別更新項目詳細

本機能はデータベーステーブルの更新を行わない。ファイルシステム操作のみ。

## メッセージ仕様

| 種別 | メッセージID | メッセージ内容 | 発生条件 |
|------|-------------|---------------|---------|
| Error | - | Failure | 接続失敗時 |
| Error | - | $Path already exists | パスが既に存在する場合 |
| Error | - | Failure | ディレクトリ作成失敗時 |
| Debug | - | (SQLクエリ内容) | SQLクエリ詳細表示 |
| WhatIf | - | Creating a new path on $server | WhatIf実行時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-FunctionでConnectionErrorカテゴリ、処理中断 |
| パス既存 | Stop-Functionでエラー表示、次のインスタンスへContinue |
| 作成失敗 | Stop-Functionでエラー表示、Created = $falseを返却 |

## 備考

- SupportsShouldProcess属性により-WhatIfと-Confirmをサポート
- パス内のシングルクォートは自動的にエスケープされる
- 複数のSQL Serverインスタンスに対して同時に実行可能
- 既存パスの場合は作成をスキップ（上書きなし）
- SQL Serverサービスアカウントがアクセス可能なパスのみ作成可能

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaDirectory.ps1 | `public/New-DbaDirectory.ps1` | 108-112行目の出力オブジェクト構造 |

**読解のコツ**: 出力オブジェクトはServer, Path, Createdの3プロパティのみのシンプルな構造。

#### Step 2: パラメータ定義を理解する

必須パラメータとShouldProcessサポートを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDirectory.ps1 | `public/New-DbaDirectory.ps1` | 72-80行目のパラメータ定義 |

**主要処理フロー**:
1. **72行目**: CmdletBinding(SupportsShouldProcess)でWhatIf/Confirmサポート
2. **74-75行目**: SqlInstanceとPathは必須パラメータ
3. **78行目**: SqlCredentialはオプション

#### Step 3: 事前チェックと作成処理を理解する

パス存在確認とxp_create_subdir実行を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDirectory.ps1 | `public/New-DbaDirectory.ps1` | 82-114行目のforeach処理 |

**主要処理フロー**:
- **89行目**: シングルクォートのエスケープ（SQLインジェクション対策）
- **91行目**: Test-DbaPathで事前確認
- **93-95行目**: 既存パスの場合はスキップ
- **97行目**: xp_create_subdirクエリ構築
- **99-112行目**: ShouldProcess確認後に実行

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

```
New-DbaDirectory
    |
    +-- Connect-DbaInstance
    |
    +-- Test-DbaPath（パス存在確認）
    |
    +-- $server.Query($sql)（xp_create_subdir実行）
```

### データフロー図

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

SqlInstance -------> Connect -------> Test-DbaPath -------> xp_create_subdir -------> PSCustomObject
Path                 接続確立         存在確認              ディレクトリ作成           (Server, Path, Created)

【処理フロー詳細】
1. Path.Replace("'", "''") - SQLインジェクション対策
2. Test-DbaPath -SqlInstance $server -Path $Path
3. EXEC master.dbo.xp_create_subdir '$Path'
4. 結果返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDirectory.ps1 | `public/New-DbaDirectory.ps1` | ソース | ディレクトリ作成機能 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パス存在確認（依存） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立（依存） |
