Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Rikitav/Unified.Firmware/llms.txt

Use this file to discover all available pages before exploring further.

FirmwareEnvironment is the core class for reading and writing UEFI NVRAM variables. Each instance is scoped to a specific vendor namespace (identified by a Guid) and a specific backend (an IFirmwareBackend implementation). The class provides generic methods that handle marshalling between managed types and raw UEFI variable memory automatically, covering scalar structs, Unicode strings, and struct arrays. The static Global property gives immediate access to the standard UEFI global namespace without constructing an instance manually. Namespace: Unified.Firmware

​
Constructor

public FirmwareEnvironment(IFirmwareBackend backend, Guid vendorGuid)
​
backend
IFirmwareBackend
required
The platform backend used to perform the low-level read and write operations. Typically FirmwareInterface.CurrentBackend, but any custom IFirmwareBackend implementation is accepted.
​
vendorGuid
Guid
required
The GUID that identifies the UEFI variable namespace (vendor) this environment is scoped to. Well-known GUIDs are available as constants in FirmwareVendors (for example, FirmwareVendors.GlobalVariable = 8BE4DF61-93CA-11D2-AA0D-00E098032B8C).

​
Static Properties

​
Global

Returns the shared GlobalFirmwareEnvironment instance, pre-configured for the UEFI global variable namespace (FirmwareVendors.GlobalVariable) and backed by FirmwareInterface.CurrentBackend. The instance is lazily created on first access and cached. Use this property to read or write standard UEFI variables such as BootOrder, SecureBoot, and Timeout without constructing a FirmwareEnvironment manually.
TypeGlobalFirmwareEnvironment
Accessstatic read-only
// Access standard global variables through the shared instance
GlobalFirmwareEnvironment global = FirmwareEnvironment.Global;
bool secureBoot = global.SecureBoot;
ushort timeout = global.Timeout;
See GlobalFirmwareEnvironment for the full list of available properties.

​
Instance Properties

​
Backend

The IFirmwareBackend implementation this environment delegates all read and write calls to.
TypeIFirmwareBackend
Accessread-only

​
VendorGuid

The vendor GUID that identifies the UEFI variable namespace for this environment. All variable names passed to the read and write methods are resolved within this namespace.
TypeGuid
Accessread-only

​
Methods

​
ReadVariable<T>

Reads a single UEFI variable and marshals its raw bytes to a value type T. The buffer size is derived from Marshal.SizeOf<T>(). 
public T ReadVariable<T>(string varName, out VariableAttributes attributes)
    where T : struct
​
varName
string
required
The name of the UEFI variable to read. Must not be null or empty.
​
attributes
VariableAttributes
required
Output parameter. When the method returns, contains the VariableAttributes flags stored alongside the variable (for example, NON_VOLATILE | BOOTSERVICE_ACCESS | RUNTIME_ACCESS).
Returns: T — the variable value, unmarshalled from raw UEFI memory. 
using Unified.Firmware;

FirmwareEnvironment env = new FirmwareEnvironment(
    FirmwareInterface.CurrentBackend,
    FirmwareVendors.GlobalVariable);

ushort bootCurrent = env.ReadVariable<ushort>("BootCurrent", out VariableAttributes attrs);
Console.WriteLine($"BootCurrent = {bootCurrent}, Attributes = {attrs}");

​
WriteVariable<T>

Marshals a value type T to raw bytes and writes it to NVRAM as a UEFI variable. 
public void WriteVariable<T>(string varName, T value, VariableAttributes attributes)
    where T : struct
​
varName
string
required
The name of the UEFI variable to write. Must not be null or empty.
​
value
T
required
The value to store. The method allocates unmanaged memory, copies the struct into it, calls the backend, then frees the buffer — callers do not manage memory.
​
attributes
VariableAttributes
required
The attributes to associate with the variable, such as NON_VOLATILE | BOOTSERVICE_ACCESS | RUNTIME_ACCESS.
ushort newTimeout = 10;
env.WriteVariable(
    "Timeout",
    newTimeout,
    VariableAttributes.NON_VOLATILE |
    VariableAttributes.BOOTSERVICE_ACCESS |
    VariableAttributes.RUNTIME_ACCESS);

​
ReadStringVariable

Reads a UEFI variable whose value is a null-terminated UTF-16 Unicode string. Internally allocates a 2 KB buffer, reads the variable, converts the pointer to a managed string via Marshal.PtrToStringUni, and frees the buffer. 
public string ReadStringVariable(string varName, out VariableAttributes attributes)
​
varName
string
required
The name of the UEFI variable to read.
​
attributes
VariableAttributes
required
Output parameter. Receives the attributes of the variable on return.
Returns: string — the variable value, or null if the variable does not exist. 
string lang = env.ReadStringVariable("PlatformLang", out VariableAttributes attrs);
Console.WriteLine($"PlatformLang = {lang}");  // e.g. "en-US"

​
WriteStringVariable

Encodes a managed string as UTF-16 Unicode and writes it to NVRAM as a UEFI string variable. 
public void WriteStringVariable(string varName, string value, VariableAttributes attributes)
​
varName
string
required
The name of the UEFI variable to write.
​
value
string
required
The string value to store. The method converts it to a global Unicode pointer, writes the variable, then frees the pointer.
​
attributes
VariableAttributes
required
The attributes to store with the variable.
env.WriteStringVariable(
    "PlatformLang",
    "en-US",
    VariableAttributes.NON_VOLATILE |
    VariableAttributes.BOOTSERVICE_ACCESS |
    VariableAttributes.RUNTIME_ACCESS);

​
ReadArrayVariable<T>

Reads a UEFI variable whose value is an array of value type T elements. The method allocates a buffer of Marshal.SizeOf<T>() * 256 bytes, reads the variable, derives the element count from the returned dataSize, and returns a managed T[]. 
public T[] ReadArrayVariable<T>(string varName, out VariableAttributes attributes)
    where T : struct
​
varName
string
required
The name of the UEFI variable to read.
​
attributes
VariableAttributes
required
Output parameter. Receives the attributes of the variable on return.
Returns: T[] — the array of values stored in the variable. Returns an empty array if the variable contains no data. 
ushort[] bootOrder = env.ReadArrayVariable<ushort>("BootOrder", out _);
Console.WriteLine("Boot order:");
foreach (ushort entry in bootOrder)
    Console.WriteLine($"  Boot{entry:X4}");

​
WriteArrayVariable<T>

Writes a T[] array to NVRAM as a UEFI variable. The method pins the array in memory and passes a pointer to the backend — no intermediate copy is made. 
public void WriteArrayVariable<T>(string varName, T[] value, VariableAttributes attributes)
    where T : struct
​
varName
string
required
The name of the UEFI variable to write.
​
value
T[]
required
The array to write. Must not be null and must contain at least one element.
​
attributes
VariableAttributes
required
The attributes to store with the variable.
// Re-order boot entries (place Boot0003 first)
ushort[] newOrder = new ushort[] { 0x0003, 0x0001, 0x0002 };
env.WriteArrayVariable(
    "BootOrder",
    newOrder,
    VariableAttributes.NON_VOLATILE |
    VariableAttributes.BOOTSERVICE_ACCESS |
    VariableAttributes.RUNTIME_ACCESS);

​
FirmwareEnvironmentException

FirmwareEnvironmentException is the library’s dedicated exception type for UEFI variable access errors. It inherits from System.Exception and is thrown by backend implementations when a read or write operation fails at the platform layer (for example, a Win32 API error or a missing /sys/firmware/efi/efivars entry). 
public class FirmwareEnvironmentException : Exception
Constructors:
ConstructorDescription
FirmwareEnvironmentException()Initialises with an empty message and no inner exception.
FirmwareEnvironmentException(string message)Initialises with the specified error message.
FirmwareEnvironmentException(string message, Exception? innerException)Initialises with a message and an inner exception that caused this error.
try
{
    ushort[] bootOrder = FirmwareEnvironment.Global.BootOrder;
}
catch (FirmwareEnvironmentException ex)
{
    Console.WriteLine($"UEFI variable access failed: {ex.Message}");
    if (ex.InnerException is not null)
        Console.WriteLine($"Caused by: {ex.InnerException.Message}");
}

​
Custom Vendor Namespace Example

Use a custom Guid to scope an environment to a specific OEM or application namespace: 
using System;
using Unified.Firmware;
using Unified.Firmware.EnvironmentVendor;

// Read a Dell-specific UEFI variable
var dellEnv = new FirmwareEnvironment(
    FirmwareInterface.CurrentBackend,
    FirmwareVendors.DellVendor);

// Read a hypothetical Dell custom variable as a raw uint
uint dellSetting = dellEnv.ReadVariable<uint>("DellCustomSetting", out VariableAttributes attrs);
Console.WriteLine($"DellCustomSetting = 0x{dellSetting:X8}, Attributes = {attrs}");

// Use a completely custom GUID for a proprietary namespace
Guid myAppGuid = new Guid("aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee");
var appEnv = new FirmwareEnvironment(FirmwareInterface.CurrentBackend, myAppGuid);

appEnv.WriteStringVariable(
    "MyAppConfig",
    "version=2;debug=false",
    VariableAttributes.NON_VOLATILE |
    VariableAttributes.BOOTSERVICE_ACCESS |
    VariableAttributes.RUNTIME_ACCESS);

string readBack = appEnv.ReadStringVariable("MyAppConfig", out _);
Console.WriteLine($"MyAppConfig = {readBack}");
The FirmwareVendors static class contains ready-made Guid constants for well-known namespaces: GlobalVariable, ImageSecurityDatabase, HardwareErrorVariable, MicrosoftVendor, LenovoVendor, DellVendor, HpVendor, AsusVendor, and AppleVendor.

Build docs developers (and LLMs) love

Get started for freeTalk to us