IDialect Interface
Assembly: CodeEffects.Rule.Connection.dll
Namespace: CodeEffects.Rule.Connection
Summary
Supplies everything in SQL that differs from one database to another: the quoting of names, parameter markers, paging, the classification of failures, and the construction of parameters. The Code Effects libraries ask it for these and write the rest of their statements in plain SQL.
Syntax
public interface IDialect
This interface is the library's own concern. You get a dialect from the provider of your database, for example the Dialect property of CodeEffects.Rule.Connection.SqlServer.DbProvider, and return it from IDbProvider.Dialect. Hosts use the dialect libraries' providers, and rarely implement or call this interface. Implement it only to support a database that no dialect library covers.
The statements of the libraries follow rules that a dialect can rely on:
- Tables are named through
Table(..). Table and column names are written unquoted and are never reserved words.
- Parameters are written with
ParameterMarker(..) and created with CreateParameter(..) or CreateLargeTextParameter(..), both by their bare name.
- Each command holds one statement, without a trailing semicolon.
- A statement never uses an
UPDATE with a table alias or a FROM clause. Correlated subqueries that name the target table in full are used instead.
- The number of affected rows comes from the command, never from a SQL function.
Properties
Methods
Classify
Returns: CodeEffects.Rule.Connection.DbFailureKind - What kind of failure the exception represents.
Classifies an exception that was thrown while talking to the database. The libraries use the answer to decide whether to run the work again and which control number to report. The method walks the inner exceptions, because the exception of the ADO.NET provider usually arrives wrapped.
Parameters
- exception (
System.Exception) - The exception to classify.
ContainsPattern
Returns: System.String - The pattern, wildcards included.
Returns a LIKE pattern that matches the value anywhere in a string. Every character that the database treats as a wildcard is escaped with !. Statements use it as LOWER(column) LIKE LOWER(marker) ESCAPE '!', which is case-insensitive whatever the collation of the column.
Parameters
- value (
System.String) - The text to look for.
CreateLargeTextParameter
Returns: CodeEffects.Rule.Connection.ParameterInfo - The parameter.
Builds a parameter that is sized and typed for a large text column, such as NVARCHAR(MAX) on SQL Server.
Parameters
- name (
System.String) - The bare name of the parameter, without a marker.
- value (
System.String) - The text.
CreateParameter
Returns: CodeEffects.Rule.Connection.ParameterInfo - The parameter.
Builds an ordinary parameter. A null value is sent as a database null.
Parameters
- name (
System.String) - The bare name of the parameter, without a marker.
- value (
System.Object) - The value.
-
Returns: System.String - The clause.
Returns the clause that limits a query to its first rows. The libraries append it after ORDER BY, which the statement must have.
Parameters
- n (
System.Int32) - The number of rows to return.
-
Returns: System.String - The clause.
Returns the clause that skips some rows and returns the next ones. The libraries append it after ORDER BY, which the statement must have.
Parameters
- skip (
System.Int32) - The number of rows to skip.
- take (
System.Int32) - The number of rows to return after them.
InsertReturningId
Returns: System.String - The statement.
Returns an INSERT of one row that yields the identity column of the new row as the single scalar result of the statement.
Parameters
- table (
System.String) - The table, as Table(..) returns it.
- columns (
System.String) - The comma-separated list of columns.
- values (
System.String) - The comma-separated list of values, parameter markers included.
- idColumn (
System.String) - The identity column to return.
NewSequentialId
Returns: System.Guid - A new GUID.
Returns a new GUID that sorts after every GUID that this process made before it, in the order that the database uses for GUIDs. Rows keyed by these GUIDs are appended to a clustered index instead of being scattered through it. The Audit library keys every evaluation that it records by one. A GUID is unique across processes and machines; only its order is local to the process.
Parameters
ParameterMarker
Returns: System.String - The marker followed by the name.
Returns how a parameter is referenced in the text of a statement. For SQL Server it is @name.
Parameters
- name (
System.String) - The bare name of the parameter.
QuoteIdentifier
Returns: System.String - The quoted name.
Returns an identifier quoted for the database, such as [name] for SQL Server. The libraries use it for the schema name, which you choose and which may need quoting.
Parameters
- name (
System.String) - The identifier to quote.
Table
Returns: System.String - The table name, qualified when a schema is given.
Returns a table name qualified with the schema, or the bare table name when the schema name is empty.
Parameters
- schemaName (
System.String) - The schema, as IDbProvider.SchemaName returns it.
- tableName (
System.String) - The table.
Example
using System;
using CodeEffects.Rule.Connection;
IDialect d = dbProvider.Dialect;
string table = d.Table(dbProvider.SchemaName, "SettingRecord");
string sql = "SELECT * FROM " + table + " ORDER BY SettingName " + d.FormatPaging(0, 20);
DbFailureKind kind = d.Classify(new TimeoutException());
Console.WriteLine(sql + " " + kind);