Promptu Launcher - Rocket Your Productivity

Home Help Feedback About Download

API help topics

API Overview
Writing External Functions
ValueList Class
ValueListItem Class

Writing external functions

External .NET functions greatly expand the possibilities and power of Promptu. You can do things like create directories, get the current day, month, or year, tailor behavior depending on the particular computer, or even provide suggestion values for parameters.

Important: If you write an assembly that depends one or more assemblies, all of those assemblies that are not in the GAC will need to be added as assembly references in the Promptu setup dialog in order for Promptu to load them when necessary and also to synchronize them if the list is shared.

It is also important to increment assembly build numbers when you revise an assembly, so the correct version of the assembly will be loaded when another assembly depends on it.

External functions:

  • Exist in instance (not static) classes.
  • Take any number of string parameters.
  • Return a string, string[], or ZachJohnson.Promptu.UserModel.ValueList. The return value may be null (Nothing in VB.NET). Only functions which return a string may be invoked from the prompt.

    null is always treated like an empty string, except when the function is invoked from the prompt, in which case a null return value means "do not open the message box".

A few simple examples (C#)

The following is an example from Promptu's CommonFunctions library of a function that returns System.DateTime.Now.ToString(string format), formatted according to the format string provided as a parameter:

public string DateTimeNowToString(string format)
    return DateTime.Now.ToString(format);

The following is also an example from Promptu's CommonFunctions library. This is a function that returns a ValueList containing the names of all the currently running processes:

public ValueList GetCurrentProcesses()
    ValueList valueList = new ValueList();
    foreach (Process process in Process.GetProcesses())
        string name = process.ProcessName;
        if (!valueList.ContainsValue(name))
            valueList.Add(new ValueListItem(name));

    return valueList;

CommonFunctions library source code

If you would like to see more working examples of external functions, Promptu's CommonFunctions library source code is available for download.

A more complex ValueList function example (C#)

The following example shows a sample of the power behind the ability to return a ValueList from an external function. It connects to a SQLite database using a provided connection string and populates a ValueList using the results from a provided query. This example could be modified to use a database provider other than SQLite. Here's how to make this example work:
  1. Create a new C# class library project named SqlInterface in the .NET integrated development environment (IDE) of your choice. SharpDevelop is a good .NET IDE (and it's free), if you do not already have one.

  2. Download the latest release of SQLite.NET.

  3. Add a reference to Promptu.exe and System.Data.SQLite.dll (from SQLite.Net).

  4. Paste the following code into a file in your IDE, creating a new file if necessary.

    using System;
    using System.Data;
    using System.Data.SQLite;
    using ZachJohnson.Promptu.UserModel;
    namespace SqlInterface
        public class SqlConnector
            public ValueList GetListFromDB(string connectionString, string query)
                if (connectionString == null)
                    throw new ArgumentNullException("connectionString");
                else if (query == null)
                    throw new ArgumentNullException("query");
                DataTable table = new DataTable();
                // Connect to the database and fill 
                // the table with the query results.
                SQLiteDataAdapter adapter = new SQLiteDataAdapter(
                // If the query returned more than one column, 
                // the second column will be the translation value.
                bool useTranslations = table.Columns.Count > 1;
                ValueList valueList = new ValueList(
                if (table.Columns.Count > 0)
                    foreach (DataRow row in table.Rows)
                        string value = row[0].ToString();
                        string translation;
                        if (useTranslations)
                            translation = row[1].ToString();
                            translation = String.Empty;
                        valueList.Add(new ValueListItem(
                return valueList;

  5. Compile the project (typically you can do this by hitting F6)

  6. In the Promptu setup dialog, add an assembly reference to the compiled SqlInterface.dll (which typically can be found under \bin\debug\ or \bin\release\ in your project's folder) and to System.Data.SQLite.dll

  7. In the Promptu setup dialog, add a function with the following configuration:

    Name: GetListFromDB
    Assembly: Whatever you named the reference to SqlInterface.dll
    Class: SqlInterface.SqlConnector
    Method: GetListFromDB
    Return: ZachJohnson.Promptu.UserModel.ValueList
    Parameters: Add two parameters with the default configuration.

  8. Now you are all set to get a ValueList from a SQLite database. You can test it using the Test Function button in the Function Editor.

    • If you want to configure a command parameter to use GetListFromDB and have not done so already, add a new entry in the Parameter information section of the command editor (only shown if parameters have been specified in Target, Arguments, or Working directory) and specify the parameter number or range you want the returned ValueList to be used for.

    • If you want to configure a function parameter to use GetListFromDB, locate the parameter in Parameters section that you want the returned ValueList to be used for.

    Then, in either case, select the Function return value as the Suggestion mode and enter the following expression in the dialog that appears:

    GetListFromDB("connectionString", "query")
    Where connectionString is the connection string and query is the query selecting the data.

    If you do not have a SQLite database to test the function, you can run the following C# code to create one:

    SQLiteConnection connection = new SQLiteConnection(
        "data source=C:\\tmp\\sqltest.db");
    SQLiteCommand tableCreationCommand = new SQLiteCommand(
        "CREATE TABLE IF NOT EXISTS MyValues (value TEXT, translation TEXT)", 
    SQLiteCommand insertCommand = new SQLiteCommand(
        "INSERT INTO MyValues (value, translation) " +
    	"VALUES ('value1', 'value1Translation')",
    insertCommand = new SQLiteCommand(
        "INSERT INTO MyValues (value, translation) " +
    	"VALUES ('value2', 'value2Translation')",
    To test the GetListFromDB using the created database, you would execute the function with "data source=C:\\tmp\\sqltest.db" as the connection string and "SELECT value,translation FROM MyValues" as the query.

Documenting your functions

If your function takes a number of parameters, or you will be sharing your function with others, you may consider documenting it. Function documentation is shown in the info tooltips at the prompt and in the Available Functions dialog that is accessed from the command editor.

There are two documentation attributes provided in Promptu.exe:

  • ZachJohnson.Promptu.DocumentationAttribute
    This is the basic documentation attribute. The constructor takes a string containing the documentation.

  • ZachJohnson.Promptu.ParameterDocumentationAttribute
    This is the basic parameter documentation attribute. The constructor takes the zero-based index of the parameter and a string containing the documentation.

    Example Usage:

    [Documentation("This is my really interesting documentation.")]
    [ParameterDocumentation(0, "This is documentation about parameter 0.")]
    public string MyFunction(string value)

    <Documentation("This is my really interesting documentation.")> _
    <ParameterDocumentation(0, "This is documentation about parameter 0.")> _
    Public Function MyFunction(String value) As String
    End Function

    If you need to extend DocumentationAttribute or ParameterDocumentationAttribute, inherit from them and override GetDocumentation().