111 lines
5.3 KiB
Markdown
111 lines
5.3 KiB
Markdown
# IMSApiDotNet 10.0.0-59 – C# / HttpClient port
|
||
|
||
This project reconstructs the .NET IMSAPI client from the supplied Java reference bundle
|
||
`imsapi-client-javalib-java-bundle-10.0.0-59.jar` and the supplied legacy .NET client 10.0.0-3.
|
||
|
||
## What is included
|
||
|
||
- **446 generated public container/result classes** from the Java bundle.
|
||
- **356 IMSApiService methods** with the exact Java 10.0.0-59 wire method names.
|
||
- IHAP `BINARY_HASH` (protocol version 1) and `BINARY_FIELD` (version 17) serialization.
|
||
- Java class hashes and field order copied from the running Java reference implementation.
|
||
- `HttpClient` transport; no `HttpWebRequest` / `WebRequest` in the new transport.
|
||
- Locator support for `itac.artes.clusternodes`, `/artes/lookup`, `/imsapi/service?type=machine`, plus a direct service URL override.
|
||
- Request header behavior: `Content-Type`/`Accept` `application/octet-stream`, `reqnr`, optional Authorization and gzip request bodies.
|
||
- Legacy namespace `com.itac.mes.imsapi.client.dotnet` with the old synchronous return-code/ref-parameter API for the methods present in the legacy DLL.
|
||
- Message subscription compatibility implemented as a background `msgCallback` loop.
|
||
- Golden protocol vectors produced by the supplied Java JAR.
|
||
- The original JAR/DLL and extraction metadata under `reference/` for traceability.
|
||
|
||
## Build
|
||
|
||
Requires a current .NET SDK (8 or newer is recommended):
|
||
|
||
```powershell
|
||
./scripts/build.ps1
|
||
./scripts/test.ps1
|
||
```
|
||
|
||
The library itself targets `netstandard2.0` for broad compatibility. Its **assembly version stays at `10.0.0.3`** to improve drop-in compatibility with applications compiled against the supplied legacy DLL; file/package version is `10.0.0.59`. The golden-vector test project targets `net8.0`.
|
||
|
||
Output:
|
||
|
||
`src/IMSApiDotNet/bin/Release/netstandard2.0/IMSApiDotNet.dll`
|
||
|
||
## Legacy-style usage
|
||
|
||
```csharp
|
||
using com.itac.mes.imsapi.client.dotnet;
|
||
using com.itac.mes.imsapi.domain.container;
|
||
|
||
var api = IMSApiDotNet.loadLibrary();
|
||
api.setProperty("itac.artes.clusternodes", "http://mes-node-1:8080,http://mes-node-2:8080");
|
||
api.setProperty("itac.appid", "MyApplication");
|
||
|
||
int rc = api.imsapiInit();
|
||
var validation = new IMSApiSessionValidationStruct();
|
||
// populate validation fields ...
|
||
IMSApiSessionContextStruct context = null;
|
||
rc = api.regLogin(validation, ref context);
|
||
```
|
||
|
||
For a known endpoint you may bypass locator discovery:
|
||
|
||
```csharp
|
||
api.setProperty("itac.artes.ihap.serviceurl", "http://mes-host:8080/imsapi/service");
|
||
```
|
||
|
||
## Modern API
|
||
|
||
```csharp
|
||
var options = new com.itac.mes.imsapi.transport.IhapClientOptions();
|
||
options.ClusterNodes.Add("http://mes-node-1:8080");
|
||
using var client = new com.itac.mes.imsapi.transport.IhapClient(options);
|
||
var service = new com.itac.mes.imsapi.domain.IMSApiServiceStub(client);
|
||
var result = service.imsapiGetErrorText(context, -900);
|
||
```
|
||
|
||
## Verification status
|
||
|
||
The protocol layout was reverse-checked against **golden byte vectors generated by the supplied Java 10.0.0-59 JAR**. The test project contains vectors for both BINARY_HASH and BINARY_FIELD.
|
||
|
||
This ChatGPT execution environment does **not** contain a .NET SDK/compiler, and external package installation is blocked. Therefore the final `dotnet build` could not be executed here. The source tree was generated without NuGet dependencies so it can be built directly on a normal Visual Studio/.NET SDK machine.
|
||
|
||
## Compatibility notes
|
||
|
||
The Java 10.0.0-59 service contains six additional business methods not present in the old 10.0.0-3 .NET interface, plus `msgCallback` (which the old .NET wrapper hid behind `msgSubscribe`):
|
||
|
||
- `batchCompleteBatch`
|
||
- `batchSplitBatchNumber`
|
||
- `equCheckEquipments`
|
||
- `mlGetMaterialChainData`
|
||
- `mlSpliceMaterialChain`
|
||
- `mlSplitMaterialChain`
|
||
- `msgCallback` (transport callback used by the compatibility subscription loop)
|
||
|
||
They are available through `IMSApiServiceStub`. Existing methods retain the old synchronous wrapper shape where it could be derived from the supplied .NET binary.
|
||
|
||
The cluster locator in this port performs the Java-style `/artes/lookup` request and tests `/imsapi/service?type=machine`. In complex installations where lookup returns a node-id that maps to a URL not present in `itac.artes.clusternodes`, configure all reachable cluster-node base URLs or set `itac.artes.ihap.serviceurl` directly.
|
||
|
||
## .NET Framework 4.8 / Multi-target build
|
||
|
||
This revision multi-targets the library as `netstandard2.0;net48`.
|
||
|
||
After a Release build, use:
|
||
|
||
- `src/IMSApiDotNet/bin/Release/net48/IMSApiDotNet.dll` for classic .NET Framework 4.8 applications.
|
||
- `src/IMSApiDotNet/bin/Release/netstandard2.0/IMSApiDotNet.dll` for .NET Standard 2.0 consumers.
|
||
|
||
A private `Microsoft.NETFramework.ReferenceAssemblies.net48` build reference is included for the `net48` target. See `NET48_BUILD.md` for details.
|
||
|
||
## FIX3 - System.Net.Http / Visual Studio
|
||
|
||
If Visual Studio reports `CS0234`/`CS0246` for `System.Net.Http` or `HttpClient` in the `netstandard2.0` target, FIX3 contains an explicit conditional `System.Net.Http` 4.3.4 package reference. `CS1591` warnings for the generated API model have also been suppressed.
|
||
|
||
After opening the solution, run **Restore NuGet Packages** and then **Rebuild Solution**.
|
||
|
||
|
||
## FIX4 / native .NET Framework 4.8 build
|
||
|
||
If your goal is a .NET Framework 4.8 DLL, open `IMSApiDotNet_NET48_ONLY.sln`. This solution builds only the native `net48` project and therefore cannot be blocked by a failing `netstandard2.0` restore. See `FIX4_README.md`.
|