Toolkit CASI (Claims, Azure and SharePoint Integration) parte 3
Toolkit CASI (Claims, Azure and SharePoint Integration) parte 3
Questa è la terza parte di una serie in 5 parti dedicata al kit CASI (Claims, Azure and SharePoint Integration). Parte 1: presentazione introduttiva del framework e della soluzione nel suo complesso, con una descrizione degli obiettivi della serie a livello di contenuti. Parte 2: informazioni aggiuntive e istruzioni per la creazione di applicazioni WCF in grado di riconoscere attestazioni, con successivo spostamento in Windows Azure. In questo post verrà illustrato uno dei principali risultati finali di questo framework, ovvero una classe di base per un controllo personalizzato utilizzato per la connessione da SharePoint all'applicazione WCF ospitata in Windows Azure. Questi sono gli elementi che verranno trattati:
· La classe di base: di cosa si tratta e come viene utilizzata nel progetto
· Una pagina Layouts: come si aggiunge il nuovo controllo in una pagina nella directory _layouts
· Proprietà importanti: informazioni su alcune delle proprietà importanti da conoscere per la classe di base
Classe di base del kit CASI
Uno dei principali risultati finali del kit CASI è la classe di base per un controllo personalizzato utilizzato per la connessione all'applicazione WCF e l'inoltro delle richieste con il token di accesso dell'utente corrente. La classe di base è un controllo server ASP.NET standard e per l'implementazione di questo modello di sviluppo è necessario creare un nuovo controllo server ASP.NET che eredita da questa classe di base. Per motivi che non verranno illustrati perché esulano dagli scopi di questo post, il controllo dovrà eseguire assolutamente due operazioni:
1. Creare un riferimento al servizio per l'applicazione WCF ospitata in Windows Azure.
2. Eseguire l'override del metodo ExecuteRequest nella classe di base. Si tratta in effetti di un'operazione piuttosto semplice, che richiede la scrittura di circa cinque righe di codice per creare e configurare il proxy che si connetterà all'applicazione WCF e quindi chiamare il metodo ExecuteRequest della classe di base.
Per iniziare, è possibile creare un nuovo progetto in Visual Studio e scegliere il tipo di progetto per una libreria di classi Windows. Dopo aver specificato lo spazio dei nomi e il nome della classe desiderati, sarà necessario aggiungere un riferimento alla classe di base del kit CASI, ovvero l'assembly AzureConnect.dll. È inoltre necessario aggiungere riferimenti agli assembly seguenti: Microsoft.SharePoint, System.ServiceModel, System.Runtime.Serialization e System.Web.
Nella classe di base, aggiungere un'istruzione using per Microsoft.SharePoint, quindi modificare la classe in modo che erediti da AzureConnect.WcfConfig. WcfConfig è la classe di base che contiene tutto il codice e la logica per connettersi all'applicazione WCF, incorporare tutte le proprietà per aggiungere flessibilità all'implementazione ed evitare tutte le modifiche tipiche di web.config normalmente necessarie per la connessione a un endpoint del servizio WCF. Questo è un punto importante da capire: sarebbe normalmente necessario aggiungere circa 100 righe di modifiche nel file web.config per ogni applicazione WCF a cui è necessario connettersi, in ogni file web.config in tutti i server per tutte le applicazioni Web che utilizzano tale file. La classe di base WcfConfig esegue il wrapping di tutto ciò nel controllo stesso e per questo è sufficiente ereditare dal controllo, che eseguirà tutte le modifiche necessarie. Tutte le proprietà che dovrebbero essere modificate nel file web.config, tuttavia, possono essere modificate anche nel controllo WcfConfig, perché vengono tutte esposte. Questo argomento verrà trattato in maggiore dettaglio nella sezione relativa alle proprietà importanti.
A questo punto è necessario aggiungere un nuovo riferimento al servizio per l'applicazione WCF ospitata in Windows Azure. Questa operazione non è in effetti specifica per il kit CASI ed è sufficiente fare clic con il pulsante destro del mouse su Riferimenti nel progetto e scegliere Aggiungi riferimento al servizio. Aggiungere "?WSDL" alla fine dell'URL dell'applicazione WFC Azure in modo che recuperi il codice WSDL per l'implementazione del servizio. Specificare quindi il nome desiderato e aggiungere il riferimento per completare questa parte.
A questo punto sono disponibili una classe vuota e un riferimento al servizio per l'applicazione WCF. È ora necessario procedere con la scrittura del codice, una parte dell'operazione fortunatamente piuttosto limitata. È necessario eseguire l'override del metodo ExecuteRequest, creare e configurare il proxy della classe di servizio, quindi chiamare il metodo ExecuteRequest della classe di base. Per semplicità, quello che segue è il codice completo del controllo di esempio allegato al post, nel quale sono evidenziate in giallo le parti che è necessario modificare per specificare il riferimento al servizio corretto:
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Diagnostics;
using Microsoft.SharePoint;
//requires References to:
//1. AzureConnect
//2. Microsoft.SharePoint
//3. System.ServiceModel
//4. System.Runtime.Serialization
//5. System.Web
namespace AzureWcfPage
{
public class WcfDataControl : AzureConnect.WcfConfig
{
//this method must be overridden so the proxy can be
//configured and created correctly
public override bool ExecuteRequest()
{
try
{
//create the proxy instance with bindings and endpoint the base class
//configuration control has created for this
CustomersWCF.CustomersClient cust =
new CustomersWCF.CustomersClient(this.FedBinding,
this.WcfEndpointAddress);
//configure the channel so we can call it with
//FederatedClientCredentials.
SPChannelFactoryOperations.ConfigureCredentials<CustomersWCF.ICustomers>
(cust.ChannelFactory,
Microsoft.SharePoint.SPServiceAuthenticationMode.Claims);
//create a channel to the WCF endpoint using the
//token and claims of the current user
CustomersWCF.ICustomers claimsWCF =
SPChannelFactoryOperations.CreateChannelActingAsLoggedOnUser
<CustomersWCF.ICustomers>(cust.ChannelFactory,
this.WcfEndpointAddress,
new Uri(this.WcfEndpointAddress.Uri.AbsoluteUri));
//set the client property for the base class
this.WcfClientProxy = claimsWCF;
}
catch (Exception ex)
{
Debug.WriteLine(ex.Message);
}
//now that the configuration is complete, call the method
return base.ExecuteRequest();
}
}
}
Come già detto, si tratta fondamentalmente di cinque righe di codice. È sufficiente copiare e incollare direttamente nel proprio override il codice nell'override del metodo ExecuteRequest qui illustrato. Sarà quindi necessario sostituire le parti evidenziate in giallo con la classe e le interfacce appropriate esposte dalla propria applicazione WFC. Nel codice sopra evidenziato:
· CustomersWCF.CustomersClient: "CustomersWCF" è il nome utilizzato per la creazione del riferimento al servizio e CustomersClient è il nome della classe esposta tramite l'applicazione WCF. Il nome della classe nell'applicazione WCF è in effetti solamente "Customers". La parte "Client" alla fine viene aggiunta dagli strumenti per l'aggiunta di riferimenti ai servizi di VS.NET.
· CustomersWCF.ICustomers: "CustomersWCF" è lo stesso nome descritto sopra. "ICustomers" è l'interfaccia creata nell'applicazione WCF, implementata dalla classe "Customers" WCF.
Questo è tutto il codice che è necessario scrivere per ottenere la connessione all'applicazione WCF ospitata in Windows Azure. Si tratta senza dubbio di un'operazione molto semplice. Per maggiore chiarezza, questo è il codice che consente di passare il token dell'utente di SharePoint tramite la chiamata all'applicazione WCF. Questo passaggio è spiegato in maggiore dettaglio in un altro post: https://blogs.technet.com/b/speschka/archive/2010/09/08/calling-a-claims-aware-wcf-service-from-a-sharepoint-2010-claims-site.aspx.
Il codice è così completo ed è ora necessario assicurarsi di registrare sia la classe di base che il nuovo controllo personalizzato nella Global Assembly Cache in tutti i server in cui verranno utilizzati. È possibile ovviamente eseguire questa operazione con facilità utilizzando una soluzione SharePoint. Dopo aver completato e registrato il controllo, è possibile proseguire con una descrizione delle procedure per utilizzare tale controllo per il recupero e il rendering dei dati. Nel kit CASI vengono illustrati tre scenari principali per l'utilizzo di dati Azure:
1. Rendering del contenuto in una pagina di SharePoint utilizzando una web part
2. Recupero dei dati di configurazione per l'utilizzo con uno dei molti controlli e relativa archiviazione nella cache ASP.NET
3. Recupero dei dati e loro utilizzo in eseguibili di tipo attività, come un processo timer di SharePoint
Il primo scenario è probabilmente il più esteso, quindi verrà illustrato per primo. Il modo più semplice per eseguire questa operazione al momento della definizione di questa metodologia sarebbe stato quello di creare una web part personalizzata per eseguire tutte le chiamate durante un evento Load o qualcosa di simile, per poi recuperare i dati ed eseguirne il rendering nella pagina. Questo sarebbe, tuttavia, un GRANDE errore. Il wrapping del codice nella web part stessa, in modo da eseguirlo sul lato server durante l'elaborazione di una richiesta di pagina, potrebbe rallentare in modo significativo la velocità effettiva complessiva della farm. La situazione in cui possono esistere una o molte web part in una pagina che eseguono una o molte chiamate latenti su applicazioni e data center diversi per il recupero dei dati è giustamente fonte di preoccupazione ed è facile immaginarsi uno scenario in cui l'utilizzo diffuso di questi meccanismi potrebbe letteralmente mettere in ginocchio un'intera farm. L'esecuzione di codice nel server è comunque un requisito, perché è necessario configurare il canale per l'applicazione WCF per l'invio del token utente insieme alla richiesta. La soluzione qui proposta è costituita da due parti:
1. Una pagina personalizzata ospitata nella cartella _layouts. Questa pagina conterrà il controllo personalizzato sopra illustrato ed eseguirà il rendering effettivo dei dati restituiti dalla chiamata WCF.
2. Una web part personalizzata che NON ESEGUE CODICE sul lato server, ma utilizza invece JavaScript e jQuery per richiamare la pagina nella cartella _layouts. La web part legge i dati restituiti dalla pagina e quindi li passa a una funzione JavaScript che per impostazione predefinita eseguirà semplicemente il rendering del contenuto nella web part. La web part offre naturalmente molte altre opportunità, ma questo argomento verrà trattato in maggiore dettaglio nel post successivo. Lo scopo è ottenere che quando un utente richiede una pagina, la richiesta venga elaborata senza dovere effettuare ulteriori chiamate latenti all'applicazione WCF. La pagina attraversa invece la pipeline di elaborazione e viene quindi fornita direttamente al browser dell'utente. Dopo il completo caricamento della pagina, viene effettuata la chiamata per recuperare solo il contenuto WCF.
La pagina Layouts
La pagina Layouts per l'hosting del controllo personalizzato è veramente molto semplice da scrivere, bastano più o meno cinque minuti nel Blocco note. In questo caso sarà ancora più veloce, perché il codice della pagina Layouts è riportato di seguito con evidenziate le parti da sostituire per la creazione di una pagina personalizzata.
<%@ Page Language="C#" AutoEventWireup="true" Inherits="Microsoft.SharePoint.WebControls.LayoutsPageBase,Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" MasterPageFile="~/_layouts/simple.master" %>
<%@ Assembly Name="Microsoft.SharePoint.ApplicationPages, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c"%>
<%@ Import Namespace="Microsoft.SharePoint.ApplicationPages" %>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Assembly Name="Microsoft.Web.CommandUI, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Assembly Name="AzureConnect, Version=1.0.0.0, Culture=neutral, PublicKeyToken=c0b51bd3d3b33212"%>
<%@ Register Tagprefix="AzWcf" Namespace="AzureWcfPage" Assembly="AzureWcfPage, Version=1.0.0.0, Culture=neutral, PublicKeyToken=f0ed63b2f4046026" %>
<asp:Content ID="Content1" ContentPlaceHolderId="PlaceHolderPageTitle" runat="server">
<SharePoint:EncodedLiteral ID="wcfConnectPageTitle" runat="server" text="Azure Wcf Connect Page" EncodeMethod='HtmlEncode'/>
</asp:Content>
<asp:Content ID="Content2" ContentPlaceHolderId="PlaceHolderPageTitleInTitleArea" runat="server">
<SharePoint:EncodedLiteral ID="wcfConnectPage" runat="server" text="Azure Wcf Connect Page" EncodeMethod='HtmlEncode'/>
</asp:Content>
<asp:Content ID="Content3" ContentPlaceHolderId="PlaceHolderSiteName" runat="server"/>
<asp:Content ID="Content4" ContentPlaceHolderId="PlaceHolderMain" runat="server">
<AzWcf:WcfDataControl runat="server" id="wcf" WcfUrl="https://azurewcf.vbtoys.com/Customers.svc" OutputType="Page" MethodName="GetAllCustomersHtml" />
</asp:Content>
Ancora una volta, l'implementazione della pagina è decisamente molto semplice. Quello che è fondamentale modificare è il nome sicuro dell'assembly per il controllo personalizzato. A scopo illustrativo, sono state evidenziate anche un paio di proprietà nel tag di controllo. Queste proprietà sono specifiche del servizio WCF illustrato in questo post e possono essere modificate e in alcuni casi rimosse in altre implementazioni. Le proprietà verranno illustrate in maggiore dettaglio più avanti. Dopo aver creato la pagina Layouts è necessario distribuirla nella directory _layouts di tutti i server front-end Web nella farm di SharePoint. Sarà quindi possibile chiamarla da qualsiasi sito in qualsiasi applicazione Web in grado di riconoscere attestazioni nella farm di SharePoint. Naturalmente, non è possibile aspettarsi che funzioni in un sito con autenticazione classica, come Amministrazione centrale. Dopo la distribuzione, la pagina potrà essere utilizzata dalla web part del kit CASI, descritta nella parte 4 di questa serie.
Proprietà importanti
Il controllo WcfConfig include due categorie principali di proprietà, ovvero le proprietà per la configurazione del canale e della connessione all'applicazione WCF, nonché le proprietà per la configurazione dell'utilizzo del controllo stesso.
Proprietà del controllo WCF
Come indicato in precedenza, tutte le informazioni di configurazione per l'applicazione WCF normalmente contenute nel file web.config sono state incapsulate nel controllo WcfConfig. Praticamente tutte queste proprietà sono comunque esposte in modo da poter essere modificate in base alle esigenze specifiche di ogni implementazione. Due eccezioni importanti sono rappresentate dalla versione della sicurezza a livello di messaggio che è sempre MessageSecurityVersion.WSSecurity11WSTrust13WSSecureConversation13WSSecurityPolicy12BasicSecurityProfile10 e dal trasporto che è sempre HTTPS e non HTTP. Per il controllo sono disponibili numerose proprietà che può essere utile conoscere in maggiore dettaglio per utilizzarle nelle implementazioni personalizzate, anche se normalmente non vi è alcuna necessità di modificarle.
Innanzitutto, sono presenti cinque proprietà di sola lettura per esporre gli oggetti di configurazione di primo livello utilizzati nella configurazione. Con "sola lettura" si intende che gli oggetti stessi sono di sola lettura, ma è possibile impostare le singole proprietà corrispondenti se si utilizza il controllo a livello di programmazione. Queste cinque proprietà sono:
SecurityBindingElement SecurityBinding
BinaryMessageEncodingBindingElement BinaryMessage
HttpsTransportBindingElement SecureTransport
WS2007FederationHttpBinding FedBinding
EndpointAddress WcfEndpointAddress
Tutte le altre proprietà possono essere configurate nel tag di controllo aggiunto alla pagina ASPX Layouts. La convenzione di denominazione utilizzata per queste proprietà è stata progettata per ottenere valori di proprietà composti comprensibili. Per la proprietà SecurityBinding, ad esempio, esiste una proprietà denominata LocalClient che include una proprietà di tipo bool denominata CacheCookies. Per semplificare al massimo la comprensione e l'utilizzo di queste proprietà, è stata creata una singola proprietà denominata SecurityBindingLocalClientCacheCookies. Esistono varie proprietà come questa e si tratta anche di un'indicazione utile su come trovare la proprietà giusta in .NET Framework SDK e su come modificare alcuni di questi valori di proprietà nell'implementazione della classe di base. Di seguito è riportato l'elenco completo delle proprietà:
SecurityAlgorithmSuite SecurityBindingDefaultAlgorithmSuite
SecurityHeaderLayout SecurityBindingSecurityHeaderLayout
SecurityKeyEntropyMode SecurityBindingKeyEntropyMode
bool SecurityBindingIncludeTimestamp
bool SecurityBindingLocalClientCacheCookies
bool SecurityBindingLocalClientDetectReplays
int SecurityBindingLocalClientReplayCacheSize
int SecurityBindingLocalClientMaxClockSkew
int SecurityBindingLocalClientMaxCookieCachingTime
int SecurityBindingLocalClientReplayWindow
int SecurityBindingLocalClientSessionKeyRenewalInterval
int SecurityBindingLocalClientSessionKeyRolloverInterval
bool SecurityBindingLocalClientReconnectTransportOnFailure
int SecurityBindingLocalClientTimestampValidityDuration
int SecurityBindingLocalClientCookieRenewalThresholdPercentage
bool SecurityBindingLocalServiceDetectReplays
int SecurityBindingLocalServiceIssuedCookieLifetime
int SecurityBindingLocalServiceMaxStatefulNegotiations
int SecurityBindingLocalServiceReplayCacheSize
int SecurityBindingLocalServiceMaxClockSkew
int SecurityBindingLocalServiceNegotiationTimeout
int SecurityBindingLocalServiceReplayWindow
int SecurityBindingLocalServiceInactivityTimeout
int SecurityBindingLocalServiceSessionKeyRenewalInterval
int SecurityBindingLocalServiceSessionKeyRolloverInterval
bool SecurityBindingLocalServiceReconnectTransportOnFailure
int SecurityBindingLocalServiceMaxPendingSessions
int SecurityBindingLocalServiceMaxCachedCookies
int SecurityBindingLocalServiceTimestampValidityDuration
int BinaryMessageMaxReadPoolSize
int BinaryMessageMaxWritePoolSize
int BinaryMessageMaxSessionSize
int BinaryMessageReaderQuotasMaxDepth
int BinaryMessageReaderQuotasMaxStringContentLength
int BinaryMessageReaderQuotasMaxArrayLength
int BinaryMessageReaderQuotasMaxBytesPerRead
int BinaryMessageReaderQuotasMaxNameTableCharCount
System.Net.AuthenticationSchemes SecureTransportAuthenticationScheme
System.ServiceModel.HostNameComparisonMode SecureTransportHostNameComparisonMode
System.Net.AuthenticationSchemes SecureTransportProxyAuthenticationScheme
System.ServiceModel.TransferMode SecureTransportTransferMode
bool SecureTransportManualAddressing
long SecureTransportMaxBufferPoolSize
long SecureTransportMaxReceivedMessageSize
bool SecureTransportAllowCookies
bool SecureTransportBypassProxyOnLocal
bool SecureTransportKeepAliveEnabled
int SecureTransportMaxBufferSize
string SecureTransportRealm
bool SecureTransportUnsafeConnectionNtlmAuthentication
bool SecureTransportUseDefaultWebProxy
bool SecureTransportRequireClientCertificate
HostNameComparisonMode FedBindingHostNameComparisonMode
WSMessageEncoding FedBindingMessageEncoding
Encoding FedBindingTextEncoding
SecurityAlgorithmSuite FedBindingSecurityMessageAlgorithmSuite
SecurityKeyType FedBindingSecurityMessageIssuedKeyType
bool FedBindingSecurityMessageNegotiateServiceCredential
int FedBindingCloseTimeout
int FedBindingOpenTimeout
int FedBindingReceiveTimeout
int FedBindingSendTimeout
bool FedBindingBypassProxyOnLocal
bool FedBindingTransactionFlow
long FedBindingMaxBufferPoolSize
long FedBindingMaxReceivedMessageSize
bool FedBindingUseDefaultWebProxy
int FedBindingReaderQuotasMaxDepth
int FedBindingReaderQuotasMaxStringContentLength
int FedBindingReaderQuotasMaxArrayLength
int FedBindingReaderQuotasMaxBytesPerRead
int FedBindingReaderQuotasMaxNameTableCharCount
bool FedBindingReliableSessionOrdered
int FedBindingReliableSessionInactivityTimeout
bool FedBindingReliableSessionEnabled
Anche in questo caso, tutte le proprietà sono già state create in modo da poterle modificare direttamente nel tag di controllo nella pagina ASPX Layouts. L'esempio seguente illustra come è possibile impostare la proprietà FedBindingUseDefaultWebProxy:
<AzWcf:WcfDataControl runat="server" id="wcf" WcfUrl="https://azurewcf.vbtoys.com/Customers.svc" OutputType="Page" MethodName="GetAllCustomersHtml" FedBindingUseDefaultWebProxy="true" />
Proprietà di utilizzo
Le altre proprietà del controllo sono progettate per definirne le modalità di utilizzo. Anche se l'elenco delle proprietà è piuttosto lungo, è importante sottolineare che sono state create principalmente per maggiore flessibilità di utilizzo. Nei casi più semplici sarà necessario impostare solo una o due proprietà o, in alternativa, sarà sufficiente impostarle nella web part descritta nella quarta parte di questa serie. Di seguito è riportato un elenco di ogni proprietà con una breve descrizione.
string WcfUrl - URL dell'endpoint del servizio WCF, ovvero https://azurewcf.vbtoys.com/Customers.svc.
string MethodName - nome del metodo che deve essere richiamato quando viene richiesta la pagina. È possibile impostare questa proprietà sul metodo che verrà richiamato per impostazione predefinita. È inoltre possibile impostare la proprietà AllowQueryStringOverride su false, in modo che la pagina venga limitata all'utilizzo ESCLUSIVO del metodo definito tramite MethodName nel tag di controllo. Questa proprietà può essere impostata tramite una stringa di query utilizzando la web part del kit CASI.
string MethodParams - elenco delimitato da punti e virgola dei valori di parametro da passare alla chiamata del metodo. I valori devono essere specificati nello stesso ordine in cui compaiono nella firma del metodo. Come illustrato nella parte 2 di questa serie di blog, per i valori dei parametri sono effettivamente supportati solo tipo di dati semplici, come string, bool, int e datetime. Se si desidera passare oggetti più complessi come parametri per il metodo, è necessario convertire il parametro in stringa e deserializzare l'oggetto in XML prima di chiamare il metodo, quindi serializzare nuovamente la stringa come istanza di oggetto nell'applicazione WCF. Se si passa il valore come parametro stringa di query, tuttavia, sarà necessario rispettare i limiti a livello di lunghezza massima della stringa di query supportati dal browser e da IIS. Questa proprietà può essere impostata tramite una stringa di query utilizzando la web part del kit CASI.
object WcfClientProxy - questa proprietà è il proxy effettivamente utilizzato per la chiamata dell'applicazione WCF. È necessario configurarlo in modo che supporti il passaggio del token utente insieme alla chiamata. Questo è il motivo per cui l'ultimo codice di configurazione scritto nel controllo personalizzato nell'override di ExecuteRequest prevede l'impostazione di questo oggetto proxy sul proxy di applicazione del servizio creato e configurato per l'utilizzo delle credenziali client correnti.
string QueryResultsString - questa proprietà contiene una rappresentazione stringa dei risultati restituiti dalla chiamata del metodo. Se il metodo WCF restituisce un tipo di dati semplice come bool, int, string o datetime, il valore della proprietà sarà il valore restituito ToString(). Non è un problema anche se il metodo WCF restituisce una classe personalizzata. Quando la classe di base ottiene il valore restituito lo deserializzerà in una stringa in modo da disporre di una rappresentazione XML dei dati.
object QueryResultsObject - questa proprietà contiene una rappresentazione in forma di oggetto dei risultati restituiti dalla chiamata del metodo. Si tratta di uno strumento utile per l'utilizzo del controllo a livello di programmazione. Ad esempio, se si utilizza il controllo per recuperare i dati da archiviare nella cache ASP.NET o da utilizzare in un processo timer di SharePoint, la proprietà QueryResultsObject include esattamente i valori restituiti dalla chiamata del metodo WCF. Nel caso di una classe personalizzata, è sufficiente eseguire il cast dei risultati di questa proprietà nel tipo di classe appropriato per poterla utilizzare.
DataOutputType OutputType - enumerazione con quattro valori validi: Page, ServerCache, Both o None. Se si utilizza il controllo nella pagina Layouts e si prevede di eseguire il rendering dei risultati con la web part, è necessario impostare la proprietà OutputType su Page o Both. Se si desidera recuperare i dati e archiviarli nella cache ASP.NET, è necessario utilizzare ServerCache o Both. NOTA: quando si archiviano i risultati nella cache, viene archiviato SOLO l'oggetto QueryResultsObject. Ovviamente il valore Both consente sia di eseguire il rendering dei dati che di archiviarli nella cache ASP.NET. Se si utilizza il controllo solo a livello di programmazione, ad esempio in un processo timer di SharePoint, è possibile impostare la proprietà su None, perché si leggerà semplicemente la proprietà QueryResultsString o QueryResultsObject dopo la chiamata del metodo ExecuteRequest. Questa proprietà può essere impostata tramite una stringa di query utilizzando la web part del kit CASI.
string ServerCacheName - se si imposta la proprietà OutputType su ServerCache o Both, sarà necessario impostare la proprietà ServerCacheName su un valore stringa non vuoto. In caso contrario, verrà generata un'eccezione. Questa è la chiave che verrà utilizzata per l'archiviazione dei risultati nella cache ASP.NET. Se si imposta la proprietà ServerCacheName su "MiaProprietà", ad esempio, dopo la chiamata del metodo ExecuteRequest è possibile recuperare l'oggetto restituito dall'applicazione WCF facendo riferimento a HttpContext.Current.Cache["MiaProprietà"]. Questa proprietà può essere impostata tramite una stringa di query utilizzando la web part del kit CASI.
int ServerCacheTime - periodo di tempo, in minuti, di memorizzazione dell'elemento aggiunto nella cache ASP.NET. Se si imposta la proprietà OutputType su ServerCache o Both, sarà necessario impostare anche questa proprietà su un valore diverso da zero. In caso contrario, verrà generata un'eccezione. Questa proprietà può essere impostata tramite una stringa di query utilizzando la web part del kit CASI.
bool DecodeResults - questa proprietà è disponibile nel caso l'applicazione WCF restituisca risultati con codifica HTML. Se si imposta questa proprietà su true, ai risultati verrà applicata la decodifica HTML. Nella maggior parte dei casi, questa proprietà non è necessaria. Questa proprietà può essere impostata tramite una stringa di query utilizzando la web part del kit CASI.
string SharePointClaimsSiteUrl - questa proprietà è disponibile principalmente per supportare gli scenari di creazione del controllo a livello di programmazione all'esterno di una richiesta HTTP, come nel caso di un processo timer di SharePoint. Per impostazione predefinita, quando la richiesta viene eseguita tramite la web part, la classe di base utilizzerà l'URL del sito corrente per connettersi all'endpoint per il servizio token di sicurezza di SharePoint per fornire il token utente alla chiamata WCF. Se il controllo è stato creato a livello di programmazione e non è disponibile un contesto HTTP, tuttavia, è possibile impostare questa proprietà sull'URL di un sito di SharePoint con sicurezza basata sulle attestazioni e tale sito verrà utilizzato per accedere al servizio token di sicurezza di SharePoint. Pertanto, non sarà mai necessario impostare questa proprietà nel tag di controllo nella pagina Layouts, ad esempio, perché per la chiamata di tale pagina sarà sempre disponibile un contesto HTTP.
bool AllowQueryStringOverride - questa proprietà consente agli amministratori di bloccare un tag di controllo nella pagina Layouts. Se la proprietà AllowQueryStringOverride viene impostata su false, qualsiasi valore di override in forma di stringa di query passato dalla web part del kit CASI verrà ignorato.
string AccessDeniedMessage - messaggio per l'errore di accesso negato che dovrebbe essere visualizzato nella web part del kit CASI se viene negato l'accesso all'utente per un particolare metodo. Come illustrato nella parte 2 di questa serie, ad esempio, dato che il token dell'utente viene passato insieme alla chiamata WCF, è possibile decorare qualsiasi metodo con una richiesta PrincipalPermission del tipo "questo utente deve fare parte del gruppo Direttori vendite". Se un utente non soddisfa una richiesta PrincipalPermission, la chiamata WCF avrà esito negativo con un errore di accesso negato. In questo caso, la web part visualizzerà il messaggio impostato per AccessDeniedMessage. Si noti che è possibile utilizzare elementi di formattazione RTF nel messaggio, ad esempio per impostare il carattere in grassetto e con il colore rosso tramite tag HTML (ad esempio, <font color='red'>Accesso negato. Contattare l'amministratore</font>). Questa proprietà può essere impostata tramite una stringa di query utilizzando la web part del kit CASI.
string TimeoutMessage - messaggio che verrà visualizzato nella web part del kit CASI se si verifica un errore di timeout durante il tentativo di esecuzione della chiamata del metodo WCF. Per il messaggio sono inoltre supportati elementi di formattazione RTF come l'impostazione del carattere in grassetto, l'applicazione del colore rosso e così via. Questa proprietà può essere impostata tramite una stringa di query utilizzando la web part del kit CASI.
Questo post è piuttosto lungo, ma sarà probabilmente il più lungo della serie perché riguarda il componente più significativo del kit CASI. Nel prossimo post verrà descritta la web part inclusa nel kit CASI per il rendering dei dati dall'applicazione WCF, utilizzando il controllo personalizzato e la pagina Layouts sviluppati in questo passaggio.
A questo post è allegato un file ZIP contenente il progetto di esempio di Visual Studio 2010 creato, che include l'assembly della classe di base del kit CASI, il controllo personalizzato che eredita dalla classe di base del kit CASI, nonché la pagina Layouts personalizzata.
Questo è un post di blog localizzato. L'articolo originale è disponibile in The Claims, Azure and SharePoint Integration Toolkit Part 3