Event Provider API

This document details the API for building Event Provider extensions for Wealth-Lab 8. An Event Provider provides data points that are based on events that occur on specific dates. Some examples of appropriate events are:

• Fundamental items such as dividends, splits, and earnings
• Analyst ratings
• Chart or candlestick patterns
• News

Build Environment

You can create an Event Provider in a .NET development tool such as Visual Studio 2022. Create a class library project that targets .NET8, then reference the WealthLab.Core library DLL that you'll find in the WL8 installation folder.

Note: If you are using Visual Studio 2022, it will need to be updated to at least version 17.8.6 to use .NET8.

Your Event Provider will be a class in this library that descends from EventProviderBase, which is defined in the WealthLab.Core library, in the WealthLab.Data namespace. After you implement and build your library, simply copy the resulting assembly DLL into the WL8 installation folder. The next time WL8 starts up, it will discover your Event Provider, making it available in appropriate locations of the WL8 user interface.

Accessing the Host (WL8) Environment

The IHost interface allows your extension to access information about the user's WealthLab environment. For example, the location of the user data folder, or obtaining a list of DataSets defined by the user. At any point in your extension's code base, you can access an instance of the IHost interface using the singleton class WLHost and its Instance property. Example:

//get user data folder
string folder = WLHost.Instance.DataFolder;

Configuration of an Event Provider

EventProviderBase ultimately descends from the base class Configurable, which provides a way to allow the user to configure the Historical Data Provider. Consult the Configurable class reference for details.

By default, EventProviderBase assigns the enum value ParameterList to its ConfigurableType property, so the Event Provider will use a ParameterList containing Parameter instances for configuration. You'll define these Parameters in the GenerateParameters method.

You can create Parameter instances to represent things like user names, passwords, or API keys. When the user configures your Provider, WL8 will show a dialog box allowing them to enter appropriate, typed, values for each Parameter instance.

You are free to change the ConfigurableType to the alternate option of VanillaString, in which case you'll need to work directly with the Configuration string rather than the Parameters instances. In this case, you'll need to create your own Editor, see the topic on Providing User Interfaces for WealthLab 8 Components for details.

Important Descriptive Properties

The Configurable class provides descriptive properties that control how your Event Provider appears in WL8. The most important ones to override are Name, GlyphResource, Description, and URL.

Initialization

public virtual void Initialize()

If your Event Provider requires any kind of initialization before use, you can override this method and implement it here.

Returning Event Data

public abstract List<string> ItemNames

Override this property to return a List containing the names of each type of event your Event Provider supports. These values should correspond to the Name property of the EventDataPoint instances that your EDP will eventually create and return in GetNewEventData below.

For example, if your Event Provider will return stock split and dividends, you might return a list containing the strings "Split" and "Dividend".

protected abstract void GetNewEventData(BarHistory bh, DateTime lastUpdateDate)

WL8 calls this method when it attempts to download fresh events from your Event Provider. The lastUpdateDate parameter contains the most recent DateTime for which data is already available. This will contain a value only if your Event Provider makes use of the persistent storage mechanism (see below). If lastUpdateDate is not DateTime.MinValue, you should add new events that occurred after this date only.

Your Event Provider should collect the events from its source, and create instances of the EventDataPoint class (or a class derived from it) for each event. Your Event Provider should add these EventDataPoint instances to the BarHistory instance passed in the bh parameter, using the Add method of its EventDataPoints property.

WL8 will call your Event Provider's GetNewEventData method from multiple threads in a parallel processing mode. For this reason, you should generally avoid accessing class level variables in GetNewEventData. Rather, use variables that are defined in the method itself.

Persistent Storage Option

public virtual bool UsesPersistentStorage

Returns false by default. Override this and return true to utilize the built-in persistent storage mechanism in your Event Provider. You'd typically do this if your Event Provider procures data from a remote service, and you'd like to keep a copy of the data locally to avoid redundant requests.

protected abstract List<EventDataPoint> ConvertEventItems(EventDataCollection fdc)

If your Event Provider opts into the persistent storage mechanism, WL8 will store the collected event data locally, as instances of the EventDataPoint class. When it comes time to request updated information, WL8 reads these instances back into an EventDataCollection class instance.

Your Event Provider may use custom classes derived from EventDataPoint to represent its event data. In the ConvertEventItems method, you should enumerate through all of the EventDataPoint instances in the fdc parameter, examine their Name property, and create instances of the correct derived class, adding them to the List which is ultimately returned from this method.

public virtual EventDataCollection ReadFromStorage(string symbol, bool metaDataOnly)
public virtual void WriteToStorage(string symbol, List<EventDataPoint> lst)

By default, WL8 stores the event data in a binary file format, in files with the QF extension. If you want to implement your own storage mechanism in your Event Provider, you can override these two methods.

Provider Update Option

 public override bool SupportsBulkUpdate

This property determines whether or not your Event Provider supports Provider-wide updates from within the WL8 Data Manager. This allows the Data Manager to update event data for all symbols at one time. In practice, the default behavior will update symbols that already have at least some event data downloaded already.

By default, this property returns the value of the UsesPersistentStorage property. If you use the built-in persistent storage mechanism, you can leave this as is and enjoy the benefit of the built-in Provider Update behavior. If, however, you do not use the built-in mechanism, but would still like to support Provider Update, override the methods below.

public override void PerformBulkUpdate(IBulkUpdateHost updateHost)

Implement the logic to update all of the symbols for your Event Provider here, communicating the status of the update by making callbacks to the updateHost instance of the IBulkUpdateHost interface that is passed as a parameter.

public override void CancelBulkUpdate()

WL8 calls this method when the user has canceled a Provider Update. Override this to cancel your Provider-specific update routine.

public virtual List<string> GetSymbols()

Returns the symbols that already have at least some event data persisted. If you override the default persistent storage mechanism (ReadFromStorage and WriteToStorage), you should also override this method to return the symbols that have event data.