Microsoft Dynamics NAV
Developer Updates for Microsoft Dynamics NAV 2009 R2 User's Guide
December 2010
Contents Developer Updates for Microsoft Dynamics NAV 2009 R2 ............................................................. 1 Viewing the Definition of a Function or Object by Using Go To Definition ................................... 2 Locking and Unlocking Objects .................................................................................................... 9 How to: Lock an Object ........................................................................................................... 10 How to: Unlock an Object ....................................................................................................... 11 How to: Integrate Classic Client Report Designer and Visual Studio Report Designer ............. 12 Extending Microsoft Dynamics NAV Using Microsoft .NET Framework Interoperability ........... 14 Calling .NET Framework Members from C/AL Code.............................................................. 15 How to: Call .NET Framework Members from C/AL Code .................................................. 18 How to: Set .NET Framework Types to Target the RoleTailored Client or Microsoft Dynamics NAV Server ..................................................................................................... 21 .NET Framework and C/AL Type Mappings ........................................................................... 23 Using .NET Framework Arrays ............................................................................................... 26 Using .NET Framework Collections ........................................................................................ 30 Using .NET Framework Enumerations ................................................................................... 31 Using .NET Framework Generics ........................................................................................... 33 Using .NET Framework Interfaces.......................................................................................... 35 Calling External Web Services with Windows Communication Foundation ........................... 36 How to: Add a FactBox on a Page Using the Wizard ................................................................ 38 How to: Use the System Indicator .............................................................................................. 40
Developer Updates for Microsoft Dynamics NAV 2009 R2 This document describes the new developer tasks that you can perform in Microsoft Dynamics NAV 2009 R2. For more information about what’s new in Microsoft Dynamics NAV 2009 R2, including what’s new in the application, see What’s New in Microsoft Dynamics NAV 2009 R2 in the MSDN Library. You can also find this content in the What’s New in Microsoft Dynamics NAV 2009 R2.pdf file, which is located in the Documentation folder. By default, this folder is C:\Program Files\Microsoft Dynamics NAV\60\Documentation. For more information about the hotfixes and known issues in Microsoft Dynamics NAV 2009 R2, see the Microsoft Dynamics NAV 2009 R2 Release Notes (requires PartnerSource login). You can also find the release notes in the ReadMe.htm file on the installation media.
In This Section Viewing the Definition of a Function or Object by Using Go To Definition Locking and Unlocking Objects How to: Integrate Classic Client Report Designer and Visual Studio Report Designer Extending Microsoft Dynamics NAV Using Microsoft .NET Framework Interoperability How to: Add a FactBox on a Page Using the Wizard How to: Use the System Indicator
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
1
Viewing the Definition of a Function or Object by Using Go To Definition You can view the definition of a function or object by selecting the item in the C/AL Editor and then clicking Go To Definition. You can also view the definition of a function by selecting it in the C/AL Globals window and then clicking Go To Definition. To go to the definition of a function or object, select or place the cursor anywhere in the function name or object variable name, and then do one of the following:
On the View menu, click Go To Definition.
Right-click the function name or object variable name, and then click Go To Definition.
Press SHIFT+F12.
The following table describes how you can go to the definition of a function or object. Starting location
Result
From the C/AL Globals window, select a user-defined function
The C/AL Editor goes to the C/AL code that defines the selected function.
From the C/AL Editor, select a user-defined function
The C/AL Editor goes to the C/AL code that defines the selected function.
From the C/AL Editor, select a user-defined function that is called on an object variable
The object is opened in the corresponding designer.
A new C/AL Editor window opens to the C/AL code that defines the selected function.
From the C/AL Editor, select a system function on an object
If the system function is called on an object variable, such as a record, codeunit, or report, then the object is opened in the corresponding designer. If the system function is not called on an object variable, then nothing happens.
From the C/AL Editor, select a variable that is one of the following object types:
The object is opened in the corresponding designer or editor:
Record
Table Designer
Page
Page Designer
Form
Form Designer
Report
Report Designer
Codeunit
C/AL Editor
Dataport
Dataport Designer
XMLport
XMLport Designer Note If you select a variable that is a fundamental data type, such as Integer or Decimal, then information about the variable is displayed in the status bar.
2
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
Examples This section shows examples of using the Go To Definition shortcut menu item.
User-Defined Function from the C/AL Globals Window From the C/AL Globals window, right-click a user-defined function, and then click Go To Definition.
The result is that the C/AL Editor jumps to the C/AL code that defines the selected function.
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
3
User-Defined Function from the C/AL Editor From the C/AL Editor, right-click a user-defined function, and then click Go To Definition.
The result is that the C/AL Editor jumps to the C/AL code that defines the selected function.
4
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
User-Defined Function from the C/AL Editor for an Object Variable From the C/AL Editor, right-click a user-defined function that is called on an object variable, and then click Go To Definition.
The result is that the object on which the function is called is opened in the corresponding designer and a new C/AL Editor window opens to the C/AL code that defines the selected function.
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
5
System Function from the C/AL Editor From the C/AL Editor, right-click a system function that is called on an object variable, and then click Go To Definition.
If the system function is called on a record variable, then the table that the record is from is opened in Table Designer.
If the system function is the .RUN function, then the codeunit is opened in a new C/AL Editor window. 6
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
If the system function is called on any other object type variable, then the object is opened in the corresponding designer. For any other system function that is not called on an object variable, nothing happens.
Object Variable from the C/AL Editor From the C/AL Editor, right-click a variable that is one of the following object types, and then click Go To Definition:
Record
Page
Form
Report
Codeunit
Dataport
XMLport
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
7
The object is opened in the corresponding designer:
Table Designer
Page Designer
Form Designer
Report Designer
C/AL Editor
Dataport Designer
XMLport Designer
Permissions To go to a definition, you must have the correct permissions. If you do not have permission to view the definition of an object by selecting the object in Object Designer and then clicking Design, then you cannot view it with the Go To Definition option.
8
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
Locking and Unlocking Objects In Microsoft Dynamics NAV 2009 R2, you can lock an object in Object Designer so that other developers cannot save design changes to the object. After you lock an object, the Locked field in Object Designer is selected, and the Locked By column shows the user who locked the object. When an object is locked, another user can still do the following:
Open the object in the designer, make changes, and compile the object. However, another user cannot save the object. The locked object is marked as Read Only when another user opens it in the designer.
Run the object. For example, a user can run a table and can add or delete records in the table even if it is locked for design changes.
When you finish making design changes to an object, you can unlock it in Object Designer. The Locked and Locked By fields are cleared, and other users can now lock the object or save changes to the object. You can select one object or multiple objects at the same time to lock or unlock. You can also set the Auto-Lock on Design option to automatically lock all objects that you open for designing.
Object Table The information in the Locked and Locked By columns is stored in the Object table. The Object table is a system table that stores information about objects in the application.
Concurrency Considerations Even though you can lock objects, it is still possible for developers to have concurrency issues, as shown in the following examples.
A developer opens an object in the designer but does not lock it. The developer makes several changes to the object and saves the changes periodically. At the same time, a second developer locks the object, and the first developer cannot save design changes to the object. The first developer gets an error message that the object is locked by the second developer.
A developer locks an object. A second developer opens the locked object in read-only mode, and then the first developer unlocks the object. The second developer still cannot save design changes to the object even though the object is now unlocked because it is open in read-only mode.
See Also How to: Lock an Object How to: Unlock an Object
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
9
How to: Lock an Object You can lock objects so that other developers cannot save changes to the objects. You can either lock objects manually, or you can set an option so that all objects that you open for design are locked. To manually lock an object 1. In the Classic client, on the Tools menu, click Object Designer. 2. In Object Designer, select one or more objects that are not already locked, and then do one of the following steps:
Right-click the object or objects, and then click Lock.
On the File menu, click Lock.
Press CTRL+ALT+L.
To automatically lock all objects that you open for design 1. In the Classic client, on the Tools menu, click Options. 2. In the Options window, in the Auto-Lock on Design field, enter Yes, and then click OK. Tip You cannot automatically unlock objects that you have locked. However, you can filter for locked objects, select all objects that you have locked, and then unlock these objects. For more information, see How to: Unlock an Object. Note If you go to the definition of an object, then the object is opened in design mode. Therefore, if you set the Auto-Lock on Design field and then go to the definition of an object, then the object is locked. For more information, see Viewing the Definition of a Function or Object by Using Go To Definition.
See Also How to: Unlock an Object Locking and Unlocking Objects
10
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
How to: Unlock an Object You can lock and unlock objects to prevent other developers from making changes while you work with those objects. If you lock an object, then only you can save changes to the object. After you save your changes, you unlock the object so that other developers can make changes to that object. In some cases, a system administrator may need to force unlock an object. For example, if a user locks an object and then cannot unlock the object because of a holiday or other absence, then the system administrator can force unlock the object. To force unlock an object, the system administrator must have the SUPER user role. In some cases, you may want to unlock all objects that you have locked. To do this, you can filter on locked objects, select all objects that you have locked, and then unlock these objects. To unlock an object 1. In the Classic client, on the Tools menu, click Object Designer. 2. In Object Designer, select one or more objects that you have locked, and then do one of the following steps:
Right-click the object or objects, and then click Unlock.
On the File menu, click Unlock.
Press CTRL+ALT+U.
To force unlock an object 1. In the Classic client, on the Tools menu, click Object Designer. 2. In Object Designer, select one or more objects that you want to force unlock, and then do one of the following steps:
Right-click the object or objects, and then click Force Unlock.
On the File menu, click Force Unlock.
3. Confirm that you want to force unlock the object. Note You must have the SUPER user role to force unlock an object. To unlock all objects that you have locked 1. In the Classic client, on the Tools menu, click Object Designer. 2. In Object Designer, click All. 3. On the View menu, click Table Filter. 4. In the Table Filter window, enter Locked By in the Field field, enter your user name in the Filter field, and then click OK. 5. On the Edit menu, click Select All, and then do one of the following steps:
Right-click the object or objects, and then click Unlock.
On the File menu, click Unlock.
Press CTRL+ALT+U.
See Also How to: Lock an Object Locking and Unlocking Objects DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
11
How to: Integrate Classic Client Report Designer and Visual Studio Report Designer To create and modify client report definition (RDLC) report layouts, you must use Visual Studio. When you create an RDLC layout for a report, you may have to perform some steps in Classic client Report Designer to modify the dataset and some steps in Visual Studio Report Designer to modify the layout. To work with both Classic client Report Designer and Visual Studio Report Designer, you must know when and where to save your work and how to switch between them efficiently. You can save changes to the RDLC report layout of the report in Visual Studio multiple times and then return to Classic client Report Designer and load the changes that you made to the layout into the report. In Microsoft Dynamics NAV 2009 R2, you can save and compile changes to the report dataset in Classic client Report Designer multiple times and then return to Visual Studio Report Designer and reload the dataset into the report layout. To switch between Classic client Report Designer and Visual Studio Report Designer, we recommend that you follow these steps:
Before you switch from Visual Studio Report Designer to Classic client Report Designer, save the report.rdlc file. You can also build the report in Visual Studio before you switch to the Classic client, but this is not required.
Before you switch from Classic client Report Designer to Visual Studio Report Designer, save and compile the report.
After you update the dataset in Classic client Report Designer, you must refresh the dataset result in Visual Studio Report Designer. In the Website Data Sources pane, expand DataSet, right-click Result, and then click Refresh.
If you rename a field in Classic client Report Designer, then you must update all instances of that field in the Visual Studio Report Designer layout. Otherwise, the report will not successfully compile.
If you delete a field in Classic client Report Designer, then you must delete all instances of that field in the Visual Studio Report Designer layout. Otherwise, the report will not successfully compile.
The following procedure describes how to switch between Classic client Report Designer and Visual Studio Report Designer. To work with both Object Designer and Visual Studio Report Designer 1. In the Classic client, on the Tools menu, click Object Designer. 2. To either create or modify an RDLC report, do one of the following steps:
To create a new RDLC report layout for a report, in Object Designer, click Report, select the report, and then click Design. On the Tools menu, click Create Layout Suggestion.
To modify an existing RDLC report layout for a report, in Object Designer, click Report, select the report that you want to modify, and then click Design. On the View menu, click Layout.
3. After you make changes in the RDLC layout, in Visual Studio, on the File menu, click Save Report.rdlc. 4. In the Classic client, select an empty line in the report in Report Designer. A dialog box opens with the following message: The layout of report id: '' is changed by another application. Filename of the changed RDLC: Do you want to load the changes? 12
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
5. Click Yes to load the changes that you made to the RDLC layout into the Classic client. 6. In the Classic client, on the File menu, click Save. 7. In the Save dialog box, select Compiled, and then click OK. Note If you try to close the report in Object Designer in the Classic client, then you see the following error: You must close the Visual Studio Designer window before closing the report object. Note If you try to view the layout when the report layout is already open, then you see the following error: The report layout is already open in Visual Studio. 8. In Classic client Report Designer, make some additional changes to the report dataset. 9. In the Classic client, on the File menu, click Save. 10. In the Save dialog box, select Compiled, and then click OK. Important If you save the report but do not compile it or if you compile the report but do not save it, then you cannot load the changes into the RDLC report layout in the following step. You must both save and compile the report. 11. Go to Visual Studio Report Designer. You see the following message: This file has been modified outside of the source editor. Do you want to reload it? Click Yes or Yes to All to reload the changes from Classic client Report Designer into the RDLC report layout. 12. In Visual Studio, in the Website Data Sources pane, expand DataSet, right-click Result, and then click Refresh. The additional items that you added to the dataset in Section Designer in the Classic client are displayed in the Visual Studio dataset. 13. You can continue making changes in either Visual Studio Report Designer or Classic client Report Designer without having to close either designer. You must save and compile the report object after you make changes and load the changes into the report object or the RDLC report layout when you are prompted.
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
13
Extending Microsoft Dynamics NAV Using Microsoft .NET Framework Interoperability You can extend the RoleTailored client and Microsoft Dynamics NAV Server with functionality that is available in Microsoft .NET Framework assemblies. You can take advantage of .NET Framework interoperability so that Microsoft Dynamics NAV objects can interact with .NET Framework objects. In your Microsoft Dynamics NAV objects, you can reference .NET Framework assemblies and call their members directly from C/AL code. You can use assemblies from the .NET Framework class library, which are found in the global assembly cache; your own custom assemblies; or third-party assemblies. For more information, see Assembly Installation in the GAC in the MSDN Library. .NET Framework interoperability offers an alternative to COM so that you can extend your solution. For example, you can use .NET Framework interoperability to:
Consume web services.
Integrate with Microsoft Office products.
Create .NET Framework applications that can target the RoleTailored client.
See Also Calling .NET Framework Members from C/AL Code .NET Framework Type Conversion Using .NET Framework Arrays Using .NET Framework Collections Using .NET Framework Enumerations Using .NET Framework Generics Using .NET Framework Interfaces Calling External Web Services Using Windows Communication Framework
14
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
Calling .NET Framework Members from C/AL Code You can call .NET Framework type members, including methods, properties, and constructors, from C/AL code with the DotNet data type for C/AL variables. This section provides an overview of the DotNet data type, guidelines on its use, and aspects about calling members of a .NET Framework type. For information about how to create and use a DotNet variable to call members of a type, see How to: Call .NET Framework Members From C/AL Code.
DotNet Data Type The DotNet type resembles the Automation type in C/AL except that it references a .NET Framework type in an assembly. Assemblies can be either part of assemblies that are installed in the global assembly cache or custom assemblies that you have installed for Microsoft Dynamics NAV. After you have defined a DotNet variable, you can call it in C/AL code to instantiate members of a .NET Framework type.
Constructors A constructor is a method that creates an instance of an object and prepares it for use. Before you use a DotNet variable, you should verify whether the variable is static or is an object instance because this determines whether you have to use a constructor.
Static variables do not require a constructor because they do not have an instance.
Object instance variables require a constructor because they must be created before they can be accessed.
To find the constructor and other methods and property for your object, in Object Designer, click Symbol.
Static and Instance Method Calls Methods that you call from C/AL code can be either static or instance methods.
You use the same syntax to call static and instance methods.
Calling static methods provides a factory pattern for creating object instances. For example, to create a new System.TimeZoneInfo object, you call the type’s System.TimeZoneInfo.Local static method with the following code: zone := zone.Local;
A static class or object is loaded once per Microsoft Dynamics NAV Server instance, and the class or object is shared between all clients that are connected to the server instance. The data that is maintained by the static class or object is visible by all clients that use the type. You should consider this in your .NET Framework interoperability design to help avoid disclosing private information.
C# Indexers A C# indexer is represented as an Item property in C/AL. For example, in C#, the following code sets an array element N to the value M: arrayVariable[N] = M;
In C/AL, the corresponding code is as follows: arrayVariable.Item(N) := M;
Indexers can also be overloaded. In Object Designer, click C/AL Symbol Menu to see the parameters and return types for the indexer.
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
15
Indexers for lists and arrays that are defined by .NET Framework variables are zero-based, which means that they start at 0. Other indexers in C/AL start at 1.
Operators for Comparing .NET Framework Objects .NET Framework interoperability does not support direct use of operators to compare two DotNet variables. For example, the following scenario is not supported: IF dnVersion1 arrow to add it to the Part Order list on the right. 9. Repeat steps 7 and 8 to add more parts. The part’s vertical position in the Part Order list determines its vertical position in the FactBox on the page. 10. To remove a part, click the Page, System, or Chart tab based on the part type, select the part from the Part Order list, and then click the < arrow. 11. Finish the steps in the wizard. For more information about the wizard and creating pages, see How to: Create a Page in the MSDN Library.
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
39
How to: Use the System Indicator You can enable the system indicator when you are working with different instances of Microsoft Dynamics NAV 2009 R2. For example, you can differentiate between a production environment and a test environment or see when you are in configuration mode. In this procedure, you enable and set up the system indicator.
If you are in configuration mode, then the system indicator is automatically displayed, and you cannot turn it off.
If you are in any other mode, then you must first set up the system indicator in the Company Information window. It is then shown according to your preferences on every page. To enable the system indicator 1. In the RoleTailored client, in the navigation pane, click Departments, click Administration, click General, and then click Company Information. 2. Expand the System Indicator FastTab. 3. In the System Indicator field, select one of the following options. System indicator type
Description
None
No text is shown. Note When you are in configuration mode, the Configuration status is always displayed. You cannot turn this text off.
Custom Text
Shows text that you enter in the System Indicator Text field.
Company Information
Shows text that you enter in the Name field.
Company
Shows the company name.
Database
Shows the middle-tier host name and database name.
Company+Database
Shows the company name, the middle-tier host name, and the database name.
4. In the System Indicator Style field, select from the Standard and Accent1 through Accent9 options to add a certain style to the system indicator. 5. In the System Indicator Text field, enter custom text to show. To show the text, you must select the Custom Text option in the System Indicator field. 6. Click OK, and then exit and open the RoleTailored client to see the changes.
40
DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2
Microsoft Dynamics is a line of integrated, adaptable business management solutions that enables you and your people to make business decisions with greater confidence. Microsoft Dynamics works like and with familiar Microsoft software, automating and streamlining financial, customer relationship, and supply chain processes in a way that helps you drive business success. U.S. and Canada Toll Free (888) 477-7989 Worldwide (1) (701) 281-6500
www.microsoft.com/dynamics
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, this document should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. © 2010 Microsoft. All rights reserved.
