批注类型化数据集

2025-06-18

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

使用批注，可以使用更有意义的名称自定义类型化 数据集 中的对象名称，使代码更易于阅读，使客户端更易于使用类型化 数据集 ，同时使基础架构保持不变。例如，Northwind 数据库的 Customers 表的以下架构元素将导致 DataRow 对象名称 CustomersRow 和DataRowCollection名为 Customers。

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

Customers 的 DataRowCollection 名称在客户端代码中有意义，但 CustomersRow 的 DataRow 名称具有误导性，因为它是单个对象。此外，在常见情况下，对象会在不使用 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>

指定 Customer 的 typedName 值将导致 Customer 的 DataRow 对象名称。指定 typedPlural 值为 Customers，会保留 Customers 的 DataRowCollection 名称。

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

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

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

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

下表显示了有类型的数据集中的对象默认值和可用的批注。

对象/方法/事件	违约	注释
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

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

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

下面是一个带批注的示例架构，该架构公开了 Northwind 数据库的 Customers 表，该表与包含的 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>

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

通过

批注类型化数据集

另请参阅

其他资源