Consoul / docs 3.0.0 GitHub
Historical prerelease notes. See the current 3.0.0 release notes.

Consoul 3.0.0-preview.1

These are the prepared release notes for the first 3.0 preview. The packages and Git tag require publication separately. The preview is intended for early integration feedback; API and rendering behavior may change before a stable 3.0 release.

What is included

  • Separate optional packages. Core views, prompts, visuals, and routines remain in Consoul. Logging, configuration-provider support, JSON integration, and the command-line runner have their own packages.
  • Model-backed views. DynamicView<TModel> supports model sections, conditional sections and actions, navigation, help, shortcuts, command palettes, and generated form editing.
  • Typed input. Text, confirmation, secret, single-selection, and multi-selection prompts return explicit result objects, with validation, cancellation, and configurable feedback.
  • Composable rendering. Tables, panels, trees, rows, columns, grids, layouts, charts, calendars, canvases, and other widgets share capture, markup, theme, and color helpers. Builders add familiar Spectre-style syntax while keeping Consoul’s rendering model.
  • Long-running work displays. Progress tasks, status, spinners, and live displays can render through the same console facade and capture facilities.
  • Command-line applications. Consoul.Cli adds typed settings, command branches, aliases, help, completion metadata, and commands that launch Consoul views.
  • Testable console output. AnsiConsole.Create(...), writer-backed consoles, terminal profiles, and capture allow applications to inspect output without requiring an interactive console.
  • Redirected input handling. Reads preserve multibyte UTF-8 text and the final unterminated line. EOF ends prompts as cancellation instead of accepting defaults or retrying forever; a real blank line retains its normal meaning.

The core README and optional package guides contain usage examples.

Breaking changes to review

The logging provider types moved from the core assembly to Consoul.Extensions.Logging. Core no longer supplies Microsoft.Extensions.* dependencies transitively. Routines.getAppSettings() returns RoutineSettingsSection, and the configuration argument of Routines.InitializeRoutine(...) is now object rather than IConfigurationRoot. Rebuild consumers and follow the migration guide.

Consoul.Text.Json is an opt-in serializer/rendering integration. Enable UseSystemTextJsonForFormValues(...) when form value output should follow System.Text.Json. Legacy form serializer aliases remain available.

Consoul.Read() now distinguishes EOF (null) from a blank line (string.Empty). Update read/retry loops to handle null, and check prompt result cancellation before acting on a value. The input migration notes cover legacy helper return values.

Install the preview

Once the package is available on the selected source:

dotnet add package Consoul --version 3.0.0-preview.1

Use the same version for optional Consoul packages. See NuGet setup for package-source authentication, local package testing, and release preparation. Installing without an explicit prerelease version can select the existing stable release instead.

Known limitations

  • Unicode display widths. Several renderers measure UTF-16 character count instead of terminal display cells. Wide CJK characters, combining marks, and emoji can misalign; clipping can split a surrogate pair. UTF-8 input decoding does not fix this layout limitation. Prefer single-cell labels when exact alignment is needed.
  • Compatibility is scoped. Spectre-style names adapt common snippets to Consoul. They are not a full implementation of Spectre.Console; result types, single-line table cells, and some border presets differ.
  • Global rendering state. Static console, theme, and render options share process-wide state. Coordinate output and scoped changes in your application; independent concurrent views are not an isolation boundary.
  • Target frameworks are not a test matrix. Core packages contain netstandard2.0, netcoreapp3.1, and net461 assets; optional packages target netstandard2.0. Building these assets alone does not verify every operating system, terminal, or runtime combination. Exercise the actual environment your app supports.

Report feedback

Open a GitHub issue with the package version, target framework, operating system, terminal name, redirection state, and a minimal code example. For rendering defects, include terminal width and the text that fails. For a migration issue, include the previous package version and the compiler/runtime error.