Using the .NET API

7 minute read time.

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.

ASP.NET uses the .NET Framework as an infrastructure and offers the ability to build pages composed of controls similar to a Windows user interface. The web controls produce segments of HTML and JavaScript which form part of the resulting page sent to the end-user's browser.

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.


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.

&dotnetdll=RelatedEntities &dotnetfunc=RunREList

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

[code language="csharp"]
public class OpportunityList : ListPage
/* Constructor needs EntityName, ListName, IdField, FilterByField, FilterContext and ScreenName
public OpportunityList()
: 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.

  • You can position additional buttons relative to the buttons automatically created by the specialised class by where you call the button

    public override void BuildContents()


    AddUrlButton("test1", "new.gif", UrlDotNet(ThisDotNetDll, "RunFindOppo")); //Added ahead of the Find & Clear buttons


    AddUrlButton("test2", "new.gif", UrlDotNet(ThisDotNetDll, "RunFindOppo")); //Added after the Find & Clear buttons

    AddButtonContent("text - under buttons"); //This is always added after the buttons


  • Hi Jeff,

    I have created a URL button on a search page within the build contents(). Currently it appears above the "Find" and "Clear" buttons associated to the search screen. My question is, is there a way of moving the custom button to be below these buttons? Any help would be much appreciated!

    Thank you

  • Michele

    Within the specialised ListPage class you can add

    public override void AddNewButton()




    This allows you to basically change (or remove - as I have done by commenting out) the behaviour to whatever you need it to be.

  • Jeff..

    Where would I be able to find what I need to insert in my code to get rid of the New button in the example list page you show above (the opportunity list). I have a list page that I do not want users to add to. I think I need something like this....

    this.? = false;

    However, I don't know how to identify that button and I don't know where to look to find it. Any assistance you could provide would be greatly appreciated.