Operazioni del servizio (WCF Data Services)

WCF Data Services consente di definire operazioni del servizio in un servizio dati per esporre metodi nel server. Allo stesso modo di altre risorse del servizio dati, le operazioni del servizio vengono indirizzate mediante URI. 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. Le operazioni del servizio sono metodi aggiunti alla classe del servizio dati che deriva da DataService<T>. Analogamente a tutte le altre risorse del servizio dati, è possibile fornire parametri al metodo dell'operazione del servizio. L'URI dell'operazione del servizio seguente, basato sul servizio dati della Guida rapida, passa ad esempio il valore London al parametro city:

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

La definizione per questa operazione del servizio è la seguente:

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

[WebGet]
public IQueryable<Order> GetOrdersByCity(string city)

È possibile utilizzare la proprietà CurrentDataSource dell'oggetto DataService<T> per accedere direttamente all'origine dati utilizzata dal servizio dati. Per ulteriori informazioni, vedere Procedura: definire un'operazione del servizio (WCF Data Services).

Per informazioni su come chiamare un'operazione del servizio da un'applicazione client .NET Framework, vedere Chiamata di operazioni e azioni di servizio (WCF Data Services).

Requisiti delle operazioni del servizio

I requisiti seguenti si applicano in caso di definizione di operazioni del servizio nel servizio dati. Se un metodo non soddisfa questi requisiti, non verrà esposto come operazione del servizio per il servizio dati.

• L'operazione deve essere un metodo di istanza pubblica, ovvero un membro della classe del servizio dati.

• È possibile che il metodo dell'operazione accetti solo parametri di input. L'accesso ai dati inviati nel corpo del messaggio non può essere eseguito dal servizio dati.

• Se sono definiti parametri, il tipo di ogni parametro deve essere primitivo. I dati di un tipo non primitivo devono essere serializzati e passati in un parametro di stringa.

• Il metodo deve restituire uno degli elementi seguenti:

  • void (Nothing in Visual Basic)

  • IEnumerable<T>

  • IQueryable<T>

  • Un tipo di entità nel modello di dati esposto dal servizio dati.

  • Una classe primitiva, ad esempio Integer o stringa.

• Per supportare opzioni di query di ordinamento, paging e filtro, i metodi delle operazioni del servizio devono restituire IQueryable<T>. Le richieste a operazioni del servizio che includono opzioni di query vengono rifiutate per le operazioni che restituiscono solo IEnumerable<T>.

• Per supportare l'accesso alle entità correlate tramite le proprietà di navigazione, l'operazione del servizio deve restituire IQueryable<T>.

• Il metodo deve essere annotato con l'attributo [WebGet] o [WebInvoke].

  • [WebGet] abilita il metodo da richiamare tramite una richiesta GET.

  • [WebInvoke(Method = "POST")] abilita il metodo da richiamare tramite una richiesta POST. Altri metodi WebInvokeAttribute non sono supportati.

• 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à. Questa distinzione determina la serializzazione della risposta e il modo in cui gli attraversamenti delle proprietà di navigazione aggiuntivi vengono rappresentati nell'URI. Ad esempio, quando si utilizza la serializzazione AtomPub, una singola istanza del tipo di risorsa viene rappresentata come elemento entry e un set di istanze come elemento feed.

Indirizzamento delle operazioni del servizio

È possibile indirizzare le operazioni del servizio inserendo il nome del metodo nel primo segmento di percorso di un URI. Ad esempio, l'URI riportato di seguito consente l'accesso a un'operazione GetOrdersByState che restituisce una raccolta IQueryable<T> di oggetti Orders.

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

Quando si chiama un'operazione del servizio, i parametri vengono forniti come opzioni query. 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.

Di seguito sono riportati i tipi restituiti validi per un'operazione del servizio:

Tipi restituiti validi	Regole URI
void (Nothing in Visual Basic) -oppure- Tipi di entità -oppure- Tipi primitivi	L'URI deve essere costituito da un singolo segmento di percorso corrispondente al nome dell'operazione del servizio. Le opzioni di query non sono consentite.
IEnumerable<T>	L'URI deve essere costituito da un singolo segmento di percorso corrispondente al nome dell'operazione del servizio. Poiché il tipo di risultato non è un tipo IQueryable<T>, le opzioni di query non sono consentite.
IQueryable<T>	Oltre al percorso corrispondente al nome dell'operazione del servizio, sono consentiti segmenti di percorso di query. Sono consentite anche le opzioni di query.

A seconda del tipo restituito dell'operazione del servizio, è possibile aggiungere all'URI segmenti di percorso o opzioni di query aggiuntive. 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:

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

Controllo di accesso alle operazioni del servizio

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. Ad esempio, la riga di codice seguente nella definizione del servizio dati abilita l'accesso all'operazione del servizio CustomersByCity.

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.

Per ulteriori informazioni, vedere Procedura: definire un'operazione del servizio (WCF Data Services).

Generazione di eccezioni

È consigliabile utilizzare la classe DataServiceException quando si genera un'eccezione nell'esecuzione del servizio dati, 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. Quando si genera un oggetto DataServiceException in un'operazione del servizio, verrà eseguito il wrapping dell'eccezione restituita in un oggetto TargetInvocationException. Per restituire l'oggetto DataServiceException di base senza includere l'oggetto TargetInvocationException, è necessario eseguire l'override del metodo HandleException(HandleExceptionArgs) in DataService<T>, estrarre DataServiceException da TargetInvocationException e restituirlo come errore di livello superiore, come illustrato nell'esempio seguente:

' 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

// 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);
        }
    }
}

Vedere anche

Concetti

Intercettori (WCF Data Services)