Programming models for Dynamics 365 Customer Engagement (on-premises)

Microsoft Dynamics 365 Customer Engagement (on-premises) offers several programming models designed to give you the flexibility to decide what works best for your needs.

The following diagram illustrates the key programmability scenarios for Dynamics 365 Customer Engagement (on-premises). Use the appropriate Dynamics 365 Customer Engagement (on-premises) programming models for the type of solutions you create.

Connecting to Dynamics 365 Customer Engagement (on-premises)

When you write clients to access data in Dynamics 365 Customer Engagement (on-premises) you have two options: you can use the Web API or the organization service.

Web API

The Web API was introduced with December 2016 update for Dynamics 365 (online and on-premises) and it provides a development experience that can be used across a wide variety of programming languages, platforms, and devices. The Web API implements the OData (Open Data Protocol) v4. OData is an OASIS standard for building and consuming RESTful APIs over rich data sources.

When you use the Web API, you can choose from a list of community-supported libraries that support the OData v4 standard. You can also choose to write code using HTTP directly. More information: Use the Dynamics 365 Customer Engagement Web API

When you connect to Dynamics 365 for Customer Engagement (on-premises) environments with Internet-facing deployment (IFD), you can use Azure AD Authentication Libraries (ADAL) to enable authentication from a wide variety of programming languages and platforms. More information: Authenticate to Dynamics 365 Customer Engagement (on-premises) with the Web API

The organization data service («REST endpoint» or «OData endpoint») is an OData v2 service that was deprecated in December 2016 update for Dynamics 365 (online and on-premises) in favor of the Web API. The organization data service isn’t included in the preceding diagram. The organization service is still available to support code that used it. However, for any new development for Dynamics 365 Customer Engagement (on-premises) we recommend using the Web API. More information: Use the OData endpoint with web resources

Organization service

If you are a .NET developer you can use either the Web API or the organization service. With the organization service you can use a set of assemblies and tools to generate strongly typed classes that include custom entities and attributes that have been added to an instance of Dynamics 365 Customer Engagement (on-premises).

With SDK assemblies and tools for code generation you can also include an OrganizationServiceContext, which is based on the same concept as the DataServiceContext in Windows Communication Foundation (WCF) Data Services. This class lets you track changes, manage identities and relationships, and gives you access to the Dynamics 365 Customer Engagement (on-premises) .NET Language-Integrated Query (LINQ) provider so you can build queries using LINQ. When you use the tools for code generation, you get strongly typed classes for entities and attributes that are defined when the code generation tool is run. These are called early-bound classes. More information: Use the Early Bound Entity Classes in Code

When your code needs to work with entities and attributes that weren’t known at the time that the code generation tools were run, you can use an Entity class that allows for specifying entities and entity attribute in your code. This late-bound style of writing code provides greater flexibility but doesn’t allow for compile-time checking of all types so that no implicit casts occur. Late binding checks types only when the object is created or an action is performed on the type. The Entity class requires types to be explicitly specified to prevent implicit casts. More information: Use the Late Bound Entity Class in Code

If you create a Windows client or are using Windows PowerShell, Xrm.Tooling provides a set of APIs that use the SDK assemblies to provide additional capabilities and resources specifically for Windows client development. More information: Build Windows client applications using the XRM tools

Extending on the server

You can write code that listens for events and applies custom business logic to modify or augment the standard behavior of the platform. This code is only available to be written using .NET managed code and the developer experience is based on the same objects defined in the SDK assemblies. You can work with the organization service to perform operations with Dynamics 365 Customer Engagement (on-premises) data. More information: Write Plug-Ins to Extend Business Processes.

You can also create custom processes based on the Windows Workflow Foundation programming model. You can create several different types of processes. Most of the time you’ll use the workflow designer. But when there is some capability you can’t achieve in the designer, you can define processes using code. More information: Write Workflows to Automate Business Processes

Extending in the application

Each of the client applications provided by Dynamics 365 Customer Engagement (on-premises) includes the ability to define customizations and deploy to multiple types of clients. The web application, Dynamics 365 for Outlook, Dynamics 365 for tablets, and Dynamics 365 for phones each provide capabilities to include custom navigation and command options as well as the Xrm object model and Xrm.Utility functions you can use with JavaScript to provide responsive experiences in the client. JavaScript libraries, HTML pages, images, and other types of files that can be used or displayed in the client are available as URL addressable web resources. More information: Use JavaScript with Customer Enagement apps and Web Resources for Dynamics 365 Customer Engagement (on-premises).

When you need to access Dynamics 365 Customer Engagement (on-premises) data that isn’t available in the context where your JavaScript code is running, you can make calls to the server to get the data you need. The organization service can be used, but it is much easier to use the Web API with JSON rather than the XML required by the organization service. Because your script runs in the context of the application, you are automatically authenticated. More information: Get started with the Dynamics 365 Customer Engagement Web API (client-side JavaScript)

See also

Can you tell us about your documentation language preferences? Take a short survey.

The survey will take about seven minutes. No personal data is collected (privacy statement).

Overview of Windows Programming in C++

There are several broad categories of Windows applications that you can create with C++. Each has its own programming model and set of Windows-specific libraries, but the C++ standard library and third-party C++ libraries can be used in any of them.

This section discusses how to use Visual Studio and the MFC/ATL wrapper libraries to create Windows programs. For documentation on the Windows platform itself, see Windows documentation.

Command line (console) applications

C++ console applications run from the command line in a console window and can display text output only. For more information, see Create a console calculator in C++.

Native desktop client applications

A native desktop client application is a C or C++ windowed application that uses the original native Windows C APIs or Component Object Model (COM) APIs to access the operating system. Those APIs are themselves written mostly in C. There’s more than one way to create a native desktop app: You can program using the Win32 APIs directly, using a C-style message loop that processes operating system events. Or, you can program using Microsoft Foundation Classes (MFC), a lightly object-oriented C++ library that wraps Win32. Neither approach is considered «modern» compared to the Universal Windows Platform (UWP), but both are still fully supported and have millions of lines of code running in the world today. A Win32 application that runs in a window requires the developer to work explicitly with Windows messages inside a Windows procedure function. Despite the name, a Win32 application can be compiled as a 32-bit (x86) or 64-bit (x64) binary. In the Visual Studio IDE, the terms x86 and Win32 are synonymous.

To get started with traditional Windows C++ programming, see Get Started with Win32 and C++. After you gain some understanding of Win32, it will be easier to learn about MFC Desktop Applications. For an example of a traditional C++ desktop application that uses sophisticated graphics, see Hilo: Developing C++ Applications for Windows.

C++ or .NET?

In general, .NET programming in C# is less complex, less error-prone, and has a more modern object-oriented API than Win32 or MFC. In most cases, its performance is more than adequate. .NET features the Windows Presentation Foundation (WPF) for rich graphics, and you can consume both Win32 and the modern Windows Runtime API. As a general rule, we recommend using C++ for desktop applications when you require:

• precise control over memory usage
• the utmost economy in power consumption
• usage of the GPU for general computing
• access to DirectX
• heavy usage of standard C++ libraries

It’s also possible to combine the power and efficiency of C++ with .NET programming. You can create a user interface in C# and use C++/CLI to enable the application to consume native C++ libraries. For more information, see .NET Programming with C++/CLI.

COM Components

The Component Object Model (COM) is a specification that enables programs written in different languages to communicate with one another. Many Windows components are implemented as COM objects and follow standard COM rules for object creation, interface discovery, and object destruction. Using COM objects from C++ desktop applications is relatively straightforward, but writing your own COM object is more advanced. The Active Template Library (ATL) provides macros and helper functions that simplify COM development. For more information, see ATL COM desktop components.

Universal Windows Platform apps

The Universal Windows Platform (UWP) is the modern Windows API. UWP apps run on any Windows 10 device, use XAML for the user-interface, and are fully touch-enabled. For more information about UWP, see What’s a Universal Windows Platform (UWP) app? and Guide to Windows Universal Apps.

The original C++ support for UWP consisted of (1) C++/CX, a dialect of C++ with syntax extensions, or (2) the Windows Runtime Library (WRL), which is based on standard C++ and COM. Both C++/CX and WRL are still supported. For new projects, we recommend C++/WinRT, which is entirely based on standard C++ and provides faster performance.

Desktop Bridge

In Windows 10, you can package your existing desktop application or COM object as a UWP app, and add UWP features such as touch, or call APIs from the modern Windows API set. You can also add a UWP app to a desktop solution in Visual Studio, and package them together in a single package and use Windows APIs to communicate between them.

Visual Studio 2017 version 15.4 and later lets you create a Windows Application Package Project to greatly simplify the work of packaging your existing desktop application. A few restrictions apply to the registry calls or APIs your desktop application can use. However, in many cases you can create alternate code paths to achieve similar functionality while running in an app package. For more information, see Desktop Bridge.

Games

DirectX games can run on the PC or Xbox. For more information, see DirectX Graphics and Gaming.

SQL Server database clients

To access SQL Server databases from native code, use ODBC or OLE DB. For more information, see SQL Server Native Client.

Windows device drivers

Drivers are low-level components that make data from hardware devices accessible to applications and other operating system components. For more information, see Windows Driver Kit (WDK).

Windows services

A Windows service is a program that can run in the background with little or no user interaction. These programs are called daemons on UNIX systems. For more information, see Services.

SDKs, libraries, and header files

Visual Studio includes the C Runtime Library (CRT), the C++ Standard Library, and other Microsoft-specific libraries. Most of the include folders that contain header files for these libraries are located in the Visual Studio installation directory under the \VC\ folder. The Windows and CRT header files are found in the Windows SDK installation folder.

The Vcpkg package manager lets you conveniently install hundreds of third-party open-source libraries for Windows.

The Microsoft libraries include:

Microsoft Foundation Classes (MFC): An object-oriented framework for creating traditional Windows programs—especially enterprise applications—that have rich user interfaces that feature buttons, list boxes, tree views, and other controls. For more information, see MFC Desktop Applications.

Active Template Library (ATL): A powerful helper library for creating COM components. For more information, see ATL COM Desktop Components.

C++ AMP (C++ Accelerated Massive Parallelism): A library that enables high-performance general computational work on the GPU. For more information, see C++ AMP (C++ Accelerated Massive Parallelism).

Concurrency Runtime: A library that simplifies the work of parallel and asynchronous programming for multicore and many-core devices. For more information, see Concurrency Runtime.

Many Windows programming scenarios also require the Windows SDK, which includes the header files that enable access to the Windows operating system components. By default, Visual Studio installs the Windows SDK as a component of the C++ Desktop workload, which enables development of Universal Windows apps. To develop UWP apps, you need the Windows 10 version of the Windows SDK. For information, see Windows 10 SDK. (For more information about the Windows SDKs for earlier versions of Windows, see the Windows SDK archive).

Program Files (x86)\Windows Kits is the default location for all versions of the Windows SDK that you’ve installed.

Other platforms such as Xbox and Azure have their own SDKs that you may have to install. For more information, see the DirectX Developer Center and the Azure Developer Center.

Development Tools

Visual Studio includes a powerful debugger for native code, static analysis tools, graphics debugging tools, a full-featured code editor, support for unit tests, and many other tools and utilities. For more information, see Get started developing with Visual Studio, and Overview of C++ development in Visual Studio.