Westwind.Scripting

Class that can be used to execute code snippets or entire blocks of methods dynamically. Two methods are provided: * ExecuteCode - executes code. Pass parameters and return a value * ExecuteMethod - lets you provide one or more method bodies to execute * Evaluate - Evaluates an expression on the fly (uses ExecuteCode internally) * CompileClass - compiles a class and returns the a class instance Assemblies used for execution are cached and are reused for a given block of code provided.

Internal list of assemblies that are cached for snippets of the same type. List holds a list of cached assemblies with a hash code for the code executed as the key.

List of additional namespaces to add to the script

List of additional assembly references that are added to the compiler parameters in order to execute the script code.

Last generated code for this code snippet with line numbers

Name of the namespace that a class is generated in

Name of the class when a class name is not explicitly provided as part of the code compiled. Always used for the module name. By default this value is a unique generated id. Make sure if you create multiple compilations that you change the name here, otherwise you end up with duplicate module names that fail.

Last generated code for this code snippet if SaveGeneratedCode = true

Determines whether GeneratedCode will be set with the source code for the full generated class

If true throws exceptions when executing the code rather than setting the `Error`, `ErrorMessage` and `LastException` properties. Note: Compilation errors will not throw, but always set properties!

If true parses references in code that are referenced with: #r assembly.dll

Filename for the output assembly to generate. If empty the assembly is generated in memory (dynamic filename managed by the .NET runtime)

Determines whether the code is compiled in Debug or Release mode Defaults to Release and there's no good reason for scripts to use anything else since debug info is not available in Reflection invoked or dynamically invoked methods. Useful only when generating classes with OutputAssembly set when creating self-contained assemblies for other uses.

If disabled, assemblies will not be cached through hashes Instead for each execution a new unique assembly will get generated and loaded This combined with an alternate AssemblyLoadContext can lower the memory pressure of long running programs executing a lot of different code

Disables caching object instances that are created after CompileClass If true you can't execute new code on the instance as the class instance is cached. If false the instance is cached and automatically resused.

The ideals use case treats the script execution class as a single code unit so each piece of code (snippet, expresion, method or class) is generated and treated distinctly and therefore it's recommended to NOT REUSE instances for multiple pieces of code.

Optional code injections at various points in the code generation

Error message if an error occurred during the invoked method or script call

Error flag that is set if an error occurred during the invoked method or script call

Determines whether the error is a compile time error or runtime error

Last Exception fired when a runtime error occurs Generally this only contains the error message, but there's no call stack information available due to the Reflection or dynamic code invocation

Internal reference to the Assembly Generated

Internal reference to the generated type that is to be invoked Can also be used to cache an object instance using ReuseObjectInstance, which is useful if you work with a single object/method that is repeatedly called and never changes.

If true reuses the ObjectInstance fromt he previous operation (if set) instead of creating a new instance. Use if you pre-generate a single instance and call one or more methods/scripts repeatedly without changing the code. For most use cases leave this setting at false. IMPORTANT: If you change code either explicitly clear the object reference or set this value to false.

Creates a default Execution Engine which has: * AddDefaultReferences and Namespaces set * SaveGeneratedCode = true Optionally allows to pass in references and namespaces

Executes a complete method by wrapping it into a class, compiling and instantiating the class and calling the method. Code should include full method header (instance type, return value and parameters) Example: "public string HelloWorld(string name) { return name; }" "public async Task<string> HelloWorld(string name) { await Task.Delay(1); return name; }" Async Method Note: Keep in mind that the method is not cast to that result - it's cast to object so you have to unwrap it: var objTask = script.ExecuteMethod(asyncCodeMethod); // object result var result = await (objTask as Task<string>); // cast and unwrap

One or more complete methods. Name of the method to call. any number of variable parameters

Executes a complete async method by wrapping it into a class, compiling and instantiating the class and calling the method. This method has to return a result value - it cannot be void! Class should include full class header (instance type, return value and parameters) "public async Task<object> HelloWorld(string name) { await Task.Delay(1); return name; }" "public async Task HelloWorld(string name) { await Task.Delay(1); Console.WriteLine(name); }" Async Method Note: Keep in mind that the method is not cast to that result - it's cast to object so you have to unwrap it: var objTask = script.ExecuteMethod(asyncCodeMethod); // object result var result = await (objTask as Task<string>); // cast and unwrap

One or more complete methods. Name of the method to call. any number of variable parameters result value of the method

Executes a complete async method by wrapping it into a class, compiling and instantiating the class and calling the method and unwrapping the task result. Method should include full method header (instance type, return value and parameters) "public async Task<string> HelloWorld(string name) { await Task.Delay(1); return name; }" Async Method Note: Keep in mind that the method is not cast to that result - it's cast to object so you have to unwrap it: var objTask = script.ExecuteMethod(asyncCodeMethod); // object result var result = await (objTask as Task<string>); // cast and unwrap

One or more complete methods. Name of the method to call. any number of variable parameters The result type (string, object, etc.) of the method result value of the method

Executes a complete async method by wrapping it into a class, compiling and instantiating the class and calling the method. This method returns no value. Class should include full class header (instance type, return value and parameters) "public async Task<object> HelloWorld(string name) { await Task.Delay(1); return name; }" "public async Task HelloWorld(string name) { await Task.Delay(1); Console.WriteLine(name); }" Async Method Note: Keep in mind that the method is not cast to that result - it's cast to object so you have to unwrap it: var objTask = script.ExecuteMethod(asyncCodeMethod); // object result var result = await (objTask as Task<string>); // cast and unwrap

One or more complete methods. Name of the method to call. any number of variable parameters result value of the method

Evaluates a single value or expression that returns a value.

Evaluates an awaitable expression that returns a value Example: script.EvaluateAsync("await ActiveEditor.GetSelection()",model);

Code to execute Optional parameters to pass. Access as `object parameters[]` in expression

Evaluates an awaitable expression that returns a value Example: script.EvaluateAsync("await ActiveEditor.GetSelection()",model);

code to execute Optional parameters to pass. Access as `object parameters[]` in expression

Executes a snippet of code. Pass in a variable number of parameters (accessible via the parameters[0..n] array) and return an object parameter. Code should include: return (object) SomeValue as the last line or return null

The code to execute The parameters to pass the code You can reference parameters as @0, @1, @2 in code to map to the parameter array items (ie. @1 instead of parameters[1])

The code to execute The parameters to pass the code You can reference parameters as @0, @1, @2 in code to map to the parameter array items (ie. @1 instead of parameters[1]) Result cast to a type you specify

Executes a snippet of code. Pass in a variable number of parameters (accessible via the parameters[0..n] array) and return an `object` value. Code should always return a result: include: `return (object) SomeValue` or `return null`

The code to execute The parameters to pass the code You can reference parameters as @0, @1, @2 in code to map to the parameter array items (ie. @1 instead of parameters[1])

The code to execute an optional model to pass to the code which is then accessible as a `Model` property in the code.

Executes a method from an assembly that was previously compiled

Executes a method from an assembly that was previously compiled. Creates the instance based on the current settings of this class.

Executes a script template that interpolates `{{ }}` C# expressions and `{{% }}` C# code blocks in a string.

Compiles a class and creates an assembly from the compiled class. Assembly is stored on the `.Assembly` property. Use `noLoad()` to bypass loading of the assembly Must include parameterless ctor()

Source code if set doesn't load the assembly (useful only when OutputAssembly is set)

Compiles the source code for a complete class and then loads the resulting assembly. Loads the generated assembly and sets the `.Assembly` property if successful. If `OutputAssembly` is set, the assembly is compiled to the specified file. Otherwise the assembly is compiled 'in-memory' and cleaned up by the host application/runtime. Must include parameterless ctor()

Stream that contains C# code If set won't load the assembly and just compiles it. Useful only if OutputAssembly is set so you can explicitly load the assembly later.

This method compiles a class and hands back a dynamic reference to that class that you can call members on. Must have include parameterless ctor()

Fully self-contained C# class Instance of that class or null

This method compiles a class and hands back a dynamic reference to that class that you can call members on. Must have include parameterless ctor()

Does not allow for #r reference inclusion - if you need #r Fully self-contained C# class Instance of that class or null

This method compiles a class and hands back a dynamic reference to that class that you can call members on.

Fully self-contained C# class Instance of that class or null

This method expects a fully self-contained class file including namespace and using wrapper to compile from an input stream.

Does not parse #r reference inclusion. If you need to use #r pass code as string Fully self-contained C# class A type reference to the generated class

This method creates a class wrapper around a passed in class body. The wrapper creates the namespace, adds usings, and creates the class header based on the property settings for the instance. You pass in the 'body' of the class which is properties, constants, methods etc. to fill out the class

The class body - methods, properties, constants etc. without a class header

Adds core system assemblies and namespaces for basic operation. Any additional references need to be explicitly added. Alternatelively use: AddLoadedReferences()

Explicitly adds all referenced assemblies of the currently executing process. Also adds default namespaces. Useful in .NET Core to ensure that all those little tiny system assemblies that comprise NetCoreApp.App etc. dependencies get pulled in. For full framework this is less important as the base runtime pulls in all the system and system.core types. Alternative: use LoadDefaultReferencesAndNamespaces() and manually add

Adds an assembly from disk. Provide a full path if possible or a path that can resolve as part of the application folder or the runtime folder.

assembly DLL name. Path is required if not in startup or .NET assembly folder

Adds an assembly reference from an existing type

any .NET type that can be referenced in the current application

Add several reference assemblies in batch. Useful for use with Basic.ReferenceAssemblies from Nuget to load framework dependencies in Core Example: ReferenceAssemblies.Net60 ReferenceAssemblies.NetStandard20

MetaDataReference or PortableExecutiveReference

Adds a list of assemblies to the References collection.

Adds a namespace to the referenced namespaces used at compile time.

Adds a set of namespace to the referenced namespaces used at compile time.

Error wrapper that assigns exception, errormessage and error flag. Also throws exception by if ThrowException is enabled

Parses references with this syntax: #r assembly.dll Each match found is added to the assembly list

Parses a string into an array of lines broken by \r\n or \n

String to check for lines Optional - max number of lines to return array of strings, or null if the string passed was a null

Returns 0 offset line number where matched line lives

Helper method to invoke a method on an object using Reflection

An object instance. null uses ObjectInstance property if set. Pass `null` to use a previously set ObjectInstance. The method name as a string a variable list of parameters to pass Throws if the instance is null result from method call or null.

Creates an instance of the object specified by the GeneratedNamespace and GeneratedClassName in the currently active, compiled assembly Sets the ObjectInstance member which is returned and which can possibly be reused.

If true force to create a new instance regardless whether an instance is already loaded Instance of the class or null on error

Generates a hashcode for a block of code in combination with the compiler mode.

Returns path of the runtime or in self contained install local folder

List of default namespaces that are added when adding default references and namespaces

HashSet of namespaces

HashSet of References

This helper can help start up Roslyn before first call so that there's no long startup delay for first script execution and you can also optionally shut Roslyn down and kill the VBCSCompiler that otherwise stays loaded even after shutting down your application.

Run a script execution asynchronously in the background to warm up Roslyn. Call this during application startup or anytime before you run the first script to ensure scripts execute quickly. Although this method returns `Task` so it can be tested for success, in applications you typically will call this without `await` on the result task and just let it operate in the background.

Call this method to shut down the VBCSCompiler if our application started it.

Marker interface

String container that indicates that this string should never be Html Encoded.

The raw string value that's been assigned. Alternately retrieve with .ToString()

Returns a raw string (same as new RawString() but easier to use in code {{ RawString.Raw() }} Functions can return IRawString to

Context object used for File based script parsing. The main purpose of this context is to pass data through so that Layout and Sections and partials can be processed reliably.

The base path used for / and ~/ resolution If not specified the document's path (for files) or the current directory (for strings) is used

The actual script code that's passed and updated through out the request processing process

The model that will be passed to the execution code

The layout page if any to use for this script. Path is relative the detail page. Provided so compilation works not used in code.

The title of the page

Dictionary of sections that are captured and passed through

The top level script that is being processing

Script Helper that is injected into the script as a global `Script` variable To use: {{ Script.RenderPartial("./test.template") }}

This the base path that's used for ~/ or / paths when using RenderTemplate This value is null by default and if not set the current working directory is used instead.

Optional Page Title - useful in HTML Pages that use Layout to pass the title to the Layout page

Renders a partial file into the template

Path to script file to execute optional model to pass in

Renders a partial file into the template

Path to script file to execute optional model to pass in

Used in a Layout Page to indicate where the content should be rendered

Renders a string of script to effectively allow recursive rendering of content into a fixed template

text or script to render optional model to pass in

Renders a string of script to effectively allow recursive rendering of content into a fixed template

text or script to render optional model to pass in

Reads the entire content of a file asynchronously

Returns a raw string that is Html Encoded even if encoding by default is enabled or an explicit {{: }} block is used.

Encodes a value using Html Encoding by first converting

Retrieve a property value from an object dynamically. This is a simple version that uses Reflection calls directly. It doesn't support indexers.

Object to make the call on Property to retrieve Object - cast to proper type

Calls a method on an object dynamically. This version doesn't require specific parameter signatures to be passed. Instead parameter types are inferred based on types passed. Note that if you pass a null parameter, type inferrance cannot occur and if overloads exist the call may fail. if so use the more detailed overload of this method.

Instance of object to call method on The method to call as a stringToTypedValue Specify each of the types for each parameter passed. You can also pass null, but you may get errors for ambiguous methods signatures when null parameters are passed any variable number of parameters. object

Calls a method on an object dynamically. This version requires explicit specification of the parameter type signatures.

String Writer Abstraction

A very simple C# script parser that parses the provided script as a text string with embedded expressions and code blocks. Literal text: Parsed as plain text into the script output. Expressions: {{ DateTime.Now.ToString("d") }} Code Blocks: {{% for(int x; x<10; x++ { }} {{ x }}. Hello World {{% } }} Uses the `.ScriptEngine` property for execution and provides error information there.

Script Engine used if none is passed in

Allows you to inject additional code into the generated method that executes the script.

Determines whether the was a compile time or runtime error

Error Message if an error occurred

Type of error that occurred during compilation or execution of the template

Generated code that is compiled

Generated code with line numbers that is compiled. You can use this to match error messages to code lines.

Delimiters used for script parsing

Executes a script that supports {{ expression }} and {{% code block }} syntax and returns a string result. You can optionally pass in a pre-configured `CSharpScriptExecution` instance which allows setting references/namespaces and can capture error information. Function returns `null` on error and `scriptEngine.Error` is set to `true` along with the error message and the generated code.

The template to execute that contains C# script A model that can be accessed in the template as `Model`. Pass null if you don't need to access values. Optional CSharpScriptEngine so you can customize configuration and capture result errors Optional basePath/root for the script and related partials so ~/ or / can be resolved expanded template or null. On null check `scriptEngine.Error` and `scriptEngine.ErrorMessage`

Extracts a variable like Scripts.Title = "Title of code"

The template to execute that contains C# script A model that can be accessed in the template as `Model`. Pass null if you don't need to access values. Optional CSharpScriptEngine so you can customize configuration and capture result errors expanded template or null. On null check `scriptEngine.Error` and `scriptEngine.ErrorMessage`

Executes a script that supports {{ expression }} and {{% code block }} syntax and returns a string result. This version allows for `async` code inside of the template. You can optionally pass in a pre-configured `CSharpScriptExecution` instance which allows setting references/namespaces and can capture error information. Function returns `null` on error and `scriptEngine.Error` is set to `true` along with the error message and the generated code.

The template to execute that contains C# script A model that can be accessed in the template as `Model`. Model is exposed as `dynamic` which allows passing any value without requiring type dependencies at compile time. Pass null if you don't need to access values. Optional CSharpScriptEngine so you can customize configuration and capture result errors Optional start delimiter for script tags Optional end delimiter for script tags Optional Code block indicator that indicates raw code to create in the template (ie. `%` which uses `{{% }}`) expanded template or null. On null check `scriptEngine.Error` and `scriptEngine.ErrorMessage`

The template to execute that contains C# script A model that can be accessed in the template as `Model`. Pass null if you don't need to access values. Optional CSharpScriptEngine so you can customize configuration and capture result errors Optional basePath/root for the script and related partials so ~/ or / can be resolved expanded template string or null on error. On null check `scriptEngine.Error` and `scriptEngine.ErrorMessage`

The template to execute that contains C# script A model that can be accessed in the template as `Model`. Pass null if you don't need to access values. Optional CSharpScriptEngine so you can customize configuration and capture result errors expanded template or null. On null check `scriptEngine.Error` and `scriptEngine.ErrorMessage`

This parses the script file and extracts layout and section information and updates the `Script` property

This is a helper function that ooks at the content page and retrieves the ScriptLayout directive, and then tries to the load the layout template. The code then looks for the content page and merges the content page into layout template producing a single script that is assigned to context.Script. If Layout lookup fails the existing context.Script (ie. the content page) is returned.

True - Layout page processed - No Layout found

Parses out sections from the content page and assigns them into the ScriptContext.Sections dictionary to be later expanded into the layout page.

Strips {{@ commented block @}} from script

Passes in a block of finalized 'script' code into a string using code that uses a text writer to output. You can feed the output from this method in `ExecuteCode()` or similar to parse the script into an output string that includes the processed text.

Script context that is filled in process of parsing the script.

Passes in a block of 'script' code into a string using code that uses a text writer to output. You can feed the output from this method in `ExecuteCode()` or similar to parse the script into an output string that includes the processed text.

Script context that is filled in process of parsing the script.

Creates an instance of a script engine with default configuration settings set and the abililty to quickly specify addition references and namespaces. You can pass this to ExecuteScript()/ExecuteScriptAsync()

optional list of string assembly file names optional list of name spaces optional list of reference types

Adds an assembly to the list of references for compilation using a dll filename

Assembly filenames

Adds an assembly to the list of references for compilation using a type that is loaded and contained in the assembly

type loaded and contained in the target assembly

Adds several assembly to the list of references for compilation using a dll filenames.

Assembly file names

list of meta references to assemblies. Can be used with `Basic.References

Add a namespace for compilation of the template

Add a list of namespaces for compilation of the template

Encodes a string to be represented as a C# style string literal. Example output: "Hello \"Rick\"!\r\nRock on"

string to encode if true adds quotes around the encoded text

Encodes a value using Html Encoding by first converting

Any object - encodes .ToString()

Encodes a value using Html Encoding by first converting

string value

Class that encapsulates the delimiters used for script parsing

Start delimiter for expressions and script tags

End delimiter for expressions and script tags

Indicator for code blocks inside of StartDelim (ie. {{% code }} for code blocks)

If true all expressions except the Raw Html indicator are Html Encoded

Indicator for expressions to be explicitly HtmlEncoded

Indicator for expressions to be explicitly NOT encoded and just returned as is regardless of HtmlEncodeByDefault

Used to indicate a block of code should be commented {{ }}

A default instance of the delimiters

Returns the number or right characters specified

full string to work with number of right characters to return

Extracts a string from between a pair of delimiters. Only the first instance is found.

Input String to work on Beginning delimiter ending delimiter Determines whether the search for delimiters is case sensitive Extracted string or string.Empty on no match

Normalizes a file path to the operating system default slashes.