API Reference
LiveSession
Single-use live renderer. Producers only enqueue; one background thread owns widget updates. Stop closes admission, joins that thread, drains accepted events and restores the terminal.
Inheritance
- Object
- LiveSession
Usage
Explore 9 API references to this type
This type appears in these public API surfaces even when no hand-authored example is attached directly to the page.
Returned or exposed by 4
- Property RunContext.Session
- Property LivePause.Session
- Property LiveSession.Current
- Property RunMonitor.Session
Accepted by parameters 5
- Method ConsoleExporter.ToHtml
- Method ConsoleExporter.ToSvg
- Method ConsoleExporter.ToText
- Method LiveSession.Run
- Method LiveSession.RunAsync
Constructors
public LiveSession(IWidget root, LiveSessionOptions? options = null) #Discovers targets in the widget tree. Definitions must remain stable after construction.
Parameters
- root ConsoleMonster.Layout.IWidget
- Dashboard root.
- options ConsoleMonster.Live.LiveSessionOptions? = null
- Optional configuration, fixed when Start is called.
Methods
public Void Dispose() #VoidPerforms application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
public LiveSessionCounters GetCounters() #LiveSessionCountersA snapshot of the session's counters, the target names that received updates but do not exist, and the errors, so hosts can report problems that would otherwise disappear behind the live screen.
Returns
The snapshot.
public Void Mark(String label) #VoidAdds a marker to the recording (a named point such as "Deploy started"), which Show-ConsoleReplay can jump to. Markers change nothing on screen; without a recording they are ignored.
Parameters
- label System.String
- The marker text.
public LivePause Pause() #LivePausePauses drawing so a prompt can take the screen (for example "Continue on errors?" during a run). Updates keep being applied while paused, so the dashboard is current when it comes back. Dispose the pause to resume; the next frame redraws everything.
Returns
The pause, with the last frame as the backdrop for an overlay.
public Void Post(LiveEvent liveEvent) #VoidEnqueues without locks or per-event signaling. Events may be queued before Start.
Parameters
- liveEvent ConsoleMonster.Live.LiveEvent
- Event; zero timestamps are stamped relative to Start.
public SlotHandle Region(String name) #SlotHandleA handle to the Slot named name: session.Region("main").Set(widget) replaces its content between frames, from any thread.
Parameters
- name System.String
- The slot name.
Returns
The handle.
Exceptions
ArgumentException– No slot has that name.
public Void Register(ILiveTarget target) #VoidRegisters an additional target, rejecting duplicate names and the reserved log alias.
Parameters
- target ConsoleMonster.Live.ILiveTarget
- Target to register.
public static Void Replay(IWidget root, TextReader jsonLines, LiveSessionOptions? options = null, Double speed = 1, CancellationToken ct = default) #VoidReplays events in order with scaled original timing, then drains and restores the session.
Parameters
- root ConsoleMonster.Layout.IWidget
- Target widget tree.
- jsonLines System.IO.TextReader
- Borrowed recording input.
- options ConsoleMonster.Live.LiveSessionOptions? = null
- Session options; ReplayDelay can supply a deterministic scheduler.
- speed System.Double = 1
- Playback multiplier; zero or negative disables waits.
- ct System.Threading.CancellationToken = default
- Playback cancellation.
public Void Run(Action<LiveSession> work) #VoidRuns work inside a session, restoring the terminal even when work throws.
Parameters
- work System.Action<ConsoleMonster.Live.LiveSession>
- Work to execute.
public async Task RunAsync(Func<LiveSession, CancellationToken, Task> work, CancellationToken ct = default) #TaskRuns asynchronous work with linked caller and session cancellation.
Parameters
- work System.Func<ConsoleMonster.Live.LiveSession, System.Threading.CancellationToken, System.Threading.Tasks.Task>
- Work to execute.
- ct System.Threading.CancellationToken = default
- Caller cancellation.
Returns
Completion, preserving work exceptions after restoration.
public IDisposable Scope(String target, String? key = null) #IDisposableBegins an ambient progress scope for this session.
Parameters
- target System.String
- Target name.
- key System.String? = null
- Optional item key.
Returns
The scope lifetime.
public CellBuffer? Snapshot() #CellBuffer?A copy of the last frame the session drew (for exports and screenshots), or null before the first frame and for line-based outputs that draw no frames. Safe to call from any thread.
Returns
The frame copy, or null.
public Void Start() #VoidStarts the dedicated background render thread. Repeated calls while running are harmless.
public Void Stop() #VoidStops admission, cancels work and joins for up to StopTimeout (two seconds by default). Accepted events are drained on the stopping caller after joining, before restoration. If user code blocks the render thread, console capture is restored immediately and final cleanup is deferred until that callback returns. A call from the render thread also defers final cleanup to its loop exit.
public static IDisposable SuspendCapture() #IDisposableUntil the returned scope is disposed, what the calling thread writes to Console.Out and Console.Error goes to the original streams instead of a live session's log. A host that hands a session's own output lines on through Console.Out (as PowerShell's console host does with redirected output) writes them inside this scope, so they are not captured, drawn and written again.
Returns
The scope; dispose it on the same thread.
public Boolean TryGetTarget(String name, out ILiveTarget? target) #BooleanLooks up a registered target, including the reserved log alias.
Parameters
- name System.String
- Target name.
- target ConsoleMonster.Live.ILiveTarget?
- Matching target, or null.
Returns
Whether the target exists.
public Void Write(String line, String level = "out") #VoidEnqueues a line for the session log target.
Parameters
- line System.String
- Text.
- level System.String = "out"
- Stream or severity, default out.
Inherited Methods
public virtual Boolean Equals(Object? obj) #BooleanParameters
- obj Object?
Properties
public static LiveSession? Current { get; } #The most recently started session that is still running, across all runspaces.
public CancellationToken Cancellation { get; } #Cancelled by Stop or the first intercepted Ctrl+C.
public Int64 Resizes { get; } #The number of size changes the session redrew for (coalesced: rapid drags count once per redraw).
public Int64 RenderErrors { get; } #Frames where the layout threw and a one-line note was shown instead (the session keeps running).
public String? WidthDecision { get; private set; } #The terminal width probe result for this session ("width probe (cursor report, 12 ms): ..."), the reason it was skipped, or null when probing was not applicable (Stream/Plain output, a borrowed output, or explicit width settings).
public TimeSpan Elapsed { get; } #Time since Start, frozen after shutdown. During LiveSession.Replay it follows the recorded timeline (real time multiplied by the replay speed), so the header clock agrees with recorded timestamps.
public Int64 EventsPosted { get; } #Number of events accepted before shutdown closed admission.
public Int64 EventsDropped { get; } #Number of events ignored because the target was unknown, or admission had closed.
public Int64 FramesRendered { get; } #Number of frames rendered, including the final frame.
public Exception? LastError { get; } #Most recent target, rendering, recording or cleanup exception.
public Exception? Failure { get; } #The exception that ended the session early (the render thread failed, for example on a broken output), or null.
public IReadOnlyCollection<String> TargetNames { get; } #A snapshot of registered target names.
public String? RecordingPath { get; private set; } #The automatic recording file of this session, or null.
Fields
public const String MarkerTarget #The reserved target of marker events (LiveSession.Mark): recorded for replay, shown nowhere.
$marker