Install & configuration | XData website

Installation and configuration

NuGet configuration

To get XData NuGet packages You will need modify nuget.config as described below and place it in project root folder near Your solution file.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="xdata" value="https://nuget.pkg.github.com/mickfierte/index.json" />
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <xdata>
            <add key="Username" value="API_KEY" />
            <add key="ClearTextPassword" value="API_KEY" />
        </xdata>
    </packageSourceCredentials>
</configuration>

* replace API_KEY with API key provided by author

Installation

To start use XData basic functionality is required to setup NuGet XData package. XData plugins or additional modules can be downloaded and used separately.

To work with related objects (Unit of Work implementation) is required to setup NuGet XData WorkSet (UnitOfWork) package.

To implement security session and use application data access with XData is required to setup NuGet XData Security package.

To use one or more SQL dialect, SQL adapter, specific .Net 4.0 log writer XData plugins it can be installed like any other NuGet package.

To deploy application in three-tier architecture read here

Acquiring XData configuration during runtime

.Net Standard 2.0:

XData can be dynamically configured when defining XData service (see AddXData) in ServiceCollection using optional parameter options in LINQ style.

.AddSingleton(typeof(IConfigurationRoot), x => null)
    .AddXData(x => x.AddDialect("postgresql", XDataAdapter.PostgreSql.Dialect)
        .AddAdapter("postgresql", XDataAdapter.PostgreSql.Adapter)
        .AddContext("test", "postgresql", "postgresql", 
"Server=localhost;Database=XDataTest;User Id=postgres;Password=123456", true))

Configuration file in .Net Standard 2.0 version is read by Microsoft.Extensions.Configuration service registered during application startup.

Tip

XDataAdapter.PostgreSql.Dialect, XDataAdapter.PostgreSql.Adapter and similar constants for other databases is defined in adapter NuGet packages.

.Net 4.0:

XData can be dynamically configured when acquiring XData engine XDataManager.InitXData using optional parameter options in LINQ style.

Warning

Signature of XDataManager.InitXData method is slightly different for .Net 4.0 version! See versions comparison for details.

var dataEngine = XDataManager.InitXData(x => 
    x.AddDialect("postgresql", XData.PostgreSql.Dialect)
        .AddAdapter("postgresql", XData.PostgreSql.Adapters)
        .AddContext("test", "postgresql", "postgresql", 
"Server=localhost;Database=XDataTest;User Id=postgres;Password=123456", true));
//or using configuration file
var dataEngine = XDataManager.InitXData(x => x.UseConfiguration(
    System.Web.Configuration.WebConfigurationManager.OpenWebConfiguration("~")))

Tip

When using both versions You can use IDataOptions methods to store partial non secure connection string only and fill credentials during runtime. Security related information can be obtained separately from some secure source.

Configuration XData using config file

Tip

When using .Net Standard 2.0 version config file can be formatted in any notation but structure of config file need to be correspond XML structure described here

Important

When using XML formatted config file required to add specific descriptor for XData specific section "xdata"

<configuration>
  <configSections>
    <section name="xdata" type="System.Configuration.IgnoreSectionHandler"/>
  </configSections>
...

Important

Check configSections section is first section inside XML configuration file!

Connection strings for each of context must to be declared in standard section connectionStrings and name attribute should equal to context name. Connection strings is required on client side only when two-tier (client-server) architecture used.

  <connectionStrings>
    <add name="TEST" 
        connectionString="Data Source=(local);Initial Catalog=XDataTest;User Id=test;Password=test"/>
  </connectionStrings>

There are three possible ways to secure connection string in configuration file:

Cipher config file section connectionStrings section
Using partial connection strings during runtime
Deploy application in three tier mode. In this case connection string is not required to be configured on client side.

XData specific section xdata has a structure:

<xdata default="TEST_ORACLE_ODP" log="XDataTraceLog.TraceLog, XDataTraceLog">
  <adapter name="ORACLE_ODP" assembly="XOracleODPAdapter"/>
  <dialect name="ORACLE" assembly="XOracleDialect"/>
  <context name="TEST_ORACLE_ODP" adapter="ORACLE_ODP" dialect="ORACLE" 
    sequence="XDataObjectTest.MySequenceRule, XDataObjectTest" concurrencyError="-20001"/>
</xdata>

The xdata section required to contain attribute default with context name used by default. Attribute log optional, used for .Net 4.0 version only (.Net Standard 2.0 version used Microsoft.Extensions.Logging service). Log attribute value is assembly qualified type name for ILogWriter realization (see available log plugins or implement any You want log system adapter). Log messages minimal severity level filters can be configured using native tools and abilities provided with chosen log subsystem.

Inside xdata section for each of context required elements:

dialect (required always, can be shared between multiple contexts) - register an unique alias to specific RDBMS SQL dialect support. Attribute name contains an alias of dialect. Attribute assembly - assembly name of specific dialect plugin. When plugin implementation support additional configuration settings, element dialect may have an specifically organized internal structure described in plugin readme file.
adapter (required when two-tier architecture is used only, can be shared between multiple contexts) - register unique alias to adapter for specific ADO.Net provider. Attribute name contains an alias of adapter. Attribute assembly - assembly name of specific adapter plugin. When plugin implementation support additional configuration settings, element adapter may have an specifically organized internal structure described in plugin readme file.
context (required always) - contains context settings. Attribute name contains context name. Attribute adapter (required when two-tier architecture is used only) contains adapter alias. Attribute dialect - dialect alias. In case of using sequences required to specify attribute sequence contains assembly qualified type name of ISequenceNameRule implementation. When optimistic concurrency error code need to have a special value for some reason (see specific adapter readme file) set concurrencyError attribute to specific error code value.
proxy (required when three-tier architecture is used only) - declare WCF client endpoint name for context named same as proxy attribute name value. WCF client endpoint name is stored in endpoint attribute value. Same WCF endpoint can be used for multiple contexts. Contexts names on client and server must to have same names. Deploying and configuration process for three tier architecture is described here.

Deploying application in three three-tier architecture

Project organization rules and assembly deployment principles to deploy application using three-tier architecture described here.

Note

Three-tier architecture can be applied over .Net 4.0 version only! See next versions to use three-tier feature on .Net Standard 2.0 version.

Install and configure server

Server is implemented as WCF service XData.Server.dll. Base engine XData.dll library is required to server functionality. As well as log plugins, dialects and adapters to connect database directly. To run Your application business logic on server side server logic and data mapping modules are required on server side two.

Limits to choose protocol can be used as transport between client and server:

Duplex support
Reenter-ability inside one session support

It's recommended to host XData.Server on IIS. By default IIS is not configured to activate service over net.tcp, and if You want to use this protocol, see here to configure it.

Changes on client side

When three-tier architecture is used, required to obtain special module XData.Remote. Application folder must contain client logic and data mapping modules, as well as used by Your application log modules, SQL dialect modules BUT now adapters not required to contexts used in three-tier mode.

In configuration file, is required to configure WCF client according Your server settings. Section xdata must to be configured as described above with defining of proxy elements for every context that used three-tier architecture. Remote contexts must to have same names on client and server. Sample three-tier configuration can be obtained from XData test project.

Tip

You able to combine local connections to some databases with one or more three-tier servers. In the same time You can use multiple dedicated servers, each for one or more contexts.

Tip

You can fast and simple switch from three-tier mode to client server mode and then back to three-tier by commenting/uncommenting proxy descriptions. It's a very useful feature to debug server logic code ;)