Key Submission Methods

In this scenario, the goal is to send the data automatically in the background without the user being aware that it is being sent.  This commonly applies with:

• Corporate / private applications:  When the application is deployed in a business setting where there is a corporate or higher level decision to gather this information and there isn't implied user privacy.
• Beta and Preview builds:  Often in exchange for early access to new versions it's required to participate in providing diagnostic information

How to Configure

• Configure the Server section with the connection information on your Loupe Server.
• Set the AutoSendSessions option to True.  We also recommend you set the PurgeSentSessions option as well.

What Happens

1. As your application runs the Loupe Agent records session data locally. Once the application exits or an error occurs this session data is eligible to be sent up to the Server.
2. Whenever any instance of your application is running one will be selected by the Agent to send data to the Server. This is arbitrated in the background and will automatically shift to another instance if the active application exits.
3. The active Agent will check periodically for eligible sessions to submit to the Server.
4. When submitting sessions to the Server, first a small set of summary information is submitted.  The Server then informs the Agent whether the full session details should be submitted or not.
5. If the full session details are requested, they are transmitted to the Server using HTTP(s). 
6. If the process is interrupted (due to a network connection loss or the end of the application) it will be automatically resumed the next time the Agent can communicate with the Server. 
7. Once the Server has confirmed receipt of the session it will be removed from the local file system if the PurgeSentSessions option is enabled.

All of this happens in the background as a low priority task from within your application. 

In this scenario you have multiple applications that are all part of the same product family.  You want all of them to submit data together - as long as any of the applications is running it can submit session data recorded by any other application in the family.  This commonly applies with:

• Corporate / private applications:  When the application is deployed in a business setting where there is a corporate or higher level decision to gather this information and there isn't implied user privacy.
• Beta and Preview builds:  Often in exchange for early access to new versions it's required to participate in providing diagnostic information.
• Common Server:  All of the applications need to be identically configured to submit to the same Server.

How to Configure

• Configure the Server section with the connection information on your Loupe Server.
• Set the AutoSendSessions option to True.  Set the SendAllApplications option to True.  We also recommend you set the PurgeSentSessions option as well.

What Happens

1. As any of the applications in your product family runs the Loupe Agent records session data locally. Once the application exits or an error occurs this session data is eligible to be sent up to the Server.
2. Whenever any instance of an application in your product family is running one will be selected by the Agent to send data to the Server. This is arbitrated in the background and will automatically shift to another instance if the active application exits.
3. The active Agent will check periodically for eligible sessions to submit to the Server.
4. When submitting sessions to the Server, first a small set of summary information is submitted.  The Server then informs the Agent whether the full session details should be submitted or not.
5. If the full session details are requested, they are transmitted to the Server using HTTP(s). 
6. If the process is interrupted (due to a network connection loss or the end of the application) it will be automatically resumed the next time the Agent can communicate with the Server. 
7. Once the Server has confirmed receipt of the session it will be removed from the local file system if the PurgeSentSessions option is enabled.

All of this happens in the background as a low priority task from within your application. 

In this scenario data isn't generally flowing automatically to the Server.  Instead, you want to use it as part of an active request by an end user.  This commonly applies with:

• Commercial, widely deployed applications:  In cases where you have a very large number of users and are just interested in supporting customer service requests.
• Sensitive applications:  If your customers are very unlikely to provide a blanket authorization to collect the data or have already have declined consent.

How to Configure

• Configure the Server section with the connection information on your Loupe Server.  Do not set the AutoSendSessions option to True.
• Configure the Packager section to set the AllowServer option to True.

What Happens

Submitting Data through Code

Whenever you want to send data to the Server you can use either the Packager class or Packager Dialog (WinForms and WPF applications only).

• Packager Class:  Use the SendToServer method.  This can synchronously or asynchronously send data to the server.  If the server can't be contacted the data won't be sent and an exception will be thrown with diagnostic information.
• Packager Dialog:  (WinForms and WPF only).  Call the Send or SendToServer method.  This will prompt the user as necessary for session criteria and can fall back to sending via email or to a file if the Server is not accessible.

Submitting After an Error

You can package data automatically after your session completes by setting the SendSessionsOnExit option.  This can be done through code at any time or by the user checking the Automatically report these problems at the end of the session option in the Loupe Error Manager.  For details on the Loupe Error Manager (WinForms and WPF only) see Getting Started - Loupe Error Manager.

• Once the session is preparing to shutdown (After the EndSession call or when the .NET runtime signals that the AppDomain is starting to shut down) the Loupe Packager is started with a set of command line arguments that tell it to wait for the original process to exit and then submit all new sessions to the Server.
• The Packager process will wait for the original process to exit.
• Once the original process exits the Packager will look for sessions that have not yet been submitted and will push them to the Server.  In this mode the full session detail will be sent to the Server regardless of whether they meet the criteria set on the Server for session detail retrieval.  Only sessions that have not previously been submitted to the Server will be sent, and once sent they will not be sent a second time if SendSessionsOnExit is used again in the future.
• Once the selected sessions have been sent to the server the Packager process will exit.

For complete information on how this works, see Reference - Sending Sessions On Exit.

In this scenario the goal is to allow the user to opt into a CEIP and if they do automatically send data (like Scenario One and Scenario Two) but otherwise function in Scenario Three.  This is typical with:

• Third Party Applications:  If you are developing an application for use by users outside of your organization (such as a typical commercial or free application) it is advisable to gain their consent before submitting diagnostic information.

How to Configure

• Configure the Server section with the connection information on your Loupe Server. 
• If you are developing a Windows application (WinForms or WPF) use the built-in user opt-in feature configured with the AutoSendConsentConfiguration Class.  Otherwise programmatically set the AutoSendSessions option to True when the user has opted in, False when they haven't.  The SendAllApplications and PurgeSentSessions options can be set as indicated in Scenario One and Scenario Two.
• Configure the Packager section to set the AllowServer option to True.  This enables the Agent to fall back to Scenario Three in the event the user has opted out.

If you are not using the built-in user opt in feature of the agent then this scenario requires that the AutoSendSessions option be changed depending on the Opt In status of the user it is necessary to use the Configure Through Code strategy under the assumption that rewriting the application configuration file is generally not feasible in a deployed configuration.

What Happens (Windows applications)

• Once your main form displays and the agent has been started (typically through a call to Log.StartSession) call Log.DisplayStartupConsentDialog to allow the user to opt in or out if they already haven't.  This call is always safe. 
• The application will then behave according to Scenario One or Two if the AutoSendSessions option is set to True and the user has opted in and Scenario Three otherwise.

What Happens (Non-windows applications)

• You provide a way to have the user opt in to your CEIP and track their status.
• At application startup set the Server.AutoSendSessions option to reflect their opt in status by subscribing to the Log.Initialize event.  You can store the rest of your configuration in the configuration file if you'd prefer and just have this option set programmatically.
• The application will then behave according to Scenario One or Two if the AutoSendSessions option is set to True and Scenario Three if set to False.

Developer's Guide

Gibraltar.Agent Namespace

Gibraltar.Agent.Configuration Namespace

Reference