Skip to content

Free, open-source Windows optimization tool for performance, privacy, and simplicity.

docs: update contributing (and its locales) and agents.md

fatDucka574f9111894
diff --git a/.github/contributing/CONTRIBUTING.ja-JP.md b/.github/contributing/CONTRIBUTING.ja-JP.md
index 3b6c6d0..a6bc027 100644
--- a/.github/contributing/CONTRIBUTING.ja-JP.md
+++ b/.github/contributing/CONTRIBUTING.ja-JP.md
@@ -1,10 +1,10 @@
<div align="center">
-<a href="https://optimizerduck.vercel.app/"><img src="./.github/assets/optimizerDuck.png" alt="optimizerDuck Banner" title="optimizerDuck"/></a>
+<a href="https://optimizerduck.vercel.app/"><img src="../assets/optimizerDuck.png" alt="optimizerDuck Banner" title="optimizerDuck"/></a>
-[English](../CONTRIBUTING.md) | **日本語** | [Türkçe](CONTRIBUTING.tr-TR.md)
+[English](../../CONTRIBUTING.md) | **日本語** | [Türkçe](CONTRIBUTING.tr-TR.md)
-[はじめに](#introduction) • [セットアップ](#getting-started) • [アーキテクチャ概要](#architecture-overview) • [貢献の方法](#ways-to-contribute) • [最適化の作成](#creating-an-optimization) • [カスタマイズ設定の作成](#creating-a-customize-setting) • [リフレッシュスコープシステム](#the-refresh-scope-system) • [新機能の構築](#building-new-features) • [リバートシステム](#revert-system) • [テスト](#testing) • [コーディング規約](#coding-standards) • [ローカライズ](#localization) • [プルリクエストの手順](#pull-request-process) • [Issue ガイドライン](#issue-guidelines) • [FAQ とトラブルシューティング](#faq--troubleshooting) • [ライセンス](#license)
+[はじめに](#introduction) • [セットアップ](#getting-started) • [アーキテクチャ概要](#architecture-overview) • [貢献の方法](#ways-to-contribute) • [最適化の作成](#creating-an-optimization) • [カスタマイズ設定の作成](#creating-a-customize-setting) • [条件システム](#the-condition-system) • [リフレッシュスコープシステム](#the-refresh-scope-system) • [新機能の構築](#building-new-features) • [リバートシステム](#revert-system) • [テスト](#testing) • [コーディング規約](#coding-standards) • [ローカライズ](#localization) • [プルリクエストの手順](#pull-request-process) • [Issue ガイドライン](#issue-guidelines) • [FAQ とトラブルシューティング](#faq--troubleshooting) • [ライセンス](#license)
</div>
@@ -12,9 +12,10 @@
<h1 id="introduction">はじめに</h1>
-**optimizerDuck** への貢献ありがとうございます。本プロジェクトは、.NET 10 上の WPF で構築された、無料のオープンソース Windows 最適化ツールです。
+**.NET 10 上の WPF で構築された、無料のオープンソース Windows 最適化ツール**である **optimizerDuck** への貢献ありがとうございます。
以下のような形でお手伝いいただけます:
+
- 再現手順を明確にしたバグ報告
- 新しい最適化や機能の提案(まず Issue を作成してください)
- ドキュメントやガイドの改善
@@ -22,6 +23,8 @@
- コードの貢献:最適化、カスタマイズ設定、サービス、UI の改善
- テストの追加や既存テストのレビュー
+> **初めての方へ**:まず [セットアップ](#getting-started)、次に [アーキテクチャ概要](#architecture-overview) を読んでください。最も一般的なコード貢献は [最適化の作成](#creating-an-optimization) と [カスタマイズ設定の作成](#creating-a-customize-setting) です。
+
---
<h1 id="getting-started">セットアップ</h1>
@@ -39,20 +42,20 @@
```bash
dotnet --version
-# Should output 10.x
+# 10.x と表示されるはずです
```
<h3 id="fork-and-clone">2. フォークとクローン</h3>
```bash
-# Fork on GitHub first, then clone your fork
+# まず GitHub でリポジトリをフォークし、自分のフォークをクローンします
git clone https://github.com/<your-username>/optimizerDuck.git
cd optimizerDuck
-# Add upstream remote to sync with the main repo
+# メインリポジトリと同期するために upstream を追加します
git remote add upstream https://github.com/itsfatduck/optimizerDuck.git
-# Create a branch for your work (never work on master)
+# 作業用のブランチを作成します(master で直接作業しないこと)
git checkout -b feature/your-feature-name
```
@@ -61,19 +64,19 @@ git checkout -b feature/your-feature-name
ソリューションは `.slnx` 形式(XML ベースのソリューションファイル、`.sln` ではありません)を使用します。
```bash
-# Restore dependencies
+# 依存関係を復元
dotnet restore optimizerDuck.slnx
-# Build (CI uses Release, Debug works too)
+# ビルド(CI は Release、Debug でも動作します)
dotnet build optimizerDuck.slnx --configuration Release --no-restore
-# Run tests
+# テストを実行
dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build
-# Run the app
+# アプリを実行(システム設定を変更するため管理者権限のプロンプトが必要)
dotnet run --project optimizerDuck/optimizerDuck.csproj
-# Format code with CSharpier
+# CSharpier でコードを整形
dotnet csharpier .
```
@@ -82,12 +85,14 @@ dotnet csharpier .
<h3 id="publishing">4. 公開(Publishing)</h3>
```bash
-publish.bat portable # Portable folder (recommended for testing)
-publish.bat single # Single-file executable
-publish.bat single --skip-tests # Skip tests for quick iteration
-publish.bat portable --no-pause # Don't pause at the end (CI-friendly)
+publish.bat portable # ポータブルフォルダ(テスト用に推奨)
+publish.bat single # 単一ファイルの実行可能ファイル
+publish.bat single --skip-tests # 素早い反復のためにテストをスキップ
+publish.bat portable --no-pause # 最後に一時停止しない(CI 向け)
```
+`publish.bat` はまずテストを実行し(`--skip-tests` を渡した場合はスキップ)、選択したプロファイル(`Portable` または `Single`)で `dotnet publish` を呼び出します。
+
<h3 id="quick-start-checklist">5. クイックスタートチェックリスト</h3>
初めて貢献する前に:
@@ -95,7 +100,7 @@ publish.bat portable --no-pause # Don't pause at the end (CI-friendly)
- [ ] リポジトリをフォークしてクローンする
- [ ] `dotnet build` が成功する(エラー 0 件)
- [ ] `dotnet test` が通る(すべてのテストが成功)
-- [ ] `dotnet csharpier .` がエラーなくフォーマットできる
+- [ ] `dotnet csharpier .` がエラーなく整形できる
- [ ] 下記の [アーキテクチャ概要](#architecture-overview) を読む
---
@@ -105,82 +110,118 @@ publish.bat portable --no-pause # Don't pause at the end (CI-friendly)
<h3 id="solution-structure">ソリューション構成</h3>
```
-optimizerDuck.slnx # Solution file (.slnx format)
-├── optimizerDuck/ # Main WPF app (net10.0-windows)
-│ ├── App.xaml.cs # DI registration, startup, theme, logging
+optimizerDuck.slnx # ソリューションファイル(.slnx 形式)
+├── optimizerDuck/ # メイン WPF アプリ(net10.0-windows)
+│ ├── App.xaml.cs # DI 登録、スタートアップ、テーマ、ログ
│ ├── optimizerDuck.csproj # TFM: net10.0-windows10.0.17763.0, UseWPF=true
-│ ├── app.manifest # requireAdministrator UAC level
+│ ├── app.manifest # requireAdministrator UAC レベル
│ │
-│ ├── Domain/ # Pure models, interfaces, attributes (no WPF deps)
-│ │ ├── Abstractions/ # IOptimization, ICustomizeSetting, IRevertStep, IWindow, ICustomizeCategory, IOptimizationCategory
-│ │ ├── Attributes/ # [Optimization], [CustomizeSetting], [OptimizationCategory], [CustomizeCategory]
-│ │ ├── Configuration/ # AppSettings model
-│ │ ├── Execution/ # ExecutionScope — ambient step tracking via AsyncLocal
-│ │ ├── Customize/ # Customize settings (Desktop, Gaming, Preferences, System)
-│ │ │ ├── Categories/ # Category classes with nested setting classes
-│ │ │ └── Models/ # BaseCustomizeSetting, RegistryToggle, RefreshScope, SettingOption, CustomizeControlType, RecommendationState
-│ │ ├── Optimizations/ # Optimizations (Performance, Privacy, GPU, etc.)
-│ │ │ ├── Categories/ # Category classes with nested optimization classes
-│ │ │ └── Models/ # BaseOptimization, ApplyResult, OptimizationContext, ServiceItem, RegistryItem
-│ │ │ ├── Bloatware/ # AppXPackage model
-│ │ │ ├── Cleanup/ # CleanupItem
+│ ├── Domain/ # 純粋なモデル、インターフェイス、属性(WPF 依存なし)
+│ │ ├── Abstractions/ # IOptimization, ICustomizeSetting, IRevertStep, IWindow,
+│ │ │ # ICustomizeCategory, IOptimizationCategory
+│ │ ├── Attributes/ # [Optimization], [CustomizeSetting],
+│ │ │ # [OptimizationCategory], [CustomizeCategory]
+│ │ ├── Conditions/ # 互換性条件システム(「条件システム」を参照)
+│ │ │ ├── BuiltIn/ # 既製の条件(Windows バージョン、GPU/CPU ブランド、
+│ │ │ │ # 最小 RAM、レジストリキー/サービスの存在など)
+│ │ │ ├── ICondition.cs # 条件のコントラクト
+│ │ │ ├── ConditionBase.cs # 共通ヘルパー(OS ビルド番号の解析など)
+│ │ │ ├── ConditionResult.cs # Available / Unsupported / Error の結果
+│ │ │ ├── ConditionState.cs # 結果の列挙型
+│ │ │ ├── ConditionValidation.cs # 検出時のメタデータ検証
+│ │ │ └── WindowsBuilds.cs # OS ビルド番号の定数
+│ │ ├── Configuration/ # AppSettings モデル
+│ │ ├── Exceptions/ # StepExecutionException
+│ │ ├── Execution/ # ExecutionScope — AsyncLocal による環境的ステップ追跡
+│ │ ├── Customize/ # カスタマイズ設定
+│ │ │ ├── Categories/ # ネストされた設定クラスを持つカテゴリクラス
+│ │ │ └── Models/ # BaseCustomizeSetting, RegistryToggle, RegistryBinding,
+│ │ │ # CustomizeRefreshScope, SettingOption,
+│ │ │ # CustomizeControlType, RecommendationState など
+│ │ ├── Optimizations/ # 最適化
+│ │ │ ├── Categories/ # ネストされた最適化クラスを持つカテゴリクラス
+│ │ │ └── Models/ # BaseOptimization, ApplyResult, OptimizationContext,
+│ │ │ ├── Bloatware/ # プリインストールアプリ用の AppXPackage モデル
+│ │ │ ├── Cleanup/ # ディスククリーンアップ用の CleanupItem
│ │ │ ├── ScheduledTask/ # ScheduledTaskModel
│ │ │ ├── Services/ # RegistryItem, ServiceItem, ShellResult, ServiceStartupType
-│ │ │ └── StartupManager/ # StartupApp, StartupTask
-│ │ ├── Revert/ # RevertData, RevertResult, revert step types
-│ │ │ └── Steps/ # RegistryRevertStep, ServiceRevertStep, ScheduledTaskRevertStep, ShellRevertStep, UsbPowerRevertStep
-│ │ └── UI/ # Enums: OptimizationRisk, OptimizationTags, OptimizationCategoryOrder, CustomizeOrder, LanguageOption, OptimizationState, RiskVisual, ProcessingProgress
+│ │ │ └── StartupManager/ # StartupApp, StartupTask モデル
+│ │ ├── Revert/ # RevertData, RevertResult, リバートステップ型
+│ │ │ └── Steps/ # RegistryRevertStep, ServiceRevertStep,
+│ │ │ # ScheduledTaskRevertStep, ShellRevertStep, UsbPowerRevertStep
+│ │ └── UI/ # 列挙型: OptimizationRisk, OptimizationTags,
+│ │ # OptimizationCategoryOrder, CustomizeOrder,
+│ │ # LanguageOption, OptimizationState, RiskVisual,
+│ │ # ProcessingProgress など
│ │
-│ ├── Common/ # Shared helpers, extensions, converters
-│ │ ├── Converters/ # 20+ WPF value converters
-│ │ ├── Extensions/ # StringExtensions, CustomizePageRegistryExtensions, OptimizationPageRegistryExtensions, LanguageExtensions
-│ │ ├── Helpers/ # Shared.cs, ReflectionHelper.cs, SystemRefreshService.cs, EmbeddedResourceHelper.cs, GitHubSourceHelper.cs, WmiHelper.cs, ThemeResource.cs
-│ │ └── Native/ # Native interop helpers
+│ ├── Common/ # 共有ヘルパー、拡張、コンバーター
+│ │ ├── Converters/ # WPF 値コンバーター(BooleanToVisibility, MBToGB など)
+│ │ ├── Extensions/ # StringExtensions, ページレジストリ拡張,
+│ │ │ # LanguageExtensions
+│ │ └── Helpers/ # Shared.cs, ReflectionHelper.cs, SystemRefreshService.cs,
+│ │ # EmbeddedResourceHelper.cs, WmiHelper.cs,
+│ │ # GitHubSourceHelper.cs, ThemeResource.cs など
│ │
-│ ├── Services/ # Business logic layer
+│ ├── Services/ # ビジネスロジック層
+│ │ ├── Conditions/ # ConditionEvaluator(静的評価のエントリポイント)
│ │ ├── Configuration/ # ConfigManager, LanguageManager
-│ │ ├── Customize/ # CustomizeRegistry (reflection-based discovery)
+│ │ ├── Customize/ # CustomizeRegistry(リフレクションベースの検出)
│ │ ├── Optimization/ # OptimizationRegistry, OptimizationService
-│ │ │ └── Providers/ # Static: RegistryService, ShellService, ScheduledTaskService, ServiceProcessService
-│ │ ├── Revert/ # RevertManager (atomic write/read of revert JSON files)
-│ │ ├── System/ # RegistryWatcher, StreamService, SystemInfoService, UpdaterService
+│ │ │ └── Providers/ # 静的: RegistryService, ShellService (+ ShellPolicy),
+│ │ │ # ScheduledTaskService, ServiceProcessService
+│ │ ├── Revert/ # RevertManager(リバート JSON のアトミック読み書き)
+│ │ ├── System/ # RegistryWatcher (+ IRegistryWatcher), SystemInfoService,
+│ │ │ # StreamService, UpdaterService, CrossPageEventBus
│ │ └── UI/ # BloatwareService, DiskCleanupService, StartupManagerService
│ │
-│ ├── UI/ # WPF pages, ViewModels, controls, styles
+│ ├── UI/ # WPF ページ、ViewModel、コントロール、スタイル
│ │ ├── Behaviors/ # SmoothScrollBehavior
-│ │ ├── Controls/ # FilledNavigationViewItem
-│ │ ├── Dialogs/ # ProcessingDialog, OptimizationDetailsDialog, OptimizationResultDialog, RestorePointDialog, LegalDialog, BloatwareConfirmationDialog, ScheduledTaskCreateDialog, ScheduledTaskDetailsDialog, StartupTaskDetailsPanel
-│ │ ├── Pages/ # Dashboard, Optimize, Customize, Settings, Bloatware, DiskCleanup, StartupManager, ScheduledTasks + sub-folders
-│ │ │ ├── Customize/ # CustomizePage + Categories/
-│ │ │ └── Optimize/ # OptimizePage + Categories/
+│ │ ├── Controls/ # FilledNavigationViewItem, EmptyBadge
+│ │ ├── Dialogs/ # ProcessingDialog, OptimizationDetailsDialog,
+│ │ │ # OptimizationResultDialog, RestorePointDialog, LegalDialog,
+│ │ │ # BloatwareConfirmationDialog, ScheduledTask ダイアログなど
+│ │ ├── Pages/ # Dashboard, Optimize, Customize, Settings, Bloatware,
+│ │ │ ├── Customize/ # CustomizePage + Categories/(自動登録ページ)
+│ │ │ ├── Optimize/ # OptimizePage + Categories/(自動登録ページ)
+│ │ │ ├── DiskCleanupPage
+│ │ │ ├── StartupManagerPage
+│ │ │ └── ScheduledTasksPage
│ │ ├── Styles/ # FluentDesign.xaml, NavigationViewOverride.xaml, ToolTipOverride.xaml
-│ │ ├── ViewModels/ # Page and dialog ViewModels
-│ │ │ ├── Customize/ # CustomizeItemViewModel, CustomizeCategoryViewModel
-│ │ │ ├── Dialogs/ # ProcessingViewModel, OptimizationDetailsViewModel, etc.
-│ │ │ ├── Optimizer/ # OptimizationCategoryViewModel
-│ │ │ ├── Pages/ # Dashboard, Optimize, Customize, Settings, etc.
-│ │ │ └── Windows/ # MainWindowViewModel
+│ │ ├── ViewModels/ # ページ、ダイアログ、ウィンドウの ViewModel
│ │ └── Windows/ # MainWindow
│ │
-│ └── Resources/ # Images, embedded assets, localization
-│ ├── Embedded/ # Power plans, icons
-│ ├── Images/ # Duck.png, logos
-│ └── Languages/ # Translations.resx + 11 locale variants
+│ └── Resources/ # 画像、埋め込みアセット、ローカライズ
+│ ├── Embedded/ # Icons/ と PowerPlans/(optimizerDuck.pow)
+│ ├── Images/ # Duck.png, GitHub ロゴ, Discord ロゴ
+│ └── Languages/ # Translations.resx(デフォルト)+ ロケール版
│
-└── optimizerDuck.Test/ # xUnit v3 test project
+└── optimizerDuck.Test/ # xUnit v3 テストプロジェクト(InternalsVisibleTo)
```
+> **上のツリーを厳密な仕様として参照しないでください。** これは地図であり仕様ではありません — フォルダやファイルは進化します。迷ったら実際のフォルダを確認してください。本セクション末尾の「プロジェクト構造」も参照してください。
+
<h3 id="key-design-decisions">主要な設計判断</h3>
| 判断 | 理由 |
|---|---|
-| **リフレクションによる自動検出** | DI 登録配列を更新する必要がありません。`ReflectionHelper.FindImplementationsInLoadedAssemblies<T>()` が起動時に `optimizerDuck.*` アセンブリをスキャンします。新しい最適化や設定は自動的に検出されます。 |
-| **静的プロバイダーサービス** | `RegistryService`、`ShellService`、`ScheduledTaskService`、`ServiceProcessService` は静的クラスです。アンビエントな `ExecutionScope` にリバートステップを記録するため、コンテキストの注入や受け渡しは不要です。 |
+| **リフレクションによる自動検出** | DI 登録配列を更新する必要がありません。`ReflectionHelper.FindImplementationsInLoadedAssemblies<T>()` が `optimizerDuck.*` アセンブリをスキャンします。新しい最適化や設定は自動的に検出されます。 |
+| **静的プロバイダーサービス** | `RegistryService`、`ShellService`、`ScheduledTaskService`、`ServiceProcessService` は静的クラスです。環境的な `ExecutionScope` にリバートステップを記録するため、コンテキストの注入や受け渡しは不要です。 |
| **ファイルベースのリバート追跡** | 適用状態 = ディスク上にファイルが存在する(`%localappdata%\optimizerDuck\Revert\{id}.json`)。データベースは使用しません。`File.Replace()` によるアトミック書き込み。 |
+| **条件システム(フェイルオープン)** | 最適化や設定は互換性条件を宣言できます。評価の失敗がアイテムを隠すことはありません — [条件システム](#the-condition-system) を参照。 |
| **統合スタイルのテスト** | 実際のファイルシステム、実際のレジストリ(`HKCU\Software\TestOptimizerDuck*` 配下)、実際のプロセス実行。モックライブラリは使用せず、手書きのテストダブルのみ。 |
-| **非同期サービスメソッド** | 外部プロセスを実行するプロバイダーメソッドは非同期(`*Async` サフィックス)です。最適化の `ApplyAsync` メソッドでは `async`/`await` を使用して UI の応答性を保ってください。 |
-| **静的な WMI ヘルパー** | `WmiHelper.Initialize()` が起動時に実行され、異常終了時の WMI イベントクリーンアップハンドラを登録します。 |
-| **保留中の変更トラッキング** | `App.HasPendingChanges` プロパティが未リバートの最適化を追跡します。アプリ終了時に PC/Explorer 再起動または終了のオプションを表示します。 |
+| **非同期サービスメソッド** | 外部プロセスを実行するプロバイダーメソッドは非同期(`*Async` サフィックス)。最適化の `ApplyAsync` では `async`/`await` で UI の応答性を保ちます。 |
+| **静的な WMI ヘルパー** | `WmiHelper.Initialize()` が起動時に実行され、異常終了時の WMI クリーンアップハンドラを登録します。 |
+| **保留中の変更トラッキング** | `App.HasPendingChanges` が未リバートの最適化を追跡。終了時に PC/Explorer 再起動または終了のオプションを表示します。 |
+
+<h3 id="project-structure">プロジェクト構造</h3>
+
+信頼できる構造は次の 3 か所にあり、移動やリネームの際は常に同期を保つ必要があります:
+
+1. **ディスク上のフォルダ** — `optimizerDuck/`(アプリ)と `optimizerDuck.Test/`(テスト)。これ以外のトップレベルプロジェクトディレクトリはありません。
+2. **`optimizerDuck.csproj`** — 埋め込みリソース、画像、パッケージ参照。
+3. **`App.xaml.cs`** — DI 登録と起動シーケンス。
+
+これら 2 つのプロジェクトフォルダ以外のトップレベルディレクトリを作成**しないでください**。
---
@@ -189,7 +230,8 @@ optimizerDuck.slnx # Solution file (.slnx format)
| 貢献の種類 | 説明 | 着手場所 |
|---|---|---|
| **新しい最適化** | レジストリの調整、サービスの変更、システムの調整 | `Domain/Optimizations/Categories/*.cs` |
-| **新しいカスタマイズ設定** | Windows 設定の UI トグル(ゲームモード、マウス加速度など) | `Domain/Customize/Categories/*.cs` |
+| **新しいカスタマイズ設定** | Windows 設定の UI トグル(ゲームモード、マウス加速度、タスクバーなど) | `Domain/Customize/Categories/*.cs` |
+| **新しい条件** | 最適化/設定の互換性ゲート(Windows バージョン、ハードウェアなど) | `Domain/Conditions/` |
| **新しいアプリ機能** | 新しいページ、ツール、機能 | まず Issue を作成 |
| **バグ修正** | クラッシュ修正、ロジックエラー、UI の問題 | 任意の場所 |
| **翻訳** | 新しい言語の追加や既存翻訳の修正 | `Resources/Languages/Translations.*.resx` |
@@ -202,29 +244,31 @@ optimizerDuck.slnx # Solution file (.slnx format)
<h3 id="how-discovery-works">検出の仕組み</h3>
-起動時:
+起動時にアプリは `OptimizationRegistry.PreloadOptimizationsAsync()` を呼び出し、リフレクション処理をバックグラウンドスレッドで実行します:
-1. `ReflectionHelper.FindImplementationsInLoadedAssemblies<IOptimizationCategory>()` がすべての `optimizerDuck.*` アセンブリをスキャンする
-2. `IOptimizationCategory` を実装するすべてのクラスを見つける
-3. 各カテゴリについて、`IOptimization` を実装する**ネストされた public クラス**をスキャンする
-4. 検出されたすべての最適化がインスタンス化され、`OwnerType` が自動的に割り当てられる
-5. `OptimizationService.UpdateOptimizationStateAsync` がディスク上のリバートファイルをスキャンし、各最適化を適用済み/未適用としてマークする
-6. `OptimizationRegistry.StartPreload()` が起動時にバックグラウンドスレッドでこれを実行する
+1. `ReflectionHelper.FindImplementationsInLoadedAssemblies<IOptimizationCategory>()` がすべてのカテゴリクラスを検出します。
+2. 各カテゴリについて、`IOptimization` を実装する**ネストされた public クラス**をスキャンします。
+3. 各最適化をインスタンス化し、`OwnerType` を割り当て、`[Optimization]` メタデータ(`Condition` を含む)を検証します。
+4. `OptimizationService.UpdateOptimizationStateAsync` がディスク上のリバートファイルをスキャンし、各最適化を適用済み/未適用としてマークします。
+5. Optimize ページはバインド前に `EnsurePreloadedAsync()` を呼び出します(プリロード済みなら何もしません)。
-**あなたの作業**:カテゴリ内にネストされたクラスを作成し、`BaseOptimization` を継承し、`[Optimization]` を付与する。以上です。
+**あなたの作業**:カテゴリ内にネストされたクラスを作成し、`BaseOptimization` を継承し、`[Optimization]` を付与する。以上です — 登録の更新は不要です。
<h3 id="optimization-categories">最適化カテゴリ</h3>
-現在のカテゴリ(`Domain/Optimizations/Categories/` 内):
+カテゴリは `Domain/Optimizations/Categories/` にファイル単位で配置されています。正確な一覧はそのフォルダを確認してください(セットは時間とともに変わります)。執筆時点のカテゴリは次のとおりです:
-| ファイル | 属性 | 対象 |
-|---|---|---|
-| `Performance.cs` | `[OptimizationCategory(typeof(PerformanceOptimizerPage))]` | RAM 調整、プロセス優先度、キーボードレイテンシ、マルチメディアスケジューラ、アクセシビリティホットキー |
-| `SecurityAndPrivacy.cs` | `[OptimizationCategory(typeof(SecurityAndPrivacyOptimizerPage))]` | テレメトリ、エラー報告、広告 ID、位置情報、Cortana、Copilot、コンテンツ配信マネージャー、アクティビティ履歴、AutoLogger |
-| `Gpu.cs` | `[OptimizationCategory(typeof(GpuOptimizerPage))]` | AMD/NVIDIA/Intel レジストリ調整、電源状態、クロックゲーティング、ASPM、非同期フリップ |
-| `PowerManagement.cs` | `[OptimizationCategory(typeof(PowerManagementOptimizerPage))]` | 休止状態、高速スタートアップ、USB 選択的サスペンド、カスタム電源プランのインストール、省電力設定の無効化 |
-| `BloatwareAndServices.cs` | `[OptimizationCategory(typeof(BloatwareAndServicesOptimizerPage))]` | OEM プリインストールアプリのブロック、170 以上の Windows サービス起動タイプ最適化 |
-| `UserExperience.cs` | `[OptimizationCategory(typeof(UserExperienceOptimizerPage))]` | メニュー遅延、視覚効果、タスクバーアニメーション、透明度、スタートメニューの Web 検索 |
+| ファイル | 対象 |
+|---|---|
+| `Performance.cs` | RAM 調整、プロセス優先度、キーボードレイテンシ、マルチメディアスケジューラ、アクセシビリティホットキー |
+| `SecurityAndPrivacy.cs` | テレメトリ、エラー報告、広告 ID、位置情報、Copilot、アクティビティ履歴、配信最適化など |
+| `Gpu.cs` | AMD/NVIDIA/Intel レジストリ調整、電源状態、クロックゲーティング、ASPM、非同期フリップ |
+| `PowerManagement.cs` | 休止状態、高速スタートアップ、USB 選択的サスペンド、カスタム電源プランのインストール |
+| `BloatwareAndServices.cs` | OEM プリインストールアプリのブロック、Windows サービス起動タイプの最適化 |
+| `UserExperience.cs` | メニュー遅延、視覚効果、タスクバーアニメーション、透明度、スタートメニューの Web 検索 |
+| `AI.cs` | Windows AI 機能(Recall、Click To Do) |
+
+各カテゴリクラスは `[OptimizationCategory(typeof(SomePage))]` 属性で UI ページと紐づけられています。
<h3 id="step-by-step-add-to-existing-category">ステップバイステップ:既存カテゴリへの追加</h3>
@@ -239,9 +283,10 @@ public class Performance : IOptimizationCategory
public ObservableCollection<IOptimization> Optimizations { get; init; } = [];
[Optimization(
- Id = "a1b2c3d4-...", // Generate a NEW GUID
+ Id = "a1b2c3d4-...", // 新しい GUID を生成
Risk = OptimizationRisk.Safe, // Safe / Moderate / Risky
- Tags = OptimizationTags.Performance // Flags — combine with |
+ Tags = OptimizationTags.Performance, // フラグ — | で組み合わせ
+ Condition = typeof(Windows11Condition) // 任意(「条件システム」を参照)
)]
public class MyNewTweak : BaseOptimization
{
@@ -249,15 +294,15 @@ public class Performance : IOptimizationCategory
IProgress<ProcessingProgress> progress,
OptimizationContext context)
{
- // 1. Use static providers to make system changes
+ // 1. 静的プロバイダーでシステムを変更
RegistryService.Write(new RegistryItem(
@"HKLM\SOFTWARE\Something", "ValueName", 1));
- // 2. Await async operations — this yields the UI thread
+ // 2. 非同期操作を await — UI スレッドを解放
await ServiceProcessService.ChangeServiceStartupTypeAsync(
new ServiceItem("SomeService", ServiceStartupType.Disabled));
- // 3. Return result from the ambient ExecutionScope
+ // 3. 環境的な ExecutionScope から結果を返す
return CompleteFromScope();
}
}
@@ -268,15 +313,18 @@ public class Performance : IOptimizationCategory
| ルール | 詳細 |
|---|---|
-| **`Id` は新しい GUID であること** | リバートファイルの命名と適用状態の追跡に使用されます。PowerShell で `[guid]::NewGuid()` を使用して生成します。 |
-| **`BaseOptimization` を継承する** | 属性とローカライズキーから `Name`、`ShortDescription`、`Prefix`、`RiskVisual`、`TagDisplays` を提供します |
-| **`async Task<ApplyResult>` を使用する** | `Task.FromResult()` は使用しない。サービスプロバイダーは非同期 — await して UI の応答性を保つ |
-| **`CompleteFromScope()` を返す** | アンビエントな `ExecutionScope` に記録されたステップから `ApplyResult` を導出する |
-| **進捗を報告する** | `progress.Report(new ProcessingProgress { ... })` を使用して UI ダイアログを更新する |
-| **すべての例外をキャッチしない** | 例外は上位に伝播させる。`ExecutionScope` が成功/失敗を追跡する。`OptimizationService` レイヤーが例外を処理する |
-| **リバートステップを手動で作成しない** | 静的プロバイダーサービスが `ExecutionScope.RecordStep()` 経由で自動的に行う |
-| **`context.Logger` を使用する** | 最適化コンテキストはロガーを提供します。重要な診断情報の記録に使用します |
-| **`context.Snapshot` をチェックする** | `OptimizationContext.Snapshot` がシステム情報(RAM、GPU、CPU)を提供します。条件付きロジックに使用できます |
+| **`Id` は新しい GUID であること** | リバートファイルの命名と適用状態の追跡に使用。PowerShell で `[guid]::NewGuid()` で生成。 |
+| **`BaseOptimization` を継承する** | 属性とローカライズキーから `Name`、`ShortDescription`、`RiskVisual`、`TagDisplays` を提供。 |
+| **`OwnerType` は自動で割り当てられる** | 検出処理が設定します — 自分で設定しないこと。 |
+| **`async Task<ApplyResult>` を使用する** | サービスプロバイダーは非同期 — `await` して UI の応答性を保つ。 |
+| **`CompleteFromScope()` を返す** | 環境的な `ExecutionScope` に記録されたステップから `ApplyResult` を導出。手動で `ApplyResult` を構築しないこと。 |
+| **進捗を報告する** | `progress.Report(new ProcessingProgress { ... })` で UI ダイアログを更新。 |
+| **すべての例外をキャッチしない** | 例外は上位に伝播。`ExecutionScope` が成功/失敗を追跡し、`OptimizationService` が処理。 |
+| **リバートステップを手動で作成しない** | 静的プロバイダーサービスが `ExecutionScope.RecordStep()` 経由で自動的に行う。 |
+| **`context.Logger` を使用する** | 重要な診断情報の記録に使用。 |
+| **`context.Snapshot` を使用する** | `OptimizationContext.Snapshot`(`SystemSnapshot`)が RAM、GPU、CPU、OS 情報を提供。条件分岐に使用。 |
+| **`context.StreamService` を使用する** | リモートリソース(電源プランなど)をダウンロードする最適化向け。 |
+| **必要なら `Condition` を宣言する** | Windows バージョンやハードウェアでゲート — [条件システム](#the-condition-system) を参照。 |
<h3 id="available-service-providers">利用可能なサービスプロバイダー</h3>
@@ -284,50 +332,79 @@ public class Performance : IOptimizationCategory
| サービス | 主要メソッド | 使用理由 |
|---|---|---|
-| **`RegistryService`** | `Write()`、`Read<T>()`、`DeleteValue()`、`CreateSubKey()`、`DeleteSubKeyTree()`、`KeyExists()` | レジストリキーの読み書き/削除。リバート用に元の値をバックアップする。複数の RegistryItem を一度に書き込み可能。 |
-| **`ShellService`** | `CMDAsync()`、`PowerShellAsync()`、`CMD()`(同期)、`PowerShell()`(同期) | CMD または PowerShell コマンドの実行。常に非同期バリアントを使用する。`revertCommand` パラメータで元に戻すコマンドを指定可能。 |
-| **`ScheduledTaskService`** | `DisableTask()`、`EnableTask()`、`IsTaskEnabled()`、`DeleteTask()` | Windows スケジュールタスクの管理。 |
-| **`ServiceProcessService`** | `ChangeServiceStartupTypeAsync()`、`GetStartupTypeAsync()` | Windows サービスの管理。常に非同期バリアントを使用する。複数のサービスを一度に変更可能。 |
+| **`RegistryService`** | `Write()`、`Read<T>()`、`DeleteValue()`、`CreateSubKey()`、`DeleteSubKeyTree()`、`KeyExists()`、`CleanupEmptyKeys()` | レジストリキーの読み書き/削除。リバート用に元の値をバックアップ。params 配列でバッチ書き込み可能。 |
+| **`ShellService`** | `CMDAsync()`、`PowerShellAsync()`、`CMD()`(同期)、`PowerShell()`(同期) | CMD / PowerShell コマンドの実行。非同期版を推奨。元に戻すコマンドを `revertCommand` で指定可能。非標準終了コードは `ShellPolicy` を参照。 |
+| **`ScheduledTaskService`** | `DisableTask()`、`EnableTask()`、`IsTaskEnabled()`、`DeleteTask()`、`GetAllTasks()`、`RegisterTask()`、`RunTask()`、`StopTask()` | Windows スケジュールタスクの管理。 |
+| **`ServiceProcessService`** | `ChangeServiceStartupTypeAsync()`、`GetStartupTypeAsync()` | Windows サービスの管理。常に非同期版を使用。params 配列でバッチ変更可能。 |
+
+> **params 配列で複数アイテムを受け付けるメソッド**:ほとんどの書き込み/変更メソッドは params 配列を受け付けます(例:`RegistryService.Write(item1, item2, item3)`)。個別呼び出しより効率的です。
使用例:
```csharp
-// Sync registry writes — multiple items at once
+// 同期レジストリ書き込み — 複数アイテムを一度に
RegistryService.Write(
new RegistryItem(@"HKLM\...", "Value1", 1),
new RegistryItem(@"HKLM\...", "Value2", 0)
);
RegistryService.DeleteValue(new RegistryItem(@"HKCU\...", "OldValue"));
-// Async service changes — multiple services at once
+// 非同期サービス変更 — 複数サービスを一度に
await ServiceProcessService.ChangeServiceStartupTypeAsync(
new ServiceItem("DiagTrack", ServiceStartupType.Disabled),
new ServiceItem("dmwappushservice", ServiceStartupType.Disabled)
);
-// Async shell commands with revert command
+// リバートコマンド付きの非同期シェルコマンド
var result = await ShellService.CMDAsync(
"powercfg /h off",
- "powercfg /h on" // revert command stored for undo
+ "powercfg /h on" // 元に戻すコマンドを保存
);
-// Async PowerShell
+// 非同期 PowerShell
var usbStates = await ShellService.PowerShellAsync(
"Get-CimInstance -Namespace root\\wmi -ClassName MSPower_DeviceEnable"
);
```
-<h3 id="new-category-and-helper-class">新しいカテゴリとヘルパーベースクラスの作成</h3>
+<h3 id="handling-async">非同期操作の扱い</h3>
+
+すべての最適化が `async`/`await` を必要とするわけではありません。同期レジストリ書き込みのみ(非同期呼び出しなし)の場合は `Task.FromResult()` を返せます:
+
+```csharp
+public override Task<ApplyResult> ApplyAsync(
+ IProgress<ProcessingProgress> progress,
+ OptimizationContext context)
+{
+ RegistryService.Write(new RegistryItem(@"HKLM\...", "Value", 1));
+ context.Logger.LogInformation("Applied tweak");
+ return Task.FromResult(CompleteFromScope());
+}
+```
+
+ただし、非同期プロバイダー(サービス、シェル、タスク)を使う場合は常に `await` します:
+
+```csharp
+public override async Task<ApplyResult> ApplyAsync(...)
+{
+ await ServiceProcessService.ChangeServiceStartupTypeAsync(...);
+ return CompleteFromScope();
+}
+```
+
+<h3 id="new-category">新しいカテゴリの作成</h3>
-最適化が既存のカテゴリに当てはまらない場合のみ。過度に細かいカテゴリは避けてください。
+既存カテゴリに当てはまらない場合のみ。過度に細かいカテゴリは避けてください。
-1. `Domain/Optimizations/Categories/YourCategory.cs` を作成する
-2. `IOptimizationCategory` を実装する
-3. `[OptimizationCategory(PageType = typeof(YourPage))]` を適用する — XAML ページも必要です
-4. `Domain/UI/OptimizationCategoryOrder.cs` の `OptimizationCategoryOrder` 列挙型にメンバーを追加する
-5. XAML ページは `App.xaml.cs` の `services.AddAllOptimizationPages()` 経由で自動登録される
+1. `Domain/Optimizations/Categories/YourCategory.cs` を作成します。
+2. `IOptimizationCategory` を実装します。
+3. `[OptimizationCategory(typeof(YourPage))]` を適用します — XAML ページも必要です([新機能の構築](#building-new-features) を参照)。
+4. `Domain/UI/OptimizationCategoryOrder.cs` の `OptimizationCategoryOrder` 列挙型にメンバーを追加し、並び順を整えます。
+5. XAML ページは `App.xaml.cs` の `services.AddAllOptimizationPages()` で自動登録されます。
-複数の最適化が同じ構造を共有する場合(例:GPU ツイーク)、抽象中間クラスを作成します:
+<h3 id="helper-base-class">最適化ヘルパーベースクラスの作成</h3>
+
+複数の最適化が同じ構造を共有する場合(検出された GPU を反復する GPU ツイークなど)、抽象中間クラスを作成します:
```csharp
public abstract class GpuRegistryOptimization : BaseOptimization
@@ -347,6 +424,8 @@ public abstract class GpuRegistryOptimization : BaseOptimization
}
```
+AMD、NVIDIA、Intel のサブクラスを使った実例は `Domain/Optimizations/Categories/Gpu.cs` を参照してください。
+
<h3 id="localization-keys-optimization">ローカライズキー</h3>
すべての最適化には `Translations.resx` へのエントリが必要です。キーは厳格な規則に従います:
@@ -361,7 +440,7 @@ Optimizer.{CategoryName}.{OptimizationKey}.Error.{CustomKey}
`CategoryName` = カテゴリクラス名(例:`Performance`)、`OptimizationKey` = ネストされたクラス名。
> [!IMPORTANT]
-> **翻訳は必須です**。これらのキーを追加し忘れると、アプリは `"Optimizer.Performance.MyNewTweak.Name"` のような生のキー文字列を表示します。最低限 `Translations.resx`(英語)にエントリを追加してください。
+> **翻訳は必須です**。キーを追加し忘れると、アプリは `"Optimizer.Performance.MyNewTweak.Name"` のような生のキー文字列を表示します。最低限 `Translations.resx`(英語)にエントリを追加してください。
---
@@ -371,12 +450,16 @@ Optimizer.{CategoryName}.{OptimizationKey}.Error.{CustomKey}
<h3 id="customize-categories">カスタマイズカテゴリ</h3>
-| ファイル | 属性 | 対象 |
-|---|---|---|
-| `Desktop.cs` | `[CustomizeCategory(PageType = typeof(DesktopFeatureCategory))]` | デスクトップアイコン(PC、ごみ箱、ネットワーク、ユーザーファイル)、ショートカットオーバーレイ |
-| `Preferences.cs` | `[CustomizeCategory(PageType = typeof(PreferencesFeatureCategory))]` | タスクバーの配置、ウィジェット、ダークモード、ファイル拡張子、隠しファイル、クリップボード履歴、検索モード、秒表示、Bing 検索、クラシックコンテキストメニュー |
-| `Gaming.cs` | `[CustomizeCategory(PageType = typeof(GamingFeatureCategory))]` | ゲームモード、ゲームバー、バックグラウンド録画、マウス加速度、フルスクリーン最適化、GPU スケジューリング |
-| `SystemFeatures.cs` | `[CustomizeCategory(PageType = typeof(SystemFeatureCategory))]` | 起動時の Num Lock、開発者モード、LongPaths、バッテリー残量表示 |
+カテゴリは `Domain/Customize/Categories/` にファイル単位で配置されています — 正確な一覧はそのフォルダを確認してください。執筆時点:
+
+| ファイル | 対象 |
+|---|---|
+| `Desktop.cs` | デスクトップアイコン(PC、ごみ箱、ネットワーク、ユーザーファイル、コントロールパネル)、全体の表示/非表示、ショートカット矢印の表示 |
+| `Preferences.cs` | タスクバー配置、ウィジェット、タスクビュー、タスク終了、ダークモード、ファイル拡張子、隠しファイル、クリップボード履歴、検索モード、秒表示、Bing 検索、クラシックコンテキストメニュー |
+| `Gaming.cs` | ゲームモード、ゲームバー、バックグラウンド録画、マウス加速度、フルスクリーン最適化、GPU スケジューリング |
+| `SystemFeatures.cs` | 起動時の Num Lock、開発者モード、長いパス、バッテリー残量表示 |
+
+各カテゴリクラスは `[CustomizeCategory(PageType = typeof(SomePage))]` 属性で UI ページと紐づけられています。
<h3 id="step-by-step-simple-registry-toggle">ステップバイステップ:シンプルなレジストリトグル</h3>
@@ -386,9 +469,10 @@ Optimizer.{CategoryName}.{OptimizationKey}.Error.{CustomKey}
private enum Sections { Taskbar, Widgets, Advanced }
[CustomizeSetting(
- Section = nameof(Sections.Taskbar), // Groups settings in the UI
- Icon = SymbolRegular.AlignCenter24, // From Wpf.Ui.Controls.SymbolRegular
- Recommendation = RecommendationState.On // On / Off / Depends / Experimental / None
+ Section = nameof(Sections.Taskbar), // UI で設定をグループ化
+ Icon = SymbolRegular.AlignCenter24, // Wpf.Ui.Controls.SymbolRegular から
+ Recommendation = RecommendationState.On, // On / Off / Depends / Experimental / None
+ Condition = typeof(Windows11Condition) // 任意の互換性条件
)]
public class TaskbarAlignment : BaseCustomizeSetting
{
@@ -398,13 +482,13 @@ public class TaskbarAlignment : BaseCustomizeSetting
{
Path = @"HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced",
Name = "TaskbarAl",
- OnValue = 0, // value when toggle is ON
- OffValue = 1, // value when toggle is OFF
- DefaultValue = 1, // value = default state (used when key missing)
+ OnValues = [0], // ON のときの値(複数可)
+ OffValues = [1], // OFF のときの値(複数可)
+ DefaultValue = 1, // デフォルト状態の値(キー欠落時に使用)
},
];
- // Declare what needs refreshing after this setting changes
+ // 変更後にリフレッシュが必要な対象を宣言
protected override CustomizeRefreshScope RefreshScope =>
CustomizeRefreshScope.TaskbarSettings;
}
@@ -416,62 +500,99 @@ public class TaskbarAlignment : BaseCustomizeSetting
|---|---|---|---|
| `Path` | `string` | 必須 | レジストリキーの完全パス(例:`@"HKCU\Software\..."`) |
| `Name` | `string` | 必須 | レジストリ値の名前 |
-| `OnValue` | `object?` | `1` | 「オン」状態を表す値 |
-| `OffValue` | `object?` | `0` | 「オフ」状態を表す値 |
-| `DefaultValue` | `object?` | `0` | レジストリ値が存在しない場合のフォールバック |
-| `IsOptional` | `bool` | `false` | `true` の場合、状態検出に不要 |
-| `TreatMissingAsDefault` | `bool` | `false` | `true` の場合、キーが存在しないときは「オフ」ではなく `DefaultValue` を使用 |
-| `ValueKind` | `RegistryValueKind` | `DWord` | レジストリ値の型(DWord、String など) |
+| `OnValues` | `IReadOnlyList<object?>` | `[1]` | 「オン」状態を表す値のリスト。`null` は「キー不在 = オン」。 |
+| `OffValues` | `IReadOnlyList<object?>` | `[0]` | 「オフ」状態を表す値のリスト。`null` は「キー不在 = オフ」。 |
+| `DefaultValue` | `object?` | `0` | キー欠落時のデフォルト状態値(デフォルトへのリセットに使用)。 |
+| `IsOptional` | `bool` | `false` | `true` の場合、状態検出に不要。 |
+| `ValueKind` | `RegistryValueKind` | `DWord` | レジストリ値の型(DWord、String など)。 |
+
+**状態検出ロジック**:`GetState()`(`BaseCustomizeSetting` 内)は非オプションの `RegistryToggles` をすべて集め、**すべて**の必須トグルが `OnValues` のいずれかに一致する場合のみ `true` を返します。
<h3 id="control-types">コントロールタイプ</h3>
| 型 | 表示形式 | 用途 |
|---|---|---|
| `Toggle` | ON/OFF スイッチ | ほとんどの設定(デフォルト) |
-| `Dropdown` | コンボボックス | 複数選択(例:電源プラン、検索ボックスモード) |
+| `Dropdown` | コンボボックス | 複数選択(例:電源プラン、検索ボックスモード、タスクバー配置) |
| `Option` | ラジオボタングループ | 排他的な視覚オプション(例:左/中央揃え) |
| `NumberInt` | 整数テキスト入力 | 数値(例:秒数) |
| `NumberFloat` | 小数テキスト入力 | 精度の高い値 |
| `String` | テキスト入力 | 自由形式のテキスト |
-<h3 id="dropdown-with-options">オプション付きドロップダウン</h3>
+UI コントロールを変更するには `ControlType` をオーバーライドします:
```csharp
public override CustomizeControlType ControlType => CustomizeControlType.Dropdown;
+```
-public override IReadOnlyList<SettingOption>? Options =>
- [
- Option("Never", 0), // Option() helper reads from Translations.resx
- Option("Battery", 1),
- Option("Always", 2),
- ];
+<h3 id="dropdown-with-options">オプション付きドロップダウン</h3>
-public override async Task ApplyAsync(object? value)
+ドロップダウンのオプションは `RegistryBinding` を宣言するため、基底クラスが現在値の自動読み取りと選択時の自動書き込みを行えます。`Option()` ヘルパーを使用します:
+
+```csharp
+[CustomizeSetting(Section = nameof(Sections.Taskbar), Icon = SymbolRegular.AlignCenter24)]
+public class TaskbarAlignment : BaseCustomizeSetting
{
- var intValue = value is int i ? i : 0;
- RegistryService.Write(new RegistryItem(Path, "ValueName", intValue));
- await ExecutePostActionAsync(); // MUST call when overriding ApplyAsync
+ private const string RegPath =
+ @"HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced";
+ private const string RegName = "TaskbarAl";
+
+ public override CustomizeControlType ControlType => CustomizeControlType.Dropdown;
+
+ // Option(key, regPath, regName, value) はラベルを
+ // Customize.{Category}.{Feature}.Options.{key} から読み取る
+ protected override IReadOnlyList<SettingOption>? GetOptions() =>
+ [Option("Center", RegPath, RegName, 1), Option("Left", RegPath, RegName, 0)];
+
+ protected override CustomizeRefreshScope RefreshScope =>
+ CustomizeRefreshScope.TaskbarSettings;
}
```
+**複数**のレジストリ値に触れるオプションでは、明示的なバインディングを渡します:
+
+```csharp
+protected override IReadOnlyList<SettingOption>? GetOptions() =>
+[
+ Option("On", 1,
+ new RegistryBinding(@"HKCU\...\Key1", "ValueA", 1),
+ new RegistryBinding(@"HKCU\...\Key2", "ValueB", "enabled", RegistryValueKind.String)),
+ Option("Off", 0,
+ new RegistryBinding(@"HKCU\...\Key1", "ValueA", 0),
+ new RegistryBinding(@"HKCU\...\Key2", "ValueB", "disabled", RegistryValueKind.String)),
+];
+```
+
+基底クラスはバインディングから現在値を読み取り、ライブ値がどの宣言オプションにも一致しない場合はメモリ上だけの **「カスタム」**(または **「未設定」**)フォールバックを表示し、選択されたオプションのすべてのバインディングを書き込みます。一般的なケースではカスタムの `ApplyAsync` は不要です。
+
<h3 id="dynamic-options">動的オプション(プラットフォーム対応)</h3>
Windows バージョンに応じてオプションを条件付きで表示できます:
```csharp
-public override IReadOnlyList<SettingOption>? Options
+protected override IReadOnlyList<SettingOption>? GetOptions()
{
- get
- {
- if (Shared.IsWindows11OrGreater)
- return [Option("Hidden", 0), Option("Icon", 1), Option("IconAndLabel", 2), Option("SearchBox", 3)];
- return [Option("Hidden", 0), Option("Icon", 1), Option("SearchBox", 2)];
- }
+ if (Shared.IsWindows11OrGreater)
+ return
+ [
+ Option("Hidden", RegPath, RegName, 0),
+ Option("Icon", RegPath, RegName, 1),
+ Option("IconAndLabel", RegPath, RegName, 2),
+ Option("SearchBox", RegPath, RegName, 3),
+ ];
+ return
+ [
+ Option("Hidden", RegPath, RegName, 0),
+ Option("Icon", RegPath, RegName, 1),
+ Option("SearchBox", RegPath, RegName, 2),
+ ];
}
```
<h3 id="custom-logic-override">カスタムロジック(GetStateAsync / ApplyAsync のオーバーライド)</h3>
+シンプルなレジストリトグルでない設定(マウス加速度が 3 つのレジストリ値を組み合わせるなど)の場合:
+
```csharp
[CustomizeSetting(
Section = nameof(Sections.Input),
@@ -482,6 +603,7 @@ public class MouseAcceleration : BaseCustomizeSetting
{
private const string Path = @"HKCU\Control Panel\Mouse";
+ // 監視パスにより外部変更時に UI が自動リフレッシュされる
protected override IReadOnlyList<string> GetWatchedRegistryPaths() => [Path];
public override Task<bool> GetStateAsync()
@@ -503,92 +625,226 @@ public class MouseAcceleration : BaseCustomizeSetting
RegistryService.Write(new RegistryItem(Path, "MouseSpeed", isOn ? "1" : "0"));
RegistryService.Write(new RegistryItem(Path, "MouseThreshold1", isOn ? "6" : "0"));
RegistryService.Write(new RegistryItem(Path, "MouseThreshold2", isOn ? "10" : "0"));
- await ExecutePostActionAsync(); // MUST call when overriding ApplyAsync
+
+ if (NeedsPostAction)
+ await ExecutePostActionAsync();
}
protected override CustomizeRefreshScope RefreshScope => CustomizeRefreshScope.Default;
}
```
-<h3 id="recommendation-system">レコメンデーションシステム</h3>
+> `ApplyAsync` をオーバーライドする場合、**必ず** `await ExecutePostActionAsync()` を自分で呼び出してください(`NeedsPostAction` でガード)。基底クラスが自動的に行うのは、デフォルトの `RegistryToggles` ベースとドロップダウンバインディングベースの適用経路のみです。
-各カスタマイズ設定はレコメンデーションを宣言できます:
+<h3 id="state-detection-retry">リトライ付きの状態検出</h3>
+
+値の適用後、UI は `GetStateWithRetryAsync()`(`GetStateAsync()` ではありません)を呼び出します。このメソッドは:
+
+1. 状態を `maxRetries`(デフォルト 3)回、`delayMs`(デフォルト 80ms)間隔で読み取ります。
+2. 連続する 2 回の読み取りが同じ値で一致したら(収束チェック)返します。
+3. リトライを使い切ったら最後の読み取り値にフォールバックします。
+
+これにより、書き込み後にレジストリが落ち着くまでの間、UI が古い値を表示するのを防ぎます。
+
+<h3 id="non-registry-deps">非レジストリ依存のカスタムロジック</h3>
+
+埋め込みリソースの抽出を伴う設定(ショートカット矢印を空白アイコンに置き換えるなど)の場合:
```csharp
-[CustomizeSetting(..., Recommendation = RecommendationState.On)]
-// Available: On, Off, Depends, Experimental, None
+public override async Task ApplyAsync(object? value)
+{
+ var isOn = value is bool b && b;
+ if (isOn)
+ {
+ RegistryService.DeleteValue(new RegistryItem(Path, "29"));
+ }
+ else
+ {
+ var outputPath = Path.Combine(Shared.AssetsDirectory, nameof(Desktop), "blank.ico");
+ EmbeddedResourceHelper.TryExtract("Icons.blank.ico", outputPath);
+ RegistryService.Write(new RegistryItem(Path, "29", outputPath));
+ }
+ await ExecutePostActionAsync();
+}
```
-レコメンデーションの理由はローカライズキーで追加:`Customize.{Category}.{Feature}.Recommendation.Reason`
+埋め込みリソースをアセンブリからディスクに抽出するには `EmbeddedResourceHelper.TryExtract(resourceName, outputPath)` を使用します。
-<h3 id="embedded-resource-extraction">埋め込みリソースの抽出</h3>
+<h3 id="recommendation-system">レコメンデーションシステム</h3>
-設定によってはアセンブリから埋め込みリソースを抽出する必要があります:
+各カスタマイズ設定はレコメンデーションを宣言できます:
```csharp
-var outputPath = Path.Combine(Shared.AssetsDirectory, nameof(Desktop), "blank.ico");
-EmbeddedResourceHelper.TryExtract("Icons.blank.ico", outputPath);
-RegistryService.Write(new RegistryItem(Path, "29", outputPath));
+[CustomizeSetting(..., Recommendation = RecommendationState.On)]
+// 利用可能: On, Off, Depends, Experimental, None
```
+- **`On`**: オン推奨 — システム改善
+- **`Off`**: オフ推奨 — システム改善
+- **`Depends`**: ユーザーのニーズ/構成に依存
+- **`Experimental`**: 不安定な可能性、注意して使用
+- **`None`**(デフォルト): レコメンデーション非表示
+
+理由はローカライズキーで追加できます:`Customize.{Category}.{Feature}.Recommendation.Reason`。
+
<h3 id="what-to-override-per-pattern">パターンごとのオーバーライド</h3>
| シナリオ | オーバーライド |
|---|---|
| シンプルなレジストリトグル | `RegistryToggles` + `RefreshScope` |
-| 複数のレジストリトグル | `RegistryToggles`(すべてリストする) |
-| ドロップダウン/オプション | `ControlType` → `Dropdown`、`Options`、カスタム `ApplyAsync`、`CurrentValue` |
-| 複数値ロジック | `GetStateAsync()` + `ApplyAsync()` + `GetWatchedRegistryPaths()` |
+| 複数のレジストリトグル(例:ゲームモード 2 値) | `RegistryToggles`(すべてリスト) |
+| ドロップダウン / オプション | `ControlType` → `Dropdown` + `GetOptions()` で `Option(...)` バインディング |
+| 複数値ロジック(例:マウス加速度 3 値) | `GetStateAsync()` + `ApplyAsync()` + `GetWatchedRegistryPaths()` |
| レジストリ操作のない設定 | `GetStateAsync()` + `ApplyAsync()`(完全カスタム) |
-| カスタムリフレッシュ動作 | `RefreshScope` または `ExecutePostActionAsync()` |
+| カスタムリフレッシュ動作 | `RefreshScope`(フラグのみ)または `ExecutePostActionAsync()`(完全オーバーライド) |
| 収束チェック付き状態検出 | `GetStateWithRetryAsync()`(組み込み — オーバーライド不要) |
-| Windows バージョンごとの動的オプション | `Options` ゲッターを条件付きでオーバーライド |
-| 埋め込みリソース抽出 | `EmbeddedResourceHelper.TryExtract()` |
+| Windows バージョンごとの動的オプション | `GetOptions()` を条件付きでオーバーライド |
+| 埋め込みリソース抽出 | カスタム `ApplyAsync` で `EmbeddedResourceHelper.TryExtract()` |
+| 互換性ゲート | `[CustomizeSetting]` 属性の `Condition = typeof(...)` |
<h3 id="create-a-new-customize-category">新しいカテゴリの作成</h3>
-1. `Domain/Customize/Categories/YourCategory.cs` を作成する
-2. `[CustomizeCategory(PageType = typeof(YourPage))]` 付きで `ICustomizeCategory` を実装する
-3. `Domain/UI/CustomizeOrder.cs` の `CustomizeOrder` 列挙型にメンバーを追加する
-4. XAML ページを作成する(`UI/Pages/Customize/Categories/` に新しいクラス)
-5. ページは `App.xaml.cs` の `services.AddAllCustomizeCategoryPages()` 経由で自動登録される
+1. `Domain/Customize/Categories/YourCategory.cs` を作成します。
+2. `[CustomizeCategory(PageType = typeof(YourPage))]` 付きで `ICustomizeCategory` を実装します。
+3. `Domain/UI/CustomizeOrder.cs` の `CustomizeOrder` 列挙型にメンバーを追加します。
+4. XAML ページを作成します(`UI/Pages/Customize/Categories/` に新しいクラス)。
+5. ページは `App.xaml.cs` の `services.AddAllCustomizeCategoryPages()` で自動登録されます。
<h3 id="localization-keys-customize">カスタマイズ設定のローカライズキー</h3>
```
Customize.{CategoryName}.{SettingKey}.Name
Customize.{CategoryName}.{SettingKey}.Description
-Customize.{CategoryName}.{SettingKey}.Options.{OptionKey} (if using SettingOption)
-Customize.{CategoryName}.{SettingKey}.Recommendation.Reason (if Recommendation != None)
-Customize.{CategoryName}.Section.{SectionName} (for section headers)
+Customize.{CategoryName}.{SettingKey}.Options.{OptionKey} (SettingOption 使用時)
+Customize.{CategoryName}.{SettingKey}.Recommendation.Reason (Recommendation != None のとき)
+Customize.{CategoryName}.Section.{SectionName} (セクションヘッダー用)
```
---
+<h1 id="the-condition-system">条件システム</h1>
+
+条件を使うと、最適化やカスタマイズ設定を互換性チェックでゲートし、「お使いのシステムではサポートされていません」と UI に表示できます。動作しないものを適用する代わりになります。
+
+<h3 id="core-concepts">中核概念</h3>
+
+条件は `Domain/Conditions/` にあり、`Services/Conditions/` の静的 `ConditionEvaluator` が評価します。
+
+| 要素 | 目的 |
+|---|---|
+| `ICondition` | コントラクト: `ConditionResult Evaluate(SystemSnapshot snapshot)`。実装には public のパラメータなしコンストラクタが必要(リフレクションでインスタンス化されるため)。 |
+| `ConditionBase` | 共通ヘルパーを持つ任意の基底クラス(例:OS ビルド番号解析の `TryGetOsBuild`)。 |
+| `ConditionResult` | 結果: `Available`、`Unsupported(title, description)`、または `Error()`。ローカライズテキストはプロバイダー経由で遅延解決。 |
+| `ConditionState` | `Available`、`Unsupported`、`Error`。 |
+| `ConditionValidation` | 検出時に `Condition = typeof(...)` メタデータを検証し、設定ミスを起動時に早期検出。 |
+| `WindowsBuilds` | OS ビルド番号の定数(例:`Windows11`、`Windows11_24H2`)。 |
+
+**フェイルオープンの原則**:アイテムをブロックするのは `Unsupported` のみで、それも未適用(またはユーザーが非表示にしていない)の場合だけです。`Error` や未取得のスナップショットがアイテムを隠すことはありません — 不完全なハードウェア検出が利用可能な選択肢を奪ってはなりません。
+
+<h3 id="declaring-a-condition">条件の宣言</h3>
+
+両方の属性が任意の `Condition` を受け付けます:
+
+```csharp
+// 最適化
+[Optimization(Id = "...", Risk = OptimizationRisk.Safe,
+ Tags = OptimizationTags.Privacy | OptimizationTags.System,
+ Condition = typeof(Windows11_24H2OrGreaterCondition))]
+public class DisableRecall : BaseOptimization { ... }
+
+// カスタマイズ設定
+[CustomizeSetting(Section = ..., Icon = SymbolRegular.Grid24,
+ Condition = typeof(Windows11Condition))]
+public class TaskbarWidgets : BaseCustomizeSetting { ... }
+```
+
+<h3 id="built-in-conditions">組み込み条件</h3>
+
+既製の条件は `Domain/Conditions/BuiltIn/` にあります — 完全で最新の一覧はそのフォルダを確認してください。例:
+
+| 条件 | 一致対象 |
+|---|---|
+| `Windows10Condition` / `Windows11Condition` | ビルド番号による OS バージョン |
+| `Windows11_24H2OrGreaterCondition` | Windows 11 24H2(ビルド 26100)以降 |
+| `CpuBrandCondition` / `GpuBrandCondition` | CPU/GPU ベンダー(Intel、AMD、NVIDIA) |
+| `MinimumRamCondition`(基底)/ `SixteenGbRamCondition` | 最小搭載 RAM |
+| `RegistryKeyExistsCondition` | レジストリキーの存在 |
+| `ServiceExistsCondition` | Windows サービスの存在 |
+| `RecallInstalledCondition` | Windows Recall の存在 |
+
+<h3 id="writing-a-custom-condition">カスタム条件の作成</h3>
+
+```csharp
+public sealed class MyCondition : ConditionBase
+{
+ public override ConditionResult Evaluate(SystemSnapshot snapshot)
+ {
+ // ConditionBase.TryGetOsBuild は "22631.xxxx" を 22631 に解析
+ if (TryGetOsBuild(snapshot, out var build) && build >= 22000)
+ return ConditionResult.Available;
+
+ return ConditionResult.Unsupported(
+ () => Loc.Instance["Condition.MyCondition.Title"],
+ () => Loc.Instance["Condition.MyCondition.Description"]);
+ }
+}
+```
+
+ガイドライン:
+
+- システムが通過したら **`Available`** を、そうでなければ **`Unsupported(title, description)`** を返します。
+- 予期しない失敗には `ConditionResult.Error()` を使う(または throw — `ConditionEvaluator` がキャッチして `Error` に変換)。エラーはブロックしません。
+- ユーザー向けテキストはローカライズプロバイダー(`() => Loc.Instance[...]`)の後ろに置き、読み取り時に現在のカルチャが反映されるようにします。
+- クラスに **public のパラメータなしコンストラクタ**を与えます(追加しないか、明示的な空コンストラクタを追加)。
+
+<h3 id="how-conditions-evaluated">評価の仕組み</h3>
+
+1. 検出処理が `ConditionValidation.Validate(...)` を呼び、宣言された型が `ICondition` を実装し構築可能であることを確認します。
+2. UI は `ConditionEvaluator.Evaluate(conditionType, snapshot, logger)` を呼び出します。条件インスタンスをキャッシュし、決して例外を投げません。
+3. `Unsupported` のアイテムはブロック/非対応状態で表示されます(ユーザーはセッション中だけ非表示にできます)。適用済みのアイテムが再ブロックされることはありません。
+
+---
+
<h1 id="the-refresh-scope-system">リフレッシュスコープシステム</h1>
+カスタマイズ設定が状態を変更すると、Windows の各サーフェスごとに異なるリフレッシュ戦略が必要です。`CustomizeRefreshScope` の `[Flags]` 列挙型がこれを細かく制御します。
+
<h3 id="available-flags">利用可能なフラグ</h3>
| メンバー | 値 | 効果 | P/Invoke |
|---|---|---|---|
| `None` | `0` | リフレッシュなし | — |
| `Settings` | `1 << 0` | `WM_SETTINGCHANGE` をブロードキャスト | `SendMessageTimeout(HWND_BROADCAST, WM_SETTINGCHANGE)` |
-| `Associations` | `1 << 1` | ファイル関連付け変更をシェルに通知 | `SHChangeNotify(SHCNE_ASSOCCHANGED)` |
-| `Desktop` | `1 << 2` | デスクトップアイコンリストの再描画を強制 | `LVM_REFRESH` + `LVM_UPDATE` |
-| `Taskbar` | `1 << 3` | タスクバー向け `WM_SETTINGCHANGE` | `SendMessageTimeout(HWND_BROADCAST, WM_SETTINGCHANGE, "TraySettings")` |
-| `PolicyUpdate` | `1 << 4` | `SystemParametersInfo` をプッシュ | `SystemParametersInfo(SPI_SETDESKWALLPAPER)` |
+| `Associations` | `1 << 1` | ファイル関連付け/アイコンキャッシュの変更をシェルに通知 | `SHChangeNotify(SHCNE_ASSOCCHANGED)` |
+| `Desktop` | `1 << 2` | デスクトップアイコンリスト(`SysListView32`)の再描画を強制 | `LVM_REFRESH` + `LVM_UPDATE` |
+| `Taskbar` | `1 << 3` | タスクバー向け `WM_SETTINGCHANGE`("TraySettings")をブロードキャスト | `SendMessageTimeout(HWND_BROADCAST, WM_SETTINGCHANGE, "TraySettings")` |
+| `PolicyUpdate` | `1 << 4` | ユーザー単位パラメータのため `SPIF_SENDCHANGE` 付き `SystemParametersInfo` をプッシュ | `SystemParametersInfo` |
| `Theme` | `1 << 5` | `WM_THEMECHANGED` をブロードキャスト | `SendMessageTimeout(HWND_BROADCAST, WM_THEMECHANGED)` |
-| `DesktopIconCache` | `1 << 6` | HideIcons レジストリ + `WM_COMMAND 0x7402` | Registry read + `SendMessage(Progman, WM_COMMAND)` |
+| `DesktopIconCache` | `1 << 6` | HideIcons レジストリの切り替え + `WM_COMMAND 0x7402` をデスクトップへ送信 | レジストリ読み取り + `SendMessage(Progman, WM_COMMAND)` |
<h3 id="named-composites">名前付きコンポジット</h3>
| 名前 | 構成 | 使用例 |
|---|---|---|
| `Default` | `Settings \| Associations` | 一般的なエクスプローラーレベルの設定 |
-| `DesktopIcons` | `Settings \| Desktop` | 個別のデスクトップアイコンの表示/非表示 |
+| `DesktopIcons` | `Settings \| Desktop` | 個別デスクトップアイコンの表示/非表示 |
| `HideDesktopIcons` | `Settings \| DesktopIconCache` | 「すべてのデスクトップアイコンを非表示」トグル |
-| `TaskbarSettings` | `Settings \| Taskbar` | タスクバー設定 |
-| `ExplorerView` | `Settings \| Associations \| PolicyUpdate` | ファイル拡張子、隠しファイル |
+| `TaskbarSettings` | `Settings \| Taskbar` | タスクバー配置、ウィジェット、タスクビュー、タスク終了 |
+| `ExplorerView` | `Settings \| Associations \| PolicyUpdate` | ファイル拡張子、隠しファイル、コンパクトビュー |
+
+<h3 id="how-refresh-flows">リフレッシュの流れ</h3>
+
+```
+設定トグル → BaseCustomizeSetting.ApplyAsync(value)
+ ├─ RegistryToggles を書き込み(あれば)、または選択オプションのバインディングを適用
+ ├─ NeedsPostAction を確認(RefreshScope != None なら true)
+ └─ Task.Run → ExecutePostActionAsync()
+ ├─ 各 CustomizeRefreshScope フラグを確認
+ ├─ SystemRefreshService のメソッド(P/Invoke)を呼び出し
+ └─ Win32 通知を Windows へ送信
+```
+
+`ApplyAsync` をオーバーライドする場合、**必ず** `await ExecutePostActionAsync()` を自分で呼び出してください(上記の例を参照)。基底クラスが自動的に行うのは、デフォルトの `RegistryToggles` ベースとドロップダウンバインディングベースの適用のみです。
---
@@ -596,15 +852,65 @@ Customize.{CategoryName}.Section.{SectionName} (for section heade
新しいページやツール(例:「ネットワークモニター」)を追加する場合:
-1. **まず GitHub Issue を作成する** — 機能、ユースケース、設計を説明する。
-2. **実装順序**:Service → ViewModel → XAML Page → App.xaml.cs に登録
+1. **まず GitHub Issue を作成する** — 機能、ユースケース、設計を説明し、メンテナのフィードバックを待ちます。
+2. **実装順序**:
```csharp
-// DI Registration Pattern (from App.xaml.cs)
+// 1. サービス層: Services/UI または Services/System/YourService.cs
+public class YourService(ILogger<YourService> logger) { ... }
+
+// 2. ViewModel: UI/ViewModels/Pages/YourViewModel.cs
+// ViewModel(ObservableValidator + INavigationAware を継承)を拡張
+
+// 3. XAML ページ: UI/Pages/YourPage.xaml(+ コードビハインド)
+
+// 4. App.xaml.cs にシングルトン登録
services.AddSingleton<YourViewModel>();
services.AddSingleton<YourPage>();
+```
+
+- ViewModel とページは `App.xaml.cs` に**シングルトンとして登録する必要があります**。
+- ナビゲーションは WPF UI(`INavigationService`)が処理します。
+- 既存のパターンに従ってください — `DashboardPage`、`OptimizePage`、`BloatwarePage`、`DiskCleanupPage`、`ScheduledTasksPage`、`StartupManagerPage` などを参照。
+
+<h3 id="di-registration-pattern">DI 登録パターン(App.xaml.cs より)</h3>
+
+```csharp
+// ページ + ViewModel — 機能ごとに 1 ペア
+services.AddSingleton<DashboardViewModel>();
+services.AddSingleton<DashboardPage>();
+
+services.AddSingleton<OptimizeViewModel>();
+services.AddSingleton<OptimizePage>();
+
+services.AddSingleton<SettingsViewModel>();
+services.AddSingleton<SettingsPage>();
+
+services.AddSingleton<BloatwareViewModel>();
+services.AddSingleton<BloatwarePage>();
+
+services.AddSingleton<DiskCleanupViewModel>();
+services.AddSingleton<DiskCleanupPage>();
+
+services.AddSingleton<StartupManagerViewModel>();
+services.AddSingleton<StartupManagerPage>();
+
+services.AddSingleton<ScheduledTasksViewModel>();
+services.AddSingleton<ScheduledTasksPage>();
+
+// Customize
+services.AddSingleton<CustomizeViewModel>();
+services.AddSingleton<CustomizePage>();
+
+// 自動ページ登録(リフレクションによるカテゴリページ)
+services.AddAllCustomizeCategoryPages(); // [CustomizeCategory] 属性をスキャン
+services.AddAllOptimizationPages(); // [OptimizationCategory] 属性をスキャン
+
+// マネージャー
services.AddSingleton<ConfigManager>();
services.AddSingleton<RevertManager>();
+
+// サービス
services.AddSingleton<OptimizationRegistry>();
services.AddSingleton<CustomizeRegistry>();
services.AddSingleton<OptimizationService>();
@@ -617,38 +923,51 @@ services.AddSingleton<UpdaterService>();
services.AddSingleton<IRegistryWatcher, RegistryWatcher>();
```
+> これは把握のためのスナップショットです — 現在の登録は `App.xaml.cs` が正です。また、起動時の呼び出し `ShellService.Init(appOptionsMonitor)` と `WmiHelper.Initialize()` にも注意してください。
+
<h3 id="system-services">システムサービスリファレンス</h3>
| サービス | 目的 |
|---|---|
-| `SystemInfoService` | CPU、RAM、GPU 情報を含む `SystemSnapshot` を提供 |
-| `StreamService` | リモートリソースのダウンロード |
-| `UpdaterService` | GitHub リリースの更新確認 |
-| `RegistryWatcher` | レジストリキーの監視と UI 更新 |
-| `BloatwareService` | プリインストール AppX パッケージの一覧表示 |
-| `DiskCleanupService` | ディスククリーンアップのスキャン |
-| `StartupManagerService` | スタートアップアプリとタスクの管理 |
+| `SystemInfoService` | `OptimizationContext` と条件システムが使う `SystemSnapshot`(CPU、RAM、GPU、OS、ディスク)を提供。 |
+| `StreamService` | リモートリソース(更新された電源プランなど)をダウンロード。`OptimizationContext.StreamService` 経由。 |
+| `UpdaterService` | GitHub リリースの更新確認。Dashboard に更新プロンプトを表示。 |
+| `RegistryWatcher` | 外部変更を監視して UI にリフレッシュ通知。`IRegistryWatcher` を実装。 |
+| `BloatwareService` | プリインストール AppX パッケージを一覧表示し、Safe/Caution/Dangerous に分類。 |
+| `DiskCleanupService` | クリーンアップ対象(一時ファイル、キャッシュ、ログ)をスキャン。 |
+| `StartupManagerService` | スタートアップアプリとスケジュールタスクを一覧・管理。 |
+| `ConditionEvaluator` | 互換性条件を評価する静的エントリポイント([条件システム](#the-condition-system) を参照)。 |
---
<h1 id="revert-system">リバートシステム</h1>
+適用された各最適化は `%localappdata%\optimizerDuck\Revert\{optimizationId}.json` に JSON ファイルを作成します。
+
<h3 id="how-it-works-jp">仕組み</h3>
```
ApplyAsync()
│
- ├─ ExecutionScope.Begin(optimization, logger) ← creates ambient AsyncLocal scope
+ ├─ ExecutionScope.Begin(optimization, logger) ← 環境的な AsyncLocal スコープを作成
│
- ├─ RegistryService.Write(...) ← auto-records RegistryRevertStep
- ├─ ServiceProcessService.ChangeServiceStartupTypeAsync(...) ← auto-records ServiceRevertStep
- ├─ ShellService.CMDAsync(...) ← auto-records ShellRevertStep
+ ├─ RegistryService.Write(...) ← RegistryRevertStep を自動記録
+ ├─ ServiceProcessService.ChangeServiceStartupTypeAsync(...) ← ServiceRevertStep を自動記録
+ ├─ ShellService.CMDAsync(...) ← ShellRevertStep を自動記録
│
- ├─ CompleteFromScope() → ApplyResult ← derived from recorded steps
+ ├─ CompleteFromScope() → ApplyResult ← 記録されたステップから導出
│
- └─ ExecutionScope disposes → RevertManager.SaveRevertDataAsync()
+ └─ ExecutionScope 破棄 → RevertManager.SaveRevertDataAsync()
```
+<h3 id="scope-variants-jp">スコープのバリエーション</h3>
+
+| メソッド | 目的 |
+|---|---|
+| `ExecutionScope.Begin(optimization, logger)` | 実際の適用のための永続化可能なスコープを作成。 |
+| `ExecutionScope.BeginForLogging(logger)` | ログのみ — ステップは記録するがリバートデータは永続化しない。 |
+| `ExecutionScope.BeginForCapture(logger)` | リトライ用: `OptimizationId = Guid.Empty` でステップを捕捉し、後で実スコープに再割り当て。 |
+
<h3 id="step-types-jp">ステップタイプ</h3>
| ステップタイプ | 記録内容 | 自動作成元 |
@@ -659,46 +978,96 @@ ApplyAsync()
| **`ShellRevertStep`** | 元に戻すシェルコマンド | `ShellService.CMDAsync()`、`PowerShellAsync()` — `revertCommand` パラメータを渡す |
| **`UsbPowerRevertStep`** | USB 電源設定(デバイス別) | USB 関連の最適化(手動で `ExecutionScope.RecordStep()`) |
-リバートコマンドをシェル呼び出しに追加する:
+<h3 id="revert-command">シェル呼び出しへのリバートコマンド追加</h3>
+
+`CMDAsync` または `PowerShellAsync` を呼ぶとき、元に戻すために保存される `revertCommand` パラメータを任意で渡せます:
```csharp
-await ShellService.CMDAsync("powercfg /h off", "powercfg /h on"); // revertCommand
+// "powercfg /h on" がこの変更を元に戻すために保存される
+await ShellService.CMDAsync("powercfg /h off", "powercfg /h on");
+```
+
+<h3 id="revert-data-format-jp">リバートデータ形式</h3>
+
+```json
+{
+ "SchemaVersion": 1,
+ "OptimizationId": "guid",
+ "OptimizationName": "DisableTelemetry",
+ "AppliedAt": "2026-06-02T12:00:00Z",
+ "Steps": [
+ { "Index": 0, "Type": "Registry", "Data": { "..." } },
+ null, // null ギャップ = このインデックスの失敗ステップ
+ { "Index": 2, "Type": "Service", "Data": { "..." } }
+ ]
+}
```
<h3 id="key-details-jp">重要な詳細</h3>
-- **適用状態**はディスク上のファイルの存在から推論される
-- **アトミック書き込み**:`.tmp` に書き込んでから `File.Replace()`
-- **同時アクセス**:ファイルごとの `SemaphoreSlim` ロック、30秒タイムアウト
-- **リバートは逆順で実行**(最後に適用 = 最初にリバート)
-- **部分的成功**:一部のステップが失敗しても続行
-- **リトライ**:`OptimizationService.RetryFailedStepsAsync()`
-- **Upsert**:`RevertManager.UpsertRevertStepAtIndexAsync()` で特定インデックスのリバートステップを追加/置換
-- **ステップレジストリ**:`IRevertStep` を実装 + 静的な `FromData(JObject)` メソッドで自動登録
+- **適用状態**はディスク上のファイルの存在から推論されます(`RevertManager.IsAppliedAsync(id)`)。
+- **アトミック書き込み**:`.tmp` に書き込んでから `File.Replace()` — クラッシュ安全。
+- **同時アクセス**:ファイルごとの `SemaphoreSlim` ロックで競合を防止、30 秒タイムアウト。
+- **`ExecutionScope`** は `AsyncLocal<ExecutionScope?>` で環境的ステップ追跡。パラメータでコンテキストを渡す必要なし。
+- **リバートは逆順で実行**(最後に適用 = 最初にリバート)。
+- **部分成功**:一部のステップが失敗しても続行。失敗ステップにはリトライアクションが記録。
+- **リトライ**:`OptimizationService.RetryFailedStepsAsync()` が個別の失敗ステップをリトライ。`RecordStepAtIndex()` が元のインデックス配置を保持。
+- **Upsert**:`RevertManager.UpsertRevertStepAtIndexAsync()` が特定インデックスのリバートステップを追加/置換(リトライ時に使用)。
+- **ステップレジストリ**:リバートステップのデシリアライズはリフレクションベースの `_stepRegistry` — 新しいステップ型は `IRevertStep` を実装し静的な `FromData(JObject)` メソッドを持つだけで自動登録。
+
+> **重要**: プロバイダーサービス(`RegistryService.Write`、`ShellService.CMDAsync` など)を呼ぶと、リバートステップは自動記録されます。カスタムプロバイダー(`UsbPowerRevertStep` など)を実装する場合を除き、手動でリバートステップを作成**しないでください**。
---
<h1 id="testing">テスト</h1>
+テストは **xUnit v3** を使い、実 I/O による統合スタイルのアプローチを取ります。
+
<h3 id="test-patterns-jp">テストパターン</h3>
| パターン | 詳細 |
|---|---|
-| **モックライブラリなし** | すべてのテストダブルは手書きクラス |
-| **実際の I/O** | 実際のファイルシステム、レジストリ、プロセス実行 |
-| **クリーンアップ** | `try/finally` または `IDisposable` |
-| **命名** | `{Method}_{Scenario}_{ExpectedResult}` |
-| **ログ記録** | `NullLogger<T>.Instance` |
-| **STA スレッド** | WPF コンポーネントを含むテストは `RunInStaThreadAsync` ヘルパーを使用 |
+| **モックライブラリなし** | すべてのテストダブルはインターフェイスを実装する手書きクラス |
+| **実際の I/O** | 実際のファイルシステム(リバート JSON ファイル)、実際のレジストリ(`HKCU\Software\TestOptimizerDuck*`)、実際のプロセス実行(CMD、PowerShell) |
+| **クリーンアップ** | `try/finally` または `IDisposable` でテスト成果物を削除 |
+| **命名** | `{Method}_{Scenario}_{ExpectedResult}` — 例: `ApplyAsync_Success_PersistsRevertDataFile` |
+| **ログ記録** | DI ログパラメータには `NullLogger<T>.Instance` / `NullLoggerFactory.Instance` を使用 |
+| **STA スレッド** | WPF コンポーネントを含むテストは `RunInStaThreadAsync` ヘルパー(STA スレッド + `TaskCompletionSource`)を使用 |
+
+<h3 id="test-structure-jp">テスト構成</h3>
+
+```
+optimizerDuck.Test/
+├── Common/Helpers/
+├── Domain/
+│ ├── Customize/
+│ ├── Exceptions/
+│ ├── Optimizations/
+│ └── Revert/Steps/
+└── Services/
+ ├── Managers/
+ ├── OptimizationServices/
+ └── ApplyRevertComprehensiveTests.cs
+```
+
+アプリの構造を反映してください:`Services/OptimizationServices/` のテストは `Services/OptimizationServices/` に、ドメインモデルのテストは対応する `Domain/` サブディレクトリに配置します。
+
+<h3 id="running-tests-jp">テストの実行</h3>
```bash
-# Running tests
+# ビルド後
dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build
+
+# ビルド + テストを一度に
+dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release
+
+# 名前で単一テストを実行
+dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build --filter "FullyQualifiedName~TestName"
```
<h3 id="ci-integration-jp">CI 統合</h3>
-CI パイプライン(`ci.yml`)は以下のコマンドを実行します:
+CI パイプライン(`.github/workflows/ci.yml`)は以下を実行します:
```bash
dotnet restore optimizerDuck.slnx
@@ -706,6 +1075,45 @@ dotnet build optimizerDuck.slnx --configuration Release --no-restore
dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build --blame-hang --blame-hang-timeout 30s
```
+`--blame-hang --blame-hang-timeout 30s` フラグにより、テストが 30 秒以上ハングしないことを保証します。これは実 Windows サービスとやり取りする統合スタイルのテストにとって重要です。
+
+<h3 id="writing-tests-jp">プロバイダーサービスのテスト作成</h3>
+
+```csharp
+public class MyOptimizationTests
+{
+ [Fact]
+ public async Task ApplyAsync_Success_PersistsRevertDataFile()
+ {
+ var optimization = new TestOptimization
+ {
+ ApplyImpl = _ =>
+ {
+ ExecutionScope.RecordStep("Test", "Step 1", true);
+ return Task.FromResult(ApplyResult.True());
+ },
+ };
+
+ var service = CreateService();
+ var result = await service.ApplyAsync(optimization, new Progress<ProcessingProgress>());
+
+ Assert.Equal(OptimizationSuccessResult.Success, result.Status);
+ }
+
+ private static OptimizationService CreateService()
+ {
+ return new OptimizationService(
+ new RevertManager(NullLogger<RevertManager>.Instance, NullLoggerFactory.Instance),
+ NullLoggerFactory.Instance,
+ new SystemInfoService(NullLogger<SystemInfoService>.Instance),
+ new StreamService(NullLogger<StreamService>.Instance),
+ null!,
+ NullLogger<OptimizationService>.Instance
+ );
+ }
+}
+```
+
---
<h1 id="coding-standards">コーディング規約</h1>
@@ -715,45 +1123,69 @@ dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release
| 機能 | 使用 | 備考 |
|---|---|---|
| ファイルスコープ名前空間 | はい | `namespace X.Y;` |
-| コレクション式 | はい | `[]`、`[item1, item2]` |
-| プライマリコンストラクタ | 一部 | シンプルな型で使用 |
+| コレクション式 | はい | 空は `[]`、リストは `[item1, item2]` |
+| プライマリコンストラクタ | はい | サービスやシンプルな型で使用 |
| 暗黙的 using | はい | `.csproj` で有効 |
-| Null 許容参照型 | はい | `<Nullable>enable</Nullable>` |
-| 拡張メソッド(`extension(T type)`) | はい | C# 13 機能 |
+| Null 許容参照型 | はい | `<Nullable>enable</Nullable>` — null を適切に処理 |
+| 拡張メソッド(`extension(T type)`) | はい | C# 13 機能、`OptimizationTagsToDisplay` で使用 |
<h3 id="naming-conventions-jp">命名規則</h3>
| 要素 | 規則 | 例 |
|---|---|---|
-| クラス、列挙型、メソッド、プロパティ | `PascalCase` | `RegistryService` |
+| クラス、列挙型、インターフェイス、メソッド、プロパティ | `PascalCase` | `RegistryService`、`ApplyAsync` |
| プライベートフィールド | `_camelCase` | `_lastError` |
-| ローカル変数、パラメータ | `camelCase` | `progress` |
-| 非同期メソッド | `*Async` サフィックス | `ChangeServiceStartupTypeAsync` |
+| ローカル変数、パラメータ | `camelCase` | `progress`、`serviceName` |
+| 非同期メソッド | `*Async` サフィックス | `ChangeServiceStartupTypeAsync`、`CMDAsync` |
| 定数 | `PascalCase` / `_PascalCase` | `MaxRetries` / `_defaultTimeout` |
<h3 id="formatting-jp">フォーマット</h3>
| 設定 | 値 |
|---|---|
-| インデント | 4 スペース |
+| インデント | 4 スペース(タブなし) |
+| 行末 | LF |
+| エンコーディング | UTF-8 |
| 最大行長 | 100 文字 |
-| フォーマッター | **CSharpier** — `dotnet csharpier .` |
+| 末尾の空白 | 削除 |
+| 末尾の改行 | 必須 |
+| フォーマッター | **CSharpier** — コミット前に `dotnet csharpier .` |
+| CA1416 | `.editorconfig` で抑制 — すべて Windows 専用 |
<h3 id="code-style-jp">コードスタイル</h3>
- **ハードコードされた文字列は禁止** — 常に `Translations.KeyName` または `Loc.Instance["Key"]`
-- **コメントは最小限に**
-- **既存のライブラリを優先**
-- **`@formatter:off` / `@formatter:on`** を使用して大きなレジストリ書き込みブロックの自動フォーマットを抑制可能
+- **コメントは最小限に** — 既存コードにはほとんどありません。不要なコメントを追加しないこと。
+- **既存のライブラリを優先**(新しい依存関係より)
+- **小さく焦点を絞った変更を優先**(大きなリファクタより)
+- **マシン固有のパスやシークレットをコミットしない**
+
+<h3 id="dependency-injection-jp">依存性注入</h3>
+
+- サービス、ViewModel、ページは `App.xaml.cs` にシングルトンとして登録します。
+- コンストラクタ注入を使用:`public class Foo(Bar bar, Baz baz)` または `public class Foo(ILogger<Foo> logger)`。
+- 静的プロバイダーサービス(`RegistryService`、`ShellService`、`ScheduledTaskService`、`ServiceProcessService`)は注入**されません** — 直接アクセスします。
+- テストダブルは手書き(モックライブラリなし)。
<h3 id="error-handling-jp">エラー処理</h3>
| レイヤー | プラクティス |
|---|---|
-| **最適化** | `ApplyResult.False("reason")` を返す。例外はスローしない |
-| **プロバイダーサービス** | try/catch + `ExecutionScope.LogError` |
-| **ViewModel** | コマンドハンドラーで例外をキャッチ、スナックバー表示 |
-| **グローバル** | App.xaml.cs で 3 つのグローバル例外ハンドラを登録。クラッシュは `%localappdata%\optimizerDuck\Crashes\crash_*.log` に記録 |
+| **最適化** | スローせず `ApplyResult.False("reason")` を返す。ステップ単位の失敗追跡は `ExecutionScope` に任せる。 |
+| **プロバイダーサービス** | システム呼び出しを try/catch で囲みエラーをログ。失敗ステップにリトライアクションを記録。 |
+| **ViewModel** | コマンドハンドラーで例外をキャッチし、ユーザーフレンドリーなスナックバーを表示。 |
+| **条件** | `ConditionResult.Error()` を返すか throw — `ConditionEvaluator` がキャッチして `Error`(ブロックしない)に変換。 |
+| **してはいけない** | 処理できない例外のキャッチ。すべての例外を黙って握りつぶさない。 |
+
+<h3 id="global-error-handling-jp">グローバルエラー処理</h3>
+
+`App.xaml.cs` は 3 つのグローバル例外ハンドラを登録します:
+
+- `AppDomain.CurrentDomain.UnhandledException` — 致命的例外を捕捉
+- `TaskScheduler.UnobservedTaskException` — 未監視のタスク例外を捕捉
+- `DispatcherUnhandledException` — 未処理の UI スレッド例外を捕捉
+
+クラッシュの詳細はすべて `%localappdata%\optimizerDuck\Crashes\crash_*.log` に記録されます。
---
@@ -761,123 +1193,198 @@ dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release
<h3 id="resx-files-jp">RESX ファイル</h3>
-すべてのユーザー向け文字列は `Resources/Languages/Translations.resx` に格納されています。
+すべてのユーザー向け文字列は `Resources/Languages/Translations.resx`(英語のデフォルト)に格納されています。C# では型付きの `Translations` クラス、動的ルックアップでは `Loc.Instance["Key"]` を使用します。
-- `Translations.Designer.cs` は直接編集しない
-- `{0}`、`{1}` などのフォーマットパラメータは正確に保持する
+- `Translations.Designer.cs` は**直接編集しないでください** — 自動生成です。
+- [ResXManager](https://marketplace.visualstudio.com/items?itemName=TomEnglert.ResXManager)(VS)または Rider 組み込みのリソースエディタを使用します。
+- `{0}`、`{1}` などのフォーマットパラメータは正確に保持してください。
+- 文字列は簡潔に — 一部の UI カードには幅制限があります。
-<h3 id="available-locales-jp">利用可能なロケール(11 言語 + 英語)</h3>
+<h3 id="available-locales-jp">利用可能なロケール</h3>
-| 言語 | ファイル |
-|---|---|
-| English | `Translations.resx` (default) |
-| Vietnamese | `Translations.vi-VN.resx` |
-| Spanish | `Translations.es-ES.resx` |
-| French | `Translations.fr-FR.resx` |
-| Traditional Chinese | `Translations.zh-TW.resx` |
-| Simplified Chinese | `Translations.zh-CN.resx` |
-| Russian | `Translations.ru-RU.resx` |
-| Korean | `Translations.ko-KR.resx` |
-| Japanese | `Translations.ja-JP.resx` |
-| Polish | `Translations.pl-PL.resx` |
-| Turkish | `Translations.tr-TR.resx` |
-| Portuguese (Brazil) | `Translations.pt-BR.resx` |
+アプリは**15 を超える言語**を同梱しており、その数は増え続けています。ここに列挙すると古くなってしまうため、代わりに次を確認してください:
+
+- **ロケールファイル自体**:`optimizerDuck/Resources/Languages/` — 言語ごとに `Translations.{locale}.resx` が 1 つ、英語のデフォルトとして `Translations.resx` があります。
+- **登録リスト**:`UI/ViewModels/Pages/SettingsViewModel.cs` の `Languages` — UI に表示される言語の正式なリストです。
+
+<h3 id="adding-a-new-language-jp">新しい言語の追加</h3>
+
+1. `Translations.{locale}.resx`(例:`Translations.de-DE.resx`)を `Translations.resx` と同じすべてのキーで作成します。
+2. `UI/ViewModels/Pages/SettingsViewModel.cs` に言語を登録します:
+
+```csharp
+new() { DisplayName = "Deutsch", Culture = new CultureInfo("de-DE") },
+```
<h3 id="hardcoded-string-rule-jp">文字列ハードコードの禁止</h3>
+**文字列をハードコードしないでください**。常に次を使用します:
+
```csharp
+// 型付き(推奨)
string title = Translations.Features_Desktop_Name;
+
+// フォーマット引数付き
+string msg = string.Format(Translations.Dashboard_SystemInfo_Storage_DiskInfo, used, total, percent);
+
+// 動的キールックアップ(規則ベースのキー用)
string title = Loc.Instance[$"Optimizer.{category}.{key}.Name"];
```
XAML:
```xml
+<!-- 引数なし -->
<ui:TextBlock Text="{ext:Loc Dashboard.Header.Title}" />
+
+<!-- バインドされた引数付き -->
+<ui:TextBlock Text="{ext:Loc Dashboard.UpdateInfoBar.Message, {Binding ViewModel.LatestVersion}}" />
```
---
<h1 id="pull-request-process">プルリクエストの手順</h1>
-1. `master` からブランチを作成:`feature/name` または `fix/issue-id`
-2. Conventional Commits:`feat:`、`fix:`、`refactor:`、`docs:`、`test:`、`i18n:`、`chore:`
-3. プッシュ前に確認:
+1. **`master` からブランチを作成** — master で直接作業しないこと:
-```bash
-dotnet build optimizerDuck.slnx --configuration Release
-dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build
-dotnet csharpier .
-```
+ ```bash
+ git checkout -b feature/your-feature-name
+ # または
+ git checkout -b fix/issue-number
+ ```
+
+2. **Conventional Commits でコミット**:
+
+ | プレフィックス | 使用場面 |
+ |---|---|
+ | `feat:` | 新しい最適化や機能 |
+ | `fix:` | バグ修正 |
+ | `refactor:` | 動作を変えないコード再構成 |
+ | `docs:` | ドキュメント更新 |
+ | `test:` | テストの追加・修正 |
+ | `i18n:` | 翻訳の更新 |
+ | `chore:` | メンテナンス、ビルド設定、依存関係 |
+
+3. **プッシュ前に確認**:
+
+ ```bash
+ # 1. ビルド
+ dotnet build optimizerDuck.slnx --configuration Release
-4. PR を作成:変更内容と理由を説明、UI 変更のスクリーンショットを含める、関連 Issue を `Closes #42` でリンク
+ # 2. テスト
+ dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build
+
+ # 3. 整形
+ dotnet csharpier .
+
+ # 4. git status を確認 — 意図したファイルだけがステージされていることを確認
+ git status
+ git diff --cached
+ ```
+
+4. **PR を開く**:
+ - **何を**変え、**なぜ**変えたかを説明します。
+ - UI 変更がある PR は**スクリーンショットを含めてください**。
+ - 関連 Issue をリンク:`Closes #42`。
+ - 作業中ならドラフトとしてマークします。
+
+5. **レビュー**:メンテナがレビューします。フィードバックにオープンに、迅速に対応してください。
<h3 id="pr-checklist-jp">PR チェックリスト</h3>
-- [ ] 既存のパターンに従っている
-- [ ] ローカライズキーが `Translations.resx` に追加されている
-- [ ] `dotnet build` 成功
-- [ ] `dotnet test` 成功
-- [ ] `dotnet csharpier .` 実行済み
+- [ ] 既存のパターンに従っている(検出、属性、非同期命名)
+- [ ] ローカライズキーが最低限 `Translations.resx` に追加されている
+- [ ] 関連する場合は条件が宣言されている([条件システム](#the-condition-system) を参照)
+- [ ] `dotnet build` が成功(エラー 0 件)
+- [ ] `dotnet test` が成功(全テスト緑)
+- [ ] `dotnet csharpier .` を実行済み
- [ ] ハードコード文字列なし
-- [ ] リバートステップが記録されている(該当する場合)
+- [ ] リバートステップが適切に記録されている(該当する場合)
- [ ] UI 変更のスクリーンショットあり
---
<h1 id="issue-guidelines">Issue ガイドライン</h1>
-- **バグ報告**:再現手順、期待/実際の動作、`%localappdata%\optimizerDuck\optimizerDuck.log` のログ + システム仕様
-- **機能リクエスト**:ユースケース、解決する問題、動作
-- **最適化の提案**:レジストリパス、サービス名、CLI コマンド、情報源へのリンク
-- **質問**:GitHub Discussions または [Discord](https://discord.gg/tDUBDCYw9Q)
+- **バグ報告**:Bug Report テンプレートを使用。再現手順、期待/実際の動作、`%localappdata%\optimizerDuck\optimizerDuck.log` のログ + システム仕様を含めてください。
+- **機能リクエスト**:ユースケース、解決する問題、動作の仕方を説明します。
+- **最適化の提案**:レジストリパス、サービス名、CLI コマンドを含めます。ドキュメントや信頼できる情報源へのリンクを付けます。
+- **質問**:GitHub Discussions または [Discord](https://discord.gg/tDUBDCYw9Q) を利用してください。
---
<h1 id="faq--troubleshooting">FAQ とトラブルシューティング</h1>
<h3>ビルドが CA1416 エラーで失敗する</h3>
-`.editorconfig` が CA1416 を抑制。最新の `.editorconfig` を確認。
+
+`.editorconfig` が CA1416 を抑制しています。それでも表示される場合は、master の最新 `.editorconfig` を使用しているか確認してください。このプロジェクトは Windows 専用です — `SupportedOSPlatform` ガードを追加しないでください。
<h3>最適化が UI に表示されない</h3>
-- カテゴリクラス内のネストされた public クラス?
-- カテゴリが `IOptimizationCategory` を実装?
-- `BaseOptimization` を継承?
-- `[Optimization(Id = "...")]` 属性?
-- ローカライズキーが `Translations.resx` に追加されている?
-- `OptimizationRegistry.IsPreloaded` を確認?
+
+チェックリスト:
+
+- カテゴリクラス内の**ネストされた public クラス**ですか?
+- カテゴリクラスは `IOptimizationCategory` を実装していますか?
+- 最適化クラスは `BaseOptimization` を継承していますか?
+- `[Optimization(Id = "...", ...)]` 属性がありますか?
+- ローカライズキーは `Translations.resx` に追加されていますか?
+- 最適化カテゴリはプリロード済みですか?(`OptimizationRegistry.IsPreloaded` を確認)
+- `Condition` がブロックしていませんか?(次の質問を参照)
+
+<h3>最適化/設定が「非対応」(ブロック)と表示される</h3>
+
+- 属性に宣言された `Condition = typeof(...)` を確認してください。
+- 条件型が `ICondition` を実装し、具象型で、public のパラメータなしコンストラクタを持つことを確認してください(`ConditionValidation` が起動時に強制します)。
+- アイテムがブロックされるのは**未適用**の場合のみです。適用済みアイテムは常に通常のカードを表示します。
<h3>カスタマイズ設定が表示されない</h3>
-- `[CustomizeSetting(Section = ..., Icon = ...)]` 属性?
-- `Section` のスペルは正しい?
-- `[CustomizeCategory(PageType = ...)]` 属性?
-<h3>UI がフリーズする</h3>
-`async`/`await` を使用していることを確認。`.Result` / `.Wait()` はフリーズの原因。
+- `[CustomizeSetting(Section = ..., Icon = ...)]` がありますか?(`Icon` は必須です。)
+- `Section` の値のスペルは正しいですか?
+- カテゴリクラスは正しい `[CustomizeCategory(PageType = ...)]` 属性を使っていますか?
+- `Condition` がブロックしていませんか?
+
+<h3>テスト後にリバートデータファイルがない</h3>
+
+リバートデータを確認するテストは `%localappdata%\optimizerDuck\Revert\` のファイルを期待します。テストのクリーンアップは `finally` ブロックで実行されます — アサーションがクリーンアップの前に実行されることを確認してください。
-<h3>GUID の生成</h3>
+<h3>最適化の適用中に UI がフリーズする</h3>
+
+非同期プロバイダー呼び出し(`ChangeServiceStartupTypeAsync`、`CMDAsync`、`PowerShellAsync`)では `ApplyAsync` が `async`/`await` を使っていることを確認してください。`Task.FromResult` や `.Result` / `.Wait()` でのブロックは UI スレッドをフリーズさせます。
+
+<h3>GUID の生成方法</h3>
```powershell
+# PowerShell
[guid]::NewGuid()
```
+```bash
+# コマンドライン(uuidgen が利用可能な場合)
+uuidgen
+```
+
<h3>翻訳がキー名として表示される</h3>
-`Translations.resx` へのローカライズキーの追加を忘れている。
-<h3>「No revert data」エラー</h3>
-最適化の `Id` GUID が変更されていないことを確認。
+`Translations.resx` へのローカライズキーの追加を忘れています。期待されるキーパターンは [ローカライズ](#localization) セクションを確認してください。
+
+<h3>リバート時に「No revert data」エラー</h3>
+
+最適化の `Id` GUID が変更されていないことを確認してください。リバートファイルは `Id` でキー付けされます。GUID を再生成すると、以前に適用した最適化に一致するリバートファイルがなくなります。
+
+<h3>新しいリバートステップタイプの追加方法</h3>
+
+1. `Domain/Revert/Steps/` に `IRevertStep` を実装する新しいクラスを作成します。
+2. デシリアライズ用に静的な `FromData(JObject data)` メソッドを追加します。
+3. `RevertManager` のリフレクションベースの `_stepRegistry` が自動検出します。
+4. `ExecutionScope.RecordStep()` で `revertStep` パラメータとして記録します。
-<h3>新しいリバートステップタイプの追加</h3>
-1. `Domain/Revert/Steps/` に `IRevertStep` を実装する新しいクラスを作成
-2. 静的な `FromData(JObject data)` メソッドを追加(デシリアライズ用)
-3. `RevertManager` のリフレクションベースの `_stepRegistry` が自動検出
-4. `ExecutionScope.RecordStep()` で記録
+<h3>クラッシュセーフティの仕組み</h3>
-<h3>クラッシュセーフティ</h3>
-- リバートファイル:アトミック書き込み(`.tmp` + `File.Replace`)
-- クラッシュログ:`%localappdata%\optimizerDuck\Crashes\crash_*.log`
-- `WmiHelper.Initialize()` が起動時に異常終了クリーンアップを登録
-- App.xaml.cs に 3 つのグローバル例外ハンドラ
+- リバートファイルはアトミック書き込み(`.tmp` + `File.Replace`)。
+- クラッシュログは `%localappdata%\optimizerDuck\Crashes\crash_*.log` に書き込み。
+- `WmiHelper.Initialize()` が起動時に異常終了の WMI クリーンアップを登録。
+- `App.xaml.cs` が 3 つのグローバル例外ハンドラを登録。
---
@@ -885,7 +1392,7 @@ dotnet csharpier .
<h2 id="credits">クレジット</h2>
-マージされた PR の貢献者はリリースノートに記載されます。
+マージされた PR の貢献者はリリースノートに記載されます。モジュールに大きく貢献した場合、ファイルヘッダー上部に作者タグを追加できます。
---
diff --git a/.github/contributing/CONTRIBUTING.tr-TR.md b/.github/contributing/CONTRIBUTING.tr-TR.md
index 224f21b..fafa2d8 100644
--- a/.github/contributing/CONTRIBUTING.tr-TR.md
+++ b/.github/contributing/CONTRIBUTING.tr-TR.md
@@ -1,20 +1,21 @@
<div align="center">
-<a href="https://optimizerduck.vercel.app/"><img src="./.github/assets/optimizerDuck.png" alt="optimizerDuck Afişi" title="optimizerDuck"/></a>
+<a href="https://optimizerduck.vercel.app/"><img src="../assets/optimizerDuck.png" alt="optimizerDuck Afişi" title="optimizerDuck"/></a>
-[English](../CONTRIBUTING.md) | [日本語](CONTRIBUTING.ja-JP.md) | **Türkçe**
+[English](../../CONTRIBUTING.md) | [日本語](CONTRIBUTING.ja-JP.md) | **Türkçe**
-[Giriş](#giriş) • [Başlangıç](#başlangıç) • [Mimariye Genel Bakış](#mimariye-genel-bakış) • [Katkıda Bulunma Yolları](#katkıda-bulunma-yolları) • [Optimizasyon Oluşturma](#optimizasyon-oluşturma) • [Özelleştirme Ayarı Oluşturma](#özelleştirme-ayarı-oluşturma) • [Yenileme Kapsamı Sistemi](#yenileme-kapsamı-sistemi) • [Yeni Özellikler Geliştirme](#yeni-özellikler-geliştirme) • [Geri Alma Sistemi](#geri-alma-sistemi) • [Test Etme](#test-etme) • [Kodlama Standartları](#kodlama-standartları) • [Yerelleştirme](#yerelleştirme) • [Çekme İsteği Süreci](#çekme-isteği-süreci) • [Sorun (Issue) Yönergeleri](#sorun-issue-yönergeleri) • [SSS ve Sorun Giderme](#sss-ve-sorun-giderme) • [Lisans](#lisans)
+[Giriş](#introduction) • [Başlangıç](#getting-started) • [Mimariye Genel Bakış](#architecture-overview) • [Katkıda Bulunma Yolları](#ways-to-contribute) • [Optimizasyon Oluşturma](#creating-an-optimization) • [Özelleştirme Ayarı Oluşturma](#creating-a-customize-setting) • [Koşul Sistemi](#the-condition-system) • [Yenileme Kapsamı Sistemi](#the-refresh-scope-system) • [Yeni Özellikler Geliştirme](#building-new-features) • [Geri Alma Sistemi](#revert-system) • [Test Etme](#testing) • [Kodlama Standartları](#coding-standards) • [Yerelleştirme](#localization) • [Çekme İsteği Süreci](#pull-request-process) • [Sorun (Issue) Yönergeleri](#issue-guidelines) • [SSS ve Sorun Giderme](#faq--troubleshooting) • [Lisans](#license)
</div>
---
-# Giriş
+<h1 id="introduction">Giriş</h1>
-.NET 10 üzerinde WPF ile oluşturulmuş ücretsiz, açık kaynaklı bir Windows optimizasyon aracı olan **optimizerDuck**'a katkıda bulunduğunuz için teşekkür ederiz.
+**.NET 10 üzerinde WPF ile oluşturulmuş ücretsiz, açık kaynaklı bir Windows optimizasyon aracı** olan **optimizerDuck**'a katkıda bulunduğunuz için teşekkür ederiz.
Birçok şekilde yardımcı olabilirsiniz:
+
- Açık yeniden üretme adımlarıyla hataları bildirmek
- Yeni optimizasyonlar veya özellikler önermek (önce bir sorun açın)
- Dokümantasyonu ve kılavuzları geliştirmek
@@ -22,11 +23,13 @@ Birçok şekilde yardımcı olabilirsiniz:
- Kod katkısında bulunmak: optimizasyonlar, özelleştirme ayarları, hizmetler, kullanıcı arayüzü iyileştirmeleri
- Test eklemek veya mevcut testleri gözden geçirmek
+> **Burada yeni misiniz?** Önce [Başlangıç](#getting-started) bölümünü, ardından [Mimariye Genel Bakış](#architecture-overview) bölümünü okuyun. En yaygın iki kod katkısı [Optimizasyon Oluşturma](#creating-an-optimization) ve [Özelleştirme Ayarı Oluşturma](#creating-a-customize-setting) bölümleridir.
+
---
-# Başlangıç
+<h1 id="getting-started">Başlangıç</h1>
-### 1. Ortam Kurulumu
+<h3 id="environment-setup">1. Ortam Kurulumu</h3>
| Gereksinim | Notlar |
|---|---|
@@ -42,7 +45,7 @@ dotnet --version
# 10.x çıktısını vermelidir
```
-### 2. Forklayın ve Klonlayın
+<h3 id="fork-and-clone">2. Forklayın ve Klonlayın</h3>
```bash
# Önce GitHub'da depoyu forklayın, ardından kendi çatalınızı klonlayın
@@ -56,7 +59,7 @@ git remote add upstream https://github.com/itsfatduck/optimizerDuck.git
git checkout -b feature/sizin-ozellik-adiniz
```
-### 3. Geri Yükleme, Derleme ve Test
+<h3 id="restore-build-test">3. Geri Yükleme, Derleme ve Test</h3>
Çözüm, `.slnx` formatını kullanır (XML tabanlı çözüm dosyası, `.sln` değil).
@@ -70,7 +73,7 @@ dotnet build optimizerDuck.slnx --configuration Release --no-restore
# Testleri çalıştır
dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build
-# Uygulamayı çalıştır
+# Uygulamayı çalıştır (sistem ayarlarını değiştirdiği için yükseltilmiş komut istemi gerekir)
dotnet run --project optimizerDuck/optimizerDuck.csproj
# CSharpier ile kodu biçimlendir
@@ -79,7 +82,7 @@ dotnet csharpier .
> Yeni NuGet bağımlılıkları eklerseniz, `dotnet restore` komutunu tekrar çalıştırın (sonraki derlemelerde `--no-restore` kullanabilirsiniz).
-### 4. Yayımlama (Publishing)
+<h3 id="publishing">4. Yayımlama (Publishing)</h3>
```bash
publish.bat portable # Taşınabilir klasör (test için önerilir)
@@ -88,7 +91,9 @@ publish.bat single --skip-tests # Hızlı yineleme için testleri atlar
publish.bat portable --no-pause # Sonunda duraklamaz (CI dostu)
```
-### 5. Hızlı Başlangıç Kontrol Listesi
+`publish.bat` önce test paketini çalıştırır (`--skip-tests` geçilmediyse), ardından seçilen profille (`Portable` veya `Single`) `dotnet publish` çağırır.
+
+<h3 id="quick-start-checklist">5. Hızlı Başlangıç Kontrol Listesi</h3>
İlk katkınızdan önce:
@@ -96,13 +101,13 @@ publish.bat portable --no-pause # Sonunda duraklamaz (CI dostu)
- [ ] `dotnet build` başarılı oldu (0 hata)
- [ ] `dotnet test` geçer (tüm testler yeşil)
- [ ] `dotnet csharpier .` hatasız şekilde kodunuzu biçimlendiriyor
-- [ ] Aşağıdaki [Mimariye Genel Bakış](#mimariye-genel-bakış) bölümünü okudunuz
+- [ ] Aşağıdaki [Mimariye Genel Bakış](#architecture-overview) bölümünü okudunuz
---
-# Mimariye Genel Bakış
+<h1 id="architecture-overview">Mimariye Genel Bakış</h1>
-### Çözüm Yapısı
+<h3 id="solution-structure">Çözüm Yapısı</h3>
```
optimizerDuck.slnx # Çözüm dosyası (.slnx formatı)
@@ -112,110 +117,162 @@ optimizerDuck.slnx # Çözüm dosyası (.slnx formatı)
│ ├── app.manifest # requireAdministrator UAC seviyesi
│ │
│ ├── Domain/ # Saf modeller, arayüzler, özellikler (WPF bağımlılığı yok)
-│ │ ├── Abstractions/ # IOptimization, ICustomizeSetting, IRevertStep, IWindow, ICustomizeCategory, IOptimizationCategory
-│ │ ├── Attributes/ # [Optimization], [CustomizeSetting], [OptimizationCategory], [CustomizeCategory]
+│ │ ├── Abstractions/ # IOptimization, ICustomizeSetting, IRevertStep, IWindow,
+│ │ │ # ICustomizeCategory, IOptimizationCategory
+│ │ ├── Attributes/ # [Optimization], [CustomizeSetting],
+│ │ │ # [OptimizationCategory], [CustomizeCategory]
+│ │ ├── Conditions/ # Uyumluluk koşul sistemi ("Koşul Sistemi" bölümüne bakın)
+│ │ │ ├── BuiltIn/ # Hazır koşullar (Windows sürümü, GPU/CPU markası,
+│ │ │ │ # minimum RAM, kayıt defteri anahtarı / hizmet varlığı, ...)
+│ │ │ ├── ICondition.cs # Koşul sözleşmesi
+│ │ │ ├── ConditionBase.cs # Paylaşılan yardımcılar (örn. OS derleme ayrıştırma)
+│ │ │ ├── ConditionResult.cs # Available / Unsupported / Error sonucu
+│ │ │ ├── ConditionState.cs # Sonuç enum'u
+│ │ │ ├── ConditionValidation.cs # Keşif sırasında meta veri doğrulama
+│ │ │ └── WindowsBuilds.cs # OS derleme numarası sabitleri
│ │ ├── Configuration/ # AppSettings modeli
+│ │ ├── Exceptions/ # StepExecutionException
│ │ ├── Execution/ # ExecutionScope — AsyncLocal ile çevresel adım takibi
-│ │ ├── Customize/ # Özelleştirme ayarları (Desktop, Gaming, Preferences, System)
-│ │ │ ├── Categories/ # İçi içe ayar sınıflarına sahip kategori sınıfları
-│ │ │ └── Models/ # BaseCustomizeSetting, RegistryToggle, RefreshScope, SettingOption, RecommendationState
-│ │ ├── Optimizations/ # Optimizasyonlar (Performance, Privacy, GPU, vb.)
-│ │ │ ├── Categories/ # İçi içe optimizasyon sınıflarına sahip kategori sınıfları
-│ │ │ └── Models/ # BaseOptimization, ApplyResult, OptimizationContext, ServiceItem, RegistryItem
+│ │ ├── Customize/ # Özelleştirme ayarları
+│ │ │ ├── Categories/ # İç içe ayar sınıflarına sahip kategori sınıfları
+│ │ │ └── Models/ # BaseCustomizeSetting, RegistryToggle, RegistryBinding,
+│ │ │ # CustomizeRefreshScope, SettingOption,
+│ │ │ # CustomizeControlType, RecommendationState, ...
+│ │ ├── Optimizations/ # Optimizasyonlar
+│ │ │ ├── Categories/ # İç içe optimizasyon sınıflarına sahip kategori sınıfları
+│ │ │ └── Models/ # BaseOptimization, ApplyResult, OptimizationContext,
+│ │ │ ├── Bloatware/ # Önceden yüklü uygulamalar için AppXPackage modeli
+│ │ │ ├── Cleanup/ # Disk temizliği için CleanupItem
+│ │ │ ├── ScheduledTask/ # ScheduledTaskModel
+│ │ │ ├── Services/ # RegistryItem, ServiceItem, ShellResult, ServiceStartupType
+│ │ │ └── StartupManager/ # StartupApp, StartupTask modelleri
│ │ ├── Revert/ # RevertData, RevertResult, geri alma adımı türleri
-│ │ │ └── Steps/ # RegistryRevertStep, ServiceRevertStep, ScheduledTaskRevertStep, ShellRevertStep, UsbPowerRevertStep
-│ │ └── UI/ # Enumlar: OptimizationRisk, OptimizationTags, OptimizationCategoryOrder, CustomizeOrder, LanguageOption, OptimizationState
+│ │ │ └── Steps/ # RegistryRevertStep, ServiceRevertStep,
+│ │ │ # ScheduledTaskRevertStep, ShellRevertStep, UsbPowerRevertStep
+│ │ └── UI/ # Enumlar: OptimizationRisk, OptimizationTags,
+│ │ # OptimizationCategoryOrder, CustomizeOrder,
+│ │ # LanguageOption, OptimizationState, RiskVisual,
+│ │ # ProcessingProgress, ...
│ │
│ ├── Common/ # Ortak yardımcılar, eklentiler, dönüştürücüler
-│ │ ├── Converters/ # 20+ WPF değer dönüştürücüsü
-│ │ ├── Extensions/ # StringExtensions, CustomizePageRegistryExtensions, OptimizationPageRegistryExtensions
-│ │ ├── Helpers/ # Shared.cs, ReflectionHelper.cs, SystemRefreshService.cs, EmbeddedResourceHelper.cs, WmiHelper.cs
-│ │ └── Native/ # Yerel işletim sistemi yardımcıları
+│ │ ├── Converters/ # WPF değer dönüştürücüleri (BooleanToVisibility, MBToGB, ...)
+│ │ ├── Extensions/ # StringExtensions, sayfa-kayıt eklentileri,
+│ │ │ # LanguageExtensions
+│ │ └── Helpers/ # Shared.cs, ReflectionHelper.cs, SystemRefreshService.cs,
+│ │ # EmbeddedResourceHelper.cs, WmiHelper.cs,
+│ │ # GitHubSourceHelper.cs, ThemeResource.cs, ...
│ │
│ ├── Services/ # İş mantığı katmanı
+│ │ ├── Conditions/ # ConditionEvaluator (statik değerlendirme giriş noktası)
│ │ ├── Configuration/ # ConfigManager, LanguageManager
│ │ ├── Customize/ # CustomizeRegistry (yansıma tabanlı keşif)
│ │ ├── Optimization/ # OptimizationRegistry, OptimizationService
-│ │ │ └── Providers/ # Statik: RegistryService, ShellService, ScheduledTaskService, ServiceProcessService
-│ │ ├── Revert/ # RevertManager (atomik JSON okuma/yazma)
-│ │ ├── System/ # RegistryWatcher, StreamService, SystemInfoService, UpdaterService
+│ │ │ └── Providers/ # Statik: RegistryService, ShellService (+ ShellPolicy),
+│ │ │ # ScheduledTaskService, ServiceProcessService
+│ │ ├── Revert/ # RevertManager (geri alma JSON'unun atomik okuma/yazması)
+│ │ ├── System/ # RegistryWatcher (+ IRegistryWatcher), SystemInfoService,
+│ │ │ # StreamService, UpdaterService, CrossPageEventBus
│ │ └── UI/ # BloatwareService, DiskCleanupService, StartupManagerService
│ │
│ ├── UI/ # WPF sayfaları, ViewModel'ler, kontroller, stiller
│ │ ├── Behaviors/ # SmoothScrollBehavior
-│ │ ├── Controls/ # FilledNavigationViewItem
-│ │ ├── Dialogs/ # ProcessingDialog, OptimizationDetailsDialog, RestorePointDialog, LegalDialog, BloatwareConfirmationDialog, ScheduledTaskCreateDialog
-│ │ ├── Pages/ # Dashboard, Optimize, Customize, Settings, Bloatware, DiskCleanup, StartupManager, ScheduledTasks
-│ │ ├── Styles/ # FluentDesign.xaml, NavigationViewOverride.xaml
-│ │ ├── ViewModels/ # Sayfa ve diyalog ViewModel'leri
+│ │ ├── Controls/ # FilledNavigationViewItem, EmptyBadge
+│ │ ├── Dialogs/ # ProcessingDialog, OptimizationDetailsDialog,
+│ │ │ # OptimizationResultDialog, RestorePointDialog, LegalDialog,
+│ │ │ # BloatwareConfirmationDialog, ScheduledTask diyalogları, ...
+│ │ ├── Pages/ # Dashboard, Optimize, Customize, Settings, Bloatware,
+│ │ │ ├── Customize/ # CustomizePage + Categories/ (otomatik kayıtlı sayfalar)
+│ │ │ ├── Optimize/ # OptimizePage + Categories/ (otomatik kayıtlı sayfalar)
+│ │ │ ├── DiskCleanupPage
+│ │ │ ├── StartupManagerPage
+│ │ │ └── ScheduledTasksPage
+│ │ ├── Styles/ # FluentDesign.xaml, NavigationViewOverride.xaml, ToolTipOverride.xaml
+│ │ ├── ViewModels/ # Sayfa, diyalog ve pencere ViewModel'leri
│ │ └── Windows/ # MainWindow
│ │
│ └── Resources/ # Resimler, gömülü dosyalar, yerelleştirme
-│ ├── Embedded/ # Güç planları, simgeler
-│ ├── Images/ # Duck.png, logolar
-│ └── Languages/ # Translations.resx + 11 dil varyantı
+│ ├── Embedded/ # Icons/ ve PowerPlans/ (optimizerDuck.pow)
+│ ├── Images/ # Duck.png, GitHub logoları, Discord logosu
+│ └── Languages/ # Translations.resx (varsayılan) + yerel ayar sürümleri
│
-└── optimizerDuck.Test/ # xUnit v3 test projesi
+└── optimizerDuck.Test/ # xUnit v3 test projesi (InternalsVisibleTo)
```
-### Önemli Tasarım Kararları
+> **Yukarıdaki ağacı katı bir referans olarak almayın.** Bu bir haritadır, şartname değildir — klasörler ve dosyalar gelişir. Şüpheye düştüğünüzde gerçek klasörlere bakın. Bu bölümün sonundaki [Proje Yapısı](#project-structure) notuna da bakın.
-| Karar | Gerekçesi |
+<h3 id="key-design-decisions">Temel Tasarım Kararları</h3>
+
+| Karar | Gerekçe |
|---|---|
-| **Yansıma tabanlı keşif** | Güncellenecek DI kayıt dizileri yok. `ReflectionHelper.FindImplementationsInLoadedAssemblies<T>()` başlangıçta `optimizerDuck.*` derlemelerini tarar. Yeni optimizasyonlar/ayarlar otomatik keşfedilir. |
-| **Statik sağlayıcı hizmetler** | `RegistryService`, `ShellService`, `ScheduledTaskService`, `ServiceProcessService` statik sınıflardır. Geri alma adımlarını `ExecutionScope`'a otomatik kaydederler. |
-| **Dosya tabanlı geri alma takibi** | Uygulanan durum = diskte dosyanın var olması (`%localappdata%\optimizerDuck\Revert\{id}.json`). Veritabanı yok. Atomik yazmalar `File.Replace()` ile yapılır. |
-| **Entegrasyon tarzı testler** | Gerçek dosya sistemi, gerçek kayıt defteri, gerçek işlem yürütme. Mock kütüphanesi yok — elle yazılmış test double'ları. |
-| **Zaman uyumsuz servis metotları** | Harici işlemleri yürüten yöntemler asenkrondur (`*Async` son eki). |
-| **Statik WMI yardımcısı** | `WmiHelper.Initialize()` başlangıçta çalışır, anormal sonlanma için WMI temizleme işleyicilerini kaydeder. |
+| **Yansıma tabanlı keşif** | Güncellenecek DI kayıt dizisi yok. `ReflectionHelper.FindImplementationsInLoadedAssemblies<T>()` `optimizerDuck.*` derlemelerini tarar. Yeni optimizasyonlar/ayarlar otomatik keşfedilir. |
+| **Statik sağlayıcı hizmetler** | `RegistryService`, `ShellService`, `ScheduledTaskService`, `ServiceProcessService` statik sınıflardır. Geri alma adımlarını çevresel `ExecutionScope`'a kaydeder — bağlam enjekte etmek veya geçirmek gerekmez. |
+| **Dosya tabanlı geri alma takibi** | Uygulanma durumu = diskte dosya var (`%localappdata%\optimizerDuck\Revert\{id}.json`). Veritabanı yok. `File.Replace()` ile atomik yazma. |
+| **Koşul sistemi (açık kalma)** | Optimizasyonlar ve ayarlar uyumluluk koşulları bildirebilir. Değerlendirme hataları asla bir öğeyi gizlemez — [Koşul Sistemi](#the-condition-system) bölümüne bakın. |
+| **Entegrasyon tarzı testler** | Gerçek dosya sistemi, gerçek kayıt defteri (`HKCU\Software\TestOptimizerDuck*` altında), gerçek süreç yürütme. Mock kütüphanesi yok — yalnızca elle yazılmış test ikizleri. |
+| **Asenkron hizmet metotları** | Harici süreç çalıştıran sağlayıcı metotları asenkrondur (`*Async` eki). Optimizasyon `ApplyAsync` metotları, UI'nın duyarlı kalması için `async`/`await` kullanmalıdır. |
+| **Statik WMI yardımcısı** | `WmiHelper.Initialize()` başlangıçta çalışır ve anormal sonlanma için WMI temizleme işleyicilerini kaydeder. |
+| **Bekleyen değişiklik takibi** | `App.HasPendingChanges`, geri alınmamış optimizasyonları izler. Uygulama kapanırken PC/Explorer'ı yeniden başlatma veya çıkış seçenekleri sunar. |
+
+<h3 id="project-structure">Proje Yapısı</h3>
+
+Yetkili yapı üç yerde bulunur; bir şeyi taşıdığınızda veya yeniden adlandırdığınızda bunların hepsi senkron tutulmalıdır:
+
+1. **Diskteki klasörler** — `optimizerDuck/` (uygulama) ve `optimizerDuck.Test/` (testler). Başka üst düzey proje dizini yoktur.
+2. **`optimizerDuck.csproj`** — gömülü kaynaklar, resimler, paket referansları.
+3. **`App.xaml.cs`** — DI kayıtları ve başlangıç sırası.
+
+Bu iki proje klasörünün dışında üst düzey dizin oluşturmayın.
---
-# Katkıda Bulunma Yolları
+<h1 id="ways-to-contribute">Katkıda Bulunma Yolları</h1>
| Katkı Türü | Açıklama | Nereden Başlamalı |
|---|---|---|
-| **Yeni Optimizasyonlar** | Kayıt defteri ayarları, servis değişiklikleri, sistem ayarları | `Domain/Optimizations/Categories/*.cs` |
-| **Yeni Özelleştirme Ayarları** | Windows ayarları için kullanıcı arayüzü anahtarları | `Domain/Customize/Categories/*.cs` |
-| **Yeni Uygulama Özellikleri** | Yeni sayfalar, araçlar veya işlevsellikler | Önce bir sorun (Issue) açın |
+| **Yeni Optimizasyonlar** | Kayıt defteri ayarları, hizmet değişiklikleri, sistem ayarları | `Domain/Optimizations/Categories/*.cs` |
+| **Yeni Özelleştirme Ayarları** | Windows ayarları için UI anahtarları (Oyun Modu, Fare Hızlandırma, Görev Çubuğu, vb.) | `Domain/Customize/Categories/*.cs` |
+| **Yeni Koşullar** | Optimizasyon/ayarlar için uyumluluk kapıları (Windows sürümü, donanım, ...) | `Domain/Conditions/` |
+| **Yeni Uygulama Özellikleri** | Yeni sayfalar, araçlar veya işlevler | Önce bir sorun açın |
| **Hata Düzeltmeleri** | Çökme düzeltmeleri, mantık hataları, UI sorunları | Herhangi bir yer |
| **Çeviriler** | Yeni diller veya mevcut çevirileri düzeltme | `Resources/Languages/Translations.*.resx` |
| **Dokümantasyon** | README, CONTRIBUTING vb. | `*.md` dosyaları |
-| **Test** | Yeni/mevcut testleri ekleme veya gözden geçirme | `optimizerDuck.Test/` |
+| **Test Etme** | Mevcut veya yeni optimizasyonlar için test ekleme/gözden geçirme | `optimizerDuck.Test/` |
---
-# Optimizasyon Oluşturma
+<h1 id="creating-an-optimization">Optimizasyon Oluşturma</h1>
-### Keşif Nasıl Çalışır
+<h3 id="how-discovery-works">Keşif Nasıl Çalışır</h3>
-Başlangıçta:
+Başlangıçta uygulama `OptimizationRegistry.PreloadOptimizationsAsync()` çağırır. Bu, yansıma işini arka plan iş parçacığında çalıştırır:
-1. `ReflectionHelper.FindImplementationsInLoadedAssemblies<IOptimizationCategory>()` tüm `optimizerDuck.*` derlemelerini tarar.
-2. `IOptimizationCategory` uygulayan her sınıfı bulur.
-3. Her kategori için, `IOptimization` uygulayan **iç içe geçmiş public sınıfları** tarar.
-4. Keşfedilen tüm optimizasyonlar örneklenir ve `OwnerType` otomatik olarak atanır.
-5. `OptimizationService.UpdateOptimizationStateAsync` diskteki geri alma dosyalarını tarar.
-6. `OptimizationRegistry.StartPreload()` bunu başlangıçta arka planda çalıştırır.
+1. `ReflectionHelper.FindImplementationsInLoadedAssemblies<IOptimizationCategory>()` her kategori sınıfını bulur.
+2. Her kategori için `IOptimization` uygulayan **iç içe public sınıfları** tarar.
+3. Her optimizasyon örneklenir, `OwnerType` atanır ve `[Optimization]` meta verisi (`Condition` dahil) doğrulanır.
+4. `OptimizationService.UpdateOptimizationStateAsync` diskteki geri alma dosyalarını tarar ve her optimizasyonu Uygulandı/Uygulanmadı olarak işaretler.
+5. Optimize sayfası bağlamadan önce `EnsurePreloadedAsync()` çağırır (önceden yüklendiyse hiçbir şey yapmaz).
-**Sizin göreviniz**: Bir kategorinin içine yerleştirilmiş bir sınıf oluşturun, `BaseOptimization`'dan türetin ve `[Optimization]` ile işaretleyin. Hepsi bu kadar.
+**Sizin işiniz**: Bir kategorinin içinde iç içe bir sınıf oluşturun, `BaseOptimization`'dan türetin ve `[Optimization]` ile işaretleyin. Hepsi bu — güncellenecek kayıt yok.
-### Optimizasyon Kategorileri
+<h3 id="optimization-categories">Optimizasyon Kategorileri</h3>
-Mevcut kategoriler (`Domain/Optimizations/Categories/` içinde):
+Kategoriler `Domain/Optimizations/Categories/` içinde, her dosyada bir kategori olacak şekilde bulunur. Kesin küme zamanla değişir — yetkili liste için o klasöre bakın. Bu yazı yazıldığı sırada kategoriler şunlardır:
-| Dosya | Öznitelik | Odak Noktası |
-|---|---|---|
-| `Performance.cs` | `[OptimizationCategory(typeof(PerformanceOptimizerPage))]` | RAM ayarı, süreç önceliği, klavye gecikmesi, multimedya zamanlayıcısı, erişilebilirlik kısayol tuşları |
-| `SecurityAndPrivacy.cs` | `[OptimizationCategory(typeof(SecurityAndPrivacyOptimizerPage))]` | Telemetri, hata bildirimleri, reklam kimliği, konum, Cortana, Copilot, içerik dağıtım yöneticisi, etkinlik geçmişi |
-| `Gpu.cs` | `[OptimizationCategory(typeof(GpuOptimizerPage))]` | AMD/NVIDIA/Intel kayıt defteri ayarları, güç durumları, clock gating, ASPM, async flips |
-| `PowerManagement.cs` | `[OptimizationCategory(typeof(PowerManagementOptimizerPage))]` | Hazırda bekletme, hızlı başlatma, USB seçmeli askıya alma, özel güç planı kurulumu |
-| `BloatwareAndServices.cs` | `[OptimizationCategory(typeof(BloatwareAndServicesOptimizerPage))]` | OEM uygulama engellemesi, 170+ Windows servis başlatma türü optimizasyonu |
-| `UserExperience.cs` | `[OptimizationCategory(typeof(UserExperienceOptimizerPage))]` | Menü gecikmeleri, görsel efektler, görev çubuğu animasyonları, şeffaflık, Başlat Menüsü web araması |
+| Dosya | Odak |
+|---|---|
+| `Performance.cs` | RAM ayarı, süreç önceliği, klavye gecikmesi, multimedya zamanlayıcı, erişilebilirlik kısayol tuşları |
+| `SecurityAndPrivacy.cs` | Telemetri, hata raporlama, reklam kimliği, konum, Copilot, etkinlik geçmişi, teslimat optimizasyonu vb. |
+| `Gpu.cs` | AMD/NVIDIA/Intel kayıt defteri ayarları, güç durumları, saat geçitleme, ASPM, asenkron çevirme |
+| `PowerManagement.cs` | Hazırda bekletme, hızlı başlangıç, USB seçici askıya alma, özel güç planı kurulumu |
+| `BloatwareAndServices.cs` | OEM önceden yüklü uygulama engelleme, Windows hizmeti başlangıç türü optimizasyonu |
+| `UserExperience.cs` | Menü gecikmeleri, görsel efektler, görev çubuğu animasyonları, saydamlık, Başlat Menüsü web araması |
+| `AI.cs` | Windows AI özellikleri (Recall, Click To Do) |
+
+Her kategori sınıfı, onu UI sayfasına bağlayan bir `[OptimizationCategory(typeof(SomePage))]` özniteliği taşır.
-### Adım Adım: Mevcut Bir Kategoriye Ekleme
+<h3 id="step-by-step-add-to-existing-category">Adım Adım: Mevcut Kategoriye Ekleme</h3>
-En uygun kategori dosyasını seçin ve içine yerleştirilmiş bir sınıf ekleyin:
+En uygun kategori dosyasını seçin ve iç içe bir sınıf ekleyin:
```csharp
[OptimizationCategory(typeof(PerformanceOptimizerPage))]
@@ -228,7 +285,8 @@ public class Performance : IOptimizationCategory
[Optimization(
Id = "a1b2c3d4-...", // YENİ bir GUID oluşturun
Risk = OptimizationRisk.Safe, // Safe / Moderate / Risky
- Tags = OptimizationTags.Performance // Etiketler — | ile birleştirin
+ Tags = OptimizationTags.Performance, // Bayraklar — | ile birleştirin
+ Condition = typeof(Windows11Condition) // İsteğe bağlı ("Koşul Sistemi"ne bakın)
)]
public class MyNewTweak : BaseOptimization
{
@@ -236,156 +294,304 @@ public class Performance : IOptimizationCategory
IProgress<ProcessingProgress> progress,
OptimizationContext context)
{
- // 1. Sistem değişiklikleri yapmak için statik sağlayıcıları kullanın
+ // 1. Sistem değişiklikleri için statik sağlayıcıları kullanın
RegistryService.Write(new RegistryItem(
@"HKLM\SOFTWARE\Something", "ValueName", 1));
- // 2. Async işlemleri await ile bekleyin
+ // 2. Asenkron işlemleri await edin — bu UI iş parçacığını serbest bırakır
await ServiceProcessService.ChangeServiceStartupTypeAsync(
new ServiceItem("SomeService", ServiceStartupType.Disabled));
- // 3. Sonucu çevresel ExecutionScope'tan döndürün
+ // 3. Çevresel ExecutionScope'tan sonucu döndürün
return CompleteFromScope();
}
}
}
```
-### Temel Kurallar
+<h3 id="key-rules">Temel Kurallar</h3>
| Kural | Detay |
|---|---|
-| **`Id` yeni bir GUID olmalıdır** | Geri alma dosyası adlandırmasında kullanılır. PowerShell'de `[guid]::NewGuid()` ile oluşturun. |
-| **`BaseOptimization`'ı genişletin** | `Name`, `ShortDescription`, `RiskVisual`, `TagDisplays`'i otomatik sağlar |
-| **`async Task<ApplyResult>` kullanın** | Servis sağlayıcıları asenkrondur — `await` kullanın |
-| **`CompleteFromScope()` döndürün** | `ApplyResult`'u kaydedilen adımlardan türetir |
-| **İlerlemeyi raporlayın** | `progress.Report(new ProcessingProgress { ... })` |
-| **Tüm istisnaları yakalamayın** | `ExecutionScope` başarı/başarısızlığı izler |
-| **Manuel geri alma adımı oluşturmayın** | Statik sağlayıcılar bunu `ExecutionScope.RecordStep()` ile otomatik yapar |
-| **`context.Logger` kullanın** | Tanılama bilgilerini kaydetmek için |
-| **`context.Snapshot`'ı kontrol edin** | `SystemSnapshot` RAM, GPU, CPU bilgisi sağlar |
-
-### Mevcut Servis Sağlayıcıları
-
-| Servis | Önemli Metotlar | Açıklama |
+| **`Id` yeni bir GUID olmalı** | Geri alma dosyası adlandırma ve uygulanma durumu takibi için kullanılır. PowerShell'de `[guid]::NewGuid()` ile oluşturun. |
+| **`BaseOptimization`'dan türetin** | Öznitelik + yerelleştirme anahtarlarından `Name`, `ShortDescription`, `RiskVisual`, `TagDisplays` sağlar. |
+| **`OwnerType` otomatik atanır** | Keşif bunu ayarlar — kendiniz ayarlamayın. |
+| **`async Task<ApplyResult>` kullanın** | Hizmet sağlayıcıları asenkrondur — UI'nın duyarlı kalması için `await` edin. |
+| **`CompleteFromScope()` döndürün** | Çevresel `ExecutionScope`'a kaydedilen adımlardan `ApplyResult` türetir. `ApplyResult`'ı elle oluşturmayın. |
+| **İlerlemeyi bildirin** | UI diyaloğunu güncellemek için `progress.Report(new ProcessingProgress { ... })` kullanın. |
+| **Tüm istisnaları yakalamayın** | Yukarı yayılsın. `ExecutionScope` başarı/başarısızlığı izler; `OptimizationService` istisnaları işler. |
+| **Geri alma adımlarını elle oluşturmayın** | Statik sağlayıcı hizmetler bunu `ExecutionScope.RecordStep()` ile otomatik yapar. |
+| **`context.Logger` kullanın** | Önemli tanılama bilgileri için günlük kaydı sağlar. |
+| **`context.Snapshot` kullanın** | `OptimizationContext.Snapshot` (`SystemSnapshot`) RAM, GPU, CPU, OS bilgisi verir. Koşullu mantık için kullanın. |
+| **`context.StreamService` kullanın** | Uzak kaynakları (örn. güç planları) indiren optimizasyonlar için. |
+| **Gerekirse `Condition` bildirin** | Windows sürümü veya donanımla kapılayın — [Koşul Sistemi](#the-condition-system) bölümüne bakın. |
+
+<h3 id="available-service-providers">Mevcut Hizmet Sağlayıcılar</h3>
+
+Bu **statik** sınıflar günlük kaydı, hata işleme ve otomatik geri alma adımı kaydını yönetir.
+
+| Hizmet | Temel Metotlar | Neden Kullanılır |
|---|---|---|
-| **`RegistryService`** | `Write()`, `Read<T>()`, `DeleteValue()`, `CreateSubKey()`, `DeleteSubKeyTree()`, `KeyExists()` | Kayıt defteri okuma/yazma/silme. Orijinal değerleri yedekler. |
-| **`ShellService`** | `CMDAsync()`, `PowerShellAsync()`, `CMD()`, `PowerShell()` | CMD/PowerShell komutları. `revertCommand` parametresi alabilir. |
-| **`ScheduledTaskService`** | `DisableTask()`, `EnableTask()`, `IsTaskEnabled()`, `DeleteTask()` | Windows Zamanlanmış Görevlerini yönetir. |
-| **`ServiceProcessService`** | `ChangeServiceStartupTypeAsync()`, `GetStartupTypeAsync()` | Windows Hizmetlerini yönetir. |
+| **`RegistryService`** | `Write()`, `Read<T>()`, `DeleteValue()`, `CreateSubKey()`, `DeleteSubKeyTree()`, `KeyExists()`, `CleanupEmptyKeys()` | Kayıt defteri anahtarlarını oku/yaz/sil. Geri alma için orijinal değerleri yedekler. params dizisiyle toplu yazmayı destekler. |
+| **`ShellService`** | `CMDAsync()`, `PowerShellAsync()`, `CMD()` (senkron), `PowerShell()` (senkron) | CMD veya PowerShell komutları çalıştırır. Asenkron sürümleri tercih edin. Geri alma için isteğe bağlı `revertCommand` parametresi. Standart dışı çıkış kodları için `ShellPolicy`'ye bakın. |
+| **`ScheduledTaskService`** | `DisableTask()`, `EnableTask()`, `IsTaskEnabled()`, `DeleteTask()`, `GetAllTasks()`, `RegisterTask()`, `RunTask()`, `StopTask()` | Windows Zamanlanmış Görevlerini yönetir. |
+| **`ServiceProcessService`** | `ChangeServiceStartupTypeAsync()`, `GetStartupTypeAsync()` | Windows Hizmetlerini yönetir. Her zaman asenkron sürümleri kullanın. params dizisiyle toplu değişikliği destekler. |
-Kullanım örnekleri:
+> **params ile birden çok öğe kabul eden metotlar**: Çoğu yazma/değiştirme metodu bir params dizisi kabul eder (örn. `RegistryService.Write(item1, item2, item3)`). Bu, birden çok ayrı çağrıdan daha verimlidir.
+
+Örnek kullanım:
```csharp
-// Çoklu kayıt defteri yazma
+// Senkron kayıt defteri yazma — birden çok öğeyi tek seferde
RegistryService.Write(
new RegistryItem(@"HKLM\...", "Value1", 1),
new RegistryItem(@"HKLM\...", "Value2", 0)
);
+RegistryService.DeleteValue(new RegistryItem(@"HKCU\...", "OldValue"));
-// Çoklu asenkron servis değişikliği
+// Asenkron hizmet değişiklikleri — birden çok hizmeti tek seferde
await ServiceProcessService.ChangeServiceStartupTypeAsync(
new ServiceItem("DiagTrack", ServiceStartupType.Disabled),
new ServiceItem("dmwappushservice", ServiceStartupType.Disabled)
);
-// Geri alma komutu ile shell komutu
+// Geri alma komutuyla asenkron kabuk komutu
var result = await ShellService.CMDAsync(
"powercfg /h off",
- "powercfg /h on" // geri alma için saklanır
+ "powercfg /h on" // geri alma komutu saklanır
+);
+
+// Asenkron PowerShell
+var usbStates = await ShellService.PowerShellAsync(
+ "Get-CimInstance -Namespace root\\wmi -ClassName MSPower_DeviceEnable"
);
```
-### Yeni Kategori Oluşturma ve Yardımcı Sınıflar
+<h3 id="handling-async">Asenkron İşlemleri Yönetme</h3>
+
+Tüm optimizasyonların `async`/`await`'e ihtiyacı yoktur. Optimizasyonunuz yalnızca senkron kayıt defteri yazma yapıyorsa (asenkron çağrı yok), `Task.FromResult()` döndürebilirsiniz:
-Yalnızca optimizasyonlarınız mevcut kategorilere uymuyorsa. Aşırı spesifik kategorilerden kaçının.
+```csharp
+public override Task<ApplyResult> ApplyAsync(
+ IProgress<ProcessingProgress> progress,
+ OptimizationContext context)
+{
+ RegistryService.Write(new RegistryItem(@"HKLM\...", "Value", 1));
+ context.Logger.LogInformation("Applied tweak");
+ return Task.FromResult(CompleteFromScope());
+}
+```
+
+Ancak herhangi bir asenkron sağlayıcı (hizmet, kabuk, görev) kullanıyorsanız her zaman `await` edin:
+
+```csharp
+public override async Task<ApplyResult> ApplyAsync(...)
+{
+ await ServiceProcessService.ChangeServiceStartupTypeAsync(...);
+ return CompleteFromScope();
+}
+```
+
+<h3 id="new-category">Yeni Kategori Oluşturma</h3>
+
+Yalnızca optimizasyonlarınız hiçbir mevcut kategoriye uymuyorsa. Aşırı spesifik kategorilerden kaçının.
+
+1. `Domain/Optimizations/Categories/YourCategory.cs` oluşturun.
+2. `IOptimizationCategory` uygulayın.
+3. `[OptimizationCategory(typeof(YourPage))]` uygulayın — bir XAML sayfasına da ihtiyacınız olacak ([Yeni Özellikler Geliştirme](#building-new-features) bölümüne bakın).
+4. Kategorinin doğru sıralanması için `Domain/UI/OptimizationCategoryOrder.cs` içindeki `OptimizationCategoryOrder` enum'una bir üye ekleyin.
+5. XAML sayfası `App.xaml.cs` içindeki `services.AddAllOptimizationPages()` ile otomatik kaydedilir.
+
+<h3 id="helper-base-class">Optimizasyon Yardımcı Taban Sınıfı Oluşturma</h3>
+
+Birkaç optimizasyon aynı yapıyı paylaşıyorsa (algılanan GPU'lar üzerinde yinelenen GPU ayarları gibi), soyut bir ara sınıf oluşturun:
+
+```csharp
+public abstract class GpuRegistryOptimization : BaseOptimization
+{
+ protected abstract GpuVendor Vendor { get; }
+ protected abstract IReadOnlyList<RegistryItem> CreateItems(string registryPath);
-1. `Domain/Optimizations/Categories/YourCategory.cs` oluşturun
-2. `IOptimizationCategory` uygulayın
-3. `[OptimizationCategory(PageType = typeof(YourPage))]` ekleyin
-4. `Domain/UI/OptimizationCategoryOrder.cs`'e yeni üye ekleyin
-5. XAML sayfası `App.xaml.cs`'deki `services.AddAllOptimizationPages()` ile otomatik kaydedilir
+ public override Task<ApplyResult> ApplyAsync(...)
+ {
+ foreach (var gpu in context.Snapshot.Gpus.Where(g => g.Vendor == Vendor))
+ {
+ var path = $@"HKLM\...\{index:D4}";
+ RegistryService.Write(CreateItems(path).ToArray());
+ }
+ return Task.FromResult(CompleteFromScope());
+ }
+}
+```
-Birden fazla optimizasyon aynı yapıyı paylaşıyorsa soyut bir ara sınıf oluşturun (örn. `Gpu.cs`'deki `GpuRegistryOptimization`).
+AMD, NVIDIA ve Intel alt sınıflarıyla gerçek bir örnek için `Domain/Optimizations/Categories/Gpu.cs` dosyasına bakın.
-### Yerelleştirme Anahtarları
+<h3 id="localization-keys-optimization">Yerelleştirme Anahtarları</h3>
-Her optimizasyon `Translations.resx` içinde girdilere ihtiyaç duyar:
+Her optimizasyonun `Translations.resx` içinde girdileri olmalıdır. Anahtarlar katı bir kuralı izler:
```
-Optimizer.{KategoriAdı}.{OptimizasyonAnahtarı}.Name
-Optimizer.{KategoriAdı}.{OptimizasyonAnahtarı}.ShortDescription
-Optimizer.{KategoriAdı}.{OptimizasyonAnahtarı}.Progress.{ÖzelAnahtar}
-Optimizer.{KategoriAdı}.{OptimizasyonAnahtarı}.Error.{ÖzelAnahtar}
+Optimizer.{CategoryName}.{OptimizationKey}.Name
+Optimizer.{CategoryName}.{OptimizationKey}.ShortDescription
+Optimizer.{CategoryName}.{OptimizationKey}.Progress.{CustomKey}
+Optimizer.{CategoryName}.{OptimizationKey}.Error.{CustomKey}
```
+Burada `CategoryName` = kategori sınıf adı (örn. `Performance`), `OptimizationKey` = iç içe sınıf adı.
+
> [!IMPORTANT]
-> **Çeviriler zorunludur**. En azından `Translations.resx`'e (İngilizce) giriş ekleyin.
+> **Çeviriler zorunludur**. Bu anahtarları eklemeyi atlarsanız, uygulama `"Optimizer.Performance.MyNewTweak.Name"` gibi ham anahtar dizeleri gösterir. En azından `Translations.resx` (İngilizce) içine girdi ekleyin.
---
-# Özelleştirme Ayarı Oluşturma
+<h1 id="creating-a-customize-setting">Özelleştirme Ayarı Oluşturma</h1>
-Özelleştirme ayarları, Windows ayarlarını AÇIK/KAPALI yapan UI kontrolleridir. `Domain/Customize/Categories/` dizininde bulunurlar.
+Özelleştirme ayarları, Windows ayarlarını AÇIK/KAPALI duruma getiren UI kontrolleridir (anahtar düğmeler, açılır menüler, sayı girişleri). `Domain/Customize/Categories/` içinde bulunurlar.
-### Özelleştirme Kategorileri
+<h3 id="customize-categories">Özelleştirme Kategorileri</h3>
-| Dosya | Öznitelik | Odak Noktası |
-|---|---|---|
-| `Desktop.cs` | `[CustomizeCategory(PageType = typeof(DesktopFeatureCategory))]` | Masaüstü simgeleri, kısayol okları |
-| `Preferences.cs` | `[CustomizeCategory(PageType = typeof(PreferencesFeatureCategory))]` | Görev çubuğu, widget'lar, karanlık mod, dosya uzantıları, gizli dosyalar, pano geçmişi |
-| `Gaming.cs` | `[CustomizeCategory(PageType = typeof(GamingFeatureCategory))]` | Oyun Modu, Game Bar, fare ivmesi, GPU zamanlaması |
-| `SystemFeatures.cs` | `[CustomizeCategory(PageType = typeof(SystemFeatureCategory))]` | Num Lock, Geliştirici Modu, Uzun Yollar, pil yüzdesi |
+Kategoriler `Domain/Customize/Categories/` içinde, her dosyada bir kategori olacak şekilde bulunur — yetkili liste için oraya bakın. Bu yazı yazıldığı sırada:
-### Basit Kayıt Defteri Anahtarı
+| Dosya | Odak |
+|---|---|
+| `Desktop.cs` | Masaüstü simgeleri (Bu PC, Geri Dönüşüm Kutusu, Ağ, Kullanıcı Dosyaları, Denetim Masası), genel göster/gizle, kısayol oku görünürlüğü |
+| `Preferences.cs` | Görev çubuğu hizalaması, widget'lar, görev görünümü, görevi sonlandırma, koyu mod, dosya uzantıları, gizli dosyalar, pano geçmişi, arama modu, saatte saniye, Bing araması, klasik bağlam menüsü |
+| `Gaming.cs` | Oyun Modu, Oyun Çubuğu, arka plan kaydı, fare hızlandırma, tam ekran optimizasyonları, GPU zamanlaması |
+| `SystemFeatures.cs` | Önyüklemede Num Lock, Geliştirici Modu, uzun yollar, pil yüzdesi |
+
+Her kategori sınıfı, onu UI sayfasına bağlayan bir `[CustomizeCategory(PageType = typeof(SomePage))]` özniteliği taşır.
+
+<h3 id="step-by-step-simple-registry-toggle">Adım Adım: Basit Kayıt Defteri Anahtarı</h3>
+
+Basit bir aç/kapat kayıt defteri anahtarı için taban sınıf tüm işi yapar:
```csharp
+private enum Sections { Taskbar, Widgets, Advanced }
+
[CustomizeSetting(
- Section = nameof(Sections.Taskbar),
- Icon = SymbolRegular.AlignCenter24,
- Recommendation = RecommendationState.On
+ Section = nameof(Sections.Taskbar), // UI'da ayarları gruplar
+ Icon = SymbolRegular.AlignCenter24, // Wpf.Ui.Controls.SymbolRegular'dan
+ Recommendation = RecommendationState.On, // On / Off / Depends / Experimental / None
+ Condition = typeof(Windows11Condition) // İsteğe bağlı uyumluluk koşulu
)]
public class TaskbarAlignment : BaseCustomizeSetting
{
protected override IEnumerable<RegistryToggle> RegistryToggles =>
- [new()
- {
- Path = @"HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced",
- Name = "TaskbarAl",
- OnValue = 0,
- OffValue = 1,
- DefaultValue = 1,
- }];
-
+ [
+ new()
+ {
+ Path = @"HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced",
+ Name = "TaskbarAl",
+ OnValues = [0], // anahtar AÇIK olduğundaki değer(ler)
+ OffValues = [1], // anahtar KAPALI olduğundaki değer(ler)
+ DefaultValue = 1, // varsayılan durum değeri (anahtar yokken kullanılır)
+ },
+ ];
+
+ // Bu ayar değiştikten sonra neyin yenilenmesi gerektiğini bildirin
protected override CustomizeRefreshScope RefreshScope =>
CustomizeRefreshScope.TaskbarSettings;
}
```
-### RegistryToggle Özellikleri
+<h3 id="registrytoggle-properties">RegistryToggle Özellikleri</h3>
| Özellik | Tür | Varsayılan | Açıklama |
|---|---|---|---|
-| `Path` | `string` | zorunlu | Tam kayıt defteri yolu |
+| `Path` | `string` | zorunlu | Tam kayıt defteri anahtarı yolu (örn. `@"HKCU\Software\..."`) |
| `Name` | `string` | zorunlu | Kayıt defteri değer adı |
-| `OnValue` | `object?` | `1` | "Açık" durumu değeri |
-| `OffValue` | `object?` | `0` | "Kapalı" durumu değeri |
-| `DefaultValue` | `object?` | `0` | Anahtar yoksa kullanılacak değer |
-| `IsOptional` | `bool` | `false` | Durum tespiti için gerekli değilse `true` |
-| `ValueKind` | `RegistryValueKind` | `DWord` | Kayıt defteri değer türü |
+| `OnValues` | `IReadOnlyList<object?>` | `[1]` | "Açık" durumunu temsil eden değerler. Listede `null` "anahtar yok = açık" demektir. |
+| `OffValues` | `IReadOnlyList<object?>` | `[0]` | "Kapalı" durumunu temsil eden değerler. Listede `null` "anahtar yok = kapalı" demektir. |
+| `DefaultValue` | `object?` | `0` | Anahtar yokken varsayılan durum değeri (Varsayılana Sıfırla için kullanılır). |
+| `IsOptional` | `bool` | `false` | `true` ise durum algılama için gerekli değildir. |
+| `ValueKind` | `RegistryValueKind` | `DWord` | Kayıt defteri değer türü (DWord, String, vb.). |
-### Kontrol Türleri
+**Durum algılama mantığı**: `GetState()` (`BaseCustomizeSetting` içinde) zorunlu olmayan `RegistryToggles`'ı toplar ve yalnızca **her** zorunlu anahtar `OnValues`'tan biriyle eşleştiğinde `true` döndürür.
-| Tür | Görüntü | Kullanım |
+<h3 id="control-types">Kontrol Türleri</h3>
+
+| Tür | Görüntülenen | Kullanım |
|---|---|---|
-| `Toggle` | Aç/Kapat anahtarı | Çoğu ayar (varsayılan) |
-| `Dropdown` | Açılır menü | Çoklu seçim |
-| `Option` | Radyo düğmesi | Birbirini dışlayan seçenekler |
-| `NumberInt` | Sayı girişi | Tamsayı değerleri |
-| `NumberFloat` | Ondalık giriş | Hassas değerler |
-| `String` | Metin girişi | Serbest metin |
+| `Toggle` | Aç/kapat anahtarı | Çoğu ayar (varsayılan) |
+| `Dropdown` | ComboBox | Çoklu seçim (örn. güç planı, arama kutusu modu, görev çubuğu hizalaması) |
+| `Option` | Radyo düğmesi grubu | Birbirini dışlayan görsel seçenekler (örn. sol/orta hizalama) |
+| `NumberInt` | Tam sayı metin girişi | Sayısal değerler (örn. saniyeler) |
+| `NumberFloat` | Ondalık metin girişi | Hassas değerler |
+| `String` | Metin girişi | Serbest biçimli metin |
+
+UI kontrolünü değiştirmek için `ControlType`'ı geçersiz kılın:
+
+```csharp
+public override CustomizeControlType ControlType => CustomizeControlType.Dropdown;
+```
+
+<h3 id="dropdown-with-options">Seçenekli Açılır Menü</h3>
+
+Açılır menü seçenekleri bir `RegistryBinding` bildirir, böylece taban sınıf mevcut değeri otomatik okuyabilir ve seçimde otomatik yazabilir. `Option()` yardımcısını kullanın:
+
+```csharp
+[CustomizeSetting(Section = nameof(Sections.Taskbar), Icon = SymbolRegular.AlignCenter24)]
+public class TaskbarAlignment : BaseCustomizeSetting
+{
+ private const string RegPath =
+ @"HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced";
+ private const string RegName = "TaskbarAl";
+
+ public override CustomizeControlType ControlType => CustomizeControlType.Dropdown;
+
+ // Option(key, regPath, regName, value) etiketini şuradan okur:
+ // Customize.{Category}.{Feature}.Options.{key}
+ protected override IReadOnlyList<SettingOption>? GetOptions() =>
+ [Option("Center", RegPath, RegName, 1), Option("Left", RegPath, RegName, 0)];
+
+ protected override CustomizeRefreshScope RefreshScope =>
+ CustomizeRefreshScope.TaskbarSettings;
+}
+```
-### Özel Mantık (GetStateAsync / ApplyAsync)
+**Birden çok** kayıt defteri değerine dokunan seçenekler için açık bağlamalar geçirin:
+
+```csharp
+protected override IReadOnlyList<SettingOption>? GetOptions() =>
+[
+ Option("On", 1,
+ new RegistryBinding(@"HKCU\...\Key1", "ValueA", 1),
+ new RegistryBinding(@"HKCU\...\Key2", "ValueB", "enabled", RegistryValueKind.String)),
+ Option("Off", 0,
+ new RegistryBinding(@"HKCU\...\Key1", "ValueA", 0),
+ new RegistryBinding(@"HKCU\...\Key2", "ValueB", "disabled", RegistryValueKind.String)),
+];
+```
+
+Taban sınıf mevcut değeri bağlamalardan okur, canlı değer hiçbir bildirilen seçenekle eşleşmediğinde yalnızca bellek içi bir **"Özel"** (veya **"Ayarlanmadı"**) yedeği gösterir ve seçilen seçeneğin tüm bağlamalarını yazar. Yaygın durum için özel bir `ApplyAsync` gerekmez.
+
+<h3 id="dynamic-options">Dinamik Seçenekler (Platforma Duyarlı)</h3>
+
+Seçenekleri Windows sürümüne göre koşullu gösterebilirsiniz:
+
+```csharp
+protected override IReadOnlyList<SettingOption>? GetOptions()
+{
+ if (Shared.IsWindows11OrGreater)
+ return
+ [
+ Option("Hidden", RegPath, RegName, 0),
+ Option("Icon", RegPath, RegName, 1),
+ Option("IconAndLabel", RegPath, RegName, 2),
+ Option("SearchBox", RegPath, RegName, 3),
+ ];
+ return
+ [
+ Option("Hidden", RegPath, RegName, 0),
+ Option("Icon", RegPath, RegName, 1),
+ Option("SearchBox", RegPath, RegName, 2),
+ ];
+}
+```
+
+<h3 id="custom-logic-override">Özel Mantık (GetStateAsync / ApplyAsync'i Geçersiz Kılma)</h3>
+
+Basit kayıt defteri anahtarı olmayan ayarlar için (örn. fare hızlandırma 3 kayıt defteri değerini birleştirir):
```csharp
[CustomizeSetting(
@@ -397,6 +603,7 @@ public class MouseAcceleration : BaseCustomizeSetting
{
private const string Path = @"HKCU\Control Panel\Mouse";
+ // İzlenen yollar, dış değişiklikler olduğunda UI'nın otomatik yenilenmesini sağlar
protected override IReadOnlyList<string> GetWatchedRegistryPaths() => [Path];
public override Task<bool> GetStateAsync()
@@ -418,338 +625,784 @@ public class MouseAcceleration : BaseCustomizeSetting
RegistryService.Write(new RegistryItem(Path, "MouseSpeed", isOn ? "1" : "0"));
RegistryService.Write(new RegistryItem(Path, "MouseThreshold1", isOn ? "6" : "0"));
RegistryService.Write(new RegistryItem(Path, "MouseThreshold2", isOn ? "10" : "0"));
- await ExecutePostActionAsync();
+
+ if (NeedsPostAction)
+ await ExecutePostActionAsync();
}
protected override CustomizeRefreshScope RefreshScope => CustomizeRefreshScope.Default;
}
```
-### Öneri Sistemi
+> `ApplyAsync`'i geçersiz kıldığınızda, **kendiniz** `await ExecutePostActionAsync()` çağırmalısınız (`NeedsPostAction` ile korunur). Taban sınıf bunu yalnızca varsayılan `RegistryToggles` tabanlı ve açılır menü bağlama tabanlı yollar için otomatik yapar.
+
+<h3 id="state-detection-retry">Yeniden Denemeli Durum Algılama</h3>
+
+Bir değer uygulandıktan sonra UI `GetStateWithRetryAsync()` çağırır (`GetStateAsync()` değil). Bu metot:
+
+1. Durumu `maxRetries` (varsayılan 3) kez, denemeler arasında `delayMs` (varsayılan 80ms) bekleyerek okur.
+2. Ardışık iki okuma aynı değerde anlaştığında (yakınsama kontrolü) döner.
+3. Denemeler tükendiğinde son okunan değere düşer.
+
+Bu, yazma sonrası kayıt defteri otururken UI'nın bayat değerler göstermesini önler.
+
+<h3 id="non-registry-deps">Kayıt Defteri Dışı Bağımlılıklarla Özel Mantık</h3>
+
+Gömülü kaynak çıkarmayı içeren ayarlar için (kısayol oklarını boş bir simgeyle değiştirmek gibi):
+
+```csharp
+public override async Task ApplyAsync(object? value)
+{
+ var isOn = value is bool b && b;
+ if (isOn)
+ {
+ RegistryService.DeleteValue(new RegistryItem(Path, "29"));
+ }
+ else
+ {
+ var outputPath = Path.Combine(Shared.AssetsDirectory, nameof(Desktop), "blank.ico");
+ EmbeddedResourceHelper.TryExtract("Icons.blank.ico", outputPath);
+ RegistryService.Write(new RegistryItem(Path, "29", outputPath));
+ }
+ await ExecutePostActionAsync();
+}
+```
+
+Gömülü kaynakları derlemeden diske çıkarmak için `EmbeddedResourceHelper.TryExtract(resourceName, outputPath)` kullanın.
+
+<h3 id="recommendation-system">Öneri Sistemi</h3>
Her özelleştirme ayarı bir öneri bildirebilir:
```csharp
-[CustomizeSetting(
- ...,
- Recommendation = RecommendationState.On // On / Off / Depends / Experimental / None
-)]
+[CustomizeSetting(..., Recommendation = RecommendationState.On)]
+// Mevcut: On, Off, Depends, Experimental, None
```
-| Durum | Anlamı |
-|---|---|
-| `On` | AÇILMASI önerilir — sistemi iyileştirir |
-| `Off` | KAPATILMASI önerilir — sistemi iyileştirir |
-| `Depends` | Kullanıcının ihtiyaçlarına bağlıdır |
-| `Experimental` | Kararsız olabilir, dikkatli kullanın |
-| `None` (varsayılan) | Öneri gösterilmez |
+- **`On`**: AÇIK önerilir — sistemi iyileştirir
+- **`Off`**: KAPALI önerilir — sistemi iyileştirir
+- **`Depends`**: Kullanıcının özel ihtiyaçlarına/yapılandırmasına bağlıdır
+- **`Experimental`**: Kararsız olabilir, dikkatli kullanın
+- **`None`** (varsayılan): Öneri gösterilmez
+
+Yerelleştirme anahtarıyla isteğe bağlı bir neden ekleyin: `Customize.{Category}.{Feature}.Recommendation.Reason`.
-### Ne Zaman Ne Geçersiz Kılınır
+<h3 id="what-to-override-per-pattern">Desene Göre Geçersiz Kılınacaklar</h3>
-| Senaryo | Geçersiz Kıl |
+| Senaryo | Geçersiz Kılma |
|---|---|
| Basit kayıt defteri anahtarı | `RegistryToggles` + `RefreshScope` |
-| Çoklu kayıt defteri | `RegistryToggles` (hepsini listele) |
-| Açılır menü/Seçenekler | `ControlType`, `Options`, `ApplyAsync`, `CurrentValue` |
-| Çoklu değer mantığı | `GetStateAsync()` + `ApplyAsync()` + `GetWatchedRegistryPaths()` |
-| Kayıt defteri olmayan ayar | `GetStateAsync()` + `ApplyAsync()` (tamamen özel) |
-| Dinamik seçenekler | `Options` getter'ını koşullu yap |
-| Yakınsama ile durum tespiti | `GetStateWithRetryAsync()` (yerleşik — geçersiz kılmayın) |
-| Gömülü kaynak çıkarma | `EmbeddedResourceHelper.TryExtract()` içinde `ApplyAsync` |
+| Birden çok kayıt defteri anahtarı (örn. Oyun Modu: 2 değer) | `RegistryToggles` (hepsini listeleyin) |
+| Açılır menü / seçenekler | `ControlType` → `Dropdown` + `Option(...)` bağlamalarıyla `GetOptions()` |
+| Çok değerli mantık (örn. fare hızlandırma: 3 değer) | `GetStateAsync()` + `ApplyAsync()` + `GetWatchedRegistryPaths()` |
+| Kayıt defteri etkileşimi olmayan ayar | `GetStateAsync()` + `ApplyAsync()` (tamamen özel) |
+| Özel yenileme davranışı | `RefreshScope` (yalnızca bayraklar) veya `ExecutePostActionAsync()` (tam geçersiz kılma) |
+| Yakınsamalı durum algılama | `GetStateWithRetryAsync()` (yerleşik — geçersiz kılmayın) |
+| Windows sürümüne göre dinamik seçenekler | `GetOptions()`'ı koşullu mantıkla geçersiz kılın |
+| Gömülü kaynak çıkarma | Özel `ApplyAsync` içinde `EmbeddedResourceHelper.TryExtract()` |
+| Uyumluluk kapısı | `[CustomizeSetting]` özniteliğinde `Condition = typeof(...)` |
+
+<h3 id="create-a-new-customize-category">Yeni Kategori Oluşturma</h3>
+
+1. `Domain/Customize/Categories/YourCategory.cs` oluşturun.
+2. `[CustomizeCategory(PageType = typeof(YourPage))]` ile `ICustomizeCategory` uygulayın.
+3. `Domain/UI/CustomizeOrder.cs` içindeki `CustomizeOrder` enum'una bir üye ekleyin.
+4. XAML sayfasını oluşturun (`UI/Pages/Customize/Categories/` içinde yeni bir sınıf).
+5. Sayfa `App.xaml.cs` içindeki `services.AddAllCustomizeCategoryPages()` ile otomatik kaydedilir.
+
+<h3 id="localization-keys-customize">Özelleştirme Ayarları için Yerelleştirme Anahtarları</h3>
+
+```
+Customize.{CategoryName}.{SettingKey}.Name
+Customize.{CategoryName}.{SettingKey}.Description
+Customize.{CategoryName}.{SettingKey}.Options.{OptionKey} (SettingOption kullanılıyorsa)
+Customize.{CategoryName}.{SettingKey}.Recommendation.Reason (Recommendation != None ise)
+Customize.{CategoryName}.Section.{SectionName} (bölüm başlıkları için)
+```
+
+---
+
+<h1 id="the-condition-system">Koşul Sistemi</h1>
+
+Koşullar, bir optimizasyonu veya özelleştirme ayarını bir uyumluluk kontrolünün arkasına kapılamanıza olanak tanır; böylece UI, çalışmayacak bir şeyi uygulamak yerine "bu, sisteminizde desteklenmiyor" diyebilir.
-### Yerelleştirme Anahtarları (Özelleştirme)
+<h3 id="core-concepts">Temel Kavramlar</h3>
+Koşullar `Domain/Conditions/` içinde bulunur ve `Services/Conditions/` içindeki statik `ConditionEvaluator` tarafından değerlendirilir.
+
+| Parça | Amaç |
+|---|---|
+| `ICondition` | Sözleşme: `ConditionResult Evaluate(SystemSnapshot snapshot)`. Uygulamaların public parametresiz yapıcıya ihtiyacı vardır (yansıma ile örneklenirler). |
+| `ConditionBase` | Paylaşılan yardımcılara sahip isteğe bağlı taban sınıf (örn. OS derleme numarası ayrıştırmak için `TryGetOsBuild`). |
+| `ConditionResult` | Sonuç: `Available`, `Unsupported(title, description)` veya `Error()`. Yerelleştirilmiş metin sağlayıcılar üzerinden tembel çözülür. |
+| `ConditionState` | `Available`, `Unsupported`, `Error`. |
+| `ConditionValidation` | Keşif sırasında `Condition = typeof(...)` meta verisini doğrular; yanlış yapılandırmalar başlangıçta hızlıca başarısız olur. |
+| `WindowsBuilds` | OS derleme numarası sabitleri (örn. `Windows11`, `Windows11_24H2`). |
+
+**Açık kalma ilkesi**: bir öğeyi yalnızca `Unsupported` engeller, o da yalnızca zaten uygulanmadıysa (veya kullanıcı gizlemediyse). `Error` ve doldurulmamış bir anlık görüntü hiçbir şeyi asla gizlemez — eksik donanım algılaması, kullanıcının hâlâ kullanabileceği seçenekleri kaldırmamalıdır.
+
+<h3 id="declaring-a-condition">Koşul Bildirme</h3>
+
+Her iki öznitelik de isteğe bağlı bir `Condition` kabul eder:
+
+```csharp
+// Optimizasyon
+[Optimization(Id = "...", Risk = OptimizationRisk.Safe,
+ Tags = OptimizationTags.Privacy | OptimizationTags.System,
+ Condition = typeof(Windows11_24H2OrGreaterCondition))]
+public class DisableRecall : BaseOptimization { ... }
+
+// Özelleştirme ayarı
+[CustomizeSetting(Section = ..., Icon = SymbolRegular.Grid24,
+ Condition = typeof(Windows11Condition))]
+public class TaskbarWidgets : BaseCustomizeSetting { ... }
```
-Customize.{KategoriAdı}.{AyarAnahtarı}.Name
-Customize.{KategoriAdı}.{AyarAnahtarı}.Description
-Customize.{KategoriAdı}.{AyarAnahtarı}.Options.{SeçenekAnahtarı}
-Customize.{KategoriAdı}.{AyarAnahtarı}.Recommendation.Reason
-Customize.{KategoriAdı}.Section.{BölümAdı}
+
+<h3 id="built-in-conditions">Yerleşik Koşullar</h3>
+
+Hazır koşullar `Domain/Conditions/BuiltIn/` içinde bulunur — tam ve güncel liste için o klasöre bakın. Örnekler:
+
+| Koşul | Eşleştiği |
+|---|---|
+| `Windows10Condition` / `Windows11Condition` | Derleme numarasına göre OS sürümü |
+| `Windows11_24H2OrGreaterCondition` | Windows 11 24H2 (derleme 26100) veya üstü |
+| `CpuBrandCondition` / `GpuBrandCondition` | CPU/GPU satıcısı (Intel, AMD, NVIDIA) |
+| `MinimumRamCondition` (taban) / `SixteenGbRamCondition` | Minimum kurulu RAM |
+| `RegistryKeyExistsCondition` | Bir kayıt defteri anahtarının varlığı |
+| `ServiceExistsCondition` | Bir Windows hizmetinin varlığı |
+| `RecallInstalledCondition` | Windows Recall'ın varlığı |
+
+<h3 id="writing-a-custom-condition">Özel Koşul Yazma</h3>
+
+```csharp
+public sealed class MyCondition : ConditionBase
+{
+ public override ConditionResult Evaluate(SystemSnapshot snapshot)
+ {
+ // ConditionBase.TryGetOsBuild "22631.xxxx" -> 22631 olarak ayrıştırır
+ if (TryGetOsBuild(snapshot, out var build) && build >= 22000)
+ return ConditionResult.Available;
+
+ return ConditionResult.Unsupported(
+ () => Loc.Instance["Condition.MyCondition.Title"],
+ () => Loc.Instance["Condition.MyCondition.Description"]);
+ }
+}
```
+Yönergeler:
+
+- Sistem geçtiğinde **`Available`**; geçmediğinde **`Unsupported(title, description)`** döndürün.
+- Beklenmeyen hatalar için `ConditionResult.Error()` kullanın (veya fırlatın — `ConditionEvaluator` yakalar ve `Error`'a eşler). Hatalar engellemez.
+- Kullanıcıya dönük metni yerelleştirme sağlayıcılarının arkasına koyun (`() => Loc.Instance[...]`), böylece okuma sırasında güncel kültür kazanır.
+- Sınıfa bir **public parametresiz yapıcı** verin (hiç eklemeyin veya açık boş bir yapıcı ekleyin).
+
+<h3 id="how-conditions-evaluated">Nasıl Değerlendirilir</h3>
+
+1. Keşif, bildirilen türün `ICondition` uyguladığını ve oluşturulabilir olduğunu doğrulamak için `ConditionValidation.Validate(...)` çağırır.
+2. UI, `ConditionEvaluator.Evaluate(conditionType, snapshot, logger)` çağırır; bu, koşul örneklerini önbelleğe alır ve asla fırlatmaz.
+3. `Unsupported` sonucu olan öğeler engellenmiş/desteklenmeyen durumda gösterilir (kullanıcı oturum için gizleyebilir). Zaten uygulanmış öğeler asla yeniden engellenmez.
+
---
-# Yenileme Kapsamı Sistemi
+<h1 id="the-refresh-scope-system">Yenileme Kapsamı Sistemi</h1>
+
+Bir özelleştirme ayarı durum değiştirdiğinde, farklı Windows yüzeyleri farklı yenileme stratejilerine ihtiyaç duyar. `CustomizeRefreshScope` `[Flags]` enum'u bunu ayrıntılı olarak kontrol eder.
-`CustomizeRefreshScope` [Flags] enum'u Windows yüzeylerinin nasıl yenileneceğini kontrol eder.
+<h3 id="available-flags">Mevcut Bayraklar</h3>
-| Üye | Değer | Etki |
+| Üye | Değer | Etki | P/Invoke |
+|---|---|---|---|
+| `None` | `0` | Yenileme yok | — |
+| `Settings` | `1 << 0` | Uygulamalar kayıt defterini yeniden okusun diye `WM_SETTINGCHANGE` yayınla | `SendMessageTimeout(HWND_BROADCAST, WM_SETTINGCHANGE)` |
+| `Associations` | `1 << 1` | Dosya ilişkilendirmelerinin veya simge önbelleğinin değiştiğini kabuğa bildir | `SHChangeNotify(SHCNE_ASSOCCHANGED)` |
+| `Desktop` | `1 << 2` | Masaüstü simge listesinin (`SysListView32`) yeniden çizilmesini zorla | `LVM_REFRESH` + `LVM_UPDATE` |
+| `Taskbar` | `1 << 3` | Görev çubuğu hedefli `WM_SETTINGCHANGE` ("TraySettings") yayınla | `SendMessageTimeout(HWND_BROADCAST, WM_SETTINGCHANGE, "TraySettings")` |
+| `PolicyUpdate` | `1 << 4` | Kullanıcı başına parametreler için `SPIF_SENDCHANGE` ile `SystemParametersInfo` it | `SystemParametersInfo` |
+| `Theme` | `1 << 5` | Tema/görsel ayarlar için `WM_THEMECHANGED` yayınla | `SendMessageTimeout(HWND_BROADCAST, WM_THEMECHANGED)` |
+| `DesktopIconCache` | `1 << 6` | HideIcons kayıt defterini değiştir + `WM_COMMAND 0x7402` masaüstüne gönder | Kayıt defteri okuma + `SendMessage(Progman, WM_COMMAND)` |
+
+<h3 id="named-composites">Adlandırılmış Bileşimler</h3>
+
+| Ad | Bileşim | Kullanım |
|---|---|---|
-| `None` | `0` | Yenileme yok |
-| `Settings` | `1 << 0` | `WM_SETTINGCHANGE` yayınla |
-| `Associations` | `1 << 1` | Dosya ilişkilendirme değişikliklerini bildir |
-| `Desktop` | `1 << 2` | Masaüstü simge listesini yenile |
-| `Taskbar` | `1 << 3` | Görev çubuğu `WM_SETTINGCHANGE` yayınla |
-| `PolicyUpdate` | `1 << 4` | `SystemParametersInfo` gönder |
-| `Theme` | `1 << 5` | `WM_THEMECHANGED` yayınla |
-| `DesktopIconCache` | `1 << 6` | Masaüstü simge önbelleğini yenile |
+| `Default` | `Settings \| Associations` | Genel gezgin düzeyi ayarlar |
+| `DesktopIcons` | `Settings \| Desktop` | Bireysel masaüstü simgelerini göster/gizle (Bu PC, Geri Dönüşüm Kutusu) |
+| `HideDesktopIcons` | `Settings \| DesktopIconCache` | Genel "Tüm masaüstü simgelerini gizle" anahtarı |
+| `TaskbarSettings` | `Settings \| Taskbar` | Görev çubuğu hizalaması, widget'lar, görev görünümü, görevi sonlandır |
+| `ExplorerView` | `Settings \| Associations \| PolicyUpdate` | Dosya uzantıları, gizli dosyalar, kompakt görünüm |
-**Bileşikler**: `Default` (`Settings | Associations`), `DesktopIcons` (`Settings | Desktop`), `TaskbarSettings` (`Settings | Taskbar`), `ExplorerView` (`Settings | Associations | PolicyUpdate`).
+<h3 id="how-refresh-flows">Yenileme Akışı</h3>
-`ApplyAsync`'i geçersiz kılarsanız, `await ExecutePostActionAsync()` çağırmayı unutmayın.
+```
+Ayar anahtarı → BaseCustomizeSetting.ApplyAsync(value)
+ ├─ RegistryToggles'ı yazar (varsa) veya seçilen seçeneğin bağlamalarını uygular
+ ├─ NeedsPostAction'ı kontrol eder (RefreshScope != None ise true)
+ └─ Task.Run → ExecutePostActionAsync()
+ ├─ Her CustomizeRefreshScope bayrağını kontrol eder
+ ├─ SystemRefreshService metotlarını (P/Invoke) çağırır
+ └─ Win32 bildirimlerini Windows'a gönderir
+```
+
+`ApplyAsync`'i geçersiz kılarsanız, **kendiniz** `await ExecutePostActionAsync()` çağırmalısınız (yukarıdaki örneklere bakın). Taban sınıf bunu yalnızca varsayılan `RegistryToggles` tabanlı ve açılır menü bağlama tabanlı uygulama için otomatik yapar.
---
-# Yeni Özellikler Geliştirme
+<h1 id="building-new-features">Yeni Özellikler Geliştirme</h1>
+
+Yeni bir sayfa veya araç eklemek istiyorsanız (örn. bir "Ağ Monitörü"):
-1. **Önce GitHub Sorunu (Issue) açın**
-2. **Uygulama sırası**: Service → ViewModel → XAML Page → `App.xaml.cs`'e kaydet
+1. **Önce bir GitHub Sorunu açın** — özelliği, kullanım durumunu ve tasarımı açıklayın. Bakımcı geri bildirimini bekleyin.
+2. **Uygulama sırası**:
```csharp
-// DI Kayıt Deseni
+// 1. Hizmet katmanı: Services/UI veya Services/System/YourService.cs
+public class YourService(ILogger<YourService> logger) { ... }
+
+// 2. ViewModel: UI/ViewModels/Pages/YourViewModel.cs
+// ViewModel'i genişletir (ObservableValidator + INavigationAware)
+
+// 3. XAML Sayfası: UI/Pages/YourPage.xaml (+ kod arkası)
+
+// 4. App.xaml.cs'e singleton olarak kaydet
services.AddSingleton<YourViewModel>();
services.AddSingleton<YourPage>();
+```
+
+- ViewModel'ler ve Sayfalar `App.xaml.cs` içinde **singleton olarak kaydedilmelidir**.
+- Gezinme WPF UI (`INavigationService`) tarafından yönetilir.
+- Mevcut desenleri izleyin — `DashboardPage`, `OptimizePage`, `BloatwarePage`, `DiskCleanupPage`, `ScheduledTasksPage`, `StartupManagerPage` vb.'ye bakın.
+
+<h3 id="di-registration-pattern">DI Kayıt Deseni (App.xaml.cs'ten)</h3>
+
+```csharp
+// Sayfalar + ViewModel'ler — özellik başına bir çift
+services.AddSingleton<DashboardViewModel>();
+services.AddSingleton<DashboardPage>();
+
+services.AddSingleton<OptimizeViewModel>();
+services.AddSingleton<OptimizePage>();
+
+services.AddSingleton<SettingsViewModel>();
+services.AddSingleton<SettingsPage>();
+
+services.AddSingleton<BloatwareViewModel>();
+services.AddSingleton<BloatwarePage>();
+
+services.AddSingleton<DiskCleanupViewModel>();
+services.AddSingleton<DiskCleanupPage>();
+
+services.AddSingleton<StartupManagerViewModel>();
+services.AddSingleton<StartupManagerPage>();
+
+services.AddSingleton<ScheduledTasksViewModel>();
+services.AddSingleton<ScheduledTasksPage>();
+
+// Customize
+services.AddSingleton<CustomizeViewModel>();
+services.AddSingleton<CustomizePage>();
+
+// Otomatik sayfa kaydı (yansıma kullanan kategori sayfaları)
+services.AddAllCustomizeCategoryPages(); // [CustomizeCategory] özniteliklerini tarar
+services.AddAllOptimizationPages(); // [OptimizationCategory] özniteliklerini tarar
+
+// Yöneticiler
services.AddSingleton<ConfigManager>();
services.AddSingleton<RevertManager>();
+
+// Hizmetler
services.AddSingleton<OptimizationRegistry>();
+services.AddSingleton<CustomizeRegistry>();
services.AddSingleton<OptimizationService>();
+services.AddSingleton<BloatwareService>();
+services.AddSingleton<DiskCleanupService>();
+services.AddSingleton<StartupManagerService>();
services.AddSingleton<SystemInfoService>();
services.AddSingleton<StreamService>();
services.AddSingleton<UpdaterService>();
+services.AddSingleton<IRegistryWatcher, RegistryWatcher>();
```
-### Sistem Servisleri
+> Bu, oryantasyon için bir anlık görüntüdür — güncel kayıtlar için `App.xaml.cs` kaynaktır. Ayrıca başlangıç çağrılarına dikkat edin: `ShellService.Init(appOptionsMonitor)` ve `WmiHelper.Initialize()`.
-| Servis | Amaç |
+<h3 id="system-services">Sistem Hizmetleri Referansı</h3>
+
+| Hizmet | Amaç |
|---|---|
-| `SystemInfoService` | `SystemSnapshot` ile CPU, RAM, GPU bilgisi |
-| `StreamService` | Uzak kaynakları indirme |
-| `UpdaterService` | GitHub sürümlerini kontrol etme |
-| `RegistryWatcher` | Kayıt defteri değişikliklerini izleme |
-| `BloatwareService` | Ön yüklemeli AppX paketlerini listeleme |
-| `DiskCleanupService` | Disk temizlik taraması |
-| `StartupManagerService` | Başlangıç uygulamalarını yönetme |
+| `SystemInfoService` | `OptimizationContext` ve koşul sisteminin kullandığı `SystemSnapshot`'ı (CPU, RAM, GPU, OS, disk) sağlar. |
+| `StreamService` | Uzak kaynakları (örn. güncellenmiş güç planı dosyaları) indirir. `OptimizationContext.StreamService` ile kullanılır. |
+| `UpdaterService` | Güncellemeler için GitHub sürümlerini kontrol eder. Dashboard'da güncelleme istemi gösterir. |
+| `RegistryWatcher` | Kayıt defteri anahtarlarını dış değişiklikler için izler ve UI'ya yenileme bildirir. `IRegistryWatcher` uygular. |
+| `BloatwareService` | Önceden yüklü AppX paketlerini listeler, Güvenli/Dikkatli/Tehlikeli olarak sınıflandırır. |
+| `DiskCleanupService` | Diskleri temizlik fırsatları için tarar (geçici dosyalar, önbellekler, günlükler). |
+| `StartupManagerService` | Başlangıç uygulamalarını ve zamanlanmış görevleri listeler ve yönetir. |
+| `ConditionEvaluator` | Uyumluluk koşullarını değerlendirmek için statik giriş noktası ([Koşul Sistemi](#the-condition-system) bölümüne bakın). |
---
-# Geri Alma Sistemi
+<h1 id="revert-system">Geri Alma Sistemi</h1>
-Her uygulanan optimizasyon `%localappdata%\optimizerDuck\Revert\{optimizationId}.json` yolunda bir JSON dosyası oluşturur.
+Uygulanan her optimizasyon `%localappdata%\optimizerDuck\Revert\{optimizationId}.json` konumunda bir JSON dosyası oluşturur.
-### Nasıl Çalışır
+<h3 id="how-it-works-tr">Nasıl Çalışır</h3>
```
-ApplyAsync() → ExecutionScope.Begin() → Provider çağrıları otomatik adım kaydeder → CompleteFromScope() → RevertManager.SaveRevertDataAsync()
+ApplyAsync()
+ │
+ ├─ ExecutionScope.Begin(optimization, logger) ← çevresel AsyncLocal kapsamı oluşturur
+ │
+ ├─ RegistryService.Write(...) ← RegistryRevertStep'i otomatik kaydeder
+ ├─ ServiceProcessService.ChangeServiceStartupTypeAsync(...) ← ServiceRevertStep'i otomatik kaydeder
+ ├─ ShellService.CMDAsync(...) ← ShellRevertStep'i otomatik kaydeder
+ │
+ ├─ CompleteFromScope() → ApplyResult ← kaydedilen adımlardan türetilir
+ │
+ └─ ExecutionScope dispose → RevertManager.SaveRevertDataAsync()
```
-### Adım Türleri
+<h3 id="scope-variants-tr">Kapsam Varyantları</h3>
+
+| Metot | Amaç |
+|---|---|
+| `ExecutionScope.Begin(optimization, logger)` | Gerçek bir uygulama için kalıcı kapsam oluşturur. |
+| `ExecutionScope.BeginForLogging(logger)` | Yalnızca günlük — adımları kaydeder ama geri alma verisini asla kalıcılaştırmaz. |
+| `ExecutionScope.BeginForCapture(logger)` | Yeniden deneme için: `OptimizationId = Guid.Empty` ile adımları yakalar, daha sonra gerçek kapsama yeniden atanır. |
+
+<h3 id="step-types-tr">Adım Türleri</h3>
-| Adım Türü | Kaydedilen | Otomatik Oluşturan |
+| Adım Türü | Kaydettiği | Otomatik Oluşturan |
|---|---|---|
-| **`RegistryRevertStep`** | Orijinal kayıt defteri değeri | `RegistryService.Write()`, `DeleteValue()`, vb. |
-| **`ServiceRevertStep`** | Orijinal servis başlatma türü | `ServiceProcessService.ChangeServiceStartupTypeAsync()` |
-| **`ScheduledTaskRevertStep`** | Orijinal görev durumu | `ScheduledTaskService.DisableTask()`, `EnableTask()` |
-| **`ShellRevertStep`** | Geri alma komutu | `ShellService.CMDAsync()` — `revertCommand` parametresi |
-| **`UsbPowerRevertStep`** | USB güç ayarları | USB optimizasyonları (manuel `ExecutionScope.RecordStep()`) |
+| **`RegistryRevertStep`** | Değişiklikten önceki orijinal kayıt defteri değeri | `RegistryService.Write()`, `DeleteValue()`, `CreateSubKey()`, `DeleteSubKeyTree()` |
+| **`ServiceRevertStep`** | Orijinal hizmet başlangıç türü | `ServiceProcessService.ChangeServiceStartupTypeAsync()` |
+| **`ScheduledTaskRevertStep`** | Orijinal görev durumu (etkin/devre dışı) | `ScheduledTaskService.DisableTask()`, `EnableTask()` |
+| **`ShellRevertStep`** | Değişikliği tersine çeviren kabuk komutu | `ShellService.CMDAsync()`, `PowerShellAsync()` — bir `revertCommand` parametresi geçirin |
+| **`UsbPowerRevertStep`** | USB güç ayarları (cihaz başına) | USB ile ilgili optimizasyonlar (elle `ExecutionScope.RecordStep()` ile) |
-Geri alma komutu ekleme:
+<h3 id="revert-command">Kabuk Çağrılarına Geri Alma Komutu Ekleme</h3>
+
+`CMDAsync` veya `PowerShellAsync` çağırırken, geri alma için saklanan `revertCommand` parametresini isteğe bağlı geçebilirsiniz:
```csharp
-await ShellService.CMDAsync("powercfg /h off", "powercfg /h on"); // revertCommand
+// "powercfg /h on" bu değişikliği tersine çevirmek için saklanır
+await ShellService.CMDAsync("powercfg /h off", "powercfg /h on");
+```
+
+<h3 id="revert-data-format-tr">Geri Alma Veri Formatı</h3>
+
+```json
+{
+ "SchemaVersion": 1,
+ "OptimizationId": "guid",
+ "OptimizationName": "DisableTelemetry",
+ "AppliedAt": "2026-06-02T12:00:00Z",
+ "Steps": [
+ { "Index": 0, "Type": "Registry", "Data": { "..." } },
+ null, // null boşluğu = bu dizindeki başarısız adım
+ { "Index": 2, "Type": "Service", "Data": { "..." } }
+ ]
+}
```
-### Önemli Detaylar
+<h3 id="key-details-tr">Temel Detaylar</h3>
-- **Uygulanma durumu**: Dosyanın diskteki varlığından çıkarılır
-- **Atomik yazma**: `.tmp` + `File.Replace()`
-- **Eşzamanlı erişim**: Dosya başına `SemaphoreSlim` kilitleri, 30 saniye zaman aşımı
-- **Ters sırada geri alma**: Son uygulanan = ilk geri alınan
-- **Kısmi başarı**: Bazı adımlar başarısız olsa bile devam eder
-- **Yeniden deneme**: `OptimizationService.RetryFailedStepsAsync()`
-- **Yeni adım türü ekleme**: `Domain/Revert/Steps/`'e `IRevertStep` uygulayan sınıf + `FromData(JObject)` metodu
+- **Uygulanma durumu**, diskte dosya varlığından çıkarılır (`RevertManager.IsAppliedAsync(id)`).
+- **Atomik yazma**: `.tmp` dosyasına yazar, sonra `File.Replace()` — çökme güvenli.
+- **Eşzamanlı erişim**: dosya başına `SemaphoreSlim` kilitleri yarış koşullarını önler; 30 saniye zaman aşımı.
+- **`ExecutionScope`** çevresel adım takibi için `AsyncLocal<ExecutionScope?>` kullanır. Parametrelerle bağlam geçirmeye gerek yok.
+- **Geri alma adımları ters sırada çalışır** (en son uygulanan = ilk geri alınan).
+- **Kısmi başarı**: bazı adımlar başarısız olsa bile geri alma devam eder. Başarısız adımlara yeniden deneme eylemleri kaydedilir.
+- **Yeniden deneme**: `OptimizationService.RetryFailedStepsAsync()` tek tek başarısız adımları yeniden deneyebilir; `RecordStepAtIndex()` orijinal dizin düzenini korur.
+- **Upsert**: `RevertManager.UpsertRevertStepAtIndexAsync()` belirli dizinlerdeki geri alma adımlarını ekleyebilir/değiştirebilir (yeniden deneme sırasında kullanılır).
+- **Adım kaydı**: Geri alma adımı serisizleştirme yansıma tabanlı `_stepRegistry` kullanır — yeni adım türleri, `IRevertStep` uygulayıp statik bir `FromData(JObject)` metoduyla otomatik kaydolur.
+
+> **Önemli**: Sağlayıcı hizmetleri (`RegistryService.Write`, `ShellService.CMDAsync` vb.) çağırdığınızda geri alma adımları otomatik kaydedilir. Özel bir sağlayıcı uygulamadığınız sürece (`UsbPowerRevertStep` gibi) geri alma adımlarını elle oluşturMAYIN.
---
-# Test Etme
+<h1 id="testing">Test Etme</h1>
-Testler **xUnit v3** kullanır ve gerçek G/Ç ile entegrasyon tarzı bir yaklaşım benimser.
+Testler **xUnit v3** kullanır ve gerçek I/O ile entegrasyon tarzı bir yaklaşım izler.
-### Test Kalıpları
+<h3 id="test-patterns-tr">Test Desenleri</h3>
-| Kalıp | Detay |
+| Desen | Detay |
|---|---|
-| **Mock kütüphanesi yok** | Tüm test double'ları elle yazılmıştır |
-| **Gerçek G/Ç** | Gerçek dosya sistemi, kayıt defteri, süreç yürütme |
-| **Temizlik** | `try/finally` veya `IDisposable` |
-| **İsimlendirme** | `{Method}_{Scenario}_{ExpectedResult}` |
-| **Loglama** | `NullLogger<T>.Instance` |
-
-```bash
-dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release
-```
+| **Mock kütüphanesi yok** | Tüm test ikizleri arayüzleri uygulayan elle yazılmış sınıflardır |
+| **Gerçek I/O** | Gerçek dosya sistemi (geri alma JSON dosyaları), gerçek kayıt defteri (`HKCU\Software\TestOptimizerDuck*`), gerçek süreç yürütme (CMD, PowerShell) |
+| **Temizlik** | Test artefakt temizliği için `try/finally` veya `IDisposable` kullanın |
+| **Adlandırma** | `{Method}_{Scenario}_{ExpectedResult}` — örn. `ApplyAsync_Success_PersistsRevertDataFile` |
+| **Günlük** | DI günlük parametreleri için `NullLogger<T>.Instance` / `NullLoggerFactory.Instance` kullanın |
+| **STA iş parçacığı** | WPF bileşenleri içeren testler `RunInStaThreadAsync` yardımcısını (STA iş parçacığı + `TaskCompletionSource`) kullanmalıdır |
-### Test Yapısı
+<h3 id="test-structure-tr">Test Yapısı</h3>
```
optimizerDuck.Test/
├── Common/Helpers/
-│ └── SystemRefreshServiceTests.cs
├── Domain/
-│ ├── Customize/BaseCustomizeSettingTests.cs
-│ ├── Exceptions/StepExecutionExceptionTests.cs
-│ └── Revert/Steps/RevertStepSerializationTests.cs, ScheduledTaskRevertStepTests.cs
+│ ├── Customize/
+│ ├── Exceptions/
+│ ├── Optimizations/
+│ └── Revert/Steps/
└── Services/
- ├── ApplyRevertComprehensiveTests.cs
- ├── OptimizationServiceTests.cs, OptimizationServiceIntegrationTests.cs
- ├── RevertManagerTests.cs
- ├── RegistryServiceTests.cs, ServiceProcessServiceTests.cs, ShellServiceTests.cs
- └── RegistryWatcherTests.cs, SystemInfoServiceTests.cs
+ ├── Managers/
+ ├── OptimizationServices/
+ └── ApplyRevertComprehensiveTests.cs
```
-### CI Entegrasyonu
+Uygulamanın yapısını yansıtın: `Services/OptimizationServices/` testleri `Services/OptimizationServices/` içine, etki alanı modeli testleri eşleşen `Domain/` alt dizinine gider.
+
+<h3 id="running-tests-tr">Testleri Çalıştırma</h3>
```bash
+# Derlemeden sonra
+dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build
+
+# Derleme + testi tek adımda
+dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release
+
+# Ada göre tek bir test çalıştır
+dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build --filter "FullyQualifiedName~TestName"
+```
+
+<h3 id="ci-integration-tr">CI Entegrasyonu</h3>
+
+CI hattı (`.github/workflows/ci.yml`) şunları çalıştırır:
+
+```bash
+dotnet restore optimizerDuck.slnx
+dotnet build optimizerDuck.slnx --configuration Release --no-restore
dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build --blame-hang --blame-hang-timeout 30s
```
+`--blame-hang --blame-hang-timeout 30s` bayrakları, testlerin 30 saniyeden uzun süre asılı kalmamasını sağlar; bu, gerçek Windows hizmetleriyle etkileşime giren entegrasyon tarzı testler için kritiktir.
+
+<h3 id="writing-tests-tr">Sağlayıcı Hizmetler için Test Yazma</h3>
+
+```csharp
+public class MyOptimizationTests
+{
+ [Fact]
+ public async Task ApplyAsync_Success_PersistsRevertDataFile()
+ {
+ var optimization = new TestOptimization
+ {
+ ApplyImpl = _ =>
+ {
+ ExecutionScope.RecordStep("Test", "Step 1", true);
+ return Task.FromResult(ApplyResult.True());
+ },
+ };
+
+ var service = CreateService();
+ var result = await service.ApplyAsync(optimization, new Progress<ProcessingProgress>());
+
+ Assert.Equal(OptimizationSuccessResult.Success, result.Status);
+ }
+
+ private static OptimizationService CreateService()
+ {
+ return new OptimizationService(
+ new RevertManager(NullLogger<RevertManager>.Instance, NullLoggerFactory.Instance),
+ NullLoggerFactory.Instance,
+ new SystemInfoService(NullLogger<SystemInfoService>.Instance),
+ new StreamService(NullLogger<StreamService>.Instance),
+ null!,
+ NullLogger<OptimizationService>.Instance
+ );
+ }
+}
+```
+
---
-# Kodlama Standartları
+<h1 id="coding-standards">Kodlama Standartları</h1>
+
+<h3 id="language-features-tr">Dil Özellikleri</h3>
-| Kural | Değer |
+| Özellik | Kullanım | Notlar |
+|---|---|---|
+| Dosya kapsamlı ad alanları | Evet | `namespace X.Y;` |
+| Koleksiyon ifadeleri | Evet | Boş için `[]`, listeler için `[item1, item2]` |
+| Birincil yapıcılar | Evet | Hizmetlerde ve basit tiplerde kullanılır |
+| Örtük using'ler | Evet | `.csproj` içinde etkin |
+| Null atanabilir referans tipleri | Evet | `<Nullable>enable</Nullable>` — null'ları düzgün işleyin |
+| Uzantı metotları (`extension(T type)`) | Evet | C# 13 özelliği, `OptimizationTagsToDisplay` içinde kullanılır |
+
+<h3 id="naming-conventions-tr">Adlandırma Kuralları</h3>
+
+| Öğe | Kural | Örnek |
+|---|---|---|
+| Sınıflar, enum'lar, arayüzler, metotlar, özellikler | `PascalCase` | `RegistryService`, `ApplyAsync` |
+| Özel alanlar | `_camelCase` | `_lastError` |
+| Yerel değişkenler, parametreler | `camelCase` | `progress`, `serviceName` |
+| Asenkron metotlar | `*Async` eki | `ChangeServiceStartupTypeAsync`, `CMDAsync` |
+| Sabitler | `PascalCase` / `_PascalCase` | `MaxRetries` / `_defaultTimeout` |
+
+<h3 id="formatting-tr">Biçimlendirme</h3>
+
+| Ayar | Değer |
|---|---|
-| Sınıflar, metotlar, özellikler | `PascalCase` |
-| Private alanlar | `_camelCase` |
-| Yerel değişkenler | `camelCase` |
-| Async metotlar | `*Async` soneki |
-| Girinti | 4 boşluk |
+| Girinti | 4 boşluk (sekme yok) |
+| Satır sonu | LF |
+| Kodlama | UTF-8 |
| Maksimum satır uzunluğu | 100 karakter |
-| Biçimlendirici | **CSharpier** — `dotnet csharpier .` |
-| **String'leri hardcode etmeyin** | `Translations.KeyName` veya `Loc.Instance["Key"]` kullanın |
-| **Yorumları minimumda tutun** | |
-| **Null yapılabilir referans türleri** | Etkin (`<Nullable>enable</Nullable>`) |
+| Sondaki boşluk | Kırpılır |
+| Sondaki yeni satır | Zorunlu |
+| Biçimlendirici | **CSharpier** — commit öncesi `dotnet csharpier .` çalıştırın |
+| CA1416 | `.editorconfig` ile susturulur — tüm kod Windows'a özeldir |
+
+<h3 id="code-style-tr">Kod Stili</h3>
+
+- **Sabit kodlanmış dize yok** — her zaman `Translations.KeyName` veya `Loc.Instance["Key"]`
+- **Yorumları seyrek tutun** — mevcut kodda neredeyse hiç yok. Gereksiz yorum eklemeyin.
+- **Yeni bağımlılıklar yerine mevcut kütüphaneleri tercih edin**.
+- **Büyük yeniden düzenlemeler yerine küçük, odaklı değişiklikleri tercih edin**.
+- **Makineye özgü yolları veya sırları asla commit etmeyin**.
+
+<h3 id="dependency-injection-tr">Bağımlılık Enjeksiyonu</h3>
-### Hata Yönetimi
+- Hizmetler, ViewModel'ler ve Sayfalar `App.xaml.cs` içinde singleton olarak kaydedilir.
+- Yapıcı enjeksiyonu kullanın: `public class Foo(Bar bar, Baz baz)` veya `public class Foo(ILogger<Foo> logger)`.
+- Statik sağlayıcı hizmetler (`RegistryService`, `ShellService`, `ScheduledTaskService`, `ServiceProcessService`) enjekte EDİLMEZ — doğrudan erişin.
+- Test ikizleri elle yazılır (mock kütüphanesi yok).
+
+<h3 id="error-handling-tr">Hata İşleme</h3>
| Katman | Uygulama |
|---|---|
-| **Optimizasyonlar** | `ApplyResult.False("sebep")` döndürün, fırlatmayın |
-| **Sağlayıcı servisler** | try/catch + `ExecutionScope.LogError` |
-| **ViewModel'ler** | Komut işleyicilerinde yakalayın, snackbar gösterin |
-| **Genel** | App.xaml.cs'de 3 genel hata işleyici. Çökmeler `%localappdata%\optimizerDuck\Crashes\crash_*.log`'a kaydedilir |
+| **Optimizasyonlar** | Fırlatmak yerine `ApplyResult.False("reason")` döndürün. Adım düzeyi başarısızlık takibini `ExecutionScope`'a bırakın. |
+| **Sağlayıcı hizmetler** | Sistem çağrılarını try/catch ile sarın, hataları günlükleyin. Başarısız adımları yeniden deneme eylemleriyle kaydedin. |
+| **ViewModel'ler** | Komut işleyicilerinde istisnaları yakalayın, kullanıcı dostu snackbar'lar gösterin. |
+| **Koşullar** | `ConditionResult.Error()` döndürün veya fırlatın — `ConditionEvaluator` yakalar ve `Error`'a (asla engellemez) eşler. |
+| **Yapmayın** | İşleyemeyeceğiniz istisnaları yakalamayın. Tüm istisnaları sessizce yutmayın. |
+
+<h3 id="global-error-handling-tr">Genel Hata İşleme</h3>
+
+`App.xaml.cs` üç genel istisna işleyicisi kaydeder:
+
+- `AppDomain.CurrentDomain.UnhandledException` — ölümcül istisnaları yakalar
+- `TaskScheduler.UnobservedTaskException` — gözlemlenmemiş görev istisnalarını yakalar
+- `DispatcherUnhandledException` — işlenmemiş UI iş parçacığı istisnalarını yakalar
+
+Tüm çökme ayrıntıları `%localappdata%\optimizerDuck\Crashes\crash_*.log` konumuna kaydedilir.
---
-# Yerelleştirme
+<h1 id="localization">Yerelleştirme</h1>
-Tüm kullanıcı metinleri `Resources/Languages/Translations.resx` içindedir.
+<h3 id="resx-files-tr">RESX Dosyaları</h3>
-### Mevcut Diller (11 dil + İngilizce)
+Kullanıcıya dönük tüm dizeler `Resources/Languages/Translations.resx` (İngilizce varsayılan) içinde bulunur. C# içinde güçlü tipli `Translations` sınıfını, dinamik arama için `Loc.Instance["Key"]` kullanın.
+
+- `Translations.Designer.cs`'i **doğrudan düzenlemeyin** — otomatik oluşturulur.
+- [ResXManager](https://marketplace.visualstudio.com/items?itemName=TomEnglert.ResXManager) (VS) veya Rider'ın yerleşik kaynak düzenleyicisini kullanın.
+- `{0}`, `{1}` gibi biçim parametrelerini tam olarak koruyun.
+- Dizeleri kısa tutun — bazı UI kartlarının genişlik sınırları vardır.
+
+<h3 id="available-locales-tr">Mevcut Yerel Ayar</h3>
+
+Uygulama **15'ten fazla dil** ile gelir ve liste büyümeye devam eder. Burada listelemek (bayatlayacağı için) yerine şunlara bakın:
+
+- **Yerel ayar dosyalarının kendisi**: `optimizerDuck/Resources/Languages/` — her dil için bir `Translations.{locale}.resx`, İngilizce varsayılan olarak da `Translations.resx`.
+- **Kayıt listesi**: `UI/ViewModels/Pages/SettingsViewModel.cs` içindeki `Languages` — UI'da gösterilen dillerin yetkili listesidir.
+
+<h3 id="adding-a-new-language-tr">Yeni Dil Ekleme</h3>
+
+1. `Translations.{locale}.resx` (örn. `Translations.de-DE.resx`) dosyasını, `Translations.resx` ile aynı tüm anahtarlarla oluşturun.
+2. Dili `UI/ViewModels/Pages/SettingsViewModel.cs` içine kaydedin:
-| Dil | Dosya |
-|---|---|
-| English | `Translations.resx` (varsayılan) |
-| Vietnamese | `Translations.vi-VN.resx` |
-| Spanish | `Translations.es-ES.resx` |
-| French | `Translations.fr-FR.resx` |
-| Geleneksel Çince | `Translations.zh-TW.resx` |
-| Basitleştirilmiş Çince | `Translations.zh-CN.resx` |
-| Russian | `Translations.ru-RU.resx` |
-| Korean | `Translations.ko-KR.resx` |
-| Japanese | `Translations.ja-JP.resx` |
-| Polish | `Translations.pl-PL.resx` |
-| Turkish | `Translations.tr-TR.resx` |
-| Portuguese (Brazil) | `Translations.pt-BR.resx` |
-
-### Yeni Dil Ekleme
-
-1. `Translations.{locale}.resx` dosyasını oluşturun (tüm anahtarlarla)
-2. `SettingsViewModel.cs`'e kaydedin:
```csharp
new() { DisplayName = "Deutsch", Culture = new CultureInfo("de-DE") },
```
-XAML'de:
+<h3 id="hardcoded-string-rule-tr">Sabit Dize Kuralı</h3>
+
+**Asla dize sabit kodlamayın**. Her zaman şunları kullanın:
+
+```csharp
+// Güçlü tipli (önerilir)
+string title = Translations.Features_Desktop_Name;
+
+// Biçim argümanlarıyla
+string msg = string.Format(Translations.Dashboard_SystemInfo_Storage_DiskInfo, used, total, percent);
+
+// Dinamik anahtar arama (kural tabanlı anahtarlar için)
+string title = Loc.Instance[$"Optimizer.{category}.{key}.Name"];
+```
+
+XAML içinde:
+
```xml
+<!-- Argümansız -->
<ui:TextBlock Text="{ext:Loc Dashboard.Header.Title}" />
+
+<!-- Bağlı argümanlarla -->
+<ui:TextBlock Text="{ext:Loc Dashboard.UpdateInfoBar.Message, {Binding ViewModel.LatestVersion}}" />
```
---
-# Çekme İsteği Süreci (Pull Request Process)
+<h1 id="pull-request-process">Çekme İsteği Süreci</h1>
-1. **`master`'dan dal açın**: `feature/adiniz` veya `fix/issue-id`
-2. **Conventional Commits**: `feat:` (yeni özellik), `fix:` (hata düzeltme), `refactor:` (yeniden düzenleme), `docs:` (dokümantasyon), `test:` (test), `i18n:` (çeviri), `chore:` (bakım)
-3. **Göndermeden önce doğrulayın**:
+1. **`master`'dan dallanın** — asla doğrudan master üzerinde çalışmayın:
-```bash
-dotnet build optimizerDuck.slnx --configuration Release
-dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build
-dotnet csharpier .
-```
+ ```bash
+ git checkout -b feature/sizin-ozellik-adiniz
+ # veya
+ git checkout -b fix/sorun-numarasi
+ ```
+
+2. **Conventional Commits ile commit edin**:
+
+ | Önek | Ne Zaman Kullanılır |
+ |---|---|
+ | `feat:` | Yeni optimizasyonlar veya özellikler |
+ | `fix:` | Hata düzeltmeleri |
+ | `refactor:` | Davranış değişikliği olmadan kod yeniden yapılandırma |
+ | `docs:` | Dokümantasyon güncellemeleri |
+ | `test:` | Test ekleme veya düzeltme |
+ | `i18n:` | Çeviri güncellemeleri |
+ | `chore:` | Bakım, derleme yapılandırması, bağımlılıklar |
+
+3. **İtmeden önce doğrulayın**:
+
+ ```bash
+ # 1. Derle
+ dotnet build optimizerDuck.slnx --configuration Release
+
+ # 2. Test
+ dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build
+
+ # 3. Biçimlendir
+ dotnet csharpier .
+
+ # 4. git status'u kontrol edin — yalnızca amaçlanan dosyaların aşamalandığından emin olun
+ git status
+ git diff --cached
+ ```
+
+4. **PR'ı açın**:
+ - **Neyin** değiştiğini ve **neden** değiştiğini açıklayın.
+ - UI değişikliği içeren PR'lar **bir ekran görüntüsü içermelidir**.
+ - İlgili sorunları bağlayın: `Closes #42`.
+ - Hâlâ devam eden bir çalışmaysa taslak olarak işaretleyin.
-4. **PR açın**: Ne ve neden değişti? UI değişiklikleri varsa ekran görüntüsü ekleyin. İlgili Issue'ları `Closes #42` ile bağlayın.
+5. **İnceleme**: Bir bakımcı inceleyecektir. Geri bildirime açık olun ve hızlı yanıt verin.
-### PR Kontrol Listesi
+<h3 id="pr-checklist-tr">PR Kontrol Listesi</h3>
-- [ ] Kod mevcut kalıpları takip ediyor
-- [ ] Yerelleştirme anahtarları `Translations.resx`'e eklendi
+- [ ] Kod mevcut desenleri izliyor (keşif, öznitelikler, asenkron adlandırma)
+- [ ] Yerelleştirme anahtarları en azından `Translations.resx` içine eklendi
+- [ ] İlgiliyse koşullar bildirildi ([Koşul Sistemi](#the-condition-system) bölümüne bakın)
- [ ] `dotnet build` başarılı (0 hata)
-- [ ] `dotnet test` başarılı
+- [ ] `dotnet test` geçiyor (tüm testler yeşil)
- [ ] `dotnet csharpier .` çalıştırıldı
-- [ ] Hardcode string yok
-- [ ] Geri alma adımları kaydedildi (varsa)
-- [ ] UI değişiklikleri için ekran görüntüsü eklendi
+- [ ] Sabit kodlanmış dize yok
+- [ ] Geri alma adımları düzgün kaydedildi (geçerliyse)
+- [ ] UI değişiklikleri bir ekran görüntüsü içeriyor
---
-# Sorun (Issue) Yönergeleri
+<h1 id="issue-guidelines">Sorun (Issue) Yönergeleri</h1>
-- **Hata raporları**: Yeniden üretme adımları, beklenen/gerçek davranış, `%localappdata%\optimizerDuck\optimizerDuck.log` + sistem özellikleri
-- **Özellik istekleri**: Kullanım durumu, çözdüğü sorun, nasıl çalışması gerektiği
-- **Optimizasyon önerileri**: Kayıt defteri yolları, servis adları, CLI komutları, güvenilir kaynaklar
-- **Sorular**: GitHub Discussions veya [Discord](https://discord.gg/tDUBDCYw9Q)
+- **Hata raporları**: Hata Raporu şablonunu kullanın. Yeniden üretme adımlarını, beklenen ve gerçekleşen davranışı, `%localappdata%\optimizerDuck\optimizerDuck.log` günlüklerini + sistem özelliklerini ekleyin.
+- **Özellik istekleri**: Kullanım durumunu, çözdüğü sorunu ve nasıl çalışması gerektiğini açıklayın.
+- **Optimizasyon önerileri**: Kayıt defteri yollarını, hizmet adlarını veya CLI komutlarını ekleyin. Dokümantasyona veya güvenilir kaynaklara bağlantı verin.
+- **Sorular**: GitHub Discussions'ı kullanın veya [Discord](https://discord.gg/tDUBDCYw9Q) sunucusuna katılın.
---
-# SSS ve Sorun Giderme
+<h1 id="faq--troubleshooting">SSS ve Sorun Giderme</h1>
+
+<h3>Derleme "CA1416" hatalarıyla başarısız oluyor</h3>
+
+`.editorconfig` CA1416'yı susturur. Hâlâ görüyorsanız, master'dan en son `.editorconfig`'e sahip olduğunuzdan emin olun. Bu proje Windows'a özeldir — `SupportedOSPlatform` korumaları eklemeyin.
+
+<h3>Optimizasyonum UI'da görünmüyor</h3>
+
+Kontrol listesi:
+
+- Kategori sınıfı içinde **iç içe public bir sınıf** mı?
+- Kategori sınıfı `IOptimizationCategory` uyguluyor mu?
+- Optimizasyon sınıfı `BaseOptimization`'dan mı türüyor?
+- Bir `[Optimization(Id = "...", ...)]` özniteliği var mı?
+- Yerelleştirme anahtarları `Translations.resx` içine eklendi mi?
+- Optimizasyon kategorisi önceden yüklendi mi? (`OptimizationRegistry.IsPreloaded`'ı kontrol edin)
+- Bir `Condition` onu engelliyor mu? (Bir sonraki soruya bakın)
+
+<h3>Optimizasyonum/ayarım "desteklenmiyor" (engelli) olarak görünüyor</h3>
+
+- Öznitelikte bildirilen `Condition = typeof(...)` değerini kontrol edin.
+- Koşul türünün `ICondition` uyguladığını, somut olduğunu ve public parametresiz yapıcıya sahip olduğunu doğrulayın (`ConditionValidation` bunu başlangıçta zorlar).
+- Öğenin yalnızca **uygulanmadığında** engellendiğini unutmayın; uygulanan öğeler her zaman normal kartlarını gösterir.
+
+<h3>Özelleştirme ayarım görünmüyor</h3>
-### Derleme "CA1416" hatasıyla başarısız oluyor
-`.editorconfig` CA1416'yı susturur. Proje Windows'a özeldir.
+- `[CustomizeSetting(Section = ..., Icon = ...)]` var mı? (`Icon` zorunludur.)
+- `Section` değeri doğru yazıldı mı?
+- Kategori sınıfı doğru `[CustomizeCategory(PageType = ...)]` özniteliğini mi kullanıyor?
+- Bir `Condition` onu engelliyor mu?
-### Optimizasyon UI'da görünmüyor
-- Kategori içinde **iç içe public sınıf** mı?
-- Kategori `IOptimizationCategory` uyguluyor mu?
-- `BaseOptimization`'dan türetilmiş mi?
-- `[Optimization(Id = "...")]` özniteliği var mı?
-- Yerelleştirme anahtarları `Translations.resx`'e eklendi mi?
+<h3>Testten sonra geri alma veri dosyası yok</h3>
-### Özelleştirme ayarı görünmüyor
-- `[CustomizeSetting(Section = ..., Icon = ...)]` var mı?
-- `Section` yazımı doğru mu?
-- `[CustomizeCategory(PageType = ...)]` var mı?
+Geri alma verisini kontrol eden testler `%localappdata%\optimizerDuck\Revert\` içindeki dosyaları bekler. Test temizliği `finally` bloklarında çalışır — önermelerin (assertions) temizlikten önce çalıştığından emin olun.
-### UI donuyor
-`ApplyAsync`'te `async`/`await` kullandığınızdan emin olun. `.Result`/`.Wait()` UI'ı dondurur.
+<h3>Optimizasyon uygularken UI donuyor</h3>
+
+`ApplyAsync`'in, asenkron olan tüm sağlayıcı çağrıları (`ChangeServiceStartupTypeAsync`, `CMDAsync`, `PowerShellAsync`) için `async`/`await` kullandığından emin olun. `Task.FromResult` kullanıyor veya `.Result` / `.Wait()` ile blokluyorsanız UI iş parçacığı donar.
+
+<h3>GUID nasıl üretirim?</h3>
-### GUID nasıl oluşturulur?
```powershell
+# PowerShell
[guid]::NewGuid()
```
-### Çeviriler anahtar adı olarak görünüyor
-`Translations.resx`'e yerelleştirme anahtarları eklemeyi unuttunuz.
+```bash
+# Komut satırı (uuidgen mevcutsa)
+uuidgen
+```
+
+<h3>Çeviriler UI'da anahtar adları olarak görünüyor</h3>
+
+`Translations.resx` içine yerelleştirme anahtarlarını eklemeyi kaçırdınız. Beklenen anahtar desenleri için [Yerelleştirme](#localization) bölümüne bakın.
+
+<h3>Geri alırken "No revert data" hatası</h3>
+
+Optimizasyonun `Id` GUID'inin değişmediğini kontrol edin. Geri alma dosyaları `Id` ile anahtarlanır. GUID'i yeniden üretirseniz, daha önce uygulanan optimizasyonların eşleşen geri alma dosyaları kalmaz.
-### "Geri alma verisi yok" hatası
-Optimizasyonun `Id` GUID'inin değişmediğinden emin olun.
+<h3>Yeni bir geri alma adımı türü nasıl eklerim?</h3>
-### Yeni geri alma adım türü ekleme
-1. `Domain/Revert/Steps/`'e `IRevertStep` uygulayan sınıf oluşturun
-2. Statik `FromData(JObject data)` metodu ekleyin
-3. `ExecutionScope.RecordStep()` ile kaydedin
+1. `Domain/Revert/Steps/` içinde `IRevertStep` uygulayan yeni bir sınıf oluşturun.
+2. Serisizleştirme için statik bir `FromData(JObject data)` metodu ekleyin.
+3. `RevertManager`'ın yansıma tabanlı `_stepRegistry`'si onu otomatik keşfeder.
+4. `ExecutionScope.RecordStep()` ile `revertStep` parametresi olarak kaydedin.
-### Çökme güvenliği
-- Geri alma dosyaları atomik yazma kullanır (`.tmp` + `File.Replace`)
-- Çökme günlükleri: `%localappdata%\optimizerDuck\Crashes\crash_*.log`
-- App.xaml.cs'de 3 genel hata işleyici
+<h3>Uygulama çökme güvenliğini nasıl ele alır?</h3>
+
+- Geri alma dosyaları atomik yazma kullanır (`.tmp` + `File.Replace`).
+- Çökme günlükleri `%localappdata%\optimizerDuck\Crashes\crash_*.log` konumuna yazılır.
+- `WmiHelper.Initialize()` başlangıçta anormal sonlanma için WMI temizliği kaydeder.
+- `App.xaml.cs` 3 genel istisna işleyicisi kaydeder.
---
<div align="center">
-## Teşekkürler
+<h2 id="credits">Krediler</h2>
+
+Birleştirilmiş PR'ları olan katkıda bulunanlar sürüm notlarında listelenir. Bir modüle önemli ölçüde katkıda bulunursanız, dosya başlığının üstüne bir yazar etiketi ekleyebilirsiniz.
+
+---
+
+<h2 id="license">Lisans</h2>
+
+optimizerDuck'a katkıda bulunarak, katkılarınızın projenin [GPL v3 Lisansı](../../LICENSE) altında lisanslanacağını kabul etmiş olursunuz.
+
+---
-Katkıda bulunanlar sürüm notlarında listelenir.
+<p><i>optimizerDuck'ı daha iyi hale getirdiğiniz için teşekkürler.</i></p>
[![Contributors](https://contrib.rocks/image?repo=itsfatduck/optimizerDuck)](https://github.com/itsfatduck/optimizerDuck/graphs/contributors)
diff --git a/AGENTS.md b/AGENTS.md
index bb83536..d5c21cd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,7 +5,7 @@
- **Runs as admin**: `app.manifest` sets `requireAdministrator` UAC level. Tests that modify system settings or registry need admin too.
- **Solution format**: `.slnx` (not `.sln`).
- **Data directory**: `%LocalAppData%\optimizerDuck\` — holds revert files (`Revert/`), resources (`Resources/`), downloads (`Resources/Downloads/`), assets (`Resources/Assets/`), crash logs (`Crashes/`).
-- **Version**: Currently 2.24.2 (defined in `optimizerDuck.csproj`).
+- **Version**: Defined in `optimizerDuck.csproj` (`<Version>`). Don't hardcode it elsewhere; read it from the project file.
## Build, Test, Run Commands
- `dotnet restore optimizerDuck.slnx` — restore dependencies.
@@ -21,57 +21,68 @@
- `Domain/` — models, interfaces, attributes (no UI deps)
- `Abstractions/` — `IOptimization`, `ICustomizeSetting`, `IRevertStep`, `ICustomizeCategory`, `IOptimizationCategory`, `IWindow`
- `Attributes/` — `[Optimization]`, `[CustomizeSetting]`, `[OptimizationCategory]`, `[CustomizeCategory]`
+ - `Conditions/` — compatibility condition system: `ICondition`, `ConditionBase`, `ConditionResult`, `ConditionState`, `ConditionValidation`, `WindowsBuilds`, and `BuiltIn/` (Windows version, CPU/GPU brand, min RAM, registry-key/service existence conditions)
+ - `Exceptions/` — `StepExecutionException`
- `Execution/` — `ExecutionScope` (ambient `AsyncLocal`-based step tracking)
- `Customize/Categories/` — Desktop, Gaming, Preferences, SystemFeatures (nested setting classes)
- - `Optimizations/Categories/` — Performance, SecurityAndPrivacy, Gpu, PowerManagement, BloatwareAndServices, UserExperience (nested optimization classes)
- - `Optimizations/Models/` — `BaseOptimization`, `ApplyResult`, `OptimizationContext`
+ - `Optimizations/Categories/` — Performance, SecurityAndPrivacy, Gpu, PowerManagement, BloatwareAndServices, UserExperience, AI (nested optimization classes)
+ - `Optimizations/Models/` — `BaseOptimization`, `ApplyResult`, `OptimizationContext`, `OptimizationResult`, `OperationStepResult`
- `Optimizations/Models/Services/` — `RegistryItem`, `ServiceItem` (+ `ServiceStartupType`), `ShellResult`
- `Optimizations/Models/Bloatware/` — `AppXPackage`
- `Optimizations/Models/Cleanup/` — `CleanupItem`
- `Optimizations/Models/ScheduledTask/` — `ScheduledTaskModel`
- `Optimizations/Models/StartupManager/` — `StartupApp`, `StartupTask`
- - `Customize/Models/` — `BaseCustomizeSetting`, `RegistryToggle`, `CustomizeRefreshScope`, `SettingOption`, `CustomizeControlType`, `RecommendationState`, `CustomizeRecommendationResult`
+ - `Customize/Models/` — `BaseCustomizeSetting`, `RegistryToggle`, `RegistryBinding`, `CustomizeRefreshScope`, `SettingOption`, `CustomizeControlType`, `RecommendationState`, `CustomizeRecommendationResult`
- `Revert/` — `RevertData`, `RevertResult`
- `Revert/Steps/` — `RegistryRevertStep`, `ServiceRevertStep`, `ScheduledTaskRevertStep`, `ShellRevertStep`, `UsbPowerRevertStep`
- `Configuration/` — `AppSettings`
- `UI/` — enums: `OptimizationRisk`, `OptimizationTags` (flags), `OptimizationCategoryOrder`, `CustomizeOrder`, `OptimizationSuccessResult`, `OptimizationState` (ObservableObject with relative-time display), `RiskVisual`, `ProcessingProgress`, `LanguageOption`
- `Services/` — business logic:
+ - `Conditions/` — `ConditionEvaluator` (static, fail-open evaluation)
- `Configuration/` — `ConfigManager`, `LanguageManager`
- `Customize/` — `CustomizeRegistry` (reflection-based discovery)
- `Optimization/` — `OptimizationRegistry`, `OptimizationService`
- `Optimization/Providers/` — static: `RegistryService`, `ShellService` (+ `ShellPolicy`), `ScheduledTaskService`, `ServiceProcessService`
- `Revert/` — `RevertManager` (atomic file-based revert data persistence)
- - `System/` — `RegistryWatcher` (+ `IRegistryWatcher`), `SystemInfoService`, `StreamService`, `UpdaterService`
+ - `System/` — `RegistryWatcher` (+ `IRegistryWatcher`), `SystemInfoService` (defines `SystemSnapshot` + models), `StreamService`, `UpdaterService`, `CrossPageEventBus`, `CrossPageEvents`
- `UI/` — `BloatwareService`, `DiskCleanupService`, `StartupManagerService`
- `UI/` — XAML pages, ViewModels, windows, controls, dialogs, styles
- `Common/` — extensions, helpers, converters:
- - `Helpers/` — `Shared.cs` (constants, paths, SafeApps/CautionApps sets), `ReflectionHelper.cs`, `SystemRefreshService.cs` (P/Invoke for Windows refresh), `EmbeddedResourceHelper.cs`, `WmiHelper.cs`, `GitHubSourceHelper.cs`, `ThemeResource.cs`
- - `Converters/` — 20+ WPF value converters
+ - `Helpers/` — `Shared.cs` (constants, paths, SafeApps/CautionApps sets), `ReflectionHelper.cs`, `SystemRefreshService.cs` (P/Invoke for Windows refresh), `EmbeddedResourceHelper.cs`, `WmiHelper.cs`, `GitHubSourceHelper.cs`, `ThemeResource.cs`, `HttpClientFactory.cs`, `UiThread.cs`
+ - `Converters/` — WPF value converters (BooleanToVisibility, MBToGB, ...)
- `Extensions/` — `StringExtensions`, `CustomizePageRegistryExtensions`, `OptimizationPageRegistryExtensions`, `LanguageExtensions`
- `Resources/` — images, embedded assets, locale files
- - `Languages/` — `Translations.resx` (default) + 11 locale variants (vi-VN, es-ES, fr-FR, zh-TW, zh-CN, ru-RU, ko-KR, ja-JP, pl-PL, tr-TR, pt-BR)
+ - `Languages/` — `Translations.resx` (default English) + locale variants. Do **not** hardcode the list of languages; the authoritative lists are the files in this folder and `Languages` in `UI/ViewModels/Pages/SettingsViewModel.cs`.
- `optimizerDuck.Test/` — xUnit v3 tests (single test project with `InternalsVisibleTo`)
- Do **not** create top-level directories outside these two project folders.
## Key NuGet Packages
- `CommunityToolkit.Mvvm` 8.4.2 — MVVM source generators (`[ObservableProperty]`, `[RelayCommand]`)
- `WPF-UI` + `WPF-UI.DependencyInjection` 4.3.0 — Fluent Design controls + navigation
-- `Microsoft.Extensions.Hosting` 10.0.9 — DI / hosted service wiring
+- `Microsoft.Extensions.Hosting` + `Microsoft.Extensions.DependencyInjection` 10.0.10 — DI / hosted service wiring
- `Newtonsoft.Json` 13.0.4 — JSON serialization for revert data
-- `Serilog` 4.3.1 + sinks — structured logging
+- `Serilog` 4.4.0 + `Serilog.Extensions.Hosting` + `Serilog.Sinks.File` — structured logging
- `TaskScheduler` 2.12.2 — Windows scheduled task management
-- `System.Management.Automation` 7.6.3 — PowerShell host integration
+- `System.Management.Automation` 7.6.4 — PowerShell host integration
- `xunit.v3` 3.2.2 — test framework (with global using `Xunit` in test csproj)
+> Package versions live in `optimizerDuck.csproj` / `optimizerDuck.Test.csproj` — verify there rather than trusting this snapshot.
+
## Optimization & Customize Discovery (Reflection, No Manual Registration)
-- **New optimizations**: Create a **nested class** inside the relevant category class (e.g., `Domain/Optimizations/Categories/Performance.cs`), extend `BaseOptimization`, decorate with `[Optimization(Id = "guid", Risk = ..., Tags = ...)]`.
-- **New customize settings**: Same nesting pattern inside `Domain/Customize/Categories/`, extend `BaseCustomizeSetting`, decorate with `[CustomizeSetting(Section = ..., Icon = ..., Recommendation = ...)]`. `Icon` is required (`SymbolRegular` enum). `Section` can be a string or enum value. `Recommendation` can be `On`, `Off`, `Depends`, `Experimental`, or `None`.
+- **New optimizations**: Create a **nested class** inside the relevant category class (e.g., `Domain/Optimizations/Categories/Performance.cs`), extend `BaseOptimization`, decorate with `[Optimization(Id = "guid", Risk = ..., Tags = ..., Condition = typeof(...)?)]`.
+- **New customize settings**: Same nesting pattern inside `Domain/Customize/Categories/`, extend `BaseCustomizeSetting`, decorate with `[CustomizeSetting(Section = ..., Icon = ..., Recommendation = ..., Condition = typeof(...)?)]`. `Icon` is required (`SymbolRegular` enum). `Section` can be a string or enum value. `Recommendation` can be `On`, `Off`, `Depends`, `Experimental`, or `None`.
- **Category classes**: Decorate with `[OptimizationCategory(typeof(PageClass))]` or `[CustomizeCategory(PageType = typeof(PageClass))]`.
- **Discovery**: `ReflectionHelper.FindImplementationsInLoadedAssemblies<T>()` scans assemblies whose name starts with `optimizerDuck` — no DI registration array to update. Results are cached in `_implementationCache`.
- **Static provider services**: `RegistryService`, `ServiceProcessService`, `ScheduledTaskService`, `ShellService` are **static classes** (not DI-registered). They capture revert steps into the ambient `ExecutionScope`.
- **`CompleteFromScope()`**: Optimizations call `BaseOptimization.CompleteFromScope()` to build the `ApplyResult` from steps recorded in the ambient `ExecutionScope`. Do not manually construct `ApplyResult`.
-- **Preloading**: `OptimizationRegistry.StartPreload()` runs discovery on a background thread at startup. The Optimizations page calls `EnsurePreloadedAsync()` before binding.
-- **Customize discovery**: `CustomizeRegistry` uses the same reflection pattern for `ICustomizeSetting` implementations nested inside `ICustomizeCategory` classes.
+- **Preloading**: `OptimizationRegistry.PreloadOptimizationsAsync()` / `EnsurePreloadedAsync()` (and `CustomizeRegistry.PreloadCategoriesAsync()` / `EnsurePreloadedAsync()`) run reflection discovery on a background thread. `App.xaml.cs` preloads at startup; the Optimize/Customize pages call `EnsurePreloadedAsync()` before binding.
+
+## Condition System (Compatibility Gating)
+- Conditions live in `Domain/Conditions/` (`ICondition`, `ConditionBase`, `ConditionResult`, `ConditionState`, `ConditionValidation`, `WindowsBuilds`, `BuiltIn/`). They're evaluated by the static `Services/Conditions/ConditionEvaluator.cs`.
+- `[Optimization]` and `[CustomizeSetting]` both accept an optional `Condition = typeof(SomeCondition)` where the type implements `ICondition` with a public parameterless constructor.
+- `ConditionState` = `Available` | `Unsupported` | `Error`. Only `Unsupported` blocks an item, and only when the item isn't already applied (or hidden by the user). `Error` and an unpopulated `SystemSnapshot` **fail open** (never hide).
+- `ConditionValidation.Validate(...)` runs at discovery time to fail fast on misconfigured condition metadata.
+- Custom conditions return `ConditionResult.Available` / `ConditionResult.Unsupported(titleProvider, descriptionProvider)` / `ConditionResult.Error()`. User-facing text must go behind localization providers (`() => Loc.Instance[...]`).
## Revert System
- **File-based**: Each applied optimization creates `%LocalAppData%\optimizerDuck\Revert\{optimizationId}.json`. Applied state is inferred from file presence on disk.
@@ -87,6 +98,11 @@
- **Upsert**: `RevertManager.UpsertRevertStepAtIndexAsync()` can add/replace revert steps at specific indices (used during retry to persist recovered steps).
- **Key methods**: `SaveRevertDataAsync()`, `RevertAsync()`, `IsAppliedAsync(id)`, `GetRevertDataAsync(id)`, `ClearAllRevertData()`.
+## Customize Setting API Notes
+- `RegistryToggle` uses `OnValues` / `OffValues` (lists; `null` = key absent) + `DefaultValue`, `IsOptional`, `ValueKind`. There is no `OnValue`/`OffValue`/`TreatMissingAsDefault`.
+- Dropdown settings override `ControlType => CustomizeControlType.Dropdown` and `GetOptions()` returning `SettingOption`s built with `Option(key, regPath, regName, value)` or `Option(key, value, params RegistryBinding[])`. The base class auto-reads/auto-writes via bindings and shows a "Custom"/"Not set" fallback for out-of-scope values.
+- When overriding `ApplyAsync`, call `await ExecutePostActionAsync()` (guarded by `NeedsPostAction`) yourself.
+
## Coding & Style
- Nullable enabled, file-scoped namespaces, implicit usings.
- Indent: 4 spaces. PascalCase types/members, `_camelCase` private fields, `camelCase` locals/params.
@@ -97,6 +113,7 @@
- `optimizerDuck.csproj` has `<InternalsVisibleTo Include="optimizerDuck.Test" />` — test project can access internal members.
- Category pages auto-register via `services.AddAllCustomizeCategoryPages()` and `services.AddAllOptimizationPages()`.
- ShellService must be initialized at startup: `ShellService.Init(appOptionsMonitor)`.
+- `WmiHelper.Initialize()` registers WMI cleanup for abnormal termination.
## Testing (xUnit v3, Integration-Style)
- **No mocking libraries** — all test doubles are hand-written (`FakeOptimization`, `TestOptimization`, etc.) implementing interfaces directly.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 67b300d..a2072b5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,7 @@
**English** | [日本語](.github/contributing/CONTRIBUTING.ja-JP.md) | [Türkçe](.github/contributing/CONTRIBUTING.tr-TR.md)
-[Introduction](#introduction) • [Getting Started](#getting-started) • [Architecture Overview](#architecture-overview) • [Ways to Contribute](#ways-to-contribute) • [Creating an Optimization](#creating-an-optimization) • [Creating a Customize Setting](#creating-a-customize-setting) • [The Refresh Scope System](#the-refresh-scope-system) • [Building New Features](#building-new-features) • [Revert System](#revert-system) • [Testing](#testing) • [Coding Standards](#coding-standards) • [Localization](#localization) • [Pull Request Process](#pull-request-process) • [Issue Guidelines](#issue-guidelines) • [FAQ & Troubleshooting](#faq--troubleshooting) • [License](#license)
+[Introduction](#introduction) • [Getting Started](#getting-started) • [Architecture Overview](#architecture-overview) • [Ways to Contribute](#ways-to-contribute) • [Creating an Optimization](#creating-an-optimization) • [Creating a Customize Setting](#creating-a-customize-setting) • [The Condition System](#the-condition-system) • [The Refresh Scope System](#the-refresh-scope-system) • [Building New Features](#building-new-features) • [Revert System](#revert-system) • [Testing](#testing) • [Coding Standards](#coding-standards) • [Localization](#localization) • [Pull Request Process](#pull-request-process) • [Issue Guidelines](#issue-guidelines) • [FAQ & Troubleshooting](#faq--troubleshooting) • [License](#license)
</div>
@@ -15,11 +15,15 @@
Thanks for contributing to **optimizerDuck** — a free, open-source Windows optimization tool built with WPF on .NET 10.
You can help in many ways:
+
- Reporting bugs with clear reproduction steps
- Suggesting new optimizations or features (open an issue first)
- Improving documentation and guides
- Adding or fixing translations
- Contributing code: optimizations, customize settings, services, UI improvements
+- Writing or reviewing tests
+
+> **New here?** Start with [Getting Started](#getting-started), then read [Architecture Overview](#architecture-overview). The two most common code contributions are [Creating an Optimization](#creating-an-optimization) and [Creating a Customize Setting](#creating-a-customize-setting).
---
@@ -69,7 +73,7 @@ dotnet build optimizerDuck.slnx --configuration Release --no-restore
# Run tests
dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build
-# Run the app
+# Run the app (needs an elevated prompt — it modifies system settings)
dotnet run --project optimizerDuck/optimizerDuck.csproj
# Format code with CSharpier
@@ -87,7 +91,7 @@ publish.bat single --skip-tests # Skip tests for quick iteration
publish.bat portable --no-pause # Don't pause at the end (CI-friendly)
```
-Publishing uses built-in dotnet publish profiles. The `publish.bat` script handles the workflow: it runs tests first (unless `--skip-tests`), then calls `dotnet publish` with the chosen profile.
+`publish.bat` runs the test suite first (unless `--skip-tests` is passed), then calls `dotnet publish` with the chosen profile (`Portable` or `Single`).
### 5. Quick Start Checklist
@@ -113,91 +117,111 @@ optimizerDuck.slnx # Solution file (.slnx format)
│ ├── app.manifest # requireAdministrator UAC level
│ │
│ ├── Domain/ # Pure models, interfaces, attributes (no WPF deps)
-│ │ ├── Abstractions/ # IOptimization, ICustomizeSetting, IRevertStep, IWindow, ICustomizeCategory, IOptimizationCategory
-│ │ ├── Attributes/ # [Optimization], [CustomizeSetting], [OptimizationCategory], [CustomizeCategory]
+│ │ ├── Abstractions/ # IOptimization, ICustomizeSetting, IRevertStep, IWindow,
+│ │ │ # ICustomizeCategory, IOptimizationCategory
+│ │ ├── Attributes/ # [Optimization], [CustomizeSetting],
+│ │ │ # [OptimizationCategory], [CustomizeCategory]
+│ │ ├── Conditions/ # Compatibility condition system (see "The Condition System")
+│ │ │ ├── BuiltIn/ # Ready-made conditions (Windows version, GPU/CPU brand,
+│ │ │ │ # min RAM, registry key / service existence, ...)
+│ │ │ ├── ICondition.cs # Condition contract
+│ │ │ ├── ConditionBase.cs # Shared helpers (e.g. OS build parsing)
+│ │ │ ├── ConditionResult.cs # Available / Unsupported / Error outcome
+│ │ │ ├── ConditionState.cs # Outcome enum
+│ │ │ ├── ConditionValidation.cs # Discovery-time metadata validation
+│ │ │ └── WindowsBuilds.cs # OS build number constants
│ │ ├── Configuration/ # AppSettings model
+│ │ ├── Exceptions/ # StepExecutionException
│ │ ├── Execution/ # ExecutionScope — ambient step tracking via AsyncLocal
-│ │ ├── Customize/ # Customize settings (Desktop, Gaming, Preferences, System)
+│ │ ├── Customize/ # Customize settings
│ │ │ ├── Categories/ # Category classes with nested setting classes
-│ │ │ └── Models/ # BaseCustomizeSetting, RegistryToggle, RefreshScope, SettingOption, CustomizeControlType, RecommendationState
-│ │ ├── Optimizations/ # Optimizations (Performance, Privacy, GPU, etc.)
+│ │ │ └── Models/ # BaseCustomizeSetting, RegistryToggle, RegistryBinding,
+│ │ │ # CustomizeRefreshScope, SettingOption,
+│ │ │ # CustomizeControlType, RecommendationState, ...
+│ │ ├── Optimizations/ # Optimizations
│ │ │ ├── Categories/ # Category classes with nested optimization classes
-│ │ │ └── Models/ # BaseOptimization, ApplyResult, OptimizationContext, ServiceItem, RegistryItem
+│ │ │ └── Models/ # BaseOptimization, ApplyResult, OptimizationContext,
│ │ │ ├── Bloatware/ # AppXPackage model for preinstalled apps
│ │ │ ├── Cleanup/ # CleanupItem for disk cleanup
│ │ │ ├── ScheduledTask/ # ScheduledTaskModel
│ │ │ ├── Services/ # RegistryItem, ServiceItem, ShellResult, ServiceStartupType
│ │ │ └── StartupManager/ # StartupApp, StartupTask models
│ │ ├── Revert/ # RevertData, RevertResult, revert step types
-│ │ │ └── Steps/ # RegistryRevertStep, ServiceRevertStep, ScheduledTaskRevertStep, ShellRevertStep, UsbPowerRevertStep
-│ │ └── UI/ # Enums: OptimizationRisk, OptimizationTags, OptimizationCategoryOrder, CustomizeOrder, LanguageOption, OptimizationState, RiskVisual, ProcessingProgress
+│ │ │ └── Steps/ # RegistryRevertStep, ServiceRevertStep,
+│ │ │ # ScheduledTaskRevertStep, ShellRevertStep, UsbPowerRevertStep
+│ │ └── UI/ # Enums: OptimizationRisk, OptimizationTags,
+│ │ # OptimizationCategoryOrder, CustomizeOrder,
+│ │ # LanguageOption, OptimizationState, RiskVisual,
+│ │ # ProcessingProgress, ...
│ │
│ ├── Common/ # Shared helpers, extensions, converters
-│ │ ├── Converters/ # 20+ WPF value converters (BooleanToVisibility, InverseBoolean, MBToGB, etc.)
-│ │ ├── Extensions/ # StringExtensions, CustomizePageRegistryExtensions, OptimizationPageRegistryExtensions, LanguageExtensions
-│ │ ├── Helpers/ # Shared.cs, ReflectionHelper.cs, SystemRefreshService.cs, EmbeddedResourceHelper.cs, GitHubSourceHelper.cs, WmiHelper.cs, ThemeResource.cs
-│ │ └── Native/ # Native interop helpers (currently available for future use)
+│ │ ├── Converters/ # WPF value converters (BooleanToVisibility, MBToGB, ...)
+│ │ ├── Extensions/ # StringExtensions, page-registry extensions,
+│ │ │ # LanguageExtensions
+│ │ └── Helpers/ # Shared.cs, ReflectionHelper.cs, SystemRefreshService.cs,
+│ │ # EmbeddedResourceHelper.cs, WmiHelper.cs,
+│ │ # GitHubSourceHelper.cs, ThemeResource.cs, ...
│ │
│ ├── Services/ # Business logic layer
+│ │ ├── Conditions/ # ConditionEvaluator (static evaluation entry point)
│ │ ├── Configuration/ # ConfigManager, LanguageManager
-│ │ ├── Customize/ # CustomizeRegistry (reflection-based discovery of customize settings)
+│ │ ├── Customize/ # CustomizeRegistry (reflection-based discovery)
│ │ ├── Optimization/ # OptimizationRegistry, OptimizationService
-│ │ │ └── Providers/ # Static: RegistryService, ShellService, ScheduledTaskService, ServiceProcessService
+│ │ │ └── Providers/ # Static: RegistryService, ShellService (+ ShellPolicy),
+│ │ │ # ScheduledTaskService, ServiceProcessService
│ │ ├── Revert/ # RevertManager (atomic write/read of revert JSON files)
-│ │ ├── System/ # RegistryWatcher, StreamService, SystemInfoService, UpdaterService
+│ │ ├── System/ # RegistryWatcher (+ IRegistryWatcher), SystemInfoService,
+│ │ │ # StreamService, UpdaterService, CrossPageEventBus
│ │ └── UI/ # BloatwareService, DiskCleanupService, StartupManagerService
│ │
│ ├── UI/ # WPF pages, ViewModels, controls, styles
│ │ ├── Behaviors/ # SmoothScrollBehavior
-│ │ ├── Controls/ # FilledNavigationViewItem (custom nav control)
-│ │ ├── Dialogs/ # ProcessingDialog, OptimizationDetailsDialog, OptimizationResultDialog, RestorePointDialog, LegalDialog, BloatwareConfirmationDialog, ScheduledTaskCreateDialog, ScheduledTaskDetailsDialog, StartupTaskDetailsPanel
-│ │ ├── Pages/ # App pages + sub-folders
-│ │ │ ├── Customize/ # CustomizePage + Categories/ (auto-registered category pages)
-│ │ │ ├── Optimize/ # OptimizePage + Categories/ (auto-registered category pages)
-│ │ │ ├── DashboardPage
-│ │ │ ├── SettingsPage
-│ │ │ ├── BloatwarePage
+│ │ ├── Controls/ # FilledNavigationViewItem, EmptyBadge
+│ │ ├── Dialogs/ # ProcessingDialog, OptimizationDetailsDialog,
+│ │ │ # OptimizationResultDialog, RestorePointDialog, LegalDialog,
+│ │ │ # BloatwareConfirmationDialog, ScheduledTask dialogs, ...
+│ │ ├── Pages/ # Dashboard, Optimize, Customize, Settings, Bloatware,
+│ │ │ ├── Customize/ # CustomizePage + Categories/ (auto-registered pages)
+│ │ │ ├── Optimize/ # OptimizePage + Categories/ (auto-registered pages)
│ │ │ ├── DiskCleanupPage
│ │ │ ├── StartupManagerPage
│ │ │ └── ScheduledTasksPage
│ │ ├── Styles/ # FluentDesign.xaml, NavigationViewOverride.xaml, ToolTipOverride.xaml
-│ │ ├── ViewModels/ # Page and dialog ViewModels
-│ │ │ ├── Customize/ # CustomizeItemViewModel, CustomizeCategoryViewModel
-│ │ │ ├── Dialogs/ # ProcessingViewModel, OptimizationDetailsViewModel, OptimizationResultDialogViewModel, BloatwareConfirmationDialogViewModel
-│ │ │ ├── Optimizer/ # OptimizationCategoryViewModel
-│ │ │ ├── Pages/ # DashboardViewModel, OptimizeViewModel, CustomizeViewModel, SettingsViewModel, BloatwareViewModel, DiskCleanupViewModel, StartupManagerViewModel, ScheduledTasksViewModel
-│ │ │ └── Windows/ # MainWindowViewModel
+│ │ ├── ViewModels/ # Page, dialog and window ViewModels
│ │ └── Windows/ # MainWindow
│ │
│ └── Resources/ # Images, embedded assets, localization
-│ ├── Embedded/ # Power plans (optimizerDuck.pow), Icons (blank.ico)
-│ ├── Images/ # Duck.png, GitHubLogo, DiscordLogo
-│ └── Languages/ # Translations.resx + 12 locale variants
+│ ├── Embedded/ # Icons/ and PowerPlans/ (optimizerDuck.pow)
+│ ├── Images/ # Duck.png, GitHub logos, Discord logo
+│ └── Languages/ # Translations.resx (default) + locale variants
│
-└── optimizerDuck.Test/ # xUnit v3 test project
- ├── Common/Helpers/
- ├── Domain/
- │ ├── Customize/
- │ ├── Exceptions/
- │ ├── Optimizations/
- │ └── Revert/Steps/
- └── Services/
- ├── Managers/
- ├── OptimizationServices/
- └── ApplyRevertComprehensiveTests.cs
+└── optimizerDuck.Test/ # xUnit v3 test project (InternalsVisibleTo)
```
+> **Don't rely on the tree above as a hard reference.** It's a map, not a specification — folders and files evolve. When in doubt, look at the actual folders. See the [Project Structure](#project-structure) note at the end of this section.
+
### Key Design Decisions
| Decision | Rationale |
|---|---|
-| **Reflection-based discovery** | No DI registration arrays to update. `ReflectionHelper.FindImplementationsInLoadedAssemblies<T>()` scans `optimizerDuck.*` assemblies at startup. New optimizations/settings are auto-discovered. |
-| **Static provider services** | `RegistryService`, `ShellService`, `ScheduledTaskService`, `ServiceProcessService` are static classes. They capture revert steps into the ambient `ExecutionScope` — no need to inject or pass context. |
+| **Reflection-based discovery** | No DI registration arrays to update. `ReflectionHelper.FindImplementationsInLoadedAssemblies<T>()` scans `optimizerDuck.*` assemblies. New optimizations/settings are auto-discovered. |
+| **Static provider services** | `RegistryService`, `ShellService`, `ScheduledTaskService`, `ServiceProcessService` are static classes. They record revert steps into the ambient `ExecutionScope` — no need to inject or pass context. |
| **File-based revert tracking** | Applied state = file exists on disk (`%localappdata%\optimizerDuck\Revert\{id}.json`). No database. Atomic writes via `File.Replace()`. |
+| **Condition system (fail-open)** | Optimizations and settings can declare compatibility conditions. Evaluation failures never hide an item — see [The Condition System](#the-condition-system). |
| **Integration-style tests** | Real filesystem, real registry (under `HKCU\Software\TestOptimizerDuck*`), real process execution. No mocking libraries — hand-written test doubles only. |
| **Async service methods** | Provider methods that run external processes are async (`*Async` suffix). Optimization `ApplyAsync` methods should use `async`/`await` to keep the UI responsive. |
-| **Static WMI helper** | `WmiHelper.Initialize()` runs at startup to register WMI event cleanup handlers for abnormal process termination. |
-| **Pending changes tracking** | `App.HasPendingChanges` property tracks whether applied optimizations haven't been reverted. The app warns on close with options to restart PC/Explorer or exit. |
+| **Static WMI helper** | `WmiHelper.Initialize()` runs at startup to register WMI cleanup handlers for abnormal process termination. |
+| **Pending changes tracking** | `App.HasPendingChanges` tracks whether applied optimizations haven't been reverted. The app warns on close with options to restart PC/Explorer or exit. |
+
+### Project Structure
+
+The authoritative structure lives in three places, all of which should be kept in sync when you move or rename things:
+
+1. **Folders on disk** — `optimizerDuck/` (the app) and `optimizerDuck.Test/` (tests). There are no other top-level project directories.
+2. **`optimizerDuck.csproj`** — embedded resources, images, package references.
+3. **`App.xaml.cs`** — DI registrations and startup sequence.
+
+Do **not** create top-level directories outside these two project folders.
---
@@ -207,6 +231,7 @@ optimizerDuck.slnx # Solution file (.slnx format)
|---|---|---|
| **New Optimizations** | Registry tweaks, service changes, system tweaks | `Domain/Optimizations/Categories/*.cs` |
| **New Customize Settings** | UI toggles for Windows settings (Game Mode, Mouse Acceleration, Taskbar, etc.) | `Domain/Customize/Categories/*.cs` |
+| **New Conditions** | Compatibility gates for optimizations/settings (Windows version, hardware, ...) | `Domain/Conditions/` |
| **New App Features** | New pages, tools, or functionality | Open an issue first |
| **Bug Fixes** | Crash fixes, logic errors, UI issues | Anywhere |
| **Translations** | New languages or fixing existing translations | `Resources/Languages/Translations.*.resx` |
@@ -219,29 +244,31 @@ optimizerDuck.slnx # Solution file (.slnx format)
### How Discovery Works
-At startup:
+At startup the app calls `OptimizationRegistry.PreloadOptimizationsAsync()`. This runs reflection work on a background thread:
-1. `ReflectionHelper.FindImplementationsInLoadedAssemblies<IOptimizationCategory>()` scans all `optimizerDuck.*` assemblies
-2. It finds every class implementing `IOptimizationCategory`
-3. For each category, it scans **nested public classes** implementing `IOptimization`
-4. All discovered optimizations are instantiated and `OwnerType` is assigned automatically
-5. `OptimizationService.UpdateOptimizationStateAsync` scans revert files on disk to mark each optimization as Applied or not
-6. `OptimizationRegistry.StartPreload()` runs this on a background thread at startup for non-blocking loading
+1. `ReflectionHelper.FindImplementationsInLoadedAssemblies<IOptimizationCategory>()` finds every category class.
+2. For each category it scans **nested public classes** implementing `IOptimization`.
+3. Each optimization is instantiated, `OwnerType` is assigned, and its `[Optimization]` metadata (including any `Condition`) is validated.
+4. `OptimizationService.UpdateOptimizationStateAsync` scans revert files on disk to mark each optimization as Applied or not.
+5. The Optimize page calls `EnsurePreloadedAsync()` before binding (a no-op if preloading already finished).
-**Your job**: Create a nested class inside a category, extend `BaseOptimization`, decorate with `[Optimization]`. That's it.
+**Your job**: Create a nested class inside a category, extend `BaseOptimization`, decorate with `[Optimization]`. That's it — no registration to update.
### Optimization Categories
-Current categories (in `Domain/Optimizations/Categories/`):
+Categories live in `Domain/Optimizations/Categories/`, one file per category. The exact set changes over time — look at that folder for the authoritative list. As of writing, categories include:
-| File | Attribute | Focus |
-|---|---|---|
-| `Performance.cs` | `[OptimizationCategory(typeof(PerformanceOptimizerPage))]` | RAM tuning, process priority, keyboard latency, multimedia scheduler, accessibility keyboard hotkeys |
-| `SecurityAndPrivacy.cs` | `[OptimizationCategory(typeof(SecurityAndPrivacyOptimizerPage))]` | Telemetry, error reporting, advertising ID, location, Cortana, Copilot, content delivery manager, activity history, auto-logger |
-| `Gpu.cs` | `[OptimizationCategory(typeof(GpuOptimizerPage))]` | AMD/NVIDIA/Intel registry tweaks, power states, clock gating, ASPM, async flips |
-| `PowerManagement.cs` | `[OptimizationCategory(typeof(PowerManagementOptimizerPage))]` | Hibernation, fast startup, USB selective suspend, custom power plan installation, power saving disable |
-| `BloatwareAndServices.cs` | `[OptimizationCategory(typeof(BloatwareAndServicesOptimizerPage))]` | OEM preinstalled app blocking, 170+ Windows service startup type optimization |
-| `UserExperience.cs` | `[OptimizationCategory(typeof(UserExperienceOptimizerPage))]` | Menu delays, visual effects, taskbar animations, transparency, Start Menu web search |
+| File | Focus |
+|---|---|
+| `Performance.cs` | RAM tuning, process priority, keyboard latency, multimedia scheduler, accessibility hotkeys |
+| `SecurityAndPrivacy.cs` | Telemetry, error reporting, advertising ID, location, Copilot, activity history, delivery optimization, etc. |
+| `Gpu.cs` | AMD/NVIDIA/Intel registry tweaks, power states, clock gating, ASPM, async flips |
+| `PowerManagement.cs` | Hibernation, fast startup, USB selective suspend, custom power plan installation |
+| `BloatwareAndServices.cs` | OEM preinstalled app blocking, Windows service startup type optimization |
+| `UserExperience.cs` | Menu delays, visual effects, taskbar animations, transparency, Start Menu web search |
+| `AI.cs` | Windows AI features (Recall, Click To Do) |
+
+Each category class carries a `[OptimizationCategory(typeof(SomePage))]` attribute that links it to its UI page.
### Step-by-Step: Add to an Existing Category
@@ -258,7 +285,8 @@ public class Performance : IOptimizationCategory
[Optimization(
Id = "a1b2c3d4-...", // Generate a NEW GUID
Risk = OptimizationRisk.Safe, // Safe / Moderate / Risky
- Tags = OptimizationTags.Performance // Flags — combine with |
+ Tags = OptimizationTags.Performance, // Flags — combine with |
+ Condition = typeof(Windows11Condition) // Optional (see "The Condition System")
)]
public class MyNewTweak : BaseOptimization
{
@@ -286,14 +314,17 @@ public class Performance : IOptimizationCategory
| Rule | Detail |
|---|---|
| **`Id` must be a new GUID** | Used for revert file naming and applied-state tracking. Generate with `[guid]::NewGuid()` in PowerShell. |
-| **Extend `BaseOptimization`** | Provides `Name`, `ShortDescription`, `Prefix`, `RiskVisual`, `TagDisplays` from attribute + localization keys |
-| **Use `async Task<ApplyResult>`** | Not `Task.FromResult()`. Service providers are async — await them to keep the UI responsive. |
-| **Return `CompleteFromScope()`** | Derives `ApplyResult` from steps recorded in the ambient `ExecutionScope` |
-| **Report progress** | Use `progress.Report(new ProcessingProgress { ... })` to update the UI dialog |
-| **Don't catch all exceptions** | Let them bubble up. `ExecutionScope` tracks success/failure. The `OptimizationService` layer handles exceptions. |
-| **Don't manually create revert steps** | Static provider services do this automatically via `ExecutionScope.RecordStep()` |
-| **Use `context.Logger`** | The optimization context provides a logger — use it for important diagnostic info |
-| **Check `context.Snapshot`** | `OptimizationContext.Snapshot` (a `SystemSnapshot`) gives you system info: RAM, GPU info, CPU. Use it for conditional logic (e.g., skip if insufficient RAM). |
+| **Extend `BaseOptimization`** | Provides `Name`, `ShortDescription`, `RiskVisual`, `TagDisplays` from attribute + localization keys. |
+| **`OwnerType` is assigned automatically** | Discovery sets it — don't set it yourself. |
+| **Use `async Task<ApplyResult>`** | Service providers are async — `await` them to keep the UI responsive. |
+| **Return `CompleteFromScope()`** | Derives `ApplyResult` from steps recorded in the ambient `ExecutionScope`. Don't construct `ApplyResult` manually. |
+| **Report progress** | Use `progress.Report(new ProcessingProgress { ... })` to update the UI dialog. |
+| **Don't catch all exceptions** | Let them bubble up. `ExecutionScope` tracks success/failure; `OptimizationService` handles exceptions. |
+| **Don't manually create revert steps** | Static provider services do this automatically via `ExecutionScope.RecordStep()`. |
+| **Use `context.Logger`** | The optimization context provides a logger for important diagnostic info. |
+| **Use `context.Snapshot`** | `OptimizationContext.Snapshot` (a `SystemSnapshot`) gives system info: RAM, GPU, CPU, OS. Use it for conditional logic. |
+| **Use `context.StreamService`** | For optimizations that need to download remote resources (e.g. power plans). |
+| **Declare a `Condition` if needed** | Gate the optimization on Windows version or hardware — see [The Condition System](#the-condition-system). |
### Available Service Providers
@@ -301,10 +332,10 @@ These **static** classes handle logging, error handling, and automatic revert st
| Service | Key Methods | Why It's Used |
|---|---|---|
-| **`RegistryService`** | `Write()`, `Read<T>()`, `DeleteValue()`, `CreateSubKey()`, `DeleteSubKeyTree()`, `KeyExists()` | Read/write/delete registry keys. Backs up original values for revert. Supports writing multiple RegistryItem entries in one call via params array. |
-| **`ShellService`** | `CMDAsync()`, `PowerShellAsync()`, `CMD()` (sync), `PowerShell()` (sync) | Run CMD or PowerShell commands. Prefer async variants. Both sync and async methods accept an optional `revertCommand` parameter. |
-| **`ScheduledTaskService`** | `DisableTask()`, `EnableTask()`, `IsTaskEnabled()`, `DeleteTask()` | Manage Windows Scheduled Tasks. |
-| **`ServiceProcessService`** | `ChangeServiceStartupTypeAsync()`, `GetStartupTypeAsync()` | Manage Windows Services. Always use async variants. Supports changing multiple services at once via params array. |
+| **`RegistryService`** | `Write()`, `Read<T>()`, `DeleteValue()`, `CreateSubKey()`, `DeleteSubKeyTree()`, `KeyExists()`, `CleanupEmptyKeys()` | Read/write/delete registry keys. Backs up original values for revert. Supports batch writes via params array. |
+| **`ShellService`** | `CMDAsync()`, `PowerShellAsync()`, `CMD()` (sync), `PowerShell()` (sync) | Run CMD or PowerShell commands. Prefer async variants. Optional `revertCommand` parameter for undo. See `ShellPolicy` for non-standard exit codes. |
+| **`ScheduledTaskService`** | `DisableTask()`, `EnableTask()`, `IsTaskEnabled()`, `DeleteTask()`, `GetAllTasks()`, `RegisterTask()`, `RunTask()`, `StopTask()` | Manage Windows Scheduled Tasks. |
+| **`ServiceProcessService`** | `ChangeServiceStartupTypeAsync()`, `GetStartupTypeAsync()` | Manage Windows Services. Always use async variants. Supports batch changes via params array. |
> **Methods accepting multiple items via params**: Most write/change methods accept a params array of items (e.g., `RegistryService.Write(item1, item2, item3)`). This is more efficient than multiple individual calls.
@@ -324,7 +355,7 @@ await ServiceProcessService.ChangeServiceStartupTypeAsync(
new ServiceItem("dmwappushservice", ServiceStartupType.Disabled)
);
-// Async shell commands with revert command
+// Async shell command with revert command
var result = await ShellService.CMDAsync(
"powercfg /h off",
"powercfg /h on" // revert command stored for undo
@@ -338,7 +369,7 @@ var usbStates = await ShellService.PowerShellAsync(
### Handling Asynchronous Operations
-Not all optimizations need `async`/`await`. If your optimization only does synchronous registry writes (no async calls), you can return `Task.FromResult()`:
+Not all optimizations need `async`/`await`. If your optimization only does synchronous registry writes (no async calls), return `Task.FromResult()`:
```csharp
public override Task<ApplyResult> ApplyAsync(
@@ -365,15 +396,15 @@ public override async Task<ApplyResult> ApplyAsync(...)
Only if your optimizations don't fit any existing category. Avoid hyper-specific categories.
-1. Create `Domain/Optimizations/Categories/YourCategory.cs`
-2. Implement `IOptimizationCategory`
-3. Apply `[OptimizationCategory(PageType = typeof(YourPage))]` — you'll also need a XAML page
-4. Add a member to `OptimizationCategoryOrder` enum in `Domain/UI/OptimizationCategoryOrder.cs`
-5. The XAML page auto-registers via `services.AddAllOptimizationPages()` in `App.xaml.cs`
+1. Create `Domain/Optimizations/Categories/YourCategory.cs`.
+2. Implement `IOptimizationCategory`.
+3. Apply `[OptimizationCategory(typeof(YourPage))]` — you'll also need a XAML page (see [Building New Features](#building-new-features)).
+4. Add a member to the `OptimizationCategoryOrder` enum in `Domain/UI/OptimizationCategoryOrder.cs` so the category sorts correctly.
+5. The XAML page auto-registers via `services.AddAllOptimizationPages()` in `App.xaml.cs`.
### Create an Optimization Helper Base Class
-If you have multiple optimizations that share the same structure (like GPU tweaks that all iterate over detected GPUs), create an abstract intermediate class:
+If several optimizations share the same structure (like GPU tweaks that iterate over detected GPUs), create an abstract intermediate class:
```csharp
public abstract class GpuRegistryOptimization : BaseOptimization
@@ -393,7 +424,7 @@ public abstract class GpuRegistryOptimization : BaseOptimization
}
```
-See `Gpu.cs` for a real example with AMD, NVIDIA, and Intel subclasses.
+See `Domain/Optimizations/Categories/Gpu.cs` for a real example with AMD, NVIDIA, and Intel subclasses.
### Localization Keys
@@ -419,12 +450,16 @@ Customize settings are UI controls (toggle switches, dropdowns, number inputs) t
### Customize Categories
-| File | Attribute | Focus |
-|---|---|---|
-| `Desktop.cs` | `[CustomizeCategory(PageType = typeof(DesktopFeatureCategory))]` | Desktop icons (This PC, Recycle Bin, Network, User Files, Control Panel), global show/hide icons, shortcut arrow visibility |
-| `Preferences.cs` | `[CustomizeCategory(PageType = typeof(PreferencesFeatureCategory))]` | Taskbar alignment, widgets, task view button, end task, dark mode, file extensions, hidden files, clipboard history, search mode, seconds in clock, Bing search, classic context menu |
-| `Gaming.cs` | `[CustomizeCategory(PageType = typeof(GamingFeatureCategory))]` | Game Mode, Game Bar, background recording, mouse acceleration, fullscreen optimizations, GPU scheduling |
-| `SystemFeatures.cs` | `[CustomizeCategory(PageType = typeof(SystemFeatureCategory))]` | Num Lock on boot, Developer Mode, allow all trusted apps, long paths enabled, battery percentage |
+Categories live in `Domain/Customize/Categories/`, one file per category — look there for the authoritative list. As of writing:
+
+| File | Focus |
+|---|---|
+| `Desktop.cs` | Desktop icons (This PC, Recycle Bin, Network, User Files, Control Panel), global show/hide icons, shortcut arrow visibility |
+| `Preferences.cs` | Taskbar alignment, widgets, task view button, end task, dark mode, file extensions, hidden files, clipboard history, search mode, seconds in clock, Bing search, classic context menu |
+| `Gaming.cs` | Game Mode, Game Bar, background recording, mouse acceleration, fullscreen optimizations, GPU scheduling |
+| `SystemFeatures.cs` | Num Lock on boot, Developer Mode, long paths, battery percentage |
+
+Each category class carries a `[CustomizeCategory(PageType = typeof(SomePage))]` attribute linking it to its UI page.
### Step-by-Step: Simple Registry Toggle
@@ -436,7 +471,8 @@ private enum Sections { Taskbar, Widgets, Advanced }
[CustomizeSetting(
Section = nameof(Sections.Taskbar), // Groups settings in the UI
Icon = SymbolRegular.AlignCenter24, // From Wpf.Ui.Controls.SymbolRegular
- Recommendation = RecommendationState.On // On / Off / Depends / Experimental / None
+ Recommendation = RecommendationState.On, // On / Off / Depends / Experimental / None
+ Condition = typeof(Windows11Condition) // Optional compatibility condition
)]
public class TaskbarAlignment : BaseCustomizeSetting
{
@@ -446,9 +482,9 @@ public class TaskbarAlignment : BaseCustomizeSetting
{
Path = @"HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced",
Name = "TaskbarAl",
- OnValue = 0, // value when toggle is ON
- OffValue = 1, // value when toggle is OFF
- DefaultValue = 1, // value = default state (used when key missing)
+ OnValues = [0], // value(s) when toggle is ON
+ OffValues = [1], // value(s) when toggle is OFF
+ DefaultValue = 1, // value = default state (used when key missing)
},
];
@@ -464,14 +500,13 @@ public class TaskbarAlignment : BaseCustomizeSetting
|---|---|---|---|
| `Path` | `string` | required | Full registry key path (e.g., `@"HKCU\Software\..."`) |
| `Name` | `string` | required | Registry value name |
-| `OnValue` | `object?` | `1` | Value representing "on" state |
-| `OffValue` | `object?` | `0` | Value representing "off" state |
-| `DefaultValue` | `object?` | `0` | Fallback when registry value is missing |
-| `IsOptional` | `bool` | `false` | If `true`, not required for state detection |
-| `TreatMissingAsDefault` | `bool` | `false` | If `true`, missing key uses `DefaultValue` instead of treating as "off" |
-| `ValueKind` | `RegistryValueKind` | `DWord` | Registry value type (DWord, String, etc.) |
+| `OnValues` | `IReadOnlyList<object?>` | `[1]` | Values representing the "on" state. `null` in the list means "key absent = on". |
+| `OffValues` | `IReadOnlyList<object?>` | `[0]` | Values representing the "off" state. `null` in the list means "key absent = off". |
+| `DefaultValue` | `object?` | `0` | Default state value when the key is missing (used for Reset to Default). |
+| `IsOptional` | `bool` | `false` | If `true`, not required for state detection. |
+| `ValueKind` | `RegistryValueKind` | `DWord` | Registry value type (DWord, String, etc.). |
-**State detection logic**: `GetState()` (in `BaseCustomizeSetting`) collects all non-optional `RegistryToggles` and returns `true` only when **every** required toggle matches its `OnValue`.
+**State detection logic**: `GetState()` (in `BaseCustomizeSetting`) collects all non-optional `RegistryToggles` and returns `true` only when **every** required toggle matches one of its `OnValues`.
### Control Types
@@ -492,49 +527,66 @@ public override CustomizeControlType ControlType => CustomizeControlType.Dropdow
### Dropdown with Options
-For settings with multiple choices:
+Dropdown options declare a `RegistryBinding` so the base class can auto-read the current value and auto-write on selection. Use the `Option()` helper:
```csharp
-public override CustomizeControlType ControlType => CustomizeControlType.Dropdown;
+[CustomizeSetting(Section = nameof(Sections.Taskbar), Icon = SymbolRegular.AlignCenter24)]
+public class TaskbarAlignment : BaseCustomizeSetting
+{
+ private const string RegPath =
+ @"HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced";
+ private const string RegName = "TaskbarAl";
-public override IReadOnlyList<SettingOption>? Options =>
- [
- Option("Never", 0), // Option() helper reads from Translations.resx:
- Option("Battery", 1), // Customize.{Category}.{Feature}.Options.Never
- Option("Always", 2), // Customize.{Category}.{Feature}.Options.Always
- ];
+ public override CustomizeControlType ControlType => CustomizeControlType.Dropdown;
-public override async Task ApplyAsync(object? value)
-{
- var intValue = value is int i ? i : 0;
- RegistryService.Write(new RegistryItem(Path, "ValueName", intValue));
- await ExecutePostActionAsync(); // MUST call when overriding ApplyAsync
+ // Option(key, regPath, regName, value) reads its label from
+ // Customize.{Category}.{Feature}.Options.{key}
+ protected override IReadOnlyList<SettingOption>? GetOptions() =>
+ [Option("Center", RegPath, RegName, 1), Option("Left", RegPath, RegName, 0)];
+
+ protected override CustomizeRefreshScope RefreshScope =>
+ CustomizeRefreshScope.TaskbarSettings;
}
```
-### Dynamic Options (Platform-Aware)
-
-You can conditionally show options based on the Windows version:
+For options that touch **multiple** registry values, pass explicit bindings:
```csharp
-public override IReadOnlyList<SettingOption>? Options
-{
- get
- {
- if (Shared.IsWindows11OrGreater)
- return [Option("Hidden", 0), Option("Icon", 1), Option("IconAndLabel", 2), Option("SearchBox", 3)];
- return [Option("Hidden", 0), Option("Icon", 1), Option("SearchBox", 2)];
- }
-}
+protected override IReadOnlyList<SettingOption>? GetOptions() =>
+[
+ Option("On", 1,
+ new RegistryBinding(@"HKCU\...\Key1", "ValueA", 1),
+ new RegistryBinding(@"HKCU\...\Key2", "ValueB", "enabled", RegistryValueKind.String)),
+ Option("Off", 0,
+ new RegistryBinding(@"HKCU\...\Key1", "ValueA", 0),
+ new RegistryBinding(@"HKCU\...\Key2", "ValueB", "disabled", RegistryValueKind.String)),
+];
```
-### CurrentValue for Dropdowns
+The base class reads the current value from the bindings, shows a memory-only **"Custom"** (or **"Not set"**) fallback when the live value matches no declared option, and writes all bindings of the selected option. You don't need a custom `ApplyAsync` for the common case.
+
+### Dynamic Options (Platform-Aware)
-For dropdowns and option-based controls, implement `CurrentValue` so the UI shows the current system state:
+You can conditionally show options based on the Windows version:
```csharp
-public override object? CurrentValue =>
- RegistryService.Read<object>(new RegistryItem(RegPath, RegName));
+protected override IReadOnlyList<SettingOption>? GetOptions()
+{
+ if (Shared.IsWindows11OrGreater)
+ return
+ [
+ Option("Hidden", RegPath, RegName, 0),
+ Option("Icon", RegPath, RegName, 1),
+ Option("IconAndLabel", RegPath, RegName, 2),
+ Option("SearchBox", RegPath, RegName, 3),
+ ];
+ return
+ [
+ Option("Hidden", RegPath, RegName, 0),
+ Option("Icon", RegPath, RegName, 1),
+ Option("SearchBox", RegPath, RegName, 2),
+ ];
+}
```
### Custom Logic (Override GetStateAsync / ApplyAsync)
@@ -573,19 +625,24 @@ public class MouseAcceleration : BaseCustomizeSetting
RegistryService.Write(new RegistryItem(Path, "MouseSpeed", isOn ? "1" : "0"));
RegistryService.Write(new RegistryItem(Path, "MouseThreshold1", isOn ? "6" : "0"));
RegistryService.Write(new RegistryItem(Path, "MouseThreshold2", isOn ? "10" : "0"));
- await ExecutePostActionAsync(); // MUST call when overriding ApplyAsync
+
+ if (NeedsPostAction)
+ await ExecutePostActionAsync();
}
protected override CustomizeRefreshScope RefreshScope => CustomizeRefreshScope.Default;
}
```
+> When you override `ApplyAsync`, you **must** call `await ExecutePostActionAsync()` yourself (guarded by `NeedsPostAction`). The base class only does this automatically for the default `RegistryToggles`-based and dropdown-binding-based paths.
+
### State Detection with Retry
After applying a value, the UI calls `GetStateWithRetryAsync()` (not `GetStateAsync()`). This method:
-1. Reads state up to `maxRetries` (default 3) times with `delayMs` (default 80ms) between attempts
-2. Returns when two consecutive reads agree on the same value (convergence check)
-3. Falls back to the last read value after exhausting retries
+
+1. Reads state up to `maxRetries` (default 3) times with `delayMs` (default 80ms) between attempts.
+2. Returns when two consecutive reads agree on the same value (convergence check).
+3. Falls back to the last read value after exhausting retries.
This prevents the UI from showing stale values while the registry settles after a write.
@@ -618,20 +675,17 @@ Use `EmbeddedResourceHelper.TryExtract(resourceName, outputPath)` to extract emb
Each customize setting can declare a recommendation:
```csharp
-[CustomizeSetting(
- ...,
- Recommendation = RecommendationState.On // or Off, Depends, Experimental, None
-)]
+[CustomizeSetting(..., Recommendation = RecommendationState.On)]
+// Available: On, Off, Depends, Experimental, None
```
-Available states:
- **`On`**: Recommended to turn ON — improves system
- **`Off`**: Recommended to turn OFF — improves system
- **`Depends`**: Depends on user's specific needs/configuration
- **`Experimental`**: May be unstable, use with caution
- **`None`** (default): No recommendation displayed
-You can also add a recommendation reason via localization key: `Customize.{Category}.{Feature}.Recommendation.Reason`.
+Add an optional reason via localization key: `Customize.{Category}.{Feature}.Recommendation.Reason`.
### What to Override per Pattern
@@ -639,21 +693,22 @@ You can also add a recommendation reason via localization key: `Customize.{Categ
|---|---|
| Simple registry toggle | `RegistryToggles` + `RefreshScope` |
| Multiple registry toggles (e.g., Game Mode: 2 values) | `RegistryToggles` (list them all) |
-| Dropdown/Options | `ControlType` → `Dropdown`, `Options`, custom `ApplyAsync`, `CurrentValue` |
+| Dropdown / options | `ControlType` → `Dropdown` + `GetOptions()` with `Option(...)` bindings |
| Multi-value logic (e.g., mouse accel: 3 registry values) | `GetStateAsync()` + `ApplyAsync()` + `GetWatchedRegistryPaths()` |
| Setting with no registry interaction | `GetStateAsync()` + `ApplyAsync()` (full custom) |
-| Custom refresh behavior | `RefreshScope` (if only changing flags) or `ExecutePostActionAsync()` (full override) |
-| State detection with convergence | Use `GetStateWithRetryAsync()` (built-in — don't override) |
-| Dynamic options per Windows version | Override `Options` getter with conditional logic |
+| Custom refresh behavior | `RefreshScope` (flags only) or `ExecutePostActionAsync()` (full override) |
+| State detection with convergence | `GetStateWithRetryAsync()` (built-in — don't override) |
+| Dynamic options per Windows version | Override `GetOptions()` with conditional logic |
| Embedded resource extraction | `EmbeddedResourceHelper.TryExtract()` in custom `ApplyAsync` |
+| Compatibility gate | `Condition = typeof(...)` on the `[CustomizeSetting]` attribute |
### Create a New Category
-1. Create `Domain/Customize/Categories/YourCategory.cs`
-2. Implement `ICustomizeCategory` with `[CustomizeCategory(PageType = typeof(YourPage))]`
-3. Add a member to `CustomizeOrder` enum in `Domain/UI/CustomizeOrder.cs`
-4. Create the XAML page (a new class in `UI/Pages/Customize/Categories/`)
-5. The page auto-registers via `services.AddAllCustomizeCategoryPages()` in `App.xaml.cs`
+1. Create `Domain/Customize/Categories/YourCategory.cs`.
+2. Implement `ICustomizeCategory` with `[CustomizeCategory(PageType = typeof(YourPage))]`.
+3. Add a member to the `CustomizeOrder` enum in `Domain/UI/CustomizeOrder.cs`.
+4. Create the XAML page (a new class in `UI/Pages/Customize/Categories/`).
+5. The page auto-registers via `services.AddAllCustomizeCategoryPages()` in `App.xaml.cs`.
### Localization Keys for Customize Settings
@@ -667,9 +722,92 @@ Customize.{CategoryName}.Section.{SectionName} (for section heade
---
+# The Condition System
+
+Conditions let you gate an optimization or customize setting behind a compatibility check, so the UI can tell the user "this isn't supported on your system" instead of applying something that won't work.
+
+### Core Concepts
+
+Conditions live in `Domain/Conditions/` and are evaluated by the static `ConditionEvaluator` in `Services/Conditions/`.
+
+| Piece | Purpose |
+|---|---|
+| `ICondition` | The contract: `ConditionResult Evaluate(SystemSnapshot snapshot)`. Implementations need a public parameterless constructor (they're instantiated via reflection). |
+| `ConditionBase` | Optional base class with shared helpers (e.g., `TryGetOsBuild` for parsing the OS build number). |
+| `ConditionResult` | Outcome: `Available`, `Unsupported(title, description)`, or `Error()`. Localized text is resolved lazily via providers. |
+| `ConditionState` | `Available`, `Unsupported`, `Error`. |
+| `ConditionValidation` | Validates `Condition = typeof(...)` metadata at discovery time so misconfigurations fail fast at startup. |
+| `WindowsBuilds` | OS build-number constants (e.g. `Windows11`, `Windows11_24H2`). |
+
+**Fail-open principle**: only `Unsupported` blocks an item, and only when it isn't already applied (or hidden by the user). `Error` and an unpopulated snapshot never hide anything — incomplete hardware detection must not remove options the user could still use.
+
+### Declaring a Condition
+
+Both attributes accept an optional `Condition`:
+
+```csharp
+// Optimization
+[Optimization(Id = "...", Risk = OptimizationRisk.Safe,
+ Tags = OptimizationTags.Privacy | OptimizationTags.System,
+ Condition = typeof(Windows11_24H2OrGreaterCondition))]
+public class DisableRecall : BaseOptimization { ... }
+
+// Customize setting
+[CustomizeSetting(Section = ..., Icon = SymbolRegular.Grid24,
+ Condition = typeof(Windows11Condition))]
+public class TaskbarWidgets : BaseCustomizeSetting { ... }
+```
+
+### Built-In Conditions
+
+Ready-made conditions live in `Domain/Conditions/BuiltIn/` — check that folder for the full, up-to-date list. Examples include:
+
+| Condition | Matches |
+|---|---|
+| `Windows10Condition` / `Windows11Condition` | OS version by build number |
+| `Windows11_24H2OrGreaterCondition` | Windows 11 24H2 (build 26100) or later |
+| `CpuBrandCondition` / `GpuBrandCondition` | CPU/GPU vendor (Intel, AMD, NVIDIA) |
+| `MinimumRamCondition` (base) / `SixteenGbRamCondition` | Minimum installed RAM |
+| `RegistryKeyExistsCondition` | A registry key exists |
+| `ServiceExistsCondition` | A Windows service exists |
+| `RecallInstalledCondition` | Windows Recall is present |
+
+### Writing a Custom Condition
+
+```csharp
+public sealed class MyCondition : ConditionBase
+{
+ public override ConditionResult Evaluate(SystemSnapshot snapshot)
+ {
+ // ConditionBase.TryGetOsBuild parses "22631.xxxx" -> 22631
+ if (TryGetOsBuild(snapshot, out var build) && build >= 22000)
+ return ConditionResult.Available;
+
+ return ConditionResult.Unsupported(
+ () => Loc.Instance["Condition.MyCondition.Title"],
+ () => Loc.Instance["Condition.MyCondition.Description"]);
+ }
+}
+```
+
+Guidelines:
+
+- **Return `Available`** when the system passes; **`Unsupported(title, description)`** when it doesn't.
+- Use `ConditionResult.Error()` (or throw — `ConditionEvaluator` catches and maps to `Error`) for unexpected failures. Errors don't block.
+- Put user-facing text behind localization providers (`() => Loc.Instance[...]`) so the current culture wins at read time.
+- Give the class a **public parameterless constructor** (add none, or an explicit empty one).
+
+### How It's Evaluated
+
+1. Discovery calls `ConditionValidation.Validate(...)` to confirm the declared type implements `ICondition` and is constructible.
+2. The UI calls `ConditionEvaluator.Evaluate(conditionType, snapshot, logger)`, which caches condition instances and never throws.
+3. Items with an `Unsupported` result are shown in a blocked/unsupported state (the user can hide it for the session). Items already applied are never re-blocked.
+
+---
+
# The Refresh Scope System
-When a customize setting changes state, different Windows surfaces need different refresh strategies. The `CustomizeRefreshScope` [Flags] enum controls this granularly.
+When a customize setting changes state, different Windows surfaces need different refresh strategies. The `CustomizeRefreshScope` `[Flags]` enum controls this granularly.
### Available Flags
@@ -680,7 +818,7 @@ When a customize setting changes state, different Windows surfaces need differen
| `Associations` | `1 << 1` | Notify shell that file associations or icon cache changed | `SHChangeNotify(SHCNE_ASSOCCHANGED)` |
| `Desktop` | `1 << 2` | Force desktop icon list (`SysListView32`) to repaint | `LVM_REFRESH` + `LVM_UPDATE` |
| `Taskbar` | `1 << 3` | Broadcast taskbar-targeted `WM_SETTINGCHANGE` ("TraySettings") | `SendMessageTimeout(HWND_BROADCAST, WM_SETTINGCHANGE, "TraySettings")` |
-| `PolicyUpdate` | `1 << 4` | Push `SystemParametersInfo` with `SPIF_SENDCHANGE` for per-user params | `SystemParametersInfo(SPI_SETDESKWALLPAPER)` |
+| `PolicyUpdate` | `1 << 4` | Push `SystemParametersInfo` with `SPIF_SENDCHANGE` for per-user params | `SystemParametersInfo` |
| `Theme` | `1 << 5` | Broadcast `WM_THEMECHANGED` for theme/visual tweaks | `SendMessageTimeout(HWND_BROADCAST, WM_THEMECHANGED)` |
| `DesktopIconCache` | `1 << 6` | Toggle HideIcons registry + send `WM_COMMAND 0x7402` to desktop | Registry read + `SendMessage(Progman, WM_COMMAND)` |
@@ -698,7 +836,7 @@ When a customize setting changes state, different Windows surfaces need differen
```
Setting toggle → BaseCustomizeSetting.ApplyAsync(value)
- ├─ Writes RegistryToggles (if any)
+ ├─ Writes RegistryToggles (if any), or applies the selected option's bindings
├─ Checks NeedsPostAction (true if RefreshScope != None)
└─ Task.Run → ExecutePostActionAsync()
├─ Checks each CustomizeRefreshScope flag
@@ -706,7 +844,7 @@ Setting toggle → BaseCustomizeSetting.ApplyAsync(value)
└─ Win32 notifications sent to Windows
```
-If you override `ApplyAsync`, you **must** call `await ExecutePostActionAsync()` yourself to trigger the refresh. The base class only does this automatically when using the default `RegistryToggles`-based apply.
+If you override `ApplyAsync`, you **must** call `await ExecutePostActionAsync()` yourself (see the examples above). The base class only does this automatically when using the default `RegistryToggles`-based or dropdown-binding-based apply.
---
@@ -731,8 +869,8 @@ services.AddSingleton<YourViewModel>();
services.AddSingleton<YourPage>();
```
-- ViewModels and Pages **must** be registered as singletons in `App.xaml.cs`
-- Navigation is handled by WPF UI (`INavigationService`)
+- ViewModels and Pages **must** be registered as singletons in `App.xaml.cs`.
+- Navigation is handled by WPF UI (`INavigationService`).
- Follow the existing patterns — check `DashboardPage`, `OptimizePage`, `BloatwarePage`, `DiskCleanupPage`, `ScheduledTasksPage`, `StartupManagerPage`, etc.
### DI Registration Pattern (from App.xaml.cs)
@@ -785,19 +923,20 @@ services.AddSingleton<UpdaterService>();
services.AddSingleton<IRegistryWatcher, RegistryWatcher>();
```
-### System Services Reference
+> This is a snapshot for orientation — `App.xaml.cs` is the source of truth for the current registrations. Also note the startup calls: `ShellService.Init(appOptionsMonitor)` and `WmiHelper.Initialize()`.
-Additional services available for feature development:
+### System Services Reference
| Service | Purpose |
|---|---|
-| `SystemInfoService` | Provides `Snapshot` property (`SystemSnapshot`) with CPU, RAM, GPU info via WMI. Used in optimization context. |
+| `SystemInfoService` | Provides the `SystemSnapshot` (CPU, RAM, GPU, OS, disk) used by `OptimizationContext` and the condition system. |
| `StreamService` | Downloads remote resources (e.g., updated power plan files). Used via `OptimizationContext.StreamService`. |
| `UpdaterService` | Checks GitHub releases for updates. Shows update prompt on Dashboard. |
| `RegistryWatcher` | Monitors registry keys for external changes and notifies the UI to refresh. Implements `IRegistryWatcher`. |
| `BloatwareService` | Lists preinstalled AppX packages, categorizes them as Safe/Caution/Dangerous. |
| `DiskCleanupService` | Scans disks for cleanup opportunities (temp files, caches, logs). |
| `StartupManagerService` | Lists and manages startup applications and scheduled tasks. |
+| `ConditionEvaluator` | Static entry point for evaluating compatibility conditions (see [The Condition System](#the-condition-system)). |
---
@@ -821,14 +960,22 @@ ApplyAsync()
└─ ExecutionScope disposes → RevertManager.SaveRevertDataAsync()
```
+### Scope Variants
+
+| Method | Purpose |
+|---|---|
+| `ExecutionScope.Begin(optimization, logger)` | Creates a persistable scope for a real apply. |
+| `ExecutionScope.BeginForLogging(logger)` | Logging only — records steps but never persists revert data. |
+| `ExecutionScope.BeginForCapture(logger)` | For retry: captures steps with `OptimizationId = Guid.Empty`, later re-assigned to the real scope. |
+
### Step Types
| Step Type | Records | Automatically Created By |
|---|---|---|
-| **`RegistryRevertStep`** | Original registry value before change | `RegistryService.Write()`, `RegistryService.DeleteValue()`, `RegistryService.CreateSubKey()`, `RegistryService.DeleteSubKeyTree()` |
+| **`RegistryRevertStep`** | Original registry value before change | `RegistryService.Write()`, `DeleteValue()`, `CreateSubKey()`, `DeleteSubKeyTree()` |
| **`ServiceRevertStep`** | Original service startup type | `ServiceProcessService.ChangeServiceStartupTypeAsync()` |
-| **`ScheduledTaskRevertStep`** | Original task state (enabled/disabled) | `ScheduledTaskService.DisableTask()`, `ScheduledTaskService.EnableTask()` |
-| **`ShellRevertStep`** | Shell command to reverse the change | `ShellService.CMDAsync()`, `ShellService.PowerShellAsync()` — pass a `revertCommand` parameter |
+| **`ScheduledTaskRevertStep`** | Original task state (enabled/disabled) | `ScheduledTaskService.DisableTask()`, `EnableTask()` |
+| **`ShellRevertStep`** | Shell command to reverse the change | `ShellService.CMDAsync()`, `PowerShellAsync()` — pass a `revertCommand` parameter |
| **`UsbPowerRevertStep`** | USB power settings (per-device) | USB-related optimizations (manual via `ExecutionScope.RecordStep()`) |
### Adding a Revert Command to Shell Calls
@@ -849,25 +996,24 @@ await ShellService.CMDAsync("powercfg /h off", "powercfg /h on");
"OptimizationName": "DisableTelemetry",
"AppliedAt": "2026-06-02T12:00:00Z",
"Steps": [
- { "Index": 0, "Type": "Registry", "Data": { ... } },
+ { "Index": 0, "Type": "Registry", "Data": { "..." } },
null, // null gap = failed step at this index
- { "Index": 2, "Type": "Service", "Data": { ... } }
+ { "Index": 2, "Type": "Service", "Data": { "..." } }
]
}
```
### Key Details
-- **Applied state** is inferred from file presence on disk (`RevertManager.IsAppliedAsync(id)`)
-- **Atomic writes**: writes to `.tmp` then `File.Replace()` — crash-safe
-- **Concurrent access**: per-file `SemaphoreSlim` locks prevent race conditions; 30-second timeout
-- **File locking**: `_fileLocks` dictionary (`ConcurrentDictionary<Guid, SemaphoreSlim>`) protects each revert file
-- **`ExecutionScope`** uses `AsyncLocal<ExecutionScope?>` for ambient step tracking. No need to pass context through parameters
-- **Revert executes steps in reverse order** (last applied = first reverted)
-- **Partial success**: revert continues even if some steps fail. Failed steps get retry actions recorded
-- **Retry**: `OptimizationService.RetryFailedStepsAsync()` can retry individual failed steps
-- **Upsert**: `RevertManager.UpsertRevertStepAtIndexAsync()` can add/replace revert steps at specific indices (used during retry)
-- **Step registry**: Revert step deserialization uses reflection-based `_stepRegistry` — new step types auto-register by implementing `IRevertStep` with a static `FromData(JObject)` method
+- **Applied state** is inferred from file presence on disk (`RevertManager.IsAppliedAsync(id)`).
+- **Atomic writes**: writes to `.tmp` then `File.Replace()` — crash-safe.
+- **Concurrent access**: per-file `SemaphoreSlim` locks prevent race conditions; 30-second timeout.
+- **`ExecutionScope`** uses `AsyncLocal<ExecutionScope?>` for ambient step tracking. No need to pass context through parameters.
+- **Revert executes steps in reverse order** (last applied = first reverted).
+- **Partial success**: revert continues even if some steps fail. Failed steps get retry actions recorded.
+- **Retry**: `OptimizationService.RetryFailedStepsAsync()` can retry individual failed steps; `RecordStepAtIndex()` preserves the original index layout.
+- **Upsert**: `RevertManager.UpsertRevertStepAtIndexAsync()` can add/replace revert steps at specific indices (used during retry).
+- **Step registry**: Revert step deserialization uses reflection-based `_stepRegistry` — new step types auto-register by implementing `IRevertStep` with a static `FromData(JObject)` method.
> **Important**: When you call provider services (`RegistryService.Write`, `ShellService.CMDAsync`, etc.), revert steps are recorded automatically. Do NOT manually create revert steps unless you're implementing a custom provider (like `UsbPowerRevertStep`).
@@ -886,42 +1032,26 @@ Tests use **xUnit v3** and follow an integration-style approach with real I/O.
| **Cleanup** | Use `try/finally` or `IDisposable` for test artifact cleanup |
| **Naming** | `{Method}_{Scenario}_{ExpectedResult}` — e.g., `ApplyAsync_Success_PersistsRevertDataFile` |
| **Logging** | Use `NullLogger<T>.Instance` / `NullLoggerFactory.Instance` for DI logging parameters |
-| **STA thread** | Tests involving `ContentDialogService` or WPF components must use `RunInStaThreadAsync` helper |
+| **STA thread** | Tests involving WPF components must use `RunInStaThreadAsync` helper (STA thread + `TaskCompletionSource`) |
### Test Structure
```
optimizerDuck.Test/
├── Common/Helpers/
-│ └── SystemRefreshServiceTests.cs
├── Domain/
│ ├── Customize/
-│ │ └── BaseCustomizeSettingTests.cs
│ ├── Exceptions/
-│ │ └── StepExecutionExceptionTests.cs
│ ├── Optimizations/
-│ │ ├── Models/
-│ │ │ └── Services/RegistryItemKindDetectionTests.cs
-│ │ └── PowerManagementTests.cs
│ └── Revert/Steps/
-│ ├── RevertStepSerializationTests.cs
-│ └── ScheduledTaskRevertStepTests.cs
└── Services/
- ├── ApplyRevertComprehensiveTests.cs
- ├── OptimizationServiceTests.cs
- ├── OptimizationServiceIntegrationTests.cs
- ├── OptimizationExecutionContextTests.cs
- ├── OptimizationServices/
- │ ├── RegistryServiceTests.cs
- │ ├── ServiceProcessServiceTests.cs
- │ ├── ShellServiceTests.cs
- │ └── ShellPolicyTests.cs
├── Managers/
- │ └── RevertManagerTests.cs
- ├── RegistryWatcherTests.cs
- └── SystemInfoServiceTests.cs
+ ├── OptimizationServices/
+ └── ApplyRevertComprehensiveTests.cs
```
+Mirror the app's structure: tests for `Services/OptimizationServices/` go in `Services/OptimizationServices/`, tests for domain models go in the matching `Domain/` subdirectory.
+
### Running Tests
```bash
@@ -930,11 +1060,14 @@ dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release
# Build + test in one step
dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release
+
+# Run a single test by name
+dotnet test optimizerDuck.Test/optimizerDuck.Test.csproj --configuration Release --no-build --filter "FullyQualifiedName~TestName"
```
### CI Integration
-The CI pipeline (`ci.yml`) runs:
+The CI pipeline (`.github/workflows/ci.yml`) runs:
```bash
dotnet restore optimizerDuck.slnx
@@ -956,7 +1089,7 @@ public class MyOptimizationTests
{
ApplyImpl = _ =>
{
- ExecutionScope.RecordStep("Test", "Step 1", true, ...);
+ ExecutionScope.RecordStep("Test", "Step 1", true);
return Task.FromResult(ApplyResult.True());
},
};
@@ -981,10 +1114,6 @@ public class MyOptimizationTests
}
```
-### Registering New Tests
-
-When adding tests for a new optimization or service, follow the existing directory structure. Tests for `OptimizationServices/` go in `Services/OptimizationServices/`, and tests for domain models go in the matching `Domain/` subdirectory.
-
---
# Coding Standards
@@ -995,7 +1124,7 @@ When adding tests for a new optimization or service, follow the existing directo
|---|---|---|
| File-scoped namespaces | Yes | `namespace X.Y;` |
| Collection expressions | Yes | `[]` for empty, `[item1, item2]` for lists |
-| Primary constructors | Some | Used in simple types |
+| Primary constructors | Yes | Used in services and simple types |
| Implicit usings | Yes | Enabled in `.csproj` |
| Nullable reference types | Yes | `<Nullable>enable</Nullable>` — handle nulls properly |
| Extension methods (`extension(T type)`) | Yes | C# 13 feature, used in `OptimizationTagsToDisplay` |
@@ -1005,11 +1134,10 @@ When adding tests for a new optimization or service, follow the existing directo
| Element | Convention | Example |
|---|---|---|
| Classes, enums, interfaces, methods, properties | `PascalCase` | `RegistryService`, `ApplyAsync` |
-| Private fields | `_camelCase` | `_lastError`, `registryService` |
+| Private fields | `_camelCase` | `_lastError` |
| Local variables, parameters | `camelCase` | `progress`, `serviceName` |
| Async methods | `*Async` suffix | `ChangeServiceStartupTypeAsync`, `CMDAsync` |
-| Public constants | `PascalCase` | `MaxRetries` |
-| Private constants | `_PascalCase` | `_defaultTimeout` |
+| Constants | `PascalCase` / `_PascalCase` | `MaxRetries` / `_defaultTimeout` |
### Formatting
@@ -1028,31 +1156,30 @@ When adding tests for a new optimization or service, follow the existing directo
- **No hardcoded strings** — always use `Translations.KeyName` or `Loc.Instance["Key"]`
- **Keep comments sparse** — existing code has almost none. Don't add unnecessary comments.
-- **No type error suppression** — handle types properly.
- **Prefer existing libraries** over new dependencies.
- **Prefer small, focused changes** over large refactors.
-- **Use `@formatter:off` / `@formatter:on`** comments around large, structured registry write blocks when needed to suppress automatic reformatting.
- **Never commit machine-specific paths or secrets.**
### Dependency Injection
-- Services, ViewModels, and Pages are registered as singletons in `App.xaml.cs`
-- Use constructor injection: `public class Foo(Bar bar, Baz baz)` or `public class Foo(ILogger<Foo> logger)`
-- Static provider services (`RegistryService`, `ShellService`, `ScheduledTaskService`, `ServiceProcessService`) are NOT injected — access them directly
-- Test doubles are hand-written (no mocking libraries like Moq)
+- Services, ViewModels, and Pages are registered as singletons in `App.xaml.cs`.
+- Use constructor injection: `public class Foo(Bar bar, Baz baz)` or `public class Foo(ILogger<Foo> logger)`.
+- Static provider services (`RegistryService`, `ShellService`, `ScheduledTaskService`, `ServiceProcessService`) are NOT injected — access them directly.
+- Test doubles are hand-written (no mocking libraries).
### Error Handling
| Layer | Practice |
|---|---|
| **Optimizations** | Return `ApplyResult.False("reason")` instead of throwing. Let `ExecutionScope` handle step-level failure tracking. |
-| **Provider services** | Use try/catch around system calls, log errors via `ExecutionScope.LogError`. Record failed steps with retry actions. |
+| **Provider services** | Use try/catch around system calls, log errors. Record failed steps with retry actions. |
| **ViewModels** | Catch exceptions in command handlers, show user-friendly snackbars. |
+| **Conditions** | Return `ConditionResult.Error()` or throw — `ConditionEvaluator` catches and maps to `Error` (which never blocks). |
| **Don't** | Catch exceptions you can't handle. Don't silently swallow all exceptions. |
### Global Error Handling
-The `App.xaml.cs` registers three global exception handlers:
+`App.xaml.cs` registers three global exception handlers:
- `AppDomain.CurrentDomain.UnhandledException` — catches fatal exceptions
- `TaskScheduler.UnobservedTaskException` — catches unobserved task exceptions
@@ -1066,37 +1193,23 @@ All crash details are logged to `%localappdata%\optimizerDuck\Crashes\crash_*.lo
### RESX Files
-All user-facing strings live in `Resources/Languages/Translations.resx`. Use the strongly-typed `Translations` class in C#, or `Loc.Instance["Key"]` for dynamic lookup.
+All user-facing strings live in `Resources/Languages/Translations.resx` (the English default). Use the strongly-typed `Translations` class in C#, or `Loc.Instance["Key"]` for dynamic lookup.
-- **Do not edit** `Translations.Designer.cs` directly — it's auto-generated
-- Use [ResXManager](https://marketplace.visualstudio.com/items?itemName=TomEnglert.ResXManager) (VS) or Rider's built-in resource editor
-- Preserve format parameters like `{0}`, `{1}` exactly
-- Keep strings concise — some UI cards have width limits
+- **Do not edit** `Translations.Designer.cs` directly — it's auto-generated.
+- Use [ResXManager](https://marketplace.visualstudio.com/items?itemName=TomEnglert.ResXManager) (VS) or Rider's built-in resource editor.
+- Preserve format parameters like `{0}`, `{1}` exactly.
+- Keep strings concise — some UI cards have width limits.
### Available Locales
-| Language | File |
-|---|---|
-| English | `Translations.resx` (default) |
-| German | `Translations.de-DE.resx` |
-| Vietnamese | `Translations.vi-VN.resx` |
-| Spanish | `Translations.es-ES.resx` |
-| French | `Translations.fr-FR.resx` |
-| Traditional Chinese | `Translations.zh-TW.resx` |
-| Simplified Chinese | `Translations.zh-CN.resx` |
-| Russian | `Translations.ru-RU.resx` |
-| Korean | `Translations.ko-KR.resx` |
-| Japanese | `Translations.ja-JP.resx` |
-| Polish | `Translations.pl-PL.resx` |
-| Turkish | `Translations.tr-TR.resx` |
-| Portuguese (Brazil) | `Translations.pt-BR.resx` |
-| Hebrew | `Translations.he-IL.resx` |
-
-> **Note**: 12 locale variants total, plus English as the default fallback.
+The app ships with **more than 15 languages**, and the list keeps growing. Instead of listing them here (which would go stale), check:
+
+- **The locale files themselves**: `optimizerDuck/Resources/Languages/` — one `Translations.{locale}.resx` per language, plus `Translations.resx` as the English default.
+- **The registration list**: `Languages` in `UI/ViewModels/Pages/SettingsViewModel.cs` — this is the authoritative list of languages shown in the UI.
### Adding a New Language
-1. Create `Translations.{locale}.resx` (e.g., `Translations.de-DE.resx`) with all the same keys as `Translations.resx`
+1. Create `Translations.{locale}.resx` (e.g., `Translations.de-DE.resx`) with all the same keys as `Translations.resx`.
2. Register the language in `UI/ViewModels/Pages/SettingsViewModel.cs`:
```csharp
@@ -1170,10 +1283,10 @@ In XAML:
```
4. **Open the PR**:
- - Describe **what** changed and **why**
- - If your PR has UI changes, **include a screenshot**
- - Link related issues: `Closes #42`
- - Mark as draft if still a work in progress
+ - Describe **what** changed and **why**.
+ - If your PR has UI changes, **include a screenshot**.
+ - Link related issues: `Closes #42`.
+ - Mark as draft if still a work in progress.
5. **Review**: A maintainer will review. Be open to feedback and respond promptly.
@@ -1181,6 +1294,7 @@ In XAML:
- [ ] Code follows existing patterns (discovery, attributes, async naming)
- [ ] Localization keys added to `Translations.resx` at minimum
+- [ ] Conditions declared where relevant (see [The Condition System](#the-condition-system))
- [ ] `dotnet build` succeeds (0 errors)
- [ ] `dotnet test` passes (all tests green)
- [ ] `dotnet csharpier .` has been run
@@ -1208,19 +1322,27 @@ The `.editorconfig` silences CA1416. If you're still seeing it, ensure you have
### My optimization isn't showing up in the UI
Checklist:
+
- Is it a **nested public class** inside a category class?
- Does the category class implement `IOptimizationCategory`?
- Does the optimization class extend `BaseOptimization`?
-- Does it have `[Optimization(Id = "...", ...)]` attribute?
+- Does it have an `[Optimization(Id = "...", ...)]` attribute?
- Are the localization keys added to `Translations.resx`?
- Has the optimization category been preloaded? (Check `OptimizationRegistry.IsPreloaded`)
+- Is a `Condition` blocking it? (See the next question)
+
+### My optimization/setting shows as "unsupported" (blocked)
+
+- Check the `Condition = typeof(...)` declared on the attribute.
+- Confirm the condition type implements `ICondition`, is concrete, and has a public parameterless constructor (`ConditionValidation` enforces this at startup).
+- Remember the item only blocks when **not** already applied; applied items always show their normal card.
### My customize setting isn't showing up
-Same checks as above but for `ICustomizeCategory` / `BaseCustomizeSetting`.
-- Does it have `[CustomizeSetting(Section = ..., Icon = ...)]`?
-- Is the `Section` enum value correctly spelled?
+- Does it have `[CustomizeSetting(Section = ..., Icon = ...)]`? (`Icon` is required.)
+- Is the `Section` value correctly spelled?
- Does the category class use the correct `[CustomizeCategory(PageType = ...)]` attribute?
+- Is a `Condition` blocking it?
### No revert data file after testing
@@ -1252,17 +1374,17 @@ Check that the optimization's `Id` GUID hasn't changed. Revert files are keyed b
### How do I add a new revert step type?
-1. Create a new class in `Domain/Revert/Steps/` that implements `IRevertStep`
-2. Add a static `FromData(JObject data)` method for deserialization
-3. The `RevertManager`'s reflection-based `_stepRegistry` will auto-discover it
-4. Record it via `ExecutionScope.RecordStep()` with your step as the `revertStep` parameter
+1. Create a new class in `Domain/Revert/Steps/` that implements `IRevertStep`.
+2. Add a static `FromData(JObject data)` method for deserialization.
+3. The `RevertManager`'s reflection-based `_stepRegistry` will auto-discover it.
+4. Record it via `ExecutionScope.RecordStep()` with your step as the `revertStep` parameter.
### How does the app handle crash safety?
-- Revert files use atomic writes (`.tmp` + `File.Replace`)
-- Crash logging writes to `%localappdata%\optimizerDuck\Crashes\crash_*.log`
-- `WmiHelper.Initialize()` at startup registers WMI cleanup for abnormal termination
-- App.xaml.cs registers 3 global exception handlers
+- Revert files use atomic writes (`.tmp` + `File.Replace`).
+- Crash logging writes to `%localappdata%\optimizerDuck\Crashes\crash_*.log`.
+- `WmiHelper.Initialize()` at startup registers WMI cleanup for abnormal termination.
+- `App.xaml.cs` registers 3 global exception handlers.
---