Modules

#What is a Module?

A Module is a unit of functionality that extends the scriptcs runtime itself. Modules have access to all the core service that scriptcs uses, they can modify existing services, replace them completely or introduce new services.

A few examples of the kinds of things you can do with modules:

• Introduce a new engine for executing scripts. The Roslyn, Mono and FSharp engines are all deployed as modules.
• Register custom line processors.
• Replace the existing FilePreProcessor with a derived one that does special parsing.
• Introduce a custom script host
• Replace the File System with an alternative implementation, like one that can talk to Azure Blob Storage or S3.
• Register new REPL commands (future)

As you can see modules are extremely powerful!

#Installing Modules are installed via NuGet as packages. Unlike script packs, these packages are stored in a global location as they apply to scriptcs itself rather than to a particular script. To install a module you use the -install and -g parameters on scriptcs.

scriptcs -install ScriptCs.MyModule -g

#Loading Specify which modules you want loaded at runtime with the -modules switch (-M) for short.

scriptcs start.csx -modules mymodule

#Authoring Here are the steps for authoring a module:

• Create a new .NET 4.5 class library. Name it with the template ScriptCs.[ModuleName]Module i.e. ScriptCs.HelloWorldModule
• Add scriptcs packages
  • If you are going to derive from existing scriptcs services, add a NuGet reference to the `ScriptCs.Hosting' package.
  • Otherwise add a NuGet reference to the ScriptCs.Contracts package.
• Add additional packages
  • If your module will depend on other nuget packages, you should add them as nuget references.
• Create a new class for the module. Name it with the template [ModuleName]Module.
• Add a using ScriptCs; to the class.
• Implement the IModule interface.

Below is an example of a super simple HelloWorld Module which simply writes a "Hello World" message to the console when the module is loaded.

[Module("helloworld", Extensions = "csx")]
public class HelloWorldModule : IModule
{
    public void Initialize(IModuleConfiguration config)
    {
        Console.WriteLine("Hello World");
    }
}

IModuleConfiguration

Testing and Debugging.

While developing a module, you will need to test it and may need to step through and debug. To test your module follow these steps.

1. Create a NuGet package for your module i.e. nuget pack -version 0.1.0-alpha
2. In VS edit your Nuget package sources and add the folder where the package lives, or use a NuGet.config in the folder where your csx file lives.
3. Install the package globally: scriptcs -install scriptcs.helloworldmodule -g -pre
4. Run scriptcs forcing the module to load: scriptcs -modules helloworld
5. Check the output for the message "Hello World"
6. To debug, and step through your module, open your module project in Visual Studio and set project options to launch scriptcs using scriptcs -debug -modules helloworld. You should then be able to put a break point on your module and debug it in scriptcs.

Sample Module

[Here] (https://github.com/scriptcs-contrib/scriptcs-sample-module) is a sample module that you can clone to start playing with developing modules. The README contains full instructions to get it building and to test it out.