Today’s article guides you through the necessary steps to create, use, and debug a .NET DLL in Unity. These can help you modularize your code into libraries that can be imported as a single file by the users of your library. They’re especially useful when utilizing the “pure code” approach to code design as you can easily break up a Unity app’s monolithic structure into reusable components. So read on to learn how to use DLLs in Unity!

First of all, let’s talk about what a .NET DLL is. Simply put, it’s a file that contains one or more compiled .NET scripts. These are usually C#, but could be any other .NET language such as F# or IronPython. In fact, when you just add scripts directly to your Unity project, they are automatically compiled into a DLL stored in MyProject/Library/ScriptAssemblies/Assembly-CSharp.dll.

So how can you make a DLL of your own? The Unity editor doesn’t provide any way to build them, so you’ll need to make use of external tools like MonoDevelop, Xamarin Studio, or Microsoft Visual Studio. We’ll talk about each of them since they’re all common in Unity development.

MonoDevelop (version included with Unity 5.0.2f1)

  1. File > New > Solution
  2. C# > Library
  3. Choose a project name and directory > OK
  4. Project > ProjectName Options
  5. Build > General > Target framework > Mono / .NET 2.0
  6. Project > Edit References > .NET Assembly
  7. Navigate to /Applications/Unity/Unity.app/Contents/Frameworks/Managed/UnityEngine.dll
  8. OK
  9. Add your code to the project
  10. Build > Build All
  11. The DLL is placed in ProjectDirectory/bin/Debug/ProjectName.dll

Xamarin Studio (as of 5.9.1 build 3)

  1. File > New > Solution
  2. Other > .NET > Library > Next
  3. Choose a project name and directory > Create
  4. Project > ProjectName Options
  5. Build > General > Target framework > Mono / .NET 2.0
  6. Project > Edit References > .NET Assembly > Browse…
  7. Navigate to /Applications/Unity/Unity.app/Contents/Frameworks/Managed/UnityEngine.dll
  8. Open > OK
  9. Add your code to the project
  10. Build > Build All
  11. The DLL is placed in ProjectDirectory/bin/Debug/ProjectName.dll

Microsoft Visual Studio (as of 2013, version 12.0.31101.00 Update 4)

  1. File > New > Project
  2. Top drop-down list > .NET Framework 2.0
  3. Templates > Visual C# > Class Library
  4. Choose a project name and directory > OK
  5. Project > Add Reference > Browse > Browse Button
  6. Navigate to C:\Program Files\Unity\Editor\Data\Managed\UnityEngine.dll
  7. Add > OK
  8. Add your code to the project
  9. Build > Build Solution

You now have a DLL placed in ProjectDirectory/bin/Debug/ProjectName.dll. Copy this file to your Unity project’s Assets directory or any folder in it and it will be usable by the rest of your project’s scripts.

One issue that will crop up at this point is that if any code in your DLL ever crashes, your stack trace won’t contain as much information as it would had you put the scripts directly into your Unity project. Specifically, file names and line numbers will be omitted making debugging much harder.

Luckily, there is a solution to this issue. If you build with MonoDevelop or Xamarin Studio, there will be a ProjectName.dll.mdb file in the same directory that the DLL gets placed in. Copy this file to your Unity project’s Assets directory along with the DLL and Unity will now have debugging information about your DLL’s contents, including file names and line numbers.

If you’re building your DLLs with Microsoft Visual Studio, there’s one extra step. Visual Studio builds a PDB file instead of an MDB and Unity doesn’t know how to use it directly. Instead, Unity provides a command-line utility to convert PDB files into MDB files. Run it like this:

c:\Program Files\Unity\Data\MonoBleedingEdge\lib\mono\4.5\pdb2mdb.exe MyLib.dll

Lastly, there are a couple of downsides to using DLLs in Unity. The first is that there is an issue that crops up when dispatching an event from code in a DLL. This is easily overcome, as I’ve described in this article.

The other issue is that when code in a DLL crashes, you can’t simply double-click on the crash in the Unity editor’s Console pane and jump straight to the line for a quick fix. Instead, you need to note the line that crashed, open the IDE you’re building the DLL in, find the line, fix the crash, rebuild the DLL, and re-import the DLL into Unity. This can be a tedious process, but you can partially automate it in each IDE via post-build steps.

Now you know how to create, use, and debug a .NET DLL in Unity. If you decide to use them, you’ll have a powerful tool to modularize your app into reusable libraries. If you’ve already adopted this strategy and are using DLLs in your app, let me know how it’s gone for you in the comments. Do you have any particular strategies that make using DLLs easier or more powerful?