批注具類型的數據集

註釋可讓您修改類型化DataSet中元素的名稱，而不需要修改底層結構。修改底層結構中元素名稱會導致類型 DataSet 指向資料來源中不存在的物件，並且會失去對資料來源中存在物件的參考。

透過註解，你可以自訂型別 DataSet 中物件的名稱，讓程式碼更易讀，並使 DataSet 更易於客戶端使用，同時保留底層結構完好無損。例如，針對資料庫Northwind的Customers資料表，下列結構元素會生成名為CustomersRow的DataRow物件和一個名為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 的名稱為 Customers，這是有意義的，但 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 的 Customers 值會保留 DataRowCollectionCustomers 的名稱。

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

註解	說明
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 Schema 定義語言（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>

以下程式碼範例使用由範例結構建立的強型別 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)
    {

    }

另請參閱

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

Last updated on 2025-12-02

共用方式為

批注具類型的數據集

另請參閱

其他資源