Deprecated APIs

This document provides the list of deprecated APIs and migration guidance for some of the deprecated APIs.

Overview

A number of APIs from Dynamics AX 2012 have been identified. The reason for the deprecation for each API varies. Most commonly, the reasons are one of the following:

  • Not suited/applicable to the new client.
  • Degrade performance.
  • Chatty (cause lot of traffic back and forth between server and client).
  • Redundant (framework automatically handles these now).

Throughout this table, under the
Reason for Deprecation heading, "the client" refers to the web client.

List of deprecated APIs

Object Type Name Notes
ActionPane Method tabChanged Updates to ActionPanes (or controls inside of ActionPanes) should be done based on the active row, not when the tab becomes active.
ActionPaneTab Method selectionChanged Updates to ActionPaneTabs (or controls inside of ActionPaneTabs) should be done based on the active row, not when the tab becomes active.
Box Method yesNoTextMenu-
LinkText
ComboBox Method getEditText Overview
N/A
Reason for deprecation
Redundant.
Migration notes
Use getText instead.
DataSet DataSetNode DataSetRun Class Overview
Used in Dynamics AX 2012 with Enterprise Portal.
Reason for deprecation
Not applicable in the client.



Migration notes
Remove calls to these APIs from your code.

DataSourceMethodInfo
DataSourceMethodInfoList
Class
DDEClient DDEServer DLL DLLFunction HDC HWnd Thread WinAPINative WinGDI Class Overview
N/A
Reason for deprecation
Specific to Dynamics AX 2012 Windows client and not compatible with the client.
Migration notes
Remove usage of these APIs from your code.
DocumentManagement-
Helper
Class
Form Method addhistory
currentHistoryName
currentHistoryState
updateHistory
Overview
Used in Dynamics AX 2012 with address bar.
Reason for deprecation
Navigation model in the client has changed.

Migration notes
Remove calls to these APIs from your code.
Form Method arrange
Form Method controlCallingMethod
Form Method controlMethod-
Overload controlMethod-
OverloadObject
Overview
Used in Dynamics AX 2012 to register override methods.
Reason for deprecation
This is not a clean and recommended way to register override methods.

Migration notes
Use registerOverrideMethod instead.
Form Method copy cut paste
Form Method delAutoCompleteString getAutoCompleteString setAutoCompleteString Overview
Used in Dynamics AX 2012 to set, get, and delete automatic suggestions.
Reason for deprecation
Specific to Dynamics AX 2012 Windows client.
Migration notes
Remove calls to these APIs from your code.
Form Method firstField
Form Method formOnTop Overview
Used in Dynamics AX 2012 to manage windows and navigation.
Reason for deprecation
The client has a new navigation model.
Migration notes
Remove calls to these APIs from your code.
Form Method hWnd installMessageProc removeMessageProc Overview
N/A
Reason for deprecation
Specific to Dynamics AX 2012 Windows client and not compatible with the client.
Migration notes
Remove usage of these APIs from your code.
Form Method isPreloadedInstance Overview
Used in Dynamics AX 2012 with preloading.
Reason for deprecation
Preloading is not applicable in the client.
Migration notes
Remove calls to these APIs from your code.
Form Method lastField nextField nextGroup prevField prevGroup
Form Method Lock
lockWindowUpdate
unLock
Overview
These methods were used to prevent the redrawing of windows when performing a set of UI updates. Without these the window would be redrawn in response to each individual change leading to bad end-user experience and degraded performance.
Reason for deprecation
These methods are specific to the Windows client and are no longer needed for the client.
Migration notes
A code upgrade rule has been provided to remove occurrences of these APIs. You can safely remove any calls to these APIs from your code.
Form Method print printPreview send Overview
Used in Dynamics AX 2012 to override the Auto Report generation for the form
Reason for deprecation
Microsoft 365 integration offers a better user experience in the client. The ‘Export’ function is available for the user in the Dynamics AX client forms.
Migration notes
Remove calls to these APIs from your code.
Form Method redraw
resetStatusBar-
BackgroundColor
setStatusBar-
BackgroundColor
sysColorChanged
Overview
Used to control styles or colors.
Reason for deprecation
Remove ability for developers to specify the colors via API for consistent visuals.
Migration notes
A code upgrade rule has been provided to remove occurrences of the redraw API. Remove usage of these APIs from your code.
Form Method reload
Form Method resetSize Overview
This method was used when controls were added/removed from a form causing its size to change. Without it the window might not be correctly sized to account for the added/removed controls.
Reason for deprecation
These methods are specific to the Windows client and are no longer needed for the client.
Migration notes
You can safely remove any calls to these APIs from your code.
Form Method resize
FormActiveXControl
FormAnimateControl
FormBuildActiveXControl
FormBuildAnimateControl
FormBuildManaged-
HostControl
FormBuildSegmented-
EntryControl FormManagedHostControl
FormSegmented-
EntryControl
Class Overview
These were used to host or create various custom controls for Dynamics AX 2012.
Reason for deprecation
These technologies will not work with the client.
Migration notes
Application developers need to build replacement controls where needed using the control extensibility features.
FormControl Method beginDrag
dragDrop
dragLeave
dragOver
dragOverEx
dragText
drop
dropEx
dropFile
endDrag
Overview
Used to enable drag-and-drop scenarios in Dynamics AX 2012.
Reason for deprecation
Drag-and-drop scenarios are not supported in the client.
Migration notes
Remove usage of these APIs from your code and refactor to enable the scenarios without dependency on drag-and-drop functionality.
FormControl Method calcControlSize
FormControl Method command processBase processForm processLink processPicture processTitle Overview
Was marked for deprecation in Dynamics AX 2012.
Reason for deprecation
N/A
Migration notes
Remove calls to these APIs from your code.
FormControl Method context showContextMenu Overview
This method was used when controls were added/removed from a form causing its size to change. Without it the window might not be correctly sized to account for the added/removed controls.
Reason for deprecation
These methods relied on APIs that are specific to the Windows client.
Migration notes
Use getContextMenuOptions and selectedMenuOptions instead.
FormControl Method copy cut paste
FormControl Method dateTextChange
FormControl Method editControl
FormControl Method hasControl-
PositionOverride
FormControl Method helpField
FormControl Method hWnd Overview
N/A
Reason for deprecation
Specific to Dynamics AX 2012 Windows client and not compatible with the client.
Migration notes
Remove usage of these APIs from your code.
FormControl Method inputSearch
FormControl Method itemChanging
FormControl Method keyDown
FormControl Method labelMouseDblClick
mouseDblClick
Overview
The FormControl.labelMouseDblClick (int x, int y, int button, Boolean Ctrl, Boolean Shift) method is called when the label for a control is double-clicked. It provides the x, y co-ordinates of the mouse pointer, a Boolean to indicate which mouse button was clicked and Booleans to indicate whether the Ctrl and Shift key were pressed. The FormControl.mouseDblClick (int x, int y, int button, Boolean Ctrl, Boolean Shift) method is similar in function to the labelMouseDblClick method. The difference is that this method is called whenever there is a double-click (not just on the labels).
Reason for deprecation
The double-click action does not translate well to web-based application and touch-based scenarios. Additionally they might end up being chatty in many instances.
Migration notes
The recommended replacement for these methods is to use a button and the clicked event.
FormControl Method labelMousedown labelMouseup mouseDown mouseEnter mouseLeave mouseMove mouseUp Overview
Used to detect and respond to mouse events.
Reason for deprecation
These are not touchscreen friendly and not supported in the client.
Migration notes
Remove usage of these APIs from your code and refactor to enable the scenarios without dependency on mouse events.
FormControl Method onHScroll onVScroll
FormControl Method paint
FormControl Method prefColumnSize Overview
Used in Dynamics AX 2012 to control width and height
Reason for deprecation
Not applicable in the client.
Migration notes
Set the width and height explicitly instead.
FormControl Method selectionChanging
FormControl Method setScrollInfo
FormControl Method size
FormControl Method updateWindow
FormControl / FormDesign Property AcquireFocus
FormControl / FormDesign Property ActiveBackCol ActiveBackColor ActiveBackColorRGB ActiveForeColor ActiveForeColorRGB AlternateRowShading BackgroundColor BackgroundColorRGB BackStyle BackStyleRGB CharacterSet ColorScheme DrawFocusRect ForegroundColor ForegroundColorRGB GridLines GridLinesStyle PromptRect Overview
Used to control styles or colors.
Reason for deprecation
Remove ability for developers to specify the colors via API for consistent visuals.
Migration notes
Remove usage of these APIs from your code.
FormControl / FormDesign Property AlignChild AlignChildren AlignControl Border BottomMargin BottomMarginMode ColumnSpace ColumnSpaceMode ColumnSpaceValue Left LeftMargin LeftMarginMode LeftMode RightMargin RightMarginMode SizeHeight SizeWidth TabAppearance TabAutoChange TabLayout TabMode TabPlacement Top TopMargin TopMarginMode TopMode VerticalSpacing VerticalSpacingMode VerticalSpacingValue Overview
Used to control layout.
Reason for deprecation
Remove ability for developers to control layout using this property to achieve a consistent layout.


Migration notes
Remove usage of these APIs from your code. Use styles or CSS instead.

FormControl / FormDesign Property AllowDocking AlwaysOnTop ArrangeGuide ArrangeWhen ContainerScroll-
HorizontalOffset ContainerScroll-
VerticalOffset IMEMode MaximizeBox MinimizeBox Mode NeededAccessLevel ProgressType Securable SecurityKey StatusBarStyle WindowResize
Overview
N/A
Reason for deprecation
Specific to Dynamics AX 2012 Windows client, no longer needed.
Migration notes
Remove usage of these APIs from your code.
FormControl / FormDesign Property Bold
FormControl / FormDesign Property CanScroll
FormControl / FormDesign Property DisabledImage DisabledImageLocation DisabledResource
FormControl / FormDesign Property DisplayTarget HyperLinkDataSource HyperLinkMenuItem SaveFilter SaveSize Overview
Used in Dynamics AX 2012 with Enterprise Portal
Reason for deprecation
Not applicable in the client.
Migration notes
Remove calls to these APIs from your code.
FormControl / FormDesign Property Font
FormControl / FormDesign Property FontSize
FormControl / FormDesign Property Frame FramePosition Overview
N/A
Reason for deprecation
Remove ability for developers to control frames via metadata.
Migration notes
Remove usage of these APIs from your code.
FormControl / FormDesign Property HideToolbar HorizontalScrollBarVisible Scrollbars VerticalScrollBarVisible Overview
N/A.
Reason for deprecation
Remove ability for developers to control scrollbars via metadata.
Migration notes
Remove usage of these APIs from your code.
FormControl / FormDesign Property ImageMode
FormControl / FormDesign Property ImageName
FormControl / FormDesign Property ImageResource
FormControl / FormDesign Property Italic
FormControl / FormDesign Property LabelAlignment
FormControl / FormDesign Property LabelBold
FormControl / FormDesign Property LabelCharacterSet
FormControl / FormDesign Property LabelFont
FormControl / FormDesign Property LabelFontSize
FormControl / FormDesign Property LabelForegroundColor LabelForegroundColorRGB
FormControl / FormDesign Property LabelGuide
FormControl / FormDesign Property LabelHeight LabelHeightMode LabelHeightValue
FormControl / FormDesign Property LabelItalic
FormControl / FormDesign Property LabelUnderline
FormControl / FormDesign Property LabelWidth LabelWidthMode LabelWidthValue
FormControl / FormDesign Property Location
FormControl / FormDesign Property NormalResource
FormControl / FormDesign Property ParentPage
FormControl / FormDesign Property SearchAfterInput SearchMode
FormControl / FormDesign Property SelectControl
FormControl / FormDesign Property SendExternalContext
FormControl / FormDesign Property ShortKey
FormControl / FormDesign Property Underline
FormDataRow Class
FormDataSource Property autoNotify Overview
Was marked for deprecation in Dynamics AX 2012.
Reason for deprecation
N/A
Migration notes
Remove usage from your code.
FormDataSource Method cacheOnlyMode
FormDataSource Method cacheRemoveRecord
FormDataSource Method defaultMark
FormDataSource Method findRecord findValue Usage
The FormDataSource.findRecord( Common record) method finds a specific record in the data source and makes it the current record. The FormDataSource.findValue(FieldId field, str value) method find a specific value in a specific field in the data source and makes the corresponding record the current record. It uses the FormDataSource.findRecord method for this.
Reason for deprecation
These methods use linear searching and load a large number of records in memory and negatively impact performance.
Migration notes
Replace with new APIs. Replace findRecord with positionToRecord and findValue with positionToRecordByValue. New APIs do not work in some cases, most notably with Temp tables and Views. The framework will throw an exception in those cases. If replacing with new APIs is not possible, recommended replacement is to call element.args(). lookupRecord(recordToFind) Followed by FormDataSource.research(false); FormDataSource is the data source that contains the record you want to find. Passing in a “false” argument to research causes it to not retain the current position since we want to change the position to the record we found using args.lookupRecord avoids resetting sort order, ranges, etc.
FormDataSource Method getDataRow
FormDataSource Method markAllLoadedRecords
FormDataSource Method maxPagingRowCountValue pagingEnabled startRowIndex setPagingParameters totalNumberOfRows Overview
Used in Dynamics AX 2012 with Enterprise Portal
Reason for deprecation
Not applicable in the client.
Migration notes
Remove calls to these APIs from your code.
FormDataSource Method print
FormDesign Method cssClass localWebMenu showWebHelp supportReload Overview
Used in Dynamics AX 2012 with Enterprise Portal
Reason for deprecation
Not applicable in the client.
Migration notes
Remove calls to these APIs from your code.
FormObjectSetNotify Method onPaging-
ParametersChanged
FormObjectSetPaging-
ParamsChangedEvtArgs
Class
Global xInfo Method endLengthyOperation startLengthyOperation Overview
These methods were used to show/stop showing a progress indicator during long running operations.
Reason for deprecation
In the client, the system automatically takes care of showing/hiding the progress indicator and calls to these APIs are not needed.
Migration notes
You can safely remove any calls to these APIs from your code.
Image Method captureScreen captureWindow clipboardCopy clipboardPaste crop displayImage displayOrign exportBitmap flip getImageDimensionUnits getPixel height imageInfo imageSpotlight promoteColor reduceColorOctree resize rotate saveImage saveType transparent width
ListPage Page Method activeActionPane-
TabNames
Overview
This method was used to find the active action pane tab.
Reason for deprecation
In the client, Action Pane tabs are handled client-side only, the server is not aware of the state.


Migration notes
Remove usage of this API from your code.

MessageWin Class
Object Method notify notifyAll wait Overview
Used to block and wait for an interaction/operation and notify to unblock.
Reason for deprecation
These calls are deprecated for all objects except formRun and it’s derivatives.
Migration notes
Calls to these APIs from formRun or it’s derivatives are allowed. Calls to these APIs from any other object should be removed.
Object Method objectOnServer Overview
Used to determine whether an object is on the server.
Reason for deprecation
This is redundant and no longer required because all objects are on the server.
Migration notes
You can safely remove calls to these APIs from you code. It will always evaluate to true.
Object Method setTimeOut Overview
This method existed on Object, but was non-functional. The implementation on FormRun was used as a timer to delay the execution of a piece of logic.
Reason for deprecation
The browser based client no longer supported this implementation.
Migration notes
Use the new setTimeOutEx method on the FormRun instead. Note that the setTimeOutEx method expects the callback to accept a parameter of type AsyncTaskResult, example: myCallBack(AsyncTaskResult result).
PopupMenu Class Overview
Used in Dynamics AX 2012 to get splitters that let users change the size of the two parts that are split.
Reason for deprecation
Relied on APIs that are specific to the Dynamics AX 2012 Windows Client and cannot be used with the client.
Migration notes
Use ContextMenu instead.
SysExcel Class Overview
The SysExcel classes used COM to create and edit Excel workbooks.
Reason for deprecation
SysExcel relied on calls to Excel COM objects from the client. Those COM objects are not on the server and COM calls are highly discouraged going forward.
Migration notes
Use the OpenXML .NET framework APIs instead. We are investigating the creation of an assembly that wraps OpenXML to make it easier to call from X++.
SysINetMai SysMailer SmmOutlook Class Overview
These email related classes used predominantly client-side technologies that are no longer available and/or are highly discouraged.
Reason for deprecation
The SysINetMail class is being deprecated because it used client-side MAPI. The SysMailer class is being deprecated because it used CDO (a variant of OLE messaging). The classes beginning with SmmOutlook are being deprecated since they use Outlook COM objects.
Migration notes
Sending email via SMTP using the SysMailerNet class will be supported going forward. We are also actively working on client-side interactive email capabilities.
SysFormSplitter Class Overview
Used in Dynamics AX 2012 to get splitters that let users change the size of the two parts that are split.
Reason for deprecation
No longer needed in the client.
Migration notes
Controls automatically provide the functionality. You can safely remove any calls to these APIs from your code. A code upgrade rule may be created in the future to automatically remove the usage.
SysListPageHelper Class
SysSetupFormRun Class Overview
Used to by classes to indirectly extend FormRun.
Reason for deprecation
Has been merged with FormRun class.
Migration notes
Use the FormRun class instead.
TextBuffer Method fromFile Use the .NET StreamReader class instead.
TextBuffer Method toFile Use the .NET StreamWriter class instead.
Thread Class Overview
N/A
Reason for deprecation
Specific to Dynamics AX 2012 Windows client and not compatible with the client.
Migration notes
Consider replacing with the new runAsync method or remove usage of these APIs from your code.
WinAPI Class Overview
N/A
Reason for deprecation
Specific to Dynamics AX 2012 Windows client and not compatible with the client.
Migration notes
Remove usage of these APIs from your code. Replace file access APIs, such as WinAPI::getTempPath, WinAPI::fileExists, with the new file APIs.
WinAPIServer Method cryptProtectData cryptUnprotectData Overview
The WinAPIServer::cryptProtectData( CryptoBlob _unEncryptedDataBlob) and WinAPIServer::cryptUnProtectData( CryptoBlob _encryptedDataBlob) methods were used to encrypt and decrypt sensitive data.
Reason for deprecation
These methods are best suited to desktop usage and not recommended for web-based application usage. They also have a negative impact on performance.
Migration notes
Use the .NET framework APIs and well-known hashing/security algorithms instead.
xApplication Method runAsync Overview
In Dynamics AX 2012 the xApplication::runAsync method was used to make asynchronous calls to methods.
Reason for deprecation
Replaced with methods better suited to the client.
Migration notes
Use runAsync methods on the Global or FormRun classes instead. These new versions of runAsync enable the caller to make an async call to a static X++ class method. They leverage the .NET System.Threading.Tasks library to execute an async method in X++. The use of the System.Threading.Tasks.Task type allows the developer to take advantage of the rich set of features available in .NET.
xGlobal Method clientKind Overview
Most commonly used to detect presence of client, such as an interactive session.
Reason for deprecation
Replaced with a method better suited to the client.
Migration notes
Use global::hasGUI method instead.
xGlobal Method computerName
xGlobal Method forceFormPreload Overview
Used in Dynamics AX 2012 with preloading.
Reason for deprecation
Preloading is not applicable in the client.
Migration notes
Remove calls to these APIs from your code.
xGlobal Method terminalServer
xInfo Method directory
xInfo Method navPane
XmlDocument Method LoadSave
XmlWriter Method CreateNewFile
XppCompiler Class