ProGuide Diagnosing ArcGIS Pro Add ins - EsriJapan/arcgis-pro-sdk GitHub Wiki

Language:      C#
Subject:       Framework
Contributor:   ArcGIS Pro SDK Team <[email protected]>  
Organization:  Esri, http://www.esri.com  
Date:          10/06/2024  
ArcGIS Pro:    3.4  
Visual Studio: 2022

このガイドでは、ArcGIS Pro アドインを使用して開発を行う際に時々遭遇する以下の問題の解決策を紹介します。

3.0 - 3.2 アドインが ArcGIS Pro 3.3 でコンパイルされない
3.3 でコンパイルすると "The specified RuntimeIdentifier win10-x64 is not recognized" エラーが発生する
NuGet パッケージを 3.3 に変更すると "NU1202 Package Esri.ArcGISPro.Extensions30 is not compatible" エラーが表示される
2.x アドインが ArcGIS Pro 3.0 で読み込まれない
2.x アドインが ArcGIS Pro 3.0 でコンパイルされない
Visual Studio でビルドした後に ArcGIS Pro でアドインが読み込まれない
ArcGIS.Core.CalledOnWrongThreadException の例外が発生する
ArcGIS Pro でアドインが読み込まれない
ボタンコントロールで画像が読み込まれない
アセンブリ名の不一致により、Visual Studio でコンパイル時の警告が表示される
名前空間 (ネームスペース) の不一致により、コントロールが動作しなかったり消えたりする
アドインにより起動時に Pro がクラッシュする
Copy-local=No が機能しない
アドインのトラブルシューティングユーティリティ:
- 起動時に読み込まれた DAML 要素を表示する: dumpcombineddaml
- ダイナミックモードのイベントログを有効にする: enablediagnostics

3.0 - 3.2 アドインが ArcGIS Pro 3.3 でコンパイルされない

以下のようなエラーが表示される場合：

Error	CS1705
Assembly 'ArcGIS.Desktop.Framework' with identity 'ArcGIS.Desktop.Framework, Version=13.3.0.0, Culture=neutral, 
   PublicKeyToken=8fc3cc631e44ad86' uses 'System.Runtime, Version=8.0.0.0, Culture=neutral, 
   PublicKeyToken=b03f5f7f11d50a3a' which has a higher version than referenced assembly 'System.Runtime' 
   with identity 'System.Runtime, Version=6.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'  
   "YourProjectName here" ...

ターゲットフレームワークを .NET 8 に変更します。3.3 で ArcGIS Pro は .NET 8.0 に移行しました。詳しくは ProGuide NET 8 Upgrade をご参照ください。

3.3 でコンパイルすると "The specified RuntimeIdentifier win10-x64 is not recognized" エラーが発生する

.NET 8 では、.csproj または.vbproj の<RuntimeIdentifier> の値を変更する必要があるかもしれません。.csproj を開き、以下の行が正しい内容を示していることを確認してください。必要に応じて変更してください。

<TargetFramework>net8.0-windows</TargetFramework>
<!--RuntimeIdentifier>win10-x64</RuntimeIdentifier --><!-- old - note win"10"-x64 -->
<RuntimeIdentifier>win-x64</RuntimeIdentifier><!-- new - "win10-x64" was changed to "win-x64" -->

詳しくは ProGuide NET 8 Upgrade をご参照ください。

NuGet パッケージを 3.3 に変更すると "NU1202 Package Esri.ArcGISPro.Extensions30 is not compatible" エラーが表示される

3.3 で NuGet パッケージの参照を変更すると、以下のエラーが発生します。

Error	NU1202	Package Esri.ArcGISPro.Extensions30 3.3.0.52579 is not compatible with net6.0-windows7.0 
(.NETCoreApp,Version=v6.0). Package Esri.ArcGISPro.Extensions30 3.3.0.52579 supports: net8.0-windows7.0 
(.NETCoreApp,Version=v8.0) AcmeAddin C:\Users\tester\source\AcmeAddin\AcmeAddin.csproj

ターゲットフレームワークを .NET 8 に変更する必要があります。3.3 で ArcGIS Pro は .NET 8.0 に移行しました。詳しくは ProGuide NET 8 Upgrade をご参照ください。

2.x アドインが ArcGIS Pro 3.0 で読み込まれない

アドインは、メジャーリリース間で前方互換性がありません。アドインを 3.0 に移行する必要があります. 詳細は migrate you add-in to 3.0 をご参照ください

2.x アドインが ArcGIS Pro 3.0 でコンパイルされない

ArcGIS Pro 3.0 は 重大な変更を伴うリリース です。ArcGIS Pro 3.0 は .NET Framework 4.8 から .NET 6.0 に移行しています。このため、アドインを 3.0 に移行し、再コンパイルし、変更箇所を修正する必要があります。

Visual Studio でビルドした後に ArcGIS Pro でアドインが読み込まれない

問題

Visual Studio のデバッガーを使用して ArcGIS Pro を起動するか、直接 ArcGIS Pro を起動すると、アドインが ArcGIS Pro で読み込まれず、リボンに表示されない。

この問題の原因はいくつかあります。

原因 1

C:\Users\<UserName>\Documents\ArcGIS\AddIns\ArcGISPro フォルダ内のアドインファイル (*.esriAddinX ファイル) を削除した。

コードを変更せずに、Visual Studio でアドインプロジェクトをビルドして ArcGIS Pro を起動するか、Visual Studio の [開始] ボタンをクリックしてデバッガーを起動する。

解決策

Visual Studio の [ビルド] メニューから [ソリューションのリビルド] をクリックします。これにより、C:\Users\<UserName>\Documents\ArcGIS\AddIns\ArcGISPro フォルダにアドインファイル (*.esriAddinX ファイル) が作成されます。ArcGIS Pro を起動するとアドインが読み込まれます。

アドインプロジェクトをビルドすると Visual Studio はインクリメンタルビルドを実行します。これは、前回のビルドからコードの変更がない場合、アセンブリとアドインは再作成されないことを意味します。C:\Users\<UserName>\Documents\ArcGIS\AddIns\ArcGISPro フォルダからアドインファイル (*.esriAddinX ファイル) を削除したため ArcGIS Pro で読み込むことができません。Visual Studio でリビルドすると、すべての中間ファイルとコンパイル済みファイル (C:\Users\<UserName>\Documents\ArcGIS\AddIns\ArcGISPro\*.esriAddinX ファイルを含む) が削除され、コンパイル後に再作成されます。

原因 2

読み込もうとしているアドインの、config.daml ファイルの desktopVersion 属性値がマシンの ArcGIS Pro バージョンよりも高い (新しい) 値になっている。例えば、マシンに ArcGIS Pro 2.6 がインストールされているが、読み込むアドインは ArcGIS Pro 2.9 SDK を使用して作成されている。アドインのバージョンは、config.daml ファイルの desktopVersion 属性値で確認することができます。

...
 <AddInInfo id="{979319f4-267c-4bf9-981b-a7e41c0cc9cc}" version="1.0" desktopVersion="2.2.xxxx">
    <Name>ProAppModule1</Name>   
    <Description>ProAppModule2 description</Description>
    <Image>Images\AddinDesktop32.png</Image>

解決策

マシンの ArcGIS Pro のバージョンをアドインのバージョンに一致するようアップグレードします。アドインは新しいバージョンの ArcGIS Pro でのみ利用可能な API を使用している可能性があります。

以下の 2 つのユーティリティを使用して、ArcGIS Pro アドインでの問題のトラブルシューティングを行うことができます。

起動時に読み込まれたDAML要素を表示する: dumpcombineddaml

ダイナミックモードのイベントログを有効にする: enablediagnostics

注: ArcGIS Pro 3.0 は重大な変更を伴うリリースです。すべての 2.x アドインは、ArcGIS Pro 3.0 で実行する前に 3.0 に移行する必要があります。

原因 3

読み込もうとしているアドインがデジタル署名されていない可能性があります。システム上の ArcGIS Pro は、デジタル署名されたアドインのみをロードするように構成できます。これらの設定は、ArcGIS Pro でアドインマネージャーを使用して定義されます。アドインマネージャーには Pro の設定からアクセスできます。アドインマネージャを使用して、デジタル署名されたアドインのみを読み込むように ArcGIS Pro を構成できます。

解決策

アドインマネージャで定義された設定を確認するには、ArcGIS Pro を起動します。スタートアップページから、[ArcGIS Pro について] をクリックして設定にアクセスします。[アドインマネージャー] タブをクリックします。[オプション] をクリックします。アドインの読み込みを制御するために使用できるさまざまな設定を確認することができます。最初の 2 つのラジオボタンのオプションのいずれかがオンになっているかどうかを確認します。

注：また、ArcGIS Pro のいくつかの高度な設定を実行して、レジストリキーを使用しアドインの読み込みを制御することもできます。

原因 4

PackageType: Addin
1>  Deploying Addin...
1>  ArcGISFolder Name: C:\ProgramData\EsriProCommon\...
Execute RegisterAddIn.exe "E:\Data\SDK\TestAddin\bin\Debug\net8.0-windows\TestAddin.esriAddinX" /s...
1>
1>Done building project "TestAddin.csproj".
1>
1>Build succeeded.

解決策

RegisterAddin.exeの登録に失敗した原因を調べ、問題を解決してください。 MyDocumentsフォルダの場所が無効である可能性があります。特に、カスタムパスやカスタム設定を使用している場合、Windowsが「マイドキュメント」をどのように構成するかについての詳細は、マイドキュメントフォルダの構成を参照してください。

ArcGIS.Core.CalledOnWrongThreadException の例外が発生する

問題

デバッグまたはアドインを使用しているときに、ArcGIS.Core.CalledOnWrongThreadException エラーが発生する。

原因

アドイン内の特定のオブジェクトの API メソッドが間違ったスレッドで呼び出された場合、その呼び出しによって ArcGIS.Core.CalledOnWrongThreadException エラーが発生します。ProConcepts: Framework のタスクとタスクの非同期パターンを参照してください。

解決策

ArcGIS Pro フレームワークには、ArcGIS Pro SDK 内の同期メソッドへの呼び出しを行うタスクをディスパッチする際に使用するカスタムタスクスケジューラが提供されています。アドイン開発者は、QueuedTask.Run を呼び出す必要があります。

  Task t = QueuedTask.Run(()=>
      {
        // Call synchronous SDK methods here
      });

このエラーをスローしているアドインのメソッドは同期メソッドです。同期メソッドはワーカースレッドでのみ呼び出される必要があります。このタイプのメソッドは、APIリファレンス内で注釈が付けられており、メソッド上にカーソルを合わせるとコードのヒントが表示されます。コードのヒントには、「このメソッドは MCT で呼び出す必要があります。QueuedTask.Run を使用してください。」と表示されます。

ArcGIS Pro でアドインが読み込まれない

問題

アドインがクライアントマシンに正常にインストールされました。

アドインは以前のリリースでは問題なく動作しました。

アドインのアセンブリキャッシュフォルダを削除した後でも、アドインはProによってロードされなくなります。

原因

ArcGIS Pro アセンブリ参照の少なくとも 1 つでのローカルのコピーが true に設定されています。

解決策

アドインプロジェクト内のすべての ArcGIS Pro アセンブリ参照のプロパティを確認します。ローカルコピーの設定が false に設定されていることを確認してください。デフォルトでは、.NET アセンブリ参照がプロジェクトに追加されるたびに、Visual Studio のデフォルトの動作では、[Copy Local] を true に設定されます (Visual Studio では、このデフォルトの動作を変更することはできません)。ArcGIS Pro アセンブリ参照をアドインプロジェクトに手動で追加する場合は、[Copy Local] を false に設定してください。詳細は ProConcepts Advanced Topics, ArcGIS Pro Assembly references in your project を参照してください。

ボタンコントロールで画像が読み込まれない

アドインで画像コンテンツを含めるためのオプションについては、ProGuide Content and Image Resources, Image Content を参照してください。

アセンブリ名の不一致により、Visual Studio でコンパイル時の警告が表示される

問題

アドイン・プロジェクトをコンパイルすると、Visual Studioで「<AddInAssembly.dll>が見つかりませんでした。config.daml の defaultAssembly 属性の値は、アドインプロジェクトのアセンブリの名前と一致する必要があります。」という警告が表示されます。

原因

ArcGIS Pro アドインの config.daml ファイルは、defaultAssembly 属性を使用してアセンブリの名前を指定します。アセンブリがアドインパッケージ (.esriAddInX ファイル) に存在しない場合、アドインのコンパイル時に Visual Studio で警告が表示されます。

解決策

config.daml ファイルにリストされている defaultAssembly 属性値を見つけます。コンテキストメニューからアドインプロジェクトの [プロパティ] にアクセスします。[アセンブリ名] テキストボックス内の名称が config.daml ファイルの defaultAssembly 属性値と一致していることを確認します。

<?xml version="1.0" encoding="utf-8"?>
<ArcGIS defaultAssembly="ChangedAssemblyName.dll" defaultNamespace="ChangedAssemblyName" xmlns="..." xmlns:xsi="..." xsi:schemaLocation="...">
  <AddInInfo id="...
....

Config.daml の defaultAssembly と defaultNamespace 属性の値は、この例では Visual Studio プロジェクトのプロパティにある、対応するアセンブリ名とデフォルト名前空間名に一致していないことに注意してください。そのため、Config.daml または Visual Studio の値が一致するように変更する必要があります。

名前空間 (ネームスペース) の不一致により、コントロールが動作しなかったり消えたりする

問題

アドインで作成した ArcGIS Pro のリボン上のボタンをクリックすると、ボタンが消えてしまいます。

原因

ボタンのクラス (またはコードビハインド) が ArcGIS Pro アドインフレームワークで見つかりません。これは、config.daml ファイルで宣言されたネームスペースとボタンのクラスファイルのネームスペースが一致しないことが原因である可能性が高いです。

Note: Visual Studio 2022 では、.csproj/.vbproj の名前に基づいてデフォルトのネームスペース名を決定するために、以下のマクロを使用します。 $(MSBuildProjectName.Replace(" ", "_"))

このマクロは、Config.daml の defaultNamespace に加えて、プロジェクトファイルの名前も変更すると、ミスマッチを起こす可能性があります。また、デフォルト名前空間マクロは、プロジェクト名にアンダースコア "_" がある場合、それを削除することに注意してください。このため、プロジェクト名にアンダースコアを使用することは避けてください。

解決策

config.daml ファイルに記載されているdefaultNamespace 属性値を探します。

<?xml version="1.0" encoding="utf-8"?>
<ArcGIS defaultAssembly="ProAppModule1.dll" defaultNamespace="ChangedAssemblyName" xmlns="..." xmlns:xsi="..." xsi:schemaLocation="...">
  <AddInInfo id="...
....

アドインプロジェクトのコンテキストメニューから、プロパティページにアクセスします。Config.daml の defaultNamespace 属性が、Visual Studio プロジェクトのプロパティにある Default Namespace と一致することを確認します。この場合、Config.daml の defaultNamespace は ChangedAssemblyName に設定されていますが、プロジェクトの Default Namespace は ProAppModule1 に設定されていることに注意してください。したがって、この問題を解決するには、Config.daml の値または Visual Studio のプロパティの値が一致するように変更する必要があります。

ボタンクラス (または任意の ArcGIS Pro コントロール) がアドインプロジェクトのフォルダ内、または入れ子になったネームスペース内にある場合は、config.daml ファイルにボタンの className 属性に完全修飾クラス名を入力します。次の例は、"ProAppModule1.Ribbon.ActivateButton" ネームスペース内のボタンクラスを示しています。

  <button id="ProAppModule1_Ribbon_ActivateButton"
caption="ActivateButton" 
        className="ProAppModule1.Ribbon.ActivateButton"...

アドインにより起動時に Pro がクラッシュする

問題

以前の 3.x でリリースされた Pro で動作していたアドインが、Pro をアップグレードするとアプリケーションがクラッシュします。

原因

コーディングの問題 (null 変数、コード内の不正なパスや名前など) ではないと仮定して、Visual Studio IDE で Pro API アセンブリ参照をチェックしてください。Pro のアップグレード後に原因不明のアドインがクラッシュする最も一般的な原因は、"Copy Local" プロパティが "true" に設定された Pro API アセンブリ参照です。デフォルトでは、Visual Studio は、.NET プロジェクトに追加されたアセンブリ参照に対して、Copy Local = Yes を設定します。このデフォルトの動作を変更する方法はありません。Copy Local = true セマンティクスを持つアセンブリは、実行時に Pro アドイン (または構成やプラグイン) のアセンブリキャッシュにコピーされます。コピーされた Pro API アセンブリのバージョンが間違っている場合、アドインがロードされると、Pro も含めクラッシュします。

解決策

Visual Studio で、Pro API アセンブリのプロパティを確認します。Copy Local = Yes の設定を Copy Local = No に変更します。アドインを再度コンパイルして再配置します (既知のフォルダからロードされている場合は、ダブルクリックして xcopy を実行します)。

注: Pro SDK プロジェクトテンプレートは、プロジェクト (.csproj または .vbproj) が作成されたときに、Pro API 参照が (テンプレートによって) 自動的に追加されるように、Copy Local = false になっています。Copy Local = true は、プロジェクトが作成された後のある時点で "手動で" 追加した参照に対してのみ発生します。

Copy Local=No が機能しない

問題

Copy Local=No アセンブリプロパティを設定しても、効果はありません。アセンブリはローカルにコピーされたままです(アドインと一緒にデプロイされます)。

原因

MSBuildは、実際には「False」タグを使って、コピーローカルの動作を制御しています。MSBuild project itemsを参照してください。

解決策

4/25/22 執筆時点では、Visual Studio 2022 v17.1.6 以下では、現在、.csproj/.vbprj に <Private>False | True</Private> タグを追加してローカルコピー動作を制御することはできないようです。Visual Studio 2022 のローカルコピー動作に問題がある場合、.csproj/.vbprj の関連するアセンブリ参照に <Private> タグを追加してみてください。

<!-- Before -->
 <Reference Include="SomeCustom3rdparty">
      <HintPath>C:\Data\bin\SomeCustom3rdparty.dll</HintPath>
      <CopyLocal>False</CopyLocal>
 </Reference>

<!-- After -->
<Reference Include="SomeCustom3rdparty">
      <HintPath>C:\Data\bin\SomeCustom3rdparty.dll</HintPath>
      <CopyLocal>False</CopyLocal>
      <Private>False</Private>
 </Reference>