Adding C# scripting to your development arsenal - Part 1

Guest Post by Filip W

Welcome to our weekly MVP series where we discuss some of the most useful solutions, tips & tricks and how to’s on integrating OSS & Microsoft technologies. In case you have any questions, don’t hesitate and drop us a comment below or reach out to us via Twitter and Facebook! Enjoy!

For years, developers using popular dynamic languages such as JavaScript, Ruby or Python, have benefited from the ability of using their favorite language in a scripting context. This allowed them to apply their knowledge of the language and the overall ecosystem to scenarios way beyond "regular" application development - automation, quick experiments, API experimentation or batch tasks - just to name a few.

Through the new Roslyn compiler, scripting has also finally come to C#. While the sound of such concept - after all we are talking about scripting for a compiled, object oriented (class based) programming language - might sound counter intuitive, just bear with me for a moment, as we'll try to make sense of it in this article.

Background

C# scripting was introduced into .NET community together with the Roslyn CTP back in October 2011. The primary idea behind C# scripting was to allow for code to be dynamically evaluated at runtime. While there have been other technologies allowing that in the past (Reflection.Emit, CodeDOM etc.), Roslyn took this concept to new heights by introducing scripting - using not the regular strict C#, but a relaxed version of C# language semantics.

As Roslyn matured, in one of the later preview releases, the scripting bits were actually pulled from Roslyn altogether, as the Microsoft Language Team opted for a redesign of the scripting APIs. As a result, scripting didn't make it into the stable Roslyn 1.0.0 release (which was also the version that shipped with Visual Studio 2015). However, since then, scripting has made a return to Roslyn and is currently available on Nuget, in 1.1.0 version of Roslyn. It is also part of Visual Studio 2015 Update 1 - the stable version of which was released yesterday (30 November 2015).

Aside from the official Roslyn packages from Microsoft, the C# community has been enjoying a community-driven way of scripting with C# via a very popular scriptcs open source project for a few years now. scriptcs was built around the initial Roslyn CTP with the goal to provide excellent, rich experience for C# scripting - further enhancing the capabilities of Roslyn. It even introduced support for cross platform - Linux, OS X - C# scripting using Mono.CSharp. This is particularly useful, because Roslyn, while it has an ultimate goal of supporting x-plat scripting, even at this day, with the latest 1.1.0, only works on Windows.

What does it all mean in practice?

Well, C# scripting allows you to write C# code you know and love, but in a way that's much friendlier for non-Visual Studio usage.

Because scripted C# is characterized by looser syntax requirements, the overall experience can be really low-ceremony. Below are a few things to remember:
- the entry point to your script is the first line of your script (no mandatory Main method)
- any code allowed from the first line (no top level mandatory Program class)
- global functions allowed
- no namespaces
- no project or solution file
- your script can be entirely self-contained
- using statements and references can be imported implicitly by the hosting application (responsible for invoking the script)

Think about it for a second - because it is a very enticing idea - being able to author C# in any text editor (no need for Visual Studio), without having to worry about the heavy structures of solution and project files, build tasks, or traditional entry point constructs like "static void Main", holds tremendous power.

To get started with C# scripting, you can either install the Roslyn scripting package from Nuget or opt to use scriptcs instead.

Getting started with Roslyn scripting

You can grab the C# scripting package using the following Nuget installation command (there is also a corresponding one for Visual Basic scripting, Microsoft.CodeAnalysis.Scripting.VisualBasic):

1	Install-Package Microsoft.CodeAnalysis.Scripting.CSharp

This will add the Roslyn scripting libraries to your project and allow you to execute C# scripts from your application./p>

The simplest thing you can do is to use the static EvaluateAsync method of CSharpScript class. It allows you to quickly compile and invoke C# scripted code. For example:

1	await CSharpScript.EvaluateAsync("Console.WriteLine(\"Hello world!\")");

Of course your script code can be more elaborate - as mentioned earlier, you can define classes, loose methods and global variables. Moreover, your C# script can actually return a value to the hosting application if needed. The last line of your script, without a semicolon, is an instruction for Roslyn to evaluate an expression on that last line and return it. For example:

class Program{ static void Main(string[] args) { var script = @"int Add(int x, int y) { return x+y; } Add(1, 4)"; //note: we block here, because we are in Main method, normally we could await as scripting APIs are async var result = CSharpScript.EvaluateAsync<int>(script).Result; //result is now 5 Console.WriteLine(result); Console.ReadLine(); }}

In the above snippet, the last line is a call to the Add method (notice the lack of semicolon) - this means that this statement will be evaluated and the value returned to the host application, which conveniently captures it into result variable. This is a very easy way of marshaling the data back from the script.

If you want to do the opposite - that is, pass data into your script, you can do so using an instance of a so called globals object. This concept, also known as a host object, will expose all of the public members of the host class as ambient global properties and methods, that can simply be accessed anywhere in the script. Host object can be any type you wish, but it must itself be declared as public.

For example:

public class ScriptHost{ public int Number { get; set; }}class Program{ static void Main(string[] args) { var script = @"int Square(int number) { return number*number; } Square(Number)"; //note: we block here, because we are in Main method, normally we could await as scripting APIs are async var result = CSharpScript.EvaluateAsync<int>(script, null, new ScriptHost { Number = 5 }).Result; //result is now 25 Console.WriteLine(result); Console.ReadLine(); }}

In the snippet above, an instance of ScriptHost is used as host object, and therefore its property Number can be used inside the script to read the data (number 5) being passed in.

Finally, in a more advanced scenario, you can also pre-seed your script context with assembly references (this way your script will have access to types defined there) and using statements (this way your script will automatically have access to types from those namespaces without having to manually import them, of course as long as the relevant assembly is referenced too).

This is a great way to simplify your scripting experience. The following snippet adds a reference to System.Xml DLL from the GAC and imports the using statements for System.Xml in order to process an XML file (obviously that file has to exist on your machine in the first place - I just used a generic test file I had). This is controlled by the ScriptOptions object.

123456789

class Program{ static void Main(string[] args) { var scriptOptions = ScriptOptions.Default.AddReferences(typeof(XmlDocument).Assembly) .AddImports("System.Xml", "System"); var xmlScript = @"var xmlDoc = new XmlDocument(); xmlDoc.Load(""c:\\test\\report.xml""); Console.WriteLine(xmlDoc.InnerText); "; var result = CSharpScript.EvaluateAsync(xmlScript, scriptOptions).Result; Console.ReadLine(); }}

Notice that in the above example, both the XmlDocument and Console classes are available, because the relevant namespaces have been imported into the script context. Additionally, the XmlDocument is only resolved correctly, because a reference to its assembly (the aforementioned System.Xml DLL) was done.

Finally, there are two new extra feature worth mentioning, and these are new compiler directive, #load and #r. They are only allowed to be used in C# script code (would not work with "classic" C# syntax), and allow you to reference a script from another script ( #load) and import an assembly reference from GAC or from a path ( #r).

This is particularly useful for code sharing between files. Let's take our earlier example and extend it with a #load and #r sample:

class Program{ static void Main(string[] args) { var scriptOptions = ScriptOptions.Default.AddImports("System.Xml", "System"); var xmlScript = @"#r ""C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.6\System.Xml.dll"" #load ""c:\test\setup.csx"" var xmlDoc = new XmlDocument(); xmlDoc.Load(reportPath); Console.WriteLine(xmlDoc.InnerText); "; var result = CSharpScript.EvaluateAsync(xmlScript, scriptOptions).Result; Console.ReadLine(); }}

The above snippet is similar to the previous one, but we introduced a few changes. First of all, System.Xml is no longer referenced from the host application level, via ScriptOptions. Instead, the script itself is asking for the DLL to be referenced. The end result is the same as earlier, meaning that the assembly is available to be used in the script, but the responsibility of making that decision has been shifted.

Moreover, we actually replaced the path to the XML report file with a variable reportPath - and you might be wondering where is it coming from? Well, since at the second line, we load a C# script file from c:\test\setup.csx, that's a good bet to look. And indeed, whatever you declare in the #loaded script (variables, methods, classes) - all of that will be available in the other script. In our case, the setup.csx happened to be a one line CSX file:

1	var reportPath = @"c:\\test\\report.xml";

By the way, CSX is the C# script file extension convention.

REPL

In case you are wondering how all of this works under the hood, Roslyn will create a so called submission from your script code. A submission is an in memory assembly containing the types generated around your script code, which can be identified among the assemblies in the current AppDomain by a ℛ prefix in the name.

The precise implementation details are not important here (though, for example, scriptcs heavily relies on understanding in detail how Roslyn works to provide its extra features), but it's important to know that submissions can be chained together. When they are chained, variables, methods or classes defined in an earlier submission are available to use in subsequent submissions, creating a feature of a C# REPL (read-evaluate-print loop). The following example can illustrate how a super simple C# REPL could be built in a few lines of C# code:

class Program{ static void Main(string[] args) { ScriptState<object> scriptState = null; while (true) { Console.Write("* "); var input = Console.ReadLine(); scriptState = scriptState == null ? CSharpScript.RunAsync(input, ScriptOptions.Default.AddImports("System")).Result : scriptState.ContinueWithAsync(input).Result; } Console.ReadLine(); } }

In this very basic example, we enter into a forever loop, and create a null ScriptState variable. We then wait for user input. To initialize a C# REPL, we call CSharpScript.RunAsync and pass in user's input, which results in the user code being invoked and the script state being populated from this first submission. On subsequent runs, we call ContinueWithAsync method on the ScriptState itself, which will effectively result in new submissions being chained after the original one.

Here's a sample output from the above snippet:

 * using System; * var msg = "Hello";
* Console.WriteLine(msg);
Hello
* 

Going further

Now, this is all excellent and very exciting - but the biggest productivity gains from C# scripting probably do not involve calling C# script code from within your application.

Instead, what is likely of most value for us developers, is the ability to write that scripted C# as standalone CSX files, and rely on a stable, established script runner to run them, just like it's the case with all scripting languages. Sure, you could write such a runner yourself, but that would be an unnecessary overkill.

What you can do, is one of two things:

- install scriptcs, which has been the go-to community driven script runner for quite a while now (scriptcs installation instructions)
- install Visual Studio 2015 Update 1, which ships with CSI, a command line script runner which can be accessed from Visual Studio Developer Prompt (it's also located under C:\Program Files (x86)\MSBuild\14.0\Bin if you need to access the EXE directly)

They are both very powerful, and aside from being able to execute scripts, they also ship with built-in REPLs.
We'll look into using both in the next post of this series!

Comments

• Anonymous
  December 03, 2015
  If anyone else is getting an error message trying to do a: Install-Package Microsoft.CodeAnalysis.Scripting.CSharp I had to:

1. First do a Install-Package Microsoft.DiaSymReader.Native
2. add -Pre to Install-Package Microsoft.CodeAnalysis.Scripting.CSharp Hope this helps Mark

• Anonymous
  December 05, 2015
  It's not only dynamically typed languages that have REPLs. F#, OCaml and Haskell all had REPLs right from their inception.

• Anonymous
  December 06, 2015
  Install-Package Microsoft.CodeAnalysis.Scripting.CSharp should be Install-Package Microsoft.CodeAnalysis.CSharp.Scripting Looks like they changed the namespace ordering between 1.1.0-rc1 and 1.1.1

• Anonymous
  December 08, 2015
  I got an error on the first: Install-Package Microsoft.CodeAnalysis.Scripting.CSharp for me: Install-Package Microsoft.CodeAnalysis.Scripting worked

• Anonymous
  December 14, 2015
  Great post, thanks a lot! C# scripting is a great addition to "classic" C#

• Anonymous
  December 15, 2015
  Hi I'm unable to find the scripting package on NuGet for VB.NET.

• Anonymous
  December 18, 2015
  Waiting for Part 2!

• Anonymous
  March 30, 2016
  The comment has been removed

  • Anonymous
    March 31, 2016
    Found the problem. DLL not found.Br,Timo