Utilizzo di azioni OData per implementare il comportamento lato server
OData (Open Data Protocol) consente di definire l'azione di servizio su un servizio dati. L'azione di servizio è un'operazione speciale definita in un servizio dati. Le azioni di servizio forniscono un modo per inserire comportamenti in un modello altrimenti basato sui dati. Le azioni di servizio consentono di richiamare logica di business in OData, in cui la logica deve essere associata a una determinata risorsa. Le azioni di servizio differiscono dalle normali operazioni di servizio basate su endpoint nei modi seguenti:
Associazione a risorse
A differenza delle operazioni di servizio definite in un endpoint fisso, le azioni di servizio sono in genere associate a risorse, set di entità (feed) o singole entità. Queste risorse sono note come parametri di associazione In WCF Data Services i parametri di associazione possono essere esclusivamente tipi di entità e raccolte di tipi di entità. Alle azioni di servizio è inoltre possibile fornire parametri di non associazione. Questi parametri possono tuttavia essere esclusivamente di tipo primitivo, complesso oppure una raccolta di questi due tipi. Se un'azione di servizio è associata a una risorsa, l'azione è esposta nella serializzazione dell'entità come risorsa di azione.
Effetti collaterali
La logica di business richiamata da un'azione di servizio incide sul sistema, ad esempio modificando i dati o lo stato oppure richiamando un altro processo aziendale. Poiché le azioni di servizio presentano sempre effetti collaterali, possono essere richiamate esclusivamente mediante una richiesta POST. A differenza delle operazioni di servizio, vengono forniti parametri non di associazione alle azioni di servizio nel corpo del messaggio, anziché nell'URI. Questi parametri vengono forniti come valori con codifica JavaScript Notation (JSON) nel corpo della richiesta.
Impossibilità di ulteriore composizione
Le azioni di servizio possono disporre degli stessi tipi restituiti delle operazioni di servizio. Tuttavia, a differenza di queste ultime, le azioni non possono essere ulteriormente composte. A un'azione di servizio non è quindi possibile applicare opzioni di query di sistema.
Se si considera come risorsa un filmato digitale, sono diverse le operazioni che è possibile eseguire, ad esempio l'estrazione, la valutazione, l'aggiunta di commenti o l'archiviazione. Sono tutti esempi di azioni che possono essere implementate da un servizio di WCF Data Services che gestisce i filmati digitali. Le azioni vengono descritte in una risposta OData che contiene una risorsa in cui l'azione può essere richiamata. Quando un utente richiede una risorsa che rappresenta un filmato digitale, la risposta restituita da un servizio di WCF Data Services contiene le informazioni sulle azioni disponibili per tale risorsa. La disponibilità di un'azione può dipendere dallo stato del servizio dati o della risorsa. Ad esempio, una volta estratto, un filmato digitale non può essere estratto da un altro utente. I client possono richiamare un'azione semplicemente specificando un URL. Ad esempio http://MyServer/MovieService.svc/Movies(6) identifica un filmato digitale specifico e http://MyServer/MovieService.svc/Movies(6)/Checkout richiama l'azione sul filmato specifico. Le azioni consentono di esporre il modello di servizio senza esporre il modello di dati. Continuando con l'esempio del servizio del filmato, è possibile che si desideri consentire a un utente di valutare un filmato ma non di esporre direttamente i dati della valutazione come risorsa. È possibile implementare un'azione Rate per consentire all'utente di valutare un filmato ma non di accedere direttamente ai dati della valutazione come risorsa.
Implementazione di un'azione
Per implementare un'azione di servizio, è necessario implementare le interfacce IServiceProvider, IDataServiceActionProvider e IDataServiceInvokable. IServiceProvider consente a WCF Data Services di ottenere l'implementazione di IDataServiceActionProvider. IDataServiceActionProvider consente a WCF Data Services di creare, trovare, descrivere e richiamare le azioni di servizio. IDataServiceInvokable consente di richiamare il codice che implementa il comportamento delle azioni di servizio e di ottenere i risultati, se disponibili. Tenere presente che WCF Data Services contiene servizi WCF "per chiamata", ovvero ogni volta che viene chiamato il servizio, verrà creata una nuova istanza del servizio. Assicurarsi che non vengano eseguite operazioni non necessarie quando viene creato il servizio.
IServiceProvider
IServiceProvider contiene un metodo denominato GetService(Type). Questo metodo viene chiamato da WCF Data Services per recuperare diversi provider di servizi, tra cui provider di servizi di metadati e provider di azioni di servizio dati. Quando viene richiesto un provider di azioni di servizio dati, viene restituita l'implementazione di IDataServiceActionProvider.
IDataServiceActionProvider
IDataServiceActionProvider contiene i metodi che consentono di recuperare le informazioni sulle azioni disponibili. Quando si implementa IDataServiceActionProvider, ai metadati del servizio definito dall'implementazione del servizio di IDataServiceMetadataProvider vengono aggiunte le azioni. Viene inoltre gestita la distribuzione a tali azioni, se necessario.
AdvertiseServiceAction
AdvertiseServiceAction(DataServiceOperationContext, ServiceAction, Object, Boolean, ODataAction%) viene chiamato per determinare le azioni disponibili per la risorsa specificata. Questo metodo viene chiamato solo per le azioni che non sono sempre disponibili. Viene utilizzato per verificare se l'azione deve essere inclusa nella risposta OData in base allo stato della risorsa richiesta o allo stato del servizio. La modalità con cui viene eseguita tale verifica viene scelta dall'utente. Se calcolare la disponibilità richiede tempo e la risorsa corrente è presente in un feed, è possibile ignorare la verifica e annunciare l'azione. Il parametro inFeed viene impostato su true se la risorsa corrente da restituire fa parte di un feed.
CreateInvokable
CreateInvokable(DataServiceOperationContext, ServiceAction, array<Object[]) viene chiamato per creare un oggetto IDataServiceInvokable che contiene un delegato che incapsula il codice che implementa il comportamento dell'azione. Questo metodo crea l'istanza di IDataServiceInvokable ma non richiama l'azione. Le azioni di WCF Data Services hanno effetti collaterali e devono essere utilizzate insieme al provider di aggiornamento per salvare le modifiche su disco. Il metodo Invoke() viene chiamato dal metodo SaveChanges() del provider di aggiornamento.
GetServiceActions
Questo metodo restituisce una raccolta di istanze di ServiceAction che rappresentano tutte le azioni esposte da un servizio di WCF Data Services. ServiceAction è la rappresentazione dei metadati di un'azione che include informazioni quali il nome dell'azione, i relativi parametri e il relativo tipo restituito.
GetServiceActionsByBindingParameterType
Questo metodo restituisce una raccolta di tutte le istanze di ServiceAction che possono essere associate al tipo di parametro di associazione specificato. In altre parole, tutti gli oggetti ServiceAction che possono agire sul tipo di risorsa specificato, detto anche tipo di parametro di associazione. Viene utilizzato quando il servizio restituisce una risorsa per includere le informazioni sulle azioni che possono essere richiamate sulla risorsa. Questo metodo deve restituire solo le azioni che è possibile associare al tipo di parametro di associazione esatto (nessun tipo derivato). Il metodo viene chiamato una volta per ogni richiesta per tipo rilevato e il risultato viene memorizzato nella cache da WCF Data Services.
TryResolveServiceAction
Questo metodo cerca un oggetto ServiceAction specificato e restituisce true se l'oggetto ServiceAction viene trovato. Se trovato, ServiceAction viene restituito nel parametro serviceAction out.
IDataServiceInvokable
Questa interfaccia consente di eseguire un'azione di WCF Data Services. Quando si implementa IDataServiceInvokable, si è responsabili di tre operazioni:
Acquisizione e marshalling potenziale dei parametri
Distribuzione dei parametri nel codice che implementa effettivamente l'azione quando viene chiamato Invoke()
Archiviazione dei risultati restituiti da Invoke() in modo da poter essere recuperati mediante GetResult()
I parametri possono essere passati come token poiché è possibile scrivere un provider di servizi dati da utilizzare con i token che rappresentano le risorse. In tal caso, potrebbe essere necessario convertire (effettuare il marshalling) i token in risorse effettive prima della distribuzione all'azione effettiva. Dopo il marshalling del parametro, è necessario che venga impostato uno stato modificabile in modo tale che tutte le modifiche alla risorsa, che si verificano quando l'azione viene richiamata, vengano salvate e scritte su disco.
Questa interfaccia richiede due metodi: Invoke e GetResult. Invoke richiama il delegato che implementa il comportamento dell'azione e GetResult restituisce il risultato dell'azione.
Controllo di accesso alle azioni di servizio
In WCF Data Services la visibilità a livello di servizi delle azioni di servizio è controllata dal metodo SetServiceActionAccessRule(String, ServiceActionRights) nella classe IDataServiceConfiguration nello stesso modo in cui la visibilità delle operazioni di servizio vengono controllate mediante il metodo SetServiceOperationAccessRule(String, ServiceOperationRights).
Definizione di metadati delle azioni di servizio
In modo analogo alle operazioni di servizio, le azioni di servizio vengono definite come elementi FunctionImport nei metadati del servizio. Un'azione di servizio FunctionImport contiene zero o più elementi Parameter che rappresentano parametri di associazione e non associazione. Gli attributi seguenti in FunctionImport definiscono inoltre il comportamento dell'azione di servizio:
IsSideEffecting
Poiché le azioni di servizio possono presentare effetti collaterali, questo attributo è sempre true.
IsBindable
Le azioni di servizio sono in genere (ma non sempre) associate a una risorsa. Se questo attributo è true, il primo parametro deve essere un tipo o una raccolta di entità.
IsComposable
Poiché le azioni di servizio non supportano ulteriore composizione di query, questo attributo è sempre false.
Richiamo di un'azione di WCF Data Services
Le azioni vengono richiamate mediante una richiesta HTTP POST. L'URL specifica la risorsa seguita dal nome dell'azione. I parametri vengono passati nel corpo della richiesta. Se ad esempio è presente un servizio denominato MovieService che espone un'azione denominata Rate, è possibile utilizzare l'URL seguente per richiamare l'azione Rate in un filmato specifico:
http://MovieServer/MovieService.svc/Movies(1)/Rate
Movies(1) specifica il filmato che si desidera valutare e Rate specifica l'azione di valutazione. Il valore effettivo della valutazione sarà presente nel corpo della richiesta HTTP come mostrato nell'esempio seguente:
POST http://MovieServer/MoviesService.svc/Movies(1)/Rate HTTP/1.1
Content-Type: application/json
Content-Length: 20
Host: localhost:15238
{
"rating": 4
}
Avviso
Il codice di esempio precedente funzionerà solo con WCF Data Services 5.2 e versioni successive che supportano la versione light di JSON.Se si utilizza una versione precedente di WCF Data Services, è necessario specificare il tipo di contenuto json verbose come segue: application/json;odata=verbose.
In alternativa, è possibile richiamare un'azione mediante il client di WCF Data Services come mostrato nel frammento di codice seguente.
MoviesModel context = new MoviesModel (new Uri("http://MyServer/MoviesService.svc/"));
//...
context.Execute(new Uri("http://MyServer/MoviesService.svc/Movies(1)/Rate"), "POST", new BodyOperationParameter("rating",4) );
Nel frammento di codice precedente la classe MoviesModel è stata generata mediante la procedura per aggiungere il riferimento a un servizio WCF Data Services in Visual Studio.
Vedere anche
Concetti
Sviluppo e distribuzione di WCF Data Services
Provider di servizi dati personalizzati (WCF Data Services)