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.
| Package | Purpose | Main entry point | Default configuration / external dependency |
|---|---|---|---|
Fast.Runtime | Shared ASP.NET Core context, configuration, and MVC extensions | AddConfigurableOptions<T>(), AddMvcFilter() | Usually referenced transitively |
Fast.IaaS | Encoding, validation, masking, retry, tree, and general utilities | MaskingUtil, RetryUtil, and related APIs | No web host dependency |
Fast.NET.Core | Application initialization, configuration scanning, CORS, compression, and buffering | builder.Initialize(), AddCorsAccessor(), AddGzipCompression() | CorsAccessorSettings |
Fast.Cache | CSRedisCore cache wrapper | services.AddCache() | RedisSettings; requires Redis |
Fast.Consul | Service registration, health checks, and KV | services.AddFastConsul() | ConsulSettings; requires Consul |
Fast.DependencyInjection | Marker-based convention registration | services.AddDependencyInjection() | ITransientDependency, IScopedDependency, ISingletonDependency |
Fast.DynamicApplication | Dynamic API discovery for application services | services.AddDynamicApplication() | Call AddControllers() first |
Fast.EventBus | Bounded in-process channel, publishing, subscription, and background handling | services.AddEventBus() | Default capacity 3000; not distributed or durable |
Fast.JwtBearer | JWT Bearer authentication, authorization, and token helpers | services.AddJwtBearer() | JWTSettings |
Fast.Logging | Console and file logging extensions | services.AddLoggingService() | Logging:Fast; file path must be writable |
Fast.Mapster | Mapster registration and mapping | services.AddMapster() | Mapster 10 |
Fast.OpenApi | OpenAPI DTO and JavaScript/TypeScript client generation | services.AddOpenApi() | OpenApiSettings |
Fast.Serialization.System.Text.Json | Shared System.Text.Json options, converters, and masking | services.AddSerialization() | Usually choose one serialization module |
Fast.Serialization.Newtonsoft.Json | Shared Newtonsoft.Json options, converters, and masking | services.AddSerialization() and MVC extension | Usually choose one serialization module |
Fast.SqlSugar | SqlSugar integration, multi-database settings, repositories, and paging | services.AddSqlSugar(), AddSnowflake() | ConnectionSettings, SnowflakeSettings; requires a database |
Fast.Swagger | Swagger documents, grouping, security definitions, and UI | AddSwaggerDocuments(), UseSwaggerDocuments() | SwaggerSettings |
Fast.UnifyResult | Unified responses, model validation, and friendly exceptions | services.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.
Recommended registration order
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:
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).
| Output | Color |
|---|---|
| Information labels | DarkGray |
| Application name, host name, operating system, OS platform/architecture, process architecture | Gray |
| .NET runtime description and Fast.NET framework versions | Cyan |
| Application versions | Cyan |
| ASCII logo | Green |
| Environment name | Green for Production, Yellow for Development, Magenta otherwise |
| Startup time | White |
| Gitee address | Red |
| Usage reminder | Yellow |
| Learning messages | Cyan |
| Framework description and PR invitation | Magenta |
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, andFast.SqlSugarrequire real external services. Use an isolated environment for validation and never point repository checks at production data.Fast.EventBusis 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.Serializationnamespace 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
- Fast.Cache
- Fast.Consul
- Fast.NET.Core
- Fast.DependencyInjection
- Fast.DynamicApplication
- Fast.EventBus
- Fast.IaaS
- Fast.JwtBearer
- Fast.Logging
- Fast.Mapster
- Fast.OpenApi
- Fast.Runtime
- Fast.Serialization.Newtonsoft.Json
- Fast.Serialization.System.Text.Json
- Fast.SqlSugar
- Fast.Swagger
- Fast.UnifyResult
Upgrades and migrations
- Your app stores or transmits runtime enum values. Read the Fast.Runtime 3.5.37 H5 migration and check the version table for the 14 affected packages. The new H5 flag changes the values of Android and subsequent flags.
- Your code uses removed composite Runtime members. See Fast.Runtime 3.5.36 composite-member migration.
- Your app uses SqlSugar multi-database configuration or older repository members. See Fast.SqlSugar 3.5.73 connection and API migration.
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.
| PackageId | Previous version | Batch version |
|---|---|---|
Fast.Cache | 3.5.34 | 3.5.35 |
Fast.Consul | 3.5.10 | 3.5.11 |
Fast.NET.Core | 3.5.40 | 3.5.41 |
Fast.DependencyInjection | 3.5.30 | 3.5.31 |
Fast.DynamicApplication | 3.5.36 | 3.5.37 |
Fast.EventBus | 3.5.29 | 3.5.30 |
Fast.JwtBearer | 3.5.44 | 3.5.45 |
Fast.Logging | 3.5.33 | 3.5.34 |
Fast.Mapster | 3.5.28 | 3.5.29 |
Fast.OpenApi | 3.5.40 | 3.5.41 |
Fast.Runtime | 3.5.31 | 3.5.32 |
Fast.SqlSugar | 3.5.69 | 3.5.70 |
Fast.Swagger | 3.5.35 | 3.5.36 |
Fast.UnifyResult | 3.5.35 | 3.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.
| PackageId | Previous version | Batch version |
|---|---|---|
Fast.Cache | 3.5.35 | 3.5.36 |
Fast.Consul | 3.5.11 | 3.5.12 |
Fast.NET.Core | 3.5.41 | 3.5.42 |
Fast.DependencyInjection | 3.5.31 | 3.5.32 |
Fast.DynamicApplication | 3.5.37 | 3.5.38 |
Fast.EventBus | 3.5.30 | 3.5.31 |
Fast.JwtBearer | 3.5.45 | 3.5.46 |
Fast.Logging | 3.5.34 | 3.5.35 |
Fast.Mapster | 3.5.29 | 3.5.30 |
Fast.OpenApi | 3.5.41 | 3.5.42 |
Fast.Runtime | 3.5.32 | 3.5.33 |
Fast.SqlSugar | 3.5.70 | 3.5.71 |
Fast.Swagger | 3.5.36 | 3.5.37 |
Fast.UnifyResult | 3.5.36 | 3.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.
| PackageId | Previous version | Batch version |
|---|---|---|
Fast.Cache | 3.5.36 | 3.5.37 |
Fast.Consul | 3.5.12 | 3.5.13 |
Fast.NET.Core | 3.5.42 | 3.5.43 |
Fast.DependencyInjection | 3.5.32 | 3.5.33 |
Fast.DynamicApplication | 3.5.38 | 3.5.39 |
Fast.EventBus | 3.5.31 | 3.5.32 |
Fast.JwtBearer | 3.5.46 | 3.5.47 |
Fast.Logging | 3.5.35 | 3.5.36 |
Fast.Mapster | 3.5.30 | 3.5.31 |
Fast.OpenApi | 3.5.42 | 3.5.43 |
Fast.Runtime | 3.5.33 | 3.5.34 |
Fast.SqlSugar | 3.5.71 | 3.5.72 |
Fast.Swagger | 3.5.37 | 3.5.38 |
Fast.UnifyResult | 3.5.37 | 3.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.
| PackageId | Previous version | New version | Guide |
|---|---|---|---|
Fast.JwtBearer | 3.5.47 | 3.5.48 | Fast.JwtBearer |
Fast.Serialization.Newtonsoft.Json | 3.5.27 | 3.5.28 | Fast.Serialization.Newtonsoft.Json |
Fast.SqlSugar | 3.5.72 | 3.5.73 | Fast.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.
| PackageId | Previous version | New version |
|---|---|---|
Fast.Cache | 3.5.37 | 3.5.38 |
Fast.Consul | 3.5.13 | 3.5.14 |
Fast.NET.Core | 3.5.44 | 3.5.45 |
Fast.DependencyInjection | 3.5.33 | 3.5.34 |
Fast.DynamicApplication | 3.5.39 | 3.5.40 |
Fast.EventBus | 3.5.32 | 3.5.33 |
Fast.JwtBearer | 3.5.48 | 3.5.49 |
Fast.Logging | 3.5.36 | 3.5.37 |
Fast.Mapster | 3.5.31 | 3.5.32 |
Fast.OpenApi | 3.5.43 | 3.5.44 |
Fast.Runtime | 3.5.34 | 3.5.35 |
Fast.SqlSugar | 3.5.73 | 3.5.74 |
Fast.Swagger | 3.5.38 | 3.5.39 |
Fast.UnifyResult | 3.5.38 | 3.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.
| PackageId | Previous version | New version |
|---|---|---|
Fast.Cache | 3.5.38 | 3.5.39 |
Fast.Consul | 3.5.14 | 3.5.15 |
Fast.NET.Core | 3.5.45 | 3.5.46 |
Fast.DependencyInjection | 3.5.34 | 3.5.35 |
Fast.DynamicApplication | 3.5.40 | 3.5.41 |
Fast.EventBus | 3.5.33 | 3.5.34 |
Fast.JwtBearer | 3.5.49 | 3.5.50 |
Fast.Logging | 3.5.37 | 3.5.38 |
Fast.Mapster | 3.5.32 | 3.5.33 |
Fast.OpenApi | 3.5.44 | 3.5.45 |
Fast.Runtime | 3.5.35 | 3.5.36 |
Fast.SqlSugar | 3.5.74 | 3.5.75 |
Fast.Swagger | 3.5.39 | 3.5.40 |
Fast.UnifyResult | 3.5.39 | 3.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.
| PackageId | Previous version | New version |
|---|---|---|
Fast.Cache | 3.5.39 | 3.5.40 |
Fast.Consul | 3.5.15 | 3.5.16 |
Fast.NET.Core | 3.5.46 | 3.5.47 |
Fast.DependencyInjection | 3.5.35 | 3.5.36 |
Fast.DynamicApplication | 3.5.41 | 3.5.42 |
Fast.EventBus | 3.5.34 | 3.5.35 |
Fast.JwtBearer | 3.5.50 | 3.5.51 |
Fast.Logging | 3.5.38 | 3.5.39 |
Fast.Mapster | 3.5.33 | 3.5.34 |
Fast.OpenApi | 3.5.45 | 3.5.46 |
Fast.Runtime | 3.5.36 | 3.5.37 |
Fast.SqlSugar | 3.5.75 | 3.5.76 |
Fast.Swagger | 3.5.40 | 3.5.41 |
Fast.UnifyResult | 3.5.40 | 3.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.
