| Format | Assembly Format | Description |
|---|---|---|
| 8C <T> | box typeTok |
Convert a boxable value to its boxed form |
…, val → …, obj
If typeTok is a value type, the box instruction converts val to its boxed form. When typeTok is a non-nullable type (§I.8.2.4), this is done by creating a new object and copying the data from val into the newly allocated object. If it is a nullable type, this is done by inspecting val's HasValue property; if it is false, a null reference is pushed onto the stack; otherwise, the result of boxing val's Value property is pushed onto the stack.
If typeTok is a reference type, the box instruction does returns val unchanged as obj.
If typeTok is a generic parameter, the behavior of box instruction depends on the actual type at runtime. If this type is a value type it is boxed as above, if it is a reference type then val is not changed. However the type tracked by verification is always "boxed" typeTok for generic parameters, regardless of whether the actual type at runtime is a value or reference type.
typeTok is a metadata token (a typedef, typeref, or typespec) indicating the type of val. typeTok can represent a value type, a reference type, or a generic parameter.
System.OutOfMemoryException is thrown if there is insufficient memory to satisfy the request.
System.TypeLoadException is thrown if typeTok cannot be found. (This is typically detected when CIL is converted to native code rather than at runtime.)
typeTok shall be a valid typedef, typeref, or typespec metadata token. The type operand typeTok shall represent a boxable type (§I.8.2.4).
The top-of-stack shall be verifier-assignable-to the type represented by typeTok. When typeTok represents a non-nullable value type or a generic parameter, the resulting type is "boxed" typeTok; when typeTok is Nullable<T>, the resulting type is "boxed" T. When typeTok is a reference type, the resulting type is typeTok. The type operand typeTok shall not be a byref-like type.