Release 5.0 alpha.2

[fw2568]

Release 5.0-alpha.1

This release should only be consumed by those who are interested in the new features coming in the v5 release.

Not ready for production!

If you add it to a production project, you should only do so to see (potentially) how many breaking changes there are.

Breaking changes

Removed AllowStartOfPrograms from IRfcRuntime and IConnection

AllowStartOfPrograms was marked as obsolete in the previous release and has been removed.

RfcErrorInfo replaced by RfcError

Within language-ext the logic of error types (e.g. used in Either,L,R) has changed from a struct (like RfcErrorInfo) to a class hierarchy starting with the error type Error. Therefore, we have replaced RfcErrorInfo with the new type RfcError in all APIs.
RfcError is syntactically compatible with RfcErrorInfo and it can be converted between the two types. So you can simply replace RfcErrorInfo with RfcError in all your code.

Deprecation of RfcRuntime

The RfcRuntime was the central class to abstract between the Netweaver SDK API and YaNco. Originally YaNco was built with several runtime versions (either a managed C++ implementation or an Interopt version). These days the RfcRuntime is only used for unit testing, but is quite difficult to handle.
The RfcRuntime is no longer used internally. Instead, we now use the language-ext runtime concept (see also https://github.com/louthy/language-ext/wiki/How-to-deal-with-side-effects). This abstracts between all operations that perform IO (calls to SAP Netweaver RFC SDK) and our library.

The default runtime we use is SAPRfcRuntime which is a struct that provides access to IO effects (e.g. RfcConnectionEff). However all types have been updated to support also a custom runtime that users build for their applications (for example a runtime with Console support).

For example, RfcContext is now also available as RfcContext<RT>, where RT is the type of runtime to use. All new types also no longer use EitherAsync<RfcError,R>, but Aff<RT, R> (or the synchronous version Eff<RT,R>). Aff is the type of an asynchronous effect that is not executed immediately, but only in the context of a runtime.

Also the ConnectionBuilder and RfcServerBuilder are now implemented as generic type ConnectionBuilder<RT> and RfcServerBuilder<RT>. If you use the generic version, you opt for the new runtime concept, so the Build() methods of both builders will now return an Aff<RT, R> instead of a Func<Either<RfcError,R>.

The non generic versions of these types are still available. So common use cases should work without any change.
But if you have used deeper APIs, you will have some types where you may need to add the runtime generic type parameter to your code.

You will also have to rewrite all unit tests that replaced calls on IRfcRuntime with mocked IO effects. See our unit tests for an example.

Connection was replaced by Connection<RT>

The non-generic version of Connection was removed.
This will typically only be noticed during unit testing, as you don't normally need to create the connection yourself.

ConnectionBuilder runtime methods results change

If you have configured a runtime using the ConfigureRuntime method, you may notice that the result types within the builder have changed. The updated version of ConfigureRuntime no longer configures an RfcRuntime, but the settings within the runtime.

Rfc Servers and callbacks are only supported with runtime type

For callbacks and RFC servers, we have removed support for the non-generic versions, as adding them would have required a lot of duplicate code. Since RFC servers are also a more expert feature, we feel that this change will not have a big impact.

This applies to to following types: CalledFunction, IRfcServer, RfcServer, RfcServerContext, ITransactionalRfcHandler
The context within a called function is also only available as IRfcContext<RT>, but this is consistent with the following change.

Function handlers now have to return effects (Eff or Aff)

In older versions function handlers had to return EitherAsync<RfcError,Unit>. This was changed to Aff<RT,Unit>. Also the Process method on a CalledFunction<RT> processing chain now has to return a Eff or Aff. ProcessAsync is still supported and will be wrapped into a Aff internally.

This change also removes an inconsistency in how errors are handled after the Process step of the function chain.
The Reply method of the called function chain no longer allows you to access the error of the process step if you return an Either. Instead, the error is always returned to the ABAP backend and Reply is not called.

New features

Side-effect free functional API

As explained above, one of the key improvements in moving to the new runtime concept was the isolation of I/O operations.
Therefore, we now provide a new API that can be used to create pure functional code.

Please see the README for a high-level introduction to these patterns.
Typically, there is a learning curve to fully understand the concept of the new runtime, but once mastered, it allows you to write pure functional code like this: https://github.com/dbosoft/YaNco/blob/main/samples/net6.0/ExportMATMAS/SAPIDocServerRT.cs

For classic OO integration (and dependency injection via a dependency container), the RfcContext is still available and supported.
However, under the hood it just wraps to the functional API as the RfcContext has an internal managed runtime behind it that is created on the fly.

New types SAPRfcRuntime and TestSAPRfcRuntime

The SAPRfcRuntime was allready explained in detail above. The TestSAPRfcRuntime should be used as a template for unit testing, by settings its IO implementations by mock implementions. We have not added any mock types to the library as we assume that you use a mocking framework like Moq.

IO interfaces

The IRfcRuntime was splitted into following IO interfaces. Please note that we followed the naming convention of language-ext that IO interfaces don't start with an I.

• SAPRfcTypeIO
  Used for type creation and type information lookup

• SAPRfcStructureIO
  Used for SAP structure management

• SAPRfcTableIO
  Used for table management and navigation to table rows.

• SAPRfcFunctionIO
  IO operations for SAP functions like creation of function descriptions and invocation of functions.

• SAPRfcConnectionIO
  Used for deep level connection IO that are normally only executed within a IConnection.

• SAPRfcServerIO
  Used for deep level server IO that are normally only executed within a IRfcServer.

• SAPRfcFieldIO
  IO methods for mapping and reading of field values either directly from the NW RFC SDK or via a field mapper.

New class SAPRfc<RT>

The SAPRfc<RT> is a static class that implements a number of common use cases for interacting with SAP systems as a client. It is pure functional without any side-effects.
Highlighted methods:

• useConnection
  This method takes a Aff<RT,IConnection> as input (as from the ConnectionBuilder<RT>.Build method) and allows to use the IConnection with the provided function.
• useContext
  This method also takes a Aff<RT,IConnection> as input, but then provides a IRfcContext<RT> within the function. In this case the connection will be managed by the context.

---

This discussion was created from the release Release 5.0 alpha.1.

[fw2568]

Release 5.0-alpha.2

This release should only be consumed by those who are interested in the new features coming in the v5 release.

Not ready for production!

If you add it to a production project, you should only do so to see (potentially) how many breaking changes there are.

Breaking changes

see https://github.com/dbosoft/YaNco/releases/v5.0-alpha.1 for alpha.1 breaking changes

Transactional RfcHandlers have to return Eff<RT,RfcRc>

Transactional handlers now have to return a effect (Eff). All unhandeled errors that occur in a transactional rfc handler will be logged and responded back to the SAP backend with RfcRc.RFC_EXTERNAL_FAILURE.

Reduced number of traits

This is breaking only between alpha.1 and alpha.2:
Instead of using one trait per IO implementation we have reduced traits to HasSAPRfc<RT> for clients and HasSAPRfcServer<RT> for servers. This reduced the complexity for runtime type constraint.

New Features

Added extension method RunIO to IRfcContext

As IRfcRuntime is deprecated but IRfcContext is not, we have to provide a way that users can access IO effects from a RfcContext.
RunIO provides a bridge from IRfcContext to the new functional API. The effect constructed with this method will be run with the build-in SPRfcRuntime.

Internals

• Cleaned up code quality issues throughout the project.
• Updated sample ExportMATMAS to functional style.
• Dependencies have been updated to latested versions,
• Disabled security warnings for ASPNET Core 2.x as it is only used in samples.