Bring your

Financials app

into Microsoft

AppSource

Step 3.1 -

Develop the

technical

aspects of

your app

White paper

Dynamics 365 for Financials App Team

February 2017

Contents Introduction: Bring your Financials app into Microsoft AppSource ....................................................... 4

This document .................................................................................................................................... 4

Readiness and further information .................................................................................................... 5

Supported product versions ............................................................................................................... 5

Checklist .................................................................................................................................................. 6

App requirements and recommendations ............................................................................................. 7

Extensions package requirements ...................................................................................................... 7

1.1 The package must be digitally signed ....................................................................................... 7

1.2 The package manifest must contain required attributes ......................................................... 8

1.3 All extensions identified in the manifest as dependencies must be validated ........................ 9

Development requirements ............................................................................................................... 9

2.1 The C/AL code must pass the required code analysis tests...................................................... 9

2.2 The .NET Add-ins included in the extension must be compiled with at least the .NET Framework 4.5

and must pass the required code analysis tests ........................................................................... 10

2.3 Sign assemblies with a strong name ....................................................................................... 11

2.4 New application objects must use assigned number range ................................................... 11

2.5 Pages and codeunits that are designed to be exposed as web services must not generate any UI

that would cause an exception in the calling code ...................................................................... 11

2.6 Server-side .NET add-ins must not generate any UI ............................................................... 12

2.7 Remote services use message protection .............................................................................. 13

2.8 Including additional files into the extension .......................................................................... 13

User assistance and product documentation requirements ............................................................ 14

3.1 Provide tooltips and a setup and user guide .......................................................................... 14

User experience requirements ......................................................................................................... 15

4.1 The app must comply with core Dynamics 365 for Financials user-experience guidelines ... 15

4.2 An app that restricts the functionality of Dynamics 365 for Financials must document the

restriction ..................................................................................................................................... 17

Translation and localization requirement ........................................................................................ 18

5.1 The app must contain translations for targeted country/region languages .......................... 18

Performance and stability requirements ......................................................................................... 18

6.1 The extension package can be successfully deployed ............................................................ 19

6.2 Successfully complete end-to-end key usage scenarios ......................................................... 19

6.3 The app does not consume excessive system resources ....................................................... 20

6.4 The app can be successfully removed .................................................................................... 20

Upgrade and maintenance requirements ........................................................................................ 20

7.1 Upgrade code required for all schema changes ..................................................................... 21

7.2 The ISV must update the file version and public key when making changes to .NET Framework add-

in assemblies ................................................................................................................................ 21

Appendix A: Rules and Guidelines for C/AL Code ................................................................................ 22

Critical errors: ................................................................................................................................... 22

Important errors: .............................................................................................................................. 22

Appendix B: Unsupported .NET methods ............................................................................................. 23

System namespaces: ........................................................................................................................ 23

System.Security ............................................................................................................................ 25

System.ServiceModel ................................................................................................................... 25

Appendix C: Dynamics 365 for Financials usage verification test ........................................................ 27

Create Sales Order ............................................................................................................................ 27

Edit Sales Order ................................................................................................................................ 29

Post Sales Order ............................................................................................................................... 30

Appendix D: Fully test extension before submitting ............................................................................ 34

Appendix D: Fully test extension before submitting ............................................................................ 35

Introduction: Bring your Financials app into

Microsoft AppSource

There are plenty of benefits of using Microsoft Dynamics 365 for Financials as a platform for app builders:

• Enrich Dynamics 365 for Financials, a proven Microsoft online solution, with your expertise. • Leverage the Dynamics 365 brand – a brand that millions of users know and trust. • Reach more customers for your business apps with Microsoft AppSource. • Achieve more from a platform that delivers a modern experience and offers scale. • Bundle with intelligent business apps such as Microsoft PowerApps, Microsoft Flow, Power BI,

Cortana Intelligence, and many more.

Go through the following steps to bring your Financials app into Microsoft AppSource:

1. Create your accounts. 2. Engage with us about your app idea. 3.1 Develop the technical aspects of your app 3.2 Develop the marketing aspects of your app 4. Publish your app.

The typical application process and timeline will be as follows:

This paper outlines step 3.2. on how to develop the technical aspects of your app. To access the

documentation about the other steps, please look at aka.ms/AppsForFinancials.

This document This document describes the requirements that an independent software vendor’s (ISV) extension must

meet in order to be validated as an app for Dynamics 365 for Financials.

The goals of the test are to increase the quality of apps that run in Dynamics 365 for Financials and to

assure the market that ISV apps meet technical requirements that ensure a high standard. The test

guidelines are designed to walk you through the test process and to help you ensure that your app can

meet the requirements. The test guidelines are described in individual, subject-based modules and provide

detailed information about the summary and intent, additional resources, compliance, test methodology,

and criteria for passing. Some guidelines may be common to other Microsoft Dynamics tests.

To pass the test, you must demonstrate the development quality of your app, the reliability to run in a

multitenant cloud deployment, and your ability as a software company to maintain and enhance the app in

the future. The test is administered and conducted by Microsoft or a third-party vendor and includes a

technical review and an in-lab inspection.

This document contains the following sections:

• The Checklist provides you with an overview of the must-requirements before submitting your

extension via the Azure Publishing Portal. If any of these must-requirements are not met, the app

will fail the technical validation. The app will need to be updated to fix the issues and be

resubmitted which will start the validation process over from the beginning. All criteria will be

explained in more detail in the sections afterwards.

• The App Requirements and Recommendations section defines each requirement and

recommendation category, how these requirements and recommendations are tested, and what

you can do to ensure that your app meets the requirements.

• In the different Appendix, you can find information to C/Al Code, unsupported .NET methods and

usage verification tests.

We welcome your comments and suggestions. Send an email message to

NAVExtGuidelines@microsoft.com with your feedback.

Readiness and further information Learn how to build an app by going through the material in our Learning Plan (select Financials and

developer as a role) on the Dynamics Learning Portal (DLP).

• For more information about the functionality of Dynamics 365 for Financials, see the Dynamics 365 for Financials page.

• For more information on extensions in Dynamics 365 for Financials, see the Customizing Dynamics 365 for Financials using Extensions page.

• For more information on extensions, see the Extending Microsoft Dynamics NAV Using Extension Packages page.

• For more information about the Microsoft Partner Program, see the Microsoft Partner Network page.

Supported product versions Extension packages that are submitted for testing must run on the most current version of Dynamics

365 for Financials.

Checklist The following is a checklist of all requirements that you must meet before submitting an extension for

validation. If you do not meet these mandatory requirements, your extension will fail validation.

Requirement: Example/Guidance:

All correct information needs to be in your manifest. The Name, Description, Version, and Publisher should all correctly be there. There must be links for the following: Terms & Conditions; Privacy Statement; Website; and Help. All links must go directly to the site/page they pertain to.

For example, Help link must go to your Help page containing information about setup and usage. It should not go to the general website or the support/contact us page. Have a look at 1.2 & 3.1 for more detail.

Do not hard code any dates/timestamps. With different countries having different formats, hardcoding these will result in build check-in errors.

Use the DMY2DATE function for doing anything related to date/time.

Remote services (includes all Web Services calls) must use message protection. Check any remote services calls that exchange sensitive data to verify they have implemented message protection

If you do not use message protection, valid documentation as to why is Required. Refer to 2.7 for more detail.

The .NET Add-ins included in the extension must be compiled with at least the .NET Framework 4.5 and must pass the required code analysis tests.

Refer to 2.2 for more detail.

Do not zip up libraries, DLL’s, etc. All should be included in the extension as an additional file

Refer to 2.8 for more detail

All libraries supplied with the extension must be signed. Refer to 2.3 for more detail.

The navx file must be digitally signed. Refer to 1.1 for more detail.

User scenario document must contain detailed steps for all setup and user testing. Please use a step by step approach as if you were walking through setup and testing yourself (recording the steps along the way).

Refer to Appendix C for example of an acceptable user scenario doc

Make sure to define application areas for your controls on the page. If not done, the controls will not appear in D365 resulting in validation failure

The controls have to be set with an application area of #Basic, #Suite, or #All. Refer to 6.2 for more detail.

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

Permission Set MSDN1 Permission Set MSDN2 Permission Set MSDN3

Fully test your extension using the partner D365 environment. Instructions for environment setup can be found here

Refer to Appendix D for more detail

App requirements and recommendations The Dynamics 365 for Financials app guidelines help ensure that apps interoperate with Dynamics 365 for

Financials without causing problems or errors. Microsoft and third-party test vendors worked together to

define the minimum requirements that an app must meet to operate successfully with Dynamics 365 for

Financials.

Note: The requirements do not validate the correctness or relevance of app functionality.

This section describes the requirements and recommendations and the procedures for verifying that each

requirement is met. In this document, the word must in the text of a requirement means that the item or

feature is required. The word should means that the item or feature is recommended and its inclusion is a

best practice, but it is not strictly required. These recommendations may be considered for inclusion as

requirements in later versions of this test.

Extensions package requirements The extension package must meet the following requirements:

• 1.1 The package must be digitally signed

• 1.2 The package manifest must contain required attributes

• 1.3 All extensions identified in the manifest as dependencies must be certified

1.1 The package must be digitally signed

SUMMARY AND INTENT: The extension package and any library package must be digitally signed in order to

uniquely identify the publisher of the extension and ensure the integrity of the package against tampering

or corruption.

RESOURCES: See Authenticode in the MSDN Library.

For a list of trusted certification authorities (CA) see Microsoft Root Certificate Program Members.

HOW TO COMPLY: Sign the package file (.navx) and library package files that you will submit for validation

with a security certificate obtained from a third-party trusted certification authority.

TEST METHODOLOGY: The tester will verify the package files (.navx) are signed by a trusted third-party

certification authority and that the signature is valid.

CRITERIA FOR PASSING: This requirement is mandatory. If the extension package files (.navx) are not

signed by a trusted certification authority or the signature is not valid, it will fail the test.

1.2 The package manifest must contain required attributes

SUMMARY AND INTENT: The extension package manifest must contain valid values for the attributes that

will be required for publishing to AppSource. Providing these required attributes ensures a consistent

quality experience for Dynamics 365 for Financials users.

RESOURCES: See Microsoft Dynamics NAV Extension Packages in the MSDN Library. You can also refer to

here and here.

HOW TO COMPLY: Provide valid values for the following manifest attributes. In order to be valid, the

values must accurately represent the extension, follow any requirements listed in the description below,

not reference Microsoft Dynamics NAV, and not contain content that a reasonable person would consider

obscene or offensive.

Attribute Description

Id An identifier that uniquely identifies the extension. Must be unique for all

certified extensions unless the extension is an upgraded version of a

previously certified extension.

Name The name of the extension. The name of the extension must be unique

for all certified extensions.

Publisher The publisher of the extension.

Description The full description of the extension.

Brief The brief description of the extension. Use the Summary field from

AppSource

Version Version string in the format of Major.Minor.Build.Revision. If the extension

is an upgraded version from a previously certified extension, then the

value must be incremented from the previous version.

Compatibility Id Version string in the format of Major.Minor.Build.Revision. This value

defines the compatibility ID of the extension.

Logo The primary image file for the extension. A single image file that will be

the primary image displayed in the store. The image must be 240 x 240

pixels. The file can be provided as a png or jpg file.

EULA A link to the end-user license agreement for the extension.

Help A link to a site that contains setup and usage information for the

extension (not to the support/contact site)

Privacy Statement A link to the privacy statement for the extension.

Website A link to the general website for your company

TEST METHODOLOGY: The tester will review the attributes of the extension for accuracy as well as

obscene or offensive content. The values for the Name, Version and Publisher attributes must match the

Title, Version and Publisher Short Name provided for the offer in the Azure Publisher Portal.

CRITERIA FOR PASSING: This requirement is mandatory. If the extension package files manifest doesn’t

contain a valid value for all of the specified attributes, it will fail the test.

1.3 All extensions identified in the manifest as dependencies must be validated

SUMMARY AND INTENT: An extension may have been built on top of functionality added by another

extension, in which case the extension takes a dependency on the other extension. The extension that the

dependency is taken on must be validated prior to the extension with the dependency, or be included as a

library extension that will go through validation at the same time.

RESOURCES: See How to: Develop an Extension in the MSDN Library.

HOW TO COMPLY: Verify that all extensions that the package file (.navx) has a dependency on are

validated or included as a library extension.

TEST METHODOLOGY: The list of extension dependencies will be obtained from the package file’s (.navx)

manifest and verified as having already been validated and published, or it will be validated as a library

extension.

CRITERIA FOR PASSING: This requirement is mandatory. If the extension’s manifest contains a

dependency to an extension that is not certified or not included as a library extension, it will fail the test.

Development requirements Your extension must meet the following requirements:

• 2.1 The C/AL code must pass the required code analysis tests

• 2.2 The .NET Add-ins included in the extension must be compiled with at least the .NET Framework 4.5

and must pass the required code analysis tests

• 2.3 Sign assemblies with a strong name

• 2.4 New application objects must use assigned number range

• 2.5 Pages and codeunits that are designed to be exposed as web services must not generate any UI that

would cause an exception in the calling code

• 2.6 .NET objects that run on Microsoft Dynamics NAV Server must not generate any UI

• 2.7 Remote services use message protection

2.1 The C/AL code must pass the required code analysis tests

SUMMARY AND INTENT: Extensions that include C/AL code must pass a code analysis test to verify

compatibility, security, performance, and stability. The analysis will verify conformance to a defined set of

rules and guidelines designed to minimize any negative impact on the deployment.

RESOURCES: See NAV Development Getting Started in the MSDN library.

See list of rules and guidelines in Appendix A.

HOW TO COMPLY: When you develop the C/AL code using C/SIDE, follow the rules and guidelines

referenced in Appendix A of this document.

To pass this requirement, you must act on all critical errors for all issues. It is good practice to act on all

issue types of all importance levels. You must provide an explanation and justification for any unresolved

code analysis errors.

Note: Explaining and justifying the reason for the violation does not guarantee that a waiver will be granted

by Microsoft.

TEST METHODOLOGY: The C/AL code will be reviewed for conformance with the specified rules and

guidelines. If the review identifies any code errors without sufficient explanation and justification, the

extension doesn’t pass code analysis.

CRITERIA FOR PASSING: This requirement is mandatory. If the extension package contains code that

doesn’t pass code analysis, it will fail the test.

2.2 The .NET Add-ins included in the extension must be compiled with at least the

.NET Framework 4.5 and must pass the required code analysis tests

SUMMARY AND INTENT: Extensions that include new .NET Framework assemblies as add-ins must use at

least the .NET Framework 4.5, must pass the code analysis test provided by Visual Studio and Microsoft

FxCop, and must not use any unsupported .NET classes. Visual Studio includes code analysis tools that

check .NET Framework assemblies for conformance to .NET Framework design guidelines. In addition, the

code in any server-side .NET add-in assemblies must not use any unsupported .NET classes that could lead

to security, performance, or stability issues.

RESOURCES: See Analyzing Managed Code Quality by Using Code Analysis or FxCop in the MSDN library, or

see the list of unsupported .NET Framework classes in Appendix B.

HOW TO COMPLY: When you develop assemblies using Visual Studio, use the code analysis tools and

default rulesets included in Visual Studio and Microsoft FxCop to identify issues and implement the relevant

changes. For any assemblies that will be included in server-side .NET add-ins, verify that you are not using

any of the unsupported classes.

To pass this requirement, you must act on all critical errors for all issues, errors for security issues, and use

of any unsupported classes. It is a good practice to act on all issue types of all importance levels. For

example, you can suppress an error by explaining the reason for violating the rule and why it is not a valid

issue. You can suppress a violation. For more information, see In-Source Suppression Overview. You must

provide information about in-source suppressions or use of any unsupported classes.

Note: Suppressing an error and explaining the reason for the violation does not guarantee that a waiver will

be granted by Microsoft.

TEST METHODOLOGY: Visual Studio/FxCop and the default rulesets will be used to analyze the .NET add-

in assemblies. If there are any critical errors, any security errors, or use of unsupported classes, the ISV

must provide a written explanation and justification in the tool or in a separate document.

CRITERIA FOR PASSING: This requirement is mandatory. If the extension does not pass this requirement,

it will fail the test.

2.3 Sign assemblies with a strong name

SUMMARY AND INTENT: This requirement is included for security purposes. You can ensure that a name

is globally unique by signing an assembly with a strong name. In particular, strong names satisfy the

following requirements:

• Guarantees name uniqueness by relying on unique key pairs.

• Protects the version lineage of an assembly.

• Provides a strong integrity check.

RESOURCES: The Sn.exe tool that is provided with Microsoft Visual Studio and with the .NET Framework

4.5 supports the proper use of strong names. For more information about the Strong Name tool, see Strong

Name Tool (Sn.exe).

HOW TO COMPLY: You must use strong naming for managed assemblies included as .NET add-ins in the

extension package. If your extension uses a vendor or third-party assembly, then the assembly must also be

signed and you must have the proper licenses.

TEST METHODOLOGY: The Sn.exe tool that is provided with Visual Studio will be used to verify the proper

use of strong names.

CRITERIA FOR PASSING: This requirement is mandatory. If the solution does not use strong naming for

managed assemblies, then it will fail the test.

2.4 New application objects must use assigned number range

SUMMARY AND INTENT: When an ISV extension is registered, Microsoft Dynamics Sales Operations will

assign a specific range of object numbers for that extension to use. All new objects that are installed by the

extension must use this number range.

RESOURCES: See the Microsoft Dynamics 365 for Financials App - Extension Questionnaire and Object

Range Request Form, which is provided to you by your Regional Operations Center when you “List an app”

on AppSource, to obtain a number range for objects in your extension.

HOW TO COMPLY: The objects added by the extension must use your assigned extension range between

70 and 75 million.

TEST METHODOLOGY: The ID values of the new objects included in the extensions will be verified against

the ISV assigned range for extensions.

CRITERIA FOR PASSING: This requirement is mandatory. If the extension adds objects that are outside of

their assigned object number range, then it will fail the test.

2.5 Pages and codeunits that are designed to be exposed as web services must not

generate any UI that would cause an exception in the calling code

SUMMARY AND INTENT: When writing code for web services, you must not use end-user confirmation

dialog boxes, message boxes, or any other page constructs in the code. Because a web service runs

independently of a user interface, running this type of code causes the code to throw an exception. The

exception can be caught and handled, but the web service will not complete.

RESOURCES: For more information, see Microsoft Dynamics NAV Web Services in the Microsoft Dynamics

NAV Developer and IT Pro Documentation in the MSDN Library.

HOW TO COMPLY: Ensure that code for pages and codeunits that are being exposed as web services do

not use any end-user confirmation dialog boxes or message boxes.

TEST METHODOLOGY: To verify this requirement, the following tests will be performed:

1. Identify the pages and codeunits that are exposed as web services during the installation of the

extension.

2. Using code inspection, verify that functions from the following table are not used by the pages and

codeunits published by the installation without conditional code that is based on

GUIALLOWED=FALSE or CurrFieldNo=0 circumventing their call.

C/AL function Applies to

CONFIRM Codeunit/page

STRMENU Codeunit/page

(Form RunModal) Page

Page of type Confirmation Dialog Page

(Request form) Page

ERROR Codeunit/page

BEEP Codeunit/page

YIELD Codeunit/page

Additionally, when running the page or codeunit as a web service, the following exception should never

occur:

Microsoft.Dynamics.Nav.Types.Exceptions.NavNCLCallbackNotAllowedException: Callback functions are not

allowed.

CRITERIA FOR PASSING: This requirement is mandatory. If the extension uses end-user confirmation

dialogs or message boxes in the code that is exposed as a web service, then it will fail the test.

2.6 Server-side .NET add-ins must not generate any UI

SUMMARY AND INTENT: Any .NET Framework-based objects that allow a user interface to be generated

cannot be run on Dynamics 365 for Financials. Because Dynamics 365 for Financials runs as a service, it is

running in the security context of a service account that has limited permissions for UI objects.

RESOURCES: For more information, see Extending Microsoft Dynamics NAV Using Microsoft .NET

Framework Interoperability in the MSDN Library.

HOW TO COMPLY: Ensure that only in-process .NET Framework objects with no user interface are

included in the extension.

TEST METHODOLOGY: Run the scenarios that are provided with the documentation with .NET

Framework-based objects that target Dynamics 365 for Financials and verify that no errors or dialog boxes

or pages are displayed, stop responding, or exit unexpectedly.

CRITERIA FOR PASSING: This requirement is mandatory. If the extension has .NET Framework-based

objects that generate a user interface and target Dynamics 365 for Financials, then it will fail the test.

2.7 Remote services use message protection

SUMMARY AND INTENT: The remote services used by the extension must be configured using message

protection to avoid disclosure of sensitive data. Message protection includes mechanisms that protect

sensitive data in transit over a network from unauthorized access or modification.

RESOURCES: For more information, see Security Fundamentals for Web Services –Message Protection in

the MSDN Library.

HOW TO COMPLY: Ensure that all remote services used by the extension are implemented with message

protection. The message protection can use either message security or transport security (that is, HTTPS) to

encrypt the messages. An exemption may be granted if the remote service provides public information to

anonymous users that isn’t considered sensitive. You must provide information on the service being used

and the type of data being exchanged in order to be granted any exemptions.

TEST METHODOLOGY: To verify this requirement, the remote services used by the extension will be

checked to verify they have implemented message protection.

CRITERIA FOR PASSING: This requirement is mandatory. If the extension is using a remote service without

message protection and a valid exemption hasn’t been provided, then it will fail the test.

2.8 Including additional files into the extension

SUMMARY AND INTENT: Do not zip up libraries, Dll’s, etc. They should be included in the extension

as an additional file

RESOURCES: See Control Add-Ins in the MSDN library

HOW TO COMPLY: Following are recommendations on how to comply

1) Server-Side .NET Interop Types: a. The DLL is a fully functional .NET library that they wish to reference from within AL code that they

have included in their package. b. It needs to be a strong name signed binary preferably targeting the same version of the .NET

framework as us. (currently 4.5.*) c. Should not be ‘zipped’, can just be included directly as a source

d. Inclusion of these types denotes inspection into the package or even the dll’s to ensure no misuse is going on (direct SQL calls, strange filesystem access, etc.)

2) Control Add-Ins: a. The DLL is nothing but a single .NET interface type that describes the public interface for a java script

control that will be displayed to users on pages. b. Should be ‘zipped’ and follow the general overview/walkthrough as described here: Control Add-Ins

with one exception: i. When completed, ‘normal’ control add-ins say to zip up the source artifacts (manifest,

script, etc) separate from the interface (DLL), and import the types into NAV individually. For extensions, the source artifacts and the interface should be included in the SAME zip file. This is then added to the list of sources included in the extension package.

c. The ‘name’ of the control add-in (specified in the [ControlAddInExport] attribute in the interface) needs to match the name of the DLL.

d. There are 2 types of control add-ins; the newer java script ones, which are supported by all clients, and the older .net-only ones, which are only supported on the RTC (desktop client) and should not be accepted for Dynamics365.

User assistance and product documentation requirements Your app must comply with the following requirements:

• 3.1 Provide tooltips and a setup and user guide

3.1 Provide tooltips and a setup and user guide

SUMMARY AND INTENT: ISV partners and customers who deploy an app must be able to successfully set

up the app for use in Dynamics 365 for Financials. Your documentation must provide information that

allows partners and customers to successfully set up and use your app. Your documentation must also

provide information to users about how to use the app functionality. It is recommended that you use field

tooltips to provide users with information within the application.

RESOURCES: None

HOW TO COMPLY: Provide adequate setup and user documentation to enable a partner or a customer to

implement your app in Dynamics 365 for Financials. The documentation must be specific to Dynamics 365.

This can take the form of one document, or you can also refer to separate documents for additional

information. We recommend that you use one of the following formats: a Microsoft Word document, .pdf,

or HTML page.

A compliant guide contains the following sections:

• Description of the app, which describes the problem that the app solves.

• Setup and configuration tasks and walkthroughs.

• Operational checklist, which includes information about performing daily, monthly, and annual

procedures; and other related tasks.

The app should provide tooltips that provide sufficient user information about the app fields.

TEST METHODOLOGY: The documentation will be reviewed to verify that you have included adequate

information.

Note: The quality and technical accuracy of the information will be reviewed as it pertains to the set up and

testing of the app.

CRITERIA FOR PASSING: This requirement is mandatory. If the solution documentation does not include a

setup and user guide, then it will fail the test.

User experience requirements Your app must comply with the following requirements:

• 4.1: The app must comply with core Dynamics 365 for Financials user experience

guidelines

• 4.2: An app that restricts the functionality of Dynamics 365 for Financials must

document the restriction

4.1 The app must comply with core Dynamics 365 for Financials user-experience

guidelines

SUMMARY AND INTENT: Users of your app must have a user experience that is consistent with Dynamics

365 for Financials. It is important that users can reuse the knowledge they build from using standard

Dynamics 365 for Financials and expect to complete similar tasks in your app by using the same user-

interface elements and the same interaction steps as in the standard application. Therefore, the user

interface for your application must comply with the Dynamics 365 for Financials user-experience guidelines.

Note: This requirement does not apply to user interfaces that are designed for special devices, such as

handheld scanners or cash registers. Additionally, there may be other justifications for deviating from the

standard user-experience guidelines. You must include these justifications with the application when you

submit it for testing. The justifications will be evaluated during the test process.

RESOURCES: See the Page types and templates section of the User Interface Design Guidelines in the

MSDN Library. Additional Dynamics 365 for Financials user-experience guidelines are being developed and

will be available in the future.

HOW TO COMPLY: Observe the following user-experience requirements. If your user experience deviates

from these requirements, then you must prepare a justification for the deviation. Include this justification

in your software submission package. Some requirements are specific to the Dynamics 365 for Financials

Web client or the Dynamics 365 for Financials Tablet client. If no client is specified, the requirement applies

to all clients.

1. Role Center pages added or modified by the solution: 1.1. There must be no more than 5 cue groups (that is, titled containers for cues) on the Role Center.

1.2. Each cue group must contain 1 to 6 cues.

1.3. The Role Center must show at least 1 chart part.

1.3.1. A justification can be provided stating why a specific Role Center should not show any chart parts. For

example: “The service technician user profile will only give access to basic workflows involving time

registration and therefore only needs to show a list part with the list of time registered this week.”

1.3.2. If no chart part is shown, there must be at least 1 part of another type.

1.3.3. (Tablet client only) Role Center parts must be sequenced to show a chart part first (vertically from top to

bottom).

1.4. (Tablet client only) Role Center parts must not have more than 7 actions and action groups at the first level,

and must not have more than 12 actions and action groups in total.

1.5. All links in the navigation pane must open a list place or filtered view.

1.6. (Web client only) There must be a Home activity button in the navigation pane with the most frequently

used lists/views.

1.7. (Web client only) The navigation pane must contain no more than 8 activity buttons, not counting the Home

and Departments activity buttons.

1.8. (Web client only) The Home button and each (optional) activity button must show a list of navigation items

that is short enough to not introduce a vertical scroll bar in the navigation pane when it displays with all list

place views expanded, in a window with a height of 1024 pixels.

2. Ribbon on pages added or modified by the solution (Web client only):

2.1. The Home ribbon tab must contain promoted actions, related information, and reports when these are

defined by the page. Only Role Center pages do not have a Home ribbon tab.

2.1.1. If a page has New Document items defined, at least 1 and up to 5 of the most frequently used items

must be promoted to the New group.

2.1.2. If a page has application actions defined, at least 1 and up to 5 of the most frequently used actions

must be promoted to the Process group or a custom category.

2.1.3. If a page has related information items defined, at least 1 and up to 5 of the most frequently used items

must be promoted to the Process group or a custom category.

2.1.4. If a page has reports defined, at least 1 and up to 5 of the most frequently used reports must be

promoted to the Reports group or a custom category.

2.2. The New and New Document groups must contain only actions that open up a new window from which the

user can create a new entity.

2.3. No group on the Home tab must contain more than 9 items, not counting items placed inside drop-down

menus.

3. List and Worksheet Pages added or modified by the solution:

3.1. (Tablet client only) Actions that act in relation to a specific row must not appear in the

page’s action pane. To ensure this, the action property ‘Scope’ must be set to ‘Repeater’.

4. Card, Document, and ListPlus pages added or modified by the solution:

4.1. The Document page type must be used only for entities that have a transactional or

statutory aspect.

4.1.1. Documents must have a single Lines grid in the second section.

4.2. The Card page type must be used only for pages that display master, reference, or setup

data.

4.2.1. Card pages may have sections (FastTabs) with a grid to represent a repeating field. To

avoid confusion with the lines on Document pages, such sections must be named to

reflect the data they display and not be entitled Lines.

4.3. The ListPlus page type must not be used for entities for which the Card or Document page

type is designed.

4.3.1. A ListPlus page may—as needed—contain any number of sections with fields or grids.

4.4. All top-level sections on a page (FastTabs) must show a title. Field groups within a section

need not be titled.

4.5. A page section with fields (and not a grid) must by default show a maximum of 16 fields.

4.5.1. (Windows client only) A FastTab with fields must have between 1 and 5 fields displayed as

Summary Values in the FastTab’s header. This is displayed when the FastTab is

collapsed.

4.5.2. (Windows client only) Within a FastTab, fields that are rarely needed by the user must be

marked Additional and made available via the Show more fields option.

4.6. (Windows client only) Card and Document pages must not display Limit Totals To by default.

4.7. Pages of type Card, Document, and ListPlus must not directly contain a Repeater group, but

may contain a subpage that in turn has a Repeater group.

TEST METHODOLOGY: To verify this requirement, the user experience will be evaluated using the key

usage scenarios provided by the ISV as part of the Documentation Requirements.

The tests will confirm that the Role Centers, ribbons, and pages follow the full set of applicable

requirements.

CRITERIA FOR PASSING: This requirement is mandatory. If the solution does not follow the user-

experience requirements, then it will fail the test.

4.2 An app that restricts the functionality of Dynamics 365 for Financials must

document the restriction

SUMMARY AND INTENT: End users expect that the underlying Dynamics 365 for Financials service is fully

functional. In addition, other ISVs will expect that the Dynamics 365 for Financials service will be fully

functional.

RESOURCES: None

HOW TO COMPLY: If your app limits or breaks existing Dynamics 365 for Financials functionality or cannot

coexist with Dynamics 365 for Financials functionality, then you must include documentation that explains

the conflict and states that the Dynamics 365 for Financials feature or function is not available after the

user installs your app. For example, if a reporting solution is designed for customers who do not use

inventory and will not work for a customer who uses standard inventory functionality, then you must

explain this limitation.

TEST METHODOLOGY: The test will confirm that you have provided the required documentation.

CRITERIA FOR PASSING: This requirement is mandatory. If the app limits or breaks existing Dynamics 365

for Financials functionality and does not document the limitation, then it will fail the test.

Translation and localization requirement Your app must comply with the following requirement:

• 5.1: The app must contain translations for targeted country/region languages

5.1 The app must contain translations for targeted country/region languages

SUMMARY AND INTENT: Apps must be able to be localized in the same markets as the underlying

Dynamics 365 for Financials service. Therefore, your app must be globalized and follow localization best

practices.

RESOURCES: For more information, see the following websites:

• Microsoft Global Development and Computing Portal

• MSDN Library: Globalization

HOW TO COMPLY: Dynamics 365 for Financials includes multilanguage features. Therefore, Dynamics 365

for Financials users in certain countries/regions may switch languages within the application. To provide a

consistent user experience, your extension must have multilanguage properties set on all captions and

user-interface elements when being used in these countries/regions. All text constants must be

multilanguage enabled, unless they refer to computer-to-computer communication, such as building XML

documents or integrating with other applications.

Your app must be shipped with English language strings, in addition to the language or languages for the

country/regions that your app will target.

TEST METHODOLOGY: To verify this requirement, the test will confirm that the app’s captions and UI

elements are displayed in English and the languages available for the supported country/regions.

CRITERIA FOR PASSING: This requirement is mandatory, your app must contain translations for English

and the languages of the country/regions that it targets. If the app does not meet the multilanguage

requirements, then it will fail the test.

Performance and stability requirements Your app must meet the following requirements:

• 6.1: The extension package can be successfully deployed

• 6.2: Successfully complete end-to-end key usage scenarios

• 6.3: The app does not consume excessive system resources

• 6.4 The app can be successfully removed

6.1 The extension package can be successfully deployed

SUMMARY AND INTENT: Extension packages must be able to be successfully deployed to a multitenant

deployment of the supported country/regions provided in the Documentation Requirements.

RESOURCES: See the How to: Publish and Install an Extension in the MSDN Library.

HOW TO COMPLY: The extension package must be able to be published without errors to a multitenant

instance of the most current version of Dynamics 365 for Financials. The app must be able to be installed

for one or more tenants without errors. The Dynamics 365 for Financials service can be successfully

stopped and started after the extension package has been published and installed.

TEST METHODOLOGY: The test includes publishing and installing the extension package on the Dynamics

365 for Financials service of the supported country/regions. The Dynamics 365 for Financials service will be

stopped and started after the extension package is published.

CRITERIA FOR PASSING: This requirement is mandatory. If the extension package does not deploy without

errors or the Dynamics 365 for Financials service fails to start/stop with the extension package published,

then it will fail the test.

6.2 Successfully complete end-to-end key usage scenarios

SUMMARY AND INTENT: The business functionality of the app performs without errors and as

documented in the end-to-end key usage scenarios in the Documentation Requirements.

RESOURCES: None

HOW TO COMPLY: The app’s key usage scenarios that are provided as part of the Documentation

Requirements must be able to be completed as documented. The key usage scenario must provide enough

step by step details for the tester to complete the test. The information must also provide detailed setup

information to complete the test. (Refer to the example in Appendix C)

The setup and end to end tests must be able to be run by a user assigned to the permissions sets loaded

with the extension, not requiring the user to be assigned to the SUPER permission set.

In order to successfully complete the end to end usage scenarios, make sure to set the ApplicationArea for

your objects to one of the following values. If the applicationarea is not set to one of these values, the object

will not be displayed in Dynamics 365 for Financials. Refer to ApplicationArea Property for more

information.

• #Basic

• #Basic, #Suite

• #Suite

• #All

TEST METHODOLOGY: The tester will use the installed apps to verify that the end-to-end key usage

scenarios provided can be completed without any errors and with expected results.

CRITERIA FOR PASSING: This requirement is mandatory. If the app’s key usage scenarios can’t be

completed as documented or the end to end scenario doesn’t provide step by step details, then it will fail

the test.

6.3 The app does not consume excessive system resources

SUMMARY AND INTENT: An installed app provides acceptable user performance and does not consume

an excessive amount of system resources, so that it does not affect the overall performance of the system

and other tenants of the system.

RESOURCES: None

HOW TO COMPLY: The key usage scenarios for the app must be able to be completed with acceptable

user performance. Acceptable performance is similar to comparable tasks in Dynamics 365 for Financials.

The app should not consume an unreasonable amount of system resources.

TEST METHODOLOGY: The tester will execute the key usage scenarios while monitoring the system’s CPU,

memory, and Disk I/O. The results captured from monitoring must be similar to the results of running

similar tasks without the app installed. The tester will also look for tasks that seem to take longer than

expected or time-out.

CRITERIA FOR PASSING: This requirement is mandatory. If the app performance is not acceptable or uses

excessive system resources, then it will fail the test.

6.4 The app can be successfully removed

SUMMARY AND INTENT: Apps must be able to be successfully uninstalled and unpublished from the

Dynamics 365 for Financials service.

RESOURCES: See the How to: Publish and Install an Extension in the MSDN Library.

HOW TO COMPLY: The app must be able to be uninstalled without errors from a tenant, leaving the

tenant in the same functioning state as before the app was installed. The extension package must be able

to be unpublished without errors from a system where it is not installed for any tenants. The Dynamics 365

for Financials service can be successfully stopped and started after the Extension package has been

uninstalled and unpublished.

TEST METHODOLOGY: The tester will uninstall and unpublish the extension package after completing the

end-to-end usage testing. The tester will verify that the functionality added by the app is no longer

available. The Dynamics 365 for Financials service will be stopped and started after the extension package

is removed.

CRITERIA FOR PASSING: This requirement is mandatory. If the app cannot be removed without errors or

the Dynamics 365 for Financials service fails to start/stop with the extension package removed, then it will

fail the test.

Upgrade and maintenance requirements Your app must meet the following requirements:

• 7.1: Upgrade code required for all schema changes

• 7.2: The ISV must update the file version and public key when making changes to .NET Framework add-

in assemblies

7.1 Upgrade code required for all schema changes

SUMMARY AND INTENT: The app must contain upgrade code for each new or modified table to avoid

unintended data loss during an uninstall and reinstall of the app. The upgrade code can be used to upgrade

the data from one version of the app to the next, restore the data on a reinstall of the same version, load

default starting data during a reinstall, or intentionally remove data during a reinstall.

RESOURCES: See the How to: Write Extension upgrade code in the MSDN Library.

HOW TO COMPLY: An app with at least one new or modified table must include a new codeunit

containing either the OnNavAppUpgradePerDatabase or OnNavAppUpgradePerCompany function. The

function must contain code to restore, delete, upgrade, or load starting data for each of the new or

modified table objects.

TEST METHODOLOGY: The tester will review the code to verify that upgrade code has been included for

each new or modified table. The tester will uninstall the app after performing the end-to-end test scenarios

and then reinstall the same version of the app to verify that there is upgrade code that will handle the

archived data without error.

CRITERIA FOR PASSING: This requirement is mandatory. If the app does not include upgrade code for a

new or modified table, then it will fail the test.

7.2 The ISV must update the file version and public key when making changes to .NET

Framework add-in assemblies

SUMMARY AND INTENT: To make sure that an updated version of a .NET add-in assembly is deployed

correctly with the new version of an app, the updated assembly’s version must be incremented and a new

public key generated.

RESOURCES: None

HOW TO COMPLY: Update the .NET assembly version and public key when making changes to an

assembly that was included in a previous version of the app.

TEST METHODOLOGY: The tester will review the code and compare it to the previous version. If the code

has changed, the tester will verify that the version has been incremented and the public key changed.

CRITERIA FOR PASSING: This requirement is mandatory. If the assembly has changed but has the same

version or public key, then the app will fail the test.

Appendix A: Rules and Guidelines for C/AL Code This section defines the rules and guidelines to follow when writing C/AL code in an extension package. The

rules and guidelines are grouped according to two importance levels: Critical errors that must be resolved,

and important errors that should be resolved. Errors that are not resolved must include an explanation and

justification for the error.

Critical errors:

1. User has direct control over file system paths for the server. 2. Code uses NAV encryption key functions, IMPORTENCRYPTIONKEY, EXPORTENCRYPTIONKEY,

CREATEENCRYPTIONKEY, DELETEENCRYPTIONKEY. (FYI - It is fine to use the ENCRYPT and DECRYPT functions.)

3. Code uses APPLICATIONPATH. 4. Code uses unsupported .NET Framework methods from Appendix B. 5. Code uses or relies on debugger functionality. 6. Code uses the following functions:

a. Automation.CREATE b. Automation.ISCLEAR c. Debugger functions

7. Code uses Microsoft.Office.Interop libraries or namespaces. 8. Code uses ASSERTERROR. 9. Calls to Report, Instream, Outstream, or XMLPort use un-approved storage areas. 10. External data connections do not properly handle sensitive data. 11. Code uses AutoIncrement=Yes for a table field that may be used in a Foreign Key relationship.

Recommend code comment that the table field will not be used in a Foreign Key relationship to pass validation.

12. Doesn’t encrypt sensitive table data. (i.e. credit card info, passwords, etc.)

Important errors:

1. Temporary files are not cleaned up after use. 2. Code uses files other than temporary files. 3. Code generates file names or interacts with files without using codeunit 419 (File Management). 4. Code uses directories other than temporary directories. 5. Code uses codeunits that require printers to be selected. 6. Code uses a specific time zone or locale.

Appendix B: Unsupported .NET methods

This section defines the unsupported .NET Framework methods for an extension package. The .NET methods added to a package that could be used as an entry/exit point for problematic code (such as direct SQL calls) will not be supported.

If the C/AL code references any .NET libraries, then the libraries cannot be in the unsupported namespaces and assemblies listed below without approved justification.

System namespaces: System.AddIn

System.AddIn System.AddIn.Contract

System.Configuration

System.Configuration.Install System.Core

System.Core System.Data

System.Data System.Data.DataSetExtensions System.Data.Entity System.Data.Entity.Design System.Data.Linq System.Data.OracleClient System.Data.Services System.Data.Services.Client System.Data.Services.Design System.Data.SqlServerCe System.Data.SqlServerCe.Entity System.Data.SqlXml

System.Deployment

System.Deployment System.Design

System.Design System.Design.VisualStudio.11.0

System.Device

System.Device System.Diagnostics

System.Diagnostics.Contracts System.Diagnostics.Debug System.Diagnostics.Tools System.Diagnostics.Tracing

System.DirectoryServices

System.DirectoryServices System.DirectoryServices.AccountManagement System.DirectoryServices.Protocols

System.Drawing

System.Drawing.VisualStudio.11.0 System.Dynamic

System.Dynamic System.Dynamic.Runtime

System.EnterpriseServices

System.EnterpriseServices System.IO

System.IO System.IO.Compression System.IO.Compression.FileSystem System.IO.Log

System.Management

System.Management System.Management.Automation System.Management.Automation.Resources System.Management.Instrumentation

System.Messaging

System.Messaging System.Net

System.Net System.Net.Http System.Net.Http.Formatting System.Net.Http.Rtc System.Net.Http.WebRequest System.Net.NetworkInformation System.Net.Primitives System.Net.Requests System.Net.WebHeaderCollection

System.Reflection

System.Reflection System.Reflection.Context System.Reflection.Emit System.Reflection.Emit.ILGeneration System.Reflection.Emit.Lightweight System.Reflection.Extensions System.Reflection.Primitives System.Resources.ResourceManager

System.Runtime

System.Runtime System.Runtime.Caching System.Runtime.DurableInstancing System.Runtime.Extensions System.Runtime.Handles System.Runtime.InteropServices System.Runtime.InteropServices.WindowsRuntime System.Runtime.Numerics System.Runtime.Remoting System.Runtime.Serialization System.Runtime.Serialization.Formatters.Soap

System.Runtime.Serialization.Json System.Runtime.Serialization.Primitives System.Runtime.Serialization.Xml System.Runtime.WindowsRuntime System.Runtime.WindowsRuntime.UI.Xaml

System.Security

System.Security System.Security.Principal

System.ServiceModel

System.ServiceModel System.ServiceModel.Activation System.ServiceModel.Activities System.ServiceModel.Channels System.ServiceModel.Discovery System.ServiceModel.DomainServices.EntityFramework System.ServiceModel.DomainServices.EntityFramework.resources System.ServiceModel.DomainServices.Hosting System.ServiceModel.DomainServices.Hosting.OData System.ServiceModel.DomainServices.Hosting.OData.resources System.ServiceModel.DomainServices.Hosting.resources System.ServiceModel.DomainServices.Server System.ServiceModel.DomainServices.Server.resources System.ServiceModel.Duplex System.ServiceModel.Http System.ServiceModel.Install System.ServiceModel.Internals System.ServiceModel.NetTcp System.ServiceModel.Primitives System.ServiceModel.Routing System.ServiceModel.Security System.ServiceModel.ServiceMoniker40 System.ServiceModel.WasHosting System.ServiceModel.Web

System.ServiceProcess

System.ServiceProcess System.VisualStudio

System.VisualStudio.11.0 System.Web

System.Web System.Web.Abstractions System.Web.ApplicationServices System.Web.DataVisualization System.Web.DataVisualization.Design System.Web.DynamicData System.Web.DynamicData.Design System.Web.DynamicData.VisualStudio.11.0 System.Web.Entity System.Web.Entity.Design System.Web.Extensions

System.Web.Extensions.Design System.Web.Extensions.Design.VisualStudio.11.0 System.Web.Extensions.VisualStudio.11.0 System.Web.Helpers System.Web.Http System.Web.Http.SelfHost System.Web.Http.WebHost System.Web.Mobile System.Web.Mvc System.Web.Razor System.Web.RegularExpressions System.Web.Routing System.Web.Services System.Web.VisualStudio.11.0 System.Web.WebPages System.Web.WebPages.Administration System.Web.WebPages.Deployment System.Web.WebPages.Razor

System.Windows

System.Windows System.Windows.Controls.Ribbon System.Windows.Forms System.Windows.Forms.DataVisualization System.Windows.Forms.DataVisualization.Design System.Windows.Forms.VisualStudio.11.0 System.Windows.Input.Manipulations System.Windows.Presentation

System.Workflow

System.Workflow.Activities System.Workflow.ComponentModel System.Workflow.Runtime System.WorkflowServices

Appendix C: Dynamics 365 for Financials usage

verification test

The following is an example of an acceptable user scenario document. For the document, we aren’t looking

for a general explanation as to what the extension is or what it all does. Instead, we need a detailed step by

step list of instructions that walk the user through all the required setup and common usage (we aren't

looking to test all of your functionality but only your most common scenarios you feel should be validated).

For example, imagine if you were walking through the setup and usage of your extension yourself and you

decided to write down each step along the way. Screenshots are helpful and if the exact value of the field is

important please add that as well.

Below is an example.

Create Sales Order Profile – Order Processor

Steps:

1. Navigate to Sales Order page Select Sales Order from the actions ribbon of the user’s home page or using Search.

2. Enter Customer Enter customer 10000 or select another customer in the system.

3. Enter Item Enter item 1896-S or select another item in the system.

4. Enter quantity Enter a quantity.

Continue to the Post Sales Order scenario or select to close the order and continue to the Edit Sales Order scenario.

Edit Sales Order Profile – Order Processor

Steps:

1. Navigate to Sales Orders page Select Sales Orders under the Sales navigation using Search.

2. Select Sales Order Select the first, or any other, Sales Order in the list.

3. Add another line item Add item 1896-S or select another item in the system.

4. Enter quantity Enter a quantity.

Continue to the Post Sales Order scenario or select to close the order

Post Sales Order Profile – Order Processor

Steps:

1. Navigate to Sales Orders page Select Sales Orders under the Sales navigation using Search.

2. Select Sales Order Select the first, or any other, Sales Order in the list.

3. Post the sale order Select Post in the action ribbon.

4. Select Ship and Invoice Select Ship and Invoice and click OK.

5. Open posted invoice Click Yes to open the posted invoice.

6. View posted invoice Verify the sales over was posted successfully.

(c) 2017 Microsoft Corporation. All rights reserved. This document is provided "as-is." Information and views expressed in this document, including URL and other

Internet Web site references, may change without notice. You bear the risk of using it. Some examples are for illustration only and are fictitious. No real association is

intended or inferred.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your

internal, reference purposes.

Appendix D: Fully test extension before

submitting

Please take the time and test your extension in the partner D365 test environment before submitting your

extension for validation. Keep the following points in mind when doing your testing

1) Ensure that your extension can be published with no code signing errors

2) Ensure that the extension can be installed without errors

3) If you are using the Assisted Setup, ensure that you can use your wizard without errors

4) Walk through the setup and usage of your extension to verify that you do not receive any

permissions errors (remember to not make the user mark the SUPER permission set)

5) Ensure that you can uninstall and unpublish your extension without any errors

6) Ensure that you can republish and reinstall your extension without any errors (this tests out the upgrade functionality)