Interactive Service: Embedding F# Interactive

This tutorial demonstrates how to embed F# interactive in your application. F# interactiveis an interactive scripting environment that compiles F# code into highly efficient IL codeand executes it on the fly. The F# interactive service allows you to embed F# evaluation inyour application.

NOTE: There is a number of options for embedding F# Interactive. The easiest one is to use thefsi.exe process and communicate with it using standard input and standard output. In thistutorial, we look at calling F# Interactive directly through .NET API. However, if you haveno control over the input, it is a good idea to run F# interactive in a separate process.One reason is that there is no way to handleStackOverflowException and so a poorly writtenscript can terminate the host process.Remember that while calling F# Interactive through .NET API,--shadowcopyreferences option will be ignored. For detailed discussion, please take a look atthis thread.NOTE: IfFsiEvaluationSession.Create fails with an error saying thatFSharp.Core.dll cannot be found,add theFSharp.Core.sigdata andFSharp.Core.optdata files. More infohere.

However, the F# interactive service is still useful, because you might want to wrap it in yourown executable that is then executed (and communicates with the rest of your application), orif you only need to execute a limited subset of F# code (e.g. generated by your own DSL).

Starting the F# interactive

First, we need to reference the libraries that contain the F# interactive service:

#r"FSharp.Compiler.Service.dll"openFSharp.Compiler.Interactive.ShellopenFSharp.Compiler.Tokenization

To communicate with F# interactive, we need to create streams that represent input andoutput. We will use those later to read the output printed as a result of evaluating someF# code that prints:

openSystemopenSystem.IOopenSystem.Text// Initialize output and input streamsletsbOut=newStringBuilder()letsbErr=newStringBuilder()letinStream=newStringReader("")letoutStream=newStringWriter(sbOut)leterrStream=newStringWriter(sbErr)// Build command line arguments & start FSI sessionletargv=[|"C:\\fsi.exe"|]letallArgs=Array.appendargv[|"--noninteractive"|]letfsiConfig=FsiEvaluationSession.GetDefaultConfiguration()letfsiSession=FsiEvaluationSession.Create(fsiConfig,allArgs,inStream,outStream,errStream)

Evaluating and executing code

The F# interactive service exposes several methods that can be used for evaluation. The firstisEvalExpression which evaluates an expression and returns its result. The result containsthe returned value (asobj) and the statically inferred type of the value:

/// Evaluate expression & return the resultletevalExpressiontext=matchfsiSession.EvalExpression(text)with|Somevalue->printfn"%A"value.ReflectionValue|None->printfn"Got no result!"

This takes a string as an argument and evaluates (i.e. executes) it as F# code.

evalExpression"42+1"// prints '43'

This can be used in a strongly typed way as follows:

/// Evaluate expression & return the result, strongly typedletevalExpressionTyped<'T>(text)=matchfsiSession.EvalExpression(text)with|Somevalue->value.ReflectionValue|>unbox<'T>|None->failwith"Got no result!"evalExpressionTyped<int>"42+1"// gives '43'

TheEvalInteraction method can be used to evaluate side-effectful operationssuch as printing, declarations, or other interactions that are not valid F# expressions, but can be entered inthe F# Interactive console. Such commands include#time "on" (and other directives),open Systemall declarations and other top-level statements. The codedoes not require;; at the end. Just enter the code that you want to execute:

fsiSession.EvalInteraction"printfn \"bye\""

TheEvalScript method allows to evaluate a complete .fsx script.

File.WriteAllText("sample.fsx","let twenty = 10 + 10")fsiSession.EvalScript"sample.fsx"

Catching errors

EvalExpression,EvalInteraction andEvalScript are awkward if thecode has type checking warnings or errors, or if evaluation fails with an exception.In these cases you can useEvalExpressionNonThrowing,EvalInteractionNonThrowingandEvalScriptNonThrowing. These return a tuple of a result and an array ofFSharpDiagnostic values.These represent the errors and warnings. The result part is aChoice<_,_> between an actualresult and an exception.

The result part ofEvalExpression andEvalExpressionNonThrowing is an optionalFSharpValue.If that value is not present then it just indicates that the expression didn't have a tangibleresult that could be represented as a .NET object. This situation shouldn't actuallyoccur for any normal input expressions, and only for primitives used in libraries.

File.WriteAllText("sample.fsx","let twenty = 'a' + 10.0")letresult,warnings=fsiSession.EvalScriptNonThrowing"sample.fsx"// show the resultmatchresultwith|Choice1Of2()->printfn"checked and executed ok"|Choice2Of2exn->printfn"execution exception:%s"exn.Message

Gives:

executionexception:Operationcouldnotbecompletedduetoearliererror

// show the errors and warningsforwinwarningsdoprintfn"Warning%s at%d,%d"w.Messagew.StartLinew.StartColumn

Gives:

WarningThetype'float'doesnotmatchthetype'char'at1,19WarningThetype'float'doesnotmatchthetype'char'at1,17

For expressions:

letevalExpressionTyped2<'T>text=letres,warnings=fsiSession.EvalExpressionNonThrowing(text)forwinwarningsdoprintfn"Warning%s at%d,%d"w.Messagew.StartLinew.StartColumnmatchreswith|Choice1Of2(Somevalue)->value.ReflectionValue|>unbox<'T>|Choice1Of2None->failwith"null or no result"|Choice2Of2(exn:exn)->failwith(sprintf"exception%s"exn.Message)evalExpressionTyped2<int>"42+1"// gives '43'

Executing in parallel

By default the code passed toEvalExpression is executed immediately. To execute in parallel, submit a computation that starts a task:

openSystem.Threading.TasksletsampleLongRunningExpr="""async {    // The code of what you want to run    do System.Threading.Thread.Sleep 5000    return 10}  |> Async.StartAsTask"""lettask1=evalExpressionTyped<Task<int>>(sampleLongRunningExpr)lettask2=evalExpressionTyped<Task<int>>(sampleLongRunningExpr)

Both computations have now started. You can now fetch the results:

task1.Result// gives the result after completion (up to 5 seconds)task2.Result// gives the result after completion (up to 5 seconds)

Type checking in the evaluation context

Let's assume you have a situation where you would like to typecheck codein the context of the F# Interactive scripting session. For example, you firstevaluate a declaration:

fsiSession.EvalInteraction"let xxx = 1 + 1"

Now you want to typecheck the partially complete codexxx + xx

letparseResults,checkResults,checkProjectResults=fsiSession.ParseAndCheckInteraction("xxx + xx")

TheparseResults andcheckResults have typesParseFileResults andCheckFileResultsexplained inEditor. You can, for example, look at the type errors in the code:

checkResults.Diagnostics.Length// 1

The code is checked with respect to the logical type context available in the F# interactive sessionbased on the declarations executed so far.

You can also request declaration list information, tooltip text and symbol resolution:

// get a tooltipcheckResults.GetToolTip(1,2,"xxx + xx",["xxx"],FSharpTokenTag.IDENT)checkResults.GetSymbolUseAtLocation(1,2,"xxx + xx",["xxx"])// symbol xxx

The 'fsi' object

If you want your scripting code to be able to access the 'fsi' object, you should pass in an implementation of this object explicitly.Normally the one from FSharp.Compiler.Interactive.Settings.dll is used.

letfsiConfig2=FsiEvaluationSession.GetDefaultConfiguration(fsiSession)

Collectible code generation

Evaluating code in using FsiEvaluationSession generates a .NET dynamic assembly and uses other resources.You can make generated code collectible by passingcollectible=true. However, code will onlybe collected if there are no outstanding object references involving types, for exampleFsiValue objects returned byEvalExpression, and you must have disposed theFsiEvaluationSession.See alsoRestrictions on Collectible Assemblies.

The example below shows the creation of 200 evaluation sessions. Note thatcollectible=true anduse session = ... are both used.

If collectible code is working correctly,overall resource usage will not increase linearly as the evaluation progresses.

letcollectionTest()=foriin1..200doletdefaultArgs=[|"fsi.exe""--noninteractive""--nologo""--gui-"|]useinStream=newStringReader("")useoutStream=newStringWriter()useerrStream=newStringWriter()letfsiConfig=FsiEvaluationSession.GetDefaultConfiguration()usesession=FsiEvaluationSession.Create(fsiConfig,defaultArgs,inStream,outStream,errStream,collectible=true)session.EvalInteraction(sprintf"type D = { v : int }")letv=session.EvalExpression(sprintf"{ v = 42 *%d }"i)printfn"iteration%d, result =%A"iv.Value.ReflectionValue// collectionTest()  <-- run the test like this