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.

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#)

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(
                   query, 
                   connectionString);
   
               adapter.Fill(table);
   
               // 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(
                   false, 
                   useTranslations);
   
               if (table.Columns.Count > 0)
               {
                   foreach (DataRow row in table.Rows)
                   {
                       string value = row[0].ToString();
                       string translation;
                       if (useTranslations)
                       {
                           translation = row[1].ToString();
                       }
                       else
                       {
                           translation = String.Empty;
                       }
   
                       valueList.Add(new ValueListItem(
                           value, 
                           translation, 
                           useTranslations));
                   }
               }
   
               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");
   connection.Open();
   
   SQLiteCommand tableCreationCommand = new SQLiteCommand(
       "CREATE TABLE IF NOT EXISTS MyValues (value TEXT, translation TEXT)", 
       connection);
   tableCreationCommand.ExecuteNonQuery();
   
   SQLiteCommand insertCommand = new SQLiteCommand(
       "INSERT INTO MyValues (value, translation) " +
   	"VALUES ('value1', 'value1Translation')",
       connection);
   insertCommand.ExecuteNonQuery();
   
   insertCommand = new SQLiteCommand(
       "INSERT INTO MyValues (value, translation) " +
   	"VALUES ('value2', 'value2Translation')",
       connection);
   insertCommand.ExecuteNonQuery();
   
   connection.Close();

   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:

  C#:

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

  VB.NET:

  <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().