XML File Format

This article is relevant to entity models that utilize the deprecated Visual Studio integration of Telerik Data Access. The current documentation of the Data Access framework is available here.

A typical external XML mapping file consists of a <orm> element for defining a metadata mapping source. This is the root element and it has two child elements:

• <namespace> - defines the object model used by an application built on Telerik Data Access. It may have the following child elements:
  • <class>
  • <identity>
  • <concurrency>
  • <field>
  • <index>
  • <procedures>
• <schema> - describes the backend database. It may have the following child elements:
  • <table>
  • <procedure>

<?xml version="1.0" encoding="utf-8"?>
<DomainModel xmlns:dm0="http://schemas.microsoft.com/VisualStudio/2008/DslTools/Core"
            dslVersion="2.0.0.0" name="EntitiesModel" namespace="MetadataDemo"
            showPropertiesCompartment="true" xmlns="http://www.telerik.com/ORM">
 <orm:orm name="EntitiesModel" backend="mssql" xmlns:orm="http://tempuri.org/ORM">
   <orm:namespace name="MetadataDemo" default="true">
     <!--Persistent classes description and database mapping-->
   </orm:namespace>
   <orm:schema schema="">
     <!--Database description-->
   </orm:schema>
 </orm:orm>
</DomainModel>

The <namespace> Element

The <namespace> element defines the object model used by an application built on Telerik Data Access. The <namespace> element declared in the external mapping XML file will be the namespace name that qualifies the persistent classes in the generated object model. Also each type defined inside the <namespace> element is mapped to metadata describing the storage model. The <namespace> element may contain one or more <class> child elements.

The <class> Element

The <class> element is a formal description of a persistent class used in an application built on Telerik Data Access. Each class is mapped to a single database table. This is done via the <table> child element, like in the example below. Note that the name attribute is used to specify the class name, as well as the corresponding table name.

<orm:class name="Category" behavior="readwrite" uniqueId="c1d2af1e-e8f7-435a-a04d-6c9b8edf85a5">
 <orm:table name="Categories" />
</orm:class>

The <identity> Element

For each class an identity must be specified. Via the <identity> child element is described the way in which Telerik Data Access will manage the primary key generation. Two types of identities are supported: <single-field> or <multiple-field>. In case of <single-field> identity, the field that will hold the identity information must be specified, and Telerik Data Access manages the rest. In case of <multiple-field> identity each primary key field must be counted as nested <single-field> element. The last element used for the identity declaration is the <key-generator> element. The <key-generator> element is optional.

The example below describes a new class named Category that is maped to the Categories table and declares a single-field identity.

<orm:class name="Category" behavior="readwrite" uniqueId="c1d2af1e-e8f7-435a-a04d-6c9b8edf85a5">
 <orm:table name="Categories" />
 <orm:identity>
   <orm:key-generator name="autoinc" />
   <orm:single-field field-name="_categoryID" />
 </orm:identity>
</orm:class>

Note the way in which the identity field is specified - via the field-name attribute.

The next example declares a new object named OrderDetail, and maps it to the OrderDetails table. However, this time a <multiple-field> identity is used. Note the way in which the <multiple-field> identity is defined - nested <single-field> elements are used.

<orm:class name="OrderDetail" behavior="readwrite" 
    uniqueId="81309abd-5c62-411f-94bf-472746426947">
 <orm:table name="Order Details" />
 <orm:identity>
   <orm:multiple-field>
     <orm:single-field field-name="_orderID" />
     <orm:single-field field-name="_productID" />
   </orm:multiple-field>
 </orm:identity>
</orm:class>

The <concurrency> Element

After the <identity> element is specified, the next step is the optimistic concurrency control for the class to be specified. This is done via the <concurrency> element. Optimistic concurrency control prevents changes made in one transaction from overwriting changes committed by another transaction, after the instance in the first transaction had been read. Telerik Data Access supports the following verification methods:

• none - do not detect concurrent updates.
• version - this is the default method for optimistic concurrency control.
• timestamp - use a timestamp column to detect concurrent updates. The timestamp is set on every update and the previous value is included in the where clause.
• changed - include the previous value of all changed columns in the where clause. This provides more fine-grained optimistic concurrency control as different transactions may modify different fields of the same instance.
• backend - uses backend - specific concurrency control.

The example below declares the Category class and sets its <concurrency> element.

<orm:class name="Category" behavior="readwrite" uniqueId="c1d2af1e-e8f7-435a-a04d-6c9b8edf85a5">
 <orm:table name="Categories" />
 <orm:identity>
   <orm:key-generator name="autoinc" />
   <orm:single-field field-name="_categoryID" />
 </orm:identity>
 <orm:concurrency strategy="changed" />
</orm:class>

The <field> Element

The <field> element is used to specify a concrete field of the class. Four attributes additionally describe the field as well as the property to which it is related. Each <field> element should be mapped to a corresponding table column in the database. This is done via a nested <column> element.

The next example defines all fields of the Category class.

<orm:class name="Category" behavior="readwrite" uniqueId="c1d2af1e-e8f7-435a-a04d-6c9b8edf85a5">
 <orm:table name="Categories" />
 <orm:identity>
   <orm:key-generator name="autoinc" />
   <orm:single-field field-name="_categoryID" />
 </orm:identity>
 <orm:concurrency strategy="changed" />
 <orm:field name="_categoryID" property="CategoryID" behavior="readwrite" 
    uniqueId="dae7474b-2b21-401a-bc55-f709168ae6de" type="System.Int32">
   <orm:column name="CategoryID" sql-type="int" nullable="false" length="0" scale="0" 
    primary-key="true" backend-calculated="true" ado-type="Int32" />
 </orm:field>
 <orm:field name="_categoryName" property="CategoryName" behavior="readwrite" 
    uniqueId="95bf1bf7-5af8-46a3-a02b-c9fcf39fa776" type="System.String">
   <orm:column name="CategoryName" sql-type="nvarchar" nullable="false" length="15" scale="0" 
    ado-type="Varchar" />
 </orm:field>
 <orm:field name="_description" property="Description" behavior="readwrite" 
    uniqueId="ef6878d0-edbe-4597-b1f4-9b4848f4c065" type="System.String">
   <orm:column name="Description" sql-type="ntext" nullable="true" length="0" scale="0" 
    ado-type="Clob" />
 </orm:field>
 <orm:field name="_picture" property="Picture" behavior="readwrite" 
    uniqueId="76ad6d92-6011-4c92-9998-b9c7ba75e280" type="System.Byte[]">
   <orm:column name="Picture" sql-type="image" nullable="true" length="0" scale="0" 
    ado-type="LongVarBinary" />
 </orm:field>
 <orm:field name="_products" property="Products" behavior="readwrite" 
    uniqueId="4c66f667-3d2f-4c84-9ddd-8c5007487212" type="MetadataDemo.Product">
   <orm:collection element-class="MetadataDemo.Product" inverse-field="_category" 
    order-by="" uniqueId="987f18d1-2295-4f24-8653-edb9931de164" />
 </orm:field>
</orm:class>

The <index> Element

The <index> element specifies the index column\field for the current table\class.

<orm:class name="Category" behavior="readwrite" uniqueId="c1d2af1e-e8f7-435a-a04d-6c9b8edf85a5">
 <orm:table name="Categories" />
 <orm:identity>
   <orm:key-generator name="autoinc" />
   <orm:single-field field-name="_categoryID" />
 </orm:identity>
 <orm:concurrency strategy="changed" />
 <orm:index name="CategoryName" sort-order="descending">
   <orm:columnMapping>
     <orm:column name="CategoryName" sql-type="nvarchar" nullable="false" length="15" 
        scale="0" ado-type="Varchar" />
   </orm:columnMapping>
 </orm:index>
</orm:class>

The <procedures> Element

The <procedures> element describes the stored procedures used for the create, update, delete operations. Check out the <procedure> section in this topic for more information.

<orm:class name="Category" behavior="readwrite" uniqueId="c1d2af1e-e8f7-435a-a04d-6c9b8edf85a5">
 <orm:table name="Categories" />
 <orm:identity>
   <orm:key-generator name="autoinc" />
   <orm:single-field field-name="_categoryID" />
 </orm:identity>
 <orm:concurrency strategy="changed" />
 <orm:field name="_categoryID" property="CategoryID" behavior="readwrite" 
    uniqueId="dae7474b-2b21-401a-bc55-f709168ae6de" type="System.Int32">
   <orm:column name="CategoryID" sql-type="int" nullable="false" length="0" scale="0" 
    primary-key="true" backend-calculated="true" ado-type="Int32" />
 </orm:field>
 <orm:field name="_categoryName" property="CategoryName" behavior="readwrite" 
    uniqueId="95bf1bf7-5af8-46a3-a02b-c9fcf39fa776" type="System.String">
   <orm:column name="CategoryName" sql-type="nvarchar" nullable="false" length="15" 
    scale="0" ado-type="Varchar" />
 </orm:field>
 <orm:field name="_description" property="Description" behavior="readwrite" 
    uniqueId="ef6878d0-edbe-4597-b1f4-9b4848f4c065" type="System.String">
   <orm:column name="Description" sql-type="ntext" nullable="true" length="0" scale="0" 
    ado-type="Clob" />
 </orm:field>
 <orm:field name="_picture" property="Picture" behavior="readwrite" 
    uniqueId="76ad6d92-6011-4c92-9998-b9c7ba75e280" type="System.Byte[]">
   <orm:column name="Picture" sql-type="image" nullable="true" length="0" 
    scale="0" ado-type="LongVarBinary" />
 </orm:field>
 <orm:field name="_products" property="Products" behavior="readwrite" 
    uniqueId="4c66f667-3d2f-4c84-9ddd-8c5007487212" type="MetadataDemo.Product">
   <orm:collection element-class="MetadataDemo.Product" inverse-field="_category" 
    order-by="" uniqueId="987f18d1-2295-4f24-8653-edb9931de164" />
 </orm:field>
 <orm:index name="CategoryName">
   <orm:columnMapping>
     <orm:column name="CategoryName" sql-type="nvarchar" nullable="false" length="15" 
        scale="0" ado-type="Varchar" />
   </orm:columnMapping>
 </orm:index>
 <orm:procedures>
   <orm:insert autoinc-parameter="true" use-default-mapping="true" />
   <orm:update use-default-mapping="true" />
   <orm:delete use-default-mapping="true" />
 </orm:procedures>
</orm:class>

The <schema> Element

The <schema> element is a formal description of the database that persists data for an application built on Telerik Data Access metadata model. The tables, views, stored procedures and associations are declared inside this element and they are the basis for mapping persistent classes and associations in the conceptual layer to the corresponding objects in the storage model. The <schema> element may contain one or more <table> or <procedure> child elements.

The <table> Element

The <table> element definition in the external mapping XML file specifies that a table or view exists in the database. Since Telerik Data Access treats tables and views in the same manner, the <table> element is used to describe both of the types. The name of the table\view is specified via the name attribute. An additional view attribute is used to specify whether the described database type is a table or a view. The view attribute is optional. If it is not specified, then the currently described type is a table. Nested column elements (<column>) specify the names of the columns and their data types. These definitions identify columns that can be mapped to a class' fields. Several attributes should be specified for the <column> element, in order to be fully qualified:

• name - specifies the name of the column.
• sql-type - specifies the sql type for the column (e.g.: ntext, int, nvarchar, money, etc.).
• nullable - specifies whether the column is nullable.
• length - specifies the length (or precision) of the database column.
• primary-key - specifies whether the column is a primary key.
• backend-calculated - specifies whether the column is backend calculated.
• ado-type - specifies the ado type for the parameter.

The following XML declarations specify two tables and one view: Categories, Employees, and Summary of Sales by Year.

<orm:table name="Employees">
 <orm:column name="EmployeeID" sql-type="int" nullable="false" length="0" scale="0" 
    primary-key="true" backend-calculated="true" ado-type="Int32" />
 <orm:column name="LastName" sql-type="nvarchar" nullable="false" length="20" scale="0" 
    ado-type="Varchar" />
 <orm:column name="FirstName" sql-type="nvarchar" nullable="false" length="10" scale="0" 
    ado-type="Varchar" />
 <orm:column name="Title" sql-type="nvarchar" nullable="true" length="30" scale="0" 
    ado-type="Varchar" />
 <orm:column name="TitleOfCourtesy" sql-type="nvarchar" nullable="true" length="25" 
    scale="0" ado-type="Varchar" />
 <orm:column name="BirthDate" sql-type="datetime" nullable="true" length="0" scale="0" 
    ado-type="DateTime" />
 <orm:column name="HireDate" sql-type="datetime" nullable="true" length="0" scale="0" 
    ado-type="DateTime" />
 <orm:column name="Address" sql-type="nvarchar" nullable="true" length="60" scale="0" 
    ado-type="Varchar" />
 <orm:column name="City" sql-type="nvarchar" nullable="true" length="15" scale="0" 
    ado-type="Varchar" />
 <orm:column name="Region" sql-type="nvarchar" nullable="true" length="15" scale="0" 
    ado-type="Varchar" />
 <orm:column name="PostalCode" sql-type="nvarchar" nullable="true" length="10" scale="0" 
    ado-type="Varchar" />
 <orm:column name="Country" sql-type="nvarchar" nullable="true" length="15" scale="0" 
    ado-type="Varchar" />
 <orm:column name="HomePhone" sql-type="nvarchar" nullable="true" length="24" scale="0" 
    ado-type="Varchar" />
 <orm:column name="Extension" sql-type="nvarchar" nullable="true" length="4" scale="0" 
    ado-type="Varchar" />
 <orm:column name="Photo" sql-type="image" nullable="true" length="0" scale="0" 
    ado-type="LongVarBinary" />
 <orm:column name="Notes" sql-type="ntext" nullable="true" length="0" scale="0" 
    ado-type="Clob" />
 <orm:column name="ReportsTo" sql-type="int" nullable="true" length="0" scale="0" 
    ado-type="Int32" />
 <orm:column name="PhotoPath" sql-type="nvarchar" nullable="true" length="255" scale="0" 
    ado-type="Varchar" />
 <orm:index name="LastName">
   <orm:columnMapping>
     <orm:column name="LastName" sql-type="nvarchar" nullable="false" length="20" scale="0" 
        ado-type="Varchar" />
   </orm:columnMapping>
 </orm:index>
 <orm:index name="PostalCode">
   <orm:columnMapping>
     <orm:column name="PostalCode" sql-type="nvarchar" nullable="true" length="10" scale="0"
         ado-type="Varchar" />
   </orm:columnMapping>
 </orm:index>
 <orm:constraint name="FK_Employees_Employees" destination-table="Employees">
   <orm:column name="ReportsTo" sql-type="int" nullable="true" length="0" scale="0" 
    ado-type="Int32" />
 </orm:constraint>
</orm:table>
<orm:table name="Categories">
 <orm:column name="CategoryID" sql-type="int" nullable="false" length="0" scale="0" 
    primary-key="true" backend-calculated="true" ado-type="Int32" />
 <orm:column name="CategoryName" sql-type="nvarchar" nullable="false" length="15" scale="0" 
    ado-type="Varchar" />
 <orm:column name="Description" sql-type="ntext" nullable="true" length="0" scale="0" 
    ado-type="Clob" />
 <orm:column name="Picture" sql-type="image" nullable="true" length="0" scale="0" 
    ado-type="LongVarBinary" />
 <orm:index name="CategoryName">
   <orm:columnMapping>
     <orm:column name="CategoryName" sql-type="nvarchar" nullable="false" length="15" 
        scale="0" ado-type="Varchar" />
   </orm:columnMapping>
 </orm:index>
</orm:table>
<orm:table name="Summary of Sales by Year" view="true">
 <orm:column nullable="true" length="0" name="Subtotal" scale="0" sql-type="money" 
    ado-type="Decimal" />
 <orm:column nullable="true" length="0" name="ShippedDate" scale="0" sql-type="datetime" 
    ado-type="DateTime" />
 <orm:column nullable="false" length="0" name="OrderID" scale="0" sql-type="int" 
    ado-type="Int32" />
</orm:table>

The <procedure> Element

The <procedure> element definition in the external mapping XML file specifies that a stored procedure exists in the database. The <procedure> element contains only one attribute - Name, which is used to specify the stored procedure name. Nested parameter elements (<procedure-parameter>) specify the names of parameters and their data types. These definitions identify a stored procedure that can be mapped to a function.

The following XML declarations specify three stored procedures .

<orm:procedure name="SalesByCategory">
 <orm:procedure-parameter nullable="true" length="4" name="OrdYear" scale="0" 
    sql-type="nvarchar" ado-type="Varchar" mode="in" type="System.String" />
 <orm:procedure-parameter nullable="true" length="15" name="CategoryName" scale="0" 
    sql-type="nvarchar" ado-type="Varchar" mode="in" type="System.String" />
 <orm:result-sets />
</orm:procedure>
<orm:procedure name="Sales by Year">
 <orm:procedure-parameter nullable="true" length="0" name="Ending_Date" scale="0" 
    sql-type="datetime" ado-type="DateTime" mode="in" 
    type="System.Nullable`1[[System.DateTime, mscorlib, Version=4.0.0.0, 
    Culture=neutral, PublicKeyToken=b77a5c561934e089]]" />
 <orm:procedure-parameter nullable="true" length="0" name="Beginning_Date" scale="0" 
    sql-type="datetime" ado-type="DateTime" mode="in" 
    type="System.Nullable`1[[System.DateTime, mscorlib, Version=4.0.0.0, 
    Culture=neutral, PublicKeyToken=b77a5c561934e089]]" />
 <orm:result-sets />
</orm:procedure>
<orm:procedure name="Employee Sales by Country">
 <orm:procedure-parameter nullable="true" length="0" name="Ending_Date" scale="0" 
    sql-type="datetime" ado-type="DateTime" mode="in" 
    type="System.Nullable`1[[System.DateTime, mscorlib, Version=4.0.0.0, 
    Culture=neutral, PublicKeyToken=b77a5c561934e089]]" />
 <orm:procedure-parameter nullable="true" length="0" name="Beginning_Date" scale="0" 
    sql-type="datetime" ado-type="DateTime" mode="in" 
    type="System.Nullable`1[[System.DateTime, mscorlib, Version=4.0.0.0, 
    Culture=neutral, PublicKeyToken=b77a5c561934e089]]" />
 <orm:result-sets />
</orm:procedure>
<orm:procedure name="CustOrdersOrders">
 <orm:procedure-parameter nullable="true" length="5" name="CustomerID" scale="0" 
    sql-type="nchar" ado-type="Character" mode="in" type="System.String" />
 <orm:result-sets />
</orm:procedure>

Several attributes should be specified for the <procedure-parameter> element, in order the same to be fully qualified:

• name - specifies the parameter name.
• ado-type - specifies the ado type for the parameter.
• sql-type - specifies the sql type for the parameter (e.g.: ntext, int, nvarchar, money, etc.).
• length - sets the length (or precision) of the database column.
• scale - sets the scale (digits after the decimal point).
• mode - specifies whether the parameter is in or out.