Skip to content

README_BODY.md

Latest commit

 

History

History
173 lines (119 loc) · 8.65 KB

README_BODY.md

File metadata and controls

173 lines (119 loc) · 8.65 KB

Build automation system for .NET

NuGet csi GitHub GitHub Build

C# interactive build automation system makes it easy to build .NET projects. It can be part of your solution as a regular .NET console project or run C# scripts without compiling them, or even run in REPL mode - allowing you to run C# interactively.

Key Features

✔️ Three Integrated Execution Modes

  • Flexible interoperability between modes (#operating-modes) to adapt to diverse workflow requirements.

✔️ Native Cross-Platform Support

  • Seamlessly operates on Windows, Linux, and macOS without compatibility compromises.

✔️ Integrated Debugging Capabilities

  • Debug ".NET build projects" directly to identify and resolve issues during compilation and builds.

✔️ Zero Abstraction Overhead

  • Eliminates restrictive constructs (e.g., Tasks/Targets):
  • Pure .NET codebase – no proprietary syntax or hidden layers
  • Industry-standard practices ensure long-term maintainability

✔️ Granular Build Control API

  • Precise management of builds, tests, and deployments with streamlined project configuration.

✔️ Consolidated Build Analytics

  • Actionable insights through summarized statistics.

Operating modes

.NET build project

Seamless integration into existing solutions as a standard .NET console project.

Typical .NET console project

  1. Create the Project
    Initialize a new console application using .NET CLI:
dotnet new console -n MyBuildApp
cd MyConsoleApp
  1. Add a reference to the Build automation library for .NET
    Add the CSharpInteractive NuGet package for scripting capabilities:
dotnet add package CSharpInteractive

Creating a Build Automation Project from the build template

  1. Install the Template
    First, install the CSharpInteractive.Templates NuGet package as a dotnet template:
dotnet new install CSharpInteractive.Templates

Detailed installation guide

  1. Generate the Project
    Create a new project named Build using the template:
dotnet new build -o ./Build

Dual Execution Modes

The generated project supports two run methods:

  • Compiled Application (via Program.cs): 
    dotnet run --project ./Build
  • Script Execution (via Program.csx): 
    dotnet csi ./Build
Running C# script

Direct execution of C# scripts without prior compilation:

  • Zero-Compilation Workflow - execute .csx files directly using Roslyn scripting engines, bypassing traditional dotnet build steps for rapid iteration.
  • Cross-Platform Scripting
    • Windows - integrate with PowerShell/PowerShell Core automation pipelines
    • Linux/macOS - combine with bash/zsh scripts via shebang directives (#!/usr/bin/env dotnet-script)
    • Dependency Management - resolve NuGet packages in scripts via #r "nuget: PackageName/Version" syntax, with local cache optimization.

Run a specified script with a given argument:

dotnet csi ./MyDirectory/hello.csx World

Run a single script located in the MyDirectory directory:

dotnet csi ./MyDirectory World
Usage details 
dotnet csi [options] [--] [script] [script arguments]

Executes a script if specified, otherwise launches an interactive REPL (Read Eval Print Loop).

-- - Indicates that the remaining arguments should not be treated as options.

script - The path to the script file to run. If no such file is found, the command will treat it as a directory and look for a single script file inside that directory.

script arguments - Script arguments are accessible in a script via the global list Args[index] by an argument index.

@file - Read the response file for more options.

Supported options:

Option Description Alternative form
--help Show how to use the command. /?, -h, /h, /help
--version Display the tool version. /version
--source Specify the NuGet package source to use. Supported formats: URL, or a UNC directory path. -s, /s, /source
--property <key=value> Define a key-value pair(s) for the script properties called Props, which is accessible in scripts. -p, /property, /p
--property:<key=value> Define a key-value pair(s) in MSBuild style for the script properties called Props, which is accessible in scripts. -p:<key=value>, /property:<key=value>, /p:<key=value>, --property:key1=val1;key2=val2
Interactive

REPL (Read-Eval-Print-Loop) interface for interactive code evaluation. Please see this page for installation details.

Launch the tool in the interactive mode:

dotnet csi

Simply enter C# commands sequentially one line after another and get the result in console output.

NuGet packages

Package name Link Description Installation
dotnet-csi NuGet C# script runner and REPL tool for build automation dotnet tool install --global dotnet-csi
CSharpInteractive NuGet Build automation library for .NET dotnet add package CSharpInteractive
CSharpInteractive.Templates NuGet Build automation project templates for .NET dotnet new install CSharpInteractive.Templates

Usage examples