# openbytedev/netcorehost architecture

> Architecture diagram of the GitHub repository openbytedev/netcorehost, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openbytedev/netcorehost
- Repository: https://github.com/openbytedev/netcorehost

## Overview

##### Project Type & Purpose
- This is an open-source Rust library (“crate”) that provides a high-level host for the .NET Core runtime.
- It exposes a Rust API to locate, load, and drive the .NET Core runtime (hostfxr/nethost), and call into managed assemblies.

##### Major Components
a. Consumer (your native host application)
b. netcorehost Rust crate
- High-level API (lib.rs)
- Modules:
– nethost (src/nethost.rs)
– hostfxr (src/hostfxr/*.rs)
– pdcstring (src/pdcstring/*.rs)
– error handling (src/error/*.rs)
- Sys-bindings (src/bindings/mod.rs)
c. Native hosting libraries (externals)
- nethost (nethost library from .NET Core installation or downloaded via feature)
- hostfxr (hostfxr library versions 1.0,2.1,3.0,6.0)
d. .NET Core Runtime
e. Managed code (C# assemblies)
- Test and example projects under `/examples` and `/tests`
f. Optional external service
- NuGet (for automatic download-nethost feature)

##### Relationships & Data Flows
1. Consumer → call into netcorehost’s public API (e.g., `load_hostfxr()`)
2. netcorehost/nethost module → FFI into nethost library to locate hostfxr
3. netcorehost/hostfxr module → dynamically load hostfxr library and invoke `hostfxr_initialize_for_*`
4. hostfxr → (.NET Core runtime loader) → set up runtime context
5. netcorehost/hostfxr context → run apps or get delegate loader
6. Delegate loader → load managed assembly → resolve function pointer
7. Consumer → invoke managed function → execution in .NET runtime → result back to Rust

##### Key Architectural Patterns & Principles
- Facade Pattern: `netcorehost` exposes a simplified Rust API over complex native hosting APIs
- Layered Abstraction:
- High-level Rust modules
- Sys-bindings (unsafe FFI)
- Native hosting libraries (nethost/hostfxr)
- .NET runtime and managed assemblies
- Separation of Concerns: string management (pdcstring), error handling, hosting logic, delegate loading

##### Minimum Elements
- Consumer application
- netcorehost public API (lib.rs)
- Modules: nethost, hostfxr, pdcstring, error, bindings
- Native libraries: nethost, hostfxr (multiple versions)
- .NET Core runtime
- Managed assemblies (ExampleProject/Test)
- Notes on optional features (download-nethost, runtimeconfig.json generation)

[Consumer App]
↓ calls
[netcorehost API (lib.rs)]
→ uses → [pdcstring]
→ uses → [error module]
→ uses → [bindings (src/bindings)]
↓ FFI calls
[nethost library] ─ locates ─> [hostfxr library] ─ boots ─> [.NET Core runtime]
│                                        ↓ executes
└──────────── delegates loader ────────> [Managed Assembly (ExampleProject.dll)]
↑ callback
function pointer

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Consumer Application"
        Consumer["Consumer App"]:::consumer
    end

    Consumer -->|"load_hostfxr()"| Netcore["netcorehost Public API (lib.rs)"]:::rust
    click Netcore "https://github.com/openbytedev/netcorehost/blob/master/src/lib.rs"

    subgraph "netcorehost Crate (Rust Modules)"
        Netcore --> Pdc["pdcstring"]:::rust
        click Pdc "https://github.com/openbytedev/netcorehost/blob/master/src/pdcstring/mod.rs"
        Pdc --> PdcShared["shared"]:::rust
        click PdcShared "https://github.com/openbytedev/netcorehost/blob/master/src/pdcstring/shared.rs"
        Pdc --> PdcImplWin["impl/windows"]:::rust
        click PdcImplWin "https://github.com/openbytedev/netcorehost/blob/master/src/pdcstring/impl/windows/mod.rs"
        Pdc --> PdcImplOther["impl/other"]:::rust
        click PdcImplOther "https://github.com/openbytedev/netcorehost/blob/master/src/pdcstring/impl/other/mod.rs"
        Pdc --> Traits["traits"]:::rust
        click Traits "https://github.com/openbytedev/netcorehost/blob/master/src/pdcstring/impl/traits.rs"

        Netcore --> Error["error"]:::rust
        click Error "https://github.com/openbytedev/netcorehost/blob/master/src/error/mod.rs"
        Error --> HostRes["hosting_result"]:::rust
        click HostRes "https://github.com/openbytedev/netcorehost/blob/master/src/error/hosting_result.rs"
        Error --> UnivErr["univ"]:::rust
        click UnivErr "https://github.com/openbytedev/netcorehost/blob/master/src/error/univ.rs"

        Netcore --> Bindings["bindings (FFI)"]:::ffi
        click Bindings "https://github.com/openbytedev/netcorehost/blob/master/src/bindings/mod.rs"

        Netcore --> NethostMod["nethost"]:::rust
        click NethostMod "https://github.com/openbytedev/netcorehost/blob/master/src/nethost.rs"

        subgraph "hostfxr Module"
            HFMod["mod.rs"]:::rust
            click HFMod "https://github.com/openbytedev/netcorehost/blob/master/src/hostfxr/mod.rs"
            HFMod --> Context["context"]:::rust
            click Context "https://github.com/openbytedev/netcorehost/blob/master/src/hostfxr/context.rs"
            HFMod --> Delegate["delegate_loader"]:::rust
            click Delegate "https://github.com/openbytedev/netcorehost/blob/master/src/hostfxr/delegate_loader.rs"
            HFMod --> Library["library"]:::rust
            click Library "https://github.com/openbytedev/netcorehost/blob/master/src/hostfxr/library.rs"
            HFMod --> Lib10["library1_0"]:::rust
            click Lib10 "https://github.com/openbytedev/netcorehost/blob/master/src/hostfxr/library1_0.rs"
            HFMod --> Lib21["library2_1"]:::rust
            click Lib21 "https://github.com/openbytedev/netcorehost/blob/master/src/hostfxr/library2_1.rs"
            HFMod --> Lib30["library3_0"]:::rust
            click Lib30 "https://github.com/openbytedev/netcorehost/blob/master/src/hostfxr/library3_0.rs"
            HFMod --> Lib60["library6_0"]:::rust
            click Lib60 "https://github.com/openbytedev/netcorehost/blob/master/src/hostfxr/library6_0.rs"
            HFMod --> ManageFn["managed_function"]:::rust
            click ManageFn "https://github.com/openbytedev/netcorehost/blob/master/src/hostfxr/managed_function.rs"
            HFMod --> RunProps["runtime_property"]:::rust
            click RunProps "https://github.com/openbytedev/netcorehost/blob/master/src/hostfxr/runtime_property.rs"
        end
        Netcore --> HFMod
    end

    Bindings -->|"extern load_nethost()"| NethostLib["nethost library"]:::native
    NethostLib -->|"locate hostfxr"| HostfxrLib["hostfxr library"]:::native
    HostfxrLib -->|"hostfxr_initialize_for_dotnet()"| Runtime[".NET Core Runtime"]:::managed

    Runtime -->|"execute delegate"| ManageAsm["Managed Assembly (ExampleProject)"]:::managed
    click ManageAsm "https://github.com/openbytedev/netcorehost/blob/master/examples/*/ExampleProject/Program.cs"
    ManageAsm -->|"fn ptr callback"| Delegate

    subgraph "Examples (Rust Consumers)"
        EX1["call-managed-function"]:::consumer
        click EX1 "https://github.com/openbytedev/netcorehost/blob/master/examples/call-managed-function/main.rs"
        EX2["passing-parameters"]:::consumer
        click EX2 "https://github.com/openbytedev/netcorehost/blob/master/examples/passing-parameters/main.rs"
        EX3["return-string-from-managed"]:::consumer
        click EX3 "https://github.com/openbytedev/netcorehost/blob/master/examples/return-string-from-managed/main.rs"
        EX4["run-app-with-args"]:::consumer
        click EX4 "https://github.com/openbytedev/netcorehost/blob/master/examples/run-app-with-args/main.rs"
        EX5["run-app"]:::consumer
        click EX5 "https://github.com/openbytedev/netcorehost/blob/master/examples/run-app/main.rs"
    end
    Consumer --> EX1
    Consumer --> EX2
    Consumer --> EX3
    Consumer --> EX4
    Consumer --> EX5

    classDef rust fill:#ADD8E6,stroke:#000;
    classDef ffi fill:#FFA500,stroke:#000;
    classDef native fill:#90EE90,stroke:#000;
    classDef managed fill:#D8BFD8,stroke:#000;
    classDef consumer fill:#87CEEB,stroke:#000;
```
