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.

FirmwareBootService is the primary entry point in the Unified.Firmware.BootService package for interacting with your system’s UEFI NVRAM. It exposes static properties that mirror the BootCurrent, BootNext, and BootOrder global EFI variables, and static methods for every operation you need: listing all boot entries, reading a single entry by index, creating a new entry, updating or editing one in-place, and deleting one along with its BootOrder reference.
All write operations — CreateLoadOption, UpdateLoadOption, EditLoadOption, and DeleteLoadOption — commit data directly to UEFI NVRAM. NVRAM writes are persistent across reboots and survive power loss. Test on non-production hardware, keep backups of your BootOrder, and ensure your process has the required firmware-access privileges before calling any mutating method.

​
Namespace

namespace Unified.Firmware.BootService;

​
Static Properties

​
CurrentLoadOptionIndex
BootOptionIndex
Gets the index of the Boot#### variable this machine was booted from, read from the BootCurrent EFI global variable. Use the returned value as an argument to any method that accepts a BootOptionIndex.Access: get-only
​
NextLoadOptionIndex
BootOptionIndex
Sets the BootNext EFI global variable, which causes the firmware to load the specified boot entry exactly once on the next reboot, after which the normal BootOrder is restored.Access: set-only
​
LoadOrder
BootOptionIndex[]
Gets or sets the full BootOrder EFI global variable as an array of BootOptionIndex values. The firmware processes entries in array order during startup. Assigning a new array replaces BootOrder in NVRAM.Access: get / set

​
Static Methods

​
EnumerateBootOptions

public static IEnumerable<FirmwareBootOption> EnumerateBootOptions()
Iterates over all Boot#### entries in the current boot order, reading each one from NVRAM and deserializing it as a FirmwareBootOption. Parameters: none Returns: IEnumerable<FirmwareBootOption> — a lazy sequence of boot options in boot-order sequence. Exceptions: none specific to this method; underlying firmware access may raise platform I/O exceptions. 
// Print every boot entry in order
int index = 0;
foreach (FirmwareBootOption bootOption in FirmwareBootService.EnumerateBootOptions())
{
    Console.WriteLine("\n===[ Boot option #" + index++ + " ]" + new string('=', 60));
    Console.WriteLine("Option name : \"{0}\"", bootOption.Description);
    Console.WriteLine("Attributes  : {0}", bootOption.Attributes);

    foreach (DevicePathProtocolBase protocol in bootOption.Protocols)
        Console.WriteLine(protocol.ToString());
}

​
EnumrateBootOptions<T>

public static IEnumerable<T> EnumrateBootOptions<T>()
    where T : LoadOptionBase, new()
Typed variant of EnumerateBootOptions. Each Boot#### entry is deserialized into an instance of T rather than FirmwareBootOption. Use this when you have a custom LoadOptionBase subclass that adds domain-specific properties.
The method name EnumrateBootOptions contains a typo (missing the second e in Enumerate). This is the actual name in the API — use it exactly as written.
Type Parameters
​
T
LoadOptionBase (new())
The concrete load-option type to deserialize each boot entry as. Must inherit LoadOptionBase and have a public parameterless constructor.
Returns: IEnumerable<T> — a lazy sequence of T instances in boot-order sequence. 
foreach (MyBootOption option in FirmwareBootService.EnumrateBootOptions<MyBootOption>())
{
    Console.WriteLine(option.Description);
}

​
EnumrateRawBootOptions

public static IEnumerable<EFI_LOAD_OPTION> EnumrateRawBootOptions()
Returns each Boot#### entry in boot order as an EFI_LOAD_OPTION native structure without any managed-type conversion. Useful for low-level inspection or when you need to access fields not surfaced by LoadOptionBase.
The method name EnumrateRawBootOptions contains a typo (missing the second e in Enumerate). This is the actual name in the API — use it exactly as written.
Parameters: none Returns: IEnumerable<EFI_LOAD_OPTION> — a lazy sequence of raw native structures in boot-order sequence. 
foreach (EFI_LOAD_OPTION raw in FirmwareBootService.EnumrateRawBootOptions())
{
    Console.WriteLine("Raw attributes: 0x{0:X8}", (uint)raw.Attributes);
}

​
ReadLoadOption(BootOptionIndex)

public static FirmwareBootOption ReadLoadOption(BootOptionIndex bootOptionIndex)
Reads a single Boot#### NVRAM variable and deserializes it as a FirmwareBootOption. Parameters
​
bootOptionIndex
BootOptionIndex
required
The index of the Boot#### variable to read. A ushort literal is implicitly converted — e.g. 0x0003 targets Boot0003.
Returns: FirmwareBootOption — the deserialized boot entry. 
// Read Boot0003
FirmwareBootOption bootOption = FirmwareBootService.ReadLoadOption(0x0003);

Console.WriteLine("Option name : \"{0}\"", bootOption.Description);
Console.WriteLine("Attributes  : {0}", bootOption.Attributes);

foreach (DevicePathProtocolBase protocol in bootOption.Protocols)
    Console.WriteLine(protocol.ToString());

​
ReadLoadOption<T>(BootOptionIndex)

public static T ReadLoadOption<T>(BootOptionIndex bootOptionIndex)
    where T : LoadOptionBase, new()
Reads a single Boot#### NVRAM variable and deserializes it as an instance of T. Type Parameters
​
T
LoadOptionBase (new())
The concrete type to deserialize into. Must inherit LoadOptionBase and have a public parameterless constructor.
Parameters
​
bootOptionIndex
BootOptionIndex
required
The index of the Boot#### variable to read.
Returns: T — the deserialized boot entry. 
MyBootOption option = FirmwareBootService.ReadLoadOption<MyBootOption>(0x0001);
Console.WriteLine(option.Description);

​
ReadRawLoadOption(BootOptionIndex)

public static EFI_LOAD_OPTION ReadRawLoadOption(BootOptionIndex bootOptionIndex)
Reads a single Boot#### NVRAM variable and returns its native EFI_LOAD_OPTION structure without managed-type conversion. Parameters
​
bootOptionIndex
BootOptionIndex
required
The index of the Boot#### variable to read.
Returns: EFI_LOAD_OPTION — the raw native load option structure. 
EFI_LOAD_OPTION raw = FirmwareBootService.ReadRawLoadOption(0x0000);
Console.WriteLine("Description : {0}", raw.Description);

​
CreateLoadOption

public static BootOptionIndex CreateLoadOption(LoadOptionBase loadOption, bool AddFirst)
Finds the first free Boot#### index, writes the serialized loadOption into it, and updates BootOrder in NVRAM. Pass AddFirst: true to prepend the new entry to the boot order (making it the highest-priority option), or false to append it at the end. Parameters
​
loadOption
LoadOptionBase
required
The load option to serialize and store. Accepts any LoadOptionBase subclass, including FirmwareBootOption.
​
AddFirst
bool
required
When true, the new entry is inserted at position 0 of BootOrder. When false, it is appended.
Returns: BootOptionIndex — the index assigned to the newly created Boot#### variable. Exceptions
ExceptionCondition
FreeLoadOptionIndexNotFoundAll 65 535 Boot#### slots are occupied and no free index can be found.
DevicePathProtocolBase[] protocols =
[
    new HardDriveProtocol(new Guid("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")),
    new FilePathProtocol("EFI\\MyApplication\\bootx64.efi"),
];

FirmwareBootOption bootOption = new FirmwareBootOption(
    LoadOptionAttributes.ACTIVE,
    "MyLoader",
    protocols,
    []);

BootOptionIndex newIndex = FirmwareBootService.CreateLoadOption(bootOption, AddFirst: true);
Console.WriteLine("Created at index: {0}", newIndex); // e.g. Boot0004

​
UpdateLoadOption

public static void UpdateLoadOption(LoadOptionBase loadOption, BootOptionIndex bootOptionIndex)
Serializes loadOption and writes it over the existing Boot#### variable at bootOptionIndex. The BootOrder array is not modified. Parameters
​
loadOption
LoadOptionBase
required
The updated load option to serialize and write.
​
bootOptionIndex
BootOptionIndex
required
The index of the existing Boot#### variable to overwrite.
Returns: void 
FirmwareBootOption updated = new FirmwareBootOption(
    LoadOptionAttributes.ACTIVE,
    "Updated Entry",
    protocols,
    []);

FirmwareBootService.UpdateLoadOption(updated, 0x0002);

​
EditLoadOption

public static void EditLoadOption(
    BootOptionIndex bootOptionIndex,
    Action<FirmwareBootOption> UpdateOptionAction)
Reads the Boot#### entry at bootOptionIndex, passes the deserialized FirmwareBootOption to UpdateOptionAction for in-place mutation, then writes the modified object back to NVRAM. This avoids having to perform a separate read and update. Parameters
​
bootOptionIndex
BootOptionIndex
required
The index of the Boot#### variable to edit.
​
UpdateOptionAction
Action<FirmwareBootOption>
required
A callback that receives the deserialized boot option. Mutate its properties inside the callback — changes are written back automatically when the delegate returns.
Returns: void 
FirmwareBootService.EditLoadOption(0x0002, option =>
{
    option.Description = "Renamed Entry";
    option.Attributes  = LoadOptionAttributes.ACTIVE;
});

​
DeleteLoadOption

public static void DeleteLoadOption(BootOptionIndex loadOptionIndex)
Resets the Boot#### NVRAM variable at loadOptionIndex to null (writing IntPtr.Zero) and removes that index from BootOrder. Parameters
​
loadOptionIndex
BootOptionIndex
required
The index of the Boot#### variable to delete.
Returns: void 
// Delete Boot0005 and remove it from BootOrder
FirmwareBootService.DeleteLoadOption(0x0005);
DeleteLoadOption removes the index from BootOrder automatically. You do not need to read and reassign LoadOrder yourself.

​
Exceptions Reference

ExceptionNamespaceDescription
FreeLoadOptionIndexNotFoundUnified.Firmware.BootServiceThrown by CreateLoadOption when every possible Boot#### slot (0x0000–0xFFFE) is already present in BootOrder.
InvalidHandleValueExceptionUnified.Firmware.BootServiceThrown when the firmware backend returns an invalid handle value during a variable read or write operation. Extends Win32Exception.
InvalidLoadOptionStrcutreExceptionUnified.Firmware.BootServiceThrown when a Boot#### variable contains a malformed EFI_LOAD_OPTION structure that cannot be deserialized.
DeviceProtocolCastingExceptionUnified.Firmware.BootServiceThrown when a device path protocol entry cannot be cast to the expected managed wrapper type.
InvalidInheritedClassExceptionUnified.Firmware.BootServiceThrown when a type registered as a device path protocol wrapper does not inherit the required base class.
MissingDevicePathProtocolWrapperAttributeExceptionUnified.Firmware.BootServiceThrown when a device path protocol wrapper class is missing the required defining attribute.
InvalidDevicePathProtocolStructureExceptionUnified.Firmware.BootServiceThrown when a device path protocol wrapper class has an incorrect structure.

Build docs developers (and LLMs) love

Get started for freeTalk to us