# native class — a provider implemented in .NET

> 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.

<!-- id: class-native · area: class · stability: preview · html: https://osysharp.com/reference/class/native/ -->

## Summary        {#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      {#signature}
```osy syntax
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    {#description}

### What it declares   {#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   {#package}
Only in a package, because only a package ships an assembly. The manifest names it with the `native` role:

```osy syntax
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](https://osysharp.com/reference/local/generating-a-seam/).

### What is refused   {#refusals}
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   {#running}
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](https://osysharp.com/reference/local/generating-a-seam/)) 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       {#examples}
```osy title="a package's native data source, and the app registering it" preview
// 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" } ];
```

## See also       {#see-also}
- [Interfaces — a contract several types can satisfy](https://osysharp.com/reference/class/interfaces/) — the contract a native class implements
- [package.osy](https://osysharp.com/reference/project/package/) — the manifest, and its `native` role
- [Generating the C# a native provider implements](https://osysharp.com/reference/local/generating-a-seam/) — the C# an assembly is built against