Operazioni di servizio (WCF Data Services)Service Operations (WCF Data Services)

WCF Data ServicesWCF Data Services consente di definire operazioni del servizio in un servizio dati per esporre metodi nel server. enables you to define service operations on a data service to expose methods on the server. Allo stesso modo di altre risorse del servizio dati, le operazioni del servizio vengono indirizzate mediante URI.Like other data service resources, service operations are addressed by URIs. Le operazioni del servizio consentono di esporre la logica di business in un servizio dati, ad esempio per implementare la logica di convalida, per applicare la sicurezza basata sui ruoli o per esporre funzionalità di query specializzate.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. Le operazioni del servizio sono metodi aggiunti alla classe del servizio dati che deriva da DataService<T>.Service operations are methods added to the data service class that derives from DataService<T>. Analogamente a tutte le altre risorse del servizio dati, è possibile fornire parametri al metodo dell'operazione del servizio.Like all other data service resources, you can supply parameters to the service operation method. Ad esempio, la seguente operazione URI del servizio (in base il delle Guide rapide servizio dati) passa il valore London per il city parametro:For example, the following service operation URI (based on the quickstart data service) passes the value London to the city parameter:

http://localhost:12345/Northwind.svc/GetOrdersByCity?city='London'  

La definizione per questa operazione del servizio è la seguente:The definition for this service operation is as follows:

[WebGet]
public IQueryable<Order> GetOrdersByCity(string city)
<WebGet()> _
Public Function GetOrdersByCity(ByVal city As String) As IQueryable(Of Order)

È possibile usare la proprietà CurrentDataSource dell'oggetto DataService<T> per accedere direttamente all'origine dati usata dal servizio dati.You can use the CurrentDataSource of the DataService<T> to directly access the data source that the data service is using. Per ulteriori informazioni, vedere procedura: definire un'operazione del servizio.For more information, see How to: Define a Service Operation.

Per informazioni su come chiamare un'operazione del servizio da un'applicazione client .NET Framework, vedere la chiamata a operazioni del servizio.For information on how to call a service operation from a .NET Framework client application, see Calling Service Operations.

Requisiti delle operazioni del servizioService Operation Requirements

I requisiti seguenti si applicano in caso di definizione di operazioni del servizio nel servizio dati.The following requirements apply when defining service operations on the data service. Se un metodo non soddisfa questi requisiti, non verrà esposto come operazione del servizio per il servizio dati.If a method does not meet these requirements, it will not be exposed as a service operation for the data service.

  • L'operazione deve essere un metodo di istanza pubblica, ovvero un membro della classe del servizio dati.The operation must be a public instance method that is a member of the data service class.

  • È possibile che il metodo dell'operazione accetti solo parametri di input.The operation method may only accept input parameters. L'accesso ai dati inviati nel corpo del messaggio non può essere eseguito dal servizio dati.Data sent in the message body cannot be accessed by the data service.

  • Se sono definiti parametri, il tipo di ogni parametro deve essere primitivo.If parameters are defined, the type of each parameter must be a primitive type. I dati di un tipo non primitivo devono essere serializzati e passati in un parametro di stringa.Any data of a non-primitive type must be serialized and passed into a string parameter.

  • Il metodo deve restituire uno degli elementi seguenti:The method must return one of the following:

    • void (Nothing in Visual Basic)void (Nothing in Visual Basic)

    • IEnumerable<T>

    • IQueryable<T>

    • Un tipo di entità nel modello di dati esposto dal servizio dati.An entity type in the data model that the data service exposes.

    • Una classe primitiva, ad esempio Integer o stringa.A primitive class such as integer or string.

  • Per supportare opzioni di query di ordinamento, paging e filtro, i metodi delle operazioni del servizio devono restituire IQueryable<T>.In order to support query options such as sorting, paging, and filtering, service operation methods should return IQueryable<T>. Le richieste a operazioni del servizio che includono opzioni di query vengono rifiutate per le operazioni che restituiscono solo IEnumerable<T>.Requests to service operations that include query options are rejected for operations that only return IEnumerable<T>.

  • Per supportare l'accesso alle entità correlate tramite le proprietà di navigazione, l'operazione del servizio deve restituire IQueryable<T>.In order to support accessing related entities by using navigation properties, the service operation must return IQueryable<T>.

  • Il metodo deve essere annotato con l'attributo [WebGet] o [WebInvoke].The method must be annotated with the [WebGet] or [WebInvoke] attribute.

    • [WebGet] abilita il metodo da richiamare tramite una richiesta GET.[WebGet] enables the method to be invoked by using a GET request.

    • [WebInvoke(Method = "POST")] abilita il metodo da richiamare tramite una richiesta POST.[WebInvoke(Method = "POST")] enables the method to be invoked by using a POST request. Altri metodi WebInvokeAttribute non sono supportati.Other WebInvokeAttribute methods are not supported.

  • Un'operazione del servizio può essere annotata con SingleResultAttribute che specifica che il valore restituito dal metodo è una singola entità anziché una raccolta di entità.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. Questa distinzione determina la serializzazione della risposta e il modo in cui gli attraversamenti delle proprietà di navigazione aggiuntivi vengono rappresentati nell'URI.This distinction dictates the resulting serialization of the response and the manner in which additional navigation property traversals are represented in the URI. Nel caso di utilizzo della serializzazione AtomPub, ad esempio, un'istanza singola del tipo di risorsa viene rappresentata come elemento entry e un set di istanze come elemento feed.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.

Indirizzamento di operazioni di servizioAddressing Service Operations

È possibile indirizzare le operazioni del servizio inserendo il nome del metodo nel primo segmento di percorso di un URI.You can address service operations by placing the name of the method in the first path segment of a URI. Ad esempio, l'URI riportato di seguito consente l'accesso a un'operazione GetOrdersByState che restituisce una raccolta IQueryable<T> di oggetti Orders.As an example, the following URI accesses a GetOrdersByState operation that returns an IQueryable<T> collection of Orders objects.

http://localhost:12345/Northwind.svc/GetOrdersByState?state='CA'&includeItems=true  

Quando si chiama un'operazione del servizio, i parametri vengono forniti come opzioni query.When calling a service operation, parameters are supplied as query options. L'operazione del servizio precedente accetta sia un parametro di stringa state che un parametro booleano includeItems che indicano se includere oggetti Order_Detail correlati nella risposta.The previous service operation accepts both a string parameter state and a Boolean parameter includeItems that indicates whether to include related Order_Detail objects in the response.

Di seguito sono riportati i tipi restituiti validi per un'operazione del servizio:The following are valid return types for a service operation:

Tipi restituiti validiValid Return Types Regole URIURI Rules
void (Nothing in Visual Basic)void (Nothing in Visual Basic)

-oppure--or-

Tipi di entitàEntity types

-oppure--or-

Tipi primitiviPrimitive types
L'URI deve essere costituito da un singolo segmento di percorso corrispondente al nome dell'operazione del servizio.The URI must be a single path segment that is the name of the service operation. Le opzioni di query non sono consentite.Query options are not allowed.
IEnumerable<T> L'URI deve essere costituito da un singolo segmento di percorso corrispondente al nome dell'operazione del servizio.The URI must be a single path segment that is the name of the service operation. Poiché il tipo di risultato non è un tipo IQueryable<T>, le opzioni di query non sono consentite.Because the result type is not an IQueryable<T> type, query options are not allowed.
IQueryable<T> Oltre al percorso corrispondente al nome dell'operazione del servizio, sono consentiti segmenti di percorso di query.Query path segments in addition to the path that is the name of the service operation are allowed. Sono consentite anche le opzioni di query.Query options are also allowed.

A seconda del tipo restituito dell'operazione del servizio, è possibile aggiungere all'URI segmenti di percorso o opzioni di query aggiuntive.Additional path segments or query options may be added to the URI depending on the return type of the service operation. Ad esempio, l'URI riportato di seguito consente l'accesso a un'operazione GetOrdersByCity che restituisce una raccolta IQueryable<T> di oggetti Orders ordinati in ordine decrescente in base a RequiredDate insieme agli oggetti Order_Details correlati:For example, the following URI accesses a GetOrdersByCity operation that returns an IQueryable<T> collection of Orders objects, ordered by RequiredDate in descending order, along with the related Order_Details objects:

http://localhost:12345/Northwind.svc/GetOrdersByCity?city='London'&$expand=Order_Details&$orderby=RequiredDate desc  

Controllo di accesso alle operazioni del servizioService Operations Access Control

La visibilità a livello di servizio delle operazioni del servizio viene controllata dal metodo SetServiceOperationAccessRule sulla classe IDataServiceConfiguration pressoché nello stesso modo in cui viene controllata la visibilità del set di entità tramite il metodo SetEntitySetAccessRule.Service-wide visibility of service operations is controlled by the SetServiceOperationAccessRule method on the IDataServiceConfiguration class in much the same way that entity set visibility is controlled by using the SetEntitySetAccessRule method. Ad esempio, la riga di codice seguente nella definizione del servizio dati abilita l'accesso all'operazione del servizio CustomersByCity.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)

Nota

Se un'operazione del servizio dispone di un tipo restituito nascosto mediante limitazione dell'accesso nei set di entità sottostanti, l'operazione del servizio non sarà disponibile alle applicazioni client.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.

Per ulteriori informazioni, vedere procedura: definire un'operazione del servizio.For more information, see How to: Define a Service Operation.

Generazione di eccezioniRaising Exceptions

È consigliabile usare la classe DataServiceException quando si genera un'eccezione nell'esecuzione del servizio dati,We recommend that you use the DataServiceException class whenever you raise an exception in the data service execution. poiché il runtime del servizio dati è in grado di eseguire il mapping delle proprietà di questo oggetto eccezione al messaggio di risposta HTTP in modo corretto.This is because the data service runtime knows how to map properties of this exception object correctly to the HTTP response message. Quando si genera un oggetto DataServiceException in un'operazione del servizio, verrà eseguito il wrapping dell'eccezione restituita in un oggetto TargetInvocationException.When you raise a DataServiceException in a service operation, the returned exception is wrapped in a TargetInvocationException. Per restituire l'oggetto DataServiceException di base senza includere l'oggetto TargetInvocationException, è necessario eseguire l'override del metodo HandleException in DataService<T>, estrarre DataServiceException da TargetInvocationException e restituirlo come errore di livello superiore, come illustrato nell'esempio seguente:To return the base DataServiceException without the enclosing TargetInvocationException, you must override the HandleException method in the DataService<T>, extract the DataServiceException from the TargetInvocationException, and return it as the top-level error, as in the following example:

// Override to manage returned exceptions.
protected override void HandleException(HandleExceptionArgs args)
{
    // Handle exceptions raised in service operations.
    if (args.Exception.GetType() ==
        typeof(TargetInvocationException)
        && args.Exception.InnerException != null)
    {
        if (args.Exception.InnerException.GetType()
            == typeof(DataServiceException))
        {

            // Unpack the DataServiceException.
            args.Exception = args.Exception.InnerException as DataServiceException;

        }
        else
        {
            // Return a new DataServiceException as "400: bad request."
            args.Exception =
                new DataServiceException(400,
                    args.Exception.InnerException.Message);
        }
    }
}
' Override to manage returned exceptions.
Protected Overrides Sub HandleException(args As HandleExceptionArgs)
    ' Handle exceptions raised in service operations.
    If args.Exception.GetType() = GetType(TargetInvocationException) _
        AndAlso args.Exception.InnerException IsNot Nothing Then
        If args.Exception.InnerException.GetType() = GetType(DataServiceException) Then
            ' Unpack the DataServiceException.
            args.Exception = _
                TryCast(args.Exception.InnerException, DataServiceException)
        Else
            ' Return a new DataServiceException as "400: bad request."
            args.Exception = _
                New DataServiceException(400, args.Exception.InnerException.Message)
        End If
    End If
End Sub

Vedere ancheSee Also

IntercettoriInterceptors