1. Oracle ADFデスクトップ統合によるアプリケーションの開発
  2. 統合Excelワークブックのトラブルシューティング

C 統合Excelワークブックのトラブルシューティング

開発中に問題が発生した場合に統合Excelワークブックのトラブルシューティングを行い、ログ・ファイルを生成する方法について説明します。

この付録の内容は次のとおりです。

注意:

プロパティ・インスペクタは、プロパティまたはプロパティの組合せに入力した値が有効かどうかの検証は実行しません。無効な値があると、実行時にエラーが発生します。実行時のエラーを回避するには、プロパティ・インスペクタでプロパティに有効な値を指定してください。プロパティ・インスペクタの詳細は、「プロパティ・インスペクタの使用」を参照してください。

Fusion WebアプリケーションによるADFデスクトップ統合のサポートの検証

サーバーのpingテストを使用して、Fusion WebアプリケーションによってADFデスクトップ統合のリモート・サーブレット(adfdiRemote)が実行されていることを確認し、ADFデスクトップ統合のバージョンを確認できます。

この情報は、統合Excelワークブックに関連するエラーが発生した場合に役立ちます。たとえば、統合Excelワークブックのトラブルシューティングを行う際に、ADFデスクトップ統合のリモート・サーブレットが稼働しているかどうかを判断できます。

認証を実施するFusion Webアプリケーションの場合、サーバーのpingテストを使用して、ADFデスクトップ統合サーブレットURLに対して適切な認証構成が完了していることを確認できます。

ADFデスクトップ検証は、Internet Explorer固有の様々な設定に依存します。このような理由から、Internet Explorerを使用して検証テストを実行してください。

ADFデスクトップ統合のリモート・サーブレットが稼働していることを検証するには:

  1. Webブラウザのアドレス・バーに、ワークブックのプロパティWebAppRootおよびRemoteServletPathを連結した値を入力します。これは、次のようなURLに相当します。

    http://hostname:7101/summit/adfdiRemoteServlet

    ADFデスクトップ統合のリモート・サーブレットが稼働している場合、Webページが元に戻って図C-1のようなメッセージが表示されます。

    図C-1 ADFデスクトップ統合のリモート・サーブレット

    図C-1の説明が続きます
    「図C-1 ADFデスクトップ統合のリモート・サーブレット」の説明

ADFデスクトップ統合診断レポートの生成

ADFデスクトップ統合は、エンド・ユーザーがクライアント・サイドの環境で発生する可能性のある問題を診断して解決できる複数のツールを提供しています。

これには、「クライアント・ヘルス・チェック・ツールの実行」に示すクライアント・ヘルス・チェック・ツールが含まれています。これにより、クライアントの環境が適切に構成されているか判断し、一般的に発生する問題のいくつかを解決するためのオプションが示されます。エンド・ユーザーは、次の項で説明するように、統合Excelワークブックから診断レポート(adfdi-diagnostic-report.txt) を生成することもできます。

ADFデスクトップ統合診断レポートの生成方法

図C-2で示すように、ADFデスクトップ統合がMicrosoft Excelの「ファイル」 > 「アドイン」メニューに追加する診断レポートを保存メニュー項目をクリックして、診断レポートを生成できます。

図C-2 診断レポートを保存するファイル・メニュー

このイメージについては周囲のテキストで説明しています。

このメニュー項目の場所は、使用するMicrosoft Excelのバージョンによって異なります。図C-2に、Microsoft Excel 2013でのこのメニュー項目の場所を示します。

また、エンド・ユーザーは、「情報」ダイアログから診断レポートを生成できます。

「情報」ダイアログからADFデスクトップ統合の診断レポートを生成するには:

  1. 統合Excelワークブックを開きます。
  2. 統合Excelワークブックを設計モードで開いた場合は、「Oracle ADF」タブの「ワークブック」グループの「情報」ボタンをクリックします。

    統合Excelワークブックを実行時モードで開いた場合は、実行時リボン・タブの「情報」ボタンをクリックします。

  3. 「情報」ダイアログの「診断レポート」ボタンをクリックします。
  4. 診断レポートのテキスト・ファイルを保存します。デフォルトでは、ファイルは、adfdi-diagnostic-report.txtとしてDesktopディレクトリ(例: C:\Users\<USER_NAME>\Desktop)に保存されます。
  5. 保存したファイルの場所を示す「診断レポート」ダイアログが開きます。「OK」をクリックして、デフォルトのテキスト・エディタでファイルを開きます。

ADFデスクトップ統合診断レポートに関する必知事項

診断レポートは、次のような様々な情報を含むテキスト・ファイルです。

  • ADFデスクトップ統合アドインのバージョン

  • Microsoft Windowsのバージョン

  • Microsoft Excelのバージョン

  • 「情報」ダイアログの「バージョン」タブからのすべてのプロパティの値

  • 「情報」ダイアログの「プロパティ」タブにリストされるすべてのプロパティの値

  • Excel COMアドインのリスト

  • 「情報」からのブランディング項目(レポートが実行時に生成される場合)

  • ADFデスクトップ統合サーブレットのバージョン(有効なログイン後にレポートが生成される場合)

テキスト・ファイルは、任意のテキスト・エディタまたはExcelで開いて編集できます。ファイルの各行は、タブで区切られたキーと値のペアで構成されます。

エンド・ユーザーが診断ファイルを送信する前に、レポートを見直して、共有したくない機密情報があれば削除するようにエンド・ユーザーに求めます。

Fusion Webアプリケーションへの接続の問題のトラブルシューティング

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ワークブックのエンド・ユーザー認証の確認

統合Excelワークブックのユーザーが、ADFセキュリティを使用して構成されているFusion Webアプリケーションと相互作用するアクションを起動する際にユーザー認証を要求されない場合、統合ExcelワークブックまたはFusion Webアプリケーションのどちらかでセキュリティが正しく構成されていない可能性があります。

次の手順を実行して、セキュアなFusion Webアプリケーションによってエンド・ユーザーが認証されること、およびセキュリティが有効であることを検証できます。

セキュアなFusion Webアプリケーションによってエンド・ユーザーが認証されることを検証するには、ADFデスクトップ統合のリモート・サーブレットが稼働中かどうかを検証するために使用したURLを、ブラウザのアドレス・バーに入力します。「Fusion WebアプリケーションによるADFデスクトップ統合のサポートの検証」を参照してください。Fusion Webアプリケーションのセキュリティが有効である場合は、ユーザー資格証明を入力するよう求められます。

統合Excelワークブックの保護の詳細は、「統合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デスクトップ統合サーバー・ロジック

oracle.adf.desktopintegration

ADFデスクトップ統合のHTTPフィルタ

oracle.adf.desktopintegration.filter

Oracle Diagnostics Log Analyzerを使用したADFデスクトップ統合サーブレット・リクエストの分析

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つあります。

統合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のバージョンに応じて異なります。図C-5 に、Microsoft Excel 2013でのこのメニュー項目の場所を示します。

図C-5 詳細ロギングを有効にするExcelの「ファイル」メニュー

図C-5の説明が続きます。
「図C-5 詳細ロギングを有効にするExcelの「ファイル」メニュー」の説明

Microsoft Excelを終了すると、ADFデスクトップ統合はログ・ファイルへの情報の記録を停止します。

一時的な詳細ロギングを有効にするには:

  1. WindowsメニューからMicrosoft Excelを起動しますが、詳細ログのデータをキャプチャする、問題の発生している統合Excelワークブックは開きません。

  2. 図C-5に示すように、Excelの「Office」メニューまたは「ファイル」メニューから、「アドイン」 > 「ADFデスクトップ統合」 > 「ロギングの有効化」を選択します。

  3. 選択した場所にログ・ファイルを保存するか、「ロギング・データの別名保存」ダイアログが提案したデフォルトのデスクトップの場所を使用します。後で参照できるように、ログ・ファイルの名前と場所をメモします。

  4. 統合Excelワークブックを開き、詳細ログのデータをキャプチャする問題を再現するためのステップを繰り返します。

  5. ステップが完了したら、Microsoft Excelを終了できます。Microsoft Excelを終了すると、ADFデスクトップ統合はステップ3で作成したログ・ファイルへの詳細データの記録を停止します。

ヒント:

問題についてキャプチャした詳細なログ・データを含み、テクニカル・サポートに送信できる、ADFデスクトップ統合が動作する環境についての情報が記載された診断レポートを保存します。図C-5に示すように、Excelの「Office」メニューまたは「ファイル」メニューから、「アドイン」 > 「ADFデスクトップ統合」 > 「診断レポートを保存」を選択します。

詳細は、My Oracle Support (https://support.oracle.com)でドキュメントID 2094434.1を検索すると入手できるドキュメントを参照してください。

「Oracle ADF」タブのロギングの構成方法

図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 クライアント・サイド・ロギングのレベル

    レベル 説明

    Critical

    クリティカルな情報を取得します。

    Error

    重度のエラーと例外に関する情報を取得します。

    Warning

    警告に関する情報を取得します。

    Information

    ライフ・サイクル・イベントとコントロール・フロー・イベントを取得します。これはデフォルト値です。

    Verbose

    アプリケーションの実行フローに関する詳細を取得します。

    注意:

    ログ出力のレベルは、指定されたロガーのすべてのリスナーに適用されます。

  • ログ出力ファイルの追加

    指定のファイルまたは形式にロギング出力を送るための、一時ロギング・リスナーを作成します。「新規一時ロギング出力ファイルの追加」ダイアログで、目的のファイル出力形式(テキストまたはXML)を選択し、ログ出力ファイルのパスとファイル名を指定します。

    図C-9 新規一時ロギング出力ファイルの追加ダイアログ

    この図は周囲のテキストで説明しています

    一時リスナーは、現在のExcelセッションのロギング出力のみを送り、ADFデスクトップ統合の構成ファイルには登録されません。Excelを終了すると、一時リスナーは削除されます。

    注意:

    「ログ出力ファイルの追加」ボタンをクリックすると、新しいリスナーが作成されます。新しいリスナーによって、ADFデスクトップ統合の構成ファイルで定義された既存のリスナー、または他の一時リスナーは置換されません。

  • 構成のリフレッシュ

    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でユーザー環境変数を追加または構成するには:

  1. Windowsの「スタート」ボタン、「コントロール パネル」の順にクリックします。
  2. 「コントロール パネル」で、「システム」、「システムの詳細設定」の順にクリックします。
  3. 「システムのプロパティ」ダイアログの「詳細設定」タブで、「環境変数」をクリックします。
  4. 「環境変数」ダイアログで「usernameのユーザー環境変数」入力フィールドの下方にある「新規」をクリックし、表C-3の説明に従って変数を追加します。

    表C-3 ロギングを構成するためのユーザー環境変数

    入力する変数の名前 指定する値

    adfdi-common-file

    ロギング情報を取得するXMLファイルのディレクトリ・パスおよびファイル名を定義する値。

    ここで指定するディレクトリは、adfdi-common-file変数を追加する前に存在している必要があります。生成されるログ・ファイルはXML形式です。

    adfdi-common-level

    ロギングのレベルを指定する値。有効な値は表C-2を参照してください。

  5. 「OK」をクリックします。
adfdi-commonオブジェクトに関する必知事項

adfdi-commonオブジェクトは、Microsoft .NET FrameworkのSystem.Diagnostics名前空間のTraceSourceクラスのインスタンスです。このオブジェクトを使用してログ・ファイルを生成すると、Fusion Webアプリケーションと統合するExcelワークブックでトリガーされるイベントの情報を取得できます。ログ・ファイルの場所を知るには、「情報」ダイアログの「プロパティ」タブの「ログ・ファイル」属性を確認します。

TraceSourceクラスの詳細は、Microsoft Developer Networkのドキュメントを参照してください。