Scenario: How to Create, Import, and Use Windows Communication Foundation Services in your CA Plex Application

Introduction

Product: CA Plex

Release: 7.1

This scenario describes how as a CA Plex Developer, you can create, import, and use Windows Communication Foundation (WCF) services in your CA Plex application. The Plex WCF Service Generator plug-in lets you generate WCF Services from Service Connectors modeled in your application.

This Knowledge Base Article constitutes a portion of the official CA product documentation for this CA product. This Knowledge Base Article is subject to the following notices, terms and conditions.

How to Create, Import, and Use WCF Services in CA Plex

As a CA Plex Developer, you can create, import, and use Windows Communication Foundation (WCF) Services in your CA Plex.

The following diagram illustrates how you can create, import, and use WCF Services from your application:

Prerequisites

Install the following prerequisites in your machine to create, import, and use WCF Services in the CA Plex:

Note: Install Visual Studio in the following scenarios:

If you are writing client code in other environments and languages, then Visual Studio is not required.

Example:

Your client code could be Java that is developed within the Eclipse IDE.

Ensure to meet the following conditions for creating the WCF services on your Plex applications:

Create a Basic WCF Service

This example details how you can build and deploy the WCF sample model that is located in the \Samples\Dot NET WCF support directory. However, you can adapt the same process to deploy any of the Plex generated applications that meet the prerequisites.

Complete the following tasks to create a basic WCF service process:

  1. Generate, build, and test your Plex client-server application.
  2. Create a Plex connector for the Plex functions that you want to call.
  3. Add Service Connector specific implementation triples to your Plex Connector.
  4. Define the WCF endpoints that you want to expose.
  5. Associate the Service Connector Package object with a Code Library.
  6. Configure the Plex .Net runtime template configuration file.
  7. Run the Code Library Wizard.
  8. Review the generated and build the WCF services.
  9. Review your configuration files.
  10. Run your WCF service.
  11. Invoke an operation on your WCF service.

Follow these steps:

  1. Generate, build, and test your Plex client-server application.
    1. Start with a fully functioning Plex client-server application and that the functions you want to expose as service operations execute in the Plex environment correctly.

    Note: For more information about the SalesSystem.mdl sample model, refer the Dot NET Support and Code Libraries sample model.

  2. Create a Plex connector for the Plex functions that you want to call.
    1. Use the Component Modeling capabilities in Plex to create a Plex Connector that is generated as a WCF service.

      Note: You create the object model hierarchy similar to creating an EJB or COM Connector interface within Plex. For more information about the Plex Connector modeling capabilities, see the online help.

      The following diagram shows the basic triples that are required to model a Plex Connector interface.

    Part-1 Triples

    1. Enter similar data in your model.

      Note: In this example, no Service-specific triples have been added yet. You can add implementation triples to generate this as a COM object, an EJB, a WCF service, or even some other form of service object. You can review the object hierarchy in the Plex Object Browser.

  3. Add Service Connector specific implementation triples to your Plex Connector.
    1. Add implementation triples to the Package object to define the specifics of the WCF Service Connector that you will generate.

      The following diagram shows the implementation triples that are required to be added at Package level in the SalesSystem sample model.

    Part-1 Step 4 a

    The PkgTypeSys and PkgLanguageSys triples define the Package that is generated as a WCF service to the WCF generator.

    The PkgServiceHostTypeSys triple defines the type of service hosting to generate around your WCF Service components. You can use the following possible values of this triple:

    Note: The WAS option is not implemented yet and generates your WCF service in the same way as the None option.

    In this sample, a host type of None has been selected, which means although you cannot run the WCF service stand-alone, you can still run it through tools shipped with the .NET Framework and through Visual Studio.

  4. Define the WCF endpoints that you want to expose.
    1. Define the specifics of the endpoints that your WCF services expose such as name, protocol, and address. Use a new triple defined at Interface level, IntEndpointBindingNme, to affect the generation of endpoint information.

      The following diagram shows an example of the use of this new triple, and the two continuations that are associated with it.

    Part-1 Step 6a

    The endpoint binding name defines the location where clients can connect to your WCF service after it is hosted. The specific endpoint information consists of the protocol and address of the endpoint, which are represented by two continuation triples defined against the endpoint name.

    1. Type an HTTP protocol, and set the large property of the address Label object to http://localhost:8090, as shown in the following diagram.

    Creating a WCF

    Note:

  5. Associate the Service Connector Package object with a Code Library.
    1. Use an existing Code Library for deployment or use a new Code Library that is used for generating and deploying service interfaces. You can associate this using the new CdlServicePkg triple. The following diagram shows the Service Connector added to the Code Library already created for the SalesSystem model.

    Part-1 Step 7

    Note: The Code Library must be implemented with a language of C# when creating WCF service objects.

  6. Configure the Plex .Net runtime template configuration file.

    Your generated WCF service contains a copy of the Plex runtime, which the WCF uses to run. This runtime uses a configuration file named Plex.ObRun.dll.config. The Plex .NET Runtime uses the runtime settings information contained in this file when running the WCF service. The template version of this file is located in the \...\ob.Net\<configuration> directory, where <configuration> is either ‘Release’ or ‘Debug’. The configuration option is dependent on which compile option you take during the WCF service generate and build process.

    1. Ensure that the Default environment contains all the information required to access your .Net server application.
    2. Ensure to correct the AssemblyList and default database UDLFileName properties are set for your C# application.

      Note: These settings should be same as you used in Step 1 when you ran your original application.

    3. Enter the details of the servers where your application is deployed for the System i and Java server applications. If you do not have FncLocatedOnNme triples against your server functions, set the server details in the Default server location settings for the relevant platform.

      Note:

      • Ensure to enter the same information for your server connections that you have used for any WinC.ini or Java.properties file, to make a server connection.
      • If you have FncLocatedOnNme triples to define your servers, you can add locations in your configuration file that relate to the servers you want to contact.
      • After you change the default Plex.ObRun.dll.config file, it is copied and used for every WCF service that you generate and build. You can edit the config file that gets copied into your WCF service. However, if you regenerate your WCF service, the changes you made are overwritten by the template version.
    4. Save your modified configuration file.
  7. Run the Code Library Wizard.
    1. Select Tools, Code Library Wizard from the main Plex menu to launch the Code Library Deployment Wizard.
    2. Select the Code Library object that you have associated your newly modeled service with as the one you want to deploy.
    3. Complete the deployment steps until you get to the Plug-in Options step.
    4. Select the WCF Services plug-in from the drop-down menu.

      You see a list of options that are used for deployment.

    Creating a WCF

    1. Set the following WCF-specific settings:
      • DefaultBindingProtocol

        Defines the default protocol that is used for any endpoint that does not have a ProtocolSys triple defined against it.

        Note: The value is string based.

        Example: You can specify a custom protocol binding to be used for your endpoints in this field.

        Default value: wsDualHttpBinding.

      • DefaultHostType

        Defines the default WCF host type to generate for each Service Connector you are generating that does not have a PkgServiceHostTypeSys triple. You can choose the same as you choose for a triple.

      • EndpointBaseAddress

        Defines the base address where service endpoints without AddressLbl triples can be contacted. This base address can also be used for all endpoints where you may have specified a relative address in the AddressLbl literal.

    2. Retain all the default values and click Next to complete the Code Library Wizard deployment.
  8. Review the generated and build the WCF services.
    1. The Code Library Deployment Wizard creates the following items upon deployment:
      • Any Code Library assemblies that were selected to be created.
      • The WCF services for each Code Library that were associated with a Service Connector Package.
    2. Review the WCF source code that was generated during deployment.

      A directory named .\Services\Wcf is created within which, a sub-directory that is named after the Services Connector Package is created.

      This directory contains all the source and other support files for the WCF implementation of the Service Connector. Depending on the service host type selection for your service connector, the source is generated accordingly.

      Example: The following diagram shows the output for the SalesSystem sample model, where the service host type was set to None.

    Part-1 Step 10

    The WCF services and their associated Visual Studio projects are created and then the Code Library Wizard compiles these projects. Based on your host type selection, the code library is compiled and the output of the compile process. The actual output created by the compile process resides in the .\bin subdirectory under the main WCF project directory.

  9. Review your configuration files.

    The Visual Studio solution file, which is available in the .\Services\Wcf directory, contains the service that you have generated.

    1. Double-click the Visual Studio solution.

      The files that are generated for your WCF service displays in the Solution Explorer.

    2. Review the endpoint information that has been generated for this service based on the triples in the App.config file (step 3).

      You can see the following line of code or lines if you have configured multiple endpoints:

      <endpoint address ="http://localhost:8090" binding="wsDualHttpBinding" name="OrderWebEndpoint" contract="OrderService.IOrder" />

    Note: The Plex.ObRun.dll.config file, which is part of this project is a copy of the file that you configured in step 4. The WCF service uses this file to make calls into the Plex runtime. Ensure to configure this file correctly so that your application runs properly. When you encounter runtime errors, your probable diagnosis must be the configuration file.

  10. Run your WCF service.
    1. Select Debug, Start Debugging.

      The two processes, WCF Service Host and WCF Test Client tool are launched.

    2. Double-click the WCF Service Host icon in the system tray

      The WCF Service Host main window displays the running services.

      The WCF Test Client tool (second process), appears after the WCF service is started.

      Note: This tool queries the WCF service through the metadata exchange endpoint (also known as the ‘mex endpoint’) exposed for the service and displays the WCF service details and all the operations that can be called on it.

    3. Double-click the method that you want to call.

      A parameter entry page appears on the right-hand side of the screen displaying the input parameters for the operation you selected. These parameters are based on the Data Contracts generated for the operation, and were derived from the function in the Plex model. The endpoint operation calls your CA Plex server function with these parameters.

    4. Initialize all the input parameters available on the right-hand side of the WCF Test Client interface to call the function.
    5. Initialize each input variable class that are passed for the operation, since the Data Contracts for Plex WCF Services are generated as nested-classes for each variable.
    6. Select one of the values from the drop-down next to each input variable class name (example, each grid entry that contains the word ‘(null)’).

      This selection initializes the inner-classes that contain the actual input fields that you pass to the operation.

    7. Set the values for your call.

      The following WCF Test Client interface displays when you are ready to call your service.

    Creating a WCF

  11. Invoke an operation on your WCF service.
    1. Click Invoke to call the operation on the service.

      The call results display in the Response window.

    2. Select Debug, Stop Debugging to close the client and the service.

Import and Use WCF Services in .NET Client Applications

After you confirm that the WCF service works as expected, you can create client applications that consume your service. The following section details creating client applications that call WCF services.

The pre-requisite to create client applications is to have an understanding of creating C# applications using the Visual Studio project templates.

Example:

Complete the following tasks to show how a sample project that ships under the Visual Studio Clients directory are created:

  1. Create a Visual Studio Project.
  2. Add the controls to the Form.
  3. Add a Service Reference for the WCF service.
  4. Add C# code to call your WCF service.
  5. Compile and run your client application.

Follow these steps:

  1. Create a Visual Studio Project.
    1. Open a new instance of Visual Studio and create a new C# Windows Forms Application project that is named WindowsClient, in a Visual Studio Clients solution.

      Note: Ensure that the project targets the .NET Framework 3.5 or above.

      After the project is created, a form named Form1.cs appears in the design view.

  2. Add the controls to the Form.
    1. Add the following controls to the form, and set the properties as shown.
      • DataGridView (Name: dgvOrders)
      • Button (Name: btnGetOrders, Text: Get Orders)
    2. Resize the layout to look as follows:

    Import and Use WCF

    1. Double-click the button to add a clicked event for it.
  3. Add a Service Reference for the WCF service.
    1. Select Project, Add Service Reference.
    2. Type the metadata exchange endpoint address, as specified in the Review the generated and build WCF services (step 8) and click Go.

      Hint: You can copy the metadata exchange endpoint address by selecting the running service in the WCF Service Host application, right-clicking on the service, and selecting Copy Metadata Address from the popup menu.

      The Visual Studio queries the service and displays the operation endpoints that it exposes.

    3. Expand the Order service to see the IOrder interface, and select the interface to see the GetOrderHeaders operation that it exposes.
    4. Change the namespace name as OrderServiceReference and click OK to create a client-side stub to interact with your deployed WCF service.

    Import and Use WCF

    After you created the client WCF stub code, the OrderServiceReference node appears under the Service References section of your project. This contains the client code that your program needs to interact with and call operations on your running WCF service.

    Import and Use WCF

  4. Add C# code to call your WCF service.

    Add the following code to the top of the Form1.cs source file, immediately after the using statements.

    // Add a reference to the namespace that contains the service client stub.

    using WindowsClient.OrderServiceReference;

    Now change the btnGetOrders_Click method as follows:

    private void btnGetOrders_Click(object sender, EventArgs e)

    {

    // Create an instance of the WCF Service via the client stub.

    OrderClient myOrderClient = new OrderClient();

    // Create the input DataContract for the operation we wish to call.

    HeaderBlockFetch_Input input = new HeaderBlockFetch_Input();

    // WORKAROUND: This gets around the inner-class initialization issue.

    HeaderBlockFetch_Input._Control control = new

    HeaderBlockFetch_Input._Control();

    HeaderBlockFetch_Input._Position position = new

    HeaderBlockFetch_Input._Position();

    // Set up the input parameters for the call.

    control.Position = "Y";

    position.ORDERNUMBER = 1;

    // WORKAROUND: This gets around the inner-struct issue.

    input.Control = control;

    input.Position = position;

    // Call the operation on the service stub.

    HeaderBlockFetch_Output output = myOrderClient.GetOrderHeaders(input);

    // Do whatever you want with the output.

    dgvOrders.DataSource = output.FetchedData;

    }

  5. Compile and run your client application.
    1. Ensure that your WCF service is up and running and select Debug, Start Debugging to run your project.
    2. Click Get Orders.

      The DataGridView control populates the results of the call.

    Part-2 Step 5 - Copy

    Note:

  6. Close the client application and the running WCF service.

Change the WCF Service Hosting Type

After you create the client applications that call the WCF services, you can change the WCF service hosting type. The following section details how you can host your WCF services using the different hosting types.

The basic steps for developing WCF services with different host types remain the same; however, configuring and running the WCF services after they are generated differs for each host type.

Follow these steps:

  1. Reuse the client code that you developed in the Import and Use WCF Services in .NET Client Applications section, to call any of these services, after they are running.
  2. Model your WCF Service as detailed in creating a basic WCF service. To change the WCF hosting type, choose your hosting type using the PkgServiceHostTypeSys triple. Use the descriptions of each hosting type to decide the required hosting type to use. All other service modeling concepts are the same for all hosting types. Enter the same endpoint information for all hosting types.
  3. Use the Code Library wizard to deploy your WCF service as detailed in creating a basic WCF service. After the deployment is complete, from the source output directory, open the Visual Studio that relates to the WCF service you just generated. Notice that different files are generated into your project depending on the project type.

Note: For a detailed description of each hosting type, the files that they generate, and how to deploy and run each WCF host type, see the following sections:

Application Hosting

The WCF Services that use the Application hosting type are hosted by a basic .NET managed application that runs as a console executable program. The following diagram shows the example that is used in creating a basic WCF service, which is generated as a managed application.

Application Hosting

The Program.cs file contains a main entry point for the WCF Service Host process. The Main() method that is contained within this source file starts up the WCF service, when the process starts. After the process starts, the WCF service manages connection to the service from client programs.

Follow these steps:

  1. Ensure that your modeled Service Connector has a PkgServiceHostTypeSys of the application.
  2. Generate and build your WCF service using the Code Library Deployment Wizard.
  3. Ensure that the Plex .NET runtime configuration information is correct in the deployed application.
  4. Review the Plex.ObRun.dll.config file in the compiled WCF service output directory.
  5. Double-click the WCF service executable that is located in the .\bin\Debug or .\bin\Release directory where the service gets compiled by the Code Library Deployment Wizard.

    A console window displays the information that the WCF service is ready to be called.

    Note: You can also run the WCF service using the Visual Studio debugger.

  6. Call your WCF service by writing a client application.

    Note: For more information, see the Import and Use WCF Services in .NET Client Applications section.

IIS Hosting

The WCF services that use the IIS hosting type generate in an IIS-friendly project that differs slightly from the other project types. You can review the major differences by looking at the project in the Visual Studio Solution Explorer.

IIS Hosting

The following list outlines the major differences between the IIS and other hosting types:

Hosting WCF Service using the IIS Hosting Type:

Follow these steps:

  1. Ensure that your modeled Service Connector has a PkgServiceHostTypeSys of IIS.
  2. Generate and build your WCF service using the Code Library Deployment Wizard.
  3. Open the solution for your generated WCF service in Visual Studio.
  4. Ensure that the Plex .NET runtime configuration information is correct in the deployed application.
  5. Review the Plex.ObRun.dll.config file in the compiled WCF service output directory.

    Note: You can run this host type using the Visual Studio ASP.NET Development Server that ships with Visual Studio.

  6. Select Debug, Start Debugging to debug the project.

    An instance of the ASP.NET Development Server starts to run the application in.

  7. Select Yes to add the debug capability for your application.

    After the WCF service is hosted in the ASP.NET Development Server, Internet Explorer points to the root directory of the web application.

  8. Select the .svc file that is created for the WCF service.

    The browser displays some basic information about the deployed service instance.

    IIS Hosting

    Note: The ASP.NET Development Server starts the WCF service on a unique port number. In this example, the port number is 58952. You can use this port when calling any operations on the WCF service or when querying the metadata exchange endpoint associated with the service.

  9. Call your WCF service by writing a client application.

Note: Since the ASP.NET Development Server instance has allocated a non-used port, use this port for the metadata exchange endpoint when importing the service for use. For more information, see the Import and Use WCF Services in .NET Client Applications section.

Windows Service Hosting

The WCF services that are hosted using the Windows Service hosting type generates a host wrapper that compiles as an executable. This executable can be installed and run as a Windows Service. You can review the major differences by looking at the project in the Visual Studio Solution Explorer.

Windows Service Hosting

The following list outlines the major differences between the Windows Service and other hosting types:

Hosting WCF Service using the Windows Service Hosting Type:

Follow these steps:

  1. Ensure that your modeled Service Connector has a PkgServiceHostTypeSys of Service.
  2. Generate and build your WCF service using the Code Library Deployment Wizard.
  3. Ensure that the Plex .NET runtime configuration information is correct in the deployed application.
  4. Review the Plex.ObRun.dll.config file in the compiled WCF service output directory.
  5. Double-click the InstallService.cmd file that is located in the .\bin\Debug or .\bin\Release directory where the service gets compiled by the Code Library Deployment Wizard.

    The following image shows a successful installation, after you press any key to exit the install batch process.

    Windows Service Hosting

  6. Locate your newly installed Windows Service in the Computer Management tool, under the Services node (the service is named after the Code Library to which is associated).

    Windows Service Hosting

  7. Select Action, Start to start the service.

    The Windows Service starts and is now ready to accept client requests.

  8. Call your WCF service by writing a client application.

    Note: For more information, see the Import and Use WCF Services in .NET Client Applications section.

Troubleshooting

The basic code that is outlined in importing and using WCF Services in .NET Client Applications enables you to make calls through WCF to your Plex server applications. However, one of the primary considerations while creating client-based applications that access your services is the error handling.

Error Handling

Symptom:

There can be many reasons when a call to a Plex-generated server application fails. Here are some of the scenarios:

Solution:

You can handle the first three types of errors by checking whether the Environment<*Call status> flag has a value of <*Call status.*Error> returned by the runtime. The Plex-generated function can then test the environment field after the call and decide if the call was successful or not.

You can handle the last type of error at function level in the Action Diagram code. In the Plex Pattern and Class libraries, any error that is returned from a database is returned to the calling program by copying the Environment<*View status> field into the Environment<*Returning status> field. In turn, this is returned to the calling function, which can check the value in the Environment<*Returned status> after the call to decide if the call was successful or not.

Note: The WCF supports the concept of Fault Contracts to define any abnormal return from an operation call. A fault contract defines the type of exception a client can expect to get back if an error occurs in the server. The fault contract is then translated back into the client as a technology-specific exception. The Plex WCF runtime defines a fault contract that is used against every operation generated only a WCF service interface called PlexRuntimeException. By monitoring this exception in client code, a caller can validate that a call was successful and if it was not, can decide on the best course of action.

Troubleshooting Information

The Plex-specific runtime information is hidden from the caller. The PlexRuntimeException class contains a number of properties that a client application can use to diagnose an error. The properties are:

Best Practice

As a best practice, use the exception handling when calling operations on the WCF services. Ensure to enclose every operation call with a try/catch block that monitors the exceptions raised, based on the WCF fault contracts that are defined on an interface. You can add error handling to the C# code while importing and using WCF Services in .NET Client Applications.

Follow these steps:

  1. Add a reference to the System.ServiceModel namespace to your client application that lets you monitor the fault exceptions in your runtime.

    // Add a reference to the WCF runtime namespace (for exception handling).

    using System.ServiceModel

  2. Modify the btnGetOrders_Click() method where the WCF service call is made.

    private void btnGetOrders_Click(object sender, EventArgs e)

    {

    // Create an instance of the WCF Service via the client stub.

    OrderClient myOrderClient = new OrderClient();

    // Create the input DataContract for the operation we wish to call.

    HeaderBlockFetch_Input input = new HeaderBlockFetch_Input();

    // WORKAROUND: This gets around the inner-class initialization issue.

    HeaderBlockFetch_Input._Control control = new

    HeaderBlockFetch_Input._Control();

    HeaderBlockFetch_Input._Position position = new

    HeaderBlockFetch_Input._Position();

    // Set up the input parameters for the call.

    control.Position = "Y";

    position.ORDERNUMBER = 1;

    // WORKAROUND: This gets around the inner-struct issue.

    input.Control = control;

    input.Position = position;

    try

    {

    // Call the operation on the service stub.

    HeaderBlockFetch_Output output= myOrderClient.GetOrderHeaders(input);

    // Do whatever you want with the output.

    dgvOrders.DataSource = output.FetchedData;

    }

    catch (FaultException<PlexRuntimeException> ex)

    {

    // Report the Message, Environment<*Call status> and

    // Environment<*Returned status> as passed back from the server.

    // These values are held in the Detail portion of the FaultException.

    String title = "Plex Function Call Exception";

    String message1 = "Message: " + ex.Detail.Message;

    String message2 = "\nEnvironment<*Call status>: " +

    ex.Detail.CallStatus.ToString();

    String message3 = "\nEnvironment<*ReturnedStatus>: " +

    ex.Detail.ReturnedStatus;

    // Show the message.

    MessageBox.Show(message1 + message2 + message3, title);

    }

    }

Generate WCF Services for Non C# Functions

The Plex .NET runtime fully supports the calling of Plex-generated Java and System i functions. However, set a generation option in your Plex build file to generate the necessary C# parameter interface classes suitable for marshalling input and output parameters to those functions.

Follow these steps:

  1. Close the local model that you are using.
  2. Open the build file, which is associated with your local model in a notepad.
  3. Add the following entries that are shown to the top of the file.

    [Service generation options]

    Create C# interface classes=1

  4. Save and close the build file.
  5. Reopen the local model and generate the Plex functions that you want to call using the WCF service.

    This generates the _ObIn and _ObOut classes for each function that want to call using the WCF service.

The rest of steps to create the WCF service remain the same.

Note: You can retain the build file option that is switched on. You get the _ObIn and _ObOut classes for any non-C# function you generate, though it is not called using the WCF. If you switch this option off and if you add another method to the WCF service, then repeat the steps to generate the necessary parameter interface class.

Copyright

Copyright © 2014 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to their respective companies.

Back to the Top