.NET 6 SDK

Running C# scripts is dependent on the installation of the Microsoft .NET 6.0 SDK. See the article titled .NET Prerequisites and Installation for more information.

Script Host Choices

There are two techniques available to run C# scripts from the command line:

• rcsx.exe
  A customised command provided by Red Centre Software for running scripts that call the Carbon API.
• dotnet-script
  An integrated tool published by .NET contributors that runs any scripts.

Each of the commands acts as a script host and they are discussed in the following sections. The commands are independent and either can be used according to developer preference or company policy.

rcsx.exe

Red Centre Software provides the command line utility rcsx.exe to run C# scripts that call the Carbon API. The command is provided as part of the standard installation folders and is customised for the processing scripts that call the Carbon API with the following special behaviour.

• #r and #load statements in the script are adjusted to have correct relative paths in the standard distribution path which defaults to C:\RedCentre.
• using statements for common namespaces are inserted into the script.
• The Carbon NuGet packages available from nuget.org are not used. All references to Carbon libraries and their dependencies are hard-coded as paths to the C:\RedCentre\Apps folder.

For a technical discussion of rcsx see Appendix 6 in the Carbon Scripting PDF.

A wide variety of sample scripts for rcsx can be found under the C:\RedCentre distribution folder. Most scripts use #load statements to reuse boilerplate code for authentication, job open, etc, thereby making #r and using statements unnecessary in the top-level script files.

dotnet-script

The dotnet-script tool runs C# scripts in an agnostic way, it is not customised for any specific application, including Carbon. dotnet-script simply runs the scripts passed to it without any interpretation or modification. Example scripts for dotnet-script that call the Carbon API can be found in the public GitHub repository Carbon.Example.Script-csx. The project page and scripts contain comments about what they are doing and how they work.

The dotnet-script tool is not a standard part of the .NET runtime. The following command will download, install and register dotnet-script as a global .NET tool for the current user login account.

> dotnet tool install -g dotnet-script 

C# script files normally have the .csx extension and are run using a command like this example:

> dotnet-script Monthly-Report.csx

Script Host Comparison

This section provides examples of scripts that are suitable for running by dotnet-script and rcsx and it illustrates the differences between the scripts.

rcsx.exe

#load "..\startup.csx"

if (!SetJobDir(@"\RedCentre\Jobs\Demo")) return;
var ret = eng.GenTab("test", "gender(cwf;*)", "region(cwf;*)", "", "", sprops, dprops);
Console.WriteLine(ret);

The #load statement brings in 35 lines of code that creates the Carbon engine, issues a login request, creates common objects and includes a method to open a job. The rcsx command silently inserts all the required #r and using statements. By design, rcsx tries to reduce the amount of code required by making the assumption that all scripts have a similar usage pattern.

Developers may need to become familar with the contents of the supplied and loaded files to understand what pre-processing they perform and what methods they make available.

It's important to note that scripts run via rcsx are bound to a specific version of Carbon that is distributed in the standard C:\RedCentre\App distribution folder. Attempts to use #r nuget to load different versions of Carbon will produce runtime errors.

dotnet-script

The equivalent script for dotnet-script follows. Note the script is necessarily longer because no #load statements are used and you are seeing the plain code. It is of course possible to use #load to factor common code out of many repetitive scripts, but that is not illustrated here and is left as an exercise for script developers.

#r "nuget:RCS.Carbon.Tables, 8.3.14"

using RCS.Carbon.Tables;
using RCS.Carbon.Shared;

var eng = new CrossTabEngine();
await eng.LoginId("16499372", "C6H12O6");
eng.OpenJob(@"\RedCentre\Jobs\Demo");
var sprops = new XSpecProperties();
var dprops = new XDisplayProperties();
dprops.Output.Format = XOutputFormat.TSV;
dprops.Cells.Frequencies.Visible = true;
dprops.Cells.ColumnPercents.Visible = true;
var ret = eng.GenTab("test", "gender(cwf;*)", "region(cwf;*)", "", "", sprops, dprops);
Console.WriteLine(ret);
eng.CloseJob();

Scripts run via dotnet-script are independent of rcsx and the standard distribution folders. It is possible to use different #r nuget versions in diffrent scripts which by convention are downloaded and cached separately on first use. The sample code above has a hard-coded package version number, but the version can be omitted and the most recently published version will be automatically detected, downloaded and used.

Return to the Development Portal

Last updated: 03-Oct-2022