This is not my first article about Sage CRM's .NET API and those of you who are members of the Developer Program will know that you have access to a series of articles that discuss the API in the gated area of the community. In addition there a short series of training videos that explain the API and how to start your projects using the Software Development Kit (SDK).
But nevertheless it is a while since I have written about the API in the public areas of the community and I thought it would be worthwhile to remind ourselves about the API and the options that it provides to those carrying out customizations.
In this article I want to consider the .NET API and how the SDK resources can be used to extend Sage CRM. I hope that this will be a straight forward and simple introduction that illustrates the nature of the API.
I need to explain what the Sage CRM .NET API is and what it is not. If you are used to hearing colleagues or other partners and Sage staff talking about classic ASP pages you might be tempted to jump to the conclusion that the Sage CRM .NET API was something to do with ASP.NET.
You would be wrong!
The Microsoft .NET Framework is an environment for building, deploying, and running Web Services and other applications. It consists of three main parts: the Common Language Runtime, the Framework classes, and ASP.NET.
.NET Framework provides a large body of pre-coded solutions to common program requirements, and manages the execution of programs written specifically for the framework.
Let's look at ASP.NET first.
The point about ASP.NET is that is assumes that it is in control of the HTTP request, the generation of the HTML to be returned to the browser and the response that sends that HTML back to the browser.
Sage CRM .NET API
The Sage CRM .NET API conforms to the .NET Framework. It provides a type library that exposes the Sage CRM objects, properties, and methods. Through its core libraries the Sage CRM .NET Component manages both data access and web interface generation. Projects developed using the Sage CRM .NET Component will be compiled into a dll and called directly from within Sage CRM. By using Sage CRM meta data Application Extensions constructed using the Sage CRM .NET API will look, feel and perform exactly like core system pages.
The above image shows that part of the architecture of Sage CRM which governs the .NET API and the extensions that are created. To understand more fully about the technical design of Sage CRM then you may want to read the article "System Architecture".
The point I want to make about the .NET dlls that are created using the Sage CRM .NET API is that these dlls are accessed by calls that pass through the main eWare.dll (the main program that is run in Sage CRM).
This point is illustrated very clearly if we look at the way in which the Relationship tab is invoked under the company context.
The Relationship feature in Sage CRM is written using the .NET API.
The URL that calls this page looks like
- http://localhost/crm/eware.dll/Do?SID=130486632349475 &Act=432 &Mode=1 &CLk=T &Key0=1 &Key1=28 &Key2=30 &dotnetdll=RelatedEntities &dotnetfunc=RunREList &J=Relationships &T=Company
- http://[servername]/[installname]/eware.dll/Do?SID=130486632349475 &Act=432 &Mode=1 &CLk=T &Key0=1 &Key1=28 &Key2=30 &dotnetdll=RelatedEntities &dotnetfunc=RunREList &J=Relationships &T=Company
You may not understand everything in that URL but you should be able to see that the URL is directed at the eWare.dll
with additional parameters contained in the QueryString that causes CRM to pass the request to the .NET dll.
Hopefully you can start to see why Sage CRM .NET API and ASP.NET pages must not be confused. Reference to the Sage CRM .NET classes from within ASP.NET projects is not supported. The two are incompatible.
This then leaves some other important questions.
- Who can use the .NET API?
- How can you start a .NET project?
- Why would you use the .NET API?
Who can use the .NET API?
As you saw from the screen shot above of the Relationships tab this shows that everyone can use the .NET API. It is a default part of the Sage CRM system. What I mean by that is that everyone can use the dlls that are the product of the API. This means that developers working with the API do not have to worry about the delivery of a runtime license or environment as that is included in the out of the box install of Sage CRM.
What is needed however is a license that includes the DPP or Developer rights. Currently only members of the Developer Program have access to a license that will allow the SDK to be installed.
How can you start a .NET project?
Any programming language that conforms with the .NET Framework can be used for the development of Sage CRM Application Extensions (e.g. J#, C# VB.NET etc)
Although you can write your code in any .NET language in practice C# is likely to be the language that is used. This is mainly because Software Development Kit only provides examples in C# and all the example code in the documentation and community is in C#.
The SDK provides a developer with templates and code snippets that speed up the creation of code.
Among the resources provided by the SDK are example projects.
- RelatedEntities source code - A version of the code behind the Relationship tab
- CompanySummary - A partial rebuild of the company summary screen.
- CompoundEntryScreen - An example of a compound screen.
- QuickLook - A partial rebuild of the Company Quicklook page.
Below is a screenshot of rebuild of an Opportunity List in the context of a Company.
The code for this page looks like this
public class OpportunityList : ListPage
/* Constructor needs EntityName, ListName, IdField, FilterByField, FilterContext and ScreenName
: base("Opportunity", "OpportunityList", "OpportunityFilterBox")
FilterByField = "oppo_primarycompanyid";
FilterByContextId = (int)Sage.KeyList.CompanyId;
The .NET API uses the concept of Meta Data in a broadly similar way to that used by Sage CRM's classic ASP API.
In the code above you can see that the constructor has referenced the name of the entity, the list to be used and name of the screen to be used as the filterbox.
The diagram below shows that the properties for any screen and screen element (List, Column, Screen, Entry Field) are determined by definitions held in the Meta Data tables (prefixed "custom_").
The .NET API classes obtain the definition of the screens from Meta Data and generate the HTML necessary for the output to the browser.
I've already made reference to Sage CRM's system architecture. The .NET API interacts with the eWare.dll. This is COM 32bit architecture and so the requests written in .NET are actually passed to the eWare.dll through a COM interop layer.
If you are the developer then you would write your code in C#. Your code is in a project that references the classes and objects contained in the Sage CRM .NET API which in turn communicate with the eWare.dll through COM InterOp. The code that you write is complied into a dll and added into the Sage CRM system where it can be called from the menus in a similar to ASP pages.
Why would you use the .NET API?
Creating .dlls that extend Sage CRM becomes an option for members of the Developer Program as those are the people who can install the SDK.
It has never been seen as a replacement for ASP COM API rather it has been seen as a way of meeting developers needs.
It allows developers to use the features of a sophisticated integrated development environment (IDE). It actually exposes deeper and richer functionality than the COM API but because it is similar and uses meta data to underlie its code the extensions that are created look, feel and perform exactly like core system pages.
But many developers like the .NET API because it provides the code that they create as a compiled end product that is not human non-readable. This means that there is some protection for Intellectual Property and ensures that nobody can 'just tweak a line' of code. Because a compiled assembly has to be added to the system it implies a more disciplined development cycle which is much better for system support and maintenance.
And those assemblies, the dll files, that need to be added to Sage CRM can just be copied into position. It provides 'Drop in Deployment' and there is no need to stop and start the server.