クレームと Azure と SharePoint を統合するツールキット パート 3

クレームと Azure と SharePoint を統合するツールキット パート 3

この投稿は、CASI (Claims, Azure and SharePoint Integration) キットに関する 5 部シリーズのパート 3 に当たります。 パート 1 では、フレームワークとソリューション全体の概要を説明し、このブログ シリーズで説明する内容を示しました。 パート 2 では、WCF アプリケーションを作成してクレームに対応させ、Windows Azure に移行させるためのガイダンスを示しました。 この投稿では、このフレームワークの大きな成果物の 1 つについて説明します。それは、SharePoint を Windows Azure でホストされた WCF アプリケーションに接続するために使用するカスタム コントロールの基本クラスです。 今回説明する項目は次のとおりです。

· 基本クラス - その全容とプロジェクトでの使用方法

· レイアウト ページ - レイアウト ディレクトリ内のページに新しいコントロールを追加する方法

· 重要なプロパティ - 基本クラスで知っておく必要がある重要なプロパティの一部についての解説

CASI キットの基本クラス

CASI キットの主な成果物の 1 つとして、WCF アプリケーションに接続し、現在のユーザーのログオン トークンと共に要求を送信するカスタム コントロールの基本クラスがあります。 基本クラスそのものは標準の ASP.NET サーバー コントロールであり、こうした開発パターンの実装ではこの基本クラスを継承した ASP.NET サーバー コントロールを新たに作成する必要があります。 今回の投稿の趣旨から外れるので理由は説明しませんが、実際には次の 2 つの作業を行う必要があります。

1. Windows Azure でホストされた WCF アプリケーションへのサービス参照を作成します。

2. 基本クラスの ExecuteRequest メソッドをオーバーライドします。 実際にはこの作業は非常に簡単で、5 行ほどのコードを記述して、WCF アプリケーションに接続するプロキシの作成および構成と、基本クラスの ExecuteRequest メソッドの呼び出しを行うだけです。

以上の作業を開始するには、Visual Studio で新しいプロジェクトを作成し、プロジェクトの種類として Windows クラス ライブラリを選択します。 名前空間とクラス名を適切なものに変更したら、AzureConnect.dll アセンブリ内にある CASI キット基本クラスへの参照を追加します。 また、次のアセンブリへの参照も追加する必要があります。 Microsoft.SharePoint、System.ServiceModel、System.Runtime.Serialization、および System.Web。

基本クラス内で、Microsoft.SharePoint 用の using ステートメントを追加し、AzureConnect.WcfConfig を継承するようにクラスを変更します。 WcfConfig は、WCF アプリケーションに接続し、すべてのプロパティを組み込んで実装の柔軟性を向上させ、WCF サービス エンドポイントへの接続に通常は必要な web.config の一般的な変更のすべてを不要にするためのコードとロジックがすべて含まれた基本クラスです。 これは理解しておくべき重要な点です。通常であれば、接続する WCF アプリケーション 1 つにつき 100 行近くの web.config の変更を、サーバーを使用する Web アプリケーションのすべてのサーバー上にあるあらゆる web.config ファイルに対して加える必要があるからです。 WcfConfig 基本クラスはそのすべてをコントロール自体にまとめたものなので、そのコントロールを継承するだけで残りの処理を代わりに行ってくれます。 本来であれば web.config ファイル内で変更されるこうしたプロパティのすべてを WcfConfig コントロールでも変更できるのは、そのすべてに対応するプロパティが WcfConfig によって公開されているからです。 この点については、重要なプロパティに関するセクションで説明します。

次に、Windows Azure でホストされた WCF アプリケーションへの新しい Service Reference を追加します。 ここで必要になる CASI キット特有の作業は何もありません。ただ、プロジェクトで [参照] (References) を右クリックし、[サービス参照の追加] (Add Service Reference) を選択するだけです。 Azure WCF アプリケーションの URL の最後に "?WSDL" を付けて入力し、サービス実装の WSDL が取得されるようにします。 さらに、名前を自由に変更してこの参照を追加すれば、この部分の作業は完了です。

この時点で、空のクラスと WCF アプリケーションへのサービス参照ができあがっています。 続いて、コードの記述に入ります。幸いにしてその量はわずかです。 ExecuteRequest メソッドをオーバーライドし、サービス プロキシ クラスを作成および構成して、基本クラスの ExecuteRequest メソッドを呼び出します。 説明を簡単にするために、この投稿に添付するサンプル コントロールの完全なコードを以下に示します。強調表示 (黄色) されている部分は、サービス参照に合わせて変更が必要な箇所です。

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();

        }

    }

}

以上のように、基本的には 5 行のコードであり、実際には ExcecuteRequest のオーバーライド部分のコードをそのままコピーして各自のオーバーライド箇所に貼り付けることができます。その後は、黄色で強調表示された部分を WCF アプリケーションで公開している適切なクラスおよびインターフェイスで置き換えるだけです。 強調表示されているのは次の部分です。

· CustomersWCF.CustomersClient: "CustomersWCF" は私がサービス参照を作成したときに使用した名前であり、CustomersClient は WCF アプリケーションで公開しているクラスの名前です。 実際には、WCF 内のクラス名は "Customers" のみですが、VS.NET のサービス参照ツールによってその後に "Client" が追加されています。

· CustomersWCF.ICustomers: "CustomersWCF" については、上記と同様です。 "ICustomers" は、私が WCF アプリケーション内に作成したインターフェイスであり、実際には WCF の "Customers" クラスによって実装されています。

コードについては以上です。つまり、Windows Azure でホストされた WCF アプリケーションに接続するために記述が必要なコードはこれだけです。 きっと読者の皆さんもこの作業の手軽さを認めてくれると思います。 ちなみに、ここで記述したコードは、WCF アプリケーションを呼び出して SharePoint ユーザーのトークンを渡せるようにするためのものです。 詳細については、次に示す私の別の投稿を参照してください。 https://blogs.technet.com/b/speschka/archive/2010/09/08/calling-a-claims-aware-wcf-service-from-a-sharepoint-2010-claims-site.aspx (英語).

コードが完成したら、そのコードを使用する各サーバーのグローバル アセンブリ キャッシュに基本クラスと新しいカスタム コントロールの両方を登録する必要があります。 もちろん、この作業は SharePoint ソリューションによって簡単に行えます。 コントロールが完成してその登録を済ませたところで、このコントロールを使用してデータを取得したり表示したりする方法を説明します。 Azure のデータを使用する重要なシナリオとして、私は CASI キットで次の 3 つに取り組もうとしました。

1. SharePoint ページへのコンテンツの表示 (Web パーツを使用)

2. 1 対多のコントロールで使用する構成データの取得と ASP.NET キャッシュへの保存

3. タスク型実行ファイル (SharePoint タイマー ジョブなど) でのデータの取得と使用

最初のシナリオがおそらく最も一般的なものなので、まずはこれに取り組みます。 この方法が打ち出された場合に最も容易に思い浮かぶのは、読み込みイベント時などにこれらの呼び出しのすべてを実行し、データを取得して、ページに表示するカスタム Web パーツを作成することです。 しかし、これは大きな誤りだと私は思います。 そうしたコードを Web パーツ自体にまとめた場合、ページ要求の処理中にサーバー側の作業を実行すると、ファーム全体のスループットが大きく低下する可能性があります。 表からは見えない 1 対多の呼び出しをアプリケーションおよびデータ センター間で実行してデータを取得するので、その多用によってファーム全体の機能が停止してしまう状況が容易に想像できる 1 対多の Web パーツをページで利用することについては、大きな不安があったのです。 しかし、サーバー上での何らかのコードの実行を必要とするこうした要件は存在します。要求と共にユーザー トークンを送信するように WCF アプリケーションへのチャネルを構成する必要があったからです。 ここでの解決策は、次の 2 つで構成されます。

1. レイアウト フォルダー内でホストされるカスタム ページ。 このページには、先ほど記述したカスタム コントロールが含まれることになり、WCF の呼び出しによって返されるデータが実際に表示されます。

2. サーバー側では一切のコードを実行せず、代わりに JavaaScript と jQuery を使用してレイアウト フォルダー内のページを呼び出すカスタム Web パーツ。 この Web パーツは、ページから返されたデータを読み取り、既定では Web パーツのコンテンツを表示する JavaScript 関数に渡します。 もちろん、Web パーツで可能なことは他にも数多くありますが、Web パーツの詳細については次の投稿で説明する予定です。 要するに、ユーザーがこのページを要求した場合、表からは見えない追加の呼び出しを WCF アプリケーションに対して行わなくても、ページは処理されるわけです。 代わりに、このページはパイプライン処理によって、直ちにユーザーのブラウザーに伝えられます。 ページの読み込みの完了後は、WCF コンテンツのみを取得するための呼び出しが実行されます。

レイアウト ページ

カスタム コントロールをホストするレイアウト ページの記述は、実に簡単です。 メモ帳ですべての作業を終えるのに 5 分ほどしかかかりませんでした。 さらに手早く、コピーして貼り付けるだけで済むように、レイアウト ページの内容とページ内で置き換えが必要な部分を以下に示します。

<%@ 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>

 

ここでも、ページ自体の実装は実に簡単です。 間違いなく変更が必要なのは、カスタム コントロール用のアセンブリの厳密な名前です。 また、説明のために、コントロール タグ内の 2 つのプロパティも強調表示しています。 これらのプロパティは私の WCF サービスに特有のものなので、変更して構いません。場合によっては実装から完全に削除することもできます。 これらのプロパティについては後で詳しく説明します。 作成が済んだレイアウト ページは、SharePoint ファーム内のすべての Web フロントエンド サーバー上のレイアウト ディレクトリに配布する必要があります。 そうすれば、SharePoint ファーム内にある任意のクレーム対応 Web アプリケーションの任意のサイトからそのレイアウト ページを呼び出せるようになります。 もちろん、サーバーの全体管理など、従来の認証サイトでこのページが機能するとは思わないでください。 展開されたページは CASI キット Web パーツによって使用できるのですが、これについてはこのシリーズのパート 4 で説明します。

重要なプロパティ

WcfConfig には、大きく分けて 2 つのカテゴリのプロパティが含まれています。WCF アプリケーションへのチャネルおよび接続を構成するものと、コントロール自体の使用法を構成するものです。

WCF プロパティ

前述のように、通常であれば web.config ファイルに含まれる WCF アプリケーション向け構成情報のすべては、WcfConfig コントロール内にカプセル化されています。 ただし、これらのプロパティのほぼすべては実装のニーズに応じて変更できるように公開されています。 その重要な例外として、メッセージ セキュリティ バージョン (常に MessageSecurityVersion.WSSecurity11WSTrust13WSSecureConversation13WSSecurityPolicy12BasicSecurityProfile10) とトランスポート (HTTP ではなく 常に HTTPS) の 2 つがあります。 これらを除けば、コントロールのプロパティには実装の詳細を知るのに役立ちそうなものが数多くあります (ただし、通常はそれらを変更する必要はありません)。

まず、構成で使用される最上位の構成オブジェクトを公開するための読み取り専用プロパティが 5 つあります。 読み取り専用とはオブジェクトそのものが読み取り専用という意味ですが、コントロールをプログラムによって操作すればそれらの個々のプロパティを設定できます。 その 4 つのプロパティを以下に示します。

SecurityBindingElement SecurityBinding

BinaryMessageEncodingBindingElement BinaryMessage

HttpsTransportBindingElement SecureTransport

WS2007FederationHttpBinding FedBinding

EndpointAddress WcfEndpointAddress

レイアウト aspx ページに追加されているコントロール タグ内のその他のプロパティはすべて構成できます。 それらのプロパティでは、複合プロパティ値の意味がわかりやすくなるように名前付け規則を使用しました。 たとえば、SecurityBinding プロパティは LocalClient というプロパティを持ち、さらにこのプロパティは CacheCookies というブール型プロパティを持ちます。 これをできるだけわかりやすく使いやすいものにするために、単純に SecurityBindingLocalClientCacheCookies という 1 つのプロパティを作成したわけです。 このようなプロパティがいくつか出てきますが、こうした名前付けは、.NET Framework SDK を参照していて基本クラスの実装でそれらのプロパティ値を変更する方法を探している場合に、適切なプロパティを見つけるための手がかりにもなります。 以下に、プロパティの完全なリストを示します。

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

これらもやはり、すべてレイアウト aspx ページ内のコントロール タグで直接変更できるように作成されたものです。 例として、FedBindingUseDefaultWebProxy プロパティの設定方法を示しておきます。

<AzWcf:WcfDataControl runat="server" id="wcf" WcfUrl="https://azurewcf.vbtoys.com/Customers.svc" OutputType="Page" MethodName="GetAllCustomersHtml" FedBindingUseDefaultWebProxy="true" />

 

使用方法に関するプロパティ

このコントロールの他のプロパティ群は、コントロールの使用方法を制御するために設計されたものです。 少し長いリストになりますが、これらのプロパティの主なねらいはコントロールの柔軟な使用にあります。単純な場合であれば、プロパティを 1 つか 2 つ設定するか、またはそれらを Web パーツ (このシリーズのパート 4 で説明します) 内で設定するだけで済みます。 以下に、プロパティのリストとそれぞれの簡単な説明を示します。

string WcfUrl - WCF サービス エンドポイントの URL です (例: https://azurewcf.vbtoys.com/Customers.svc)。

string MethodName - ページが要求されたときに呼び出しが必要なメソッドの名前です。 ここには、既定で呼び出されるメソッドを設定できます。 また、AllowQueryStringOverride プロパティを false に設定して、コントロール タグ内で定義する MethodName の使用のみにページを制限することもできます。 このプロパティは、CASI キット Web パーツを使用してクエリ文字列によって設定できます。

string MethodParams - メソッド呼び出し時に渡す必要があるパラメーター値のセミコロン区切りリストです。 パラメーター値は、メソッド シグネチャ表示と同じ順序で指定する必要があります。 このブログ シリーズのパート 2 で説明したように、パラメーター値で実際にサポートされているのは、文字列、ブール値、整数、日時など、単純なデータ型のみです。 複雑なオブジェクトをメソッド パラメーターとして渡す場合は、パラメーターを文字列にし、オブジェクトを XML に逆シリアル化したうえでメソッドを呼び出す必要があります。その後、文字列は WCF アプリケーションでシリアル化してオブジェクト インスタンスに戻せます。 ただし、クエリ文字列パラメーターとして渡す場合は、ブラウザーおよび IIS でサポートされるクエリ文字列の最大長の制限を受けます。 このプロパティは、CASI キット Web パーツを使用してクエリ文字列によって設定できます。

object WcfClientProxy - WCF アプリケーションに対する呼び出しを実際に行うために使用されます。 呼び出しに伴うユーザー トークンの受け渡しをサポートするように構成する必要があります。ExecuteRequest をオーバーライドする際、カスタム コントロールに記述する構成コードの最後で、このプロキシ オブジェクトが現在のクライアント資格情報を使用するように作成および構成したサービス アプリケーション プロキシに等しくなるように設定したのは、そのためです。

string QueryResultsString - このプロパティには、メソッド呼び出しで返される結果の文字列表現が含まれます。 WCF メソッドが単純なデータ型 (ブール値、整数、文字列、日時など) を返す場合、このプロパティの値は返り値を ToString() したものになります。 WCF メソッドがカスタム クラスを返す場合でも問題はありません。基本クラスはそうした返り値を取得すると文字列に逆シリアル化するので、データの XML 表現が得られます。

object QueryResultsObject - このプロパティには、メソッド呼び出しで返される結果のオブジェクト表現が含まれます。 これはコントロールをプログラムで使用する場合に便利です。 たとえば、コントロールを使用して、取得したデータを ASP.NET キャッシュに保存したり SharePoint タイマー ジョブで使用したりする場合、QueryResultsObject プロパティは WCF メソッドの呼び出しで返された内容そのものを保持します。 それがカスタム クラスであれば、このプロパティの結果を適切なクラス型にキャストして使用できます。

DataOutputType OutputType - このプロパティは、次の 4 つの値のいずれかをとる列挙型です。 Page、ServerCache、Both、または None。 コントロールをレイアウト ページで使用し、結果を Web パーツによって表示する場合は、OutputType を Page または Both にする必要があります。 データを取得して ASP.NET キャッシュに保存する場合は、ServerCache または Both を使用する必要があります。 メモ: 結果をキャッシュに保存する際には、QueryResultsObject のみが保存されます。 もちろん、Both の場合はデータの表示と ASP.NET への保存の両方が行われます。 SharePoint タイマー ジョブなどでコントロールをプログラムによって使用する場合は、このプロパティを None に設定できます。ExecuteRequest メソッドの呼び出し後、QueryResultsString または QueryResultsObject を単純に読み取ればよいからです。 このプロパティは、CASI キット Web パーツを使用してクエリ文字列によって設定できます。

string ServerCacheName - OutputType で ServerCache または Both を選択した場合は、ServerCacheName プロパティに空でない文字列値を設定する必要があります。そうしないと例外が発生します。 これは、結果を ASP.NET キャッシュに保存する際に使用されるキーです。 たとえば、ServerCacheName プロパティを "MyFooProperty" に設定した場合は、ExecuteRequest メソッドを呼び出した後、HttpContext.Current.Cache["MyFooProperty"] を参照することで、WCF アプリケーションから返されたオブジェクトを取得できます。 このプロパティは、CASI キット Web パーツを使用してクエリ文字列によって設定できます。

int ServerCacheTime - このプロパティには、ASP.NET キャッシュに追加された項目を保持しておく時間を分単位で指定します。 OutputType プロパティを ServerCache と Both のどちらかに設定した場合は、このプロパティを 0 以外の値に設定する必要があります。そうしないと例外が発生します。 このプロパティは、CASI キット Web パーツを使用してクエリ文字列によって設定できます。

bool DecodeResults - このプロパティは、WCF アプリケーションの返す結果が HtmlEncoded である場合に備えて用意されています。 このプロパティを true に設定すると、HtmlDecoding が結果に対して適用されます。 ほとんどの場合、このプロパティは必要ありません。 このプロパティは、CASI キット Web パーツを使用してクエリ文字列によって設定できます。

string SharePointClaimsSiteUrl - このプロパティは、本来、SharePoint タイマー ジョブなど、プログラムによって HTTP 要求の外側でコントロールを作成するシナリオのために用意されています。 既定では、Web パーツによって要求が生成されると、基本クラスは現在のサイトの URL を使用して SharePoint STS エンドポイントに接続し、ユーザー トークンを WCF 呼び出しに提供します。 しかし、コントロールをプログラムによって作成していて、HTTP コンテキストがない場合は、このプロパティをクレームでセキュリティ保護された SharePoint サイトの URL に設定でき、そうするとそのサイトが SharePoint STS へのアクセスに使用されるようになります。 その場合は、たとえば、このプロパティをレイアウト ページのコントロール タグで設定する必要が一切なくなります。そのページを呼び出すと、HTTP コンテキストが必ず得られることになるからです。

bool AllowQueryStringOverride - 管理者は、このプロパティを使用してレイアウト ページ内のコントロール タグを効果的にロック ダウンできます。 AllowQueryStringOverride が false に設定されている場合、CASI キット Web パーツから渡されるすべてのクエリ文字列オーバーライド値は無視されます。

string AccessDeniedMessage - 特定のメソッドのユーザーに対してアクセスが拒否された場合に、CASI キット Web パーツに表示されるアクセス拒否エラー メッセージです。 たとえば、このシリーズのパート 2 で説明したように、ここでは WCF 呼び出し時にユーザーのトークンを渡すので、"このユーザーは Sales Managers グループのメンバーである必要があります" のように、PrincipalPermission 要求によって任意のメソッドを修飾できます。 ユーザーが PrincipalPermission 要求を満たしていない場合、WCF 呼び出しはアクセス拒否エラーによって失敗します。 その場合は、Web パーツによって AccessDeniedMessage の内容が表示されます。 このメッセージでは、高度な書式設定を使用でき、HTML タグによってフォントを太字や赤色に設定するといったことができます (例: <font color='red'>アクセス権がありません。管理者に問い合わせてください</font>)。 このプロパティは、CASI キット Web パーツを使用してクエリ文字列によって設定できます。

string TimeoutMessage - WCF メソッド呼び出しの実行時にタイムアウト エラーが発生した場合に、CASI キット Web パーツに表示されるメッセージです。 フォントの太字、赤色など、高度な書式設定もサポートされています。 このプロパティは、CASI キット Web パーツを使用してクエリ文字列によって設定できます。

以上、今回は長くなってしまいましたが (おそらくこのシリーズで最も長い投稿です)、それは CASI キットで最も重要な部分だったからです。 次の投稿では、今回作成したカスタム コントロールとレイアウト ページを使用して、CASI キットに付属する Web パーツで WCF アプリケーションのデータを表示する方法を説明します。

また、この投稿には、私が作成したサンプル Visual Studio 2010 プロジェクトの zip ファイルを付けておきます。このプロジェクトには、CASI キット基本クラス アセンブリ、CASI キット基本クラスを継承したカスタム コントロール、カスタム レイアウト ページが含まれています。

これはローカライズされたブログ投稿です。原文の記事は、「The Claims, Azure and SharePoint Integration Toolkit Part 3」をご覧ください。