この付録の内容は次のとおりです。
注意:
プロパティ・インスペクタは、プロパティまたはプロパティの組合せに入力した値が有効かどうかの検証は実行しません。無効な値があると、実行時にエラーが発生します。実行時のエラーを回避するには、プロパティ・インスペクタでプロパティに有効な値を指定してください。プロパティ・インスペクタの詳細は、「プロパティ・インスペクタの使用」を参照してください。
サーバーのpingテストを使用して、Fusion WebアプリケーションによってADFデスクトップ統合のリモート・サーブレット(adfdiRemote
)が実行されていることを確認し、ADFデスクトップ統合のバージョンを確認できます。
この情報は、統合Excelワークブックに関連するエラーが発生した場合に役立ちます。たとえば、統合Excelワークブックのトラブルシューティングを行う際に、ADFデスクトップ統合のリモート・サーブレットが稼働しているかどうかを判断できます。
認証を実施するFusion Webアプリケーションの場合、サーバーのpingテストを使用して、ADFデスクトップ統合サーブレットURLに対して適切な認証構成が完了していることを確認できます。
ADFデスクトップ検証は、Internet Explorer固有の様々な設定に依存します。このような理由から、Internet Explorerを使用して検証テストを実行してください。
ADFデスクトップ統合のリモート・サーブレットが稼働していることを検証するには:
ADFデスクトップ統合は、エンド・ユーザーがクライアント・サイドの環境で発生する可能性のある問題を診断して解決できる複数のツールを提供しています。
これには、「クライアント・ヘルス・チェック・ツールの実行」に示すクライアント・ヘルス・チェック・ツールが含まれています。これにより、クライアントの環境が適切に構成されているか判断し、一般的に発生する問題のいくつかを解決するためのオプションが示されます。エンド・ユーザーは、次の項で説明するように、統合Excelワークブックから診断レポート(adfdi-diagnostic-report.txt
) を生成することもできます。
診断レポートは、次のような様々な情報を含むテキスト・ファイルです。
ADFデスクトップ統合アドインのバージョン
Microsoft Windowsのバージョン
Microsoft Excelのバージョン
「情報」ダイアログの「バージョン」タブからのすべてのプロパティの値
「情報」ダイアログの「プロパティ」タブにリストされるすべてのプロパティの値
Excel COMアドインのリスト
「情報」からのブランディング項目(レポートが実行時に生成される場合)
ADFデスクトップ統合サーブレットのバージョン(有効なログイン後にレポートが生成される場合)
テキスト・ファイルは、任意のテキスト・エディタまたはExcelで開いて編集できます。ファイルの各行は、タブで区切られたキーと値のペアで構成されます。
エンド・ユーザーが診断ファイルを送信する前に、レポートを見直して、共有したくない機密情報があれば削除するようにエンド・ユーザーに求めます。
ADFデスクトップ統合は、統合ExcelワークブックからFusion Webアプリケーションへの接続の問題の原因の診断に役立つ、接続失敗レポートをエンド・ユーザーに提供します。
接続失敗レポートには、Fusion Webアプリケーションへの接続の試行が失敗した場合、またはエンド・ユーザーが接続の試行を取り消した場合にADFデスクトップ統合が生成する情報が含まれます。図C-3では、Summitサンプル・アプリケーションがオフラインだったために、EditCustomers.xlsx
ワークブックからSummitサンプル・アプリケーションに接続できなかったときに表示されたダイアログを示しています。エンド・ユーザーは「レポートの保存」をクリックして、マシンのディレクトリにレポートを保存します。
図C-3 エンド・ユーザーが接続レポートを保存するためのダイアログ
エンド・ユーザーが接続失敗レポートを送信する前に、レポートを見直して、共有が望ましくない機密情報があれば削除するようにエンド・ユーザーに求めます。次の例は、図C-3で生成されるレポートの抜粋を示しています。
Report: Oracle ADF Desktop Integration (ADFdi) Connection Failure Report Generated: (UTC) 04/12/2015 09:47:13 Language: en-US *** NOTE: this file contains detailed diagnostic information. Review the contents and edit out any information you do not wish to share with third parties. *** === Summary === Failure Phase AuthenticationTest Failure Reason UnexpectedHttpStatusException - ADFDI-00501: An unexpected status: 404 (NotFound) was returned from the server while requesting the URL: http://127.0.0.1:7101/summit/adfdiRemoteServlet ADFdi servlet URL http:// 127.0.0.1:7101/summit/adfdiRemoteServlet ...
接続の問題のトラブルシューティングの詳細は、My Oracle Support (https://support.oracle.com)でドキュメントID 2014348.1
と2094772.1
を検索すると入手できるドキュメントを参照してください。
統合Excelワークブックのユーザーが、ADFセキュリティを使用して構成されているFusion Webアプリケーションと相互作用するアクションを起動する際にユーザー認証を要求されない場合、統合ExcelワークブックまたはFusion Webアプリケーションのどちらかでセキュリティが正しく構成されていない可能性があります。
次の手順を実行して、セキュアなFusion Webアプリケーションによってエンド・ユーザーが認証されること、およびセキュリティが有効であることを検証できます。
セキュアなFusion Webアプリケーションによってエンド・ユーザーが認証されることを検証するには、ADFデスクトップ統合のリモート・サーブレットが稼働中かどうかを検証するために使用したURLを、ブラウザのアドレス・バーに入力します。「Fusion WebアプリケーションによるADFデスクトップ統合のサポートの検証」を参照してください。Fusion Webアプリケーションのセキュリティが有効である場合は、ユーザー資格証明を入力するよう求められます。
統合Excelワークブックの保護の詳細は、「統合Excelワークブックの保護」を参照してください。
ADFデスクトップ統合では、サーバー・サイドおよびクライアント・サイドのソフトウェアによってトリガーされたイベントに基づいて情報を取得するログ・ファイルを生成できます。
ADFデスクトップ統合内の次のソフトウェア部分によって、イベントがトリガーされます。
Webサーバー上にある、HTTPフィルタおよびADFデスクトップ統合のリモート・サーブレット(サーバー・サイド・ロギング)
サーバー・サイド・ロギングの詳細は、「サーバー・サイド・ロギングの概要」を参照してください。
Fusion Webアプリケーションと統合するExcelワークブック(クライアント・サイド・ロギング)
クライアント・サイド・ロギングの詳細は、「クライアント・サイド・ロギングの概要」を参照してください。
ADFデスクトップ統合のサーバー・サイド・ログ・ファイルの生成は、他のOracle ADFモジュールの場合と同じように構成します。構成するには、logging.xml
という構成ファイルで冗長レベルと出力場所を指定する値を設定する必要があります。また、JDeveloperのOracle Diagnostic Logging構成を使用して、logging.xml
ファイルで指定されるロギング・レベルを構成することもできます。JDeveloperのデバッグ・ツールおよびADFログ出力の使用の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のADFログ出力の使用に関する項を参照してください。
表C-1に、ADFデスクトップ統合のログ・ファイルの生成を構成するために、logging.xml
ファイルの<logger>
要素に属性パラメータとして指定するパッケージ名を示します。
表C-1 ログ・ファイルを構成するためのパッケージの名前
ログ・ファイル・エントリを生成するコンポーネント | 入力するパッケージ名 |
---|---|
すべてのADFデスクトップ統合サーバー・ロジック |
|
ADFデスクトップ統合のHTTPフィルタ |
|
Oracle Diagnostics Log Analyzerを使用すると、各ADFデスクトップ統合サーブレット・リクエストの実行に費やされた経過時間の階層ブレークダウンを表示できます。階層ブレークダウンには、ADFモデル・レイヤーなどのその他のADFコンポーネントで費やされた時間も含まれます。ログ・アナライザを使用してWebリクエストを表示する方法の詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のログ・アナライザを使用してログ・メッセージを表示する方法に関する項を参照してください。
ヒント:
階層ブレークダウンは、異常に長い実行時間によるパフォーマンスのボトルネックを特定する際に役に立ちます。
ADFデスクトップ統合イベントなどのADFイベント・メッセージの完全な階層ツリーを記録するために、oracle.adfdiagnostics
パッケージにログ・レベルCONFIG
を指定します。oracle.adfdiagnostics
ロガーの詳細は、『Oracle Application Development FrameworkによるFusion Webアプリケーションの開発』のOracle ADFデバッグ構成の作成方法に関する項を参照してください。
ADFデスクトップ統合は、ADFデスクトップ統合アドイン内で発生するアクティビティのログ・ファイルを作成するために、いくつかの方法を提供します。ロギングは、常に概要レベルであるInformation
レベルで有効になっています。これらのログはプレーン・テキスト・フォーマットで、基本的なユーザー処理の段階やエラーと警告が含まれています。詳細は、「常時有効なロギングに関する必知事項」を参照してください。
特定の問題のトラブルシューティングに、より詳細なログが必要になることがあります。Verbose
レベルの詳細なログを生成するための方法がいくつかあります。最もシンプルな方法は、ADFデスクトップ統合がMicrosoft Excelに追加するExcelアドイン・メニューから「ロギングの有効化」を選択して、一時的な詳細ロギングを有効にするものです。これらのログはXML形式で、クライアント・サイドのアクティビティの詳細な説明が含まれています。詳細は、「一時的な詳細ロギングの有効化」を参照してください。
さらに、クライアントのログを制御する方法が他に2つあります。
「「Oracle ADF」タブのロギングの構成方法」の説明に従って、「Oracle ADF」タブが表示するロギングのオプションを使用します。
「ADFデスクトップ統合の構成ファイルについて」の説明に従って、ADFデスクトップ統合の構成ファイルを使用します。
「ユーザー環境変数を使用したロギングの構成方法」の説明に従って、環境変数を構成します。
統合Excelワークブックの1回以上の再起動にまたがるログ情報をキャプチャする場合、またはverbose
より低いロギング・レベルを構成する場合は、後の2つのオプションのいずれかの利用を検討してください。
表C-2に、クライアント・サイドのロギングで有効にできる様々なログ・レベルの説明を示します。
ADFデスクトップ統合では、デフォルトで次のディレクトリ(優先度順)のいずれかのadfdi-logs
サブディレクトリのテキスト・ファイルへのInformation
レベルでのロギングが有効になっています。
%TEMP%\oracle\adfdi-logs
%TMP%\oracle\adfdi-logs
%LocalAppData%\temp\oracle\adfdi-logs
%SystemDrive%\oracle\adfdi-logs
ADFデスクトップ統合がログ・ファイル情報の格納に前述のどのディレクトリを使用するかを判断するには、図C-4に示すように、統合Excelワークブックの「バージョン情報」ダイアログから表示できる「ログ・ファイル」プロパティを確認します。
図C-4 常時有効なログ・ファイルのディレクトリの場所
統合Excelワークブックで新しいExcelセッションを開始するたびに、ADFデスクトップ統合によって新しいログ・ファイルが作成されます。ログ・ファイルには、adfdi-log-
timestamp
.txt
というネーミング規則で名前が付けられます。timestamp
は統合Excelワークブックを起動した時刻です(例: adfdi-log-2015-11-25-191209.txt
)。
注意:
ADFデスクトップ統合は、フォルダが特定のサイズに達したときに、フォルダ内の常時有効なログ・ファイルの最も古いものをパージします。詳細は、My Oracle Support (https://support.oracle.com)でドキュメントID 2094378.1
を検索すると入手できるドキュメントを参照してください。
エンド・ユーザーは、アクティブな統合Excelワークブックのメニューから詳細ロギングを有効にできます。ADFデスクトップ統合は、メニューからログ出力を有効にしたときに指定するディレクトリのファイルに詳細ログの情報を書き込みます。
このロギングを有効にするときにADFデスクトップ統合が作成するファイル名は、次の形式になります。
adfdi-log-timestamp.xml
timestampは、ロギングを有効にした時刻です。たとえば、adfdi-log-2015-11-24-145055.xml
のようになります。
Microsoft Excelを終了すると、ADFデスクトップ統合はログ・ファイルへの情報の記録を停止します。
一時的な詳細ロギングを有効にするには:
WindowsメニューからMicrosoft Excelを起動しますが、詳細ログのデータをキャプチャする、問題の発生している統合Excelワークブックは開きません。
図C-5に示すように、Excelの「Office」メニューまたは「ファイル」メニューから、「アドイン」 > 「ADFデスクトップ統合」 > 「ロギングの有効化」を選択します。
選択した場所にログ・ファイルを保存するか、「ロギング・データの別名保存」ダイアログが提案したデフォルトのデスクトップの場所を使用します。後で参照できるように、ログ・ファイルの名前と場所をメモします。
統合Excelワークブックを開き、詳細ログのデータをキャプチャする問題を再現するための手順を繰り返します。
手順が完了したら、Microsoft Excelを終了できます。Microsoft Excelを終了すると、ADFデスクトップ統合はステップ3で作成したログ・ファイルへの詳細データの記録を停止します。
ヒント:
問題についてキャプチャした詳細なログ・データを含み、テクニカル・サポートに送信できる、ADFデスクトップ統合が動作する環境についての情報が記載された診断レポートを保存します。図C-5に示すように、Excelの「Office」メニューまたは「ファイル」メニューから、「アドイン」 > 「ADFデスクトップ統合」 > 「診断レポートを保存」を選択します。詳細は、My Oracle Support (https://support.oracle.com)でドキュメントID 2094434.1
を検索すると入手できるドキュメントを参照してください。
図C-6に示すように、「Oracle ADF」タブは、設計モードとテスト・モードの両方で利用できるメニュー・オプションのロギング・グループを提供します。
図C-6 「Oracle ADF」タブのロギング・ツール
「ロギング」グループには次のボタンがあります。
コンソール
統合Excelワークブックを開発およびテストしながら最新のログ・エントリを確認できる、ロギング・コンソール・ウィンドウを表示します。このコンソールには、コンソールが開いている間に記録されたエントリが表示されます。図C-7に示すロギング・コンソール・ウィンドウには、情報およびエラーのログ・エントリが表示されています。
このコンソールは、サイズ変更が可能でバッファ・サイズが64,000文字の非モーダル・ウィンドウです。バッファがいっぱいになると、古いエントリは削除されます。
図C-7 ロギング・コンソール・ウィンドウ
このダイアログには次のボタンがあります。
レベルの設定: ログ出力レベルを設定する場合は、これをクリックします。このボタンをクリックすると、目的のログ出力レベルを選択できるロギング出力レベル・ダイアログが開きます。
クリア: ログ・バッファをクリアする場合にクリックします。
閉じる: ダイアログを閉じる場合にクリックします。
注意:
一般的なロギング・コンソール・ウィンドウでは、開いているすべての統合Excelワークブックのエントリが記録されます。
出力レベルの設定
ログ出力のレベルを選択するよう求められます。表C-2に、クライアント・サイド・ロギングがサポートするログ・レベルを示します。ログ・レベルは、表C-2のリストの下方向に累積されます。つまり、Information
レベルにはCritical
、Error
およびWarning
レベルでログされたデータは含まれますが、Verbose
レベルでログされたデータは含まれません。
図C-8 ロギング出力レベル・ダイアログ
表C-2 クライアント・サイド・ロギングのレベル
レベル | 説明 |
---|---|
|
クリティカルな情報を取得します。 |
|
重度のエラーと例外に関する情報を取得します。 |
|
警告に関する情報を取得します。 |
|
ライフ・サイクル・イベントとコントロール・フロー・イベントを取得します。これはデフォルト値です。 |
|
アプリケーションの実行フローに関する詳細を取得します。 |
注意:
ログ出力のレベルは、指定されたロガーのすべてのリスナーに適用されます。
ログ出力ファイルの追加
指定のファイルまたは形式にロギング出力を送るための、一時ロギング・リスナーを作成します。「新規一時ロギング出力ファイルの追加」ダイアログで、目的のファイル出力形式(テキストまたはXML)を選択し、ログ出力ファイルのパスとファイル名を指定します。
図C-9 新規一時ロギング出力ファイルの追加ダイアログ
一時リスナーは、現在のExcelセッションのロギング出力のみを送り、ADFデスクトップ統合の構成ファイルには登録されません。Excelを終了すると、一時リスナーは削除されます。
注意:
「ログ出力ファイルの追加」ボタンをクリックすると、新しいリスナーが作成されます。新しいリスナーによって、ADFデスクトップ統合の構成ファイルで定義された既存のリスナー、または他の一時リスナーは置換されません。
構成のリフレッシュ
ADFデスクトップ統合の構成ファイルをリロードします。ADFデスクトップ統合の構成ファイルによって、ADFデスクトップ統合アドインで記録される情報のレベルを決定できます。
ADFデスクトップ統合の構成ファイルの作成および構成の詳細は、「ADFデスクトップ統合の構成ファイルについて」を参照してください。
ADFデスクトップ統合の構成ファイルは、adfdi-excel-addin.dll.config
として保存されます。ファイルの正しい名前および場所を調べるには、「Oracle ADF」タブの「ワークブック」グループにある「バージョン情報」ボタンをクリックします。表示されるダイアログで「プロパティ」タブをクリックし、「構成」エントリで構成ファイルのファイル名および場所を調べます。
構成ファイルの要素の詳細は、Microsoft Developer Networkのドキュメントの.NET Frameworkの構成ファイル・スキーマに関する項を参照してください。トレースおよびデバッグの設定の詳細は、Microsoft Developer Networkのドキュメントのトレースおよびデバッグ設定のスキーマに関する項を参照してください。
クライアント・サイド・ロギングの有効な構成方法は多数ありますが、例C-1に示す構成ファイルのサンプルはその1つで、.xml
ログ・ファイルが生成されます。このファイルでは、様々な情報(ThreadId
、ProcessId
およびDateTime
など)がVerbose
ロギング・レベルで取得されます。
例C-1 サンプル構成ファイル
<?xml version="1.0"?> <configuration> <system.diagnostics> <sources> <source name="adfdi-common" switchValue="Verbose"> <listeners> <add type="System.Diagnostics.XmlWriterTraceListener" name="adfdi-common-excel.xml" initializeData="c:\logs\adfdi-common-excel.xml" traceOutputOptions="ThreadId, ProcessId, DateTime"/> </listeners> </source> </sources> </system.diagnostics> </configuration>
ADFデスクトップ統合の構成ファイルを格納するディレクトリにアクセスできないユーザーは、ユーザー環境変数の値を設定してログ・ファイルの保存場所とロギング・レベルを変更できます。ロギング・レベルとXMLログ・ファイルの場所を構成するための、2つのユーザー環境変数を追加できます。
詳細は、My Oracle Support (https://support.oracle.com)でドキュメントID 2012985.1
を検索すると入手できるADFデスクトップ統合のログ・ファイルの入手方法に関するドキュメントを参照してください。
ヒント:
環境変数を構成する前に、必ずExcelを完全に終了してください。Windowsでユーザー環境変数を追加または構成するには:
adfdi-common
オブジェクトは、Microsoft .NET FrameworkのSystem.Diagnostics
名前空間のTraceSource
クラスのインスタンスです。このオブジェクトを使用してログ・ファイルを生成すると、Fusion Webアプリケーションと統合するExcelワークブックでトリガーされるイベントの情報を取得できます。ログ・ファイルの場所を知るには、「情報」ダイアログの「プロパティ」タブの「ログ・ファイル」属性を確認します。
TraceSource
クラスの詳細は、Microsoft Developer Networkのドキュメントを参照してください。