Skip to main content

Data-Sources

DataSources are generic implementation for a source of any data. The name "Data" is a bit misleading in this context, as a DataSource can also execute specific actions with no input- nor output-data. The meaning is, that a DataSource can be consumed by eg a Endpoint to allow a particular DataSource be accessed over a HTTP-Endpoint.

Overview​

A custom DataSource consists always of implementations of the following interfaces:

  • IDataSourceProvider
  • IDataSource

The IDataSourceProvider is used to generate / get all DataSourceDefinitions for this particular DataSourceProvider and must be able to generate a instance of a IDataSource for a given DataSourceKeyModel.

The IDataSource on the other hand provides the access to a specific data or functiionality of the system. It consists of a list of supported actions (custom-defined strings) and has a ExecuteAction(string action, JObject input) method to execute the given action.

Here is a overview of the used interfaces and classes:



This generic construct allows to handle both simple CRUD- but also complex code-execution-functionality. There are already some implementations available that can be used as an example.

DataSource Keys​

The system works generally with DataSource Keys (string) to identify a specific DataSource with a specific configuration and a specific action. So a DataSourceKey can uniquely identify exactly one possible action on a DataSource. Only this way, we can simplify eg the Endpoint-Configuration to only specify a DataSourceKey for the target, without specifying additional configurations (eg a action name).

By default, a DataSourceKey is defined as follows:
<provider-type-discriminator>::<data-source-type-discriminator>::<action-discriminator>

Here are some examples of DataSourceKey's:

  • DataSourcesDataSourceProvider::DataSourcesDataSource::get-all
  • SearchIndexingDataSourceProvider::SearchIndexingDataSource<UserModel>::reindex
  • PrimaryEntityStructureDataSourceProvider::PrimaryEntityStructureDataSource<CompanyModel>::create
  • RelatedEntityStructureDataSourceProvider::RelatedEntityStructureDataSource<UserLoginModel>::definition

DataSourceKey and DataSourceKeyModel​

The DataSourceKey generally is a string that can be easily serialized and used in other definitions (eg the Endpoint-Definition). To use this key again in a decomposed state, there is the DataSourceKeyModel that is decomposed using the IDataSourceKeyManager. The decomposed model contains now the three parts of the source key to be used to easily identify eg the used action.

Create your own​

To define your own DataSource, you need to implement both the IDataSourceProvider and the IDataSource interfaces and finally register the IDataSourceProvider implementation in the ServicesCollection of your DI-Container.

Provider implementation​

Your IDataSourceProvider implementation should always derive from BaseDataSourceProvider<TConfiguration> to have a good starting-point for a provider. There you have to implement the following:

LoadDataSourceKeysAndConfigurations()​

This method must return a list of DataSourceKeys (string) and the configuration for this DataSource.

GetDataSourceDefinitions()​

This method creates all possible DataSourceDefinitionModels for the current DataSourceProvider. Always first call the await EnsureKeyConfigurationCache() method and iterate over the property KeyConfigurationCache to get the previously generated keys and statically create the DataSourceDefinitionModels.

CreateDataSource(IServiceProvider, TConfiguration, DataSourceKeyModel)​

This method must initialize a new IDataSource instance for the given DataSourceKeyModel (the resolved DataSourceKey string).

warning

Always create a new instance of the IDataSource implementation when using this method, as multiple DataSources with slightly changed configurations can be requested in parallel.

DataSource implementation​

Registration​

To have your DataSource implementation registered and available in the system, it must be registered using the IServiceCollection extension-method AddDataSourceProvider<TDataSourceProvider>():

services.AddDataSourceProvider<YourDataSourceImplementation>();

Existing implementations​

DataSourcesDataSource​

The mother of all DataSources 😊 provides a DataSource that returns all available DataSource-Keys for the current system.

PrimaryEntityStructureDataSource​

Generic DataSource that provides access to the EntityStructure System.

EntityStructureValidatorsDataSource​

A DataSource that delivers all registered EntitiyStructure Validators from the system.