Writing Applications with the .NET Wrapper

This document covers the following topics:

Writing a Client Application

Required Steps

Writing a client application with the EntireX .NET Wrapper typically requires the following steps:

The following description outlines as an example the steps required to build a .NET Wrapper client application (solution) with the Microsoft Visual Studio.

Creating a Microsoft Visual Studio Solution

  1. Start Microsoft Visual Studio.

  2. From the File menu, choose New > Blank Solution.... and choose an appropriate name for the solution.

Creating the .NET Wrapper Client Stub Library (Assembly)

  1. Select the solution and choose Add, choose New Project.

  2. In the New Project dialog, choose Visual C# Projects and Class Library. Choose an appropriate name for the class library, e.g. "exampleClientStub".

  3. Delete the default class file Class1.cs.

  4. Select the new project and choose Add > Add Existing Item and add the example.cs file generated previously.

  5. Select References, choose Add Reference and add the .NET Wrapper runtime SoftwareAG.EntireX.NETWrapper.Runtime.dll.

    Note:
    Make sure the property CopyLocal is not set to true in the properties of the referenced assembly.

  6. Build the class library.

Creating the .NET Wrapper Client Application

  1. Add a new project to the solution: Choose the solution, Add, New Project..., Visual C# Projects, Console Application. Choose an appropriate name for the project, for example, "exampleClient".

  2. Rename the default class file Class1.cs as appropriate.

  3. Choose References > Add Reference and add the .NET Wrapper runtime SoftwareAG.EntireX.NETWrapper.Runtime.dll.

  4. Choose References > Add Reference > Projects and add the .NET Wrapper client interface object exampleClientStub.

  5. Now implement your client application. Add the following lines to the top of the class file: 

    using SoftwareAG.EntireX.NETWrapper.Runtime;
using SoftwareAG.EntireX.NETWrapper.Generated.example;

  6. In a method of the application class implement the connection to an EntireX Broker, for example: 

    Broker broker = new Broker("localhost:1971", "ERX-USER");
broker.Logon("ERX-PASS");

    and an EntireX RPC service, for example:

    Service service = new Service(broker, "RPC/SRV1/CALLNAT", "EXAMPLE");
service.UserIDAndPassword("RPC-USER", "RPC-PASSWORD");

  7. The example class can now be instantiated, for example:

    Example e = new Example( service );

    and the example methods called, for example:

    int result = ex.Calculator( "+", 10, 15);

Writing a .NET Server Assembly

Writing a .NET server assembly with the EntireX .NET Wrapper typically requires the following steps:

Creating ASP.NET Web Services

The generated C# client interface object can be used in an ASP.NET web service to publish EntireX RPC services as web services. With Visual Studio you can easily create an ASP.NET web service that publishes methods of the EntireX RPC service (or your own methods that just use the EntireX RPC service).

Note:
The .NET Wrapper Runtime uses unmanaged DLLs. For this reason, ASP.NET applications have to run in full-trust mode.

Example

You have built the .NET Wrapper example EntireX\examples\RPC\dotNetClient as described in the README file.

Then create a new "ASP.NET web service" project with references to the generated client interface object and the .NET Wrapper runtime.

You can use the following example code (in the .asmx file) to implement a Web method add that exposes the calc method of the example. 

using System;
using System.Collections;
using System.ComponentModel;
using System.Data;
using System.Diagnostics;
using System.Web;
using System.Web.Services;
using System.Text;
using SoftwareAG.EntireX.NETWrapper.Runtime;
using SoftwareAG.EntireX.NETWrapper.Generated.example;
namespace WebService1
{
/// <summary>
/// Summary description for Service1.
/// </summary>
public class Service1 : System.Web.Services.WebService
{
public Service1()
{
//CODEGEN: This call is required by the ASP.NET Web Services Designer
InitializeComponent();
}
#region Component Designer generated code
//Required by the Web Services Designer
private IContainer components = null;
/// <summary>
/// Required method for Designer support - do not modify
/// the contents of this method with the code editor.
/// </summary>
private void InitializeComponent()
{
}
/// <summary>
/// Clean up any resources being used.
/// </summary>
protected override void Dispose( bool disposing )
{
if(disposing && components != null)
{
components.Dispose();
}
base.Dispose(disposing);
}
#endregion
// WEB SERVICE EXAMPLE
 [WebMethod]
public int add(int sum1, int sum2)
{
Example e = new Example();
int result = e.calc("+", sum1,sum2);
return result;
}
}
}

Using the Broker and RPC User ID/Password

EntireX supports two user ID/password pairs: a broker user ID/password pair and an (optional) RPC user ID/password pair sent from RPC clients to RPC servers. With EntireX Security, the broker user ID/password pair can be checked for authentication and authorization.

The RPC user ID/password pair is designed to be used by the receiving RPC server. This component's configuration determines whether the pair is considered or not. Useful scenarios are:

  • Credentials for Natural Security

  • Impersonation under z/OS (CICS, Batch, IMS)

  • Web Service Transport Security with the RPC Server for XML/SOAP, see XML Mapping Files

  • Service execution with client credentials for EntireX Adapter Listeners, see Configuring Listeners

  • etc.

Sending the RPC user ID/password pair needs to be explicitly enabled by the RPC client. If it is enabled but no RPC user ID/password pair is provided, the broker user ID/password pair is inherited to the RPC user ID/password pair.

With the property NaturalLogon (see below) sending the RPC user ID/password pair is enabled for the Java RPC clients. If you do so, we strongly recommend using SSL/TLS. See Using SSL/TLS.

Start of instruction setTo use the broker and RPC user ID/password

  1. Specify a broker user ID and broker password using the constructor and methods of class Broker.

  2. Set the property NaturalLogon of class Service to true to enable sending the RPC user ID/password pair.

  3. If different user IDs and/or passwords are used for broker and RPC, use the methods and properties offered by class Service to provide a different RPC user ID/password pair.

  4. By default the library name sent to the RPC server is retrieved from the IDL file (see library-definition under Software AG IDL Grammar in the IDL Editor documentation). The library name can be overwritten. This is useful if communicating with a Natural RPC server. Specify a library in the property Library of class Service.

Using SSL/TLS

RPC client applications can use Secure Sockets Layer/Transport Layer Security (SSL/TLS) as the transport medium. The term "SSL" in this section refers to both SSL and TLS. RPC-based clients are always SSL clients. The SSL server can be either the EntireX Broker or Direct RPC in webMethods Integration Server (IS inbound). For an introduction see SSL/TLS, HTTP(S), and Certificates with EntireX in the platform-independent Administration documentation.

With the .NET Wrapper, the SSL parameters (e.g. certificates) are appended to the Broker ID, separated by a question mark (?). See URL-style Broker ID under EntireX RPC Programming.

Start of instruction setTo use SSL

  1. To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides sample certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.

  2. Specify the Broker ID using URL style, for example:

    ssl://localhost:2010

    If no port number is specified, port 1958 is used as default.

  3. Specify SSL parameters, for example:

    "VERIFY_SERVER=N&TRUST_STORE=c:\\certs\\CaCert.pem"

    If the SSL client checks the validity of the SSL server only, this is known as one-way SSL. Two SSL parameters must be specified on the SSL client side: trust_store and trust_passwd. The mandatory trust_store parameter specifies the file name of a PKCS#12 certificate store that must contain the certificate chain of the trusted certificate authority (CA) that issued the SSL server's certificate.
    To unlock this certificate store, the password has to be set with SSL parameter trust_passwd.
    By default a check is made that the certificate of the SSL server is issued for the hostname specified in the Broker ID. The common name of the subject entry in the server's certificate is checked against the hostname. If they do not match, the connection will be refused.
    You can disable this check with SSL parameter verify_server=no.

    If the SSL server additionally checks the identity of the SSL client, this is known as two-way SSL. In this case the SSL server requests a client certificate (the parameter verify_client=yes is defined in the configuration of the SSL server). Two additional SSL parameters must be specified on the SSL client side: key_store and key_passwd. This keystore must contain the private key of the SSL client. The password that protects the private key is specified with key_passwd.

    The ampersand (&) character cannot appear in the password.

    SSL parameters are separated by ampersand (&). See also SSL/TLS Parameters for SSL Clients.

  4. Make sure the SSL server to which the .NET client connects is prepared for SSL connections as well. The SSL server can be EntireX Broker or Direct RPC. See Running Broker with SSL/TLS Transport under z/OS | Linux | Windows.

Using Internationalization with the .NET Wrapper

RPC clients generated with the .NET Wrapper use by default the "current locale" encoding set up on the Windows system for converting UNICODE (UTF-16) representations of strings to single-byte or multibyte representations that are sent to the Broker, and vice versa. The codepage name is also transferred to tell the broker the encoding of the data. If you want to adapt the locale settings of your Windows system, use the Regional and Language Options in the Windows Control Panel.

The Broker class of the .NET Wrapper Runtime makes use of the .NET Framework class System.Text.Encoding for character conversion.

Refer also to the .NET Framework class library documentation for System.Text.Encoding.

The CharacterEncoding property of the Broker class that guides the character conversion is initialized with System.Text.Encoding.GetEncoding(0) (current locale). The application programmer can also assign a custom encoding object to the Broker class's CharacterEncoding property for custom character conversions. If an encoding object is provided, the corresponding codepage is transferred to the Broker instead of the default Windows locale.

Enable character conversion in the broker by setting the service-specific attribute CONVERSION to "SAGTRPC". See also Configuring ICU Conversion under z/OS | Linux | Windows | BS2000. More information can be found under Internationalization with EntireX.