How to build and debug external DLLs

yoyo · December 7, 2012, 11:15pm

We all throw dozens or hundreds of scripts into our Assets folder and let Unity build and load them. Usually this works well, but there are a number of reasons for wanting to compile at least some of your code into a DLL. This post outlines a method for building code with Visual Studio and still being able to debug it with MonoDevelop.

For context, I’m using Windows 7 64-bit, Visual C# 2010 Express, Unity 3.5.6 and MonoDevelop 2.8.2 (shipped with Unity 3.5.6). The information should apply to other versions and possibly even to Mac development, but I haven’t tested it.

The basic approach is:

create a .csproj file that uses wildcards to find all source code
add this C# project to a Visual Studio solution
use an MSBuild post-build target to convert Visual Studio’s PDB symbols to Mono’s MDB format
debug with MonoDevelop from Unity, as normal
source code should -not- be in the Assets folder, but the generated DLL should be

Here’s a handmade .csproj file that demonstrates how this works:

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

  <!-- Common Properties -->
  <PropertyGroup>
    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
    <ProductVersion>8.0.30703</ProductVersion>
    <SchemaVersion>2.0</SchemaVersion>
    <ProjectGuid>{61A89EEC-36B9-49ED-8431-D6A7DBDD9EA7}</ProjectGuid>
    <OutputType>Library</OutputType>
    <RootNamespace>UnityDLLExample</RootNamespace>
    <AssemblyName>UnityDLLExample</AssemblyName>
    <TargetFrameworkVersion>v3.5</TargetFrameworkVersion>
    <TargetFrameworkProfile>
    </TargetFrameworkProfile>
    <FileAlignment>512</FileAlignment>
    
    <!-- Look up Unity install folder, and set the ReferencePath for locating managed assembly references. -->
    <UnityInstallFolder>$([System.IO.Path]::GetDirectoryName($(registry:HKEY_CURRENT_USER\Software\Unity Technologies\Unity Editor 3.x\Location)))</UnityInstallFolder>
    <ReferencePath>$(UnityInstallFolder)\Data\Managed</ReferencePath>
    <MonoMdbGenerator>$(UnityInstallFolder)\Data\MonoBleedingEdge\lib\mono\4.0\pdb2mdb.exe</MonoMdbGenerator>
    
  </PropertyGroup>
  
  <!-- Debug Properties -->
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <PlatformTarget>AnyCPU</PlatformTarget>
    <DebugSymbols>true</DebugSymbols>
    <DebugType>full</DebugType>
    <Optimize>false</Optimize>
    <OutputPath>Assets\Plugins</OutputPath>
    <DefineConstants>DEBUG;UNITY_3_5</DefineConstants>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>
  
  <!-- Release Properties -->
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <PlatformTarget>AnyCPU</PlatformTarget>
    <DebugType>pdbonly</DebugType>
    <Optimize>true</Optimize>
    <OutputPath>Assets\Plugins</OutputPath>
    <DefineConstants>UNITY_3_5</DefineConstants>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>
  <PropertyGroup>
    <StartupObject />
  </PropertyGroup>
  
  <!-- Microsoft standard stuff. -->
  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
  
  <!-- Find all source -->
  <ItemGroup>
    <Compile Include="scripts\**\*.cs" />
  </ItemGroup>
  
  <!-- References -->
  <ItemGroup>
    <Reference Include="System" />
    <Reference Include="UnityEngine">
      <Private>False</Private>
    </Reference>
  </ItemGroup>
  
  <!-- Use AfterUnityBuild from Blackbird.CSharp.targets. -->
  <Target Name="AfterBuild">
    <CallTarget Targets="GenerateMonoSymbols" Condition=" Exists('$(OutputPath)\$(AssemblyName).pdb') " />
  </Target>

  <Target Name="GenerateMonoSymbols">
    <Message Text="$(ProjectName) -> $(TargetPath).mdb" Importance="High" />
    <Exec Command=""$(MonoMdbGenerator)" $(AssemblyName).dll" WorkingDirectory="$(MSBuildProjectDirectory)\$(OutputPath)" />
  </Target>

  </Project>

To use this build file, save it as “UnityDLLExample.csproj” in a project folder with the following layout:

-project/
-----UnityDLLExample.csproj (from this post)
-----UnityDLLExample.sln (create with Visual Studio)
-----scripts/
---------SomeScript.cs (put your source code in here, use sub-folders if you like)
-----Assets/ (Unity assets folder)
---------Plugins/ (DLL and MDB files go here)

Notes:

MonoDevelop doesn’t support the Include=“***.cs” wildcard syntax, so you can’t build this project with MonoDevelop
you can build with the MSBuild command line if you don’t want to open Visual Studio
if you have editor scripts mixed in with game scripts, you can find them with Include=“**\Editor***.cs”
if your editor and game scripts are inter-mixed then you need to Include the editor scripts in the editor csproj and Exclude them from the game csproj
Unity comes with two versions of pdb2mdb.exe – only the one in the MonoBleedingEdge folder works for coroutines (that return IEnumerator)
for hand-building .csproj files, you can get GUIDs from http://www.guidgen.com/

This thread was started after a bunch of thought and discussion on this other thread. Thanks to @guavaman for getting the ball rolling.

guavaman · December 8, 2012, 1:06am

Amazing discovery! I can’t believe this much time has passed and nobody noticed this. (Should be added to Unity docs on working with DLLs.) Now I feel silly for re-rolling it. Oh well. And thanks for taking the time to post your DLL debug solution!

Demigiant · December 8, 2012, 9:02am

Awesome! I can’t believe the Unity guys never mentioned that thing about the correct pdb2mdb, and that it wasn’t noticed before. Thanks a lot yoyo for this discovery, and guavaman for starting it all

Demigiant · December 10, 2012, 8:16pm

Uhm, I tried using the other pdb2mdb (the one in the MonoBleedingEdge folder) but, while it compiles ok with IEnumerators, it seems it doesn’t work, and Unity’s log doesn’t report error lines (exactly as if you didn’t have an MDB at all).

yoyo · December 10, 2012, 8:51pm

I had previously tested to make sure I could step into the DLL code and see full source. This works as I described.

I just checked how Debug.Log messages are handled, and what I see is that the Unity console reports the correct file and line in the shared code (so it is using the information in the MDB), but when I double-click on the error message it opens the script that calls into the DLL code, not the DLL code itself.

Note that pdb2mdb.exe generates a new version of the DLL, and that both this updated DLL and the MDB need to be copied into Unity’s assets folder.

Demigiant · December 10, 2012, 9:19pm

Mhmm I use Visual Studio, and use a post-build routine to convert the PDB, and then copy all the files in my project’s Assets folder (DLL, MDB, and eventually XML), but then the Debug.Log messages show no line at all. I wonder, did you try this with Unity 4, which I’m using? Maybe something different happens, even if it would be weird.

yoyo · December 10, 2012, 9:29pm

I’ve only tried with Unity 3.5.6. Do you still have Unity 3.5.x installed that you could test with?

Also, have a look in your Visual Studio .csproj file and make sure you’ve got DebugSymbols=true and DebugType=full in the configuration you’re building. I’m not sure both settings are strictly necessary, but that’s what I’m using.

Demigiant · December 11, 2012, 11:23am

Ow, sorry for my previous posts: it works perfectly

To call the correct pdb2mdb executable, I was referencing the full path to the correct pdb2mdb, with this line in my post-build command:

c:\Program Files\_Design\Unity 4\Editor\Data\MonoBleedingEdge\lib\mono\4.5\pdb2mdb.exe $(TargetFileName)

Which actually did nothing, and I didn’t realize (very stupidly), that I was still using an old mdb instead than a newly created one.

Now I simply set the default pdb2mdb to the MonoBleedingEdge one, and simply call:

pdb2mdb $(TargetFileName)

which works perfectly.

Thanks again and sorry for my dumbness

chrisjjones · December 12, 2012, 5:36pm

Does anyone have this working on the Mac? We are doing cross-platform development so we have some developers working on Windows and others working in OSX. I can’t seem to get the debugger to step into code that is in DLLs on OSX…it just shows the Assembly Browser which doesn’t really allow for breakpoints…

Of course, it works great on Windows…

Any thoughts?

Thanks,
Chris

Terikon · January 17, 2013, 7:54pm

Great job guys.
Works perfectly with Unity 4.
This must improve whole lifecycle for us.
Thanks a lot for discovery.

BraveSirAndrew · January 29, 2013, 10:21am

Hi Terikon

Would you mind letting us know how you got this working in Unity 4? My registry doesn’t contain a Location folder under Unity Editor 4.x, so the build fails. Hard coded the UnityInstallFolder path for now and everything seems to be working great, but that’s just a stop gap.

Cheers
Andrew

yoyo · January 30, 2013, 1:28am

I should also mention that breakpoints in the DLL work, and stepping into the DLL works, but “Go to declaration” does not – MonoDevelop will still open up the Assembly Browser, even though it ought to be able to open the source file for you.

On that note, if the Assembly Browser is not showing you disassembled source, you need to go to Tools > Options … Preferences > Build, and then on the Assembly Folders tab, add your Unity\Editor\Data\Managed folder.

Also, I have experienced cases where MonoDevelop did not step gracefully through my DLL source code – for example F10 (step over) might advance back out of the DLL code. This seemed to be a temporary MonoDevelop glitch, and it went away after closing down and updating the solution.

GaVaR · February 7, 2013, 10:56pm

Whoever is using VS among Unity might check this asset solution, so you will not ever need to add post build events to your project file by just specifying target output folder.

Demigiant · March 15, 2013, 12:57pm

Pay attention, in Unity 4.1 the correct path to the pdb2mdb has changed from “mono/4.5” to “mono/4.0”

Jiraiyah · April 3, 2013, 9:41am

Wow, i was trying for some days now, i had copiled using monodevelop before but until now i was not able to compile using vs.net and it works on 2012 too.
by the way i think the proper file on unity 4.1 is in 4.5 not in 4.0 folder

Demigiant · April 3, 2013, 9:53am

Weird! Can you confirm that? I can confirm that on my computer it’s in 4.0 folder (for Unity 4.1.0 - it was in 4.5 folder in Unity 4.0 instead)

amirabiri · April 6, 2013, 7:46pm

Is anyone else getting this exception?

Unhandled Exception: System.TypeInitializationException: The type initializer for 'Mono.Cecil.Metadata.TableHeap' threw an exception. ---> System.ArgumentException: Value does not fall within the expected range.
   at System.Runtime.CompilerServices.RuntimeHelpers.InitializeArray(Array array, RuntimeFieldHandle fldHandle)
   at Mono.Cecil.Metadata.TableHeap..cctor()
   --- End of inner exception stack trace ---
   at Mono.Cecil.PE.ImageReader.ReadTableHeap()
   at Mono.Cecil.PE.ImageReader.ReadImage()
   at Mono.Cecil.PE.ImageReader.ReadImageFrom(Stream stream)
   at Mono.Cecil.ModuleDefinition.ReadModule(Stream stream, ReaderParameters parameters)
   at Mono.Cecil.ModuleDefinition.ReadModule(String fileName, ReaderParameters parameters)
   at Pdb2Mdb.Driver.Main(String[] args)

This doesn’t seem to be related to the to the project, the same thing happens when I run the command from the command line.

amirabiri · April 6, 2013, 8:01pm

Not sure why, but using the 2.0 pdb2mdb.exe from the mono (not monobleedingedge) solved this problem.

Demigiant · April 6, 2013, 8:11pm

What Unity version are you using? Maybe they changed something in v4.1.2 - which I still didn’t install. Does the 2.0 pdb2mdb.exe support IEnumerators and coroutines?

TaiChiAnt · May 7, 2013, 10:41am

I have the same problem as well. 2.0 pdb2mdb.exe solved this problem but not the IEnumerator Issue.

Topic		Replies	Views
Running pdb2mdb with Unity 5 and later Unity Engine Scripting , Official	8	10293	April 17, 2020
UnityVS Debugging DLLs Unity Engine Scripting	10	5499	July 1, 2016
Unity 3.1 new feature: move any code into a DLL News & General Discussion	53	15433	January 2, 2013
[Video Tutorial] How to use Visual Studio for all your Unity development Unity Engine Scripting	17	25487	November 10, 2014
Problems compiling DLLs from MonoDevelop Unity Engine Scripting	68	41853	July 11, 2014

How to build and debug external DLLs

Related topics