Refactor EF Core extensions, enhance XML docs, and improve README - #313
Merged
Conversation
Refactored EF Core extension and converter classes to use primary constructors, expression-bodied members, and C# 14 extension syntax. Changed static extension methods to instance extension methods for ModelBuilder and DbContext. Updated NuGet package references to latest patch versions. Improved XML documentation and ensured code style consistency.
Comprehensive XML documentation added to public APIs, extension methods, and attributes, especially for EF Core helpers, converters, and comparers. Transaction helpers now accept CancellationToken parameters. Improved code clarity, parameter naming, and centralized JSON options documentation.
Significantly improved README.md: clarified package purpose, added compatibility details, reorganized content into clear sections with tables and examples, and updated contribution guidelines for better usability.
Added comprehensive XML documentation to all public Dapper type handler APIs, clarifying their purpose and usage. Significantly expanded and restructured README.md with compatibility info, usage examples, and contribution guidelines. Updated TinyHelpers NuGet reference to 3.3.25. No functional code changes.
Comprehensive XML documentation added to Swagger/OpenAPI helper classes and methods, improving clarity and maintainability. Refactored SwaggerExtensions to use grouped extension methods with detailed docs. Cleaned up code and ensured consistent documentation across public APIs.
Major overhaul of README.md: - Improved introduction and clarified library purpose - Added compatibility and installation sections - Documented all helper methods in tables with usage guidance - Included multiple code examples for common scenarios - Updated contribution guidelines and branch warning - Enhanced overall structure and readability for users
Updated Microsoft.EntityFrameworkCore.SqlServer to 10.0.9 in the sample project. Upgraded Microsoft.NET.Test.Sdk to 18.6.0 in both test projects.
There was a problem hiding this comment.
Pull request overview
This PR improves discoverability and documentation across the TinyHelpers libraries (Swashbuckle, Entity Framework Core, and Dapper) by expanding READMEs and adding XML documentation, while also refactoring several extension-method containers and updating package references.
Changes:
- Expanded and reorganized READMEs for
TinyHelpers.AspNetCore.Swashbuckle,TinyHelpers.EntityFrameworkCore, andTinyHelpers.Dapper, adding usage guidance and examples. - Added/updated XML docs across multiple public APIs and refactored several extension classes to use the newer
extension(...) { ... }structure. - Updated a handful of package references and refreshed a sample snippet to flow
CancellationToken.
Reviewed changes
Copilot reviewed 33 out of 33 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/TinyHelpers.Tests/TinyHelpers.Tests.csproj | Bumps test SDK package reference. |
| tests/TinyHelpers.EntityFrameworkCore.Tests/TinyHelpers.EntityFrameworkCore.Tests.csproj | Bumps test SDK package reference. |
| src/TinyHelpers.EntityFrameworkCore/TinyHelpers.EntityFrameworkCore.csproj | Updates EF Core + TinyHelpers package references. |
| src/TinyHelpers.EntityFrameworkCore/README.md | Major README expansion with compatibility/usage guidance. |
| src/TinyHelpers.EntityFrameworkCore/JsonOptions.cs | Adds XML docs for shared JSON options. |
| src/TinyHelpers.EntityFrameworkCore/Extensions/PropertyBuilderExtensions.cs | Adds XML docs for property builder helpers. |
| src/TinyHelpers.EntityFrameworkCore/Extensions/ModelBuilderExtensions.cs | Refactors query-filter helpers into extension(ModelBuilder ...) + updates docs. |
| src/TinyHelpers.EntityFrameworkCore/Extensions/DbContextExtensions.cs | Refactors into extension(DbContext ...) and updates XML docs/signatures. |
| src/TinyHelpers.EntityFrameworkCore/Converters/StringEmptyToNullTrimConverter.cs | Adds XML docs + refactors to primary-constructor style. |
| src/TinyHelpers.EntityFrameworkCore/Converters/StringEmptyToNullConverter.cs | Adds XML docs + refactors to primary-constructor style. |
| src/TinyHelpers.EntityFrameworkCore/Converters/StringArrayConverter.cs | Adds XML docs + refactors to primary-constructor style. |
| src/TinyHelpers.EntityFrameworkCore/Converters/JsonStringConverter.cs | Adds XML docs + refactors to primary-constructor style. |
| src/TinyHelpers.EntityFrameworkCore/Comparers/StringArrayComparer.cs | Adds XML docs + refactors to primary-constructor style. |
| src/TinyHelpers.EntityFrameworkCore/Comparers/JsonStringComparer.cs | Adds XML docs + refactors to primary-constructor style. |
| src/TinyHelpers.EntityFrameworkCore/Annotations/VectorAttribute.cs | Adds XML docs and minor namespace/import adjustments. |
| src/TinyHelpers.Dapper/TypeHandlers/TimeSpanTypeHandler.cs | Adds XML docs and <inheritdoc /> markers. |
| src/TinyHelpers.Dapper/TypeHandlers/TimeOnlyTypeHandler.cs | Updates compilation condition + adds XML docs. |
| src/TinyHelpers.Dapper/TypeHandlers/StringEnumerableTypeHandler.cs | Adds XML docs and <inheritdoc /> markers. |
| src/TinyHelpers.Dapper/TypeHandlers/StringArrayTypeHandler.cs | Adds XML docs and <inheritdoc /> markers. |
| src/TinyHelpers.Dapper/TypeHandlers/JsonTypeHandler.cs | Adds XML docs and <inheritdoc /> markers. |
| src/TinyHelpers.Dapper/TypeHandlers/DateOnlyTypeHandler.cs | Updates compilation condition + adds XML docs. |
| src/TinyHelpers.Dapper/TinyHelpers.Dapper.csproj | Updates TinyHelpers package reference. |
| src/TinyHelpers.Dapper/README.md | Major README expansion with compatibility/usage guidance. |
| src/TinyHelpers.Dapper/JsonOptions.cs | Adds XML docs for shared JSON options. |
| src/TinyHelpers.AspNetCore.Swashbuckle/SwaggerExtensions.cs | Refactors Swagger extension methods into an extension(SwaggerGenOptions ...) block + doc updates. |
| src/TinyHelpers.AspNetCore.Swashbuckle/README.md | Major README expansion with compatibility/usage guidance. |
| src/TinyHelpers.AspNetCore.Swashbuckle/OpenApiSchemaHelper.cs | Adds XML docs for schema helper methods. |
| src/TinyHelpers.AspNetCore.Swashbuckle/Filters/OpenApiParametersOperationFilter.cs | Adds XML docs and <inheritdoc />. |
| src/TinyHelpers.AspNetCore.Swashbuckle/Filters/OpenApiOperationOptions.cs | Adds XML docs to options container. |
| src/TinyHelpers.AspNetCore.Swashbuckle/Filters/DefaultResponseOperationFilter.cs | Adds XML docs and <inheritdoc />. |
| src/TinyHelpers.AspNetCore.Swashbuckle/Filters/AcceptLanguageHeaderOperationFilter.cs | Adds XML docs and <inheritdoc />. |
| samples/TinyHelpers.EntityFrameworkCore.Sample/TinyHelpers.EntityFrameworkCore.Sample.csproj | Updates EF Core SqlServer package reference. |
| samples/TinyHelpers.EntityFrameworkCore.Sample/Program.cs | Updates commented sample to pass CancellationToken. |
Comments suppressed due to low confidence (1)
src/TinyHelpers.AspNetCore.Swashbuckle/OpenApiSchemaHelper.cs:60
CreateSchema<TValue>(..., TValue? defaultValue)currently turns the default value into a JSON string viadefaultValue.ToString(). For numeric/boolean defaults this produces the wrong OpenAPI schema default type (and can be culture-sensitive). The default should be emitted as a correctly typed JSON value.
var schema = new OpenApiSchema
{
Type = type,
Format = format,
Default = defaultValue is not null ? JsonValue.Create(defaultValue.ToString()) : null
};
Comment on lines
+10
to
+13
| /// <remarks>/// This converter keeps simple list-shaped data close to the entity without requiring a join table. It is a | ||
| /// pragmatic mapping for cases where the collection is small, text-based, and does not need independent | ||
| /// relational querying. | ||
| /// </remarks> |
| /// <remarks> | ||
| /// Use this overload when the operation does not need direct access to the active transaction object. | ||
| /// </remarks> | ||
| public Task ExecuteTransactionAsync(Func<CancellationToken, Task> action, IsolationLevel isolationLevel = IsolationLevel.ReadCommitted, CancellationToken cancellationToken = default) |
Comment on lines
+82
to
+86
| return strategy.ExecuteAsync(async () => | ||
| { | ||
| using var transaction = await context.Database.BeginTransactionAsync(isolationLevel, cancellationToken).ConfigureAwait(false); | ||
| await action.Invoke(transaction, cancellationToken).ConfigureAwait(false); | ||
| }); |
Comment on lines
+14
to
+16
| public class StringArrayComparer() : ValueComparer<IEnumerable<string>>( | ||
| (list1, list2) => (list1 ?? Array.Empty<string>()).SequenceEqual(list2 ?? Array.Empty<string>()), | ||
| list => list == null ? 0 : list.GetHashCode()); |
Comment on lines
+21
to
+23
| public class JsonStringComparer<T>(JsonSerializerOptions? jsonSerializerOptions = null) : ValueComparer<T?>( | ||
| (first, second) => JsonSerializer.Serialize<object?>(first, jsonSerializerOptions ?? JsonOptions.Default) == JsonSerializer.Serialize<object?>(second, jsonSerializerOptions ?? JsonOptions.Default), | ||
| value => value == null ? 0 : value.GetHashCode()) | ||
| { | ||
| } | ||
| (first, second) => JsonSerializer.Serialize<object?>(first, jsonSerializerOptions ?? JsonOptions.Default) == JsonSerializer.Serialize<object?>(second, jsonSerializerOptions ?? JsonOptions.Default), | ||
| value => value == null ? 0 : value.GetHashCode()); |
Comment on lines
+22
to
27
| /// <inheritdoc /> | ||
| public override void SetValue(IDbDataParameter parameter, IEnumerable<string>? value) | ||
| { | ||
| var content = string.Join(separator, value!); | ||
| parameter.Value = content; | ||
| } |
Comment on lines
+28
to
33
| /// <inheritdoc /> | ||
| public override void SetValue(IDbDataParameter parameter, T? value) | ||
| { | ||
| var json = JsonSerializer.Serialize<object>(value!, jsonSerializerOptions); | ||
| parameter.Value = json; | ||
| } |
| ``` | ||
|
|
||
| - `AddDefaultProblemDetailsResponse()`: adds a default (error) response to all endpoints in the OpenAPI definition: | ||
| ## Schema helpers |
Comment on lines
+11
to
+13
| /// <summary> | ||
| /// Creates a string schema with an optional example value that can be reused in Swagger mapping. | ||
| /// </summary> |
Refactor OpenApiSchemaHelper to simplify default value logic and use invariant culture for value conversion. Enhance Dapper type handlers to handle nulls as DBNull.Value and improve parsing robustness. Update EF Core comparers for better null and sequence hash code handling. Clarify XML docs in StringArrayConverter. Add missing import in README code example.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request primarily enhances documentation and code clarity for the
TinyHelpers.AspNetCore.Swashbucklelibrary, focusing on making Swagger/OpenAPI helpers easier to understand and use. It introduces comprehensive XML doc comments, improves the public README with detailed usage instructions and examples, and refactors some extension method structures for better organization. No functional or behavioral changes are introduced.The most important changes are:
Documentation Improvements:
TinyHelpers.AspNetCore.Swashbuckle, includingSwaggerExtensions,OpenApiSchemaHelper, and all operation filters, to clarify their purpose and usage. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13]README.mdforTinyHelpers.AspNetCore.Swashbuckle, including compatibility information, installation instructions, a breakdown of available helpers, practical examples, and clearer contribution guidelines.Code Organization and Refactoring:
SwaggerExtensionsto use a C# extension method class structure, grouping related Swagger helper methods and improving discoverability.AddSwaggerOperationParametersandAddOperationParameters) for consistent usage and easier configuration. [1] [2]Sample Code Update:
CancellationTokenwhere appropriate, reflecting best practices for async EF Core operations.Closes #74