Zongsoft.Commands 7.14.0

Zongsoft.Commands Command Plugin Library

English | 简体中文

Overview

Zongsoft.Commands packages commonly needed terminal commands for the Zongsoft command framework. It is useful for application diagnostics, maintenance scripts, interactive administration, and testing framework services without writing a dedicated user interface.

The package contributes commands through Zongsoft.Commands.plugin. After the plugin is loaded, they appear below /Workbench/Executor/Commands and can be invoked from a Zongsoft terminal host or through CommandExecutor.

Command Model

A command receives a parsed expression through a command context and returns a value asynchronously. The framework separates four concerns:

• Command tree: hierarchical names such as File Info or Messaging Queue Produce select a command node.
• Arguments and options: positional arguments carry input values; named options use forms such as --algorithm:SHA256.
• Pipeline value: the result of one command can become the input value of another command.
• Output: commands may return an object and may also write formatted content through ICommandOutlet.

See CommandExecutor, CommandContext, and CommandLine for the underlying public abstractions.

Installation and Deployment

dotnet add package Zongsoft.Commands

For a plugin application, deploy the package artifacts so that Zongsoft.Commands.plugin is placed in the host's plugins directory. The manifest depends on the framework's main plugin and registers the command tree automatically.

💡 The easiest interactive entry point is the Zongsoft terminal host. Use help after startup to inspect the commands actually loaded by the current application.

Quick Start

help
range --type:int --min:1 --max:5
checksum --algorithm:SHA256 "hello"
file.info ./appsettings.json
directory.list ./plugins

Application code can invoke the same tree after plugin initialization:

using Zongsoft.Components;

using var cancellation = new CancellationTokenSource(TimeSpan.FromSeconds(5));
var checksum = await CommandExecutor.Default.ExecuteAsync(
	"checksum --algorithm:SHA256 hello",
	cancellation: cancellation.Token);

🚨 CommandExecutor.Default only contains nodes registered by the current host. A successful package reference does not load Zongsoft.Commands.plugin; verify deployment when a command cannot be found.

Included Commands

Some commands require services supplied by other plugins. Scheduling, sequence, messaging, and virtual file-system commands resolve their providers from the running application.

Extending the Tree

Custom commands normally derive from CommandBase<CommandContext>, declare options with CommandOptionAttribute, and are mounted by a plugin manifest. Keep command bodies thin: validate terminal input, call an application service, and return a useful result rather than duplicating domain logic.

💡 Use a parent command node to group related operations. This keeps completion and help output discoverable while avoiding long flat command names.

Errors and Safety

• Invalid or missing options are reported as command option exceptions; do not silently substitute security-sensitive values.
• File deletion, key export, scheduling changes, and message publication can alter external state. Confirm the active host, environment, and provider before invoking them.
• Cancellation is propagated to asynchronous commands, but an external provider may already have accepted an operation.
• Avoid passing credentials directly in expressions because terminal history and diagnostic output may retain them.

Related Resources

• Core command abstractions
• Command plugin manifest
• Deployment manifest
• Plugin framework

Plugin-Based Integration

Compose this feature through the host; a package reference supplies compile-time APIs, while plugin loading also requires deployed manifests and runtime assets. See the complete plugin workflow.

The manifest mounts the command set at /Workbench/Executor/Commands. In a terminal host, verify help and echo hello; provider-dependent commands still require their corresponding plugins.

Add this fragment to an existing host .deploy (retain Main and the host’s other base manifests; do not replace the whole file):

[plugins zongsoft commands]
nuget:Zongsoft.Commands

Run dotnet deploy against a test deployment as explained in the workflow, with the host's framework, platform, architecture and, where needed, site. Pin compatible versions in real deployments; application dependencies such as databases, caches or commercial runtimes are still separate prerequisites.

Additional artifacts listed by the deployment manifest include Zongsoft.Commands.plugin. Retain assemblies, dependencies and satellite resource directories as well. Restart the host after deployment, check plugin loading and service/driver registration, then verify the workflow above; copied files alone do not prove that the feature is active.