Best practices

Path: Development > Rules, guidelines, and best practices > Best practices · tier official · system development · narrative reviewed (checked by Opus)

Overview

This section collects guidance for developers building Business Central extensions. Five subtopics cover AL code (naming, file structure, formatting, obsolete attributes, Marketplace validation rules), restrictions (what AL code should avoid), testing, performance and security.

Three pages sit directly in the hub. One explains how to add telemetry signals to an application. One lists requirements for connectivity apps published to Marketplace. One defines how to write user scenario documentation so Microsoft validation teams can test an extension.

Start with AL code best practices for the baseline conventions. Then read testing and the scenario documentation page if you plan to publish to Marketplace. Use the performance, security and telemetry pages when troubleshooting or hardening an extension.

Key points

• AL code guidance covers naming conventions, file structure, formatting, prefix and suffix rules, and deprecation with obsolete attributes and CLEAN symbols.
• Restrictions: avoid UI in web service objects, the obsolete OnCompanyOpen event, and the deprecated OnBeforeCompanyOpen and OnAfterCompanyOpen events, to prevent sign-in errors, login slowdowns and web service exceptions.
• Testing uses a Customer Rewards sample extension tested with the Application Test Toolkit, plus pre-submission checks before Marketplace validation.
• Performance guidance gives a measure, locate, eliminate approach, diagnostic tools, and advice on pages, web services, reports, AL code and data access.
• Security covers authentication, authorization, encryption, auditing and change logging, and using Azure Key Vault for secrets when calling external web services.
• The telemetry page describes logmessage, sendtracetag, custom events, Application Insights integration, event log and feature telemetry.
• Connectivity apps need app compatibility, 85% test coverage, sales volume thresholds and regulatory compliance such as PSD2 licensing. The page references 2022 release wave 2.
• User scenario documentation needs step-by-step guides with screenshots, prerequisite steps, demo data and rapid start packages.

Subtopics

• AL code (4 pages)
• Restrictions (3 pages)
• Testing (3 pages)
• Performance (2 pages)
• Security (2 pages)

More Learn pages

• Developing telemetry into your Business Central application: This article describes how to add code to application objects that enables you to gather telemetry.
• Requirements for connectivity apps: Learn about connectivity apps, how they can increase business productivity, and how to get your app listed as a connectivity app.
• User scenario documentation: Describing how to generate the required scenario document to get your app approved for Marketplace.

Videos, posts and code changes

Linked by a Haiku matcher with a grounding quote from the item’s summary (link/topics.ts); machine-generated.

• #10675 Temporarily suppress AS0072 (ObsoleteTag 29.0) on 10 Base App elements for v30 prep (code change): “Pragmas temporarily suppress the AppSourceCop AS0072 error on elements”
• #11870 Reduce allocations in the “Export to Execl” scenario (code change): “The Export to Excel scenario now allocates less memory by reusing objects”
• #108 Complete AL review knowledge readiness (code change): “AL review knowledge expanded with new guidance on telemetry, Query objects, AppSource, breaking changes, and security”
• #114 Document the skill-vs-knowledge boundary so BC facts land in knowledge files (code change): “Skills should contain mechanics while knowledge files hold Business Central facts”
• #130 knowledge(performance): align SetLoadFields placement with AL Guidelines (code change): “align SetLoadFields placement with AL Guidelines by placing filters before SetLoadFields”
• #132 Refine self-improvement review guidance (code change): “BCQuality guidance refined to reduce false positives in event handling, UI testing, performance analysis”
• #133 Add TransferFields SkipFieldsNotMatchingType guidance (code change): “Good pattern: use explicit field-by-field mapping with Evaluate for type conversions to fail loudly”
• #135 Correct severe misconception about SetCurrentKey in the knowledge base (code change): “Using SetCurrentKey when sorting is unnecessary hurts performance”
• #137 Add community guidance and review support for Business Central agents (code change): “20 community-authored guidance rules covering agent registration, permissions, profiles”
• #175 9 AL/BC patterns: document distribution, price calculation & barcode extensibility (code change): “Nine new AL/BC patterns document best practices for document distribution”
• #183 Add reporting review guidance and evaluation fixtures (code change): “Included bad and good AL code samples for each rule to guide developers”
• #196 Strengthen review contracts and add AL reliability guidance (code change): “Strengthen review contracts and add AL reliability guidance. Adds seven AL reliability rules”
• #98 Add P0 event and interface compatibility knowledge (code change): “Guidance added for event and interface compatibility patterns, covering enum unknown value handling”
• Introducing the “No Shortcuts” Series: The 100% Correct Way to Develop for Business Central (community post): “Shortcuts in development create technical debt and upgrade problems tomorrow”
• BC Friday Tips #68 Always Use Field Validation (community post): “Always validate fields to ensure all business logic executes properly”

Source: Microsoft Learn (CC BY 4.0). Descriptions are Learn’s own.