XFEExtension.NetCore.XFEConsole 2.4.0

XFEExtension.NetCore.XFEConsole

🌐 English | 简体中文

Overview

XFEExtension.NetCore.XFEConsole is a debugging aid that allows remote console output. It is designed to work with the XFE Toolbox, but you can also build your own debugging tool based on the architecture provided in this library.

Installation

dotnet add package XFEExtension.NetCore.XFEConsole

Windows Terminal and Interactive Terminal APIs

These APIs live in XFEExtension.NetCore.XFEConsole.Terminal. The library distinguishes Windows Terminal, the legacy Windows console, other VT terminals, and redirected output. Modern-only operations degrade safely when unavailable.

Capability detection

using XFEExtension.NetCore.XFEConsole.Terminal;

XFETerminalCapabilities terminal = XFETerminal.Capabilities;
Console.WriteLine(terminal.Kind);
Console.WriteLine(terminal.SupportsTrueColor);
Console.WriteLine(terminal.SupportsTaskbarProgress);

terminal = XFETerminal.RefreshCapabilities(); // Also tries to enable Windows VT processing

Windows Terminal tab and taskbar progress

XFEConsole.SetTerminalProgress(XFETerminalProgressState.Normal, 50);
XFEConsole.SetTerminalProgress(XFETerminalProgressState.Warning, 75);
XFEConsole.SetTerminalProgress(XFETerminalProgressState.Indeterminate);
XFETerminal.ClearTaskbarProgress();

using var progress = XFEConsole.CreateTerminalProgressBar(new XFETerminalProgressBarOptions
{
    Width = 36,
    Prefix = "Building ",
    UseTaskbarProgress = true
});
progress.Report(0.5, "step 50/100");

The inline progress bar remains usable in legacy terminals. OSC 9;4 taskbar progress is emitted only in Windows Terminal.

VT controls and Windows Terminal integration

XFETerminalSequences builds reusable strings, while XFETerminal.WriteRaw sends them to the local terminal:

var style = new XFETerminalStyle
{
    Foreground = XFETerminalColor.FromRgb(70, 190, 255),
    Background = XFETerminalColor.FromIndex(236),
    Bold = true
};

XFETerminal.WriteRaw(
    XFETerminalSequences.CursorPosition(5, 10) +
    style.Apply("24-bit color"));

XFETerminal.SetTitle("Building");
XFETerminal.WriteHyperlink("Project", new Uri("https://github.com/XFEstudio"));
XFETerminal.SetWorkingDirectory(Environment.CurrentDirectory);

The sequence API covers relative/absolute cursor movement, save/restore, cursor visibility and shape, erase operations, character/line insertion and deletion, scrolling and margins, wrapping, alternate screen, 16/256/24-bit colors, palette updates, OSC 8 hyperlinks, OSC 9;4 progress, OSC 9;9 working directory, OSC 133 command marks, bracketed paste, focus and SGR mouse reporting, device/cursor queries, soft reset, and explicit OSC 52 clipboard sequence generation.

Full-screen canvas and game loop

The canvas uses zero-based coordinates and VT differential rendering. Legacy Windows consoles fall back to the Console cursor/color APIs. Terminal state is restored on completion, cancellation, or exception.

await XFETerminalGame.RunAsync((game, cancellationToken) =>
{
    if (game.IsKeyPressed(ConsoleKey.LeftArrow))  playerX--;
    if (game.IsKeyPressed(ConsoleKey.RightArrow)) playerX++;

    game.Canvas.Clear();
    game.Canvas.DrawBox(0, 0, game.Canvas.Width, game.Canvas.Height,
        XFETerminalBoxStyle.Rounded);
    game.Canvas.Set(playerX, playerY, '@', new XFETerminalStyle
    {
        Foreground = XFETerminalColor.Red,
        Bold = true
    });
    return ValueTask.CompletedTask;
}, new XFETerminalGameOptions
{
    FramesPerSecond = 30,
    CaptureMouse = true,
    ExitKey = ConsoleKey.Escape
});

For custom loops, compose XFETerminalSession, XFETerminalCanvas, and XFETerminalInputReader. Input events include key up/down and modifiers, mouse buttons/movement/double-click/wheels, and window resizing.

Colored title art

Seven styles are built in (Block, Compact, Dots, Outline, Shadow, Slant, and Framed) together with cyan, rainbow, ocean, sunset, forest, fire, and neon palettes. Bitmap styles cover A-Z, 0-9, and common punctuation. Other Unicode text automatically uses a frame so that CJK and emoji are preserved.

string plain = XFETerminalTitleArt.GeneratePlain(
    "XFE",
    XFETerminalArtStyle.Shadow,
    XFETerminalCompatibility.Legacy);

string terminalReady = XFEConsole.GenerateTitleArt("XFE", new XFETerminalTitleArtOptions
{
    Style = XFETerminalArtStyle.Outline,
    Palette = XFETerminalArtPalette.Rainbow
});

XFEConsole.WriteTitleArt("XFE", new XFETerminalTitleArtOptions
{
    Style = XFETerminalArtStyle.Block,
    Palette = XFETerminalArtPalette.Ocean,
    Compatibility = XFETerminalCompatibility.Auto
});

Modern mode uses Unicode drawing characters and ANSI true color. Legacy mode returns clean ASCII and uses ConsoleColor when writing directly.

Run the feature demos and deterministic checks with:

dotnet run --project XFEExtension.NetCore.XFEConsole.Test -- self-test
dotnet run --project XFEExtension.NetCore.XFEConsole.Test -- game

Protocol references: Windows Console VT sequences, Windows Terminal progress, and Windows Terminal shell integration.

Remote Console

Connect to the Remote Console

// Connect to a local console debug terminal on the given port (port and password are optional)
bool connected = await XFEConsole.UseXFEConsole(port: 3280, password: "");

// Connect to a remote console debug terminal at a specific IP address
bool connected = await XFEConsole.UseXFEConsole("ws://192.168.1.100:3280/", "MyApp", Guid.NewGuid().ToString(), "password");

Once connected, all Console.WriteLine and Console.Write output is automatically forwarded to the remote console.

Properties

XFEConsole.ShowInDebug = true;          // Show output in local Debug; default is true
XFEConsole.UseConsoleColor = true;      // Use console colors; default is true
XFEConsole.ShowInLocalConsole = true;   // Show output in local console; default is true
XFEConsole.AutoAnalyzeObject = true;    // Auto-analyze objects instead of calling .ToString(); default is true

Stop the XFE Console

await XFEConsole.StopXFEConsole();      // Close all remote connections and restore the original console output

Connect Only (without redirecting output)

// Establish a connection without modifying Console's output stream
bool connected = await XFEConsole.ConnectConsole("ws://localhost:3280/", "MyApp", Guid.NewGuid().ToString(), "");

Direct Write Methods

XFEConsole.WriteLine("Hello World!");              // Synchronous write line
XFEConsole.Write("Hello ");                        // Synchronous write (no newline)
await XFEConsole.WriteLineAsync("Hello World!");   // Asynchronous write line
await XFEConsole.WriteAsync("Hello ");             // Asynchronous write (no newline)

Output Object Information

await XFEConsole.WriteObject(myObject);                                         // Output object details
await XFEConsole.WriteObject(myObject, onlyProperty: true, onlyPublic: true);  // Only public properties
await XFEConsole.WriteObject(myObject, remarkName: "User Object");              // Custom remark name

Use with XUnit Test Framework

class Program
{
    [UseXFEConsole]          // Use default port 3280
    [UseXFEConsole(3280)]    // Or specify the port explicitly
    [SMTest]
    static void TestMethod()
    {
        Console.WriteLine("Output via XUnit framework");
    }
}

Logging

Enable Logging

// Enable logging with default settings (file log, timestamps enabled)
XFEConsole.UseXFEConsoleLog();

// Configure with an Action builder
XFEConsole.UseXFEConsoleLog(options =>
{
    options.LogType = LogType.MemoryLog;        // Use in-memory log (default: FileLog)
    options.AutoApplyTimeInfo = true;           // Automatically include timestamps (default: true)
    options.UseAnsiConsoleEncoding = true;      // Enable ANSI encoding (default: true)
    options.LogTextMaximizeLength = 1024 * 10;  // Max log length; -1 = unlimited (default: -1)
});

// Or pass an options object directly
var logOptions = new XFEConsoleLogOptions
{
    LogType = LogType.FileLog,
    AutoApplyTimeInfo = true
};
XFEConsole.UseXFEConsoleLog(logOptions);

Write Logs

Console.WriteLine("Hello World!");       // Recorded directly in the log

Console.Write("Hello");                  // Buffered until the next WriteLine
Console.WriteLine(" World!");            // Now "Hello World!" is recorded

Console.WriteLine("[DEBUG]This is a debug message");                // Logged at DEBUG level
Console.WriteLine("[INFO]This is an info message");                 // Logged at INFO level
Console.WriteLine("[TRACE]Throw at Main() on line:24 position:25"); // Logged at TRACE level
Console.WriteLine("[WARN]Low memory warning");                      // Logged at WARN level
Console.WriteLine("[ERROR]Exception thrown");                       // Logged at ERROR level
Console.WriteLine("[FATAL]Application crashed... unknown reason");  // Logged at FATAL level

Configure Log Path

XFEConsole.Log.LogPath = "my-app.log";  // Set the log file path (file log only)

Export, Import, and Clear Logs

string logText  = XFEConsole.Log.Export();                              // Export all logs as text
string rangeLog = XFEConsole.Log.Export(DateTime.Today, DateTime.Now); // Export by date range
string original = XFEConsole.Log.ExportOriginal();                      // Export raw logs (no escaping)

XFEConsole.Log.Import(logText);                                         // Import log text
XFEConsole.Log.Clear();                                                 // Clear all logs