Table of Contents

Class DataSourceBase

Namespace
ToSic.Eav.DataSource
Assembly
ToSic.Eav.DataSources.dll

The base class for all DataSources, especially custom DataSources. It must always be inherited. It provides a lot of core functionality to get configurations, ensure caching and more.

Important: in most cases you will inherit the CustomDataSource DataSource for custom data sources.

[InternalApi_DoNotUse_MayChangeWithoutNotice("Just FYI for people who need to know more about the internal APIs")]
public abstract class DataSourceBase : ServiceBase<DataSourceBase.MyServices>, IDataSource, IAppIdentity, IZoneIdentity, IAppIdentityLight, ICacheKey, ICacheExpiring, ITimestamped, IHasLog, IDataSourceLinkable
Inheritance
object
ServiceBase
DataSourceBase
Implements
Derived

Remarks

Had a major, breaking update in v15. Consult the guide to upgrade your custom data sources.

Properties

AppId

The app id as used internally

public virtual int AppId { get; protected set; }

Property Value

int

The App ID this thing belongs to

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.

public virtual long CacheTimestamp { get; }

Property Value

long

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.

public IDataSourceConfiguration Configuration { get; }

Property Value

IDataSourceConfiguration

Error

Special helper to generate error-streams.

DataSources should never throw exceptions but instead return a stream containing the error information.

[PublicApi]
public DataSourceErrorHelper Error { get; }

Property Value

DataSourceErrorHelper

Guid

Internal ID usually from persisted configurations IF the configuration was build from an pre-stored query.

public Guid Guid { get; }

Property Value

Guid

The guid of this data source which identifies the configuration IEntity of the data source.

Immutable

Information if the DataSource is Immutable. Reason is that starting in v15, everything should become immutable. So setting parameters or attaching other sources will not be possible any more after initial creation. But because a lot of code is still out there which assumes mutable objects, this is set depending on how the DataSource was created. Newer APIs will result in Immutable DataSources, while older APIs will get you a mutable DataSource. See Convention: Everything is Immutable.

[InternalApi_DoNotUse_MayChangeWithoutNotice]
public virtual bool Immutable { get; }

Property Value

bool

Remarks

New in 15.06

In

List of all In connections.

[PublicApi]
public virtual IReadOnlyDictionary<string, IDataStream> In { get; }

Property Value

IReadOnlyDictionary<string, IDataStream>

A dictionary of named IDataStream objects, case insensitive

this[string]

Gets the Out-Stream with specified Name.

public IDataStream this[string outName] { get; }

Parameters

outName string

Property Value

IDataStream

an IDataStream of the desired name

Exceptions

NullReferenceException

if the stream does not exist

A link - or possibly many. In most cases, this references the parent object which provides this/these links.

public virtual IDataSourceLink Link { get; }

Property Value

IDataSourceLink

List

The items in the data-source - to be exact, the ones in the Default stream.

[PublicApi]
public IEnumerable<IEntity> List { get; }

Property Value

IEnumerable<IEntity>

A list of IEntity items in the Default stream.

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.

[PublicApi]
public virtual IReadOnlyDictionary<string, IDataStream> Out { get; }

Property Value

IReadOnlyDictionary<string, IDataStream>

A dictionary of named IDataStream objects, case insensitive

ZoneId

ID of the zone (EAV Tenant)

public virtual int ZoneId { get; protected set; }

Property Value

int

The zone ID this thing belongs to

Methods

Attach(string, IDataSource, string)

Add a single named stream to the In

[PublicApi]
public void Attach(string streamName, IDataSource dataSource, string sourceName = "Default")

Parameters

streamName string

In-name of the stream

dataSource IDataSource

The data source - will use it's default out

sourceName string

The stream name on the source, will default to "Default"

Attach(string, IDataStream)

Add a single named stream to the In

[PublicApi]
public void Attach(string streamName, IDataStream dataStream)

Parameters

streamName string

In-name of the stream

dataStream IDataStream

The data stream to attach

Attach(IDataSource)

Attach a DataSource to In - replaces all existing in-streams.

[PublicApi]
public void Attach(IDataSource dataSource)

Parameters

dataSource IDataSource

DataSource to attach

CacheChanged(long)

Detect if the cache has newer data. It's called using the TimeStamp of the dependent object which may still have old data.

public virtual bool CacheChanged(long dependentTimeStamp)

Parameters

dependentTimeStamp long

New time stamp of a dependent object, which could have an older timestamp.

Returns

bool

True if the timestamps differ, false if it's the same

Remarks

This is implemented in each object, because sometimes it compares its own timestamp, sometimes that of another underlying object.

GetStream(string, NoParamOrder, bool, bool)

Gets the Out-Stream with specified Name and allowing some error handling if not found.

[PublicApi]
public IDataStream GetStream(string name = null, NoParamOrder noParamOrder = default, bool nullIfNotFound = false, bool emptyIfNotFound = false)

Parameters

name string

The desired stream name. If empty, will default to the default stream.

noParamOrder NoParamOrder

see Convention: Named Parameters

nullIfNotFound bool

In case the stream name isn't found, will return null. Ideal for chaining with ??

emptyIfNotFound bool

In case the stream name isn't found, will return an empty stream. Ideal for using LINQ directly.

Returns

IDataStream

an IDataStream of the desired name

Remarks

  1. Added in 2sxc 12.05
  2. for more in-depth checking if a stream exists, you can access the Out which is an IDictionary

Exceptions

NullReferenceException

if the stream does not exist and nullIfNotFound is false

ProvideOut(Func<IEnumerable<IEntity>>, string)

Provide a function to get the data which this DataSource offers.

This is the more generic IEnumerable implementation. We recommend using the IImmutableList overload as it allows the system to optimize more.

[PublicApi]
protected void ProvideOut(Func<IEnumerable<IEntity>> getList, string name = "Default")

Parameters

getList Func<IEnumerable<IEntity>>

The function which will get the list.

name string

(optional) stream name, defaults to Default

ProvideOut(Func<IImmutableList<IEntity>>, string)

Provide a function to get the data which this DataSource offers.

This is the ImmutableList implementation, which is recommended.

[PublicApi]
protected void ProvideOut(Func<IImmutableList<IEntity>> getList, string name = "Default")

Parameters

getList Func<IImmutableList<IEntity>>

The function which will get the list.

name string

(optional) stream name, defaults to Default

TryGetIn(string)

Get a specific 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()
{
  var source = TryGetIn();
  if (source is null) return Error.TryGetInFailed(this);
  var result = source.Where(s => ...).ToImmutableList();
  return result;
}

Or if you're using Call Logging do something like this:

private IImmutableList<IEntity> GetList() => Log.Func(l =>
{
  var source = TryGetIn();
  if (source is null) return (Error.TryGetInFailed(this), "error");
  var result = source.Where(s => ...).ToImmutableList();
  return (result, $"ok - found: {result.Count}");
});
[PublicApi]
protected IImmutableList<IEntity> TryGetIn(string name = "Default")

Parameters

name string

Stream name - optional

Returns

IImmutableList<IEntity>

A list containing the data, or null if not found / something breaks.

Remarks

Introduced in 2sxc 15.04

TryGetOut(string)

Try get an out-stream.

protected IImmutableList<IEntity> TryGetOut(string name = "Default")

Parameters

name string

Returns

IImmutableList<IEntity>

Remarks

Introduced in 2sxc 16.01

Edit this page