1.3 Base Application, System Application & AppSource

1.3 Base App, System App & AppSource Publishing Process

To build scalable, certified enterprise applications for Dynamics 365 Business Central, developers must understand the foundational structure of Microsoft's first-party application packages and navigate the rigorous technical validation pipeline required for Microsoft AppSource certification.

1. System Application vs. Base Application Architecture

Historically, the legacy Dynamics NAV application was a monolithic codebase where technical platform utilities and complex accounting logic were intertwined in massive objects (e.g., Codeunit 1 ApplicationManagement). Modern Business Central architecture splits the first-party application layer into two distinct packages:

+-----------------------------------------------------------------------+
|                   CUSTOM EXTENSIONS & APP-SOURCE APPS                 |
+-----------------------------------------------------------------------+
                                   │ Depends on
                                   ▼
+-----------------------------------------------------------------------+
|                   BASE APPLICATION (BaseApp.app)                      |
|   - General Ledger, Accounts Receivable, Accounts Payable             |
|   - Inventory Valuation, Warehousing, Supply Chain                    |
|   - Sales & Purchase Document Posting Pipelines (Codeunit 80 / 90)    |
|   - Manufacturing, Jobs/Projects, Service Management, Fixed Assets    |
+-----------------------------------------------------------------------+
                                   │ Depends on
                                   ▼
+-----------------------------------------------------------------------+
|                 SYSTEM APPLICATION (SystemApp.app)                    |
|   - Cryptography & Hashing (AES, SHA, RSA, X509 Certificates)         |
|   - Communication & Email (SMTP, Microsoft Graph, Exchange)           |
|   - Identity & Security (Azure AD User, User Permissions, OAuth2)     |
|   - Data Formats & IO (JSON, XML, CSV, TempBlob, Base64, Zip)         |
|   - Client Enhancements (Camera, Geolocation, Barcode Scanner)        |
|   - Diagnostics & Upgrade (Telemetry, Feature Management, Upgrades)   |
+-----------------------------------------------------------------------+

The System Application

The System Application is a modular, domain-agnostic layer that provides low-level technical capabilities and operating system abstractions:

• Modular Architecture: Composed of dozens of self-contained modules (e.g., Cryptography Management, Email, Azure AD Authentication, Guided Experience, Environment Information).
• The Facade Pattern: Each module exposes a single public API codeunit (the "Facade") that developers interact with, while internal logic is encapsulated within internal codeunits (Access = Internal). This prevents external extensions from coupling to volatile internal implementation details.
• Open Source on GitHub: Microsoft publishes the complete source code of the System Application on GitHub (microsoft/ALAppExtensions). The developer community can inspect code, report issues, and submit pull requests (contributing new features or bug fixes directly to the core platform).

The Base Application

The Base Application contains the complete enterprise business logic, accounting rules, posting state machines, and reporting models that define Business Central as an ERP system. It depends directly on the System Application for all underlying technical services.

2. Extension Manifest Anatomy: app.json

Every AL extension is declared and governed by a root configuration manifest file named app.json. This file establishes the unique cryptographic identity, dependencies, platform runtime targets, and security properties of the package.

{
  "id": "7c28f114-699e-4e4b-9e4a-569d251d7e29",
  "name": "Advanced Automated Logistics",
  "publisher": "Contoso Solutions Inc.",
  "version": "24.1.1004.0",
  "brief": "Streamlined warehouse logistics and automated package tracking for Business Central.",
  "description": "Comprehensive logistics management solution featuring real-time carrier tracking, automated shipping label generation, and advanced warehouse bin optimization.",
  "privacyStatement": "https://www.contoso.com/privacy",
  "EULA": "https://www.contoso.com/eula",
  "help": "https://www.contoso.com/support/logistics",
  "url": "https://www.contoso.com",
  "logo": "assets/contoso_logo_300x300.png",
  "dependencies": [],
  "screenshots": [],
  "platform": "24.0.0.0",
  "application": "24.0.0.0",
  "idRanges": [
    {
      "from": 50100,
      "to": 50149
    }
  ],
  "contextSensitiveHelpUrl": "https://www.contoso.com/help/{0}",
  "showMyCode": false,
  "runtime": "13.0",
  "target": "Cloud"
}

Critical Manifest Properties

• id (GUID): The immutable, globally unique identifier (UUID v4) of the application. Once published, this GUID can never change, or the system will treat the package as a completely unrelated new application.
• name & publisher: Human-readable solution name and organization. The combination of id, name, and publisher forms the unique identity triplet.
• version: A 4-part semantic version string formatted as Major.Minor.Build.Revision (e.g., 24.1.1004.0). Incremented on each deployment.
• idRanges: Defines the permitted integer ID range for custom objects (tables, pages, reports, codeunits, XMLports). Per-Tenant Extensions typically operate in the 50000..99999 range; AppSource ISVs purchase dedicated registered ranges (e.g., 1000000..1099999) from Microsoft.
• target: Specifies the compilation target. Must be set to "Cloud" for all AppSource apps and SaaS PTEs.
• application (not dependencies): Since Business Central 2020 release wave 2, the System Application and Base Application must not be listed as explicit dependencies. Reference them through the single "application" version property instead; dependencies is reserved for third-party and partner libraries. AppSourceCop enforces this with AS0085 (Use the 'application' property instead of specifying explicit dependencies) and AS0100 (The 'application' property must be specified in the app.json file).

3. AppSource Technical Validation & AppSourceCop Rules

Publishing an extension to Microsoft AppSource requires passing an automated and manual certification pipeline. Automated technical validation is enforced by the AppSourceCop code analyzer.

1. Mandatory Prefix and Suffix Reservation

To prevent global naming collisions across multiple ISV extensions installed on the same tenant, Microsoft requires all AppSource developers to register a 3-to-4 character prefix or suffix in Microsoft Partner Center (e.g., ABC or CONT).

• Enforcement Rules (AS0011, AS0013): Every object name, table field, page action, global variable, and enum value must start or end with the registered prefix/suffix.
  • Valid Table Extension Field: field(50100; "ABC_CarrierTrackingNo"; Code[30]) { ... }
  • Invalid Table Extension Field: field(50100; "CarrierTrackingNo"; Code[30]) { ... } (Fails AppSourceCop with rule AS0011).

2. Strict Prevention of Breaking Changes

When publishing version updates to an existing AppSource application, AppSourceCop compares the new source code against the previous baseline version (baselinePackage in settings.json). The analyzer immediately rejects the package if breaking changes are detected:

3. Additional Quality Analyzers

• CodeCop: Enforces AL coding guidelines, naming conventions, and variable scoping.
• UICop: Verifies that all page fields and actions have non-empty ToolTip properties and appropriate ApplicationArea assignments for search discovery.
• PTECop: Used for Per-Tenant Extensions to ensure compatibility with tenant data isolation rules.