This document covers the following topics:
Writing a client application with the EntireX .NET Wrapper typically requires the following steps:
Starting from an IDL file, generate a C# client interface object as described under Using the .NET Wrapper. From the context menu of the IDL file, choose > > . As an alternative, use the Microsoft Visual Studio Wizard for EntireX .NET Wrapper. Both approaches generate C# sources from an IDL file. If there is a related server mapping file (Natural | COBOL), this is also used (internally).
Create a Visual Studio Solution. See Creating a Microsoft Visual Studio Solution.
Build a .NET assembly from the generated C# client interface object. See Creating the .NET Wrapper Client Stub Library (Assembly).
Create an application that uses the generated client interface object assembly and the .NET Wrapper runtime SoftwareAG.EntireX.NETWrapper.Runtime.dll. See Creating the .NET Wrapper Client Application.
The following description outlines as an example the steps required to build a .NET Wrapper client application (solution) with the Microsoft Visual Studio.
Start Microsoft Visual Studio.
From the menu, choose .... and choose an appropriate name for the solution.
Select the solution and choose , choose .
In the New Project dialog, choose and . Choose an appropriate name for the class library, e.g. "exampleClientStub".
Delete the default class file Class1.cs.
Select the new project and choose and add the example.cs file generated previously.
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.
Build the class library.
Add a new project to the solution: Choose the solution, , ..., , . Choose an appropriate name for the project, for example, "exampleClient".
Rename the default class file Class1.cs as appropriate.
Choose and add the .NET Wrapper runtime SoftwareAG.EntireX.NETWrapper.Runtime.dll.
Choose and add the .NET Wrapper client interface object exampleClientStub.
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;
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");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 with the EntireX .NET Wrapper typically requires the following steps:
Generate a C# file as described under Using the .NET Wrapper. From the context menu of the IDL file, choose > > . As an alternative, use the Microsoft Visual Studio Wizard for EntireX .NET Wrapper.
Insert your server-specific code at the required positions (C# methods).
Build a .NET Server assembly (DLL) from the generated C# file, following the rules for building a client stub library with the Microsoft Visual Studio.
Make the .NET Server assembly available to the RPC Server for .NET, see Locating and Calling the Target Server in the RPC Server for .NET documentation.
To start, stop and configure the RPC Server for .NET to suit your needs, see Administering the RPC Server for .NET in the RPC Server for .NET documentation.
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.
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;
}
}
}
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
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.
To use the broker and RPC user ID/password
Specify a broker user ID and broker password using the constructor and methods of class Broker.
Set the property NaturalLogon of class Service to true to enable sending the RPC user ID/password pair.
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.
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.
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.
To use SSL
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Specify the Broker ID using URL style, for example:
ssl://localhost:2010
If no port number is specified, port 1958 is used as default.
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. The mandatory trust_store parameter
specifies the file name of a keystore that must contain the list of trusted certificate authorities for the certificate of
the SSL server.
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.
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 | UNIX | Windows.
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 | UNIX | Windows | BS2000.
More information can be found under Internationalization with EntireX.