Zongsoft.Core 7.67.0

Zongsoft Core

English | 简体中文

Overview

Zongsoft.Core is the foundation package of the Zongsoft Framework. It provides the shared abstractions, base types, utility APIs, and infrastructure building blocks used by the rest of the Zongsoft ecosystem.

The current project targets net8.0, net9.0, and net10.0, uses the root namespace Zongsoft, and is packaged as the Zongsoft.Core NuGet package. It integrates with the Microsoft.Extensions.* stack for dependency injection, configuration, options, hosting abstractions, object pooling, and memory caching.

Installation

dotnet add package Zongsoft.Core

What's Included

The package is intentionally broad: it is the common layer that higher-level Zongsoft packages build on. The main areas are:

• Common utilities (Zongsoft.Common)

  Conversion helpers, random generation, sequences, predicates, timers, bit vectors, string/type/URI extensions, timestamps, locking helpers, and validation contracts. Variable sources include the IVariables contract, the case-insensitive in-memory Variables dictionary, live dictionary views through Variables.Wrap() / ToVariables(), and live environment variables through Variables.Environments().

• Collections (Zongsoft.Collections)

  Hierarchical nodes, category trees, parameter bags, synchronized collections, queues, object pools, and collection/dictionary extensions.

• Components (Zongsoft.Components)

  Command infrastructure, command-line parsing, command option variables, event exchange, feature pipelines, retry/fallback/breaker/throttle/timeout features, state machines, workers, supervisors, handlers, executors, filters, converters, and identifiers.

• Configuration (Zongsoft.Configuration)

  Settings and connection settings, configuration binding and recognition, XML configuration providers and processing instructions, model-backed configuration, Profile/INI parsing, directive extensions and variable views, and options integration with Microsoft.Extensions.Options.

• Data abstractions (Zongsoft.Data)

  Query criteria, conditions, ranges, paging, sorting, operands, model descriptors, data access/service contracts, operation options and events, metadata models, archiving contracts, and transaction primitives.

• Services (Zongsoft.Services)

  Application context and modules, service registration/discovery helpers, dependency metadata, modular services, service accessors, and distributed-lock abstractions.

• Caching (Zongsoft.Caching)

  In-memory cache wrappers, eviction/change events, cache scanner, distributed-cache contract, and the Spooler<T> batching helper.

• Communication and messaging (Zongsoft.Communication, Zongsoft.Messaging)

  Network address and protocol values, channel, listener, sender, receiver, requester/responder, transmitter, packetizer, notifier, message queue, producer/consumer, poller, and queue option abstractions.

• Diagnostics and telemetry (Zongsoft.Diagnostics)

  Logging contracts, console/text/XML loggers and formatters, diagnostic configuration, telemetry meters, metric descriptors, and exporter launcher contracts.

• IO and hardware (Zongsoft.IO)

  Virtual file-system contracts and local implementation, path parsing, Searcher local wildcard search, MIME helpers, compression helpers, binary/text reader extensions, and hardware profile models.

• Security (Zongsoft.Security)

  Claims helpers, credentials, certificates, secret/signature contracts, password utilities, authentication/authorization flows, users, roles, privileges, and privilege evaluators.

• Serialization (Zongsoft.Serialization)

  Serializer contracts, JSON serializer helpers, serialization options, naming conventions, member attributes, and System.Text.Json converters.

• Expressions (Zongsoft.Expressions)

  Lexer/tokenizer infrastructure, expression evaluator contracts, and syntax exceptions.

• Text and templates (Zongsoft.Text, Zongsoft.Text.Templating)

  Regular-text processing, template contracts, and text template evaluation, member navigation, formatting and diagnostics.

• Reflection (Zongsoft.Reflection)

  High-performance reflection helpers and member-expression parsing/evaluation.

• Runtime helpers (Zongsoft.Resources, Zongsoft.Scheduling, Zongsoft.Versioning, Zongsoft.Terminals)

  Resource lookup, trigger abstractions, semantic version parsing, and terminal/console command execution.

Password Hashing

Password uses PBKDF2 with SHA256 by default. Its Factor ranges from 0 to 255 and defaults to 10. Zero disables additional iterations by performing PBKDF2 once; positive factors map to Factor × 65,535 iterations. The default factor 10 means 655,350 iterations; factor 127 means 8,322,945 iterations. Execution time depends on the hardware, hash algorithm, and load.

The text format is algorithm#factor:nonce|value; #factor may be omitted when the factor is zero. Factor replaces Exponent; hashes generated with earlier iteration mappings must be regenerated.

Password implements ISpanParsable<Password> and IParsable<Password>, with public Parse and TryParse overloads for strings and character spans. The text format is culture-independent and the interface's format provider is ignored. Null or empty input represents an empty password. Invalid text returns false and an empty result from TryParse; Parse throws FormatException instead.

Service Registration

ServiceCollectionExtension.Register discovers IServiceRegistration implementations throughout an assembly, including internal classes and private nested classes. It uses an instance supplied by a public static field or property first; otherwise, it invokes a public or non-public parameterless constructor. Open generic types and abstract registrars without a supplied instance are not instantiated. Registration failures propagate to the caller.

Ordinary [Service] registrations and option scanning still require externally visible types. A public nested service inside a non-public containing type is not externally visible. This keeps implementation-only services out of automatic registration while allowing private registration helpers.

Event Dispatch

EventExchanger uses IEventDispatcher to capture ambient features and a fixed private IExecutor<EventContext> for remote delivery. FeatureProvider.Default includes Transaction.Features, the shared provider of transaction-bound features implementing IFeature and IPredication, including in standalone use. Applications can extend its Providers collection or register IFeatureProvider services to add conditions. Channels receive events through IEventReceiver. Queue event channels share the topic convention in Events.GetTopic() and the incoming message handler from Events.GetHandler(receiver). Default delivery has no policy pipeline; application plugins can explicitly configure Polly policies through EventDispatcher.Pipeline. See event dispatch and ambient features.

Application Lifetime

ApplicationContext participates in the host's awaited startup and shutdown phases. Exit() and Exit(exitCode) request host shutdown; they do not terminate the process. DisposeAsync() waits for owned worker cleanup before releasing context resources. Application builders expose BuildAsync() so initialization failure can await asynchronous disposal. Container-resolved initializers and borrowed service-provider views retain their original owner.

Terminal Input

ITerminal.Input uses TextReader, accepting StreamReader and StringReader directly. Terminal.Console.Input provides shared line input with process lifetime: only one caller can wait, and cancellation preserves the read and its result for a subsequent call. Executors do not dispose input. Injected readers follow their own cancellation and ownership contracts. See Terminal input.

ITerminalExecutor runs its command loop through three RunAsync overloads and returns the exit code when the loop ends. Callers must await the task.

ITerminal.Abort() synchronously notifies interruption and returns whether it was handled; it does not stop the executor or process. Hosts own process-signal policy. Core registers no global console signal handlers.

Periodic Work

Common.Timer executes its constructor callback serially and accepts a TimeProvider. Start() schedules periodic execution. Startup, stopping, and disposal accept no cancellation tokens. Stop() requests internal cancellation without waiting for callbacks or cleanup; StopAsync() waits for shutdown. Dispose() permanently closes the timer without waiting, while DisposeAsync() awaits cleanup even after synchronous disposal. Callers must avoid using business operations after disposal or awaiting completion from within the same run. Failed reports run failures, and Stopped reports that the callback and resource cleanup have ended. Asynchronous stopping and disposal wait for notifications to return and propagate run and notification failures. The timer observes background task exceptions internally and does not write logs. See Asynchronous periodic timers.

Spooler<T> serializes batch callbacks triggered by a period, a full-buffer write, or an explicit flush. It supports consuming enumeration and inheritance. PutAsync admits data; FlushAsync waits for an active flush and processes remaining data once. Disposal is asynchronous: DisposeAsync stops admission and waits for active flushes and cleanup without draining the buffer. Periodic errors raise Failed and propagate from asynchronous disposal; the buffer does not write logs.

Both constructors accept an optional TimeProvider. The Zongsoft.Caching.Spooler meter exposes admission, queue, flush duration, full-buffer wait, and failure metrics for application-selected export. FileLogger supports only asynchronous disposal and releases its resources after active file writes finish.

Communication Lifetimes

ChannelBase.CloseAsync executes once and shares its result with concurrent callers. Cancellation before entry prevents closing; after entry it only cancels that caller's wait. Closing and closed notifications cannot bypass transport cleanup. Disposal waits for closing before invoking the derived resource cleanup once. A closed channel cannot be reopened; create a new instance. Lifecycle callbacks may request closing but must not synchronously wait for the operation that contains them.

WorkerBase coordinates start, stop, pause and resume asynchronously and supports IAsyncDisposable. Matching in-flight actions share their result. Stop waits for the current action; start, pause and resume return without scheduling work when a different action is in progress. Starting during stop does not schedule a restart, and pausing during startup does not schedule a subsequent pause. Startup failures propagate and invoke the stop hook to clean partially initialized resources. Stop failures retain Stopping and block restart until cleanup succeeds; notification failures do not roll back established state. IWorker exposes StartAsync, StopAsync, PauseAsync and ResumeAsync. WorkerBase and IListener<T> expose disposal through IAsyncDisposable; owners use await using or await DisposeAsync. Enabled only controls whether a worker may start. Changes after startup begins apply to the next start; they do not stop the current run or affect pause, resume, stop or disposal.

State notifications retain the action names Start, Stop, Pause and Resume. OnStopAsync stops execution and releases all owned resources, including partial initialization and retries after failure. A successfully stopped worker can start again. Pause preserves resources and internal state; resume continues with them. If either operation fails, its implementation must undo partial changes while the base class restores Running or Paused. Implementations without pause/resume support expose CanPauseAndContinue = false.

DisposeAsync permanently disables the instance and cleans up through OnStopAsync, including instances that have never started. Concurrent disposal calls share the current attempt. Cleanup failures propagate; a later DisposeAsync retries cleanup, and successful disposal makes subsequent calls no-ops. Once disposal begins, new start, stop, pause and resume calls throw ObjectDisposedException; previously accepted operations finish their cleanup. IsDisposed indicates successful cleanup. Diagnostic properties and ToString remain readable. Notification failures do not undo completed cleanup. Canceling a stop waiter only ends that wait.

Lifecycle hooks and StateChanged handlers must complete their own work without waiting for lifecycle or disposal operations on the same worker. Callers are responsible for avoiding dependency cycles. The owner coordinates subsequent operations outside the callback after the current operation completes. Calls to other workers are supported when they do not create a dependency cycle. Callbacks may change Enabled; assigning it does not initiate a lifecycle operation. See WorkerCallbackTest for worker composition and sequential operations from background tasks.

start, stop, pause and resume commands await the corresponding asynchronous worker operation and forward command cancellation. Their --timeout option limits command waiting only: it defaults to five seconds, uses five seconds for non-positive values, and is capped at thirty seconds. Expiration raises TimeoutException without canceling the worker operation; its eventual result remains the worker's responsibility, and the command does not produce late completion output. Pause and resume ignore requests that do not apply to the current state. Completion hooks receive the command context, worker and timeout; the resume hook is WorkerResumeCommand.OnResumed.

ListenerBase<T> dispatches handler arguments without decoding bytes and does not own injected handlers. An absent handler is a no-op with cancellation checking. Parameterless HandlerBase<T> calls pass null parameters; explicitly supplied parameters retain their identity. Both IPacketizer interfaces define only Pack and Unpack: encode without flushing, leave incomplete input untouched, and advance input after successful decoding. Exact frame lengths and decoded-resource release belong to the transport implementation; Net supplies these through its packetizer base class.

Repository Layout

Zongsoft.Core/
  src/        Main library source code.
  test/       xUnit unit tests; test/integration contains separate OS input tests.
  samples/    Console samples for MemoryCache, Spooler, Superviser, and EventExchanger.
  benchmark/  BenchmarkDotNet benchmarks for reflection, data model helpers, and Spooler batching.

Build and Test

dotnet restore Zongsoft.Core.slnx
dotnet build Zongsoft.Core.slnx -c Release
dotnet test test/Zongsoft.Core.Tests.csproj -c Release

The repository also includes a Cake script:

dotnet cake build.cake --target=test --edition=Release

Samples

The samples directory contains small console applications that exercise real APIs from this package:

• memorycache

  MemoryCache, expiration scanning, limit handling, and terminal output.

• spooler

  Spooler<T> batching under high write volume.

• superviser

  Superviser, Supervisable, worker state reporting, and terminal commands.

• eventexchanger

  EventExchanger channels and application context integration.

License

Zongsoft.Core is released under the LGPL-3.0-or-later license.