Event Provider API
Updated for WL8
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
You can create an Event Provider in a .NET development tool such as Visual Studio, or Visual Studio Code.
Create a class library project that targets .NET6, then reference the
WealthLab.Core library DLL that you'll find in the WL8 installation folder.
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 for the user to select in the Data Manager, Event Providers tab.
Accessing the WL8 Host Environment
Use the WLHost.Instance property to access various aspects of the WL8 environment. See the API reference for the IHost interface for details.
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.
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.