Choose your development style for managed code

Article
07/22/2016

Applies To: Dynamics CRM 2015

The Microsoft Dynamics CRM SDK offers a variety of methods and technologies to use when you write code to access the Microsoft Dynamics CRM 2015 and Microsoft Dynamics CRM Online 2015 Update web services or to extend the application. This guide highlights some tools and methods that you can use to accomplish different coding tasks, and offers some guidance on when to use them.

In This Topic

Authenticate using code

Create and deploy plug-ins or custom workflow activities

Create and deploy XAML workflows

Entity programming (early bound vs. late bound vs. developer extensions)

Query (Fetch vs. QueryExpressions vs. LINQ vs. Developer Extensions)

Authenticate using code

The following table lists the choices you have for writing code that authenticates the caller with an installation of Microsoft Dynamics CRM for on-premises, Internet-facing deployment (IFD), or online deployments.

Classes	Description and usage	More information
Helper code	The classes in the sample code demonstrate how to connect to the web services and authenticate the user. You can use the helper code as a basis of your own custom authentication code. This code is easy to use and supports all Microsoft Dynamics CRM deployment types. It also supports storing users’ passwords in the Windows Credential Manager for later reuse. Full source code is provided so you can copy and customize it for your needs. This is a recommended practice to isolate your programs from changes to this helper code in future releases.	Sample: Quick start for Microsoft Dynamics CRM Use the sample and helper code Helper code: ServerConnection class This code can be found in the SampleCode\CS\HelperCode\CrmServiceHelpers.cs and SampleCode\VB\HelperCode\CrmServiceHelpers.vb files in the SDK. Download the Microsoft Dynamics CRM SDK package.
Developer Extensions	These assemblies are provided to simplify and accelerate the development of applications that interact with Microsoft Dynamics CRM. The extensions extend the functionality of the core Microsoft Dynamics CRM SDK specifically around the use of the OrganizationServiceContext class. For an easy method that does the hard work for you in a few lines of code, use the CrmConnection class. This code is easy to use and supports all Microsoft Dynamics CRM deployment types.	Developer extensions for Microsoft Dynamics CRM Simplified connection to Microsoft Dynamics CRM
Xrm client	For advanced developers who need to customize the Windows Communication Foundation (WCF) service channel management and the authentication process, use the IServiceManagement<TService> and OrganizationServiceProxy classes in the Microsoft.Xrm.Sdk.Client namespace. Using these classes directly can provide better connection and authentication performance, and more flexibility. However, they require more advanced knowledge of the WCF service channel and server authentication. In addition, you must write more code to handle all Microsoft Dynamics CRM deployment types.	Active Directory and claims-based authentication Sample: Authenticate users with Microsoft Dynamics CRM web services Improve service channel allocation performance
XRM tooling	These assemblies leverage the CRM APIs to provide easy authentication support with fewer lines of code and through Windows PowerShell cmdlets. All the function calls in these classes provide thread-safety for actions performed in CRM in a multithreaded environment. It provides a common sign-in control with integrated authentication logic and an ability to securely store and reuse the authentication information to provide a consistent and seamless sign-in experience to CRM from your Windows client applications. These classes also provide built-in diagnostic tracing to aid troubleshooting and performance reporting of the action calls from your Windows client applications. These classes support all Microsoft Dynamics CRM deployment types and authentication types, except OAuth.	Build Windows client applications using the XRM tools Use XRM tooling to connect to CRM Use PowerShell cmdlets for XRM tooling to connect to CRM Sample: Quick start for XRM Tooling API

Helper code

The classes in the sample code demonstrate how to connect to the web services and authenticate the user. You can use the helper code as a basis of your own custom authentication code.

This code is easy to use and supports all Microsoft Dynamics CRM deployment types. It also supports storing users’ passwords in the Windows Credential Manager for later reuse.

Full source code is provided so you can copy and customize it for your needs. This is a recommended practice to isolate your programs from changes to this helper code in future releases.

Sample: Quick start for Microsoft Dynamics CRM

Use the sample and helper code

Helper code: ServerConnection class

This code can be found in the SampleCode\CS\HelperCode\CrmServiceHelpers.cs and SampleCode\VB\HelperCode\CrmServiceHelpers.vb files in the SDK. Download the Microsoft Dynamics CRM SDK package.

Developer Extensions

These assemblies are provided to simplify and accelerate the development of applications that interact with Microsoft Dynamics CRM. The extensions extend the functionality of the core Microsoft Dynamics CRM SDK specifically around the use of the OrganizationServiceContext class.

For an easy method that does the hard work for you in a few lines of code, use the CrmConnection class.

This code is easy to use and supports all Microsoft Dynamics CRM deployment types.

Developer extensions for Microsoft Dynamics CRM

Simplified connection to Microsoft Dynamics CRM

Xrm client

For advanced developers who need to customize the Windows Communication Foundation (WCF) service channel management and the authentication process, use the IServiceManagement<TService> and OrganizationServiceProxy classes in the Microsoft.Xrm.Sdk.Client namespace.

Using these classes directly can provide better connection and authentication performance, and more flexibility. However, they require more advanced knowledge of the WCF service channel and server authentication. In addition, you must write more code to handle all Microsoft Dynamics CRM deployment types.

Active Directory and claims-based authentication

Sample: Authenticate users with Microsoft Dynamics CRM web services

Improve service channel allocation performance

XRM tooling

These assemblies leverage the CRM APIs to provide easy authentication support with fewer lines of code and through Windows PowerShell cmdlets. All the function calls in these classes provide thread-safety for actions performed in CRM in a multithreaded environment. It provides a common sign-in control with integrated authentication logic and an ability to securely store and reuse the authentication information to provide a consistent and seamless sign-in experience to CRM from your Windows client applications.

These classes also provide built-in diagnostic tracing to aid troubleshooting and performance reporting of the action calls from your Windows client applications.

These classes support all Microsoft Dynamics CRM deployment types and authentication types, except OAuth.

Build Windows client applications using the XRM tools

Use XRM tooling to connect to CRM

Use PowerShell cmdlets for XRM tooling to connect to CRM

Sample: Quick start for XRM Tooling API

Create and deploy plug-ins or custom workflow activities

The following table lists the choices you have for writing and deploying plug-ins and custom workflow activities.

Tool	Description and usage	More information
Plug-in and Custom Workflow Activity classes Plug-in Registration Tool	The plug-in and custom workflow activity classes allow you to create event handlers to perform custom business logic that you can integrate with Microsoft Dynamics CRM to modify or augment the standard behavior of the platform. By using these classes directly, your code will not contain any helper code provided in the Developer Toolkit. If you write plug-ins and custom workflow activities from scratch, you must use the Plug-in Registration Tool to register them. This tool provides a graphical user interface and supports registering plug-ins and custom workflow activities with Microsoft Dynamics CRM. Use this method if you: Understand how to use the plug-in and custom activity classes. Don't want extra library code auto-generated and placed in your code files. Don't mind using an external tool and the web application to register and package custom code assemblies.	Plug-in development Custom workflow activities (workflow assemblies) Register and Deploy Plug-Ins Walkthrough: Register a plug-in using the plug-in registration tool

Plug-in and Custom Workflow Activity classes

Plug-in Registration Tool

The plug-in and custom workflow activity classes allow you to create event handlers to perform custom business logic that you can integrate with Microsoft Dynamics CRM to modify or augment the standard behavior of the platform.

By using these classes directly, your code will not contain any helper code provided in the Developer Toolkit.

If you write plug-ins and custom workflow activities from scratch, you must use the Plug-in Registration Tool to register them. This tool provides a graphical user interface and supports registering plug-ins and custom workflow activities with Microsoft Dynamics CRM.

Use this method if you:

Understand how to use the plug-in and custom activity classes.

Don't want extra library code auto-generated and placed in your code files.

Don't mind using an external tool and the web application to register and package custom code assemblies.

Plug-in development

Custom workflow activities (workflow assemblies)

Walkthrough: Register a plug-in using the plug-in registration tool

Create and deploy XAML workflows

The following table lists the choices you have for writing and deploying XAML workflows.

Tool	Description and usage	More information
Microsoft Visual Studio Workflow Designer	Microsoft Dynamics CRM on-premises and IFD supports the ability to create custom XAML workflows. Using the Microsoft Visual Studio Workflow Designer, you can create custom XAML workflows, also called declarative workflows, by dragging workflow activities from the toolbox onto the design surface, creating variables, and setting properties of these activities to implement the workflow’s functionality. You can use built-in Windows Workflow Foundation activities or the process activities that are specific to Microsoft Dynamics CRM. Use this method when you just want to write custom XAML workflows.	Custom XAML workflows Write workflows to automate business processes

Microsoft Visual Studio Workflow Designer

Microsoft Dynamics CRM on-premises and IFD supports the ability to create custom XAML workflows. Using the Microsoft Visual Studio Workflow Designer, you can create custom XAML workflows, also called declarative workflows, by dragging workflow activities from the toolbox onto the design surface, creating variables, and setting properties of these activities to implement the workflow’s functionality. You can use built-in Windows Workflow Foundation activities or the process activities that are specific to Microsoft Dynamics CRM.

Use this method when you just want to write custom XAML workflows.

Custom XAML workflows

Write workflows to automate business processes

Entity programming (early bound vs. late bound vs. developer extensions)

The following table lists the choices you have for writing code that uses entities in Microsoft Dynamics CRM.

Class	Description and usage	More information
Early Bound <optional namespace>.Account, <optional namespace>.Contact, and so on	The code generation tool (CrmSvcUtil) creates early-bound entity classes, derived from the Entity class, that you can use to access business data in Microsoft Dynamics CRM. These classes include one class for each entity in your installation, including custom entities. Use this method when you want to have the compiler check type references at compile time. Also, attributes and relationships are included in the generated class, so they have IntelliSense support for entity, attribute, and relationship names. Using strong types is generally the preferred method and is used in the majority of samples in this SDK documentation. There are some downsides to this approach: Classes must be regenerated each time entities are customized to take advantage of schema changes. Serialization costs increase as the entities are converted to late bound types during transmission over the network.	Use the early bound entity classes in code Create early bound entity classes with the code generation tool (CrmSvcUtil.exe)
Late Bound Microsoft.Xrm.Entity	The Entity class contains the logical name of an entity and a property-bag array of the entity’s attributes. This lets you use late binding so that you can work with types such as custom entities and custom attributes that were not present when your application was compiled. Another benefit of this is that less serialization occurs as entity data is transmitted over a network, which means higher performance. There are some downsides to this approach: Types must be explicitly specified to prevent implicit casts. It is harder to isolate the impact of changes to the schema because the names for resources, such as entities and attributes, are hardcoded. Spelling mistakes while coding are easier to make because the attribute names are hardcoded strings.	Use the late bound entity class in code
Developer Extensions Microsoft.Xrm.Client.CrmEntity	The CrmEntity class derives from the Entity class. In addition to providing all the same functionality of the Entity class, CrmEntity adds new get and set extension methods to simplify common coding tasks, and two new property change events.	Developer extensions for Microsoft Dynamics CRM
Early Bound using Code Generation Tool Extensions <optional namespace>.Account, <optional namespace>.Account, and so on	By using the Developer Extensions version of the CrmSvcUtil tool, you can generate early-bound types that are derived from the CrmEntity class. Use this when you want to take advantage of other features available in the Developer Extensions.	Generate code with the code generation tool extensions Attach entities to the context Developer extensions for Microsoft Dynamics CRM

Early Bound

<optional namespace>.Account, <optional namespace>.Contact, and so on

The code generation tool (CrmSvcUtil) creates early-bound entity classes, derived from the Entity class, that you can use to access business data in Microsoft Dynamics CRM. These classes include one class for each entity in your installation, including custom entities.

Use this method when you want to have the compiler check type references at compile time. Also, attributes and relationships are included in the generated class, so they have IntelliSense support for entity, attribute, and relationship names. Using strong types is generally the preferred method and is used in the majority of samples in this SDK documentation.

There are some downsides to this approach:

Classes must be regenerated each time entities are customized to take advantage of schema changes.

Serialization costs increase as the entities are converted to late bound types during transmission over the network.

Use the early bound entity classes in code

Create early bound entity classes with the code generation tool (CrmSvcUtil.exe)

Late Bound

Microsoft.Xrm.Entity

The Entity class contains the logical name of an entity and a property-bag array of the entity’s attributes. This lets you use late binding so that you can work with types such as custom entities and custom attributes that were not present when your application was compiled.

Another benefit of this is that less serialization occurs as entity data is transmitted over a network, which means higher performance.

There are some downsides to this approach:

Types must be explicitly specified to prevent implicit casts.

It is harder to isolate the impact of changes to the schema because the names for resources, such as entities and attributes, are hardcoded.

Spelling mistakes while coding are easier to make because the attribute names are hardcoded strings.

Use the late bound entity class in code

Developer Extensions

Microsoft.Xrm.Client.CrmEntity

The CrmEntity class derives from the Entity class. In addition to providing all the same functionality of the Entity class, CrmEntity adds new get and set extension methods to simplify common coding tasks, and two new property change events.

Developer extensions for Microsoft Dynamics CRM

Early Bound using Code Generation Tool Extensions

<optional namespace>.Account, <optional namespace>.Account, and so on

By using the Developer Extensions version of the CrmSvcUtil tool, you can generate early-bound types that are derived from the CrmEntity class. Use this when you want to take advantage of other features available in the Developer Extensions.

Generate code with the code generation tool extensions

Attach entities to the context

Developer extensions for Microsoft Dynamics CRM

Query (Fetch vs. QueryExpressions vs. LINQ vs. Developer Extensions)

The following table lists the choices you have for creating queries you can use to retrieve records from the Microsoft Dynamics CRM database.

Query style	Description and usage	More information
FetchXML	This is a custom XML-based query language that supports all the features of QueryExpression plus aggregates and grouping. Fetch queries can return records for multiple entities. In addition, queries can be serialized and saved in the database. This is used to save a query as a user-owned saved view in the UserQuery entity and as an organization-owned saved view in the SavedQuery entity. Use this query language when you need support for aggregates and grouping or you need to save the query.	Build queries with FetchXML
QueryExpression	A query expression is used to search for records for a single entity type. Queries are built as an object model. This class supports all the features in FetchXML except for aggregates and grouping. It also supports both early and late bound entity programming styles.	Build queries with QueryExpression
LINQ	Queries are built using standard language, but internally .NET Language-Integrated Query (LINQ) uses QueryExpression, so it is limited to the features of QueryExpression. LINQ supports both early and late bound entity programming styles.	Build queries with LINQ (.NET language-integrated query)

FetchXML

This is a custom XML-based query language that supports all the features of QueryExpression plus aggregates and grouping. Fetch queries can return records for multiple entities. In addition, queries can be serialized and saved in the database. This is used to save a query as a user-owned saved view in the UserQuery entity and as an organization-owned saved view in the SavedQuery entity.

Use this query language when you need support for aggregates and grouping or you need to save the query.

Build queries with FetchXML

QueryExpression

A query expression is used to search for records for a single entity type. Queries are built as an object model. This class supports all the features in FetchXML except for aggregates and grouping. It also supports both early and late bound entity programming styles.

Build queries with QueryExpression

LINQ

Queries are built using standard language, but internally .NET Language-Integrated Query (LINQ) uses QueryExpression, so it is limited to the features of QueryExpression. LINQ supports both early and late bound entity programming styles.

Build queries with LINQ (.NET language-integrated query)

Share via

Choose your development style for managed code

In This Topic

Authenticate using code

Create and deploy plug-ins or custom workflow activities

Create and deploy XAML workflows

Entity programming (early bound vs. late bound vs. developer extensions)

Query (Fetch vs. QueryExpressions vs. LINQ vs. Developer Extensions)

See Also

Additional resources