Developing Applications for the Classic Client and RoleTailored Client

If your application must run on both the Classic client and on the RoleTailored client, then you must carefully consider how you will design and develop the application. Additionally, if at design time you do not know if your application may need to run on both clients in the future, then you should design your application so that it can run on both clients.

The following differences in the Classic client and the RoleTailored client can affect application development:

  • Forms and Pages:   Forms are used in the Classic client, and pages are used in the RoleTailored client.

  • Reports:   From the Classic client, you can view reports in the Classic report layout. From the RoleTailored client, you can view reports in either the Classic report layout or the client report definition (RDLC) report layout.

  • Dataports and XMLports:   Dataports are not supported in the RoleTailored client. You use XMLports in the RoleTailored client to import and export data.

  • ISSERVICETIER System Function:   You can use the ISSERVICETIER function to execute different code based on the client that you are running.

  • C/AL Behavior:   Some C/AL functions behave differently in the Classic client and the RoleTailored client.

  • Using File Data Type Functions:   From the Classic client, local files are accessed on the client. From the RoleTailored client, local files are accessed on Microsoft Dynamics NAV Server.

  • Automation Objects:   In the Classic client, Automation objects run on the client. In the RoleTailored client, when you create an object, you can specify whether it runs on Microsoft Dynamics NAV Server or on the RoleTailored client.

  • Source Expression Evaluation:   Source expressions are evaluated at different times on the Classic client and the RoleTailored client.

  • System Tables:   Several System tables are not supported in a three-tier environment.

  • Supported C/AL Data Types, Functions, Properties, and Triggers   Some C/AL functions and properties are not supported in the Classic client, and some functions and properties are not supported in the RoleTailored client.

For more information about client architecture in Microsoft Dynamics NAV 2009, see the following topics:

Forms and Pages

In the Classic client, forms are the basis of user interface in the application. In the RoleTailored client, pages are the basis of user interface in the application. You have different options for creating and maintaining forms depending on which clients on which your application must run.

Classic Client Only

If you want your application to run only on the Classic client, then you have the following option for creating and maintaining forms:

  • Create and maintain forms with Form Designer.

RoleTailored Client Only

If you want your application to run on the RoleTailored client only, then you have the following options for creating and maintaining pages:

  • Create and maintain pages with Page Designer.

  • Create forms with Form Designer and then transform the forms to pages with the Form Transformation tool. After the initial form transformation, maintain pages by using Page Designer or by using Form Designer and retransforming your forms to pages.

Both Classic and RoleTailored Clients

If you want your application to run on both the Classic client and the RoleTailored client, then you have the following options for creating forms and pages:

  • Create forms for the Classic client with Form Designer. Create pages for the RoleTailored client with the Form Transformation tool. Maintain forms and pages by using Form Designer to modify forms and then retransforming forms to pages after you make changes.

  • Create forms for the Classic client with Form Designer. Create pages for the RoleTailored client with Page Designer. Maintain forms by using Form Designer and maintain pages by using Page Designer. This approach is not recommended if you have many forms and pages that you must maintain separately with two designers.

Considerations

To decide which tools you want to use to develop pages, consider the following:

  • Do both Form Designer and Page Designer allow you to create the objects that you need for your application?

  • Which designer do you prefer using?

For more information about Form Designer, see Creating and Maintaining Forms. For more information about Page Designer, see Creating and Maintaining Pages. For more information about form transformation, see Transforming Forms to Pages.

Reports

In the RoleTailored client, you can create RDLC report layouts. An RDLC file is a file with an .rdlc extension that is created by Visual Studio Report Designer and stores the layout information for the report. You use both Report Designer in the Classic client and Visual Studio Report Designer to create RDLC report layouts for Microsoft Dynamics NAV 2009. RDLC report layouts provide some new features that are not available in Classic client report layouts. For more information, see Understanding Report Redesign.

If your application runs on both the Classic client and the RoleTailored client, you might want your reports to be exactly the same, regardless of the client. In that case, you can view Classic client report layouts from the RoleTailored client, instead of creating RDLC report layouts. For more information, see How to: View Classic Report Layouts from the RoleTailored Client.

If your application runs on both the Classic client and the RoleTailored client, you can transform your request forms to request pages. The report object contains both the request form and the request page. When your application runs on the Classic client, the request form is used. When your application runs on the RoleTailored client, the request page is used. For more information about transforming request forms, see How to: Transform the Request Form.

To decide which report layouts to use in your application, consider the following:

  • Are any of the features that you want in your reports available in one layout but not in the other? For more information about new features in RDLC reports, see Understanding Report Redesign.

  • Are you familiar with the tools that are required for the report layout that you chose? For Classic report layouts, the tool is the Classic client Report Designer. For RDLC report layouts, the tools are the Classic client Report Designer and Visual Studio Report Designer.

  • If you create RDLC report layouts for existing reports, do you understand the manual updates that are required for the redesigned reports? For more information, see Manual Updates to Redesigned RDLC Report Layouts.

  • Do your reports need to appear exactly the same, regardless of the client?

For more information about designing and maintaining Classic client report layouts, see Designing Reports for the Classic Client. For more information about designing and maintaining RDLC report layouts, see Designing Reports for the RoleTailored Client. For more information about redesigning existing Classic report layouts as RDLC report layouts, see Redesigning Classic Reports with Visual Studio Report Designer.

Dataports and XMLports

If you use dataports to import or export data, your application will run on the Classic client but will result in run-time errors on the RoleTailored client. If your application runs on both the Classic and the RoleTailored clients, we recommend that you use XMLports instead of dataports to import and export data. XMLports are supported on both the Classic and RoleTailored clients. You can configure XMLport objects to achieve the same functionality as dataports in previous versions of Microsoft Dynamics NAV.

When you are developing for the RoleTailored client, you can use additional properties and have access to additional functionality. Request pages and import and export text functionality have been added to XMLports. These properties are visible in the Classic client so that you can access them in XMLport Designer. However, setting or executing an XMLport with these properties in the Classic client has no effect.

Importing and exporting text also works differently in XMLports:

  • XMLports do not have an OnBeforeExportRecord trigger.

  • XMLports support multiple languages for the CaptionML and Language properties.

  • XMLports support UTF-8 and UTF-16 formats for XML.

If you set a filter on an XMLport, then you must verify that the LinkTable and LinkFields properties are set correctly. Additionally, we recommend that you set the filter on the node to which the filter applies, not on a parent node. Otherwise, when you run the XMLport on the RoleTailored client, it will time out on large datasets.

Note

With dataports, you can use the CurrFile object to read and write directly to the input or output file. XMLports do not have a CurrFile object.

For more information about XMLports, see Creating XMLports.

ISSERVICETIER System Function

In some cases, such as if you use automation, access files, or call functions that behave differently or are not supported in the RoleTailored client, you can use the ISSERVICETIER system function. If you call ISSERVICETIER from the Classic client, then the function returns false. If you call ISSERVICETIER from the RoleTailored client, then the function returns true. This allows you to execute different code that is based on the client that you are running. The following sections describe some examples of using ISSERVICETIER.

C/AL Behavior

Some C/AL data types, functions properties, and triggers behave differently when run on the Classic client or when run on the RoleTailored client. You should be familiar with these differences so that when you design code for your application, you can create an application that behaves in the ways that you expect on each client.

The following provides an overview of the behavior differences. For more information, see the specific topic about the data type, function, property, or trigger.

Data type, function, property or trigger Change

BLOB Data Type

In the Classic client, a control on a form can have a SourceExpr that specifies a BLOB field from a table other than the SourceTable for the form. In the RoleTailored client, this is not supported.

Char Data Type

In the Classic client, you can assign a char to any position within the defined length of a text or code variable. In the RoleTailored client, a run-time error occurs if you assign a char to a position that is greater than the current length of the string plus 1.

Code Data Type

In the Classic client, you can assign a char to any position within the defined length of a text or code variable. In the RoleTailored client, a run-time error occurs if you assign a char to a position that is greater than the current length of the string plus 1.

CREATE Function (Automation)

In the RoleTailored client, you can specify if you want the automation object to run on the client or on Microsoft Dynamics NAV Server by using an optional parameter. In the Classic client, the Automation object always runs on the client.

CREATE Function (File)

In the RoleTailored client, if you call CREATE on a file variable that refers to an open file, then the function will not automatically close the existing file and create the new file. You must explicitly call the CLOSE Function (File) to close the existing file. Otherwise, a run-time error occurs.

File Data Type

In the RoleTailored client, if you do not specify the uniform naming convention (UNC) path of a file, then FILE functions access files on the computer running Microsoft Dynamics NAV Server.

In the Classic client, if you do not specify the UNC path of a file, then FILE functions access files on the computer running the client.

For more information, see Using FILE Data Type Functions.

FlowFilters

In the RoleTailored client, it is not supported to have a FlowFilter field as the SourceExpr for a control on a page.

FORM.RUN Function (Form)

If you have code that calls the FORM.RUN function and you run this code on Microsoft Dynamics NAV Server, then the code is translated to call the PAGE.RUN Function instead. For more information, see Using RUN and RUNMODAL Functions.

FORM.RUNMODAL Function (Form)

If you have code that calls the FORM.RUNMODAL function and you run this code on Microsoft Dynamics NAV Server, then the code is translated to call the PAGE.RUNMODAL instead. For more information, see Using RUN and RUNMODAL Functions.

MinOccurs Property

In the Classic client, the minimum number is 0. In the RoleTailored client, if you use Lazy API for XML (LAX), then the minimum number is 1. If you do not use LAX, then the minimum number is 0.

OnInit Trigger

In the RoleTailored client, if you set filters, keys, sort order, or other settings that affect a table view in the OnInit trigger, then the settings are overwritten by the OnOpenForm trigger.

OnValidate (Fields) Trigger

In the RoleTailored client, after a validation error occurs, the user can enter data in other fields.

OPEN Function (File)

In the RoleTailored client, if you call OPEN on a file variable that refers to an open file, then the function will not automatically close the existing file and create the new file. You must explicitly call the CLOSE Function (File) to close the existing file. Otherwise, a run-time error occurs.

PREVIEW Function (Report)

In the Classic client, if you run a report in preview mode and then call CurrReport.PREVIEW, then printing is disabled. In the RoleTailored client, if you run a client report definition (RDLC) report layout in preview mode and then call CurrReport.PREVIEW, then the Print icon is not displayed. If you do not call CurrReport.PREVIEW, then the Print icon is displayed and you can print.

PopulateAllFields Property

In the Classic client, the value of simple identical filters that are set in different filter groups is not assigned to the field when populating a form with a new record.

In the RoleTailored client, the value of simple identical filters that are set in different filter groups is assigned to the field just before executing the OnNewRecord trigger.

Text Data Type

In the Classic client, you can assign a char to any position within the defined length of a text or code variable. In the RoleTailored client, a run-time error occurs if you assign a char to a position that is greater than the current length of the string plus 1.

Variant Data Type

In the Classic client, if an Automation method returns a DateTime in a variant, then the time component is removed when the variant variable is converted to a typed variable. If an Automation method returns a value in a method argument, then the time component is not removed. In the RoleTailored client, the time component is not removed from either a variant return value or a variant method argument when the variant variable is converted to a typed variable.

The following functions are described in detail:

  • Using RUN and RUNMODAL Functions

  • Using FILE Data Type Functions

Using RUN and RUNMODAL Functions

Examples of functions that behave differently when run on the Classic and the RoleTailored clients are FORM.RUN and FORM.RUNMODAL. These functions run a form that you specify. When a form is run modally, no input (keyboard or mouse click) can occur except to objects on the modal form.

The following table shows the result of calling various RUN and RUNMODAL functions from the RoleTailored client and the Classic client.

Client on which code runs Function call Result

RoleTailored client

FORM.RUN

Translated to PAGE.RUN. If page exists, it runs; otherwise, a run-time error occurs.

RoleTailored client

FORM.RUNMODAL

Translated to PAGE.RUNMODAL. If page exists, it runs; otherwise, a run-time error occurs.

RoleTailored client

PAGE.RUN

If page exists, it runs; otherwise, a run-time error occurs.

RoleTailored client

PAGE.RUNMODAL

If page exists, it runs; otherwise, a run-time error occurs.

Classic client

FORM.RUN

If form exists, it runs; otherwise, a run-time error occurs.

Classic client

FORM.RUNMODAL

If form exists, it runs; otherwise, a run-time error occurs.

Classic client

PAGE.RUN

Not supported. A run-time error occurs.

Classic client

PAGE.RUNMODAL

Not supported. A run-time error occurs.

If you are developing an application that will run on both the RoleTailored client and the Classic client, then you have the following options for using a RUN or RUNMODAL function to run forms and pages:

  • Use the ISSERVICETIER system function. If you are running on the RoleTailored client, then call PAGE.RUN or PAGE.RUNMODAL. If you are running on the Classic client, then call FORM.RUN or FORM.RUNMODAL. Use this option if the form and the page have different IDs.

  • Always call FORM.RUN or FORM.RUNMODAL and allow the code to be translated automatically to PAGE.RUN or PAGE.RUNMODAL if it is being run on the RoleTailored client. Use this option if you have both a form and a page with the same ID. If you use the form transformation tool to transform the form to a page, then the form and the page have the same ID.

Using FILE Data Type Functions

If you access a file from the RoleTailored client by using a local file name, such as C:\MyFile.txt, then the location that is accessed is on the computer running Microsoft Dynamics NAV Server. If you access a file from the Classic client by using a local file name, such as C:\MyFile.txt, then the location that is accessed is on the client computer. If you are developing an application that will run on both the Classic client and the RoleTailored client, then you can do one of the following:

  • Use the ISSERVICETIER function. If you are running on the RoleTailored client, then either upload the file from the computer running RoleTailored client to the computer running Microsoft Dynamics NAV Server, or download the file from the computer running Microsoft Dynamics NAV Server to the computer running the RoleTailored client.

  • Use the uniform naming convention (UNC) path of the file to specify the computer on which the file resides. If you use the UNC path of the file, then you must ensure that users running the application have the appropriate permissions to access files.

For example, codeunit 419, 3-Tier Automation Mgt., uses the ISSERVICETIER function. If the codeunit is running on the RoleTailored client, then it uploads a file from the computer running the RoleTailored client to the computer running Microsoft Dynamics NAV Server so that it can access the file using other functions.

Note

We recommend that when possible, you use the functions in codeunit 419, 3-Tier Automation Mgt., to upload and download files. The functions in this codeunit use the DOWNLOAD Function (File), DOWNLOADFROMSTREAM Function (File), and UPLOADINTOSTREAM Function (File).

For more information about accessing files, see File Handling.

Automation Objects

Before you can use an Automation variable, you must create, or instantiate, the automation server that is referenced by the Automation variable. You use the CREATE Function (Automation) to create the automation server. When you create an automation object from the Classic client, it always runs on the client. On the RoleTailored client, you can choose if the automation object runs on the computer running the RoleTailored client or on the computer running Microsoft Dynamics NAV Server by using an optional parameter in the CREATE function. By default, the automation object runs on the computer running the RoleTailored client. For more information about running automation objects on the RoleTailored client and Microsoft Dynamics NAV Server, see Best Practices for Using Automation With the RoleTailored Client.

Source Expression Evaluation

Source expression evaluation on pages in the RoleTailored client differs from source expression evaluation on forms in the Classic client. On pages, source expressions are evaluated on every call that the client makes to Microsoft Dynamics NAV Server but never between calls. If the value of a source expression is a function of page fields that have been changed, then the source expression is only evaluated and updated the first time that the client calls Microsoft Dynamics NAV Server after the fields were changed. For example, the source expression can be evaluated to perform field validation. There may be an interval when the underlying fields change, but the control that is bound to the source expression displays the old value.

Because source expressions on the RoleTailored client are evaluated on every call that the client makes to Microsoft Dynamics NAV Server, we recommend that you do not create source expressions that are bound to the result of a function that performs multiple tasks, such as writing records to a table.

System Tables

Several tables that you can use when developing for the Classic client are not supported when developing for the RoleTailored client. The following table describes these system tables.

Table name Table ID

Printer

2000000039

OCX

2000000042

Automation

2000000046

Server

2000000047

Code Coverage

2000000049

Supported C/AL Data Types, Functions, Properties, and Triggers

Most C/AL data types, functions, properties, and triggers are supported on both the Classic client and the RoleTailored client. However, some are supported only on the Classic client and some are supported only on the RoleTailored client. For more information about what is supported on which client, see Supported Data Types, Functions, Properties, and Triggers in the Classic Client and RoleTailored Client.

See Also

Concepts

Changes in C/AL Behavior and Support from Previous Versions of Microsoft Dynamics NAV
Supported Data Types, Functions, Properties, and Triggers in the Classic Client and RoleTailored Client