LINQPad Scripting

LINQPad is shipped with a utility program called lprun.exe (LINQPad run). This program offers a full command-line experience, and also allows the user to write scripts. These scripts can be executed from the command line or invoked from another query.

Lprun command-line options

The lprun.exe tool can be executed with the following syntax.

Code Listing 2: Lprun.exe Execution Syntax

The options that control lprun.exe behavior will be explained in the following sections. The script file can be a plain text file with any extension (even .txt), or a previously saved query file with the .linq extension. The difference between them is an XML header that LINQPad places at the beginning of every .linq file created with the program, which is absent in a plain-text script file.

A script file can receive parameters as a series of arguments. These parameters can be declared after the name of the script file, in a white-space separated list.

The following figure shows the execution of the helloworld.linq query using the lprun.exe tool.

Figure 20: Running the helloworld.linq Query

Code Listing 3: helloworld.linq

Output formatting

By default, the lprun.exe tool outputs the result for a query in plain text format. Lists and non-basic objects are formatted as JSON. The output format can be controlled by the -format option, which has the following syntax.

Code Listing 4: The -format Option Syntax

The values for the -format option are:

• text: Generates output in plain text. This is the default behavior.
• html: Returns a complete HTML output. This output can be written to a file.
• htmlfrag: Returns an HTML fragment that can be inserted into an existing HTML document.
• csv: Renders the output to a CSV (Excel-friendly) format. This is useful when simple lists are returned.
• csvi: Same as csv, but forcing to a culture-insensitive formatting.

The following sample executes the helloworld.linq query with an HTML format output.

Code Listing 5: Execution of helloworld.linq Example

The output generated is an HTML text, like the following sample:

Code Listing 6: Helloworld.linq Output Generated

Output redirection

The standard > operator can be used to redirect the output generated by lprun.exe. The following code writes the result of the helloworld.linq query to a file called helloworld.html.

Code Listing 7: Redirecting helloworld.linq Output

Another way to write the output to a file is by making the script itself to do the job. The following code writes the output for the query to an HTML file, which will take the same name of the query file, except for the .html extension.

Code Listing 8: Writing Query Output to a File from the Query Itself

If you save the query as helloworldhtml.linq, when this code is executed using the lprun.exe tool, a file called helloworldhtml.html will be found in the default queries folder.

The following figure shows how to execute the previous query using the lprun.exe tool.

 Figure 21: Helloworldhtml.linq Creating the HTML File Itself

Note: Error messages and warnings are written to the stderr, so they’re not redirected.

Error handling

Error handling for the lprun.exe tool can be managed by using the %errorlevel% variable since all errors and warnings are written to the stderr (Console.Error). The following sample can be saved into a batch file in order to know if the query was executed with no errors.

Code Listing 9: Lprun.exe Error Handling

Compilation options

There are three options for controlling the way lprun.exe compiles queries:

• -optimize: Enables compile optimizations. This produces a slightly faster execution but less accurate error reporting.
• -warn: Outputs the compiler warnings to the stderr (Console.Error).
• -compileonly: Tells lprun.exe that the query will be compiled only, without running anything.

The following sample tells lprun.exe that the helloworldhtml.linq query should be only compiled, not executed.

Code Listing 10: Compiling a Query

Plain-text scripts

Lprun.exe can execute plain text files as scripts. These files are known as plain-text scripts, and as explained in the “Lprun command-line options” section of this chapter, their difference compared to a regular .linq file is the absence of the XML header found at the beginning of .linq files.

In the case of plain-text scripts, lprun.exe forces the user to tell which language will be used to compile the code. This is done with the -lang option of lprun.exe, and the possible values this option can take are the following:

• Expression: A C# expression with no semicolon at the end of the line.
• Statements: Several C# statements ending with a semicolon.
• Program: A C# program that begins with a Main method declaration.
• VBExpression: A Visual Basic .NET expression.
• VBStatements: Server Visual Basic .NET statements.
• VBProgram: A Visual Basic .NET program with a Main sub declaration.
• FSharpExpression: An F# expression.
• FSharpProgram: An F# program.
• SQL: A SQL language query.
• ESQL: An Entity SQL language query.

The first three values can be abbreviated to their first letter: e can be used for Expression, s can be used for Statements, and p can be used for Program.

The following code displays the value of 44. This code should be saved as expressionscript.txt in the LINQPad queries default folder.

Code Listing 11: Code for Displaying a Numeric Constant

To display the result in the command window, lprun.exe should be executed in the following way.

Code Listing 12: Executing expressionscript.txt with Lprun.exe

The following figure shows the output displayed.

Figure 22: Executing an Expression Plain-Text Script

Managing connections

For plain-text scripts that require connections, the -cxnname option of lprun.exe should be used to specify the connection’s name.

The following sample takes the first 20 rows from the Places table, which belongs to the connection called uspostalcodesEntities. The code should be saved as placestake20.txt in the LINQPad queries default folder.

Code Listing 13: A Script that Uses a Connection

The placestake20.txt script should be executed in the following way.

Code Listing 14: Executing a Script with the -cxname Option

The output displayed by this script is shown in the following listing.

Code Listing 15: Output Generated by placestake20.txt

Managing assemblies and namespaces

LINQPad plain-text scripts support a directive named ref. This directive is used for referencing additional assemblies. Also, unlike .linq queries, plain-text scripts support using directives to import additional namespaces.

The following sample creates a custom button class derived from the System.Windows.Forms.Button class.

Code Listing 16: Referencing Assemblies in a Script

As noted in the previous code, all assemblies’ references and namespaces importing must be at the top of the script. The user can specify each assembly either by its file name (including the absolute path) or its fully qualified name, in case the assembly is in the GAC.

Note: ref directives must precede using directives.

The previous script must be executed as a Program script, as shown in the following example.

Code Listing 17: Executing a Script as a Program Script

This code executes the script, formatting the result in HTML. The result is saved into the custombutton.html file.

Passing arguments to scripts

To pass arguments to scripts from the command line, a space-separated list should be typed after the file name of the script. To pick those arguments, a Program query can be written, declaring a string array parameter at the Main method.

The following example dumps all arguments passed to the query.

Code Listing 18: A Script that Receives Arguments from the Command Line

Assuming that the previous code was saved in a file named passingarguments.txt, the following command will display ["Hello", "World"].

Code Listing 19: Executing a Script with Arguments

The CMD Boolean symbol

Sometimes it is necessary to know if a query is being executed from the command line or from the GUI. In order to do this, LINQPad provides a Boolean symbol called CMD. This symbol should be used in conjunction with the #if directive, as shown in the following sample.

Code Listing 20: Using the CMD Symbol

As noted in the previous code, the CMD directive helps LINQPad choose whether to save the contents of the CustomButton object into an HTML file, or to display the button in the Results panel.

The code should be saved as a .linq query file (for book purposes, cmdsymbolsample.linq), referencing the System.Drawing.dll and System.Windows.Forms.dll assemblies, and also importing the System.Drawing and System.Windows.Forms namespaces.

Now, if the query is executed as a script using lprun.exe, a file named cmdsymbolsample.html will be created in the default queries folder. Otherwise, if the query is executed from the LINQPad user interface, the CustomButton object will be displayed in the Results panel.

Calling a script from another script

Scripts can be combined in order to execute one script from another. To do this, use the Util.Run method. The following sample takes the name of any query as an argument from the command line, and then runs that query getting the result in HTML format. The result is displayed in the command window.

Code Listing 21: Executing a Script from Another Script

This code expects a one-element length array with the name of the query file to run. If no arguments or more than one argument are passed to the query, a help message is displayed. Also, the query validates if the file exists in the filesystem. If not, an error message is displayed. Once all validation tasks are passed, the Util.Run method executes the query, formatting the result as an HTML string, using the AsString method. The result of the query is stored in the htmlResult variable, which is dumped to the command window.

Assuming that the previous script was saved in a file named querytohtml.txt, the following sample runs the imagerendering.linq query from within this script.

Code Listing 22: Executing the Scripts

Chapter summary

LINQPad is shipped with a utility program called lprun.exe, which offers a full command-line experience and also allows the user to write scripts to be executed from the command line or from within another query.

A script can be written using plain-text files or LINQPad .linq query files. A script saved in plain-text format doesn’t have the XML header found in .linq files.

The lprun.exe tool has a series of options that can control its behavior. These options control the output formatting, the way a script is compiled, the database connection that a script should use, and the language used by the script.

Arguments can be passed to a script from the command line. To do this, you should write the values for these arguments using a space-separated list after the name of the script. The arguments are trapped by the query using a string array parameter in the Main method of a C# Program query.

You can determine if a script is being executed either from the command line or from the user interface by using the CMD Boolean symbol. This symbol takes the value of true when a script is executed by lprun.exe. Otherwise, a value of false is stored in that symbol.

Finally, the Util.Run method allows you to execute a script from another one. The output format for the result can be established by the QueryResultFormat enumeration, and converted to a string using the AsString method.