Annotation de DataSet typés

Les annotations vous permettent de modifier les noms des éléments de votre type DataSet sans modifier le schéma sous-jacent. La modification des noms des éléments de votre schéma sous-jacent ferait en sorte que DataSet fasse référence à des objets qui n'existent pas dans la source de données et provoquerait la perte d'une référence aux objets qui existent dans la source de données.

À l’aide d’annotations, vous pouvez personnaliser les noms d’objets de votre DataSet typé avec des noms plus explicites, ce qui rend le code plus lisible et votre DataSet typé plus facile à utiliser pour les clients, tout en laissant le schéma sous-jacent intact. Par exemple, l'élément de schéma suivant pour la table Customers de la base de données Northwind entraînerait un nom d'objet DataRow nommé CustomersRow et un DataRowCollection nommé Clients.

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

Un nom de DataRowCollection est significatif dans le code client, mais un nom de DataRow est trompeur car il s'agit d'un objet unique. En outre, dans les scénarios courants, l’objet serait référencé sans l’identificateur Row et serait simplement appelé objet Customer . La solution consiste à annoter le schéma et à identifier de nouveaux noms pour les objets DataRow et DataRowCollection. Voici la version annotée du schéma précédent.

<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>

La spécification d'une valeur typedName de Customer aboutira à un nom d'objet DataRowClient. La spécification d’une typedPlural valeur de Customers préserve le DataRowCollection nom de Customers.

Le tableau suivant présente les annotations disponibles pour une utilisation.

Le tableau suivant montre les valeurs qui peuvent être spécifiées pour l’annotation nullValue .

Le tableau suivant présente les valeurs par défaut des objets dans un type DataSet et les annotations disponibles.

Pour utiliser des annotations typées DataSet , vous devez inclure la référence suivante xmlns dans votre schéma XSD (XML Schema Definition Language). Pour créer un xsd à partir de tables de base de données, consultez WriteXmlSchema ou utiliser des jeux de données dans Visual Studio.

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

Voici un exemple de schéma annoté qui expose la Customers table de la Northwind base de données avec une relation avec la Orders table incluse.

<?xml version="1.0" encoding="utf-8"?>
<xs:schema id="CustomerDataSet"
      xmlns:codegen="urn:schemas-microsoft-com:xml-msprop"
      xmlns=""
      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 d'exemple. Il utilise un SqlDataAdapter pour remplir la Customers table et un autre SqlDataAdapter pour remplir la Orders table. Le type fortement typé DataSet définit les 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.NewCustomer()
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.NewCustomer();
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

• DataColumnCollection
• DataSet
• DataSets typés
• DataSets, DataTables et DataViews
• Vue d'ensemble d’ADO.NET