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, https://www.esri.com  
Date:          04/20/2026  
ArcGIS Pro:    3.7  
Visual Studio: 2026  

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

• 3.3 - 3.6 アドインが ArcGIS Pro 3.7 でコンパイルされない
• 3.7 でコンパイルすると "The specified RuntimeIdentifier win10-x64 is not recognized" エラーが発生する
• NuGet パッケージを 3.7 に変更すると "NU1202 Package Esri.ArcGISPro.Extensions30 is not compatible" エラーが表示される
• 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

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

Error	CS1705
Assembly 'ArcGIS.Desktop.Framework' with identity 'ArcGIS.Desktop.Framework, Version=13.3.7.0, Culture=neutral, 
   PublicKeyToken=8fc3cc631e44ad86' uses 'System.Runtime, Version=10.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 10 に変更します。3.7 で ArcGIS Pro は .NET 10.0 に移行しました。詳しくは ProGuide NET 10 Upgrade をご参照ください。

.NET 10 では、.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 10 Upgrade をご参照ください。

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

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

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

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

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 をご参照ください。

.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 をご参照ください。

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 をご参照ください。

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

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

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

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

• 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 ファイルを含む) が削除され、コンパイル後に再作成されます。

読み込もうとしているアドインの、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 に移行する必要があります。

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

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

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

• RegisterAddin.exe がアドインを正常に登録できたことを再確認してください。RegisterAddin.exe は、コンパイル/ビルドごとにアドインを登録します。登録のステータス (成功/失敗) が Visual Studio のウィンドウに表示されます。ステータス メッセージが表示されない場合は、Visual Studio の[オプション]でビルドの詳細設定を確認してください。[ツール] -> [オプション] -> [プロジェクトとソリューション] -> [ビルドと実行] -> [MSBuild プロジェクト ビルド出力の詳細] に移動します。「通常」以上に設定されていることを確認してください。

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 エラーが発生する。

アドイン内の特定のオブジェクトの 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 を使用してください。」と表示されます。

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

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

• アドインのアセンブリキャッシュフォルダを削除した後でも、アドインは 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で 「<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"...

以前の 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 アセンブリ プロパティを設定しても、効果はありません。アセンブリはローカルにコピーされたままです(アドインと一緒にデプロイされます)。

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>