Developer's Guide - Packager Utility
In This Topic
The Loupe Packager is a stand-alone utility that collects the session logs from the computer where it's run, assembles it into a Loupe Log Package, and can transport it via email or removable media to another computer for analysis. The Packager is available via NuGet and includes versions for older and newer versions of .NET: other
- Gibraltar.Packager.exe: For .NET 2.0 and later. Some newer operating systems don't have .NET 2.0->3.5 installed by default, so the .NET 4.0 version is recommended.
- Gibraltar.Packager.NET40.exe: For .NET 4.0 and later.
Both versions depend on Gibraltar.Agent.dll which must be in the same directory as the executable.
Loupe Packager is free, open source software and is hosted on GitHub. You can freely modify it to suit your needs (or make a request and someone else may help out!)
Packaging Sessions
To work, the packager has to determine:
- What sessions to send: Which application(s) and what sessions for those applications.
- How to send them: Via email, file, or removable media.
- Transmission options: For email, what email address to send to and what email the package should appear to come from. For file the full file name and path to use.
Most of these options can (and should) be specified in the Packager configuration file (Gibraltar.Package.config). This allows the wizard to operate in the most streamlined fashion possible for end users. For more information on the configuration options, see the Packager section in Developer's Guide - Agent Configuration.
In addition to options provided by the Packager configuration file, the Loupe Packager respects several command line options:
| Option | Name | Description |
| s | Silent Mode | When specified the packager utility will run in silent mode without any user feedback. The only way to find out what it did is to look at its log data using Loupe Desktop. |
| w | Wait on Process | If specified and followed with a Process Id of a running process it will cause the packager to wait until that process exits before proceeding to package & send data. |
| m | Send Mode |
Specifies how the package should be transported:
If using silent mode a send mode must be specified. |
| folder | Folder | Specifies a path to use for the local log files instead of the default path calculated by the Agent for the product. Be sure to quote the value if it may have an embedded space. |
| d | Destination | When mode is set to file, the full file name & path to write to (minus file extension which will always be set to the Loupe Log Package extension) Be sure to quote the value if it may have an embedded space. |
| p | Product Name | Overrides the product name configured in the Packager Configuration file. Be sure to quote the value if it may have an embedded space. |
| a | Application Name | Overrides the application name configured in the Packager Configuration file. Be sure to quote the value if it may have an embedded space. |
| server | Email / Loupe Server | Overrides the email or Loupe server (depending on mode) configured in the Packager Configuration file. If you override the server then the Port and SSL settings are also overridden and if not specified will use default values. |
| port | Email / Loupe Server Port | Overrides the email or Loupe server port (depending on mode) configured in the Packager Configuration file. Only applies if Server is also specified. |
| user | Email Server User | Overrides the email server user configured in the Packager Configuration file. If a user is specified then the password must also be specified. Only applies if Server is also specified. |
| password | Email Server Password |
Overrides the email server password configured in the Packager Configuration file. If a user is specified then the password must also be specified. Only applies if Server is also specified. Be sure to quote the value if it may have an embedded space or delimiter character. The value may not include a single our double quote. |
| ssl | Use SSL | Overrides the Secure Sockets Layer (SSL) setting configured in the Packager Configuration file. Only applies if a server is also specified. |
| repository | Loupe Server Enterprise Repository | Specifies the repository to send to for Loupe Server Enterprise Edition. Standard Edition only has a single repository so this parameter is ignored. Only applies if a server is also specified. |
| customer | Loupe Service Customer | Overrides the Loupe Server customer configured in the Packager Configuration file. If a value is specified and the mode is set to server then it will be assumed that the Loupe Service should be used and any server entry will be ignored. |
| directory | Private Loupe Server virtual directory | Overrides the application base directory configured in the Packager Configuration file. Only applies if the mode is set to server a server is also specified. |
| purgeSentSessions | Purge Sent Sessions | When used with the server Send Mode sessions will be removed from the local collection repository once they are confirmed by the server. |
These options can be used to provide a completely silent package experience without code changes. each argument option can be specified using either / or - as a delimiter. Valid command line examples include:
| Packager Utility Command Line Samples |
Copy Code
|
|---|---|
Gibraltar.Packager /s /m email /p "Your Product" /a "Your Application" /d yourName@yourcompany.com Gibraltar.Packager -s -m file -d "C:\Temp\Diagnostic Package" REM This example shows how the Loupe Agent sends sessions on exit to the Loupe Service Gibraltar.Package.NET40.exe /s /w "4088" /m server /p "Demo" /a "Client" /customer "eSymmetrix" |
|
Silent Mode
When the packager utility is started with the /s option it triggers silent mode. In this mode, the process will not raise a user interface. Because no user interface can be raised, enough information must be specified between the configuration file and the command line options to successfully select, package, and store the data.
Interactive Mode
When the packager is run normally (without the -s silent mode option) it will display the packaging wizard. Depending on the configuration options specified, the packager wizard will display three screens:
Session Selection
The user selects whether to send just unsent sessions for the specified application(s) or all information in the local sessions repository for the specified application(s). The default value is to just send unsent information.
Packager Wizard - Session Selection |
Sessions are marked as having been sent upon the successful completion of the Packager wizard. If the wizard is canceled or doesn't send the sessions successfully they will not be marked sent.
Transmission Method
The user selects where the package should be written - to an email, to a fully specified file name and path, or to removable media.
Packager - Transmission Method |
Individual options can be configured and disabled through the Packager configuration file. If the configuration file specifies all of the necessary options then the user will not be presented with this screen.
If you leave the email option enabled, you should either specify email server information in the packager configuration file or have high confidence that the .NET email server information will be specified in the machine.config file on each computer that will run the packager. Otherwise, the packager will be unable to send email. It's also recommended that the destination email address be specified.
Finish
Once the user has selected the transmission method and clicks Finish they will see a progress bar and status messages while all of the sessions are gathered, written to a package, stored in the final location, and sessions are marked as read.
Packager - Finishing |
See Also