Add APIs OrtApi::CreateEnvWithOptions() and OrtEpApi::GetEnvConfigEntries()
#26971
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
adrianlizarraga
changed the title
OrtApi::CreateEnvWithConfig() and OrtEpApi::GetEnvConfigEntries()OrtApi::CreateEnvWithOptions() and OrtEpApi::GetEnvConfigEntries()
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request adds two new APIs to ONNX Runtime for improved environment configuration handling, particularly for execution provider (EP) libraries:
-
OrtApi::CreateEnvWithOptions()- A new C API function that creates an OrtEnv instance with comprehensive configuration options including logging, threading, and environment-level config entries. -
OrtEpApi::GetEnvConfigEntries()- A new EP API function that allows EP libraries to retrieve environment configuration entries that were set during environment creation.
The PR also removes the OrtEpFactory::SetEnvironmentOptions() callback in favor of the new approach where config entries are passed during environment creation and retrieved as needed by EP libraries.
Changes:
- Introduced
OrtEnvCreationOptionsstruct to encapsulate all environment creation parameters - Added
CreateEnvWithOptions()API and corresponding C++ wrapper constructors - Added
GetEnvConfigEntries()EP API for retrieving environment config entries - Removed
SetEnvironmentOptions()fromOrtEpFactoryinterface (breaking change) - Renamed
OrtEnv::GetInstance()toOrtEnv::GetOrCreateInstance()for clarity - Added
OrtEnv::TryGetInstance()for retrieving existing instance without creating - Updated example plugin EP and tests to demonstrate new pattern
Reviewed changes
Copilot reviewed 27 out of 27 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
include/onnxruntime/core/session/onnxruntime_c_api.h |
Added OrtEnvCreationOptions struct and CreateEnvWithOptions() API |
include/onnxruntime/core/session/onnxruntime_ep_c_api.h |
Added GetEnvConfigEntries() to OrtEpApi, removed SetEnvironmentOptions() from OrtEpFactory |
include/onnxruntime/core/session/onnxruntime_env_config_keys.h |
New header defining well-known environment config keys |
include/onnxruntime/core/session/onnxruntime_cxx_api.h |
Added C++ constructor for Env using OrtEnvCreationOptions |
onnxruntime/core/session/ort_env.h/.cc |
Renamed GetInstance() to GetOrCreateInstance(), added TryGetInstance() and config entry support |
onnxruntime/core/session/environment.h/.cc |
Added config entry storage and retrieval, updated EP library registration to set virtual device flags |
onnxruntime/core/session/onnxruntime_c_api.cc |
Implemented CreateEnvWithOptions() with validation |
onnxruntime/core/session/plugin_ep/ep_api.cc |
Implemented GetEnvConfigEntries() EP API |
onnxruntime/core/session/plugin_ep/*.h/.cc |
Removed SetEnvironmentOptions from factory interfaces |
onnxruntime/test/shared_lib/test_env_creation.cc |
New test file for CreateEnvWithOptions() API |
onnxruntime/test/autoep/test_registration.cc |
Updated tests to use new config approach |
onnxruntime/test/autoep/library/example_plugin_ep_virt_gpu/* |
Updated example plugin to retrieve config via GetEnvConfigEntries() |
onnxruntime/python/*.cc and orttraining/orttraining/python/*.cc |
Updated Python bindings to use GetOrCreateInstance() |
cmake/*.cmake |
Added new test file and header to build |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
edgchen1
reviewed
Jan 12, 2026
edgchen1
reviewed
Jan 12, 2026
…vironment-level vs session-level config entries for EPs
skottmckay
reviewed
Jan 12, 2026
edgchen1
reviewed
Jan 12, 2026
edgchen1
reviewed
Jan 13, 2026
skottmckay
previously approved these changes
Jan 13, 2026
edgchen1
reviewed
Jan 13, 2026
edgchen1
previously approved these changes
Jan 13, 2026
adrianlizarraga
dismissed stale reviews from edgchen1 and skottmckay
via
d5247e1
skottmckay
previously approved these changes
Jan 14, 2026
edgchen1
previously approved these changes
Jan 14, 2026
adrianlizarraga
dismissed stale reviews from skottmckay and edgchen1
via
2839c10
edgchen1
approved these changes
Jan 14, 2026
alex-spacemit
pushed a commit
to spacemit-com/onnxruntime
that referenced
this pull request
Jan 20, 2026
…Entries()` (microsoft#26971) ### Description - Adds API `CreateEnvWithOptions` that allows the user to pass in a `OrtEnvCreationOptions` struct that aggregates all env creation options (log id, logging level, custom logger, thread pool options, etc.). - The new `OrtEnvCreationOptions` struct also allows the application to provide an `OrtKeyValuePairs` containing general configuration entries. - Adds EP API `GetEnvConfigEntries` that returns the environment's configuration entries as a `OrtKeyValuePairs` instance. - Remove `OrtEpFactory::SetEnvironmentOptions` and update example EP to pull the necessary configuration entry via the new api `GetEnvConfigEntries`. ### Motivation and Context <!-- - Why is this change required? What problem does it solve? - If it fixes an open issue, please link to the issue here. -->
nieubank
added a commit
that referenced
this pull request
Jan 20, 2026
Fixes multiple Doxygen errors introduced by recent API additions that cause the nightly documentation build to fail with WARN_AS_ERROR=YES. Root causes by PR: PR #26828 (c54be3c - OrtExternalResourceImporter API for D3D12): - Incorrect \param names for ORT_CLASS_RELEASE macros: the macro expands to use 'input' as the parameter name, but docs used 'importer' and 'handle' PR #26927 (1ed8fd9 - Control flow kernels API): - Used ::CreateLoopKernel() and ::CreateScanKernel() syntax which Doxygen cannot resolve as links PR #26971 (3874516 - CreateEnvWithOptions API): - Used ::SetSessionLogSeverityLevel() and ::RunOptionsSetRunLogSeverityLevel() syntax which Doxygen cannot resolve - Used <ep_name> in documentation which Doxygen interprets as HTML tag - Used incorrect \param[out] name 'out' instead of 'config_entries' Fixes: - Qualify method references with struct name (e.g., OrtApi::Method) - Escape angle brackets as \<ep_name\> - Use 'input' as param name for ORT_CLASS_RELEASE documentation - Use actual param name 'config_entries' for GetEnvConfigEntries Verified locally with Doxygen 1.9.8 (matches CI configuration).
yuslepukhin
pushed a commit
that referenced
this pull request
Jan 21, 2026
# Fix Doxygen documentation build errors from recent PRs Fixes multiple Doxygen errors introduced by recent API additions that cause the nightly documentation build to fail (`WARN_AS_ERROR=YES`). ## Root Cause Analysis | Error | File | Line | Introduced By | Commit | Fix | |-------|------|------|---------------|--------|-----| | Duplicate `\addtogroup Global` | onnxruntime_c_api.h | 973 | PR #26828 - OrtExternalResourceImporter API | c54be3c | Remove redundant group markers | | Unresolved `::SetSessionLogSeverityLevel()` | onnxruntime_c_api.h | 1065 | PR #26971 - CreateEnvWithOptions API | 3874516 | Use `OrtApi::SetSessionLogSeverityLevel` | | Unresolved `::RunOptionsSetRunLogSeverityLevel()` | onnxruntime_c_api.h | 1066 | PR #26971 - CreateEnvWithOptions API | 3874516 | Use `OrtApi::RunOptionsSetRunLogSeverityLevel` | | `<ep_name>` interpreted as HTML | onnxruntime_c_api.h | 1119 | PR #26971 - CreateEnvWithOptions API | 3874516 | Escape as `\<ep_name\>` | | `\param[in] importer` not found | onnxruntime_c_api.h | 7982 | PR #26828 - OrtExternalResourceImporter API | c54be3c | Use `\param[in] input` (macro expands to `input`) | | `\param[in] handle` not found | onnxruntime_c_api.h | 8025 | PR #26828 - OrtExternalResourceImporter API | c54be3c | Use `\param[in] input` | | `\param[in] handle` not found | onnxruntime_c_api.h | 8091 | PR #26828 - OrtExternalResourceImporter API | c54be3c | Use `\param[in] input` | | Unresolved `::CreateLoopKernel()` | onnxruntime_ep_c_api.h | 667 | PR #26927 - Control flow kernels API | 1ed8fd9 | Use `OrtEpApi::CreateLoopKernel` | | Unresolved `::CreateScanKernel()` | onnxruntime_ep_c_api.h | 710 | PR #26927 - Control flow kernels API | 1ed8fd9 | Use `OrtEpApi::CreateScanKernel` | | `<ep_name>` interpreted as HTML | onnxruntime_ep_c_api.h | 1434 | PR #26971 - CreateEnvWithOptions API | 3874516 | Escape as `\<ep_name\>` | | `\param[out] out` not found | onnxruntime_ep_c_api.h | 1440 | PR #26971 - CreateEnvWithOptions API | 3874516 | Use `\param[out] config_entries` | ## Summary by PR | PR | Issues | |----|--------| | **#26828** (c54be3c) - OrtExternalResourceImporter API for D3D12 | Duplicate Doxygen group, incorrect `\param` names for `ORT_CLASS_RELEASE` macros | | **#26927** (1ed8fd9) - Control flow kernels API | `::Method()` syntax unresolvable by Doxygen | | **#26971** (3874516) - CreateEnvWithOptions API | `::Method()` syntax, `<ep_name>` HTML interpretation, incorrect param name | ## Technical Details ### `ORT_CLASS_RELEASE` Macro Issue The `ORT_CLASS_RELEASE(X)` macro at line 164 expands to: ```cpp void(ORT_API_CALL * Release##X)(_Frees_ptr_opt_ Ort##X * input) ``` The parameter is always named `input`, but the documentation in PR #26828 used semantic names like `importer` and `handle`. Doxygen validates `\param` names against actual parameter names in the expanded code. ### Doxygen Link Resolution Doxygen 1.9.8 cannot resolve `::MethodName()` as a link to a method. The correct syntax is to qualify with the struct name: `OrtApi::MethodName`. ## Testing Verified locally with Doxygen 1.9.8 (matches CI configuration).
tianleiwu
pushed a commit
that referenced
this pull request
Jan 21, 2026
# Fix Doxygen documentation build errors from recent PRs Fixes multiple Doxygen errors introduced by recent API additions that cause the nightly documentation build to fail (`WARN_AS_ERROR=YES`). ## Root Cause Analysis | Error | File | Line | Introduced By | Commit | Fix | |-------|------|------|---------------|--------|-----| | Duplicate `\addtogroup Global` | onnxruntime_c_api.h | 973 | PR #26828 - OrtExternalResourceImporter API | c54be3c | Remove redundant group markers | | Unresolved `::SetSessionLogSeverityLevel()` | onnxruntime_c_api.h | 1065 | PR #26971 - CreateEnvWithOptions API | 3874516 | Use `OrtApi::SetSessionLogSeverityLevel` | | Unresolved `::RunOptionsSetRunLogSeverityLevel()` | onnxruntime_c_api.h | 1066 | PR #26971 - CreateEnvWithOptions API | 3874516 | Use `OrtApi::RunOptionsSetRunLogSeverityLevel` | | `<ep_name>` interpreted as HTML | onnxruntime_c_api.h | 1119 | PR #26971 - CreateEnvWithOptions API | 3874516 | Escape as `\<ep_name\>` | | `\param[in] importer` not found | onnxruntime_c_api.h | 7982 | PR #26828 - OrtExternalResourceImporter API | c54be3c | Use `\param[in] input` (macro expands to `input`) | | `\param[in] handle` not found | onnxruntime_c_api.h | 8025 | PR #26828 - OrtExternalResourceImporter API | c54be3c | Use `\param[in] input` | | `\param[in] handle` not found | onnxruntime_c_api.h | 8091 | PR #26828 - OrtExternalResourceImporter API | c54be3c | Use `\param[in] input` | | Unresolved `::CreateLoopKernel()` | onnxruntime_ep_c_api.h | 667 | PR #26927 - Control flow kernels API | 1ed8fd9 | Use `OrtEpApi::CreateLoopKernel` | | Unresolved `::CreateScanKernel()` | onnxruntime_ep_c_api.h | 710 | PR #26927 - Control flow kernels API | 1ed8fd9 | Use `OrtEpApi::CreateScanKernel` | | `<ep_name>` interpreted as HTML | onnxruntime_ep_c_api.h | 1434 | PR #26971 - CreateEnvWithOptions API | 3874516 | Escape as `\<ep_name\>` | | `\param[out] out` not found | onnxruntime_ep_c_api.h | 1440 | PR #26971 - CreateEnvWithOptions API | 3874516 | Use `\param[out] config_entries` | ## Summary by PR | PR | Issues | |----|--------| | **#26828** (c54be3c) - OrtExternalResourceImporter API for D3D12 | Duplicate Doxygen group, incorrect `\param` names for `ORT_CLASS_RELEASE` macros | | **#26927** (1ed8fd9) - Control flow kernels API | `::Method()` syntax unresolvable by Doxygen | | **#26971** (3874516) - CreateEnvWithOptions API | `::Method()` syntax, `<ep_name>` HTML interpretation, incorrect param name | ## Technical Details ### `ORT_CLASS_RELEASE` Macro Issue The `ORT_CLASS_RELEASE(X)` macro at line 164 expands to: ```cpp void(ORT_API_CALL * Release##X)(_Frees_ptr_opt_ Ort##X * input) ``` The parameter is always named `input`, but the documentation in PR #26828 used semantic names like `importer` and `handle`. Doxygen validates `\param` names against actual parameter names in the expanded code. ### Doxygen Link Resolution Doxygen 1.9.8 cannot resolve `::MethodName()` as a link to a method. The correct syntax is to qualify with the struct name: `OrtApi::MethodName`. ## Testing Verified locally with Doxygen 1.9.8 (matches CI configuration). (cherry picked from commit 39f966e)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
CreateEnvWithOptionsthat allows the user to pass in aOrtEnvCreationOptionsstruct that aggregates all env creation options (log id, logging level, custom logger, thread pool options, etc.).OrtEnvCreationOptionsstruct also allows the application to provide anOrtKeyValuePairscontaining general configuration entries.GetEnvConfigEntriesthat returns the environment's configuration entries as aOrtKeyValuePairsinstance.OrtEpFactory::SetEnvironmentOptionsand update example EP to pull the necessary configuration entry via the new apiGetEnvConfigEntries.Motivation and Context