index.json

{
  "api/ArgentSea.DbDataStores-1.DataConnection.html": {
    "href": "api/ArgentSea.DbDataStores-1.DataConnection.html",
    "title": "Class DbDataStores<TConfiguration>.DataConnection | ArgentSea Docs",
    "keywords": "Class DbDataStores<TConfiguration>.DataConnection Inheritance System.Object DbDataStores<TConfiguration>.DataConnection Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class DataConnection Properties | Improve this Doc View Source ConnectionString Declaration public string ConnectionString { get; } Property Value Type Description System.String Methods | Improve this Doc View Source ListAsync<TResult>(String, DbParameterCollection, CancellationToken) Connect to the database and return the values as a list of objects. Declaration public Task<IList<TResult>> ListAsync<TResult>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TResult : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task < System.Collections.Generic.IList <TResult>> A list containing an object for each data row. Type Parameters Name Description TResult The type of object to be listed. | Improve this Doc View Source LookupAsync<TValue>(String, DbParameterCollection, CancellationToken) Connect to the database and return a single value. Declaration public Task<TValue> LookupAsync<TValue>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the value. System.Data.Common.DbParameterCollection parameters A parameters collction. Input parameters may be used to find the parameter; will return the value of the first output (or input/output) parameter. If TValue is an int, will also return the sproc return value. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TValue> The retrieved value. Type Parameters Name Description TValue The expected type of the return value. | Improve this Doc View Source QueryAsync<TModel>(String, DbParameterCollection, QueryResultModelHandler<Int32, Object, TModel>, Boolean, CancellationToken) Declaration public Task<TModel> QueryAsync<TModel>(string sprocName, DbParameterCollection parameters, QueryResultModelHandler<int, object, TModel> resultHandler, bool isTopOne, CancellationToken cancellationToken) where TModel : class, new() Parameters Type Name Description System.String sprocName System.Data.Common.DbParameterCollection parameters QueryResultModelHandler < System.Int32 , System.Object , TModel> resultHandler System.Boolean isTopOne System.Threading.CancellationToken cancellationToken Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel | Improve this Doc View Source QueryAsync<TModel>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding output parameters. Declaration public Task<TModel> QueryAsync<TModel>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel The type of the object to be returned. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TReaderResult7, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TReaderResult7, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TReaderResult5 : class, new() where TReaderResult6 : class, new() where TReaderResult7 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TReaderResult4 The fifth result set from data reader will be mapped an object or property of this type. TReaderResult5 The sixth result set from data reader will be mapped an object or property of this type. TReaderResult6 The seventh result set from data reader will be mapped an object or property of this type. TReaderResult7 The eighth result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TArg, TModel>(String, DbParameterCollection, QueryResultModelHandler<Int32, TArg, TModel>, Boolean, TArg, CancellationToken) Declaration public Task<TModel> QueryAsync<TArg, TModel>(string sprocName, DbParameterCollection parameters, QueryResultModelHandler<int, TArg, TModel> resultHandler, bool isTopOne, TArg optionalArgument, CancellationToken cancellationToken) where TModel : class, new() Parameters Type Name Description System.String sprocName System.Data.Common.DbParameterCollection parameters QueryResultModelHandler < System.Int32 , TArg, TModel> resultHandler System.Boolean isTopOne TArg optionalArgument System.Threading.CancellationToken cancellationToken Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TArg TModel | Improve this Doc View Source QueryAsync<TModel, TReaderResult, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult The data reader result set will be mapped an object or property of this type. If TOutParmaters is set to Mapper.DummyType then this must be a single row result of type TModel. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TReaderResult4 The fifth result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TReaderResult5 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TReaderResult4 The fifth result set from data reader will be mapped an object or property of this type. TReaderResult5 The sixth result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TReaderResult5 : class, new() where TReaderResult6 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TReaderResult4 The fifth result set from data reader will be mapped an object or property of this type. TReaderResult5 The sixth result set from data reader will be mapped an object or property of this type. TReaderResult6 The seventh result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source RunAsync(String, DbParameterCollection, CancellationToken) Declaration public Task RunAsync(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) Parameters Type Name Description System.String sprocName System.Data.Common.DbParameterCollection parameters System.Threading.CancellationToken cancellationToken Returns Type Description System.Threading.Tasks.Task"
  },
  "api/ArgentSea.ParameterMapAttribute.html": {
    "href": "api/ArgentSea.ParameterMapAttribute.html",
    "title": "Class ParameterMapAttribute | ArgentSea Docs",
    "keywords": "Class ParameterMapAttribute Inheritance System.Object System.Attribute ParameterMapAttribute Inherited Members System.Attribute.Equals(System.Object) System.Attribute.GetCustomAttribute(System.Reflection.Assembly, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.Assembly, System.Type, System.Boolean) System.Attribute.GetCustomAttribute(System.Reflection.MemberInfo, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.MemberInfo, System.Type, System.Boolean) System.Attribute.GetCustomAttribute(System.Reflection.Module, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.Module, System.Type, System.Boolean) System.Attribute.GetCustomAttribute(System.Reflection.ParameterInfo, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.ParameterInfo, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Assembly) System.Attribute.GetCustomAttributes(System.Reflection.Assembly, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Assembly, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.Assembly, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Module) System.Attribute.GetCustomAttributes(System.Reflection.Module, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Module, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.Module, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo, System.Type, System.Boolean) System.Attribute.GetHashCode() System.Attribute.IsDefaultAttribute() System.Attribute.IsDefined(System.Reflection.Assembly, System.Type) System.Attribute.IsDefined(System.Reflection.Assembly, System.Type, System.Boolean) System.Attribute.IsDefined(System.Reflection.MemberInfo, System.Type) System.Attribute.IsDefined(System.Reflection.MemberInfo, System.Type, System.Boolean) System.Attribute.IsDefined(System.Reflection.Module, System.Type) System.Attribute.IsDefined(System.Reflection.Module, System.Type, System.Boolean) System.Attribute.IsDefined(System.Reflection.ParameterInfo, System.Type) System.Attribute.IsDefined(System.Reflection.ParameterInfo, System.Type, System.Boolean) System.Attribute.Match(System.Object) System.Attribute.TypeId System.Object.Equals(System.Object, System.Object) System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax [AttributeUsage(AttributeTargets.Property, Inherited = true, AllowMultiple = true)] public abstract class ParameterMapAttribute : Attribute Constructors | Improve this Doc View Source ParameterMapAttribute(String, Int32) Declaration public ParameterMapAttribute(string name, int sqlType) Parameters Type Name Description System.String name System.Int32 sqlType | Improve this Doc View Source ParameterMapAttribute(String, Int32, Boolean) Declaration public ParameterMapAttribute(string name, int sqlType, bool isRequired) Parameters Type Name Description System.String name System.Int32 sqlType System.Boolean isRequired Properties | Improve this Doc View Source ColumnName Declaration public virtual string ColumnName { get; } Property Value Type Description System.String | Improve this Doc View Source IsRequired Declaration public bool IsRequired { get; } Property Value Type Description System.Boolean | Improve this Doc View Source Name Declaration public string Name { get; } Property Value Type Description System.String | Improve this Doc View Source ParameterName Declaration public virtual string ParameterName { get; } Property Value Type Description System.String | Improve this Doc View Source SqlType Declaration public int SqlType { get; } Property Value Type Description System.Int32 Methods | Improve this Doc View Source AppendInParameterExpressions(IList<Expression>, ParameterExpression, ParameterExpression, HashSet<String>, Expression, Type, ParameterExpression, ILogger) Declaration protected abstract void AppendInParameterExpressions(IList<Expression> expressions, ParameterExpression expSprocParameters, ParameterExpression expIgnoreParameters, HashSet<string> parameterNames, Expression expProperty, Type propertyType, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression expSprocParameters System.Linq.Expressions.ParameterExpression expIgnoreParameters System.Collections.Generic.HashSet < System.String > parameterNames System.Linq.Expressions.Expression expProperty System.Type propertyType System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source AppendReaderExpressions(Expression, IList<MethodCallExpression>, IList<Expression>, ParameterExpression, ParameterExpression, ParameterExpression, ref Int32, Type, ParameterExpression, ILogger) Declaration protected abstract void AppendReaderExpressions(Expression expProperty, IList<MethodCallExpression> columnLookupExpressions, IList<Expression> expressions, ParameterExpression prmSqlRdr, ParameterExpression expOrdinals, ParameterExpression expOrdinal, ref int propIndex, Type propertyType, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.Linq.Expressions.Expression expProperty System.Collections.Generic.IList < System.Linq.Expressions.MethodCallExpression > columnLookupExpressions System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression prmSqlRdr System.Linq.Expressions.ParameterExpression expOrdinals System.Linq.Expressions.ParameterExpression expOrdinal System.Int32 propIndex System.Type propertyType System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source AppendReadOutParameterExpressions(Expression, IList<Expression>, ParameterExpression, ParameterExpression, Type, ParameterExpression, ILogger) Declaration protected abstract void AppendReadOutParameterExpressions(Expression expProperty, IList<Expression> expressions, ParameterExpression expSprocParameters, ParameterExpression expPrm, Type propertyType, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.Linq.Expressions.Expression expProperty System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression expSprocParameters System.Linq.Expressions.ParameterExpression expPrm System.Type propertyType System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source AppendSetOutParameterExpressions(IList<Expression>, ParameterExpression, ParameterExpression, HashSet<String>, ParameterExpression, ILogger) Declaration protected abstract void AppendSetOutParameterExpressions(IList<Expression> expressions, ParameterExpression expSprocParameters, ParameterExpression expIgnoreParameters, HashSet<string> parameterNames, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression expSprocParameters System.Linq.Expressions.ParameterExpression expIgnoreParameters System.Collections.Generic.HashSet < System.String > parameterNames System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source IsValidType(Type) Declaration public abstract bool IsValidType(Type candidate) Parameters Type Name Description System.Type candidate Returns Type Description System.Boolean"
  },
  "api/ArgentSea.ShardDataStores-2.ShardDataSet.html": {
    "href": "api/ArgentSea.ShardDataStores-2.ShardDataSet.html",
    "title": "Class ShardDataStores<TShard, TConfiguration>.ShardDataSet | ArgentSea Docs",
    "keywords": "Class ShardDataStores<TShard, TConfiguration>.ShardDataSet Inheritance System.Object ShardDataStores<TShard, TConfiguration>.ShardDataSet Implements System.Collections.ICollection System.Collections.IEnumerable Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class ShardDataSet : ICollection, IEnumerable Constructors | Improve this Doc View Source ShardDataSet(ShardDataStores<TShard, TConfiguration>, IShardConnectionsConfiguration<TShard>) Declaration public ShardDataSet(ShardDataStores<TShard, TConfiguration> parent, IShardConnectionsConfiguration<TShard> config) Parameters Type Name Description ShardDataStores <TShard, TConfiguration> parent IShardConnectionsConfiguration <TShard> config Properties | Improve this Doc View Source Count Declaration public int Count { get; } Property Value Type Description System.Int32 | Improve this Doc View Source IsSynchronized Declaration public bool IsSynchronized { get; } Property Value Type Description System.Boolean | Improve this Doc View Source Item[TShard] Declaration public ShardDataStores<TShard, TConfiguration>.ShardInstance this[TShard shardId] { get; } Parameters Type Name Description TShard shardId Property Value Type Description ShardDataStores.ShardInstance <> | Improve this Doc View Source Key Declaration public string Key { get; set; } Property Value Type Description System.String | Improve this Doc View Source SyncRoot Declaration public object SyncRoot { get; } Property Value Type Description System.Object Methods | Improve this Doc View Source CopyTo(Array, Int32) Declaration public void CopyTo(Array array, int index) Parameters Type Name Description System.Array array System.Int32 index | Improve this Doc View Source GetEnumerator() Declaration public IEnumerator GetEnumerator() Returns Type Description System.Collections.IEnumerator | Improve this Doc View Source QueryAllAsync<TModel>(String, TShard[], DbParameterCollection, Int32, QueryResultModelHandler<TShard, Object, TModel>, CancellationToken) Declaration public Task<List<TModel>> QueryAllAsync<TModel>(string sprocName, TShard[] exclude, DbParameterCollection parameters, int shardIdParameterIndex, QueryResultModelHandler<TShard, object, TModel> resultHandler, CancellationToken cancellationToken) where TModel : class, new() Parameters Type Name Description System.String sprocName TShard[] exclude System.Data.Common.DbParameterCollection parameters System.Int32 shardIdParameterIndex QueryResultModelHandler <TShard, System.Object , TModel> resultHandler System.Threading.CancellationToken cancellationToken Returns Type Description System.Threading.Tasks.Task < System.Collections.Generic.List <TModel>> Type Parameters Name Description TModel | Improve this Doc View Source QueryAllAsync<TArg, TModel>(String, TShard[], DbParameterCollection, Int32, QueryResultModelHandler<TShard, TArg, TModel>, TArg, CancellationToken) Declaration public Task<List<TModel>> QueryAllAsync<TArg, TModel>(string sprocName, TShard[] exclude, DbParameterCollection parameters, int shardIdParameterIndex, QueryResultModelHandler<TShard, TArg, TModel> resultHandler, TArg dataObject, CancellationToken cancellationToken) where TModel : class, new() Parameters Type Name Description System.String sprocName TShard[] exclude System.Data.Common.DbParameterCollection parameters System.Int32 shardIdParameterIndex QueryResultModelHandler <TShard, TArg, TModel> resultHandler TArg dataObject System.Threading.CancellationToken cancellationToken Returns Type Description System.Threading.Tasks.Task < System.Collections.Generic.List <TModel>> Type Parameters Name Description TArg TModel | Improve this Doc View Source QueryFirstAsync<TArg, TResult>(String, TShard[], DbParameterCollection, Int32, QueryResultModelHandler<TShard, TArg, TResult>, TArg, CancellationToken) Declaration public Task<TResult> QueryFirstAsync<TArg, TResult>(string sprocName, TShard[] exclude, DbParameterCollection parameters, int shardIdParameterIndex, QueryResultModelHandler<TShard, TArg, TResult> resultHandler, TArg dataObject, CancellationToken cancellationToken) where TResult : class, new() Parameters Type Name Description System.String sprocName TShard[] exclude System.Data.Common.DbParameterCollection parameters System.Int32 shardIdParameterIndex QueryResultModelHandler <TShard, TArg, TResult> resultHandler TArg dataObject System.Threading.CancellationToken cancellationToken Returns Type Description System.Threading.Tasks.Task <TResult> Type Parameters Name Description TArg TResult Implements System.Collections.ICollection System.Collections.IEnumerable"
  },
  "api/ArgentSea.LoggingExtensions.EventIdentifier.html": {
    "href": "api/ArgentSea.LoggingExtensions.EventIdentifier.html",
    "title": "Enum LoggingExtensions.EventIdentifier | ArgentSea Docs",
    "keywords": "Enum LoggingExtensions.EventIdentifier Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public enum EventIdentifier Fields Name Description LogCircuitBreakerOff LogCircuitBreakerOn LogCircuitBreakerTest LogCmdExecuted LogCommandRetry LogConnectRetry LogExpressionTreeCreation MapperGetOutTrace MapperInParameterCacheStatus MapperInTrace MapperRdrTrace MapperReaderCacheStatus MapperReadOutParameterCacheStatus MapperResultsReaderInvalid MapperSetOutParameterCache MapperSetOutParameterCacheStatus MapperSetOutTrace MapperShardChildNull MapperShardKeyNull MapperSqlColumnNotFound MapperSqlParameterNotFound RequiredPropertyIsDbNull"
  },
  "api/ArgentSea.DataConnectionConfiguration.html": {
    "href": "api/ArgentSea.DataConnectionConfiguration.html",
    "title": "Class DataConnectionConfiguration | ArgentSea Docs",
    "keywords": "Class DataConnectionConfiguration Abstract class implementing the data connection functionality shared by PostgreSQL and SQL Server implementations. Inheritance System.Object DataConnectionConfiguration Implements IConnectionConfiguration Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public abstract class DataConnectionConfiguration : IConnectionConfiguration Fields | Improve this Doc View Source hasConnectionPropertyChanged Declaration protected bool hasConnectionPropertyChanged Field Value Type Description System.Boolean Properties | Improve this Doc View Source ConnectionDescription Declaration public abstract string ConnectionDescription { get; } Property Value Type Description System.String | Improve this Doc View Source ResilienceKey Declaration public string ResilienceKey { get; set; } Property Value Type Description System.String | Improve this Doc View Source SecurityKey Declaration public string SecurityKey { get; set; } Property Value Type Description System.String Methods | Improve this Doc View Source GetConnectionString() Declaration public abstract string GetConnectionString() Returns Type Description System.String | Improve this Doc View Source GetResilienceStrategy(ILogger) Declaration protected DataResilienceConfiguration GetResilienceStrategy(ILogger logger) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger Returns Type Description DataResilienceConfiguration | Improve this Doc View Source GetSecurityConfiguration() Declaration protected SecurityConfiguration GetSecurityConfiguration() Returns Type Description SecurityConfiguration | Improve this Doc View Source SetConfigurationOptions(DataSecurityOptions, DataResilienceOptions) Declaration public void SetConfigurationOptions(DataSecurityOptions securityOptions, DataResilienceOptions resilienceStrategiesOptions) Parameters Type Name Description DataSecurityOptions securityOptions DataResilienceOptions resilienceStrategiesOptions Implements IConnectionConfiguration"
  },
  "api/ArgentSea.Test.ShardSerializationTests.html": {
    "href": "api/ArgentSea.Test.ShardSerializationTests.html",
    "title": "Class ShardSerializationTests | ArgentSea Docs",
    "keywords": "Class ShardSerializationTests Inheritance System.Object ShardSerializationTests Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea.Test Assembly : ArgentSea.Test.dll Syntax public class ShardSerializationTests Methods | Improve this Doc View Source TestShardChildSerializationInts() Declaration [Fact] public void TestShardChildSerializationInts() | Improve this Doc View Source TestShardKeySerializationFloat() Declaration [Fact] public void TestShardKeySerializationFloat() | Improve this Doc View Source TestShardKeySerializationInts1() Declaration [Fact] public void TestShardKeySerializationInts1() | Improve this Doc View Source TestShardKeySerializationInts2() Declaration [Fact] public void TestShardKeySerializationInts2() | Improve this Doc View Source TestShardKeySerializationMore1() Declaration [Fact] public void TestShardKeySerializationMore1() | Improve this Doc View Source TestShardKeySerializationMore2() Declaration [Fact] public void TestShardKeySerializationMore2() | Improve this Doc View Source TestShardKeySerializationStr() Declaration [Fact] public void TestShardKeySerializationStr()"
  },
  "api/ArgentSea.SecurityConfiguration.html": {
    "href": "api/ArgentSea.SecurityConfiguration.html",
    "title": "Class SecurityConfiguration | ArgentSea Docs",
    "keywords": "Class SecurityConfiguration This class represents data security information, with a key that can be reference by any connection(s) that share the security information. Inheritance System.Object SecurityConfiguration Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class SecurityConfiguration Properties | Improve this Doc View Source Password Declaration public string Password { get; set; } Property Value Type Description System.String | Improve this Doc View Source SecurityKey Used by data connection classes to identify the corresponding security information. Declaration public string SecurityKey { get; set; } Property Value Type Description System.String | Improve this Doc View Source UserName Declaration public string UserName { get; set; } Property Value Type Description System.String | Improve this Doc View Source WindowsAuth Declaration public bool WindowsAuth { get; set; } Property Value Type Description System.Boolean"
  },
  "api/ArgentSea.ShardDataStores-2.ShardInstance.html": {
    "href": "api/ArgentSea.ShardDataStores-2.ShardInstance.html",
    "title": "Class ShardDataStores<TShard, TConfiguration>.ShardInstance | ArgentSea Docs",
    "keywords": "Class ShardDataStores<TShard, TConfiguration>.ShardInstance Inheritance System.Object ShardDataStores<TShard, TConfiguration>.ShardInstance Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class ShardInstance Constructors | Improve this Doc View Source ShardInstance(ShardDataStores<TShard, TConfiguration>, TShard, IConnectionConfiguration, IConnectionConfiguration) Declaration public ShardInstance(ShardDataStores<TShard, TConfiguration> parent, TShard shardId, IConnectionConfiguration readConnection, IConnectionConfiguration writeConnection) Parameters Type Name Description ShardDataStores <TShard, TConfiguration> parent TShard shardId IConnectionConfiguration readConnection IConnectionConfiguration writeConnection Properties | Improve this Doc View Source ReadConnection Declaration public ShardDataStores<TShard, TConfiguration>.DataConnection ReadConnection { get; } Property Value Type Description ShardDataStores.DataConnection <> | Improve this Doc View Source ShardId Declaration public TShard ShardId { get; } Property Value Type Description TShard | Improve this Doc View Source WriteConnection Declaration public ShardDataStores<TShard, TConfiguration>.DataConnection WriteConnection { get; } Property Value Type Description ShardDataStores.DataConnection <>"
  },
  "api/ArgentSea.IShardConnectionConfiguration-1.html": {
    "href": "api/ArgentSea.IShardConnectionConfiguration-1.html",
    "title": "Interface IShardConnectionConfiguration<TShard> | ArgentSea Docs",
    "keywords": "Interface IShardConnectionConfiguration<TShard> This interface is used by provider specific implementations. It is unlikely that you would implement this in consumer code. Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public interface IShardConnectionConfiguration<TShard> where TShard : IComparable Type Parameters Name Description TShard Properties | Improve this Doc View Source ReadConnectionInternal Declaration IConnectionConfiguration ReadConnectionInternal { get; } Property Value Type Description IConnectionConfiguration | Improve this Doc View Source ShardId Declaration TShard ShardId { get; set; } Property Value Type Description TShard | Improve this Doc View Source WriteConnectionInternal Declaration IConnectionConfiguration WriteConnectionInternal { get; } Property Value Type Description IConnectionConfiguration"
  },
  "api/ArgentSea.StringExtensions.InputCleaningOptions.html": {
    "href": "api/ArgentSea.StringExtensions.InputCleaningOptions.html",
    "title": "Enum StringExtensions.InputCleaningOptions | ArgentSea Docs",
    "keywords": "Enum StringExtensions.InputCleaningOptions Namespace : ArgentSea Assembly : ArgentSea.dll Syntax [Flags] public enum InputCleaningOptions Fields Name Description AllowEmojis Do not remove Unicode surrogate values, like Emoji. AllowMultiline All “control” characters are removed by default; setting this flag preserve keep CrLf and/or Cr. It also ensures Windows line endings (Cr+Lf) when encountering Lf only (Unix line endings). CleanAll Remove starting and trailing whitespace, “control” characters including Lf and Cr, and extended characters like Emoji icons."
  },
  "api/ArgentSea.ShardDataStores-2.html": {
    "href": "api/ArgentSea.ShardDataStores-2.html",
    "title": "Class ShardDataStores<TShard, TConfiguration> | ArgentSea Docs",
    "keywords": "Class ShardDataStores<TShard, TConfiguration> This class is used by provider specific implementations. It is unlikely that you would call this in consumer code. This is the generic class that defines connections for sharded data sets. Inheritance System.Object ShardDataStores<TShard, TConfiguration> Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class ShardDataStores<TShard, TConfiguration> where TShard : IComparable where TConfiguration : class, IShardDataConfigurationOptions<TShard>, new() Type Parameters Name Description TShard TConfiguration Constructors | Improve this Doc View Source ShardDataStores(IOptions<TConfiguration>, IOptions<DataSecurityOptions>, IOptions<DataResilienceOptions>, IDataProviderServiceFactory, ILogger<ShardDataStores<TShard, TConfiguration>>) Declaration public ShardDataStores(IOptions<TConfiguration> configOptions, IOptions<DataSecurityOptions> securityOptions, IOptions<DataResilienceOptions> resilienceStrategiesOptions, IDataProviderServiceFactory dataProviderServices, ILogger<ShardDataStores<TShard, TConfiguration>> logger) Parameters Type Name Description Microsoft.Extensions.Options.IOptions <TConfiguration> configOptions Microsoft.Extensions.Options.IOptions < DataSecurityOptions > securityOptions Microsoft.Extensions.Options.IOptions < DataResilienceOptions > resilienceStrategiesOptions IDataProviderServiceFactory dataProviderServices Microsoft.Extensions.Logging.ILogger < ShardDataStores <TShard, TConfiguration>> logger Properties | Improve this Doc View Source ShardSets Declaration public ShardDataStores<TShard, TConfiguration>.ShardDataSets ShardSets { get; } Property Value Type Description ShardDataStores.ShardDataSets <>"
  },
  "api/ArgentSea.IShardConnectionsConfiguration-1.html": {
    "href": "api/ArgentSea.IShardConnectionsConfiguration-1.html",
    "title": "Interface IShardConnectionsConfiguration<TShard> | ArgentSea Docs",
    "keywords": "Interface IShardConnectionsConfiguration<TShard> This interface is used by provider specific implementations. It is unlikely that you would implement this in consumer code. Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public interface IShardConnectionsConfiguration<TShard> where TShard : IComparable Type Parameters Name Description TShard Properties | Improve this Doc View Source ShardSetName Declaration string ShardSetName { get; set; } Property Value Type Description System.String | Improve this Doc View Source ShardsInternal Declaration IShardConnectionConfiguration<TShard>[] ShardsInternal { get; } Property Value Type Description IShardConnectionConfiguration <TShard>[]"
  },
  "api/ArgentSea.ShardDataStores-2.ShardInstance.DataAccess.html": {
    "href": "api/ArgentSea.ShardDataStores-2.ShardInstance.DataAccess.html",
    "title": "Enum ShardDataStores<TShard, TConfiguration>.ShardInstance.DataAccess | ArgentSea Docs",
    "keywords": "Enum ShardDataStores<TShard, TConfiguration>.ShardInstance.DataAccess Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public enum DataAccess Fields Name Description ReadOnly WriteAccess"
  },
  "api/ArgentSea.Mapper.DummyType.html": {
    "href": "api/ArgentSea.Mapper.DummyType.html",
    "title": "Class Mapper.DummyType | ArgentSea Docs",
    "keywords": "Class Mapper.DummyType Inheritance System.Object Mapper.DummyType Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class DummyType"
  },
  "tutorials/Querying/fetching.html": {
    "href": "tutorials/Querying/fetching.html",
    "title": "Fetching Data | ArgentSea Docs",
    "keywords": "Fetching Data Retrieving database data consists of running a query on each connection. ArgentSea provides various methods to offer the best approach. Connection methods Both database connections and shards have distinct Read and Write connections. The distinction allows the system to “scale out” reads and writes. The Read connection should be used for SELECT-only stored procedures or SQL statements; the Write connection should be used for everything else. For example, you could direct reads to a mirror, active standby, or read-only endpoint, and direct writes to the master or source database. Tip Even if you do not currently have separate read-only endpoints like mirrors or active standbys, consistent discrimination of Read and Write access will allow you to scale-out in the future. If only the Read or Write connection is configured, both the Read and Write connections will have the same value. These are the methods that can be invoked on a connection: Method Description ReturnValueAsync Returns a value from the database. This may be a return value (int) or single output value from a parameter or column. RunAsync Executes a database statement, procedure, or batch. No results are returned (except possibly batch results). QueryAsync Returns the typed object created by a handler delegate. MapListAsync Returns a List of typed objects from the data results. MapReaderAsync Returns a typed object created by the Mapper from DataReader results. MapOutputAsync Returns a typed object created by the Mapper from output parameters and DataReader results. Database objects and shard instances have both Write and Read connections, which executes a query on a single database. All the methods listed are available on either connection (even though it may not make sense to use RunAsync on a read connection). The ShardSet has Write , ReadAll , and ReadFirst connections, which execute the procedure or SQL statement on every shard. They return either the combined result or the first valid (non-null) result. For example, if you need to look up a user by their login name (rather than their user key), use ReadFirst to query all shards for a matching record, and to return the single expected matching result. Whereas, ReadAll could be used to retrieve all users in any shard with particular attribute. Note that ReadAll methods always return list results. Method Uses Mapper Db.Read Db.Write ShardSet.ReadAll ShardSet.ReadFirst ShardSet.Write ReturnValueAsync • • RunAsync • • • QueryAsync • • • • • ListAsync • • • • • MapListAsync • • • • MapReaderAsync • • • • • • MapOutputAsync • • • • • • Method Arguments The arguments are largely consistent across all of the methods, except running a query batch which is discussed later. Required Argument: (Query) query There are two types of query objects: Stored procedures are parameterized statements stored within the database server. This is the preferred approach with SQL Server. Statements are parameterized SQL files stored in a application folder (rather than compiled into the source code). This is useful for PostgreSQL databases and situations with less-than-full ownership of the target database. The recommended practice is to create a single static class rendering all SQL statements and procedures. This approach is simple and also provides a reference count indicating which procedures/statements are in use, which can be a problem when an application has grown large. Sample code and more detail is discussed in SQL queries and the configuration quickstart . An example invocation is like this: await database.RunAsync(Queries.MyProcedure, parameters, cancellationToken); Required Argument: (DbParameterCollection) parameters The abstract DbParameterCollection is implemented by ArgentSea’s QueryParameterCollection object. Because it is also implemented by the provider-specific command.Parameters property, if you have a command with valid parameters defined (for some reason), you can use that too. This value can be null if there are no parameters. Warning When working with output parameters in standard ADO.NET, you may habitually maintain a variable reference to any output parameters you created before adding it to the collection. This makes it easy to get the output parameter value after the query is executed. This approach will not work with sharded data, because ArgentSea will copy the parameter set before executing the query. Any referenced output parameters will not contain a data result. Optional ShardSet Argument: (IEnumerable<ShardParameterValue>) shardParameterValues Some shard query method overloads accept a ShardParameterValue object. This object allows you to specify which shards should be queried and even provide distinct parameter values to each shard. For example, suppose your User record returns a list of “Friends”. The Friend detail data may be hosted on other shards, but not on every shard. Building a list of ShardParameterValue objects from the User results would limit the subsequent queries to just the relevant shards. The ShardParameterValue type has a ShardId and an optional parameter name and value. Only shards with at least one listed ShardId will be queried. If a parameter name is also specified, the corresponding parameter will be set to that value on the indicated shard. You can include multiple parameters/values on the same shard by repeating the shardId. Optional ShardSet Argument: (string) shardParameterName Some shard query overloads also accept the name of the parameter that represents the name of the parameter that should be set to shardId value. If specified, ArgentSea will set this parameter value to the current shardId value as it executes each query. For example, a query for a list of records that spans shards could be enhanced if the query new the value of its own ShardId. Alternatively, because a shard misconfiguration might result in catastrophic data corruption (due to the high likelihood of duplicate record identities between shards), you might require that queries that write to the database also have a ShardId parameter that they validate is correct. Optional Argument: (QueryResultModelHandler<TArg, TModel>>) resultHandler This is only used in the QueryAsync methods. As described earlier, the data query process is divided into two processes. The resultHandler is a delegate that may be invoked concurrently by distinct, shard-specific threads. If you use a data access method prefixed with Map*, this argument is not required because the delegate provided by the Mapper is used. If the Mapper does not suit your purpose, then a custom delegate must be provided to a Query* method. Your custom delegate can have an argument that provides additional data or context information. Information on how to build a custom delegate is provided below. Optional Argument: (bool) isTopOne Some overloads expose the isTopOne option, which allows a minor optimization when only a single result is expected. For example, if you are looking up a record by its key, you don’t need to allocate space for multiple results when only a single result can ever be returned. Optional Argument: (TArg) optionalArgument If you are creating a custom data handling method, you may need to provide additional data or context information. This argument may be generically typed. The provided object is passed to your result handling delegate. Required Argument: (CancellationToken) cancellationToken The cancellation token allow you to cancel asynchronous operations. ASP.NET MVC provides cancellation tokens and these can be passed along. In this way, when a user abandons their session, any uncompleted queries can be cancelled. The MapReader* and MapOutput* Methods The MapReader* and MapOutput* methods are similar. Both use the Mapping attributes to resolve data to Model objects. The MapOutput* method uses output parameters to build the root result object; the MapReader methods use a (single record) DataReader result instead. So, if you use output parameters (which is potentially more performant), use MapOutput* . If you use standard SELECTs to return your data, use MapReader* . Both methods support multiple result sets that populate properties that contain Lists ( List<Model> or IList<Model> ) of related data. For example, you might have an Order record with a property containing an OrderItem List. The list items come from (additional) DataReader results. A single root Model may have up to eight of these List properties. The List property must be settable. Note The order in which your attribute-mapped class appears in the generic definitions should be the same order as the list data results in the procedure or statement output. An example of calling each would be: // In this example, ws.GetOrderDetails returns Order data in output parameters: _database.MapOutputAsync<Order>(Queries.GetOrderDetails, parameters, cancellation); // Here, ws.GetOrderDetails returns simple Order data in a single-row SELECT: _database.MapReaderAsync<Order>(Queries.GetOrderDetails, parameters, cancellation); // Now ws.GetOrderDetails returns Order data in output parameters and a list of OrderItem from a SELECT: _database.MapOutputAsync<Order, OrderItems>(Queries.GetOrderDetails, parameters, cancellation); // Finally, ws.GetOrderDetails returns Order data in a single-row SELECT, then a list of OrderItems from a 2nd SELECT: _database.MapReaderAsync<Order, Order, OrderItems>(Queries.GetOrderDetails, parameters, cancellation); // Expanding this, we now have output parameters and three SELECTs: _database.MapOutputAsync<Store, OrderHistory, Locations, Contact>(Queries.GetStoreDetails, parameters, cancellation); // Likewise, the query now returns four SELECTs, and the third one is a single-row SELECT with the base customer data, // the remaining select are used to build customer property lists (order history, locations, and contacts): _database.MapReaderAsync<Store, OrderHistory, Store, Locations, Contact>(Queries.GetStoreDetails, parameters, cancellation); In both methods, the generic type in the first position is the return type. If additional results are included in the result stream, the subsequent types define the order in which they are expected in the DataReader results. You can have up to eight DataReader results streamed to distinct List properties. In the MapOutput* example, then, the result type is Order and the first DataReader result is a series of OrderItems. In the MapOutput* example, the result type is Order, and the first DataReader result is the Order data, and the second DataReader result is a series of OrderItems. The Query* Methods The Query* methods provide the most control, as you are given raw ADO.NET query results to construct whatever return value you like. You can return a list, a dictionary, or any type of Model object. When you call a Query* method, you must provide a handler method whose signature corresponds to the QueryResultModelHandler delegate. There are two obvious scenarios for the Query* methods: The Model class is defined in a library, so Mapping attributes cannot be added. The rendering a complex return value is beyond the capabilities of the Mapper. The delegate even has a parameter that allows you to provide custom data (through the query method) with which to construct your result object. The delegate must be thread-safe. The ShardSet manages the complexity of initializing multiple queries on multiple connections and multiple results, but it is the delegate that takes the database results (from each connection/thread) and creates an object result. Note The Mapper provides several thread-safe, high-performance QueryResultModelHandler delegates. In fact, providing a Mapper delegate to the Query* method is exactly how the MapOutput* an MapOutput* methods are implemented. You can use this yourself to extend the Mapper; just provide your own delegate that calls the Mapper in turn. Details on implementing the QueryResultModelHandler delegate is in the next section. Next: Handling Data Results"
  },
  "tutorials/Querying/batches.html": {
    "href": "tutorials/Querying/batches.html",
    "title": "Query Batches | ArgentSea Docs",
    "keywords": "Query Batches A Batch allows multiple commands to run within a single transaction on the same connection. For example, ArgentSea makes it easy to save a single “customer” record with multiple “locations”. However, using a batch you could save multiple customers, each with multiple locations — all within the same transaction. The real purpose of the Batch is that it allows non-query actions, like SqlBulkCopy (SQL Server) or the NpgsqlBinaryImporter (PostgreSQL) to be combined with queries within the same transaction. See multi-record saves for more information. Caution Because they involve multiple round-trips to the database server, Batches are less efficient than executing multiple SQL statements in a single command. You should avoid using batches to execute a series of statements that could be combined into a single command. Note Because client-managed transactions are much less efficient than server-side transactions, a Batch is the only place where ArgentSEa explicitly enlists ADO.NET transactions. Batch Types There are three types of batches. Each type offers somewhat different operations. DatabaseBatch can be used for non-sharded database connections. ShardBatch is for a specific shard in a shard set. ShardSetBatch can run the batch commands on every shard in the shard set. These commands cannot return a result. Batches are executed with the RunAsync command. The ShardSet’s RunAsync method will only accept a ShardSetBatch argument. Likewise, the Database or Shard connections will only accept the DatabaseBatch or ShardBatch respectively. Batches are simply collections of BatchStep objects. The BatchStep is abstract. You can implement your own BatchStep, but several implementations are available. The principal one enables execution of Query . ShardSet batches cannot not return a result, but the other batches use a generic argument to specify the type of the return value. For example, this batch will return a integer value when run: var batch = new DatabaseBatch<int>(); You use the Add method to set up the batch commands. The Add method has a fluent API: var batch = new DatabaseBatch<string>() .Add(Queries.CustomerLoadStuff, parameters) .Add(Queries.CustomerCreate, \"customername\"); var customerName = _database.Write.RunAsync(batch, cancellation); In this example, the batch is declared with a return type (of integer). The second step run a query that ultimately returns a value; the value in the first row with a column name of “customername” is returned to the caller. The Shard Set Batch Because the ShardSetBatch will run on multiple sharded databases, the ShardSetBatch does return data when executed. ArgentSea offers the ability to run a query ( QueryProcedure or QueryStatement ) on a ShardSetBatch , although a user-created implementation of a custom BatchStep<> could also be used. When creating a ShardSetBatch , the generic parameter is the shard id type. var batch = new ShardSetBatch<short>() .Add(Queries.UpdateCustomers, parameters) .Add(Queries.ProcessCustomers); await _shardSet.Write.RunAsync(batch, cancellation); The query can include input parameters. As with other query commands, if a shardParameters argument is provided, only the listed shards with be impacted — and the shard parameter values will be updated as per any matching argument values. Instantiation: Batch argument: Return Type: new ShardSetBatch<TShard>() Query none Custom BatchStep implementation varies none Caution The ShardSetBatch will likely perform more poorly than a single SQL command. The main circumstance where this would be useful is when the client application must dynamically assemble the Query set. Really, the ShardSetBatch seems to have a fairly limited number of use cases. The Shard Batch The ShardBatch can execute a query and return a Model result (using the Mapper), a ShardKey or a list of ShardKeys. For example, a batch that inserts records with identity columns might need to return the ShardKey(s) containing the identifiers of the newly inserted records. You can use ShardKey for a single record key result, or List<ShardKey> or IList<ShardKey> for a multi-record key result. The ShardBatch has two generic parameters. The first is the ubiquitous shard id type; the second is the return type. Note The methods that are available are determined by the return type specified in the second generic argument. For example, this would return the ShardKey of the new customer: var batch = new ShardBatch<short, ShardKey<short, int>>() .Add(Queries.CustomerCreate) .Add(Queries.CustomerGet, parameters, 'c', \"customerid\"); var customerKey = await _shardSet.DefaultShard.Write.RunAsync(batch, cancellation); Note that you must specify the DataOrigin value for the new ShardKey and the column name from which to get the new record id. To instead return a list of new keys from the query, make the return type a list: var batch = new ShardBatch<short, List<ShardKey<short, int>>>() .Add(Queries.CustomersCreate) .Add(Queries.CustomersGet, parameters, 'c', \"customerid\"); var customerKeys = await _shardSet.DefaultShard.Write.RunAsync(batch, cancellation); In both the above examples, the shard id of the resulting key will be set to the shard id of the current shard. If the query result contains shardkeys that reference other shards, simply provide the ShardId column name also: var batch = new ShardBatch<short, List<ShardKey<short, int>>>() .Add(Queries.CustomersCreate) .Add(Queries.CustomersGet, parameters, 'c', \"shardid\", \"customerid\"); var customerKeys = await _shardSet.DefaultShard.Write.RunAsync(batch, cancellation); Note If you do not need a result, you can simply specified the return type of object and the Run method will return null. Ideally, only one step in the batch should return a result. If multiple steps each return a result, only the last one with a valid value (non-null or non-default value) is returned to the client. Instantiation: Batch argument: Return Type: new ShardBatch<TShard, ShardKey<TShard, TRecord>>() Query ShardKey new ShardBatch<TShard, ShardKey<TShard, TRecord, TChild>>() Query ShardKey new ShardBatch<TShard, List<ShardKey<TShard, TRecord>>>() Query ShardKey List new ShardBatch<TShard, List<ShardKey<TShard, TRecord, TChild>>>() Query ShardKey List new ShardBatch<TShard, IList<ShardKey<TShard, TRecord>>>() Query ShardKey List new ShardBatch<TShard, IList<ShardKey<TShard, TRecord, TChild>>>() Query ShardKey List new ShardBatch<TShard, Model>() Query Model new ShardBatch<TShard, CustomBatchStep) varies any The Database Batch The DatabaseBatch object is similar to the ShardBatch object. It has one generic argument, which specifies the return type when executed. var batch = new DatabaseBatch<long>() .Add(Queries.CustomerCreate, parameters) .Add(Queries.CustomerList, \"customerid\"); var newCustomerId = _database.Write.RunAsync(batch4, cancellation); The return type can be a Model class (using the Mapper), a column value, or a list of column values. This allows you to return the identity value (or values) of an inserted record (or records). Note The methods that are available are determined by the return type specified in the generic argument. For example, this would return the identity value of the new customer: var batch = new DatabaseBatch<int>() .Add(Queries.CustomerPrep) .Add(Queries.CustomerCreate, parameters, \"customerid\"); var customerId = await _database.Write.RunAsync(batch, cancellation); To instead return a list of values from the query, make the return type a list: var batch = new DatabaseBatch<List<int>>() .Add(Queries.CustomerPrep) .Add(Queries.CustomersCreate, parameters, \"customerid\"); var customerIds = await _database.Write.RunAsync(batch, cancellation); Note If you do not need a result, you can simply specified the return type of object and the Run method will return null. Ideally, only one step in the batch should return a result. If multiple steps each return a result, only the last one with a valid value (non-null or non-default value) is returned to the client. Instantiation: Batch argument: Return Type: new DatabaseBatch<TRecord>() Query TRecord new DatabaseBatch<int>() Query int new DatabaseBatch<List<TRecord>>() Query Id List new DatabaseBatch<IList<TRecord>>() Query Id List new DatabaseBatch<Model>() Query Model new DatabaseBatch<CustomBatchStep) varies any Next: Multi-record Saves"
  },
  "tutorials/Querying/setparameters.html": {
    "href": "tutorials/Querying/setparameters.html",
    "title": "Setting Parameters | ArgentSea Docs",
    "keywords": "Setting Parameters With the ArgentSea framework, you need to set parameter values before a connection or command is created. The ADO.NET standard parameter collections cannot be created without a command object host. To fill this need, ArgentSea provides a QueryParameterCollection object, which is simply a collection of ADO.NET DbParameters. This object allow you to create an instance with a simple new statement. var parameters = new QueryParameterCollection(); ArgentSea provides a variety of extension methods to work with the parameters collection. Methods to easily add parameters to any parameters collection Methods to simplify obtaining values from parameters. Methods to Map Models properties to parameters. Note Parameter names are implicitly normalized. On SQL Server this means always ensuring a “@” prefix. On PostgreSQL, future versions might automatically convert to lowercase. Creating Parameters with Extension Methods ArgentSea offers a set of extension methods that simplify the code required to optimally create and populate parameters and also handle database nulls. The methods to add parameters to a collection are provider-specific, since they are converting .NET types to database types. This means that the extension methods won’t appear unless you have a using statement referencing the provider. SQL Server PostgreSQL Note The QueryParameterCollection and SqlParameterCollection inherit from the same base class. Not only can you use these methods on ArgentSea’s QueryParameterCollection , but you can also use them on the standard ADO.NET SqlCommand.Parameters property. To access the extension methods, you need the following using statement: using ArgentSea.Sql; Adding a correctly typed parameter now requires only one line: parameters.AddSqlIntInputParameter(\"@TransactionId\", transactionId); parameters.AddSqlDecimalInputParameter(\"@Amount\", amount, 16, 2); parameters.AddSqlNVarCharInputParameter(\"@Name\", name, 255); parameters.AddSqlFloatOutputParameter(\"@Temperature\"); These methods all support a fluent api, so these can be written instead as: var parameters = new QueryParameterCollection() .AddSqlIntInputParameter(\"@TransactionId\", transactionId) .AddSqlDecimalInputParameter(\"@Amount\", amount, 16, 2) .AddSqlNVarCharInputParameter(\"@Name\", name, 255) .AddSqlRealOutputParameter(\"@Temperature\"); And these methods also work directly on the data provider’s command parameters collection. cmd.Parameters.AddSqlIntInputParameter(\"@TransactionId\", transactionId) .AddSqlDecimalInputParameter(\"@Amount\", amount, 16, 2) .AddSqlNVarCharInputParameter(\"@Name\", name, 255) .AddSqlRealOutputParameter(\"@Temperature\"); Note The QueryParameterCollection and NpgsqlParameterCollection inherit from the same base class. Not only can you use these methods on ArgentSea’s QueryParameterCollection , but you can also use them on the standard ADO.NET NpgsqlCommand.Parameters property. To access the extension methods, you need the following using statement: using ArgentSea.Pg; Adding a correctly typed parameter now requires only one line: parameters.AddPgIntegerInputParameter(\"transactionid\", transactionId); parameters.AddPgDecimalInputParameter(\"amount\", amount, 16, 4); parameters.AddPgVarcharInputParameter(\"name\", name, 255); parameters.AddPgDoubleOutputParameter(\"temperature\"); These methods all support a fluent api, so these can be written instead as: var parameters = new QueryParameterCollection() .AddPgIntegerInputParameter(\"transactionid\", transactionId) .AddPgDecimalInputParameter(\"amount\", amount, 16, 2) .AddPgVarcharInputParameter(\"name\", name, 255) .AddPgDoubleOutputParameter(\"temperature\"); And these methods also work directly on the data provider’s command parameters collection. cmd.Parameters..AddPgIntegerInputParameter(\"transactionid\", transactionId) .AddPgDecimalInputParameter(\"amount\", amount, 16, 2) .AddPgVarcharInputParameter(\"name\", name, 255) .AddPgDoubleOutputParameter(\"temperature\"); Where appropriate, the methods have overloads that accept nullable value types. When the nullable type is null, the parameter will be set to a database Null value. If you are not using the Nullable overloads, then the values Guid.Empty, double.NaN, and float.NaN will also be saved as database Nulls. Likewise, null strings will be set to database Nulls, but empty strings will save as zero-length strings. The extension methods accepting string values have a max length argument, and those converting to Ansi database values have a code page parameter. The decimal methods have arguments for specifying precision and scale. Creating Parameters with the Mapper The Mapper uses Model property attributes to automatically generate code that is much like what would be created in the previous section. Assuming that the Model (in this example, a “Store” class) has Mapping attributes associated with each of its properties, you can render all the corresponding input parameters and set their respective values with: parameters.CreateInputParameters<Store>(store, logger); This one line of code is much easier than individually coding the creation of each parameter and setting each value. SQL Server PostgreSQL You can do something similar with output parameters. Because you will probably need at least one input parameter (likely a key), set that first. Then, when you generate the output parameters the Mapper will not duplicate this existing parameter with a redundant output parameter. parameters.AddSqlIntInputParameter(\"@TransactionId\", transactionId); parameters.CreateOutputParameters<Store>(logger); // Again, these methods all support a fluent api, so this can be written instead as: var parameters = new QueryParameterCollection() .AddSqlIntInputParameter(\"@TransactionId\", transactionId) .CreateOutputParameters<Store>(logger); Although ArgentSea can set and retrieve PostgreSQL output parameters, it is not a recommended practice . If you are determined to use output parameters, here is an example: parameters.AddPgIntegerInputParameter(\"transactionid\", transactionId); parameters.CreateOutputParameters<Store>(logger); // Again, these methods all support a fluent api, so this can be written instead as: var parameters = new QueryParameterCollection() .AddPgIntegerInputParameter(\"transactionid\", transactionId) .CreateOutputParameters<Store>(logger); Of course, you can always add parameters using standard ADO.NET syntax. SQL Server PostgreSQL var parameter = new System.Data.SqlClient.SqlParameter(); parameter.SqlDbType = System.Data.SqlDbType.Int; parameter.Value = transactionId; command.Parameters.Add(parameter); var parameter = new Npgsql.NpgsqlParameter(); parameter.NpgsqlDbType = NpgsqlType.Integer; parameter.Value = transactionId; command.Parameters.Add(parameter); This may be useful for types not yet supported by ArgentSea. Tip As you define parameters in your queries, naming them as consistently as possible will make using the Mapper easy. Next: Fetching Data"
  },
  "api/ArgentSea.MapShardChildAttribute.html": {
    "href": "api/ArgentSea.MapShardChildAttribute.html",
    "title": "Class MapShardChildAttribute | ArgentSea Docs",
    "keywords": "Class MapShardChildAttribute Inheritance System.Object System.Attribute MapShardChildAttribute Inherited Members System.Attribute.Equals(System.Object) System.Attribute.GetCustomAttribute(System.Reflection.Assembly, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.Assembly, System.Type, System.Boolean) System.Attribute.GetCustomAttribute(System.Reflection.MemberInfo, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.MemberInfo, System.Type, System.Boolean) System.Attribute.GetCustomAttribute(System.Reflection.Module, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.Module, System.Type, System.Boolean) System.Attribute.GetCustomAttribute(System.Reflection.ParameterInfo, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.ParameterInfo, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Assembly) System.Attribute.GetCustomAttributes(System.Reflection.Assembly, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Assembly, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.Assembly, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Module) System.Attribute.GetCustomAttributes(System.Reflection.Module, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Module, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.Module, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo, System.Type, System.Boolean) System.Attribute.GetHashCode() System.Attribute.IsDefaultAttribute() System.Attribute.IsDefined(System.Reflection.Assembly, System.Type) System.Attribute.IsDefined(System.Reflection.Assembly, System.Type, System.Boolean) System.Attribute.IsDefined(System.Reflection.MemberInfo, System.Type) System.Attribute.IsDefined(System.Reflection.MemberInfo, System.Type, System.Boolean) System.Attribute.IsDefined(System.Reflection.Module, System.Type) System.Attribute.IsDefined(System.Reflection.Module, System.Type, System.Boolean) System.Attribute.IsDefined(System.Reflection.ParameterInfo, System.Type) System.Attribute.IsDefined(System.Reflection.ParameterInfo, System.Type, System.Boolean) System.Attribute.Match(System.Object) System.Attribute.TypeId System.Object.Equals(System.Object, System.Object) System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class MapShardChildAttribute : Attribute Constructors | Improve this Doc View Source MapShardChildAttribute(DataOrigin, String, String) Declaration public MapShardChildAttribute(DataOrigin origin, string recordIdName, string childIdName) Parameters Type Name Description DataOrigin origin System.String recordIdName System.String childIdName | Improve this Doc View Source MapShardChildAttribute(DataOrigin, String, String, String) Declaration public MapShardChildAttribute(DataOrigin origin, string shardIdName, string recordIdName, string childIdName) Parameters Type Name Description DataOrigin origin System.String shardIdName System.String recordIdName System.String childIdName | Improve this Doc View Source MapShardChildAttribute(Char, String, String) Declaration public MapShardChildAttribute(char originValue, string recordIdName, string childIdName) Parameters Type Name Description System.Char originValue System.String recordIdName System.String childIdName | Improve this Doc View Source MapShardChildAttribute(Char, String, String, String) Declaration public MapShardChildAttribute(char originValue, string shardIdName, string recordIdName, string childIdName) Parameters Type Name Description System.Char originValue System.String shardIdName System.String recordIdName System.String childIdName Properties | Improve this Doc View Source ChildIdName Declaration public virtual string ChildIdName { get; set; } Property Value Type Description System.String | Improve this Doc View Source Origin Declaration public DataOrigin Origin { get; set; } Property Value Type Description DataOrigin | Improve this Doc View Source RecordIdName Declaration public virtual string RecordIdName { get; set; } Property Value Type Description System.String | Improve this Doc View Source ShardIdName Declaration public virtual string ShardIdName { get; set; } Property Value Type Description System.String"
  },
  "tutorials/Mapping/complexattributes.html": {
    "href": "tutorials/Mapping/complexattributes.html",
    "title": "Complex Attributes | ArgentSea Docs",
    "keywords": "Complex Attributes The Attribute tutorial described how the Mapper populates simple Model class properties, like numbers, strings, etc. This guide extends this information to account for complex objects that combine mapped values into a new object. There are three types of complex objects handled by the Mapper: Model Properties, via the MapToModel attribute List Properties Shard Identifiers, via the ShardKey attributes Models that inherit from parent Models The MapToModel Attribute Some Model objects may have properties that are objects with their own properties, which also need to be mapped to the underlying data. For example, you might have an Address object that contains street address, city, region, etc. Since this data is used for customer addresses, store addresses, vendor addresses, etc. you might have a single, shared Address model. The Customer, Store, and Vendor Models would all have an Address property of type Address Model. The MapToModel attribute tells the Mapper that this property contains an object that should also be mapped. SQL Server PostgreSQL public class Vendor { [MapToSqlInt(\"VendorId\")] public int VendorId { get; set; } //include other properties... [MapToModel] public Address VendorAddress { get; set; } } public class Store { [MapToSqlInt(\"StoreId\")] public int StoreId { get; set; } //include other properties... [MapToModel] public Address StoreAddress { get; set; } } public class Customer { [MapToSqlInt(\"CustomerId\")] public int CustomerId { get; set; } //include other properties... [MapToModel] public Address CustomerAddress { get; set; } } public class Address { [MapToSqlNVarChar(\"StreetAddress\", 255)] public string StreetAddress { get; set; } [MapToSqlNVarChar(\"Locality\", 100)] public string Locality { get; set; } [MapToSqlNVarChar(\"Region\", 100)] public string Region { get; set; } [MapToSqlNVarChar(\"PostalCode\", 25)] public string PostalCode { get; set; } } public class Vendor { [MapToPgInteger(\"VendorId\")] public int VendorId { get; set; } //include other properties... [MapToModel] public Address VendorAddress { get; set; } } public class Store { [MapToPgInteger(\"StoreId\")] public int StoreId { get; set; } //include other properties... [MapToModel] public Address StoreAddress { get; set; } } public class Customer { [MapToPgInteger(\"CustomerId\")] public int CustomerId { get; set; } //include other properties... [MapToModel] public Address CustomerAddress { get; set; } } public class Address { [MapToPgVarchar(\"StreetAddress\", 255)] public string StreetAddress { get; set; } [MapToPgVarchar(\"Locality\", 100)] public string Locality { get; set; } [MapToPgVarchar(\"Region\", 100)] public string Region { get; set; } [MapToPgVarchar(\"PostalCode\", 25)] public string PostalCode { get; set; } } In this example, the Vendor, Store, and Customer Models each have a property with an Address Model type. When mapping Vendor database results, the Mapper will map the StreetAddress column or parameter to Vendor.VendorAddress.StreetAddress. Likewise for the Store and Customer Models. In each case, the Address properties and attributes are simply included in the properties that the Mapper expects to see in the data results or parameters. In short, MapToModel simply extends the expected parameter or column lists with further values, but it offers the capability to reuse or encapsulate a column/parameter set in your code. Null Values The Mapper will automatically set the property to a new instance of the model object, if: The property value is null The property is settable (not readonly) The property model class has a default constructor Otherwise, simply instantiate the property’s object when the base Model class is created. public class Customer { [MapToModel] public Address CustomerAddress { get; } = new Address(); } As discussed earlier , the mapping attributes have a required argument — when set to true , a database null will cause the entire object to be null. This may not behave like you expect in this context: this does not cause the MapToModel property to become null; the entire parent model will be null. Essentially, a MapToModel property simply extends the Model with additional properties. Consequently, a “required” column that has a null database value will cause the entire Model to be null, not just the MapToModel property. Chaining MapToModel Properties In the example above, suppose the Address Model also had a MapToModel property — perhaps a Coordinates Model object. Theoretically, the Coordinates Model itself could also have a MapToModel property; the Mapper should be able to resolve nearly any number of chained MapToModel properties. All of these attributes are included in the data mapping. Lists The Mapper can also map to properties that contain lists ( List<Model> or IList<Model> ) of Model objects. This allows for one-to-many relationships. Mapping to a List works quite differently than MapToModel . The List data can only come from a data reader result. Because data readers can contain multiple results — which might be mapped to different list properties — the mapping and result order is specified at query time. For this reason, no attribute is required. Models in a List may themselves have child lists, but unlike MapToModel properties, they will be ignored by the Mapper. In cases where a result set must be transformed into a complete Model hierarchy, you can use the Query methods to bypass the Mapper. This allows you to hydrate the results in your own code, optionally invoking Mapper on parts of the result stream. List properties cannot be read-only. For the details on how to populate Models with List<Model> properties, see the discussion on querying . MapShardKey Attributes A ShardKey is a record identifier containing a shard Id and one or more record Ids. Essentially, it uniquely identifies a sharded record by combining the table key with the shard Id. Because the record identifier type is generic, you can use the ShardKey for any primary key or unique identity value. The shard id is always short/Int16/tinyint. ShardKey classes with multiple generic definitions can be used for tables that use up to four columns as compound keys. The MapShardKey attribute is used to decorate properties of type ShardKey . These are special types are reviewed in detail in the sharding section. Next: Mapping Targets"
  },
  "api/ArgentSea.MapShardKeyAttribute.html": {
    "href": "api/ArgentSea.MapShardKeyAttribute.html",
    "title": "Class MapShardKeyAttribute | ArgentSea Docs",
    "keywords": "Class MapShardKeyAttribute Inheritance System.Object System.Attribute MapShardKeyAttribute Inherited Members System.Attribute.Equals(System.Object) System.Attribute.GetCustomAttribute(System.Reflection.Assembly, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.Assembly, System.Type, System.Boolean) System.Attribute.GetCustomAttribute(System.Reflection.MemberInfo, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.MemberInfo, System.Type, System.Boolean) System.Attribute.GetCustomAttribute(System.Reflection.Module, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.Module, System.Type, System.Boolean) System.Attribute.GetCustomAttribute(System.Reflection.ParameterInfo, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.ParameterInfo, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Assembly) System.Attribute.GetCustomAttributes(System.Reflection.Assembly, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Assembly, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.Assembly, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Module) System.Attribute.GetCustomAttributes(System.Reflection.Module, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Module, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.Module, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo, System.Type, System.Boolean) System.Attribute.GetHashCode() System.Attribute.IsDefaultAttribute() System.Attribute.IsDefined(System.Reflection.Assembly, System.Type) System.Attribute.IsDefined(System.Reflection.Assembly, System.Type, System.Boolean) System.Attribute.IsDefined(System.Reflection.MemberInfo, System.Type) System.Attribute.IsDefined(System.Reflection.MemberInfo, System.Type, System.Boolean) System.Attribute.IsDefined(System.Reflection.Module, System.Type) System.Attribute.IsDefined(System.Reflection.Module, System.Type, System.Boolean) System.Attribute.IsDefined(System.Reflection.ParameterInfo, System.Type) System.Attribute.IsDefined(System.Reflection.ParameterInfo, System.Type, System.Boolean) System.Attribute.Match(System.Object) System.Attribute.TypeId System.Object.Equals(System.Object, System.Object) System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax [AttributeUsage(AttributeTargets.Property, AllowMultiple = false)] public class MapShardKeyAttribute : Attribute Constructors | Improve this Doc View Source MapShardKeyAttribute(DataOrigin, String) Declaration public MapShardKeyAttribute(DataOrigin origin, string recordIdName) Parameters Type Name Description DataOrigin origin System.String recordIdName | Improve this Doc View Source MapShardKeyAttribute(DataOrigin, String, String) Declaration public MapShardKeyAttribute(DataOrigin origin, string shardIdName, string recordIdName) Parameters Type Name Description DataOrigin origin System.String shardIdName System.String recordIdName | Improve this Doc View Source MapShardKeyAttribute(Char, String) Declaration public MapShardKeyAttribute(char originValue, string recordIdName) Parameters Type Name Description System.Char originValue System.String recordIdName | Improve this Doc View Source MapShardKeyAttribute(Char, String, String) Declaration public MapShardKeyAttribute(char originValue, string shardIdName, string recordIdName) Parameters Type Name Description System.Char originValue System.String shardIdName System.String recordIdName Properties | Improve this Doc View Source Origin Declaration public DataOrigin Origin { get; set; } Property Value Type Description DataOrigin | Improve this Doc View Source RecordIdName Declaration public virtual string RecordIdName { get; set; } Property Value Type Description System.String | Improve this Doc View Source ShardIdName Declaration public virtual string ShardIdName { get; set; } Property Value Type Description System.String"
  },
  "api/ArgentSea.Mapper.html": {
    "href": "api/ArgentSea.Mapper.html",
    "title": "Class Mapper | ArgentSea Docs",
    "keywords": "Class Mapper This static class contains the logic for mapping database parameters to/from properties. Inheritance System.Object Mapper Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public static class Mapper Methods | Improve this Doc View Source FromDataReader<TModel>(DbDataReader, ILogger) Accepts a data reader object and returns a list of objects of the specified type, one for each record. Declaration public static IList<TModel> FromDataReader<TModel>(DbDataReader rdr, ILogger logger) where TModel : class, new() Parameters Type Name Description System.Data.Common.DbDataReader rdr The data reader, set to the current result set. Microsoft.Extensions.Logging.ILogger logger The logger instance to write any processing or debug information to. Returns Type Description System.Collections.Generic.IList <TModel> A list of objects of the specified type, one for each result. Type Parameters Name Description TModel The type of the list result | Improve this Doc View Source FromDataReader<TShard, TModel>(TShard, DbDataReader, ILogger) Accepts a data reader object and returns a list of objects of the specified type, one for each record. Declaration public static IList<TModel> FromDataReader<TShard, TModel>(TShard shardId, DbDataReader rdr, ILogger logger) where TShard : IComparable where TModel : class, new() Parameters Type Name Description TShard shardId System.Data.Common.DbDataReader rdr The data reader, set to the current result set. Microsoft.Extensions.Logging.ILogger logger The logger instance to write any processing or debug information to. Returns Type Description System.Collections.Generic.IList <TModel> A list of objects of the specified type, one for each result. Type Parameters Name Description TShard TModel The type of the list result | Improve this Doc View Source MapToInParameters<TModel>(DbParameterCollection, TModel, ILogger) Accepts a Sql Parameter collection and appends Sql input parameters whose values correspond to the provided object properties and MapTo attributes. Declaration public static DbParameterCollection MapToInParameters<TModel>(this DbParameterCollection parameters, TModel model, ILogger logger) where TModel : class, new() Parameters Type Name Description System.Data.Common.DbParameterCollection parameters A parameter collection, generally belonging to a ADO.Net Command object. TModel model An object model instance. The property values are use as parameter values. Microsoft.Extensions.Logging.ILogger logger The logger instance to write any processing or debug information to. Returns Type Description System.Data.Common.DbParameterCollection Type Parameters Name Description TModel The type of the object. The \"MapTo\" attributes are used to create the Sql metadata and columns. | Improve this Doc View Source MapToInParameters<TModel>(DbParameterCollection, TModel, HashSet<String>, ILogger) Accepts a Sql Parameter collection and appends Sql input parameters whose values correspond to the provided object properties and MapTo attributes. Declaration public static DbParameterCollection MapToInParameters<TModel>(this DbParameterCollection parameters, TModel model, HashSet<string> ignoreParameters, ILogger logger) where TModel : class, new() Parameters Type Name Description System.Data.Common.DbParameterCollection parameters A parameter collection, generally belonging to a ADO.Net Command object. TModel model An object model instance. The property values are use as parameter values. System.Collections.Generic.HashSet < System.String > ignoreParameters A lists of parameter names that should not be created. Each entry must exactly match the parameter name, including prefix and casing. Microsoft.Extensions.Logging.ILogger logger The logger instance to write any processing or debug information to. Returns Type Description System.Data.Common.DbParameterCollection Type Parameters Name Description TModel The type of the object. The \"MapTo\" attributes are used to create the Sql metadata and columns. | Improve this Doc View Source MapToOutParameters(DbParameterCollection, Type, ILogger) Accepts a Sql Parameter collection and appends Sql output parameters corresponding to the MapTo attributes. Declaration public static DbParameterCollection MapToOutParameters(this DbParameterCollection parameters, Type TModel, ILogger logger) Parameters Type Name Description System.Data.Common.DbParameterCollection parameters A parameter collection, possibly belonging to a ADO.Net Command object or a QueryParmaters object. System.Type TModel The type of the object. The \"MapTo\" attributes are used to create the Sql parameter types. Microsoft.Extensions.Logging.ILogger logger The logger instance to write any processing or debug information to. Returns Type Description System.Data.Common.DbParameterCollection | Improve this Doc View Source MapToOutParameters(DbParameterCollection, Type, HashSet<String>, ILogger) Accepts a Sql Parameter collection and appends Sql output parameters corresponding to the MapTo attributes. Declaration public static DbParameterCollection MapToOutParameters(this DbParameterCollection parameters, Type TModel, HashSet<string> ignoreParameters, ILogger logger) Parameters Type Name Description System.Data.Common.DbParameterCollection parameters A parameter collection, generally belonging to a ADO.Net Command object. System.Type TModel System.Collections.Generic.HashSet < System.String > ignoreParameters A lists of parameter names that should not be created. Microsoft.Extensions.Logging.ILogger logger The logger instance to write any processing or debug information to. Returns Type Description System.Data.Common.DbParameterCollection | Improve this Doc View Source MapToOutParameters<TModel>(DbParameterCollection, ILogger) Accepts a Sql Parameter collection and appends Sql output parameters corresponding to the MapTo attributes. Declaration public static DbParameterCollection MapToOutParameters<TModel>(this DbParameterCollection parameters, ILogger logger) where TModel : class, new() Parameters Type Name Description System.Data.Common.DbParameterCollection parameters A parameter collection, possibly belonging to a ADO.Net Command object or a QueryParmaters object. Microsoft.Extensions.Logging.ILogger logger The logger instance to write any processing or debug information to. Returns Type Description System.Data.Common.DbParameterCollection The DbParameterCollection, enabling a fluent API. Type Parameters Name Description TModel The type of the object. The \"MapTo\" attributes are used to create the Sql parameter types. | Improve this Doc View Source MapToOutParameters<TModel>(DbParameterCollection, HashSet<String>, ILogger) Accepts a Sql Parameter collection and appends Sql output parameters corresponding to the MapTo attributes. Declaration public static DbParameterCollection MapToOutParameters<TModel>(this DbParameterCollection parameters, HashSet<string> ignoreParameters, ILogger logger) where TModel : class, new() Parameters Type Name Description System.Data.Common.DbParameterCollection parameters A parameter collection, possibly belonging to a ADO.Net Command object or a QueryParmaters object. System.Collections.Generic.HashSet < System.String > ignoreParameters A lists of parameter names that should not be created. Microsoft.Extensions.Logging.ILogger logger The logger instance to write any processing or debug information to. Returns Type Description System.Data.Common.DbParameterCollection The DbParameterCollection, enabling a fluent API. Type Parameters Name Description TModel The type of the object. The \"MapTo\" attributes are used to create the Sql parameter types. | Improve this Doc View Source QueryResultsHandler<TShard, TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TReaderResult7, TOutResult>(TShard, String, Object, DbDataReader, DbParameterCollection, String, ILogger) A function whose signature cooresponds to delegate QueryResultModelHandler and is used to map the provided model type(s) to query results. Declaration public static TModel QueryResultsHandler<TShard, TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TReaderResult7, TOutResult>(TShard shardId, string sprocName, object notUsed, DbDataReader rdr, DbParameterCollection parameters, string connectionDescription, ILogger logger) where TShard : IComparable where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TReaderResult5 : class, new() where TReaderResult6 : class, new() where TReaderResult7 : class, new() where TOutResult : class, new() Parameters Type Name Description TShard shardId This value will be provided to ShardKey or ShardChild objects. If not using sharded data, any provided value will be ignored. System.String sprocName The name of the stored procedure is used to cache the mapping metadata and also for provide richer logging information. System.Object notUsed This parameter is required to conform to the QueryResultModelHandler delegate signature. This argument should be null. System.Data.Common.DbDataReader rdr The data reader returned by the query. System.Data.Common.DbParameterCollection parameters The output parameters returned by the query. System.String connectionDescription The connection description is used to enrich logging information. Microsoft.Extensions.Logging.ILogger logger The logging instance to use for any logging requirements. Returns Type Description TModel An instance of TResult, with properties matching the provided data. Type Parameters Name Description TShard The type of the shardId value. Can be any value type if not used. TModel This is the expected return type of the handler. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. Set to Mapper.DummyType if not used. TReaderResult1 The second result set from data reader will be mapped an object or property of this type. Set to Mapper.DummyType if not used. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. Set to Mapper.DummyType if not used. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. Set to Mapper.DummyType if not used. TReaderResult4 The fifth result set from data reader will be mapped an object or property of this type. Set to Mapper.DummyType if not used. TReaderResult5 The sixth result set from data reader will be mapped an object or property of this type. Set to Mapper.DummyType if not used. TReaderResult6 The seventh result set from data reader will be mapped an object or property of this type. Set to Mapper.DummyType if not used. TReaderResult7 The eighth result set from data reader will be mapped an object or property of this type. Set to Mapper.DummyType if not used. TOutResult This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryResultsHandler<TShard, TModel>(TShard, String, Object, DbDataReader, DbParameterCollection, String, ILogger) Declaration public static TModel QueryResultsHandler<TShard, TModel>(TShard shardId, string sprocName, object notUsed, DbDataReader rdr, DbParameterCollection parameters, string connectionDescription, ILogger logger) where TShard : IComparable where TModel : class, new() Parameters Type Name Description TShard shardId System.String sprocName System.Object notUsed System.Data.Common.DbDataReader rdr System.Data.Common.DbParameterCollection parameters System.String connectionDescription Microsoft.Extensions.Logging.ILogger logger Returns Type Description TModel Type Parameters Name Description TShard TModel | Improve this Doc View Source QueryResultsHandler<TShard, TModel, TReaderResult, TOutParameters>(TShard, String, Object, DbDataReader, DbParameterCollection, String, ILogger) Declaration public static TModel QueryResultsHandler<TShard, TModel, TReaderResult, TOutParameters>(TShard shardId, string sprocName, object notUsed, DbDataReader rdr, DbParameterCollection parameters, string connectionDescription, ILogger logger) where TShard : IComparable where TModel : class, new() where TReaderResult : class, new() where TOutParameters : class, new() Parameters Type Name Description TShard shardId System.String sprocName System.Object notUsed System.Data.Common.DbDataReader rdr System.Data.Common.DbParameterCollection parameters System.String connectionDescription Microsoft.Extensions.Logging.ILogger logger Returns Type Description TModel Type Parameters Name Description TShard TModel TReaderResult TOutParameters | Improve this Doc View Source QueryResultsHandler<TShard, TModel, TReaderResult0, TReaderResult1, TOutParameters>(TShard, String, Object, DbDataReader, DbParameterCollection, String, ILogger) Declaration public static TModel QueryResultsHandler<TShard, TModel, TReaderResult0, TReaderResult1, TOutParameters>(TShard shardId, string sprocName, object notUsed, DbDataReader rdr, DbParameterCollection parameters, string connectionDescription, ILogger logger) where TShard : IComparable where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TOutParameters : class, new() Parameters Type Name Description TShard shardId System.String sprocName System.Object notUsed System.Data.Common.DbDataReader rdr System.Data.Common.DbParameterCollection parameters System.String connectionDescription Microsoft.Extensions.Logging.ILogger logger Returns Type Description TModel Type Parameters Name Description TShard TModel TReaderResult0 TReaderResult1 TOutParameters | Improve this Doc View Source QueryResultsHandler<TShard, TModel, TReaderResult0, TReaderResult1, TReaderResult2, TOutParameters>(TShard, String, DbDataReader, DbParameterCollection, String, ILogger) Declaration public static TModel QueryResultsHandler<TShard, TModel, TReaderResult0, TReaderResult1, TReaderResult2, TOutParameters>(TShard shardId, string sprocName, DbDataReader rdr, DbParameterCollection parameters, string connectionDescription, ILogger logger) where TShard : IComparable where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TOutParameters : class, new() Parameters Type Name Description TShard shardId System.String sprocName System.Data.Common.DbDataReader rdr System.Data.Common.DbParameterCollection parameters System.String connectionDescription Microsoft.Extensions.Logging.ILogger logger Returns Type Description TModel Type Parameters Name Description TShard TModel TReaderResult0 TReaderResult1 TReaderResult2 TOutParameters | Improve this Doc View Source QueryResultsHandler<TShard, TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TOutParameters>(TShard, String, Object, DbDataReader, DbParameterCollection, String, ILogger) Declaration public static TModel QueryResultsHandler<TShard, TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TOutParameters>(TShard shardId, string sprocName, object notUsed, DbDataReader rdr, DbParameterCollection parameters, string connectionDescription, ILogger logger) where TShard : IComparable where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TOutParameters : class, new() Parameters Type Name Description TShard shardId System.String sprocName System.Object notUsed System.Data.Common.DbDataReader rdr System.Data.Common.DbParameterCollection parameters System.String connectionDescription Microsoft.Extensions.Logging.ILogger logger Returns Type Description TModel Type Parameters Name Description TShard TModel TReaderResult0 TReaderResult1 TReaderResult2 TReaderResult3 TOutParameters | Improve this Doc View Source QueryResultsHandler<TShard, TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TOutParameters>(TShard, String, Object, DbDataReader, DbParameterCollection, String, ILogger) Declaration public static TModel QueryResultsHandler<TShard, TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TOutParameters>(TShard shardId, string sprocName, object notUsed, DbDataReader rdr, DbParameterCollection parameters, string connectionDescription, ILogger logger) where TShard : IComparable where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TOutParameters : class, new() Parameters Type Name Description TShard shardId System.String sprocName System.Object notUsed System.Data.Common.DbDataReader rdr System.Data.Common.DbParameterCollection parameters System.String connectionDescription Microsoft.Extensions.Logging.ILogger logger Returns Type Description TModel Type Parameters Name Description TShard TModel TReaderResult0 TReaderResult1 TReaderResult2 TReaderResult3 TReaderResult4 TOutParameters | Improve this Doc View Source QueryResultsHandler<TShard, TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TOutParameters>(TShard, String, Object, DbDataReader, DbParameterCollection, String, ILogger) Declaration public static TModel QueryResultsHandler<TShard, TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TOutParameters>(TShard shardId, string sprocName, object notUsed, DbDataReader rdr, DbParameterCollection parameters, string connectionDescription, ILogger logger) where TShard : IComparable where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TReaderResult5 : class, new() where TOutParameters : class, new() Parameters Type Name Description TShard shardId System.String sprocName System.Object notUsed System.Data.Common.DbDataReader rdr System.Data.Common.DbParameterCollection parameters System.String connectionDescription Microsoft.Extensions.Logging.ILogger logger Returns Type Description TModel Type Parameters Name Description TShard TModel TReaderResult0 TReaderResult1 TReaderResult2 TReaderResult3 TReaderResult4 TReaderResult5 TOutParameters | Improve this Doc View Source ReadOutParameters<TModel>(DbParameterCollection, ILogger) Creates a new object with property values based upon the provided output parameters which correspond to the MapTo attributes. Declaration public static TModel ReadOutParameters<TModel>(this DbParameterCollection parameters, ILogger logger) where TModel : class, new() Parameters Type Name Description System.Data.Common.DbParameterCollection parameters A parameter collection, generally belonging to a ADO.Net Command object after a database query. Microsoft.Extensions.Logging.ILogger logger The logger instance to write any processing or debug information to. Returns Type Description TModel An object of the specified type, with properties set to parameter values. Type Parameters Name Description TModel The type of the object. The \"MapTo\" attributes are used to read the Sql parameter collection values. | Improve this Doc View Source ReadOutParameters<TShard, TModel>(DbParameterCollection, TShard, ILogger) Creates a new object with property values based upon the provided output parameters which correspond to the MapTo attributes. Declaration public static TModel ReadOutParameters<TShard, TModel>(this DbParameterCollection parameters, TShard shardId, ILogger logger) where TShard : IComparable where TModel : class, new() Parameters Type Name Description System.Data.Common.DbParameterCollection parameters A parameter collection, generally belonging to a ADO.Net Command object after a database query. TShard shardId Microsoft.Extensions.Logging.ILogger logger The logger instance to write any processing or debug information to. Returns Type Description TModel An object of the specified type, with properties set to parameter values. Type Parameters Name Description TShard TModel The type of the object. The \"MapTo\" attributes are used to read the Sql parameter collection values."
  },
  "tutorials/Sharding/shardsets.html": {
    "href": "tutorials/Sharding/shardsets.html",
    "title": "ShardSets | ArgentSea Docs",
    "keywords": "ShardSets A “shard set” is a collection of databases with essentially identical schemas, each of which contain a segment of the data. Many — probably most — sharded applications will have only one ShardSet, but this supports contexts where multiple sharding plans exist. For example, User information might be sharded globally by datacenter location, while product availability information might be sharded by subsidiary (ok, this specious example might be better served via microservices; the point is that the framework does not preclude multiple ShardSets if you need them). The root injectable service is a ShardSets object, which is merely a collection of ShardSet instances. The ShardSets Class Hierarchy The ShardSets collection is the root of an object hierarchy. The child objects in the hierarchy are implemented as nested classes. This simplifies the implementation, but can also make declarations somewhat verbose. Nested classes ShardSets - the root collection, which provides access to any of the various sharding schemas. ShardSets.ShardSet - a collection of servers which have the same schema and different segments of data. ShardSets.ShardInstance - a shard (single data store) with one segment of data. Includes (optionally) separate read and write connections. ShardSets.DataConnection - A database connection to a shard. Accessing the ShardSets In .NET Core, the ShardSets collection is an injectable service. The instructions in the Configuration section can help you with setup. You can reference any ShardSet by name (i.e. a string key), which is also defined during configuration. Note that the key name is case/accent/kana sensitive; it must exactly match the value used in your configuration. Because it is unlikely that you would need to access more than one ShardSet in the same data access class, your class-level variable should capture only the relevant ShardSet. You can access a ShardSet by name (i.e. a string key value): SQL Server PostgreSQL public class SubscriberStore { private readonly SqlShardSets<string>.ShardSet _shardSet; private readonly ILogger<SubscriberStore> _logger; public SubscriberStore(SqlShardSets<string> shardSets, ILogger<SubscriberStore> logger) { _shardSet = shardSets[\"Subscribers\"]; _logger = logger; } public class SubscriberStore { private readonly PgShardSets<string>.ShardSet _shardSet; private readonly ILogger<SubscriberStore> _logger; public SubscriberStore(PgShardSets<string> shardSets, ILogger<SubscriberStore> logger) { _shardSet = shardSets[\"Subscribers\"]; _logger = logger; } } Querying a ShardSet There are two types of ShardSet queries: Queries on a particular shard - usually to obtain a specific record, like when you have a ShardKey. Queries across all shards - when you need a combined list or when don’t know the specific shard(s) to search. Accessing a Shard Access any shard in the ShardSet collection using a shardId key value, just like you would with any other collection. The ShardId value often comes from the ShardId property of a ShardKey ; for convenience, you can simply provide the ShardKey object instead. /// all of these are equally valid: var shard = myShardSet[myShardId]; var shard = myShardSet[myShardKey.ShardId]; var shard = myShardSet[myShardKey]; If you have implemented a solution using identity ranges, just call your custom resolver to get the shard index. The Default Shard When your data clients need to insert a new record, they need to know which shard within the ShardSet to put it in. If, for example, your shards are segmented by region, your regional clients should “default” to the appropriate shard when creating new records. This is configured by the DefaultShardId property in your ShardSet configuration. The default shard works exactly like any other shard, except that you do not need to specify a collection key; instead you can get it from the DefaultShard property. var shard = myShardSet.DefaultShard; Shard Connections Each shard has two data connections, exposed as Read property and a Write property. The Read and Write connection properties correspond to the read and write connections defined in your connection configuration . If you have both connections defined in your configuration, then the query will execute on the corresponding read or write connection; if only Read or Write is configured, it doesn’t matter which you use since they will both have the same connection. SQL Server PostgreSQL public async Task<Subscriber> GetSubscriber(ShardKey<byte, int> subscriberKey, CancellationToken cancellation) { var prms = new QueryParameterCollection() .AddSqlIntInputParameter(\"@SubId\", subscriberKey.RecordId); return await _shardSet[subscriberKey].Read.MapOutputAsync<Subscriber>(Queries.GetSubscriber, prms, cancellation); } public async Task<Subscriber> GetSubscriber(ShardKey<short, int> subscriberKey, CancellationToken cancellation) { var prms = new QueryParameterCollection() .AddPgIntegerInputParameter(\"SubId\", subscriberKey.RecordId); return await _shardSet[subscriberKey].Read.MapOutputAsync<Subscriber>(Queries.GetSubscriber, prms, cancellation); } Several database implementations — such as SQL Server Availability Groups or AWS Aurora PostgreSQL to name a couple of examples — enable a master server to handle both reads and writes and separate clone instances that can handle read-only traffic. Most applications have a greater percentage of reads than writes, so this is a great way to scale-out database access. However, there are two issues of concern: ArgentSea has no idea which queries update data and which are read-only, so it is left to the application developer to designate this by selecting the appropriate connection property (Read or Write). There is often some latency between the time that data is saved and when it is available from the read instance. This temporary data inconsistency can cause problems or confusion due to missing data. There are several architectural solutions to the latency-driven data inconsistency problem, such as intelligent caching, client observable collections, delayed retries, and retries on the Write connection. Due to the variations in environments, optimal solutions, and the challenge of simple determining when a missing record is really expected, ArgentSea does not attempt an automatic retry on the Write connection. To implement your own latency handling, you can easily implement an automatic retry using the Write connection after an unexpectedly missing record on the Read connection. In this example method we retrieve data by key value, so a missing record is unexpected and might be due to replication latency. The code assumes that the subscriber key has the “required” attribute set so that the Mapper returns a null object if the key is null. The resolution is to simply retry on the Write connection. var sub = await _shardSet[subscriberKey].Read.MapReaderAsync<Subscriber>(Queries.GetSubscriber, prms, cancellation); // add automatic retry on write connection if subscriber is not found. if (sub is null) { // consider logging the retry on the write connection var sub = await _shardSet[subscriberKey].Write.MapReaderAsync<Subscriber>(Queries.GetSubscriber, prms, cancellation); } return sub; } Tip Even if you are not using a scale-out strategy today, it would be a good idea to use the Read and Write properties as if you were. This would make a future migration to separate read and write instances a little easier. You might also consider using different database schemas for read-only and write-capable stored procedures. This helps underline the importance of separating read-only activity to your data developers. And testing may be easier if each connection’s permissions is limited to the appropriate schema. Shard Query Methods There are several query methods, described briefly below and in more detail in the querying tutorial. The arguments for these query methods are described in the next section. RunAsync Executes a stored procedure or SQL statement without returning a result — other than an Exception if it is not successful. Presumably, this method would only be called on the Write connection but nothing prevents running a query on the Read connection. This method also supports running a Batch , which is a set of statements which run within the same transaction. Batches on ShardSets do not return results, but batches on databases or shard instances can. ReturnValueAsync Executes a query and returns the value (string, number, etc.) of either the return result, output parameter, or first-row column. The result can also be a ShardKey. This method might be useful to lookup a single value from the shard rather than an entire record. Its principle and essential role, however, is to enable the return of inserted keys when identity columns are used. This method is available on individual shards, but not across the ShardSet. ListAsync Executes a query and returns a list containing a Model object, one entry for each record in the result set. The objects are created using Mapping attributes. If the Model object does not have attributes, you can create a List using QueryAsync with a custom handler. This method is available on both individual shards and the entire ShardSet. Results across ShardSets are combined into a single list. QueryAsync , QueryFirstAsync , and QueryAllAsync Executes a query and returns a (potentially complex) result object from output parameters and/or result sets. The method can create an arbitrary result (List, Dictionary, Model, etc.) via a custom delegate that constructs the response. MapOutputAsync , MapOutputFirstAsync , and MapOutputAllAsync Uses the Mapper to build a result using output parameters. The Mapper can use DataReader results to build list properties. MapOutputAsync is found on individual shards; MapOutputFirstAsync and MapOutputAllAsync are on ShardSets and return the first non-null result, or a list of all non-null results, respectively. MapReaderAsync , MapReaderFirstAsync , and MapReaderAllAsync Also uses the Mapper to build a results, but does so through a single-row DataReader result, rather than output parameters. List properties of the object result can also be populated through additional result sets. Note Parallelized queries across a ShardSet use the Read connection. Writes should be managed on individual shards. Arguments Query (required) The stored procedure or SQL statement to run. Parameters (required) In most cases this should be a QueryParametersCollection object. Technically, this argument can be any parameter collection, but the collections provided by ADO.NET are problematic: the DbParameterCollection is abstract, while the provider implementations (SqlParameterCollection and NpgsqlParameterCollection) can only be created by existing command objects. shardParameterOrdinal (optional) This parameter allows you to set a parameter to current ShardId value. For example, you might want to return a list of related records that do not exist on the current shard, but the database itself does not know its own shard number. Or perhaps the database does know its ShardId and, because mixing up ShardIds in your configuration would be catastrophic, you want to validate that the expected ShardId on the connection corresponds to the ShardId of the database (a practice that I follow). If set the argument to a value of zero or higher, ArgentSea will assign parameter at that (zero-based) index the value of the connection’s ShardId. If set to -1, no parameter will be assign a ShardId value. cancellationToken The cancellation token is used to cancel the query on all threads. Typically, you would pass the cancellation token from your MVC web method. resultHandler (optional) The QueryAsync method requires a method that knows how to convert the data results (output parameters and/or DataReader results) into an object instance. The result could be a Model, List, Dictionary, etc. The handler must have a method signature corresponding to the QueryResultModelHandler delegate. Because the ArgentSea Mapper includes method signature that can act as a QueryResultModelHandler delegate. The query methods that do not require this parameter assume the Mapper is being used. The generic result type must implement MapTo property attributes for the Mapper to function. TopOne Set this argument True if only one result is expected. For example, suppose you are searching a ShardSet for a User account matching a login. There should only be one match, so as soon as the first match is obtained you want to return the result object and abandon any remaining queries. Technically, when this argument is True, ArgentSea checks each shard query to see if it has a non-null Model result. If it finds one, it fires the cancellation token for any shard connection that has not yet completed, and returns the result. Of course, if the search conditions are not unique (which is difficult to enforce with sharded data), any duplicate result(s) will be lost."
  },
  "api/ArgentSea.ShardKey-2.html": {
    "href": "api/ArgentSea.ShardKey-2.html",
    "title": "Struct ShardKey<TShard, TRecord> | ArgentSea Docs",
    "keywords": "Struct ShardKey<TShard, TRecord> Immutable class representing a sharded record with a “compound” key: the (virtual) shardId and the (database) recordId. Implements System.IEquatable < ShardKey <TShard, TRecord>> Inherited Members System.Object.Equals(System.Object, System.Object) System.Object.GetType() System.Object.ReferenceEquals(System.Object, System.Object) Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public struct ShardKey<TShard, TRecord> : IEquatable<ShardKey<TShard, TRecord>> where TShard : IComparable where TRecord : IComparable Type Parameters Name Description TShard TRecord Constructors | Improve this Doc View Source ShardKey(DataOrigin, TShard, TRecord) Declaration public ShardKey(DataOrigin origin, TShard shardId, TRecord recordId) Parameters Type Name Description DataOrigin origin TShard shardId TRecord recordId | Improve this Doc View Source ShardKey(Char, TShard, TRecord) Declaration public ShardKey(char dataOrigin, TShard shardId, TRecord recordId) Parameters Type Name Description System.Char dataOrigin TShard shardId TRecord recordId Properties | Improve this Doc View Source Empty Declaration public static ShardKey<TShard, TRecord> Empty { get; } Property Value Type Description ShardKey <TShard, TRecord> | Improve this Doc View Source IsEmpty Declaration public bool IsEmpty { get; } Property Value Type Description System.Boolean | Improve this Doc View Source Origin Declaration public DataOrigin Origin { get; } Property Value Type Description DataOrigin | Improve this Doc View Source RecordId Declaration public TRecord RecordId { get; } Property Value Type Description TRecord | Improve this Doc View Source ShardId Declaration public TShard ShardId { get; } Property Value Type Description TShard Methods | Improve this Doc View Source Equals(ShardKey<TShard, TRecord>) Declaration public bool Equals(ShardKey<TShard, TRecord> other) Parameters Type Name Description ShardKey <TShard, TRecord> other Returns Type Description System.Boolean | Improve this Doc View Source Equals(Object) Declaration public override bool Equals(object obj) Parameters Type Name Description System.Object obj Returns Type Description System.Boolean Overrides System.ValueType.Equals(System.Object) | Improve this Doc View Source FromExternalString(String) Declaration public static ShardKey<TShard, TRecord> FromExternalString(string value) Parameters Type Name Description System.String value Returns Type Description ShardKey <TShard, TRecord> | Improve this Doc View Source GetHashCode() Declaration public override int GetHashCode() Returns Type Description System.Int32 Overrides System.ValueType.GetHashCode() | Improve this Doc View Source ToExternalString() Serializes ShardKey data into a URL-safe string with a checksum Declaration public string ToExternalString() Returns Type Description System.String A string which includes the concurrency stamp if defined and includeConcurrencyStamp is true, otherwise returns a smaller string . | Improve this Doc View Source ToString() Declaration public override string ToString() Returns Type Description System.String Overrides System.ValueType.ToString() Operators | Improve this Doc View Source Equality(ShardKey<TShard, TRecord>, ShardKey<TShard, TRecord>) Declaration public static bool operator ==(ShardKey<TShard, TRecord> sk1, ShardKey<TShard, TRecord> sk2) Parameters Type Name Description ShardKey <TShard, TRecord> sk1 ShardKey <TShard, TRecord> sk2 Returns Type Description System.Boolean | Improve this Doc View Source Inequality(ShardKey<TShard, TRecord>, ShardKey<TShard, TRecord>) Declaration public static bool operator !=(ShardKey<TShard, TRecord> sk1, ShardKey<TShard, TRecord> sk2) Parameters Type Name Description ShardKey <TShard, TRecord> sk1 ShardKey <TShard, TRecord> sk2 Returns Type Description System.Boolean Implements System.IEquatable<T>"
  },
  "api/ArgentSea.Test.StringExtensionTests.html": {
    "href": "api/ArgentSea.Test.StringExtensionTests.html",
    "title": "Class StringExtensionTests | ArgentSea Docs",
    "keywords": "Class StringExtensionTests Inheritance System.Object StringExtensionTests Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea.Test Assembly : ArgentSea.Test.dll Syntax public class StringExtensionTests Methods | Improve this Doc View Source TestEmojiLineStringCleaning() Declaration [Fact] public void TestEmojiLineStringCleaning() | Improve this Doc View Source TestEmojiTwoLineEndStringCleaning() Declaration [Fact] public void TestEmojiTwoLineEndStringCleaning() | Improve this Doc View Source TestNormalStringCleaning() Declaration [Fact] public void TestNormalStringCleaning() | Improve this Doc View Source TestNornalEmojiStringCleaning() Declaration [Fact] public void TestNornalEmojiStringCleaning() | Improve this Doc View Source TestTwoLineEmojiStringCleaning() Declaration [Fact] public void TestTwoLineEmojiStringCleaning() | Improve this Doc View Source TestWhitespaceStringCleaning() Declaration [Fact] public void TestWhitespaceStringCleaning()"
  },
  "tutorials/Configuration/configuration.html": {
    "href": "tutorials/Configuration/configuration.html",
    "title": "Configuration Deep-Dive | ArgentSea Docs",
    "keywords": "Configuration Deep-Dive Introduction The many environments required by SDLC processes — and possibly several Geo-dispersed production instances too — require application deployments in many distinct environments; managing configurations in each environment is already a challenge. Worse, sharded data sets can create a very large number of client connections, amplifying the configuration problem further. Then, scale-out of read and write endpoints doubles the number of connections. In the end, there can be a lot of connections to manage. ArgentSea is designed to make this potentially large number connections manageable. Using the configuration architecture in .NET core and a unique Hereditary Configuration Hierarchy , ArgentSea allows application changes to be promoted through staging environments and deployed into multiple production environments. It does this while storing passwords securely and without the need for messy transformations. ArgentSea Data Connections There are two types of data connections in ArgentSea: A database connection - a data set which is hosted by a single database A shard set - a data set spread over multiple database connections A shard set represents a set of data that is spread among multiple database servers. This structure is common for high-performance data access, since it is usually more cost effective and predictably scalable to have multiple smaller database servers than to build one massive server. Global applications might try to improve performance for their global users by distributing shards in datacenters around the globe. The ArgentSea data access components allow you to query across multiple servers or a find specific record on its corresponding host server. ArgentSea configuration supports any number of database definitions in the Databases collection , and any number of shard sets in the ShardSets collection. Each shard set can have any number of database connections (shard instances). All data connections have the option of separate read and write connections. If you are scaling-out your data access by sharding your data, you are likely also scaling-out by separating read activity from write operations. Even if you are not yet doing this, being explicit about it today makes a transition later much easier. This creates a potentially large number of connections. Many of these will likely have similar connection information. For example, all of the connections in a shard set might use the same login information or database name, varying only the server address. To manage this redundancy, ArgentSea offers a unique Hereditary Configuration Hierarchy . Next: The Hereditary Configuration Hierarchy"
  },
  "api/ArgentSea.DbDataStores-1.html": {
    "href": "api/ArgentSea.DbDataStores-1.html",
    "title": "Class DbDataStores<TConfiguration> | ArgentSea Docs",
    "keywords": "Class DbDataStores<TConfiguration> This class is used by provider specific implementations. It is unlikely that you would reference this in consumer code. This generic class manages non-sharded database connections. Inheritance System.Object DbDataStores<TConfiguration> Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class DbDataStores<TConfiguration> where TConfiguration : class, IDbDataConfigurationOptions, new() Type Parameters Name Description TConfiguration The provider-specific connection implementation. Constructors | Improve this Doc View Source DbDataStores(IOptions<TConfiguration>, IOptions<DataSecurityOptions>, IOptions<DataResilienceOptions>, IDataProviderServiceFactory, ILogger<DbDataStores<TConfiguration>>) Declaration public DbDataStores(IOptions<TConfiguration> configOptions, IOptions<DataSecurityOptions> securityOptions, IOptions<DataResilienceOptions> resilienceStrategiesOptions, IDataProviderServiceFactory dataProviderServices, ILogger<DbDataStores<TConfiguration>> logger) Parameters Type Name Description Microsoft.Extensions.Options.IOptions <TConfiguration> configOptions Microsoft.Extensions.Options.IOptions < DataSecurityOptions > securityOptions Microsoft.Extensions.Options.IOptions < DataResilienceOptions > resilienceStrategiesOptions IDataProviderServiceFactory dataProviderServices Microsoft.Extensions.Logging.ILogger < DbDataStores <TConfiguration>> logger Properties | Improve this Doc View Source DbConnections Declaration public DbDataStores<TConfiguration>.DbDataSets DbConnections { get; } Property Value Type Description DbDataStores.DbDataSets <>"
  },
  "api/ArgentSea.DataResilienceConfiguration.SequenceLengthening.html": {
    "href": "api/ArgentSea.DataResilienceConfiguration.SequenceLengthening.html",
    "title": "Enum DataResilienceConfiguration.SequenceLengthening | ArgentSea Docs",
    "keywords": "Enum DataResilienceConfiguration.SequenceLengthening Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public enum SequenceLengthening Fields Name Description Fibonacci HalfSquare Linear Squaring"
  },
  "api/ArgentSea.DataSecurityOptions.html": {
    "href": "api/ArgentSea.DataSecurityOptions.html",
    "title": "Class DataSecurityOptions | ArgentSea Docs",
    "keywords": "Class DataSecurityOptions This options class contains an array of SecurityConfiguration (login information). A connection can specify as particular login account by referencing a SecurityKey. Inheritance System.Object DataSecurityOptions Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class DataSecurityOptions Examples For example, you might configure your usersecrets.json like this: \"Credentials\": [ { \"SecurityKey\": \"0\", \"UserName\": \"user\", \"Password\": \"123456\" }, { \"SecurityKey\": \"1\", \"WindowsAuth\": true, }, { \"SecurityKey\": \"2\", \"UserName\": \"account\", \"Password\": \"7890\" } Properties | Improve this Doc View Source Credentials Declaration public SecurityConfiguration[] Credentials { get; set; } Property Value Type Description SecurityConfiguration []"
  },
  "api/ArgentSea.DbParameterCollectionExtensions.html": {
    "href": "api/ArgentSea.DbParameterCollectionExtensions.html",
    "title": "Class DbParameterCollectionExtensions | ArgentSea Docs",
    "keywords": "Class DbParameterCollectionExtensions Inheritance System.Object DbParameterCollectionExtensions Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public static class DbParameterCollectionExtensions Methods | Improve this Doc View Source GetBoolean(DbParameter) Declaration public static bool GetBoolean(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Boolean | Improve this Doc View Source GetByte(DbParameter) Declaration public static byte GetByte(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Byte | Improve this Doc View Source GetBytes(DbParameter) Returns a byte array, or null if the parameter value is DbNull. Declaration public static byte[] GetBytes(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Byte [] Parameter value as a byte[]. | Improve this Doc View Source GetDateTime(DbParameter) Declaration public static DateTime GetDateTime(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.DateTime | Improve this Doc View Source GetDateTimeOffset(DbParameter) Declaration public static DateTimeOffset GetDateTimeOffset(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.DateTimeOffset | Improve this Doc View Source GetDecimal(DbParameter) Declaration public static decimal GetDecimal(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Decimal | Improve this Doc View Source GetDouble(DbParameter) Returns a double (64-bit floating point) value from the parameter, or NaN (Not a Number) if the value is DbNull. Declaration public static double GetDouble(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Double Parameter value as double. | Improve this Doc View Source GetFloat(DbParameter) Returns a double (32-bit floating point) value from the parameter, or NaN (Not a Number) if the value is DbNull. Declaration public static float GetFloat(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Single Parameter value as float. | Improve this Doc View Source GetGuid(DbParameter) Returns a Guid value from the parameter, or Guid.Emtpy if the value is DbNull. Declaration public static Guid GetGuid(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Guid Parameter value as Guid. | Improve this Doc View Source GetInteger(DbParameter) Declaration public static int GetInteger(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Int32 | Improve this Doc View Source GetLong(DbParameter) Returns a Char value from the parameter, or NUL (char 0) if the value is DbNull. Declaration public static long GetLong(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Int64 Parameter value as Char. | Improve this Doc View Source GetNullableBoolean(DbParameter) Declaration public static bool? GetNullableBoolean(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Nullable < System.Boolean > | Improve this Doc View Source GetNullableByte(DbParameter) Declaration public static byte? GetNullableByte(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Nullable < System.Byte > | Improve this Doc View Source GetNullableDateTime(DbParameter) Declaration public static DateTime? GetNullableDateTime(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Nullable < System.DateTime > | Improve this Doc View Source GetNullableDateTimeOffset(DbParameter) Declaration public static DateTimeOffset? GetNullableDateTimeOffset(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Nullable < System.DateTimeOffset > | Improve this Doc View Source GetNullableDecimal(DbParameter) Declaration public static decimal? GetNullableDecimal(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Nullable < System.Decimal > | Improve this Doc View Source GetNullableDouble(DbParameter) Declaration public static double? GetNullableDouble(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Nullable < System.Double > | Improve this Doc View Source GetNullableFloat(DbParameter) Declaration public static float? GetNullableFloat(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Nullable < System.Single > | Improve this Doc View Source GetNullableGuid(DbParameter) Declaration public static Guid? GetNullableGuid(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Nullable < System.Guid > | Improve this Doc View Source GetNullableInteger(DbParameter) Declaration public static int? GetNullableInteger(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Nullable < System.Int32 > | Improve this Doc View Source GetNullableLong(DbParameter) Declaration public static long? GetNullableLong(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Nullable < System.Int64 > | Improve this Doc View Source GetNullableShort(DbParameter) Declaration public static short? GetNullableShort(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Nullable < System.Int16 > | Improve this Doc View Source GetNullableTimeSpan(DbParameter) Declaration public static TimeSpan? GetNullableTimeSpan(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Nullable < System.TimeSpan > | Improve this Doc View Source GetShort(DbParameter) Declaration public static short GetShort(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.Int16 | Improve this Doc View Source GetString(DbParameter) Returns a string, or null if the parameter value is DbNull. Declaration public static string GetString(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.String Parameter value as a string. | Improve this Doc View Source GetTimeSpan(DbParameter) Declaration public static TimeSpan GetTimeSpan(this DbParameter prm) Parameters Type Name Description System.Data.Common.DbParameter prm Returns Type Description System.TimeSpan"
  },
  "api/ArgentSea.ExpressionHelpers.html": {
    "href": "api/ArgentSea.ExpressionHelpers.html",
    "title": "Class ExpressionHelpers | ArgentSea Docs",
    "keywords": "Class ExpressionHelpers This class is used by provider specific implementations. It is unlikely that you would reference this in consumer code. Inheritance System.Object ExpressionHelpers Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public static class ExpressionHelpers Methods | Improve this Doc View Source InParameterEnumXIntExpressionBuilder(String, Type, String, Type, IList<Expression>, ParameterExpression, ParameterExpression, HashSet<String>, Expression, Type, ParameterExpression, ILogger) Declaration public static void InParameterEnumXIntExpressionBuilder(string parameterName, Type staticType, string addMethodName, Type nullableBaseType, IList<Expression> expressions, ParameterExpression expSprocParameters, ParameterExpression expIgnoreParameters, HashSet<string> parameterNames, Expression propValue, Type propertyType, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.String parameterName System.Type staticType System.String addMethodName System.Type nullableBaseType System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression expSprocParameters System.Linq.Expressions.ParameterExpression expIgnoreParameters System.Collections.Generic.HashSet < System.String > parameterNames System.Linq.Expressions.Expression propValue System.Type propertyType System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source InParameterSimpleBuilder(String, Type, ParameterExpression, ParameterExpression, Expression, IList<Expression>, Type, String, ConstantExpression, ConstantExpression, HashSet<String>, ParameterExpression, ILogger) Declaration public static void InParameterSimpleBuilder(string parameterName, Type propertyType, ParameterExpression expSprocParameters, ParameterExpression expIgnoreParameters, Expression expProperty, IList<Expression> expressions, Type staticType, string addMethod, ConstantExpression thirdArg, ConstantExpression forthArg, HashSet<string> parameterNames, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.String parameterName System.Type propertyType System.Linq.Expressions.ParameterExpression expSprocParameters System.Linq.Expressions.ParameterExpression expIgnoreParameters System.Linq.Expressions.Expression expProperty System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Type staticType System.String addMethod System.Linq.Expressions.ConstantExpression thirdArg System.Linq.Expressions.ConstantExpression forthArg System.Collections.Generic.HashSet < System.String > parameterNames System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source InParameterStringExpressionBuilder(String, Int32, Type, String, ConstantExpression, IList<Expression>, ParameterExpression, ParameterExpression, HashSet<String>, Expression, Type, ParameterExpression, ILogger) Declaration public static void InParameterStringExpressionBuilder(string parameterName, int length, Type staticType, string methodName, ConstantExpression expLocale, IList<Expression> expressions, ParameterExpression expSprocParameters, ParameterExpression expIgnoreParameters, HashSet<string> parameterNames, Expression propValue, Type propertyType, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.String parameterName System.Int32 length System.Type staticType System.String methodName System.Linq.Expressions.ConstantExpression expLocale System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression expSprocParameters System.Linq.Expressions.ParameterExpression expIgnoreParameters System.Collections.Generic.HashSet < System.String > parameterNames System.Linq.Expressions.Expression propValue System.Type propertyType System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source InParmHelper(String, ParameterExpression, Expression, Type, String, ConstantExpression, ConstantExpression, ParameterExpression) Declaration public static Expression InParmHelper(string parameterName, ParameterExpression expSprocParameters, Expression propValue, Type staticType, string addMethod, ConstantExpression thirdArg, ConstantExpression forthArg, ParameterExpression expIgnoreParameters) Parameters Type Name Description System.String parameterName System.Linq.Expressions.ParameterExpression expSprocParameters System.Linq.Expressions.Expression propValue System.Type staticType System.String addMethod System.Linq.Expressions.ConstantExpression thirdArg System.Linq.Expressions.ConstantExpression forthArg System.Linq.Expressions.ParameterExpression expIgnoreParameters Returns Type Description System.Linq.Expressions.Expression | Improve this Doc View Source OutParameterBuilder(String, ParameterExpression, IList<Expression>, Type, String, ConstantExpression, ConstantExpression, HashSet<String>, ParameterExpression, ILogger) Declaration public static void OutParameterBuilder(string parameterName, ParameterExpression expSprocParameters, IList<Expression> expressions, Type staticType, string addMethod, ConstantExpression secondArg, ConstantExpression thirdArg, HashSet<string> parameterNames, ParameterExpression expIgnoreParameters, ILogger logger) Parameters Type Name Description System.String parameterName System.Linq.Expressions.ParameterExpression expSprocParameters System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Type staticType System.String addMethod System.Linq.Expressions.ConstantExpression secondArg System.Linq.Expressions.ConstantExpression thirdArg System.Collections.Generic.HashSet < System.String > parameterNames System.Linq.Expressions.ParameterExpression expIgnoreParameters Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source ReaderEnumXIntExpressions(String, Expression, Type, IList<MethodCallExpression>, IList<Expression>, ParameterExpression, ParameterExpression, ParameterExpression, ref Int32, Type, ParameterExpression, ILogger) Declaration public static void ReaderEnumXIntExpressions(string columnName, Expression expProperty, Type baseType, IList<MethodCallExpression> columnLookupExpressions, IList<Expression> expressions, ParameterExpression prmSqlRdr, ParameterExpression expOrdinals, ParameterExpression expOrdinal, ref int propIndex, Type propertyType, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.String columnName System.Linq.Expressions.Expression expProperty System.Type baseType System.Collections.Generic.IList < System.Linq.Expressions.MethodCallExpression > columnLookupExpressions System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression prmSqlRdr System.Linq.Expressions.ParameterExpression expOrdinals System.Linq.Expressions.ParameterExpression expOrdinal System.Int32 propIndex System.Type propertyType System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source ReaderNullableValueTypeExpressions(String, Expression, ConstantExpression, IList<MethodCallExpression>, IList<Expression>, ParameterExpression, ParameterExpression, ParameterExpression, ref Int32, Type, ParameterExpression, ILogger) Declaration public static void ReaderNullableValueTypeExpressions(string columnName, Expression expProperty, ConstantExpression expNullResult, IList<MethodCallExpression> columnLookupExpressions, IList<Expression> expressions, ParameterExpression prmSqlRdr, ParameterExpression expOrdinals, ParameterExpression expOrdinal, ref int propIndex, Type propertyType, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.String columnName System.Linq.Expressions.Expression expProperty System.Linq.Expressions.ConstantExpression expNullResult System.Collections.Generic.IList < System.Linq.Expressions.MethodCallExpression > columnLookupExpressions System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression prmSqlRdr System.Linq.Expressions.ParameterExpression expOrdinals System.Linq.Expressions.ParameterExpression expOrdinal System.Int32 propIndex System.Type propertyType System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source ReaderSimpleValueExpressions(String, Expression, IList<MethodCallExpression>, IList<Expression>, ParameterExpression, ParameterExpression, ParameterExpression, ref Int32, Type, ParameterExpression, ILogger) Declaration public static void ReaderSimpleValueExpressions(string columnName, Expression expProperty, IList<MethodCallExpression> columnLookupExpressions, IList<Expression> expressions, ParameterExpression prmSqlRdr, ParameterExpression expOrdinals, ParameterExpression expOrdinal, ref int propIndex, Type propertyType, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.String columnName System.Linq.Expressions.Expression expProperty System.Collections.Generic.IList < System.Linq.Expressions.MethodCallExpression > columnLookupExpressions System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression prmSqlRdr System.Linq.Expressions.ParameterExpression expOrdinals System.Linq.Expressions.ParameterExpression expOrdinal System.Int32 propIndex System.Type propertyType System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source ReaderStringExpressions(String, Expression, IList<MethodCallExpression>, IList<Expression>, ParameterExpression, ParameterExpression, ParameterExpression, ref Int32, Type, ParameterExpression, ILogger) Declaration public static void ReaderStringExpressions(string columnName, Expression expProperty, IList<MethodCallExpression> columnLookupExpressions, IList<Expression> expressions, ParameterExpression prmSqlRdr, ParameterExpression expOrdinals, ParameterExpression expOrdinal, ref int propIndex, Type propertyType, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.String columnName System.Linq.Expressions.Expression expProperty System.Collections.Generic.IList < System.Linq.Expressions.MethodCallExpression > columnLookupExpressions System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression prmSqlRdr System.Linq.Expressions.ParameterExpression expOrdinals System.Linq.Expressions.ParameterExpression expOrdinal System.Int32 propIndex System.Type propertyType System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source ReadOutParameterBinaryExpressions(String, Type, String, Expression, IList<Expression>, ParameterExpression, ParameterExpression, Type, ParameterExpression, ILogger) Declaration public static void ReadOutParameterBinaryExpressions(string parameterName, Type staticType, string getMethodName, Expression expProperty, IList<Expression> expressions, ParameterExpression expPrms, ParameterExpression expPrm, Type propertyType, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.String parameterName System.Type staticType System.String getMethodName System.Linq.Expressions.Expression expProperty System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression expPrms System.Linq.Expressions.ParameterExpression expPrm System.Type propertyType System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source ReadOutParameterEnumXIntExpressions(String, Type, String, String, Expression, IList<Expression>, ParameterExpression, ParameterExpression, Type, ParameterExpression, ILogger) Declaration public static void ReadOutParameterEnumXIntExpressions(string parameterName, Type staticType, string getMethodName, string nullableGetMethodName, Expression expProperty, IList<Expression> expressions, ParameterExpression expPrms, ParameterExpression expPrm, Type propertyType, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.String parameterName System.Type staticType System.String getMethodName System.String nullableGetMethodName System.Linq.Expressions.Expression expProperty System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression expPrms System.Linq.Expressions.ParameterExpression expPrm System.Type propertyType System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source ReadOutParameterSimpleValueExpressions(String, Type, String, String, Expression, IList<Expression>, ParameterExpression, ParameterExpression, Type, ParameterExpression, ILogger) Declaration public static void ReadOutParameterSimpleValueExpressions(string parameterName, Type staticType, string getMethodName, string nullableGetMethodName, Expression expProperty, IList<Expression> expressions, ParameterExpression expPrms, ParameterExpression expPrm, Type propertyType, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.String parameterName System.Type staticType System.String getMethodName System.String nullableGetMethodName System.Linq.Expressions.Expression expProperty System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression expPrms System.Linq.Expressions.ParameterExpression expPrm System.Type propertyType System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger | Improve this Doc View Source ReadOutParameterStringExpressions(String, Type, String, Expression, IList<Expression>, ParameterExpression, ParameterExpression, Type, ParameterExpression, ILogger) Declaration public static void ReadOutParameterStringExpressions(string parameterName, Type staticType, string getMethodName, Expression expProperty, IList<Expression> expressions, ParameterExpression expPrms, ParameterExpression expPrm, Type propertyType, ParameterExpression expLogger, ILogger logger) Parameters Type Name Description System.String parameterName System.Type staticType System.String getMethodName System.Linq.Expressions.Expression expProperty System.Collections.Generic.IList < System.Linq.Expressions.Expression > expressions System.Linq.Expressions.ParameterExpression expPrms System.Linq.Expressions.ParameterExpression expPrm System.Type propertyType System.Linq.Expressions.ParameterExpression expLogger Microsoft.Extensions.Logging.ILogger logger"
  },
  "api/ArgentSea.IShardDataConfigurationOptions-1.html": {
    "href": "api/ArgentSea.IShardDataConfigurationOptions-1.html",
    "title": "Interface IShardDataConfigurationOptions<TShard> | ArgentSea Docs",
    "keywords": "Interface IShardDataConfigurationOptions<TShard> This interface is used by provider specific implementations. It is unlikely that you would implement this in consumer code. Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public interface IShardDataConfigurationOptions<TShard> where TShard : IComparable Type Parameters Name Description TShard Properties | Improve this Doc View Source ShardSetsInternal Declaration IShardConnectionsConfiguration<TShard>[] ShardSetsInternal { get; } Property Value Type Description IShardConnectionsConfiguration <TShard>[]"
  },
  "api/ArgentSea.DataResilienceConfiguration.html": {
    "href": "api/ArgentSea.DataResilienceConfiguration.html",
    "title": "Class DataResilienceConfiguration | ArgentSea Docs",
    "keywords": "Class DataResilienceConfiguration This class contains the definition for a data resiliance strategy. Specifically: when to retry and when to circuit break. This class is created as a configuration entry in an array in the DataResilienceStrategies property of the DataConfigurationOptions class. Inheritance System.Object DataResilienceConfiguration Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class DataResilienceConfiguration Properties | Improve this Doc View Source CircuitBreakerFailureCount If a connection or command consistantly fails, the circuit breaker will reject all further connections until one suceeds. This setting determines how many failures (after retries, if retry-able) before blocking all connections apart from a few periodic test attempts. Declaration public int CircuitBreakerFailureCount { get; set; } Property Value Type Description System.Int32 | Improve this Doc View Source CircuitBreakerTestInterval If a connection or command fails, the circuit breaker will reject all further connections until one suceeds. This setting determines how long (in milliseonds) the system should wait before allowing a test connection. Declaration public int CircuitBreakerTestInterval { get; set; } Property Value Type Description System.Int32 | Improve this Doc View Source ResilienceKey Declaration public string ResilienceKey { get; set; } Property Value Type Description System.String | Improve this Doc View Source RetryCount Declaration public int RetryCount { get; set; } Property Value Type Description System.Int32 | Improve this Doc View Source RetryInterval This is the number of milliseconds to wait before retrying a “retry-able” connection or command error. Default is 500 ms. This interval may be extended with each retry, depending upon the RetryLengthening setting, up to RetryCount. Declaration public int RetryInterval { get; set; } Property Value Type Description System.Int32 | Improve this Doc View Source RetryLengthening If a connection or command fails, this setting determines how much each subsequent retry should be further delayed. Declaration public DataResilienceConfiguration.SequenceLengthening RetryLengthening { get; set; } Property Value Type Description DataResilienceConfiguration.SequenceLengthening Methods | Improve this Doc View Source HandleRetryTimespan(Int32) Declaration public TimeSpan HandleRetryTimespan(int attempt) Parameters Type Name Description System.Int32 attempt Returns Type Description System.TimeSpan"
  },
  "api/ArgentSea.ShardDataStores-2.ShardDataSets.html": {
    "href": "api/ArgentSea.ShardDataStores-2.ShardDataSets.html",
    "title": "Class ShardDataStores<TShard, TConfiguration>.ShardDataSets | ArgentSea Docs",
    "keywords": "Class ShardDataStores<TShard, TConfiguration>.ShardDataSets Inheritance System.Object ShardDataStores<TShard, TConfiguration>.ShardDataSets Implements System.Collections.ICollection System.Collections.IEnumerable Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class ShardDataSets : ICollection, IEnumerable Constructors | Improve this Doc View Source ShardDataSets(ShardDataStores<TShard, TConfiguration>, IShardConnectionsConfiguration<TShard>[]) Declaration public ShardDataSets(ShardDataStores<TShard, TConfiguration> parent, IShardConnectionsConfiguration<TShard>[] config) Parameters Type Name Description ShardDataStores <TShard, TConfiguration> parent IShardConnectionsConfiguration <TShard>[] config Properties | Improve this Doc View Source Count Declaration public int Count { get; } Property Value Type Description System.Int32 | Improve this Doc View Source IsSynchronized Declaration public bool IsSynchronized { get; } Property Value Type Description System.Boolean | Improve this Doc View Source Item[String] Declaration public ShardDataStores<TShard, TConfiguration>.ShardDataSet this[string key] { get; } Parameters Type Name Description System.String key Property Value Type Description ShardDataStores.ShardDataSet <> | Improve this Doc View Source SyncRoot Declaration public object SyncRoot { get; } Property Value Type Description System.Object Methods | Improve this Doc View Source CopyTo(Array, Int32) Declaration public void CopyTo(Array array, int index) Parameters Type Name Description System.Array array System.Int32 index | Improve this Doc View Source GetEnumerator() Declaration public IEnumerator GetEnumerator() Returns Type Description System.Collections.IEnumerator Implements System.Collections.ICollection System.Collections.IEnumerable"
  },
  "tutorials/Mapping/mapping.html": {
    "href": "tutorials/Mapping/mapping.html",
    "title": "Mapping | ArgentSea Docs",
    "keywords": "Mapping The Mapper make data-access coding simpler and more productive by using property attributes to map a model class’s properties to data values — parameters, reader columns, and (in the case of SQL Server) table-value parameters. This reduces and simplifies the amount of code required to render data. Overview Using the Mapper consists of two parts: Add attributes to a model class define how each property should be mapped to a data store (if at all) Call a method which maps properties to parameters and/or maps data results to properties By defining metadata about the names of parameters or result columns, the Mapper can automatically map properties to columns and/or parameters. Several query methods on both Database connections and ShardSets implicitly use the Mapper. Performance The ArgentSea Mapper is written to be as high-performance as optimized hand-coded data access code. However, there is a hitch. Property attributes can only be retrieved using reflection , which is relatively slow .NET code. To avoid this type of performance penalty on every data access, ArgentSea uses reflection only the first time the mapping is performed; using that metadata it then creates and compiles an “Expression Tree”to build an optimized, compiled mapping. The compiled code is cached in memory and reused for all subsequent calls. Warning The Mapper will be relatively slow (and CPU intensive) the first time each model class is mapped to parameters or data. The initial compilation usually takes less than a second. Subsequent calls will execute the data to property mapping at native machine-code speeds. When the application is restarted, the memory is cleared and the compilation overhead occurs again. Missing Parameters or Columns In some cases, the Model may have more properties than are defined in a parameter list or in data reader columns. When this happens, ArgentSea is somewhat forgiving. As part of a Query definition ( QueryStatement or QueryProcedure class), you can optionally specify the parameter set. If set, only parameters included in this list will be mapped from the Model object. This is a great way to suppress values not needed for this particular request. Of course, if the Mapper sets/reads/writes parameters and the query does not include that parameter, ADO.NET will return an error if the query is sent to the database. If a data reader result does not contain an expected column, the property is simply ignored. If the logging level is “Debug” or lower, a log message will be created including the Model name and column name. Next: Property Attributes"
  },
  "api/ArgentSea.InvalidMapTypeException.html": {
    "href": "api/ArgentSea.InvalidMapTypeException.html",
    "title": "Class InvalidMapTypeException | ArgentSea Docs",
    "keywords": "Class InvalidMapTypeException This exception is raise when a model property has a database mapping attribute that is not of the correct type. Inheritance System.Object System.Exception InvalidMapTypeException Implements System.Runtime.Serialization.ISerializable Inherited Members System.Exception.GetBaseException() System.Exception.GetObjectData(System.Runtime.Serialization.SerializationInfo, System.Runtime.Serialization.StreamingContext) System.Exception.GetType() System.Exception.ToString() System.Exception.Data System.Exception.HelpLink System.Exception.HResult System.Exception.InnerException System.Exception.Message System.Exception.Source System.Exception.StackTrace System.Exception.TargetSite System.Exception.SerializeObjectState System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public sealed class InvalidMapTypeException : Exception, ISerializable Examples An attempt to map a string property to an integer parameter would generate this error. Constructors | Improve this Doc View Source InvalidMapTypeException() Initializes a new instance of the InvalidMapTypeException class with no error message. Declaration public InvalidMapTypeException() | Improve this Doc View Source InvalidMapTypeException(PropertyInfo, Int32) Initializes a new instance of the InvalidMapTypeException class. Declaration public InvalidMapTypeException(PropertyInfo property, int sqlType) Parameters Type Name Description System.Reflection.PropertyInfo property The property decorated with the mapping attribute. System.Int32 sqlType The stored procedure parameter type (int, not enum, due to provider discrepancies). | Improve this Doc View Source InvalidMapTypeException(String) Initializes a new instance of the InvalidMapTypeException class with a specified error message. Declaration public InvalidMapTypeException(string message) Parameters Type Name Description System.String message The message that describes the error. | Improve this Doc View Source InvalidMapTypeException(String, Exception) Initializes a new instance of the InvalidMapTypeException class. Declaration public InvalidMapTypeException(string message, Exception innerException) Parameters Type Name Description System.String message The message that describes the error. System.Exception innerException The exception that is the cause of the current exception. | Improve this Doc View Source InvalidMapTypeException(String, Type, Int32) Declaration public InvalidMapTypeException(string variableName, Type type, int sqlType) Parameters Type Name Description System.String variableName System.Type type System.Int32 sqlType Implements System.Runtime.Serialization.ISerializable"
  },
  "api/ArgentSea.ShardChild-3.html": {
    "href": "api/ArgentSea.ShardChild-3.html",
    "title": "Struct ShardChild<TShard, TRecord, TChild> | ArgentSea Docs",
    "keywords": "Struct ShardChild<TShard, TRecord, TChild> Immutable class representing a sharded record with a database compound key. The ShardChild consist of the (virtual) shardId, the recordId, and the childId. Implements System.IEquatable < ShardChild <TShard, TRecord, TChild>> Inherited Members System.Object.Equals(System.Object, System.Object) System.Object.GetType() System.Object.ReferenceEquals(System.Object, System.Object) Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public struct ShardChild<TShard, TRecord, TChild> : IEquatable<ShardChild<TShard, TRecord, TChild>> where TShard : IComparable where TRecord : IComparable where TChild : IComparable Type Parameters Name Description TShard TRecord TChild Constructors | Improve this Doc View Source ShardChild(DataOrigin, TShard, TRecord, TChild) Declaration public ShardChild(DataOrigin origin, TShard shardId, TRecord recordId, TChild childRecordId) Parameters Type Name Description DataOrigin origin TShard shardId TRecord recordId TChild childRecordId | Improve this Doc View Source ShardChild(ShardKey<TShard, TRecord>, TChild) Declaration public ShardChild(ShardKey<TShard, TRecord> key, TChild childRecordId) Parameters Type Name Description ShardKey <TShard, TRecord> key TChild childRecordId | Improve this Doc View Source ShardChild(Char, TShard, TRecord, TChild) Declaration public ShardChild(char dataOrigin, TShard shardId, TRecord recordId, TChild childId) Parameters Type Name Description System.Char dataOrigin TShard shardId TRecord recordId TChild childId Properties | Improve this Doc View Source ChildId Declaration public TChild ChildId { get; } Property Value Type Description TChild | Improve this Doc View Source Empty Declaration public static ShardChild<TShard, TRecord, TChild> Empty { get; } Property Value Type Description ShardChild <TShard, TRecord, TChild> | Improve this Doc View Source IsEmpty Declaration public bool IsEmpty { get; } Property Value Type Description System.Boolean | Improve this Doc View Source Key Declaration public ShardKey<TShard, TRecord> Key { get; } Property Value Type Description ShardKey <TShard, TRecord> | Improve this Doc View Source Origin Declaration public DataOrigin Origin { get; } Property Value Type Description DataOrigin | Improve this Doc View Source RecordId Declaration public TRecord RecordId { get; } Property Value Type Description TRecord | Improve this Doc View Source ShardId Declaration public TShard ShardId { get; } Property Value Type Description TShard Methods | Improve this Doc View Source Equals(ShardChild<TShard, TRecord, TChild>) Declaration public bool Equals(ShardChild<TShard, TRecord, TChild> other) Parameters Type Name Description ShardChild <TShard, TRecord, TChild> other Returns Type Description System.Boolean | Improve this Doc View Source Equals(Object) Declaration public override bool Equals(object obj) Parameters Type Name Description System.Object obj Returns Type Description System.Boolean Overrides System.ValueType.Equals(System.Object) | Improve this Doc View Source FromExternalString(String) Declaration public static ShardChild<TShard, TRecord, TChild> FromExternalString(string value) Parameters Type Name Description System.String value Returns Type Description ShardChild <TShard, TRecord, TChild> | Improve this Doc View Source GetHashCode() Declaration public override int GetHashCode() Returns Type Description System.Int32 Overrides System.ValueType.GetHashCode() | Improve this Doc View Source ToExternalString() Serializes ShardChild data into a URL-safe string with a checksum, optionally including a concurrency stamp. Declaration public string ToExternalString() Returns Type Description System.String A URL-safe string that can be re-serialized into a shard child. | Improve this Doc View Source ToString() Declaration public override string ToString() Returns Type Description System.String Overrides System.ValueType.ToString() Operators | Improve this Doc View Source Equality(ShardChild<TShard, TRecord, TChild>, ShardChild<TShard, TRecord, TChild>) Declaration public static bool operator ==(ShardChild<TShard, TRecord, TChild> sc1, ShardChild<TShard, TRecord, TChild> sc2) Parameters Type Name Description ShardChild <TShard, TRecord, TChild> sc1 ShardChild <TShard, TRecord, TChild> sc2 Returns Type Description System.Boolean | Improve this Doc View Source Inequality(ShardChild<TShard, TRecord, TChild>, ShardChild<TShard, TRecord, TChild>) Declaration public static bool operator !=(ShardChild<TShard, TRecord, TChild> sc1, ShardChild<TShard, TRecord, TChild> sc2) Parameters Type Name Description ShardChild <TShard, TRecord, TChild> sc1 ShardChild <TShard, TRecord, TChild> sc2 Returns Type Description System.Boolean Implements System.IEquatable<T>"
  },
  "tutorials/Configuration/shardtype.html": {
    "href": "tutorials/Configuration/shardtype.html",
    "title": "The Shard Id Type | ArgentSea Docs",
    "keywords": "The Shard Id Type End each shard instance has a ShardId property, which identifies a specific subset (“shard”) of the data. This value is not simply a key for a shard instance; the ShardId is generally used in combination with the record key to uniquely identify a record. ArgentSea identifies records in the shard set with a sort-of “virtual” compound key, consisting of both the numeric shard identifier and the record key. Note that because records in a data shard may refer to foreign records in other shards, the “foreign shard” reference requires saving the shard identifier too. Caution The shardId value is managed by the client when it calls a shard instance. If two clients are (mis-)configured differently (i.e. with different databases having the same shard Id) reading on one client and writing on the other client could result in data corruption. Always ensure that the shard Id configuration is consistent across all clients! You might consider including the shard Id with each query and validating it on the database server. More details about the ShardId type is in the Sharding section. Note The initial version of ArgentSea used a generic type as the ShardId — allowing the application to use an integer, string, short, etc. to identify each shard. This flexibility created an unnecessarily complex object model and redundant and verbose client code, particularly since the generic type could not change within the application. Even then, he best choice for the ShardId type was clearly a short (Int32/SmallInt): it is a small enough for efficient storage, yet large enough to theoretically support 65,535 shards. The current version of ArgentSea assumes this type and is much easier to use as a result. Next: Resilience Strategies"
  },
  "index.html": {
    "href": "index.html",
    "title": "ArgentSea Documentation | ArgentSea Docs",
    "keywords": "ArgentSea Documentation Modern web applications need to be built for performance and scalability, as well as security, monitoring, and configuration. ArgentSea offers a framework that consistently represents best practices for all of these concerns. The goal of ArgentSea is to simplify the development process for delivering highly scalable and supportable applications. Massive Scalability The essential ingredients for building a service that can scale to any demand include highly efficient code, reducing server round-trips, and the scale-out of reads and writes. Highly scalable data typically means data “ sharding ” — the practice of spreading data across many database servers. Data sharding offers the most cost effective way to scale your data application as demand grows. To scale your application globally, data sharding offers the ability locate copies of your data across regional datacenters, so that data is located closer to your customers. ArgentSea uses explicit read and write connections to enable further scale-out. By directing read activity to a mirror or cloned data set, the data load can be spread among multiple servers. Examples include SQL Server Availability Groups , PostgreSQL Hot Standby , Amazon RDS Read Replicas , Azure SQL Geo-Replication , Amazon Aurora Low-Latency Read Replicas , etc. ArgentSea helps deliver highly optimized data access through data-to-object mapping without the overhead of reflection. The consistent use of stored procedures (SQL Server) or prepared statements (PostgreSQL) reduces both SQL compilation overhead and support/maintenance costs. Because ArgentSea can handle multiple results from the same query, the number of server round-trips can be reduced — a huge performance win. While the genesis of ArgentSea was to support the complex requirements of data sharding, it will likely be useful for high-performance data access even if you are not accessing sharded data. Especially with a cloud infrastructure, more efficient code requires fewer resources and this translates into ongoing cost savings. Mission Critical Supportability ArgentSea also addresses production concerns with built-in features like monitoring/logging, automatic retries after failures, controlling cascading failures (circuit breaking), security best-practices, and an elegant approach to managing connection configuration. The data framework will attempt to recover from transient errors by automatically retrying the data access; you have control over how long and how often. If repeated failures occur, the system will “circuit break”, so that data failures have less chance of bringing down the whole application. The robust logging implementation allows you to log to any provider, including Application Insights , CloudWatch , the file system, Windows event logs, and more. Database passwords can be secured using Key Vault , Secrets Manager , User Secrets , Docker secrets , or other secure storage. The configuration architecture simplifies the management of large numbers of data connections, reducing redundancy while making it easy to deploy a release though staging environments. Maintainability via Code Clarity Supportability is about more than managing the operational burden. It also includes simplicity in understanding application behavior, ease in extending it with new features and requirements, and a discoverable path to resolving bugs. When long-lived applications must be supported by teams that are not the original authors, this becomes especially critical. The ArgentSea Mapper helps reduce the burden of code maintenance by simplifying and reducing data access code. This makes the code easier to understand and therefore easier to enhance and maintain. Further, the framework helps consolidate and segregate the SQL data access statements so that they can be more easily managed and optimized. The logging functionality can also provide substantial insight to developers, including the dynamic code compilation behind the Mapper, misconfigurations, and data errors. Getting Started Explore the deep dives to understand the logic and services of ArgentSea. An ArgentSea implementation consists of the NuGet library packages , loading the configuration and services at startup, decorating the models classes with data attributes , and calling the various query methods . If you prefer to learn by getting your hands dirty, jump into the walkthroughs . You can find the most detailed information in the API section . Next: Explore ArgentSea’s functionality"
  },
  "tutorials/Querying/sequence.html": {
    "href": "tutorials/Querying/sequence.html",
    "title": "The Coding Sequence | ArgentSea Docs",
    "keywords": "The Coding Sequence ArgentSea was originally built to support application data sharding. Today, it offers valuable capabilities that recommend it even if you do not use data sharding in your application. A brief discussion of the issues raised with sharding will help explain the architecture behind of ArgentSea’s data access approach. Ultimately, the ArgentSea approach has a slightly different sequence, but it is no more difficult than any other ADO.NET query. Accommodating Sharding The best way to understand the query architecture of ArgentSea is to describe a typical ADO.NET query then describe how this must change to account for concurrent multi-threaded queries across a shard set. To keep both practices and tooling consistent, and because it really is not complicated, this same approach is used whether or not sharding is required. A typical ADO.NET data access method follows these steps: Start with a connection object, created from a connection string. Create a command object that is associated with the connection object. Next, the populate the command's Parameters property with the necessary input and output parameters. Open the connection and run the command. Create a Model object (or list) and use the DataReader (or output parameters) to map each column result to each of the Model’s properties. In a sharded environment, however, the same parameters must be executed on multiple connections — reversing the steps 1 to 3. Furthermore, a distinct command object must be executed and the results processed on a separate thread for each connection. The parameters cannot be shared (different threads would overwrite each other’s values) and the result handler must be thread-safe because it could be simultaneously executing on different connections. ArgentSea manages the challenges of multi-threaded access with a differently ordered sequence: Declare the parameters and arguments that will be passed to the stored procedure or SQL statement. Create a thread for each shard connection, then create the connection (and command ) object for each. Copy the parameter values to the parameter collection on each shard’s command object. Run the query on each shard’s thread. When results are obtained, call (thread-safe) code to create and populate a Model object. Merge the results and return them to the caller. Ultimately, using ArgentSea on multiple shards is no more difficult than writing simple ADO.NET database access code (and usually much easier), but the code new needs to be grouped and sequenced differently. The ArgentSea Query Paradigm Previously, you would usually use just one data access command object, which would host the ADO.NET parameters, and run the query, converting the results to a Model object. Now, because processing results is multi-threaded whereas setting up the query is not, you need to split that process into two procedures: The caller method sets the parameters and calls an ArgentSea query method. This executes on a single thread. The handler procedure converts the results to a Model object result. This can execute on many threads. This ArgentSea query paradigm applies even to non-sharded queries using the Databases collection. This provides some design consistency, and also enables the Mapper for both sharded and non-sharded data. Tip If you use ArgentSea’s optional Mapping functionality, the multi-threaded results handling procedure is already provided by the Mapper. You do not have to write a handler. Next: Setting Parameters"
  },
  "tutorials/Configuration/hierarchy.html": {
    "href": "tutorials/Configuration/hierarchy.html",
    "title": "The Hereditary Configuration Hierarchy | ArgentSea Docs",
    "keywords": "The Hereditary Configuration Hierarchy ArgentSea essentially dispenses with traditional connection strings. Instead, it uses the new .NET configuration architecture to manage each attribute as a discrete property. Each property can be managed globally, or at the shardSet, database, or connection level. Lower-level settings inherit values from their parent, which they can also overwrite if their own values are set differently. The Hereditary Configuration Hierarchy allows users to configure their data connection information at multiple levels. Child nodes “inherit” any settings of their parent. By dramatically reducing configuration redundancy, it makes handling many connections much more manageable. For example, if your network infrastructure supports jumbo frames, you can configure the network packet size once , in the global configuration section, and every ArgentSea connection will default to this value. The Global Section The root of the configuration hierarchy is the “global settings” section. All properties set here are applied to every data connection — unless the value is overwritten by lower-level properties (i.e. database, shard set, shard, etc.). SQL Server PostgreSQL The SQL Server global section is SqlGlobalSettings . Any attributes specified in this section are applied to all SQL Server connections. For example, to globally change both the connection timeout property and packet size: { \"SqlGlobalSettings\": { \"ConnectTimeout\": 3, \"PacketSize\": 8196 } } The PostgreSQL global section is PgGlobalSettings . Any attributes specified in this section are applied to all PostgreSQL connections. For example, to globally change both the connection timeout property and packet size: { \"PgGlobalSettings\": { \"Timeout\": 3, \"SocketReceiveBufferSize\": 8192, \"SocketSendBufferSize\": 8192 } } Note that these examples include only the attributes that we want to change. The complete attribute list is described below. (Non-Sharded) Database Connections The database configuration architecture allow any number of database connections. Each connection is identified by a key, which you also use to request the connection in your code. The key in your configuration must exactly match the keys used in your code (i.e casing, accents, and kana must match — and spelling too). Database connections have a three-level hierarchy: global properties, database properties, and properties for distinct read and write endpoints. This illustration shows how various “parent” configuration properties are applied to the child values. Ultimately, these values are combined to build a Read or Write connection. The upshot is that if you have a simple database connection that handles both reads and writes, you can define this once at the database level; both Read and Write connections will “inherit” this value. SQL Server PostgreSQL The JSON section for SQL database connections is SqlDbConnections . This is an array of connections. Each connection has a required DatabaseKey property, and whatever connection properties are needed for the connection. { \"SqlDbConnections\": [ { \"DatabaseKey\": \"MainDb\", \"DataSource\": \"DbServer1\", \"InitialCatalog\": \"MainDb\", \"WindowsAuth\": true }, { \"DatabaseKey\": \"OtherDb\", \"DataSource\": \"DbServer1\", \"InitialCatalog\": \"OtherDb\", \"WindowsAuth\": true, \"WriteConnection\": { \"DataSource\": \"DbServer2\" } }, { \"DatabaseKey\": \"ThirdDb\", \"ReadConnection\": { \"DataSource\": \"DbServer3\", \"InitialCatalog\": \"Db1\", \"UserName\": \"apiUser\", \"Password\": \"pwd1234\" }, \"WriteConnection\": { \"DataSource\": \"DbServer4\", \"InitialCatalog\": \"Db2\", \"UserName\": \"webUser\", \"Password\": \"pwd5678\" } } ] } The JSON section for PostgreSQL database connections is PgDbConnections . This is an array of connections. Each connection has a required DatabaseKey property, and whatever connection properties are needed for the connection. The application obtains a connection by this DatabaseKey and the characters must be an exact match. \"PgDbConnections\": [ { \"DatabaseKey\": \"MainDb\", \"Host\": \"10.10.25.1\", \"Database\": \"MainDb\", \"WindowsAuth\": true }, { \"DatabaseKey\": \"OtherDb\", \"Host\": \"10.10.25.2\", \"Database\": \"OtherDb\", \"WindowsAuth\": true, \"WriteConnection\": { \"Host\": \"10.10.25.2\" } }, { \"DatabaseKey\": \"ThirdDb\", \"ReadConnection\": { \"Host\": \"10.10.25.4\", \"Database\": \"MainDb\", \"UserName\": \"apiUser\", \"Password\": \"pwd1234\" }, \"WriteConnection\": { \"Host\": \"10.10.20.25\", \"Database\": \"MainDb\", \"UserName\": \"webUser\", \"Password\": \"pwd5678\" } } ] } Each connection has two optional child sections, ReadConnection and WriteConnection . These can be set explicitly if you want different values between read and write connections; otherwise, both read and write connections these will inherit from the parent properties. In the example above, the first connection has the same values for read and write connections (both Read and Write connections inherit the same values from the parent). The second connection will access a different server for read connections than write connections. The third connection explicitly defines connection information for both the Read and Write connections. As mentioned before, any connection property from the complete property list (as listed earlier), can be included in the database definition, read connection, or write connection. Shard Set Connections ArgentSea shard sets have up to five inheritance levels: global properties, shard set properties, shard set read/write properties, shard properties, and distinct read and write endpoint properties. The corresponding illustration again shows how various “parent” configuration properties are applied to the child values. As with non-sharded databases, these values are combined to build a Read or Write connection. When using a scale-out read strategy, all or most of your read connections might have consistent values (a login, for example), which could likely be different than the consistent values used for all of your write connections. A straightforward parent-child inheritance would require you to redundantly specify the same values for every shard’s read or write connection. To better manage this, the ShardSet has an exception to the parent-child hierarchy: a Read and Write configuration section. Values set in the ShardSet Read section will be used by only the read connections in the shards within the set. Likewise, write connections in the shard set inherit from the write parameters. SQL Server PostgreSQL The root JSON section for SQL shard connections is SqlShardSets . This is an array of shard sets, each of which has an array of shards. Presumably, most applications will not require multiple shard sets, but the capability exists if required. Each shard set has a required ShardSetName property. This is how the shard set retrieved from within the application, so the characters must exactly match. In addition, a shard set can include a DefaultShardId value, which may be used to determine which shard should be used when this client creates new records. { \"SqlShardSets\": [ { \"ShardSetName\": \"Primary\", \"DefaultShardId\": 1, \"UserName\": \"webUser\", \"Password\": \"pwd1234\", \"Read\": { \"ApplicationIntent\": \"ReadOnly\", \"UserName\": \"webReader\" }, \"Shards\": [ { \"ShardId\": 0, \"DataSource\": \"DbServer1\", \"FailoverPartner\": \"Mirror1\", \"InitialCatalog\": \"ShardDb1\", \"ReadConnection\": { \"DataSource\": \"Mirror1\", } }, { \"ShardId\": 1, \"DataSource\": \"DbServer2\", \"FailoverPartner\": \"Mirror2\", \"InitialCatalog\": \"ShardDb2\", \"ReadConnection\": { \"DataSource\": \"Mirror2\", } } ] } ] } In this example, there is one shard set with two shards as two databases on the same server. The read connections are directed to a mirror by overwriting the inherited DataSource value with the name of the mirror. Of course, in reality the password should be moved to a different, more secure configuration provider. The root JSON section for SQL shard connections is PgShardSets . This is an array of shard sets, each of which has an array of shards. Presumably, most applications will not require multiple shard sets, but the capability exists if required. Each shard set has two required properties: The ShardSetName property is how the shard set retrieved from within the application, so the characters must exactly match. The DefaultShardId value can be used to determine which shard should be used when this client creates new records. { \"PgShardSets\": [ { \"ShardSetName\": \"Primary\", \"DefaultShardId\": 1, \"Host\": \"DbServer1\", \"UserName\": \"webUser\", \"Password\": \"pwd1234\", \"Read\": { \"UserName\": \"webReader\" }, \"Shards\": [ { \"ShardId\": 0, \"Database\": \"ShardDb1\", \"ReadConnection\": { \"DataSource\": \"HotStandby1\", } }, { \"ShardId\": 1, \"Database\": \"ShardDb2\", \"ReadConnection\": { \"DataSource\": \"HotStandby1\", } } ] } ] } In this example, there is one shard set with two shards as two databases on the same server. The read connections are directed to a hot standby replication instance by overwriting the inherited DataSource value with the name of the mirror. Of course, in reality the password should be moved to a different, more secure configuration provider. Again, any connection property from the complete property list — as enumerated in the next section — can be included in the shard set definition (to be used by all connections in the shard set), or shard instance (to be used by both Read and Write connections), or to specifically configure the Read and/or Write connection. In a typical data sharding implementation, all shard read or write connections are likely to use same login information. Each server may even use the same database name. The Hereditary Configuration Hierarchy makes this easy to manage because the login information and database can be defined once for the shard set, or shard set read/write connection type, then used by every connection. Connection Attributes The complete set of available properties is: SQL Server PostgreSQL { \"ApplicationIntent\": \"ReadWrite\", \"ApplicationName\": \"MyWebApp\", \"CircuitBreakerFailureCount\": 20, \"CircuitBreakerTestInterval\": 5000, \"ConnectTimeout\": 2, \"CurrentLanguage\": \"english\", \"DataSource\": \"localhost\", \"Encrypt\": false, \"FailoverPartner\": \"MyMirror\", \"InitialCatalog\": \"MyDb\", \"LoadBalanceTimeout\": 0, \"MaxPoolSize\": 100, \"MinPoolSize\": 0, \"MultipleActiveResultSets\": false, \"MultiSubnetFailover\": true, \"PacketSize\": 4096, \"Password\": \"pwd1234\", \"PersistSecurityInfo\": false, \"Pooling\": true, \"Replication\": true, \"RetryCount\": 6, \"RetryInterval\": 256, \"RetryLengthening\": \"Fibonacci\", \"TransactionBinding\": \"\", \"TrustServerCertificate\": true, \"TypeSystemVersion\": \"Latest\", \"UserInstance\": \"\", \"UserName\": \"webUser\", \"WindowsAuth\": false, \"WorkstationID\": \"MyPC\" } { \"ApplicationName\": \"MyWebApp\", \"AutoPrepareMinUsages\": 5, \"CheckCertificateRevocation\": false, \"CircuitBreakerFailureCount\": 20, \"CircuitBreakerTestInterval\": 25, \"ClientEncoding\": \"UTF8\", \"CommandTimeout\": 5, \"ConnectionIdleLifetime\": 300, \"ConnectionPruningInterval\": 10, \"ConvertInfinityDateTime\": false, \"Database\": \"MyDb\", \"Encoding\": \"UTF8\", \"Enlist\": true, \"Host\": \"10.10.25.1\", \"IncludeRealm\": false, \"InternalCommandTimeout\": -1, \"KeepAlive\": null, \"KerberosServiceName\": \"postgres\", \"LoadTableComposites\": false, \"MaxAutoPrepare\": 0, \"MaxPoolSize\": 100, \"MinPoolSize\": 1, \"NoResetOnClose\": false, \"Password\": \"pwd1234\", \"PersistSecurityInfo\": false, \"Pooling\": true, \"Port\": 5432, \"ReadBufferSize\": 8192, \"RetryCount\": 15, \"RetryInterval\": 10, \"RetryLengthening\": \"Fibonacci\", \"SearchPath\": null, \"ServerCompatibilityMode\": \"none\", \"SocketReceiveBufferSize\": 8192, \"SocketSendBufferSize\": 8192, \"SslMode\": \"Require\", \"TcpKeepAlive\": true, \"Timeout\": 5, \"Timezone\": \"America/Los_Angeles\", \"TrustServerCertificate\": true, \"UsePerfCounters\": false, \"UserName\": \"webUser\", \"UseSslStream\": true, \"WindowsAuth\": false, \"WriteBufferSize\": 8192 } Caution Displayed are all of the available properties. It is neither necessary nor wise to set all of them. All that is minimally required for most connections is login information, a server or host name, and a database name. Each level in the Hereditary Configuration Hierarchy can use any of the properties on this list. Next: The Shard Id Data Type"
  },
  "tutorials/Mapping/logging.html": {
    "href": "tutorials/Mapping/logging.html",
    "title": "Logging | ArgentSea Docs",
    "keywords": "Logging You have surely noticed that every Mapper command requires a logger instance — an object that implements the ILogger interface. A supportable application requires logging, so the parameter is not optional. The .NET Core environment provides objects that log to the console, debug window, Windows event logs, file system, Application Insights , CloudWatch , and much more. ArgentSea can consume any of these logging providers and provide diagnostic and runtime data to their respective targets. In production, you will generally want to use log level Information . In development you may find Debug or even Trace very helpful. Caution Be sure to manage the logging level in your configuration. This determines the amount of logging and this can have a substantial impact upon performance. Logging Levels The logging levels determine the types of events that are logged. These are described below: Critical Logs when the circuit breaker is triggered on a connection or command. This may generate many downstream errors until the functionality is restored. Error In most cases, an error condition will throw to the caller so they become the caller’s responsibility to handle or log. Because data access may happen on multiple threads, however, a simple throw may lose context. If the data reader passed to the Mapper is closed or null, this is logged as an exception along with the connection description. Warning ArgentSea creates a warning log event when starting an automatic retry on a connection or command. Information When the circuit breaker is triggered, ArgentSea creates a log record each time a test transaction is attempted and again when functionality is restored. Debug The logged events in the Debug level are intended to help diagnose internal processes that may not be returning the expected results. The first type of event is when a DbNull value is presented to an object that then becomes null or empty, as can happen with ShardKeys or any object with a Required argument set to true. When this happens unexpectedly, it can be difficult to determine which database value caused the problem (because now no properties exist to determine the culprit). This logging event identifies which DbNull caused the result to be null or Empty. The second type of event provides full visibility into the generated code used to build the Mapper’s activity. The Expression Tree is walked and the pseudo-code saved to the log before it is compiled. This can be extremely useful in understanding the complexities of the Mapping behavior. The log record will be rather long and the extraction may not be efficient, but it also runs only during the first data access. This log level also reports when a parameter attribute was defined but the parameter was not found among the output parameters. This might be by design or it might be a programming oversight. Finally, the Mapper logs when it did not find an cached delegate so an Expression Tree is being built and compiled. This is normal at startup because the cache will be empty; if these event occur afterward, there is likely a problem. Trace The Mapper creates a trace log record as it iterates over properties. This can provide insight into the current context when other error conditions occur. Also, the logger will report the execution time for commands sent to a database connection or shard sets. Next: Querying"
  },
  "tutorials/Configuration/loading.html": {
    "href": "tutorials/Configuration/loading.html",
    "title": "Loading the Configuration | ArgentSea Docs",
    "keywords": "Loading the Configuration ArgentSea fully leverages the configuration architecture of .NET Core. In brief, ArgentSea requires one or more configuration files and offers a simple extension method to load the entire framework at start up. About .NET Configuration If the .NET Core configuration architecture is new to you, it essentially consists of two parts: A configuration Dictionary , which can be loaded from multiple sources — one of which is typically a file called appsettings.json An “Options” architecture, which casts the configuration entries into a strongly-typed configuration objects. One of the key improvements of the configuration architecture in .NET standard is the dictionary architecture, which allows entries to be loaded and combined from multiple sources. So, for example, you might load the account names from an appsettings.json configuration file, the passwords from a secrets.json file (or Key Vault or Secrets Manager ), and the server names from environment variables. Properly managed, this can make deployments both easier and more secure. The previous examples all used JSON for configuration. This is not a requirement. In non-JSON configuration contexts, like environment variables, you can specify these values as key-value pairs. The key concatenates the hierarchy separated by “:”. Arrays and lists should include an index. The same configuration information listed above can be stored and loaded as key-value pairs. An example of the same shard set configuration in non-JSON format would be: SQL Server PostgreSQL Key Value SqlShardSets:0:ShardSetName Primary SqlShardSets:0:DataSource DbServer1 SqlShardSets:0:FailoverPartner Mirror1 SqlShardSets:0:UserName webUser SqlShardSets:0:Password pwd1234 SqlShardSets:0:Shards:0:ShardId 0 SqlShardSets:0:Shards:0:InitialCatalog ShardDb1 SqlShardSets:0:Shards:0:ReadConnection:ApplicationIntent ReadOnly SqlShardSets:0:Shards:0:ReadConnection:DataSource Mirror1 SqlShardSets:0:Shards:1:ShardId 1 SqlShardSets:0:Shards:1:InitialCatalog ShardDb2 SqlShardSets:0:Shards:1:ReadConnection:ApplicationIntent ReadOnly SqlShardSets:0:Shards:1:ReadConnection:DataSource Mirror1 Key Value PgShardSets:0:ShardSetName Primary PgShardSets:0:DataSource DbServer1 PgShardSets:0:UserName webUser PgShardSets:0:Password pwd1234 PgShardSets:0:Shards:0:ShardId 0 PgShardSets:0:Shards:0:InitialCatalog ShardDb1 PgShardSets:0:Shards:0:ReadConnection:DataSource HotStandby1 PgShardSets:0:Shards:1:ShardId 1 PgShardSets:0:Shards:1:InitialCatalog ShardDb2 PgShardSets:0:Shards:1:ReadConnection:DataSource HotStandby1 Because .NET Core’s configuration architecture allows values to be aggregated from multiple data stores, we can create configuration entries where they can be most conveniently managed. Gone are the days of needing to transform configuration files upon deployment (unless you really like that type of thing). Typically, there are three types of configuration entries: Secure values, like passwords or keys, which should not be readily accessible. Environment-specific values, like server names, which change as releases are promoted through various environments. Application values, which specify how the application should consistently behave. This capability is critical for managing configuration outside of the application. Using key-value pairs allows configuration values to be hosted in environment variables and secure stores. Securing Passwords In a development environment, you should consider using the UserSecrets functionality, which prevents this information from being checked into your source code repository. UserSecrets uses a JSON file, so the password entries can be simply removed from the appsettings.json file and stored in the secrets.json file. Note that the object counts must be consistent between your appsettings.json file and the secrets.json file. SQL Server PostgreSQL User Secrets { \"SqlDbConnections\": [ { }, { }, { \"ReadConnection\": { \"Password\": \"pwd1234\" }, \"WriteConnection\": { \"Password\": \"pwd5678\" } } ] } User Secrets \"PgDbConnections\": [ { }, { }, { \"ReadConnection\": { \"Password\": \"pwd1234\" }, \"WriteConnection\": { \"Password\": \"pwd5678\" } } ] } In other environments, you might consider using AWS Secrets Manager , Azure Key Vault , Docker secrets , a secure file share, or something similar. Most of these secrets stores store key value pairs. The .NET configuration manager resolves the hierarchical JSON files with a semi-colon, “:”, separator between the property hierarchy. Array elements are referenced with an index value. Tip Systems that don’t support semi-colon separators in their keys (AWS Secrets Manager, for example) can use double underscores (“__”) instead. Consequently, the previous JSON values could be saved as corresponding key-value pairs as: SQL Server PostgreSQL Key Value SqlDbConnections:2:ReadConnection:Password pwd1234 SqlDbConnections:2:WriteConnection:Password pwd5678 Key Value PgDbConnections:2:ReadConnection:Password pwd1234 PgDbConnections:2:WriteConnection:Password pwd5678 In reality, most implementations would have a single secure password used for every shard connection, in which case the key in your secrets store is simply: SQL Server PostgreSQL Key Value SqlShardSets:0:Password pwd1234 Key Value PgShardSets:0:Password pwd1234 Environment-specific Configuration Managing configuration through multiple staging and release environments works the same way. You can store environment-specific settings — like server names or database names — in server environment variables . These are also key-value pairs, so the .NET Core configuration hierarchy would be rendered to keys in the same way as described in the previous section. The database configuration JSON presented previously would be saved in environment variables as: Key Value SqlDbConnections:0:DataSource DbServer1 SqlDbConnections:0:InitialCatalog MainDb SqlDbConnections:1:DataSource DbServer1 SqlDbConnections:1:InitialCatalog OtherDb SqlDbConnections:1:WriteConnection:DataSource DbServer2 SqlDbConnections:1:ReadConnection:DataSource DbServer3 SqlDbConnections:1:ReadConnection:InitialCatalog Db1 SqlDbConnections:1:WriteConnection:DataSource DbServer4 SqlDbConnections:1:WriteConnection:InitialCatalog Db2 Note The order of configuration loading matters. Your Startup class should load appsettings.json first. When the environment variables are subsequently loaded, any existing values in appsettings.json will be overwritten. ArgentSea uses the configuration dictionary built into .NET Core, so you can use any compatible configuration provider — including files, command line arguments, databases, and more . There are no restrictions on which configuration entries belong to which providers (data sources). You can store passwords in environment variables or even command arguments, if you want to. Pick the right platform to management your data effectively, ArgentSea can use it as long as the values are consolidated correctly into the configuration dictionary. Configuration Options The next phase in .NET Core’s configuration processing is the Options rendering. This converts the aggregated dictionary entries into strongly typed configuration objects, called Options. ArgentSea uses these typed Options objects to build its ShardSets and Databases services. Unfortunately, a misconfigured property or entry can cause the Options class to be null when a value was expected. This can be difficult to debug, as there are often no error messages, just a null result. You can debug the Options classes during startup to see which values are unexpectedly null. Experiment with removing configuration values until the Options classes render as expected. The JSON object hierarchy and property types should exactly match those of the Options objects, so if you have any doubts, explore the Options classes using C# or other strongly typed language. Loading the Configuration ArgentSea uses .NET Core’s built-in Options configuration and dependency injection architecture. The complexity of turning a JSON configuration file into a connection object is as simple as calling an extension method in the ConfigureServices method of your Startup class. SQL Server PostgreSQL public void ConfigureServices(IServiceCollection services) { ... // add your injectable logging provider services.AddLogging(); // add the ArgentSea SQL database connections services.AddSqlServices(Configuration); // now add your custom data classes, which use the data components services.AddSingleton<MyDataStore>(); ... services.AddMvc(); ... } public void ConfigureServices(IServiceCollection services) { ... // add your injectable logging provider services.AddLogging(); // add the ArgentSea SQL database connections services.AddPgServices(Configuration); // now add your custom data classes, which use the data components services.AddSingleton<MyDataStore>(); ... services.AddMvc(); ... } public IConfiguration Configuration { get; } This code references a Configuration property. It is common practice to obtain the configuration object from the constructor of the Startup class, then use this to set the Configuration property. Next: Simplifying Your Data Access Code"
  },
  "LICENSE.html": {
    "href": "LICENSE.html",
    "title": "ArgentSea License | ArgentSea Docs",
    "keywords": "ArgentSea License The MIT License (MIT) Copyright © John Hicks and Contributors. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE."
  },
  "tutorials/Querying/querying.html": {
    "href": "tutorials/Querying/querying.html",
    "title": "Queries | ArgentSea Docs",
    "keywords": "Queries The twin goals of performance and supportability help drive ArgentSea’s approach to SQL queries. One of the areas in which ArgentSea’s design is most distinctive is its attempt to avoid tight coupling between the application and the database. Tight Coupling Tight coupling describes when a system’s integration with a second system depends on the internal implementation of the other system. Often the result of haphazard design, this interdependency makes it nearly impossible to change systems or even improve the implementation due to the difficulty of fully accounting for potential inter-system impact. When your database client code depends upon how tables and columns are implemented, the application layer and database layer have a type of tight coupling. ArgentSea tries to minimize this by ensuring that SQL is segregated and explicit. Loose Coupling Loosely coupled systems have well-defined interfaces. Because of this, you can change the implementation as long as you maintain the interface “contract”. These systems are more robust, testable, and manageable. Because of the well-defined interface between services, systems can be optimized without concern about inadvertent downstream impacts. ArgentSea’s use of static, parameterized queries are intended to make the data “contract” as explicit as possible, and managed independently of application code. The goal is to enable the changing of database structures — you can rewrite queries, partition tables, add hints, materialize views, and more — and as long as the same parameters are provided and the same results returned, the application should not break. To keep database interactions as manageable as possible, ArgentSea seeks to keep SQL static , consolidated , and segregated . Static ArgentSea discourages dynamic SQL queries. Dynamic SQL may have slightly poorer performance due to the overhead of a SQL compiler, and the potential for SQL injection may make some dynamic SQL less secure. Primarily, though, it can be difficult to parse, understand, and — especially — improve SQL created from a C# object model. This is why ArgentSea is intended to work with static SQL and parameters . Consolidated Large applications routinely have “orphaned” procedures, tables, views, etc. As functionality changes, once necessary objects are no longer required. Application developers often have no easy way to confidently drop these objects, yet there is a continuing maintenance cost to preserving them. By consolidating SQL queries, ArgentSea helps provide visibility to query usage. Especially helpful is Visual Studio’s reference count: if the count is zero, the query is no longer in use. Segregated ArgentSea avoids compiling SQL implementation code into application binaries. Well-written application code, running in the same environment, will likely continue to run well indefinitely; however, a query that initially worked efficiently may need to be rewritten as the data set grows or cardinality changes. By separating SQL and C# files, queries can be adapted as data changes over the lifetime of an application. This also encourages SQL for data-domain work, and .NET for application work. People expert at optimizing SQL do not always welcome dealing with C# projects and concomitant build processes. Next: Creating SQL Queries"
  },
  "api/ArgentSea.InvalidShardArgumentsException.html": {
    "href": "api/ArgentSea.InvalidShardArgumentsException.html",
    "title": "Class InvalidShardArgumentsException | ArgentSea Docs",
    "keywords": "Class InvalidShardArgumentsException This error is raised upon an attempt to create an Empty ShardKey or ShardChild, but the IDs are not zero. Essentially, any shard object with a DataOrigin of '0' (Empty) must also have zeroed IDs (be equal to ShardKey.Empty or ShardChild.Empty). Inheritance System.Object System.Exception InvalidShardArgumentsException Implements System.Runtime.Serialization.ISerializable Inherited Members System.Exception.GetBaseException() System.Exception.GetObjectData(System.Runtime.Serialization.SerializationInfo, System.Runtime.Serialization.StreamingContext) System.Exception.GetType() System.Exception.ToString() System.Exception.Data System.Exception.HelpLink System.Exception.HResult System.Exception.InnerException System.Exception.Message System.Exception.Source System.Exception.StackTrace System.Exception.TargetSite System.Exception.SerializeObjectState System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public sealed class InvalidShardArgumentsException : Exception, ISerializable Constructors | Improve this Doc View Source InvalidShardArgumentsException() Initializes a new instance of the InvalidShardArgumentsException class with no error message. Declaration public InvalidShardArgumentsException() | Improve this Doc View Source InvalidShardArgumentsException(String) Initializes a new instance of the InvalidShardArgumentsException class with a specified error message. Declaration public InvalidShardArgumentsException(string message) Parameters Type Name Description System.String message The message that describes the error. | Improve this Doc View Source InvalidShardArgumentsException(String, Exception) Initializes a new instance of the InvalidShardArgumentsException class. Declaration public InvalidShardArgumentsException(string message, Exception innerException) Parameters Type Name Description System.String message The message that describes the error. System.Exception innerException The exception that is the cause of the current exception. Implements System.Runtime.Serialization.ISerializable"
  },
  "api/ArgentSea.IConnectionConfiguration.html": {
    "href": "api/ArgentSea.IConnectionConfiguration.html",
    "title": "Interface IConnectionConfiguration | ArgentSea Docs",
    "keywords": "Interface IConnectionConfiguration This interface is used by provider specific implementations. It is unlikely that you would reference this in consumer code. The interface defines the minimum capability of a connection definition. Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public interface IConnectionConfiguration Properties | Improve this Doc View Source ConnectionDescription Declaration string ConnectionDescription { get; } Property Value Type Description System.String | Improve this Doc View Source ResilienceKey Declaration string ResilienceKey { get; } Property Value Type Description System.String Methods | Improve this Doc View Source GetConnectionString() Declaration string GetConnectionString() Returns Type Description System.String | Improve this Doc View Source SetConfigurationOptions(DataSecurityOptions, DataResilienceOptions) Declaration void SetConfigurationOptions(DataSecurityOptions securityOptions, DataResilienceOptions resilienceStrategiesOptions) Parameters Type Name Description DataSecurityOptions securityOptions DataResilienceOptions resilienceStrategiesOptions"
  },
  "tutorials/Querying/sql.html": {
    "href": "tutorials/Querying/sql.html",
    "title": "Creating SQL Queries | ArgentSea Docs",
    "keywords": "Creating SQL Queries Every ArgentSea data access method takes a Query argument. ArgentSea offers two implementations: QueryProcedure - which names a stored procedure (or function). This also sets the DbCommandType to StoredProcedure . Of course, the actual SQL implementation is hosted on the server, giving DBAs or SQL developers the ability to revise the implementation, if needed. This is the recommended approach for SQL Server. QueryStatement - which presents a parameterized SQL statement which is loaded from a file. This sets the DbCommandType to “Text”. This is the recommended approach for PostgreSQL and situations with limited ownership of the database. ArgentSea recommends creating a single, static class which contains all defined procedures or SQL statements as static properties. As large applications evolve, it can become difficult to determine procedures or commands are actually used by the application. Noting Visual Studio’s reference count for each property may help prune dead code. Here is an example: public static class Queries { // Define query for a SQL Stored Procedure or PostgreSQL function. public static QueryProcedure GetSubscriber => new QueryProcedure(\"ws.ListSubscribers\", new[] { \"subscriberid\" }); // Define query in a SQL file named “GetSubscriber”. Lazy load and cache. private static readonly Lazy<QueryStatement> _getSubscriber = QueryStatement.Create(\"GetSubscriber\", new[] { \"subid\" }); public static QueryStatement GetSubscriber => _getSubscriber.Value; // add a new static properties for each additional query... } Once this is done, it is easy to reference the statement batch or procedure like this: return await db.Read.MapReaderAsync<Subscriber>(Queries.GetSubscriber, parameters, cancellation); QueryProcedures SQL Server PostgreSQL The recommended way to query SQL Server is via stored procedures. This offers performance benefits, the advantage of consolidating SQL in a single repository (SQL Server itself), and the ability to tinker with SQL without changing application code. The defined inputs and output of the stored procedure becomes the defined “interface” to the underlying data. A QueryProcedure class requires a stored procedure name in its constructor. Optionally, you can add parameter names. The advantage of providing parameters names is described below, along with a SQL script that can generate this metadata automatically. If you are referencing a database where creating stored procedures would be problematic (say, you don’t control the target database), then the Statement class allows SQL strings to be used instead. Caution PostgreSQL clients are generally advised to use the QueryStatement class, rather than QueryProcedure . You can use the QueryProcedure type to call a PostgreSQL function. The longstanding behavior of the Npgsql provider is to implicitly change the query to “SELECT * FROM <functionName>”. Consequently, this class can only invoke functions , not stored procedures. To invoke stored procedures, use “CALL <sprocName>” in the QueryStatement class instead. A QueryProcedure class requires the function name in its constructor. Optionally, you can add parameter names. The advantage of providing parameters names is described below. QueryStatements A QueryStatement class loads a text file containing SQL commands. The file contains the batch of SQL commands to execute. This helps avoid immutable SQL that is compiled within the application. The default steps to implement this are: 1. Create a project folder called “SQL” This is the subdirectory folder from which ArgentSea will load the SQL batch files. The default “SQL” folder name can be changed by setting the static QueryStatement.Folder` property. This should be done during startup. public void ConfigureServices(IServiceCollection services) { QueryStatement.Folder = Configuration[\"sqlFolder\"]; QueryStatement.Extension = \"psql\"; ... } Alternatively, the QueryStatement.Create() factory method overloads allow you specify a folder and extension or absolute path and filename. 2. In the SQL folder, add a new file for each statement batch The file name should be the same name as the property in your Queries class. SQL Server PostgreSQL The default extension for each file is “.sql”. This will be appended to the name you specify. In other words, by default ArgentSea uses “<AppFolder>\\SQL&lt;name>.sql” to locate SQL files. As with the default folder, you can change the default extension by setting the static QueryStatement.Extension property, or by using one of the Create overloads. When PostgreSQL services are loaded, via the AddPgServices call in the ConfigureServices method, the default extension for SQL files is set to “psql”. This will be appended to the name you specify. In other words, by default ArgentSea uses “<AppFolder>\\SQL&lt;name>.psql” to locate SQL files. As with the default folder, you can change the default extension by setting the static QueryStatement.Extension property, or by using one of the Create overloads. Be sure to set this value, after the AddPgServices call, but before a query is invoked. As with the default folder, you can change the default extension by setting the static QueryStatement.Extension property, or by using one of the Create overloads. 3. Ensure the SQL files are deployed In your IDE (i.e. Visual Studio), access the file’s Properties pane, then: Ensure the Build Action attribute is “None” Set the Copy to Output Directory attribute to “Copy if newer” for each SQL file. This will ensure that the files are copied to the output/publish directory. Warning This step is critical and often overlook on new query files. If you get an error that the query file was not found, this is probably the reason. 4. Add a corresponding property to the Queries static class The QueryStatement class does not have a default constructor; use the Create factory method instead. The Create factory method returns a Lazy<QueryStatement> . This allows the SQL file to be loaded only when first requested, and then cached for all subsequent requests. Each static method takes only two lines: private static readonly Lazy<QueryStatement> _getSubscriber = QueryStatement.Create(\"ListSubscribers\"); public static QueryStatement GetSubscriber => _getSubscriber.Value; The create method overloads allow you to explicitly set a folder and extension, or an absolute path and filename. private static readonly Lazy<QueryStatement> _getSubscriber = QueryStatement.Create(\"ListSubscribers\", null, \"SqlQueries\", \"qry\"); public static QueryStatement GetSubscriber => _getSubscriber.Value; Parameter Names Both the QueryProcedure constructor and the QueryStatement factory method take an optional string array of parameter names. If not provided, the Mapper will set/write/read all the parameters defined on the Model class; otherwise, only those matching the listed parameter names will be set. For example, INSERT queries would be unlikely to expect a “LastModified” parameter, but UPDATE queries often do. Unless the appropriate parameters are listed with the Query definition, the ArgentSea Mapper will create parameters from all properties with a corresponding attribute. Extra or missing parameters will generate a query error. Another scenario where this is helpful is the the “ShardId” parameter. Because this can be implicitly handled by ArgentSea Mapper, there can be ambiguity and inconsistency as to whether or not a shard id parameter should be created. The parameter list helps resolve this. SQL Server PostgreSQL SQL parameter names are always implicitly normalized to include a “@” prefix, so parameters names should match even if the Model’s property attribute does not include the “@” sign. Casing does matter though. This SQL statement will generate the Queries class from the existing stored procedures, you can paste this code into SQL Management Studio. PRINT N'public static class Queries {' DECLARE @Parameters nvarchar(max), @ObjectId int, @SchemaName sysname, @SprocName sysname, @ParameterName sysname; DECLARE curProcedures CURSOR FOR SELECT procedures.object_id, schemas.name, procedures.name FROM sys.procedures INNER JOIN sys.schemas ON schemas.schema_id = procedures.schema_id ORDER BY schemas.name, procedures.name OPEN curProcedures; FETCH NEXT FROM curProcedures INTO @ObjectId, @SchemaName, @SprocName; WHILE @@FETCH_STATUS = 0 BEGIN; SET @Parameters = N''; DECLARE curParameters CURSOR FOR SELECT parameters.name FROM sys.parameters WHERE object_id = @ObjectId ORDER BY parameter_id; OPEN curParameters; FETCH NEXT FROM curParameters INTO @ParameterName; WHILE @@FETCH_STATUS = 0 BEGIN; IF @Parameters = N'' BEGIN; SET @Parameters = N'\"' + @ParameterName + N'\"' END; ELSE BEGIN; SET @Parameters = @Parameters + N', \"' + @ParameterName + N'\"' END; --PRINT N' ' + @ParameterName FETCH NEXT FROM curParameters INTO @ParameterName; END; CLOSE curParameters; DEALLOCATE curParameters; IF @Parameters = N'' BEGIN; PRINT N' public static QueryProcedure ' + @SprocName + N' => new QueryProcedure(\"' + @SchemaName + N'.' + @SprocName + N'\", new string[] { });' END; ELSE BEGIN; PRINT N' public static QueryProcedure ' + @SprocName + N' => new QueryProcedure(\"' + @SchemaName + N'.' + @SprocName + N'\", new[] { ' + @Parameters + ' });' END; FETCH NEXT FROM curProcedures INTO @ObjectId, @SchemaName, @SprocName; END; CLOSE curProcedures; DEALLOCATE curProcedures; PRINT N'}' Parameter names much match, including casing, kana type, etc. Parameter names should generally be consistently lowercase. Future versions of ArgentSea may automatically convert data object names to lowercase. Next: Coding Queries with ArgentSea"
  },
  "tutorials/Mapping/attributes.html": {
    "href": "tutorials/Mapping/attributes.html",
    "title": "Property Attributes | ArgentSea Docs",
    "keywords": "Property Attributes You use properties attributes to define the metadata that the Mapper requires. For example, given this very simple model class: using System; public class Subscriber { public int SubscriberId { get; set; } public string Name { get; set; } public DateTime Expiration { get; set; } } Adding mapping attributes to this class provides the metadata to automatically map these properties to stored procedures or SQL statements: SQL Server PostgreSQL using System; using ArgentSea.Sql; public class Subscriber { [MapToSqlInt(\"@SubID\", true)] public int SubscriberId { get; set; } [MapToSqlNVarChar(\"@SubscriberName\", 255)] public string Name { get; set; } [MapToSqlDateTime2(\"@EndDate\")] public DateTime Expiration { get; set; } } Note The “@” parameter prefix is optional — ArgentSea will always add the “@” automatically for parameters and remove it automatically when reading data reader rows. using System; using ArgentSea.Pg; public class Subscriber { [MapToPgInteger(\"SubId\", true)] public int SubscriberId { get; set; } [MapToPgVarchar(\"SubscriberName\", 255)] public string Name { get; set; } [MapToPgTimestamp(\"EndDate\")] public DateTime Expiration { get; set; } } Note ArgentSea will automatically convert the casing of parameter names and column names to lowercase . Often, due to different naming conventions or development drift, database column names and the corresponding .NET properties names do not match. That is why every attribute requires a “name” argument — which should correspond to the database name. The Mapper will create query parameters and reference DataReader columns based on this name. Important Database parameters and columns should be named as consistently as possible. In most cases, this means the parameters have the same name as the columns they reference. If you like to use varying parameter names or alias columns in your result, you will find the Mapper unhelpful. Properties without a mapping attribute are simply ignored. Attribute Types A mapping attribute is defined for most common database types. Attributes for spatial data types, CLR types, XML, and JSON types (for example) are missing because there is no straightforward mapping between the core .NET base types and these database types. ArgentSea supports writing a custom handler to render any of these complex types; such work is no more difficult than writing the same processing in ADO.NET. The attribute itself defines the underlying database type. Naturally, the attribute type and the property type must match. For example, a long (Int64) property must map to a bigint database type. The Mapper will throw an error if these types do not match. There is no attempt to cast data to a different type, even if the cast would be successful. Many data attribute types have an additional parameters. The length argument, for example, on string and array types, helps optimize data access performance by ensuring that buffers are sized appropriately. Here is catalog of the current attributes, along with their arguments and corresponding .NET types: SQL Server PostgreSQL Attribute Arguments .NET types SqlType MapToSqlNVarCharAttribute length¹ String, Enum², Nullable<Enum> NVarChar MapToSqlNCharAttribute length String, Enum², Nullable<Enum> NChar MapToSqlVarCharAttribute length¹, localeid³ String, Enum², Nullable<Enum> VarChar MapToSqlCharAttribute length, localeid³ String, Enum², Nullable<Enum> Char MapToSqlBigIntAttribute Int64, Enum⁴, Nullable<Int64>, Nullable<Enum> BigInt MapToSqlIntAttribute Int32, Enum⁴, Nullable<Int32>, Nullable<Enum> Int MapToSqlSmallIntAttribute Int16, Enum⁴, Nullable<Int16>, Nullable<Enum> SmallInt MapToSqlTinyIntAttribute Byte, Enum⁴, Nullable<Byte>, Nullable<Enum> TinyInt MapToSqlBitAttribute Boolean, Nullable<Boolean> Bit MapToSqlDecimalAttribute precision, scale Decimal, Nullable<Decimal> Decimal MapToSqlMoneyAttribute Decimal, Nullable<Decimal> Money MapToSqlSmallMoneyAttribute Decimal, Nullable<Decimal> SmallMoney MapToSqlFloatAttribute Double, Nullable<Double> Float MapToSqlRealAttribute Float, Nullable<Float> Real MapToSqlDateTimeAttribute DateTime, Nullable<DateTime> DateTime MapToSqlDateTime2Attribute precision DateTime, Nullable<DateTime> DateTime2 MapToSqlDateAttribute DateTime, Nullable<DateTime> Date MapToSqlTimeAttribute TimeSpan, Nullable<TimeSpan> Time MapToSqlDateTimeOffsetAttribute DateTimeOffset, Nullable<DateTimeOffset> DateTimeOffset MapToSqlVarBinaryAttribute length¹ byte[] VarBinary MapToSqlBinaryAttribute length byte[] Binary MapToSqlUniqueIdentifierAttribute Guid, Nullable<Guid> UniqueIdentifier ¹ For “max” values (nvarchar(max), varbinary(max), etc.) use length of -1. ² The Enum name is saved as string. ³ Locale Id is the Ansi code page to use for Unicode conversion. For en-US locale, for example, use 1033. ⁴ The Enum value is saved based on its underlying numeric value. The Enum integer base type (int, short, byte, etc.) must match the database type. Attribute Arguments .NET types SQL Type MapToPgVarcharAttribute length String, Enum¹, Nullable<Enum> VarChar MapToPgCharAttribute length String, Enum¹, Nullable<Enum> Char MapToPgTextAttribute String, Enum¹, Nullable<Enum> VarChar MapToPgBigintAttribute Int64, Enum², Nullable<Int64>, Nullable<Enum> Bigint MapToPgIntegerAttribute Int32, Enum², Nullable<Int32>, Nullable<Enum> Integer MapToPgSmallintAttribute Int16, Enum², Nullable<Int16>, Nullable<Enum> Smallint MapToPgInternalCharAttribute Byte, Enum², Nullable<Byte>, Nullable<Enum> (Internal) \"char\"³ MapToPgBooleanAttribute Boolean, Nullable<Boolean> Boolean MapToPgNumericAttribute precision, scale Decimal, Nullable<Decimal> Numeric MapToPgMoneyAttribute Decimal, Nullable<Decimal> Money MapToPgDoubleAttribute Double, Nullable<Double> Double MapToPgRealAttribute Float, Nullable<Float> Real MapToPgTimestampAttribute DateTime, DateTimeOffset, Nullable<DateTime>, Nullable<DateTimeOffset> Timestamp MapToPgTimestampTzAttribute DateTimeOffset, Nullable<DateTimeOffset> TimestampTz MapToPgDateAttribute DateTime, Nullable<DateTime> Date MapToPgTimeAttribute TimeSpan, Nullable<TimeSpan> Time MapToPgIntervalAttribute TimeSpan, Nullable<TimeSpan> Interval MapToPgTimeTzAttribute TimeSpan, DateTimeOffset, Nullable<TimeSpan>, Nullable<DateTimeOffset> TimeTz MapToPgArrayAttribute Array Array MapToPgByteaAttribute length byte[] Bytea MapToPgArrayAttribute NpgsqlType T[]⁴ Array MapToPgHstoreAttribute length IDictionary<string, string> Hstore MapToPgUuidAttribute Guid, Nullable<Guid> UniqueIdentifier ¹ The Enum name is saved as string. ² The Enum value is saved based on its underlying numeric value. The Enum integer base type (int, short, etc.) must match the database type. ³ This data type is not intended for general use. ⁴ The Npgsql type is used to create parameters; the Property type is used to read them. Required Finally, the the data attributes have an optional required (sic) parameter. If a database field is DbNull, the Mapper will normally set the corresponding property to null. However, the missing value may represent an entirely absent record. In this case, the correct result is a null object, not a valid instance with null/default properties. Setting a property attribute’s required argument to True causes the Mapper to return a null object if the property would be null. By default (if not specified), required is false. Handling Nulls and Empty Types Because the Mapper is handling database values, there is generally a possibility that the database value is DbNull. How this is converted to a .NET type depends upon the type. Strings and Arrays A .NET string with a value of null or a null array will be saved as a DbNull. Empty strings will save as a zero-length string. Integers Integers cannot be null, so the advent of nullable types is a godsend for mapping to database storage. To save or retrieve an integer (byte, Int16, Int32, or Int64) database value from a column that allows null, you should declare a nullable value type. Floating Point Numbers Like integer types, floating point types (Double and Float) can be wrapped in a nullable value. However, ArgentSea also handles NaN as a DbNull. If the floating point value is presented as a nullable type, then ArgentSea will save or retrieve NaN; if floating point type is presented, then NaN will be converted to/from a DbNull. Guids Rather like floating point types, Guid.Empty (00000000-0000-0000-0000-000000000000) will be converted to a data DbNull when read from or written to the database. Also like floats, if you need to write an empty Guid value, wrap it in a nullable type. Enum Types .NET enum values can be stored as either numbers or strings. Writing to a text column will automatically save the name of the enum; writing to a numeric column saves the number value. Warning Enums can inherit from several base types (byte, short, int, etc.). If you are saving to a numeric database column, the base type must correctly correspond to the database data type. Enums are Int32 by default. Nullable Enum types will read or write as a DbNull when the value is null. Model Inheritance Models which inherit from other Model classes also inherit the attributes of the parent class. This can be very useful when some queries return a subset of the data entities overall columns. Properties with Object Types This page has described simple 1:1 mapping between database columns and model properties. This is the heart of the Mapper. However, mapping sometimes requires more complex types, built from these simple relationships. In addition to the types already described, the Mapper supports three additional types of Model properties: Properties which contain a second Model class Properties which contain lists of Model classes Sharded record identifiers These will be explored in the next section. Next: Complex Attributes"
  },
  "tutorials/index.html": {
    "href": "tutorials/index.html",
    "title": "Overview | ArgentSea Docs",
    "keywords": "Overview ArgentSea is built on top of ADO.NET, so an understanding of basic .NET data access is essential to understanding ArgentSea. Once you understand the architecture of the framework, you will find it no more difficult to use (and generally less difficult) than other .NET data access approaches. You can always still use ADO.NET to resolve any capability gaps or distinctive query requirements. Setup Tutorial Because data sharding is difficult to retroactively add to an existing project without rewriting it, if you are creating a new project, it makes sense to use .NET Core rather than the legacy .NET Framework. ArgentSea would probably work in a legacy .NET Framework application (i.e. it is .NET standard compatible), but it is not tested for this purpose and it uses services — such as dependency injection, configuration, and logging — that are implemented differently in the different .NET versions. If you do use the legacy .NET Framework, please help build out our documentation with any guidance you can share. Configuration Tutorial Especially when sharding is introduced, applications may need to manage many database connections. ArgentSea introduces a unique “hereditary configuration hierarchy”, which allows a large number of connections to be managed painlessly. This approach also allows sensitive elements — like database login passwords — to be stored securely, away from your source code. This innate flexibility also dramatically simplifies managing configuration in different dev, test, staging, and production environments. ArgentSea fully supports scale-out deployments where writes are sent to a principal node and read activity is sent to an actively cloned endpoint. This leverages capabilities like SQL Availability Group Readable Secondaries and SQL Read-scale Availability Groups , PostgreSQL Hot Standbys , SQL Azure Read Scale-out or SQL Azure Geo-replicas , and Amazon RDS Read Replicas or Amazon Aurora Reader Endpoints . ArgentSea uses the new configuration infrastructure in .NET Core, including strongly typed Options classes and injectable services, and retains the flexibility of using the many available configuration providers: JSON file, environment variables, key stores, and more. Mapping Tutorial ADO.NET data access can require a lot of boilerplate code but libraries that try to reduce this often come with performance tradeoffs. ArgentSea contains a unique ORM (Object-Relational Mapper) that is focused on parameters and data results rather than generating dynamic SQL. Like most ORMs, simple property attributes provide metadata which makes the coding easy and simple. Unlike many ORMs, ArgentSea removes the reflection overhead by compiling the property-to-data mapping; subsequent mapping invocations are as fast as optimized ADO.NET code. The Mapper flexibly handles nulls and Enumerated values. Database null values map to/from nullable types (or, occasionally, empty types). Enum properties can map to either string data fields (containing the Enum name) or numeric fields (containing the base value). The Mapper even handles nullable Enums. Querying Tutorial The ArgentSea framework allows querying either Databases and ShardSets. When using the Mapper, this can take as little as one line of code. You may occasionally need to write a custom data handler, but this isn’t more difficult than the ADO.NET code you are used to. Concurrent querying across multiple shards requires “non-standard” implementations of ADO.NET or Entity Framework, but ArgentSea makes this easy. If you are using shards, you can easily and simultaneously query across all shards, combining the results or getting only the first valid result. Sharding Tutorial Sharded data presents two special challenges: uniquely identifying a specific record across all servers and managing data relationships between shards. Because foreign key relationships and unique constraints are no longer enforced by the database engine, a sharded application needs a global strategy for identifying records. ArgentSea offers a “virtual compound key” where the shard identifier and the record identity combine as the record key. (Of course, ArgentSea can also work with other record identity approaches too). ArgentSea makes querying a shard set as simple as querying a single database. Next: Setting up"
  },
  "tutorials/Querying/handling.html": {
    "href": "tutorials/Querying/handling.html",
    "title": "Handling Data Results | ArgentSea Docs",
    "keywords": "Handling Data Results If you are using data mapping attributes in your Model classes, the MapReader* , MapOutput* , and MapList* methods make handling data results unnecessary. This section is for queries that use the Query* methods, which allow you to return an arbitrary object from the data input. If you are familiar with ADO.NET programming, this will be very familiar. The delegate simply receives the standard ADO.NET query results and processes them like it would in most other ADO.NET scenarios. As an example, a method with the correct signature for returning a Store model looks like this: public static Store MyStoreHandler ( short shardId, string sprocName, Department department, // this is an optional custom argument DbDataReader reader, DbParameterCollection parameters, string connectionDescription, ILogger logger) { var result = new Store(); // use the reader argument and/or parameters collection to set your result properties. return result; } The Arguments Both the return type (“Store”, in the example) and the optional data argument (“Department”, in the example) are generic, so they can be of any type. (short) shardId The shardId argument will be a default value, like null or zero, when not using a ShardSet; otherwise it will be set to the current ShardId. This value is essential when building ShardKey types, where the shard identity is a component of the record identity. (string) sprocName This is the name of the stored procedure or SQL statement that was executed. It is provided to the procedure for logging purposes. (TArg) optionalArgument The third argument type is a generic parameter; the type is defined when you declare the delegate. This object provides whatever external data or context that many be necessary or useful in order to create your result. If it not needed (i.e. most cases), define the type as object . This allows you to use the Query* overloads that do not require this parameter; in those cases, this value will be null. (DbDataReader) reader The reader argument is a standard data reader. You can call reader.MoveNext() to get the next row and reader.NextResult() to get the next result set. You do not need to dispose of it when you are done. (DbParameterCollection) parameters The parameters collection contains the input and output parameters for the query. ArgentSea offers a set of extension methods to simplify converting parameter values to .NET types. These are extension methods on the parameter object (not the collection). var transactionId = parameters[\"@TransactionId\"].GetInteger(); var amount = parameters[\"@Amount\"].GetNullableDecimal(); var name = parameters[\"@Name\"].GetString(); (string) connectionDescription The connectionDescription argument allows the logger to include the connection that raised the error or event. You should include this (and also the stored procedure or statement name) in any logging or errors in your procedures. Because your delegate could run on multiple connections, this can be essential debugging information. (ILogger) logger Finally, the logger argument allows you to write debugging, warning, and error information to the application logs. This is the same logger instance as is passed in through the various query methods. Next: The Query Batch"
  },
  "tutorials/Mapping/targets.html": {
    "href": "tutorials/Mapping/targets.html",
    "title": "Mapping Targets | ArgentSea Docs",
    "keywords": "Mapping Targets The ArgentSea Mapper maps to: Query input parameters Query output parameters Data reader columns Table-valued parameters (SQL Server) or Copy statements (PostgreSQL) The mapper does not generate dynamic SQL statements. The Mapper may be useful in situations where dynamic SQL is used, but, philosophically, this is not encouraged. Stored procedures and parameterized SQL statements are generally more secure, more performant, and offer a less tightly-coupled architecture. The Parameter Collection The Mapper’s parameter methods are implemented as an extension method to the (abstract) DbParametersCollection, which is inherited by each provider implementation of the DbCommand.Parameters property. This means that you can call the Mapper through the command object of any provider. cmd.Parameters.CreateInputParameters<MyDataClass>(myDataClass, logger); // or cmd.Parameters.CreateOutputParameters<MyDataClass>(logger); These extension methods can be combined with the other extension methods for a fluent API , which allows you to build a logical sequence of code that may be more readable. SQL Server PostgreSQL For example, this code uses the fluent API to to set an output parameter and then the mapper to create and set all the other object properties from a transaction object. cmd.Parameters.AddSqlIntOutputParameter(\"@TransactionId\") .CreateInputParameters<Transaction>(transaction, logger); For example, this code uses the fluent API to to set an output parameter and then the mapper to create and set all the other object properties from a transaction object. cmd.Parameters.AddPgIntegerOutputParameter(\"TransactionId\") .CreateInputParameters<Transaction>(transaction, logger); In ADO.NET, you normally access the data parameters collection ( SqlParametersCollection , NpgsqlParametersCollection , etc.) through the Parameters property of the command object. In ArgentSea, you can still do this; the Mapper and other extension methods work on the parameters collection property. When working with sharded data, however, this presents a problem that is described in detail in the tutorial on querying . The gist is that there is a need to create a parameters list independently of a command object. Enter the QueryParameterCollection class. It’s functionally not much more than a parameter list, but it can be created without a command object. Because it also inherits from the abstract DbParameterCollection , the same extension methods — like the Mapper — work on this object too. SQL Server PostgreSQL Again, the optional fluent API makes setting an input parameter and a mapped set of output parameters quite simple: var prms = new QueryParameterCollection() .AddSqlBigIntInputParameter(\"@ID\", _id) .CreateOutputParameters<MyClass>(logger); Again, the optional fluent API makes setting an input parameter and a mapped set of output parameters quite simple: var prms = new QueryParameterCollection() .AddPgBigintInputParameter(\"ID\", _id) .CreateOutputParameters<MyClass>(logger); Mapping to Input Parameters You can create input parameters with the CreateInputParameters method. This is an extension method on the parameters collection. The mapping attributes in your class will be used to: Create the set of input parameters Set the value of those parameters to the value of the corresponding property. That is all the Mapper does. The Mapper simply saved you the time and effort of hand-coding a whole bunch of parameters. You can view the parameters in the debugger and you can add, remove or update any of them. If a particular query needs a parameter that is not presented in a property attribute, just add it to parameter the collection yourself! Any parameters already added to the parameter collection will not be recreated (the names must match exactly). This is helpful if you need to treat one or more parameters differently (say, an output parameter in a collection of input parameters). If you don’t want the Mapper to create a particular parameter set, you can provide a list of parameter names to suppress. Mapping to Output Parameters Working with output parameters is done in two steps: Create the output parameters before executing the query Read the output parameter values after executing the query SQL Server PostgreSQL This example creates and sets the CustomerId parameter and creates all of the output parameters. It then executes the query and reads the output values into a new object. cmd.Parameters.AddSqlIntInputParameter(\"@CustomerId\", _Id) .CreateOutputParameters<Customer>(logger); await cmd.ExecuteNonQueryAsync(); var customer = cmd.Parameters.ToModel<Customer>(logger); This example creates and sets the CustomerId parameter and creates all of the output parameters. It then executes the query and reads the output values into a new object. cmd.Parameters.AddPgIntegerInputParameter(\"CustomerId\", _Id) .CreateOutputParameters<Customer>(logger); await cmd.ExecuteNonQueryAsync(); var customer = cmd.Parameters.ToModel<Customer>(logger); Of course, it would be quite unusual to have a query that only uses output parameters. Because the input parameter is added to the collection first, the output parameter will be automatically skipped. As with input parameters, you can also provide a list of parameter names that you want to explicitly skip. And also like input parameters, the CreateOutputParameters method simply creates output parameters; you can modify the collection as needed. Once the parameters are set and the query is executed, the Mapper can read the values of the output parameters into the corresponding properties of a new object instance. The ToModel method returns a new object with the properties set. Note The MapOutput*; methods of the Database or ShardSet objects fetch results from the database and implicitly use the Mapper to return a Model based upon output parameters. In most cases, you would use one of those methods rather than ToModel on the Mapper directly. Mapping from DataReader Results The Mapper also converts the rows presented by a DataReader object into a list of corresponding objects, or a single row into a Model instance. For example, to map to a list of objects: var customers = rdr.ToList<Customer>(logger); The IList result will contain an object instance for each valid row. If an attribute is marked “required” but the corresponding data field is DbNull, then the object will not be included listed results. To map to a single Model instance: var customer = rdr.ToModel<Customer>(logger); Note As with output parameters, the MapReader*; or MapListAsync methods of the Database or ShardSet objects fetch results from the database and implicitly use the Mapper to return a Model based upon DataReader results. In most cases, you would use one of those methods rather than ToList or ToModel on the Mapper. The DataReader mapping methods allow you to use multiple SELECT result to map both the base object and one or more list properties. The order of the generic objects provided to the Mapper determines the expected order of the result streams in the DataReader. Mapping to Data Loaders In addition to the capabilities just discussed, ArgentSea has provider-specific Mapping functionality. SQL Server PostgreSQL The SQL Server library offers a Mapper to set Table Valued Parameters. A Table Valued Parameter allows a series of records to be sent to a stored procedure, which can dramatically improve performance compared to multiple requests. The PostgreSQL library offers a Mapper to create tables and load data using PostgreSQL COPY command and the NpgsqlBinaryImporter. Next: The Mapper Generated Code"
  },
  "tutorials/Configuration/simplifying.html": {
    "href": "tutorials/Configuration/simplifying.html",
    "title": "Simplifying Your Data Access Code | ArgentSea Docs",
    "keywords": "Simplifying Your Data Access Code As per standard practice in .NET Core, any data repository class can use the ArgentSea data access component by having the service injected into its constructor. For example, requesting the databases collection in your data access class is straightforward: SQL Server PostgreSQL public class MyDataAccessStore { private readonly SqlDatabases _dbs; public MyDataAccessStore(SqlDatabases dbs, ILogger<MyDataAccessStore> logger) { _dbs = dbs; // capturing injected SqlDatabases collection ... Likewise, access to the entire collection of shard sites via injection: public class MyDataAccessStore { private readonly SqlShardSets _shardSets; public MyDataAccessStore(SqlShardSets shardsets, ILogger<MyDataAccessStore> logger) { _shardSets = shardSets; // capturing injected SqlShardSets collection ... In most cases, your repository class would not require access to all shard sets or all databases. Capturing the entire collection also requires specifying the collection key for every data access. A class will generally only access a single data source, so, to simplify the data access code, you can instead store only the relevant connection instance: public class MyDataAccessStore { private readonly SqlDatabases.DataConnection _data; public MyDataAccessStore(SqlDatabases dbs, ILogger<MyDataAccessStore> logger) { _data = dbs[\"MyConnectionKey\"]; // capturing only the relevant database ... Or public class MyDataAccessStore { private readonly SqlShardSets.ShardDataSet _shards; public MyDataAccessStore(SqlShardSets shardSets, ILogger<MyDataAccessStore> logger) { _shards = shardSets[\"MyShardSetKey\"]; // capturing only the relevant shard set ... Setup this way, subsequent calls to the SQL database can be on methods directly on the _data object. Now, calls within the class do not need to specify a key. public class MyDataAccessStore { private readonly PgDatabases _dbs; public MyDataAccessStore(PgDatabases dbs, ILogger<MyDataAccessStore> logger) { _dbs = dbs; // capturing injected PgDatabases collection ... Likewise, access to the entire collection of shard sites via injection: public class MyDataAccessStore { private readonly PgShardSets _shardSets; public MyDataAccessStore(PgShardSets shardsets, ILogger<MyDataAccessStore> logger) { _shardSets = shardSets; // capturing injected SqlShardSets collection ... In most cases, your repository class would not require access to all shard sets or all databases. Capturing the entire collection also requires specifying the collection key for every data access. A class will generally only access a single data source, so, to simplify the data access code, you can instead store only the relevant connection instance: public class MyDataAccessStore { private readonly PgDatabases.DataConnection _data; public MyDataAccessStore(PgDatabases dbs, ILogger<MyDataAccessStore> logger) { _data = dbs[\"MyConnectionKey\"]; // capturing only the relevant database ... Or public class MyDataAccessStore { private readonly PgShardSets.ShardDataSet _shards; public MyDataAccessStore(PgShardSets shardSets, ILogger<MyDataAccessStore> logger) { _shards = shardSets[\"MyShardSetKey\"]; // capturing only the relevant shard set ... Setup this way, subsequent calls to the SQL database can be on methods directly on the _data object. Now, calls within the class do not need to specify a key. Next: Data Mapping"
  },
  "documentation/faqs.html": {
    "href": "documentation/faqs.html",
    "title": "Frequently Asked Questions | ArgentSea Docs",
    "keywords": "Frequently Asked Questions Q: What happens if ArgentSea isn’t flexible enough to do what I need it to do? A: ArgentSea is a simple layer over ADO.Net. You can easily amend its functionality by simply coding your unique requirements directly in ADO.Net (as you would have done without the framework). For example, if you are using the Mapper and the model attributes add a database parameter that you don’t want; just remove the parameter after calling the mapper! Or set the parameters yourself. Setting parameters, invoking queries, and collecting results are all separate processes, so you can skip any one that has unique requirements, and still use any of the others. You can, for example, create parameters using the Mapper and invoke a query using your own Command object. Q: Can I combine the PostgreSQL and SQL Server implementations? Nope. A review of the effort involved in enabling both platforms in the same project indicates that the effort to support this exceeds the potential value. If you disagree with this conclusion, sending a note describing the value in your implementation. (The first obstacle is that Mapper does not know which provider will eventually execute the parameters it creates, so if it encountered multiple attributes referencing different providers, it would not know which to use; the other problem is that we would have to separately the function delegates from each provider. Both concerns might be surmountable, but they would add considerable complexity). Q: Why is an approach that exclusively uses stored procedures better? A: Stored procedures offer performance, manageability, and security benefits. Stored procedures do not require the database engine to parse your SQL string, so this can have a performance benefit. In most cases, the benefit is very small, however SQL Server’s compiled procedures offer a potentially dramatic improvement. If your application only has EXECUTE permission to stored procedures, then it becomes possible for DBA to comprehensively determine which tables/views/columns are access by the application. Knowing this allows the database to be refactored and improved much less concern about unintended consequences. With dynamic SQL, DBAs must resort to traces or logs to see what activity is being performed, which makes troubleshooting much harder. When a bad SQL plan is uncovered, the fix can be even harder. Stored procedures, on the other hand, allow the DBA to hint, rewrite, and optimize as necessary. Finally, stored procedures allow DBAs (or data access SMEs) to review and approve data access code changes, also to ensure that indexes exist to support the new queries. Q: How can I make sure that my data is secure? A: Start by hiring an knowledgeable DBA. ArgentSea helps in a few additional ways: ArgentSea’s configuration design helps protect against unsafe storage of login passwords within connection strings. Because it uses stored procedures, users cannot run arbitrary SQL statements. This reduces the opportunity for mistaken SQL statements that corrupt data, SQL injection attacks, and data operations to which the DBAs do not have visibility. Because you can run your application with only EXECUTE permissions, no user would have access to operations that are not explicitly enabled by a procedure."
  },
  "tutorials/Querying/multirecord.html": {
    "href": "tutorials/Querying/multirecord.html",
    "title": "Multi-record Saves | ArgentSea Docs",
    "keywords": "Multi-record Saves One of the best ways to improve performance is to simply reduce the number of server round-trips. When transactions need to save a list of order items, or customer locations, or other related data, the entire data set should be loaded and committed as a batch. Unfortunately, ADO.Net makes this a little more difficult because it doesn’t offer consistency across platforms. SQL Server PostgreSQL Although SQL Server can accept multi-valued parameters via XML or JSON or even parsable strings, the standard, recommended approach is to use Table Valued Parameters. ArgentSea offers a Mapper for TVPs too. The TVP Mapper accepts a Model object and returns a SqlDataRecord build from the mapping attributes. The Table Valued Parameters accepts a collection (list, array, etc.) or the SqlDataRecord objects. Like all Mapper processes, the conversion logic is extracted and compiled on the first call, offering native-compiliation performance on subsequent calls. An implementation, then, simply iterates the list of Model objects, creating the corresponding list of SqlDataRecords . The list of records is a assigned to a parameter like any other value. Like this: var contactRecords = new List<SqlDataRecord>(); customer.Contacts.ForEach(contact => { contactRecords.Add(TvpMapper.ToTvpRecord<ContactModel>(contact, _logger)); }); var prms = new ParameterCollection() .AddSqlIntInputParameter(\"@CustomerId\") .AddSqlTableValuedParameter(\"@Contacts\", contactRecords); For higher performance with very large data sets, the Batch functionality could allow someone to implement a BatchStep that uses the SqlBulkCopy class. This would be similar to the approach used by the PostgreSQL implementation. ArgentSea supports PostgreSQL’s COPY functionality using the NpgsqlBinaryImporter. This is how data sets can be efficiently loaded into PostgreSQL. ArgentSea’s Batch functionality is used to load data into PostgreSQL tables or temporary tables, then a SQL statement is used to process and commit these values. The Batch automatically ensures that both steps share the same transaction. This example creates a batch, then adds a step to push a series of values to a temporary table called “t-locations”. The next step runs a SQL statement that uses both the SQL parameters and the temporary table to save the data. using ArgentSea.Pg; //... var customerPrms = new ParameterCollection() .AddPgVarcharInputParameter(\"customername\", customer.Name, 255); var shardBatch = new ShardBatch<ShardKey<short, int>>() .Add(customer.Locations, \"t-locations\") .Add(Queries.CustomerSave, customerPrms, DataOrigins.Customer, \"customerid\"); var custKey = await _shardSet.DefaultShard.Write.RunAsync(shardBatch, cancellation); Next: Sharding"
  },
  "api/ArgentSea.IDataProviderServiceFactory.html": {
    "href": "api/ArgentSea.IDataProviderServiceFactory.html",
    "title": "Interface IDataProviderServiceFactory | ArgentSea Docs",
    "keywords": "Interface IDataProviderServiceFactory This interface is used by provider specific implementations. It is unlikely that you would reference this in consumer code. The interface defines the capabilities of a database providers service. Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public interface IDataProviderServiceFactory Methods | Improve this Doc View Source GetIsErrorTransient(Exception) Declaration bool GetIsErrorTransient(Exception exception) Parameters Type Name Description System.Exception exception Returns Type Description System.Boolean | Improve this Doc View Source NewCommand(String, DbConnection) Declaration DbCommand NewCommand(string storedProcedureName, DbConnection connection) Parameters Type Name Description System.String storedProcedureName System.Data.Common.DbConnection connection Returns Type Description System.Data.Common.DbCommand | Improve this Doc View Source NewConnection(String) Declaration DbConnection NewConnection(string connectionString) Parameters Type Name Description System.String connectionString Returns Type Description System.Data.Common.DbConnection | Improve this Doc View Source SetParameters(DbCommand, DbParameterCollection) Declaration void SetParameters(DbCommand cmd, DbParameterCollection parameters) Parameters Type Name Description System.Data.Common.DbCommand cmd System.Data.Common.DbParameterCollection parameters"
  },
  "api/ArgentSea.Test.html": {
    "href": "api/ArgentSea.Test.html",
    "title": "Namespace ArgentSea.Test | ArgentSea Docs",
    "keywords": "Namespace ArgentSea.Test Classes ShardSerializationTests StringExtensionTests"
  },
  "api/ArgentSea.DataOrigin.html": {
    "href": "api/ArgentSea.DataOrigin.html",
    "title": "Struct DataOrigin | ArgentSea Docs",
    "keywords": "Struct DataOrigin This object help descript the “type” of data. For example, you could assign Customer data a data origin value of 'c'. When comparing data values, the ShardKey/ShardChild will not match if the data origin is not the same value — even if IDs are the same. This helps prevent accidentaly comparisions that are not valid and also prevents collisions if you choose allows values of different types to be stored in the same cache. Implements System.IEquatable < System.Object > Inherited Members System.ValueType.ToString() System.Object.Equals(System.Object, System.Object) System.Object.GetType() System.Object.ReferenceEquals(System.Object, System.Object) Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public struct DataOrigin : IEquatable<object> Constructors | Improve this Doc View Source DataOrigin(Char) Declaration public DataOrigin(char sourceIndicator) Parameters Type Name Description System.Char sourceIndicator Properties | Improve this Doc View Source SourceIndicator Declaration public char SourceIndicator { get; } Property Value Type Description System.Char Methods | Improve this Doc View Source Equals(Object) Declaration public override bool Equals(object other) Parameters Type Name Description System.Object other Returns Type Description System.Boolean Overrides System.ValueType.Equals(System.Object) | Improve this Doc View Source GetHashCode() Declaration public override int GetHashCode() Returns Type Description System.Int32 Overrides System.ValueType.GetHashCode() Operators | Improve this Doc View Source Equality(DataOrigin, DataOrigin) Declaration public static bool operator ==(DataOrigin do1, DataOrigin do2) Parameters Type Name Description DataOrigin do1 DataOrigin do2 Returns Type Description System.Boolean | Improve this Doc View Source Inequality(DataOrigin, DataOrigin) Declaration public static bool operator !=(DataOrigin do1, DataOrigin do2) Parameters Type Name Description DataOrigin do1 DataOrigin do2 Returns Type Description System.Boolean Implements System.IEquatable<T>"
  },
  "api/ArgentSea.MultipleMapAttributesException.html": {
    "href": "api/ArgentSea.MultipleMapAttributesException.html",
    "title": "Class MultipleMapAttributesException | ArgentSea Docs",
    "keywords": "Class MultipleMapAttributesException This exception is invoked if a model property has multiple mapping attributes. A single value cannot be mapped to/from multiple parameters or columns. This exception is not raised in the case of ShardKey > or ShardChild properties. Inheritance System.Object System.Exception MultipleMapAttributesException Implements System.Runtime.Serialization.ISerializable Inherited Members System.Exception.GetBaseException() System.Exception.GetObjectData(System.Runtime.Serialization.SerializationInfo, System.Runtime.Serialization.StreamingContext) System.Exception.GetType() System.Exception.ToString() System.Exception.Data System.Exception.HelpLink System.Exception.HResult System.Exception.InnerException System.Exception.Message System.Exception.Source System.Exception.StackTrace System.Exception.TargetSite System.Exception.SerializeObjectState System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public sealed class MultipleMapAttributesException : Exception, ISerializable Constructors | Improve this Doc View Source MultipleMapAttributesException() Initializes a new instance of the MultipleMapAttributesException class with no error message. Declaration public MultipleMapAttributesException() | Improve this Doc View Source MultipleMapAttributesException(PropertyInfo) Initializes a new instance of the MultipleMapAttributesException class. Declaration public MultipleMapAttributesException(PropertyInfo property) Parameters Type Name Description System.Reflection.PropertyInfo property The property that is decorated with multiple mapping attributes. | Improve this Doc View Source MultipleMapAttributesException(String) Initializes a new instance of the MultipleMapAttributesException class with a specified error message. Declaration public MultipleMapAttributesException(string message) Parameters Type Name Description System.String message The message that describes the error. | Improve this Doc View Source MultipleMapAttributesException(String, Exception) Initializes a new instance of the MultipleMapAttributesException class. Declaration public MultipleMapAttributesException(string message, Exception innerException) Parameters Type Name Description System.String message The message that describes the error. System.Exception innerException The exception that is the cause of the current exception. Implements System.Runtime.Serialization.ISerializable"
  },
  "api/ArgentSea.DbDataStores-1.DbDataSets.html": {
    "href": "api/ArgentSea.DbDataStores-1.DbDataSets.html",
    "title": "Class DbDataStores<TConfiguration>.DbDataSets | ArgentSea Docs",
    "keywords": "Class DbDataStores<TConfiguration>.DbDataSets Inheritance System.Object DbDataStores<TConfiguration>.DbDataSets Implements System.Collections.ICollection System.Collections.IEnumerable Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class DbDataSets : ICollection, IEnumerable Constructors | Improve this Doc View Source DbDataSets(DbDataStores<TConfiguration>, IDbConnectionConfiguration[]) Declaration public DbDataSets(DbDataStores<TConfiguration> parent, IDbConnectionConfiguration[] config) Parameters Type Name Description DbDataStores <TConfiguration> parent IDbConnectionConfiguration [] config Properties | Improve this Doc View Source Count Declaration public int Count { get; } Property Value Type Description System.Int32 | Improve this Doc View Source IsSynchronized Declaration public bool IsSynchronized { get; } Property Value Type Description System.Boolean | Improve this Doc View Source Item[String] Declaration public DbDataStores<TConfiguration>.DataConnection this[string key] { get; } Parameters Type Name Description System.String key Property Value Type Description DbDataStores.DataConnection <> | Improve this Doc View Source SyncRoot Declaration public object SyncRoot { get; } Property Value Type Description System.Object Methods | Improve this Doc View Source CopyTo(Array, Int32) Declaration public void CopyTo(Array array, int index) Parameters Type Name Description System.Array array System.Int32 index | Improve this Doc View Source GetEnumerator() Declaration public IEnumerator GetEnumerator() Returns Type Description System.Collections.IEnumerator Implements System.Collections.ICollection System.Collections.IEnumerable"
  },
  "api/ArgentSea.DataResilienceOptions.html": {
    "href": "api/ArgentSea.DataResilienceOptions.html",
    "title": "Class DataResilienceOptions | ArgentSea Docs",
    "keywords": "Class DataResilienceOptions This options class contains an array of resilience strategies (retry and circuit breaking settings). To specify as particular resilience strategy, a connection can specify a ResilienceKey. Inheritance System.Object DataResilienceOptions Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class DataResilienceOptions Examples For example, you might configure your appsettings.json like this: \"ResilienceStrategies\": [ { \"ResilienceKey\": \"remote\", \"RetryCount\": \"6\", \"RetryInterval\": \"250\", \"RetryLengthening\": \"Finonacci\", \"CircuitBreakerFailureCount\": \"20\", \"CircuitBreakerTestInterval\": \"5000\" }, { \"ResilienceKey\": \"local\", \"RetryCount\": \"6\", \"RetryInterval\": \"150\", \"RetryLengthening\": \"Linear\", \"CircuitBreakerFailureCount\": \"10\", \"CircuitBreakerTestInterval\": \"5000\" } ] Properties | Improve this Doc View Source DataResilienceStrategies Declaration public DataResilienceConfiguration[] DataResilienceStrategies { get; set; } Property Value Type Description DataResilienceConfiguration []"
  },
  "api/ArgentSea.IDbDataConfigurationOptions.html": {
    "href": "api/ArgentSea.IDbDataConfigurationOptions.html",
    "title": "Interface IDbDataConfigurationOptions | ArgentSea Docs",
    "keywords": "Interface IDbDataConfigurationOptions This interface is used by provider specific implementations. It is unlikely that you would implement this in consumer code. Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public interface IDbDataConfigurationOptions Properties | Improve this Doc View Source DbConnectionsInternal Declaration IDbConnectionConfiguration[] DbConnectionsInternal { get; } Property Value Type Description IDbConnectionConfiguration []"
  },
  "api/ArgentSea.IDbConnectionConfiguration.html": {
    "href": "api/ArgentSea.IDbConnectionConfiguration.html",
    "title": "Interface IDbConnectionConfiguration | ArgentSea Docs",
    "keywords": "Interface IDbConnectionConfiguration This interface is used by provider specific implementations. It is unlikely that you would implement this in consumer code. Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public interface IDbConnectionConfiguration Properties | Improve this Doc View Source DatabaseKey Declaration string DatabaseKey { get; set; } Property Value Type Description System.String | Improve this Doc View Source DataConnectionInternal Declaration IConnectionConfiguration DataConnectionInternal { get; } Property Value Type Description IConnectionConfiguration"
  },
  "api/ArgentSea.ShardDataStores-2.DataConnection.html": {
    "href": "api/ArgentSea.ShardDataStores-2.DataConnection.html",
    "title": "Class ShardDataStores<TShard, TConfiguration>.DataConnection | ArgentSea Docs",
    "keywords": "Class ShardDataStores<TShard, TConfiguration>.DataConnection Inheritance System.Object ShardDataStores<TShard, TConfiguration>.DataConnection Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class DataConnection Properties | Improve this Doc View Source ConnectionString Declaration public string ConnectionString { get; } Property Value Type Description System.String Methods | Improve this Doc View Source ListAsync<TResult>(String, DbParameterCollection, Int32, CancellationToken) Connect to the database and return the values as a list of objects. Declaration public Task<IList<TResult>> ListAsync<TResult>(string sprocName, DbParameterCollection parameters, int shardParameterOrdinal, CancellationToken cancellationToken) where TResult : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Int32 shardParameterOrdinal The ordinal position of a parameter that should be automatically set to the current shard number value. If there is no such parameter, set to -1. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task < System.Collections.Generic.IList <TResult>> A list containing an object for each data row. Type Parameters Name Description TResult The type of object to be listed. | Improve this Doc View Source ListAsync<TResult>(String, DbParameterCollection, CancellationToken) Connect to the database and return the values as a list of objects. Declaration public Task<IList<TResult>> ListAsync<TResult>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TResult : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task < System.Collections.Generic.IList <TResult>> A list containing an object for each data row. Type Parameters Name Description TResult The type of object to be listed. | Improve this Doc View Source LookupAsync<TValue>(String, DbParameterCollection, Int32, CancellationToken) Connect to the database and return a single value. Declaration public Task<TValue> LookupAsync<TValue>(string sprocName, DbParameterCollection parameters, int shardParameterOrdinal, CancellationToken cancellationToken) Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the value. System.Data.Common.DbParameterCollection parameters A parameters collction. Input parameters may be used to find the parameter; will return the value of the first output (or input/output) parameter. If TValue is an int, will also return the sproc return value. System.Int32 shardParameterOrdinal The ordinal position of a parameter that should be automatically set to the current shard number value. If there is no such parameter, set to -1. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TValue> The retrieved value. Type Parameters Name Description TValue The expected type of the return value. | Improve this Doc View Source LookupAsync<TValue>(String, DbParameterCollection, CancellationToken) Connect to the database and return a single value. Declaration public Task<TValue> LookupAsync<TValue>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the value. System.Data.Common.DbParameterCollection parameters A parameters collction. Input parameters may be used to find the parameter; will return the value of the first output (or input/output) parameter. If TValue is an int, will also return the sproc return value. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TValue> The retrieved value. Type Parameters Name Description TValue The expected type of the return value. | Improve this Doc View Source QueryAsync<TModel>(String, DbParameterCollection, QueryResultModelHandler<TShard, Object, TModel>, Boolean, CancellationToken) Declaration public Task<TModel> QueryAsync<TModel>(string sprocName, DbParameterCollection parameters, QueryResultModelHandler<TShard, object, TModel> resultHandler, bool isTopOne, CancellationToken cancellationToken) where TModel : class, new() Parameters Type Name Description System.String sprocName System.Data.Common.DbParameterCollection parameters QueryResultModelHandler <TShard, System.Object , TModel> resultHandler System.Boolean isTopOne System.Threading.CancellationToken cancellationToken Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel | Improve this Doc View Source QueryAsync<TModel>(String, DbParameterCollection, Int32, QueryResultModelHandler<TShard, Object, TModel>, Boolean, CancellationToken) Connect to the database and send the result to a custom handler for processing. Declaration public Task<TModel> QueryAsync<TModel>(string sprocName, DbParameterCollection parameters, int shardParameterOrdinal, QueryResultModelHandler<TShard, object, TModel> resultHandler, bool isTopOne, CancellationToken cancellationToken) where TModel : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Int32 shardParameterOrdinal The ordinal position of a parameter that should be automatically set to the current shard number value. If there is no such parameter, set to -1. QueryResultModelHandler <TShard, System.Object , TModel> resultHandler System.Boolean isTopOne If only one result is expected from the data ready, set to true. This is a mild optimization. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> The object created by the delegate handler. Type Parameters Name Description TModel This is the expected return type of the query. | Improve this Doc View Source QueryAsync<TModel>(String, DbParameterCollection, Int32, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding output parameters. Declaration public Task<TModel> QueryAsync<TModel>(string sprocName, DbParameterCollection parameters, int shardParameterOrdinal, CancellationToken cancellationToken) where TModel : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Int32 shardParameterOrdinal The ordinal position of a parameter that should be automatically set to the current shard number value. If there is no such parameter, set to -1. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel The type of the object to be returned. | Improve this Doc View Source QueryAsync<TModel>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding output parameters. Declaration public Task<TModel> QueryAsync<TModel>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel The type of the object to be returned. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TReaderResult7, TOutParameters>(String, DbParameterCollection, Int32, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TReaderResult7, TOutParameters>(string sprocName, DbParameterCollection parameters, int shardParameterOrdinal, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TReaderResult5 : class, new() where TReaderResult6 : class, new() where TReaderResult7 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Int32 shardParameterOrdinal The ordinal position of a parameter that should be automatically set to the current shard number value. If there is no such parameter, set to -1. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TReaderResult4 The fifth result set from data reader will be mapped an object or property of this type. TReaderResult5 The sixth result set from data reader will be mapped an object or property of this type. TReaderResult6 The seventh result set from data reader will be mapped an object or property of this type. TReaderResult7 The eighth result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TReaderResult7, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TReaderResult7, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TReaderResult5 : class, new() where TReaderResult6 : class, new() where TReaderResult7 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TReaderResult4 The fifth result set from data reader will be mapped an object or property of this type. TReaderResult5 The sixth result set from data reader will be mapped an object or property of this type. TReaderResult6 The seventh result set from data reader will be mapped an object or property of this type. TReaderResult7 The eighth result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TArg, TModel>(String, DbParameterCollection, QueryResultModelHandler<TShard, TArg, TModel>, Boolean, TArg, CancellationToken) Declaration public Task<TModel> QueryAsync<TArg, TModel>(string sprocName, DbParameterCollection parameters, QueryResultModelHandler<TShard, TArg, TModel> resultHandler, bool isTopOne, TArg optionalArgument, CancellationToken cancellationToken) where TModel : class, new() Parameters Type Name Description System.String sprocName System.Data.Common.DbParameterCollection parameters QueryResultModelHandler <TShard, TArg, TModel> resultHandler System.Boolean isTopOne TArg optionalArgument System.Threading.CancellationToken cancellationToken Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TArg TModel | Improve this Doc View Source QueryAsync<TArg, TModel>(String, DbParameterCollection, Int32, QueryResultModelHandler<TShard, TArg, TModel>, Boolean, TArg, CancellationToken) Declaration public Task<TModel> QueryAsync<TArg, TModel>(string sprocName, DbParameterCollection parameters, int shardParameterOrdinal, QueryResultModelHandler<TShard, TArg, TModel> resultHandler, bool isTopOne, TArg optionalArgument, CancellationToken cancellationToken) where TModel : class, new() Parameters Type Name Description System.String sprocName System.Data.Common.DbParameterCollection parameters System.Int32 shardParameterOrdinal QueryResultModelHandler <TShard, TArg, TModel> resultHandler System.Boolean isTopOne TArg optionalArgument System.Threading.CancellationToken cancellationToken Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TArg TModel | Improve this Doc View Source QueryAsync<TModel, TReaderResult, TOutParameters>(String, DbParameterCollection, Int32, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult, TOutParameters>(string sprocName, DbParameterCollection parameters, int shardParameterOrdinal, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Int32 shardParameterOrdinal The ordinal position of a parameter that should be automatically set to the current shard number value. If there is no such parameter, set to -1. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult The data reader result set will be mapped an object or property of this type. If TOutParmaters is set to Mapper.DummyType then this must be a single row result of type TModel. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult The data reader result set will be mapped an object or property of this type. If TOutParmaters is set to Mapper.DummyType then this must be a single row result of type TModel. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TOutParameters>(String, DbParameterCollection, Int32, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TOutParameters>(string sprocName, DbParameterCollection parameters, int shardParameterOrdinal, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Int32 shardParameterOrdinal The ordinal position of a parameter that should be automatically set to the current shard number value. If there is no such parameter, set to -1. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TOutParameters>(String, DbParameterCollection, Int32, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TOutParameters>(string sprocName, DbParameterCollection parameters, int shardParameterOrdinal, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Int32 shardParameterOrdinal The ordinal position of a parameter that should be automatically set to the current shard number value. If there is no such parameter, set to -1. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TOutParameters>(String, DbParameterCollection, Int32, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TOutParameters>(string sprocName, DbParameterCollection parameters, int shardParameterOrdinal, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Int32 shardParameterOrdinal The ordinal position of a parameter that should be automatically set to the current shard number value. If there is no such parameter, set to -1. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TReaderResult4 The fifth result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TReaderResult4 The fifth result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TOutParameters>(String, DbParameterCollection, Int32, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TOutParameters>(string sprocName, DbParameterCollection parameters, int shardParameterOrdinal, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TReaderResult5 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Int32 shardParameterOrdinal The ordinal position of a parameter that should be automatically set to the current shard number value. If there is no such parameter, set to -1. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TReaderResult4 The fifth result set from data reader will be mapped an object or property of this type. TReaderResult5 The sixth result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TReaderResult5 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TReaderResult4 The fifth result set from data reader will be mapped an object or property of this type. TReaderResult5 The sixth result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TOutParameters>(String, DbParameterCollection, Int32, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TOutParameters>(string sprocName, DbParameterCollection parameters, int shardParameterOrdinal, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TReaderResult5 : class, new() where TReaderResult6 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Int32 shardParameterOrdinal The ordinal position of a parameter that should be automatically set to the current shard number value. If there is no such parameter, set to -1. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TReaderResult4 The fifth result set from data reader will be mapped an object or property of this type. TReaderResult5 The sixth result set from data reader will be mapped an object or property of this type. TReaderResult6 The seventh result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TOutParameters>(String, DbParameterCollection, CancellationToken) Connect to the database and return an object of the specified type built from the corresponding data reader results and/or output parameters. Declaration public Task<TModel> QueryAsync<TModel, TReaderResult0, TReaderResult1, TReaderResult2, TReaderResult3, TReaderResult4, TReaderResult5, TReaderResult6, TOutParameters>(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) where TModel : class, new() where TReaderResult0 : class, new() where TReaderResult1 : class, new() where TReaderResult2 : class, new() where TReaderResult3 : class, new() where TReaderResult4 : class, new() where TReaderResult5 : class, new() where TReaderResult6 : class, new() where TOutParameters : class, new() Parameters Type Name Description System.String sprocName The stored procedure to call to fetch the data. System.Data.Common.DbParameterCollection parameters The query parameters. System.Threading.CancellationToken cancellationToken A token to cancel the asynchronous operation. Returns Type Description System.Threading.Tasks.Task <TModel> Type Parameters Name Description TModel This is the expected return type of the query. TReaderResult0 The first result set from data reader will be mapped an object or property of this type. TReaderResult1 The second result set from data reader will be mapped an object or property of this type.. TReaderResult2 The third result set from data reader will be mapped an object or property of this type. TReaderResult3 The forth result set from data reader will be mapped an object or property of this type. TReaderResult4 The fifth result set from data reader will be mapped an object or property of this type. TReaderResult5 The sixth result set from data reader will be mapped an object or property of this type. TReaderResult6 The seventh result set from data reader will be mapped an object or property of this type. TOutParameters This must be either type TModel or Mapper.DummyType. If set to TModel the TModel properties will be mapped to cooresponding output parameters; if set to DummyType, the output parameters are ignored. | Improve this Doc View Source RunAsync(String, DbParameterCollection, Int32, CancellationToken) Declaration public Task RunAsync(string sprocName, DbParameterCollection parameters, int shardParameterOrdinal, CancellationToken cancellationToken) Parameters Type Name Description System.String sprocName System.Data.Common.DbParameterCollection parameters System.Int32 shardParameterOrdinal System.Threading.CancellationToken cancellationToken Returns Type Description System.Threading.Tasks.Task | Improve this Doc View Source RunAsync(String, DbParameterCollection, CancellationToken) Declaration public Task RunAsync(string sprocName, DbParameterCollection parameters, CancellationToken cancellationToken) Parameters Type Name Description System.String sprocName System.Data.Common.DbParameterCollection parameters System.Threading.CancellationToken cancellationToken Returns Type Description System.Threading.Tasks.Task"
  },
  "tutorials/Configuration/resilience.html": {
    "href": "tutorials/Configuration/resilience.html",
    "title": "Resilience Strategies | ArgentSea Docs",
    "keywords": "Resilience Strategies Unexpected failures happen, and business-critical applications must be able to recover gracefully. ArgentSea uses Polly to offer a combination of retry logic and circuit breaking. The properties specific to a resilience strategy are: { \"CircuitBreakerFailureCount\": 20, \"CircuitBreakerTestInterval\": 5000, \"ConnectTimeout\": 5, \"RetryCount\": 6, \"RetryInterval\": 256, \"RetryLengthening\": \"Fibonacci\", } If no retry or circuit breaking properties are configured, ArgentSea uses a default resilience strategy using automatic retries and circuit breaking. Like everything else, these values participate in the ArgentSea Hereditary Configuration Hierarchy — you can set these values globally (most likely) or at any level down to the individual Read or Write connection. Retries Retries occur on errors that are defined as transient . A network interruption may quickly resolve itself, so it makes sense to retry after a short interval; it doesn’t make sense to retry after a permission exception. (The list of errors defined as transient is in the provider-specific implementation of IDataProviderServiceFactory. You can view this in the source code). The properties that define the retry behavior are: The RetryCount setting determines how many times the connection retries before aborting and raising an error back to the caller. The RetryInterval determines the length of time (in milliseconds) between retries. The RetryLengthening value can add an additional pause between subsequent retries. Presumably, if the system encounters a transient error, it should retry quickly, then, if the retry is not successful, it should wait a bit longer for the error to clear before retrying again. The RetryLengthening value is what determines how much longer it will pause on subsequent retries before giving up. The Retry Sequence Lengthening values are: Linear - each retry is the same duration as specified in RetryInterval Fibonacci - The first retry is at RetryInterval , each subsequent retry interval pauses for the duration of the previous two combined. HalfSquare - the retry count number is squared, then divided by two, then multiplied by RetryInterval Squaring - each retry attempt doubles the duration of the previous one. You can visualize the impact of RetryLengthening with these charts: If a Resilience Strategy is not defined, ArgentSea will use a default strategy. Currently, this is: Setting Default Value RetryCount 6 tries RetryInterval 256 milliseconds Lengthening Fibonacci (Connect) Timeout 5 Note SQL Server’s ADO.NET provider also offers automatic retries. ArgentSea disables this in lieu of its own functionality, which logs these automatic retries. This valuable environment diagnostic information should not be invisible. Connection Timeout The connection timeout value is critical to determining the duration of connection attempts before failure. The ADO.NET default of 15 seconds is far too long, so the ArgentSea default is 2 seconds. Datacenter connections are generally resolved in that time unless something is wrong. If you have a WAN or high-latency connection, you should consider increasing this value. It is not guaranteed that any defaults will remain unchanged in future versions. Note that a high RetryCount and/or connection timeout could create a very long delay before a connection is allowed to ultimately fail. Circuit Breaking When a database connection is unavailable, this can cause serious downstream problems. Processes may pile-on further requests even while earlier requests are simply waiting to time out. As this continues, the queue of backlogged requests becomes so large that the caller itself can manage no more. The bottleneck will then start blocking other systems too. What started as a broken connection to a single database eventually becomes fatal to the entire system! This is the reason to add a “circuit breaker” — a fail-fast mechanism to ensure that callers do not wait needlessly for queued connections that are unlikely to succeed, and which are blocking other processes too. Once the circuit breaker is tripped, subsequent connections will fail immediately . This prevents queuing, bottleneck blocking, and downstream failures. While tripped, the circuit breaker will periodically allow a single transaction to proceed; if it successful the circuit breaker is reopened. In this way, a system restoration will automatically close the circuit breaker too so that connections can resume. The CircuitBreakerFailureCount value determines how many sequential failures will trigger the circuit breaker. The CircuitBreakerTestInterval value determines how often (in milliseconds) the circuit breaker will allow a single transaction through. Data Failover for High-Availability and Disaster Recovery ArgentSea itself does not currently include specific functionality that enables an automatic failover to a standby database server. This is not to say that high-availability or disaster-recovery solutions cannot be used, only that ArgentSea is not opinionated about whatever approach you choose. Often, failover is managed through DNS changes or via configuration of the .NET data provider (such as the FailoverPartner property), which may not even require client connection string changes. It would be difficult to build a robust strategy that predictably worked well with the variations of approaches possible. Furthermore, business continuity plans typically do not expect disaster recovery plans to be fully “automatic” at the individual client level; a lot of infrastructure must be coordinated in a robust failover, and a rogue client should not failover without a coordinated signal. Consequently, ArgentSea makes it possible to easily build failover capability, but does not natively offer this. All of the connection properties in the configuration hierarchy are updatable. This allows you to build failover logic that updates the connection information — server endpoints, database names, etc. — given whatever trigger you prefer. Note Once created, both the ShardSets and Databases singleton collections themselves are immutable, although any connection property in the configuration hierarchy can still be updated. In other words, after the Hereditary Configuration Hierarchy is created, you cannot change the layout of the hierarchy, but the connection properties of the members can still be changed and will update the client connections. Child objects will also continue to inherit any updates from their parents. Of course, updating connection properties is not fully thread-safe, but it will not impact queries that have already started. The configuration objects are .NET Options classes, which are obtained through an IOptions<> injection. One possible point of confusion is that the you reference objects in the ShardSets and Databases collections by their (string) key; however, the Options objects themselves originate as arrays that reflect your configuration layout. You must use an integer index to reference a shard set or connection. The value of this index depends on the order in your configuration files and the order in which they are loaded. In other words, you can verify the configuration options object by checking the key property, but you cannot use the key as an indexer. Next: Loading the Configuration"
  },
  "tutorials/quickstarts/sharding.html": {
    "href": "tutorials/quickstarts/sharding.html",
    "title": "QuickStart Two | ArgentSea Docs",
    "keywords": "QuickStart Two The previous QuickStart introduced configuration and mapping. This tutorial extends that information while working with a sharded data set. This tutorial also extends the mapping functionality to include list and object properties on the model class. Sharded data introduces two complexities: How do I uniquely identify and locate a record, which might be on any shard? How do I manage data on one shard and related data on a foreign shard? This walkthrough illustrates how both challenges can be met. Create the Project If you are following along at home with a new project, in Visual Studio create a new “ASP.NET Core Web Application” project. When prompted, select the “API” project type. Once the solution is created, open your dependencies and add the following NuGet packages: ArgentSea.Sql or ArgentSea.Pg - for SQL Sever or PostgreSQL databases respectively Swashbuckle.Aspnetcore - for Swagger and for invoking the API without creating a client To follow a standard convention for an MVC project, create folders for Models , InputModels , and Stores (or “Repositories” if you prefer). The Sample Data Whether you simply downloaded the walkthrough or a creating a new project, you will need to create some sample shards. Our sample application is going to track Customers . The data set is completely made-up and not especially realistic. Customers can have multiple Locations (1:∞). Customers can also have Contacts , but the Contacts can belong to more than one Customer (∞:∞). The Contact may not exist in the same shard as the Customer . Note The data is set up this way to illustrate one of the difficulties with sharded data: managing relationships between records that exist on different shards. In this case, a Customer may be associated with a Contact on any shard. Managing this — an managing this efficiently — adds substantial complexity. In our sample model, the ∞:∞ relationship between a Contact and a Customer is managed by a linking table, CustomerContacts . Given the id of a local Customer , the table lists the keys of the associated Contacts . What happens if instead I have the id of a Contact and want to find all of the Customers ? With only that table, it would be necessary to query every shard to determine whether they have a related Customer ! To better optimize this, the data model creates a second ContactCustomers linking table. With this approach, if I have a Contact and want to find Customers (including those in foreign shards), or Customers and want to find Contacts (again, even those not local), I can use the appropriate linking table and query only the shards with relevant records data. The downside is that when the Customer and Contact are on different shards, this relationship must be managed in different tables on different databases. In a real implementation, it might be beneficial to include additional information in the linking tables, like including the contact name within the CustomerContact table for example, so that common lookups do not require secondary lookups from related shards just to get the contact name. The QuickStart example doesn’t do this so that it can illustrate performing these secondary lookups. Naturally, deleting a Customer means removing the ContactCustomers link from each Contact also, which could be on any shard. This shard list must be retrieved from the CustomerContacts list before it is deleted. Updating a Customer’s Contacts could also impact multiple shards in two ways: a removed foreign-shard Contact must be deleted and a additional foreign-shard Contacts must be added. SQL Server PostgreSQL The SQL for the sample data is found in the GitHub source repository, at https://github.com/argentsea/quickstarts/tree/master/QuickStart2.Sql/QuickStart2.Sql/SqlSetup . The first SQL script to execute is ServerSetup.sql , which creates four databases and two logins. Caution The logins contain weak passwords (that are published on the Internet), so you might consider changing them; on the other hand, these will only have permission to execute procedures or functions in a specific namespace, so it’s not a big risk. Note Conceptually, these four databases would correspond to regional data stores in the United States , Brazil , Europe , and China . In my real global application I would replicate the data from each region to each other region. Therefore, each region would have one writable data store and three readable ones. In this way, the “local” shard is writeable, the “foreign” shards are read-only. Writes to a foreign shard must be done across the WAN. Your implementation may vary. Our walkthrough, however, only needs four simple databases on one server. We’ll only imagine the rest. Next, after the databases have been created, connect to each database in turn and run the ShardSetup.sql SQL script. This will created the schemas, tables, stored procedures, reference data, etc. for our sample databases. Finally, run the shard-specific SQL scripts — ShardUS.sql , ShardBR.sql , ShardUS.sql , ShardUS.sql — within their respective databases. This will load the shard-specific sample data. The SQL for the sample data is found in the GitHub source repository, at https://github.com/argentsea/quickstarts/tree/master/QuickStart2.Pg/QuickStart2.Pg/SqlSetup . Create four PostgreSQL databases: customershard_br customershard_eu customershard_us customershard_zh Note Conceptually, these four databases would correspond to regional data stores in the United States , Brazil , Europe , and China . In my real global application I would replicate the data from each region to each other region. Therefore, each region would have one writable data store and three readable ones. In this way, the “local” shard is writeable, the “foreign” shards are read-only. Writes to a foreign shard must be done across the WAN. Your implementation may vary. Our walkthrough, however, only needs four simple databases on one server. We’ll only imagine the rest. After the databases have been created, connect to each database in turn and run the ShardSetup.sql SQL script. This will create the schemas, tables, stored procedures, reference data, etc. for our sample databases. Caution The database setup create users with weak passwords (that are also published on the Internet), so you might consider changing them. Finally, run the shard-specific SQL scripts — ShardUS.sql , ShardBR.sql , ShardUS.sql , ShardUS.sql — within their respective databases. This will load the shard-specific sample data. At this point, we should have four database with identical table structures. SQL Server instances should also have a identical set of stored procedures. The Shard Set Record Key Each of the four databases needs an identifier. ArgentSea uses a short (Int32/tinyint) to identify each shard, and a generic type as a record id. The combination of shard id and record id becomes a “virtual compound key”, which is called a ShardKey . A thorough discussion of the options and impact is here . Some tables may require a compound key themselves. For these, ArgentSea offers ShardKeys with generic overloads, which may consist of a shard id, record id, child id, grandchild id, and even great grandchild id! Because all the the record and child id types are generic, they can accommodate most data column types. Configuring Connections Because sharded data may require a large number of data connections, ArgentSea offers a more flexible way of managing this than by using connection strings. ArgentSea offers the “Hereditary Configuration Hierarchy”. This allows you to set an attribute at the parent level and all children will inherit this value, unless overwritten by a child. A more thorough discussion is here . In our sample application, we can use the same server or host for all connections; each shard connection only changes the database name. (In a production deployment, the configuration might be exactly backwards: the databases have identical names, but each is on a different host). We also want to use the webWriter user for write connections and webReader for read connections. So the configuration settings looks like this (with annotations): SQL Server PostgreSQL { \"SqlShardSets\": [¹ { \"ShardSetName\": \"Customers\",² \"DataSource\": \".\",³ \"DefaultShardId\": 1,⁴ \"Write\": {⁵ \"UserName\": \"webWriter\", \"Password\": \"Pwd567890\", }, \"Read\": {⁵ \"ApplicationIntent\": \"ReadOnly\", \"UserName\": \"webReader\", \"Password\": \"Pwd123456\" }, \"Shards\": [⁶ { \"ShardId\": 1,⁷ \"InitialCatalog\": \"CustomerShardUS\"⁸ }, { \"ShardId\": 2,⁷ \"InitialCatalog\": \"CustomerShardEU\"⁸ }, { \"ShardId\": 3,⁷ \"InitialCatalog\": \"CustomerShardBR\"⁸ }, { \"ShardId\": 4,⁷ \"InitialCatalog\": \"CustomerShardZH\"⁸ } ] } ] } Annotations ¹ SqlShardSets is the root JSON section for all the shard configuration metadata. It contains an array of shard sets. ² ShardSetName is a required key for this specific shard set. Multiple shard sets are possible and each will be identified by this key. This value must exactly match the value used in your code to invoke this shard set. ³ DataSourceName is a connection attribute. Connection attributes can appear anywhere in the hierarchy. Because it appears at the “shard set” level, all shards in the shard set will inherit this server name. ⁴ DefaultShardId this setting determins which shard is presented as the ShardSet.DefaultShard . This is useful for determining which shard should be actively accepting new records for this client. ⁵ Read and Write are peculiar, and optional, members of shard set’s “inheritance” chain, as their children are indirect. Any attributes defined in the shard set’s Write section apply only to write connections. Likewise, for Read connections. These values can be overwritten by shard or connection attributes. ⁶ Shards is an array of shard connections, one for each shard in the shard set. ⁷ ShardId is a required identifier for the shard. This value is essential for finding and identifying a sharded record. It cannot be duplicated within a shard set. The value must be a number. ⁸ InitialCatalog is a connection attribute. Because it appears at the shard level, both read connections and write connections for this shard will inherit this value. { \"PgShardSets\": [¹ { \"ShardSetName\": \"Customers\",² \"DefaultShardId\": 1,⁴ \"Host\": \"localhost\",³ \"Write\": {⁵ \"UserName\": \"webWriter\", \"Password\": \"Pwd567890\" }, \"Read\": {⁵ \"UserName\": \"webReader\", \"Password\": \"Pwd123456\" }, \"Shards\": [⁶ { \"ShardId\": 1,⁷ \"Database\": \"CustomerShardUS\"⁸ }, { \"ShardId\": 2,⁷ \"Database\": \"CustomerShardEU\"⁸ }, { \"ShardId\": 3,⁷ \"Database\": \"CustomerShardBR\"⁸ }, { \"ShardId\": 4,⁷ \"Database\": \"CustomerShardZH\"⁸ } ] } ] } Annotations ¹ PgShardSets is the root JSON section for all the shard configuration metadata. It contains an array of shard sets. ² ShardSetName is a required key for this specific shard set. Multiple shard sets are possible and each will be identified by this key. This value must exactly match the value used in your code to invoke this shard set. ³ Host is a connection attribute. Connection attributes can appear anywhere in the hierarchy. Because it appears at the “shard set” level, all shards in the shard set will inherit this server name. ⁴ DefaultShardId this setting determins which shard is presented as the ShardSet.DefaultShard . This is useful for determining which shard should be actively accepting new records for this client. ⁵ Read and Write are peculiar, and optional, members of shard set’s “inheritance” chain, as their children are indirect. Any attributes defined in the shard set’s Write section apply only to write connections. Likewise, for Read connections. These values can be overwritten by shard or connection attributes. ⁶ Shards is an array of shard connections, one for each shard in the shard set. ⁷ ShardId is a required identifier for the shard. This value is essential for finding and identifying a sharded record. It cannot be duplicated within a shard set. The value must be a number. ⁸ Database is a connection attribute. Because it appears at the shard level, both read connections and write connections for this shard will inherit this value. This hierarchy, then, defines a server name once, to be used for the entire shard set. The read and write logins are also defined once, to be used by all read or write connections in the shard set. Each shard has a distinct database name. ArgentSea can build read and write connections to each data store without the need to configure any of this data redundantly — the login, server name, and database names are each managed only once. When you save this configuration to project’s appsettings file, be sure to update the JSON to the appropriate server references. You might consider moving the login password information to the UserSecrets store, which is a best practice. Simply remove the password entries from the appsettings.json hierarchy and add them to the usersecrets.json file. Ideally, the password should also be changed to a different value. SQL Server PostgreSQL User Secrets Entry { \"SqlShardSets\": [ { \"Write\": { \"Password\": \"Pwd567890\", }, \"Read\": { \"Password\": \"Pwd123456\" } } ] } User Secrets Entry { \"PgShardSets\": [ { \"Write\": { \"Password\": \"Pwd567890\", }, \"Read\": { \"Password\": \"Pwd123456\" } } ] } Warning The configuration arrays in appsettings.json and usersecrets.json will not match if they do not appear in exactly the same order. In this sample, we have only one shard set and the passwords are not in the Shards array, so this is not a concern. Creating the Models The process of creating a model class was introduced in Quickstart 1 . Essentially, it simply requires adding attributes to properties, which the Mapper can then use. This QuickStart adds four new wrinkles: shard keys, object properties, list properties, and inheritance. The complete code is on GitHub, at https://github.com/argentsea/quickstarts/tree/master/QuickStart2.Sql/QuickStart2.Sql for SQL Server, or https://github.com/argentsea/quickstarts/tree/master/QuickStart2.Pg/QuickStart2.Pg for PostgreSQL. The classes and SQL you need are located there; it is not fully reproduced here. SQL Server PostgreSQL To use the attributes, each Model class should include a using ArgentSea.Sql statement. using ArgentSea.Sql; To use the attributes, each Model class should include a using ArgentSea.Pg; statement. using ArgentSea.Pg; Advanced Model Mapping The previous walthrough demonstrated mapping to standard .NET types like strings, numbers, and dates. This walkthrough illustrates mapping to objects, lists, and child classes. Properties with Object Types Our data contains Location data with latitude and longitude values. Generally, these are usually managed as a value pair. Geographic functions would likely expect a single geographic coordinates argument, rather than the two separate values. It would be handy to map data directly to/from a coordinates class, which would be a property of the Location class. That is exactly what the MapToModel attribute does. This attribute tells the mapper that the property is a child object that also has properties to be included in the mapping. SQL Server PostgreSQL // The coordinates class: public class CoordinatesModel { [MapToSqlFloat(\"Latitude\")] public double Latitude { get; set; } [MapToSqlFloat(\"Longitude\")] public double Longitude { get; set; } } // The location, which contains the coordinates class as a property: public class LocationModel { //include other properties here... [MapToModel] public CoordinatesModel Coordinates { get; set; } } // The coordinates class: public class CoordinatesModel { [MapToPgDouble(\"latitude\")] public double Latitude { get; set; } [MapToPgDouble(\"longitude\")] public double Longitude { get; set; } } // The location, which contains the coordinates class as a property: public class LocationModel { //include other properties here... [MapToModel] public CoordinatesModel Coordinates { get; set; } } If the Coordinates property is null, the Mapper will instantiate an instance before setting the properties. Of course, the CoordinatesModel must have a default constructor and the property must be settable. If you want to make the property read-only, just make sure that the Coordinates object exists: [MapToModel] public CoordinatesModel Coordinates { get; } = new CoordinatesModel(); Properties with List Types One of the most expensive activities an application can do is reach out to another server. Our high-performance application should do everything possible to minimize database server round-trips. This means getting all the data necessary to populate our Customer model in a single request. The ArgentSea Mapper can automatically handle multiple results from a single request. Our Customer can have any number of Locations . Our Customer can also have any number of Contacts . Our query returns the Customer , Location and Contact information in a single round-trip. SQL Server PostgreSQL Tip The base Customer record could be returned in either output parameters or in a single-row SELECT result. The first would use the Mapper’s MapOutput method, the other requires the MapReader method; both would use the data reader to handle list properties. To map the multiple data reader results to the Model, we tell the Mapper the order of the results when we fetch: var prms = new QueryParameterCollection() .AddSqlIntInputParameter(\"@CustomerId\", customerKey.RecordId) .CreateOutputParameters<CustomerModel>(_logger); return await _shardSet[customerKey].Read.MapOutputAsync<CustomerModel, LocationModel, ContactModel>(Queries.CustomerGet, prms, cancellation); The CustomerModel type in the first generic position tells the Mapper that that is the base object type. The Mapper will automatically create a new instance of the CustomerModel type and populate its properties from the query’s output parameters. The LocationModel type in the next generic position indicates that the first data reader result contains this type. The Mapper will build a list of locations, find a property of type List<LocationModel> or IList<LocationModel> , and set the property to the list object. Likewise, the third generic argument tells the Mapper that the next data reader result is a list of Contacts , which the Mapper will use to populate the Contacts property. To map the multiple data reader results to the Model, we tell the Mapper the order of the results when we fetch: var prms = new ParameterCollection() .AddPgIntegerInputParameter(\"customerid\", customerKey.RecordId); return await _shardSet[customerKey].Read.MapReaderAsync<CustomerModel, CustomerModel, LocationModel, ContactModel>(Queries.CustomerGet, prms, cancellation); Warning Although you can also capture database results using output parameters by using MapOutputAsync , this is not recommended. Unlike SQL Server, there is no performance benefit with this approach and this will error if multiple SQL statements are used in the query. The CustomerModel type in the first generic position tells the Mapper that that is the base object type. The remaining generic arguments inform the mapper of the order in the query results. Because our customer data is returned in the first result, the CustomerModel appears again in the second position of the generic argument list. The LocationModel type in the third generic position indicates that the second data reader result contains this type. The Mapper will build a list of locations, find a property of type List<LocationModel> or IList<LocationModel> , and set the property to the list object. Likewise, the forth generic argument tells the Mapper that the third data reader result is a list of Contacts , which the Mapper will used to populate the Contacts property. Only a few lines of code are all that is required to manage this complex result. Model Inheritance The sample application has a CustomerListItem Model, which contains a record key and a customer name property. The CustomerModel include those same values, plus some others. By inheriting from first Model, the CustomerModel inherits the key and an customer name, including their mapping attributes. Because database queries often return subsets of entity columns, this object inheritance technique is useful in allowing the mapping attributes to be defined only once. The ShardKey The final object type which may combine multiple data records is the ShardKey type. This type is described in detail here . SQL Server PostgreSQL [MapShardKey('c', \"@CustomerId\")] [MapToSqlInt(\"@CustomerId\")] public ShardKey<int> CustomerKey { get; set; } [MapShardKey('c', \"customerid\")] [MapToPgInteger(\"customerid\")] public ShardKey<int> CustomerKey { get; set; } Note The ShardKey in this example does not specify a ShardId data mapping. Because the client knows the ShardId, ArgentSea will populate the ShardId value from this configuration data. If you provide a ShardId mapping (and include the shardid argument in the MapShardKey attribute), ArgentSea will understand that you want to use the data value instead. The ShardKey type supports table compound keys in your sharded data. In this sample application, the Customer Location records are identified by a compound key including both a CustomerId and LocationId. SQL Server PostgreSQL [MapShardKey('L', \"CustomerId\", \"LocationId\")] [MapToSqlInt(\"CustomerId\")] [MapToSqlSmallInt(\"LocationId\")] public ShardKey<int, int> CustomerLocationKey { get; set; } [MapShardKey'L', \"customerid\", \"locationid\")] [MapToPgInteger(\"customerid\")] [MapToPgSmallint(\"locationid\")] public ShardKey<int, int> CustomerLocationKey { get; set; } It would be possible for ArgentSea to include a “ShardGrandChild” struct, for three-column compound keys, (or even a “ShardGreatGrandChild”) but the need for this hasn’t arisen. Loading the Shard Service Loading and injecting the ArgentSea ShardSets service is identical to the Databases services explained in the last tutorial. SQL Server PostgreSQL Calling the ArgentSea AddSqlService extension method will load both the ArgentSea sharding and database services. using ArgentSea.Sql; ... public void ConfigureServices(IServiceCollection services) { ... services.AddSqlServices(this.Configuration); ... } Calling the ArgentSea AddPgService extension method will load both the ArgentSea sharding and database services. using ArgentSea.Pg; ... public void ConfigureServices(IServiceCollection services) { ... services.AddPgServices(this.Configuration); } Note The ShardSets services implicitly loads the Databases service also. Of course, if no databases are configured, the collection will be empty. Queries and Data Our implementation adds two static classes which help describe our data. The first is a simple list of constants, which correspond to the “origin” parameter of ShardKey object. the “Origin” helps prevent accidental use of, say, an Inventory key to delete an Order record. By using constants, you cam more explicitly distinguish the “c” used for Contact data from the “C” used for Customer data, which might otherwise be confusing. The second static class consolodates query definitions, as described in the Creating SQL Queries tutorial. This serves two purposes: first, it becomes easy to determine which queries are actually used by the code (on large projects, this can be difficult). Also, the optional parameter list can limit the parameters that are set when Model attributes have more parameters than the query requires. The code for these are in the DataOrigins and Queries classes respectively. The code is self explainitory. The Repository Pattern Our sample code uses a CustomerStore class, which implements all of the actual data access logic. The theory of the repository pattern is help contain the coupling between the data layer and application logic. We could theorectically replace the data store by only changing the CustomerStore implementation. Because this is a web service that provides data access, the virtue of this approach is not compelling in our sample. Your milage may vary. Because our web service does very little except read and write data, there is actually very little for the controller to do. You will find nearly all of the ArgentSea implemetation in the CustomerStore class. Note The code in the CustomerStore would have been even simpler if there was no relationship between Customers and Contacts . The sample is intended to illustrate handling a challenging sharding scenario, but without this relationship the code would have been half as long. This class is injected into the controller, so it need to be a registered as a service at startup. services.AddTransient<Stores.CustomerStore>(); The injectable CustomerStore class in turn uses the injected ShardSets service. Obtaining the injectible ShardSets service in your repository class is straightforward: public class CustomerStore { private readonly ShardSets.ShardSet _shardSet; private readonly ILogger<CustomerStore> _logger; public CustomerStore(ShardSets shardSets, ILogger<CustomerStore> logger) { _shardSet = shardSets[\"Customers\"]; _logger = logger; } .... If you elected to use the ArgentSea shard sets collection instead, things are just a little more verbose: SQL Server PostgreSQL public class CustomerStore { private readonly SqlShardSets<byte>.ShardSet _shardSet; private readonly ILogger<CustomerStore> _logger; public CustomerStore(SqlShardSets<byte> shardSets, ILogger<CustomerStore> logger) { _shardSet = shardSets[\"Customers\"]; _logger = logger; } .... public class CustomerStore { private readonly PgShardSets<short>.ShardSet _shardSet; private readonly ILogger<CustomerStore> _logger; public CustomerStore(PgShardSets<short> shardSets, ILogger<CustomerStore> logger) { _shardSet = shardSets[\"Customers\"]; _logger = logger; } .... Using a ShardSet instance, you generally simply provide a query, set parameters, and invoke a method. You can query across all shards, some shards, or within a single shard instance. Querying across all or some shards can return all results in a unified list or the first valid result. The code necessary to query all shards is very simple: SQL Server PostgreSQL public async Task<CustomerModel> FindByLogonName(string loginName, CancellationToken cancellation) { var prms = new ParameterCollection() .AddSqlNVarCharInputParameter(\"@LoginName\", loginName, 255) .CreateOutputParameters<CustomerModel>(_logger); return await _shardSet.ReadFirst.MapOutputAsync<CustomerModel, LocationModel, ContactListItem>(Queries.CustomerFind, prms, cancellation); } ```csharp public async Task<CustomerModel> FindByLogonName(string loginName, CancellationToken cancellation) { var prms = new ParameterCollection() .AddPgVarcharInputParameter(\"loginname\", loginName, 255) .CreateOutputParameters<CustomerModel>(_logger); return await _shardSet.ReadFirst.MapOutputAsync<CustomerModel, LocationModel, ContactListItem>(Queries.CustomerFind, prms, cancellation); } Optimizing Multi-Record Saves The principal means of optimizing data access is to limit the number of round-trips to the database server . If the need to save ten records generates ten distinct calls to the database, the solution will not be very efficient. Unfortuantely, there is no standard way of handling multi-record saves; fortunately, there are platform-specific ways of managing it. SQL Server PostgreSQL SQL Server uses Table Valued Parameters to save multiple records. Our sample data saves a Customer with multiple Locations and multiple Contacts . These are both passed to Table Valued Parameters. This also allows the related records to be managed in a single internally-managed (low oeverhead) transaction. Table Valued Parameters require a “User Defined Type”, which defines the column names and types for each row. ArgentSea offers a SQL Server-specific Mapper which converts the metadata attrributes to the correct format for this paramteter. (Like its siblings, it also uses expression trees to to compile a high-performance solution when it is initially run). In our sample implementation, the combined mapping attributes created more columns than the User Defined Type required. To solve this, we can simply provide a list or array of names; then, only those are used. var prms = new ParameterCollection() .CreateInputParameters(customer, _logger) .AddSqlTableValuedParameter(\"@Locations\", customer.Locations, customerLocationTypeColumns, _logger) .AddSqlTableValuedParameter<ContactListItem, byte, int>(\"@Contacts\", customer.Contacts, \"ShardId\", System.Data.SqlDbType.TinyInt, \"RecordId\", System.Data.SqlDbType.Int); In this example, there are two AddSqlTableValuedParameter overloads, the first uses a Model and maps to the Unser Defined Type using mapping attributes; the second example maps only the key values, using the column names supplied. You can learn more in the section on Multi-Record Saves . PostgreSQL uses the COPY statement to quickly load multiple rows into tables or temporary tables. Once these records are loaded, a SQL statement can be run to process them further. This process uses ArgentSea’s Batch functionality, which allows multiple steps to execute within a single open and transacted connection. In our sample, the first two steps load the Contacts and Locations data into temporary tables, then the third batch steps runs a SQL statement to save this data. If the table name has a “.” schema seperater, then the target is assumed to a a standard table; without a “.” in the table name, the table is understood to be a temporary table. If the table does not exist it will be created (unless, of course, the client does not have permission to create a table). The table will have all of the coloumns defined by the model’s metadata attributes. var customerPrms = new ParameterCollection() .CreateInputParameters<CustomerModel>(customer, _logger); var shardBatch = new ShardBatch<short, List<short>>() .Add(customer.Contacts, \"temp_contacts\") .Add(customer.Locations, \"temp_locations\") .Add(Queries.CustomerSave, customerPrms, \"contactshardid\"); Using Swagger when you launch the web API project, it will open to thw Swagger UI by default. If you are creating a new project, open project properties, go to the Debug tab, then change the Launch browser: text value to “swagger”. The first GET method returns all customers, across all shards (you don't want to do this in the real world). You can selected any ShardKey in the resulting list and provide that to the other GET method, which takes a ShardKey string argument. This methods returns a complex JSON result with extended customer detail. You can edit the customer detail and provide that to the PATCH method to update the database values. The POST method allows you to create a new customer. If successful, it returns the ShardKey of the created record. To create a new customer you can provide the following JSON: { \"name\": \"New Customer\", \"type\": \"WalkIn\", \"locations\": [ { \"type\": \"RetailStore\", \"streetAddress\": \"123 Main Street\", \"locality\": \"Chicago\", \"region\": \"IL\", \"postalCode\": \"60612\", \"iso3166\": \"us\", \"coordinates\": { \"latitude\": 41.867789, \"longitude\": -87.675839 } }, { \"type\": \"RetailStore\", \"streetAddress\": \"456 Oak Avenue\", \"locality\": \"Dallas\", \"region\": \"TX\", \"postalCode\": \"75211\", \"iso3166\": \"us\", \"coordinates\": { \"latitude\": 32.730430, \"longitude\": -87.675839 } } ], \"contacts\": [ { \"origin\": \"c\", \"shardId\": 1, \"recordId\": 7 }, { \"origin\": \"c\", \"shardId\": 2, \"recordId\": 4 }, { \"origin\": \"c\", \"shardId\": 1, \"recordId\": 8 } ] } Finally, you can DELETE a customer by providing a ShardKey."
  },
  "api/ArgentSea.QueryResultModelHandler-3.html": {
    "href": "api/ArgentSea.QueryResultModelHandler-3.html",
    "title": "Delegate QueryResultModelHandler<TShard, TArg, TModel> | ArgentSea Docs",
    "keywords": "Delegate QueryResultModelHandler<TShard, TArg, TModel> This delegate will be invoked for each shard (probably on different threads) to convert the cmd.Execute result to model types. Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public delegate TModel QueryResultModelHandler<TShard, TArg, TModel>(TShard shardId, string sprocName, TArg optionalArgument, DbDataReader rdr, DbParameterCollection parameters, string connectionDescription, ILogger logger) where TShard : IComparable where TModel : class, new(); Parameters Type Name Description TShard shardId The value of the Shard Number. System.String sprocName Used to uniquely identify any cached Expression Trees (along with TModel type) and also included in any logging information. TArg optionalArgument System.Data.Common.DbDataReader rdr A data reader instance supplied by the data provider when a query is executed. System.Data.Common.DbParameterCollection parameters An output parameter set supplied by the data provider when a query is executed. System.String connectionDescription Provides any logging writes with connection information to help troubleshoot any errors. Microsoft.Extensions.Logging.ILogger logger A logger instance for writing logs. Returns Type Description TModel An object of the defined type. Type Parameters Name Description TShard The Type of the ShardId. TArg The Type of an optional parameter that can be passed to the parsing function. If not used, simply use Type \"object\" and pass null if required. TModel"
  },
  "api/ArgentSea.StringExtensions.html": {
    "href": "api/ArgentSea.StringExtensions.html",
    "title": "Class StringExtensions | ArgentSea Docs",
    "keywords": "Class StringExtensions This static class contains extension methods for cleaning input strings of invalid characters. It does NOT sanitize input strings for protection against injection attacks (your parmemeterized queries should protect against that). Inheritance System.Object StringExtensions Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public static class StringExtensions Methods | Improve this Doc View Source CleanInput(String) Removes leading/trailing whitespace, control charactors (cr, lf, tab, etc.), and emojis from input string. Declaration public static string CleanInput(this string value) Parameters Type Name Description System.String value Input string, resumably provided by user. Returns Type Description System.String Input string with undesired characters removed. | Improve this Doc View Source CleanInput(String, StringExtensions.InputCleaningOptions) Declaration public static string CleanInput(this string value, StringExtensions.InputCleaningOptions flags) Parameters Type Name Description System.String value StringExtensions.InputCleaningOptions flags Returns Type Description System.String"
  },
  "tutorials/Sharding/sharding.html": {
    "href": "tutorials/Sharding/sharding.html",
    "title": "Sharding | ArgentSea Docs",
    "keywords": "Sharding About Sharding Sharding is the technique of spreading your data across multiple database servers. It is difficult to add sharding to an existing application because it requires careful thought about the data model and data access. Scalability For large data sets, sharding has the advantage of being more cost effective and more predictably scalable than a single massive server. It is hard to justify a massive database server purchase today to accommodate an unreliable growth forecast. Incrementally adding new database servers as demand grows is much a sounder financial approach. Virtualization and cloud technologies help alleviate this problem by making it easier to scale instances, but if you reach the limits of their instance scalability then you have the same problem. Disaster Recovery Business continuity plans often specify a disaster recovery datacenter that can resume processing if the primary data center goes offline (usually due to a natural disaster like fire, earthquakes, flooding, etc.). Although this approach is common, it is usually plagued by two issues: The business must buy a complete data center that is nearly always idle Unless testing is unusually robust and frequent, there will always be doubt about whether the failover datacenter would be really able to assume a primary role It would be immeasurably better to simply have both the primary and secondary datacenters actively processing transactions, each with enough reserve capacity to handle the load of the other in the event of failure. This negates both the waste of buying an idle datacenter and also any concerns about whether the failover site is truly ready to handle live transactions. In order for both datacenters to be simultaneously active, each one must “own” a segment of the data — which means data sharding. Global Availability Your foreign customers will have a better, more responsive experience with your application if they access their data from a regionally nearby datacenter. Users accessing a single datacenter across the globe will experience noticeably slower connections. Using sharding with geo-replication can optimize regional access and still allow local queries across all the data. Data privacy laws — particularly in China, Europe, and Russia — are also driving data storage to regional datacenters. A data sharding approach can be a useful way to consolidate the legally exportable subset of the data collected in these jurisdictions. Switching to Shards If you are familiar with relational databases, you will discover that the database engine enforced some standard functionality that is no longer automatically available. For example, unique keys may not be unique across servers and foreign keys may refer to records that do not exist on that server. Thinking carefully through these issues will likely lead to successful workarounds. ArgentSea offers essentially two services for managing sharded data: The ShardSet unifies the many shard connections and directs queries to the correct shard and allows concurrent queries across all of them The ShardKey is a “virtual compound key” that uniquely identifies a record using the shard Id and the record key(s). ArgentSea’s querying architecture is designed to support concurrent queries across multiple shards. You can explore that further here . Next: The ShardKey"
  },
  "api/ArgentSea.UnexpectedSqlResultException.html": {
    "href": "api/ArgentSea.UnexpectedSqlResultException.html",
    "title": "Class UnexpectedSqlResultException | ArgentSea Docs",
    "keywords": "Class UnexpectedSqlResultException The exception is thrown when an output parameter is expected, but not found, when ExecuteQueryToValueAsync is invoked. Inheritance System.Object System.Exception UnexpectedSqlResultException Implements System.Runtime.Serialization.ISerializable Inherited Members System.Exception.GetBaseException() System.Exception.GetObjectData(System.Runtime.Serialization.SerializationInfo, System.Runtime.Serialization.StreamingContext) System.Exception.GetType() System.Exception.ToString() System.Exception.Data System.Exception.HelpLink System.Exception.HResult System.Exception.InnerException System.Exception.Message System.Exception.Source System.Exception.StackTrace System.Exception.TargetSite System.Exception.SerializeObjectState System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public sealed class UnexpectedSqlResultException : Exception, ISerializable Constructors | Improve this Doc View Source UnexpectedSqlResultException() Initializes a new instance of the UnexpectedSqlResultException class with no error message. Declaration public UnexpectedSqlResultException() | Improve this Doc View Source UnexpectedSqlResultException(String) Initializes a new instance of the UnexpectedSqlResultException class with a specified error message. Declaration public UnexpectedSqlResultException(string message) Parameters Type Name Description System.String message The message that describes the error. | Improve this Doc View Source UnexpectedSqlResultException(String, Exception) Initializes a new instance of the UnexpectedSqlResultException class. Declaration public UnexpectedSqlResultException(string message, Exception innerException) Parameters Type Name Description System.String message The message that describes the error. System.Exception innerException The exception that is the cause of the current exception. Implements System.Runtime.Serialization.ISerializable"
  },
  "api/ArgentSea.html": {
    "href": "api/ArgentSea.html",
    "title": "Namespace ArgentSea | ArgentSea Docs",
    "keywords": "Namespace ArgentSea Classes DataConnectionConfiguration Abstract class implementing the data connection functionality shared by PostgreSQL and SQL Server implementations. DataResilienceConfiguration This class contains the definition for a data resiliance strategy. Specifically: when to retry and when to circuit break. This class is created as a configuration entry in an array in the DataResilienceStrategies property of the DataConfigurationOptions class. DataResilienceOptions This options class contains an array of resilience strategies (retry and circuit breaking settings). To specify as particular resilience strategy, a connection can specify a ResilienceKey. DataSecurityOptions This options class contains an array of SecurityConfiguration (login information). A connection can specify as particular login account by referencing a SecurityKey. DbDataStores<TConfiguration> This class is used by provider specific implementations. It is unlikely that you would reference this in consumer code. This generic class manages non-sharded database connections. DbDataStores<TConfiguration>.DataConnection DbDataStores<TConfiguration>.DbDataSets DbParameterCollectionExtensions ExpressionHelpers This class is used by provider specific implementations. It is unlikely that you would reference this in consumer code. InvalidMapTypeException This exception is raise when a model property has a database mapping attribute that is not of the correct type. InvalidShardArgumentsException This error is raised upon an attempt to create an Empty ShardKey or ShardChild, but the IDs are not zero. Essentially, any shard object with a DataOrigin of '0' (Empty) must also have zeroed IDs (be equal to ShardKey.Empty or ShardChild.Empty). LoggingExtensions The are extension methods for high-performance logging. Mapper This static class contains the logic for mapping database parameters to/from properties. Mapper.DummyType MapShardChildAttribute MapShardKeyAttribute MapToModel MultipleMapAttributesException This exception is invoked if a model property has multiple mapping attributes. A single value cannot be mapped to/from multiple parameters or columns. This exception is not raised in the case of ShardKey > or ShardChild properties. ParameterMapAttribute QueryParameterCollection This is an implementation of the abstract DbParameterCollecion class. Unlike most provider-specific parameter collections, it can be created without a prior DbCommand object instance. RetryLimitExceededException This exception is raise when a transient failure occurs, but automatic retries were not successful. SecurityConfiguration This class represents data security information, with a key that can be reference by any connection(s) that share the security information. ShardDataStores<TShard, TConfiguration> This class is used by provider specific implementations. It is unlikely that you would call this in consumer code. This is the generic class that defines connections for sharded data sets. ShardDataStores<TShard, TConfiguration>.DataConnection ShardDataStores<TShard, TConfiguration>.ShardDataSet ShardDataStores<TShard, TConfiguration>.ShardDataSets ShardDataStores<TShard, TConfiguration>.ShardInstance StringExtensions This static class contains extension methods for cleaning input strings of invalid characters. It does NOT sanitize input strings for protection against injection attacks (your parmemeterized queries should protect against that). UnexpectedSqlResultException The exception is thrown when an output parameter is expected, but not found, when ExecuteQueryToValueAsync is invoked. Structs DataOrigin This object help descript the “type” of data. For example, you could assign Customer data a data origin value of 'c'. When comparing data values, the ShardKey/ShardChild will not match if the data origin is not the same value — even if IDs are the same. This helps prevent accidentaly comparisions that are not valid and also prevents collisions if you choose allows values of different types to be stored in the same cache. ShardChild<TShard, TRecord, TChild> Immutable class representing a sharded record with a database compound key. The ShardChild consist of the (virtual) shardId, the recordId, and the childId. ShardKey<TShard, TRecord> Immutable class representing a sharded record with a “compound” key: the (virtual) shardId and the (database) recordId. Interfaces IConnectionConfiguration This interface is used by provider specific implementations. It is unlikely that you would reference this in consumer code. The interface defines the minimum capability of a connection definition. IDataProviderServiceFactory This interface is used by provider specific implementations. It is unlikely that you would reference this in consumer code. The interface defines the capabilities of a database providers service. IDbConnectionConfiguration This interface is used by provider specific implementations. It is unlikely that you would implement this in consumer code. IDbDataConfigurationOptions This interface is used by provider specific implementations. It is unlikely that you would implement this in consumer code. IShardConnectionConfiguration<TShard> This interface is used by provider specific implementations. It is unlikely that you would implement this in consumer code. IShardConnectionsConfiguration<TShard> This interface is used by provider specific implementations. It is unlikely that you would implement this in consumer code. IShardDataConfigurationOptions<TShard> This interface is used by provider specific implementations. It is unlikely that you would implement this in consumer code. Enums DataResilienceConfiguration.SequenceLengthening LoggingExtensions.EventIdentifier ShardDataStores<TShard, TConfiguration>.ShardInstance.DataAccess StringExtensions.InputCleaningOptions Delegates QueryResultModelHandler<TShard, TArg, TModel> This delegate will be invoked for each shard (probably on different threads) to convert the cmd.Execute result to model types."
  },
  "tutorials/quickstarts/configuration.html": {
    "href": "tutorials/quickstarts/configuration.html",
    "title": "QuickStart One | ArgentSea Docs",
    "keywords": "QuickStart One This article will step you through a simple setup of ArgentSea for non-sharded data access. This presentation introduces concepts which are further elaborated in the subsequent article , so this is a good orientation prior that that walkthrough too. If you get stuck or have questions, click on one of the links to the in-depth tutorial articles. 1. Create a Project (or use an existing one) The sample QuickStart project is here . You can reproduce the starting point by creating a new ASP.NET API project type. If you prefer to start by creating a new, empty project, ensure that appsettings.json is added. 2. Setup your Database If you are using the QuickStart1 project, a setup SQL script is including in the project; otherwise you can access it on GitHub . You can run the SQL script against the database server to create the sample databases, tables, data, etc. SQL Server PostgreSQL The best way to use ArgentSea is to exclusively use stored procedures, and to enforce least-privileged access by granting the logon only EXECUTE permissions. Going further, you might consider creating distinct schemas, one for SELECT (read) procedures and one for INSERT, UPDATE, DELETE (write) procedures. Create two users and grant each EXECUTE to one or the other schema. Besides adding additional security, this may also help validate scale-out read-only endpoints during development and testing. As part of a general approach to lease-privileged access, you might consider creating two database users — one for read access and the other for writes. This approach can also help validate scale-out read-only endpoints during development and testing. Caution A password is embedded in the setup script (and corresponds to the credential sections below); you might consider changing this value. However, this is also a low-privileged user, so it is not a high risk if you leave things as they are. 3. Add ArgentSea to your project If you have loaded the QuickStart project, you can skip this step. If you are creating a new project, use NuGet to add ArgentSea to your project by selected the package that corresponds to your database platform: For Microsoft SQL Server databases, use ArgentSea.Sql For PostgreSQL, use ArgentSea.Pg Both packages will automatically include the shared ArgentSea package and any other dependencies. Using both packages in the same project may work but is not a tested scenario. You can learn more about adding a reference to ArgentSea here . 4. Define your Login Information ArgentSea leverages the .NET Core configuration architecture, which means that the configuration information is combined from multiple providers. In this example, we will store most connection information in the appsettings.json file, but store the login password securely in a separate store. Tip Because the new configuration architecture in .NET core allows values to be hosted in multiple places, we can also use environment variables — which can be very useful for managing a release pipeline. In that case, we might store the server or database information there instead of appsettings.json . Again, the details are described in the configuration tutorial. Open the User Secrets JSON configuration file by right-clicking on the project node and selecting it from the popup menu. If a User Secrets option does not appear, you may need to add the Microsoft.Extensions.Configuration.UserSecrets NuGet package to your project. User Secrets provides a means of keeping passwords out of your source control files. Note Because the QuickStart1 sample application uses User Secrets, those following along at home with the downloaded project will still need to manually copy the credentials to the User Secrets in the sample app. SQL Server PostgreSQL To connect using username and password authentication, add this to your User Secrets: { \"SqlDbConnections\": [ { \"Password\": \"Pwd123456\" } ] } Change the values, as appropriate, to represent a valid login. Configure the DataSource and InitialCatalog properties in your appsettings.json configuration file: { \"SqlDbConnections\": [ { \"DatabaseKey\": \"MyDatabase\", \"UserName\": \"webUser\", \"DataSource\": \"localhost\", \"InitialCatalog\": \"MyDb\" } ] } Note that if you are using Windows authentication, you can just specify this in appsettings.json and you don’t need to manage User Secrets : { \"SqlDbConnections\": [ { \"DatabaseKey\": \"MyDatabase\", \"WindowsAuth\": true, \"DataSource\": \"localhost\", \"InitialCatalog\": \"MyDb\" } ] } To connect using username and password authentication, add this to your User Secrets: { \"PgDbConnections\": [ { \"Password\": \"Pwd123456\" } ] } Configure the Host and Database properties in your appsettings.json configuration file: { \"PgDbConnections\": [ { \"DatabaseKey\": \"MyDatabase\", \"Host\": \"localhost\", \"Database\": \"MyDb\", \"UserName\": \"webuser\" } ] } Note that if you are using Windows authentication, you can just specify this in appsettings.json and you don’t need to manage secrets: { \"PgDbConnections\": [ { \"DatabaseKey\": \"MyDatabase\", \"Host\": \"localhost\", \"Database\": \"MyDb\", \"WindowsAuth\": true } ] } Caution In a production deployment, the Credential section — entries currently placed in User Secrets — should be hosted in AWS Secrets Manager , Azure Key Vault , a secure file share, or some other secure resource. 7. Load ArgentSea on Application Start ArgentSea is an injectable service, so it needs to be registered on application startup. SQL Server PostgreSQL Open your project’s Startup class. At the top, there should be the following using statement: using ArgentSea.Sql; Then, in the Startup class’ ConfigureServices method, add: services.AddSqlServices(Configuration); This step creates an injectable SqlServices object that we can consume in all of our data access clients. Open your project’s Startup class. At the top, there should be the following using statement: using ArgentSea.Pg; Then, in the Startup class’ ConfigureServices method, add: services.AddPgServices(Configuration); This step creates an injectable SqlServices object that we can consume in all of our data access clients. Note The ArgentSea services include both the Databases and ShardSets service. Of course, if no ShardSets are configured, the collection will be empty. 8. Create a Model Class A model class has properties that correspond the the fields of a data entity. ArgentSea can automatically map these properties to input or output parameters, the columns of a DataReader object, or (in SQL Server) a table-valued parameter. For example, suppose your subscriber data can be represented by a class like this: using System; public class Subscriber { public int SubscriberId { get; set; } public string Name { get; set; } public DateTime Expiration { get; set; } } We can simply add mapping attributes to this class: SQL Server PostgreSQL using System; using ArgentSea.Sql; public class Subscriber { [MapToSqlInt(\"@SubID\")] public int SubscriberId { get; set; } [MapToSqlNVarChar(\"@SubscriberName\", 255)] public string Name { get; set; } [MapToSqlDateTime2(\"@EndDate\")] public DateTime Expiration { get; set; } } The “@” parameter prefix is optional — ArgentSea will add the “@” automatically for parameters and remove it automatically when reading data reader columns. using System; using ArgentSea.Pg; public class Subscriber { [MapToPgInteger(\"subid\")] public int SubscriberId { get; set; } [MapToPgVarchar(\"subname\", 255, true)] public string Name { get; set; } [MapToPgTimestamp(\"enddate\")] public DateTime? Expiration { get; set; } } Note that the property name does not need to match the parameter or column name. It is not uncommon for database naming conventions to differ from .NET property naming conventions. Warning ArgentSea assumes consistent naming in your data parameters and results. A project with “consistently inconsistent” parameters or column names will find the ArgentSea Mapper of little practical use. 5. Define the SQL implementation SQL Server PostgreSQL In the sample QuickStart , the stored procedure looks like this: CREATE PROCEDURE ws.GetSubscriber @SubId int, @SubName nvarchar(255) OUTPUT, @EndDate datetime2 OUTPUT AS BEGIN SELECT @SubName = Subscribers.SubName, @EndDate = Subscribers.EndDate FROM dbo.Subscribers WHERE Subscribers.SubId = @SubId; END; ArgentSea deliberately tries minimize mixing SQL and .NET code; ideally, only stored procedure names are compiled into the project. Further, to help track which procedures are in use, ArgentSea recommends centralizing the procedure names in a single static Queries class: public static class Queries { public static QueryProcedure GetSubscriber => new QueryProcedure(\"ws.GetSubscriber\", new[] { \"@SubId\", \"SubName\", \"EndDate\" }); } Finally, the application needs a repository class to actually retrieve the data. In the sample application, this is called the SubscriberStore . This is the class that will call the database stored procedure or SQL statement and return the specified subscriber. If you are creating your own project, you need to construct something similar. Our implementation of the data access code requires only a few lines: public class SubscriberStore { private readonly SqlDatabases _dbs; private readonly ILogger<SubscriberStore> _logger; public SubscriberStore(SqlDatabases dbs, ILogger<SubscriberStore> logger) { _dbs = dbs; _logger = logger; } public async Task<Subscriber> GetSubscriber(int subscriberId, CancellationToken cancellation) { var db = _dbs[\"MyDatabase\"]; var prms = new ParameterCollection() .AddSqlIntInputParameter(\"@SubId\", subscriberId) .CreateOutputParameters<Subscriber>(_logger); return await db.Read.MapOutputAsync<Subscriber>(Queries.GetSubscriber, prms, cancellation); } } Because the “@SubId” parameter was manually created, the when the Mapper is enlisted to automatically create all the output parameters, it knows not to duplicate the “@SubId” parameter. The MapOutputAsync method retrieves the data and creates the model instance automatically. Create a new folder call “SQL” in your project. In that folder, create a new file named “GetSubscriber.psql”. In Visual Studio, open the file properties and ensure the Build Action attribute is set to “None” and the Copy to Output Directory attribute is set to “Copy if newer”. In the simple QuickStart query , the statement looks like this: SELECT subscribers.subid, subscribers.subname, subscribers.enddate FROM qs1.subscribers WHERE subscribers.subid = @subid; ArgentSea deliberately tries minimize mixing SQL and .NET code by storing SQL in files loaded at runtime. To help track which SQL statements are in use, ArgentSea recommends centralizing the procedure names in a single static Queries class: public static class Queries { public static QueryStatement GetSubscriber => _getSubscriber.Value; private static readonly Lazy<QueryStatement> _getSubscriber = QueryStatement.Create(\"GetSubscriber\", new[] { \"subid\" }); } Because want to load the file only when it’s needed and we need cache the file without multiple thread all doing the same thing, our declaration of each SQL statement requires two lines of code. Finally, the application needs a repository class to actually retrieve the data. In the sample application, this is called the SubscriberStore . This is the class that will invoke the query and return the specified subscriber. If you are creating your own project, you need to construct something similar. Our implementation of the data access code requires only a few lines: public class SubscriberStore { private readonly PgDatabases.Database _db; private readonly ILogger<SubscriberStore> _logger; public SubscriberStore(PgDatabases dbs, ILogger<SubscriberStore> logger) { _db = dbs[\"MyDatabase\"]; _logger = logger; } public async Task<Subscriber> GetSubscriber(int subscriberId, CancellationToken cancellation) { var prms = new ParameterCollection() .AddPgIntegerInputParameter(\"subid\", subscriberId); return await _db.Read.MapReaderAsync<Subscriber>(Queries.GetSubscriber, prms, cancellation); } } Because the “subid” parameter was manually created, the when the Mapper is enlisted to automatically create all the output parameters, it knows not to duplicate the “subid” parameter. The MapReaderAsync method retrieves the data and creates the model instance automatically. The ArgentSea database service is injected into the SubscriberStore class by the .NET framework. The SubscriberStore itself is in turn injected into the controller. Don’t forget to add the SubscriberStore class to services.Configure() in Startup, so that injection works. public void ConfigureServices(IServiceCollection services) { ... services.AddSingleton<SubscriberStore>(); ... } The controller for a web API example, can be very simple: [Route(\"api/[controller]\")] [ApiController] public class SubscriberController : ControllerBase { private readonly SubscriberStore _store; private readonly ILogger<SubscriberController> _logger; public SubscriberController(SubscriberStore store, ILogger<SubscriberController> logger) { _store = store; _logger = logger; } // GET api/subscriber/5 [HttpGet(\"{id}\")] public async Task<ActionResult<Subscriber>> Get(int id, CancellationToken cancellation) { var result = await _store.GetSubscriber(id, cancellation); if (result is null) { return NotFound(); } return result; } } Due to the work of the Mapper, the controller code would not increase in complexity even if the model had a many more properties, each mapped to a parameter or result column. You should be able to build and run your project. You can test the web service by specifying http://<projectUrl&gr;/api/subscriber/1. The QuickStart code has a test project that validates that the web service returns the expected results."
  },
  "reference/apis.html": {
    "href": "reference/apis.html",
    "title": "API Reference | ArgentSea Docs",
    "keywords": "API Reference Objects shared across providers ArgentSea.Shared The ArgentSea.Shared project has two types objects: those that are base classes for provider-specific implementations, and those that can be used directly. The most important of the directly usable objects are the the ADO.NET parameter extension methods , and the useful Query Parameter Collection . Most of the actual ArgentSea code exists in this shared library. SQL Server objects ArgentSea.Sql This is the SQL Server implementation of ArgentSea. PostreSQL objects ArgentSea.Pg This is the PostgreSQL implementation of ArgentSea."
  },
  "api/ArgentSea.QueryParameterCollection.html": {
    "href": "api/ArgentSea.QueryParameterCollection.html",
    "title": "Class QueryParameterCollection | ArgentSea Docs",
    "keywords": "Class QueryParameterCollection This is an implementation of the abstract DbParameterCollecion class. Unlike most provider-specific parameter collections, it can be created without a prior DbCommand object instance. Inheritance System.Object System.MarshalByRefObject System.Data.Common.DbParameterCollection QueryParameterCollection Implements System.Data.IDataParameterCollection System.Collections.IList System.Collections.ICollection System.Collections.IEnumerable Inherited Members System.Data.Common.DbParameterCollection.System.Collections.IList.get_Item(System.Int32) System.Data.Common.DbParameterCollection.System.Collections.IList.set_Item(System.Int32, System.Object) System.Data.Common.DbParameterCollection.System.Data.IDataParameterCollection.get_Item(System.String) System.Data.Common.DbParameterCollection.System.Data.IDataParameterCollection.set_Item(System.String, System.Object) System.Data.Common.DbParameterCollection.Item[System.Int32] System.Data.Common.DbParameterCollection.Item[System.String] System.Data.Common.DbParameterCollection.System.Collections.IList.Item[System.Int32] System.Data.Common.DbParameterCollection.System.Data.IDataParameterCollection.Item[System.String] System.MarshalByRefObject.GetLifetimeService() System.MarshalByRefObject.InitializeLifetimeService() System.MarshalByRefObject.MemberwiseClone(System.Boolean) System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public class QueryParameterCollection : DbParameterCollection, IDataParameterCollection, IList, ICollection, IEnumerable Properties | Improve this Doc View Source Count Declaration public override int Count { get; } Property Value Type Description System.Int32 Overrides System.Data.Common.DbParameterCollection.Count | Improve this Doc View Source SyncRoot Declaration public override object SyncRoot { get; } Property Value Type Description System.Object Overrides System.Data.Common.DbParameterCollection.SyncRoot Methods | Improve this Doc View Source Add(Object) Declaration public override int Add(object value) Parameters Type Name Description System.Object value Returns Type Description System.Int32 Overrides System.Data.Common.DbParameterCollection.Add(System.Object) | Improve this Doc View Source AddRange(Array) Declaration public override void AddRange(Array values) Parameters Type Name Description System.Array values Overrides System.Data.Common.DbParameterCollection.AddRange(System.Array) | Improve this Doc View Source Clear() Declaration public override void Clear() Overrides System.Data.Common.DbParameterCollection.Clear() | Improve this Doc View Source Contains(Object) Declaration public override bool Contains(object value) Parameters Type Name Description System.Object value Returns Type Description System.Boolean Overrides System.Data.Common.DbParameterCollection.Contains(System.Object) | Improve this Doc View Source Contains(String) Declaration public override bool Contains(string value) Parameters Type Name Description System.String value Returns Type Description System.Boolean Overrides System.Data.Common.DbParameterCollection.Contains(System.String) | Improve this Doc View Source CopyTo(Array, Int32) Declaration public override void CopyTo(Array array, int index) Parameters Type Name Description System.Array array System.Int32 index Overrides System.Data.Common.DbParameterCollection.CopyTo(System.Array, System.Int32) | Improve this Doc View Source GetEnumerator() Declaration public override IEnumerator GetEnumerator() Returns Type Description System.Collections.IEnumerator Overrides System.Data.Common.DbParameterCollection.GetEnumerator() | Improve this Doc View Source GetParameter(Int32) Declaration protected override DbParameter GetParameter(int index) Parameters Type Name Description System.Int32 index Returns Type Description System.Data.Common.DbParameter Overrides System.Data.Common.DbParameterCollection.GetParameter(System.Int32) | Improve this Doc View Source GetParameter(String) Declaration protected override DbParameter GetParameter(string parameterName) Parameters Type Name Description System.String parameterName Returns Type Description System.Data.Common.DbParameter Overrides System.Data.Common.DbParameterCollection.GetParameter(System.String) | Improve this Doc View Source IndexOf(Object) Declaration public override int IndexOf(object value) Parameters Type Name Description System.Object value Returns Type Description System.Int32 Overrides System.Data.Common.DbParameterCollection.IndexOf(System.Object) | Improve this Doc View Source IndexOf(String) Declaration public override int IndexOf(string parameterName) Parameters Type Name Description System.String parameterName Returns Type Description System.Int32 Overrides System.Data.Common.DbParameterCollection.IndexOf(System.String) | Improve this Doc View Source Insert(Int32, Object) Declaration public override void Insert(int index, object value) Parameters Type Name Description System.Int32 index System.Object value Overrides System.Data.Common.DbParameterCollection.Insert(System.Int32, System.Object) | Improve this Doc View Source Remove(Object) Declaration public override void Remove(object value) Parameters Type Name Description System.Object value Overrides System.Data.Common.DbParameterCollection.Remove(System.Object) | Improve this Doc View Source RemoveAt(Int32) Declaration public override void RemoveAt(int index) Parameters Type Name Description System.Int32 index Overrides System.Data.Common.DbParameterCollection.RemoveAt(System.Int32) | Improve this Doc View Source RemoveAt(String) Declaration public override void RemoveAt(string parameterName) Parameters Type Name Description System.String parameterName Overrides System.Data.Common.DbParameterCollection.RemoveAt(System.String) | Improve this Doc View Source SetParameter(Int32, DbParameter) Declaration protected override void SetParameter(int index, DbParameter value) Parameters Type Name Description System.Int32 index System.Data.Common.DbParameter value Overrides System.Data.Common.DbParameterCollection.SetParameter(System.Int32, System.Data.Common.DbParameter) | Improve this Doc View Source SetParameter(String, DbParameter) Declaration protected override void SetParameter(string parameterName, DbParameter value) Parameters Type Name Description System.String parameterName System.Data.Common.DbParameter value Overrides System.Data.Common.DbParameterCollection.SetParameter(System.String, System.Data.Common.DbParameter) Implements System.Data.IDataParameterCollection System.Collections.IList System.Collections.ICollection System.Collections.IEnumerable Extension Methods Mapper.MapToInParameters<TModel>(DbParameterCollection, TModel, ILogger) Mapper.MapToInParameters<TModel>(DbParameterCollection, TModel, HashSet<String>, ILogger) Mapper.MapToOutParameters(DbParameterCollection, Type, ILogger) Mapper.MapToOutParameters<TModel>(DbParameterCollection, ILogger) Mapper.MapToOutParameters<TModel>(DbParameterCollection, HashSet<String>, ILogger) Mapper.MapToOutParameters(DbParameterCollection, Type, HashSet<String>, ILogger) Mapper.ReadOutParameters<TModel>(DbParameterCollection, ILogger) Mapper.ReadOutParameters<TShard, TModel>(DbParameterCollection, TShard, ILogger)"
  },
  "api/ArgentSea.RetryLimitExceededException.html": {
    "href": "api/ArgentSea.RetryLimitExceededException.html",
    "title": "Class RetryLimitExceededException | ArgentSea Docs",
    "keywords": "Class RetryLimitExceededException This exception is raise when a transient failure occurs, but automatic retries were not successful. Inheritance System.Object System.Exception RetryLimitExceededException Implements System.Runtime.Serialization.ISerializable Inherited Members System.Exception.GetBaseException() System.Exception.GetObjectData(System.Runtime.Serialization.SerializationInfo, System.Runtime.Serialization.StreamingContext) System.Exception.GetType() System.Exception.ToString() System.Exception.Data System.Exception.HelpLink System.Exception.HResult System.Exception.InnerException System.Exception.Message System.Exception.Source System.Exception.StackTrace System.Exception.TargetSite System.Exception.SerializeObjectState System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public sealed class RetryLimitExceededException : Exception, ISerializable Constructors | Improve this Doc View Source RetryLimitExceededException() Initializes a new instance of the RetryLimitExceededException class with no error message. Declaration public RetryLimitExceededException() | Improve this Doc View Source RetryLimitExceededException(String) Initializes a new instance of the RetryLimitExceededException class with a specified error message. Declaration public RetryLimitExceededException(string message) Parameters Type Name Description System.String message The message that describes the error. | Improve this Doc View Source RetryLimitExceededException(String, Exception) Initializes a new instance of the RetryLimitExceededException class. Declaration public RetryLimitExceededException(string message, Exception innerException) Parameters Type Name Description System.String message The message that describes the error. System.Exception innerException The exception that is the cause of the current exception. Implements System.Runtime.Serialization.ISerializable"
  },
  "tutorials/Sharding/shardkey.html": {
    "href": "tutorials/Sharding/shardkey.html",
    "title": "The ShardKey | ArgentSea Docs",
    "keywords": "The ShardKey All databases need a way to uniquely identify a record — a record key. With sharded data sets, a record key need to be unique across all the shards. Within a single database, uniqueness is easily managed; across a shard set, database engines can no longer enforce uniqueness for data they don’t know about. Additionally, on the client side, the query dispatcher needs to be able to use the record key in order to know to which shard connection to use. There are two approaches to maintaining a unique key across multiple databases: Use distinct identity ranges for each database in the shard set. The upside of this approach is that it is possible to combine data sets without conflicts; the downside is that configuration is complicated — on both the client and database servers — so mistakes are more likely, and some mistakes can be very hard to fix. The query dispatcher must know the various identity ranges hosted by each server in order to select the right connection. Combine the shard connection key and the record key into a larger “compound key”. With this approach, finding the right shard connection is easy because the value is embedded in the compound record key. The database servers do not need to be configured with separate identity ranges, which in some case may allow smaller, more efficient key sizes (i.e. int vs bigint). Combining or splitting shards could be more complicated, however. ArgentSea will work with either design. The ShardKey object offers support for the second approach. Components A ShardKey consists of three essential components: a DataOrigin char value, a ShardId , and a RecordId . ShardKey instances with additional generic types can be used for compound table keys; these will had the additional ChildId , GrandChildId , and GreatGrandChildId values. The DataOrigin ShardKey types have a DataOrigin value. The purpose of this value is to represent a distinct data source (table). It is simply a character value that you can choose to differentiate them. For example, keys representing a Customer record might have a DataOrigin of “c”, whereas keys representing a Product record might have a DataOrigin of “p”. Because this simple tag identifies the data source, two different ShardKeys from the same shard and with the same record number will still not be equal because they represent different source data. Important One DataOrigin character value is reserved: “0” (Unicode character Zero, Unicode numeric value 30). This is used for the DataOrigin of ShardKey.Empty . Creating a ShardKey with a “zero” DataOrigin character but non-default (i.e. not zero or not null) ShardId or RecordId values will throw an InvalidShardArgumentsException error. This capability is useful for helping prevent data from being accessed with the wrong type of key — like an inventory key inadvertently passed to fetch an account record. Also, this may be helpful for caching data, since you can use the same dictionary to cache objects of different types without key collision. Caution Although the DataOrigin is a char, it is serialized as an 8-bit ANSI character value. You should avoid using non-alphanumeric characters for this value. And definitely no emojis. The ShardId The ShardId is used to identify a particular shard in the ShardSet. This is a 16-bit integer, also called Int16, short, or Smallint in SQL. Because it only requires two bytes, it is very compact in storage and memory, yet it can theoretically support over 65,000 shards. Note The earliest versions of the ArgentSea framework used a generic type for the ShardId — similar to that used for the RecordId, ChildId, etc. — which allowed the shard identifier to be a string, byte, Guid, etc. However, this created a verbose object model where the consuming code had to endlessly declare the ShardId type. Within a given project this type could never change, so this created a lot of redundancy. Given the types available in both .Net and SQL, the efficiency of data storage, and the likely maximum number of shards, one type was clearly optimal: ArgentSea was rewritten so that the ShardId type was always a 16-bit integer. Caution The database shards themselves may not know what their own ShardId is! The ShardId comes only from the connection information in the local configuration file. This means that a misconfiguration can corrupt data! For example, if a user attempts to update the record with Id 2 on shard 4 but a misconfiguration directs the connection to the wrong shard, the command will overwrite the record with id 4 — in the wrong database! Consider using optimistic concurrency practices like a rowversion or timestamp. This validation will also protect against updating the wrong database. The RecordId Like the ShardId, the RecordId is also an generic type, which can be one of the following: RecordId (and ChildId/GrandChildId/GreatGrandChildId) Possible Data Types byte , char , DateTime , DateTimeOffset , decimal , double , float , Guid , int , long , sbyte , short , string , TimeSpan , uint , ulong , ushort If you have a data key that is not one of these types, the ShardKey class will not know how to serialize the values. The ChildId, GrandChildId, and GreatGrandChildId The ShardKey type gets its name from the parent-child relationship that is typical of a two-column compound key. By specifying additional generic arguments, you can extend the object to accommodate a compound key of up to four columns! Using The ShardKey Having a single object represent a compound record key adds only a little convenience. The real value comes from three capabilities: The shard Mapping attributes and the External key string. ToString(), ToExternalString(), and FromExternalString() Calling ToString() on a ShardKey returns a json-formatted list of the constituent values. The ToExternalKey() function serializes the ShardKey values into a URL-safe string. This string also has a small amount of tampering protection. This is also the value returned when the model is serialized (i.e. in JSON results). As you would expect, the FromExternalString() function reverses the operation, returning a ShardKey instance from a valid input string. The External String value can be used with, say, REST endpoints to specify a sharded record using a single argument. The MapShardKey Attribute The MapShardKey and attribute maps the shard information, record key, and (as appropriate) the child record values to a new ShardKey instance. The simplest implementation is to simply add the MapShardKey and the type-appropriate MapTo attribute(s). SQL Server PostgreSQL [MapShardKey('c', \"@CustomerId\")] [MapToSqlInt(\"@CustomerId\")] public ShardKey<byte, int> CustomerKey { get; set; } [MapShardKey('c', \"customer_id\")] [MapToPgInteger(\"customer_id\")] public ShardKey<short, int> CustomerKey { get; set; } This example sets the property to a ShardKey instance with a DataOrigin of “c”, the ShardId to the value of the data connection, and the RecordId the “CustomerId” column or parameter value. The MapShardKey attribute’s first argument is a DataOrigin char value. The second argument is the name of the data parameter or column. This name must exactly match the name in the data MapTo attribute. If ShardKey has child columns, include those column definition too (ensuring that these names also exactly match). SQL Server PostgreSQL [MapShardKey('O', \"@OrderId\", \"@OrderItemId\")] [MapToSqlBigInt(\"@OrderId\")] [MapToSqlSmallInt(\"@OrderItemId\")] public ShardKey<byte, long, short> OrderItemKey { get; set; } [MapShardKey('O', \"order_id\", \"order_item_id\")] [MapToPgBigint(\"order_id\")] [MapToPgInteger(\"order_item_id\")] public ShardKey<short, long, int> OrderItemKey { get; set; } In both previous examples, the ShardId will be implicitly obtained from the connection’s ShardId. In the case of results that include the primary key column, this works well. However, when a data record references a table belonging to a foreign shard, the ShardId must be explicitly set by the database record. To do this, just add a ShardID column name to the first argument of the MapShardKey attribute: SQL Server PostgreSQL [MapShardKey(\"@CustomerShardId\", 'c', \"@CustomerId\")] [MapToSqlInt(\"@CustomerId\")] public ShardKey<byte, int> CustomerKey { get; set; } [MapShardKey(\"@OrderShardId\", 'O', \"@OrderId\", \"@OrderItemId\")] [MapToSqlBigInt(\"@OrderId\")] [MapToSqlSmallInt(\"@OrderItemId\")] public ShardKey<long, short> OrderItemKey { get; set; } [MapShardKey(\"customer_shard_id\", 'c', \"customer_id\")] [MapToPgInteger(\"customer_id\")] public ShardKey<short, int> CustomerKey { get; set; } [MapShardKey(\"order_shard_id\", , 'O', \"order_id\", \"order_item_id\")] [MapToPgBigint(\"order_id\")] [MapToPgSmallint(\"order_item_id\")] public ShardKey<long, short> OrderItemKey { get; set; } Null Values Because a ShardKey is a struct, a variable or property of this type cannot be null. ShardKey objects are initialized to ShardKey.Empty. If a ShardKey represents a database field that might be Null, the ShardKey property or variable should be wrapped in the Nullable<> type. The MapToShardKey attribute will set Nullable<ShardKey<>> or ShardKey<>? properties to null if any of the constituent database column values are Null. If the underlying type is not Nullable<> and the database value is Null, the Mapper with throw an error (except as described in the next paragraph). In many cases, a ShardKey will represent a primary key, so a database Null value really represents a non-existent record. In this case, the desired behavior is probably to return the entire parent object as null. Marking the MapToShardKey attribute(s) as required implements this behavior. When the required parameter is set, the ShardKey property does not need to be Nullable<> since a Null database value will return a null result object. Keyed Models If your Model class uses a ShardKey key, you might consider implementing IKeyedModel<,> or IKeyedChildModel<, ,> respectively. These interfaces require a property named “Key” of ShardKey type. Models that implement this interface can leverage some additional ArgentSea utility functions. For example, the ShardKey struct has a static Merge method which can combine model sets, comparing the records by the key value. Both structs also have a ForeignShards method which returns a list of shards that are not local to the specified shard, which simplifies the problem of identifying records that need to be updated of foreign shards. Also, the SQL Server implementation also allows conversion of the Model keys directly to a Table Valued Parameter. Likewise, the PostgreSQL implementation can use model keys to write values into a temporary table. Next: ShardSets"
  },
  "readme.html": {
    "href": "readme.html",
    "title": "ArgentSea Documentation | ArgentSea Docs",
    "keywords": "ArgentSea Documentation For a description of ArgentSea, please visit the the web page at http://www.argentsea.com . This repostitory contains the markdown and links that enables DocFx to create the documentation site for ArgentSea. Documentation generation requires local access to other ArgentSea repostitories. These should each be sibling folders, with the names as: https://github.com/argentsea/docfx cloned to \\ArgentSea.DocFx https://github.com/argentsea/shared cloned to \\ArgentSea.Shared https://github.com/argentsea/sql cloned to \\ArgentSea.Sql https://github.com/argentsea/pg cloned to \\ArgentSea.Pg https://github.com/argentsea/pg cloned to \\ArgentSea.Pg https://github.com/argentsea/docs cloned to \\ArgentSea.DocFx_site DocFx should generate a web site to the “_site” folder. The _site folder is it’s own repository; pushing that site to GitHub will publish the updated documentation. This repository uses the MIT license."
  },
  "api/ArgentSea.LoggingExtensions.html": {
    "href": "api/ArgentSea.LoggingExtensions.html",
    "title": "Class LoggingExtensions | ArgentSea Docs",
    "keywords": "Class LoggingExtensions The are extension methods for high-performance logging. Inheritance System.Object LoggingExtensions Inherited Members System.Object.Equals(System.Object) System.Object.Equals(System.Object, System.Object) System.Object.GetHashCode() System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax public static class LoggingExtensions Methods | Improve this Doc View Source BuildSqlResultsHandlerScope(ILogger, String, Type) Declaration public static IDisposable BuildSqlResultsHandlerScope(this ILogger logger, string procedureName, Type model) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String procedureName System.Type model Returns Type Description System.IDisposable | Improve this Doc View Source CiruitBreakingDbCommand(ILogger, String, String) Declaration public static void CiruitBreakingDbCommand(this ILogger logger, string commandName, string connectionName) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String commandName System.String connectionName | Improve this Doc View Source CiruitBreakingDbConnection(ILogger, String) Declaration public static void CiruitBreakingDbConnection(this ILogger logger, string connectionName) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String connectionName | Improve this Doc View Source CiruitBrokenDbCommandRestored(ILogger, String, String) Declaration public static void CiruitBrokenDbCommandRestored(this ILogger logger, string commandName, string connectionName) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String commandName System.String connectionName | Improve this Doc View Source CiruitBrokenDbCommandTest(ILogger, String, String) Declaration public static void CiruitBrokenDbCommandTest(this ILogger logger, string commandName, string connectionName) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String commandName System.String connectionName | Improve this Doc View Source CiruitBrokenDbConnectionRestored(ILogger, String) Declaration public static void CiruitBrokenDbConnectionRestored(this ILogger logger, string connectionName) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String connectionName | Improve this Doc View Source CiruitBrokenDbConnectionTest(ILogger, String) Declaration public static void CiruitBrokenDbConnectionTest(this ILogger logger, string connectionName) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String connectionName | Improve this Doc View Source CreatedExpressionTreeForModel(ILogger, Type, String, Expression) Declaration public static void CreatedExpressionTreeForModel(this ILogger logger, Type model, string procedureName, Expression codeBlock) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type model System.String procedureName System.Linq.Expressions.Expression codeBlock | Improve this Doc View Source CreatedExpressionTreeForReaderOrdinals(ILogger, Type, Expression) Declaration public static void CreatedExpressionTreeForReaderOrdinals(this ILogger logger, Type model, Expression codeBlock) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type model System.Linq.Expressions.Expression codeBlock | Improve this Doc View Source CreatedExpressionTreeForReaderRowData(ILogger, Type, Expression) Declaration public static void CreatedExpressionTreeForReaderRowData(this ILogger logger, Type model, Expression codeBlock) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type model System.Linq.Expressions.Expression codeBlock | Improve this Doc View Source CreatedExpressionTreeForReadOutParameters(ILogger, Type, Expression) Declaration public static void CreatedExpressionTreeForReadOutParameters(this ILogger logger, Type model, Expression codeBlock) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type model System.Linq.Expressions.Expression codeBlock | Improve this Doc View Source CreatedExpressionTreeForSetInParameters(ILogger, Type, Expression) Declaration public static void CreatedExpressionTreeForSetInParameters(this ILogger logger, Type model, Expression codeBlock) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type model System.Linq.Expressions.Expression codeBlock | Improve this Doc View Source CreatedExpressionTreeForSetOutParameters(ILogger, Type, Expression) Declaration public static void CreatedExpressionTreeForSetOutParameters(this ILogger logger, Type model, Expression codeBlock) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type model System.Linq.Expressions.Expression codeBlock | Improve this Doc View Source DataReaderIsClosed(ILogger, String, String) Declaration public static void DataReaderIsClosed(this ILogger logger, string sprocName, string connectionName) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String sprocName System.String connectionName | Improve this Doc View Source DataReaderIsNull(ILogger, String, String) Declaration public static void DataReaderIsNull(this ILogger logger, string sprocName, string connectionName) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String sprocName System.String connectionName | Improve this Doc View Source NullShardChildArguments<TShard, TRecord, TChild>(ILogger, String, ShardChild<TShard, TRecord, TChild>) Declaration public static void NullShardChildArguments<TShard, TRecord, TChild>(this ILogger logger, string propertyName, ShardChild<TShard, TRecord, TChild> shardChild) where TShard : IComparable where TRecord : IComparable where TChild : IComparable Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String propertyName ShardChild <TShard, TRecord, TChild> shardChild Type Parameters Name Description TShard TRecord TChild | Improve this Doc View Source NullShardKeyArguments<TShard, TRecord>(ILogger, String, ShardKey<TShard, TRecord>) Declaration public static void NullShardKeyArguments<TShard, TRecord>(this ILogger logger, string propertyName, ShardKey<TShard, TRecord> shardKey) where TShard : IComparable where TRecord : IComparable Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String propertyName ShardKey <TShard, TRecord> shardKey Type Parameters Name Description TShard TRecord | Improve this Doc View Source RequiredPropertyIsDbNull(ILogger, String, String) Declaration public static void RequiredPropertyIsDbNull(this ILogger logger, string modelName, string parameterName) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String modelName System.String parameterName | Improve this Doc View Source RetryingDbCommand(ILogger, String, String, Int32, Exception) Declaration public static void RetryingDbCommand(this ILogger logger, string commandName, string connectionName, int attemptCount, Exception exception) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String commandName System.String connectionName System.Int32 attemptCount System.Exception exception | Improve this Doc View Source RetryingDbConnection(ILogger, String, Int32, Exception) Declaration public static void RetryingDbConnection(this ILogger logger, string connectionName, int attemptCount, Exception exception) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String connectionName System.Int32 attemptCount System.Exception exception | Improve this Doc View Source SqlFieldNotFound(ILogger, String, Type) Declaration public static void SqlFieldNotFound(this ILogger logger, string columnName, Type TModel) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String columnName System.Type TModel | Improve this Doc View Source SqlInParametersCacheHit(ILogger, Type) Declaration public static void SqlInParametersCacheHit(this ILogger logger, Type TModel) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type TModel | Improve this Doc View Source SqlInParametersCacheMiss(ILogger, Type) Declaration public static void SqlInParametersCacheMiss(this ILogger logger, Type TModel) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type TModel | Improve this Doc View Source SqlParameterNotFound(ILogger, String, Type) Declaration public static void SqlParameterNotFound(this ILogger logger, string parameterName, Type propertyType) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String parameterName System.Type propertyType | Improve this Doc View Source SqlReaderCacheHit(ILogger, Type) Declaration public static void SqlReaderCacheHit(this ILogger logger, Type TModel) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type TModel | Improve this Doc View Source SqlReaderCacheMiss(ILogger, Type) Declaration public static void SqlReaderCacheMiss(this ILogger logger, Type TModel) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type TModel | Improve this Doc View Source SqlReadOutParametersCacheHit(ILogger, Type) Declaration public static void SqlReadOutParametersCacheHit(this ILogger logger, Type TModel) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type TModel | Improve this Doc View Source SqlReadOutParametersCacheMiss(ILogger, Type) Declaration public static void SqlReadOutParametersCacheMiss(this ILogger logger, Type TModel) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type TModel | Improve this Doc View Source SqlSetOutParametersCacheHit(ILogger, Type) Declaration public static void SqlSetOutParametersCacheHit(this ILogger logger, Type TModel) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type TModel | Improve this Doc View Source SqlSetOutParametersCacheMiss(ILogger, Type) Declaration public static void SqlSetOutParametersCacheMiss(this ILogger logger, Type TModel) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.Type TModel | Improve this Doc View Source TraceDbCmdExecuted(ILogger, String, String, Int64) Declaration public static void TraceDbCmdExecuted(this ILogger logger, string commandName, string connectionName, long milliseconds) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String commandName System.String connectionName System.Int64 milliseconds | Improve this Doc View Source TraceGetOutMapperProperty(ILogger, String) Declaration public static void TraceGetOutMapperProperty(this ILogger logger, string propertyName) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String propertyName | Improve this Doc View Source TraceInMapperProperty(ILogger, String) Declaration public static void TraceInMapperProperty(this ILogger logger, string propertyName) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String propertyName | Improve this Doc View Source TraceRdrMapperProperty(ILogger, String) Declaration public static void TraceRdrMapperProperty(this ILogger logger, string propertyName) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String propertyName | Improve this Doc View Source TraceSetOutMapperProperty(ILogger, String) Declaration public static void TraceSetOutMapperProperty(this ILogger logger, string propertyName) Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String propertyName | Improve this Doc View Source TraceShardCmdExecuted<TShard>(ILogger, String, String, TShard, Int64) Declaration public static void TraceShardCmdExecuted<TShard>(this ILogger logger, string commandName, string shardSetKey, TShard shardId, long milliseconds) where TShard : IComparable Parameters Type Name Description Microsoft.Extensions.Logging.ILogger logger System.String commandName System.String shardSetKey TShard shardId System.Int64 milliseconds Type Parameters Name Description TShard"
  },
  "api/ArgentSea.MapToModel.html": {
    "href": "api/ArgentSea.MapToModel.html",
    "title": "Class MapToModel | ArgentSea Docs",
    "keywords": "Class MapToModel Inheritance System.Object System.Attribute MapToModel Inherited Members System.Attribute.Equals(System.Object) System.Attribute.GetCustomAttribute(System.Reflection.Assembly, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.Assembly, System.Type, System.Boolean) System.Attribute.GetCustomAttribute(System.Reflection.MemberInfo, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.MemberInfo, System.Type, System.Boolean) System.Attribute.GetCustomAttribute(System.Reflection.Module, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.Module, System.Type, System.Boolean) System.Attribute.GetCustomAttribute(System.Reflection.ParameterInfo, System.Type) System.Attribute.GetCustomAttribute(System.Reflection.ParameterInfo, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Assembly) System.Attribute.GetCustomAttributes(System.Reflection.Assembly, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Assembly, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.Assembly, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.MemberInfo, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Module) System.Attribute.GetCustomAttributes(System.Reflection.Module, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.Module, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.Module, System.Type, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo, System.Boolean) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo, System.Type) System.Attribute.GetCustomAttributes(System.Reflection.ParameterInfo, System.Type, System.Boolean) System.Attribute.GetHashCode() System.Attribute.IsDefaultAttribute() System.Attribute.IsDefined(System.Reflection.Assembly, System.Type) System.Attribute.IsDefined(System.Reflection.Assembly, System.Type, System.Boolean) System.Attribute.IsDefined(System.Reflection.MemberInfo, System.Type) System.Attribute.IsDefined(System.Reflection.MemberInfo, System.Type, System.Boolean) System.Attribute.IsDefined(System.Reflection.Module, System.Type) System.Attribute.IsDefined(System.Reflection.Module, System.Type, System.Boolean) System.Attribute.IsDefined(System.Reflection.ParameterInfo, System.Type) System.Attribute.IsDefined(System.Reflection.ParameterInfo, System.Type, System.Boolean) System.Attribute.Match(System.Object) System.Attribute.TypeId System.Object.Equals(System.Object, System.Object) System.Object.GetType() System.Object.MemberwiseClone() System.Object.ReferenceEquals(System.Object, System.Object) System.Object.ToString() Namespace : ArgentSea Assembly : ArgentSea.dll Syntax [AttributeUsage(AttributeTargets.Property, Inherited = false, AllowMultiple = false)] public class MapToModel : Attribute"
  },
  "tutorials/Mapping/process.html": {
    "href": "tutorials/Mapping/process.html",
    "title": "Mapper Code | ArgentSea Docs",
    "keywords": "Mapper Code Because the work of the Mapper is compiled on the fly, its operation can seem opaque, especially when you are trying to debug problems. The Visual Studio debugger offers almost no help. Consequently, ArgentSea offers extensive tracing-level logging and also captures a rendering of the generated code as each model is compiled. This should assist in identifying any problems. In the sample applications, the default logger will write to the Visual Studio output window. Note Tracing requires a logging level of “Trace”; the generated code is only logged with the logging level of “Debug” or “Trace”. If you are curious about the mapping logic, examples are presented here which is based upon a sample Model. Or course, the actual code generated from a different Model or different set of metadata attributes will be different. The general logic, however, will be largely intact. Creating and Setting Input Parameters Some overloads of the CreateInputParameters methods allow you to specify parameters that should not be set. Any parameters already set are added to this list, so that this delegate does not attempt to add them again. This allows you to, say, set an output parameter before setting all the remaining input parameters with this method. SQL Server PostgreSQL public void CreateAndSetInputParameter(LocationModel model, DbParameterCollection parameters, HashSet<string> ignoreParameters, ILogger logger) { int? keyRecordId; short? keyChildId; logger.TraceInMapperProperty(\"Key\"); if (model.Key != ShardKey<short, int, short>.Empty) { keyRecordId = model.Key.RecordId; keyChildId = model.Key.ChildId; } else { keyRecordId = null; keyChildId = null; } if (ExpressionHelpers.DontIgnoreThisParameter(\"@CustomerId\", ignoreParameters)) { parameters.AddSqlIntInputParameter(\"@CustomerId\", keyRecordId) } if (ExpressionHelpers.DontIgnoreThisParameter(\"@LocationId\", ignoreParameters)) { parameters.AddSqlSmallIntInputParameter(\"@LocationId\", keyChildId) } logger.TraceInMapperProperty(\"Type\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@LocationTypeId\", ignoreParameters)) { parameters.AddSqlTinyIntInputParameter(\"@LocationTypeId\", (byte)model.Type) } logger.TraceInMapperProperty(\"StreetAddress\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@StreetAddress\", ignoreParameters)) { parameters.AddSqlNVarCharInputParameter(\"@StreetAddress\", model.StreetAddress, 255) } logger.TraceInMapperProperty(\"Locality\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@Locality\", ignoreParameters)) { parameters.AddSqlNVarCharInputParameter(\"@Locality\", model.Locality, 100) } logger.TraceInMapperProperty(\"Region\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@Region\", ignoreParameters)) { parameters.AddSqlNVarCharInputParameter(\"@Region\", model.Region, 100) } logger.TraceInMapperProperty(\"PostalCode\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@PostalCode\", ignoreParameters)) { parameters.AddSqlNVarCharInputParameter(\"@PostalCode\", model.PostalCode, 25) } logger.TraceInMapperProperty(\"Iso3166\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@Iso3166\", ignoreParameters)) { parameters.AddSqlNCharInputParameter(\"@Iso3166\", model.Iso3166, 2) } logger.TraceInMapperProperty(\"Latitude\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@Latitude\", ignoreParameters)) { parameters.AddSqlFloatInputParameter(\"@Latitude\", model.Latitude) } logger.TraceInMapperProperty(\"Longitude\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@Longitude\", ignoreParameters)) { parameters.AddSqlFloatInputParameter(\"@Longitude\", model.Longitude) } } public void CreateAndSetInputParameter(LocationModel model, DbParameterCollection parameters, HashSet<string> ignoreParameters, ILogger logger) { int? keyRecordId; short? keyChildId; logger.TraceInMapperProperty(\"Key\"); if (model.Key != ShardKey<short, int, short>.Empty) { keyRecordId = model.Key.RecordId; keyChildId = model.Key.ChildId; } else { keyRecordId = null; keyChildId = null; } if (ExpressionHelpers.DontIgnoreThisParameter(\"customerid\", ignoreParameters)) { parameters.AddPgIntegerInputParameter(\"customerid\", keyRecordId) } if (ExpressionHelpers.DontIgnoreThisParameter(\"locationid\", ignoreParameters)) { parameters.AddPgSmallintInputParameter(\"locationid\", keyChildId) } logger.TraceInMapperProperty(\"Type\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"locationtypeid\", ignoreParameters)) { parameters.AddPgSmallintInputParameter(\"locationtypeid\", (short)model.Type) } logger.TraceInMapperProperty(\"StreetAddress\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"streetaddress\", ignoreParameters)) { parameters.AddPgVarcharInputParameter(\"streetaddress\", model.StreetAddress, 255) } logger.TraceInMapperProperty(\"Locality\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"locality\", ignoreParameters)) { parameters.AddPgVarcharInputParameter(\"locality\", model.Locality, 100) } logger.TraceInMapperProperty(\"Region\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"region\", ignoreParameters)) { parameters.AddPgVarcharInputParameter(\"region\", model.Region, 100) } logger.TraceInMapperProperty(\"PostalCode\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"postalcode\", ignoreParameters)) { parameters.AddPgVarcharInputParameter(\"postalcode\", model.PostalCode, 25) } logger.TraceInMapperProperty(\"Iso3166\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"iso3166\", ignoreParameters)) { parameters.AddPgCharInputParameter(\"iso3166\", model.Iso3166, 2) } logger.TraceInMapperProperty(\"Latitude\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"latitude\", ignoreParameters)) { parameters.AddPgDoubleInputParameter(\"latitude\", model.Latitude) } logger.TraceInMapperProperty(\"Longitude\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"longitude\", ignoreParameters)) { parameters.AddPgDoubleInputParameter(\"longitude\", model.Longitude) } } Creating Out Parameters The code generated to set output parameters is very straightforward. This example is SQL Server-specific, but if you chose to use output parameters on another platform, the logic would be the same. public void CreateOutParameters (DbParameterCollection parameters, HashSet<string> ignoreParameters, ILogger logger) { logger.TraceSetOutMapperProperty(\"Key\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@CustomerId\", ignoreParameters)) { parameters.AddSqlIntOutputParameter(\"@CustomerId\"); } if (ExpressionHelpers.DontIgnoreThisParameter(\"@LocationId\", ignoreParameters)) { parameters.AddSqlSmallIntOutputParameter(\"@LocationId\"); } logger.TraceSetOutMapperProperty(\"Type\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@LocationTypeId\", ignoreParameters)) { parameters.AddSqlIntOutputParameter(\"@LocationTypeId\"); } logger.TraceSetOutMapperProperty(\"StreetAddress\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@StreetAddress\", ignoreParameters)) { parameters.AddSqlNVarCharOutputParameter(\"@StreetAddress\", 255); } logger.TraceSetOutMapperProperty(\"Locality\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@Locality\", ignoreParameters)) { parameters.AddSqlNVarCharOutputParameter(\"@Locality\", 100); } logger.TraceSetOutMapperProperty(\"Region\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@Region\", ignoreParameters)) { parameters.AddSqlNVarCharOutputParameter(\"@Region\", 100); } logger.TraceSetOutMapperProperty(\"PostalCode\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@PostalCode\", ignoreParameters)) { parameters.AddSqlNVarCharOutputParameter(\"@PostalCode\", 25); } logger.TraceSetOutMapperProperty(\"Iso3166\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@Iso3166\", ignoreParameters)) { parameters.AddSqlNCharOutputParameter(\"@Iso3166\", 2); } logger.TraceSetOutMapperProperty(\"Latitude\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@Latitude\", ignoreParameters)) { parameters.AddSqlFloatOutputParameter(\"@Latitude\"); } logger.TraceSetOutMapperProperty(\"Longitude\"); if (ExpressionHelpers.DontIgnoreThisParameter(\"@Longitude\", ignoreParameters)) { parameters.AddSqlFloatOutputParameter(\"@Longitude\"); } } Reading Out Parameters This example evaluates only a few output parameters: Customer key, CustomerType, and Customer Name. The Key and Name properties are required, so we consider database Null values to represent no record. Notably, this example handles a ShardKey value. If the ShardId parameter had been specified, it would have been captured and evaluated like the RecordId parameter; if either were null then the ShardKey value would be empty. However, since no ShardId parameter was specified, the code uses the shardId of the current shard, which is provided to the procedure as an argument. public Customer ReadOutParameters(short shardId, DbParameterCollection parameters, ILogger logger) { var model = new CustomerModel(); DbParameter prm; short? keyShardId; int? keyRecordId; logger.TraceGetOutMapperProperty(\"Key_RecordId\"); prm = ExpressionHelpers.GetParameter(parameters, \"CustomerId\"); if (prm != null) { keyShardId = prm.GetNullableInteger(); } else { logger.SqlParameterNotFound(\"@CustomerId\", typeof(int?)); }; if (ExpressionHelpers.IsRequiredParameterDbNull(prm, \"CustomerModel\", \"@CustomerId\", logger)) { return null; } logger.TraceGetOutMapperProperty(\"Name\"); prm = ExpressionHelpers.GetParameter(parameters, \"@Name\"); if (ExpressionHelpers.IsRequiredParameterDbNull(prm, \"CustomerModel\", \"@Name\", logger)) { return null; } if (prm != null) { model.Name = prm.GetString(); } logger.TraceGetOutMapperProperty(\"Type\"); prm = ExpressionHelpers.GetParameter(parameters, \"@CustomerTypeId\"); if (prm != null) { model.Type = (CustomerType)prm.GetShort(); } else { logger.SqlParameterNotFound(\"@CustomerTypeId\", typeof(CustomerType)); } keyShardId = shardId; if (keyShardId != null && keyRecordId != null) { model.Key = ShardKey<short, int>('C', keyShardId.Value, keyRecordId.Value); } else { model.Key = ShardKey<short, int>.Empty; }; } Data Reader Queries Queries involving the data reader follows these steps for each result set: Use generated code to build an array of column ordinal positions based on the expected column names. Create a list result, then loop through each record in the result set. For each record in the result set, call a generated function which returns a new Model object with property values set to the corresponding columns values. Return a list of the new Model objects. The initial capture of ordinal positions is a performance optimization, since the column positions will not change and accessing a column by name always requires a ordinal lookup. This also means that a change in column order — or additional columns — will not break the code logic. Consequently, the same model class can be used for different queries, each of which may not return exactly the same results. An expected column that is not found will be logged (at “Debug” logging level), but subsequently ignored. (If you are curious, the type information passed to the GetFieldOrdinal method is for logging). The code looks like this: public int[] GetOrdinals(DbDataReader rdr, ILogger logger) { return new[] { GetFieldOrdinal(rdr, \"customerid\", \"System.Nullable`1[System.Int32]\", logger), GetFieldOrdinal(rdr, \"locationid\", \"System.Nullable`1[System.Int16]\", logger), GetFieldOrdinal(rdr, \"locationtypeid\", \"QuickStart2.Pg.Models.LocationModel+LocationType\", logger), GetFieldOrdinal(rdr, \"streetaddress\", \"System.String\", logger), GetFieldOrdinal(rdr, \"locality\", \"System.String\", logger), GetFieldOrdinal(rdr, \"region\", \"System.String\", logger), GetFieldOrdinal(rdr, \"postalcode\", \"System.String\", logger), GetFieldOrdinal(rdr, \"iso3166\", \"System.String\", logger), GetFieldOrdinal(rdr, \"latitude\", \"System.Double\", logger), GetFieldOrdinal(rdr, \"longitude\", \"System.Double\", logger) }; } Reading through the DataReader rows does not require Mapper generated code. For each new row, the system calls a second delegate, which was also generated and compiled based upon the attribute metadata. The row-handing delegate assesses the current row and returns a model with properties set to data values. Here are a few notes about the code: Ordinal values of -1 indicate that the column was not found, in which case the property will be ignored. The Trace logging commands might be useful in determining the Mapper’s last operation before an unexpected failure. In this example, the ShardId is obtained from the connection’s property. If the MapToShardKey attribute had specified a ShardId column, the code would instead be obtained a value from a database column. public LocationModel ReadData(short shardId, int[] ordinals, DbDataReader rdr, ILogger logger) { var model = new LocationModel(); var ordinal = ordinals[0]; short? keyShardId = shardId; int? keyRecordId; int? keyChildId; logger.TraceGetOutMapperProperty(\"Key_RecordId\"); if (ordinal != -1) { if (rdr.IsDBNull(ordinal)) { keyRecordId = null; } else { keyRecordId = (int?)rdr.GetFieldValue<int>(ordinal); } } logger.TraceGetOutMapperProperty(\"Key_ChildId\"); ordinal = ordinals[1]; if (ordinal != -1) { if (rdr.IsDBNull(ordinal)) { keyChildId = null; } else { keyChildId = (int?)rdr.GetFieldValue<short>(ordinal); } } if (keyShardId != null && keyRecordId != null && keyChildId != null) { model.Key = new ShardKey<short, int, short>('L', keyShardId.Value, keyRecordId.Value, keyChildId.Value); } else { model.Key = ShardKey<short, int, short>().Empty; } logger.TraceRdrMapperProperty(\"Type\"); ordinal = ordinals[2]; if (ordinal != -1) { model.Type = (LocationType)rdr.GetFieldValue<short>(ordinal); } logger.TraceRdrMapperProperty(\"StreetAddress\"); ordinal = ordinals[3]; if (ordinal != -1) { if (rdr.IsDBNull(ordinal)) { model.StreetAddress = null; } else { model.StreetAddress = rdr.GetString(ordinal); } }; logger.TraceRdrMapperProperty(\"Locality\"); ordinal = ordinals[4]; if (ordinal != -1) { if (rdr.IsDBNull(ordinal)) { model.Locality = null; } else { model.Locality = rdr.GetString(ordinal); } } logger.TraceRdrMapperProperty(\"Region\"); ordinal = ordinals[5]; if (ordinal != -1) { if (rdr.IsDBNull(ordinal)) { model.Region = null; } else { model.Region = rdr.GetString(ordinal); } }; logger.TraceRdrMapperProperty(\"PostalCode\"); ordinal = ordinals[6]; if (ordinal != -1) { if (rdr.IsDBNull(ordinal)) { model.PostalCode = null; } else { model.PostalCode = rdr.GetString(ordinal); } }; logger.TraceRdrMapperProperty(\"Iso3166\"); ordinal = ordinals[7]; if (ordinal != -1) { if (rdr.IsDBNull(ordinal)) { model.Iso3166 = null; } else { model.Iso3166 = rdr.GetString(ordinal); } } logger.TraceRdrMapperProperty(\"Latitude\"); ordinal = ordinals[8]; if (ordinal != -1) { if (rdr.IsDBNull(ordinal)) { (model.Coordinates).Latitude = double.NaN; } else { (model.Coordinates).Latitude = rdr.GetFieldValue<double>(ordinal); } }; logger.TraceRdrMapperProperty(\"Longitude\"); ordinal = ordinals[9]; if (ordinal != -1) { if (rdr.IsDBNull(ordinal)) { (model.Coordinates).Longitude = double.NaN; } else { (model.Coordinates).Longitude = rdr.GetFieldValue<double>(ordinal) } }; return model; } Create a Complex Result Some of the Mapper’s methods allow you to specify multiple generic arguments. These specify both the base return type and the types for various List properties. This complex model construction is broken down into component steps: Create a base model object, either from a single-record data reader result, from output parameters, or (failing those options) by creating a new instance. Match the type of each List parameter to any Model property of the same type, and assign the property to the List parameter value. Repeat the List matching until all parameters have been assigned. Warning Note that due to this logic, the Mapper cannot manage multiple List properties of the same type. ArgentSea uses reflection to determine which assignable properties match the expected list types, then it builds and compiles a delegate that performs the assignment. This avoids reflection overhead in future cases. In this example, the Customer model has two list properties: Locations and Contacts. The generated code is straightforward: public CustomerModel CreateComplexModel( string queryName, DbDataReader, IList<CustomerModel> rstResult0, IList<LocationModel> rstResult1, IList<ContactModel> rstResult2, ILogger logger) { var model = AssignRootToResult<TModel>(queryName, rstResult0, logger); if (model == null) { return null; } model.Locations = rstResult1; model.Contacts = rstResult2; return model; } Loading Multiple Records SQL Server PostgreSQL SQL Server used Table Valued Parameters to send multple records to a stored procedure. The logic that iterates over the Model list does not require generated code. However, for each item in the Model list, the system calls a generated delegate to convert the Model instance to a SqlDataRecord . public SqlDataRecord SetTvpRow(LocationModel model, IList<string> columnList, ILogger logger) { int? keyRecordId; short? keyChildId; var fields = new SqlMetaData[10] { new SqlMetaData(\"CustomerId\", SqlDbType.Int), new SqlMetaData(\"LocationId\", SqlDbType.SmallInt), new SqlMetaData(\"LocationTypeId\", SqlDbType.TinyInt), new SqlMetaData(\"StreetAddress\", SqlDbType.NVarChar, 255L), new SqlMetaData(\"Locality\", SqlDbType.NVarChar, 100L), new SqlMetaData(\"Region\", SqlDbType.NVarChar, 100L), new SqlMetaData(\"PostalCode\", SqlDbType.NVarChar, 25L), new SqlMetaData(\"Iso3166\", SqlDbType.NChar, 2L), new SqlMetaData(\"Latitude\", SqlDbType.Float), new SqlMetaData(\"Longitude\", SqlDbType.Float) }; var result = new SqlDataRecord(GetRecordDataFields(fields, columnList)); logger.TraceTvpMapperProperty(\"Key\"); if (model.Key != ShardKey<short, int, short>.Empty) { keyRecordId = model.Key.RecordId; } else { keyRecordId = null; } if (TvpExpressionHelpers.IncludeThisColumn(\"CustomerId\", columnList)) { if (keyRecordId.HasValue) { result.SetInt32(TvpExpressionHelpers.GetOrdinal(0, \"CustomerId\", columnList), keyRecordId.Value); } else { result.SetDBNull(TvpExpressionHelpers.GetOrdinal(0, \"CustomerId\", columnList)); } } if (model.Key != ArgentSea.ShardKey<short, int, short>.Empty) { KeyChildId = model.Key.ChildId; } else { keyChildId = null; } if (TvpExpressionHelpers.IncludeThisColumn(\"LocationId\", columnList)) { if (keyChildId.HasValue)) { result.SetInt16(TvpExpressionHelpers.GetOrdinal(1, \"LocationId\", columnList), keyChildId.Value); } else { result.SetDBNull(TvpExpressionHelpers.GetOrdinal(1, \"LocationId\", columnList)); } } logger.TraceTvpMapperProperty(\"Type\"); if (TvpExpressionHelpers.IncludeThisColumn(\"LocationTypeId\", columnList)) { result.SetByte(TvpExpressionHelpers.GetOrdinal(2, \"LocationTypeId\", columnList), (byte)model.Type); } logger.TraceTvpMapperProperty(\"StreetAddress\"); if (TvpExpressionHelpers.IncludeThisColumn(\"StreetAddress\", columnList)) { if (model.StreetAddress == null) { result.SetDBNull(TvpExpressionHelpers.GetOrdinal(3, \"StreetAddress\", columnList)); } else { result.SetString(TvpExpressionHelpers.GetOrdinal(3, \"StreetAddress\", columnList), model.StreetAddress); } } logger.TraceTvpMapperProperty(\"Locality\"); if (TvpExpressionHelpers.IncludeThisColumn(\"Locality\", columnList)) { if (model.Locality == null) { result.SetDBNull(TvpExpressionHelpers.GetOrdinal(4, \"Locality\", columnList)); } else { result.SetString(TvpExpressionHelpers.GetOrdinal(4, \"Locality\", columnList), model.Locality); } } logger.TraceTvpMapperProperty(\"Region\"); if (TvpExpressionHelpers.IncludeThisColumn(\"Region\", columnList)) { if (model.Region == null) { result.SetDBNull(TvpExpressionHelpers.GetOrdinal(5, \"Region\", columnList)); } else { result.SetString(TvpExpressionHelpers.GetOrdinal(5, \"Region\", columnList), model.Region); } } logger.TraceTvpMapperProperty(\"PostalCode\"); if (TvpExpressionHelpers.IncludeThisColumn(\"PostalCode\", columnList)) { if (model.PostalCode == null) { result.SetDBNull(TvpExpressionHelpers.GetOrdinal(6, \"PostalCode\", columnList)); } else { result.SetString(TvpExpressionHelpers.GetOrdinal(6, \"PostalCode\", columnList), model.PostalCode); } } logger.TraceTvpMapperProperty(\"Iso3166\"); if (TvpExpressionHelpers.IncludeThisColumn(\"Iso3166\", columnList)) { if (model.Iso3166 == null) { result.SetDBNull(TvpExpressionHelpers.GetOrdinal(7, \"Iso3166\", columnList)); } else { result.SetString(TvpExpressionHelpers.GetOrdinal(7, \"Iso3166\", columnList), model.Iso3166); } } logger.TraceTvpMapperProperty(\"Latitude\"); if (TvpExpressionHelpers.IncludeThisColumn(\"Latitude\", columnList)) { if (Double.IsNaN(model.Coordinates.Latitude)) { result.SetDBNull(TvpExpressionHelpers.GetOrdinal(8, \"Latitude\", columnList)); } else { result.SetDouble(TvpExpressionHelpers.GetOrdinal(8, \"Latitude\", columnList), model.Coordinates.Latitude); } } logger.TraceTvpMapperProperty(\"Longitude\"); if (TvpExpressionHelpers.IncludeThisColumn(\"Longitude\", columnList)) { if (Double.IsNaN(model.Coordinates.Longitude)) { result.SetDBNull(TvpExpressionHelpers.GetOrdinal(9, \"Longitude\", columnList)); } else { result.SetDouble(TvpExpressionHelpers.GetOrdinal(9, \"Longitude\", columnList), model.Coordinates.Longitude); } } return result; } PostgreSQL uses the Npgsql COPY functionality to send multple records to the database. The COPY function may use an new, existing, or temporary table. If a period (schema specifier) exists in the table name, then a “CREATE TABLE IF NOT EXISTS” command is used, otherwise the Mapper uses “CREATE TEMP TABLE”. CREATE TEMP TABLE \"temp_locations\" ( \"locationid\" smallint NULL, \"locationtypeid\" smallint NULL, \"streetaddress\" varchar(255) NULL, \"locality\" varchar(100) NULL, \"region\" varchar(100) NULL, \"postalcode\" varchar(25) NULL, \"iso3166\" varchar(2) NULL, \"latitude\" double precision NULL, \"longitude\" double precision NULL); Once the table is created (if necessary), the Mapper sends the SQL command to initiate the PostgreSQL COPY command: COPY \"temp_locations\" (\"locationid\",\"locationtypeid\",\"streetaddress\",\"locality\",\"region\",\"postalcode\",\"iso3166\",\"latitude\",\"longitude\") FROM STDIN BINARY; Finally, the Mapper opens a NpgsqlDataImporter . For each item in the Model List, the Mapper invokes this generated code: public void SetRow(NpgsqlDataImporter importer, CustomerLocation model) importer.StartRow(); importer.Write(model.Sequence, NpgsqlDbType.Smallint); importer.Write(model.Type, NpgsqlDbType.Smallint); if (model.StreetAddress == null) { importer.WriteNull(); } else { importer.Write(model.StreetAddress, NpgsqlDbType.Varchar); } if (model.Locality == null) { importer.WriteNull(); } else { importer.Write(model.Locality, NpgsqlDbType>(Varchar); } if (model.Region == null) { importer.WriteNull(); } else { importer.Write(model.Region, NpgsqlDbType>(Varchar); } if (model.PostalCode == null) { importer.WriteNull(); } else { importer.Write(model.PostalCode, NpgsqlDbType.Varchar); } if (model.Iso3166 == null) { importer.WriteNull(); } else { importer.Write(model.Iso3166, NpgsqlDbType.Varchar); } if (Double.IsNaN((model.Coordinates.Latitude)) { importer.WriteNull(); } else { importer.Write(model.Coordinates.Latitude, NpgsqlDbType.Double) }; if (Double.IsNaN((model.Coordinates.Longitude) { importer.WriteNull(); } else { importer.Write(model.Coordinates.Longitude, NpgsqlDbType>(Double); } } Now that the table “temp_locations” has the corresponding records, it only takes a straightforward SQL statement to write these values into the final table (presuming that the COPY function isn’t writing to the final destination). ArgentSea’s Batch functionality allows multiple steps to operation on the same transaction, so temporary tables are not dropped prior to SQL statement execution. Next: Logging"
  },
  "tutorials/setup.html": {
    "href": "tutorials/setup.html",
    "title": "ArgentSea Setup | ArgentSea Docs",
    "keywords": "ArgentSea Setup ArgentSea is a .NET Standard application, which means it should work with .NET Core, Xamarin, and the .NET Framework 4.6.1 or higher. However, ArgentSea depends on services provided by .NET Core — like logging and dependency injection — that may require “coercion” in the other environments. Because data sharding is difficult to add to an existing application, the general assumption is that consumers would be new applications created using .Net Core. If you use another framework, please help with the documentation! (And tell us if there is demand for a NuGet package targeting your framework). Setup Steps Only a few steps are necessary to use ArgentSea in your project: Install the appropriate NuGet package. Define the configuration metadata, usually in appsettings.json Load the configuration and injectable Services in your Startup class. Decorate your model classes with data attributes (optional). Invoke data access methods from the Databases or ShardSets services. NuGet There are currently two versions of ArgentSea: one for SQL Server and the other for PostgreSQL. To include ArgentSea into your project, simply search NuGet for ArgentSea.Sql (SQL Server) or ArgentSea.Pg (PostgreSQL). Both packages install a shared ArgentSea package (which has most of the actual code). Consequently, there are two namespaces; some objects will be in the ArgentSea namespace; others will be in the ArgentSea.Sql or ArgentSea.Pg namespace. Note You may be able to include multiple provider packages in your project (i.e. both PostgreSQL and SQL Server), but this is not a tested scenario. You cannot have a single model class that includes provider attributes from different providers; this is, you can’t use the same model class to read/write to both SQL Server and PostgreSQL. If you need to reference different database providers, the practical solution would be to use different projects (microservices). Dependencies ArgentSea has very few dependencies. Other than a few Microsoft packages (logging, configuration, options, and immutable collections), the only dependency is upon Polly . Of course, the data platform libraries each take a dependency upon their respective ADO.NET libraries, SqlClient and Npgsql . Next: Configuration"
  }
}