Using SOAP Web Services in Visual Studio. Add Service Reference vs Add Web Reference

Hints, Tips and Tricks

Technical Hints Tips and Tricks that cover customization and development using Sage CRM. API usage and coding are covered.

Using SOAP Web Services in Visual Studio. Add Service Reference vs Add Web Reference

  • Comments 2
  • Likes

Within a Visual Studio Project there are two ways of referencing Web Services. These are either as a Service Reference or a Web Reference.

  • Add Web Reference is the old-style, and is more commonly used within Sage CRM projects. This is the type of reference that is used with older ASP.NET (ASMX) examples that used only XmlSerializer. A Web Reference will create a client proxy class that allows your code to talk to the Sage CRM Web Service that is described via WSDL. The communication is via SOAP and using a Web References will allow Sage CRM to talk to anything so long as they all talk WSDL and conform to the WS-I interoperability standard.
  • Add Service Reference is the "newer" way of doing it. "Newer" is a relative term. Visual Studio added support for Service References along with with .NET 3.5 in Visual Studio 2008. Add Service allows you to add a Windows Communication Foundation (WCF) service reference to your project. The WCF approach allows for a much more advanced, much more flexible service model than the earlier Web Reference. The down side is that you end up having to write more code when using a Service Reference against Sage CRM.

The examples provided in the Sage CRM documentation, SDK snippets and community resources assume you are working with a Web Reference for your project.

The example below shows the code of a project that has used a service reference.

The project when run will create a logon button. The logon button when pressed will then logon to Sage CRM, retrieve the version of Sage CRM and then will log out.

Example Code

//Create the Web Service & Logon
WebServiceSoapPort CRMService = new WebServiceSoapPortClient();

logonRequest myLogonRequest = new logonRequest("Admin", "");
logonResponse myLogonResponse = CRMService.logon(myLogonRequest);

SessionHeader crmSessionHeader = new SessionHeader();
crmSessionHeader.sessionId = myLogonResponse.result.sessionid;

//Send a request
getversionstringRequest myVersionRequest = new getversionstringRequest();
myVersionRequest.SessionHeader = crmSessionHeader;
myVersionRequest.getversionstring = new object();
getversionstringResponse1 myVersionResponse = CRMService.getversionstring(myVersionRequest);

//Use the returned result
buttonLogon.Text = myVersionResponse.getversionstringresponse.result.versionstring;

logoffRequest myLogoffRequest = new logoffRequest(crmSessionHeader, crmSessionHeader.sessionId);
logoffResponse myLogoffResponse = CRMService.logoff(myLogoffRequest);

MessageBox.Show("User logged off");

  • One benefit of using the Service Reference is that it opens up the use of async...await.  This just makes any async stuff less clunky.  For example, in WSDL world, you have to do stuff like this:

          private void WSDLLogonAsync()


               WebService ws = new WebService();

               ws.logonCompleted += Ws_logonCompleted;

               ws.logonAsync("Admin", "");


           private void Ws_logonCompleted(object sender, logonCompletedEventArgs e)


               ((WebService)sender).SessionHeaderValue = new SessionHeader() { sessionId = e.Result.sessionid };


    (yes, in reality you'd probably use an anonymous delegate for logonCompleted, but my point still stands).

    In WCF world we can do this:

           private async void WCFLogonAsync()


               WCF.WebServiceSoapPortClient client = new WCF.WebServiceSoapPortClient();

               var logonTask = await client.logonAsync("Admin", "");

               WCF.SessionHeader header = new WCF.SessionHeader();

               header.sessionId = logonTask.result.sessionid;


  • Thanks for sharing Chris.