Share via

Configuring the Data Service (WCF Data Services)

  • Article

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 Service Providers (WCF Data Services).

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 Northwind service that you create when you complete the quickstart:

Public Class Northwind
    Inherits DataService(Of NorthwindEntities)

    ' This method is called only once to initialize service-wide policies.
    Public Shared Sub InitializeService(ByVal config As DataServiceConfiguration)
        ' Grant only the rights needed to support the client application.
        config.SetEntitySetAccessRule("Orders", EntitySetRights.AllRead _
             Or EntitySetRights.WriteMerge _
             Or EntitySetRights.WriteReplace)
        config.SetEntitySetAccessRule("Order_Details", EntitySetRights.AllRead _
            Or EntitySetRights.AllWrite)
        config.SetEntitySetAccessRule("Customers", EntitySetRights.AllRead)
    End Sub
End Class

public class Northwind : DataService<NorthwindEntities>
{
    // This method is called only once to initialize service-wide policies.
    public static void InitializeService(DataServiceConfiguration config)
    {
        // Grant only the rights needed to support the client application.
        config.SetEntitySetAccessRule("Orders", EntitySetRights.AllRead
             | EntitySetRights.WriteMerge
             | EntitySetRights.WriteReplace);
        config.SetEntitySetAccessRule("Order_Details", EntitySetRights.AllRead
            | EntitySetRights.AllWrite);
        config.SetEntitySetAccessRule("Customers", EntitySetRights.AllRead);
        config.DataServiceBehavior.MaxProtocolVersion =
            System.Data.Services.Common.DataServiceProtocolVersion.V3;
    }
}

Data Service Configuration Settings

The DataServiceConfiguration class enables you to specify the following data service behaviors:

Member

Behavior

AcceptAnyAllRequests

Enables you to disable support for queries that include the any and all operators.

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.

AcceptSpatialLiteralsInQuery

Enables you to disable support for supplying spatial literal values in a query URI.

AnnotationsBuilder

Enables you to apply vocabularies to the data model by using annotations. The AnnotationsBuilder property returns a delegate that enables you to supply one or more model annotations, as a collection of IEdmModel instances, for the data model, which is supplied to the delegate as an IEdmModel instance. For more information, see the post Vocabularies in WCF Data Services.

DisableValidationOnMetadataWrite

Enables you to disable validation of the data model before the service responds to a request to the $metadata endpoint.

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.

IncludeAssociationLinksInResponse

Enables you to specify whether link elements that specifically address the relationship between entities, also called associations, are included in the response from the data service. Associations are addressed by using the $links operator. For more information, see 3.2. Addressing Links between Entries in the OData protocol. The data service always returns link elements that address related entities, even when IncludeAssociationLinksInResponse is false.

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 (WCF Data Services).

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 (WCF Data Services).

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 see OData: URI Conventions and Loading Deferred Content (WCF Data Services).

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 see OData: URI Conventions and Loading Deferred Content (WCF Data Services).

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 (WCF Data Services).

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 (WCF Data Services).

SetServiceActionAccessRule(String, ServiceActionRights)

Sets the access rights for service actions that are defined on the data service. For more information, see Using OData Actions to implement server-side behavior. An asterisk (*) value can be supplied for the name parameter to set access for all service actions to the same level. We recommend that you set access to service actions to provide the least privilege access to data service resources that are required by client applications. For more information, see Securing WCF Data Services.

SetServiceOperationAccessRule

Sets the access rights for service operations that are defined on the data service. For more information, see Service Operations (WCF Data Services). 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 (WCF Data Services).

URI Path and Query Option

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/$value1

ReadSingle

WriteDelete

Not supported

Not supported

Not supported

/Customers('ALFKI')/ContactName/$value

ReadSingle

ReadSingle and WriteDelete

WriteMerge

Not supported

WriteReplace

/Customers('ALFKI')/$value2

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 (Entity Data Model Tools).

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 (WCF Data Services).

Versioning Requirements

The following data service configuration behaviors require version 3 of the OData protocol, or later versions:

  • Support for including relationship link elements in the response feed.

  • Support for any and all query operators.

  • Support for defining service actions and functions.

  • Support for spatial data types.

  • Support for vocabularies by defining data model annotations.

  • Support for disabling data model validation for a $metadata endpoint request.

The following data service configuration behaviors require version 2 of the OData protocol, or later versions:

  • Support for count requests and query projection requires version 2.0 of the OData protocol and later versions.

  • Support for the $select query option for projection requires version 2.0 of the OData protocol and later versions.

For more information, see Data Service Versioning (WCF Data Services).

See Also

Concepts

Hosting the Data Service (WCF Data Services)

Other Resources

Data Service (WCF Data Services)