Skip to content

Commit 05168dd

Browse files
ikesnowyikesnowy
authored
Merge pull request #62 from cnblogs/24-translate-asp-net-core-xml
feat: translate xml document for Cnblogs.Architecture.Cqrs.AspNetCore
2 parents c7048c8 + a5fe46d commit 05168dd

File tree

9 files changed

+55
-82
lines changed

9 files changed

+55
-82
lines changed

‎src/Cnblogs.Architecture.Ddd.Cqrs.AspNetCore/ApiControllerBase.cs

+10-11
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,20 @@
11
using Cnblogs.Architecture.Ddd.Cqrs.Abstractions;
22
using Cnblogs.Architecture.Ddd.Domain.Abstractions;
3-
43
using Microsoft.AspNetCore.Mvc;
54

65
namespace Cnblogs.Architecture.Ddd.Cqrs.AspNetCore;
76

87
/// <summary>
9-
/// Controller 基类，提供自动处理 <see cref="CommandResponse{TError}"/> 的方法。
8+
/// A base class for an API controller with methods that return <see cref="IActionResult"/> based ons <see cref="CommandResponse{TError}"/>.
109
/// </summary>
1110
[ApiController]
1211
public class ApiControllerBase : ControllerBase
1312
{
1413
/// <summary>
15-
/// 处理 CommandResponse 并返回对应的状态码，成功-204，错误-400。
14+
/// Handle command response and return 204 if success, 400 if error.
1615
/// </summary>
17-
/// <param name="response">任务结果。</param>
18-
/// <typeparam name="TError">错误类型。</typeparam>
16+
/// <param name="response">The command response.</param>
17+
/// <typeparam name="TError">The type of error.</typeparam>
1918
/// <returns><see cref="IActionResult"/></returns>
2019
protected IActionResult HandleCommandResponse<TError>(CommandResponse<TError> response)
2120
where TError : Enumeration
@@ -29,11 +28,11 @@ protected IActionResult HandleCommandResponse<TError>(CommandResponse<TError> re
2928
}
3029

3130
/// <summary>
32-
/// 自动处理命令返回的结果，成功-200，失败-400。
31+
/// Handle command response and return 204 if success, 400 if error.
3332
/// </summary>
34-
/// <param name="response">命令执行结果。</param>
35-
/// <typeparam name="TResponse">返回类型。</typeparam>
36-
/// <typeparam name="TError">错误类型。</typeparam>
33+
/// <param name="response">The command response.</param>
34+
/// <typeparam name="TResponse">The response type when success.</typeparam>
35+
/// <typeparam name="TError">The error type.</typeparam>
3736
/// <returns><see cref="IActionResult"/></returns>
3837
protected IActionResult HandleCommandResponse<TResponse, TError>(CommandResponse<TResponse, TError> response)
3938
where TError : Enumeration
@@ -54,11 +53,11 @@ private IActionResult HandleErrorCommandResponse<TError>(CommandResponse<TError>
5453
return BadRequest(response.ValidationError!.Message);
5554
}
5655

57-
if (response.IsConcurrentError && response.LockAcquired == false)
56+
if (response is { IsConcurrentError: true, LockAcquired: false })
5857
{
5958
return StatusCode(429);
6059
}
6160

6261
return BadRequest(response.ErrorCode?.Name ?? response.ErrorMessage);
6362
}
64-
}
63+
}

‎src/Cnblogs.Architecture.Ddd.Cqrs.AspNetCore/ApiVersioningInjectors.cs

+3-3
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,12 @@
55
namespace Microsoft.Extensions.DependencyInjection;
66

77
/// <summary>
8-
/// Api Versioning 注入扩展
8+
/// Extension methods to inject api versioning.
99
/// </summary>
1010
public static class ApiVersioningInjectors
1111
{
1212
/// <summary>
13-
/// 添加 API Versioning，默认使用 <see cref="VersionByNamespaceConvention"/>
13+
/// Add API Versioning, use <see cref="VersionByNamespaceConvention"/> by default.
1414
/// </summary>
1515
/// <param name="services"><see cref="IServiceCollection"/></param>
1616
/// <returns></returns>
@@ -26,4 +26,4 @@ public static IApiVersioningBuilder AddCnblogsApiVersioning(this IServiceCollect
2626
o.SubstituteApiVersionInUrl = true;
2727
});
2828
}
29-
}
29+
}

‎src/Cnblogs.Architecture.Ddd.Cqrs.AspNetCore/CommandEndpointHandler.cs

+3-5
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,18 @@
11
using Cnblogs.Architecture.Ddd.Cqrs.Abstractions;
2-
32
using MediatR;
4-
53
using Microsoft.AspNetCore.Http;
64

75
namespace Cnblogs.Architecture.Ddd.Cqrs.AspNetCore;
86

97
/// <summary>
10-
/// 命令执行器，自动将返回内容提交给 mediator 并返回结果。
8+
/// Execute command returned by endpoint handler, and then map command response to HTTP response.
119
/// </summary>
1210
public class CommandEndpointHandler : IEndpointFilter
1311
{
1412
private readonly IMediator _mediator;
1513

1614
/// <summary>
17-
/// 构造一个命令执行器。
15+
/// Create a command endpoint handler.
1816
/// </summary>
1917
/// <param name="mediator"><see cref="IMediator"/></param>
2018
public CommandEndpointHandler(IMediator mediator)
@@ -73,4 +71,4 @@ private static IResult HandleErrorCommandResponse(CommandResponse response)
7371

7472
return Results.BadRequest(response.GetErrorMessage());
7573
}
76-
}
74+
}

‎src/Cnblogs.Architecture.Ddd.Cqrs.AspNetCore/ControllerOptionInjector.cs

+5-4
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,17 @@
11
using Cnblogs.Architecture.Ddd.Cqrs.AspNetCore;
2+
using Cnblogs.Architecture.Ddd.Infrastructure.Abstractions;
23
using Microsoft.AspNetCore.Mvc;
34

45
// ReSharper disable once CheckNamespace
56
namespace Microsoft.Extensions.DependencyInjection;
67

78
/// <summary>
8-
/// 用于注入 Model Binder 的扩展方法。
9+
/// Extensions to inject custom model binder for CQRS.
910
/// </summary>
1011
public static class ControllerOptionInjector
1112
{
1213
/// <summary>
13-
/// 添加 CQRS 相关的 Model Binder Provider
14+
/// Add custom model binder used for CQRS, like model binder for <see cref="PagingParams"/>.
1415
/// </summary>
1516
/// <param name="options"><see cref="MvcOptions"/></param>
1617
public static void AddCqrsModelBinderProvider(this MvcOptions options)
@@ -19,11 +20,11 @@ public static void AddCqrsModelBinderProvider(this MvcOptions options)
1920
}
2021

2122
/// <summary>
22-
/// 添加 CQRS 相关的 Model Binder Provider
23+
/// Add custom model binder used for CQRS, like model binder for <see cref="PagingParams"/>.
2324
/// </summary>
2425
/// <param name="builder"><see cref="IMvcBuilder"/></param>
2526
public static void AddCqrsModelBinderProvider(this IMvcBuilder builder)
2627
{
2728
builder.AddMvcOptions(options => options.AddCqrsModelBinderProvider());
2829
}
29-
}
30+
}

‎src/Cnblogs.Architecture.Ddd.Cqrs.AspNetCore/CqrsModelBinderProvider.cs

+2-2
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
namespace Cnblogs.Architecture.Ddd.Cqrs.AspNetCore;
77

88
/// <summary>
9-
/// Model Binder Provider for custom types
9+
/// Model Binder Provider for custom types used in CQRS.
1010
/// </summary>
1111
public class CqrsModelBinderProvider : IModelBinderProvider
1212
{
@@ -20,4 +20,4 @@ public class CqrsModelBinderProvider : IModelBinderProvider
2020

2121
return null;
2222
}
23-
}
23+
}

‎src/Cnblogs.Architecture.Ddd.Cqrs.AspNetCore/CqrsRouteMapper.cs

+23-48
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
namespace Cnblogs.Architecture.Ddd.Cqrs.AspNetCore;
1010

1111
/// <summary>
12-
/// 用于 Minimum API CQRS 路径注册的扩展方法。
12+
/// Extension methods used for register Command and Query endpoint in minimal API.
1313
/// </summary>
1414
public static class CqrsRouteMapper
1515
{
@@ -18,11 +18,11 @@ public static class CqrsRouteMapper
1818
private static readonly List<Type> CommandTypes = new() { typeof(ICommand<>), typeof(ICommand<,>) };
1919

2020
/// <summary>
21-
/// 添加查询 API，使用 GET 方法访问，参数将自动从路径或查询字符串获取。
21+
/// Map a query API, using GET method. <typeparamref name="T"/> would been constructed from route and query string.
2222
/// </summary>
2323
/// <param name="app"><see cref="IApplicationBuilder"/></param>
24-
/// <param name="route">路径模板。</param>
25-
/// <typeparam name="T">查询类型。</typeparam>
24+
/// <param name="route">The route template for API.</param>
25+
/// <typeparam name="T">The type of the query.</typeparam>
2626
/// <returns></returns>
2727
public static IEndpointConventionBuilder MapQuery<T>(
2828
this IEndpointRouteBuilder app,
@@ -32,11 +32,11 @@ public static IEndpointConventionBuilder MapQuery<T>(
3232
}
3333

3434
/// <summary>
35-
/// 添加一个命令 API，根据前缀选择 HTTP Method，错误会被自动处理。
35+
/// Map a command API, using different HTTP methods based on prefix. See example for details.
3636
/// </summary>
3737
/// <param name="app"><see cref="ApplicationBuilder"/></param>
38-
/// <param name="route">路径模板。</param>
39-
/// <typeparam name="T">命令类型。</typeparam>
38+
/// <param name="route">The route template.</param>
39+
/// <typeparam name="T">The type of the command.</typeparam>
4040
/// <example>
4141
/// <code>
4242
/// app.MapCommand&lt;CreateItemCommand&gt;("/items"); // Starts with 'Create' or 'Add' - POST
@@ -54,36 +54,11 @@ public static IEndpointConventionBuilder MapCommand<T>(
5454
}
5555

5656
/// <summary>
57-
/// 添加一个命令 API，根据前缀选择 HTTP Method，错误会被自动处理。
57+
/// Map a query API, using GET method.
5858
/// </summary>
5959
/// <param name="app"><see cref="ApplicationBuilder"/></param>
60-
/// <param name="route">路径模板。</param>
61-
/// <param name="handler">返回 <typeparamref name="T"/> 的委托。</param>
62-
/// <typeparam name="T">命令类型。</typeparam>
63-
/// <example>
64-
/// <code>
65-
/// app.MapCommand&lt;CreateItemCommand&gt;("/items"); // Starts with 'Create' or 'Add' - POST
66-
/// app.MapCommand&lt;UpdateItemCommand&gt;("/items/{id:int}") // Starts with 'Update' or 'Replace' - PUT
67-
/// app.MapCommand&lt;DeleteCommand&gt;("/items/{id:int}") // Starts with 'Delete' or 'Remove' - DELETE
68-
/// app.MapCommand&lt;ResetItemCommand&gt;("/items/{id:int}:reset) // Others - PUT
69-
/// </code>
70-
/// </example>
71-
/// <returns></returns>
72-
// ReSharper disable once UnusedTypeParameter
73-
public static IEndpointConventionBuilder MapCommand<T>(
74-
this IEndpointRouteBuilder app,
75-
[StringSyntax("Route")] string route,
76-
Delegate handler)
77-
{
78-
return app.MapCommand(route, handler);
79-
}
80-
81-
/// <summary>
82-
/// 添加一个查询 API，使用 GET 方法访问。
83-
/// </summary>
84-
/// <param name="app"><see cref="ApplicationBuilder"/></param>
85-
/// <param name="route">路径模板。</param>
86-
/// <param name="handler">构造查询的方法，需要返回 <see cref="IQuery{TView}"/> 的对象。</param>
60+
/// <param name="route">The route template.</param>
61+
/// <param name="handler">The delegate that returns a <see cref="IQuery{TView}"/> instance.</param>
8762
/// <returns></returns>
8863
public static IEndpointConventionBuilder MapQuery(
8964
this IEndpointRouteBuilder app,
@@ -102,11 +77,11 @@ public static IEndpointConventionBuilder MapQuery(
10277
}
10378

10479
/// <summary>
105-
/// 添加一个命令 API，根据前缀选择 HTTP Method，错误会被自动处理。
80+
/// Map a command API, using different method based on type name prefix.
10681
/// </summary>
10782
/// <param name="app"><see cref="ApplicationBuilder"/></param>
108-
/// <param name="route">路径模板。</param>
109-
/// <param name="handler">构造命令的方法，需要返回 <see cref="ICommand{TError}"/> 类型的对象。</param>
83+
/// <param name="route">The route template.</param>
84+
/// <param name="handler">The delegate that returns a instance of <see cref="ICommand{TError}"/>.</param>
11085
/// <returns></returns>
11186
/// <example>
11287
/// <code>
@@ -142,11 +117,11 @@ public static IEndpointConventionBuilder MapCommand(
142117
}
143118

144119
/// <summary>
145-
/// 添加一个命令 API，使用 POST 方法访问，错误会被自动处理。
120+
/// Map a command API, using POST method.
146121
/// </summary>
147122
/// <param name="app"><see cref="ApplicationBuilder"/></param>
148-
/// <param name="route">路径模板。</param>
149-
/// <param name="handler">构造命令的方法，需要返回 <see cref="ICommand{TError}"/> 类型的对象。</param>
123+
/// <param name="route">The route template.</param>
124+
/// <param name="handler">The delegate that returns a instance of <see cref="ICommand{TError}"/>.</param>
150125
/// <returns></returns>
151126
public static IEndpointConventionBuilder MapPostCommand(
152127
this IEndpointRouteBuilder app,
@@ -158,11 +133,11 @@ public static IEndpointConventionBuilder MapPostCommand(
158133
}
159134

160135
/// <summary>
161-
/// 添加一个命令 API，使用 PUT 方法访问，错误会被自动处理。
136+
/// Map a command API, using PUT method.
162137
/// </summary>
163138
/// <param name="app"><see cref="ApplicationBuilder"/></param>
164-
/// <param name="route">路径模板。</param>
165-
/// <param name="handler">构造命令的方法，需要返回 <see cref="ICommand{TError}"/> 类型的对象。</param>
139+
/// <param name="route">The route template.</param>
140+
/// <param name="handler">The delegate that returns a instance of <see cref="ICommand{TError}"/>.</param>
166141
/// <returns></returns>
167142
public static IEndpointConventionBuilder MapPutCommand(
168143
this IEndpointRouteBuilder app,
@@ -174,11 +149,11 @@ public static IEndpointConventionBuilder MapPutCommand(
174149
}
175150

176151
/// <summary>
177-
/// 添加一个命令 API，使用 DELETE 方法访问，错误会被自动处理。
152+
/// Map a command API, using DELETE method.
178153
/// </summary>
179154
/// <param name="app"><see cref="ApplicationBuilder"/></param>
180-
/// <param name="route">路径模板。</param>
181-
/// <param name="handler">构造命令的方法，需要返回 <see cref="ICommand{TError}"/> 类型的对象。</param>
155+
/// <param name="route">The route template.</param>
156+
/// <param name="handler">The delegate that returns a instance of <see cref="ICommand{TError}"/>.</param>
182157
/// <returns></returns>
183158
public static IEndpointConventionBuilder MapDeleteCommand(
184159
this IEndpointRouteBuilder app,
@@ -199,4 +174,4 @@ private static void EnsureDelegateReturnTypeIsCommand(Delegate handler)
199174
"handler does not return command, check if delegate returns type that implements ICommand<> or ICommand<,>");
200175
}
201176
}
202-
}
177+
}

‎src/Cnblogs.Architecture.Ddd.Cqrs.AspNetCore/PagingParamsModelBinder.cs

+2-2
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
namespace Cnblogs.Architecture.Ddd.Cqrs.AspNetCore;
66

77
/// <summary>
8-
/// Model Binder for <see cref="PagingParams"/>
8+
/// Model Binder for <see cref="PagingParams"/>
99
/// </summary>
1010
public class PagingParamsModelBinder : IModelBinder
1111
{
@@ -48,4 +48,4 @@ public Task BindModelAsync(ModelBindingContext bindingContext)
4848
bindingContext.Result = ModelBindingResult.Success(pagingParams);
4949
return Task.CompletedTask;
5050
}
51-
}
51+
}

‎src/Cnblogs.Architecture.Ddd.Cqrs.AspNetCore/QueryEndpointHandler.cs

+4-4
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,16 @@
55
namespace Cnblogs.Architecture.Ddd.Cqrs.AspNetCore;
66

77
/// <summary>
8-
/// 查询执行器，自动将返回内容提交给 mediator 并返回结果。
8+
/// The query executor, auto send query to <see cref="IMediator"/>.
99
/// </summary>
1010
public class QueryEndpointHandler : IEndpointFilter
1111
{
1212
private readonly IMediator _mediator;
1313

1414
/// <summary>
15-
/// 创建一个查询执行器。
15+
/// Create a <see cref="QueryEndpointHandler"/>.
1616
/// </summary>
17-
/// <param name="mediator"></param>
17+
/// <param name="mediator">The mediator to use.</param>
1818
public QueryEndpointHandler(IMediator mediator)
1919
{
2020
_mediator = mediator;
@@ -32,4 +32,4 @@ public QueryEndpointHandler(IMediator mediator)
3232
var response = await _mediator.Send(query);
3333
return response;
3434
}
35-
}
35+
}

‎test/Cnblogs.Architecture.IntegrationTestProject/Program.cs

+3-3
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,8 @@
3737
var v1 = apis.MapGroup("/api/v{version:apiVersion}").HasApiVersion(1);
3838
v1.MapQuery<GetStringQuery>("strings/{id:int}");
3939
v1.MapQuery<ListStringsQuery>("strings");
40-
v1.MapCommand<CreateCommand>("strings", (CreatePayload payload) => new CreateCommand(payload.NeedError));
41-
v1.MapCommand<UpdateCommand>(
40+
v1.MapCommand("strings", (CreatePayload payload) => new CreateCommand(payload.NeedError));
41+
v1.MapCommand(
4242
"strings/{id:int}",
4343
(int id, UpdatePayload payload) => new UpdateCommand(id, payload.NeedError));
4444
v1.MapCommand<DeleteCommand>("strings/{id:int}");
@@ -51,4 +51,4 @@ namespace Cnblogs.Architecture.IntegrationTestProject
5151
public partial class Program
5252
{
5353
}
54-
}
54+
}

0 commit comments

Comments
 (0)