Configuring the Data Service (WCF Data Services)
Important
WCF Data Services has been deprecated and will no longer be available for download from the Microsoft Download Center. WCF Data Services supported earlier versions of the Microsoft OData (V1-V3) protocol only and has not been under active development. OData V1-V3 has been superseded by OData V4, which is an industry standard published by OASIS and ratified by ISO. OData V4 is supported through the OData V4 compliant core libraries available at Microsoft.OData.Core. Support documentation is available at OData.Net, and the OData V4 service libraries are available at Microsoft.AspNetCore.OData.
RESTier is the successor to WCF Data Services. RESTier helps you bootstrap a standardized, queryable, HTTP-based REST interface in minutes. Like WCF Data Services before it, Restier provides simple and straightforward ways to shape queries and intercept submissions before and after they hit the database. And like Web API + OData, you still have the flexibility to add your own custom queries and actions with techniques you're already familiar with.
With WCF Data Services, you can create data services that expose Open Data Protocol (OData) feeds. Data in these feeds can come from a variety of data sources. WCF Data Services uses data providers to expose this data as an OData feed. These providers include an Entity Framework provider, a reflection provider, and a set of custom data service provider interfaces. The provider implementation defines the data model for the service. For more information, see Data Services Providers.
In WCF Data Services, a data service is a class that inherits from the DataService<T> class, where the type of the data service is the entity container of the data model. This entity container has one or more properties that return an IQueryable<T>, which are used to access entity sets in the data model.
The behaviors of the data service are defined by the members of the DataServiceConfiguration class, and by members of the DataServiceBehavior class, which is accessed from the DataServiceBehavior property of the DataServiceConfiguration class. The DataServiceConfiguration class is supplied to the InitializeService method that is implemented by the data service, as in the following implementation of a Northwind data service:
// This method is called only once to initialize service-wide policies.
public static void InitializeService(DataServiceConfiguration config)
{
// Set the access rules of feeds exposed by the data service, which is
// based on the requirements of client applications.
config.SetEntitySetAccessRule("Customers", EntitySetRights.AllRead);
config.SetEntitySetAccessRule("Employees", EntitySetRights.ReadSingle);
config.SetEntitySetAccessRule("Orders", EntitySetRights.All
| EntitySetRights.WriteAppend
| EntitySetRights.WriteMerge);
config.SetEntitySetAccessRule("Order_Details", EntitySetRights.All);
config.SetEntitySetAccessRule("Products", EntitySetRights.All);
// Set page size defaults for the data service.
config.SetEntitySetPageSize("Orders", 20);
config.SetEntitySetPageSize("Order_Details", 50);
config.SetEntitySetPageSize("Products", 50);
// Paging requires v2 of the OData protocol.
config.DataServiceBehavior.MaxProtocolVersion =
System.Data.Services.Common.DataServiceProtocolVersion.V2;
}
' This method is called only once to initialize service-wide policies.
Public Shared Sub InitializeService(ByVal config As DataServiceConfiguration)
' Set the access rules of feeds exposed by the data service, which is
' based on the requirements of client applications.
config.SetEntitySetAccessRule("Customers", EntitySetRights.AllRead)
config.SetEntitySetAccessRule("Employees", EntitySetRights.ReadSingle)
config.SetEntitySetAccessRule("Orders", EntitySetRights.AllRead _
Or EntitySetRights.WriteAppend _
Or EntitySetRights.WriteMerge)
config.SetEntitySetAccessRule("Order_Details", EntitySetRights.All)
config.SetEntitySetAccessRule("Products", EntitySetRights.ReadMultiple)
' Set page size defaults for the data service.
config.SetEntitySetPageSize("Orders", 20)
config.SetEntitySetPageSize("Order_Details", 50)
config.SetEntitySetPageSize("Products", 50)
' Paging requires v2 of the OData protocol.
config.DataServiceBehavior.MaxProtocolVersion = _
System.Data.Services.Common.DataServiceProtocolVersion.V2
End Sub
Data Service Configuration Settings
The DataServiceConfiguration class enables you to specify the following data service behaviors:
| Member | Behavior |
|---|---|
| AcceptCountRequests | Enables you to disable count requests that are submitted to the data service by using the $count path segment and the $inlinecount query option. For more information, see OData: URI Conventions. |
| AcceptProjectionRequests | Enables you to disable support for data projection in requests that are submitted to the data service by using the $select query option. For more information, see OData: URI Conventions. |
| EnableTypeAccess | Enables a data type to be exposed in the metadata for a dynamic metadata provider defined by using the IDataServiceMetadataProvider interface. |
| EnableTypeConversion | Enables you to specify whether the data service runtime should convert the type that is contained in the payload to the actual property type that is specified in the request. |
| InvokeInterceptorsOnLinkDelete | Enables you to specify whether or not registered change interceptors are invoked on the related entities when a relationship link between two entities is deleted. |
| MaxBatchCount | Enables you to limit the number of change sets and query operations that are allowed in a single batch. For more information, see OData: Batch and Batching Operations. |
| MaxChangesetCount | Enables you to limit the number of changes that can be included in a single change set. For more information, see How to: Enable Paging of Data Service Results. |
| MaxExpandCount | Enables you to limit the size of a response by limiting the number of related entities that can be included in a single request by using the $expand query operator. For more information, see OData: URI Conventions and Loading Deferred Content. |
| MaxExpandDepth | Enables you to limit the size of a response by limiting the depth of the graph of related entities that can be included in a single request by using the $expand query operator. For more information, see OData: URI Conventions and Loading Deferred Content. |
| MaxObjectCountOnInsert | Enables you to limit the number of entities to be inserted that can be contained in a single POST request. |
| MaxProtocolVersion | Defines the version of the Atom protocol that is used by the data service. When the value of the MaxProtocolVersion is set to a value less than the maximum value of DataServiceProtocolVersion, the latest functionality of WCF Data Services is not available to clients accessing the data service. For more information, see Data Service Versioning. |
| MaxResultsPerCollection | Enables you to limit the size of a response by limiting the number of entities in each entity set that is returned as a data feed. |
| RegisterKnownType | Adds a data type to the list of types that are recognized by the data service. |
| SetEntitySetAccessRule | Sets the access rights for entity set resources that are available on the data service. An asterisk (*) value can be supplied for the name parameter to set access for all remaining entity sets to the same level. We recommend that you set access to entity sets to provide the least privilege access to data service resources that are required by client applications. For more information, see Securing WCF Data Services. For examples of the minimum access rights required for a given URI and HTTP action, see the table in the Minimum Resource Access Requirements section. |
| SetEntitySetPageSize | Sets the maximum page size for an entity set resource. For more information, see How to: Enable Paging of Data Service Results. |
| SetServiceOperationAccessRule | Sets the access rights for service operations that are defined on the data service. For more information, see Service Operations. An asterisk (*) value can be supplied for the name parameter to set access for all service operations to the same level. We recommend that you set access to service operations to provide the least privilege access to data service resources that are required by client applications. For more information, see Securing WCF Data Services. |
| UseVerboseErrors | This configuration property enables you to more easily troubleshoot a data service by returning more information in the error response message. This option is not intended to be used in a production environment. For more information, see Developing and Deploying WCF Data Services. |
Minimum Resource Access Requirements
The following table details the minimum entity set rights that must be granted to execute a specific operation. Path examples are based on the Northwind data service that is created when you complete the quickstart. Because both the EntitySetRights enumeration and the ServiceOperationRights enumeration are defined by using the FlagsAttribute, you can use a logical OR operator to specify multiple permissions for a single entity set or operation. For more information, see How to: Enable Access to the Data Service.
| Path/Action | GET |
DELETE |
MERGE |
POST |
PUT |
|---|---|---|---|---|---|
/Customers |
ReadMultiple | Not supported | Not supported | WriteAppend | Not supported |
/Customers('ALFKI') |
ReadSingle | ReadSingle and WriteDelete | ReadSingle and WriteMerge | n/a | ReadSingle and WriteReplace |
/Customers('ALFKI')/Orders |
Customers: ReadSingle-and- Orders: ReadMultiple |
Not supported | Not supported | Customers: ReadSingle and WriteMerge or WriteReplace-and- Orders : and WriteAppend |
Not supported |
/Customers('ALFKI')/Orders(10643) |
Customers: ReadSingle-and- Orders: ReadSingle |
Customers: ReadSingle-and- Orders: ReadSingle and WriteDelete |
Customers: ReadSingle-and- Orders: ReadSingle and WriteMerge |
Not supported | Customers: ReadSingle-and- Orders: ReadSingle and WriteReplace |
/Orders(10643)/Customer |
Customers: ReadSingle-and- Orders: ReadSingle |
Customers: ReadSingle and WriteDelete-and- Orders: ReadSingle |
Customers: ReadSingle and WriteMerge;-and- Orders: ReadSingle |
Customers: WriteAppend-and- Orders: WriteAppend and ReadSingle |
Not supported |
/Customers('ALFKI')/$links/Orders |
Customers: ReadSingle-and- Orders: ReadMultiple |
Not supported | Not supported | Customers: ReadSingle and WriteMerge or WriteReplace-and- Orders: ReadSingle |
Not supported |
/Customers('ALFKI')/$links/Orders(10643) |
Customers: ReadSingle-and- Orders: ReadSingle |
Customers: ReadSingle and WriteMerge or WriteReplace-and- Orders: ReadSingle |
Not supported | Not supported | Not supported |
/Orders(10643)/$links/Customer |
Customers: ReadSingle-and- Orders: ReadSingle |
Orders: ReadSingle and WriteMerge or WriteReplace |
Customers: ReadSingle-and- Orders: ReadSingle and WriteMerge |
Not supported | Customers: ReadSingle;-and- Orders: ReadSingle and WriteReplace |
/Customers/$count |
ReadMultiple | Not supported | Not supported | Not supported | Not supported |
/Customers('ALFKI')/ContactName |
ReadSingle | Not supported | WriteMerge | Not supported | WriteReplace |
/Customers('ALFKI')/Address/StreetAddress/$value 1 |
ReadSingle | WriteDelete | Not supported | Not supported | Not supported |
/Customers('ALFKI')/ContactName/$value |
ReadSingle | ReadSingle and WriteDelete | WriteMerge | Not supported | WriteReplace |
/Customers('ALFKI')/$value 2 |
ReadSingle | Not supported | Not supported | Not supported | WriteReplace |
/Customers?$select=Orders/*&$expand=Orders |
Customers: ReadSingle-and- Orders: ReadMultiple |
Not supported | Not supported | Customers: WriteAppend |
Not supported |
/Customers('ALFKI')?$select=Orders/*&$expand=Orders |
Customers: ReadSingle-and- Orders: ReadMultiple |
Not supported | Not supported | Not supported | Not supported |
1 In this example, Address represents a complex type property of the Customers entity that has a property named StreetAddress. The model used by the Northwind data services does not explicitly define this complex type. When the data model is defined by using the Entity Framework provider, you can use the Entity Data Model tools to define such a complex type. For more information, see How to: Create and Modify Complex Types.
2 This URI is supported when a property that returns a binary large object (BLOB) is defined as the media resource that belongs to an entity that is a media link entry, which in this case, is Customers. For more information, see Streaming Provider.
Versioning Requirements
The following data service configuration behaviors require version 2 of the OData protocol, or later versions:
Support for count requests.
Support for the $select query option for projection.
For more information, see Data Service Versioning.