Earlier this year I released the initial version of the D365FO Admin Toolkit as an open source project on GitHub. One piece of (extremely fair) feedback I got was that I did not explain the process on how to clone the source code of that project to a local machine if you wanted to extend the solution or even if you wanted to help contribute to it by creating new features or functionalities. This blog post walks through the steps you need to take if you want to clone a D365FO solution from GitHub to a local development environment.

Prerequisites

Having an already created (free) GitHub account will make this process easier.

What is GitHub?

GitHub is a developer platform that allows developers to create, store, manage and share their code. It uses a technology called Git to provide the distributed version control of Git plus access control, bug tracking, software feature requests, task management, continuous integration, and wikis for every project.

You may use an internal source control platform at your organization like Azure DevOps, BitBucket, etc. GitHub is the public facing version of that.

It is the easiest way for projects like this to share source code with the community.

Steps to Connect to a GitHub Project

The first thing we need to do is to connect our local Visual Studio instance to a GitHub project.

Note: I am going to show the steps to connect to the D365FO Admin Toolkit project I host on GitHub but the steps below apply to all D365FO projects hosted on GitHub.

On GitHub, find the project you are wanting to clone and copy the URL (for our example, this would be https://github.com/ameyer505/D365FOAdminToolkit)

Launch Visual Studio and select ‘Clone a Repository’

Input the URL from GitHub in the ‘Repository Location’ textbox and click Clone

Once the solution is cloned, navigate to the folder where the solution was copied in a File Explorer, you will find a Metadata and a Project folder. The Project folder contains the Visual Studio files necessary to maintain the project solution itself and the Metadata folder contains the actual X++ source code. Normally the Project folder would live within your local user’s folder on the C:\ drive and the Metadata folder need to reside in the PackagesLocalDirectory folder of the environment, this can either be on a separate drive path (like K:\AosService\PackagesLocalDirectory for cloud hosted environments) or can be on the same drive but in another location (like C:\AosService\PackagesLocalDirectory for locally hosted VHDs).

One of the unique aspects of Git is that you can only map a single folder to be under source control, so because we need to map the Project and Metadata folder to separate locations how do we accomplish this?

We can utilize a Windows feature called a ‘symbolic link’, this allows us to create a mapping from one file path location to another so that any changes made in one location also show up in another. In this way we can make Git happy to keep all of the files and folders under source control in one file location but can also make the AOS happy because the X++ code files are located in the correct location.

We will use Windows Command Line to accomplish this, you will need to launch the application with Administrative permissions to successfully execute the command. The syntax is as follows:

mklink /d <PathToPackagesLocalDirectory> <PathToGitFolder>

For cloud hosted D365FO environments, the path to the PackagesLocalDirectory folder should be:

• K:\AosService\PackagesLocalDirectory

For local VHDs, the path to the PackagesLocalDirectory will be:

• C:\AosService\PackagesLocalDirectory

For example, in my case the syntax was:

mklink /d K:\AosService\PackagesLocalDirectory\D365FOAdminToolkit C:\Users\Adminec6bd89c23\source\repos\D365FOAdminToolkit\Metadata\D365FOAdminToolkit

Once the command is executed, you will get confirmation it was successful and you will notice the folder is created in the PackagesLocalDirectory folder. You may notice that this folder icon looks slightly different than the rest as it has a small arrow in the bottom left hand corner, this is to alert everyone that this folder is linked from another location.

We will perform the same process above for the D365FOAdminToolkitTests folder:

Back in Visual Studio go to Extensions -> Dynamics 365 -> Model Management -> Refresh Models

Now double click on the .SLN file, this loads the solution as the active solution in Visual Studio

At this point, the solution will load within Visual Studio:

This solution contains both X++ projects and a .NET project, I’ve written in the past about how you can have both project types in one solution.

This is important in our case because there are referenced libraries in the .NET project that we need to gather for the solution to work. If you open the References menu under the .NET project, you will see a host of library references that have a yellow triangle next to them, these are libraries where Visual Studio is not sure where to find. In most cases these are handled by NuGet during the build (we’ll get to that in a second) but there are two native D365FO libraries that we reference that you have to manually add. These include:

• Microsoft.Dynamics.AX.Metadata.Core
• Microsoft Dynamics.AX.Security.Management

To add these native D365FO libraries, right click on References and go to Add Reference…

Then go to the Browse menu and click the ‘Browse…’ button at the bottom of the screen:

Then navigate to your PackagesLocalDirectory folder and look for the bin folder, in our case that was:

• K:\AosService\PackagesLocalDirectory\bin

If you are using the new Unified Development Environment deployed via PPAC, the path will be:

• C:\Users\[UsersDirectory]\AppData\Local\Microsoft\Dynamics365\[AppVersion]\PackagesLocalDirectory\bin

Then find both of the DLLs listed above.

Once those are added we have to set up the NuGet package manager for Visual Studio. NuGet is a package manager where developers can share pre-packaged libraries for others to use. This is where a majority of the libraries we reference are stored, but we have to setup a connection to NuGet for this to work. To do this right click on the .NET project and click on ‘Manage NuGet Packages…’:

In the window that opens, look for the settings gear icon in the upper right hand corner:

On the Options dialog that appears, click on the green plus icon to add a new package source:

Now enter the following information:

• Name: Nuget
• Source: https://api.nuget.org/v3/index.json

And click OK.

Now you should be able to go to the .NET project, right click on it, and go to Build. The build process will automatically download the necessary DLLs from NuGet.

If everything was configured correctly, you will get a confirmation that the build succeeded:

Now that we know that the .NET project builds successfully, we can build the entire solution by right clicking the solution and going to ‘Rebuild Solution’:

And once that completes, be sure to synchronize the X++ project to the database:

Congratulations! You’ve successfully cloned a project from GitHub and can now execute, modify, and deploy the solution locally!

Follow Up

I want to create a follow up post to show the steps to perform if you would like to contribute to a project that is hosted on GitHub using this guide: https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project

Resources

Open a Project from a Repo (Microsoft Learn)

Nuget