Membuat Anotasi Himpunan Data yang Diketik
Anotasi memungkinkan Anda untuk mengubah nama elemen dalam DataSet yang diketik tanpa mengubah skema yang mendasarinya. Memodifikasi nama elemen dalam skema yang mendasari akan menyebabkan DataSet yang diketik merujuk ke objek yang tidak ada di sumber data, serta kehilangan referensi ke objek yang ada di sumber data.
Dengan anotasi, Anda dapat mengkustomisasi nama objek di DataSet yang diketik dengan nama yang lebih bermakna, membuat kode lebih mudah dibaca dan DataSet yang diketik lebih mudah digunakan klien, sambil membiarkan skema yang mendasarinya tetap utuh. Misalnya, elemen skema berikut untuk tabel Pelanggan dari database Northwind akan menghasilkan nama objek DataRow dari CustomersRow dan DataRowCollection bernama Pelanggan.
<xs:element name="Customers">
<xs:complexType>
<xs:sequence>
<xs:element name="CustomerID" type="xs:string" minOccurs="0" />
</xs:sequence>
</xs:complexType>
</xs:element>
Nama DataRowCollection dari Pelanggan bermakna dalam kode klien, tetapi nama DataRow dari CustomersRow menyesatkan karena merupakan objek tunggal. Selain itu, dalam skenario umum, objek akan dirujuk tanpa pengidentifikasi Baris dan sebagai gantinya hanya akan dirujuk sebagai objek Pelanggan. Solusinya adalah dengan membuat anotasi untuk skema dan mengidentifikasi nama baru untuk objek DataRow dan DataRowCollection. Berikut ini adalah versi beranotasi dari skema sebelumnya.
<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>
Menentukan nilai typedName dari Pelanggan akan menghasilkan nama objek DataRow dari Pelanggan. Menentukan nilai typedPlural dari Pelanggan mempertahankan nama DataRowCollection dari Pelanggan.
Tabel berikut menunjukkan anotasi yang tersedia untuk digunakan.
| Anotasi | Deskripsi |
|---|---|
| typedName | Nama objek. |
| typedPlural | Nama kumpulan objek. |
| typedParent | Nama objek ketika dirujuk dalam hubungan induk. |
| typedChildren | Nama metode untuk mengembalikan objek dari hubungan turunan. |
| nullValue | Nilai jika nilai dasarnya adalah DBNull. Lihat tabel berikut untuk anotasi nullValue. Defaultnya adalah _throw. |
Tabel berikut menunjukkan nilai yang dapat ditentukan untuk anotasi nullValue.
| Nilai nullValue | Deskripsi |
|---|---|
| Nilai Pengganti | Tentukan nilai yang akan dikembalikan. Nilai yang dikembalikan harus cocok dengan jenis elemen. Misalnya, gunakan nullValue="0" untuk mengembalikan 0 untuk bidang bilangan bulat null. |
| _throw | Tampilkan pengecualian. Ini adalah default. |
| _null | Kembalikan referensi null atau tampilkan pengecualian jika ditemukan jenis primitif. |
| _empty | Untuk string, kembalikan String.Empty, jika tidak, kembalikan objek yang dibuat dari konstruktor yang kosong. Jika ditemukan jenis primitif, tampilkan pengecualian. |
Tabel berikut menunjukkan nilai default untuk objek dalam DataSet yang diketik dan anotasi yang tersedia.
| Objek/Metode/Peristiwa | Default | Anotasi |
|---|---|---|
| DataTable | TableNameDataTable | typedPlural |
| Metode DataTable | NewTableNameRow AddTableNameRow DeleteTableNameRow |
typedName |
| DataRowCollection | TableName | typedPlural |
| DataRow | TableNameRow | typedName |
| DataColumn | DataTable.ColumnNameColumn DataRow.ColumnName |
typedName |
| Properti | PropertyName | typedName |
| Pengakses Turunan | GetChildTableNameRows | typedChildren |
| Pengakses Induk | TableNameRow | typedParent |
| Peristiwa DataSet | TableNameRowChangeEvent TableNameRowChangeEventHandler |
typedName |
Untuk menggunakan anotasi DataSet yang diketik, Anda harus menyertakan referensi xmlns berikut dalam skema bahasa definisi Skema XML (XSD). Untuk membuat xsd dari tabel database, lihat WriteXmlSchema atau Bekerja dengan DataSets di Visual Studio.
xmlns:codegen="urn:schemas-microsoft-com:xml-msprop"
Berikut adalah contoh skema beranotasi yang mengekspos tabel Pelanggan dari database Northwind dengan kaitannya ke tabel Pesanan yang disertakan.
<?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>
Contoh kode berikut menggunakan DataSet yang bersifat strongly typed, yang dibuat dari sampel skema. Ini menggunakan satu SqlDataAdapter untuk mengisi tabel Pelanggan dan SqlDataAdapter lain untuk mengisi tabel Pesanan. DataSet yangbersifat strongly typed mendefinisikan 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)
{
}