/// <summary>
/// Creates instances of available extensions that extend the specified extension point and match the specified filter.
/// </summary>
/// <param name="extensionPoint">The extension point for which to create extensions.</param>
/// <param name="filter">An <see cref="ExtensionFilter"/> used to limit the result set to extensions with particular characteristics.</param>
/// <param name="justOne">Indicates whether or not to return only the first matching extension that is found.</param>
/// <returns>A set of extension instances.</returns>
/// <remarks>
/// Available extensions are those which are both enabled and licensed.
/// If <paramref name="justOne"/> is true, the first matching extension that is successfully instantiated is returned,
/// an no other extensions are instantiated.
/// </remarks>
public object[] CreateExtensions(ExtensionPoint extensionPoint, ExtensionFilter filter, bool justOne)
{
// get subset of applicable extensions
var extensions = ListExtensionsHelper(extensionPoint, filter);
// attempt to instantiate the extension classes
var createdObjects = new List <object>();
foreach (var extension in extensions)
{
if (justOne && createdObjects.Count > 0)
{
break;
}
try
{
// instantiate
var o = Activator.CreateInstance(extension.ExtensionClass.Resolve());
createdObjects.Add(o);
}
catch (Exception e)
{
// instantiation failed
// this should not be considered an exceptional circumstance
// instantiation may fail by design in some cases (e.g extension is designed only to run on a particular platform)
Platform.Log(LogLevel.Debug, e);
}
}
return(createdObjects.ToArray());
}
/// <summary>
/// Lists the available extensions, that also match the specified <see cref="ExtensionFilter"/>.
/// </summary>
/// <returns>An array of <see cref="ExtensionInfo" /> objects describing the available extensions.</returns>
/// <remarks>
/// Available extensions are those that are both enabled and licensed for use.
/// </remarks>
public ExtensionInfo[] ListExtensions(ExtensionFilter filter)
{
return(ListExtensionsHelper(filter));
}
/// <summary>
/// Protected method that actually retrieves the <see cref="ExtensionInfo"/>
/// objects from an internal <see cref="IExtensionFactory"/>.
/// </summary>
protected ExtensionInfo[] ListExtensionsHelper(ExtensionFilter filter)
{
// we assume that the factory itself is thread-safe, and therefore we don't need to lock
// (don't want to incur the cost of locking if not necessary)
return(_extensionFactory.ListExtensions(this, filter));
}
/// <summary>
/// Protected method that actually performs the extension creation
/// from an internal <see cref="IExtensionFactory"/>.
/// </summary>
protected object[] CreateExtensionsHelper(ExtensionFilter filter, bool justOne)
{
// we assume that the factory itself is thread-safe, and therefore we don't need to lock
// (don't want to incur the cost of locking if not necessary)
return(_extensionFactory.CreateExtensions(this, filter, justOne));
}
/// <summary>
/// Instantiates each available extension that also matches the specified <see cref="ExtensionFilter" />.
/// </summary>
/// <remarks>
/// Attempts to instantiate each matching extension. If an extension fails to instantiate
/// for any reason, the failure is logged and it is ignored. Note that only extensions that are enabled
/// and licensed are considered.
/// </remarks>
/// <returns>An array of references to the created extensions. If no extensions were created
/// the array will be empty.</returns>
public object[] CreateExtensions(ExtensionFilter filter)
{
return(CreateExtensionsHelper(filter, false));
}
/// <summary>
/// Instantiates an extension that also matches the specified <see cref="ExtensionFilter" />.
/// </summary>
/// <returns>A reference to the extension.</returns>
/// <exception cref="NotSupportedException">Failed to instantiate an extension.</exception>
/// <remarks>
/// If more than one extension exists, then the type of the extension that is
/// returned is non-deterministic. If no extensions exist that can be successfully
/// instantiated, an exception is thrown. Note that only extensions that are enabled
/// and licensed are considered.
/// </remarks>
public object CreateExtension(ExtensionFilter filter)
{
return(AtLeastOne(CreateExtensionsHelper(filter, true), this.GetType()));
}
private List <ExtensionInfo> ListExtensionsHelper(ExtensionPoint extensionPoint, ExtensionFilter filter)
{
// ensure extension map has been constructed
BuildExtensionMapOnce();
List <ExtensionInfo> extensions;
if (_extensionMap.TryGetValue(extensionPoint.GetType(), out extensions))
{
return(CollectionUtils.Select(extensions,
extension => extension.Enabled && extension.Authorized && (filter == null || filter.Test(extension))));
}
return(new List <ExtensionInfo>());
}
/// <summary>
/// Lists all available extensions for the specified <paramref name="extensionPoint"/> that match the specified <paramref name="filter"/>.
/// </summary>
/// <param name="extensionPoint">The extension point for which to retrieve a list of extensions.</param>
/// <param name="filter">An <see cref="ExtensionFilter"/> used to limit the result set to extensions with particular characteristics.</param>
/// <returns>A list of <see cref="ExtensionInfo"/> objects describing available extensions.</returns>
/// <remarks>
/// Available extensions are those which are both enabled and licensed.
/// </remarks>
public ExtensionInfo[] ListExtensions(ExtensionPoint extensionPoint, ExtensionFilter filter)
{
return(ListExtensionsHelper(extensionPoint, filter).ToArray());
}
