From 1acc157fc194bdcc37b53c236689f9a71f890cd1 Mon Sep 17 00:00:00 2001 From: "codebelt-aicia[bot]" Date: Thu, 25 Jun 2026 22:58:36 +0000 Subject: [PATCH 1/6] V10.1.5/service update --- .../PackageReleaseNotes.txt | 6 ++++++ .../PackageReleaseNotes.txt | 6 ++++++ .../PackageReleaseNotes.txt | 6 ++++++ .../PackageReleaseNotes.txt | 6 ++++++ CHANGELOG.md | 4 ++++ Directory.Packages.props | 20 +++++++++---------- 6 files changed, 38 insertions(+), 10 deletions(-) diff --git a/.nuget/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json/PackageReleaseNotes.txt b/.nuget/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json/PackageReleaseNotes.txt index f22ba95..c33c89d 100644 --- a/.nuget/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json/PackageReleaseNotes.txt +++ b/.nuget/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json/PackageReleaseNotes.txt @@ -1,3 +1,9 @@ +Version: 10.1.5 +Availability: .NET 10 and .NET 9 + +# ALM +- CHANGED Dependencies have been upgraded to the latest compatible versions for all supported target frameworks (TFMs) + Version: 10.1.4 Availability: .NET 10 and .NET 9 diff --git a/.nuget/Codebelt.Extensions.AspNetCore.Newtonsoft.Json/PackageReleaseNotes.txt b/.nuget/Codebelt.Extensions.AspNetCore.Newtonsoft.Json/PackageReleaseNotes.txt index d4e1d62..36346da 100644 --- a/.nuget/Codebelt.Extensions.AspNetCore.Newtonsoft.Json/PackageReleaseNotes.txt +++ b/.nuget/Codebelt.Extensions.AspNetCore.Newtonsoft.Json/PackageReleaseNotes.txt @@ -1,3 +1,9 @@ +Version: 10.1.5 +Availability: .NET 10 and .NET 9 + +# ALM +- CHANGED Dependencies have been upgraded to the latest compatible versions for all supported target frameworks (TFMs) + Version: 10.1.4 Availability: .NET 10 and .NET 9 diff --git a/.nuget/Codebelt.Extensions.Newtonsoft.Json.App/PackageReleaseNotes.txt b/.nuget/Codebelt.Extensions.Newtonsoft.Json.App/PackageReleaseNotes.txt index 435c9c9..ac08443 100644 --- a/.nuget/Codebelt.Extensions.Newtonsoft.Json.App/PackageReleaseNotes.txt +++ b/.nuget/Codebelt.Extensions.Newtonsoft.Json.App/PackageReleaseNotes.txt @@ -1,3 +1,9 @@ +Version: 10.1.5 +Availability: .NET 10 and .NET 9 + +# ALM +- CHANGED Dependencies have been upgraded to the latest compatible versions for all supported target frameworks (TFMs) + Version: 10.1.4 Availability: .NET 10 and .NET 9 diff --git a/.nuget/Codebelt.Extensions.Newtonsoft.Json/PackageReleaseNotes.txt b/.nuget/Codebelt.Extensions.Newtonsoft.Json/PackageReleaseNotes.txt index b78022b..debc7cf 100644 --- a/.nuget/Codebelt.Extensions.Newtonsoft.Json/PackageReleaseNotes.txt +++ b/.nuget/Codebelt.Extensions.Newtonsoft.Json/PackageReleaseNotes.txt @@ -1,3 +1,9 @@ +Version: 10.1.5 +Availability: .NET 10, .NET 9 and .NET Standard 2.0 + +# ALM +- CHANGED Dependencies have been upgraded to the latest compatible versions for all supported target frameworks (TFMs) + Version: 10.1.4 Availability: .NET 10, .NET 9 and .NET Standard 2.0 diff --git a/CHANGELOG.md b/CHANGELOG.md index a3907d7..677d75c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ For more details, please refer to `PackageReleaseNotes.txt` on a per assembly ba > [!NOTE] > Changelog entries prior to version 8.4.0 was migrated from previous versions of Cuemon.Extensions.Newtonsoft.Json, Cuemon.Extensions.AspNetCore.Newtonsoft.Json and Cuemon.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json. +## [10.1.5] - 2026-06-25 + +This is a service update that focuses on package dependencies. + ## [10.1.4] - 2026-06-05 This is a patch release focused on expanding test coverage infrastructure, enhancing CI/CD capabilities, and establishing official guidance for AI agent contributions. diff --git a/Directory.Packages.props b/Directory.Packages.props index 76f4cb4..e23b6f3 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -3,16 +3,16 @@ true - - - - - - - - - - + + + + + + + + + + From cefcd32ec08abe519c9bc33a50ed3ccef1aaee88 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Tue, 30 Jun 2026 01:18:44 +0200 Subject: [PATCH 2/6] =?UTF-8?q?=F0=9F=93=9A=20add=20type=20api=20documenta?= =?UTF-8?q?tion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add DocFX type overwrite files for all public APIs under .docfx/api/types/. Update namespace documentation pages with enhanced descriptions and Extension Members tables. Configure docfx.json to include type and namespace overwrite files in separate subdirectories. Bump nginx base image to 1.31.2-alpine. --- .docfx/Dockerfile.docfx | 2 +- ...pNetCore.Mvc.Formatters.Newtonsoft.Json.md | 7 +- ...s.AspNetCore.Newtonsoft.Json.Converters.md | 8 +-- ...s.AspNetCore.Newtonsoft.Json.Formatters.md | 4 +- ...t.Extensions.AspNetCore.Newtonsoft.Json.md | 15 ++++ ...t.Extensions.Newtonsoft.Json.Converters.md | 6 +- ...t.Extensions.Newtonsoft.Json.Formatters.md | 2 +- ...xtensions.Newtonsoft.Json.Serialization.md | 4 +- .../Codebelt.Extensions.Newtonsoft.Json.md | 7 +- ...ft.Json.JsonSerializationInputFormatter.md | 27 ++++++++ ...t.Json.JsonSerializationMvcOptionsSetup.md | 35 ++++++++++ ...t.Json.JsonSerializationOutputFormatter.md | 27 ++++++++ ...t.Json.JsonSerializerSettingsExtensions.md | 69 +++++++++++++++++++ ...rs.Newtonsoft.Json.MvcBuilderExtensions.md | 49 +++++++++++++ ...ewtonsoft.Json.MvcCoreBuilderExtensions.md | 40 +++++++++++ ...rters.JsonConverterCollectionExtensions.md | 25 +++++++ ....Formatters.ServiceCollectionExtensions.md | 36 ++++++++++ ...onsoft.Json.ServiceCollectionExtensions.md | 27 ++++++++ ...soft.Json.Converters.ExceptionConverter.md | 34 +++++++++ ...rters.JsonConverterCollectionExtensions.md | 34 +++++++++ ...son.Converters.StringFlagsEnumConverter.md | 32 +++++++++ ...erters.TransientFaultExceptionConverter.md | 47 +++++++++++++ ...Newtonsoft.Json.DynamicContractResolver.md | 29 ++++++++ ...Json.Formatters.NewtonsoftJsonFormatter.md | 31 +++++++++ ...rmatters.NewtonsoftJsonFormatterOptions.md | 28 ++++++++ ...debelt.Extensions.Newtonsoft.Json.JData.md | 26 +++++++ ....Extensions.Newtonsoft.Json.JDataResult.md | 23 +++++++ ...s.Newtonsoft.Json.JDataResultExtensions.md | 34 +++++++++ ...ns.Newtonsoft.Json.JsonConverterFactory.md | 30 ++++++++ ...t.Json.JsonSerializerSettingsExtensions.md | 24 +++++++ ...ns.Newtonsoft.Json.JsonWriterExtensions.md | 34 +++++++++ ...erialization.ContractResolverExtensions.md | 23 +++++++ ...ons.Newtonsoft.Json.ValidatorExtensions.md | 28 ++++++++ .docfx/docfx.json | 6 +- 34 files changed, 830 insertions(+), 23 deletions(-) create mode 100644 .docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.md create mode 100644 .docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationInputFormatter.md create mode 100644 .docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationMvcOptionsSetup.md create mode 100644 .docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationOutputFormatter.md create mode 100644 .docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializerSettingsExtensions.md create mode 100644 .docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.MvcBuilderExtensions.md create mode 100644 .docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.MvcCoreBuilderExtensions.md create mode 100644 .docfx/api/types/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Converters.JsonConverterCollectionExtensions.md create mode 100644 .docfx/api/types/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters.ServiceCollectionExtensions.md create mode 100644 .docfx/api/types/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.ServiceCollectionExtensions.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.ExceptionConverter.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.JsonConverterCollectionExtensions.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.StringFlagsEnumConverter.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.TransientFaultExceptionConverter.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.DynamicContractResolver.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Formatters.NewtonsoftJsonFormatter.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Formatters.NewtonsoftJsonFormatterOptions.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JData.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JDataResult.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JDataResultExtensions.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JsonConverterFactory.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JsonSerializerSettingsExtensions.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JsonWriterExtensions.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Serialization.ContractResolverExtensions.md create mode 100644 .docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.ValidatorExtensions.md diff --git a/.docfx/Dockerfile.docfx b/.docfx/Dockerfile.docfx index 9d42262..465ff57 100644 --- a/.docfx/Dockerfile.docfx +++ b/.docfx/Dockerfile.docfx @@ -1,4 +1,4 @@ -ο»ΏARG NGINX_VERSION=1.31.0-alpine +ο»ΏARG NGINX_VERSION=1.31.2-alpine FROM --platform=$BUILDPLATFORM nginx:${NGINX_VERSION} AS base RUN rm -rf /usr/share/nginx/html/* diff --git a/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.md b/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.md index e90806a..c749687 100644 --- a/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.md +++ b/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.md @@ -2,17 +2,16 @@ uid: Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json summary: *content --- -The `Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json` namespace contains both types and extension methods that complements the `Cuemon.Extensions.Newtonsoft.Json` namespace while being an addition to the `Microsoft.AspNetCore.Mvc` namespace. Provides JSON formatters for ASP.NET Core that is powered by Newtonsoft.Json. +The `Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json` namespace inserts Newtonsoft.Json-backed input and output formatters at the front of the ASP.NET Core MVC pipeline, letting MVC negotiate requests and responses through Newtonsoft.Json while leaving the built-in formatters available behind them. Use it in ASP.NET Core MVC or Web API applications that must keep Newtonsoft.Json converters, contract resolvers, or fault formatting without abandoning MVC's formatter infrastructure. Start with `AddNewtonsoftJsonFormatters` on `IMvcCoreBuilder` to register both the formatters and `NewtonsoftJsonFormatterOptions`; use `AddNewtonsoftJsonFormattersOptions` when MVC formatter insertion is already handled elsewhere and you still need the shared formatter options plus the exception-response formatter. [!INCLUDE [availability-modern](../../includes/availability-modern.md)] Complements: [Codebelt.Extensions.Newtonsoft.Json namespace](/api/extensions/jsonnet/Cuemon.Extensions.Newtonsoft.Json.html) πŸ“˜ -### Extension Methods +### Extension Members |Type|Ext|Methods| |--:|:-:|---| -|HttpExceptionDescriptorResponseHandler|⬇️|`AddNewtonsoftJsonResponseHandler`| -|JsonSerializerSettings|⬇️|`Use{T}`| |IMvcBuilder|⬇️|`AddNewtonsoftJsonFormatters`, `AddNewtonsoftJsonFormattersOptions`| |IMvcCoreBuilder|⬇️|`AddNewtonsoftJsonFormatters`, `AddNewtonsoftJsonFormattersOptions`| +|JsonSerializerSettings|⬇️|`Use`| diff --git a/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Converters.md b/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Converters.md index 82807cc..dce0851 100644 --- a/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Converters.md +++ b/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Converters.md @@ -2,14 +2,14 @@ uid: Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Converters summary: *content --- -The `Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Converters` namespace contains extension methods that complements the `Cuemon.Extensions.Newtonsoft.Json.Converters` namespace. +The `Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Converters` namespace registers ASP.NET Core-specific Json.NET converters β€” `ProblemDetails`, `HttpExceptionDescriptor`, and `StringValues` β€” into a converter collection. Use this namespace in ASP.NET Core applications where HTTP error responses must serialize through the standard `IHttpExceptionDescriptorResponseFormatter` pipeline. Start with `AddHttpExceptionDescriptorConverter` on `ICollection` to register an `HttpExceptionDescriptor` converter with optional options; `AddProblemDetailsConverter` and `AddStringValuesConverter` handle the remaining ASP.NET Core types. [!INCLUDE [availability-modern](../../includes/availability-modern.md)] -Complements: [Codebelt.Extensions.Newtonsoft.Json namespace](/api/extensions/jsonnet/Cuemon.Extensions.Newtonsoft.Json.Converters.html) πŸ“˜ +Complements: [Codebelt.Extensions.Newtonsoft.Json.Converters namespace](/api/extensions/jsonnet/Cuemon.Extensions.Newtonsoft.Json.Converters.html) πŸ“˜ -### Extension Methods +### Extension Members |Type|Ext|Methods| |--:|:-:|---| -|JsonConverter|⬇️|`AddHttpExceptionDescriptorConverter`, `AddStringValuesConverter`, `AddProblemDetailsConverter`| +|ICollection<JsonConverter>|⬇️|`AddHttpExceptionDescriptorConverter`, `AddProblemDetailsConverter`, `AddStringValuesConverter`| diff --git a/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters.md b/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters.md index 116b382..c4663e1 100644 --- a/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters.md +++ b/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters.md @@ -2,13 +2,13 @@ uid: Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters summary: *content --- -The `Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters` namespace contains both types and extension methods that complements the `Cuemon.Extensions.Newtonsoft.Json` namespace while being an addition to the `Microsoft.AspNetCore.Mvc` namespace. Provides JSON formatters for ASP.NET Core that is powered by Newtonsoft.Json. +The `Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters` namespace registers `NewtonsoftJsonFormatterOptions` and the `IHttpExceptionDescriptorResponseFormatter` into ASP.NET Core's `IServiceCollection`. Start with `AddNewtonsoftJsonExceptionResponseFormatter` on `IServiceCollection` to wire up exception-to-JSON formatting with the response formatter registered; use `AddNewtonsoftJsonFormatterOptions` when you only need the options registered without the response formatter. [!INCLUDE [availability-modern](../../includes/availability-modern.md)] Complements: [Codebelt.Extensions.Newtonsoft.Json namespace](/api/extensions/jsonnet/Cuemon.Extensions.Newtonsoft.Json.html) πŸ“˜ -### Extension Methods +### Extension Members |Type|Ext|Methods| |--:|:-:|---| diff --git a/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.md b/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.md new file mode 100644 index 0000000..137d1a8 --- /dev/null +++ b/.docfx/api/namespaces/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.md @@ -0,0 +1,15 @@ +--- +uid: Codebelt.Extensions.AspNetCore.Newtonsoft.Json +summary: *content +--- +The `Codebelt.Extensions.AspNetCore.Newtonsoft.Json` namespace wires Newtonsoft.Json into ASP.NET Core's dependency injection container so exception responses serialize through `IHttpExceptionDescriptorResponseFormatter` without manual wiring. Use it in any ASP.NET Core project where structured JSON error responses must flow through Newtonsoft.Json serialization. Call `AddMinimalNewtonsoftJsonOptions` on `IServiceCollection` to register `NewtonsoftJsonFormatterOptions` and the response formatter in a single call β€” this is the primary entry point in this namespace. + +[!INCLUDE [availability-modern](../../includes/availability-modern.md)] + +Complements: [Codebelt.Extensions.Newtonsoft.Json namespace](/api/extensions/jsonnet/Cuemon.Extensions.Newtonsoft.Json.html) πŸ“˜ + +### Extension Members + +|Type|Ext|Methods| +|--:|:-:|---| +|IServiceCollection|⬇️|`AddMinimalNewtonsoftJsonOptions`| diff --git a/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.Converters.md b/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.Converters.md index c6151bf..ce71c04 100644 --- a/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.Converters.md +++ b/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.Converters.md @@ -2,14 +2,14 @@ uid: Codebelt.Extensions.Newtonsoft.Json.Converters summary: *content --- -The `Codebelt.Extensions.Newtonsoft.Json.Converters` namespace contains both types and extension methods that complements the `Newtonsoft.Json.Converters` namespace. +The `Codebelt.Extensions.Newtonsoft.Json.Converters` namespace provides Newtonsoft.Json converters for enums, exceptions, failures, and data pairs, plus extension methods that register them into a `JsonConverter` collection. Use `AddStringEnumConverter` to serialize enums as their string names, `AddExceptionConverter` to write exceptions with configurable stack-trace and data inclusion, and the remaining converters for specialized `TransientFaultException`, `DataPair`, and `Failure` serialization. [!INCLUDE [availability-default](../../includes/availability-default.md)] Complements: [Newtonsoft.Json.Converters namespace](https://www.newtonsoft.com/json/help/html/N_Newtonsoft_Json_Converters.htm) πŸ”— -### Extension Methods +### Extension Members |Type|Ext|Methods| |--:|:-:|---| -|JsonConverter|⬇️|`AddStringEnumConverter`, `AddStringFlagsEnumConverter`, `AddExceptionDescriptorConverterOf{T}`, `AddExceptionConverter`, `AddDataPairConverter`, `AddTransientFaultExceptionConverter`, `AddFailureConverter`| +|ICollection|⬇️|`AddStringEnumConverter`, `AddStringFlagsEnumConverter`, `AddExceptionDescriptorConverterOf`, `AddExceptionConverter`, `AddDataPairConverter`, `AddTransientFaultExceptionConverter`, `AddFailureConverter`| diff --git a/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.Formatters.md b/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.Formatters.md index 8a754f6..9a32814 100644 --- a/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.Formatters.md +++ b/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.Formatters.md @@ -2,7 +2,7 @@ uid: Codebelt.Extensions.Newtonsoft.Json.Formatters summary: *content --- -The `Codebelt.Extensions.Newtonsoft.Json.Formatters` namespace contains types that are used to serialize and deserialize objects into and from JSON format using a generic signature. +The `Codebelt.Extensions.Newtonsoft.Json.Formatters` namespace provides `NewtonsoftJsonFormatter`, a stream-based serializer/deserializer that converts objects to and from JSON using Newtonsoft.Json, and `NewtonsoftJsonFormatterOptions` for configuring `JsonSerializerSettings`, supported media types, sensitivity details, and converter collections. Use `NewtonsoftJsonFormatter` when you need JSON serialization with a generic `StreamFormatter` pipeline, such as in ASP.NET Core input/output formatters. [!INCLUDE [availability-default](../../includes/availability-default.md)] diff --git a/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.Serialization.md b/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.Serialization.md index 089464d..378a77c 100644 --- a/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.Serialization.md +++ b/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.Serialization.md @@ -2,13 +2,13 @@ uid: Codebelt.Extensions.Newtonsoft.Json.Serialization summary: *content --- -The `Codebelt.Extensions.Newtonsoft.Json.Serialization` namespace contains extension methods that help in the serialization process. +The `Codebelt.Extensions.Newtonsoft.Json.Serialization` namespace resolves the configured `NamingStrategy` from any `IContractResolver`, saving you from type-checking the resolver at runtime. Call `ResolveNamingStrategyOrDefault` on an `IContractResolver` to extract its `NamingStrategy` (for example, `CamelCaseNamingStrategy` from `CamelCasePropertyNamesContractResolver`) or fall back to a default when none is set. This is the sole entry point in this namespace. [!INCLUDE [availability-default](../../includes/availability-default.md)] Complements: [Newtonsoft.Json.Serialization namespace](https://www.newtonsoft.com/json/help/html/N_Newtonsoft_Json_Serialization.htm) πŸ”— -### Extension Methods +### Extension Members |Type|Ext|Methods| |--:|:-:|---| diff --git a/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.md b/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.md index c8003b1..5806d83 100644 --- a/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.md +++ b/.docfx/api/namespaces/Codebelt.Extensions.Newtonsoft.Json.md @@ -2,18 +2,17 @@ uid: Codebelt.Extensions.Newtonsoft.Json summary: *content --- -The `Codebelt.Extensions.Newtonsoft.Json` namespace contains both types and extension methods that complements the `Newtonsoft.Json` namespace by adding new ways of working with JSON; both in terms of serialization and parsing. +The `Codebelt.Extensions.Newtonsoft.Json` namespace helps you focus on your domain objects instead of writing boilerplate JSON serialization code. When you need dynamic converter creation, custom contract resolution per property, or rich JSON parsing that surfaces path and value details, this namespace provides the building blocks. Start with `JData.ReadAll` to parse JSON into navigable `JDataResult` sequences; use `JsonConverterFactory.Create` when you need a custom `JsonConverter` from a delegate; reach for `DynamicContractResolver.Create` when per-property contract customization is required. [!INCLUDE [availability-default](../../includes/availability-default.md)] Complements: [Newtonsoft.Json namespace](https://www.newtonsoft.com/json/help/html/N_Newtonsoft_Json.htm) πŸ”— -### Extension Methods +### Extension Members |Type|Ext|Methods| |--:|:-:|---| -|JDataResult|⬇️|`Flatten`, `ExtractArrayValues`, `ExtractObjectValues`| -|JsonReader|⬇️|`ToHierarchy`| +|IEnumerable<JDataResult>|⬇️|`Flatten`, `ExtractArrayValues`, `ExtractObjectValues`| |JsonSerializerSettings|⬇️|`ApplyToDefaultSettings`| |JsonWriter|⬇️|`WriteObject`, `WritePropertyName`| |Validator|⬇️|`InvalidJsonDocument`| diff --git a/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationInputFormatter.md b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationInputFormatter.md new file mode 100644 index 0000000..908b193 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationInputFormatter.md @@ -0,0 +1,27 @@ +--- +uid: Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationInputFormatter +example: +- *content +--- + +Create `JsonSerializationInputFormatter` directly when you want to confirm which JSON media types and encodings MVC will accept before the formatter is inserted into `MvcOptions`. + +```csharp +// Program.cs +using System; +using System.Linq; +using System.Net.Http.Headers; +using Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json; +using Codebelt.Extensions.Newtonsoft.Json.Formatters; + +var options = new NewtonsoftJsonFormatterOptions(); +options.SupportedMediaTypes = options.SupportedMediaTypes + .Append(MediaTypeHeaderValue.Parse("application/vnd.weather+json")) + .ToArray(); + +var formatter = new JsonSerializationInputFormatter(options); + +Console.WriteLine(formatter.SupportedMediaTypes.Any(mediaType => mediaType == "application/json")); +Console.WriteLine(formatter.SupportedMediaTypes.Any(mediaType => mediaType == "application/vnd.weather+json")); +Console.WriteLine(formatter.SupportedEncodings.Count); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationMvcOptionsSetup.md b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationMvcOptionsSetup.md new file mode 100644 index 0000000..4cdfd2e --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationMvcOptionsSetup.md @@ -0,0 +1,35 @@ +--- +uid: Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationMvcOptionsSetup +example: +- *content +--- + +Use `JsonSerializationMvcOptionsSetup` when you want `MvcOptions` to prefer the Newtonsoft.Json formatters first while preserving any later formatters MVC already knows about. + +```csharp +// Program.cs +using System; +using System.Linq; +using Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json; +using Codebelt.Extensions.Newtonsoft.Json.Formatters; +using Microsoft.AspNetCore.Mvc; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Options; +using Newtonsoft.Json; + +var services = new ServiceCollection(); +services.Configure(options => options.Settings.Formatting = Formatting.None); +services.AddSingleton, JsonSerializationMvcOptionsSetup>(); + +var provider = services.BuildServiceProvider(); +var mvcOptions = new MvcOptions(); + +foreach (var configurator in provider.GetServices>()) +{ + configurator.Configure(mvcOptions); +} + +Console.WriteLine(mvcOptions.OutputFormatters[0] is JsonSerializationOutputFormatter); +Console.WriteLine(mvcOptions.InputFormatters[0] is JsonSerializationInputFormatter); +Console.WriteLine(mvcOptions.OutputFormatters.OfType().Count()); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationOutputFormatter.md b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationOutputFormatter.md new file mode 100644 index 0000000..89ed1f2 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationOutputFormatter.md @@ -0,0 +1,27 @@ +--- +uid: Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializationOutputFormatter +example: +- *content +--- + +Create `JsonSerializationOutputFormatter` directly when you need to inspect the response media types MVC will negotiate after you customize the shared Newtonsoft.Json formatter options. + +```csharp +// Program.cs +using System; +using System.Linq; +using System.Net.Http.Headers; +using Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json; +using Codebelt.Extensions.Newtonsoft.Json.Formatters; + +var options = new NewtonsoftJsonFormatterOptions(); +options.SupportedMediaTypes = options.SupportedMediaTypes + .Append(MediaTypeHeaderValue.Parse("application/vnd.invoice+json")) + .ToArray(); + +var formatter = new JsonSerializationOutputFormatter(options); + +Console.WriteLine(formatter.SupportedMediaTypes.Any(mediaType => mediaType == "application/problem+json")); +Console.WriteLine(formatter.SupportedMediaTypes.Any(mediaType => mediaType == "application/vnd.invoice+json")); +Console.WriteLine(formatter.SupportedEncodings.Count); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializerSettingsExtensions.md b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializerSettingsExtensions.md new file mode 100644 index 0000000..aee0016 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializerSettingsExtensions.md @@ -0,0 +1,69 @@ +--- +uid: Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializerSettingsExtensions +example: +- *content +--- + +Use `JsonSerializerSettingsExtensions.Use` when you already have a `JsonSerializerSettings` instance and want to copy a reusable formatter profile into it before MVC applies the settings to input and output formatters. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json; +using Cuemon.Configuration; +using Newtonsoft.Json; +using Newtonsoft.Json.Serialization; + +var target = new JsonSerializerSettings(); + +target.Use(settings => +{ + settings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore; +}); + +Console.WriteLine(target.Formatting); +Console.WriteLine(target.NullValueHandling); +Console.WriteLine(target.ReferenceLoopHandling); +Console.WriteLine(target.ContractResolver is CamelCasePropertyNamesContractResolver); + +sealed class MvcJsonSerializerSettings : JsonSerializerSettings, IParameterObject +{ + public MvcJsonSerializerSettings() + { + Formatting = Formatting.Indented; + NullValueHandling = NullValueHandling.Ignore; + ContractResolver = new CamelCasePropertyNamesContractResolver(); + } +} +``` + +--- +uid: Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.JsonSerializerSettingsExtensions.Use``1(Newtonsoft.Json.JsonSerializerSettings,System.Action{``0}) +example: +- *content +--- + +Call `Use` on the target `JsonSerializerSettings` instance when a formatter profile already captures the JSON conventions you want MVC to reuse. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json; +using Cuemon.Configuration; +using Newtonsoft.Json; + +var target = new JsonSerializerSettings(); +target.Use(); + +Console.WriteLine(target.Formatting); +Console.WriteLine(target.NullValueHandling); + +sealed class MvcJsonSerializerSettings : JsonSerializerSettings, IParameterObject +{ + public MvcJsonSerializerSettings() + { + Formatting = Formatting.Indented; + NullValueHandling = NullValueHandling.Ignore; + } +} +``` diff --git a/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.MvcBuilderExtensions.md b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.MvcBuilderExtensions.md new file mode 100644 index 0000000..3fc6b24 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.MvcBuilderExtensions.md @@ -0,0 +1,49 @@ +--- +uid: Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.MvcBuilderExtensions +example: +- *content +--- + +Call `MvcBuilderExtensions.AddNewtonsoftJsonFormatters` when an `IMvcBuilder` should register the shared Newtonsoft.Json options and move the Newtonsoft.Json input and output formatters to the front of MVC's formatter lists. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json; +using Codebelt.Extensions.Newtonsoft.Json.Formatters; +using Microsoft.AspNetCore.Mvc; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Options; +using Newtonsoft.Json; + +var services = new ServiceCollection(); +services.AddControllers() + .AddNewtonsoftJsonFormatters(options => + { + options.Settings.Formatting = Formatting.None; + }); + +var provider = services.BuildServiceProvider(); +var formatterOptions = provider.GetRequiredService>().Value; +var mvcOptions = new MvcOptions(); + +foreach (var configurator in provider.GetServices>()) +{ + configurator.Configure(mvcOptions); +} + +Console.WriteLine(formatterOptions.Settings.Formatting); +Console.WriteLine(mvcOptions.OutputFormatters[0] is JsonSerializationOutputFormatter); +Console.WriteLine(mvcOptions.InputFormatters[0] is JsonSerializationInputFormatter); + +var optionServices = new ServiceCollection(); +optionServices.AddControllers() + .AddNewtonsoftJsonFormattersOptions(options => + { + options.SynchronizeWithJsonConvert = true; + }); + +var optionProvider = optionServices.BuildServiceProvider(); +var optionOnly = optionProvider.GetRequiredService>().Value; +Console.WriteLine(optionOnly.SynchronizeWithJsonConvert); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.MvcCoreBuilderExtensions.md b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.MvcCoreBuilderExtensions.md new file mode 100644 index 0000000..ab70ce3 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.MvcCoreBuilderExtensions.md @@ -0,0 +1,40 @@ +--- +uid: Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json.MvcCoreBuilderExtensions +example: +- *content +--- + +Call `MvcCoreBuilderExtensions.AddNewtonsoftJsonFormattersOptions` when an `IMvcCoreBuilder` already owns the MVC core services and you need the shared Newtonsoft.Json formatter options plus the exception-response formatter without inserting the MVC input and output formatters. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json; +using Codebelt.Extensions.Newtonsoft.Json.Formatters; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Options; + +var services = new ServiceCollection(); +services.AddMvcCore() + .AddNewtonsoftJsonFormatters(options => + { + options.Settings.DateFormatString = "yyyy-MM-dd"; + }); + +var provider = services.BuildServiceProvider(); +var formatterOptions = provider.GetRequiredService>().Value; + +Console.WriteLine(formatterOptions.Settings.DateFormatString); + +var optionServices = new ServiceCollection(); +optionServices.AddMvcCore() + .AddNewtonsoftJsonFormattersOptions(options => + { + options.SynchronizeWithJsonConvert = true; + }); + +var optionProvider = optionServices.BuildServiceProvider(); +var optionOnly = optionProvider.GetRequiredService>().Value; + +Console.WriteLine(optionOnly.SynchronizeWithJsonConvert); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Converters.JsonConverterCollectionExtensions.md b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Converters.JsonConverterCollectionExtensions.md new file mode 100644 index 0000000..b9ccf8c --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Converters.JsonConverterCollectionExtensions.md @@ -0,0 +1,25 @@ +--- +uid: Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Converters.JsonConverterCollectionExtensions +example: [*content] +--- + +## Examples + +`JsonConverterCollectionExtensions` registers ASP.NET Core-specific converters `ProblemDetails`, `HttpExceptionDescriptor`, and `StringValues` into a `JsonConverter` collection. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Converters; +using Codebelt.Extensions.Newtonsoft.Json.Formatters; +using Newtonsoft.Json; + +var options = new NewtonsoftJsonFormatterOptions(); +options.Settings.Converters.Clear(); +options.Settings.Converters + .AddHttpExceptionDescriptorConverter() + .AddProblemDetailsConverter() + .AddStringValuesConverter(); + +Console.WriteLine(options.Settings.Converters.Count == 3); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters.ServiceCollectionExtensions.md b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters.ServiceCollectionExtensions.md new file mode 100644 index 0000000..31aee69 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters.ServiceCollectionExtensions.md @@ -0,0 +1,36 @@ +--- +uid: Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters.ServiceCollectionExtensions +example: +- *content +--- + +Both `AddNewtonsoftJsonExceptionResponseFormatter` and `AddNewtonsoftJsonFormatterOptions` extend `IServiceCollection` with the shared Newtonsoft.Json formatter options. The first also registers the exception-response formatter; the second leaves the registration at options-only scope. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.AspNetCore.Newtonsoft.Json.Formatters; +using Codebelt.Extensions.Newtonsoft.Json.Formatters; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Options; + +var services = new ServiceCollection(); +services.AddNewtonsoftJsonExceptionResponseFormatter(o => +{ + o.Settings.Formatting = Newtonsoft.Json.Formatting.Indented; +}); + +var provider = services.BuildServiceProvider(); +var options = provider.GetRequiredService>().Value; +Console.WriteLine(options.Settings.Formatting == Newtonsoft.Json.Formatting.Indented); + +var services2 = new ServiceCollection(); +services2.AddNewtonsoftJsonFormatterOptions(o => +{ + o.SynchronizeWithJsonConvert = true; +}); + +var provider2 = services2.BuildServiceProvider(); +var options2 = provider2.GetRequiredService>().Value; +Console.WriteLine(options2.SynchronizeWithJsonConvert); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.ServiceCollectionExtensions.md b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.ServiceCollectionExtensions.md new file mode 100644 index 0000000..35da76f --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.AspNetCore.Newtonsoft.Json.ServiceCollectionExtensions.md @@ -0,0 +1,27 @@ +--- +uid: Codebelt.Extensions.AspNetCore.Newtonsoft.Json.ServiceCollectionExtensions +example: +- *content +--- + +`ServiceCollectionExtensions.AddMinimalNewtonsoftJsonOptions` is the shortest path to wire Newtonsoft.Json into ASP.NET Core dependency injection. It registers `NewtonsoftJsonFormatterOptions` and the `IHttpExceptionDescriptorResponseFormatter` in one call. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.AspNetCore.Newtonsoft.Json; +using Codebelt.Extensions.Newtonsoft.Json.Formatters; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Options; + +var services = new ServiceCollection(); +services.AddMinimalNewtonsoftJsonOptions(o => +{ + o.Settings.Formatting = Newtonsoft.Json.Formatting.Indented; + o.Settings.NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore; +}); + +var provider = services.BuildServiceProvider(); +var options = provider.GetRequiredService>().Value; +Console.WriteLine(options.Settings.Formatting == Newtonsoft.Json.Formatting.Indented); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.ExceptionConverter.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.ExceptionConverter.md new file mode 100644 index 0000000..140e0fc --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.ExceptionConverter.md @@ -0,0 +1,34 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.Converters.ExceptionConverter +example: [*content] +--- + +## Examples + +`ExceptionConverter` serializes and deserializes exceptions to and from JSON. It handles `Exception` and all derived types. Enable `includeStackTrace` and `includeData` to capture stack traces and `Exception.Data` entries. + +```csharp +// Program.cs +using System; +using System.IO; +using System.Text; +using Codebelt.Extensions.Newtonsoft.Json.Converters; +using Newtonsoft.Json; +using Newtonsoft.Json.Serialization; + +var converter = new ExceptionConverter(includeStackTrace: true, includeData: false); +var settings = new JsonSerializerSettings(); +settings.Converters.Add(converter); + +var ex = new InvalidOperationException("Something went wrong"); +var sb = new StringBuilder(); +using (var sw = new StringWriter(sb)) +using (var writer = new JsonTextWriter(sw)) +{ + settings.ContractResolver = new CamelCasePropertyNamesContractResolver(); + var serializer = JsonSerializer.Create(settings); + serializer.Serialize(writer, ex); +} + +Console.WriteLine(sb.ToString().Contains("InvalidOperationException")); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.JsonConverterCollectionExtensions.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.JsonConverterCollectionExtensions.md new file mode 100644 index 0000000..49eb6a6 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.JsonConverterCollectionExtensions.md @@ -0,0 +1,34 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.Converters.JsonConverterCollectionExtensions +example: [*content] +--- + +## Examples + +`JsonConverterCollectionExtensions` registers common Newtonsoft.Json converters into a `JsonConverter` collection via fluent extension methods. + +```csharp +// Program.cs +using Codebelt.Extensions.Newtonsoft.Json.Converters; +using Newtonsoft.Json; +using Newtonsoft.Json.Serialization; +using System; +using System.Collections.Generic; + +var converters = new List(); +converters + .AddStringEnumConverter(new CamelCaseNamingStrategy()) + .AddStringFlagsEnumConverter() + .AddExceptionConverter(false, false) + .AddTransientFaultExceptionConverter() + .AddFailureConverter() + .AddDataPairConverter(); + +var settings = new JsonSerializerSettings(); +foreach (var c in converters) { settings.Converters.Add(c); } + +settings.Converters.AddExceptionDescriptorConverterOf(); + +var json = JsonConvert.SerializeObject(StringComparison.Ordinal, settings); +Console.WriteLine(json == "\"ordinal\""); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.StringFlagsEnumConverter.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.StringFlagsEnumConverter.md new file mode 100644 index 0000000..9be2a5d --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.StringFlagsEnumConverter.md @@ -0,0 +1,32 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.Converters.StringFlagsEnumConverter +example: [*content] +--- + +## Examples + +`StringFlagsEnumConverter` serializes `[Flags]` enums as JSON arrays of named string values instead of a numeric bitmask. It extends `StringEnumConverter` and applies the configured naming strategy. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.Newtonsoft.Json.Converters; +using Newtonsoft.Json; +using Newtonsoft.Json.Serialization; + +var settings = new JsonSerializerSettings(); +settings.Converters.Add(new StringFlagsEnumConverter(new CamelCaseNamingStrategy())); + +var access = FileAccess.Read | FileAccess.Write; +var json = JsonConvert.SerializeObject(access, settings); +Console.WriteLine(json == "[\"read\",\"write\"]"); + +[Flags] +public enum FileAccess +{ + None = 0, + Read = 1, + Write = 2, + Execute = 4 +} +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.TransientFaultExceptionConverter.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.TransientFaultExceptionConverter.md new file mode 100644 index 0000000..7949c91 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Converters.TransientFaultExceptionConverter.md @@ -0,0 +1,47 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.Converters.TransientFaultExceptionConverter +example: +- *content +--- + +Use `TransientFaultExceptionConverter` together with the exception converter when transient-fault details must round-trip through JSON without losing the captured retry evidence. + +```csharp +// Program.cs +using System; +using System.IO; +using Codebelt.Extensions.Newtonsoft.Json.Converters; +using Codebelt.Extensions.Newtonsoft.Json.Formatters; +using Cuemon.Reflection; +using Cuemon.Resilience; +using Newtonsoft.Json; + +var evidence = new TransientFaultEvidence( + 3, + TimeSpan.FromMilliseconds(100), + TimeSpan.FromMilliseconds(300), + TimeSpan.FromMilliseconds(50), + new MethodSignature("PaymentsClient", "RetryAsync", Array.Empty(), Array.Empty())); + +var original = new TransientFaultException( + "Service unavailable", + new TimeoutException("Gateway timed out"), + evidence); + +var converter = new TransientFaultExceptionConverter(); +var settings = new JsonSerializerSettings(); +settings.Converters.Add(converter); +settings.Converters.AddExceptionConverter(false, false); + +var formatter = new NewtonsoftJsonFormatter(options => options.Settings = settings); + +var stream = formatter.Serialize(original, typeof(TransientFaultException)); +var json = new StreamReader(stream).ReadToEnd(); +stream.Position = 0; + +var restored = (TransientFaultException)formatter.Deserialize(stream, typeof(TransientFaultException)); + +Console.WriteLine(json.Contains("TransientFaultException", StringComparison.Ordinal)); +Console.WriteLine(restored.Message); +Console.WriteLine(restored.Evidence.Attempts); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.DynamicContractResolver.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.DynamicContractResolver.md new file mode 100644 index 0000000..a026b07 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.DynamicContractResolver.md @@ -0,0 +1,29 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.DynamicContractResolver +example: [*content] +--- + +## Examples + +`DynamicContractResolver` creates `IContractResolver` instances with per-property handler callbacks. Call `Create` where `T` is `CamelCasePropertyNamesContractResolver` or `DefaultContractResolver`. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.Newtonsoft.Json; +using Newtonsoft.Json; +using Newtonsoft.Json.Serialization; + +var resolver = DynamicContractResolver.Create( + (pi, jp) => + { + if (pi.Name == "Id") + { + jp.PropertyName = "identifier"; + } + }); + +var settings = new JsonSerializerSettings { ContractResolver = resolver }; +var json = JsonConvert.SerializeObject(new { Id = 42, Name = "Alice" }, settings); +Console.WriteLine(json.Contains("identifier")); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Formatters.NewtonsoftJsonFormatter.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Formatters.NewtonsoftJsonFormatter.md new file mode 100644 index 0000000..50b6aab --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Formatters.NewtonsoftJsonFormatter.md @@ -0,0 +1,31 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.Formatters.NewtonsoftJsonFormatter +example: [*content] +--- + +## Examples + +`NewtonsoftJsonFormatter` serializes and deserializes objects to and from JSON streams using Newtonsoft.Json. Use the static `SerializeObject` and `DeserializeObject` convenience methods for simple round-trips. + +```csharp +// Program.cs +using System; +using System.IO; +using Codebelt.Extensions.Newtonsoft.Json.Formatters; +using Newtonsoft.Json; + +var formatter = new NewtonsoftJsonFormatter(o => +{ + o.Settings.Formatting = Formatting.Indented; + o.Settings.NullValueHandling = NullValueHandling.Ignore; +}); + +var source = new { Message = "Hello" }; +using var stream = formatter.Serialize(source, source.GetType()); +var result = formatter.Deserialize(stream, source.GetType()); +Console.WriteLine(result?.GetType().GetProperty("Message")?.GetValue(result)); + +var json = NewtonsoftJsonFormatter.SerializeObject(new { Count = 42 }); +var deserialized = NewtonsoftJsonFormatter.DeserializeObject(json); +Console.WriteLine((int)deserialized.Count); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Formatters.NewtonsoftJsonFormatterOptions.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Formatters.NewtonsoftJsonFormatterOptions.md new file mode 100644 index 0000000..d39cd9d --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Formatters.NewtonsoftJsonFormatterOptions.md @@ -0,0 +1,28 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.Formatters.NewtonsoftJsonFormatterOptions +example: [*content] +--- + +## Examples + +`NewtonsoftJsonFormatterOptions` configures the `NewtonsoftJsonFormatter` with `JsonSerializerSettings`, supported media types, sensitivity details for exception serialization, and whether to synchronize with `JsonConvert.DefaultSettings`. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.Newtonsoft.Json.Formatters; +using Newtonsoft.Json; + +var options = new NewtonsoftJsonFormatterOptions +{ + SynchronizeWithJsonConvert = true, + Settings = + { + Formatting = Formatting.Indented, + DateFormatString = "yyyy-MM-ddTHH:mm:ss.fffZ" + } +}; + +Console.WriteLine(options.Settings.Formatting == Formatting.Indented); +Console.WriteLine(options.SupportedMediaTypes.Count >= 3); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JData.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JData.md new file mode 100644 index 0000000..4a17a99 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JData.md @@ -0,0 +1,26 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.JData +example: [*content] +--- + +## Examples + +`JData` reads JSON from streams, strings, or `JsonReader` instances into `IEnumerable` sequences, enabling structured navigation of the parsed document without deserializing to a statically typed model. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.Newtonsoft.Json; +using System.Linq; + +var json = @"{ ""store"": { ""book"": [{ ""title"": ""Moby Dick"" }, { ""title"": ""Hamlet"" }] } }"; +var results = JData.ReadAll(json).ToList(); +var titles = results.Flatten() + .Where(r => r.PropertyName == "title") + .Select(r => r.Value); + +foreach (var title in titles) +{ + Console.WriteLine(title); +} +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JDataResult.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JDataResult.md new file mode 100644 index 0000000..bd41727 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JDataResult.md @@ -0,0 +1,23 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.JDataResult +example: [*content] +--- + +## Examples + +`JDataResult` represents a node in the JSON tree produced by `JData.ReadAll`. Each node carries its path, property name, value, CLR type, children, and parent reference. + +```csharp +// Program.cs +using System; +using System.Linq; +using Codebelt.Extensions.Newtonsoft.Json; + +var json = @"{ ""name"": ""Alice"", ""age"": 30 }"; +JDataResult[] results = JData.ReadAll(json).ToArray(); + +foreach (JDataResult r in results) +{ + Console.WriteLine($"{r.Path}: {r.PropertyName} = {r.Value} ({r.Type.Name})"); +} +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JDataResultExtensions.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JDataResultExtensions.md new file mode 100644 index 0000000..9f3f286 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JDataResultExtensions.md @@ -0,0 +1,34 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.JDataResultExtensions +example: +- *content +--- + +`JDataResultExtensions` helps you flatten a `JDataResult` tree and then extract values by the JSON paths produced by that flattened sequence. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.Newtonsoft.Json; +using System.Linq; + +var json = @"{ ""book"": { ""title"": ""Moby Dick"", ""price"": 12.99 } }"; +var results = JData.ReadAll(json).Flatten().ToList(); +results.ExtractObjectValues("book.title, book.price", dict => +{ + foreach (var kv in dict) + { + Console.WriteLine($"{kv.Key}: {kv.Value.Value}"); + } +}); + +var json2 = @"{ ""items"": [{ ""id"": 1 }, { ""id"": 2 }] }"; +var results2 = JData.ReadAll(json2).ToList(); +results2.ExtractArrayValues("items", dict => +{ + foreach (var kv in dict) + { + Console.WriteLine($"{kv.Key}: {kv.Value.Count()} items"); + } +}); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JsonConverterFactory.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JsonConverterFactory.md new file mode 100644 index 0000000..d957a0f --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JsonConverterFactory.md @@ -0,0 +1,30 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.JsonConverterFactory +example: [*content] +--- + +## Examples + +`JsonConverterFactory` creates `JsonConverter` instances from delegates without defining a custom converter class. Call `Create` to make a converter for a specific type with writer and optional reader lambdas. Use `Create(Func, ...)` for a custom `CanConvert` predicate. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.Newtonsoft.Json; +using Newtonsoft.Json; + +var settings = new JsonSerializerSettings(); +settings.Converters.Add(JsonConverterFactory.Create( + (writer, value, serializer) => writer.WriteValue(value.ToString("O")))); + +var json = JsonConvert.SerializeObject(DateTime.UtcNow, settings); +Console.WriteLine(json.StartsWith("\"") && json.EndsWith("\"")); + +var settings2 = new JsonSerializerSettings(); +settings2.Converters.Add(JsonConverterFactory.Create( + t => t.IsEnum, + (writer, value, serializer) => writer.WriteValue(value.ToString()?.ToLowerInvariant()))); + +var json2 = JsonConvert.SerializeObject(StringComparison.OrdinalIgnoreCase, settings2); +Console.WriteLine(json2 == "\"ordinalignorecase\""); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JsonSerializerSettingsExtensions.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JsonSerializerSettingsExtensions.md new file mode 100644 index 0000000..c7d94f1 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JsonSerializerSettingsExtensions.md @@ -0,0 +1,24 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.JsonSerializerSettingsExtensions +example: [*content] +--- + +## Examples + +`JsonSerializerSettingsExtensions.ApplyToDefaultSettings` sets `JsonConvert.DefaultSettings` to a factory that returns the configured `JsonSerializerSettings`, making all subsequent `JsonConvert` calls use the applied configuration. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.Newtonsoft.Json; +using Codebelt.Extensions.Newtonsoft.Json.Formatters; +using Newtonsoft.Json; + +var options = new NewtonsoftJsonFormatterOptions(); +options.Settings.Formatting = Formatting.None; +options.Settings.NullValueHandling = NullValueHandling.Ignore; +options.Settings.ApplyToDefaultSettings(); + +var json = JsonConvert.SerializeObject(new { Name = "Alice", Age = (int?)null }); +Console.WriteLine(json.Contains("null") == false); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JsonWriterExtensions.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JsonWriterExtensions.md new file mode 100644 index 0000000..8015b01 --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.JsonWriterExtensions.md @@ -0,0 +1,34 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.JsonWriterExtensions +example: [*content] +--- + +## Examples + +`JsonWriterExtensions` provides `WritePropertyName` and `WriteObject` for `JsonWriter`. `WritePropertyName` resolves the naming strategy from the serializer's contract resolver; `WriteObject` delegates to `serializer.Serialize(writer, value)`. + +```csharp +// Program.cs +using System; +using System.IO; +using System.Text; +using Codebelt.Extensions.Newtonsoft.Json; +using Newtonsoft.Json; +using Newtonsoft.Json.Serialization; + +var sb = new StringBuilder(); +using var sw = new StringWriter(sb); +using var writer = new JsonTextWriter(sw); +var serializer = JsonSerializer.Create(new JsonSerializerSettings +{ + ContractResolver = new CamelCasePropertyNamesContractResolver() +}); + +writer.WriteStartObject(); +writer.WritePropertyName("MyProperty", serializer); +writer.WriteObject(new { x = 1, y = 2 }, serializer); +writer.WriteEndObject(); + +Console.WriteLine(sb.ToString().Contains("myProperty")); +Console.WriteLine(sb.ToString().Contains("\"x\":1")); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Serialization.ContractResolverExtensions.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Serialization.ContractResolverExtensions.md new file mode 100644 index 0000000..480ae6e --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.Serialization.ContractResolverExtensions.md @@ -0,0 +1,23 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.Serialization.ContractResolverExtensions +example: [*content] +--- + +## Examples + +`ContractResolverExtensions.ResolveNamingStrategyOrDefault` extracts the `NamingStrategy` from any `IContractResolver`, falling back to `CamelCaseNamingStrategy` for null or unresolvable instances. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.Newtonsoft.Json.Serialization; +using Newtonsoft.Json.Serialization; + +var resolver = new CamelCasePropertyNamesContractResolver(); +var strategy = resolver.ResolveNamingStrategyOrDefault(); +Console.WriteLine(strategy is CamelCaseNamingStrategy); + +var resolver2 = new DefaultContractResolver(); +var strategy2 = resolver2.ResolveNamingStrategyOrDefault(); +Console.WriteLine(strategy2 is DefaultNamingStrategy); +``` diff --git a/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.ValidatorExtensions.md b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.ValidatorExtensions.md new file mode 100644 index 0000000..0fe40bf --- /dev/null +++ b/.docfx/api/types/Codebelt.Extensions.Newtonsoft.Json.ValidatorExtensions.md @@ -0,0 +1,28 @@ +--- +uid: Codebelt.Extensions.Newtonsoft.Json.ValidatorExtensions +example: [*content] +--- + +## Examples + +`ValidatorExtensions` extends `Validator` with `InvalidJsonDocument` to guard method arguments against invalid JSON strings and `JsonReader` instances. + +```csharp +// Program.cs +using System; +using Codebelt.Extensions.Newtonsoft.Json; +using Cuemon; + +var validJson = @"{ ""id"": ""abc-123"" }"; +Validator.ThrowIf.InvalidJsonDocument(validJson, paramName: "validJson"); + +try +{ + var invalidJson = @"{ broken"; + Validator.ThrowIf.InvalidJsonDocument(invalidJson, paramName: "invalidJson"); +} +catch (ArgumentException ex) +{ + Console.WriteLine(ex.Message.StartsWith("Value must be a JSON representation")); +} +``` diff --git a/.docfx/docfx.json b/.docfx/docfx.json index 2b205b7..35407e3 100644 --- a/.docfx/docfx.json +++ b/.docfx/docfx.json @@ -27,12 +27,13 @@ { "files": [ "api/**/*.yml", - "api/**/*.md", "packages/**/*.md", "toc.yml", "*.md" ], "exclude": [ + "api/namespaces/**", + "api/types/**", "bin/**", "obj/**" ] @@ -69,7 +70,8 @@ "overwrite": [ { "files": [ - "api/namespaces/**.md" + "api/namespaces/**/*.md", + "api/types/**/*.md" ], "exclude": [ "obj/**", From 752329d290c176c37aacc39309493c7a1602493e Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Tue, 30 Jun 2026 01:18:58 +0200 Subject: [PATCH 3/6] =?UTF-8?q?=F0=9F=92=AC=20document=20docfx=20maintenan?= =?UTF-8?q?ce=20standards?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive DocFX documentation maintenance guidance to AGENTS.md, covering namespace pages, type pages, Extension Members tables, example requirements, TFM selection for conditionally compiled APIs, verification workflows, and skip marker discipline. This section replaces the brief official-documentation note with detailed procedures aligned with dotnet-docfx-digest skill requirements. --- AGENTS.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 58 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8048938..bbc8109 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -66,8 +66,62 @@ Agents must never automatically commit code changes or push to remote repositori **Rationale:** Automatic commits can clutter history with incomplete work, temporary debugging code, or unintended changes. Unexpected remote operations risk overwriting or losing commits on shared branches. Always require explicit user approval before performing these actions. -## Official Documentation + +## DocFX Documentation Maintenance -- Public API conventions belong in `.docfx/api/namespaces/` and should be treated as the official documentation source for library behavior and naming vocabulary. -- When adding or renaming public APIs, update the relevant namespace page in `.docfx/api/namespaces/` if the change introduces or clarifies a convention. -- Keep internal reasoning, exploratory notes, and agent discussion out of DocFX pages; summarize only stable public guidance. +When changing public .NET APIs, keep the DocFX documentation current in the same change set. + +Documentation updates must cover public API only. Do not document private or internal types or members. Do not create namespace overview pages for namespaces that contain no public API. + +Public non-abstraction types β€” including enums, structs, records, plain classes, and static extension containers β€” are valid documentation targets. Generic public types and generic extension methods are valid documentation targets too. Do not exclude a type solely because it is generic or because reflection reports it as abstract and sealed (that is the IL pattern for a static class). + +For public non-abstraction types, include at least one realistic, copy/paste-ready usage example on the generated type page/overwrite section for that type UID. For example, a public `Class1` requires an example on the `Class1` API page, not only on the namespace page. Prefer deriving examples from existing unit, functional, or integration tests, but convert test code into real-life consumer-oriented usage. + +Missing type examples must be added through per-type DocFX overwrite files under `.docfx/api/types/{TypeUid}.md` in Codebelt repositories. Namespace overview text and `Extension Members` tables are not substitutes for type-page examples. + +Public extension methods must have examples too. Listing an extension method in an `Extension Members` table is required, but it is not enough. + +All added or changed code samples must be deterministic and verified to compile. Do not add pseudo-code, ellipses, hidden test helpers, or examples that rely on unverified behavior. + +Compilation is necessary but not sufficient. Do not present runtime implementation names such as `services.GetType().Name` or `host.GetType().FullName` as the example outcome. Show application behavior, configured state, a resolved domain service, an HTTP response, or another result that explains why a caller uses the API. Application-entry-point examples must not declare an empty local `Program` type merely to compile; show a real entry point or clearly identify the referenced application project. + +Every namespace containing public API must have a DocFX namespace overview page named after the namespace, such as `X.Y.Z.md`, under `.docfx/api/namespaces/`, using DocFX overwrite front matter with the namespace `uid`. + +Namespace pages must identify key entry points from release notes, package documentation, public factories/builders, and strong functional tests, then help readers choose among adjacent workflows. When the package complements a well-known upstream API, compare concrete acquisition, customization, lifecycle, and sharing tradeoffs from current official guidance; do not claim drop-in replacement compatibility without evidence. + +Namespaces exposing public extension methods must document those extension members at namespace level. The namespace page must include an `Extension Members` table listing the extended type, the extension marker, and the public extension methods. Extension members are rendered under the heading `Extension Members`. + +Both namespace overwrite files and type overwrite files are required deliverables in the same run. Generating only namespace pages or only type pages is incomplete. + +`docfx.json` must keep namespace and type overwrite files in separate subdirectories. `build.overwrite` must include both `api/namespaces/**/*.md` (for namespace pages) and `api/types/**/*.md` (for type pages). `build.content` must exclude both `api/namespaces/**` and `api/types/**` to prevent overwrite Markdown from being treated as conceptual content. Do not use `api/**/*.md` under `build.overwrite` or `build.content`. + +Availability must be documented by referencing the appropriate include file when one exists, or by adding explicit availability text when no suitable include exists. Availability must reflect the actual target frameworks, conditional compilation, and project configuration. + +For conditionally compiled APIs, choose the executable test framework from the asset that contains the API. Inspect the preprocessor condition, project TFMs, package `lib/` assets, and resolved consumer asset before changing a sample. For APIs under `NETSTANDARD2_0` or `NETSTANDARD2_0_OR_GREATER`, when modern `lib/netX.0/` assets also exist, use `net48` (or another supported .NET Framework target from `net462` onward) so the consumer selects `lib/netstandard2.0/`. Never use `netstandard*` as an executable target, and never use a modern `netX.0` target when it selects an asset where the API is absent. For other TFM guards, select a runnable consumer TFM that resolves to the containing asset and confirm that selection from restore or build evidence. + +Preserve manual documentation edits. Prefer additive changes, but correct stale or contradictory information so documentation remains accurate. + +Preserve working Markdown links, `Related:` references, and historical URL citations during prose rewrites. Remove or replace a URL only after directly verifying that the current destination returns HTTP 404. Timeouts, 403s, rate limits, DNS failures, and other lookup problems are not removal evidence. + +Interim scratch artifacts do not belong in the repository working tree. Store assessment queues, project manifests, review reports, captured validator output, progress notes, and one-off helper scripts in temp or session storage instead. New working-tree files are only legitimate when they are the managed `AGENTS.md` block, the active `docfx.json`, the deterministic `skip-compile-allowlist.json` waiver file when one is truly required, or DocFX-authored namespace/type Markdown that maps to a real public namespace or type. Everything else is blocking cleanup work, not a documentation deliverable. The validator auto-detects generic-arity type families (such as `MutableTuple`1`..`MutableTuple`N`) and skips redundant sibling examples from the public API surface alone, so no family-skip manifest is ever written into the repository. + +Skip markers are waivers, not fixes. A skip marker only suppresses compilation when it both existed before the current run and matches an entry in `.docfx/skip-compile-allowlist.json`. Each allowlist entry must include `diagnosticCode`, `filePath`, `uid` or `symbol`, `reason`, `approval`, and `lifetime` (`temporary` or `permanent`). Newly introduced or unallowlisted skip markers remain fail-level diagnostics and do not permit a completion claim. + +Do not emit a final report, audit result, completion summary, or handoff while `summary.canClaimCompletion` is false, `summary.remainingWorkItems` is greater than zero, `summary.remainingGates` is non-empty, `summary.fullVerificationRan` is false, fail-level diagnostics remain, `summary.newlyIntroducedSkipMarkers` is non-zero, or `summary.interimArtifacts` is non-zero. Large queues, many changed files, repetitive next steps, long runtimes, context pressure, session length, task size, or a "stable queue" are not valid stop reasons; the next action must be another remediation batch, a validator rerun, a validator/tooling fix, or a true blocker with exact evidence. + +Context pressure is not a completion condition. If the session feels constrained while work remains, continue with a smaller deterministic batch, regenerate deterministic queue state such as `--assessment-queue`, `--project-manifest`, or the active dry-run manifest/review pair, or report a true tooling failure with the exact command, exit code, and output. When naming a queue-state regeneration command, resolve it to a concrete temp/session path instead of leaving `` as a placeholder. Do not stop with phrases like "given context constraints", "best done in a follow-up", "remaining work requires authoring", "this is a massive task", or "I will provide a focused summary". A context-sized handoff while work remains is `FAIL_CONTEXT_HANDOFF_WITH_REMAINING_WORK`; the remediation is to continue with a smaller deterministic batch. + +Before completing documentation work, run the relevant verification commands, normally: + +```bash +dotnet build +dotnet test +dotnet run --file /scripts/docfx.cs -- --repo-root . --build-api-model --validate-samples --verify-docfx-build +``` + +Codebelt repositories are normally strong-name signed with a `.snk` file in the repository root on the main author's codespace. Preserve and copy that root `.snk` file when building a temporary copy. If the repository or temp copy has no root `.snk`, run build and test verification with `-p:SkipSignAssembly=true`, for example `dotnet build -p:SkipSignAssembly=true` and `dotnet test -p:SkipSignAssembly=true`. + +The final DocFX verification must run outside the working tree when possible. The `--verify-docfx-build` option copies the repository to a temp workspace, runs DocFX against the resolved `docfx.json` there, and removes the temp workspace afterward so generated API YAML, manifest files, and site output do not flood git status. Do not call the work complete until the final JSON reports `summary.fullVerificationRan: true`, `summary.canClaimCompletion: true`, `summary.remainingWorkItems: 0`, an empty `summary.remainingGates`, an empty `summary.remainingDiagnosticsByCode`, `summary.newlyIntroducedSkipMarkers: 0`, and `summary.interimArtifacts: 0`. + +If a command cannot be run, report the exact limitation or failure instead of claiming the documentation was verified. + From bae999978a203d5f5af6c1a355e95dfe164f914e Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Tue, 30 Jun 2026 01:19:09 +0200 Subject: [PATCH 4/6] =?UTF-8?q?=E2=AC=86=EF=B8=8F=20update=20package=20ver?= =?UTF-8?q?sions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update Microsoft.NET.Test.Sdk from 18.6.0 to 18.7.0. Update Microsoft.AspNetCore.Mvc.NewtonsoftJson from 9.0.16 to 9.0.17 for net9 and from 10.0.8 to 10.0.9 for net10. These updates include bug fixes and improvements to the test SDK and ASP.NET Core integration packages. --- Directory.Packages.props | 60 ++++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/Directory.Packages.props b/Directory.Packages.props index e23b6f3..49b206f 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -1,31 +1,31 @@ - - - true - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + true + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From e97b05d28b43786a1e90a9869bcf4f92c79fcdc2 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Tue, 30 Jun 2026 01:19:19 +0200 Subject: [PATCH 5/6] =?UTF-8?q?=F0=9F=94=A7=20improve=20ci=20deployment=20?= =?UTF-8?q?condition?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace simple pull_request check with comprehensive condition that explicitly validates success of all required jobs. Use always() to ensure deploy is not skipped when optional jobs (e.g., disabled macOS runs) are absent. This prevents deployment from being suppressed when previous jobs skip due to conditional matrix configurations. --- .github/workflows/ci-pipeline.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci-pipeline.yml b/.github/workflows/ci-pipeline.yml index 68a82d8..717c6b9 100644 --- a/.github/workflows/ci-pipeline.yml +++ b/.github/workflows/ci-pipeline.yml @@ -203,7 +203,8 @@ jobs: security-events: write deploy: - if: github.event_name != 'pull_request' + # Avoid skipped optional jobs (for example disabled macOS matrix runs) from suppressing deployment. + if: ${{ always() && github.event_name != 'pull_request' && needs.build.result == 'success' && needs.pack.result == 'success' && needs.test_qualitygate.result == 'success' && needs.sonarcloud.result == 'success' && needs.codecov.result == 'success' && needs.codeql.result == 'success' }} name: call-nuget needs: [build, pack, test_qualitygate, sonarcloud, codecov, codeql] uses: codebeltnet/jobs-nuget-push/.github/workflows/default.yml@v3 From 7babd9e4b5686305fac538baf83ca5809327df9d Mon Sep 17 00:00:00 2001 From: gimlichael Date: Tue, 30 Jun 2026 01:41:01 +0200 Subject: [PATCH 6/6] =?UTF-8?q?=F0=9F=93=9A=20update=20changelog=20for=201?= =?UTF-8?q?0.1.5=20with=20docfx=20improvements=20and=20dependency=20upgrad?= =?UTF-8?q?es?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 677d75c..c236969 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,9 +7,34 @@ For more details, please refer to `PackageReleaseNotes.txt` on a per assembly ba > [!NOTE] > Changelog entries prior to version 8.4.0 was migrated from previous versions of Cuemon.Extensions.Newtonsoft.Json, Cuemon.Extensions.AspNetCore.Newtonsoft.Json and Cuemon.Extensions.AspNetCore.Mvc.Formatters.Newtonsoft.Json. -## [10.1.5] - 2026-06-25 +## [10.1.5] - 2026-06-30 -This is a service update that focuses on package dependencies. +This is a patch release focused on complete DocFX documentation publishing, agent guidance improvements, package version updates, and CI/CD robustness. + +### Added + +- Type-specific DocFX documentation pages under `.docfx/api/types/` for all public types, providing usage examples and API guidance, +- Comprehensive DocFX documentation maintenance standards in AGENTS.md covering namespace pages, type pages, Extension Members tables, example requirements, TFM selection, and verification workflows. + +### Changed + +- Namespace documentation pages enhanced with improved descriptions and Extension Members tables clarifying public extension methods and their targets, +- DocFX configuration updated to include type and namespace overwrite files in separate subdirectories as per Keep a Changelog conventions, +- Package dependencies upgraded: + - Codebelt.Extensions.Xunit (11.1.0 β†’ 11.1.1), + - Codebelt.Extensions.Xunit.App (11.1.0 β†’ 11.1.1), + - Cuemon.AspNetCore.Mvc (10.5.3 β†’ 10.5.4), + - Cuemon.Core (10.5.3 β†’ 10.5.4), + - Cuemon.Extensions.AspNetCore (10.5.3 β†’ 10.5.4), + - Cuemon.Extensions.AspNetCore.Authentication (10.5.3 β†’ 10.5.4), + - Cuemon.Extensions.AspNetCore.Mvc (10.5.3 β†’ 10.5.4), + - Cuemon.Extensions.Core (10.5.3 β†’ 10.5.4), + - Cuemon.Extensions.IO (10.5.3 β†’ 10.5.4), + - Cuemon.IO (10.5.3 β†’ 10.5.4), + - Microsoft.NET.Test.Sdk (18.6.0 β†’ 18.7.0), + - Microsoft.AspNetCore.Mvc.NewtonsoftJson (9.0.16 β†’ 9.0.17 for net9, 10.0.8 β†’ 10.0.9 for net10), +- CI/CD deployment condition refined to explicitly validate success of all required jobs, preventing skipped optional jobs from suppressing deployment, +- nginx base image updated to 1.31.2-alpine. ## [10.1.4] - 2026-06-05 @@ -261,7 +286,8 @@ This major release is first and foremost focused on ironing out any wrinkles tha - JsonReaderResultExtensions class from the Codebelt.Extensions.Newtonsoft.Json namespace - JsonReaderParser class from the Codebelt.Extensions.Newtonsoft.Json namespace -[Unreleased]: https://github.com/codebeltnet/newtonsoft-json/compare/v10.1.4...HEAD +[Unreleased]: https://github.com/codebeltnet/newtonsoft-json/compare/v10.1.5...HEAD +[10.1.5]: https://github.com/codebeltnet/newtonsoft-json/compare/v10.1.4...v10.1.5 [10.1.4]: https://github.com/codebeltnet/newtonsoft-json/compare/v10.1.3...v10.1.4 [10.1.3]: https://github.com/codebeltnet/newtonsoft-json/compare/v10.1.2...v10.1.3 [10.1.2]: https://github.com/codebeltnet/newtonsoft-json/compare/v10.1.1...v10.1.2