批注类型化数据集

批注使你能够修改类型 DataSet 化元素的名称，而无需修改基础架构。修改基础架构中元素的名称将导致类型化 DataSet 引用数据源中不存在的对象，并丢失对数据源中存在的对象的引用。

使用批注，你可以为你的DataSet对象赋予更有意义的名称，从而提升代码可读性，且让客户端更容易使用DataSet，同时保持底层架构不变。例如，以下针对Customers表的架构元素Northwind将在Northwind数据库中生成一个名为CustomersRow的对象和名为Customers的DataRowCollection。

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

名称DataRowCollection在客户端代码中有意义，但DataRow的名称CustomersRow具有误导性，因为它是单个对象。此外，在常见情况下，将引用对象而不使用 Row 标识符，而是简单地称为对象 Customer 。解决方案是对架构进行注释，并为DataRow和DataRowCollection对象标识新名称。下面是上一架构的批注版本。

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

指定typedName值为Customer将导致对象名称为Customer。指定一个typedPlural值可CustomersDataRowCollection保留 Customers 的名称。

下表显示了可供使用的批注。

注释	DESCRIPTION
typedName	对象的名称。
typedPlural	对象的集合的名称。
typedParent	对象在父关系中被引用时的名称。
typedChildren	从子关系中返回对象的方法的名称。
nullValue	如果基础值为 DBNull，则为值。有关批注，请参阅下表 `nullValue` 。默认值为_throw。

下表显示了可为批注指定的 nullValue 值。

nullValue 值	DESCRIPTION
替换值	指定要返回的值。返回的值必须与元素的类型匹配。例如，使用 `nullValue="0"` 为 null 整数字段返回 0。
_扔	引发异常。这是默认值。
_零	如果遇到基元类型，则返回 null 引用或引发异常。
_空	对于字符串，返回 String.Empty，否则返回从空构造函数创建的对象。如果遇到基元类型，则引发异常。

下表显示已定义类型的DataSet对象的默认值和可用的批注。

对象/方法/事件	违约	注释
DataTable	TableNameDataTable	typedPlural
DataTable 方法	NewTableNameRow AddTableNameRow DeleteTableNameRow	typedName
DataRowCollection	数据表名称	typedPlural
DataRow	TableNameRow	typedName
DataColumn	DataTable.ColumnNameColumn DataRow.ColumnName	typedName
财产	属性名称	typedName
Child 访问器	GetChildTableNameRows	typedChildren
Parent 访问器	TableNameRow	typedParent
数据集事件	TableNameRowChangeEvent TableNameRowChangeEventHandler	typedName

若要使用类型化 DataSet 批注，必须在 XML 架构定义语言（XSD）架构中包含以下 xmlns 引用。若要从数据库表创建 xsd，请参阅 WriteXmlSchema 或处理 Visual Studio 中的数据集。

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

下面是一个示例注解架构，该架构公开Customers表，并包含与Northwind数据库表Orders的关系。

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

下面的代码示例使用从示例架构创建的强类型 DataSet 。它使用一个SqlDataAdapter来填充Customers表，另一个SqlDataAdapter来填充Orders表。强类型 DataSet 定义 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)
    {

    }

另请参阅

Last updated on 2025-12-02

通过

批注类型化数据集

另请参阅

其他资源