Configuring the Data Service (ADO.NET Data Services)

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.

With ADO.NET Data Services, you can create a data service that is based on an Entity Framework data model, a class that implements IQueryable, or a data service that is dynamically defined by implementing the IDataServiceMetadataProvider and the IDataServiceQueryProvider interfaces. For more information, see Data Services Providers (ADO.NET Data Services). A data service is a class that inherits from the DataService 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 that is 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)
        ' Make certain entity sets writable.
        config.SetEntitySetAccessRule("Customers", EntitySetRights.All)
        config.SetEntitySetAccessRule("Employees", EntitySetRights.All)
        config.SetEntitySetAccessRule("Orders", EntitySetRights.All)
        config.SetEntitySetAccessRule("Order_Details", EntitySetRights.All)
        config.SetEntitySetAccessRule("Products", EntitySetRights.All)

        ' Make the remaining entity sets read-only.
        config.SetEntitySetAccessRule("*", 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)
    {
        // Make certain entity sets writable.
        config.SetEntitySetAccessRule("Customers", EntitySetRights.All); 
        config.SetEntitySetAccessRule("Employees", EntitySetRights.All);
        config.SetEntitySetAccessRule("Orders", EntitySetRights.All);
        config.SetEntitySetAccessRule("Order_Details", EntitySetRights.All);
        config.SetEntitySetAccessRule("Products", EntitySetRights.All);

        // Make the remaining entity sets read-only.
        config.SetEntitySetAccessRule("*", EntitySetRights.AllRead);
    }
}

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 Special Resource Paths (ADO.NET Data Services) and Query Expressions (ADO.NET Data Services).
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 Query Expressions (ADO.NET Data Services) and Query Projections (ADO.NET Data Services).
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 ADO.NET Data Services is not available to clients accessing the data service. For more information, see Working with Working with Multiple Versions of ADO.NET Data Services.
EnableTypeAccess(String)	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.
MaxBatchCount()	Enables you to limit the number of change sets and query operations that are allowed in a single batch. For more information, see Batch Requests (ADO.NET Data Services) and Batching Operations (ADO.NET 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 (ADO.NET 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 Query Expressions (ADO.NET Data Services) and Loading Deferred Content (ADO.NET 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 Query Expressions (ADO.NET Data Services) and Loading Deferred Content (ADO.NET Data Services).
MaxObjectCountOnInsert()	Enables you to limit the number of entities to be inserted that can be contained in a single POST request.
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(Type)	Adds a data type to the list of types that are recognized by the data service.
SetEntitySetAccessRule(String, EntitySetRights)	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 examples of the minimum access rights required for a given URI and HTTP action, see the table in the following Minimum Resource Access Rights section.
SetEntitySetPageSize(String, Int32)	Sets the maximum page size for an entity set resource. For more information, see How to: Enable Paging of Data Service Results (ADO.NET Data Services).
SetServiceOperationAccessRule(String, ServiceOperationRights)	Sets the access rights for service operations that are defined on the data service. For more information, see Service Operations (ADO.NET 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.
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.

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. 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/$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 Working with Binary Data (ADO.NET Data Services).

See Also

Other Resources

Defining a Data Service (ADO.NET Data Services)

Hosting the Data Service (ADO.NET Data Services)