ASP.NET的路由是通过EndpointRoutingMiddleware和EndpointMiddleware这两个中间件协作完成的,它们在ASP.NET平台上具有举足轻重的地位,MVC和gRPC框架,Dapr的Actor和发布订阅编程模式都建立在路由系统之上。Minimal API更是将提升到了前所未有的高度,上一篇通过9个实例演示了基于路由的REST API开发,本篇演示一些“高阶”的用法。

[S2010]解析路由模式 (源代码

[S2011]利用多个中间件来构建终结点处理器(源代码

[S2012]在参数上标注特性来决定绑定的数据源(源代码

[S2013]默认的参数绑定规则(源代码

[S2014]针对TryPar[Se方法的参数绑定(源代码

[S2015]针对BindA[Sync方法的参数绑定(源代码

[S2016]自定义路由约束(源代码

[S2010]解析路由模式

下面我们通过一个简单的实例演示如何利用RoutePatternFactory对象解析指定的路由模板,并生成对应的RoutePattern对象。我们定义了如下所示的Format方法将指定的RoutePattern对象格式化成一个字符串。

static string Format(RoutePattern pattern)
{
var builder = new StringBuilder();
builder.AppendLine($"RawText:{pattern.RawText}");
builder.AppendLine($"InboundPrecedence:{pattern.InboundPrecedence}");
builder.AppendLine($"OutboundPrecedence:{pattern.OutboundPrecedence}");
var segments = pattern.PathSegments;
builder.AppendLine("Segments");
foreach (var segment in segments)
{
foreach (var part in segment.Parts)
{
builder.AppendLine($"\t{ToString(part)}");
}
}
builder.AppendLine("Defaults");
foreach (var @default in pattern.Defaults)
{
builder.AppendLine($"\t{@default.Key} = {@default.Value}");
} builder.AppendLine("ParameterPolicies ");
foreach (var policy in pattern.ParameterPolicies)
{
builder.AppendLine( $"\t{policy.Key} = {string.Join(',',policy.Value.Select(it => it.Content))}");
} builder.AppendLine("RequiredValues");
foreach (var required in pattern.RequiredValues)
{
builder.AppendLine($"\t{required.Key} = {required.Value}");
} return builder.ToString(); static string ToString(RoutePatternPart part)
=> part switch
{
RoutePatternLiteralPart literal => $"Literal: {literal.Content}",
RoutePatternSeparatorPart separator => $"Separator: {separator.Content}",
RoutePatternParameterPart parameter => @$"Parameter: Name = {parameter.Name}; Default = {parameter.Default}; IsOptional = { parameter.IsOptional}; IsCatchAll = { parameter.IsCatchAll};ParameterKind = { parameter.ParameterKind}",
_ => throw new ArgumentException("Invalid RoutePatternPart.")
};
}

如下的演示程序调用了RoutePatternFactory 类型的静态方法Parse解析指定的路由模板“weather/{city:regex(^0\d{{2,3}}$)=010}/{days:int:range(1,4)=4}/{detailed?}”生成一个RoutePattern对象,我们在调用该方法时还指定了requiredValues参数。我们调用创建的WebApplication对象的MapGet方法注册了针对根路径“/”的终结点,对应的处理器直接返回RoutePattern对象格式化生成的字符串。

using Microsoft.AspNetCore.Routing.Patterns;
using System.Text; var template =@"weather/{city:regex(^0\d{{2,3}}$)=010}/{days:int:range(1,4)=4}/{detailed?}";
var pattern = RoutePatternFactory.Parse(
pattern: template,
defaults: null,
parameterPolicies: null,
requiredValues: new { city = "010", days = 4 }); var app = WebApplication.Create();
app.MapGet("/", ()=> Format(pattern));
app.Run();

如果利用浏览器访问启动后的应用程序,回到得到如图1所示结果,它结构化地展示了路由模式的原始文本、出入栈路由匹配权重、每个段的组成、路由参数的默认值和参数策略,以及生成URL必须提供的默认参数值。

图1 针对路由模式的解析

[S2011]利用多个中间件来构建终结点处理器

如果某个终结点针对请求处理的逻辑相对复杂,需要多个中间件协同完成,我们可以调用IEndpointRouteBuilder 对象的CreateApplicationBuilder方法创建一个新的IApplicationBuilder对象,并将这些中间件注册到这个该对象上,最后利用它这些中间件转换成RequestDelegate委托。

var app = WebApplication.Create();
IEndpointRouteBuilder routeBuilder = app;
app.MapGet("/foobar", routeBuilder.CreateApplicationBuilder()
.Use(FooMiddleware)
.Use(BarMiddleware)
.Use(BazMiddleware)
.Build());
app.Run(); static async Task FooMiddleware(HttpContext context,RequestDelegate next)
{
await context.Response.WriteAsync("Foo=>");
await next(context);
};
static async Task BarMiddleware(HttpContext context, RequestDelegate next)
{
await context.Response.WriteAsync("Bar=>");
await next(context);
};
static Task BazMiddleware(HttpContext context, RequestDelegate next) => context.Response.WriteAsync("Baz");

上面的演示程序注册了一个路径模板为“foobar”的路由,并注册了三个中间件来处理路由的请求。该演示程序启动之后,如果我们利用浏览器对路由地址“/foobar”发起请求,将会得到如图2所示的输出结果。呈现出来的字符串是通过注册的三个中间件(FooMiddleware、BarMiddleware和BazMiddleware)输出内容组合而成。

图2 输出结果

[S2012]在参数上标注特性来决定绑定的数据源

如下这个演示程序调用WebApplication对象的MapPost方法注册了一个采用“/{foo}”作为模板的终结点。作为终结点处理器的委托指向静态方法Handle,我们为这个方法定义了五个参数,分别标注了上述五个特性。我们将五个参数组合成一个匿名对象作为返回值。

using Microsoft.AspNetCore.Mvc;
var app = WebApplication.Create();
app.MapPost("/{foo}", Handle);
app.Run(); static object Handle(
[FromRoute] string foo,
[FromQuery] int bar,
[FromHeader] string host,
[FromBody] Point point,
[FromServices] IHostEnvironment environment)
=> new { Foo = foo, Bar = bar, Host = host, Point = point,
Environment = environment.EnvironmentName }; public class Point
{
public int X { get; set; }
public int Y { get; set; }
}

程序启动之后,我们针对“http://localhost:5000/abc?bar=123”这个URL发送了一个POST请求,请求的主体内容为一个Point对象序列化成生成的JSON。如下所示的是请求报文和响应报文的内容,可以看出Handle方法的foo和bar参数分别绑定的是路由参数“foo”和查询字符串“bar”的值,参数host绑定的是请求的Host报头,参数point是请求主体内容反序列化的结果,参数environment则是由针对当前请求的IServiceProvider对象提供的服务(S2012)。

POST http://localhost:5000/abc?bar=123 HTTP/1.1
Content-Type: application/json
Host: localhost:5000
Content-Length: 18 {"x":123, "y":456}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sat, 06 Nov 2021 11:55:54 GMT
Server: Kestrel
Content-Length: 100 {"foo":"abc","bar":123,"host":"localhost:5000","point":{"x":123,"y":456},"environment":"Production"}

[S2013]默认的参数绑定规则

如果请求处理器方法的参数没有显式指定绑定数据的来源,路由系统也能根据参数的类型尽可能地从当前HttpContext上下文中提取相应的内容予以绑定。针对如下这几个类型,对应参数的绑定源是明确的。

  • HttpContext:绑定为当前HttpContext上下文。
  • HttpRequest:绑定为当前HttpContext上下文的Request属性。
  • HttpResponse: 绑定为当前HttpContext上下文的Response属性。
  • ClaimsPrincipal: 绑定为当前HttpContext上下文的User属性。
  • CancellationToken: 绑定为当前HttpContext上下文的RequestAborted属性。

上述的绑定规则体现在如下演示程序的调试断言中。这个演示实例还体现了另一个绑定规则,那就是只要当前请求的IServiceProvider能够提供对应的服务,对应参数(“httpContextAccessor”)上标注的FromSerrvicesAttribute特性不是必要的。但是倘若缺少对应的服务注册,请求的主体内容会一般会作为默认的数据来源,所以FromSerrvicesAttribute特性最好还是显式指定为好。对于我们演示的这个例子,如果我们将前面针对AddHttpContextAccessor方法的调用移除,对应参数的绑定自然会失败,但是错误消息并不是我们希望看到的(S2013)。

using System.Diagnostics;
using System.Security.Claims; var builder = WebApplication.CreateBuilder();
builder.Services.AddHttpContextAccessor();
var app = builder.Build();
app.MapGet("/", Handle);
app.Run(); static void Handle(HttpContext httpContext, HttpRequest request, HttpResponse response,ClaimsPrincipal user, CancellationToken cancellationToken, IHttpContextAccessor httpContextAccessor)
{
var currentContext = httpContextAccessor.HttpContext;
Debug.Assert(ReferenceEquals(httpContext, currentContext));
Debug.Assert(ReferenceEquals(request, currentContext.Request));
Debug.Assert(ReferenceEquals(response, currentContext.Response));
Debug.Assert(ReferenceEquals(user, currentContext.User));
Debug.Assert(cancellationToken == currentContext.RequestAborted);
}

[S2014]针对TryParse方法的参数绑定

如果我们在某个类型中定义了一个名为TryParse的静态方法将指定的字符串表达式转换成当前类型的实例,路由系统在对该类型的参数进行绑定的时候会优先从路由参数和查询字符串中提取相应的内容,并通过调用这个方法生成绑定的参数。

var app = WebApplication.Create();
app.MapGet("/", (Point foobar) => foobar);
app.Run(); public class Point
{
public int X { get; set; }
public int Y { get; set; } public Point(int x, int y)
{
X = x;
Y = y;
}
public static bool TryParse(string expression, out Point? point)
{
var split = expression.Trim('(', ')').Split(',');
if (split.Length == 2 && int.TryParse(split[0], out var x) && int.TryParse(split[1], out var y))
{
point = new Point(x, y);
return true;
}
point = null;
return false;
}
}

上面的演示程序为自定义的Point类型定义了一个静态的TryParse方法使我们可以将一个以“(x,y)”形式定义的表达式转换成Point对象。注册的终结点处理器委托以该类型为参数,指定的参数名称为“foobar”。我们在发送的请求中以查询字符串的形式提供对应的表达式“(123,456)”,从返回的内容可以看出参数得到了成功绑定。

图3 TryParse方法针对参数绑定的影响

[S2015]针对BindAsync方法的参数绑定

如果某种类型的参数具有特殊的绑定方式,我们还可以将具体的绑定实现在一个按照约定定义的BindAsync方法中。按照约定,这个BindAsync应该定义成返回类型为ValueTask<T>的静态方法,它可以拥有一个类型为HttpContext的参数,也可以额外提供一个ParameterInfo类型的参数,这两个参数分别与当前HttpContext上下文和描述参数的ParameterInfo对象绑定。前面演示实例中为Point类型定义了一个TryParse方法可以替换成如下这个 BingAsync方法(S2015)。

public class Point
{
public int X { get; set; }
public int Y { get; set; } public Point(int x, int y)
{
X = x;
Y = y;
} public static ValueTask<Point?> BindAsync(HttpContext httpContext, ParameterInfo parameter)
{
Point? point = null;
var name = parameter.Name;
var value = httpContext.GetRouteData().Values.TryGetValue(name!, out var v) ? v : httpContext.Request.Query[name!].SingleOrDefault(); if (value is string expression)
{
var split = expression.Trim('(', ')')?.Split(',');
if (split?.Length == 2 && int.TryParse(split[0], out var x) && int.TryParse(split[1], out var y))
{
point = new Point(x, y);
}
}
return new ValueTask<Point?>(point);
}
}

[S2016]自定义路由约束

我们可以使用预定义的IRouteConstraint实现类型完成一些常用的约束,但是在一些对路由参数具有特定约束的应用场景中,我们不得不创建自定义的约束类型。举个例子,如果需要对资源提供针对多语言的支持,最好的方式是在请求的URL中提供对应的Culture。为了确保包含在URL中的是一个合法有效的Culture,最好为此定义相应的约束。下面将通过一个简单的实例来演示如何创建这样一个用于验证Culture的自定义路由约束。我们创建了一个提供基于不同语言资源的API。我们将资源文件作为文本资源进行存储,如图4所示,我们创建了两个资源文件 (Resources.resx和Resources.zh.resx),并定义了一个名为hello的文本资源条目。

图4 存储文本资源的两个资源文件

如下演示程序中注册了一个模板为“resources/{lang:culture}/{resourceName:required}”的终结点。路由参数“{resourceName}”表示资源条目的名称(比如“hello”),另一个路由参数“{lang}”表示指定的语言,约束表达式名称culture对应的就是我们自定义的针对语言文化的约束类型CultureConstraint。因为这是一个自定义的路由约束,我们通过调用IServiceCollection接口的Configure<TOptions>方法将此约束采用的表达式名称(“culture”)和CultureConstraint类型之间的映射关系添加到RouteOptions配置选项中。

using App;
using App.Properties;
using System.Globalization; var builder = WebApplication.CreateBuilder();
var template = "resources/{lang:culture}/{resourceName:required}";
builder.Services.Configure<RouteOptions>(options => options.ConstraintMap.Add("culture", typeof(CultureConstraint)));
var app = builder.Build();
app.MapGet(template, GetResource);
app.Run(); static IResult GetResource(string lang, string resourceName)
{
CultureInfo.CurrentUICulture = new CultureInfo(lang);
var text = Resources.ResourceManager.GetString(resourceName);
return string.IsNullOrEmpty(text)? Results.NotFound(): Results.Content(text);
}

该终结点的处理方法GetResource定义了两个参数,我们知道它们会自动绑定为同名的路由参数。由于系统自动根据当前线程的UICulture来选择对应的资源文件,我们对CultureInfo类型的CurrentUICulture静态属性进行了设置。如果从资源文件将对应的文本提取出来,我们将创建一个ContentResult对象并返回。应用启动之后,我们可以利用浏览器指定匹配的URL获取对应语言的文本。如图5所示,如果指定一个不合法的语言(如“xx”),将会违反我们自定义的约束,此时就会得到一个状态码为“404 Not Found”的响应。

图5 采用相应的URL得到某个资源针对某种语言的内容

我们来看看针对语言文化的路由约束CultureConstraint究竟做了什么。如下面的代码片段所示,我们在Match方法中会试图获取作为语言文化内容的路由参数值,如果存在这样的路由参数,就可以利用它创建一个CultureInfo对象。如果这个CultureInfo对象的EnglishName属性名不以“Unknown Language”字符串作为前缀,我们就认为指定的是合法的语言文件。

public class CultureConstraint : IRouteConstraint
{
public bool Match(HttpContext? httpContext, IRouter? route, string routeKey,RouteValueDictionary values, RouteDirection routeDirection)
{
try
{
if (values.TryGetValue(routeKey, out var value) && value is not null)
{
return !new CultureInfo((string)value)
.EnglishName.StartsWith("Unknown Language");
}
return false;
}
catch
{
return false;
}
}
}

ASP.NET Core 6框架揭秘实例演示[31]:路由&ldquo;高阶&rdquo;用法的更多相关文章

  1. ASP.NET Core 6框架揭秘实例演示[33]:异常处理高阶用法

    NuGet包"Microsoft.AspNetCore.Diagnostics"中提供了几个与异常处理相关的中间件,我们可以利用它们将原生的或者定制的错误信息作为响应内容发送给客户 ...

  2. ASP.NET Core 6框架揭秘实例演示[12]:诊断跟踪的进阶用法

    一个好的程序员能够在系统出现问题之后马上定位错误的根源并找到正确的解决方案,一个更好的程序员能够根据当前的运行状态预知未来可能发生的问题,并将问题扼杀在摇篮中.诊断跟踪能够帮助我们有效地纠错和排错&l ...

  3. ASP.NET Core 6框架揭秘实例演示[07]:文件系统

    ASP.NET Core应用具有很多读取文件的场景,如读取配置文件.静态Web资源文件(如CSS.JavaScript和图片文件等).MVC应用的视图文件,以及直接编译到程序集中的内嵌资源文件.这些文 ...

  4. ASP.NET Core 6框架揭秘实例演示[08]:配置的基本编程模式

    .NET的配置支持多样化的数据源,我们可以采用内存的变量.环境变量.命令行参数.以及各种格式的配置文件作为配置的数据来源.在对配置系统进行系统介绍之前,我们通过几个简单的实例演示一下如何将具有不同来源 ...

  5. ASP.NET Core 6框架揭秘实例演示[09]:配置绑定

    我们倾向于将IConfiguration对象转换成一个具体的对象,以面向对象的方式来使用配置,我们将这个转换过程称为配置绑定.除了将配置树叶子节点配置节的绑定为某种标量对象外,我们还可以直接将一个配置 ...

  6. ASP.NET Core 6框架揭秘实例演示[10]:Options基本编程模式

    依赖注入使我们可以将依赖的功能定义成服务,最终以一种松耦合的形式注入消费该功能的组件或者服务中.除了可以采用依赖注入的形式消费承载某种功能的服务,还可以采用相同的方式消费承载配置数据的Options对 ...

  7. ASP.NET Core 6框架揭秘实例演示[11]:诊断跟踪的几种基本编程方式

    在整个软件开发维护生命周期内,最难的不是如何将软件系统开发出来,而是在系统上线之后及时解决遇到的问题.一个好的程序员能够在系统出现问题之后马上定位错误的根源并找到正确的解决方案,一个更好的程序员能够根 ...

  8. ASP.NET Core 6框架揭秘实例演示[13]:日志的基本编程模式[上篇]

    <诊断跟踪的几种基本编程方式>介绍了四种常用的诊断日志框架.其实除了微软提供的这些日志框架,还有很多第三方日志框架可供我们选择,比如Log4Net.NLog和Serilog 等.虽然这些框 ...

  9. ASP.NET Core 6框架揭秘实例演示[14]:日志的进阶用法

    为了对各种日志框架进行整合,微软创建了一个用来提供统一的日志编程模式的日志框架.<日志的基本编程模式>以实例演示的方式介绍了日志的基本编程模式,现在我们来补充几种"进阶" ...

随机推荐

  1. 2021夏季学期华清大学EE数算OJ1:算数问题

    第一次写博客,有点紧张... 也许格式也没有特别丑吧 先看原题( 此题做法众多,这里仅仅介绍蒟蒻的一种很复杂的思路(但最后还是喜提0ms的好成绩) 读完这道题,不难发现,此题不过是一个质因数分解+一堆 ...

  2. .Net 在容器中操作宿主机

    方案描述 在 docker 容器中想操作宿主机,一般会使用 ssh 的方式,然后 .Net 通过执行远程 ssh 指令来操作宿主机.本文将使用 交互式 .Net 容器版 中提供的镜像演示 .Net 在 ...

  3. linux篇-Centos7jdk安装

    2.1查看现有JDK #rpm -qa|grep jdk (如果有其他版本的JDK建议卸载) 卸载其他版本的JDK命令 #yum –y remove java-1.6.0 #yum –y remov ...

  4. 《回炉重造 Java 基础》——集合(容器)

    整体框架 绿色代表接口/抽象类:蓝色代表类. 主要由两大接口组成,一个是「Collection」接口,另一个是「Map」接口. 前言 以前刚开始学习「集合」的时候,由于没有好好预习,也没有学好基础知识 ...

  5. opencv c++安装踩坑记录 file cannot create directory: /usr/local/include/opencv2. Maybe need administrative privileges

    前言 最近深度学习Ultra-Fast-Lane-Detection/INSTALL.md at master · cfzd/Ultra-Fast-Lane-Detection (github.com ...

  6. 解决跨海高并发崩溃难题?so easy

    近年来随着互联网强势的发展浪潮,越来越多的企业选择跨境出海,扩展海外市场.而想要在一个陌生市场最快速地吸引到用户,一定不能缺少的就是丰富多样的各类活动.然而活动在带来大流量的同时,也带来了一些问题,比 ...

  7. sql语句中 int(1)与int(10)有什么区别?资深开发竟然能理解错

    过完春节该投入战斗了,上班第一天发现了一个挺有意思的知识点给大家分享一下:一直以来的的误区我们都认为了int后面的跟的数字为最大显示宽度会对后面插入的参数会有限制,其实倒不是这样的 # 困惑 最近遇到 ...

  8. AcWing-1022

    题解借鉴两位大佬的解析 墨染空 && 野生铅笔 本题是一道 01背包 的扩展题 -- 二维费用01背包问题 把 野生宝可梦 看做物品,则捕捉他需要的 精灵球 个数就是第一费用,战斗皮神 ...

  9. React + Typescript领域初学者的常见问题和技巧

    React + Typescript领域初学者的常见问题和技巧 创建一个联合类型的常量 Key const NAME = { HOGE: "hoge", FUGA: "f ...

  10. alertmanager集群莫名发送resolve消息的问题探究

    alertmanager集群莫名发送resolve消息的问题探究 术语 告警消息:指一条告警 告警恢复消息:指一条告警恢复 告警信息:指告警相关的内容,包括告警消息和告警恢复消息 问题描述 最近遇到了 ...