What you need to know to use QPad

Getting started

Download and install QPad, and start it from the Start menu. The first time, a small example is ready in the editor. Press F5 (or ▶ Run) and the result appears as a table below the code.

Enumerable.Range(1, 5)
    .Select(x => new { x, Square = x * x })
    .Dump("Squares");

The window has three parts: connections and queries on the left, the editor with tabs on the right, and the results below it. Drag the dividers to resize. Drag the divider next to the left panel all the way left to hide the panel, and back to show it. QPad remembers your tabs, the window size and the layout until next time.

Run modes

Choose the mode in the drop-down list next to ■ Stop above the editor. New tabs start in C# Statements.

C# Expression

A single expression, such as DateTime.Now.AddDays(30). The value is shown automatically – no .Dump() needed. A semicolon at the end is fine.

C# Statements

Ordinary code line by line, like a Program.cs with top-level statements. using at the top, await and your own classes at the bottom are allowed.

C# Program

A void Main() (or async Task Main()) with your own methods, fields and classes around it. A complete file with its own static Main works too.

When you switch to C# Program, the code is wrapped in void Main() { … } automatically (or async Task Main() if it uses await). Undo with Ctrl+Z if you change your mind. If the code is in the wrong mode, the error message tells you which mode to choose.

void Main()
{
    var total = Sum(1, 2, 3);
    total.Dump("Sum");
}

int Sum(params int[] numbers) => numbers.Sum();

These namespaces are always available without using: System, System.Collections.Generic, System.IO, System.Linq, System.Text, System.Threading and System.Threading.Tasks.

Results and .Dump()

Write .Dump() after a value to show it. Lists and objects become tables, dictionaries become Key/Value, and nested objects are shown inside the cells. Give the table a heading with .Dump("Title"). Dump returns the value, so it can sit in the middle of a chain.

var people = new[]
{
    new { Name = "Kari", Age = 29 },
    new { Name = "Ola", Age = 41 },
};

people.Dump("Everyone");
people.Where(p => p.Age > 30).Dump("Over 30");
Console.WriteLine($"Count: {people.Length}");

• Console.WriteLine writes straight into the results. Text written to Console.Error is shown as an error.
• A list shows up to 1000 items. A database query without .Take(n) fetches the first 1000 rows and tells you if there are more.
• Switch between Results and SQL above the results. SQL shows every SQL statement that ran against the database, with parameter values.
• Compilation errors are listed with line and column. Click an error and the cursor jumps there in the code.
• Exceptions are shown with type and message, and the stack trace can be expanded. Error text can be selected and copied.
• ■ Stop (Shift+F5) cancels the run. Scripts run in a separate process, so even an infinite loop is stopped without QPad hanging.
• Output over 20 MB in one run is cut off with a message. The status bar at the bottom shows how long the run took.

The editor

• Code completion appears when you type . or start a word, and with Ctrl+Space. Enter, Tab or a separator such as ( inserts the suggestion. Space closes the list.
• Parameter info appears when you type ( or , in a method call, and with Ctrl+Shift+Space. It shows the overload that matches the arguments you are typing.
• Hover over a name to see its type and documentation, or over an underlined error to read the message.
• Errors as you type: a red squiggle is an error, a green one a warning. The code is checked half a second after you stop typing.
• Format the code with Ctrl+K followed by Ctrl+D, as in Visual Studio, or Edit → Format document. Only indentation, spaces and line breaks change, and a single Ctrl+Z undoes it all.

Code completion also knows the NuGet packages you have added and the tables in the database the tab is connected to.

Code completion, parameter info and info when you hover over a name require an activated license. Error highlighting and formatting work without one.

Tabs

• New tab: Ctrl+T, File → New query or the + tab.
• Close: Ctrl+W, × on the tab or a middle click. If the tab has unsaved changes, you are asked whether to save.
• Switch tabs with Ctrl+Tab and Ctrl+Shift+Tab.
• Double-click the tab title to give the tab a name of its own. Enter saves, Esc cancels.
• An asterisk (*) after the name means unsaved changes.

When you close QPad, all tabs are kept – unsaved ones too – and they are back the next time you start it. That is why you are not asked to save when you exit. If you want a query as a file, save it with Ctrl+S.

qPad files

A query is saved as a .qpad file. It contains the code, the run mode, the NuGet packages (with exact versions), the DLLs you reference and which connection the query uses. The connection is only stored as a reference – never server names or passwords – so the file is safe to share or check into a repository.

• File → Save (Ctrl+S) saves. The first time, the My qPads folder and the tab's name are suggested.
• File → Save As… (Ctrl+Shift+S) saves a copy with a new name or in a new place.
• File → Open… (Ctrl+O) opens one or more files. If a file is already open, QPad goes to that tab.

A tab name of your own (set with a double-click) is not stored in the file. The file gets the name you choose when you save.

Examples and My qPads

Below the connections on the left is the Queries panel with two folders:

Examples

Ready-made examples to learn from: Hello QPad, Dump basics, LINQ to objects, Async code, C# Program, Using a NuGet package and Querying a database. They open as new, unsaved queries, so you can change them freely and save a copy of your own.

My qPads

Your own .qpad files, with subfolders. The default is Documents\QPad. Choose another folder under Edit → Settings….

This is how you organize the files, much like in Windows File Explorer:

• Open: double-click or Enter.
• New folder: right-click My qPads or a folder and choose New folder…. The folder is called “New folder”, and you can type a new name right away.
• Rename: select the file or folder and press F2, or right-click and choose Rename. The name changes right in the tree. Enter saves, Esc cancels.
• Move: drag a file to another folder. If you drop it on a file, it ends up in that file's folder.
• Delete: select the file and press Delete, or right-click and choose Delete…. The file goes to the Recycle Bin, so you can undo there. Folders are deleted in File Explorer.
• File Explorer: Show in Explorer on a file and Open in Explorer on a folder.

Open tabs follow along when a file is moved or renamed. Changes you make to the folder outside QPad show up in the tree by themselves.

Databases

QPad connects to SQL Server (LocalDB too), PostgreSQL and SQLite.

Adding a connection

1. Click Add connection at the top of the left panel.
2. Choose the Server type and enter the Server, for example localhost, .\SQLEXPRESS or (localdb)\MSSQLLocalDB. For PostgreSQL you can add a port: db.example.com:5432.
3. Choose Windows authentication or User name and password.
4. Pick the database in the Database list (fetched from the server), or type its name.
5. Press Test connection to check it, and OK to save.

For SQLite, choose SQLite as Server type and point to the database file under File, or use Browse…. No login or database list is needed. The file must already exist.

The password is stored encrypted for your Windows account and is never written in plain text to disk or logs. Right-click a connection for Use in active tab, Refresh, Edit… and Delete.

Connecting a query to the database

Each tab has its own connection, shown below the editor. Choose Use in active tab on the connection, or drag a table into the editor. Disconnect removes the connection from the tab. A new connection is used automatically in the current tab if it doesn't have one already.

The schema tree

Below the connection are Tables and Views with columns (with type, primary and foreign keys) and relationships. Drag a table into the editor to insert Customers.Take(100) – on an empty line it becomes Customers.Take(100).Dump();. Drag a column to insert the name of the property.

Tables in your code

When the tab has a connection, the tables are available directly in code as LINQ sources (linq2db). Classes get singular names and tables plural ones, for example the class Customer and the table Customers. Tables outside the default schema (dbo, public or main in SQLite) get the schema in front: Sales_Order. Foreign keys become navigation properties, so order.Customer.Name works.

Customers
    .Where(c => c.City == "Oslo")
    .OrderBy(c => c.Name)
    .Select(c => new { c.Name, Orders = c.Orders.Count() })
    .Take(20)
    .Dump();

• See exactly which SQL ran in the SQL view.
• Insert new rows with this.Insert(new Customer { … }). There is no SaveChanges.
• If the database has changed, choose Refresh on the connection. The schema is stored locally, so the tables are known even when the server doesn't respond.
• ■ Stop also cancels a database query that takes a long time.

NuGet packages and DLLs

Click References… in the toolbar. The packages apply to the query in the active tab and are stored in the .qpad file.

• Type in the search box, for example newtons. All enabled sources are searched at once, and each hit shows which source it comes from.
• Check Include prerelease for prerelease versions. Pick another version in the list next to the hit if you don't want the latest stable one.
• Add downloads the package with its dependencies right away. If the query has another version, the button says Update. Remove a package under Installed packages.
• Add your own DLLs under Assemblies with Add DLL….
• Packages are downloaded once and stored locally. The first run after a package is added shows “Restoring packages…”.

Private package sources

Under Sources… you add your own sources, for example an Azure DevOps feed. Enter a name and the URL of index.json (v3), and optionally a user name and password or a personal access token (PAT). Passwords and PATs are stored encrypted for your Windows account. nuget.org is built in and can be turned off, but not removed. On first start, the sources are read from your nuget.config.

Settings and storage

Edit → Settings… has three options:

• Theme: System (follow Windows), Light or Dark. With System, QPad follows the Windows setting while the app is running.
• qPad folder: the folder shown as My qPads and suggested when you save. Use default goes back to Documents\QPad.
• Error reports: whether errors in QPad are sent to qpad.no. See Error reports.

This is where QPad stores its files:

Error reports

When something goes wrong – an exception in the script, an error in QPad or a schema that can't be read – a report is saved in %LOCALAPPDATA%\QPad\errors. Below the error message it says “Saved for troubleshooting”, with a link that shows the file in File Explorer.

The report contains the error message, the code as it was when you ran it, the run mode, packages and which database it concerned. It never contains passwords or connection strings. Attach the file if you report an error. The 200 newest are kept.

Sending to qpad.no

Errors in QPad itself are sent to qpad.no so they can be fixed. The first time you start QPad, you are asked whether you want to send errors. You can change your choice at any time under Edit → Settings… → Send error reports to qpad.no.

• What is sent: the error message with stack trace, the QPad, .NET and Windows versions, and the query you ran (code, run mode, packages and database type).
• What is never sent: passwords, connection strings, names of servers, databases, connections or files. Your user folder (C:\Users\…) is masked.
• What stays on your machine: errors in your own code and errors from the database or the network, such as a wrong password or a server that doesn't respond. They are only stored locally.

Keyboard shortcuts

License and activation

QPad is free. Everything works without a license, except IntelliSense: code completion, parameter info and info when you hover over a name. Register your e-mail address and you get a license key by e-mail, for example AB12-CD34.

1. Click Activate license in the top right corner of QPad.
2. Enter your e-mail address and the key from the e-mail, and press Activate.
3. QPad contacts qpad.no once to activate. After that, the license is stored and works offline.

The top right corner now shows who the license is registered to. Click there to see the details or activate again, for example with another e-mail address. The license applies to the Windows user and the machine it was activated on; on a new machine, activate with the same key.

On activation, the e-mail address, the QPad version, the Windows version and an anonymous machine ID (not the machine name) are stored.

With an activated license, Feature request appears in the top right corner. There you can describe functionality you are missing and press Submit. The request is sent to qpad.no and stored with your license, so we can get in touch if anything is unclear.

Tips and troubleshooting

The installer stops and asks for the .NET 10 Desktop Runtime

Download “.NET Desktop Runtime” (x64) from dotnet.microsoft.com, install it and run the QPad installer again.

Code completion shows no documentation for .NET methods

The documentation comes with the .NET 10 SDK. Install the SDK and it appears. Everything else works without it.

“The connection this query uses no longer exists”

The connection the query was saved with doesn't exist on this machine. Choose Use in active tab on one of your own connections.

The tables don't show up in code completion

Check that the tab is connected to the database (the line below the editor). If the table is new, choose Refresh on the connection.

A query hangs

Press Shift+F5. If it doesn't stop by itself within two seconds, the process is ended.

Extension methods don't work in C# Program

In C# Program the classes are placed inside the query, and then they can't contain extension methods. Use C# Statements, or write a complete file with its own static Main.