Zongsoft.Core 7.68.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. Password digests must use the iteration rules above.

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

Use ServiceCollectionExtension.Register to register services from an assembly. Public types annotated with [Service] participate in automatic registration; implement IServiceRegistration when an application needs custom registrations. Registration failures propagate to the caller.

Event Dispatch

Use RaiseAsync to raise events and await their handlers. Bound event handlers must return an awaitable result. EventExchanger supports transaction-aware delivery, and applications can add conditions through IFeatureProvider or configure 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. 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

Await StartAsync, StopAsync, PauseAsync and ResumeAsync on workers. Enabled controls whether startup is allowed; changing it does not stop an active worker. Check CanPauseAndContinue before requesting pause or resume. A successfully stopped worker can start again; a disposed worker cannot.

Use await using or await DisposeAsync for owned workers, listeners, queues, pollers and distributed locks. Container-owned services are released by their container. Await channel closure through CloseAsync; a closed channel cannot be reopened. Lifecycle callbacks must not wait for their own shutdown or disposal.

Read request responses with await foreach over IRequestToken.GetResponsesAsync. Await message confirmation through Message.AcknowledgeAsync; a completed handler does not automatically imply confirmation.

Worker commands accept --timeout to limit waiting. The default is five seconds, non-positive values use five seconds, and the maximum is thirty seconds. A timeout raises TimeoutException while the worker operation continues.

The Windows shell command waits for process exit and redirected output. Its timeout defaults to one second; non-positive values use thirty seconds. A timeout returns -1, and caller cancellation propagates. Neither terminates the launched process.

Repository Layout

Zongsoft.Core/
  src/               Main library source code.
  test/unit/         xUnit unit tests.
  test/integration/  Separate terminal input and process integration 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/unit/Zongsoft.Core.Tests.csproj -c Release

The repository also includes a Cake script:

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

The main solution and the default Cake target run only test/unit. Run integration tests explicitly:

dotnet test test/integration/Zongsoft.Core.Tests.slnx -c Release -p:GeneratePackageOnBuild=false
# Or: dotnet cake build.cake --target=integration-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.