Annotation de DataSets typés (ADO.NET)

Article
05/20/2011

Les annotations vous permettent de modifier le nom des éléments de votre objet DataSet typé sans pour autant modifier le schéma sous-jacent. Si vous modifiiez le nom des éléments de votre schéma sous-jacent, le DataSet typé ferait référence à des objets qui n'existent pas dans la source de données et perdrait des références vers des objets qui existent bien dans la source de données.

En utilisant des annotations, vous pouvez personnaliser le nom des objets de votre DataSet typé au profit de noms plus évocateurs qui rendront le code plus aisé à lire et votre DataSet typé plus facile à utiliser par les clients, tout en laissant intact le schéma sous-jacent. Par exemple, l'élément de schéma suivant pour la table Customers de la base de données Northwind donnerait un objet DataRow nommé CustomersRow et un objet DataRowCollection nommé Customers.

<xs:element name="Customers">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="CustomerID" type="xs:string" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
</xs:element>

Le nom Customers pour un DataRowCollection est évocateur dans un code client, mais le nom CustomersRow pour un DataRow est équivoque car il s'agit d'un objet unique. C'est pourquoi, dans un scénario classique, il serait fait référence à l'objet sans l'identificateur Row, pour donner simplement Customer. La solution consiste à annoter le schéma et à identifier de nouveaux noms pour les objets DataRow et DataRowCollection. Voici une version annotée du précédent schéma.

<xs:element name="Customers" codegen:typedName="Customer" codegen:typedPlural="Customers">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="CustomerID" type="xs:string" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
</xs:element>

En assignant à typedName la valeur Customer, vous obtenez un objet DataRow nommé Customer. En assignant à typedPlural la valeur Customers, vous conservez le nom Customers pour le DataRowCollection.

Le tableau suivant présente les différentes annotations disponibles.

Annotation	Description
typedName	Nom de l'objet.
typedPlural	Nom d'une collection d'objets.
typedParent	Nom de l'objet lorsqu'il y est fait référence dans une relation parente.
typedChildren	Nom de la méthode permettant de retourner des objets d'une relation enfant.
nullValue	Valeur à utiliser si la valeur sous-jacente est DBNull. Consultez le tableau suivant pour les annotations nullValue. La valeur par défaut est _throw.

Le tableau suivant présente les valeurs qui peuvent être spécifiées pour l'annotation nullValue.

Valeur nullValue	Description
Replacement Value	Spécifier une valeur à retourner. La valeur retournée doit correspondre au type de l'élément. Par exemple, utilisez nullValue="0" pour retourner 0 pour les champs de type null integer (entier nul).
_throw	Levée d'une exception. Il s'agit de la valeur par défaut.
_null	Retourner une référence Null ou lever une exception si un type primitif est rencontré.
_empty	Pour des chaînes, retourner String.Empty, dans les autres cas, retourner un objet créé à partir d'un constructeur vide. Si un type primitif est rencontré, lever une exception.

Le tableau suivant présente les valeurs par défaut pour les objets d'un DataSet typé et les annotations disponibles.

Objet/méthode/événement	Default	Annotation
DataTable	TableNameDataTable	typedPlural
Méthodes de DataTable	NewTableNameRow AddTableNameRow DeleteTableNameRow	typedName
DataRowCollection	TableName	typedPlural
DataRow	TableNameRow	typedName
DataColumn	DataTable.ColumnNameColumn DataRow.ColumnName	typedName
Property	PropertyName	typedName
Accesseur Child	GetChildTableNameRows	typedChildren
Accesseur Parent	TableNameRow	typedParent
Événements de DataSet	TableNameRowChangeEvent TableNameRowChangeEventHandler	typedName

Pour utiliser des annotations de DataSet typé, vous devez inclure la référence xmlns suivante dans votre schéma en langage XSD (XML Schema Definition).

xmlns:codegen="urn:schemas-microsoft-com:xml-msprop"

L'exemple suivant est un schéma annoté qui expose la table Customers de la base de données Northwind et inclut une relation avec la table Orders.

<?xml version="1.0" encoding="utf-8"?>
<xs:schema id="CustomerDataSet" 
      xmlns:codegen="urn:schemas-microsoft-com:xml-msprop"
       
      xmlns:xs="http://www.w3.org/2001/XMLSchema" 
      xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
  <xs:element name="CustomerDataSet" msdata:IsDataSet="true">
    <xs:complexType>
      <xs:choice maxOccurs="unbounded">
        <xs:element name="Customers" codegen:typedName="Customer"
codegen:typedPlural="Customers">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="CustomerID"
codegen:typedName="CustomerID" type="xs:string" minOccurs="0" />
              <xs:element name="CompanyName"
codegen:typedName="CompanyName" type="xs:string" minOccurs="0" />
              <xs:element name="Phone" codegen:typedName="Phone"
codegen:nullValue="" type="xs:string" minOccurs="0" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="Orders" codegen:typedName="Order"
codegen:typedPlural="Orders">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="OrderID" codegen:typedName="OrderID"
type="xs:int" minOccurs="0" />
              <xs:element name="CustomerID"
codegen:typedName="CustomerID"
                 codegen:nullValue="" type="xs:string" minOccurs="0" />
              <xs:element name="EmployeeID"
codegen:typedName="EmployeeID" codegen:nullValue="0" 
type="xs:int" minOccurs="0" />
              <xs:element name="OrderAdapter"
codegen:typedName="OrderAdapter"
codegen:nullValue="1980-01-01T00:00:00" 
type="xs:dateTime" minOccurs="0" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:choice>
    </xs:complexType>
    <xs:unique name="Constraint1">
      <xs:selector xpath=".//Customers" />
      <xs:field xpath="CustomerID" />
    </xs:unique>
    <xs:keyref name="CustOrders" refer="Constraint1"
codegen:typedParent="Customer" codegen:typedChildren="GetOrders">
      <xs:selector xpath=".//Orders" />
      <xs:field xpath="CustomerID" />
    </xs:keyref>
  </xs:element>
</xs:schema>

L'exemple de code suivant utilise un DataSet fortement typé créé à partir du schéma précédent. Il utilise un objet SqlDataAdapter pour remplir la table Customers et un autre objet SqlDataAdapter pour remplir la table Orders. Le DataSet fortement typé définit le DataRelations.

' Assumes a valid SqlConnection object named connection.
Dim customerAdapter As SqlDataAdapter = New SqlDataAdapter( _
    "SELECT CustomerID, CompanyName, Phone FROM Customers", &
    connection)
Dim orderAdapter As SqlDataAdapter = New SqlDataAdapter( _
    "SELECT OrderID, CustomerID, EmployeeID, OrderAdapter FROM Orders", &
    connection)

' Populate a strongly typed DataSet.
connection.Open()
Dim customers As CustomerDataSet = New CustomerDataSet()
customerAdapter.Fill(customers, "Customers")
orderAdapter.Fill(customers, "Orders")
connection.Close()

' Add a strongly typed event.
AddHandler customers.Customers.CustomerChanged, &
    New CustomerDataSet.CustomerChangeEventHandler( _
    AddressOf OnCustomerChanged)

' Add a strongly typed DataRow.
Dim newCustomer As CustomerDataSet.Customer = _
    customers.Customers.NewCustomeromer()
newCustomer.CustomerID = "NEW01"
newCustomer.CompanyName = "My New Company"
customers.Customers.AddCustomer(newCustomer)

' Navigate the child relation.
Dim customer As CustomerDataSet.Customer
Dim order As CustomerDataSet.Order

For Each customer In customers.Customers
  Console.WriteLine(customer.CustomerID)
  For Each order In customer.GetOrders()
    Console.WriteLine(vbTab & order.OrderID)
  Next
Next

Private Shared Sub OnCustomerChanged( _
    sender As Object, e As CustomerDataSet.CustomerChangeEvent)

End Sub

// Assumes a valid SqlConnection object named connection.
SqlDataAdapter customerAdapter = new SqlDataAdapter(
    "SELECT CustomerID, CompanyName, Phone FROM Customers",
    connection);
SqlDataAdapter orderAdapter = new SqlDataAdapter(
    "SELECT OrderID, CustomerID, EmployeeID, OrderAdapter FROM Orders", 
    connection);

// Populate a strongly typed DataSet.
connection.Open();
CustomerDataSet customers = new CustomerDataSet();
customerAdapter.Fill(customers, "Customers");
orderAdapter.Fill(customers, "Orders");
connection.Close();

// Add a strongly typed event.
customers.Customers.CustomerChanged += new 
  CustomerDataSet.CustomerChangeEventHandler(OnCustomerChanged);

// Add a strongly typed DataRow.
CustomerDataSet.Customer newCustomer = 
    customers.Customers.NewCustomeromer();
newCustomer.CustomerID = "NEW01";
newCustomer.CompanyName = "My New Company";
customers.Customers.AddCustomer(newCustomer);

// Navigate the child relation.
foreach(CustomerDataSet.Customer customer in customers.Customers)
{
  Console.WriteLine(customer.CustomerID);
  foreach(CustomerDataSet.Order order in customer.GetOrders())
    Console.WriteLine("\t" + order.OrderID);
}

protected static void OnCustomerChanged(object sender, CustomerDataSet.CustomerChangeEvent e)
    {

    }

Voir aussi

Référence

DataColumnCollection

DataSet

Autres ressources

DataSets typés (ADO.NET)

Objets DataSet, DataTable et DataView (ADO.NET)

Partager via

Annotation de DataSets typés (ADO.NET)

Voir aussi

Référence

Autres ressources

Ressources supplémentaires