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. layui数据表格搜索

    简单介绍 我是通过Servlet传递json给layui数据表格模块,实现遍历操作的,不过数据量大的话还是需要搜索功能的.这是我参考网上大佬代码写出的搜索功能. 实现原理 要实现搜索功能,肯定需要链接 ...

  2. 跨域问题及其解决方法(JSONP&CORS)

    一.什么是跨域 当a.qq.com域名下的页⾯或脚本试图去请求b.qq.com域名下的资源时,就是典型的跨域行为.跨域的定义从受限范围可以分为两种,⼴义跨域和狭义跨域. (一)广义跨域 ⼴义跨域通常包 ...

  3. MUI+html5的plus.webview页面传值在电脑浏览器上不可见

    使用plus.webview.currentWebview() 获得当前窗口的webview对象后,再使用document.write()输出显示webview的某个属性值,而plus.webview ...

  4. 微信小程序避坑指南——echarts层级太高/层级遮挡

    问题:小程序中echarts因为小程序原生的canvas层级太高,而导致弹窗这类dom元素无法遮挡住canvas,如下图: 解决方案1:(wx:if控制dom显隐,显示canvas就重新渲染echar ...

  5. vue大型电商项目尚品汇(前台篇)day04

    这几天一直都在做项目,只是没有上传上来,即将把前台项目完结了.现在开始更新整个前台的部分 一.面包屑处理 1.分类操作 点击三级联动进入搜索产生面包屑,直接取参数中的name即可 点击x怎么干掉这个面 ...

  6. BitBlt()函数实现带数字百分比进度条控件、静态文本(STATIC)控件实现的位图进度条、自定义进度条控件实现七彩虹颜色带数字百分比

    Windows API BitBlt()函数实现带数字百分比进度条控件. 有两个例子:一用定时器实现,二用多线程实现. 带有详细注解. 此例是本人原创,绝对是网上稀缺资源(本源码用Windows AP ...

  7. net core天马行空系列-可用于依赖注入的,数据库表和c#实体类互相转换的接口实现

    1.前言 hi,大家好,我是三合.作为一名程序猿,日常开发中,我们在接到需求以后,一般都会先构思一个模型,然后根据模型写实体类,写完实体类后在数据库里建表,接着进行增删改查, 也有第二种情况,就是有些 ...

  8. 物联网lora模块应用案例和LoRawan网关通信技术

    什么是LoRa LoRa(Long Range) 无线通信技术是 Semtech 在2012年开发出来的一款适合物联网使用的射频IC.其设计理念为低功耗.长距离.低成本.网路简单.易于扩展的无线数传技 ...

  9. 对vue响应式的理解

    1.所谓数据响应式就是能够使数据变化可以被检测并对这种变化做出响应的机制. 2.MVVM框架要解决的一个核心问题是连接数据层和视图层,通过数据驱动应用,数据变化,视图更新,要做到这点的就需要对数据做响 ...

  10. python基础知识-day9(数据驱动)

    1.数据驱动的概念 在自动化测试中,需要把测试的数据分离到JSON,YAML等文件中. 2.YAML 的相关知识 YAML 入门教程 分类 编程技术 YAML 是 "YAML Ain't a ...