native class — a provider implemented in .NET

native class <Name> : <ISeam> { public <T> <Setting> = <default>; public const <T> <Constant> = <value>; }

A `native class` is a provider whose behaviour is a .NET assembly its package ships. It is declared in Osy# for what the platform needs to know before anything runs — the seam it implements, the settings an app registers it with, and the constants the compiler reads — and it has no bodies.

Summary#

Most providers — a data source, a blob store, an export sink — are ordinary Osy# classes. When one has to be .NET (a vendor SDK, a driver, a codec), a package declares it as a native class and ships the assembly that implements it. Everything that reads a provider reads the declaration: registration, settings checks, pushdown checks, decompile. Only the call differs, and it goes to the assembly.

Signature#

native class Name : ISeam {
  public string Setting = "";                                // a setting, set where the app registers it
  public const QueryFeatures Pushdown = QueryFeatures.All;   // a constant the compiler reads
}

Description#

What it declares#

The seam it implements: IBlobStore, IEntitySource, IWritableEntitySource (a source that also runs updates and deletes) or IExportSink. The platform calls a native class only through one of those.
Its settings: public fields, set where the app registers the class, and handed to the assembly. They use the same types a seam carries — text, numbers, bools, dates, ids, byte[], enums, lists, string-keyed dictionaries and classes of those.
Its constants: Pushdown, Functions and the rest the compiler reads from a provider.

It has no methods, no constructor and no computed properties — the assembly implements those.

Where it may be declared#

Only in a package, because only a package ships an assembly. The manifest names it with the native role:

package Acme.Warehouse {
  version "1.0.0";
  model   "model/**/*.osy";
  native  "lib/Acme.Warehouse.dll";
  use Osysharp.Sources;
}

The role has no default, and packing refuses a native glob that matches nothing or matches a file that is not a .dll. The assembly is built against the C# the platform generates from the seam — see Generating the C# a native provider implements.

What is refused#

Each is a compile error naming the class:

a native class in an application's own source, or in a package whose manifest names no assembly;
a method, a constructor or a computed property on one;
native on anything but a class, or together with abstract;
a base class — a native class implements a seam directly, since no Osy# body of a base would run on it;
a contract that is not a platform seam, or no seam at all;
a setting that is not public, or whose type cannot cross to .NET;
at deploy, a native package on shared hosting, where one tenant's native code could reach another's data. Native packages run on dedicated and self-hosted platforms.

Running it#

A registered native class runs its package's assembly. The platform:

loads the assembly from the archive the app's version was built from;
sets the settings the app registered;
calls it through the seam.

A throw inside the assembly is reported naming the package, its version, the class and the member.

The assembly compiles the seam osy seam generate writes (Generating the C# a native provider implements) and references nothing of the platform's. A deploy reads the package's assemblies without running them, and refuses one whose seam hash is not this platform's, or that references a platform assembly, naming the package, the seam and both hashes.

Examples#

// model/warehouse.osy, in the Acme.Warehouse package
using Osysharp.Sources;

namespace Acme.Warehouse;

public native class WarehouseSource : IEntitySource {
  public string Account = "";
  public int TimeoutSeconds = 30;
  public const QueryFeatures Pushdown = QueryFeatures.All;
}

// in the app
using Acme.Warehouse;

app.DataSources = [ new WarehouseSource("Analytics") { Account = "acme" } ];