Class OrtEnv

The singleton class OrtEnv contains the process-global ONNX Runtime environment. It sets up logging, creates system wide thread-pools (if Thread Pool options are provided) and other necessary things for OnnxRuntime to function.

Create or access OrtEnv by calling the Instance() method. Instance() can be called multiple times. It would return the same instance.

CreateInstanceWithOptions() provides a way to create environment with options. It must be called once before Instance() is called, otherwise it would not have effect.

If the environment is not explicitly created, it will be created as needed, e.g., when creating a SessionOptions instance.

Inheritance

object

CriticalFinalizerObject

SafeHandle

OrtEnv

Implements

IDisposable

Inherited Members

SafeHandle.Close()

SafeHandle.DangerousAddRef(ref bool)

SafeHandle.DangerousGetHandle()

SafeHandle.DangerousRelease()

SafeHandle.Dispose()

SafeHandle.SetHandleAsInvalid()

SafeHandle.IsClosed

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Microsoft.ML.OnnxRuntime

Assembly: Microsoft.ML.OnnxRuntime.dll

Syntax

public sealed class OrtEnv : SafeHandle, IDisposable

Properties

DisableDllImportResolver

Set this to true before accessing any OnnxRuntime type to prevent OnnxRuntime from registering its own DllImportResolver via NativeLibrary.SetDllImportResolver. This is useful when the host application needs to register its own custom resolver for the OnnxRuntime assembly. Must be set before any OnnxRuntime API is used (i.e., before the internal NativeMethods static constructor runs).

Declaration

public static bool DisableDllImportResolver { get; set; }

Property Value

Type	Description
bool

Examples

// Disable OnnxRuntime's built-in resolver before any ORT usage
OrtEnv.DisableDllImportResolver = true;

// Register your own resolver
NativeLibrary.SetDllImportResolver(typeof(OrtEnv).Assembly, MyCustomResolver);

// Now use OnnxRuntime normally
var env = OrtEnv.Instance();

EnvLogLevel

Get/Set log level property of OrtEnv instance Default LogLevel.Warning

Declaration

public OrtLoggingLevel EnvLogLevel { get; set; }

Property Value

Type	Description
OrtLoggingLevel	env log level

IsCreated

Provides visibility if singleton already been instantiated

Declaration

public static bool IsCreated { get; }

Property Value

Type	Description
bool

IsInvalid

Overrides SafeHandle.IsInvalid

Declaration

public override bool IsInvalid { get; }

Property Value

Type	Description
bool	returns true if handle is equal to Zero

Overrides

SafeHandle.IsInvalid

Methods

CopyTensors(IReadOnlyList<OrtValue>, IReadOnlyList<OrtValue>, OrtSyncStream)

Copies data from source OrtValue tensors to destination OrtValue tensors. The tensors may reside on difference devices if such are supported by the registered execution providers.

Declaration

public void CopyTensors(IReadOnlyList<OrtValue> srcValues, IReadOnlyList<OrtValue> dstValues, OrtSyncStream stream)

Parameters

Type	Name	Description
IReadOnlyList<OrtValue>	srcValues	Source OrtValues
IReadOnlyList<OrtValue>	dstValues	pre-allocated OrtValues
OrtSyncStream	stream	optional stream or null

Exceptions

Type	Condition
ArgumentNullException

CreateAndRegisterAllocator(OrtMemoryInfo, OrtArenaCfg)

Create and register an allocator to the OrtEnv instance. This API enhance CreateAndRegisterAllocator that it can create an allocator with specific type, not just CPU allocator Enables sharing the allocator between multiple sessions that use the same env instance. Lifetime of the created allocator will be valid for the duration of the environment. so as to enable sharing across all sessions using the OrtEnv instance.

OrtMemoryInfo instance to be used for allocator creation OrtArenaCfg instance that will be used to define the behavior of the arena based allocator

Declaration

public void CreateAndRegisterAllocator(OrtMemoryInfo memInfo, OrtArenaCfg arenaCfg)

Parameters

Type	Name	Description
OrtMemoryInfo	memInfo
OrtArenaCfg	arenaCfg

CreateAndRegisterAllocator(string, OrtMemoryInfo, OrtArenaCfg, IReadOnlyDictionary<string, string>)

Create and register an allocator to the OrtEnv instance. Use UnregisterAllocator to unregister it.

Declaration

public void CreateAndRegisterAllocator(string providerType, OrtMemoryInfo memInfo, OrtArenaCfg arenaCfg, IReadOnlyDictionary<string, string> provider_options)

Parameters

Type	Name	Description
string	providerType
OrtMemoryInfo	memInfo
OrtArenaCfg	arenaCfg
IReadOnlyDictionary<string, string>	provider_options

CreateInstanceWithOptions(ref EnvironmentCreationOptions)

Provides a way to create an instance with options. It throws if the instance already exists and the specified options not have effect.

Declaration

public static OrtEnv CreateInstanceWithOptions(ref EnvironmentCreationOptions options)

Parameters

Type	Name	Description
EnvironmentCreationOptions	options

Returns

Type	Description
OrtEnv

Exceptions

Type	Condition
OnnxRuntimeException	if the singleton has already been created

CreateSharedAllocator(OrtEpDevice, OrtDeviceMemoryType, OrtAllocatorType, IReadOnlyDictionary<string, string>)

Creates shared allocator owned by the OrtEnv instance.

Declaration

public OrtAllocator CreateSharedAllocator(OrtEpDevice epDevice, OrtDeviceMemoryType deviceMemoryType, OrtAllocatorType ortAllocatorType, IReadOnlyDictionary<string, string> allocatorOptions)

Parameters

Type	Name	Description
OrtEpDevice	epDevice
OrtDeviceMemoryType	deviceMemoryType
OrtAllocatorType	ortAllocatorType
IReadOnlyDictionary<string, string>	allocatorOptions	allocator specific options

Returns

Type	Description
OrtAllocator	OrtAllocator instance

DisableTelemetryEvents()

Disable platform telemetry collection

Declaration

public void DisableTelemetryEvents()

EnableTelemetryEvents()

Enable platform telemetry collection where applicable (currently only official Windows ORT builds have telemetry collection capabilities)

Declaration

public void EnableTelemetryEvents()

GetAvailableProviders()

Queries all the execution providers supported in the native onnxruntime shared library

Declaration

public string[] GetAvailableProviders()

Returns

Type	Description
string[]	an array of strings that represent execution provider names

GetCompatibilityInfoFromModel(string, string)

Extract EP compatibility info from a precompiled model file.

Declaration

public string GetCompatibilityInfoFromModel(string modelPath, string epType)

Parameters

Type	Name	Description
string	modelPath	Path to the ONNX model file.
string	epType	The execution provider type string. Use EpName to get this value.

Returns

Type	Description
string	The compatibility info string, or null if no compatibility info exists for the specified EP.

Remarks

Parses the model file to extract the compatibility info string for a specific execution provider from the model's metadata properties. This is only applicable to models that have been precompiled for an EP. Standard ONNX models do not contain this information. The compatibility info can then be passed to GetModelCompatibilityForEpDevices(IReadOnlyList<OrtEpDevice>, string) to check if a precompiled model is compatible with the current system.

Exceptions

Type	Condition
ArgumentException	If modelPath or epType is null or empty.
OnnxRuntimeException	If the model file cannot be read or parsed.

GetCompatibilityInfoFromModelBytes(byte[], string)

Extract EP compatibility info from precompiled model bytes in memory.

Declaration

public string GetCompatibilityInfoFromModelBytes(byte[] modelData, string epType)

Parameters

Type	Name	Description
byte[]	modelData	The model data bytes.
string	epType	The execution provider type string. Use EpName to get this value.

Returns

Type	Description
string	The compatibility info string, or null if no compatibility info exists for the specified EP.

Remarks

Same as GetCompatibilityInfoFromModel(string, string) but reads from a memory buffer instead of a file. Useful when precompiled models are loaded from encrypted storage, network, or other non-file sources.

Exceptions

Type	Condition
ArgumentException	If modelData is null/empty or epType is null or empty.
OnnxRuntimeException	If the model data cannot be parsed.

GetEpDevices()

Get the list of all execution provider and device combinations that are available. These can be used to select the execution provider and device for a session.

Declaration

public IReadOnlyList<OrtEpDevice> GetEpDevices()

Returns

Type	Description
IReadOnlyList<OrtEpDevice>

GetModelCompatibilityForEpDevices(IReadOnlyList<OrtEpDevice>, string)

Validate a compiled model's compatibility information for one or more EP devices.

Declaration

public OrtCompiledModelCompatibility GetModelCompatibilityForEpDevices(IReadOnlyList<OrtEpDevice> epDevices, string compatibilityInfo)

Parameters

Type	Name	Description
IReadOnlyList<OrtEpDevice>	epDevices	The list of EP devices to validate against.
string	compatibilityInfo	The compatibility string from the precompiled model to validate.

Returns

Type	Description
OrtCompiledModelCompatibility	OrtCompiledModelCompatibility enum value denoting the compatibility status

GetSharedAllocator(OrtMemoryInfo)

Returns a shared allocator owned by the OrtEnv instance if such exists (was previously created). If no such allocator exists, the API returns null.

Declaration

public OrtAllocator GetSharedAllocator(OrtMemoryInfo memoryInfo)

Parameters

Type	Name	Description
OrtMemoryInfo	memoryInfo

Returns

Type	Description
OrtAllocator	OrtAllocator instance or null if the requested allocator does not exist

GetVersionString()

This function returns the onnxruntime version string

Declaration

public string GetVersionString()

Returns

Type	Description
string	version string

Instance()

Instantiates (if not already done so) a new OrtEnv instance with the default logging level and no other options. Otherwise returns the existing instance.

It returns the same instance on every call - OrtEnv is singleton

Declaration

public static OrtEnv Instance()

Returns

Type	Description
OrtEnv	Returns a singleton instance of OrtEnv that represents native OrtEnv object

RegisterExecutionProviderLibrary(string, string)

Register an execution provider library with the OrtEnv instance. A registered execution provider library can be used by all sessions created with the OrtEnv instance. Devices the execution provider can utilize are added to the values returned by GetEpDevices() and can be used in SessionOptions.AppendExecutionProvider to select an execution provider for a device.

Coming: A selection policy can be specified and ORT will automatically select the best execution providers and devices for the model.

Declaration

public void RegisterExecutionProviderLibrary(string registrationName, string libraryPath)

Parameters

Type	Name	Description
string	registrationName	The name to register the library under.
string	libraryPath	The path to the library to register.

ReleaseHandle()

Destroys native object

Declaration

protected override bool ReleaseHandle()

Returns

Type	Description
bool	always returns true

Overrides

SafeHandle.ReleaseHandle()

ReleaseSharedAllocator(OrtEpDevice, OrtDeviceMemoryType)

Release a shared allocator from the OrtEnv for the OrtEpDevice and memory type. This will release the shared allocator for the given OrtEpDevice and memory type. If no shared allocator exists, this is a no-op.

Declaration

public void ReleaseSharedAllocator(OrtEpDevice epDevice, OrtDeviceMemoryType deviceMemoryType)

Parameters

Type	Name	Description
OrtEpDevice	epDevice
OrtDeviceMemoryType	deviceMemoryType

UnregisterAllocator(OrtMemoryInfo)

Unregister a custom allocator previously registered with the OrtEnv instance using CreateAndRegisterAllocator The memory info instance should correspond the one that is used for registration

Declaration

public void UnregisterAllocator(OrtMemoryInfo memInfo)

Parameters

Type	Name	Description
OrtMemoryInfo	memInfo	The memory info instance should correspond the one that is used for registration

UnregisterExecutionProviderLibrary(string)

Unregister an execution provider library from the OrtEnv instance.

Declaration

public void UnregisterExecutionProviderLibrary(string registrationName)

Parameters

Type	Name	Description
string	registrationName	The name the library was registered under.

Implements

IDisposable