Overview

The first time you deploy a new package there are several steps you'll need to follow:

1. Packaging: Extensions must be put in a NuGet package to be loaded by Loupe.
2. Registering: The Package is imported into the Extension Store on the Loupe installation you want to use it with.
3. Enabling: Once registered and Loupe is restarted you can enable and configure the package.  The first time a package is enabled Loupe needs to be restarted again to load it.

Review each step in more detail below.

Packaging Extensions

Loupe Extensions have to be placed in NuGet packages.  This lets Loupe take advantage of the packaging, metadata and versioning capabilities of NuGet.  For a general guide on creating NuGet packages, see Creating and Publishing a Package.  All dependency files have to be included in the package as dependency resolution isn't supported.  Here's an example NuSpec file for an Extension:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>Loupe.Extension.Sample</id>
    <version>4.0.0.0</version>
    <title>Sample Extension</title>
    <authors>Gibraltar Software</authors>
    <owners>Gibraltar Software</owners>
    <iconUrl>http://www.gibraltarsoftware.com/loupe.ico</iconUrl>
    <licenseUrl>http://www.gibraltarsoftware.com/Support/Documentation.aspx?Page=Reference_GibraltarAgentLicense.html</licenseUrl>
    <projectUrl>http://www.gibraltarsoftware.com</projectUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>This is a sample extension used to demonstrate basic extension development</description>
    <summary />
    <tags>Loupe Logging</tags>
  </metadata>
</package>

The following fields are particularly important:

• id: This is the Loupe Extension name.  It must be unique for all extensions on the same installation.  It must also match the assembly name for the extension (without the .dll extension).
• version: The version number of the extension.  The highest version installed on the server will be used.
• title: The display caption for the extension.
• description: An extended description of the extension.

The extension assembly and all dependency files must be in the package in the same library group (e.g. lib/net45).  If you create a package with the NuGet command line utility referencing your extension project it will tend to put the files in the correct library group, although you'll have to manually add all of the dependency assemblies to the NuSpec file.

How Extensions are Identified

When looking at a NuPkg file, Loupe looks for:

1. An Assembly with the package Id: Whatever the Id is as specified in the NuSpec file it must match the extension assembly (once .dll is added; for example Loupe.Extension.Sample would require an assembly named Loupe.Extension.Sample.dll)
2. Public Classes:  Internal and private classes will not be loaded.
3. Implementing the identifying attribute:  Each extension is identified by having the LoupeExtensionAttribute which provides type information without requiring it to be instantiated.  If this attribute is left off the class will be ignored.
4. With the correct interface:  If the public class has the right attribute but doesn't implement the IExtensionDefinition Interface then it will not be loaded.  When your extension is initialized it has to declare all of the types of the various other extensions that are part of it which will also be checked that they implement the correct interface before they are added.

Registering Extensions

Once you've packaged your extension it has to be imported into the Loupe Server installation to make it available.  This is done using the Loupe Server Administrator.  After launching the Loupe Server Administrator:

1. Select the Extension Store from the tree view on the left.  The extension store contains all packages used throughout the Loupe installation.
2. Click Add Package from the Extension Store ribbon and select the .NuPkg file you created.  It doesn't matter what the file name is, it will be automatically renamed in the extension store to reflect the unique extension name and version combination.
3. If the package is a valid Loupe Extension it will be added to the package list in the store.  If there is a problem with the package the message will give some feedback on what was missing so you can modify your package.
4. Restart the Loupe Server Administrator if you want to enable the extension using Loupe Server Administrator.  Otherwise, it can be done using Loupe Desktop.  It is generally necessary to restart the Loupe Service and Web Site for new extensions to be found.

You can have multiple versions of the same extension registered.  This is useful while upgrading - it's best to add the new version and make sure all parts of the Loupe Server infrastructure have switched to it before removing the old version.  If you want to roll back, just remove the newer version and on startup Loupe will revert to the prior version.

Enabling and Configuring Extensions

Once an extension has been imported into the extension store on the server they have to be enabled for each repository where you want to use them (In Standard Edition there is just one repository).  If an extension doesn't require user configuration it can be enabled in Server Administrator, otherwise you will have to use Desktop. 

Using Server Administrator

1. (Enterprise Edition): Expand the server repository you want to configure extensions for in the tree view on the left.
2. Click Extensions under the repository in the tree view on the left.
3. Select the extension you want to enable or configure.  When enabling an extension that uses configuration you will need to provide a valid configuration and press OK for it to be enabled.
4. If you just enabled an extension for the first time you will have to restart the Loupe Service for it to be recognized.

Using Desktop

1. Select the server repository you want to configure extensions for in the tree view on the left.
2. Click Extensions in the Server area of the ribbon to display the Manage Extensions Dialog.
3. Select the extension you want to enable or configure.  When enabling an extension that uses configuration you will need to provide a valid configuration and press OK for it to be enabled.
4. Click OK to close the Manage Extensions dialog.  You will be prompted to restart Loupe Desktop if the change requires it.

Implementation Notes

• Do not register the Loupe.Addin NuGet Package.  While Loupe will let you register most NuGet packages, only those that contain a Loupe extension should be registered.
• Do not include the Loupe.AddIn.dll assembly.  It is automatically loaded by Loupe and its reference version should always be loaded, not a copy redistributed by you.
• Be sure the Package Id Matches the Extension assembly.  Loupe looks in the package for an assembly with the name matching the package Id (plus .dll). If it doesn't find any such assembly or the assembly it finds doesn't include a Loupe Extension implementation the extension will not load.