Skip to content

Module guide ​

Fast.NET consists of 17 independently published NuGet packages. The primary modules target .NET 8, .NET 9, and .NET 10; Fast.IaaS targets .NET Standard 2.1.

Select a package below for installation, configuration and examples, or open the public API reference. For an existing application, start with upgrades and migrations.

Each module identifies the version covered by its guide or API reference. Installation uses the packages available from your NuGet sources. Verified example versions are listed separately.

PackagePurposeMain entry pointDefault configuration / external dependency
Fast.RuntimeShared ASP.NET Core context, configuration, and MVC extensionsAddConfigurableOptions<T>(), AddMvcFilter()Usually referenced transitively
Fast.IaaSEncoding, validation, masking, retry, tree, and general utilitiesMaskingUtil, RetryUtil, and related APIsNo web host dependency
Fast.NET.CoreApplication initialization, configuration scanning, CORS, compression, and bufferingbuilder.Initialize(), AddCorsAccessor(), AddGzipCompression()CorsAccessorSettings
Fast.CacheCSRedisCore cache wrapperservices.AddCache()RedisSettings; requires Redis
Fast.ConsulService registration, health checks, and KVservices.AddFastConsul()ConsulSettings; requires Consul
Fast.DependencyInjectionMarker-based convention registrationservices.AddDependencyInjection()ITransientDependency, IScopedDependency, ISingletonDependency
Fast.DynamicApplicationDynamic API discovery for application servicesservices.AddDynamicApplication()Call AddControllers() first
Fast.EventBusBounded in-process channel, publishing, subscription, and background handlingservices.AddEventBus()Default capacity 3000; not distributed or durable
Fast.JwtBearerJWT Bearer authentication, authorization, and token helpersservices.AddJwtBearer()JWTSettings
Fast.LoggingConsole and file logging extensionsservices.AddLoggingService()Logging:Fast; file path must be writable
Fast.MapsterMapster registration and mappingservices.AddMapster()Mapster 10
Fast.OpenApiOpenAPI DTO and JavaScript/TypeScript client generationservices.AddOpenApi()OpenApiSettings
Fast.Serialization.System.Text.JsonShared System.Text.Json options, converters, and maskingservices.AddSerialization()Usually choose one serialization module
Fast.Serialization.Newtonsoft.JsonShared Newtonsoft.Json options, converters, and maskingservices.AddSerialization() and MVC extensionUsually choose one serialization module
Fast.SqlSugarSqlSugar integration, multi-database settings, repositories, and pagingservices.AddSqlSugar(), AddSnowflake()ConnectionSettings, SnowflakeSettings; requires a database
Fast.SwaggerSwagger documents, grouping, security definitions, and UIAddSwaggerDocuments(), UseSwaggerDocuments()SwaggerSettings
Fast.UnifyResultUnified responses, model validation, and friendly exceptionsservices.AddUnifyResult()Designed for MVC/controller applications

Fast.OpenApi generates TypeScript clients with separate import type declarations and explicit Promise<T> return types. Actions returning non-generic Task or ValueTask use Promise<void>. Download and Export actions retain their response: Web clients use AxiosResponse<Blob>, while mobile clients allow AxiosResponse<Blob | ArrayBuffer | string> for browser blobs, binary buffers, or native temporary file paths. Their autoDownloadFile parameter defaults to true; set it to false to receive the file response without requesting automatic saving. Other values without a concrete schema remain unknown. The output is compatible with verbatimModuleSyntax and the current Fast ESLint Config rules. Generated Web and mobile multipart upload methods also expose an optional Axios onUploadProgress callback.

Fast.IaaS 3.5.27 formats exact TimeSpan boundaries correctly through ToDescription(): one minute is 01分00秒, one hour is 01时00分00秒, and one day is 01天00时00分00秒.

Fast.Runtime 3.5.30 safely handles an unavailable HttpContext outside the request lifecycle. LocalIpv4() and LocalIpv6() return the server endpoint, while RemoteIpv4() and RemoteIpv6() return Connection.RemoteIpAddress after trusted UseForwardedHeaders processing. The misleading LanIpv4() and LanIpv6() methods have been removed. Fast.NET.Core 3.5.38 returns HttpRequestMethodEnum.Unknown when no request context exists, and Fast.SqlSugar 3.5.65 leaves unavailable request audit fields empty.

csharp
builder.Initialize();

builder.Services.AddSerialization();
builder.Services.AddControllers();

builder.Services.AddDependencyInjection();
builder.Services.AddEventBus();
builder.Services.AddUnifyResult();
builder.Services.AddDynamicApplication();
builder.Services.AddSwaggerDocuments(builder.Configuration);

Order matters only where modules have an actual dependency. The explicit requirement is that AddDynamicApplication() runs after MVC controller registration.

Console output ​

Starting with Fast.Runtime 3.5.29, use MAppContext.ConsoleWrite to write text with colors applied to individual segments:

csharp
MAppContext.ConsoleWrite(e =>
{
    e.ForegroundColor = ConsoleColor.Blue;
    e.WriteLine();
    e.WriteLine("Fast.NET");
});

The callback receives a Fast.Runtime.ConsoleWriter with ForegroundColor, BackgroundColor, Write, WriteLine, and ResetColor(). The writer captures both colors on entry and restores them in finally; ResetColor() restores the same colors within the callback. Callbacks sharing an output stream execute serially and support nesting. Callbacks must complete synchronously, and callback or write exceptions propagate to the caller. When Console.IsOutputRedirected is true, color assignments are ignored and only text is written, without generated ANSI color codes.

Startup banners in Fast.NET.Core and direct diagnostics in Runtime, OpenApi, and SqlSugar use this entry point for Windows CMD, PowerShell, Windows Terminal, and Linux terminals. Fast.IaaS 3.5.27 remains a standalone netstandard2.1 package and uses its internal writer in src/IaaS/Internals/ConsoleWriter.cs without a Runtime dependency.

In the current Fast.NET.Core 3.5.38 source, builder.Initialize() prints application and host information before the ASCII logo. Application names and assembly versions come from the entry assembly; framework assembly versions come from the Core assembly. The implementation does not also print informational versions; unavailable names or versions use Unknown. The environment name comes from builder.Environment, and the startup timestamp is the local time when the banner is written (yyyy-MM-dd HH:mm:ss).

OutputColor
Information labelsDarkGray
Application name, host name, operating system, OS platform/architecture, process architectureGray
.NET runtime description and Fast.NET framework versionsCyan
Application versionsCyan
ASCII logoGreen
Environment nameGreen for Production, Yellow for Development, Magenta otherwise
Startup timeWhite
Gitee addressRed
Usage reminderYellow
Learning messagesCyan
Framework description and PR invitationMagenta

The banner also updates indentation and spacing and adds a lawful-use reminder and learning messages. Redirected output contains the same text without generated color codes; the writer restores the original colors after output.

Fast.Logging continues to write through the TextWriter supplied to its ConsoleFormatter. ConsoleLoggerProvider handles terminal adaptation, ANSI parsing where needed, and queued console writes. The formatter does not change Console.ForegroundColor; LoggerColorBehavior.Default suppresses generated colors for redirected output, while ANSI support is handled by the provider rather than inferred solely from redirection.

Dependency injection conventions ​

AddDependencyInjection() scans non-abstract classes that implement ITransientDependency, IScopedDependency, or ISingletonDependency. Services that expose business interfaces are registered against those interfaces; services that only implement a lifetime marker are registered by their concrete type and can be injected directly.

Infrastructure notes ​

  • Fast.Cache, Fast.Consul, and Fast.SqlSugar require real external services. Use an isolated environment for validation and never point repository checks at production data.
  • Fast.EventBus is in-process. Pending events are not recovered after application restart. Use a dedicated message broker when you need cross-process, durable, or at-least-once delivery.
  • Both serialization packages use the Fast.Serialization namespace and similar extension names. Select and configure one deliberately.
  • File logging requires a writable directory. In containers, map it to a writable volume or prefer standard output.

Configuration source of truth ​

Option types participate in the repository post-configuration convention. The corresponding *SettingsOptions type and XML API documentation are authoritative for supported fields. Never include real tokens, connection strings, or passwords in documentation, samples, or issues.

Module usage ​

Upgrades and migrations ​

The tables below preserve each batch's original versions and values. For release history, see the Fast.NET CHANGELOG.

2026-10-17 package alignment ​

This batch increments 14 packages on the 3.5.x patch line: Runtime, EventBus, Logging, UnifyResult and the remaining Runtime dependency chain. These source versions await publication; they do not confirm a NuGet upload. Fast.IaaS and both serialization packages have no source or dependency changes in this batch and retain their versions.

PackageIdPrevious versionBatch version
Fast.Cache3.5.343.5.35
Fast.Consul3.5.103.5.11
Fast.NET.Core3.5.403.5.41
Fast.DependencyInjection3.5.303.5.31
Fast.DynamicApplication3.5.363.5.37
Fast.EventBus3.5.293.5.30
Fast.JwtBearer3.5.443.5.45
Fast.Logging3.5.333.5.34
Fast.Mapster3.5.283.5.29
Fast.OpenApi3.5.403.5.41
Fast.Runtime3.5.313.5.32
Fast.SqlSugar3.5.693.5.70
Fast.Swagger3.5.353.5.36
Fast.UnifyResult3.5.353.5.36

2026-10-17 request-local cache priority ​

This batch increments 14 packages in the Runtime dependency chain by one patch version. Fast.Runtime 3.5.33 returns a request-local cache hit before checking cancellation; misses still check cancellation before shared cache or remote queries. IaaS and both standalone serialization packages retain their versions. These are the source target versions for that historical batch. No Fast.NET build, pack or tests were run, as requested; previous validation records do not apply to these new versions.

PackageIdPrevious versionBatch version
Fast.Cache3.5.353.5.36
Fast.Consul3.5.113.5.12
Fast.NET.Core3.5.413.5.42
Fast.DependencyInjection3.5.313.5.32
Fast.DynamicApplication3.5.373.5.38
Fast.EventBus3.5.303.5.31
Fast.JwtBearer3.5.453.5.46
Fast.Logging3.5.343.5.35
Fast.Mapster3.5.293.5.30
Fast.OpenApi3.5.413.5.42
Fast.Runtime3.5.323.5.33
Fast.SqlSugar3.5.703.5.71
Fast.Swagger3.5.363.5.37
Fast.UnifyResult3.5.363.5.37

2026-10-24 HarmonyOS enum and dependency alignment ​

This batch increments Runtime and its dependent packages by one patch version within 3.5.x, covering 14 packages. IaaS and both standalone serialization packages are unchanged. The table lists the NuGet package versions for this batch. Fast.Runtime adds HarmonyOS and changes enum numeric values, a breaking change that retains the requested 3.5.x cadence. See the Runtime guide for value migration and consumer recompilation requirements.

PackageIdPrevious versionBatch version
Fast.Cache3.5.363.5.37
Fast.Consul3.5.123.5.13
Fast.NET.Core3.5.423.5.43
Fast.DependencyInjection3.5.323.5.33
Fast.DynamicApplication3.5.383.5.39
Fast.EventBus3.5.313.5.32
Fast.JwtBearer3.5.463.5.47
Fast.Logging3.5.353.5.36
Fast.Mapster3.5.303.5.31
Fast.OpenApi3.5.423.5.43
Fast.Runtime3.5.333.5.34
Fast.SqlSugar3.5.713.5.72
Fast.Swagger3.5.373.5.38
Fast.UnifyResult3.5.373.5.38

Fast.SqlSugar explicitly references target-specific System.Security.Cryptography.Pkcs versions and removes the explicit SQLitePCLRaw.bundle_e_sqlite3 reference and central override. Fast.Swagger updates Swashbuckle.AspNetCore to 10.3.1. See the SqlSugar and Swagger guides.

This batch reviewed source, dependency relationships and effective MSBuild package metadata. Tests were skipped as requested; no restore, build, pack or consumer validation was performed. Historical build and assertion records do not validate these new versions. The getting-started example retains its existing pinned dependencies; its compilation record does not cover this batch.

2026-10-30 Core static-file mappings ​

Fast.NET.Core increments from 3.5.43 to 3.5.44, adding a UseStaticFiles overload that reads MIME mappings from StaticFileSettings or a custom section. Mappings supplement or override default entries while preserving the remaining defaults. The dependency remains Fast.Runtime 3.5.34. See the Core guide for configuration and constraints.

2026-10-30 dependency patch updates ​

This batch updates the three NuGet packages below. Module implementations and public APIs remain the same.

PackageIdPrevious versionNew versionGuide
Fast.JwtBearer3.5.473.5.48Fast.JwtBearer
Fast.Serialization.Newtonsoft.Json3.5.273.5.28Fast.Serialization.Newtonsoft.Json
Fast.SqlSugar3.5.723.5.73Fast.SqlSugar

Both ASP.NET Core packages use 8.0.33 / 9.0.22 / 10.0.14 for net8.0 / net9.0 / net10.0; Pkcs uses 8.0.2 / 9.0.22 / 10.0.14. Restore, Release builds, local packaging and dependency/DLL/XML checks passed for all targets without final warnings or errors. No host or runtime regression was run. The getting-started example retains its pinned dependencies and does not validate this batch; Core retains its separate 3.5.44 update and Runtime remains at 3.5.34.

SqlSugar 3.5.73 connection and public API migration ​

The 3.5.73 API-migration batch retained its package version; its connection and public API changes remain included in this follow-up 3.5.74 release. The source removes DbConnectionInfo, repository Entities and public database-helper access, revises primary/replica options and reduces/reassigns SugarDbType. Consumers must migrate and rebuild. Generated MySql/MySqlConnector, SqlServer and PostgreSQL strings support primary and replica MaxPoolSize; a custom primary connection string suppresses replicas. See the connection and API migration guide.

2026-10-30 Runtime flags and dependency alignment ​

Runtime increments to 3.5.35; each of its 13 direct or transitive consumers also increments one patch version. New packages reference Runtime 3.5.35; DynamicApplication references UnifyResult 3.5.39 and Swagger references DynamicApplication 3.5.40. IaaS and both independent serialization packages are outside this chain and retain their versions. External dependencies are unchanged.

PackageIdPrevious versionNew version
Fast.Cache3.5.373.5.38
Fast.Consul3.5.133.5.14
Fast.NET.Core3.5.443.5.45
Fast.DependencyInjection3.5.333.5.34
Fast.DynamicApplication3.5.393.5.40
Fast.EventBus3.5.323.5.33
Fast.JwtBearer3.5.483.5.49
Fast.Logging3.5.363.5.37
Fast.Mapster3.5.313.5.32
Fast.OpenApi3.5.433.5.44
Fast.Runtime3.5.343.5.35
Fast.SqlSugar3.5.733.5.74
Fast.Swagger3.5.383.5.39
Fast.UnifyResult3.5.383.5.39

Validation: full-solution Release build and local packaging passed without warnings or errors. The 14 affected packages have 84 DLL/XML files matching build-output hashes, 42 correct assembly versions and 45 internal dependency entries matching source versions. All 28 bilingual module version headers match the review records. Fast.Docs pnpm run check passed: typecheck, lint, 34 tests passed/1 Nginx test skipped because Nginx is unavailable, API coverage, site build, links/assets/anchors across 434 HTML pages, and formatting. No application host, service integration, database operation or NuGet publication was performed.

2026-10-31 Runtime composite-member removal and dependency alignment ​

Runtime increments to 3.5.36; its 13 referencing packages also increment one patch version. DynamicApplication references UnifyResult 3.5.40 and Swagger references DynamicApplication 3.5.41; the complete chain follows Runtime 3.5.36. IaaS, both independent serialization packages and external dependencies remain unchanged. Composite-member removal breaks source/name contracts, while numeric masks from 3.5.35 require no renumbering.

PackageIdPrevious versionNew version
Fast.Cache3.5.383.5.39
Fast.Consul3.5.143.5.15
Fast.NET.Core3.5.453.5.46
Fast.DependencyInjection3.5.343.5.35
Fast.DynamicApplication3.5.403.5.41
Fast.EventBus3.5.333.5.34
Fast.JwtBearer3.5.493.5.50
Fast.Logging3.5.373.5.38
Fast.Mapster3.5.323.5.33
Fast.OpenApi3.5.443.5.45
Fast.Runtime3.5.353.5.36
Fast.SqlSugar3.5.743.5.75
Fast.Swagger3.5.393.5.40
Fast.UnifyResult3.5.393.5.40

Validation: final full-solution restore, Release build and local packaging passed without warnings or errors. All 14 affected packages were checked: 84 DLL/XML files, 42 assembly versions and 45 internal dependency entries. Runtime passed 182 assertions on each of three runtimes, and both guides' replacement-mask example compiled for all targets. Reviewed API declarations decrease from 265 to 261. Full documentation checks passed: typecheck, lint, 34 tests passed/1 Nginx test skipped because Nginx is unavailable, API coverage, site build, links/assets/anchors across 434 HTML pages, and formatting. No application host, live service, database migration or package publication was performed.

2026-11-02 mobile H5 and dependency alignment ​

Runtime increments to 3.5.37 and its 13 referencing packages also increment one patch version. DynamicApplication references UnifyResult 3.5.41; Swagger references DynamicApplication 3.5.42; internal dependencies follow Runtime 3.5.37. IaaS, both independent serialization packages and external dependencies retain their versions. H5 and Web are distinct platform flags: do not reinterpret old Android=16 as new H5. Migrate old meanings and rebuild consumers.

PackageIdPrevious versionNew version
Fast.Cache3.5.393.5.40
Fast.Consul3.5.153.5.16
Fast.NET.Core3.5.463.5.47
Fast.DependencyInjection3.5.353.5.36
Fast.DynamicApplication3.5.413.5.42
Fast.EventBus3.5.343.5.35
Fast.JwtBearer3.5.503.5.51
Fast.Logging3.5.383.5.39
Fast.Mapster3.5.333.5.34
Fast.OpenApi3.5.453.5.46
Fast.Runtime3.5.363.5.37
Fast.SqlSugar3.5.753.5.76
Fast.Swagger3.5.403.5.41
Fast.UnifyResult3.5.403.5.41

Validation: final full-solution restore, Release build and local packaging passed without warnings or errors. Verified 84 DLL/XML files, 42 assembly versions, 45 internal dependencies and three H5 XML entries across 14 packages. Each target passed 290 packaged-assembly assertions; exact bilingual examples compiled on all targets and 42 old/new mapping rows match source. Full docs checks passed: typecheck, lint, 34 tests passed/1 Nginx test skipped because Nginx is unavailable, API coverage, build, links/assets/anchors across 434 pages, and formatting. No host, live service, database migration or publication was run.