Creating class libraries for Unity3D using Visual Studio

The Visual Studio Tools are a great help when programming with C# for Unity3D.
But some things are still a little bit tricky, if the code base grows larger and you still want to create “clean code”.

Especially creating library assemblies to organize and/or reuse your code across multiple projects is not as easy as with normal Visual Studio projects. If you create a new class library project, you have to copy the DLL into the asset-folder of your Unity3D project.

You can´t create the project inside the Unity3D project path for two reasons:

  1. Unity will detect the *.CS files of your class library inside the Unity3D game project folder and will compile them (again) as part of the game project. (This is ok if you only want to share the *.CS files with other Unity projects. But in this case you should not create a class library project and just use clever namespaces instead to organize your code inside the C# files.)

  2. If you build the new library project inside Visual Studio, the Unity3D DLLs are copied into the asset-folder, too. This causes the build error “Assembly DLL name is reserved for internal use: […..]/UnityEngine.dll (did files generated by a build accidentally end up in your Assets/ folder?)”.

The first step to create the class library project:

Add a new class library project to your Visual Studio solution. Place the location outside of the Unity3D folder of your game project (especially outside the assets folder). 

In my case the new project is named “de.springwald.unity3d.toolbox” and my Unity3D project is called “MiniTrue”.

Now you should see something like this:

In most cases you will want to use Unity3D objects in your library.

The needed reference can be found at
c:\Program Files (x86)\Unity\Editor\Data\Managed\

After adding the references to your project it should look like this:

Now open the new project properties and change the framework to the same entry as your "UnityVs…CSharp" project.
In my case this is „Unity 3.5 .net Subset Base Class Libraries“.

For debugging purposes you should create the mono debug symbols by adding the following post-build command line:

"c:\Program Files (x86)\Unity\Editor\Data\Mono\lib\mono\2.0\pdb2mdb.exe" $(TargetPath)

Create a subfolder inside the Unity3D asset folder and call it like your new project.
For my project the name is “Assets\AdditionalDlls\de.springwald.unity3d.toolbox”.

The last problem to solve is making your new DLL useable in multiple Unity3D projects e.g. sharing them via GIT. Your asset folder path contains the name of your Unity3d project, so it´s not a good idea to place this information inside the library project.

But you can put it into a common parent folder of your Unity3D project and the new DLL project. Place a batch file called copyAdditionalDlls.bat into this parent folder and add it to the post-build event command line like this:

$(ProjectDir)..\copyAdditionalDlls.bat



Place a simple copy command inside the a batch file to copy the library DLL files to the “Assets\AdditionalDlls\...” folder:

For my project folders structure this is the copy command:

Copy e:\MiniTrue\de.springwald.unity3d.toolbox\bin\de.springwald.unity3d.toolbox.* e:\MiniTrue\Unity3D\Assets\AdditionalDlls\de.springwald.unity3d.toolbox

That’s all. If you now build the new DLL inside Visual Studio it will be “beamed” into the asset folder of your Unity project and can be debugged, too.

Update 25.01.2015 - 23:20: pdb2mdb.exe has problems with methods containing "yield return"

While writing code for my class library suddenly the pdb2mdb.exe started to exit with “code -1”.

After searching for 2 hours I found this mono bug from 2011: “[Mono-bugs] [Bug 704702] New: pdb2mdb.exe fails on methods containing 'yield'”

Seems as if the pdb2mdb.exe delivered with Unity3D has this very old bug and it crashes when you use “yield” in your code.

Fortunately there is a newer version available, which you can include into your project using nuget.

To install the newer version of "Mono pdb2mdb", open the Package Manager Console (from the Tools menu, select Library

Package Manager and then click Package Manager Console) and run the following command:

PM> Install-Package Mono.pdb2mdb

The path to the pdb2mdb.exe also has to be changed inside the post build commands:

$(ProjectDir)packages\Mono.pdb2mdb.0.1.0.20130128\tools\pdb2mdb.exe $(TargetPath)


Comments (1) -

Thanks !! You save my day with this tutorial !

Add comment