Requirements
Dynamic DataSources Tutorial
DataSources are the magic backbone of 2sxc. They can get data, filter it, sort it, and more. In many cases you will simply use the DataSources provided by 2sxc and the EAV system, but you can do even more. Specifically:
- You can create your own Dynamic DataSources in C# and use them in your code and in Visual Query. This is a bit more advanced, but very powerful. Common scenarios are DataSources which do things or retrieve data which the built-in DataSources don't do.
- You can create compiled DataSources in C# and use them in your code and in Visual Query. This is much more advanced, and not demonstrated in these tutorials, since it would be hard to install them.
Custom Dynamic DataSources - Introduction
Here we'll give you a first taste of Custom Dynamic DataSources - a new feature in 2sxc 15.
This allows you to create DataSources directly in your App, without compiling to DLL or anything.
This is a 10-line super-simple example of a DataSource called Basic101
. It will only return a single item with the answer to the meaning of life 😉. Afterwards we'll explain in more detail what's happening.
⬇️ Result | Source ➡️
List of Data in the CSV DataSource (1)
- Hello from Basic101 - the Answer: 42
This is the same sample as before, but with a lot more explanations. Here's what's happening:
- Using
Kit.Data.GetSource(name: "...")
we retrieve the DataSource using the name - The name references a file with the same name
Basics101.cs
located in theDataSources
folder of the current App. - The rest of the magic is explained in the source code of the DataSource - see below.
⬇️ Result | Source ➡️
List of Data in the CSV DataSource (1)
- Hello from Basic101-Commented - the Answer: 42
Custom Dynamic DataSources - Lists
The previous example just returned one item/entity. But of course you can also return a list of items. This is the more common case. Our sample basically will just return data it generated, but your code will usually get data from elsewhere and provide it as a list.
Return a list of items numbered 1...5 with random Guid identifier.
⬇️ Result | Source ➡️
List of Data in the DataSource (5)
- Hello from ListBasic (1 / 8ba513ef-3730-4ed0-ab29-8c79b4e66c19) - Fav Number: 2742
- Hello from ListBasic (2 / f28e3354-a9c7-48a0-afc2-ece6401f9aff) - Fav Number: 2742
- Hello from ListBasic (3 / d89ab889-0399-48e9-9ffa-4b82489e6790) - Fav Number: 2742
- Hello from ListBasic (4 / 703bbcfe-18bb-4d8e-b1c0-91f7eb063321) - Fav Number: 2742
- Hello from ListBasic (5 / efb4a02d-d6e8-43d7-a276-dd47f96370ca) - Fav Number: 2742
⬇️ Result | Source ➡️
Data in the DataSource (1)
- Current Temperature: 4.8
- WindSpeed: 10.3
- WindDirection: 102
Custom Dynamic DataSources - Configuration
Often you will need a DataSource that accepts some kind of parameters (configuration). The code must have [Configuration]
attributes on the properties that should be configurable. When calling GetSource(...)
use options: new { ... }
to set the values.
This simple example will get a DataSource from a file, and pass some configuration options. Specifically we'll give it the AmountOfItems
and FavoriteColor
.
⬇️ Result | Source ➡️
List of Data in the WithConfig DataSource (3)
- Hello from WithConfig #1 - Favorite Color: dark blue
- Hello from WithConfig #2 - Favorite Color: dark blue
- Hello from WithConfig #3 - Favorite Color: dark blue
Custom Dynamic DataSources - Process In-Data
DataSources be attached together. This means that you can create a DataSource which takes one or more DataSources as input.
This example has a DataSource which receives data from an <em>upstream</em> source. The upstream source is the list of all authors in this App. Our DataSource will then filter this list, and only keep the authors with an odd ID.
⬇️ Result | Source ➡️
Data from the KeepOdd DataSource (2)
- Terry (ID: 5339)
- Ed (ID: 5349)
If your DataSource requires attached data (In
) you may get hard-to-debug errors. Because of this, the sample also has error handling for this. The following code uses the KeepOdd
but forgets to attach the in.
⬇️ Result | Source ➡️
Data from the KeepOdd DataSource (1)
-
Error: Stream 'Default' not found (ID: 0)
Message: This DataSource needs the stream 'Default' on the In to work, but it couldn't find it.
The default stream is called Default
so you don't need to specify it. In the following example, we have a second stream called Settings
.
⬇️ Result | Source ➡️
Data in the stream "Settings"
- PageSize: 50
- ShowStuff: True
List of Data in the Default stream (5)
- Hello from ListMultiStream (1 / f370a349-16dc-4c26-bb1b-0ebdff55db28) - Fav Number: 2742
- Hello from ListMultiStream (2 / dabc73a2-1bbb-49a3-bdbb-1f61efd37ebd) - Fav Number: 2742
- Hello from ListMultiStream (3 / d75f862a-bd86-40d6-ab55-5b56a36b773a) - Fav Number: 2742
- Hello from ListMultiStream (4 / 3bcb5f94-f2b4-457f-9478-894c1509c2d3) - Fav Number: 2742
- Hello from ListMultiStream (5 / f14e3052-6332-41b5-979a-e4deaf690bcb) - Fav Number: 2742
In some cases it makes sense to provide multiple streams which were processed at the same time. For example, when splitting data or when providing a stream Folders
and Files
which are still related.
The following sample takes the original Persons
and splits them into odd/even streams in one preparation step.
⬇️ Result | Source ➡️
List of Data in the All stream (6)
- Douglas (#5338)
- Terry (#5339)
- Neil (#5340)
- George (#5344)
- Raphael (#5348)
- Ed (#5349)
List of Data in the Odd stream (2)
- Terry (#5339)
- Ed (#5349)
List of Data in the Even stream (4)
- Douglas (#5338)
- Neil (#5340)
- George (#5344)
- Raphael (#5348)
Get Data from Other DataSources
DataSources can also get other DataSources. For example, a DataSource could get data from the App directly to process them.
The Authors
DataSource demonstrates how to get all App data and then filter it using an inner EntityTypeFilter
DataSource.
⬇️ Result | Source ➡️
Items in the DataSource (6)
- Douglas
- Terry
- Neil
- George
- Raphael
- Ed