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. Vue路由实现之通过URL中的hash(#号)来实现不同页面之间的切换(图表展示、案例分析、附源码详解)

    前言 本篇随笔主要写了Vue框架中路由的基本概念.路由对象属性.vue-router插件的基本使用效果展示.案例分析.原理图解.附源码地址获取. 作为自己对Vue路由进行页面跳转效果知识的总结与笔记. ...

  2. drools中的条件 when

    目录 1.介绍 2.语法结构 3.模式例子 3.1 单个对象匹配 3.2 匹配任何对象 3.3 带条件匹配 3.3.1 注意事项 3.4 嵌套属性的匹配 3.4.1 访问单个嵌套属性 3.4.2 访问 ...

  3. mac安装java环境

    1.java安装包获取: 链接:https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html 2.验证安装是否成 ...

  4. CF1682F MCMF?

    题意: 费用流,其实bushi 给你长为\(n\)的序列\(a\),\(b\).\(a\)单增,\(b\)有正有负. \(q\)次询问\([l,r]\),保证\(\sum\limits_{i=l}^r ...

  5. 解决Windows微软账户无法登录

    更新记录 2022年4月16日:本文迁移自Panda666原博客,原发布时间:2021年8月25日. 将DNS的服务器地址修改为4.2.2.1或者4.2.2.2就可以解决无法登录microsoft账户 ...

  6. sqlserver用windows方式验证登录踩过的坑

    坑位一: 之前没用过windows验证方式登录sqlserver,连接串怎么写 坑位二: 链接上了,但是启动报错 八月 19, 2020 9:33:43 上午 com.microsoft.sqlser ...

  7. 全新升级的AOP框架Dora.Interception[1]: 编程体验

    多年之前利用IL Emit写了一个名为Dora.Interception(github地址,觉得不错不妨给一颗星)的AOP框架.前几天利用Roslyn的Source Generator对自己为公司写的 ...

  8. rhel安装程序

    Linux下软件分类     rpm软件包,包管理器 yum     deb软件包,包管理器 apt     源代码软件包            一般为".tar.gz".&quo ...

  9. 如何编写测试团队通用的Jmeter脚本

    平时学习.工作过程中,编写的一些jmeter脚本,相信大多数都遇到过这个问题.那就是:如果换一台电脑运行,文件路径不一样,会导致运行失败. 前不久,自己就真真切切遇到过一回,A同学写了个脚本用于压测, ...

  10. 使用ventoy制作启动盘

    先去应用商店下载,非Deepin用户去官网下载Download.Ventoy. 先确认一下自己的系统镜像是否在清单内.(其实不在也没事) 按照使用说明操作Get start.Ventoy,建议配置为G ...