[3.0+] Developers Guide To Setting Up A Project

[pushedx]

This guide will show developers how to setup a project for Exilebuddy.

Before you start, you need Visual Studio 2017 Community Edition (or higher). It's free with a Microsoft account. Visual Studio 2015 and below are not supported by us anymore, so it's best to stick with the current VS version to avoid issues with not being able to access the same libraries.

When installing Visual Studio 2017, you need to make sure to install the .Net framework bundle. The new main option for .Net is called Universal, which we do not support.

Part 1

1. Create a new Project in Visual Studio.

2. Create a "Class Library (.NET Framework)" that targets ".Net Framework 4.6.1". Failure to use these exact settings will result in your project not working correctly. If you do not see the correct options, you most likely did not install the .Net framework bundle.

NOTE: I did not change my Solution name, but if you plan on having multiple projects, you can. Ideally, it's best to use separate names for the Solution and Project, to avoid issues with duplicate names, but this is just an example.

3. With a new project made, the first thing that needs to be done is to change the project configuration to 32-bit. Click on "Build" and then go to "Configuration Manager".

4. Since this is a new solution/project, we need to add the x86 platform. Expand the "Active solution platform" and choose "< New... >".

5. Now, we can make the new build platform. Change the "Type or select the new platform" drop down to "x86". Leave the second entry as "Any CPU". Make sure the checkbox is marked for "Create new project platform". Once again, since this is a new solution/project, we do not already have the x86 platform settings created, and need to create it.

If we were adding another project to the solution, we would not need to have the checkbox marked, since the platform already existed, and we could just add the x86 platform to the new project.

6. Click "OK" and "Close". At this point, we can verify our settings are correct, as we have to have x86 generated content to work in Exilebuddy. Right click on the project in the Solution Explorer and go to Properties. Change the tab to "Build" to verify settings.

In this example, I only am doing Debug, but you'd want to make sure Release was set to x86 as well if you were going to deploy content from a Release build instead.

7. At this point, it's also good to verify that the .Net 4.6.1 library is being used. If it is not, references to Exilebuddy will fail. Change the tab to "Application".

8. With those two sets of settings confirmed, it is time to start adding references to the project. Right click on the References entry in the Solution Explorer for the project and choose "Add References...".

9. First, we will add Exilebuddy specific references. Expand the "Browse" tab and click on the "Browse" button.

10. At minimal, choose: the Exilebuddy assembly, GreyMagic.dll, log4net.dll, Newtonsoft.Json.dll, and Udis86Net.dll. Depending on if you need other assemblies based on your project, you can add them the same way later. For this example, we'll just need these basic files.

 

[pushedx]

11. Next, we need to choose basic WPF assemblies for our project. These can be found under the "Framework" tab. You will want to select: PresentationCore, PresentationFramework, System.Windows.Forms, System.Xaml, and WindowsBase. Depending on if you need other assemblies based on your project, you can add them the same way later. For this example, we'll just need these basic files.

Now, our project is fully configured, has the necessary references, and we can begin to code.

12. To get the Gui.xaml/Gui.xaml.cs files shown in the upcoming images, please see this post!

Part 2

At this point in the guide, you're almost ready to deploy your content. Before getting into deploying it into EB, I want to go over the process of automatically preparing it to be deployed, because if you develop as much as we do, manually copying files each time is a lot of wasted work.

While these steps are a bit of extra work at first, if you take the time to learn them now, you will save a ton of time in the long run, and help avoid a lot of simple issues of just not copying the correct files all the time. It doesn't matter how simple your project is, if you invest into a good development setup, you'll be all the better.

NOTE: To see the manual process of deploying content to EB, please read this post.

1. To help automate the process of creating deployable content for EB, we'll first make a new project. Go to "File", "Add", and "New Project".

2. This time, we'll just choose a "Console App (.NET Framework)". Once again, make sure your .Net framework is set to 4.6.1 for consistency. This is just because we want an executable producing project, and a console is the simplest. We don't actually be running the file generated in this project though.

Please note, the project type is arbitrary. There's other ways to do this, but I'm just going with something simple, since you will never be allowed to deploy an EXE with your content, so there should be no confusion as to what the empty exe project is for in relation to your content.

For this example, I'll name the project "BuildArtifacts".

3. Now, we need to add an empty folder to the new project, Right click on the BuildArtifacts project, and choose "Add", "New folder". I will name this folder "output", but as you will see later, you can change the name to match your content's assembly name for a little less work. For this example though, it doesn't matter.

4. Now, we need to add links to our files in the plugin project. Right click on the "output" folder, choose "Add", 'Existing Item...'.

5. Now we will add all the files from our ExamplePlugin project. We should first change the filter to "All files (*.*)", then select our code/xaml files, and then click on the arrow at the end of the Add button, and choose "Add As Link".

This is very important to do, because links are shortcuts to the original files. If you do not use a link, the actual files are copied and added to the project, which means no future changes will be reflected, and the whole point of this is meaningless.

6. Once the files are added, we now need to change their build properties. Simply select all the files in the "output" folder, and right click on them and go to "Properties". Depending on your VS window layout, you should see the Properties window show somewhere.

Change the "Build Action" to "None". Change the "Copy to Output Directory" to "Copy always". By doing this, the file links will copy the current versions of your code to the output directory, relative to where the files are located in the project. In this case, since the files links were put in the "output" folder, that is where they will be copied to when the project is built.

7. Now, we need to sync the project build order so this setup works as intended. Right click on the "ExamplePlugin" project and choose "Build Dependencies", "Project Dependencies...".

8. The "ExamplePlugin" project should depend on the "BuildArtifacts" project, so place a checkbox for it as shown.

The purpose of this step is to make the BuildArtifacts project builds first, followed by the ExamplePlugin. The reason for this is simple: BuildArtifacts simply copies source files via links into a specific directory ("output"). By having this project build first, the output directory will always exist, so ExamplePlugin can copy any built files it needs into it (baml/g.cs).

 

[pushedx]

9. Now, we will verify our setup. Build the solution, and then navigate to the "BuildArtifacts/bin/Debug/output" folder.

Please note the path. Since we did not configure BuildArtifacts as x86, it is currently on Any CPU, which means the output path is different. Ideally, we would set the project to x86, but for this example, it's not important, only that you understand the effect the platform has on the output directory.

As you will see in the screenshot, we not have our latest source files automatically copied into a folder, so we do not have to manfully do it. We're not done yet though.

10. Now, we will setup ExamplePlugin to automatically copy the generated baml/g.cs files into this new directory. Right click on the ExamplePlugin project and go to Properties. Change to the "Build Events" tab. Click on the "Edit Post-build..." buton, and use the following command lines:

copy "$(ProjectDir)obj\x86\$(ConfigurationName)\Gui.baml" "$(SolutionDir)BuildArtifacts\bin\$(ConfigurationName)\output\Gui.baml"
copy "$(ProjectDir)obj\x86\$(ConfigurationName)\Gui.g.cs" "$(SolutionDir)BuildArtifacts\bin\$(ConfigurationName)\output\Gui.g.cs"

This might seem confusing at first, but users should look at the "Macros" the post-build exposes. In this case, what we're trying to achieve is to copy the "Gui.baml" and "Gui.g.cs" files from the paths they exist in the solution, into our new output folder.

This is where understanding the difference of x86 and Any CPU has on the output path. Had we made BuildArtifacts x86, we'd have to have the x86 after the bin token for the destination path. Likewise, if we didn't use "output" as the folder name, we'd have to update that here as well. The same is true of the "BuildArtifacts" project name.

11. Now, rebuild the entire solution again. Check the "BuildArtifacts/bin/Debug/output" folder again. If all was done correctly, you should now see the baml/g.cs files automatically copied.

To recap what just happened. We made a second project that simply copies our plugin's files into a new directory. We then made our plugin depend on the project so the files would always be copied first. Then, the plugin project copies files it generates into that folder, thus removing the need for any manual work once we have this setup established.

Any time we add additional guis or files, we still have to update the file links and post-build, but it's set and forget past the first time it's done.

Part 3

At this point, we now have a folder ready to deploy to Exilebuddy, but we have one task left of creating the new "3rdparty.json" file. This part was written in context of users following Part 2, but if you manually copied files, the process is the same.

Before starting, make sure to read over this ThirdPartyConfigMaker post!

1. Run "ThirdPartyConfigMaker.exe". Choose "Load Folder" and select any file in the "BuildArtifacts/bin/Debug/output" folder.

You will notice the initial Assembly Name is "output". Change this to the name of your assembly, or in this case, "ExamplePlugin". This is what I meant earlier by choosing a different name for the output folder, you can reduce an extra step later on.

Finally, click "Save". We do not have any dependencies for this example or references.

2. At this point, our "BuildArtifacts/bin/Debug/output" folder is complete, and ready to deploy into Exilebuddy.

Copy the "output" folder into the "3rdParty" folder in your Exilebuddy directory. Rename the folder to the exact same name as the "Assembly Name" you choose for the json. In this case, it should be "ExamplePlugin".

Case and spaces matter, so be sure it's exact!

This is what the final contents should look like.

3. Run Exilebuddy. If everything was done correctly, the plugin should show up as expected, and the GUI loads without any issues.

 

[pushedx]

This post will go over important things that did not fit into the step-by-step guide.

"ExamplePlugin" is on the default "do not load" list for Exilebuddy, so you will have to remove it from EB's settings to get that assembly actually loaded. Consider it the "did you actually read the entire thread" check.

Next, is naming.

Your solution/project name (namespace) should always be different than any class type name.

If you do not do this, you will cause yourself endless headaches trying to figure out why things don't work at times when there's some conflict between the names.

In this example, I did not rename the solution from ExamplePlugin, but you should. Otherwise, the path to access your plugin class could be ExamplePlugin.ExamplePlugin which reside inside the ExamplePlugin assembly. See the problem?

In my test code, I did not use ExamplePlugin as the actual class name of the plugin, but rather Plugin1, but ideally, you want different names at each level to figure out issues when things do go wrong.

In our setup for 3.0, we now have two assemblies, Default and Legacy. Those are the names for those root projects. All of our sub-projects, are now included in their own folders. This was for significant performance improvements, but I feel people are still not understanding the setup, even though nothing changed at the core.

Here's a basic example of the change that took place.

Pre 3.0:
20 assemblies each containing their own project code. This means 20 DLLs were being compiled and loaded each time you started the bot.

Post 3.0:
2 assemblies total, each containing multiple project code. This means 2 DLLs are being compiled and loaded each time you start the bot. While the DLLs are slightly larger than before, significant overhead is removed, which is why EB can startup so much faster now.

Our assembly names are "Default" and "Legacy", you should choose your own, different assembly names.

Devs should not add content to either the Default or Legacy assemblies.

Those are our assemblies, and they will get updated each time the bot updates.

The assembly name is simply the name of the DLL that gets generated and loaded into Exilebuddy. It does not imply anything about what's inside the DLL itself.

To say once again, an assembly (DLL) can contain multiple bots, plugins, and routines if you choose. You do not have to have one DLL per content type. Pre-3.0 code used a really inefficient model that just never got updated, and as a result, most people think you're limited to one plugin per DLL, but you're not.

Devs can choose whichever layout works best for then, but keep in mind, the more DLLs users have to add to EB, the more overhead there will be on startup. The trade-off of having everything in fewer assemblies is project bloat, and now a lot of extra content users have to have loaded, but there's no clear design that is better for all cases. We choose our 2 assembly layout, because most people will be using most of the content we provide one way or another, so it's not an issue.

 

[pushedx]

Manually Copying Files

Part 2 of the guide goes over a way to automatically copy your base files. This post will go over the manual aspect of it.

• Copy all "cs" files from your project's directory. This includes the "xaml.cs" files.
  
  
• Inside the "obj\x86\Release" folder (or Debug if you're building in debug) copy all "baml" and "g.cs" (not g.i.cs) files.

You copy these files into a new folder, with the same directory structure they existed with in your code.

For example, if you look at our assemblies, "3rdParty\Legacy" is the root folder for the Legacy assembly.

However, it has a bunch of sub-folders for all the sub-projects. The only file in the root folder is "3rdparty.json".

Compare that to the project layout in Visual Studio for the Legacy project.

Notice how AutoFlask has its own folder, which it then does in the root Legacy folder? This is the code structure you replicate, however you have things setup.

Now looking inside the AutoFlask folder in Legacy:

You have your main cs files, then the baml/g.cs file generated.

These represent the core project files that make up your content. You can then copy any non-code content that goes along with your project (make sure no DLLs/EXEs though).

That's about all there is to it really, keep in mind you can also zip your deployed content rather than having a folder, and EB will load it as well from the 3rdParty folder.

 

[pushedx]

Adding a GUI - User Control (WPF)

This post will go over adding the template GUI files to your project in Step 12 from Part 1.

1. Right click on the Project you want to add the GUI to, and choose "Add" -> "New Item..."

2. Choose ""User Control (WPF)" and type in a name and press "Add".

I reuse the name "Gui.xaml" because with one common name, you can copy/paste build event steps talked about in Part 2 for different plugins without having to change the name of the files copied since they will be the same.