Codebelt
v11.0.100

C# Example & Test Runner

Run C# examples and xUnit tests in an isolated Docker container or your normal environment through the same engine.

Build and Delivery C# console and xUnit runner 2,209 pulls 0 stars Updated 2026-11-18

What it is

C# Example & Test Runner (csrun) runs a complete C# console program or genuine xUnit v3 tests with one command. Use native PowerShell when you want to work with your installed .NET environment, or send the same JSON manifest to a disposable Linux container when you want the toolchain and generated files isolated from your host.

Both paths use the same csrun engine and version 1 manifest contract. Console examples run as file-based applications without creating a console project. Test examples run through the actual xUnit v3 engine and Microsoft.Testing.Platform in a temporary executable project, which csrun removes after execution, including compilation errors and failed tests. Forced termination can prevent cleanup.

Why choose it

Use csrun to try a library example, check a pinned NuGet dependency, or verify an assertion without creating and maintaining a project just for that experiment. Supply a complete runnable program or test source; csrun does not wrap methods, discover packages, rewrite source, install SDKs, or silently change the requested framework.

Docker supplies an explicitly selected SDK environment and keeps generated source, projects, package caches, and build artifacts inside the container. Native execution fits a development session that already has the required SDK and runtime. Choose the environment that fits the task while keeping the program and package pins the same.

Run in an isolated Docker environment

Docker execution requires a Docker engine running Linux containers. The image includes PowerShell and its selected .NET SDKs, so the host does not need .NET installed. Docker Desktop on Windows can run the PowerShell examples below. Other shells can use the same container interface by sending UTF-8 JSON to stdin.

# Console example: prints 42.
@{
    schemaVersion = 1
    mode = 'console'
    framework = 'net10.0'
    source = 'Console.WriteLine(42);'
} | ConvertTo-Json | docker run --rm -i codebeltnet/csrun:10
$LASTEXITCODE

# Real xUnit discovery and execution: one passing test.
$testSource = @'
using Xunit;

public class SmokeTest
{
    [Fact]
    public void Pass() => Assert.True(true);
}
'@

@{
    schemaVersion = 1
    mode = 'test'
    framework = 'net10.0'
    source = $testSource
} | ConvertTo-Json | docker run --rm -i codebeltnet/csrun:10
$LASTEXITCODE

-i keeps stdin open for the manifest; a TTY is unnecessary. No clone, host file, volume mount, clipboard access, or profile customization is needed. The image runs as the unprivileged app user and bundles the csrun engine rather than downloading it at startup. Network access remains necessary for release metadata and uncached NuGet dependencies.

With --rm, container-owned source, temporary projects, NuGet caches, and build artifacts disappear when the container exits. The Docker image itself stays cached locally; this does not provide a persistent NuGet cache between runs. No host directories, credentials, environment variables, or Docker socket are passed automatically.

Select an SDK environment

Image tag Included SDK environment Manifest target
codebeltnet/csrun:10 .NET 10 net10.0
codebeltnet/csrun:11 .NET 11 net11.0
codebeltnet/csrun:10-11 .NET 10 and .NET 11 Either installed target

Tags describe SDK environments, independently of the csrun engine release and manifest schema. Always specify a compatible framework for a single-SDK image: an omitted framework selects the highest supported GA LTS, which can be absent from the chosen image. csrun fails rather than substituting a target or installing a missing runtime.

All SDK tags are mutable. Docker pulls a missing image automatically, but updating a cached image requires an explicit pull, such as docker pull codebeltnet/csrun:10. Use a published image digest when you need an immutable image identity. Package and framework pins alone do not freeze transitive dependencies, NuGet configuration, platform behavior, or external services.

Apply tighter container restrictions

For an isolated run with a read-only root filesystem and explicit resource limits, provide executable writable temporary storage:

@{
    schemaVersion = 1
    mode = 'console'
    framework = 'net10.0'
    source = 'Console.WriteLine(42);'
} | ConvertTo-Json | docker run --rm -i `
    --read-only `
    --tmpfs /tmp:rw,exec,nosuid,nodev,size=1g,mode=1777 `
    --cap-drop=ALL --security-opt=no-new-privileges `
    --cpus=2 --memory=2g --pids-limit=256 `
    codebeltnet/csrun:10

The image places its working directory, user state, caches, and temporary builds under /tmp. Keep that storage executable because compiled programs and tests must run there, and adjust limits for larger examples. Docker provides meaningful isolation but does not make arbitrary hostile code safe. Outbound network access remains enabled. Avoid privileged mode, host namespaces, Docker socket mounts, and unnecessary host mounts or credential forwarding.

Run in your normal environment

Native execution requires PowerShell 7 and an installed .NET 10+ SDK supporting file-based applications and the requested target. The corresponding runtime and any required ASP.NET shared framework must also be installed. SDK selection follows applicable global.json configuration. Network access is needed for Microsoft release metadata and uncached NuGet dependencies.

The README's copy-and-run command downloads the latest published script and invokes it with a source argument:

$scriptUrl = 'https://github.com/codebeltnet/csrun/releases/latest/download/csrun.ps1'
& ([scriptblock]::Create((irm $scriptUrl))) -Source 'Console.WriteLine(42);'
$LASTEXITCODE

This executes with your current permissions. Trust and review the script publisher, C# source, and NuGet dependencies, including their build assets. Native execution provides no sandbox.

For repeated use, download and review csrun.ps1 from the GitHub releases, then invoke the local script. The file examples below assume you have saved your own complete program and test source in the named files:

./csrun.ps1 -Source 'Console.WriteLine(42);'
./csrun.ps1 -Mode console -Framework net10.0 `
    -File ./Example.cs -DependsOn Cuemon.Kernel@11.0.0
./csrun.ps1 -Mode test -Framework net10.0 -File ./ExampleTest.cs

# Copy a complete runnable C# program before using the clipboard input.
./csrun.ps1 -Clipboard
Get-Help ./csrun.ps1 -Detailed

Direct options default to console mode, the highest supported generally available LTS framework, and no packages. Without an explicit source input, csrun reads the clipboard and fails if it is empty or unavailable. -Source, -File, and -Clipboard are mutually exclusive. Pass multiple -DependsOn values as a PowerShell array from PowerShell; native pwsh -File does not bind comma-separated strings as arrays.

Use the same manifest in either environment

A manifest records the execution mode, complete source, target framework, and exact package versions. This example prints the number of days between two dates using Cuemon:

$source = @'
using System;
using Cuemon;

var start = new DateTime(2018, 1, 1);
var end = new DateTime(2018, 10, 1);
Console.WriteLine(new DateSpan(start, end).TotalDays);
'@

$manifest = @{
    schemaVersion = 1
    mode = 'console'
    framework = 'net10.0'
    dependsOn = @('Cuemon.Kernel@11.0.0')
    source = $source
} | ConvertTo-Json

# Your installed PowerShell and .NET environment.
./csrun.ps1 -ManifestJson $manifest

# An isolated Linux environment with its own PowerShell and .NET SDK.
$manifest | docker run --rm -i codebeltnet/csrun:10

schemaVersion, mode, and nonempty source are required. framework is optional, but specifying it explicitly keeps the target clear when selecting a Docker image. dependsOn accepts exact PackageId@Version pins, including prereleases; ranges, wildcards, unversioned packages, and conflicting pins fail. Unknown manifest fields also fail. -ManifestJson cannot be combined with direct configuration or source-input options. The upstream README documents the full contract, including explicit SDK and framework references.

Test output and exit status

Test mode uses xUnit v3 with Microsoft.Testing.Platform and live test output; its default engine package is xunit.v3@4.0.3. csrun preserves child stdout, stderr, and exit status in both environments. Failed assertions return 2, no discovered tests return 8, and validation or prerequisite failures return 1. Inspect $LASTEXITCODE after a PowerShell invocation or Docker run, and treat nonzero results as failures in automation.

For current script options, supported engine versions, and container details, consult the csrun README and Docker Hub tags.