Zongsoft.Core 7.65.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.

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. 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. Synchronous entry points block on the same asynchronous operations.

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 tests for core behaviors.
  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.