Class DataSourceBase
The base class, which should always be inherited. Already implements things like Get One / Get many, Caching and a lot more.
The DataSourceBase DataSource is the base class for all Standard EAV Data Sources.
All DataSources should inherit from this.
Read also
History
- Introduced in EAV 4.x, 2sxc 6
- Enhanced with Error methods for VisualQuery 3 in 2sxc 11.13
API Documentation
Inheritance
Implements
Inherited Members
Namespace: ToSic.Eav.DataSources
Assembly: ToSic.Eav.DataSources.dll
Syntax
[PublicApi_Stable_ForUseInYourCode]
public abstract class DataSourceBase : HasLog, IDataSource, IAppIdentity, IZoneIdentity, IAppIdentityLight, ICacheInfo, ICacheKey, ICacheExpiring, ITimestamped, ICanPurgeListCache, IHasLog, IDataTarget, IDataPartShared
Constructors
| Improve this Doc View SourceDataSourceBase()
Constructor - must be without parameters, otherwise the DI can't construct it.
Declaration
protected DataSourceBase()
Fields
| Improve this Doc View SourceErrorStream
This variable contains a stream of exceptions to return as a result of the DataSource. It is available because often some inner call will have to prepare an error and can't return the stream. So the inner call will set the variable and your primary GetList() can then do a check like this:
private IImmutableList<IEntity> GetList()
{
var useMultiLanguage = GetMultiLanguageSetting();
if (!ErrorStream.IsDefaultOrEmpty) return ErrorStream;
var result = ...
return result;
}
Or if you're using Call Logging do something like this:
private IImmutableList<IEntity> GetList()
{
var callLog = Log.Call<IImmutableList<IEntity>>();
var useMultiLanguage = GetMultiLanguageSetting();
if (!ErrorStream.IsDefaultOrEmpty) return callLog("error", ErrorStream);
var result = ...
return callLog("ok", result);
}
Declaration
[PublicApi]
protected ImmutableArray<IEntity> ErrorStream
Field Value
Type | Description |
---|---|
System.Collections.Immutable.ImmutableArray<IEntity> |
Remarks
Introduced in 2sxc 11.13
Properties
| Improve this Doc View SourceAppId
The app id as used internally
Declaration
public virtual int AppId { get; set; }
Property Value
Type | Description |
---|---|
System.Int32 | The App ID this thing belongs to |
CacheFullKey
Combination of the current key and all keys of upstream cached items, to create a long unique key for this context.
Declaration
public virtual string CacheFullKey { get; }
Property Value
Type | Description |
---|---|
System.String | Full key containing own partial key and upstream keys. |
CachePartialKey
Unique key-id for this specific situation - could be the same for all instances, or could vary by some parameter.
Declaration
public virtual string CachePartialKey { get; }
Property Value
Type | Description |
---|---|
System.String | A string which is specific to this cache-item. |
CacheRelevantConfigurations
Some configuration of the data source is cache-relevant, others are not. This list contains the names of all configuration items which are cache relevant. It will be used when generating a unique ID for caching the data.
Declaration
[InternalApi_DoNotUse_MayChangeWithoutNotice]
public List<string> CacheRelevantConfigurations { get; set; }
Property Value
Type | Description |
---|---|
System.Collections.Generic.List<System.String> |
CacheTimestamp
System time-stamp of when the data in this cached thing was initialized or updated. Depending on the implementation, this may go up-stream and return an up-stream value.
Declaration
public virtual long CacheTimestamp { get; }
Property Value
Type | Description |
---|---|
System.Int64 | A timestamp as a long number |
Configuration
The configuration system of this data source. Keeps track of all values which the data source will need, and manages the LookUp engine which provides these values.
Declaration
public IDataSourceConfiguration Configuration { get; }
Property Value
Type | Description |
---|---|
IDataSourceConfiguration |
DataBuilder
Declaration
protected IDataBuilder DataBuilder { get; }
Property Value
Type | Description |
---|---|
IDataBuilder |
Guid
Internal ID usually from persisted configurations IF the configuration was build from an pre-stored query.
Declaration
public Guid Guid { get; set; }
Property Value
Type | Description |
---|---|
System.Guid | The guid of this data source which identifies the configuration IEntity of the data source. |
In
List of all In connections
Declaration
public IDictionary<string, IDataStream> In { get; }
Property Value
Type | Description |
---|---|
System.Collections.Generic.IDictionary<System.String, IDataStream> |
Item[String]
Gets the Out-Stream with specified Name.
Declaration
public IDataStream this[string outName] { get; }
Parameters
Type | Name | Description |
---|---|---|
System.String | outName |
Property Value
Type | Description |
---|---|
IDataStream | an IDataStream of the desired name |
Exceptions
Type | Condition |
---|---|
System.NullReferenceException | if the stream does not exist |
List
The items in the data-source - to be exact, the ones in the Default stream.
Declaration
public IEnumerable<IEntity> List { get; }
Property Value
Type | Description |
---|---|
System.Collections.Generic.IEnumerable<IEntity> | A list of IEntity items in the Default stream. |
Name
Name of this DataSource - not usually relevant.
Declaration
public string Name { get; }
Property Value
Type | Description |
---|---|
System.String | Name of this source. |
Out
Gets the Dictionary of Out-Streams. This is the internal accessor, as usually you'll use this["name"] instead.
In rare cases you need the Out, for example to list the stream names in the data source.
Declaration
public virtual IDictionary<string, IDataStream> Out { get; protected set; }
Property Value
Type | Description |
---|---|
System.Collections.Generic.IDictionary<System.String, IDataStream> | A dictionary of named IDataStream objects |
ZoneId
ID of the zone (EAV Tenant)
Declaration
public virtual int ZoneId { get; set; }
Property Value
Type | Description |
---|---|
System.Int32 | The zone ID this thing belongs to |
Methods
| Improve this Doc View SourceAttach(String, IDataSource, String)
Add a single named stream to the In
Declaration
[PublicApi]
public void Attach(string streamName, IDataSource dataSource, string sourceName = "Default")
Parameters
Type | Name | Description |
---|---|---|
System.String | streamName | In-name of the stream |
IDataSource | dataSource | The data source - will use it's default out |
System.String | sourceName | The stream name on the source, will default to "Default" |
Attach(String, IDataStream)
Add a single named stream to the In
Declaration
[PublicApi]
public void Attach(string streamName, IDataStream dataStream)
Parameters
Type | Name | Description |
---|---|---|
System.String | streamName | In-name of the stream |
IDataStream | dataStream | The data stream to attach |
Attach(IDataSource)
Attach a DataSource to In - replaces all existing in-streams.
Declaration
[PublicApi]
public void Attach(IDataSource dataSource)
Parameters
Type | Name | Description |
---|---|---|
IDataSource | dataSource | DataSource to attach |
CacheChanged(Int64)
Detect if the cache has old data, by comparing it to a timestamp which may be newer.
This is implemented in each object, because sometimes it compares its own timestamp, sometimes that of another underlying object.
Declaration
public virtual bool CacheChanged(long newCacheTimeStamp)
Parameters
Type | Name | Description |
---|---|---|
System.Int64 | newCacheTimeStamp | New time stamp to compare with |
Returns
Type | Description |
---|---|
System.Boolean | True if the timestamps differ, false if it's the same |
ConfigMask(String, String, Boolean)
Add a value to the configuration list for later resolving tokens and using in Cache-Keys.
Declaration
[PublicApi]
protected void ConfigMask(string key, string mask, bool cacheRelevant = true)
Parameters
Type | Name | Description |
---|---|---|
System.String | key | The internal key to reference this value in the Configuration[Key] dictionary. |
System.String | mask | The string containing Tokens which will be parsed to find the final value. |
System.Boolean | cacheRelevant | If this key should be part of the cache-key. Default is true. Set to false for parameters which don't affect the result or are confidential (like passwords) |
GetRequiredInList(out IImmutableList<IEntity>)
Get a required Stream from In. If it doesn't exist return false and place the error message in the list for returning to the caller.
Usage usually like this in your GetList() function:
private IImmutableList<IEntity> GetList()
{
if (!GetRequiredInList(out var originals)) return originals;
var result = ...;
return result;
}
Or if you're using Call Logging do something like this:
private IImmutableList<IEntity> GetList()
{
var callLog = Log.Call<IImmutableList<IEntity>>();
if (!GetRequiredInList(out var originals)) return callLog("error", originals);
var result = ...
return callLog("ok", result);
}
Declaration
[PublicApi]
protected bool GetRequiredInList(out IImmutableList<IEntity> list)
Parameters
Type | Name | Description |
---|---|---|
System.Collections.Immutable.IImmutableList<IEntity> | list | The variable which will contain the list or the error-list |
Returns
Type | Description |
---|---|
System.Boolean | True if the stream exists and is not null, otherwise false |
Remarks
Introduced in 2sxc 11.13
GetRequiredInList(String, out IImmutableList<IEntity>)
Get a required Stream from In. If it doesn't exist return false and place the error message in the list for returning to the caller.
Usage usually like this in your GetList() function:
private IImmutableList<IEntity> GetList()
{
if (!GetRequiredInList("Fallback", out var fallback)) return fallback;
var result = ...;
return result;
}
Or if you're using Call Logging do something like this:
private IImmutableList<IEntity> GetList()
{
var callLog = Log.Call<IImmutableList<IEntity>>();
if (!GetRequiredInList("Fallback", out var fallback)) return callLog("error", fallback);
var result = ...
return callLog("ok", result);
}
Declaration
[PublicApi]
protected bool GetRequiredInList(string name, out IImmutableList<IEntity> list)
Parameters
Type | Name | Description |
---|---|---|
System.String | name | Stream name - optional |
System.Collections.Immutable.IImmutableList<IEntity> | list | The variable which will contain the list or the error-list |
Returns
Type | Description |
---|---|
System.Boolean | True if the stream exists and is not null, otherwise false |
Remarks
Introduced in 2sxc 11.13
GetStream(String, String, Boolean, Boolean)
Gets the Out-Stream with specified Name and allowing some error handling if not found.
Declaration
public IDataStream GetStream(string name = null, string noParamOrder = "Rule: All params must be named (https://r.2sxc.org/named-params)", bool nullIfNotFound = false, bool emptyIfNotFound = false)
Parameters
Type | Name | Description |
---|---|---|
System.String | name | The desired stream name. If empty, will default to the default stream. |
System.String | noParamOrder | |
System.Boolean | nullIfNotFound | In case the stream |
System.Boolean | emptyIfNotFound | In case the stream |
Returns
Type | Description |
---|---|
IDataStream | an IDataStream of the desired name |
Remarks
- Added in 2sxc 12.05
- for more in-depth checking if a stream exists, you can access the Out which is an IDictionary
Exceptions
Type | Condition |
---|---|
System.NullReferenceException | if the stream does not exist and |
PurgeList(Boolean)
Remove the current data from the cache, optionally also purge everything upstream
Declaration
public virtual void PurgeList(bool cascade = false)
Parameters
Type | Name | Description |
---|---|---|
System.Boolean | cascade | true to purge all sources as well, default is false |
SetError(String, String, Exception)
This will generate an Error Stream and return it as well as place it in the ErrorStream.
Declaration
[PublicApi]
protected ImmutableArray<IEntity> SetError(string title, string message, Exception ex = null)
Parameters
Type | Name | Description |
---|---|---|
System.String | title | Error title |
System.String | message | Error message |
System.Exception | ex | .net exception - would be logged if provided |
Returns
Type | Description |
---|---|
System.Collections.Immutable.ImmutableArray<IEntity> | A list containing the error entity |
Remarks
Introduced in 2sxc 11.13