Toolkit CASI (Claims, Azure and SharePoint Integration) parte 4
Toolkit CASI (Claims, Azure and SharePoint Integration) parte 4
Questa è la quarta di una serie di 5 parti relative al kit CASI (Claims, Azure and SharePoint Integration). Parte 1 include una panoramica introduttiva dell'intero framework e della soluzione, oltre alla descrizione delle operazioni eseguite e trattate nella serie. Parte 2 include informazioni aggiuntive su come creare applicazioni WCF e renderle compatibili con le attestazioni e quindi su come spostarle in Windows Azure. Parte 3 include una descrizione dettagliata della classe di base che verrà utilizzata per associare il sito di SharePoint con i dati di Azure aggiungendo un nuovo controllo personalizzato a una pagina nella directory _layouts. In questo post illustrerò la web part inclusa in questo framework, progettata appositamente per interagire con il controllo personalizzato che avete creato e aggiunto alla pagina layouts nella parte 3.
Utilizzo della web part
Prima di iniziare a utilizzare la web part, si presuppone ovviamente che sia disponibile a) un servizio WCF funzionante e ospitato in Windows Azure e che b) sia stato creato un controllo personalizzato e quindi aggiunto alla pagina layouts, come descritto nella parte 3 di questa serie. Si presuppone inoltre che abbiate distribuito sia l'assembly di classi di base incluso nel kit CASI sia il vostro assembly di controlli personalizzati nella cache di assembly globale di ogni server della farm di SharePoint farm. Anche la pagina aspx personalizzata che ospita il controllo personalizzato si presuppone che sia stata distribuita alla directory layouts di ogni server web front-end nella farm. Per descrivere come utilizzare la web part, utilizzerò il progetto di esempio AzureWcfPage che ho caricato e collegato al post della parte 3. A questo punto possiamo vedere in dettaglio la procedura per unire questi due elementi per il rendering dei dati da Azure in un sito di SharePoint.
NOTA: anche se non è un requisito, sarà generalmente più facile utilizzare la web part se i metodi WCF chiamati restituiscono risultati in formato HTML in modo che possa essere visualizzato direttamente nella pagina senza ulteriore elaborazione.
Il primo passaggio consiste nel distribuire la soluzione AzureRender.wsp nella farm. Il file wsp è incluso nel file con estensione zip allegato a questo post. Contiene le funzionalità per la distribuzione della web part Azure DataView e di jQuery 1.4.2 alla directory layouts. Dopo aver distribuito la soluzione e attivato la funzionalità per una raccolta siti, sarà possibile aggiungere la web part a una pagina. A questo punto, siete quasi pronti per avviare il rendering dei dati da Azure, ma è necessario impostare almeno una proprietà. Vedremo ora quali sono questa e le altre proprietà per la web part.
Proprietà della web part
Tutte le proprietà della web part si trovano nella sezione Proprietà connessione. Come minimo, è necessario impostare la proprietà Data Page sulla pagina layouts che è stata creata e distribuita. Ad esempio, /_layouts/AzureData.aspx. Se nel tag server per il controllo personalizzato sono state definite almeno le proprietà WcfUrl e MethodName, non sarà necessario fare altro. Se non sono state effettuate altre operazioni, la web part richiamerà la pagina e utilizzerà l'endpoint e il metodo WCF configurati nella pagina, recuperando qualsiasi tipo di dati restituiti dal metodo (apparentemente in formato HTML) ed eseguendone il rendering nella web part. Nella maggior parte dei casi è probabile che desideriate utilizzare altre proprietà della web part ai fini della flessibilità, quindi le esamineremo singolarmente di seguito:
· Method Name* – Nome del metodo dell'applicazione WCF da richiamare. Se è necessario richiamare la pagina layouts tramite la funzione JavaScript personalizzata, il parametro della stringa di query per questa proprietà sarà “methodname”.
· Parameter List* – Elenco di parametri delimitato da punto e virgola per il metodo WCF. Come osservato nelle parti 2 e 3 di questa serie, sono supportati solo i tipi di dati di base, string, int, bool, long e datetime. Se si richiede un tipo di dati più complesso, sarà necessario deserializzarli prima in una stringa, quindi chiamare il metodo e serializzarli di nuovo in un tipo complesso nell'endpoint WCF. Se è necessario richiamare la pagina layouts tramite la funzione JavaScript personalizzata, il parametro della stringa di query per questa proprietà sarà “methodparams”.
· Success Callback Address – Funzione JavaScript richiamata dopo il completamento della richiesta jQuery per la pagina layouts. Per impostazione predefinita, questa proprietà utilizza la funzione JavaScript inclusa nella web part. Se si utilizza la funzione personalizzata, la relativa firma dovrà avere il seguente aspetto: function NomeFunzionePersonalizzata(resultData, resultCode, queryObject). Per ulteriori informazioni, vedere la documentazione di AJAX jQuery all'indirizzo https://api.jquery.com/jQuery.ajax/.
· Error Callback Address – Funzione JavaScript richiamata se per la richiesta jQuery per la pagine layouts si verifica un errore. Per impostazione predefinita, questa proprietà utilizza la funzione JavaScript inclusa nella web part. Se si utilizza la funzione personalizzata, la relativa firma dovrà avere il seguente aspetto: function NomeFunzionePersonalizzata(XMLHttpRequest, textStatus, errorThrown). Per ulteriori informazioni, vedere la documentazione di AJAX jQuery all'indirizzo https://api.jquery.com/jQuery.ajax/.
· Standard Error Message – Messaggio visualizzato nella web part se si verifica un errore durante l'elaborazione della web part sul lato server. Ciò significa che NON sono inclusi gli scenari in cui i dati vengono in effetti recuperati da Azure.
· Access Denied Message* – Messaggio di errore di accesso negato che verrà visualizzato se all'utente viene negato l'accesso per un metodo particolare. Come spiegato, ad esempio, nella parte 2 di questa serie, poiché si passa il token utente insieme alla chiamata WCF, è possibile specificare la richiesta PrincipalPermission per qualsiasi metodo, ad esempio “questo utente deve far parte del gruppo Sales Managers”. Se un utente non soddisfa il requisito specificato nella richiesta PrincipalPermission, la chiamata WCF avrà esito negativo e verrà restituito un errore di accesso negato. In tal caso, nella web part verrà visualizzato il valore di Access Denied Message. In questo messaggio è possibile utilizzare il formato RTF, impostare il carattere in grassetto o rosso utilizzando tag HTML (ad esempio, <font color='red'>Accesso negato, contattare l'amministratore</font>). Se è necessario richiamare la pagina layouts tramite la funzione JavaScript personalizzata, il parametro della stringa di query per questa proprietà sarà “accessdenied”.
· Timeout Message* – Messaggio visualizzato in caso di errore di timeout durante il tentativo di eseguire una chiamata del metodo WCF. È supportato anche il formato RTF, ad esempio l'impostazione del carattere grassetto, rosso e così via. Se è necessario richiamare la pagina layouts tramite la funzione JavaScript personalizzata, il parametro della stringa di query per questa proprietà sarà “timeout”.
· Show Refresh Link – Selezionare questa casella di controllo per consentire il rendering di un'icona di aggiornamento sopra il risultato dei dati di Azure. Facendo clic sull'icona, il metodo WCF verrà rieseguito per ottenere i dati più recenti.
· Refresh Style – Consente di aggiungere attributi di stile aggiuntivi all'attributo Style principale nel tag IMG utilizzato per visualizzare il collegamento tramite il quale effettuare l'aggiornamento. È possibile, ad esempio, aggiungere “float:right;” tramite questa proprietà per allineare a destra l'immagine relativa all'aggiornamento.
· Cache Results – Selezionare questa casella di controllo per fare in modo che i risultati della query vengano memorizzati nella cache della raccolta jQuery. Ciò significa che ogni volta che la pagina viene caricata, utilizzerà la versione dei risultati della query memorizzata nella cache. In questo modo si eviteranno round trip da e verso Azure, offrendo prestazioni migliori agli utenti finali. Se i dati recuperati non vengono modificati di frequente, la memorizzazione dei risultati nella cache costituisce una scelta appropriata.
· Decode Results* – Selezionare questa casella di controllo qualora l'applicazione WCF restituisca risultati di tipo HtmlEncoded. Se si imposta questa proprietà su True, ai risultati verrà applicato HtmlDecoding. Nella maggior parte dei casi ciò non è necessario. Se occorre richiamare la pagina layouts tramite la funzione JavaScript personalizzata, il parametro della stringa di query per questa proprietà sarà “encode”.
* – Queste proprietà verranno ignorate se la proprietà AllowQueryStringOverride del controllo personalizzato è impostata su False.
Tipico caso di utilizzo
Supponendo che il metodo WCF restituisca risultati in formato HTML, nella maggior parte dei casi è consigliabile aggiungere la web part a una pagina e impostare due o tre proprietà: Data Page, Method Name ed eventualmente Parameter List.
Nel caso di requisiti di visualizzazione o elaborazione più avanzati per i dati restituiti da Azure, è consigliabile utilizzare una funzione JavaScript personalizzata a questo scopo. In tal caso, è consigliabile aggiungere la funzione JavaScript alla pagina e impostare la proprietà Success Callback Address sul nome di tale funzione. Se la vostra parte richiede postback aggiuntivi all'applicazione WCF per operazioni quali aggiunte, aggiornamenti o eliminazioni, è consigliabile aggiungerli alle funzioni JavaScript personalizzate e chiamare la pagina layouts personalizzata con i valori Method Name e Parameter List appropriati. I nomi delle variabili della stringa di query da utilizzare sono documentati sopra. Quando si richiama il metodo ajax in jQuery per chiamare la pagina layouts, dovreste essere in grado di utilizzare un approccio simile a quello utilizzato dalla web part. La convenzione di chiamata utilizzata si basa sulla funzione di script seguente. Probabilmente vorrete continuare a utilizzare la proprietà dataFilter illustrata, in quanto elimina tutto l'output della pagina NON generato dal metodo WCF:
$.ajax({
type: "GET",
url: "/_layouts/SomePage.aspx",
dataType: "text",
data: "methodname=GetCustomerByEmail&methodparams=steve@contoso.local",
dataFilter: AZUREWCF_azureFilterResults,
success: yourSuccessCallback,
error: yourErrorCallback
});
Prova pratica
A questo punto dovreste disporre di tutto ciò che serve per provare la soluzione completa. A questo post è allegato un file con estensione zip contenente la soluzione per la web part. Nel successivo e ultimo post di questa serie spiegherò anche come utilizzare il controllo personalizzato sviluppato nella parte 2 per recuperare dati da Azure e utilizzarli nella cache ASP.NET con altri controlli e, inoltre, come utilizzarli nelle attività di SharePoint, nel caso specifico un processo timer personalizzato di SharePoint.
Questo è un post di blog localizzato. L'articolo originale è disponibile in The Claims, Azure and SharePoint Integration Toolkit Part 4