References
References are AOT objects that register external .NET assemblies (DLLs) for use within the X++ codebase. When your X++ code needs to call methods on external libraries — third-party NuGet packages, custom .NET assemblies, or specific .NET Framework classes not available by default — you add a reference to make the assembly available to the compiler and runtime.
Each model in D365 F&O has its own set of references. The AOT already includes references to common .NET assemblies and D365 platform assemblies. You only need to add additional references when consuming libraries outside the standard set.
How References Work
When you add a reference to a model:
- The compiler includes the referenced assembly's type information, allowing you to use its classes, interfaces, and methods in X++ code with
usingstatements. - At runtime, the assembly is loaded from the model's bin folder or the Global Assembly Cache (GAC).
- The reference metadata (assembly name, version, public key token) is stored in the AOT and version-controlled.
Standard References
Every model automatically references the core D365 platform assemblies:
| Assembly | Description |
|---|---|
Microsoft.Dynamics.AX.Framework.* | Core framework assemblies |
Microsoft.Dynamics.ApplicationPlatform.* | Application platform classes |
System, System.Core, System.Data | .NET Framework base libraries |
System.Xml, System.Xml.Linq | XML processing |
System.Runtime.Serialization | Serialisation |
Newtonsoft.Json | JSON serialisation (included in platform) |
Adding a Reference
In Visual Studio
- In Solution Explorer, right-click your project → Add Reference.
- Browse to the assembly file (.dll) or select from available assemblies.
- The reference is added to your model's descriptor.
In the AOT
References appear as AxReference objects in the model metadata. Each reference stores:
- AssemblyName — the full assembly name.
- Version — the assembly version number.
- PublicKeyToken — the strong name key token (for signed assemblies).
Using Referenced Assemblies in X++
If you have a custom .NET assembly, add the DLL to your model's bin folder, add a reference in Visual Studio, then use it in X++.
External assemblies must be deployed to the server's model bin directory. In cloud-hosted environments, custom DLLs must be included in the deployable package. Ensure referenced assemblies target a compatible .NET version.
Service References
The ServiceReference property on AxReference indicates whether the reference is a WSDL / WCF service reference rather than a standard assembly reference. Service references are generated from web service endpoints and provide proxy classes for calling external SOAP/WCF services.