Struct HostBuilder 

pub struct HostBuilder { /* private fields */ }

Implementations

impl HostBuilder

pub fn new() -> Self

pub fn register<F>(self, f: F) -> Self

where F: FnOnce(ServiceCollection) -> ServiceCollection + Send + 'static,

pub fn configure<F>(self, f: F) -> Self

where F: FnOnce(&mut HostAppBuilder) + Send + 'static,

pub fn mode(self, mode: AppMode) -> Self

pub fn add_options<T>(self, section: &str) -> Self

where T: for<'de> Deserialize<'de> + Default + Send + Sync + 'static,

自动绑定 appsettings 配置节到 T，并以 Arc<T> 注册到 DI 容器。

参考 ASP.NET Core 的 services.Configure<T>(configuration.GetSection(...))： 框架在 build() 时读取已合并的 appsettings（含 {Mode} overlay 与 env override）， 取 section 子节点反序列化为 T，注册为单例供 handler 通过 Arc<T> 注入。

Host::builder()
    .add_options::<SiteConfig>("Site")
    .build()

pub fn use_spa(self, source: impl Into<SpaSource>) -> Self

Serve SPA static files from a directory on disk.

Host::builder().use_spa("wwwroot").build()

Runtime disk root — the directory next to the process (or under app_base) where operators may drop overrides. This is not build.rs web_root (that path only names what was baked in).

When the binary was built with #[webx::main(embed)] (and build.rs wrote a table), that table is layered underneath this directory at build: same-named disk files win. Without (embed), only the disk directory is served.

pub fn no_spa(self) -> Self

Explicitly disable SPA, including auto-detection.

By default, the framework auto-detects wwwroot/ under app_base(). Call this when you want a pure API host without SPA fallback, or in tests to isolate framework behavior from filesystem state.

pub fn use_cors(self, config: CorsConfig) -> Self

pub fn add_authentication(self) -> Self

Register the JWT authentication service and middleware.

The ASP.NET Core AddAuthentication() + UseAuthentication() pair: it enables JWT bearer authentication so endpoints that declare #[authorize] receive claims. Route authorization itself is part of each endpoint’s compile-time metadata and is always enforced after routing — there is no second switch to turn it on.

Host::builder()
    .add_authentication()
    .build()

pub fn add_localization(self) -> Self

Enable localization with the conventional resource layout.

Reads <culture>.json files from locales/ under the application base (for example locales/zh-CN.json, locales/en.json). The active culture is Culture.Default from appsettings (or APP__Culture__Default); it decides the language of endpoint names, OpenAPI, and the endpoint catalog.

Host::builder().add_localization().build()

A missing locales/ directory is not an error; keys then fall back to their literal or the key itself. For a single-file deployment, register compiled-in resources with Self::add_localization_with.

pub fn add_localization_with(self, options: LocalizationOptions) -> Self

Enable localization with explicit options.

Use this for compiled-in resources (include_str!) or a non-conventional resource directory. Explicit resources override files with the same culture and key.

Host::builder()
    .add_localization_with(
        LocalizationOptions::none()
            .resources("zh-CN", include_str!("../locales/zh-CN.json"))
            .resources("en", include_str!("../locales/en.json")),
    )
    .build()

pub fn use_resource_authorization(self) -> Self

👎Deprecated since 0.6.0:

Route authorization is enforced from endpoint metadata; remove this call

Deprecated: route authorization is enforced from endpoint metadata.

Every endpoint that declares #[authorize] is checked by the endpoint itself, after routing; there is no separate policy switch. This method does nothing and will be removed in a future major release.

pub fn add_memory_cache(self) -> Self

Register a memory cache instance for use via IDistributedCache trait.

The cache is registered as a singleton in the DI container. Handlers can access it by implementing From<Arc<MemoryCache>>.

Host::builder()
    .add_memory_cache()
    .build()
    .run().await;

pub fn add_memory_cache_with(self, max_entries: usize) -> Self

Register a memory cache with custom configuration.

pub fn use_middleware<T: IMiddleware + Default + 'static>(self) -> Self

Register a middleware by type in the default slot (MiddlewareSlot::AfterAuth).

The default slot runs after authentication, so middleware that reads ctx.claims() actually sees the principal. Use Self::use_middleware_at to choose a different slot.

Host::builder()
    .use_middleware::<TimingMiddleware>()
    .build()

pub fn use_middleware_at<T: IMiddleware + Default + 'static>( self, slot: MiddlewareSlot, ) -> Self

Register a middleware by type in a specific pipeline slot.

pub fn use_middleware_with<F>(self, factory: F) -> Self

where F: Fn() -> Arc<dyn IMiddleware> + Send + Sync + 'static,

Register a middleware with a custom factory function (default slot: MiddlewareSlot::AfterAuth).

Use this when the middleware requires constructor parameters:

Host::builder()
    .use_middleware_with(|| {
        Arc::new(TimingMiddleware::new("api")) as Arc<dyn IMiddleware>
    })
    .build()

pub fn use_middleware_with_at<F>(self, slot: MiddlewareSlot, factory: F) -> Self

where F: Fn() -> Arc<dyn IMiddleware> + Send + Sync + 'static,

Register a middleware with a custom factory in a specific pipeline slot.

pub fn add_health_check<F>(self, name: impl Into<String>, check: F) -> Self

where F: Fn() -> HealthStatus + Send + Sync + 'static,

Register a health check probe.

Health checks are exposed via /health and /health/ready endpoints following RFC 8407 (application/health+json content type).

Host::builder()
    .add_health_check("database", || -> HealthStatus {
        if db_ping() { HealthStatus::pass() } else { HealthStatus::fail("db unreachable") }
    })
    .build()

pub fn build(self) -> Host

Trait Implementations

impl Default for HostBuilder

fn default() -> Self

Returns the “default value” for a type.