批注具類型的數據集

2025-06-17

註釋可讓您修改類型化DataSet中元素的名稱，而不需要修改底層結構。修改基礎架構中元素的名稱會導致型別化的DataSet指向數據源中不存在的物件，同時也會失去對數據源中已存在物件的參考。

使用批註，您可以自定義具型別 DataSet 中的物件名稱，使其更具意義，從而提高程式碼的可讀性，並使客戶端更容易使用具型別 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 物件名稱。指定 Customers 的 typedPlural 值會保留 Customers 的 DataRowCollection 名稱。

下表顯示可供使用的批注。

註解	說明
typedName	物件的名稱。
typedPlural	物件的集合名稱。
typedParent	在父關聯性中參考時，對象的名稱。
typedChildren	用於從子關聯性返回物件的方法名稱。
nullValue	如果基礎值是 DBNull，則為值。如需 nullValue 註釋，請參閱下表。預設值為 _throw。

下表顯示可為 nullValue 註釋指定的值。

nullValue 值	說明
取代值	指定要傳回的值。傳回的值必須符合元素的型別。例如，使用 `nullValue="0"` 在整數位段為 null 時傳回 0。
_扔	拋出例外這是預設值。
_零	如果遇到基本類型，則傳回 null 參考或拋出例外狀況。
_空	如果是字串，則傳回 String.Empty，否則會傳回從空建構函式建立的物件。如果遇到基本類型，則擲回例外狀況。

下表顯示具型別 DataSet 中物件的預設值及其可用的批註。

物件/方法/事件	預設	註解
DataTable	資料表名稱數據表	typedPlural
DataTable 方法	新資料表名稱行新增表名稱列 (AddTableNameRow) 刪除表格名稱列	輸入的名稱
DataRowCollection	表格名稱	typedPlural
DataRow	資料表名稱列	輸入的名稱
DataColumn	資料表.欄名欄 DataRow.ColumnName	輸入的名稱
財產	屬性名稱	輸入的名稱
子項訪問器	GetChildTableNameRows（取得子表名稱列）	類型化兒童
父項存取器	資料表名稱列	typedParent
數據集事件	TableNameRowChangeEvent 資料表名稱行更改事件處理程序	輸入的名稱

若要使用具類型的 DataSet 註釋，您必須在 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 數據表。強型別的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)  
    {  
  
    }

另請參閱

DataColumnCollection
DataSet
型別化的資料集
資料集 (DataSets)、資料表格 (DataTables) 和數據視圖 (DataViews)
ADO.NET 概觀

共用方式為

批注具類型的數據集

另請參閱

其他資源