How To Update Reference Packages In D365

Have you received this error message when building your x++ code: “Are you missing a module reference”? If the code in your model references objects or methods defined in another model, you need a reference to that model. If your model does not have a reference to the other model, you will receive a compile error. In this article, I will explain how to update reference packages in D365.

Why Do You Need Reference Packages

Before learning how to update reference packages in D365, it is important to understand what they are. And why you need them.

In this last article I explained How to Create A Model In D365. Read that article first, if you have not already. In that article I explained that a Model contains all of your code. That said, it is important to understand that your code may reference tables, forms, and classes that are defined in other models, such as the base Microsoft models.

Therefore, we need reference packages (or reference models), to tell the system which models contain the definitions of objects we are using in our Model.

If you are used to coding, you may have added dll references to your Visual Studio project. Inside these dlls contain compiled code that you can reference and have your code use. Reference packages in D365 follow a very similar concept. By adding a Reference Package to the Model that we create, we are telling the compiler to look at the code defined in the referenced models. And it will use this information to determine if there exist any compile errors.

An Example

Let’s pretend that I am writing a runnable Class. Also known as a Job. And I want to select a specific Retail store record, then update it. If my model does not have a reference to the ‘Application Suite’ package, and I try to use the RetailStoreTable table buffer I will receive an error. The system will have no idea what this object is. Or if I am using it correctly. It will have no knowledge of any of the methods on that table.

Try It Yourself

Open Visual Studio as an Administrator. Click File>New>Project. Select ‘Finance Operations‘ as the Project template. If you are using Visual Studio 2019, your screen will look like this. Then click ‘Next’.

Set the Project Name to ‘ReferenceAnotherModel’ or whatever you would like. Then click ‘Create‘.

In the Solution Explorer, Right click on the Project node, and then select Properties.

Set the Model property to be a Model that does not contain a Reference to ‘Application Suite’. In my case, I created a Model named ‘My Model 2’ that does not contain this Reference. Then click ‘Ok’.

Next, Right click the Project Node and select ‘Add>New Item‘. Then select ‘Runnable Class (Job)‘ under Dynamics 365 Items. Set the Name to ‘ReferenceAnotherModelJob’ or whatever you would like. Then click ‘Add’.

The system will generate code that defines a class which is the same name you just entered. And it will also add a ‘main‘ method to this class. This is the method where you can put code that you would like to run when this job runs.

Add Code That References Another Object Not Defined In Your Model

Add a line of code that declares a table buffer of a table that exists in a Model that you did NOT reference. The complete code will look like this.

class ReferenceAnotherModelJob
{
    /// <summary>
    /// Runs the class with the specified arguments.
    /// </summary>
    /// <param name = "_args">The specified arguments.</param>
    public static void main(Args _args)
    {
        RetailStoreTable retailStoreTable;
    }

}

Click Save. You should see an error message like this.

What Reference Package Should We Use?

In order to fix this, we need to add a Reference Package. This will let the system be aware of the code that defines the object we are using in our code.

First, we need to understand what Reference Package (or Model) contains the object we are using.

To determine this, open the Application Explorer. Go to View>Application Explorer.

In the search bar, type ‘RetailStoreTable’. (Or whatever object you are using).

Find the object in the hierarchy tree. Then look for the grey text after the name. Specifically the value between the square brackets.

In this example, I can see that the table RetailStoreTable is defined in the Application Suite Model.

Update Model Parameters

Now that we know which package we need to reference, I can show you how to Update Reference Packages in D365.

Depending on which version of Visual Studio, you may see ‘Dynamics 365’ in the top menu. Or you might see ‘Extensions’. In Visual Studio 2019, you will see ‘Extensions’.

Go to Extensions>Dynamics 365>Model Management>Update model parameters.

A wizard will open up. For the ‘Model name‘ field, select the Model you wish to update. In my example, I need to update ‘My Model 2‘. Then click ‘Next‘.

Select Referenced Packages

On the next page, you will see a list of all of the packages (or models) that exist in the system. Initially all of the models listed will be all of the base Microsoft models. However, you may have created some models, or you may have 3rd party models included in your environment.

All of the models referenced by the specified model will have a checkbox next to it. In my example, I can see that the model ‘My Model 2‘ has a reference to ‘Application Foundation‘ and ‘Application Platform‘.

On quick note: This screen uses the label ‘Select referenced packages‘. In my mind I pretend that this screen says ‘Select referenced models‘. Because I believe that is really what we are looking at here. A Package can contain multiple models. But I believe in this case this list is really showing the list of Models. Someone can correct me if I am mistaken.

Notice there is not a checkbox next to ‘Application Suite‘. We determined that Application Suite is the model that contains the code for ‘RetailStoreTable’.

Check the checkbox next to that model. (Or whatever model you need to reference in your case). If you have already written code that references many different objects, you may need to add many different references.

Click the ‘Next’ button. You will see all of the Referenced packages listed on the Summary screen.

Finally click the ‘Finish’ button in the wizard.

Compile Again

Now that you have followed the steps to Update References Packages in D365, we can see if the error has gone away. Go to Build>Build solution to compile your code again.

If you now have all of the correct referenced packages, the code should compile without error.

Circular References

Circular dependencies occur when you have two models that both reference objects defined in each other. The system will not allow you to add a reference to a Package/Model that already has a reference to current Model.

This can happen often with tables or Extended Data Types.

Therefore, it is highly recommended that when you write code, you put all of your in one model, when it makes sense. This avoids the issue of circular dependencies.

There are some cases, where you might be an ISV or VAR and you wish to sell one main ‘feature’ to other companies. In this case, you would put all of the code necessary for that feature into one Model/Package. And have that Model only reference other base Microsoft Packages/Models.

And you may have a second feature that is completely distinct from the first one, and put that in its own Model. That is fine. But if you are anyone else, you will reduce your chance for errors at compile time if you put all of your code in one Model. And it will make creating a build pipeline easier to manage as well.

View Package Dependencies

As we discussed, ideally all your code would be in one Model. And so the only references you would need to worry about, would be the base Microsoft models/packages. Sometimes these base Microsoft packages will have dependencies, that will require you to add multiple references to your Model.

In this scenario, you can view package dependencies to help understand what packages to reference. See the Microsoft documentation here.

In the Application Explorer, First clear out anything you have in the search bar. Then right click on the AOT node, and select ‘Model View’.

Then, scroll down until you locate the node named ‘Directory’. Do not search, as this will cause the Application Explorer to switch back to classic view.

Right click on the Directory node and select ‘View package dependencies>view outgoing references‘.

You may receive an error that looks like this. It seems that this is not included in the LCS Cloud Hosted Development machines by default.

If so, go to Tools>Get tools and Features…

Then select the ‘Individual components’ tab. Scroll down and select ‘DGML editor’ under ‘Code Tools’. Then click ‘Modify’.

After installing the component, restart Visual Studio as an Administrator. Then repeat the steps.

A diagram will show. In this diagram we can see that the Directory Model is dependent on the Application Common, Application Foundation, and Application Platform models. Therefore, in order to use an object defined in the Directory model, you should also add references to these other packages.

Common Reference Packages

I wanted to provide a list of common referenced packages in D365 Finance and Operations. If you plan to have a lot of code in your custom model and likely going to reference a lot of different objects from the base code, you may want to include these reference packages. This is ultimately up to you and highly dependent on what base objects you reference in your code.

ApplicationCommon, ApplicationFoundation, ApplicationPlatform, ApplicationSuite, Calendar, ContactPerson, Currency, Dimensions, Directory, FiscalBooks, GeneralLedger, Ledger, PersonnelCore, PersonnelManagement, Retail, RevenueRecognition, SourceDocumentation, SourceDocumentationTypes, Subledger, Tax, TaxEngine, UnitOfMeasure.

Conclusion

If you have any need to customize or extend the base Microsoft code, you will need to Create A Model in D365. In many or most scenarios it makes sense to add all of your code to just that one Model. Unless you are creating completely new and distinct code, it is likely that you will need to reference base Microsoft objects defined in other Models. Therefore, it is important to know how to update references packages in D365. And it is important to understand what models/packages you need to include. I hope you learned something new today.