What Files do you Need?

File	What is it?	When would I use it?
Gibraltar.Agent.dll	The Loupe Agent library	This file should always be distributed.  It is the one file required for any Loupe functionality.  In most cases, this is all you need.
Gibraltar.Agent.xml	Intellisense Help for the Loupe Agent	Used during development to provide Visual Studio with extended Intellisense help for the Agent API.  It never needs to be distributed.
Gibraltar.Agent.EntityFramework.dll	The Loupe Agent for Entity Framework	Used with Entity Framework 6 and later to record details on each EF action and performance information.
Gibraltar.Agent.Web.dll	The Loupe ASP.NET WebForms Agent library	Used with ASP.NET WebForms applications to provide health monitoring and performance metrics.   It extends the Loupe Agent, so if distributed the Agent must also be distributed.  ASP.NET applications can log and record performance and custom metrics without using this library; it provides built in ASP.NET unique capabilities.
Gibraltar.Agent.Web.Mvc.dll	The Loupe ASP.NET MVC and Web API Agent library	Used with ASP.NET MVC and Web API applications to provide health monitoring and performance metrics.   It extends the Loupe Agent, so if distributed the Agent must also be distributed.  ASP.NET applications can log and record performance and custom metrics without using this library.
Gibraltar.Package.exe	The stand-alone Loupe Packager for .NET 2.0	This provides a standalone executable for running the Loupe Packager for applications targeting .NET 2.0 to .NET 3.5.  This is particularly useful for ASP.NET and windows service applications that can't use the built-in Packager dialog in the agent.  You can also use it to avoid having to change your application code to access the Packager through the Agent API.  The Packager depends on the Gibraltar.Agent assembly and its application config file (Gibraltar.Package.exe.config). The Packager is also required to enable the SendSessionsOnExit feature, an option that is available in the Loupe Error Manager and from the Log API.
Gibraltar.Package.exe.config	Configuration file for the Loupe Packager for .NET 2.0	An example configuration file for the Loupe Packager.  You must modify the settings in this file if you deploy the Loupe Packager for the purpose of directly having users run it to package and send information.  If you are only distributing the Packager to enable SendSessionsOnExit this configuration file is unnecessary.
Gibraltar.Package.NET40.exe	The stand-alone Loupe Packager for .NET 4.0	This provides a standalone executable for running the Loupe Packager for applications targeting .NET 4.0 and later.  This is particularly useful for ASP.NET and windows service applications that can't use the built-in Packager dialog in the agent.  You can also use it to avoid having to change your application code to access the Packager through the Agent API.  The Packager depends on the Gibraltar.Agent assembly and its application config file (Gibraltar.Package.exe.config). The Packager is also required to enable the SendSessionsOnExit feature, an option that is available in the Loupe Error Manager and from the Log API.
Gibraltar.Package.NET40.exe.config	Configuration file for the Loupe Packager for .NET 4.0	An example configuration file for the Loupe Packager.  You must modify the settings in this file if you deploy the Loupe Packager for the purpose of directly having users run it to package and send information.  If you are only distributing the Packager to enable SendSessionsOnExit this configuration file is unnecessary.

Third party integration modules are not included in the list above.  For more information on specific third party integration, see Developer's Guide - Third Party Integration - Introduction.

Merging Loupe with your Assembly

The Loupe Agent can also be merged into your executable using ILMerge, a free utility from Microsoft.  If you do this, please be aware that:

• The assembly name used by every type reference in the configuration file documentation will need to be changed from Gibraltar.Agent to your assembly.
• Calling class and method information may not work as you expect in certain cases.
• Agent Version information recorded in the session will not be accurate.

Because of these issues it is not recommended that you merge the agent into your assembly.  If you have a deployment scenario that requires merging the assembly, please contact us so we can investigate possible alternatives and improve the agent.

Agent Configuration

You can configure the Agent from its API or by modifying your application configuration file (app.config or web.config). 

• For an overview of editing your App.Config to associate Loupe with your application, see Getting Started - Adding Loupe to your Application .
• For details on the different configuration options see Developer's Guide - Agent Configuration.

User Permissions

Wherever possible, the Agent is designed to work even as a guest on the operating system so no elevated access is required.  The one exception for this are full performance counters which do require additional access to work.  The Agent will ignore these counters and continue running if they aren't accessible.  For more information on the permissions required for performance counters, see Developer's Guide - Metrics - Performance Counters.

Packager Deployment

The Loupe Packager is a single file assembly (Gibraltar.Package.exe or Gibraltar.Package.NET40.exe) that works with the agent.  To keep the deployment size as small as feasible, the Packager depends on the agent and requires that Gibraltar.Agent.dll be distributed in the same directory.  Be sure to pick the version of the packager that applies to the .NET framework you are targeting.  If you are targeting a version of .NET prior to 4.0 use Gibraltar.Package.exe, otherwise Gibraltar.Package.NET40.exe.

There are two reasons to distribute the Loupe Packager:

1. To enable SendSessionsOnExit:  This feature relies on being able to start a lightweight process near the end of your application's life to package and send information after your application closes.  All configuration information is passed across via command line options in this scenario.
2. To enable standalone Packaging:  In scenarios where you want to provide a graphical packaging experience for the end user but are not running from a WinForms or WPF application the Packager utility can be run to provide that user experience.

If you intend to employ the second scenario above you will should edit the provided config file to provide it with the product name & application name you want it to gather information for, set the Server information and/or email address you want it to send packages to, and optionally disable the packaging methods you don't want used.  Customizing its configuration can improve the user experience for your customers by reducing the number of steps and choices they need to make to send you diagnostic information.  For more information see Developer's Guide - Agent Configuration.

If you are only including the Packager utility to enable SendSessionsOnExit, no configuration file is necessary because all of the configuration options are passed across from the Loupe Agent.  Instead, it's recommended to not include the configuration file.