diff --git a/docs/getting-started.md b/docs/getting-started.md index f3f8955..44e998b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -10,13 +10,13 @@ The meta package is published as **`Skymly.DesignPatterns`** on [nuget.org](https://www.nuget.org/packages/Skymly.DesignPatterns). C# namespaces remain `DesignPatterns.*`. ```xml - + ``` Or from the command line: ```powershell -dotnet add package Skymly.DesignPatterns --version 0.2.2 +dotnet add package Skymly.DesignPatterns --version 0.2.3-preview1 ``` ::: warning Early preview @@ -26,9 +26,9 @@ Public APIs, generated code, and `DP###` diagnostics are **not stable** yet. Pin **Optional DI:** the DI integrations are separate packages and are not included in the meta package: ```powershell -dotnet add package Skymly.DesignPatterns.Extensions.DependencyInjection --version 0.2.2 +dotnet add package Skymly.DesignPatterns.Extensions.DependencyInjection --version 0.2.3-preview1 # Or, when using Autofac: -dotnet add package Skymly.DesignPatterns.Extensions.Autofac --version 0.2.2 +dotnet add package Skymly.DesignPatterns.Extensions.Autofac --version 0.2.3-preview1 ``` See [Dependency injection](./dependency-injection.md). diff --git a/docs/index.md b/docs/index.md index e6a9237..db4e134 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,7 +27,7 @@ features: ## Status ::: warning Early preview -Public APIs, generated code shapes, and diagnostic IDs are **not stable** yet. Install [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) `0.2.2` from nuget.org, or use a sibling clone / pin a commit until a stability announcement. +Public APIs, generated code shapes, and diagnostic IDs are **not stable** yet. Install [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) `0.2.3-preview1` from nuget.org, or use a sibling clone / pin a commit until a stability announcement. ::: ## Where to read next diff --git a/docs/reference.md b/docs/reference.md index d1f3604..f59afc3 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -12,12 +12,12 @@ | Package ID | Version | Contents | |------------|-------------------|----------| -| [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) | `0.2.2` | Meta package — runtime + source generator + analyzers + code fixes | -| [`Skymly.DesignPatterns.Extensions.DependencyInjection`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.DependencyInjection) | `0.2.2` | MSDI extensions + `RegisterDi` generation | -| [`Skymly.DesignPatterns.Extensions.Autofac`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.Autofac) | `0.2.2` | Autofac extensions + `RegisterAutofac` generation | +| [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) | `0.2.3-preview1` | Meta package — runtime + source generator + analyzers + code fixes | +| [`Skymly.DesignPatterns.Extensions.DependencyInjection`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.DependencyInjection) | `0.2.3-preview1` | MSDI extensions + `RegisterDi` generation | +| [`Skymly.DesignPatterns.Extensions.Autofac`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.Autofac) | `0.2.3-preview1` | Autofac extensions + `RegisterAutofac` generation | ```xml - + ``` ::: info Deprecated GitHub-only IDs diff --git a/docs/samples.md b/docs/samples.md index 7f61e77..eee3be8 100644 --- a/docs/samples.md +++ b/docs/samples.md @@ -40,7 +40,7 @@ The main [DesignPatterns](https://github.com/Skymly/DesignPatterns) CI checks ou ## NuGet consumption -Package **`Skymly.DesignPatterns` `0.2.2`** is on [nuget.org](https://www.nuget.org/packages/Skymly.DesignPatterns) (early preview). In the samples repo, switch off the sibling project reference: +Package **`Skymly.DesignPatterns` `0.2.3-preview1`** is on [nuget.org](https://www.nuget.org/packages/Skymly.DesignPatterns) (early preview). In the samples repo, switch off the sibling project reference: ```powershell dotnet run --project DesignPatterns.Samples.Strategy -c Release -p:UseLocalDesignPatterns=false diff --git a/docs/singleton.md b/docs/singleton.md index 1d53e62..693ce14 100644 --- a/docs/singleton.md +++ b/docs/singleton.md @@ -16,10 +16,39 @@ public sealed partial class AppSettings // Generated: AppSettings.Instance ``` +## Async initialization + +Set `InitializeAsync` to the name of a static initializer returning `Task` or +`ValueTask`. The generator validates the signature and emits +`GetInstanceAsync()` instead of the synchronous `Instance` property. + +```csharp +[GenerateSingleton(InitializeAsync = nameof(InitializeAsync))] +public sealed partial class AppSettings +{ + public bool IsInitialized { get; private set; } + + public static ValueTask InitializeAsync( + AppSettings instance, + CancellationToken cancellationToken) + { + instance.IsInitialized = true; + return ValueTask.CompletedTask; + } +} + +var settings = await AppSettings.GetInstanceAsync(); +``` + ## Diagnostics - **DP001** — type must be `partial` - **DP002** — invalid target shape +- **DP067** — async initializer has an invalid signature +- **DP068** — generated Singleton is also registered as a DI Singleton +- **DP069** — non-thread-safe generated Singleton contains mutable instance state +- **DP070** — mutable static Singleton candidate +- **DP071** — mutable static Singleton is also registered as a DI Singleton ## Sample diff --git a/docs/zh/getting-started.md b/docs/zh/getting-started.md index 2281536..173926f 100644 --- a/docs/zh/getting-started.md +++ b/docs/zh/getting-started.md @@ -10,13 +10,13 @@ 元包在 [nuget.org](https://www.nuget.org/packages/Skymly.DesignPatterns) 上的 ID 为 **`Skymly.DesignPatterns`**。C# 命名空间仍为 `DesignPatterns.*`。 ```xml - + ``` 也可以使用命令行安装： ```powershell -dotnet add package Skymly.DesignPatterns --version 0.2.2 +dotnet add package Skymly.DesignPatterns --version 0.2.3-preview1 ``` ::: warning 早期预览 @@ -26,9 +26,9 @@ dotnet add package Skymly.DesignPatterns --version 0.2.2 **可选 DI：** DI 集成作为独立包发布，不包含在元包中： ```powershell -dotnet add package Skymly.DesignPatterns.Extensions.DependencyInjection --version 0.2.2 +dotnet add package Skymly.DesignPatterns.Extensions.DependencyInjection --version 0.2.3-preview1 # 或使用 Autofac： -dotnet add package Skymly.DesignPatterns.Extensions.Autofac --version 0.2.2 +dotnet add package Skymly.DesignPatterns.Extensions.Autofac --version 0.2.3-preview1 ``` 见[依赖注入](./dependency-injection.md)。 diff --git a/docs/zh/index.md b/docs/zh/index.md index d5b09f4..a3351e7 100644 --- a/docs/zh/index.md +++ b/docs/zh/index.md @@ -27,7 +27,7 @@ features: ## 项目状态 ::: warning 早期预览 -公共 API、生成代码形态与诊断 ID **尚未稳定**。请从 nuget.org 安装 [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) `0.2.2`，或使用 sibling 克隆 / 固定 commit，直至稳定公告。 +公共 API、生成代码形态与诊断 ID **尚未稳定**。请从 nuget.org 安装 [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) `0.2.3-preview1`，或使用 sibling 克隆 / 固定 commit，直至稳定公告。 ::: ## 下一步 diff --git a/docs/zh/reference.md b/docs/zh/reference.md index ea10217..fe2f893 100644 --- a/docs/zh/reference.md +++ b/docs/zh/reference.md @@ -12,12 +12,12 @@ | 包 ID | 版本 | 内容 | |-------|----------|------| -| [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) | `0.2.2` | 元包 — 运行时 + 源生成器 + Analyzer + CodeFix | -| [`Skymly.DesignPatterns.Extensions.DependencyInjection`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.DependencyInjection) | `0.2.2` | MSDI + `RegisterDi` 生成 | -| [`Skymly.DesignPatterns.Extensions.Autofac`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.Autofac) | `0.2.2` | Autofac + `RegisterAutofac` 生成 | +| [`Skymly.DesignPatterns`](https://www.nuget.org/packages/Skymly.DesignPatterns) | `0.2.3-preview1` | 元包 — 运行时 + 源生成器 + Analyzer + CodeFix | +| [`Skymly.DesignPatterns.Extensions.DependencyInjection`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.DependencyInjection) | `0.2.3-preview1` | MSDI + `RegisterDi` 生成 | +| [`Skymly.DesignPatterns.Extensions.Autofac`](https://www.nuget.org/packages/Skymly.DesignPatterns.Extensions.Autofac) | `0.2.3-preview1` | Autofac + `RegisterAutofac` 生成 | ```xml - + ``` ::: info 已弃用的 GitHub 包 ID diff --git a/docs/zh/samples.md b/docs/zh/samples.md index 6c339b4..f2e9add 100644 --- a/docs/zh/samples.md +++ b/docs/zh/samples.md @@ -40,7 +40,7 @@ dotnet run --project DesignPatterns.Samples.Strategy -c Release ## NuGet 消费 -**`Skymly.DesignPatterns` `0.2.2`** 已发布至 [nuget.org](https://www.nuget.org/packages/Skymly.DesignPatterns)（早期预览）。在示例仓关闭 sibling 项目引用： +**`Skymly.DesignPatterns` `0.2.3-preview1`** 已发布至 [nuget.org](https://www.nuget.org/packages/Skymly.DesignPatterns)（早期预览）。在示例仓关闭 sibling 项目引用： ```powershell dotnet run --project DesignPatterns.Samples.Strategy -c Release -p:UseLocalDesignPatterns=false diff --git a/docs/zh/singleton.md b/docs/zh/singleton.md index 1f6572a..52f0891 100644 --- a/docs/zh/singleton.md +++ b/docs/zh/singleton.md @@ -14,10 +14,42 @@ public sealed partial class AppSettings } ``` +## 异步初始化 + +将 `InitializeAsync` 设置为静态初始化方法的名称。该方法必须返回 +`Task` 或 `ValueTask`，并接收生成的实例与 `CancellationToken`。生成器会校验 +签名，并生成 `GetInstanceAsync()`，不再生成同步的 `Instance` 属性。 + +```csharp +[GenerateSingleton(InitializeAsync = nameof(InitializeAsync))] +public sealed partial class AppSettings +{ + public bool IsInitialized { get; private set; } + + public static ValueTask InitializeAsync( + AppSettings instance, + CancellationToken cancellationToken) + { + instance.IsInitialized = true; + return ValueTask.CompletedTask; + } +} + +var settings = await AppSettings.GetInstanceAsync(); +``` + ## 诊断 DP001、DP002 — 见 [诊断](./diagnostics.md)。 +Singleton 生命周期相关诊断： + +- **DP067** — 异步初始化器签名无效 +- **DP068** — 生成的 Singleton 同时注册为 DI Singleton +- **DP069** — 非线程安全的生成 Singleton 含可变实例状态 +- **DP070** — 可变静态 Singleton 候选 +- **DP071** — 可变静态 Singleton 同时注册为 DI Singleton + ## 示例 [DesignPatterns.Samples.GenerateSingleton](https://github.com/Skymly/DesignPatterns.Samples/tree/main/DesignPatterns.Samples.GenerateSingleton)