CS-Script for Notepad++ — Quick Setup GuideCS-Script brings C# scripting into lightweight editors, and pairing it with Notepad++ gives you a fast, familiar environment for writing and running C# scripts without a full IDE. This guide walks through installing CS-Script, integrating it with Notepad++, configuring common workflows (run, debug-lite, and package references), and tips for a smooth scripting experience.
What is CS-Script and why use it with Notepad++?
CS-Script is a scripting system that lets you write C# code as scripts (.cs files) and run them quickly using a script engine. It supports using the full .NET runtime (or .NET Core/.NET 5+), referencing DLLs, and embedding directives inside scripts to control compilation and runtime. Notepad++ is a fast, extensible text editor on Windows with plugin support and configurable external tools, making it a convenient front end for editing and invoking CS-Script.
Benefits
- Fast edit-run cycle: No need to create a Visual Studio project for small utilities.
- Access to .NET libraries: Use System.* and third-party DLLs.
- Lightweight setup: Notepad++ + CS-Script uses less disk/CPU than full IDEs.
- Portable workflows: Scripts are plain text and easy to share.
Prerequisites
- Windows ⁄11 (or earlier Windows versions that support the required .NET runtime).
- Notepad++ (latest stable recommended).
- .NET runtime — choose based on which CS-Script variant you’ll use:
- For classic CS-Script targeting .NET Framework, install an appropriate .NET Framework (4.7.2 or newer recommended).
- For CS-Script.Core targeting .NET 6/7/8+, install the matching .NET runtime SDK or runtime.
- Internet access for downloading installers and NuGet packages when needed.
Step 1 — Install Notepad++
- Download Notepad++ from the official site and install it.
- Launch Notepad++ and optionally enable the Plugins Admin (should be present by default) to manage plugins later.
Step 2 — Install CS-Script
There are multiple ways to get CS-Script; choose the one matching your runtime preference.
Option A — Install CS-Script via installer (classic)
- Visit the CS-Script website/releases and download the installer for Windows.
- Run the installer; it will add cscs.exe (the CS-Script runner) to your PATH and register file associations.
Option B — Use CS-Script.Core (.NET 6+)
- Install the .NET SDK/runtime first.
- Download the CS-Script.Core package or use the NuGet/global tool if available:
- You can install as a global dotnet tool when supported: dotnet tool install –global csscript
- Or download the csscript.core.exe and place it in a folder included in PATH.
Confirm installation by opening Command Prompt or PowerShell and running:
cscs -version (or csscript -version / csscript.core -version depending on the binary). You should see the CS-Script version.
Step 3 — Create a basic C# script
Create a new file in Notepad++ and save it as Hello.cs with a simple script:
// Hello.cs using System; public class Script { public static void Main() { Console.WriteLine("Hello from CS-Script!"); } } Save the file. CS-Script conventions allow different entry points (Main, Run, or top-level statements on newer runtimes), but keeping a Main method is cross-compatible.
Step 4 — Configure Notepad++ to run CS-Script
Notepad++ can run external tools via the Run menu or via plugins like NppExec. Two common approaches:
Approach A — Run command via Notepad++ Run… menu (quick)
- With Hello.cs open, go to Run → Run…
- Enter a command that executes CS-Script with the current file. For example:
- For classic cscs:
cscs "$(FULL_CURRENT_PATH)" - For CS-Script.Core (csscript):
csscript "$(FULL_CURRENT_PATH)"
- Click Save…, give it a name like “Run CS-Script” and assign a keyboard shortcut (e.g., Ctrl+F5).
Approach B — Use NppExec plugin (more control)
- Install NppExec from Plugins Admin.
- Open Plugins → NppExec → Execute…
- Enter a script like:
npp_save cd $(CURRENT_DIRECTORY) csscript "$(FILE_NAME)"or
npp_save cd $(CURRENT_DIRECTORY) cscs "$(FILE_NAME)" - Save the NppExec script (e.g., “RunCS”), then assign to a menu item / shortcut via Plugins → NppExec → Advanced Options.
NppExec gives you a console window inside Notepad++, so you can see stdout/stderr and exit codes directly.
Step 5 — Passing arguments and capturing output
To pass arguments to your script when running from Notepad++, add them after the filename in the command:
-
Run menu:
csscript "$(FULL_CURRENT_PATH)" arg1 arg2 -
NppExec:
npp_save cd $(CURRENT_DIRECTORY) csscript "$(FILE_NAME)" $(INPUT)(You can type arguments at runtime if you script NppExec to prompt for input.)
For scripts that require interactive console input, run them in an external console to allow input (instead of the embedded NppExec console). Use a command that launches cmd.exe and keeps the console open, for example:
cmd /k csscript "$(FULL_CURRENT_PATH)" arg1 Step 6 — Referencing assemblies and NuGet packages
CS-Script supports assembly references through in-script directives:
-
Reference a local DLL:
//css_ref MyLibrary.dll -
Reference a NuGet package (CS-Script.Core supports NuGet resolution):
//nuget Newtonsoft.Json using Newtonsoft.Json;
If NuGet resolution isn’t automatic, you can restore packages manually and add references to the DLLs, or configure CS-Script to use a packages folder. For complex dependency scenarios, consider developing in a project-based environment, or using script precompilation.
Step 7 — Lightweight debugging and troubleshooting
CS-Script doesn’t offer full IDE debugging inside Notepad++, but you can use these techniques:
- Console logging: Use Console.WriteLine liberally and run via NppExec to view output.
- Exit codes: Return specific exit codes and inspect them in a calling batch or NppExec.
- Attach a debugger: Start the script with a small delay and attach Visual Studio or VS Code for debugging:
System.Diagnostics.Debugger.Launch(); // prompts to attach a debugger - Syntax checking: Use dotnet build or Roslyn analyzers if you want static checks; you can create a project for larger scripts and keep development in Notepad++ for small tasks.
Examples: Useful script snippets
Run a quick HTTP GET (requires System.Net.Http available on .NET Core/Framework):
// Fetch.cs using System; using System.Net.Http; using System.Threading.Tasks; public class Script { public static async Task Main() { using var http = new HttpClient(); var text = await http.GetStringAsync("https://example.com"); Console.WriteLine(text.Substring(0, Math.Min(200, text.Length))); } } Top-level statements (for newer runtimes):
// TopLevel.cs using System; Console.WriteLine("Top-level script running"); Tips and best practices
- Keep scripts small and single-purpose; move larger code into class libraries.
- Use in-script directives for references to keep scripts portable.
- Store frequently used runner commands as Notepad++ shortcuts or NppExec scripts.
- For repeatable builds or packaging, adopt a tiny project with dotnet CLI and use Notepad++ for quick edits.
- Remember to match CS-Script variant to your installed runtime (.NET Framework vs .NET Core/.NET 5+).
Troubleshooting checklist
- “Command not found” — ensure csscript/cscs is in PATH or use full path in Notepad++ command.
- Runtime mismatch errors — verify script targets the installed .NET runtime; install the correct runtime or use CS-Script.Core for newer .NET.
- Missing DLLs — add //css_ref lines or copy required DLLs to the script folder.
- Interactive input not working — run the script in an external console (cmd /k …).
Alternatives and when to switch
- Use Visual Studio or VS Code when you need full debugging, project management, and IntelliSense.
- Switch to ScriptCS (C# REPL style) or dotnet-script for alternative scripting experiences with different ecosystems and package handling.
CS-Script + Notepad++ is a pragmatic combination for quick automation tasks, learning, and lightweight development. With a few Notepad++ commands or an NppExec script, you can edit, run, and iterate on C# scripts quickly without launching a heavy IDE.
Leave a Reply