# 機能設計書 117-Get-DbaDeprecatedFeature

## 概要

本ドキュメントは、SQL Serverインスタンスで使用されている非推奨機能を特定し、その使用回数を取得するための機能設計書である。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのバージョンアップグレードを計画する際、非推奨機能の使用状況を把握することは極めて重要である。非推奨機能は将来のバージョンで削除される可能性があり、アプリケーションの互換性問題を引き起こす。本機能は、sys.dm_os_performance_countersからSQL Server Deprecated Featuresオブジェクトのカウンターを取得し、実際に使用されている非推奨機能とその使用回数を報告する。

**機能の利用シーン**：
- SQL Serverアップグレード前の互換性評価
- レガシーコードの近代化優先順位付け
- 定期的なコンプライアンス監査
- アプリケーション改修計画の策定

**主要な処理内容**：
1. 対象SQL Serverインスタンスへ接続（SQL Server 2005以降が必要）
2. sys.dm_os_performance_countersから非推奨機能カウンターを取得
3. 使用回数が0より大きい機能のみをフィルタリング
4. 機能名と使用回数をPSCustomObjectとして返却

**関連システム・外部連携**：sys.dm_os_performance_counters DMVを使用。

**権限による制御**：VIEW SERVER STATE権限が必要（DMVアクセスのため）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | PowerShellコマンドラインインターフェースのみ |

## 機能種別

データ参照 / パフォーマンスカウンター取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス（パイプライン可） | 接続可能なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | 有効なWindows/SQL認証資格情報 |
| EnableException | switch | No | 例外を発生させるかどうか | - |

### 入力データソース

- SqlInstanceパラメータ: ユーザー入力またはパイプライン（必須）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverサービス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名（DomainInstanceName） |
| DeprecatedFeature | string | 非推奨機能の名前 |
| UsageCount | int | 機能の使用回数 |

### 出力先

- PowerShellパイプライン（標準出力）
- PSCustomObject として返却

## 処理フロー

### 処理シーケンス

```
1. processブロック開始
   └─ 各SqlInstanceについてループ処理
      ├─ 1.1 Connect-DbaInstance で接続（MinimumVersion = 9）
      ├─ 1.2 DMVクエリ実行
      │      └─ SELECT instance_name, cntr_value FROM sys.dm_os_performance_counters
      │         WHERE object_name LIKE '%SQL%Deprecated Features%' AND cntr_value > 0
      └─ 1.3 各結果をPSCustomObjectとして出力
2. エラー処理
   └─ 接続失敗時は Stop-Function で次のインスタンスへ
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstanceをループ}
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function]
    E --> B
    D -->|Yes| F{SQL 2005以上?}
    F -->|No| G[MinimumVersionエラー]
    G --> B
    F -->|Yes| H[DMVクエリ実行]
    H --> I{結果をループ}
    I --> J[PSCustomObject出力]
    J --> I
    I --> B
    B --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 最小バージョン | SQL Server 2005 (Version 9) 以降が必要 | 常時 |
| BR-002 | 使用済みのみ | cntr_value > 0 の機能のみ出力 | 常時 |
| BR-003 | 名前正規化 | instance_name の前後の空白を除去（LTRIM/RTRIM） | 常時 |

### 計算ロジック

特になし。カウンター値の直接取得のみ。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| カウンター取得 | sys.dm_os_performance_counters | SELECT | 非推奨機能カウンターを取得 |

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

#### sys.dm_os_performance_counters

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | instance_name | object_name LIKE '%SQL%Deprecated Features%' | 機能名 |
| SELECT | cntr_value | cntr_value > 0 | 使用回数 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Server接続失敗 | Stop-Function でエラー出力、次のインスタンスへ |
| - | MinimumVersionError | SQL Server 2000以前 | Connect-DbaInstance でエラー |

### リトライ仕様

リトライ処理は実装されていない。接続エラー時は当該インスタンスをスキップして次を処理。

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

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- sys.dm_os_performance_counters は常にメモリ内に存在するため高速
- フィルタ条件により、結果セットは使用された機能のみに限定

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

- VIEW SERVER STATE権限が必要
- 出力には機密情報は含まれない
- SQL認証使用時は資格情報の安全な管理が必要

## 備考

- 非推奨機能の詳細: https://learn.microsoft.com/en-us/sql/relational-databases/performance-monitor/sql-server-deprecated-features-object
- カウンターはSQL Serverサービス起動時からの累積値
- サービス再起動でカウンターはリセットされる

---

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

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

### 推奨読解順序

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

本機能ではシンプルなPSCustomObjectを出力する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDeprecatedFeature.ps1 | `public/Get-DbaDeprecatedFeature.ps1` | 出力プロパティ（80-86行目） |

**読解のコツ**: 5つのプロパティ（ComputerName、InstanceName、SqlInstance、DeprecatedFeature、UsageCount）のシンプルな構造。

#### Step 2: SQLクエリを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDeprecatedFeature.ps1 | `public/Get-DbaDeprecatedFeature.ps1` | DMVクエリ（78行目） |

**主要処理フロー**:
- **78行目**: クエリ実行
  - `SELECT LTRIM(RTRIM(instance_name)) AS DeprecatedFeature, cntr_value AS UsageCount`
  - `FROM sys.dm_os_performance_counters`
  - `WHERE object_name LIKE '%SQL%Deprecated Features%' AND cntr_value > 0`

#### Step 3: 接続と結果処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDeprecatedFeature.ps1 | `public/Get-DbaDeprecatedFeature.ps1` | processブロック全体（70-88行目） |

**主要処理フロー**:
- **73行目**: Connect-DbaInstance -MinimumVersion 9
- **79行目**: foreachで結果をループ
- **80-86行目**: PSCustomObjectの構築

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

```
Get-DbaDeprecatedFeature
    │
    ├─ Connect-DbaInstance (-MinimumVersion 9)
    │
    └─ $server.Query()
           │
           └─ sys.dm_os_performance_counters クエリ
                  │
                  └─ PSCustomObject 構築
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ───▶ $server
                            │
                            ▼
                     $server.Query()
                            │
                            ▼
                     sys.dm_os_performance_counters
                     WHERE object_name LIKE '%Deprecated%'
                       AND cntr_value > 0
                            │
                            ▼
                     foreach ($feature in $results)
                            │
                            ▼
                     PSCustomObject ───▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDeprecatedFeature.ps1 | `public/Get-DbaDeprecatedFeature.ps1` | ソース | メイン関数の実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続機能 |
