Definition - What does Directional Attributes mean?
Directional attributes, in C#, are tags used to specify object method parameter(s) with information related to the directional flow of data between the caller and callee.
Directional attributes control marshaling - where an object is prepared for transfer across an application or process boundary - of the method parameter's direction and return values. Directional attributes are applied to modify runtime marshaling while communicating managed code, which is executed by the Common Language Runtime (CLR), and unmanaged code, which is executed outside the control of the CLR.
Techopedia explains Directional Attributes
InAttribute and OutAttribute are the two C# directional attributes used to map to the Component Object Model's (COM) Interface Definition Language (IDL) attributes. InAttribute maps to [in], and OutAttribute maps to [out]. The managed method signature return value maps to [out, retval] in a type library. It is essential to specify the right directional attribute to method parameters, so that the exporting type library correctly sets the In/Out bits.
By applying InAttribute and OutAttribute in arrays and formatted non-blittable types (that do not have common managed and unmanaged memory representation), the caller sees callee changes. Directional attributes applied to these types reduce unnecessary copies during marshaling.
In C#, InAttribute and OutAttribute are used in three forms with two keywords during caller and callee communication, as follows:
- "out" – Implies [OutAttribute]
- "ref" – Implies [InAttribute], [OutAttribute]
- (None specified) – [InAttribute] (by default)
The out and ref keywords are used for value types and serializable reference types. The ref keyword implies that the parameter is marshaled in both directions, and out implies callee data transfer. When ref or out are not used, this implies data is transferred to the callee.
For example, a .NET client application sends an input value to a COM component method, which calculates the input value result and returns the result to the client. Directional attributes may be applied to the parameters of the method servicing the request by indicating the required marshaling type for input value and result.
Directional attributes have the following characteristics:
- Optional and applied to method parameters at design time
- Supported for COM interop and platform invoke only
- InAttribute cannot be applied to a parameter with an out keyword
The CLR interop marshaler provides marshaling service at runtime by handling method call arguments and return values between managed and unmanaged memory. If directional attributes are not defined, the marshaler determines directional flow based on the parameter type and modifier (if any). The marshaler operates in the following manner:
- It does not overwrite the data passed as an "In" parameter from unmanaged code. Thus, only read-only data, like concurrently accessed data, may be passed.
- While passing objects - such as basic or binary strings (BSTR) - with established memory allocation, the proper allocation/deallocation sequence is followed according to In/Out settings.