.gif) Note |
|---|
|
This topic describes new functionality in ADO.NET Data Services that is available as an update to the .NET Framework version 3.5 Service Pack 1. You can download and install the update from the Microsoft Download Center.
|
When addressing a data service, each URI must include a path component. Usually, this path consists of segments that represent the entity resources that are defined in the data model. However, ADO.NET Data Services defines the following special paths that do not return entity data:
-
Service root path - returns information about the entity sets that can be accessed on the data service.
-
Service operation - defines a method that is exposed as an endpoint on the data service. For more information, see Service Operations (ADO.NET Data Services).
-
$batch path segment - defines the URI that is used to submit requests that contain more than one operation.
-
$count path segment - returns the number of entities in the set returned by the URI, without any additional response message metadata.
-
$value path segment - returns the value of a property that is a primitive type, without any additional response message metadata.
-
$metadata path segment - returns metadata, in Conceptual Schema Definition Language for the Entity Framework (CSDL), that describes the data model used by the data service.
Count Path Segment ($count)
When you append the $count segment to the path of any resource that returns a set of entities, an integer value is returned. This value is the number of resources that would have been returned by the URI. This option can be appended to the path of any URI that returns either an entity set. The $count segment must be the last segment in the path of the URI. For example, the URI http://myservice/Northwind.svc/Customers('ALFKI')/Orders/$count returns an integer value that is the number of Orders entities that belong to the Customer ALFKI. Although $count cannot be used as a query option in the URI, query options can be used with a path that ends with $count. For example, the URI http://myserver/Northwind.svc/Customers/$count?$expand=Orders&$filter=Country eq 'Germany' returns the number of German customers.
The $count path segment instructs the data service to return an integer instead of the actual data or any response message metadata. To receive the count information together with the entity data, use the $inlinecount query option instead of $count. For more information, see Query Expressions (ADO.NET Data Services).
Value Path Segment ($value)
When you append the $value segment to a path that returns a primitive type, only the value of the primitive type itself is returned, without any response message metadata. For example, the URI http://myserver/Northwind.svc/Customers('ALFKI')/CustomerID/$value returns only a string that is the customer ID value, which in this case is ALFKI.
Service Root Path
The root URI of a data service is an addressable endpoint of the service. When you send a request to the root URI of a data service, such as http://myserver/northwind.svc for a Northwind data service, the data service returns a response message that contains the entity sets that are exposed on the data service, such as the following response message body from the Northwind.svc data service. This data service is created when you complete the ADO.NET Data Services quickstart.
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<service xml:base="http://localhost:12345/Northwind.svc/" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app" xmlns="http://www.w3.org/2007/app">
<workspace>
<atom:title>Default</atom:title>
<collection href="Customers">
<atom:title>Customers</atom:title>
</collection>
<collection href="Order_Details">
<atom:title>Order_Details</atom:title>
</collection>
<collection href="Orders">
<atom:title>Orders</atom:title>
</collection>
<collection href="Products">
<atom:title>Products</atom:title>
</collection>
</workspace>
</service>
The root data service URI and the data model that is returned by using the $metadata segment are used together by tools that generate client libraries to more easily access a data service from a client application. For more information, see Generating the Data Service Client Library (ADO.NET Data Services).
Data Model Metadata Path Segment ($metadata)
ADO.NET Data Services provides a mechanism to return the data model that defines the entity types and relationships of the individual resources. The metadata is accessed by a URI that is the root endpoint of the data service appended with the $metadata operator. The returned metadata is in the CSDL format that is compatible with the Entity Framework .edmx file, and the model is equivalent to the conceptual model that is the Entity Framework implementation of the Entity Data Model (EDM). For more general information about the concept of the EDM, see Entity Data Model.
The following metadata is returned from the Northwind Data service that has four entity sets when the URI http://myserver/Northwind.svc/$metadata is requested.
| Note |
|---|
|
The complete data service response has been truncated for readability.
|
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<edmx:Edmx Version="1.0"
xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx">
<edmx:DataServices>
<Schema Namespace="NorthwindModel"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns="http://schemas.microsoft.com/ado/2006/04/edm">
<EntityType Name="Customers">
<Key>
<PropertyRef Name="CustomerID" />
</Key>
<Property Name="CustomerID" Type="Edm.String" Nullable="false"
MaxLength="5" Unicode="true" FixedLength="true" />
<Property Name="CompanyName" Type="Edm.String" Nullable="false"
MaxLength="40" Unicode="true" FixedLength="false" />
...
<NavigationProperty Name="Orders"
Relationship="NorthwindModel.FK_Orders_Customers"
FromRole="Customers" ToRole="Orders" />
</EntityType>
<EntityType Name="Order_Details">
<Key>
<PropertyRef Name="OrderID" />
<PropertyRef Name="ProductID" />
</Key>
<Property Name="OrderID" Type="Edm.Int32" Nullable="false" />
<Property Name="ProductID" Type="Edm.Int32" Nullable="false" />
...
<NavigationProperty Name="Orders"
Relationship="NorthwindModel.FK_Order_Details_Orders"
FromRole="Order_Details" ToRole="Orders" />
<NavigationProperty Name="Products"
Relationship="NorthwindModel.FK_Order_Details_Products"
FromRole="Order_Details" ToRole="Products" />
</EntityType>
<EntityType Name="Orders">
<Key>
<PropertyRef Name="OrderID" />
</Key>
<Property Name="OrderID" Type="Edm.Int32" Nullable="false" />
<NavigationProperty Name="Customers"
Relationship="NorthwindModel.FK_Orders_Customers"
FromRole="Orders" ToRole="Customers" />
<NavigationProperty Name="Order_Details"
Relationship="NorthwindModel.FK_Order_Details_Orders"
FromRole="Orders" ToRole="Order_Details" />
</EntityType>
...
<Association Name="FK_Orders_Customers">
<End Role="Customers" Type="NorthwindModel.Customers" Multiplicity="0..1" />
<End Role="Orders" Type="NorthwindModel.Orders" Multiplicity="*" />
</Association>
<Association Name="FK_Order_Details_Orders">
<End Role="Orders" Type="NorthwindModel.Orders" Multiplicity="1" />
<End Role="Order_Details" Type="NorthwindModel.Order_Details" Multiplicity="*" />
<ReferentialConstraint>
<Principal Role="Orders">
<PropertyRef Name="OrderID" />
</Principal>
<Dependent Role="Order_Details">
<PropertyRef Name="OrderID" />
</Dependent>
</ReferentialConstraint>
</Association>
...
</Schema>
<Schema Namespace="NorthwindDataService"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns="http://schemas.microsoft.com/ado/2006/04/edm">
<EntityContainer Name="NorthwindEntities" m:IsDefaultEntityContainer="true">
<EntitySet Name="Customers" EntityType="NorthwindModel.Customers" />
<EntitySet Name="Order_Details" EntityType="NorthwindModel.Order_Details" />
<EntitySet Name="Orders" EntityType="NorthwindModel.Orders" />
...
<AssociationSet Name="FK_Orders_Customers"
Association="NorthwindModel.FK_Orders_Customers">
<End Role="Customers" EntitySet="Customers" />
<End Role="Orders" EntitySet="Orders" />
</AssociationSet>
...
</EntityContainer>
</Schema>
</edmx:DataServices>
</edmx:Edmx>
In the metadata, the type that is the default entity container of the data service is attributed with IsDefaultEntityContainer="true". When a service operation is defined for the data service, the operation is defined in the metadata schema for the service as a FunctionImport element in the entity container. For example, the following FunctionImport element defines a service operation in the Northwind data service named GetOrdersByCity, which returns Orders objects:
<FunctionImport Name="GetOrdersByCity" EntitySet="Orders"
ReturnType="Collection(NorthwindModel.Orders)" m:HttpMethod="GET">
<Parameter Name="city" Type="Edm.String" Mode="In" />
</FunctionImport>
Like Web Service Description Language (WSDL) files for a Web service, this metadata can be consumed by the Add Service Reference tool in Visual Studio or the DataSvcUtil.exe tool to generate a strongly typed client library. By using this client library, an application can interact with data service resources as if they were programmable classes. For more information, see Using a Data Service in a .NET Framework Application (ADO.NET Data Services).
| Note |
|---|
|
By default, the AtomPub and JSON feeds that contain the response to a data service request are based on the entity sets, entity types, and properties defined in the data model. However, you can annotate data model definitions to enable AtomPub to return feeds in a custom format. For more information, see Atom Feed Customization (ADO.NET Data Services).
|
See Also