• Basics
  • Abyss
  • C# & Razor
  • JavaScript & TS
  • Web API
  • .net API

    Show / Hide Table of Contents

    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

    • DataSource / DataStream
    • List of all EAV Data Sources
    • Query / VisualQuery

    History

    1. Introduced in EAV 4.x, 2sxc 6
    2. Enhanced with Error methods for VisualQuery 3 in 2sxc 11.13

    API Documentation

    Inheritance
    System.Object
    HasLog
    DataSourceBase
    App
    AppRoot
    AttributeFilter
    AttributeRename
    CacheAllStreams
    EntityIdFilter
    EntityTypeFilter
    Error
    ExternalData
    ItemFilterDuplicates
    LanguageModeler
    OwnerFilter
    Paging
    PassThrough
    PublishingFilter
    Query
    QueryRun
    RelationshipFilter
    SerializationConfiguration
    Shuffle
    StreamFallback
    StreamMerge
    StreamPick
    Apps
    Attributes
    ContentTypes
    QueryInfo
    Zones
    TreeModeler
    ValueFilter
    ValueSort
    CmsBlock
    Implements
    IDataSource
    IAppIdentity
    IZoneIdentity
    IAppIdentityLight
    ICacheKey
    ICacheExpiring
    ITimestamped
    ICanPurgeListCache
    IHasLog
    IDataTarget
    IDataPartShared
    Inherited Members
    HasLog.Log
    HasLog.InitLog(String, ILog, String)
    HasLog.InitLog(String, ILog, String, CodeRef)
    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 Source

    DataSourceBase()

    Constructor - must be without parameters, otherwise the DI can't construct it.

    Declaration
    protected DataSourceBase()

    Fields

    | Improve this Doc View Source

    ErrorStream

    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 Source

    AppId

    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

    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    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>
    | Improve this Doc View Source

    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

    | Improve this Doc View Source

    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
    | Improve this Doc View Source

    DataBuilder

    Declaration
    protected IDataBuilder DataBuilder { get; }
    Property Value
    Type Description
    IDataBuilder
    | Improve this Doc View Source

    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.

    | Improve this Doc View 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>
    | Improve this Doc View Source

    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

    | Improve this Doc View Source

    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.

    | Improve this Doc View Source

    Name

    Name of this DataSource - not usually relevant.

    Declaration
    public string Name { get; }
    Property Value
    Type Description
    System.String

    Name of this source.

    | Improve this Doc View 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

    | Improve this Doc View Source

    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 Source

    Attach(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"

    | Improve this Doc View Source

    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

    | Improve this Doc View Source

    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

    | Improve this Doc View Source

    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

    | Improve this Doc View Source

    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)

    | Improve this Doc View Source

    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

    | Improve this Doc View Source

    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

    | Improve this Doc View Source

    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

    see Convention: Named Parameters

    System.Boolean nullIfNotFound

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

    System.Boolean emptyIfNotFound

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

    Returns
    Type Description
    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
    Type Condition
    System.NullReferenceException

    if the stream does not exist and nullIfNotFound is false

    | Improve this Doc View Source

    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

    | Improve this Doc View Source

    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

    Implements

    IDataSource
    IAppIdentity
    IZoneIdentity
    IAppIdentityLight
    ICacheKey
    ICacheExpiring
    ITimestamped
    ICanPurgeListCache
    IHasLog
    IDataTarget
    IDataPartShared
    • Improve this Doc
    • View Source
    Back to top Generated by DocFX