.Net 6中WebApplicationBuilder介绍和用法
介绍
.net 6为我们带来的一种全新的引导程序启动的方式。与之前的拆分成program.cs和startup不同,整个引导启动代码都在program.cs中。
webapplicationbuilder builder = webapplication.createbuilder(args);
在上篇文章中,我简要描述了如何使用 webapplication和webapplicationbuilder配置 asp.net core 应用程序。在这篇文章中,我们来深入看下代码.
正文
我们示例程序的第一步是执行webapplicationbuilder builder = webapplication.createbuilder(args);
创建一个webapplicationbuilder
实例。
从命令行中分配args参数,并将选项对象传递给webapplicationbuilder构造函数的webapplicationoptions
/// <summary> /// initializes a new instance of the <see cref="webapplicationbuilder"/> class with preconfigured defaults. /// </summary> /// <param name="args">command line arguments</param> /// <returns>the <see cref="webapplicationbuilder"/>.</returns> public static webapplicationbuilder createbuilder(string[] args) => new(new() { args = args });
webapplicationoptions和webapplicationbuilder后面在讲
internal webapplicationbuilder(webapplicationoptions options, action<ihostbuilder>? configuredefaults = null) /// <summary> /// options for configuing the behavior for <see cref="webapplication.createbuilder(webapplicationoptions)"/>. /// </summary> public class webapplicationoptions { /// <summary> /// the command line arguments. /// </summary> public string[]? args { get; init; } /// <summary> /// the environment name. /// </summary> public string? environmentname { get; init; } /// <summary> /// the application name. /// </summary> public string? applicationname { get; init; } /// <summary> /// the content root path. /// </summary> public string? contentrootpath { get; init; } /// <summary> /// the web root path. /// </summary> public string? webrootpath { get; init; } }
webapplicationbuilder由一堆只读属性和一个方法组成build(),该方法创建了一个webapplication. 我删除了部分讲解用不到的代码。
如果您熟悉 asp.net core,那么其中许多属性都使用以前版本中的常见类型
- iwebhostenvironment: 用于检索环境
- iservicecollection: 用于向 di 容器注册服务。
- configurationmanager: 用于添加新配置和检索配置值。我在之前的文章有讲
- iloggingbuilder: 用于注册额外的日志提供程序
在webhost和host性质很有趣,因为它们暴露出新的类型,configurewebhostbuilder和configurehostbuilder。这些类型分别实现iwebhostbuilder和ihostbuilder。
公开iwebhostbuilder和ihostbuilder接口对于允许从.net 6 之前的应用程序迁移到新的最小托管,我们如何将的lambda风格配置ihostbuilder与命令式风格的webapplicationbuilder协调起来,这就是configurehostbuilder和configurewebhostbuilder与一些内部沿来ihostbuilder实现。
public sealed class webapplicationbuilder { private const string endpointroutebuilderkey = "__endpointroutebuilder"; private readonly hostbuilder _hostbuilder = new(); private readonly bootstraphostbuilder _bootstraphostbuilder; private readonly webapplicationservicecollection _services = new(); private readonly list<keyvaluepair<string, string>> _hostconfigurationvalues; private webapplication? _builtapplication; /// <summary> /// provides information about the web hosting environment an application is running. /// </summary> public iwebhostenvironment environment { get; } /// <summary> /// a collection of services for the application to compose. this is useful for adding user provided or framework provided services. /// </summary> public iservicecollection services { get; } /// <summary> /// a collection of configuration providers for the application to compose. this is useful for adding new configuration sources and providers. /// </summary> public configurationmanager configuration { get; } /// <summary> /// a collection of logging providers for the application to compose. this is useful for adding new logging providers. /// </summary> public iloggingbuilder logging { get; } /// <summary> /// an <see cref="iwebhostbuilder"/> for configuring server specific properties, but not building. /// to build after configuration, call <see cref="build"/>. /// </summary> public configurewebhostbuilder webhost { get; } /// <summary> /// an <see cref="ihostbuilder"/> for configuring host specific properties, but not building. /// to build after configuration, call <see cref="build"/>. /// </summary> public configurehostbuilder host { get; } /// <summary> /// builds the <see cref="webapplication"/>. /// </summary> /// <returns>a configured <see cref="webapplication"/>.</returns> public webapplication build() { // wire up the host configuration here. we don't try to preserve the configuration // source itself here since we don't support mutating the host values after creating the builder. _hostbuilder.configurehostconfiguration(builder => { builder.addinmemorycollection(_hostconfigurationvalues); }); var chainedconfigsource = new trackingchainedconfigurationsource(configuration); // wire up the application configuration by copying the already built configuration providers over to final configuration builder. // we wrap the existing provider in a configuration source to avoid re-bulding the already added configuration sources. _hostbuilder.configureappconfiguration(builder => { builder.add(chainedconfigsource); foreach (var (key, value) in ((iconfigurationbuilder)configuration).properties) { builder.properties[key] = value; } }); // this needs to go here to avoid adding the ihostedservice that boots the server twice (the genericwebhostservice). // copy the services that were added via webapplicationbuilder.services into the final iservicecollection _hostbuilder.configureservices((context, services) => { // we've only added services configured by the genericwebhostbuilder and webhost.configurewebdefaults // at this point. hostbuilder news up a new servicecollection in hostbuilder.build() we haven't seen // until now, so we cannot clear these services even though some are redundant because // we called configurewebhostdefaults on both the _deferredhostbuilder and _hostbuilder. foreach (var s in _services) { services.add(s); } // add the hosted services that were initially added last // this makes sure any hosted services that are added run after the initial set // of hosted services. this means hosted services run before the web host starts. foreach (var s in _services.hostedservices) { services.add(s); } // clear the hosted services list out _services.hostedservices.clear(); // add any services to the user visible service collection so that they are observable // just in case users capture the services property. orchard does this to get a "blueprint" // of the service collection // drop the reference to the existing collection and set the inner collection // to the new one. this allows code that has references to the service collection to still function. _services.innercollection = services; var hostbuilderproviders = ((iconfigurationroot)context.configuration).providers; if (!hostbuilderproviders.contains(chainedconfigsource.builtprovider)) { // something removed the _hostbuilder's trackingchainedconfigurationsource pointing back to the configurationmanager. // this is likely a test using webapplicationfactory. replicate the effect by clearing the confingurationmanager sources. ((iconfigurationbuilder)configuration).sources.clear(); } // make builder.configuration match the final configuration. to do that, we add the additional // providers in the inner _hostbuilders's configuration to the configurationmanager. foreach (var provider in hostbuilderproviders) { if (!referenceequals(provider, chainedconfigsource.builtprovider)) { ((iconfigurationbuilder)configuration).add(new configurationprovidersource(provider)); } } }); // run the other callbacks on the final host builder host.rundeferredcallbacks(_hostbuilder); _builtapplication = new webapplication(_hostbuilder.build()); // mark the service collection as read-only to prevent future modifications _services.isreadonly = true; // resolve both the _hostbuilder's configuration and builder.configuration to mark both as resolved within the // service provider ensuring both will be properly disposed with the provider. _ = _builtapplication.services.getservice<ienumerable<iconfiguration>>(); return _builtapplication; } private void configureapplication(webhostbuildercontext context, iapplicationbuilder app) { debug.assert(_builtapplication is not null); // userouting called before webapplication such as in a startupfilter // lets remove the property and reset it at the end so we don't mess with the routes in the filter if (app.properties.trygetvalue(endpointroutebuilderkey, out var priorroutebuilder)) { app.properties.remove(endpointroutebuilderkey); } if (context.hostingenvironment.isdevelopment()) { app.usedeveloperexceptionpage(); } // wrap the entire destination pipeline in userouting() and useendpoints(), essentially: // destination.userouting() // destination.run(source) // destination.useendpoints() // set the route builder so that userouting will use the webapplication as the iendpointroutebuilder for route matching app.properties.add(webapplication.globalendpointroutebuilderkey, _builtapplication); // only call userouting() if there are endpoints configured and userouting() wasn't called on the global route builder already if (_builtapplication.datasources.count > 0) { // if this is set, someone called userouting() when a global route builder was already set if (!_builtapplication.properties.trygetvalue(endpointroutebuilderkey, out var localroutebuilder)) { app.userouting(); } else { // useendpoints will be looking for the routebuilder so make sure it's set app.properties[endpointroutebuilderkey] = localroutebuilder; } } // wire the source pipeline to run in the destination pipeline app.use(next => { _builtapplication.run(next); return _builtapplication.buildrequestdelegate(); }); if (_builtapplication.datasources.count > 0) { // we don't know if user code called useendpoints(), so we will call it just in case, useendpoints() will ignore duplicate datasources app.useendpoints(_ => { }); } // copy the properties to the destination app builder foreach (var item in _builtapplication.properties) { app.properties[item.key] = item.value; } // remove the route builder to clean up the properties, we're done adding routes to the pipeline app.properties.remove(webapplication.globalendpointroutebuilderkey); // reset route builder if it existed, this is needed for startupfilters if (priorroutebuilder is not null) { app.properties[endpointroutebuilderkey] = priorroutebuilder; } } private sealed class loggingbuilder : iloggingbuilder { public loggingbuilder(iservicecollection services) { services = services; } public iservicecollection services { get; } } }
configurehostbuilder
public sealed class configurehostbuilder : ihostbuilder, isupportsconfigurewebhost ihostbuilder isupportsconfigurewebhost.configurewebhost(action<iwebhostbuilder> configure, action<webhostbuilderoptions> configureoptions) { throw new notsupportedexception("configurewebhost() is not supported by webapplicationbuilder.host. use the webapplication returned by webapplicationbuilder.build() instead."); }
configurehostbuilder实现ihostbuilder和isupportsconfigurewebhost,但 isupportsconfigurewebhost 的实现是假的什么意思呢?
这意味着虽然以下代码可以编译,但是会在运行时抛出异常。
webapplicationbuilder builder = webapplication.createbuilder(args); builder.host.configurewebhost(webbuilder => { webbuilder.usestartup<startup>(); });
configureservices(),该方法action<>使用iservicecollection从webapplicationbuilder. 所以以下两个调用在功能上是相同的:
后一种方法显然不值得在正常实践中使用,但仍然可以使用依赖于这种方法的现有代码,
public ihostbuilder configureappconfiguration(action<hostbuildercontext, iconfigurationbuilder> configuredelegate) { // run these immediately so that they are observable by the imperative code configuredelegate(_context, _configuration); return this; } public ihostbuilder configureservices(action<hostbuildercontext, iservicecollection> configuredelegate) { // run these immediately so that they are observable by the imperative code configuredelegate(_context, _services); return this; }
builder.services.addsingleton<myimplementation>(); builder.host.configureservices((ctx, services) => services.addsingleton<myimplementation>());
并非所有委托configurehostbuilder都立即传递给运行中的方法。例如useserviceproviderfactory()保存在列表中,稍后在调用webapplicationbuilder.build()
public ihostbuilder useserviceproviderfactory<tcontainerbuilder>(iserviceproviderfactory<tcontainerbuilder> factory) where tcontainerbuilder : notnull { if (factory is null) { throw new argumentnullexception(nameof(factory)); } _operations.add(b => b.useserviceproviderfactory(factory)); return this; }
bootstraphostbuilder
回到configurehostbuilder我们看内部的bootstraphostbuilder,它记录了ihostbuilder收到的所有调用。例如configurehostconfiguration()和configureservices(),
这与configurehostbuilder立即执行提供的委托相比,bootstraphostbuilder的保存将委托提供给稍后执行的列表。这类似于泛型的hostbuilder工作方式。但请注意,这bootstraphostbuilder调用build()会引发异常
internal class bootstraphostbuilder : ihostbuilder { private readonly iservicecollection _services; private readonly list<action<iconfigurationbuilder>> _configurehostactions = new(); private readonly list<action<hostbuildercontext, iconfigurationbuilder>> _configureappactions = new(); private readonly list<action<hostbuildercontext, iservicecollection>> _configureservicesactions = new(); public ihost build() { // hostinghostbuilderextensions.configuredefaults should never call this. throw new invalidoperationexception(); } public ihostbuilder configurehostconfiguration(action<iconfigurationbuilder> configuredelegate) { _configurehostactions.add(configuredelegate ?? throw new argumentnullexception(nameof(configuredelegate))); return this; } public ihostbuilder configureservices(action<hostbuildercontext, iservicecollection> configuredelegate) { // hostinghostbuilderextensions.configuredefaults calls this via configurelogging _configureservicesactions.add(configuredelegate ?? throw new argumentnullexception(nameof(configuredelegate))); return this; } // ..... }
webapplicationbuilder构造函数
最后我们来看webapplicationbuilder构造函数,注释都给大家翻译了
internal webapplicationbuilder(webapplicationoptions options, action<ihostbuilder>? configuredefaults = null) { services = _services; var args = options.args; //尽早运行方法配置通用和web主机默认值,以从appsettings.json填充配置 //要预填充的环境变量(以dotnet和aspnetcore为前缀)和其他可能的默认源 //正确的默认值。 _bootstraphostbuilder = new bootstraphostbuilder(services, _hostbuilder.properties); //不要在这里指定参数,因为我们希望稍后应用它们,以便 //可以覆盖configurewebhostdefaults指定的默认值 _bootstraphostbuilder.configuredefaults(args: null); // this is for testing purposes configuredefaults?.invoke(_bootstraphostbuilder); //我们上次在这里指定了命令行,因为我们跳过了对configuredefaults的调用中的命令行。 //args可以包含主机和应用程序设置,因此我们要确保 //我们适当地订购这些配置提供程序,而不复制它们 if (args is { length: > 0 }) { _bootstraphostbuilder.configureappconfiguration(config => { config.addcommandline(args); }); } // .... }
// 自configurewebhostdefaults覆盖特定于主机的设置(应用程序名称)以来,上次将参数应用于主机配置。 _bootstraphostbuilder.configurehostconfiguration(config => { if (args is { length: > 0 }) { config.addcommandline(args); } // apply the options after the args options.applyhostconfiguration(config); });
到此你可能都非常疑惑这玩意到底在干嘛。只要能看明白下面代码就好了,调用bootstraphostbuilder.rundefaultcallbacks(),
它以正确的顺序运行我们迄今为止积累的所有存储的回调,以构建hostbuildercontext. 该hostbuildercontext则是用来最终设定的剩余性能webapplicationbuilder。
完成特定于应用程序的配置后,在由我们手动调用build()创建一个webapplication实例。
configuration = new(); // collect the hosted services separately since we want those to run after the user's hosted services _services.trackhostedservices = true; // this is the application configuration var (hostcontext, hostconfiguration) = _bootstraphostbuilder.rundefaultcallbacks(configuration, _hostbuilder); // stop tracking here _services.trackhostedservices = false; // capture the host configuration values here. we capture the values so that // changes to the host configuration have no effect on the final application. the // host configuration is immutable at this point. _hostconfigurationvalues = new(hostconfiguration.asenumerable()); // grab the webhostbuildercontext from the property bag to use in the configurewebhostbuilder var webhostcontext = (webhostbuildercontext)hostcontext.properties[typeof(webhostbuildercontext)]; // grab the iwebhostenvironment from the webhostcontext. this also matches the instance in the iservicecollection. environment = webhostcontext.hostingenvironment; logging = new loggingbuilder(services); host = new configurehostbuilder(hostcontext, configuration, services); webhost = new configurewebhostbuilder(webhostcontext, configuration, services);
webapplicationbuilder.build()
该build()方法不是非常复杂,首先是将配置的配置源复制到_hostbuilder的configurationbuilder实现中。调用此方法时,builder它最初为空,因此这将填充由默认构建器扩展方法添加的所有源,以及您随后配置的额外源。
// source itself here since we don't support mutating the host values after creating the builder. _hostbuilder.configurehostconfiguration(builder => { builder.addinmemorycollection(_hostconfigurationvalues); }); _hostbuilder.configureappconfiguration(builder => { builder.add(chainedconfigsource); foreach (var (key, value) in ((iconfigurationbuilder)configuration).properties) { builder.properties[key] = value; } });
接下来,是一样的事情iservicecollection,将它们从_services实例复制到_hostbuilder的集合中。
// this needs to go here to avoid adding the ihostedservice that boots the server twice (the genericwebhostservice). // copy the services that were added via webapplicationbuilder.services into the final iservicecollection _hostbuilder.configureservices((context, services) => { // we've only added services configured by the genericwebhostbuilder and webhost.configurewebdefaults // at this point. hostbuilder news up a new servicecollection in hostbuilder.build() we haven't seen // until now, so we cannot clear these services even though some are redundant because // we called configurewebhostdefaults on both the _deferredhostbuilder and _hostbuilder. foreach (var s in _services) { services.add(s); } // add the hosted services that were initially added last // this makes sure any hosted services that are added run after the initial set // of hosted services. this means hosted services run before the web host starts. foreach (var s in _services.hostedservices) { services.add(s); } // clear the hosted services list out _services.hostedservices.clear(); // add any services to the user visible service collection so that they are observable // just in case users capture the services property. orchard does this to get a "blueprint" // of the service collection // drop the reference to the existing collection and set the inner collection // to the new one. this allows code that has references to the service collection to still function. _services.innercollection = services; var hostbuilderproviders = ((iconfigurationroot)context.configuration).providers; if (!hostbuilderproviders.contains(chainedconfigsource.builtprovider)) { // something removed the _hostbuilder's trackingchainedconfigurationsource pointing back to the configurationmanager. // this is likely a test using webapplicationfactory. replicate the effect by clearing the confingurationmanager sources. ((iconfigurationbuilder)configuration).sources.clear(); } // make builder.configuration match the final configuration. to do that, we add the additional // providers in the inner _hostbuilders's configuration to the configurationmanager. foreach (var provider in hostbuilderproviders) { if (!referenceequals(provider, chainedconfigsource.builtprovider)) { ((iconfigurationbuilder)configuration).add(new configurationprovidersource(provider)); } } });
接下来运行我们在configurehostbuilder属性中收集的任何回调
// run the other callbacks on the final host builder host.rundeferredcallbacks(_hostbuilder);
最后我们调用_hostbuilder.build()构建host实例,并将其传递给 的新实例webapplication。调用_hostbuilder.build()是调用所有注册回调的地方。
_builtapplication = new webapplication(_hostbuilder.build());
最后,为了保持一切一致configurationmanager实例被清除,并链接到存储在webapplication. 此外iservicecollectiononwebapplicationbuilder被标记为只读,因此在调用后尝试添加服务webapplicationbuilder将抛出一个invalidoperationexception. 最后webapplication返回。
// mark the service collection as read-only to prevent future modifications _services.isreadonly = true; // resolve both the _hostbuilder's configuration and builder.configuration to mark both as resolved within the // service provider ensuring both will be properly disposed with the provider. _ = _builtapplication.services.getservice<ienumerable<iconfiguration>>(); return _builtapplication;
差不多就是这样.
到此这篇关于.net 6中webapplicationbuilder介绍和用法的文章就介绍到这了。希望对大家的学习有所帮助,也希望大家多多支持。
推荐阅读