Service Operations (ADO.NET Data Services)
ADO.NET Data Services enables you to define service operations on a data service to expose methods on the server. Like other data service resources, service operations are addressed by URIs. Service operations enable you to expose business logic in a data service, such as to implement validation logic, to apply role-based security, or to expose specialized querying capabilities. Service operations are methods added to the data service class that derives from DataService. Like all other data service resources, you can supply parameters to the service operation method. For example, the following service operation URI (based on the quickstart data service) passes the value London to the city parameter:
https://localhost:12345/Northwind.svc/GetOrdersByCity?city='London'
The definition for this service operation is as follows:
<WebGet()> _
Public Function GetOrdersByCity(ByVal city As String) As IQueryable(Of Orders)
[WebGet]
public IQueryable<Orders> GetOrdersByCity(string city)
You can use the CurrentDataSource() of the DataService to directly access the data source that the data service is using. For more information, see How to: Define a Service Operation (ADO.NET Data Services).
Service Operation Requirements
The following requirements apply when defining service operations on the data service. If a method does not meet these requirements, it will not be exposed as a service operation for the data service.
The operation must be a public instance method that is a member of the data service class.
The operation method may only accept input parameters.
If parameters are defined, the type of each parameter must be a primitive type.
The method must return one of the following:
void (Nothing in Visual Basic)
IEnumerable
IQueryable
An entity type in the data model that the data service exposes.
A primitive class such as integer or string.
In order to support query options such as sorting, paging, and filtering, service operation methods should return IQueryable. Requests to service operations that include query options are rejected for operations that only return IEnumerable.
In order to support accessing related entities by using navigation properties, the service operation must return IQueryable.
The method must be annotated with the [WebGet] or [WebInvoke] attribute.
[WebGet] enables the method to be invoked by using a GET request.
[WebInvoke] enables the method to be invoked by using a POST request.
A service operation may be annotated with the SingleResultAttribute that specifies that the return value from the method is a single entity rather than a collection of entities. This distinction dictates the resulting serialization of the response and the manner in which additional navigation property traversals are represented in the URI. For example, when using AtomPub serialization, a single resource type instance is represented as an entry element and a set of instances as a feed element.
Addressing Service Operations
You can address service operations by placing the name of the method in the first path segment of a URI. As an example, the following URI accesses a GetOrdersByCity operation that returns an IQueryable collection of Orders objects, ordered by RequiredDate in descending order, along with the related Order_Details objects:
https://localhost:12345/Northwind.svc/GetOrdersByCity?city='London'&$expand=Order_Details&$orderby=RequiredDate desc
Additional path segments or query options may be added to the URI depending on the return type of the service operation.
Valid Return Types |
URI Rules |
|---|---|
void (Nothing in Visual Basic) -or- Entity types -or- Primitive types |
The URI must be a single path segment that is the name of the service operation. Query options are not allowed. |
IEnumerable |
The URI must be a single path segment that is the name of the service operation. Since the result type is not an IQueryable type, query options are not allowed. |
IQueryable |
Query path segments in addition to the path that is the name of the service operation are allowed. Query options are also allowed. |
Service Operations Access Control
Service-wide visibility of service operations is controlled by the SetServiceOperationAccessRule(String, ServiceOperationRights) method on the IDataServiceConfiguration class in much the same way that entity set visibility is controlled by using the SetEntitySetAccessRule(String, EntitySetRights) method. For example, the following line of code in the data service definition enables access to the CustomersByCity service operation.
config.SetServiceOperationAccessRule( _
"GetOrdersByCity", ServiceOperationRights.AllRead)
config.SetServiceOperationAccessRule(
"GetOrdersByCity", ServiceOperationRights.AllRead);
Note
If a service operation has a return type that has been hidden by restricting access on the underlying entity sets, then the service operation will not be available to client applications.
For more information, see How to: Define a Service Operation (ADO.NET Data Services).