# 機能設計書 193-New-DbaDirectory

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`New-DbaDirectory`機能の設計仕様を記載する。この機能は、SQL Serverサービスアカウントを使用してSQL Serverマシン上にディレクトリを作成する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverの運用において、バックアップディレクトリ、ログシッピングパス、データベースファイルの保存場所などを作成する必要がある。これらのディレクトリはSQL Serverサービスアカウントがアクセスできる必要がある。本機能は、xp_create_subdir拡張ストアドプロシージャを使用してSQL Serverサービスアカウントの権限でディレクトリを作成することで、適切なアクセス権限を確保する。

**機能の利用シーン**：
- 新しいバックアップ保存先ディレクトリの作成
- ログシッピング用の共有フォルダパス作成
- データベースファイル（mdf/ldf）の新規保存先準備
- AlwaysOn可用性グループ用のバックアップパス設定

**主要な処理内容**：
1. SQL Serverインスタンスに接続
2. Test-DbaPathでパスの存在確認
3. 既存パスの場合はスキップ（警告出力）
4. xp_create_subdirを実行してディレクトリを作成
5. 作成結果をPSCustomObjectで返却

**関連システム・外部連携**：SQL Server（xp_create_subdir拡張ストアドプロシージャ）。

**権限による制御**：SQL Serverサービスアカウントの権限でディレクトリを作成するため、サービスアカウントが対象パスにアクセスできる必要がある。リモートサーバーへのアクセスにはリモーティングが有効である必要がある。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 227 | ディレクトリ作成 | 主機能 | ディレクトリの作成 |

## 機能種別

CRUD操作（CREATE） / システム管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | Mandatory |
| Path | string | Yes | 作成するディレクトリのフルパス | Mandatory |
| SqlCredential | PSCredential | No | SQL Server認証情報 | - |
| EnableException | switch | No | 例外をスローするかどうか | - |

### 入力データソース

パラメータ入力のみ。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Server | DbaInstanceParameter | 対象SQL Serverインスタンス |
| Path | string | 作成されたディレクトリパス |
| Created | bool | 作成成功の場合$true、失敗の場合$false |

### 出力先

PowerShellパイプラインへの出力。パスが既に存在する場合、またはWhatIfが指定された場合は出力なし。

## 処理フロー

### 処理シーケンス

```
1. 各SqlInstanceに対してループ処理
   └─ Connect-DbaInstanceで接続
2. パスのエスケープ処理
   └─ シングルクォートをエスケープ
3. パス存在確認
   └─ Test-DbaPathで確認
4. 既存パスの場合
   └─ Stop-Functionで警告、次のインスタンスへContinue
5. ShouldProcess確認
   └─ WhatIf/Confirm対応
6. xp_create_subdir実行
   ├─ SQL文実行
   ├─ 成功時: Created = $true
   └─ 失敗時: Created = $false、Stop-Function
7. 結果オブジェクト返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[foreach SqlInstance]
    B --> C{Connect-DbaInstance成功?}
    C -->|No| D[Stop-Function Continue]
    C -->|Yes| E[パスのシングルクォートをエスケープ]
    E --> F[Test-DbaPath]
    F --> G{パス存在?}
    G -->|Yes| H[Stop-Function パス既存 Continue]
    G -->|No| I{ShouldProcess確認}
    I -->|No| J[次のインスタンスへ]
    I -->|Yes| K[xp_create_subdir実行]
    K --> L{実行成功?}
    L -->|Yes| M[Created = true]
    L -->|No| N[Created = false, Stop-Function]
    M --> O[PSCustomObject返却]
    N --> O
    D --> B
    H --> B
    J --> B
    O --> P{次のインスタンス?}
    P -->|Yes| B
    P -->|No| Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 既存パススキップ | パスが既に存在する場合は作成をスキップ | Test-DbaPathでtrue |
| BR-002 | クォートエスケープ | パス内のシングルクォートはエスケープ | パスにシングルクォート含む場合 |
| BR-003 | ShouldProcess | Confirm/WhatIf対応 | 常時 |

### 計算ロジック

特に計算処理はない。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| xp_create_subdir | - | EXEC | ディレクトリ作成 |

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

データベーステーブルへの操作はない。xp_create_subdirはファイルシステム操作のみ。

#### 実行SQL

```sql
EXEC master.dbo.xp_create_subdir '{Path}'
```

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Server接続失敗 | 接続情報を確認 |
| - | Stop-Function | パス既存 | 既存パスを使用するか別パスを指定 |
| - | Stop-Function | xp_create_subdir失敗 | 権限・パスを確認 |

### リトライ仕様

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

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

xp_create_subdirはファイルシステム操作のため、データベーストランザクションは関与しない。

## パフォーマンス要件

特になし。単一ディレクトリ作成の軽量な操作。

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

- SQL Serverサービスアカウントの権限でディレクトリを作成
- SqlCredentialで認証情報を安全に渡す
- パス内のシングルクォートはエスケープしてSQLインジェクションを防止
- リモートサーバーへはリモーティング経由でアクセス

## 備考

- xp_create_subdirはSQL Serverサービスアカウントとして実行されるため、そのアカウントがアクセスできないパスには作成不可
- ネットワークパス（UNC）も作成可能だが、SQL Serverサービスアカウントに適切な権限が必要

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を理解する。

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

**読解のコツ**: 出力はServer、Path、Createdの3プロパティを持つシンプルなPSCustomObject。

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

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

**主要処理フロー**:
1. **72-80行目**: param()ブロックでパラメータ定義
2. **82-87行目**: Connect-DbaInstanceで接続
3. **89行目**: パスのシングルクォートエスケープ
4. **91-95行目**: Test-DbaPathでパス存在確認
5. **97-106行目**: xp_create_subdir実行
6. **108-112行目**: 結果オブジェクト返却

#### Step 3: SQL実行処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDirectory.ps1 | `public/New-DbaDirectory.ps1` | xp_create_subdir実行部分 |

**主要処理フロー**:
- **97行目**: SQL文構築
- **98行目**: Write-Messageでデバッグ出力
- **99-106行目**: ShouldProcess内で実行

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

```
New-DbaDirectory
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続
    │
    ├─ Test-DbaPath
    │      └─ パス存在確認
    │
    └─ $server.Query()
           └─ xp_create_subdir実行
```

### データフロー図

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

SqlInstance ───────────────┐
                           │
SqlCredential ─────────────┼──▶ Connect-DbaInstance
                           │           │
                           │           ▼
Path ──────────────────────┼──▶ Test-DbaPath ──▶ 存在チェック
                           │           │
                           │           ▼ (未存在の場合)
                           │    xp_create_subdir実行 ──────────▶ PSCustomObject
                           │                                      (Server, Path, Created)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDirectory.ps1 | `public/New-DbaDirectory.ps1` | ソース | メイン関数定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パス存在確認 |
