How To Add Service Reference In Visual Studio 2017

This page illustrates how a client application (too known as a web-service consumer) can reference and call the Service Border spider web services.

A web-service awarding tin run on any figurer that has HTTP access to the Service Border server.

The example is a C# application, developed in Microsoft Visual Studio and running on the Microsoft Windows operating system.

You can use an coordinating approach to develop applications in other web-enabled languages, in other development environments, and on other operating systems. For detailed information, see the language and development-environs documentation.

Tutorial: Calling a Web Service in C#

As an instance of how to call a web functioning, we nowadays a C# projection that calls the ClickSchedule web service, ScheduleService.svc. The code creates a chore object. It and then calls the CreateTask web performance, adding the task to the Service Edge database.

The application will work in the following fashion:

On a form, the user enters the CallID and Customer backdrop of a new chore.
When the user clicks the Create Chore button, the application sets default values of the job Number, Duration, and DueDate properties.
The application calls the CreateTask web operation.
The web operation returns the new task object.
The application displays the Central holding of the task, generated past the Service Edge server.

For simplicity, nosotros omit other task properties, input validation, and error handling. These features would be required in a production awarding.

Obtaining the WSDL Schema of Your Tenant

You must obtain a WSDL schema that defines the available web services. The WSDL schema contains references to the collections and properties that are available in your tenant, including the user-defined collection and properties. Therefore, y'all must obtain a WSDL schema that is specific for your tenant.

» To obtain the WSDL schema:

In the Schema Editor, configure any user-defined collections (UDCs) or user-defined backdrop (UDPs) that you need.
Create and download a backup file of the tenant.
Open a support call with ClickSoftware Worldwide Back up, and request a WSDL schema. Include the following items in the support call:
- A copy of the fill-in file
- The encryption key of the backup file
- The names of the spider web services that you plan to access, such as ScheduleService.svc. orServiceOptimizationService.svc.To make up one's mind which web services you lot demand, see the Spider web Service API Reference.
ClickSoftware Worldwide Back up will generate a WSDL schema and send information technology to you. There is an contained schema for each spider web service, containing a *.wsdl file and possibly other files.
If you later revise the UDCs or UDPs, repeat these steps and obtain a new WSDL schema. Note: Some of the fields that are marked as mandatory might be optional.
For example: <xs:element minOccurs="1" maxOccurs="one" name="ParallelFactor" blazon="xs:int"/>
Shop the WSDL schema files in any convenient location on your figurer.
In the post-obit sections, we presume that you have obtained a WSDL schema for ScheduleService.svc.

Creating a Projection that References the Web Service

» To set a C# project that references ScheduleService.svc:

From the Start menu, open up Microsoft Visual Studio.
Click File > New > Project.
In the Project Blazon pane, select a Visual C# application. In the Templates pane, select a Windows Forms Awarding.
Enter a project name such as CallingServiceExample, and browse to a storage location.
In the Solution Explorer, right-click the project name and click Add Service Reference.
At the prompt, enter the post-obit information:
- Accost
  The full path of the *.wsdl file.
- Namespace
  A namespace identifier for the service, such as CSSvc.
Click OK.
The Solution Explorer displays the service reference.
Salvage the project.

Getting Information most the Web Operations

To view the spider web operations in C# syntax with the Visual Studio Object Browser:

On the menu, click View > Object Browser.
In the left pane, scan to the following object:
CallingServiceExample\CallingServiceExample.CSSvc\ScheduleServiceClient
In the right pane, select and view the desired web performance. In this example, select CreateTask.

At the bottom correct of the Object Browser, you can view the complete syntax of the web functioning:

public void CreateTask(   CallingServiceExample.CSSvc.OptionalParameters      OptionalParameters,   ref CallingServiceExample.CSSvc.Task Chore,   string[] RequestedProperties )

Calling the Web Operation

You are now ready to code the awarding.

» To lawmaking the application:

In the Solution Explorer, double-click the form module (past default, Form1.cs) to display the grade.
Using the Visual Studio toolbox, add the illustrated controls to the form.
Select each command and use the Properties windows to assign its Name property.
Name the text boxes txtCallID, txtCustomer, and txtKey, respectively.
Name the command button cmdCreateTask.
Double-click the Create Task button. This displays the code of the cmdCreateTask_Click event.

Within the event, insert the following lawmaking. In the constructor call, you lot must replace int-host-proper name-of-POD with the integration host name of the POD where your tenant is located. In the credentials, enter the integration user name and password of your tenant.

private void cmdCreateTask_Click(object sender, EventArgs e) {   //Telephone call the constructor and create a spider web service client   CallingServiceExample.CSSvc.ScheduleServiceClient objClient =     new CallingServiceExample.CSSvc.ScheduleServiceClient(       "BasicHttpBinding_ScheduleService", "https://int-host-proper noun-of-POD/So/Services/ScheduleService.svc");    //Gear up the credentials to access the web service   objClient.ClientCredentials.UserName.UserName = "YourIntegrationUserName";   objClient.ClientCredentials.UserName.Password = "YourIntegrationPassword";    //Create a task object   CallingServiceExample.CSSvc.Chore objTask = new      CallingServiceExample.CSSvc.Chore();    //Set the task properties to the values that the user entered   objTask.CallID = txtCallID.Text;   objTask.Customer = txtCustomer.Text;    //Assign default holding values   objTask.Number = i;   objTask.NumberSpecified = true;    objTask.Duration = 1800;   objTask.DurationSpecified = true;    objTask.DueDate = System.DateTime.Now;   objTask.DueDateSpecified = true;    //Call the CreateTask web operation, which adds the task to    //the Service Edge database   objClient.CreateTask(zippo, ref objTask, naught);    //Brandish the key of the new task   txtKey.Text = Catechumen.ToString(objTask.Key); }

Running the Application

» To run and test the application:

On the menu, click Build > Build Solution, and confirm that it compiles without mistake.
Click Debug > Starting time Debugging.
Enter a CallID and a Customer proper name. You can enter any strings.
Click the Create Job button.
Later on a moment, the application displays the task key.

Boosted Steps

Attempt modifying the code by assigning additional task properties such every bit Region and District.

Programming Guidelines for Visual Studio

Here are some Microsoft Visual Studio programming guidelines that are illustrated in the Tutorial: Calling a Web Service in C#. Analogous guidelines employ in any .Internet linguistic communication.

Creating a Spider web Service Client

To call the web operation, you must create a web-service client object. In C#, y'all tin utilise code such as the following:

CallingServiceExample.CSSvc.ScheduleServiceClient objClient =   new CallingServiceExample.CSSvc.ScheduleServiceClient(     "BasicHttpBinding_ScheduleService", "https://int-host-name-of-POD/SO/Services/ScheduleService.svc");  objClient.ClientCredentials.UserName.UserName = "YourIntegrationUserName"; objClient.ClientCredentials.UserName.Password = "YourIntegrationPassword";

The parameter "BasicHttpBinding_ScheduleService" means that the client accesses the HTTP endpoint of the spider web service. The web services take several other endpoints that are for internal utilise simply. In user applications, you should always access the HTTP endpoint.

For other services, the parameter value follows the same pattern:

"BasicHttpBinding_ServiceName"

To verify the parameter value, view the app.config file of the Visual Studio project.

The parameter "https://int-host-proper noun-of-POD/So/Services/ScheduleService.svc" is the URL of the spider web service. You must substitute the correct int-host-name-of-POD and spider web-service path.

For the user name and password, enter the credentials of the integration user of your tenant.

Objects and References to Objects

An object is a Service Edge business object including all its backdrop. A reference to an object is a pointer to a business organization object that exists in the Service Edge database.

Object Data Types

In the web-service API, object data types take names such as Task or Engineer.

The CreateTask spider web operation provides an instance. The syntax is:

public void CreateTask(...,   ref CallingServiceExample.CSSvc.Task Chore, ...)

The second parameter is a Task object that the operation adds to the database.

Properties of Object Data Types

An object information type exposes all backdrop of the object. For example, the Chore data type exposes over 40 task backdrop, having names such equally:

Key, Revision, Stamp, CallID, Number, EarlyStart, DueDate, LateStart, Priority, Status, Customer, Calendar, Region, District, Postcode, PreferredEngineers, ...

Reference Information Types

References have information types such every bit TaskReference or EngineerReference. The DeleteTask web operation provides an instance:

public void DeleteTask(...,    ref CallingServiceExample.CSSvc.TaskReference Task)

The second parameter is a reference to an existing job, which the operation deletes.

Backdrop of Reference Data Types

A reference data type does non expose a total set of object properties. Instead, it exposes just the backdrop required to identify an existing object. For example, the TaskReference information type exposes the post-obit job properties:

An application tin can ascertain the reference by specifying:

The Central, which is a unique numerical identifier of a business concern object
and/or
The combination of CallID and Number.

The latter approach works because CallID and Number are divers every bit the identifier of tasks. Y'all can define the identifier of any object by viewing the following setting in the legacy Administration tool:

Cardinal Settings > Integration & Services > SXP Object Reference

By editing the setting, you lot can customize the identifier. If you lot do this, the reference data blazon exposes the new identifier. For instance, if you change the task identifier to a user-defined property called WorkOrder, the TaskReference information type exposes the backdrop:

An application tin reference a task past specifying either the Key or the WorkOrder.

Data Types of Properties

The properties of the Service Border business organization objects, such equally Job, can have the following C# information types:

int bool double cord System.DateTime

Properties that contain pointers to other objects or to dictionary items accept a Reference information type. For instance, the Region property points to an detail in the Service Border Region dictionary. The property blazon is RegionReference.

Multivalue properties have an array data blazon. For example, the blazon of the RequiredEngineers property is EngineerReference[].

Unassigned Backdrop

In some web operations, it is critical to distinguish betwixt the following situations:

A property has been assigned an empty or default value.
The property has not been assigned at all; its value is missing.

This is important, for instance, if you call a web operation that updates an object that already exists in the Service Edge database. If you update with an empty value, the system assigns the empty value to the existing object. If you update with a missing value, the organisation does not alter the existing property value.

The Visual Studio environment handles this result in the following manner:

If a property has a data type of cord or ObjectName Reference, a missing value is indicated by assigning the value null.
If a property value has a data type such as int, bool, or System.DateTime, it does not take a null value. Instead, Visual Studio defines an accompanying, boolean property chosen PropertyName Specified. The Specified value indicates whether the original belongings is assigned.

For example, the task DueDate property has the DateTime information type. There is an accompanying property called DueDateSpecified. If the latter property is fake, the web service ignores the DueDate value.

The default value of the Specified property is simulated. When you assign a holding of a Service Border object, you must explicitly set up its accompanying Specified property to true.

Viewing a Web Service in the Object Browser

In the Visual Studio object browser, the web operations are located under the Client node:

ProjectName > ProjectName.ServiceNamespace > ServiceNameClient

In the tutorial, for case, the web operations are located under:

CallingServiceExample > CallingServiceExample.CSSvc > ScheduleServiceClient

You lot must select the Customer node. Higher levels of the tree display objects having like names as the web operations, merely you cannot utilise them to call the spider web service.

The Service Edge business objects are located under:

ProjectName > ProjectName.ServiceNamespace

For instance, y'all can view the Task object in the tutorial projection at:

CallingServiceExample > CallingServiceExample.CSSvc > Task

Some business organization objects have a big number of properties, some of which are inherited from a base type. To view the properties conveniently, right-click the upper-right pane of the Object Browser and select the options to:

Evidence Public Members
Show Inherited Members
Sort Alphabetically

User-Defined Backdrop

The web service API exposes user-defined backdrop of business objects past name.

For instance, if the Task object has a user-divers property chosen ContactFax, you tin can access the Task.ContactFax property from a Visual Studio application. You tin can write code such equally:

objTask.ContactFax = "222-1234567"

Updating Service References

If a spider web service changes, yous must update the service references in applications that call the service. Until you practice this, the applications can go on calling existing features of the service, but they cannot call new features.

Y'all might need to update service references if you create user-defined properties or dictionaries, and you want to expose them via the web services.

» To update a service reference in Visual Studio:

Obtain a new copy of the WSDL schema, and replace the existing copy.
In the Solution Explorer, right-click the service reference.
Click the pick to Update Service Reference.
Rebuild and redeploy the application.

Custom Collections and Properties

Backing Up and Restoring Tenants

Spider web Service API Reference

Initial Access to the Tenant