KeenConveyance.AspNetCore
1.0.0-preview-007
This is a prerelease version of KeenConveyance.AspNetCore.
There is a newer prerelease version of this package available.
See the version list below for details.
See the version list below for details.
dotnet add package KeenConveyance.AspNetCore --version 1.0.0-preview-007
NuGet\Install-Package KeenConveyance.AspNetCore -Version 1.0.0-preview-007
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="KeenConveyance.AspNetCore" Version="1.0.0-preview-007" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add KeenConveyance.AspNetCore --version 1.0.0-preview-007
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: KeenConveyance.AspNetCore, 1.0.0-preview-007"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install KeenConveyance.AspNetCore as a Cake Addin #addin nuget:?package=KeenConveyance.AspNetCore&version=1.0.0-preview-007&prerelease // Install KeenConveyance.AspNetCore as a Cake Tool #tool nuget:?package=KeenConveyance.AspNetCore&version=1.0.0-preview-007&prerelease
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
KeenConveyance
1. Intro
A Asp.Net Core Controller
service call RPC framework based on interface
. 基于 interface
的 Asp.Net Core Controller
服务调用RPC框架。
- 服务端基于
Asp.Net Core
的Controller
. 支持所有标准的Controller
功能, 如Filter
、Authentication
、Authorization
等(*); - 客户端基于
Microsoft.Extensions.Http
和SourceGenerator
. 无运行时动态代码生成, 支持Microsoft.Extensions.Http
丰富的拓展 (Polly
、链路追踪
等); - 数据交换格式易拓展, 不局限于
Json
, 可拓展为任意编码如:MemoryPack
、MessagePack
等; - 动态
Controller
选择. 支持选择指定类型注册为Controller
并暴露HttpAPI
; - 基于约定的客户端代码生成. 不依赖类库共享;
- 目标框架
net6.0
+;
NOTE!!!
- 虽然支持所有标准的
Controller
功能且执行其流程, 但框架并非按照Controller
定义进行请求, 框架的请求中会忽略[FromQuery]
、[FromRoute]
等定义直接使用ModelBinder
从Body
进行绑定;- 即: 如果请求由框架发起, 则依赖原始
HttpContext
信息的功能可能不能正常工作, 例如请求的Query
、Path
中不包含Action
的信息;
- 即: 如果请求由框架发起, 则依赖原始
- 方法参数建议使用简单类型或
DTO
: 除CancellationToken
外, 客户端会将方法参数都序列化后传递给服务端,服务端从Body
进行绑定, 对一些特殊的参数不支持如IFormFile
等; - 框架对接口定义的
命名空间
、方法名称
、参数类型
、参数顺序
强依赖, 需要保证客户端与服务端接口定义一致;
2. 快速开始
2.1 服务端
- 新建
Asp.Net Core Web API
项目, 并引用包:
<ItemGroup>
<PackageReference Include="KeenConveyance.AspNetCore" Version="1.0.0-*" />
</ItemGroup>
- 新建
IApplicationService
接口用于标记服务, 以便后续筛选 (非强制要求)
public interface IApplicationService
{ }
- 配置
KeenConveyance
服务
services.AddKeenConveyance()
.ConfigureService(options =>
{
//筛选所有派生自 IApplicationService 的类型作为 Controller
options.ControllerSelectPredicate = typeInfo => typeInfo.IsAssignableTo(typeof(IApplicationService));
});
- 在请求管道中启用
KeenConveyance
// 在 MapControllers 之前 UseAuthorization 之后
app.UseKeenConveyance();
- 定义服务接口并实现服务 (或使现有
Controller
派生自服务接口), 如:
public interface ISampleService : IApplicationService
{
public Task<string> EchoAsync(string value, CancellationToken cancellationToken);
}
[Route("[controller]")]
public class SampleService : ISampleService
{
[HttpGet]
public Task<string> EchoAsync(string value, CancellationToken cancellationToken)
{
var echo = new string(value.AsEnumerable().Reverse().ToArray());
return Task.FromResult(echo);
}
}
2.2 客户端
- 新建任意类型项目 (需要
DI
支持, 可能需要手动引入), 并引用包:
<ItemGroup>
<PackageReference Include="KeenConveyance" Version="1.0.0-*" />
</ItemGroup>
Note: 项目直接引用而不要间接引用!
- 配置
KeenConveyance
服务
services.AddKeenConveyance(options =>
{
//var xxxSerializer = 自定义的序列化器;
//options.DefaultObjectSerializer = xxxSerializer; //设置默认序列化器
//options.ObjectSerializers.Add(xxxSerializer); //添加到可用序列化器
})
.ConfigureClient(builder =>
{
//客户端全局配置
builder.GlobalOptions(options =>
{
//options.ObjectSerializer = xxx; //配置客户端全局使用的序列化器
//options.HttpRequestMessageConstructor = xxx; //配置客户端全局使用的HttpRequestMessage构造器
//options.ServiceAddressProvider = xxx; //配置客户端全局使用的服务地址提供器
//options.PrePreparePayloadData = true; //配置客户端请求时预准备请求数据,以确保Http请求包含有效的 Content-Length 头
//options.BufferInitialCapacity = 1024; //配置客户端预准备请求数据时的Buffer初始化大小
});
//配置客户端
//必须在此调用 BeginSetupClients 方法,并链式调用 AddClient 使用服务接口定义添加客户端, 并在最终调用 CompleteClientsSetup 方法
builder.BeginSetupClients()
.AddClient<ISampleService>(httpClientBuilder =>
{
//配置服务地址
httpClientBuilder.ConfigureServiceAddress("http://127.0.0.1:5225"); //必须配置客户端的服务地址
// 在此进行 ISampleService 的 HttpClient 配置
httpClientBuilder.ConfigureOptions(options =>
{
//配置应用于当前客户端的配置
});
})
.CompleteClientsSetup(); //必须在最后调用 CompleteClientsSetup 方法,提示未找到此方法可尝试手动using当前项目的根命名空间
});
至此已完成所有配置,从 DI
容器中直接获取 ISampleService
实例并调用方法即可
3. 自定义数据交换格式
框架默认使用 System.Text.Json
进行数据交换,通过实现自定义的 IObjectSerializer
来自定义数据交换格式;
- 可参考测试代码对
MemoryPack
的支持;
其他
- 客户端代码生成在当前项目的根命名空间下,提示未找到
CompleteClientsSetup
方法可以手动using
当前项目的根命名空间进行尝试; - 生成的客户端代码都已标记为
partial
类型, 可声明对应的partial
类,并重写方法来进行自定义操作, 服务的代理类型为格式为{ServiceName}ProxyClient
(如ISampleService
的代理类型为ISampleServiceProxyClient
) :internal static partial class GeneratedClient { private partial class ISampleServiceProxyClient { public override Task<string> EchoAsync(string value, CancellationToken cancellationToken) { //进行请求前后的自定义操作 return base.EchoAsync(value, cancellationToken); } } }
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
-
net6.0
- KeenConveyance (>= 1.0.0-preview-007)
-
net7.0
- KeenConveyance (>= 1.0.0-preview-007)
-
net8.0
- KeenConveyance (>= 1.0.0-preview-007)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.0.0-preview-010 | 147 | 11/19/2024 |
1.0.0-preview-009 | 45 | 11/16/2024 |
1.0.0-preview-008 | 53 | 10/29/2024 |
1.0.0-preview-007 | 73 | 8/11/2024 |
1.0.0-preview-006 | 69 | 3/4/2024 |
1.0.0-preview-005 | 111 | 1/11/2024 |
1.0.0-preview-004 | 92 | 1/1/2024 |
1.0.0-preview-003 | 123 | 11/13/2023 |
1.0.0-preview-002 | 68 | 11/13/2023 |
1.0.0-preview-001 | 75 | 11/10/2023 |