3.1 Visual Studio Extension Models & Packages

Visual Studio Extension Models & Packages

Quick Answer: In Dynamics 365 Finance and Operations, a Package is the physical deployment and compilation unit that compiles into a single .NET assembly (.dll), while a Model is a design-time metadata container representing a logical feature set. Development occurs inside Visual Studio Projects, each bound to exactly one model. All metadata resides on disk under PackagesLocalDirectory\<Package>\<Model>\Ax<ElementType>\*.xml, defined by a model descriptor in PackagesLocalDirectory\<Package>\Descriptor\<Model>.xml. Overlayering is permanently sealed; customizations must use extensions (additive metadata and Chain of Command) so that Microsoft can continuously service base packages without breaking customizations.

---

1. Core Architectural Concepts: Packages, Models, and Projects

Understanding the precise separation of responsibilities between Packages, Models, and Visual Studio Projects is critical for both real-world solution architecture and the MB-500 exam.

+-------------------------------------------------------------------------+
| PACKAGE (Deployment & Compilation Boundary)                             |
| Compiles into: <PackageName>.dll + .netmodule files                     |
|                                                                         |
|   +--------------------------+    +---------------------------------+   |
|   | MODEL A (Design-time)    |    | MODEL B (Design-time)           |   |
|   | Metadata & X++ Code      |    | Metadata & X++ Code             |   |
|   | Descriptor: ModelA.xml   |    | Descriptor: ModelB.xml          |   |
|   +--------------------------+    +---------------------------------+   |
+-------------------------------------------------------------------------+
          ^                                       ^
          | (Bound to Model A)                    | (Bound to Model B)
+-----------------------+               +-----------------------+
| VS Project 1 (.rnrproj)|               | VS Project 2 (.rnrproj)|
+-----------------------+               +-----------------------+

The Package

• Compilation Boundary: A package is the unit of compilation. When built, all models residing inside a package are compiled together into a single .NET assembly (<PackageName>.dll) stored in the package's bin directory, along with symbol files (.pdb) and netmodules.
• Deployment Boundary: Software Deployable Packages (SCDPs) deployed via Lifecycle Services (LCS) or Power Platform Admin Center (PPAC) contain compiled packages. You deploy binaries at the package level, never individual models or individual elements.
• Isolation: A package can reference other packages, but circular dependencies between packages are strictly prohibited by the build system.

The Model

• Design-Time Metadata Container: A model is a logical grouping of elements (tables, forms, classes, EDTs, enums, extensions) and source files. It is purely a design-time construct.
• Multiplicity: A single package can contain multiple models. Historically, Microsoft shipped packages containing multiple models (for example, the ApplicationSuite package originally contained both ApplicationSuite and ApplicationSuiteElectronicReporting models). However, current development best practices dictate creating one model per package for custom solutions to simplify deployment and versioning.
• Descriptor File: Every model possesses an identity file called a Model Descriptor (<ModelName>.xml) located in <PackagesLocalDirectory>\<PackageName>\Descriptor\.

The Visual Studio Project

• Developer Work Unit: Projects in Visual Studio (using the Finance and Operations project system, .rnrproj) organize elements during development.
• Strict 1:1 Binding to Model: A project can belong to exactly one model. You specify this model during project creation (or in the project properties). You cannot place elements belonging to Model A and Model B inside the same Visual Studio project.
• No Runtime Existence: A project does not exist at runtime or deployment. It is purely a developer-facing filter and compilation trigger.

Comparison: Package vs. Model vs. Project

---

2. File System Architecture Under PackagesLocalDirectory

Finance and Operations uses a metadata-driven architecture where every AOT element is stored as an individual, human-readable UTF-8 XML file on disk. This replaced the legacy monolithic database store (the AX 2012 ModelStore).

Physical Location

On developer virtual machines (Cloud-Hosted Environments or local VHDs), metadata is hosted under the AOS service directory:

• Standard path: K:\AosService\PackagesLocalDirectory or C:\AOSService\PackagesLocalDirectory.

Hierarchy Anatomy

The directory structure follows a strict naming convention:

<PackagesLocalDirectory>\
    <PackageName>\
        bin\                              --> Compiled binaries (.dll, .pdb)
        Descriptor\                       --> Model descriptor metadata
            <ModelName>.xml               --> Declares dependencies & identity
        <ModelName>\
            AxClass\                      --> X++ classes (.xml)
            AxTable\                      --> Tables (.xml)
            AxTableExtension\             --> Table extensions (.xml)
            AxForm\                       --> Forms (.xml)
            AxFormExtension\              --> Form extensions (.xml)
            AxEdt\                        --> Extended Data Types (.xml)
            AxEnum\                       --> Base Enumerations (.xml)
            AxEnumExtension\              --> Enum extensions (.xml)
            AxSecurityRole\               --> Security Roles (.xml)
            AxLabelFile\                  --> Label metadata & text files

Concrete Examples of Disk Paths

• Standard Customer Table: PackagesLocalDirectory\ApplicationSuite\Foundation\AxTable\CustTable.xml
• Custom Table Extension in Model ContosoCore inside Package ContosoCore: PackagesLocalDirectory\ContosoCore\ContosoCore\AxTableExtension\CustTable.ContosoCore.xml
• Custom Runnable Class (Job) in Model ContosoCore: PackagesLocalDirectory\ContosoCore\ContosoCore\AxClass\ContosoInvoiceBatchJob.xml
• Model Descriptor for ContosoCore: PackagesLocalDirectory\ContosoCore\Descriptor\ContosoCore.xml

Key Architecture Rule: Because every element is an individual XML file, version control systems (Git or Azure DevOps TFVC) can track granular line-by-line diffs, perform parallel branch merges, and execute pull request code reviews without locking an entire binary database.

---

3. Model Descriptors & Dependency Architecture

A model cannot access elements, tables, classes, or EDTs defined in another model unless it has declared an explicit dependency on that model's package.

Anatomy of AxModelInfo in the Model Descriptor

The descriptor file located at <Package>\Descriptor\<Model>.xml contains serialized AxModelInfo metadata. Key properties include:

• <Name>: The unique internal name of the model.
• <Publisher>: The organization or ISV authoring the model (e.g., Contoso Ltd).
• <VersionMajor>, <VersionMinor>, <VersionBuild>, <VersionRevision>: Semantic version numbers.
• <Description>: Human-readable summary of the model's functional scope.
• <ModuleReferences>: The collection of package/model dependencies this model requires to compile.

<?xml version="1.0" encoding="utf-8"?>
<AxModelInfo xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Name>ContosoCustomizations</Name>
  <Publisher>Contoso Corporation</Publisher>
  <VersionMajor>1</VersionMajor>
  <VersionMinor>0</VersionMinor>
  <VersionBuild>0</VersionBuild>
  <VersionRevision>1</VersionRevision>
  <Description>Contoso Enterprise Extensions for Accounts Receivable</Description>
  <ModuleReferences>
    <string>ApplicationPlatform</string>
    <string>ApplicationFoundation</string>
    <string>Directory</string>
    <string>SourceDocumentation</string>
    <string>ApplicationSuite</string>
  </ModuleReferences>
</AxModelInfo>

The Standard Microsoft Model Hierarchy

Microsoft organizes the standard application into layered packages and models. Dependencies flow strictly downward:

1. ApplicationPlatform: Contains kernel runtime primitives, base system tables (UserInfo, Batch), foundational system classes, primitive data types, and core security definitions.
2. ApplicationFoundation: References ApplicationPlatform. Contains organizational hierarchies, the Global Address Book (GAB) core framework, number sequences, and SysOperation execution infrastructure.
3. Directory: References ApplicationFoundation. Houses the party model (DirPartyTable, contact info, address resolution).
4. SourceDocumentation / SourceDocumentationTypes: References ApplicationFoundation and Directory. Implements the underlying accounting framework, monetary distribution rules, and subledger journal entries.
5. ApplicationSuite: References all lower layers. Houses core ERP business logic: General Ledger, Accounts Receivable (CustTable), Accounts Payable (VendTable), Inventory Management (InventTable), Sales Orders (SalesTable), and Purchase Orders (PurchTable).

+-------------------------------------------------------------+
|                      ApplicationSuite                       |
|    (CustTable, VendTable, SalesTable, InventTable, etc.)    |
+-------------------------------------------------------------+
         |                                 |             |
         v                                 v             |
+------------------------+     +-----------------------+ | 
|  SourceDocumentation   |     |       Directory       | | 
+------------------------+     +-----------------------+ | 
         |                                 |             |
         +----------------+----------------+             |
                          v                              v
         +--------------------------------------------------+ 
         |              ApplicationFoundation               | 
         +--------------------------------------------------+ 
                                  |
                                  v
         +--------------------------------------------------+ 
         |               ApplicationPlatform                | 
         +--------------------------------------------------+ 

Dependency Rules for Developers

• Compilation Rule: If code in ContosoModel references CustTable, ContosoModel must reference ApplicationSuite. If it only references Global functions or system tables, referencing ApplicationPlatform suffices.
• Missing Reference Error: If you write CustTable custTable; in a model that does not reference ApplicationSuite, the compiler produces an error: "The name 'CustTable' does not denote a class, a table, or an extended data type."
• Acyclic Rule: Circular references are rejected at compile time (Model A cannot reference Model B if Model B references Model A).

---

4. The Extension Model vs. Sealed Overlayering

One of the most foundational architectural shifts evaluated on the MB-500 exam is the complete elimination and sealing of overlayering in favor of the extension model.

The Legacy Overlayering Paradigm (Sealed)

In Dynamics AX 2012 and early versions of Dynamics 365, developers used overlayering:

• Custom code was injected directly into standard Microsoft models within higher layers (e.g., VAR, CUS, USR layers).
• A developer could open standard classes like SalesLineType and edit source lines directly inside Microsoft's methods.
• The Pain Point: Whenever Microsoft released a Cumulative Update, hotfix, or service pack, existing customizations were overwritten or produced extensive merge conflicts. Upgrades required hundreds of hours of code conflict resolution and regression testing.
• The Sealing: Starting with Platform Update 11 (PU11) and finalized in Dynamics 365 Finance and Operations version 8.0, Microsoft sealed all standard models. Overlayering is impossible; developers cannot edit standard source files or insert custom code directly into Microsoft packages.

The Modern Extension Paradigm

Under the extension model, Microsoft packages are compiled assemblies that developers treat as immutable black boxes:

• Additive Metadata: To add fields, field groups, or indexes to a standard table (e.g., CustTable), developers create a Table Extension (CustTable.ContosoExtension) in their own model. The extension file contains only the delta (the new fields or modified properties). The base CustTable.xml remains untouched.
• Additive Behavior (Chain of Command - CoC): To wrap business logic around standard methods, developers create extension classes decorated with [ExtensionOf(tableStr(CustTable))] and utilize next calls. Custom logic executes before, after, or around base logic without touching Microsoft source files.
• Event Handlers & Delegates: Developers subscribe to pre/post data events (OnInserting, OnValidatedWrite) or application delegates.
• Independent Deployment & Zero-Downtime Servicing: Because custom code resides in separate packages, Microsoft can update ApplicationSuite.dll during monthly One Version platform updates without touching or recompiling partner assemblies, guaranteeing non-destructive updates.

Comparison: Overlayering vs. Extension Model

---

5. Exam Traps & Real-World Pitfalls

• Exam Trap 1: Missing Module Reference Compile Error. A question presents a scenario where a developer creates a new class in a custom model ContosoTax and declares a variable of type SalesTable. The build fails with "The name 'SalesTable' does not denote a class, a table, or an extended data type", despite SalesTable clearly existing in the AOT. The root cause is that the developer forgot to add a reference to ApplicationSuite in the ContosoTax Model Descriptor.
• Exam Trap 2: Project Spanning Multiple Models. The exam asks how to configure a single Visual Studio project to hold both a table extension in ModelA and a form extension in ModelB. The correct answer is that this is impossible: a Visual Studio project can belong to only one model. The developer must create two separate projects.
• Exam Trap 3: Physical Folder Placement Errors. If an extension element XML is copied manually into PackagesLocalDirectory\ApplicationSuite\ApplicationSuite\AxTableExtension\, the compiler will reject it or fail to track it because ApplicationSuite is sealed. All custom extensions must reside within the custom package directory (e.g., PackagesLocalDirectory\ContosoPackage\ContosoModel\AxTableExtension\).
• Exam Trap 4: Circular Model Dependencies. If ModelA references ModelB, and a developer attempts to add a reference from ModelB to ModelA to access a newly created helper class, Visual Studio will block the operation with a circular dependency violation.