C# Scripts

When to Use

• Testing a C# concept, API, or language feature with a quick one-file program
• Prototyping logic before integrating it into a larger project

When Not to Use

• The user needs a full project with multiple files or project references
• The user is working inside an existing .NET solution and wants to add code there
• The program is too large or complex for a single file

Inputs

Workflow

Step 1: Check the .NET SDK version

dotnet --version

Step 2: Write the script file

.cs

.csproj

// hello.cs
Console.WriteLine("Hello from a C# script!");

var numbers = new[] { 1, 2, 3, 4, 5 };
Console.WriteLine($"Sum: {numbers.Sum()}");

• Use top-level statements (no

  Main

  method, class, or namespace boilerplate)
• Place

  using

  directives at the top of the file
• Place type declarations (classes, records, enums) after all top-level statements

Step 3: Run the script

dotnet hello.cs

--

dotnet hello.cs -- arg1 arg2 "multi word arg"

Step 4: Add NuGet packages (if needed)

#:package

#:package Humanizer@2.14.1

using Humanizer;

Console.WriteLine("hello world".Titleize());

Step 5: Clean up

dotnet clean hello.cs

Unix shebang support

.cs

1. Add a shebang as the first line of the file:
   csharp

   #!/usr/bin/env dotnet
   Console.WriteLine("I'm executable!");

2. Set execute permissions:
   bash

   chmod +x hello.cs

3. Run directly:
   bash

   ./hello.cs

LF

CRLF

Source-generated JSON

JsonSerializer.Serialize<T>(value)

using System.Text.Json;
using System.Text.Json.Serialization;

var person = new Person("Alice", 30);
var json = JsonSerializer.Serialize(person, AppJsonContext.Default.Person);
Console.WriteLine(json);

var deserialized = JsonSerializer.Deserialize(json, AppJsonContext.Default.Person);
Console.WriteLine($"Name: {deserialized!.Name}, Age: {deserialized.Age}");

record Person(string Name, int Age);

[JsonSerializable(typeof(Person))]
partial class AppJsonContext : JsonSerializerContext;

Converting to a project

dotnet project convert hello.cs

Fallback for .NET 9 and earlier

mkdir -p /tmp/csharp-script && cd /tmp/csharp-script
dotnet new console -o . --force

Program.cs

dotnet run

dotnet add package <name>

Validation

• dotnet --version

  reports 10.0 or later (or fallback path is used)
• The script compiles without errors (can be checked explicitly with

  dotnet build <file>.cs

  )

• dotnet <file>.cs

  produces the expected output
• Script file and cached artifacts are cleaned up after the session

Common Pitfalls

.cs

.csproj

dotnet run --file file.cs

#:package

#:package PackageName@1.2.3

@*

JsonSerializerContext

global.json

Directory.Build.props

Directory.Build.targets

nuget.config

More info