Log Message Commands let you link your own custom processing and user interface dialogs with one or more log messages displayed inside of the Session Viewer.  Log Message commands extend the context menu in the Log Message Grid.   For a general overview of how Extension commands work, see Loupe Extensions - Commands.

Because these commands are invoked directly by the end user from the user interface they can have their own user interface or be purely background.

What You Need to Implement

To create a Log Message Command, you need to create a class that:

• Is Public
• Implements the ILogMessageCommand Interface
• Is added by your Extension Definition during its Initialize method by calling the RegisterLogMessageCommand Method.

For more information on how classes are evaluated and loaded see Loupe Extensions - Deploying Extensions.

Extension Lifecycle

1. Before any call is made to have an extension process information its Initialize method will be called.  Then it is eligible to be invoked for processing. 
2. When an extensible part of the user interface is being composed each extension will be requested to register its commands using its RegisterCommands method.  All commands that the extension supports must be recorded during this method by calling the provided IUserInterfaceController object's RegisterCommand method. 
3. Each time an extensible part of the user interface is displayed a BeforeCommandsDisplay Method call will be made to each extension to allow for selectively enabling / disabling commands, changing labels and tooltips.  When a command is disabled it won't show in context menus.  To update a command, call the provided IUserInterfaceController object's UpdateCommand method.  It isn't necessary to update any commands - if not updated they will keep their previous configuration.
4. If a user selects a command its Process method will be invoked and passed the entire set of currently selected sessions. 
   • If the command's isUserInteractive option was set true during registration then no user interface will be provided and the command will be executed on the UI thread.  It is recommended that if this configuration is used a user interface should be provided that will appropriately perform background processing for long-running tasks to ensure the UI remains responsive.
   • If the command's isUserInteractive option was set false during registration then the command will be executed on a background thread with a progress user interface displayed to keep the user interface refreshing.  In this configuration it isn't recommended that any user interface beyond a simple message box be employed. 
5. If an extension has been loaded, even if it was never initialized, it will be disposed when it is released. 

Notes and Best Practices

Caching Information

If it's useful to cache information to improve performance the best place to do this is in your Repository Controller or Session Controller, depending on the scope of the information.  This allows the cache to be shared between all of the extensions that make up your Extension.  Your log message command can cache information however it's important to do so in a thread safe manner because the Process method must be threadsafe and re-entrant.

Session Scope

A single instance of a log message command is associated with exactly one Session Context and, if your Extension defines one, a single Session Controller.  This means its associated with a single session within a single repository (local repository, user repository, or package).  When a session is closed any related log message command object will be disposed.  You can use the context to interact with the session, repository and user interface, including displaying sessions in the session viewer and requesting that the configuration of the extension be edited.

Managing State

• Log message commands should not acquire their own state during the RegisterCommands call.  It may be made multiple times for the same instance, or never called if the instance was recreated.  Instead, state should be acquired during the Initialize call or the first Process call.
• Log message commands should not presume any direct relationship between BeforeCommandsDisplay calls and Process calls.  It is possible for BeforeCommandsDisplay to be called on one context, another, and then process be called for the first context.