Below you will find a checklist of all requirements that you must meet before submitting an extension for validation. You will also find a description of how the Business Central Validation team is performing technical and manual validation and how you can implement a validation pipeline to perform the same technical validation yourself.
Technical Validation Checklist
If you do not meet these mandatory requirements, your extension will fail validation. To get code validation helping you bring your extension package to AppSource, you can enable the AppSourceCop code analyzer. For more information, see Using the Code Analysis Tool.
|Develop your extension in Visual Studio Code.||Developing AL Language extensions|
|The app.json file has mandatory settings that you must include. Here you can also read more about dependency syntax and multiple countries per a single app syntax.||Mandatory app.json settings|
||Use the format
|Remote services (including all Web services calls) can use either HTTP or HTTPS. However, HTTP calls are only possible by using the HttpRequest AL type.||Guidance on HTTP use|
|The .app file must be digitally signed.||Signing an APP Package File|
|The user scenario document must contain detailed steps for all setup and user validation testing.||User Scenario Documentation|
|Set the application areas that apply to your controls. Failure to do so will result in the control not appearing in Dynamics 365 Business Central.||Application Area guidance|
|Permission set(s) must be created by your extension and when marked, should give the user all setup and usage abilities. A user must not be required to have SUPER permissions for setup and usage of your extension.||Exporting Permission Sets
Managing Users and Permissions
|Before submitting for validation, ensure that you can publish/sync/install/uninstall/reinstall your extension. This must be done in a Dynamics 365 Business Central environment.||How to publish your app|
|Thoroughly test your extension in a Dynamics 365 Business Central environment.||Testing Your Extension|
|Do not use
|Include the proper upgrade code allowing your app to successfully upgrade from version to version.||Upgrading Extensions|
|Pages and code units that are designed to be exposed as Web services must not generate any UI that would cause an exception in the calling code.||Web Services Usage|
|You are required to prefix or suffix the Name of your fields and objects. This eliminates collision between apps.||Prefix/Suffix Guidelines|
|We strongly recommend you are using automated testing, using the AL Test Toolkit. You are not required to include the test package with your extension.||Testing the Advanced Sample Extension|
|DataClassification is required for fields of all tables/table extensions. Property must be set to other than
|You must use the Profile object to add profiles instead of inserting them into the Profiles table.||Profile Object|
||Placing Actions and Controls|
Technical validation performed by the Business Central validation team
The primary responsibility of the technical validation is to ensure that the Business Central online service is stable and that the apps can be installed and run without destabilizing the service.
The technical validation is for a large part automated and will validate the steps described in the technical checklist above through some pipelines.
The submitted apps will be extracted and investigated following this list:
- The apps are investigated. All dependencies must be included in the submission. We will lookup prior versions of the apps in the depot. If your app has a dependency on a third party app in AppSource, you should not include this, we will locate it in the depot. Any unresolved dependencies will cause the submission to be rejected.
- If the version numbers haven't changed and the countries haven’t changed, the validation is skipped and the apps will not be updated.
- App.json is investigated for mandatory fields. If mandatory fields are missing, the submission is rejected.
- Affixes for the submission are located. If affixes haven't been registered or cannot be located, the submission is rejected.
- Business Central Artifacts are located for the version the apps is submitted for (Current, NextMinor, or NextMajor).
- For every country in the submission list, we perform the same validation:
- A sandbox container based on the Business Central Artifacts with the right country version is created.
- Any dependency apps not included in the submission are installed. If any installation fails, the submission is rejected.
- In order of dependencies, all apps in the submission are tested using AppSourceCop analyzer. For more information, see AppSourceCop Analyzer
- If any breaking changes are identified, the submission is rejected.
- If mandatory affixes are not included on all object names, the submission is rejected.
- In order of dependencies, all prior versions of the apps are published and installed. If any installation fails, the submission is rejected.
- In order of dependencies, all new versions of the apps are published and upgrade is run (apps must be digitally signed, else they won’t install). If any installation/upgrade fails, the submission is rejected.
- A simple connection test is run; opening a role center and check simple actions and pages. If the connection test fails, the submission investigated and potentially rejected.
- If all country validations succeed and no errors are found then the submission is accepted.
Microsoft recommends that all partners are performing the same checks as described above before submitting apps for validation to maximize chances of validation success.
Running technical validation yourself
With the latest version of BcContainerHelper, you can run a single command, which should perform the same validation steps and give you a good indication of whether your apps will pass validation or not:
$validationResults = Run-AlValidation ` -licenseFile "path/url to license file" ` -validateCurrent ` -installApps @( "path/url to your foreign dependencies, apps which will not be part of the validation (or blank if this is the first)" ) ` -previousApps @( "path/url to your previous version of the .app files (or blank if this is the first)" ) ` -apps @( "path/url to the new version of the .app files" ) ` -countries @( "countries you want to validate against (f.ex. us,ca)" ) ` -affixes @( "affixes you own (f.ex. fab,con)" ) ` -supportedCountries @( "supported countries (f.eks. us,ca)" ) $validationResults | Write-Host -ForegroundColor Red
All array parameters can also be specified as a comma-separated string. For more information, you can also check this blog post Run-AlValidation and Run-AlCops.
Please include app and all library apps in both previousApps and apps and please include all countries on which you want to validate.
The Run-AlValidation cannot see whether the affixes to specify have been correctly registered with Microsoft using your MPN ID and app publisher name, please make sure registration is in place.
The Computer on which you run this command must have Docker and the latest BcContainerHelper PowerShell module installed and be able to run Business Central on Docker.
If you are having issues with Business Central on Docker, you might be able to find help here: https://freddysblog.com/2020/10/12/troubleshooting-business-central-on-docker.
You can use https://aka.ms/getbc?artifacturl=bcartifacts%2fsandbox%2f%2fus%2flatest to create an Azure VM, which has all prerequisites installed to run Business Central on Docker.
Microsoft recommends that all partners set up DevOps processes to ensure that this validation process happend automatically and regularly.
You can find resources for how to set up a build pipeline, which performs all these steps here: https://aka.ms/cicdhol and you can find sample repositories, performing these steps here:
- https://dev.azure.com/businesscentralapps/HelloWorld.AppSource (for Azure DevOps)
- https://github.com/BusinessCentralApps/HelloWorld.AppSource (for GitHub Actions)
Manual validation performed by the Business Central validation team
The primary responsibility of the manual validation is to ensure that the apps are working as described.
Manual validation is not done on all submissions. They will be done as sample tests.
For manual validation, we spin up a container with the right artifacts (same as used during technical validation) and the necessary apps are installed. Rapidstart packages needed for the manual test are installed.
The manual test validation document is run manually and if the document doesn’t match the app functionality the submission is rejected.
Microsoft recommends that all partners are performing the manual validation as the last check before submitting for validation.
This can be done either in online sandbox environments or in sandbox docker containers.