Developer Updates for. Microsoft Dynamics NAV

Transcription

1 Microsoft Dynamics NAV Developer Updates for Microsoft Dynamics NAV 2009 R2 User's Guide December 2010

2 Contents Developer Updates for Microsoft Dynamics NAV 2009 R Viewing the Definition of a Function or Object by Using Go To Definition... 2 Locking and Unlocking Objects... 9 How to: Lock an Object How to: Unlock an Object How to: Integrate Classic Client Report Designer and Visual Studio Report Designer Extending Microsoft Dynamics NAV Using Microsoft.NET Framework Interoperability Calling.NET Framework Members from C/AL Code How to: Call.NET Framework Members from C/AL Code How to: Set.NET Framework Types to Target the RoleTailored Client or Microsoft Dynamics NAV Server NET Framework and C/AL Type Mappings Using.NET Framework Arrays Using.NET Framework Collections Using.NET Framework Enumerations Using.NET Framework Generics Using.NET Framework Interfaces Calling External Web Services with Windows Communication Foundation How to: Add a FactBox on a Page Using the Wizard How to: Use the System Indicator... 40

3 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

4 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 From the C/AL Globals window, select a user-defined function From the C/AL Editor, select a user-defined function Result The C/AL Editor goes to the C/AL code that defines the selected 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 From the C/AL Editor, select a variable that is one of the following object types: 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. 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

5 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

6 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

7 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

8 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 <codeunit>.run function, then the codeunit is opened in a new C/AL Editor window. 6 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2

9 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

10 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

11 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

12 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

13 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

14 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: '<report ID>' is changed by another application. Filename of the changed RDLC: <filename> Do you want to load the changes? 12 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2

15 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

16 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

17 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

18 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 <= dnversion2 THEN If you want to compare two DotNet variables, then you can use the Equals function on the DotNet variables as shown in the following example: IF dnversion1.equals(dnversion2) THEN You can perform comparisons by using.net Framework methods and properties that return compatible C/AL types because these objects are implicitly converted to C/AL types before the comparison takes place. For example, the following C/AL code includes three DotNet variables for the System.Collections.Generic.List class: dotnetlist1, dotnetlist2, and dotnetlist3. You cannot compare the DotNet variables directly because they do not return C/AL types. You can perform comparisons on the List.Capacity property because the List.Capacity property is a NET Framework integer type that returns a C/AL integer type. For more information about conversion between.net Framework and C/AL types, see.net Framework Type Conversion. dotnetlist1 := dotnetlist1.list(5); dotnetlist2 := dotnetlist2.list(10); dotnetlist3 := dotnetlist3.list(5); IF dotnetlist1.capacity <> dotnetlist3.capacity THEN ERROR('List1 and List3 should have the same capacity.'); IF dotnetlist1.capacity = dotnetlist2.capacity THEN ERROR('List1 and List2 should not have the same capacity.'); IF dotnetlist1.tostring() <> dotnetlist2.tostring() THEN ERROR('List1 and List2 should have the same ToString output.'); Events and Public Fields Microsoft Dynamics NAV 2009 R2 does not support events and public fields in the.net Framework. Long Member Names There is a limit of 30 characters on member names. To call a constructor that is longer than 30 characters, use the C/AL Symbol Menu because the constructor names are automatically truncated to 30 characters. You cannot directly call methods and properties that are more than 30 characters long because you cannot compile the Microsoft Dynamics NAV object. To resolve this issue, you can create a method that wraps the original method or property and has a name that is 30 characters or fewer. From C/AL code, you can then call the new method instead of the original method or property. 16 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2

19 Case Sensitivity in Member Names.NET Framework member names in C/AL code are case-sensitive. If you use the incorrect case when you call a member, then you get an error when you compile the object. This behavior differs from other C/AL variables because you can mix cases and still compile the object. For other C/AL variables, the case is corrected automatically the next time that you open the object. Local DotNet Variable Limitations You should not assign a local DotNet variable to global C/AL or.net Framework objects because the local DotNet variable is disposed when it goes out of scope. If you use the DotNet variable outside the scope of its local function, then you should define it as a global DotNet variable. DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2 17

20 How to: Call.NET Framework Members from C/AL Code You can call.net Framework type members, including methods, properties, and constructors, from C/AL code. To call members, you define a DotNet type variable that references the.net Framework assembly type that contains the member and then call the variable from C/AL code of the Microsoft Dynamics NAV object. A.NET Framework interoperability example is included in this topic. To create a variable for a.net Framework type 1. If the assembly that you want to reference is a custom assembly and not installed in the global assembly cache, then copy the assembly to the Add-ins folder of the Microsoft Dynamics NAV installation folder. By default, the path to the installation folder is C:\Program Files\Microsoft Dynamics NAV\60\Classic. For more information, see Global Assembly Cache in the MSDN Library. Tip You can install the assembly in the global assembly cache with the GAC utility. For more information, see GAC Utility in the MSDN Library. 2. In the Classic client, open Object Designer, and then open the object that will use.net Framework interoperability, such as the page or codeunit. 3. To open the C/AL code for the object, on the View menu, click C/AL Code. 4. To create the variable for.net Framework interoperability, do one of the following steps: To create a global variable, on the View menu, click C/AL Globals. To create a local variable, on the View menu, click C/AL Locals. Important A local DotNet variable, including any resources that it references, is disposed after the C/AL function to which it belongs is run. 5. On the Variables tab, in the Name field, type a name for the variable. 6. Set the DataType field to DotNet. 7. In the SubType field, click the AssistEdit button to open the.net Type List window. 8. In the Assembly field, click the AssistEdit button to open the Assembly List window. 9. If the assembly that you want to reference is in the global assembly cache, then click the.net tab. If the assembly is in the Add-ins folder of your Microsoft Dynamics NAV installation, then click the Dynamics NAV tab. 10. In the list of assemblies, select the assembly, and then click OK to return to the.net Type List window. If you do not see the assembly that you want, then make sure that you have installed it correctly. For more information, see step 1 of this procedure. 11. In the.net Type List window, select the type that contains the member that you want to call from the Microsoft Dynamics NAV object, and then click OK. The.NET Type List window displays all available types, including classes, enumerations, structs, and interfaces, which are available in the selected assembly. By default, variables are set to run the assembly instance on Microsoft Dynamics NAV Server. If you want to run the assembly instance on the RoleTailored client, see How to: Run a.net Framework Assembly on the RoleTailored Client or Server. 18 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2

21 To call members in a.net Framework type from C/AL code 1. Open the C/AL code for the object. 2. On the View menu, click C/AL Symbol Menu. You can use the C/AL Symbol Menu window to help you call constructors, members, and properties of the.net Framework type. 3. In your C/AL code, add the following code to call the constructor that creates a new instance of the type. If you are calling a static method, then a constructor is not required, and you can skip this step. MyVariableName.ConstructorName(arguments); The MyVariableName variable is the name of the.net Framework variable. The ConstructorName variable is the same as the type name. The arguments variable represents any parameters that you must set for the constructor. Note Member names are case-sensitive. Also, constructor names that are longer than 30 characters are truncated after 30 characters. 4. Add the following code to call the methods or properties. Example Description MyVariableName.MethodPropertyName(arguments); The MethodPropertyName variable is the name of the method or property that you want to call, and the arguments variable represents any arguments of the method or property. Important Some types in the System namespace of the.net Framework class library are automatically converted to C/AL types. You cannot assign values to.net Framework variables for these types. For more information, see.net Framework Type Conversion. Note Methods can be overloaded. Therefore see the description at the bottom of the C/AL Symbol Menu, which shows the parameter and return types for each method. Also, method and property names that are longer than 30 characters will be truncated, and you cannot compile the Microsoft Dynamics NAV object. For more information, see Calling.NET Framework Members From C/AL Code The following code example uses.net Framework interoperability to display headlines from an RSS feed from the Microsoft Dynamics NAV team blog, which has the following URL: This example calls members of the System.XML assembly, which is part of the Microsoft.NET Framework class library and is installed in the global assembly cache. DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2 19

22 To implement this example, you create a codeunit that has the following local variables. Variable name DataType SubType xml DotNet 'System.Xml, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089'.System.Xml.XmlDocument items DotNet 'System.Xml, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089'.System.Xml.XmlNodeList i Integer title DotNet 'System.Xml, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089'.System.Xml.XmlNode After you create the codeunit, add the following code to its OnRun trigger. Code xml := xml.xmldocument(); xml.load(' items := xml.selectnodes('/rss/channel/item'); FOR i := 0 TO items.count - 1 DO BEGIN END title := items.item(i).selectsinglenode('title/text()'); MESSAGE( title.value ); Comments To see the example in the RoleTailored client, you can create an action on a page that opens the codeunit. See Also Extending Microsoft Dynamics NAV Using Microsoft.NET Framework Interoperability 20 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2

23 How to: Set.NET Framework Types to Target the RoleTailored Client or Microsoft Dynamics NAV Server To extend a Microsoft Dynamics NAV object with.net Framework interoperability, you define a C/AL variable that calls members of a.net Framework type in an assembly. When the variable is called from the C/AL code of the Microsoft Dynamics NAV object, it creates an instance of the.net Framework type. You can set the type instance to target the RoleTailored client or Microsoft Dynamics NAV Server. By default, an assembly is set to target Microsoft Dynamics NAV Server. However, you can set the type to target the RoleTailored client. Important You cannot set different types of the same variable to target both the RoleTailored client and Microsoft Dynamics NAV Server. Setting the.net Framework Type to Target the RoleTailored Client To set a.net Framework type instance to target the RoleTailored client, you must complete the following tasks as described in this topic: Set the DotNet variable for the.net Framework type to target the RoleTailored client. Copy the.net Framework assembly to the computer running the RoleTailored client. Note You must copy the assembly to each computer running the RoleTailored client. If the assembly is included in the global assembly cache, then you do not have to do this task. To set the.net Framework type to target the RoleTailored client 1. In Object Designer, open the Microsoft Dynamics NAV object that uses.net Framework interoperability. 2. Do one of the following steps: For a global variable, on the View menu, click C/AL Globals. For a local variable, in the C/AL Editor, select the trigger that uses the DotNet variable, and then on the View menu, click C/AL Locals. 3. On the Variables tab, select the DotNet variable, and then on the View menu, click Properties. 4. In the Properties window, set the RunOnClient property to Yes. To copy a.net Framework assembly to a computer running the RoleTailored client On the computer running the RoleTailored client, copy the.net Framework assembly to the Add-ins folder of the RoleTailored client installation. By default, the path of this folder is C:\Program Files\Microsoft Dynamics NAV\60\RoleTailored Client\Add-ins. Note You can also put assemblies in a subfolder of the Add-ins folder. This can be useful when you have multiple versions of the same assemblies and dependencies. DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2 21

24 Setting the.net Framework Type to Target Microsoft Dynamics NAV Server To set a.net Framework type instance to target Microsoft Dynamics NAV Server, you must complete the following tasks as described in this topic: Set the variable for the NET Framework type to target Microsoft Dynamics NAV Server. Copy the.net Framework assembly to the computer running Microsoft Dynamics NAV Server. Note If the assembly is included in the global assembly cache of the computer running Microsoft Dynamics NAV Server, then you do not have to do this task. To set the.net Framework type to target Microsoft Dynamics NAV Server 1. In Object Designer, open the Microsoft Dynamics NAV object that uses.net Framework interoperability. 2. Do one of the following steps: For a global variable, on the View menu, click C/AL Globals. For a local variable, in the C/AL Editor, select the trigger that uses the DotNet variable, and then on the View menu, click C/AL Locals. 3. On the Variables tab, select the NET Framework variable type, and then on the View menu, click Properties. 4. In the Properties window, set the RunOnClient property to No. To copy a.net Framework assembly to the computer running Microsoft Dynamics NAV Server On the computer running Microsoft Dynamics NAV Server, copy the.net Framework assembly to the Add-ins folder in the Microsoft Dynamics NAV Server installation folder. By default, the path of the Microsoft Dynamics NAV Server installation folder is C:\Program Files\Microsoft Dynamics NAV\60\Server\Add-ins. See Also Note You can also put assemblies in a subfolder of the Add-ins folder. This can be useful when you have multiple assemblies and dependencies. Calling.NET Framework Members from C/AL Code How to: Call.NET Framework Members From C/AL Code 22 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2

25 .NET Framework Type Conversion In C/AL, some.net Framework data types, such as strings, integers, and decimals, are automatically converted to C/AL types. Because the types are converted, the.net Framework versions of these types are not supported in C/AL. For example, instead of using a.net Framework integer data type in your C/AL code, you should use a C/AL integer data type. When the C/AL integer is sent back to a.net Framework object, such as through a method call, then the C/AL integer is automatically converted to a.net Framework integer. Conversion Table for.net Framework and C/AL Types The following table lists the automatic data type conversions between.net Framework and C/AL types..net Framework type (range) System.Byte (0..255) System.SByte ( ) System.Char ( ) System.Int16 ( ) System.Int32 (-2,147,483,648..2,147,483,647) System.Int64 (-9,223,372,036,854,775, ,223,372,036,854,775,807) System.UInt16 ( ) System.UInt32 (0..4,250,000,000) System.UInt64 (0..18,446,744,073,709,551,615) System.Single (± e38) C/AL type (range) Char (0..255) Integer ( ) Integer (±2,147,483,647) Integer (±2,147,483,647) Integer (±2,147,483,647) BigInteger (±9,223,372,036,854,775,807) Integer (±2,147,483,647) BigInteger (±9,223,372,036,854,775,807) Decimal ( ,446,744,073,709,551,615) Decimal (± e38) Comments Single unsigned byte that represents a value from Single signed byte that represents a value from Unicode character that is represented internally as a 16-bit unsigned integer. Microsoft Dynamics NAV does not have a corresponding type, but values can be stored in an integer. Microsoft Dynamics NAV does not have a corresponding type, but values can be stored in a BigInteger. Microsoft Dynamics NAV does not have a corresponding type, but values can be stored in a decimal. System.Double (± e308) Decimal (± e308) DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2 23

26 .NET Framework type (range) System.Decimal (±79,228,162,514,264,337,593,543, 950,335) System.Int32 (±2,147,483,647) System.Enum ( ) System.Bool (TRUE, FALSE) System.String (0 to 1024 bytes) System.String (0 to 1024 bytes) System.DateTime 3 January year December 9999 System.DateTime System.DateTime C/AL type (range) Decimal (-999,999,999,999, ,999,999,999,999.99) Option (±2,147,483,647) Integer (±2,147,483,647) Boolean (TRUE, FALSE) Text (0 to 1024 bytes) BigText (up to 2 gigabytes) Code (0 to 1024 bytes.) Date 1 January year December 9999 Time (00:00:00..23:59:59.999) DateTime (January 1, 1753, 00:00: to December 31, 9999, 23:59:59.999) Comments An internal range that is not persisted to a field but is the type s native value range. Option values can be freely converted to numeric values. The range is the same as an integer. An enumeration is a named constant whose underlying type is any integer type except Char. If no underlying type is explicitly declared, then Int32 is used. Microsoft Dynamics NAV has no knowledge about the constant s name but only knows the value. Denotes a text string with a maximum length of 1024 characters. Text strings are singlebyte only. Denotes an alphanumeric string with maximum length of 1024 characters. The value is stored in uppercase. The common language runtime only supports DateTime. In Microsoft Dynamics NAV, Date must be converted to a DateTime value type when passing as a parameter, such as for CREATEDATETIME(d, T);. The common language runtime only supports DateTime. In Microsoft Dynamics NAV, Date must be converted to a DateTime value type when passing it as a parameter, such as for CREATEDATETIME( 0D, t);. The common language runtime DateTime object that will be used for storing a Microsoft Dynamics NAV Time value must handle daylight saving time and time zone. The time value does not change. The common language runtime DateTime value type represents dates and times with values ranging from 12:00:00 midnight, January 1, 1753 Common Era (CE) through 11:59:59 P.M., December 31, 9999 CE. 24 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2

27 .NET Framework type (range) TimeSpan (Resolution is 100 nanoseconds) System.Guid (128-bit number) C/AL type (range) Duration (Resolution is 1 millisecond) GUID (128-bit number) Comments A time interval is the duration of time or elapsed time that is measured as a positive or negative number of days, hours, minutes, seconds, and fractions of a second. Duration is internally represented as a 64-bit integer. System.IO.Stream InStream Streams require a context specific conversion and specialized stream types such as {Stream,String,Text}{Reader,Writer} classes. BLOB-related streams should typically use MemoryStreams. System.IO.Stream OutStream See Also Extending Microsoft Dynamics NAV Using Microsoft.NET Framework Interoperability DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2 25

28 Using.NET Framework Arrays An array is a data structure that contains several variables of the same type. The variables are treated as a single collection. Although you can already create arrays in C/AL, you can now use arrays from the.net Framework. Choosing whether to use a C/AL array or a.net Framework array depends on how you intend to use the data. For this scenario Your C/AL code uses.net Framework interoperability extensively, and you must share an array among many methods. Your C/AL code mostly uses basic C/AL types and does not interoperate with the.net Framework. Use this array type.net Framework array C/AL array To use a.net Framework array in C/AL, you must use the System.Array class in the.net Framework class library, which is the class from which all arrays inherit. When interfacing with an array in C/AL, you must use the following methods of the System.Array class to create and access elements in the array. Method CreateInstance SetValue GetValue Description Creates a new array instance that is passed to a method or property. Sets a value in an array element. Gets a value from an array element Many.NET Framework classes implement these methods. Therefore, they are available for you to use in C/AL code. If you are writing your own.net Framework code and want to use it in Microsoft Dynamics NAV, then you must implement these methods yourself. In C/AL, some.net Framework data types, such as strings, integers, and decimals, are automatically converted to C/AL types. If a.net Framework array contains these data types, then you create an assembly that contains methods that return the information about the data types and then reference the assembly in the C/AL code. This concept is illustrated in the following examples. Example: Using Native C/AL Data Types in a.net Framework Array The following example shows how you can use a.net Framework array for an integer data type. 1. In Visual Studio, create a C# class library project called NavInteropHelper that contains a method that returns the information about the integer type as follows: namespace Microsoft.Dynamics.Nav.NavInteropHelper; { } public class WrapInt32 { } public static Type GetTypeOfInt32() { } return typeof(int32); 26 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2

29 2. Build the project, and then copy the assembly to the Add-ins folder of the Microsoft Dynamics NAV installation folder. By default, the path of the installation folder is C:\Program Files\Microsoft Dynamics NAV\60\Classic. 3. In the Classic client, open a Microsoft Dynamics NAV object, open the C/AL code, and then create the following C/AL variables. Variable name DataType SubType vardotnet DotNet 'NavInteropHelper, Version= , Culture=neutral, PublicKeyToken=null'.Microsoft.Dynamics.Nav.NavInteropHelper.WrapInt32 vararray DotNet 'mscorlib, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089'.System.Array arraysize i aldata Integer Integer Integer 4. On a trigger of the Microsoft Dynamics NAV object, add the following C/AL code to create, fill, and implement the array. // Sets the number of elements in the.net Framework array. arraysize := 10; // Creates an instance of the.net Framework array that contains the Int32 type. vararray := vararray.createinstance(vardotnet.gettypeofint32(), arraysize); // Clears the object instance because it is no longer used. clear(vardotnet); // Sets the data in the array. FOR i := 0 TO (arraysize -1) DO vararray.setvalue(i+100,i); // Gets the array data and validates the content. The object that is returned by // GetValue is automatically converted into a C/AL integer in the assignment. DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2 27

30 FOR i := 0 TO (arraysize -1) DO BEGIN aldata := vararray.getvalue(i); if aldata <> (i+100) then error('invalid array data in element %1, expected %2, actual %3', i, i+100, aldata); END; Example: Using User-Defined Classes in a.net Framework Array This example shows how you can use a.net Framework array that includes user-defined classes. 1. In Visual Studio, create a C# class library project called NavInteropHelper that contains methods that return the information about the types as follows. namespace Microsoft.Dynamics.Nav.NavInteropHelper; { } public class WrapInt32 { } public int Data { get; set; } public WrapInt32(Int32 value) { } Data = value; 2. Build the project, and then copy the assembly to the Add-ins folder of the Microsoft Dynamics NAV installation folder. By default, the path of the installation folder is C:\Program Files\Microsoft Dynamics NAV\60\Classic. 3. In the Classic client, open a Microsoft Dynamics NAV object, open the C/AL code, and then create the following C/AL variables. Variable name DataType SubType vardotnet DotNet 'NavInteropHelper, Version= , Culture=neutral, PublicKeyToken=null'.Microsoft.Dynamics.Nav.NavInteropHelper.WrapInt32 vararray DotNet 'mscorlib, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089'.System.Array arraysize i aldata Integer Integer Integer 4. On a trigger of the Microsoft Dynamics NAV object, add the following C/AL code to create, fill, and implement the array. 28 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2

31 // Sets the number of elements in the.net Framework array. arraysize := 10; // Creates an instance of the.net Framework object so the type information // can be retrieved. vardotnet := vardotnet.wrapint32(1); // Creates an instance of the.net Framework array that contains the // user-defined type. vararray := vararray.createinstance(vardotnet.gettype(), arraysize); // Clears the object instance because it is no longer used. clear(vardotnet); // Sets data in the array. FOR i := 0 TO (arraysize -1) DO BEGIN vardotnet := vardotnet.wrapint32(i+100); vararray.setvalue(vardotnet,i); END; // Gets array data and validates content. FOR i := 0 TO (arraysize -1) DO BEGIN vardotnet := vararray.getvalue(i); // Gets the integer value from the.net Framework object using the Data property. aldata := vardotnet.data; if aldata <> (i+100) then error('invalid array data in element %1, expected %2, actual %3', i, i+100, aldata); END; See Also Calling.NET Framework Members from C/AL Code How to: Call.NET Framework Members From C/AL Code.NET Framework Type Conversion DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2 29

32 Using.NET Framework Collections In Microsoft Dynamics NAV, a common development task is to write code that loops through a set of records and performs an operation on each record in the set. You can do the same task in the.net Framework with a collection, which is a.net Framework object that you can iterate over. To loop through a collection in Microsoft Dynamics NAV, the.net Framework object must support the System.Collections interface. Many types in the.net Framework and assemblies that inherit from.net Framework types support the System.Collections interface. The following example shows how you can write C/AL code to handle collections for a type that supports the System.Collections interface. Example The following example implements the System.Collections.ArrayList interface and uses the GetProcesses method from the System.Diagnostics.Process type to display a list of process IDs in message boxes. Although this is not a typical example for an ERP product such as Microsoft Dynamics NAV, it shows the flexibility that you get with the.net Framework. The example requires that you define the following C/AL variables. Variable name DataType SubType MyProcessList DotNet 'mscorlib, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089'.System.Array Process DotNet 'System, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089'.System.Diagnostics.Process I Integer MyProcessList := Process.GetProcesses(); FOR I:=0 TO (MyProcessList.Length()-1) DO BEGIN Process := MyProcessList.GetValue(I); MESSAGE(FORMAT(Process.Id)); END; See Also.NET Framework Type Conversion How to: Call.NET Framework Members From C/AL Code 30 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2

33 Using.NET Framework Enumerations In the.net Framework, an enumeration commonly represents constant values as symbolic or literal names. For example, if you have the type Color, then instead of using the values 0, 1, and 2, you can use Red, Green, and Blue. In C/AL, you must assign an enumeration to an Integer data type, so you must convert symbolic names in the.net Framework to integers in C/AL. Example This example shows how to use an enumeration in integer expressions in C/AL and then convert the text string back to an integer to store it in the enumeration variable. In the following C# example, the enumeration is contained in the Microsoft.Dynamics.Nav.EnumSample assembly. namespace Microsoft.Dynamics.Nav.EnumSample; { } public class DataTypes } public enum ItemEnum { }; Item1, Item2, Item3, Item4 In the Microsoft Dynamics NAV object, define the following C/AL variables. Variable name DataType SubType Length vardotnet DotNet 'Microsoft.Dynamics.Nav.EnumSample, Version= , Culture=neutral, PublicKeyToken=18cff5e0dac2f853'. Microsoft.Dynamics.Nav.EnumSample.DataTypes.ItemEnum formatresult Text 30 alinteger Integer To handle the enumerator type, add the following code to a C/AL function. // Assign an integer to the.net Framework enumeration. // This assigns Item3 because enum values are zero-based. vardotnet := 2; // Convert the enum object to a text string, which is equivalent to the //.NET Framework ToString method. formatresult := format(vardotnet); if formatresult <> 'Item3' then DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2 31

34 error('wrong enumeration value. Expected %1, but actual was %2.', 'Item3', formatresult); // Assuming that the enum value is stored as a text string, convert it back to the // proper enum value. vardotnet := vardotnet.parse(vardotnet.gettype(), 'Item4'); // The vardotnet enum should now contain the integer value 3 and the enum 'Item4'. alinteger := vardotnet; if alinteger <> 3 then error('wrong enumeration integer value. Expected %1, but actual was %2.', 3, alinteger); formatresult := format(vardotnet); if formatresult <> 'Item4' then error('wrong enumeration value. Expected %1, actual was %2.', 'Item4', formatresult); See Also Calling.NET Framework Members from C/AL Code How to: Call.NET Framework Members From C/AL Code.NET Framework Type Conversion 32 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2

35 Using.NET Framework Generics In the.net Framework, you can use generics to customize a method, class, structure, or interface according to the data type that it acts upon. Instead of writing a method, class, structure, or interface for a particular type, you can write it to use any type. When a generic is instantiated, the type is specified. For example, if you use the generic type parameter T, then you can write a List<T> class that is instantiated as either List<int>, List<string>, or List<MyClass>. With.NET Framework interoperability, you can define DotNet variables for generics. You cannot specify generic type names in C/AL. When a generic is instantiated by a constructor in C/AL, all type names are set to the System.Object type. For example, if you have a mylist DotNet variable for the System.List<T> generic, you create an instance of mylist in C/AL as shown. mylist is instantiated as a List<Object> type. mylist := mylist.list(); If a method returns an instance of a generic whose type name is defined, then the type name is applied. In the following example, the method returns a List<String> instance, and mylist is instantiated as a List<String> type. mylist := x.getastringlist(); Example The following example constructs a string list, fills the list with data, and then uses the Item method to validate whether the list contains the expected data. The Item method is equivalent to a C# index operator. Variable name Data Type SubType Length vardotnet DotNet 'mscorlib, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089'.System.Collections.Generic. List`1 textresult Text 30 i capacity Integer Integer capacity := 5; vardotnet := vardotnet.list(capacity); FOR i:= 0 TO (capacity-1) DO vardotnet.add(format(i)); IF vardotnet.count <> capacity THEN ERROR('Wrong list count, expected {0}, actual {1}', capacity, vardotnet.count); FOR i:= 0 TO (capacity-1) DO BEGIN DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2 33

36 textresult := vardotnet.item(i); IF textresult <> FORMAT(i) THEN ERROR('List index [%1] contains the wrong data, expected %2, actual %3', i, FORMAT(i), textresult); END; See Also Calling.NET Framework Members from C/AL Code How to: Call.NET Framework Members From C/AL Code 34 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2

37 Using.NET Framework Interfaces With.NET Framework interoperability in C/AL, you can define variables for.net Framework interface types. This is useful when you have a class that explicitly implements an interface. In the.net Framework, when an interface is explicitly implemented, you cannot call methods that belong to the interface directly from the class instance. To call a method, you must cast to the interface. This condition is similar in C/AL except that C/AL does not have a cast operation. In C/AL, you cannot call a method of an explicitly implemented interface directly on the DotNet variable for the class. Instead, you do the following steps: 1. Create a DotNet variable for the interface. 2. Assign the class variable to the interface. 3. Call the interface methods on the DotNet variable for the interface. Example In the following C# example, you have the Sample class that explicitly implements the ISample interface. class Sample : ISample { }... string ISample.Name() { }... To call the ISample.Name method from C/AL code, you create the following variables. Variable name DataType SubType (simplified) cvar DotNet Sample ivar DotNet ISample After you create the variables, add the following code that assigns the class variable to the interface variable and then calls the interface s method. // Assigns the class variable to the interface variable. ivar := cvar;... // Calls the method of the interface. ivar.name();... DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2 35

38 Calling External Web Services with Windows Communication Foundation In Microsoft Dynamics NAV 2009 R2, you can use the Windows Communication Foundation, which provides a set of reliable objects for calling web services to use with.net Framework interoperability. Example The following code example uses a proxy web service class and calls a Read method from the Microsoft Dynamics NAV web service. To set up this example, you expose page 42 as a web service in the Web Service table and then generate and compile the proxy class. For more information, see Working with Web Services in the MSDN Library. The example requires the following variables. Variable name DataType SubType Length navbinding DotNet 'System.ServiceModel, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089'.System.ServiceModel.BasicHttpB inding address text 256 salesorderservice DotNet 'SalesOrderService, Version= , Culture=neutral, PublicKeyToken=null'.NAV.SalesOrderService.SalesOrder_PortClient endpointaddress DotNet 'System.ServiceModel, Version= , Culture=neutral, PublicKeyToken=b77a5c561934e089'.System.ServiceModel.EndpointA ddress salesorder DotNet 'SalesOrderService, Version= , Culture=neutral, PublicKeyToken=null'.NAV.SalesOrderService.SalesOrder navbinding := navbinding.basichttpbinding; // Set security mode to BasicHttpSecurityMode.TransportCredentialOnly navbinding.security.mode := 4; address := ' // Set client credential type to HttpClientCredentialType.Windows navbinding.security.transport.clientcredentialtype := 4; // salesorderservice := salesorderservice.salesorder_portclient(navbinding, endpointaddress.endpointaddress(address); // Set impersonation level to System.Security.Principal.TokenImpersonationLevel.Delegation salesorderservice.clientcredentials.windows.allowedimpersonationlevel := 4; 36 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2

39 // Include the sales order ID to be read. salesorder := salesorderservice.read('10000'); See Also Calling.NET Framework Members from C/AL Code How to: Call.NET Framework Members From C/AL Code DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2 37

40 How to: Add a FactBox on a Page Using the Wizard In Microsoft Dynamics NAV 2009 R2, you can use the Page Wizard to add a FactBox to a new page. A FactBox is an area that is located on the right side of a page, and you can use FactBoxes to display other pages, charts, or system parts. You typically use a FactBox to display information that is related to an item on the main content page. For example, on a page that shows a sales order list, you can use a FactBox to show customer details for a selected sales order in the list. A FactBox is divided into one or more parts that are arranged vertically. Each part can contain one of the following objects: Page of the CardPart or ListPart type. Chart. System part, including Microsoft Outlook, Notes, MyNotes, or RecordLinks. Using the wizard, you can add a FactBox on the following page types: Card Document 38 DEVELOPER UPDATES FOR MICROSOFT DYNAMICS NAV 2009 R2