例外処理

【C#】DllNotFoundExceptionの原因と対処法をわかりやすく解説

2025-04-30更新日: 2025-04-30

C#でDllNotFoundExceptionが出るのは、ランタイムが指定DLLを検出できないためです。

実行ファイルと同じフォルダー、またはPATHにDLLとその依存DLLを置き、x86とx64をそろえ、DllImportで正しい名前を指定すると解消しやすいです。

目次から探す

DllNotFoundExceptionとは
- 発生タイミング
- 例外メッセージの読み解き方
よくある原因
トラブルシューティングフロー
解決策の具体例
クロスプラットフォーム注意点
自動テストでの予防策
まとめ

DllNotFoundExceptionとは

C#で開発をしていると、外部のDLL(ダイナミックリンクライブラリ)を呼び出す際にDllNotFoundExceptionという例外が発生することがあります。

この例外は、指定したDLLファイルが見つからない場合にスローされるもので、主にP/Invoke(Platform Invocation Services)を使ってアンマネージドコードのDLLを呼び出すときに起こります。

この例外が発生すると、プログラムはその時点で停止し、DLLが見つからないために必要な機能を実行できなくなります。

原因を正しく理解し、適切に対処することが重要です。

発生タイミング

DllNotFoundExceptionは、C#のコード内でDllImport属性を使って外部DLLの関数を呼び出そうとしたときに、実行時に指定したDLLが見つからない場合に発生します。

具体的には、以下のような状況で起こります。

P/InvokeでDLLを呼び出すとき

例えば、Windows APIや独自のネイティブDLLを呼び出すために、[DllImport("example.dll")]のように宣言している場合です。

実行時にexample.dllが見つからなければ例外が発生します。

マネージドコードからアンマネージドDLLをロードするとき

.NETのマネージドコードは直接DLLをロードしませんが、P/InvokeやNativeLibraryクラスを使ってアンマネージドDLLをロードする際に、DLLが存在しないと例外が発生します。

依存DLLが見つからない場合

呼び出そうとしているDLL自体は存在しても、そのDLLが依存している別のDLLが見つからない場合も、結果的にDllNotFoundExceptionが発生することがあります。

プラットフォームの不一致によるロード失敗

例えば、64ビットアプリケーションが32ビットDLLをロードしようとした場合や、その逆の場合もDLLが正しくロードできずに例外が発生します。

以下は、P/InvokeでDLLを呼び出す簡単な例です。

この例ではuser32.dllのMessageBox関数を呼び出していますが、もしuser32.dllが見つからなければDllNotFoundExceptionが発生します。

using System;
using System.Runtime.InteropServices;
class Program
{
    // user32.dllのMessageBox関数を呼び出す宣言
    [DllImport("user32.dll", CharSet = CharSet.Unicode)]
    public static extern int MessageBox(IntPtr hWnd, string text, string caption, uint type);
    static void Main()
    {
        // メッセージボックスを表示
        MessageBox(IntPtr.Zero, "こんにちは、世界！", "サンプル", 0);
    }
}

このコードは通常問題なく動作しますが、もしuser32.dllが存在しない環境で実行するとDllNotFoundExceptionが発生します。

例外メッセージの読み解き方

DllNotFoundExceptionが発生すると、例外メッセージには通常、見つからなかったDLLの名前が含まれています。

これを正しく読み解くことで、どのDLLが原因で問題が起きているのかを特定しやすくなります。

例外メッセージの例：

System.DllNotFoundException: Unable to load DLL 'example.dll': The specified module could not be found.

このメッセージからわかることは、

DLL名

'example.dll'が見つからなかったことが明示されています。

ここで指定されている名前が、DllImport属性で指定したDLL名と一致します。

原因の概要

「The specified module could not be found.」は、指定されたモジュール(DLL)が見つからないことを意味しています。

スタックトレース

例外のスタックトレースを確認すると、どのコード行で例外が発生したかがわかります。

これにより、どのDLL呼び出しが失敗したのかを特定できます。

例外メッセージを読み解く際のポイントは以下の通りです。

ポイント	説明
DLL名の確認	例外メッセージに表示されるDLL名が、実際に存在するか確認します。
パスの確認	DLLが実行ファイルのあるフォルダやPATH環境変数に含まれるフォルダにあるかをチェックします。
依存DLLの確認	見つからないDLLが依存している別のDLLが欠けていないか調べます。
プラットフォームの整合性	アプリケーションとDLLのビット数(x86/x64)が一致しているか確認します。

また、Visual Studioのデバッグ時には、例外が発生した行でブレークし、ローカル変数や呼び出し元の情報を確認できます。

これにより、どのDLL呼び出しが原因かを特定しやすくなります。

さらに、DllNotFoundExceptionは単にDLLが存在しないだけでなく、DLLの依存関係が満たされていない場合にも発生するため、単純にDLLファイルがあるかどうかだけでなく、依存関係のチェックも重要です。

以上のように、DllNotFoundExceptionは外部DLLが見つからないときに発生する例外であり、例外メッセージを正しく読み解くことで原因の特定がしやすくなります。

次のステップでは、具体的な原因とその対処法について詳しく解説していきます。

よくある原因

DLLが物理的に存在しない

ディレクトリ配置ミス

DLLが物理的に存在しない最も単純な原因は、DLLファイルが正しい場所に配置されていないことです。

C#のP/Invokeでは、実行時に指定したDLLが実行ファイルのあるディレクトリやシステムの検索パスに存在している必要があります。

たとえば、[DllImport("example.dll")]と指定している場合、example.dllは実行ファイルと同じフォルダか、PATHに含まれるフォルダに置かなければなりません。

よくあるミスとしては、ビルド後の出力フォルダbin\Debugやbin\ReleaseにDLLをコピーし忘れたり、プロジェクトのルートフォルダに置いてしまい実行時に見つからないケースがあります。

Visual Studioのプロジェクト設定で「ビルドアクション」や「出力ディレクトリにコピー」の設定を確認し、DLLが正しくコピーされるようにしましょう。

ファイル名のスペルミス

DLL名のスペルミスもよくある原因です。

DllImport属性で指定するDLL名は大文字・小文字を区別しないWindowsでも、拡張子の有無やスペルミスがあるとロードに失敗します。

例えば、example.dllをexmaple.dllやexample.DLLと誤って指定すると、DllNotFoundExceptionが発生します。

また、拡張子を省略して[DllImport("example")]と書くこともありますが、環境によっては正しく解決されないことがあるため、明示的に.dllを付けることをおすすめします。

PATH環境変数の不足

WindowsのシステムPATH

Windowsでは、DLLを検索する際にシステムのPATH環境変数に登録されているフォルダも参照されます。

もしDLLが実行ファイルのフォルダにない場合、PATHにDLLのあるフォルダを追加しておく必要があります。

PATHに含まれていないフォルダにDLLがあると、実行時に見つからずDllNotFoundExceptionが発生します。

PATHの確認はコマンドプロンプトでecho %PATH%を実行するか、システムの環境変数設定画面から行えます。

アプリ固有の追加パス

アプリケーション側でSetDllDirectory関数を使い、DLLの検索パスを追加する方法もあります。

これにより、PATHを変更せずに特定のフォルダをDLL検索パスに含められます。

using System;
using System.Runtime.InteropServices;
class Program
{
    [DllImport("kernel32.dll", SetLastError = true)]
    static extern bool SetDllDirectory(string lpPathName);
    static void Main()
    {
        // DLLがあるフォルダを追加
        SetDllDirectory(@"C:\MyDllFolder");
        // ここでDLLを呼び出す処理を行う
    }
}

この方法は、環境変数を変更できない場合や、特定のDLLだけを読み込みたい場合に有効です。

依存DLLの欠落

チェーン依存の落とし穴

呼び出そうとしているDLL自体は存在しても、そのDLLが依存している別のDLLが欠けている場合もDllNotFoundExceptionが発生します。

これを「チェーン依存の落とし穴」と呼ぶことがあります。

たとえば、example.dllがdependency.dllに依存している場合、example.dllは存在してもdependency.dllが見つからなければロードに失敗します。

WindowsのDependency Walkerやdumpbin /DEPENDENTSコマンドを使って依存関係を調べ、すべての依存DLLが存在するか確認しましょう。

ネイティブライブラリのバージョン不一致

依存DLLのバージョンが異なると、ロードに失敗することがあります。

特にネイティブライブラリはバージョン間でAPIやABIが変わることがあり、古いバージョンや新しいバージョンが混在すると問題が起きやすいです。

バージョン管理が難しい場合は、アプリケーションごとに依存DLLを同梱し、バージョンの衝突を避ける方法が有効です。

アーキテクチャ不一致(x86 / x64 / ARM)

AnyCPUビルドの落とし穴

.NETアプリケーションをAnyCPUでビルドすると、実行環境に応じて32ビットまたは64ビットで動作します。

しかし、呼び出すDLLが特定のアーキテクチャ用にビルドされている場合、アーキテクチャの不一致でロードに失敗します。

例えば、64ビット環境でAnyCPUビルドのアプリが64ビットで動作しているときに、32ビットDLLを呼び出そうとするとDllNotFoundExceptionが発生します。

逆も同様です。

この問題を避けるには、アプリケーションのビルド設定をDLLのアーキテクチャに合わせてx86またはx64に固定するか、両方のDLLを用意して実行時に切り替える方法があります。

Wow64での読み込み失敗

WindowsのWow64(Windows 32-bit on Windows 64-bit)環境では、32ビットアプリケーションが64ビットDLLをロードしようとすると失敗します。

逆に64ビットアプリが32ビットDLLをロードすることもできません。

このため、アプリケーションとDLLのビット数を必ず合わせる必要があります。

Visual Studioのプロジェクト設定でプラットフォームターゲットを確認し、DLLのビット数と一致させましょう。

OSセキュリティ制限

アンブロック設定の必要性

インターネットからダウンロードしたDLLは、Windowsのセキュリティ機能により「ブロック」されていることがあります。

この状態だと、DLLのロード時に失敗することがあり、DllNotFoundExceptionが発生する場合があります。

エクスプローラーでDLLのプロパティを開き、「ブロックの解除」ボタンがあればクリックしてアンブロックしてください。

PowerShellではUnblock-Fileコマンドレットを使うこともできます。

UACとファイル許可

ユーザーアカウント制御(UAC)やファイルシステムのアクセス権限が原因で、DLLにアクセスできない場合もあります。

特にProgram Files配下やシステムフォルダにDLLを配置している場合、読み取り権限が不足しているとロードに失敗します。

DLLファイルのプロパティでアクセス権を確認し、必要に応じて読み取り権限を付与してください。

管理者権限でアプリケーションを実行することも検討しましょう。

DLLの署名・バージョンの不整合

同名別バージョンの競合

同じ名前のDLLが複数のバージョンで存在し、異なる場所に配置されていると、どのDLLがロードされるか分からず競合が起きることがあります。

これにより、意図しないバージョンがロードされてDllNotFoundExceptionや他の例外が発生することがあります。

この問題を避けるには、DLLの配置場所を明確にし、バージョン管理を徹底することが重要です。

SetDllDirectoryやLoadLibraryのフルパス指定で明示的にDLLを指定する方法もあります。

強名付きアセンブリの影響

マネージドDLLの場合、強名付きアセンブリ(Strong-Named Assembly)として署名されていると、バージョンや公開キーが異なるDLLはロードされません。

アンマネージドDLLのロード時に影響することは少ないですが、マネージドラッパーを介している場合は注意が必要です。

強名付きアセンブリのバージョン不整合はFileLoadExceptionなど別の例外を引き起こすことが多いですが、間接的にDllNotFoundExceptionの原因になることもあります。

バージョンの整合性を保つことが重要です。

トラブルシューティングフロー

例外発生箇所の特定

スタックトレースの活用

DllNotFoundExceptionが発生した場合、まずは例外のスタックトレースを確認して、どのコード行で例外が発生しているかを特定しましょう。

スタックトレースには、例外がスローされたメソッドや呼び出し元の情報が含まれているため、問題のDLL呼び出し箇所を正確に把握できます。

Visual Studioのデバッガーを使っている場合は、例外発生時に自動的にブレークし、スタックトレースを表示します。

スタックトレースの中でDllImport属性を使ったメソッド呼び出しがある箇所を探し、そのDLL名を確認してください。

以下は例外のスタックトレース例です。

System.DllNotFoundException: Unable to load DLL 'example.dll': The specified module could not be found.
   at Namespace.ClassName.MethodName()
   at Namespace.Program.Main()

この例ではexample.dllが見つからないことがわかり、ClassName.MethodNameメソッド内で呼び出しが失敗しています。

これにより、どのDLLが問題かを特定できます。

Dependency Walkerで依存関係を確認

実行手順

Dependency WalkerはWindows向けの無料ツールで、DLLや実行ファイルの依存関係を解析できます。

呼び出そうとしているDLLが依存している他のDLLがすべて揃っているかを調べるのに便利です。

公式サイトや信頼できる配布元からDependency Walkerをダウンロードしてインストールします。
Dependency Walkerを起動し、メニューの「File」→「Open」で問題のDLLファイル(例：example.dll)を選択します。
解析結果がツリー形式で表示され、依存しているDLLが一覧で確認できます。赤いアイコンや黄色の警告があるDLLは見つからないか問題があることを示しています。
見つからない依存DLLがあれば、そのDLLを適切な場所に配置するか、環境変数PATHに追加してください。
依存関係の問題が解決したら、再度アプリケーションを実行して例外が解消されているか確認します。

Dependency Walkerは古いツールですが、依存関係の可視化に非常に役立ちます。

特にネイティブDLLの依存関係を調べる際に重宝します。

Process Monitorでロード失敗を追跡

Process MonitorはMicrosoftが提供する強力なシステム監視ツールで、ファイルアクセスやレジストリ操作などをリアルタイムで監視できます。

DLLのロード失敗原因を調べる際に、どのパスを探しているか、アクセスが拒否されていないかを詳細に追跡できます。

使い方のポイントは以下の通りです。

Process Monitorを管理者権限で起動します。
フィルターを設定し、対象のアプリケーションのプロセス名で絞り込みます。
DLLのロードに関係するファイルアクセスイベントを監視します。特にNAME NOT FOUNDやACCESS DENIEDの結果があるイベントに注目してください。
どのパスでDLLの検索が失敗しているかがわかるため、DLLの配置場所やアクセス権の問題を特定できます。
問題を修正した後、再度監視して正常にDLLが読み込まれているか確認します。

Process Monitorは情報量が多いため、フィルター設定を工夫して必要な情報だけを抽出することが重要です。

Visual Studio診断ツールの活用

Visual Studioには、デバッグ時にDLLのロード状況を確認できる診断ツールが備わっています。

特に「モジュール」ウィンドウを使うと、現在ロードされているDLLの一覧やパスを確認できます。

手順は以下の通りです。

Visual Studioでプロジェクトをデバッグモードで起動します。
メニューの「デバッグ」→「ウィンドウ」→「モジュール」を開きます。
モジュールウィンドウに、ロード済みのDLLが一覧表示されます。ここで目的のDLLがロードされているか、パスが正しいかを確認します。
DLLがリストにない場合は、ロードに失敗している可能性が高いです。
また、例外が発生した時点でコールスタックやローカル変数を確認し、問題の箇所を特定します。

Visual Studioの診断ツールは、コードの実行状況を詳細に把握できるため、DllNotFoundExceptionの原因調査に役立ちます。

dotnet –infoでランタイムを確認

.NET Coreや.NET 5以降の環境では、dotnet --infoコマンドを使ってインストールされているランタイムやSDKの情報を確認できます。

DLLのロード失敗がランタイムの不整合に起因している場合、この情報が手がかりになります。

コマンドプロンプトやPowerShellで以下を実行します。

dotnet --info

表示される情報には、インストールされている.NETのバージョン、ランタイムのパス、環境変数の設定などが含まれます。

特に、ターゲットとしているランタイムが正しくインストールされているか、複数バージョンが混在していないかを確認してください。

ランタイムの不整合があると、ネイティブDLLのロードに失敗することがあるため、環境を整えることが重要です。

必要に応じてランタイムの再インストールやバージョンの統一を行いましょう。

解決策の具体例

DLLを実行ファイルと同じフォルダに配置

最も基本的で効果的な解決策は、呼び出すDLLを実行ファイル(EXE)が存在するフォルダに配置することです。

WindowsのDLL検索パスの優先順位では、実行ファイルのフォルダが最初に検索されるため、ここにDLLを置くことで確実に見つけてもらえます。

Visual StudioのプロジェクトでDLLをビルド出力フォルダに自動コピーするには、プロジェクトにDLLファイルを追加し、プロパティの「出力ディレクトリにコピー」を「常にコピー」または「新しい場合にコピー」に設定します。

// 例: 実行ファイルと同じフォルダにexample.dllがある場合のDllImport
[DllImport("example.dll")]
public static extern void SampleFunction();

この方法は特別な設定が不要で、最もトラブルが少ないため推奨されます。

DllImport属性のExactSpellingとCallingConvention

DllImport属性には、DLLの関数名の正確な指定や呼び出し規約を制御するオプションがあります。

これらを正しく設定しないと、DLLは見つかっても関数呼び出しでエラーになることがあります。

ExactSpelling

デフォルトでは、WindowsのANSI/Unicodeの違いにより関数名にAやWが自動的に付加されることがあります。

ExactSpelling = trueを指定すると、指定した名前をそのまま使います。

CallingConvention

DLLの関数がどの呼び出し規約(StdCallやCdeclなど)で実装されているかを指定します。

規約が合わないと呼び出し時にスタック破壊や例外が発生します。

[DllImport("example.dll", ExactSpelling = true, CallingConvention = CallingConvention.StdCall)]
public static extern int Add(int a, int b);

これらの設定はDllNotFoundExceptionの直接的な原因ではありませんが、DLLの呼び出し失敗を防ぐために重要です。

SetDllDirectoryでカスタムパスを追加

DLLが実行ファイルのフォルダ以外にある場合、SetDllDirectory関数を使ってDLL検索パスにカスタムフォルダを追加できます。

これにより、環境変数PATHを変更せずに特定のフォルダからDLLを読み込めます。

using System;
using System.Runtime.InteropServices;
class Program
{
    [DllImport("kernel32.dll", SetLastError = true)]
    static extern bool SetDllDirectory(string lpPathName);
    [DllImport("example.dll")]
    public static extern void SampleFunction();
    static void Main()
    {
        // DLLがあるフォルダを追加
        if (!SetDllDirectory(@"C:\MyDllFolder"))
        {
            Console.WriteLine("DLLディレクトリの追加に失敗しました。");
            return;
        }
        // DLLの関数を呼び出す
        SampleFunction();
    }
}

SetDllDirectoryはプロセス単位で有効なので、アプリケーション起動時に一度呼び出せば、その後のDLLロードに反映されます。

NuGetパッケージの利用でネイティブ依存を管理

ネイティブDLLの依存関係を手動で管理するのは手間がかかり、ミスも起きやすいです。

そこで、NuGetパッケージを利用してネイティブDLLを管理する方法があります。

多くのライブラリは、プラットフォームごとに適切なネイティブDLLを含むNuGetパッケージを提供しています。

これをプロジェクトに追加すると、ビルド時に自動的に正しいDLLが出力フォルダにコピーされます。

例えば、SQLitePCLRawやOpenCvSharpなどのパッケージは、x86/x64やWindows/Linuxなど複数プラットフォームのDLLを含み、ビルド時に適切なものを選択します。

NuGetを使うメリットは以下の通りです。

DLLの配置ミスを防げる
バージョン管理が容易
クロスプラットフォーム対応がしやすい

x86/x64向けにプロジェクトを分ける

DLLのアーキテクチャ(32ビット/64ビット)に合わせて、プロジェクトのビルド設定を分けることも重要です。

AnyCPUビルドでは、実行環境に応じて動作モードが変わるため、DLLのビット数と合わない場合にDllNotFoundExceptionが発生します。

Visual Studioでは、x86とx64のビルド構成を作成し、それぞれに対応したDLLを用意してビルド・実行します。

MSBuild条件付きコピー

複数のDLLをビルド出力フォルダに自動コピーするには、MSBuildの条件付きコピーを使うと便利です。

csprojファイルに以下のように記述します。

<ItemGroup>
  <None Include="runtimes\x86\native\example.dll">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <Condition>'$(Platform)' == 'x86'</Condition>
  </None>
  <None Include="runtimes\x64\native\example.dll">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <Condition>'$(Platform)' == 'x64'</Condition>
  </None>
</ItemGroup>

これにより、ビルド時にプラットフォームに応じたDLLが自動的にコピーされ、実行時の不整合を防げます。

MSIX/ClickOnce配布時の注意点

MSIXやClickOnceなどの配布方式を使う場合、ネイティブDLLの配置やアクセス権に注意が必要です。

これらの配布方式はサンドボックス環境で動作するため、DLLの配置場所が制限されることがあります。

DLLの配置場所

配布パッケージ内の適切なフォルダにDLLを含める必要があります。

通常は実行ファイルと同じフォルダか、アプリケーションのローカルフォルダに配置します。

アクセス権限

サンドボックスの制限により、DLLのロードに失敗することがあります。

必要に応じてマニフェストで権限を設定してください。

パスの指定

DllImportで相対パスを使う場合、配布環境でのパス解決に注意が必要です。

フルパス指定やSetDllDirectoryの利用を検討しましょう。

これらの点を考慮しないと、配布後にDllNotFoundExceptionが発生しやすくなります。

配布方式のドキュメントを参照し、ネイティブDLLの取り扱いルールを守ることが重要です。

クロスプラットフォーム注意点

WindowsとLinuxでのパスの違い

C#のP/Invokeを使ってネイティブDLLを呼び出す場合、WindowsとLinuxではDLLのファイル名やパスの指定方法に違いがあります。

これを理解しておかないと、クロスプラットフォーム環境でDllNotFoundExceptionが発生しやすくなります。

ファイル名の違い

Windows

ネイティブライブラリは通常.dll拡張子を持ちます。

例：example.dll

Linux

ネイティブライブラリは.so(Shared Object)拡張子を持ち、名前の先頭にlibが付くことが多いです。

例：libexample.so

P/Invokeでの指定例

WindowsとLinuxで同じ関数を呼び出す場合、DllImportのdllNameを環境に応じて切り替える必要があります。

例えば、以下のように条件コンパイルを使う方法があります。

using System;
using System.Runtime.InteropServices;
class NativeMethods
{
#if WINDOWS
    [DllImport("example.dll")]
    public static extern void SampleFunction();
#elif LINUX
    [DllImport("libexample.so")]
    public static extern void SampleFunction();
#endif
}

.NET 5以降では、NativeLibraryクラスを使って動的にライブラリをロードする方法もあります。

パスの区切り文字

Windows

パス区切り文字はバックスラッシュ\です。

例：C:\libs\example.dll

Linux

スラッシュ/が使われます。

例：/usr/lib/libexample.so

パスをハードコーディングする場合は、環境に応じて区切り文字を切り替えるか、Path.CombineなどのAPIを使うことが推奨されます。

runtimesフォルダの使い方

.NET Coreや.NET 5以降のプロジェクトでは、クロスプラットフォーム対応のためにruntimesフォルダを使ってネイティブライブラリを管理します。

runtimesフォルダは、プラットフォームやアーキテクチャごとにネイティブDLLを分けて配置できる特別なフォルダ構造です。

フォルダ構造例

runtimes/
  win-x64/
    native/
      example.dll
  linux-x64/
    native/
      libexample.so
  osx-x64/
    native/
      libexample.dylib

このように、runtimes配下にプラットフォーム名(RID: Runtime Identifier)ごとのフォルダを作り、その中にnativeフォルダを置いてネイティブライブラリを配置します。

動作の仕組み

ビルドや実行時に、.NETのランタイムが実行環境に合ったruntimesフォルダ内のネイティブライブラリを自動的に選択し、適切な場所にコピーまたはロードします。

これにより、単一のNuGetパッケージやプロジェクトで複数プラットフォームをサポートできます。

NuGetパッケージでの利用

多くのクロスプラットフォーム対応ライブラリは、runtimesフォルダを使ってネイティブDLLを管理しています。

プロジェクトにパッケージを追加すると、ビルド時に適切なDLLが出力フォルダに配置されます。

P/Invokeとlibdlの関係

LinuxやmacOSなどのUnix系OSでは、ネイティブライブラリの動的ロードにlibdlという共有ライブラリが使われています。

libdlはdlopenやdlsymといった関数を提供し、実行時にライブラリをロードして関数ポインタを取得する仕組みです。

.NETのP/Invokeとlibdl

C#のP/Invokeは、WindowsではLoadLibraryやGetProcAddressを内部的に使ってDLLをロードしますが、Linux/macOSではdlopenやdlsymを使います。

これらはlibdlに含まれているため、libdlがシステムに存在しないとネイティブライブラリのロードに失敗します。

libdlのインストール

ほとんどのLinuxディストリビューションではlibdlは標準でインストールされていますが、最小構成の環境やコンテナでは不足していることがあります。

libdlがないとDllNotFoundExceptionが発生することがあるため、以下のようにパッケージをインストールしてください。

Debian/Ubuntu系

sudo apt-get install libc6-dev

RedHat/CentOS系

sudo yum install glibc-devel

P/Invokeでのlibdl利用例

自分で動的にライブラリをロードしたい場合、libdlの関数をP/Invokeで呼び出すことも可能です。

using System;
using System.Runtime.InteropServices;
class LibDl
{
    [DllImport("libdl.so")]
    public static extern IntPtr dlopen(string fileName, int flags);
    [DllImport("libdl.so")]
    public static extern IntPtr dlsym(IntPtr handle, string symbol);
    [DllImport("libdl.so")]
    public static extern int dlclose(IntPtr handle);
    public const int RTLD_NOW = 2;
}
class Program
{
    static void Main()
    {
        IntPtr handle = LibDl.dlopen("libexample.so", LibDl.RTLD_NOW);
        if (handle == IntPtr.Zero)
        {
            Console.WriteLine("ライブラリのロードに失敗しました。");
            return;
        }
        // ここでdlsymを使って関数ポインタを取得し、呼び出すことが可能
        LibDl.dlclose(handle);
    }
}

このように、Linux/macOSではlibdlがネイティブライブラリのロードの基盤となっているため、環境構築時にlibdlが正しく存在しているか確認することが重要です。

自動テストでの予防策

CI環境でのDLL配置チェック

継続的インテグレーション(CI)環境でのビルドやテスト実行時に、DLLの配置ミスや依存関係の欠落を早期に検出することが重要です。

CI環境は開発者のローカル環境と異なるため、DLLが正しく配置されていないとDllNotFoundExceptionが発生しやすくなります。

配置チェックのポイント

ビルド出力フォルダの確認

ビルド後の出力ディレクトリに必要なDLLがすべて存在するかをスクリプトでチェックします。

例えば、PowerShellやBashでファイルの存在を確認し、欠落があればビルド失敗として扱います。

依存DLLの存在確認

依存関係のあるDLLも含めてすべて揃っているかを確認します。

dumpbinやDependency Walkerのコマンドライン版を使い、依存DLLのリストを取得してチェックする方法もあります。

環境変数の設定確認

CI環境でPATHやその他の環境変数が正しく設定されているかを検証します。

環境変数の設定ミスでDLLが見つからないケースも多いため、スクリプトで環境変数の内容をログに出力するのも有効です。

サンプルPowerShellスクリプト例

$requiredDlls = @("example.dll", "dependency.dll")
$outputDir = "bin\Release\net5.0"
foreach ($dll in $requiredDlls) {
    $path = Join-Path $outputDir $dll
    if (-Not (Test-Path $path)) {
        Write-Error "DLLが見つかりません: $dll"
        exit 1
    }
}
Write-Host "すべてのDLLが正しく配置されています。"

このようなチェックをCIパイプラインに組み込むことで、DLLの配置ミスを早期に発見し、問題の拡大を防げます。

Unit Testでのロード検証

Unit TestでDLLのロード検証を行うことで、実行時にDllNotFoundExceptionが発生しないかを自動的に確認できます。

特に外部DLLを呼び出すラッパーやラッパークラスがある場合は、テストでロードの成功を保証することが重要です。

ロード検証の方法

簡単な関数呼び出しテスト

DLL内の簡単な関数を呼び出し、例外が発生しないことを確認します。

例えば、DLLにあるバージョン取得関数や初期化関数を呼び出すテストを作成します。

例外キャッチによる判定

テスト内でDllNotFoundExceptionをキャッチし、発生した場合はテスト失敗とします。

C#のUnit Testサンプル

using System;
using System.Runtime.InteropServices;
using Xunit;
public class DllLoadTests
{
    [DllImport("example.dll")]
    private static extern int GetVersion();
    [Fact]
    public void TestDllLoad()
    {
        try
        {
            int version = GetVersion();
            Assert.True(version > 0, "バージョン番号が正しく取得できました。");
        }
        catch (DllNotFoundException ex)
        {
            Assert.False(true, $"DLLのロードに失敗しました: {ex.Message}");
        }
    }
}

このテストは、example.dllが正しくロードでき、GetVersion関数が呼び出せるかを検証します。

CI環境やローカル環境で自動的に実行することで、DLLの配置や依存関係の問題を早期に検出できます。

注意点

テスト環境にDLLが存在しないとテストが失敗するため、テスト実行前にDLLの配置を確実に行う必要があります
複数プラットフォーム対応の場合は、プラットフォームごとにテストを分けるか、条件付きでテストを実行する工夫が必要です

これらの自動テストを導入することで、DllNotFoundExceptionの発生を未然に防ぎ、安定したアプリケーション開発を支援できます。

.NET 5以降でNativeLibrary APIは使える？

はい、.NET 5以降ではNativeLibraryクラスが利用可能で、ネイティブライブラリの動的ロードやアンロードをより柔軟に行えます。

NativeLibraryはSystem.Runtime.InteropServices名前空間にあり、従来のDllImport属性に加えて、実行時にDLLのパスを指定してロードしたり、関数ポインタを取得したりすることができます。

例えば、以下のようにNativeLibrary.LoadでDLLをロードし、NativeLibrary.GetExportで関数ポインタを取得して呼び出すことが可能です。

using System;
using System.Runtime.InteropServices;
class Program
{
    delegate int AddDelegate(int a, int b);
    static void Main()
    {
        IntPtr libHandle = NativeLibrary.Load("example.dll");
        IntPtr funcPtr = NativeLibrary.GetExport(libHandle, "Add");
        var add = Marshal.GetDelegateForFunctionPointer<AddDelegate>(funcPtr);
        int result = add(3, 5);
        Console.WriteLine($"Add関数の結果: {result}");
        NativeLibrary.Free(libHandle);
    }
}