Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
662 lines (578 sloc) 44.8 KB
<Type Name="DllImportAttribute" FullName="System.Runtime.InteropServices.DllImportAttribute">
<TypeSignature Language="C#" Value="public sealed class DllImportAttribute : Attribute" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi sealed beforefieldinit DllImportAttribute extends System.Attribute" />
<TypeSignature Language="DocId" Value="T:System.Runtime.InteropServices.DllImportAttribute" />
<TypeSignature Language="VB.NET" Value="Public NotInheritable Class DllImportAttribute&#xA;Inherits Attribute" />
<TypeSignature Language="C++ CLI" Value="public ref class DllImportAttribute sealed : Attribute" />
<TypeSignature Language="F#" Value="type DllImportAttribute = class&#xA; inherit Attribute" />
<AssemblyInfo>
<AssemblyName>System.Runtime.InteropServices</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<Base>
<BaseTypeName>System.Attribute</BaseTypeName>
</Base>
<Interfaces />
<Attributes>
<Attribute FrameworkAlternate="netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netframework-1.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.5;netstandard-1.6;netstandard-2.0;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0;netframework-4.8;netcore-2.2;dotnet-uwp-10.0;netcore-3.0;netstandard-2.1">
<AttributeName>System.AttributeUsage(System.AttributeTargets.Method, Inherited=false)</AttributeName>
</Attribute>
<Attribute FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0;netframework-4.8">
<AttributeName>System.Runtime.InteropServices.ComVisible(true)</AttributeName>
</Attribute>
</Attributes>
<Docs>
<summary>Indicates that the attributed method is exposed by an unmanaged dynamic-link library (DLL) as a static entry point.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
You can apply this attribute to methods.
The <xref:System.Runtime.InteropServices.DllImportAttribute> attribute provides the information needed to call a function exported from an unmanaged DLL. As a minimum requirement, you must supply the name of the DLL containing the entry point.
You apply this attribute directly to C# and C++ method definitions; however, the Visual Basic compiler emits this attribute when you use the `Declare` statement. For complex method definitions that include <xref:System.Runtime.InteropServices.DllImportAttribute.BestFitMapping>, <xref:System.Runtime.InteropServices.DllImportAttribute.CallingConvention>, <xref:System.Runtime.InteropServices.DllImportAttribute.ExactSpelling>, <xref:System.Runtime.InteropServices.DllImportAttribute.PreserveSig>, <xref:System.Runtime.InteropServices.DllImportAttribute.SetLastError>, or <xref:System.Runtime.InteropServices.DllImportAttribute.ThrowOnUnmappableChar> fields, you apply this attribute directly to Visual Basic method definitions.
**Note** JScript does not support this attribute. You can use C# or Visual Basic wrapper classes to access unmanaged API methods from JScript programs.
For additional information about using the platform invoke service to access functions in unmanaged DLLs, see [Consuming Unmanaged DLL Functions](~/docs/framework/interop/consuming-unmanaged-dll-functions.md).
> [!NOTE]
> The <xref:System.Runtime.InteropServices.DllImportAttribute> does not support marshaling of generic types.
## Examples
The following code example shows how to use the <xref:System.Runtime.InteropServices.DllImportAttribute> attribute to import the Win32 `MessageBox` function. The code example then calls the imported method.
[!code-csharp[System.Runtime.InteropServices.DllImport.Canonical#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.Canonical/cs/sample.cs#1)]
[!code-vb[System.Runtime.InteropServices.DllImport.Canonical#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.Canonical/vb/sample.vb#1)]
]]></format>
</remarks>
<altmember cref="F:System.Runtime.InteropServices.DllImportAttribute.SetLastError" />
<altmember cref="F:System.Runtime.InteropServices.DllImportAttribute.ExactSpelling" />
<altmember cref="F:System.Runtime.InteropServices.DllImportAttribute.PreserveSig" />
<altmember cref="F:System.Runtime.InteropServices.DllImportAttribute.CallingConvention" />
</Docs>
<Members>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public DllImportAttribute (string dllName);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string dllName) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Runtime.InteropServices.DllImportAttribute.#ctor(System.String)" />
<MemberSignature Language="VB.NET" Value="Public Sub New (dllName As String)" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; DllImportAttribute(System::String ^ dllName);" />
<MemberSignature Language="F#" Value="new System.Runtime.InteropServices.DllImportAttribute : string -&gt; System.Runtime.InteropServices.DllImportAttribute" Usage="new System.Runtime.InteropServices.DllImportAttribute dllName" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime.InteropServices</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<Parameters>
<Parameter Name="dllName" Type="System.String" />
</Parameters>
<Docs>
<param name="dllName">The name of the DLL that contains the unmanaged method. This can include an assembly display name, if the DLL is included in an assembly.</param>
<summary>Initializes a new instance of the <see cref="T:System.Runtime.InteropServices.DllImportAttribute" /> class with the name of the DLL containing the method to import.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
If an unmanaged DLL file is included in an assembly, for example, by using the linker or the `/linkresource` compiler option, you can specify the assembly display name as part of `dllName`. For example, if an unmanaged DLL named `unmanaged.dll` is included in a managed assembly named `MyAssembly`, the attribute might be specified as shown in the following code.
[!code-cpp[System.Runtime.InteropServices.DllImportAttribute#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cpp/source.cpp#2)]
[!code-csharp[System.Runtime.InteropServices.DllImportAttribute#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cs/source.cs#2)]
[!code-vb[System.Runtime.InteropServices.DllImportAttribute#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb#2)]
## Examples
The following code example shows how to use the <xref:System.Runtime.InteropServices.DllImportAttribute> attribute to import the Win32 `MessageBox` function. The code example then calls the imported method.
[!code-csharp[System.Runtime.InteropServices.DllImport.Canonical#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.Canonical/cs/sample.cs#1)]
[!code-vb[System.Runtime.InteropServices.DllImport.Canonical#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.Canonical/vb/sample.vb#1)]
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="BestFitMapping">
<MemberSignature Language="C#" Value="public bool BestFitMapping;" />
<MemberSignature Language="ILAsm" Value=".field public bool BestFitMapping" />
<MemberSignature Language="DocId" Value="F:System.Runtime.InteropServices.DllImportAttribute.BestFitMapping" />
<MemberSignature Language="VB.NET" Value="Public BestFitMapping As Boolean " />
<MemberSignature Language="C++ CLI" Value="public: bool BestFitMapping;" />
<MemberSignature Language="F#" Value="val mutable BestFitMapping : bool" Usage="System.Runtime.InteropServices.DllImportAttribute.BestFitMapping" />
<MemberType>Field</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime.InteropServices</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>Enables or disables best-fit mapping behavior when converting Unicode characters to ANSI characters.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
If `true`, best-fit mapping behavior is enabled; otherwise, best-fit mapping is disabled. The <xref:System.Runtime.InteropServices.DllImportAttribute.BestFitMapping> field is `true` by default. Settings for this field override the any level settings for the <xref:System.Runtime.InteropServices.BestFitMappingAttribute?displayProperty=nameWithType> attribute.
The common language runtime converts to ANSI characters any managed Unicode characters passed to an unmanaged method executing on Windows 98 or Windows Me. Best-fit mapping enables the interop marshaler to provide a close-matching character when no exact match exists. For example, the marshaler converts the Unicode copyright character to 'c' for unmanaged methods that accept ANSI characters. Some characters lack a best-fit representation; these characters are called unmappable. Unmappable characters are usually converted to the default '?' ANSI character.
> [!CAUTION]
> Certain Unicode characters are converted to dangerous characters, such as the backslash '\\' character, which can inadvertently change a path. By setting the <xref:System.Runtime.InteropServices.DllImportAttribute.ThrowOnUnmappableChar> field to `true`, you can signal the presence of an unmappable character to the caller by throwing an exception.
> [!CAUTION]
> You cannot change the default values provided by the <xref:System.Runtime.InteropServices.DllImportAttribute.BestFitMapping> and <xref:System.Runtime.InteropServices.DllImportAttribute.ThrowOnUnmappableChar> fields when passing a managed array whose elements are ANSI Chars or LPSTRs to an unmanaged safe array. Best-fit mapping is always enabled and no exception is thrown. Be aware that this combination can compromise your security model.
## Examples
In some cases, Visual Basic developers use the <xref:System.Runtime.InteropServices.DllImportAttribute>, instead of the `Declare` statement, to define a DLL function in managed code. Setting the <xref:System.Runtime.InteropServices.DllImportAttribute.BestFitMapping> field is one of those cases. The following example shows how to apply the strictest character mapping security to a platform invoke method definitions by specifying the ANSI character set, disabling best fit mapping behavior, and throwing an exception on unmapped Unicode characters.
[!code-cpp[System.Runtime.InteropServices.DllImportAttribute#3](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cpp/source.cpp#3)]
[!code-csharp[System.Runtime.InteropServices.DllImportAttribute#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cs/source.cs#3)]
[!code-vb[System.Runtime.InteropServices.DllImportAttribute#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb#3)]
]]></format>
</remarks>
<altmember cref="F:System.Runtime.InteropServices.DllImportAttribute.CharSet" />
<altmember cref="T:System.Runtime.InteropServices.BestFitMappingAttribute" />
<related type="Article" href="https://msdn.microsoft.com/library/115f7a2f-d422-4605-ab36-13a8dd28142a">Interop Marshaling</related>
</Docs>
</Member>
<Member MemberName="CallingConvention">
<MemberSignature Language="C#" Value="public System.Runtime.InteropServices.CallingConvention CallingConvention;" />
<MemberSignature Language="ILAsm" Value=".field public valuetype System.Runtime.InteropServices.CallingConvention CallingConvention" />
<MemberSignature Language="DocId" Value="F:System.Runtime.InteropServices.DllImportAttribute.CallingConvention" />
<MemberSignature Language="VB.NET" Value="Public CallingConvention As CallingConvention " />
<MemberSignature Language="C++ CLI" Value="public: System::Runtime::InteropServices::CallingConvention CallingConvention;" />
<MemberSignature Language="F#" Value="val mutable CallingConvention : System.Runtime.InteropServices.CallingConvention" Usage="System.Runtime.InteropServices.DllImportAttribute.CallingConvention" />
<MemberType>Field</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime.InteropServices</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Runtime.InteropServices.CallingConvention</ReturnType>
</ReturnValue>
<Docs>
<summary>Indicates the calling convention of an entry point.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
You set this field to one of the <xref:System.Runtime.InteropServices.CallingConvention> enumeration members. The default value for the <xref:System.Runtime.InteropServices.DllImportAttribute.CallingConvention> field is <xref:System.Runtime.InteropServices.CallingConvention.Winapi>, which in turn defaults to <xref:System.Runtime.InteropServices.CallingConvention.StdCall> convention.
## Examples
In some cases, Visual Basic developers use the <xref:System.Runtime.InteropServices.DllImportAttribute>, instead of the `Declare` statement, to define a DLL function in managed code. Setting the <xref:System.Runtime.InteropServices.DllImportAttribute.CallingConvention> field is one of those cases.
[!code-cpp[System.Runtime.InteropServices.DllImportAttribute#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cpp/source.cpp#1)]
[!code-csharp[System.Runtime.InteropServices.DllImportAttribute#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cs/source.cs#1)]
[!code-vb[System.Runtime.InteropServices.DllImportAttribute#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb#1)]
]]></format>
</remarks>
<altmember cref="T:System.Runtime.InteropServices.CallingConvention" />
</Docs>
</Member>
<Member MemberName="CharSet">
<MemberSignature Language="C#" Value="public System.Runtime.InteropServices.CharSet CharSet;" />
<MemberSignature Language="ILAsm" Value=".field public valuetype System.Runtime.InteropServices.CharSet CharSet" />
<MemberSignature Language="DocId" Value="F:System.Runtime.InteropServices.DllImportAttribute.CharSet" />
<MemberSignature Language="VB.NET" Value="Public CharSet As CharSet " />
<MemberSignature Language="C++ CLI" Value="public: System::Runtime::InteropServices::CharSet CharSet;" />
<MemberSignature Language="F#" Value="val mutable CharSet : System.Runtime.InteropServices.CharSet" Usage="System.Runtime.InteropServices.DllImportAttribute.CharSet" />
<MemberType>Field</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime.InteropServices</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Runtime.InteropServices.CharSet</ReturnType>
</ReturnValue>
<Docs>
<summary>Indicates how to marshal string parameters to the method and controls name mangling.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
Use this field with a member of the <xref:System.Runtime.InteropServices.CharSet> enumeration to specify the marshaling behavior of string parameters and to specify which entry-point name to invoke (the exact name given or a name ending with "A" or "W"). The default enumeration member for C# and Visual Basic is `CharSet.Ansi` and the default enumeration member for C++ is `CharSet.None`, which is equivalent to `CharSet.Ansi`. In Visual Basic, you use the `Declare` statement to specify the `CharSet` field.
The <xref:System.Runtime.InteropServices.DllImportAttribute.ExactSpelling> field influences the behavior of the `CharSet` field in determining which entry-point name to invoke. For a detailed description and examples of the string marshaling and name matching behavior associated with the `CharSet` field, see [Specifying a Character Set](~/docs/framework/interop/specifying-a-character-set.md).
## Examples
The following code example shows how to use the <xref:System.Runtime.InteropServices.DllImportAttribute> attribute to import the Win32 `MessageBox` function. The code example then calls the imported method.
[!code-csharp[System.Runtime.InteropServices.DllImport.Canonical#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.Canonical/cs/sample.cs#1)]
[!code-vb[System.Runtime.InteropServices.DllImport.Canonical#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.Canonical/vb/sample.vb#1)]
]]></format>
</remarks>
<altmember cref="F:System.Runtime.InteropServices.DllImportAttribute.ExactSpelling" />
</Docs>
</Member>
<Member MemberName="EntryPoint">
<MemberSignature Language="C#" Value="public string EntryPoint;" />
<MemberSignature Language="ILAsm" Value=".field public string EntryPoint" />
<MemberSignature Language="DocId" Value="F:System.Runtime.InteropServices.DllImportAttribute.EntryPoint" />
<MemberSignature Language="VB.NET" Value="Public EntryPoint As String " />
<MemberSignature Language="C++ CLI" Value="public: System::String ^ EntryPoint;" />
<MemberSignature Language="F#" Value="val mutable EntryPoint : string" Usage="System.Runtime.InteropServices.DllImportAttribute.EntryPoint" />
<MemberType>Field</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime.InteropServices</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Docs>
<summary>Indicates the name or ordinal of the DLL entry point to be called.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
You can specify the entry-point name by supplying a string indicating the name of the DLL containing the entry point, or you can identify the entry point by its ordinal. Ordinals are prefixed with the # sign, for example, #1. If you omit this field, the common language runtime uses the name of the.NET method marked with the <xref:System.Runtime.InteropServices.DllImportAttribute>.
For additional information, see [Identifying Functions in DLLs](~/docs/framework/interop/identifying-functions-in-dlls.md). For examples showing how to use the <xref:System.Runtime.InteropServices.DllImportAttribute.EntryPoint> field, see [Specifying an Entry Point](~/docs/framework/interop/specifying-an-entry-point.md).
## Examples
The following code example shows how to use the <xref:System.Runtime.InteropServices.DllImportAttribute> attribute to import the Win32 `MessageBox` function. The code example uses the <xref:System.Runtime.InteropServices.DllImportAttribute.EntryPoint> property to specify the function to import and then changes the name to `MyNewMessageBoxMethod`.
[!code-csharp[System.Runtime.InteropServices.DllImport.EntryPoint#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.EntryPoint/cs/sample.cs#1)]
[!code-vb[System.Runtime.InteropServices.DllImport.EntryPoint#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Runtime.InteropServices.DllImport.EntryPoint/vb/sample.vb#1)]
]]></format>
</remarks>
<altmember cref="T:System.Runtime.InteropServices.DllImportAttribute" />
</Docs>
</Member>
<Member MemberName="ExactSpelling">
<MemberSignature Language="C#" Value="public bool ExactSpelling;" />
<MemberSignature Language="ILAsm" Value=".field public bool ExactSpelling" />
<MemberSignature Language="DocId" Value="F:System.Runtime.InteropServices.DllImportAttribute.ExactSpelling" />
<MemberSignature Language="VB.NET" Value="Public ExactSpelling As Boolean " />
<MemberSignature Language="C++ CLI" Value="public: bool ExactSpelling;" />
<MemberSignature Language="F#" Value="val mutable ExactSpelling : bool" Usage="System.Runtime.InteropServices.DllImportAttribute.ExactSpelling" />
<MemberType>Field</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime.InteropServices</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>Controls whether the <see cref="F:System.Runtime.InteropServices.DllImportAttribute.CharSet" /> field causes the common language runtime to search an unmanaged DLL for entry-point names other than the one specified.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
If `false`, the entry point name appended with the letter A is invoked when the <xref:System.Runtime.InteropServices.DllImportAttribute.CharSet?displayProperty=nameWithType> field is set to `CharSet.Ansi`, and the entry-point name appended with the letter W is invoked when the <xref:System.Runtime.InteropServices.DllImportAttribute.CharSet?displayProperty=nameWithType> field is set to the `CharSet.Unicode`. Typically, managed compilers set this field.
The following table shows the relationship between the <xref:System.Runtime.InteropServices.DllImportAttribute.CharSet> and <xref:System.Runtime.InteropServices.DllImportAttribute.ExactSpelling> fields, based on default values imposed by the programming language. You can override the default setting, but do so with caution.
|Language|ANSI|Unicode|Auto|
|--------------|----------|-------------|----------|
|Visual Basic|ExactSpelling:=True|ExactSpelling:=True|ExactSpelling:=False|
|C#|ExactSpelling=false|ExactSpelling=false|ExactSpelling=false|
|C++|ExactSpelling=false|ExactSpelling=false|ExactSpelling=false|
## Examples
In some cases, Visual Basic developers use the <xref:System.Runtime.InteropServices.DllImportAttribute>, instead of using the `Declare` statement, to define a DLL function in managed code. Setting the <xref:System.Runtime.InteropServices.DllImportAttribute.ExactSpelling> field is one of those cases.
[!code-cpp[System.Runtime.InteropServices.DllImportAttribute#4](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cpp/source.cpp#4)]
[!code-csharp[System.Runtime.InteropServices.DllImportAttribute#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cs/source.cs#4)]
[!code-vb[System.Runtime.InteropServices.DllImportAttribute#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb#4)]
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="PreserveSig">
<MemberSignature Language="C#" Value="public bool PreserveSig;" />
<MemberSignature Language="ILAsm" Value=".field public bool PreserveSig" />
<MemberSignature Language="DocId" Value="F:System.Runtime.InteropServices.DllImportAttribute.PreserveSig" />
<MemberSignature Language="VB.NET" Value="Public PreserveSig As Boolean " />
<MemberSignature Language="C++ CLI" Value="public: bool PreserveSig;" />
<MemberSignature Language="F#" Value="val mutable PreserveSig : bool" Usage="System.Runtime.InteropServices.DllImportAttribute.PreserveSig" />
<MemberType>Field</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime.InteropServices</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>Indicates whether unmanaged methods that have <see langword="HRESULT" /> or <see langword="retval" /> return values are directly translated or whether <see langword="HRESULT" /> or <see langword="retval" /> return values are automatically converted to exceptions.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
Set the <xref:System.Runtime.InteropServices.DllImportAttribute.PreserveSig> field to `true` to directly translate unmanaged signatures with `HRESULT` or `retval` values; set it to `false` to automatically convert `HRESULT` or `retval` values to exceptions. By default, the <xref:System.Runtime.InteropServices.DllImportAttribute.PreserveSig> field is `true`.
When `true`, the resulting method signature returns an integer value that contains the `HRESULT` value. In this case, you must manually inspect the return value and respond accordingly in your application.
When you set the <xref:System.Runtime.InteropServices.DllImportAttribute.PreserveSig> field to `false`, the resulting method signature contains a void return type instead of an integer (`HRESULT`) return type. When the unmanaged method produces an `HRESULT`, the runtime automatically ignores a return value of `S_OK` (or 0) and does not throw an exception. For `HRESULT`s other than `S_OK`, the runtime automatically throws an exception that corresponds to the `HRESULT`. Note that the <xref:System.Runtime.InteropServices.DllImportAttribute> attribute only performs this conversion to methods that return an `HRESULT`.
You might decide to change the default error reporting behavior from `HRESULT`s to exceptions in cases where exceptions better fit the error reporting structure of your application.
This field is similar to the <xref:System.Runtime.InteropServices.PreserveSigAttribute>; however, in contrast to the <xref:System.Runtime.InteropServices.DllImportAttribute.PreserveSig> field, the default value for the attribute is `false`.
In some cases, Visual Basic developers use the <xref:System.Runtime.InteropServices.DllImportAttribute>, instead of using the `Declare` statement, to define a DLL function in managed code. Setting the <xref:System.Runtime.InteropServices.DllImportAttribute.PreserveSig> field is one of those cases.
## Examples
The following code example uses the <xref:System.Runtime.InteropServices.DllImportAttribute> to import the unmanaged `SHAutoComplete` function once with the <xref:System.Runtime.InteropServices.DllImportAttribute.PreserveSig> field set to `true` and again with the <xref:System.Runtime.InteropServices.DllImportAttribute.PreserveSig> field set to `false`. This code example causes the `SHAutoComplete` function to generate any errors with an exception one time and an `HRESULT` the next.
[!code-csharp[Runtime.InteropServices.PreserveSigAttribute#1](~/samples/snippets/csharp/VS_Snippets_CLR/Runtime.InteropServices.PreserveSigAttribute/cs/example.cs#1)]
[!code-vb[Runtime.InteropServices.PreserveSigAttribute#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Runtime.InteropServices.PreserveSigAttribute/vb/example.vb#1)]
]]></format>
</remarks>
<altmember cref="T:System.Runtime.InteropServices.PreserveSigAttribute" />
</Docs>
</Member>
<Member MemberName="SetLastError">
<MemberSignature Language="C#" Value="public bool SetLastError;" />
<MemberSignature Language="ILAsm" Value=".field public bool SetLastError" />
<MemberSignature Language="DocId" Value="F:System.Runtime.InteropServices.DllImportAttribute.SetLastError" />
<MemberSignature Language="VB.NET" Value="Public SetLastError As Boolean " />
<MemberSignature Language="C++ CLI" Value="public: bool SetLastError;" />
<MemberSignature Language="F#" Value="val mutable SetLastError : bool" Usage="System.Runtime.InteropServices.DllImportAttribute.SetLastError" />
<MemberType>Field</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime.InteropServices</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>Indicates whether the callee calls the <see langword="SetLastError" /> Windows API function before returning from the attributed method.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
`true` to indicate that the callee will call `SetLastError`; otherwise, `false`. The default is `false`.
The runtime marshaler calls `GetLastError` and caches the value returned to prevent it from being overwritten by other API calls. You can retrieve the error code by calling <xref:System.Runtime.InteropServices.Marshal.GetLastWin32Error%2A>.
## Examples
In some cases, Visual Basic developers use the <xref:System.Runtime.InteropServices.DllImportAttribute>, instead of using the `Declare` statement, to define a DLL function in managed code. Setting the <xref:System.Runtime.InteropServices.DllImportAttribute.SetLastError> field is one of those cases.
[!code-cpp[System.Runtime.InteropServices.DllImportAttribute#5](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cpp/source.cpp#5)]
[!code-csharp[System.Runtime.InteropServices.DllImportAttribute#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cs/source.cs#5)]
[!code-vb[System.Runtime.InteropServices.DllImportAttribute#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb#5)]
]]></format>
</remarks>
<altmember cref="M:System.Runtime.InteropServices.Marshal.GetLastWin32Error" />
</Docs>
</Member>
<Member MemberName="ThrowOnUnmappableChar">
<MemberSignature Language="C#" Value="public bool ThrowOnUnmappableChar;" />
<MemberSignature Language="ILAsm" Value=".field public bool ThrowOnUnmappableChar" />
<MemberSignature Language="DocId" Value="F:System.Runtime.InteropServices.DllImportAttribute.ThrowOnUnmappableChar" />
<MemberSignature Language="VB.NET" Value="Public ThrowOnUnmappableChar As Boolean " />
<MemberSignature Language="C++ CLI" Value="public: bool ThrowOnUnmappableChar;" />
<MemberSignature Language="F#" Value="val mutable ThrowOnUnmappableChar : bool" Usage="System.Runtime.InteropServices.DllImportAttribute.ThrowOnUnmappableChar" />
<MemberType>Field</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime.InteropServices</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<summary>Enables or disables the throwing of an exception on an unmappable Unicode character that is converted to an ANSI "?" character.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
`true` to indicate that an exception is thrown each time the interop marshaler converts an unmappable character; `false` to indicate that the <xref:System.Runtime.InteropServices.DllImportAttribute.ThrowOnUnmappableChar> field is disabled. This field is `false` by default.
The common language runtime converts to ANSI characters any managed Unicode characters passed to an unmanaged method executing on Windows 98 or Windows Me. Best-fit mapping enables the interop marshaler to provide a close-matching character when no exact match exists. For example, the marshaler converts the Unicode copyright character to 'c' for unmanaged methods that accept ANSI characters. Some characters lack a best-fit representation; these characters are called unmappable. Unmappable characters are usually converted to the default '?' ANSI character.
> [!CAUTION]
> Certain Unicode characters are converted to dangerous characters, such as the backslash '\\' character, which can inadvertently change a path. By setting the <xref:System.Runtime.InteropServices.DllImportAttribute.ThrowOnUnmappableChar> field to `true`, you can signal the presence of an unmappable character to the caller by throwing an exception.
> [!CAUTION]
> You cannot change the default values provided by the <xref:System.Runtime.InteropServices.DllImportAttribute.BestFitMapping> and <xref:System.Runtime.InteropServices.DllImportAttribute.ThrowOnUnmappableChar> fields when passing a managed array whose elements are ANSI Chars or LPSTRs to an unmanaged safe array. Best-fit mapping is always enabled and no exception is thrown. Be aware that this combination can compromise your security model.
## Examples
In some cases, Visual Basic developers use the <xref:System.Runtime.InteropServices.DllImportAttribute> to define a DLL function in managed code, instead of using the `Declare` statement. Setting the <xref:System.Runtime.InteropServices.DllImportAttribute.ThrowOnUnmappableChar> field is one of those cases. The following example shows how to apply the strictest character mapping security to a platform invoke method definitions by specifying the ANSI character set, disabling best fit mapping behavior, and throwing an exception on unmapped Unicode characters.
[!code-cpp[System.Runtime.InteropServices.DllImportAttribute#3](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cpp/source.cpp#3)]
[!code-csharp[System.Runtime.InteropServices.DllImportAttribute#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/cs/source.cs#3)]
[!code-vb[System.Runtime.InteropServices.DllImportAttribute#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.dllimportattribute/vb/source.vb#3)]
]]></format>
</remarks>
<altmember cref="F:System.Runtime.InteropServices.DllImportAttribute.CharSet" />
<altmember cref="F:System.Runtime.InteropServices.DllImportAttribute.BestFitMapping" />
<related type="Article" href="https://msdn.microsoft.com/library/115f7a2f-d422-4605-ab36-13a8dd28142a">Interop Marshaling</related>
</Docs>
</Member>
<Member MemberName="Value">
<MemberSignature Language="C#" Value="public string Value { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance string Value" />
<MemberSignature Language="DocId" Value="P:System.Runtime.InteropServices.DllImportAttribute.Value" />
<MemberSignature Language="VB.NET" Value="Public ReadOnly Property Value As String" />
<MemberSignature Language="C++ CLI" Value="public:&#xA; property System::String ^ Value { System::String ^ get(); };" />
<MemberSignature Language="F#" Value="member this.Value : string" Usage="System.Runtime.InteropServices.DllImportAttribute.Value" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime.InteropServices</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Docs>
<summary>Gets the name of the DLL file that contains the entry point.</summary>
<value>The name of the DLL file that contains the entry point.</value>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
You can provide a full or relative path. If you provide no path, the DLL must be in the current path at run time, unless the DLL is loaded by some other means. Be aware, however, that using a fully qualified path can introduce inaccuracy if the DLL is moved.
]]></format>
</remarks>
</Docs>
</Member>
</Members>
</Type>
You can’t perform that action at this time.