Previous

Next

Request records with SOAP

Completed

The next example is using Basic Authentication, which isn't supported on Business Central SaaS starting from April 2022 with the 2022 Wave 1 Release. Basic Authentication is still supported with Business Central On-Premises.

Adding OAuth 2.0 support in the C# SOAP example is outside the scope of the integration with Business Central, as it would require advanced C# knowledge. SOAP within Business Central will be deprecated over time, but for now we leave this example for reference/information.

To request records from Business Central by using SOAP, you need to create a separate application in another programming language that supports SOAP. The following procedure shows how you can connect from a .NET application to the Business Central SOAP web services.

1. Open Visual Studio (not Visual Studio Code). If you don't have Visual Studio installed, you can download the Visual Studio Community Edition at https://visualstudio.microsoft.com/?azure-portal=true.

2. Select Create a new project in the Visual Studio dialog box.

   

3. Search for Console App, select Console App (.NET Framework) for C#, and then select Next.

   

4. Give your application a name and specify a location where you want to store the Console App. Select Create to finish the project creation.

When requesting records, make sure that you always provide the company before you request a specific service. Accordingly, you should first define the default company in the URI. Because the primary key of the Company table is Name, you need to provide the name to select a specific company.

https://api.businesscentral.dynamics.com/v2.0/<tenant>/Sandbox/WS/<companyname>/<objecttype>/<service>

The following example shows all customer records being requested.

Base URL: https://api.businesscentral.dynamics.com/v2.0/<tenant>/Sandbox/WS/CRONUS USA%2C Inc./Page/Customers

To request the records, you need to add this link in your Visual Studio project as a Service Reference. In Visual Studio, right-click your application in Solution Explorer, select Add, and then select Service Reference...

Paste the SOAP service URL into the Address field and then select Go. You'll get a message indicating that your credentials will be sent in clear text. Select Yes to continue. You'll be requested to enter your username and password. The password is the web service access key.

Customers_Service will be listed in the Services list. You can select Customers_Port and specify a Namespace at the bottom of the screen. Notice that the Customers_Port service has already created many available methods to create, delete, read, and update customer records.

Select the OK button to finish the service reference creation. This action automatically generates C# classes based on the entities in the WSDL document of the SOAP service.

In the following example, all customers with location code Blue are retrieved by using SOAP and are then displayed in the Console output window. The Customers_PortClient class gives access to many functions that you can use. This example uses the ReadMultiple function to retrieve multiple records based on several filters. The ReadMultiple function returns an array that can be looped through.

using System;
using ConsoleApp2.BCCustomer;

namespace ConsoleApp2
{
    class Program
    {
        static void Main(string[] args)
        {
            Customers_PortClient portClient = new Customers_PortClient();

            portClient.ClientCredentials.UserName.UserName = "mywebserviceuser";
            portClient.ClientCredentials.UserName.Password = "rk3CwanGRBEM3ioideNC...";

            Customers_Filter[] filters = new Customers_Filter[1];

            Customers_Filter blueFilter = new Customers_Filter();
            blueFilter.Field = Customers_Fields.Location_Code;
            blueFilter.Criteria = "BLUE";

            filters[0] = blueFilter;

            Customers[] customers = portClient.ReadMultiple(filters, null, 0);

            foreach (var customer in customers)
            {
                Console.WriteLine(customer.Name);
            }

            Console.ReadKey();
        }
    }
}

To update or create new records by using SOAP, you can use the Create or Update methods that are available in the PortClient.

Continue