diff --git a/.openpublishing.redirection.framework.json b/.openpublishing.redirection.framework.json index 4e1fcd2aa6e28..319e7d1e5b7ff 100644 --- a/.openpublishing.redirection.framework.json +++ b/.openpublishing.redirection.framework.json @@ -1000,6 +1000,61 @@ "redirect_url": "/dotnet/standard/native-interop/runtime-callable-wrapper", "redirect_document_id": true }, + { + "source_path_from_root": "/docs/framework/interop/default-marshaling-behavior.md", + "redirect_url": "/dotnet/framework/interop/default-marshalling-behavior", + "redirect_document_id": true + }, + { + "source_path_from_root": "/docs/framework/interop/default-marshaling-for-arrays.md", + "redirect_url": "/dotnet/framework/interop/default-marshalling-for-arrays", + "redirect_document_id": true + }, + { + "source_path_from_root": "/docs/framework/interop/default-marshaling-for-objects.md", + "redirect_url": "/dotnet/framework/interop/default-marshalling-for-objects", + "redirect_document_id": true + }, + { + "source_path_from_root": "/docs/framework/interop/default-marshaling-for-strings.md", + "redirect_url": "/dotnet/framework/interop/default-marshalling-for-strings", + "redirect_document_id": true + }, + { + "source_path_from_root": "/docs/framework/interop/interop-marshaling.md", + "redirect_url": "/dotnet/framework/interop/interop-marshalling", + "redirect_document_id": true + }, + { + "source_path_from_root": "/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md", + "redirect_url": "/dotnet/framework/interop/marshalling-a-delegate-as-a-callback-method", + "redirect_document_id": true + }, + { + "source_path_from_root": "/docs/framework/interop/marshaling-classes-structures-and-unions.md", + "redirect_url": "/dotnet/framework/interop/marshalling-classes-structures-and-unions", + "redirect_document_id": true + }, + { + "source_path_from_root": "/docs/framework/interop/marshaling-data-with-com-interop.md", + "redirect_url": "/dotnet/framework/interop/marshalling-data-with-com-interop", + "redirect_document_id": true + }, + { + "source_path_from_root": "/docs/framework/interop/marshaling-data-with-platform-invoke.md", + "redirect_url": "/dotnet/framework/interop/marshalling-data-with-platform-invoke", + "redirect_document_id": true + }, + { + "source_path_from_root": "/docs/framework/interop/marshaling-different-types-of-arrays.md", + "redirect_url": "/dotnet/framework/interop/marshalling-different-types-of-arrays", + "redirect_document_id": true + }, + { + "source_path_from_root": "/docs/framework/interop/marshaling-strings.md", + "redirect_url": "/dotnet/framework/interop/marshalling-strings", + "redirect_document_id": true + }, { "source_path_from_root": "/docs/framework/mef/composition-analysis-tool-mefx.md", "redirect_url": "/previous-versions/dotnet/framework/mef/composition-analysis-tool-mefx", diff --git a/.openpublishing.redirection.standard.json b/.openpublishing.redirection.standard.json index 6dc415eb4d120..dba317dff62df 100644 --- a/.openpublishing.redirection.standard.json +++ b/.openpublishing.redirection.standard.json @@ -527,23 +527,23 @@ "redirect_document_id": true }, { - "source_path_from_root": "/docs/standard/native-interop/customize-parameter-marshalling.md", - "redirect_url": "/dotnet/standard/native-interop/customize-parameter-marshaling", + "source_path_from_root": "/docs/standard/native-interop/customize-parameter-marshaling.md", + "redirect_url": "/dotnet/standard/native-interop/customize-parameter-marshalling", "redirect_document_id": true }, { - "source_path_from_root": "/docs/standard/native-interop/customize-struct-marshalling.md", - "redirect_url": "/dotnet/standard/native-interop/customize-struct-marshaling", + "source_path_from_root": "/docs/standard/native-interop/customize-struct-marshaling.md", + "redirect_url": "/dotnet/standard/native-interop/customize-struct-marshalling", "redirect_document_id": true }, { - "source_path_from_root": "/docs/standard/native-interop/type-marshalling.md", - "redirect_url": "/dotnet/standard/native-interop/type-marshaling", + "source_path_from_root": "/docs/standard/native-interop/type-marshaling.md", + "redirect_url": "/dotnet/standard/native-interop/type-marshalling", "redirect_document_id": true }, { "source_path_from_root": "/docs/standard/parallel-processing-and-concurrency.md", - "redirect_url": "/dotnet/standard/asynchronous-programming-patterns", + "redirect_url": "/dotnet/standard/asynchronous-programming-patterns" }, { "source_path_from_root": "/docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-thread-local-variables.md", diff --git a/docs/core/compatibility/windows-forms/5.0/winforms-objects-not-accessible-from-native-code.md b/docs/core/compatibility/windows-forms/5.0/winforms-objects-not-accessible-from-native-code.md index 5f55ed204fc5f..9e15dedad6bc2 100644 --- a/docs/core/compatibility/windows-forms/5.0/winforms-objects-not-accessible-from-native-code.md +++ b/docs/core/compatibility/windows-forms/5.0/winforms-objects-not-accessible-from-native-code.md @@ -22,7 +22,7 @@ In previous .NET versions, some Windows Forms types were decorated as visible to - Removal of `ComVisible(true)` from some non-public code: The only potential consumer would be the new Visual Studio designer, but without a GUID specified, it's unlikely that it's still needed. - Removal of `ComVisible(true)` from some arbitrary public designer classes: The old Visual Studio designer may have been using COM interop to talk to these classes. However, the old designer doesn't support .NET Core, so few people would need these as `ComVisible`. - `IWin32Window` defined the same GUID that was defined in .NET Framework, which has dangerous consequences. If you require interop with .NET Framework, use `ComImport`. -- The WinForms managed `IDataObject` was made `ComVisible`. This is not required, there is a separate `ComImport` interface declaration for `IDataObject` COM interop. It's counterproductive to have the managed `IDataObject` be `ComVisible`, since no TLB is provided and marshaling will always fail. Also, the GUID was not specified and differed from .NET Framework, so its unlikely that removing an undocumented IID will affect customers negatively. +- The WinForms managed `IDataObject` was made `ComVisible`. This is not required, there is a separate `ComImport` interface declaration for `IDataObject` COM interop. It's counterproductive to have the managed `IDataObject` be `ComVisible`, since no TLB is provided and marshalling will always fail. Also, the GUID was not specified and differed from .NET Framework, so its unlikely that removing an undocumented IID will affect customers negatively. - Removal of `ComVisible(false)`: Those are placed in seemingly arbitrary places and are redundant when the default is to not expose classes to COM interop. ## Version introduced diff --git a/docs/core/dependency-loading/understanding-assemblyloadcontext.md b/docs/core/dependency-loading/understanding-assemblyloadcontext.md index a92095c52a821..ed383c005b81e 100644 --- a/docs/core/dependency-loading/understanding-assemblyloadcontext.md +++ b/docs/core/dependency-loading/understanding-assemblyloadcontext.md @@ -109,4 +109,4 @@ There are two design patterns for solving these type conversion issues. 1. Use common shared types. This shared type can either be a primitive runtime type, or it can involve creating a new shared type in a shared assembly. Often the shared type is an [interface](../../csharp/language-reference/keywords/interface.md) defined in an application assembly. For more information, read about [how dependencies are shared](#how-are-dependencies-shared). -2. Use marshaling techniques to convert from one type to another. +2. Use marshalling techniques to convert from one type to another. diff --git a/docs/csharp/language-reference/compiler-messages/cs1690.md b/docs/csharp/language-reference/compiler-messages/cs1690.md index 915ceb7efd8a2..0f0f8264c2775 100644 --- a/docs/csharp/language-reference/compiler-messages/cs1690.md +++ b/docs/csharp/language-reference/compiler-messages/cs1690.md @@ -12,7 +12,7 @@ ms.assetid: bc76efe0-4304-4449-8c11-950667aa8ac9 Accessing a member on 'member' may cause a runtime exception because it is a field of a marshal-by-reference class - This warning occurs when you try to call a method, property, or indexer on a member of a class that derives from , and the member is a value type. Objects that inherit from `MarshalByRefObject` are typically intended to be marshaled by reference across an application domain. If any code ever attempts to directly access the value-type member of such an object across an application domain, a runtime will occur. To resolve the warning, first copy the member into a local variable and call the method on that variable. + This warning occurs when you try to call a method, property, or indexer on a member of a class that derives from , and the member is a value type. Objects that inherit from `MarshalByRefObject` are typically intended to be marshalled by reference across an application domain. If any code ever attempts to directly access the value-type member of such an object across an application domain, a runtime will occur. To resolve the warning, first copy the member into a local variable and call the method on that variable. The following sample generates CS1690: diff --git a/docs/csharp/language-reference/unsafe-code.md b/docs/csharp/language-reference/unsafe-code.md index 6e4d6fffc0eb7..b078952fe7bae 100644 --- a/docs/csharp/language-reference/unsafe-code.md +++ b/docs/csharp/language-reference/unsafe-code.md @@ -114,7 +114,7 @@ A `struct` can contain an embedded array in unsafe code. In the following exampl :::code language="csharp" source="snippets/unsafe-code/FixedKeywordExamples.cs" ID="7"::: -The size of the 128 element `char` array is 256 bytes. Fixed size [char](builtin-types/char.md) buffers always take 2 bytes per character, regardless of the encoding. This array size is the same even when char buffers are marshaled to API methods or structs with `CharSet = CharSet.Auto` or `CharSet = CharSet.Ansi`. For more information, see . +The size of the 128 element `char` array is 256 bytes. Fixed size [char](builtin-types/char.md) buffers always take 2 bytes per character, regardless of the encoding. This array size is the same even when char buffers are marshalled to API methods or structs with `CharSet = CharSet.Auto` or `CharSet = CharSet.Ansi`. For more information, see . The preceding example demonstrates accessing `fixed` fields without pinning, which is available starting with C# 7.3. diff --git a/docs/csharp/misc/cs0197.md b/docs/csharp/misc/cs0197.md index d2e225d1efa71..518c3f07f0192 100644 --- a/docs/csharp/misc/cs0197.md +++ b/docs/csharp/misc/cs0197.md @@ -12,7 +12,7 @@ ms.assetid: 2b5b1b8d-ce13-4bd7-b80a-abb80e9f79ad Passing 'argument' as ref or out or taking its address may cause a runtime exception because it is a field of a marshal-by-reference class - Any class that derives, directly or indirectly, from is a marshal-by-reference class. Such a class can be marshaled by reference across process and machine boundaries. Thus, instances of this class could be proxies to remote objects. You cannot pass a field of a proxy object as [ref](../language-reference/keywords/ref.md) or [out](../language-reference/keywords/out-parameter-modifier.md). So, you cannot pass fields of such a class as `ref` or `out`, unless the instance is [this](../language-reference/keywords/this.md), which can not be a proxy object. + Any class that derives, directly or indirectly, from is a marshal-by-reference class. Such a class can be marshalled by reference across process and machine boundaries. Thus, instances of this class could be proxies to remote objects. You cannot pass a field of a proxy object as [ref](../language-reference/keywords/ref.md) or [out](../language-reference/keywords/out-parameter-modifier.md). So, you cannot pass fields of such a class as `ref` or `out`, unless the instance is [this](../language-reference/keywords/this.md), which can not be a proxy object. ## Example diff --git a/docs/csharp/programming-guide/concepts/attributes/index.md b/docs/csharp/programming-guide/concepts/attributes/index.md index 1795b3c7816a7..bee194365ea05 100644 --- a/docs/csharp/programming-guide/concepts/attributes/index.md +++ b/docs/csharp/programming-guide/concepts/attributes/index.md @@ -29,7 +29,7 @@ A method with the attribute : diff --git a/docs/csharp/programming-guide/interop/how-to-use-platform-invoke-to-play-a-wave-file.md b/docs/csharp/programming-guide/interop/how-to-use-platform-invoke-to-play-a-wave-file.md index 09e649db528b0..9ade67944c015 100644 --- a/docs/csharp/programming-guide/interop/how-to-use-platform-invoke-to-play-a-wave-file.md +++ b/docs/csharp/programming-guide/interop/how-to-use-platform-invoke-to-play-a-wave-file.md @@ -41,4 +41,4 @@ The **Open Files** dialog box is filtered to show only files that have a .wav ex - [C# Programming Guide](../index.md) - [Interoperability Overview](interoperability-overview.md) - [A Closer Look at Platform Invoke](../../../framework/interop/consuming-unmanaged-dll-functions.md#a-closer-look-at-platform-invoke) -- [Marshaling Data with Platform Invoke](../../../framework/interop/marshaling-data-with-platform-invoke.md) +- [Marshalling Data with Platform Invoke](../../../framework/interop/marshalling-data-with-platform-invoke.md) diff --git a/docs/csharp/programming-guide/interop/interoperability-overview.md b/docs/csharp/programming-guide/interop/interoperability-overview.md index c02e92d7eb8f5..dd131edcbfe78 100644 --- a/docs/csharp/programming-guide/interop/interoperability-overview.md +++ b/docs/csharp/programming-guide/interop/interoperability-overview.md @@ -62,6 +62,6 @@ For more information, see [Consuming Unmanaged DLL Functions](../../../framework - [Improving Interop Performance](/previous-versions/msp-n-p/ff647812(v=pandp.10)) - [Introduction to Interoperability between COM and .NET](/office/client-developer/outlook/pia/introduction-to-interoperability-between-com-and-net) - [Introduction to COM Interop in Visual Basic](../../../visual-basic/programming-guide/com-interop/introduction-to-com-interop.md) -- [Marshaling between Managed and Unmanaged Code](../../../framework/interop/interop-marshaling.md) +- [Marshalling between Managed and Unmanaged Code](../../../framework/interop/interop-marshalling.md) - [Interoperating with Unmanaged Code](../../../framework/interop/index.md) - [C# Programming Guide](../index.md) diff --git a/docs/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element.md b/docs/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element.md index 3dfe7682f0656..c5e69e858185c 100644 --- a/docs/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element.md +++ b/docs/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element.md @@ -86,7 +86,7 @@ Defines one or more switches used by the class to provi |`Switch.System.Net.`
`DontEnableSchUseStrongCrypto`|Controls whether the and classes can use the SSL 3.0 protocol. For more information, see [Mitigation: TLS Protocols](../../../migration-guide/mitigation-tls-protocols.md).|.NET Framework 4.6| |`Switch.System.Net.`
`DontEnableSystemDefaultTlsVersions`|Disables SystemDefault TLS versions reverting back to a default of Tls12, Tls11, Tls.|.NET Framework 4.7| |`Switch.System.Net.`
`DontEnableTlsAlerts`|Disables SslStream TLS server-side Alerts.|.NET Framework 4.7| -|`Switch.System.Runtime.InteropServices.`
`DoNotMarshalOutByrefSafeArrayOnInvoke`|Controls whether ByRef SafeArray parameters on COM interop events marshal back to native code (`false`) or whether marshaling back to native code is disabled (`true`).|.NET Framework 4.8| +|`Switch.System.Runtime.InteropServices.`
`DoNotMarshalOutByrefSafeArrayOnInvoke`|Controls whether ByRef SafeArray parameters on COM interop events marshal back to native code (`false`) or whether marshalling back to native code is disabled (`true`).|.NET Framework 4.8| |`Switch.System.Runtime.Serialization.`
`DoNotUseECMAScriptV6EscapeControlCharacter` |Controls whether the [DataContractJsonSerializer](xref:System.Runtime.Serialization.Json.DataContractJsonSerializer) serializes some control characters based on the ECMAScript V6 and V8 standards. For more information, see [Mitigation: Serialization of Control Characters with the DataContractJsonSerializer](../../../migration-guide/mitigation-serialization-control-characters.md)| .NET Framework 4.7 | |`Switch.System.Runtime.Serialization.`
`DoNotUseTimeZoneInfo`|Controls whether the supports multiple adjustments or only a single adjustment for a time zone. If `true`, it uses the type to serialize and deserialize date and time data; otherwise, it uses the type, which does not support multiple adjustment rules.|.NET Framework 4.6.2| |`Switch.System.Runtime.Serialization.UseNewMaxArraySize`|Controls whether uses a larger array size during object serialization and deserialization. Set this switch to `true` to improve the performance of serialization and deserialization of large object graphs by types such as . |.NET Framework 4.7.2| diff --git a/docs/framework/configure-apps/file-schema/runtime/netfx40-pinvokestackresilience-element.md b/docs/framework/configure-apps/file-schema/runtime/netfx40-pinvokestackresilience-element.md index 6c51b32633ce9..b9aba7ab25ca5 100644 --- a/docs/framework/configure-apps/file-schema/runtime/netfx40-pinvokestackresilience-element.md +++ b/docs/framework/configure-apps/file-schema/runtime/netfx40-pinvokestackresilience-element.md @@ -35,7 +35,7 @@ The following sections describe attributes, child elements, and parent elements. |Value|Description| |-----------|-----------------| -|`0`|The runtime uses the faster interop marshaling architecture introduced in the .NET Framework 4, which does not detect and fix incorrect platform invoke declarations. This is the default.| +|`0`|The runtime uses the faster interop marshalling architecture introduced in the .NET Framework 4, which does not detect and fix incorrect platform invoke declarations. This is the default.| |`1`|The runtime uses slower transitions that detect and fix incorrect platform invoke declarations.| ### Child Elements @@ -51,9 +51,9 @@ None. ## Remarks -This element enables you to trade faster interop marshaling for run-time resilience against incorrect platform invoke declarations. +This element enables you to trade faster interop marshalling for run-time resilience against incorrect platform invoke declarations. -Starting with the .NET Framework 4, a streamlined interop marshaling architecture provides a significant performance improvement for transitions from managed code to unmanaged code. In earlier versions of the .NET Framework, the marshaling layer detected incorrect platform invoke declarations on 32-bit platforms and automatically fixed the stack. The new marshaling architecture eliminates this step. As a result, transitions are very fast, but an incorrect platform invoke declaration can cause a program failure. +Starting with the .NET Framework 4, a streamlined interop marshalling architecture provides a significant performance improvement for transitions from managed code to unmanaged code. In earlier versions of the .NET Framework, the marshalling layer detected incorrect platform invoke declarations on 32-bit platforms and automatically fixed the stack. The new marshalling architecture eliminates this step. As a result, transitions are very fast, but an incorrect platform invoke declaration can cause a program failure. To make it easy to detect incorrect declarations during development, the Visual Studio debugging experience has been improved. The [pInvokeStackImbalance](../../../debug-trace-profile/pinvokestackimbalance-mda.md) managed debugging assistant (MDA) notifies you of incorrect platform invoke declarations when your application is running with the debugger attached. diff --git a/docs/framework/configure-apps/file-schema/wcf/soapprocessing.md b/docs/framework/configure-apps/file-schema/wcf/soapprocessing.md index 49c1b0861c43c..8e441025ff0d8 100644 --- a/docs/framework/configure-apps/file-schema/wcf/soapprocessing.md +++ b/docs/framework/configure-apps/file-schema/wcf/soapprocessing.md @@ -30,7 +30,7 @@ The following sections describe attributes, child elements, and parent elements. | Attribute | Description | | ----------------- | ----------- | -| `processMessages` | A Boolean value that specifies whether messages should be marshaled between SOAP message versions. | +| `processMessages` | A Boolean value that specifies whether messages should be marshalled between SOAP message versions. | ### Child elements diff --git a/docs/framework/data/adonet/ole-db-data-type-mappings.md b/docs/framework/data/adonet/ole-db-data-type-mappings.md index a693c3846ee1d..c65890c6607b6 100644 --- a/docs/framework/data/adonet/ole-db-data-type-mappings.md +++ b/docs/framework/data/adonet/ole-db-data-type-mappings.md @@ -43,7 +43,7 @@ The following table shows the inferred .NET Framework type for data types from t |adUserDefined|DBTYPE_UDT|not supported|| |adVarNumeric|DBTYPE_VARNUMERIC|not supported|| - \* For the OLE DB types `DBTYPE_IUNKNOWN` and `DBTYPE_IDISPATCH`, the object reference is a marshaled representation of the pointer. + \* For the OLE DB types `DBTYPE_IUNKNOWN` and `DBTYPE_IDISPATCH`, the object reference is a marshalled representation of the pointer. ## See also diff --git a/docs/framework/data/adonet/secure-data-access.md b/docs/framework/data/adonet/secure-data-access.md index 34507644dc7fb..9f7f9db0936b0 100644 --- a/docs/framework/data/adonet/secure-data-access.md +++ b/docs/framework/data/adonet/secure-data-access.md @@ -88,7 +88,7 @@ To write secure ADO.NET code, you have to understand the security mechanisms ava |Resource|Description| |--------------|-----------------| |[Interoperating with Unmanaged Code](../../interop/index.md)|Contains topics describing how to expose COM components to the .NET Framework and how to expose .NET Framework components to COM.| -|[Advanced COM Interoperability](/previous-versions/dotnet/netframework-4.0/bd9cdfyx(v=vs.100))|Contains advanced topics such as primary interop assemblies, threading and custom marshaling.| +|[Advanced COM Interoperability](/previous-versions/dotnet/netframework-4.0/bd9cdfyx(v=vs.100))|Contains advanced topics such as primary interop assemblies, threading and custom marshalling.| ## See also diff --git a/docs/framework/data/transactions/transaction-management-escalation.md b/docs/framework/data/transactions/transaction-management-escalation.md index 896c192eb88d0..7a1df2c978672 100644 --- a/docs/framework/data/transactions/transaction-management-escalation.md +++ b/docs/framework/data/transactions/transaction-management-escalation.md @@ -24,7 +24,7 @@ Windows hosts a set of services and modules that together constitute a transacti - At least two durable resources that support single-phase notifications are enlisted in the transaction. For example, enlisting a single connection with SQL Server 2005 does not cause a transaction to be promoted. However, whenever you open a second connection to a SQL Server 2005 database causing the database to enlist, the infrastructure detects that it is the second durable resource in the transaction, and escalates it to an MSDTC transaction. -- A request to "marshal" the transaction to a different application domain or different process is invoked. For example, the serialization of the transaction object across an application domain boundary. The transaction object is marshaled-by-value, meaning that any attempt to pass it across an application domain boundary (even in the same process) results in serialization of the transaction object. You can pass the transaction objects by making a call on a remote method that takes a as a parameter or you can try to access a remote transactional-serviced component. This serializes the transaction object and results in an escalation, as when a transaction is serialized across an application domain. It is being distributed and the local transaction manager is no longer adequate. +- A request to "marshal" the transaction to a different application domain or different process is invoked. For example, the serialization of the transaction object across an application domain boundary. The transaction object is marshalled-by-value, meaning that any attempt to pass it across an application domain boundary (even in the same process) results in serialization of the transaction object. You can pass the transaction objects by making a call on a remote method that takes a as a parameter or you can try to access a remote transactional-serviced component. This serializes the transaction object and results in an escalation, as when a transaction is serialized across an application domain. It is being distributed and the local transaction manager is no longer adequate. The following table lists all the possible exceptions that can be thrown during escalation. diff --git a/docs/framework/debug-trace-profile/callbackoncollecteddelegate-mda.md b/docs/framework/debug-trace-profile/callbackoncollecteddelegate-mda.md index 887c53851c04c..01e76ada6a8aa 100644 --- a/docs/framework/debug-trace-profile/callbackoncollecteddelegate-mda.md +++ b/docs/framework/debug-trace-profile/callbackoncollecteddelegate-mda.md @@ -18,7 +18,7 @@ ms.assetid: 398b0ce0-5cc9-4518-978d-b8263aa21e5b --- # callbackOnCollectedDelegate MDA -The `callbackOnCollectedDelegate` managed debugging assistant (MDA) is activated if a delegate is marshaled from managed to unmanaged code as a function pointer and a callback is placed on that function pointer after the delegate has been garbage collected. +The `callbackOnCollectedDelegate` managed debugging assistant (MDA) is activated if a delegate is marshalled from managed to unmanaged code as a function pointer and a callback is placed on that function pointer after the delegate has been garbage collected. ## Symptoms @@ -32,15 +32,15 @@ The `callbackOnCollectedDelegate` managed debugging assistant (MDA) is activated The failure appears random because it depends on when garbage collection occurs. If a delegate is eligible for collection, the garbage collection can occur after the callback and the call succeeds. At other times, the garbage collection occurs before the callback, the callback generates an access violation, and the program stops. - The probability of the failure depends on the time between marshaling the delegate and the callback on the function pointer as well as the frequency of garbage collections. The failure is sporadic if the time between marshaling the delegate and the ensuing callback is short. This is usually the case if the unmanaged method receiving the function pointer does not save the function pointer for later use but instead calls back on the function pointer immediately to complete its operation before returning. Similarly, more garbage collections occur when a system is under heavy load, which makes it more likely that a garbage collection will occur before the callback. + The probability of the failure depends on the time between marshalling the delegate and the callback on the function pointer as well as the frequency of garbage collections. The failure is sporadic if the time between marshalling the delegate and the ensuing callback is short. This is usually the case if the unmanaged method receiving the function pointer does not save the function pointer for later use but instead calls back on the function pointer immediately to complete its operation before returning. Similarly, more garbage collections occur when a system is under heavy load, which makes it more likely that a garbage collection will occur before the callback. ## Resolution - Once a delegate has been marshaled out as an unmanaged function pointer, the garbage collector cannot track its lifetime. Instead, your code must keep a reference to the delegate for the lifetime of the unmanaged function pointer. But before you can do that, you first must identify which delegate was collected. When the MDA is activated, it provides the type name of the delegate. Use this name to search your code for platform invoke or COM signatures that pass that delegate out to unmanaged code. The offending delegate is passed out through one of these call sites. You can also enable the `gcUnmanagedToManaged` MDA to force a garbage collection before every callback into the runtime. This will remove the uncertainty introduced by the garbage collection by ensuring that a garbage collection always occurs before the callback. Once you know what delegate was collected, change your code to keep a reference to that delegate on the managed side for the lifetime of the marshaled unmanaged function pointer. + Once a delegate has been marshalled out as an unmanaged function pointer, the garbage collector cannot track its lifetime. Instead, your code must keep a reference to the delegate for the lifetime of the unmanaged function pointer. But before you can do that, you first must identify which delegate was collected. When the MDA is activated, it provides the type name of the delegate. Use this name to search your code for platform invoke or COM signatures that pass that delegate out to unmanaged code. The offending delegate is passed out through one of these call sites. You can also enable the `gcUnmanagedToManaged` MDA to force a garbage collection before every callback into the runtime. This will remove the uncertainty introduced by the garbage collection by ensuring that a garbage collection always occurs before the callback. Once you know what delegate was collected, change your code to keep a reference to that delegate on the managed side for the lifetime of the marshalled unmanaged function pointer. ## Effect on the Runtime - When delegates are marshaled as function pointers, the runtime allocates a thunk that does the transition from unmanaged to managed. This thunk is what the unmanaged code actually calls before the managed delegate is finally invoked. Without the `callbackOnCollectedDelegate` MDA enabled, the unmanaged marshaling code is deleted when the delegate is collected. With the `callbackOnCollectedDelegate` MDA enabled, the unmanaged marshaling code is not immediately deleted when the delegate is collected. Instead, the last 1,000 instances are kept alive by default and changed to activate the MDA when called. The thunk is eventually deleted after 1,001 more marshaled delegates are collected. + When delegates are marshalled as function pointers, the runtime allocates a thunk that does the transition from unmanaged to managed. This thunk is what the unmanaged code actually calls before the managed delegate is finally invoked. Without the `callbackOnCollectedDelegate` MDA enabled, the unmanaged marshalling code is deleted when the delegate is collected. With the `callbackOnCollectedDelegate` MDA enabled, the unmanaged marshalling code is not immediately deleted when the delegate is collected. Instead, the last 1,000 instances are kept alive by default and changed to activate the MDA when called. The thunk is eventually deleted after 1,001 more marshalled delegates are collected. ## Output @@ -116,5 +116,5 @@ public class Entry - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) - [gcUnmanagedToManaged](gcunmanagedtomanaged-mda.md) diff --git a/docs/framework/debug-trace-profile/contextswitchdeadlock-mda.md b/docs/framework/debug-trace-profile/contextswitchdeadlock-mda.md index d8a99d8a72073..2f3bf136d118e 100644 --- a/docs/framework/debug-trace-profile/contextswitchdeadlock-mda.md +++ b/docs/framework/debug-trace-profile/contextswitchdeadlock-mda.md @@ -69,4 +69,4 @@ A message describing the current context and the target context. - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/diagnosing-errors-with-managed-debugging-assistants.md b/docs/framework/debug-trace-profile/diagnosing-errors-with-managed-debugging-assistants.md index b28f808606714..63a6eeda86f19 100644 --- a/docs/framework/debug-trace-profile/diagnosing-errors-with-managed-debugging-assistants.md +++ b/docs/framework/debug-trace-profile/diagnosing-errors-with-managed-debugging-assistants.md @@ -162,7 +162,7 @@ The following example shows how to enable and configure the [marshaling](marshal ``` -The `Marshaling` MDA emits information about the managed type that is being marshaled to an unmanaged type for each managed-to-unmanaged transition in the application. The `Marshaling` MDA can also filter the names of the method and structure fields supplied in the **methodFilter** and **fieldFilter** child elements, respectively. +The `Marshaling` MDA emits information about the managed type that is being marshalled to an unmanaged type for each managed-to-unmanaged transition in the application. The `Marshaling` MDA can also filter the names of the method and structure fields supplied in the **methodFilter** and **fieldFilter** child elements, respectively. The following example shows how to enable multiple MDAs by using their default settings: diff --git a/docs/framework/debug-trace-profile/disconnectedcontext-mda.md b/docs/framework/debug-trace-profile/disconnectedcontext-mda.md index 777cd01e1b7b6..07cf431736b3a 100644 --- a/docs/framework/debug-trace-profile/disconnectedcontext-mda.md +++ b/docs/framework/debug-trace-profile/disconnectedcontext-mda.md @@ -49,4 +49,4 @@ The `disconnectedContext` managed debugging assistant (MDA) is activated when th - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/exceptionswallowedoncallfromcom-mda.md b/docs/framework/debug-trace-profile/exceptionswallowedoncallfromcom-mda.md index d599edf414d16..d4f22796ca933 100644 --- a/docs/framework/debug-trace-profile/exceptionswallowedoncallfromcom-mda.md +++ b/docs/framework/debug-trace-profile/exceptionswallowedoncallfromcom-mda.md @@ -49,4 +49,4 @@ The `exceptionSwallowedOnCallFromCOM` managed debugging assistant (MDA) is activ - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/failedqi-mda.md b/docs/framework/debug-trace-profile/failedqi-mda.md index a0f3e5935c156..342d7d59667a6 100644 --- a/docs/framework/debug-trace-profile/failedqi-mda.md +++ b/docs/framework/debug-trace-profile/failedqi-mda.md @@ -52,4 +52,4 @@ The `failedQI` managed debugging assistant (MDA) is activated when the runtime c - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/gcmanagedtounmanaged-mda.md b/docs/framework/debug-trace-profile/gcmanagedtounmanaged-mda.md index 5a5e68920283c..92c21def87e0a 100644 --- a/docs/framework/debug-trace-profile/gcmanagedtounmanaged-mda.md +++ b/docs/framework/debug-trace-profile/gcmanagedtounmanaged-mda.md @@ -52,5 +52,5 @@ The `gcManagedToUnmanaged` managed debugging assistant (MDA) causes a garbage co - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) - [gcUnmanagedToManaged](gcunmanagedtomanaged-mda.md) diff --git a/docs/framework/debug-trace-profile/gcunmanagedtomanaged-mda.md b/docs/framework/debug-trace-profile/gcunmanagedtomanaged-mda.md index 2d6d2f133cb77..80d140217a429 100644 --- a/docs/framework/debug-trace-profile/gcunmanagedtomanaged-mda.md +++ b/docs/framework/debug-trace-profile/gcunmanagedtomanaged-mda.md @@ -53,4 +53,4 @@ The `gcUnmanagedToManaged` managed debugging assistant (MDA) causes a garbage co - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) - [gcManagedToUnmanaged](gcmanagedtounmanaged-mda.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/illegalprepareconstrainedregion-mda.md b/docs/framework/debug-trace-profile/illegalprepareconstrainedregion-mda.md index 8ba69f3d206a1..00aad6146bec7 100644 --- a/docs/framework/debug-trace-profile/illegalprepareconstrainedregion-mda.md +++ b/docs/framework/debug-trace-profile/illegalprepareconstrainedregion-mda.md @@ -69,4 +69,4 @@ void MethodWithInvalidPCR() - - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/invalidapartmentstatechange-mda.md b/docs/framework/debug-trace-profile/invalidapartmentstatechange-mda.md index e56c351d7bbaf..96fe0c31bcd7e 100644 --- a/docs/framework/debug-trace-profile/invalidapartmentstatechange-mda.md +++ b/docs/framework/debug-trace-profile/invalidapartmentstatechange-mda.md @@ -23,7 +23,7 @@ The `invalidApartmentStateChange` managed debugging assistant (MDS) is activated ## Symptoms -- A thread's COM apartment state is not what was requested. This may cause proxies to be used for COM components that have a threading model different from the current one. This in turn may cause an to be thrown when calling the COM object through interfaces that are not set up for cross-apartment marshaling. +- A thread's COM apartment state is not what was requested. This may cause proxies to be used for COM components that have a threading model different from the current one. This in turn may cause an to be thrown when calling the COM object through interfaces that are not set up for cross-apartment marshalling. - The COM apartment state of the thread is different than expected. This can cause a with an HRESULT of RPC_E_WRONG_THREAD as well as a when making calls on a [Runtime Callable Wrapper](../../standard/native-interop/runtime-callable-wrapper.md) (RCW). This can also cause some single-threaded COM components to be accessed by multiple threads at the same time, which can lead to corruption or data loss. @@ -79,4 +79,4 @@ namespace ApartmentStateMDA - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/invalidfunctionpointerindelegate-mda.md b/docs/framework/debug-trace-profile/invalidfunctionpointerindelegate-mda.md index 20554d277ee0d..d7b57bfa843e2 100644 --- a/docs/framework/debug-trace-profile/invalidfunctionpointerindelegate-mda.md +++ b/docs/framework/debug-trace-profile/invalidfunctionpointerindelegate-mda.md @@ -8,8 +8,8 @@ helpviewer_keywords: - "MDAs (managed debugging assistants), invalid function pointer to delegates" - "function pointers, invalid" - "marshaling, run-time errors" - - "managed debugging assistants (MDAs), marshaling" - - "MDAs (managed debugging assistants), marshaling" + - "managed debugging assistants (MDAs), marshalling" + - "MDAs (managed debugging assistants), marshalling" - "invalid function pointers" ms.assetid: 99ae44f1-783e-49a9-9009-24f54bbd0f09 --- @@ -51,4 +51,4 @@ The `invalidFunctionPointerInDelegate` managed debugging assistant (MDA) is acti - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/invalidgchandlecookie-mda.md b/docs/framework/debug-trace-profile/invalidgchandlecookie-mda.md index 5137f3c32d891..803eaae6b55ed 100644 --- a/docs/framework/debug-trace-profile/invalidgchandlecookie-mda.md +++ b/docs/framework/debug-trace-profile/invalidgchandlecookie-mda.md @@ -20,7 +20,7 @@ The `invalidGCHandleCookie` managed debugging assistant (MDA) is activated when ## Cause - The cookie is probably invalid because it was not originally created from a , represents a that has already been freed, is a cookie to a in a different application domain, or was marshaled to native code as a but passed back into the CLR as an , where a cast was attempted. + The cookie is probably invalid because it was not originally created from a , represents a that has already been freed, is a cookie to a in a different application domain, or was marshalled to native code as a but passed back into the CLR as an , where a cast was attempted. ## Resolution diff --git a/docs/framework/debug-trace-profile/invalidiunknown-mda.md b/docs/framework/debug-trace-profile/invalidiunknown-mda.md index 349854b7c5a77..19835a6b6429d 100644 --- a/docs/framework/debug-trace-profile/invalidiunknown-mda.md +++ b/docs/framework/debug-trace-profile/invalidiunknown-mda.md @@ -16,7 +16,7 @@ The `invalidIUnknown` managed debugging assistant (MDA) is activated when an inv ## Symptoms - An unexpected error occurs when marshaling a COM interface pointer during argument marshaling. + An unexpected error occurs when marshalling a COM interface pointer during argument marshalling. ## Cause @@ -48,4 +48,4 @@ The `invalidIUnknown` managed debugging assistant (MDA) is activated when an inv - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/invalidmemberdeclaration-mda.md b/docs/framework/debug-trace-profile/invalidmemberdeclaration-mda.md index 8061132b48cb0..912f2e4e7f9ae 100644 --- a/docs/framework/debug-trace-profile/invalidmemberdeclaration-mda.md +++ b/docs/framework/debug-trace-profile/invalidmemberdeclaration-mda.md @@ -6,8 +6,8 @@ helpviewer_keywords: - "invalid member declaration" - "InvalidMemberDeclaration MDA" - "marshaling, run-time errors" - - "managed debugging assistants (MDAs), marshaling" - - "MDAs (managed debugging assistants), marshaling" + - "managed debugging assistants (MDAs), marshalling" + - "MDAs (managed debugging assistants), marshalling" ms.assetid: a84dd9a3-d6cf-4824-989a-ecbbf443eeb4 --- # invalidMemberDeclaration MDA @@ -48,4 +48,4 @@ The `invalidMemberDeclaration` managed debugging assistant (MDA) is activated to - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/invalidoverlappedtopinvoke-mda.md b/docs/framework/debug-trace-profile/invalidoverlappedtopinvoke-mda.md index 843a35fc5dadc..b8aca0ac78ea9 100644 --- a/docs/framework/debug-trace-profile/invalidoverlappedtopinvoke-mda.md +++ b/docs/framework/debug-trace-profile/invalidoverlappedtopinvoke-mda.md @@ -75,4 +75,4 @@ The `invalidOverlappedToPinvoke` managed debugging assistant (MDA) is activated - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/invalidvariant-mda.md b/docs/framework/debug-trace-profile/invalidvariant-mda.md index a40f2044d3a14..85dd63285e665 100644 --- a/docs/framework/debug-trace-profile/invalidvariant-mda.md +++ b/docs/framework/debug-trace-profile/invalidvariant-mda.md @@ -16,7 +16,7 @@ The `invalidVariant` managed debugging assistant (MDA) is activated when an inva ## Symptoms - Unexpected behavior during a transition between native and managed code involving the marshaling of a `VARIANT` to an object. + Unexpected behavior during a transition between native and managed code involving the marshalling of a `VARIANT` to an object. ## Cause @@ -48,4 +48,4 @@ The `invalidVariant` managed debugging assistant (MDA) is activated when an inva - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/jitcompilationstart-mda.md b/docs/framework/debug-trace-profile/jitcompilationstart-mda.md index 01123c139d587..613995dbe34e8 100644 --- a/docs/framework/debug-trace-profile/jitcompilationstart-mda.md +++ b/docs/framework/debug-trace-profile/jitcompilationstart-mda.md @@ -162,4 +162,4 @@ namespace ns2 - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/marshalcleanuperror-mda.md b/docs/framework/debug-trace-profile/marshalcleanuperror-mda.md index 7a1c02c24a320..b21131153c20b 100644 --- a/docs/framework/debug-trace-profile/marshalcleanuperror-mda.md +++ b/docs/framework/debug-trace-profile/marshalcleanuperror-mda.md @@ -5,8 +5,8 @@ ms.date: "03/30/2017" helpviewer_keywords: - "cleanup operations" - "marshaling, run-time errors" - - "managed debugging assistants (MDAs), marshaling" - - "MDAs (managed debugging assistants), marshaling" + - "managed debugging assistants (MDAs), marshalling" + - "MDAs (managed debugging assistants), marshalling" - "marshaling cleanup error" - "MarshalCleanupError MDA" - "memory, cleanup errors" @@ -14,7 +14,7 @@ ms.assetid: 2f5d9e7c-ae51-4155-a435-54347aa1f091 --- # marshalCleanupError MDA -The `marshalCleanupError` managed debugging assistant (MDA) is activated when the common language runtime (CLR) encounters an error while attempting to clean up temporary structures and memory used for marshaling data types between native and managed code boundaries. +The `marshalCleanupError` managed debugging assistant (MDA) is activated when the common language runtime (CLR) encounters an error while attempting to clean up temporary structures and memory used for marshalling data types between native and managed code boundaries. ## Symptoms @@ -26,7 +26,7 @@ The `marshalCleanupError` managed debugging assistant (MDA) is activated when th ## Resolution - Review all destructor, finalizer, and custom marshaler implementations for errors. + Review all destructor, finalizer, and custom marshaller implementations for errors. ## Effect on the Runtime @@ -50,4 +50,4 @@ The `marshalCleanupError` managed debugging assistant (MDA) is activated when th - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/marshaling-mda.md b/docs/framework/debug-trace-profile/marshaling-mda.md index 03dd52c6deebb..dc84031e089f9 100644 --- a/docs/framework/debug-trace-profile/marshaling-mda.md +++ b/docs/framework/debug-trace-profile/marshaling-mda.md @@ -1,9 +1,9 @@ --- title: "marshaling MDA" -description: Review the marshaling managed debugging assistant (MDA), which is invoked if the CLR sets up marshaling information for a method parameter or a structure field. +description: Review the marshaling managed debugging assistant (MDA), which is invoked if the CLR sets up marshalling information for a method parameter or a structure field. ms.date: "03/30/2017" helpviewer_keywords: - - "marshaling, run-time errors" + - "marshalling, run-time errors" - "marshaling MDA" - "managed debugging assistants (MDAs), marshaling" - "MDAs (managed debugging assistants), marshaling" @@ -11,15 +11,15 @@ ms.assetid: 5433b1f8-b0e5-40c9-a49a-0e5bd213363d --- # marshaling MDA -The `marshaling` managed debugging assistant (MDA) is activated when the CLR sets up marshaling information for a method parameter or a field of a structure. This MDA does not work for JIT-compiled assemblies. +The `marshaling` managed debugging assistant (MDA) is activated when the CLR sets up marshalling information for a method parameter or a field of a structure. This MDA does not work for JIT-compiled assemblies. ## Effect on the Runtime - This MDA has no effect on the CLR. +This MDA has no effect on the CLR. ## Output - The MDA displays the type of the parameter or field in the managed and unmanaged contexts, and the structure or method containing the type. The following is an example of the output for a field: +The MDA displays the type of the parameter or field in the managed and unmanaged contexts, and the structure or method containing the type. The following is an example of the output for a field: ```output Marshaling from 'Char' to 'ANSI char' @@ -28,7 +28,7 @@ name="assembly!Namespace.Class::myChar ## Configuration - The MDA configuration allows you to filter the reported marshaling information based on the involved field or method names. The following example shows the use of the `methodFilter`, `fieldFilter`, and `match` elements to specify filters. Setting the `name` attribute to an asterisk (\*) will match everything. +The MDA configuration allows you to filter the reported marshalling information based on the involved field or method names. The following example shows the use of the `methodFilter`, `fieldFilter`, and `match` elements to specify filters. Setting the `name` attribute to an asterisk (\*) will match everything. ```xml @@ -51,4 +51,4 @@ name="assembly!Namespace.Class::myChar - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshalling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/noncomvisiblebaseclass-mda.md b/docs/framework/debug-trace-profile/noncomvisiblebaseclass-mda.md index 06d3117159cf2..b05b463205eaf 100644 --- a/docs/framework/debug-trace-profile/noncomvisiblebaseclass-mda.md +++ b/docs/framework/debug-trace-profile/noncomvisiblebaseclass-mda.md @@ -57,4 +57,4 @@ constrained by the COM versioning rules. - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/notmarshalable-mda.md b/docs/framework/debug-trace-profile/notmarshalable-mda.md index ededc8b4be333..d27cce570c505 100644 --- a/docs/framework/debug-trace-profile/notmarshalable-mda.md +++ b/docs/framework/debug-trace-profile/notmarshalable-mda.md @@ -7,9 +7,9 @@ helpviewer_keywords: - "interface pointer not marshalable MDA" - "MDAs (managed debugging assistants), interface pointer not marshalable" - "marshaling, run-time errors" - - "managed debugging assistants (MDAs), marshaling" + - "managed debugging assistants (MDAs), marshalling" - "marshalable interface pointers" - - "MDAs (managed debugging assistants), marshaling" + - "MDAs (managed debugging assistants), marshalling" - "notMarshalable MDA" ms.assetid: 96e7b2c1-843f-4d64-b519-740c3a18b50a --- @@ -51,4 +51,4 @@ The `notMarshalable` managed debugging assistant (MDA) is activated when the com - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/overlappedfreeerror-mda.md b/docs/framework/debug-trace-profile/overlappedfreeerror-mda.md index f53dfed451c3a..a6d7e6584c679 100644 --- a/docs/framework/debug-trace-profile/overlappedfreeerror-mda.md +++ b/docs/framework/debug-trace-profile/overlappedfreeerror-mda.md @@ -53,4 +53,4 @@ The `overlappedFreeError` managed debugging assistant (MDA) is activated when th - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/performance-counters.md b/docs/framework/debug-trace-profile/performance-counters.md index 07b7d32cb72cc..6a629998e11ab 100644 --- a/docs/framework/debug-trace-profile/performance-counters.md +++ b/docs/framework/debug-trace-profile/performance-counters.md @@ -32,8 +32,8 @@ This article provides a list of performance counters you can find in the [Window |Performance counter|Description| |-------------------------|-----------------| |**# of CCWs**|Displays the current number of COM callable wrappers (CCWs). A CCW is a proxy for a managed object being referenced from an unmanaged COM client. This counter indicates the number of managed objects referenced by unmanaged COM code.| -|**# of marshaling**|Displays the total number of times arguments and return values have been marshaled from managed to unmanaged code, and vice versa, since the application started. This counter is not incremented if the stubs are inlined. (Stubs are responsible for marshaling arguments and return values). Stubs are usually inlined if the marshaling overhead is small.| -|**# of Stubs**|Displays the current number of stubs created by the common language runtime. Stubs are responsible for marshaling arguments and return values from managed to unmanaged code, and vice versa, during a COM interop call or a platform invoke call.| +|**# of marshalling**|Displays the total number of times arguments and return values have been marshalled from managed to unmanaged code, and vice versa, since the application started. This counter is not incremented if the stubs are inlined. (Stubs are responsible for marshalling arguments and return values). Stubs are usually inlined if the marshalling overhead is small.| +|**# of Stubs**|Displays the current number of stubs created by the common language runtime. Stubs are responsible for marshalling arguments and return values from managed to unmanaged code, and vice versa, during a COM interop call or a platform invoke call.| |**# of TLB exports / sec**|Reserved for future use.| |**# of TLB imports / sec**|Reserved for future use.| diff --git a/docs/framework/debug-trace-profile/pinvokestackimbalance-mda.md b/docs/framework/debug-trace-profile/pinvokestackimbalance-mda.md index bbe8fe755d790..77e152d067ed2 100644 --- a/docs/framework/debug-trace-profile/pinvokestackimbalance-mda.md +++ b/docs/framework/debug-trace-profile/pinvokestackimbalance-mda.md @@ -57,4 +57,4 @@ The MDA message gives the name of the platform invoke method call that is causin - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/raceonrcwcleanup-mda.md b/docs/framework/debug-trace-profile/raceonrcwcleanup-mda.md index 330bcd0ddf305..d5986ec203114 100644 --- a/docs/framework/debug-trace-profile/raceonrcwcleanup-mda.md +++ b/docs/framework/debug-trace-profile/raceonrcwcleanup-mda.md @@ -49,4 +49,4 @@ The `raceOnRCWCleanup` managed debugging assistant (MDA) is activated when the c - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/releasehandlefailed-mda.md b/docs/framework/debug-trace-profile/releasehandlefailed-mda.md index c5bf90dbc989e..957b864786ca4 100644 --- a/docs/framework/debug-trace-profile/releasehandlefailed-mda.md +++ b/docs/framework/debug-trace-profile/releasehandlefailed-mda.md @@ -40,7 +40,7 @@ The `releaseHandleFailed` managed debugging assistant (MDA) is activated is to n - Ensure that the code that is used to initialize the with a valid raw handle value owns the handle. If you form a around a handle your code does not own without setting the `ownsHandle` parameter to `false` in the base constructor, then both the and the real handle owner can try to close the handle, leading to an error in if the loses the race. -- When a is marshaled between application domains, confirm the derivation being used has been marked as serializable. In the rare cases where a class derived from has been made serializable, it should implement the interface or use one of the other techniques for controlling the serialization and deserialization process manually. This is required because the default serialization action is to create a bitwise clone of the enclosed raw handle value, resulting in two instances thinking they own the same handle. Both will try to call on the same handle at some point. The second to do this will fail. The correct course of action when serializing a is to call the `DuplicateHandle` function or a similar function for your native handle type to make a distinct legal handle copy. If your handle type does not support this then the type wrapping it cannot be made serializable. +- When a is marshalled between application domains, confirm the derivation being used has been marked as serializable. In the rare cases where a class derived from has been made serializable, it should implement the interface or use one of the other techniques for controlling the serialization and deserialization process manually. This is required because the default serialization action is to create a bitwise clone of the enclosed raw handle value, resulting in two instances thinking they own the same handle. Both will try to call on the same handle at some point. The second to do this will fail. The correct course of action when serializing a is to call the `DuplicateHandle` function or a similar function for your native handle type to make a distinct legal handle copy. If your handle type does not support this then the type wrapping it cannot be made serializable. - It may be possible to track where a handle is being closed early, leading to a failure when the method is finally called, by placing a debugger breakpoint on the native routine used to release the handle, for example the `CloseHandle` function. This may not be possible for stress scenarios or even medium-sized functional tests due to the heavy traffic such routines often deal with. It may help to instrument the code that calls the native release method, in order to capture the identity of the caller, or possibly a full stack trace, and the value of the handle being released. The handle value can be compared with the value reported by this MDA. @@ -94,4 +94,4 @@ bool ReleaseHandle() - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/reportavoncomrelease-mda.md b/docs/framework/debug-trace-profile/reportavoncomrelease-mda.md index 6fd9780d0707b..498348fdbffa8 100644 --- a/docs/framework/debug-trace-profile/reportavoncomrelease-mda.md +++ b/docs/framework/debug-trace-profile/reportavoncomrelease-mda.md @@ -51,4 +51,4 @@ The `reportAvOnComRelease` managed debugging assistant (MDA) is activated when e - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/debug-trace-profile/virtualcercall-mda.md b/docs/framework/debug-trace-profile/virtualcercall-mda.md index f2351c740bca6..51cc795d09a64 100644 --- a/docs/framework/debug-trace-profile/virtualcercall-mda.md +++ b/docs/framework/debug-trace-profile/virtualcercall-mda.md @@ -98,4 +98,4 @@ void MethodWithCer(MyClass object) - - [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md) -- [Interop Marshaling](../interop/interop-marshaling.md) +- [Interop Marshaling](../interop/interop-marshalling.md) diff --git a/docs/framework/interop/blittable-and-non-blittable-types.md b/docs/framework/interop/blittable-and-non-blittable-types.md index 3834248ac72d6..e822af5a435bd 100644 --- a/docs/framework/interop/blittable-and-non-blittable-types.md +++ b/docs/framework/interop/blittable-and-non-blittable-types.md @@ -3,13 +3,13 @@ title: "Blittable and Non-Blittable Types" description: Learn about blittable and non-blittable types. Blittable data types are commonly represented in managed and unmanaged memory and don't need special handling. ms.date: "03/30/2017" helpviewer_keywords: - - "interop marshaling, blittable types" - - "blittable types, interop marshaling" + - "interop marshalling, blittable types" + - "blittable types, interop marshalling" ms.assetid: d03b050e-2916-49a0-99ba-f19316e5c1b3 --- # Blittable and Non-Blittable Types -Most data types have a common representation in both managed and unmanaged memory and do not require special handling by the interop marshaler. These types are called *blittable types* because they do not require conversion when they are passed between managed and unmanaged code. +Most data types have a common representation in both managed and unmanaged memory and do not require special handling by the interop marshaller. These types are called *blittable types* because they do not require conversion when they are passed between managed and unmanaged code. Structures that are returned from platform invoke calls must be blittable types. Platform invoke does not support non-blittable structures as return types. @@ -43,30 +43,30 @@ Most data types have a common representation in both managed and unmanaged memor - One-dimensional arrays of blittable primitive types, such as an array of integers. However, a type that contains a variable array of blittable types is not itself blittable. -- Formatted value types that contain only blittable types (and classes if they are marshaled as formatted types). For more information about formatted value types, see [Default marshaling for value types](default-marshaling-behavior.md#default-marshaling-for-value-types). +- Formatted value types that contain only blittable types (and classes if they are marshalled as formatted types). For more information about formatted value types, see [Default marshalling for value types](default-marshalling-behavior.md#default-marshalling-for-value-types). Object references are not blittable. This includes an array of references to objects that are blittable by themselves. For example, you can define a structure that is blittable, but you cannot define a blittable type that contains an array of references to those structures. - As an optimization, arrays of blittable primitive types and classes that contain only blittable members are [pinned](copying-and-pinning.md) instead of copied during marshaling. These types can appear to be marshaled as In/Out parameters when the caller and callee are in the same apartment. However, these types are actually marshaled as In parameters, and you must apply the and attributes if you want to marshal the argument as an In/Out parameter. + As an optimization, arrays of blittable primitive types and classes that contain only blittable members are [pinned](copying-and-pinning.md) instead of copied during marshalling. These types can appear to be marshalled as In/Out parameters when the caller and callee are in the same apartment. However, these types are actually marshalled as In parameters, and you must apply the and attributes if you want to marshal the argument as an In/Out parameter. - Some managed data types require a different representation in an unmanaged environment. These non-blittable data types must be converted into a form that can be marshaled. For example, managed strings are non-blittable types because they must be converted into string objects before they can be marshaled. + Some managed data types require a different representation in an unmanaged environment. These non-blittable data types must be converted into a form that can be marshalled. For example, managed strings are non-blittable types because they must be converted into string objects before they can be marshalled. - The following table lists non-blittable types from the namespace. [Delegates](default-marshaling-behavior.md#default-marshaling-for-delegates), which are data structures that refer to a static method or to a class instance, are also non-blittable. + The following table lists non-blittable types from the namespace. [Delegates](default-marshalling-behavior.md#default-marshalling-for-delegates), which are data structures that refer to a static method or to a class instance, are also non-blittable. |Non-blittable type|Description| -|-------------------------|-----------------| -|[System.Array](default-marshaling-for-arrays.md)|Converts to a C-style array or a `SAFEARRAY`.| +|-------------------------|-----------------| +|[System.Array](default-marshalling-for-arrays.md)|Converts to a C-style array or a `SAFEARRAY`.| |[System.Boolean](/previous-versions/dotnet/netframework-4.0/t2t3725f(v=vs.100))|Converts to a 1, 2, or 4-byte value with `true` as 1 or -1.| |[System.Char](/previous-versions/dotnet/netframework-4.0/6tyybbf2(v=vs.100))|Converts to a Unicode or ANSI character.| |[System.Class](/previous-versions/dotnet/netframework-4.0/s0968xy8(v=vs.100))|Converts to a class interface.| -|[System.Object](default-marshaling-for-objects.md)|Converts to a variant or an interface.| -|[System.Mdarray](default-marshaling-for-arrays.md)|Converts to a C-style array or a `SAFEARRAY`.| -|[System.String](default-marshaling-for-strings.md)|Converts to a string terminating in a null reference or to a BSTR.| +|[System.Object](default-marshalling-for-objects.md)|Converts to a variant or an interface.| +|[System.Mdarray](default-marshalling-for-arrays.md)|Converts to a C-style array or a `SAFEARRAY`.| +|[System.String](default-marshalling-for-strings.md)|Converts to a string terminating in a null reference or to a BSTR.| |[System.Valuetype](/previous-versions/dotnet/netframework-4.0/0t2cwe11(v=vs.100))|Converts to a structure with a fixed memory layout.| -|[System.Szarray](default-marshaling-for-arrays.md)|Converts to a C-style array or a `SAFEARRAY`.| +|[System.Szarray](default-marshalling-for-arrays.md)|Converts to a C-style array or a `SAFEARRAY`.| Class and object types are supported only by COM interop. For corresponding types in Visual Basic, C#, and C++, see the [Class Library Overview](../../standard/class-library-overview.md). ## See also -- [Default Marshaling Behavior](default-marshaling-behavior.md) +- [Default Marshalling Behavior](default-marshalling-behavior.md) diff --git a/docs/framework/interop/calling-a-dll-function.md b/docs/framework/interop/calling-a-dll-function.md index 05b9e8ce7872f..857170c2e3153 100644 --- a/docs/framework/interop/calling-a-dll-function.md +++ b/docs/framework/interop/calling-a-dll-function.md @@ -33,5 +33,5 @@ Although calling unmanaged DLL functions is nearly identical to calling other ma [Consuming Unmanaged DLL Functions](consuming-unmanaged-dll-functions.md) Describes how to call unmanaged DLL functions using platform invoke. - [Marshaling Data with Platform Invoke](marshaling-data-with-platform-invoke.md) + [Marshalling Data with Platform Invoke](marshalling-data-with-platform-invoke.md) Describes how to declare method parameters and pass arguments to functions exported by unmanaged libraries. diff --git a/docs/framework/interop/consuming-unmanaged-dll-functions.md b/docs/framework/interop/consuming-unmanaged-dll-functions.md index f8d75f40fe9fb..d3b3177a2bac6 100644 --- a/docs/framework/interop/consuming-unmanaged-dll-functions.md +++ b/docs/framework/interop/consuming-unmanaged-dll-functions.md @@ -43,7 +43,7 @@ Platform invoke is a service that enables managed code to call unmanaged functio Call the method on your managed class as you would any other managed method. [Passing structures](passing-structures.md) and [implementing callback functions](callback-functions.md) are special cases. - For examples that demonstrate how to construct .NET-based declarations to be used with platform invoke, see [Marshaling Data with Platform Invoke](marshaling-data-with-platform-invoke.md). + For examples that demonstrate how to construct .NET-based declarations to be used with platform invoke, see [Marshalling Data with Platform Invoke](marshalling-data-with-platform-invoke.md). ## A closer look at platform invoke @@ -57,7 +57,7 @@ Platform invoke is a service that enables managed code to call unmanaged functio 2. Loads the DLL into memory. -3. Locates the address of the function in memory and pushes its arguments onto the stack, marshaling data as required. +3. Locates the address of the function in memory and pushes its arguments onto the stack, marshalling data as required. > [!NOTE] > Locating and loading the DLL, and locating the address of the function in memory occur only on the first call to the function. @@ -70,4 +70,4 @@ Platform invoke is a service that enables managed code to call unmanaged functio - [Interoperating with Unmanaged Code](index.md) - [Platform Invoke Examples](platform-invoke-examples.md) -- [Interop Marshaling](interop-marshaling.md) +- [Interop Marshaling](interop-marshalling.md) diff --git a/docs/framework/interop/copying-and-pinning.md b/docs/framework/interop/copying-and-pinning.md index e975c671014df..4c1f04159ee4c 100644 --- a/docs/framework/interop/copying-and-pinning.md +++ b/docs/framework/interop/copying-and-pinning.md @@ -1,29 +1,29 @@ --- title: "Copying and Pinning" -description: Review how the interop marshaler can copy or pin data that's being marshaled. Copying data places a copy of data from one memory location into another location. +description: Review how the interop marshaller can copy or pin data that's being marshalled. Copying data places a copy of data from one memory location into another location. ms.date: "03/30/2017" helpviewer_keywords: - - "pinning, interop marshaling" - - "copying, interop marshaling" - - "interop marshaling, copying" - - "interop marshaling, pinning" + - "pinning, interop marshalling" + - "copying, interop marshalling" + - "interop marshalling, copying" + - "interop marshalling, pinning" ms.assetid: 0059f576-e460-4e70-b257-668870e420b8 --- # Copying and Pinning -When marshaling data, the interop marshaler can copy or pin the data being marshaled. Copying the data places a copy of data from one memory location in another memory location. The following illustration shows the differences between copying a value type and copying a type passed by reference from managed to unmanaged memory. +When marshalling data, the interop marshallercan copy or pin the data being marshalled. Copying the data places a copy of data from one memory location in another memory location. The following illustration shows the differences between copying a value type and copying a type passed by reference from managed to unmanaged memory. ![Diagram that shows how value and reference types are copied.](./media/copying-and-pinning/interop-marshal-copy.gif) -Method arguments passed by value are marshaled to unmanaged code as values on the stack. The copying process is direct. Arguments passed by reference are passed as pointers on the stack. Reference types are also passed by value and by reference. As the following illustration shows, reference types passed by value are either copied or pinned: +Method arguments passed by value are marshalled to unmanaged code as values on the stack. The copying process is direct. Arguments passed by reference are passed as pointers on the stack. Reference types are also passed by value and by reference. As the following illustration shows, reference types passed by value are either copied or pinned: ![Diagram showing reference types passed by value and by reference.](./media/copying-and-pinning/interop-marshal-reference-pin.gif) -Pinning temporarily locks the data in its current memory location, thus keeping it from being relocated by the common language runtime's garbage collector. The marshaler pins data to reduce the overhead of copying and enhance performance. The type of the data determines whether it is copied or pinned during the marshaling process. Pinning is automatically performed during marshaling for objects such as , however you can also manually pin memory using the class. +Pinning temporarily locks the data in its current memory location, thus keeping it from being relocated by the common language runtime's garbage collector. The marshaller pins data to reduce the overhead of copying and enhance performance. The type of the data determines whether it is copied or pinned during the marshalling process. Pinning is automatically performed during marshalling for objects such as , however you can also manually pin memory using the class. ## Formatted Blittable Classes -Formatted [blittable](blittable-and-non-blittable-types.md) classes have fixed layout (formatted) and common data representation in both managed and unmanaged memory. When these types require marshaling, a pointer to the object in the heap is passed to the callee directly. The callee can change the contents of the memory location being referenced by the pointer. +Formatted [blittable](blittable-and-non-blittable-types.md) classes have fixed layout (formatted) and common data representation in both managed and unmanaged memory. When these types require marshalling, a pointer to the object in the heap is passed to the callee directly. The callee can change the contents of the memory location being referenced by the pointer. > [!NOTE] > The callee can change the memory contents if the parameter is marked Out or In/Out. In contrast, the callee should avoid changing the contents when the parameter is set to marshal as In, which is the default for formatted blittable types. Modifying an In object generates problems when the same class is exported to a type library and used to make cross-apartment calls. @@ -32,15 +32,15 @@ Formatted [blittable](blittable-and-non-blittable-types.md) classes have fixed l Formatted [non-blittable](blittable-and-non-blittable-types.md) classes have fixed layout (formatted) but the data representation is different in managed and unmanaged memory. The data can require transformation under the following conditions: -- If a non-blittable class is marshaled by value, the callee receives a pointer to a copy of the data structure. +- If a non-blittable class is marshalled by value, the callee receives a pointer to a copy of the data structure. -- If a non-blittable class is marshaled by reference, the callee receives a pointer to a pointer to a copy of the data structure. +- If a non-blittable class is marshalled by reference, the callee receives a pointer to a pointer to a copy of the data structure. -- If the attribute is set, this copy is always initialized with the instance's state, marshaling as necessary. +- If the attribute is set, this copy is always initialized with the instance's state, marshalling as necessary. -- If the attribute is set, the state is always copied back to the instance on return, marshaling as necessary. +- If the attribute is set, the state is always copied back to the instance on return, marshalling as necessary. -- If both **InAttribute** and **OutAttribute** are set, both copies are required. If either attribute is omitted, the marshaler can optimize by eliminating either copy. +- If both **InAttribute** and **OutAttribute** are set, both copies are required. If either attribute is omitted, the marshaller can optimize by eliminating either copy. ## Reference Types @@ -54,27 +54,27 @@ Reference types have the following conditional behavior: - On return from the call. - To avoid unnecessarily copying and conversion, these types are marshaled as In parameters. You must explicitly apply the **InAttribute** and **OutAttribute** attributes to an argument for the caller to see changes made by the callee. + To avoid unnecessarily copying and conversion, these types are marshalled as In parameters. You must explicitly apply the **InAttribute** and **OutAttribute** attributes to an argument for the caller to see changes made by the callee. -- If a reference type is passed by value and it has only members of blittable types, it can be pinned during marshaling and any changes made to the members of the type by the callee are seen by the caller. Apply **InAttribute** and **OutAttribute** explicitly if you want this behavior. Without these directional attributes, the interop marshaler does not export directional information to the type library (it exports as In, which is the default) and this can cause problems with COM cross-apartment marshaling. +- If a reference type is passed by value and it has only members of blittable types, it can be pinned during marshalling and any changes made to the members of the type by the callee are seen by the caller. Apply **InAttribute** and **OutAttribute** explicitly if you want this behavior. Without these directional attributes, the interop marshallerdoes not export directional information to the type library (it exports as In, which is the default) and this can cause problems with COM cross-apartment marshalling. -- If a reference type is passed by reference, it will be marshaled as In/Out by default. +- If a reference type is passed by reference, it will be marshalled as In/Out by default. ## System.String and System.Text.StringBuilder -When data is marshaled to unmanaged code by value or by reference, the marshaler typically copies the data to a secondary buffer (possibly converting character sets during the copy) and passes a reference to the buffer to the callee. Unless the reference is a **BSTR** allocated with **SysAllocString**, the reference is always allocated with **CoTaskMemAlloc**. +When data is marshalled to unmanaged code by value or by reference, the marshallertypically copies the data to a secondary buffer (possibly converting character sets during the copy) and passes a reference to the buffer to the callee. Unless the reference is a **BSTR** allocated with **SysAllocString**, the reference is always allocated with **CoTaskMemAlloc**. -As an optimization when either string type is marshaled by value (such as a Unicode character string), the marshaler passes the callee a direct pointer to managed strings in the internal Unicode buffer instead of copying it to a new buffer. +As an optimization when either string type is marshalled by value (such as a Unicode character string), the marshallerpasses the callee a direct pointer to managed strings in the internal Unicode buffer instead of copying it to a new buffer. > [!CAUTION] -> When a string is passed by value, the callee must never alter the reference passed by the marshaler. Doing so can corrupt the managed heap. +> When a string is passed by value, the callee must never alter the reference passed by the marshaller. Doing so can corrupt the managed heap. -When a is passed by reference, the marshaler copies the contents the string to a secondary buffer before making the call. It then copies the contents of the buffer into a new string on return from the call. This technique ensures that the immutable managed string remains unaltered. +When a is passed by reference, the marshaller copies the contents the string to a secondary buffer before making the call. It then copies the contents of the buffer into a new string on return from the call. This technique ensures that the immutable managed string remains unaltered. -When a is passed by value, the marshaler passes a reference to a temporary copy of the internal buffer of the **StringBuilder** to the caller. The caller and callee must agree on the size of the buffer. The caller is responsible for creating a **StringBuilder** of adequate length. The callee must take the necessary precautions to ensure that the buffer is not overrun. **StringBuilder** is an exception to the rule that reference types passed by value are passed as In parameters by default. It is always passed as In/Out. +When a is passed by value, the marshaller passes a reference to a temporary copy of the internal buffer of the **StringBuilder** to the caller. The caller and callee must agree on the size of the buffer. The caller is responsible for creating a **StringBuilder** of adequate length. The callee must take the necessary precautions to ensure that the buffer is not overrun. **StringBuilder** is an exception to the rule that reference types passed by value are passed as In parameters by default. It is always passed as In/Out. ## See also -- [Default Marshaling Behavior](default-marshaling-behavior.md) +- [Default Marshalling Behavior](default-marshalling-behavior.md) - [Directional Attributes](/previous-versions/dotnet/netframework-4.0/77e6taeh(v=vs.100)) -- [Interop Marshaling](interop-marshaling.md) +- [Interop Marshaling](interop-marshalling.md) diff --git a/docs/framework/interop/creating-a-class-to-hold-dll-functions.md b/docs/framework/interop/creating-a-class-to-hold-dll-functions.md index 19844a42813f9..dece1592efd4c 100644 --- a/docs/framework/interop/creating-a-class-to-hold-dll-functions.md +++ b/docs/framework/interop/creating-a-class-to-hold-dll-functions.md @@ -28,7 +28,7 @@ Wrapping a frequently used DLL function in a managed class is an effective appro - Create one class for a set of related DLL functions to form logical groupings and reduce overhead. - You can name the class and its methods as you please. For examples that demonstrate how to construct .NET-based declarations to be used with platform invoke, see [Marshaling Data with Platform Invoke](marshaling-data-with-platform-invoke.md). + You can name the class and its methods as you please. For examples that demonstrate how to construct .NET-based declarations to be used with platform invoke, see [Marshalling Data with Platform Invoke](marshalling-data-with-platform-invoke.md). ## See also diff --git a/docs/framework/interop/creating-prototypes-in-managed-code.md b/docs/framework/interop/creating-prototypes-in-managed-code.md index e3e15704db774..949f2a0a08dfb 100644 --- a/docs/framework/interop/creating-prototypes-in-managed-code.md +++ b/docs/framework/interop/creating-prototypes-in-managed-code.md @@ -22,7 +22,7 @@ ms.assetid: ecdcf25d-cae3-4f07-a2b6-8397ac6dc42d # Creating Prototypes in Managed Code -This topic describes how to access unmanaged functions and introduces several attribute fields that annotate method definition in managed code. For examples that demonstrate how to construct .NET-based declarations to be used with platform invoke, see [Marshaling Data with Platform Invoke](marshaling-data-with-platform-invoke.md). +This topic describes how to access unmanaged functions and introduces several attribute fields that annotate method definition in managed code. For examples that demonstrate how to construct .NET-based declarations to be used with platform invoke, see [Marshalling Data with Platform Invoke](marshalling-data-with-platform-invoke.md). Before you can access an unmanaged DLL function from managed code, you need to know the name of the function and the name of the DLL that exports it. With this information, you can begin to write the managed definition for an unmanaged function that is implemented in a DLL. Furthermore, you can adjust the way that platform invoke creates the function and marshals data to and from the function. @@ -90,7 +90,7 @@ extern "C" int MessageBox( |-----------|-----------------| ||Enables or disables best-fit mapping.| ||Specifies the calling convention to use in passing method arguments. The default is `WinAPI`, which corresponds to `__stdcall` for the 32-bit Intel-based platforms.| -||Controls name mangling and the way that string arguments should be marshaled to the function. The default is `CharSet.Ansi`.| +||Controls name mangling and the way that string arguments should be marshalled to the function. The default is `CharSet.Ansi`.| ||Specifies the DLL entry point to be called.| ||Controls whether an entry point should be modified to correspond to the character set. The default value varies by programming language.| ||Controls whether the managed method signature should be transformed into an unmanaged signature that returns an HRESULT and has an additional [out, retval] argument for the return value.

The default is `true` (the signature should not be transformed).| diff --git a/docs/framework/interop/default-marshaling-behavior.md b/docs/framework/interop/default-marshalling-behavior.md similarity index 62% rename from docs/framework/interop/default-marshaling-behavior.md rename to docs/framework/interop/default-marshalling-behavior.md index abfd5ac038008..c6637a4c62b31 100644 --- a/docs/framework/interop/default-marshaling-behavior.md +++ b/docs/framework/interop/default-marshalling-behavior.md @@ -1,28 +1,28 @@ --- -title: "Default Marshaling Behavior" -description: Learn default marshaling behavior in .NET. Review memory management with interop marshaling, and see default marshaling for classes, delegates, and value types. +title: "Default Marshalling Behavior" +description: Learn default marshalling behavior in .NET. Review memory management with interop marshalling, and see default marshalling for classes, delegates, and value types. ms.date: "06/26/2018" dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "interop marshaling, default" - - "interoperation with unmanaged code, marshaling" + - "interop marshalling, default" + - "interoperation with unmanaged code, marshalling" - "marshaling behavior" ms.assetid: c0a9bcdf-3df8-4db3-b1b6-abbdb2af809a --- -# Default Marshaling Behavior +# Default Marshalling Behavior -Interop marshaling operates on rules that dictate how data associated with method parameters behaves as it passes between managed and unmanaged memory. These built-in rules control such marshaling activities as data type transformations, whether a callee can change data passed to it and return those changes to the caller, and under which circumstances the marshaler provides performance optimizations. +Interop marshalling operates on rules that dictate how data associated with method parameters behaves as it passes between managed and unmanaged memory. These built-in rules control such marshalling activities as data type transformations, whether a callee can change data passed to it and return those changes to the caller, and under which circumstances the m marshallerrovides performance optimizations. - This section identifies the default behavioral characteristics of the interop marshaling service. It presents detailed information on marshaling arrays, Boolean types, char types, delegates, classes, objects, strings, and structures. + This section identifies the default behavioral characteristics of the interop marshalling service. It presents detailed information on marshalling arrays, Boolean types, char types, delegates, classes, objects, strings, and structures. > [!NOTE] -> Marshaling of generic types is not supported. For more information see, [Interoperating Using Generic Types](/previous-versions/dotnet/netframework-4.0/ms229590(v=vs.100)). +> Marshalling of generic types is not supported. For more information see, [Interoperating Using Generic Types](/previous-versions/dotnet/netframework-4.0/ms229590(v=vs.100)). -## Memory management with the interop marshaler +## Memory management with the interop marshaller - The interop marshaler always attempts to free memory allocated by unmanaged code. This behavior complies with COM memory management rules, but differs from the rules that govern native C++. + The interop marshaller always attempts to free memory allocated by unmanaged code. This behavior complies with COM memory management rules, but differs from the rules that govern native C++. Confusion can arise if you anticipate native C++ behavior (no memory freeing) when using platform invoke, which automatically frees memory for pointers. For example, calling the following unmanaged method from a C++ DLL does not automatically free any memory. @@ -34,49 +34,49 @@ BSTR MethodOne (BSTR b) { } ``` - However, if you define the method as a platform invoke prototype, replace each **BSTR** type with a type, and call `MethodOne`, the common language runtime attempts to free `b` twice. You can change the marshaling behavior by using types rather than **String** types. + However, if you define the method as a platform invoke prototype, replace each **BSTR** type with a type, and call `MethodOne`, the common language runtime attempts to free `b` twice. You can change the marshalling behavior by using types rather than **String** types. The runtime always uses the **CoTaskMemFree** method to free memory. If the memory you are working with was not allocated with the **CoTaskMemAlloc** method, you must use an **IntPtr** and free the memory manually using the appropriate method. Similarly, you can avoid automatic memory freeing in situations where memory should never be freed, such as when using the **GetCommandLine** function from Kernel32.dll, which returns a pointer to kernel memory. For details on manually freeing memory, see the [Buffers Sample](/previous-versions/dotnet/netframework-4.0/x3txb6xc(v=vs.100)). -## Default marshaling for classes +## Default marshalling for classes - Classes can be marshaled only by COM interop and are always marshaled as interfaces. In some cases the interface used to marshal the class is known as the class interface. For information about overriding the class interface with an interface of your choice, see [Introducing the class interface](../../standard/native-interop/com-callable-wrapper.md#introducing-the-class-interface). + Classes can be marshalled only by COM interop and are always marshalled as interfaces. In some cases the interface used to marshal the class is known as the class interface. For information about overriding the class interface with an interface of your choice, see [Introducing the class interface](../../standard/native-interop/com-callable-wrapper.md#introducing-the-class-interface). ### Passing Classes to COM - When a managed class is passed to COM, the interop marshaler automatically wraps the class with a COM proxy and passes the class interface produced by the proxy to the COM method call. The proxy then delegates all calls on the class interface back to the managed object. The proxy also exposes other interfaces that are not explicitly implemented by the class. The proxy automatically implements interfaces such as **IUnknown** and **IDispatch** on behalf of the class. + When a managed class is passed to COM, the interop marshaller automatically wraps the class with a COM proxy and passes the class interface produced by the proxy to the COM method call. The proxy then delegates all calls on the class interface back to the managed object. The proxy also exposes other interfaces that are not explicitly implemented by the class. The proxy automatically implements interfaces such as **IUnknown** and **IDispatch** on behalf of the class. ### Passing Classes to .NET Code Coclasses are not typically used as method arguments in COM. Instead, a default interface is usually passed in place of the coclass. - When an interface is passed into managed code, the interop marshaler is responsible for wrapping the interface with the proper wrapper and passing the wrapper to the managed method. Determining which wrapper to use can be difficult. Every instance of a COM object has a single, unique wrapper, no matter how many interfaces the object implements. For example, a single COM object that implements five distinct interfaces has only one wrapper. The same wrapper exposes all five interfaces. If two instances of the COM object are created, then two instances of the wrapper are created. + When an interface is passed into managed code, the interop marshaller is responsible for wrapping the interface with the proper wrapper and passing the wrapper to the managed method. Determining which wrapper to use can be difficult. Every instance of a COM object has a single, unique wrapper, no matter how many interfaces the object implements. For example, a single COM object that implements five distinct interfaces has only one wrapper. The same wrapper exposes all five interfaces. If two instances of the COM object are created, then two instances of the wrapper are created. - For the wrapper to maintain the same type throughout its lifetime, the interop marshaler must identify the correct wrapper the first time an interface exposed by the object is passed through the marshaler. The marshaler identifies the object by looking at one of the interfaces the object implements. + For the wrapper to maintain the same type throughout its lifetime, the interop marshaller must identify the correct wrapper the first time an interface exposed by the object is passed through the marshaller. The marshaller identifies the object by looking at one of the interfaces the object implements. - For example, the marshaler determines that the class wrapper should be used to wrap the interface that was passed into managed code. When the interface is first passed through the marshaler, the marshaler checks whether the interface is coming from a known object. This check occurs in two situations: + For example, the marshaller determines that the class wrapper should be used to wrap the interface that was passed into managed code. When the interface is first passed through the marshaller, the marshaller checks whether the interface is coming from a known object. This check occurs in two situations: -- An interface is being implemented by another managed object that was passed to COM elsewhere. The marshaler can readily identify interfaces exposed by managed objects and is able to match the interface with the managed object that provides the implementation. The managed object is then passed to the method and no wrapper is needed. +- An interface is being implemented by another managed object that was passed to COM elsewhere. The marshaller can readily identify interfaces exposed by managed objects and is able to match the interface with the managed object that provides the implementation. The managed object is then passed to the method and no wrapper is needed. -- An object that has already been wrapped is implementing the interface. To determine whether this is the case, the marshaler queries the object for its **IUnknown** interface and compares the returned interface to the interfaces of other objects that are already wrapped. If the interface is the same as that of another wrapper, the objects have the same identity and the existing wrapper is passed to the method. +- An object that has already been wrapped is implementing the interface. To determine whether this is the case, the marshaller queries the object for its **IUnknown** interface and compares the returned interface to the interfaces of other objects that are already wrapped. If the interface is the same as that of another wrapper, the objects have the same identity and the existing wrapper is passed to the method. - If an interface is not from a known object, the marshaler does the following: + If an interface is not from a known object, the marshaller does the following: -1. The marshaler queries the object for the **IProvideClassInfo2** interface. If provided, the marshaler uses the CLSID returned from **IProvideClassInfo2.GetGUID** to identify the coclass providing the interface. With the CLSID, the marshaler can locate the wrapper from the registry if the assembly has previously been registered. +1. The marshaller queries the object for the **IProvideClassInfo2** interface. If provided, the marshaller uses the CLSID returned from **IProvideClassInfo2.GetGUID** to identify the coclass providing the interface. With the CLSID, the marshaller can locate the wrapper from the registry if the assembly has previously been registered. -2. The marshaler queries the interface for the **IProvideClassInfo** interface. If provided, the marshaler uses the **ITypeInfo** returned from **IProvideClassInfo.GetClassinfo** to determine the CLSID of the class exposing the interface. The marshaler can use the CLSID to locate the metadata for the wrapper. +2. The marshaller queries the interface for the **IProvideClassInfo** interface. If provided, the marshaller uses the **ITypeInfo** returned from **IProvideClassInfo.GetClassinfo** to determine the CLSID of the class exposing the interface. The marshaller can use the CLSID to locate the metadata for the wrapper. -3. If the marshaler still cannot identify the class, it wraps the interface with a generic wrapper class called **System.__ComObject**. +3. If the marshaller still cannot identify the class, it wraps the interface with a generic wrapper class called **System.__ComObject**. -## Default marshaling for delegates +## Default marshalling for delegates - A managed delegate is marshaled as a COM interface or as a function pointer, based on the calling mechanism: + A managed delegate is marshalled as a COM interface or as a function pointer, based on the calling mechanism: -- For platform invoke, a delegate is marshaled as an unmanaged function pointer by default. +- For platform invoke, a delegate is marshalled as an unmanaged function pointer by default. -- For COM interop, a delegate is marshaled as a COM interface of type **_Delegate** by default. The **_Delegate** interface is defined in the Mscorlib.tlb type library and contains the method, which enables you to call the method that the delegate references. +- For COM interop, a delegate is marshalled as a COM interface of type **_Delegate** by default. The **_Delegate** interface is defined in the Mscorlib.tlb type library and contains the method, which enables you to call the method that the delegate references. - The following table shows the marshaling options for the managed delegate data type. The attribute provides several enumeration values to marshal delegates. + The following table shows the marshalling options for the managed delegate data type. The attribute provides several enumeration values to marshal delegates. |Enumeration type|Description of unmanaged format| |----------------------|-------------------------------------| @@ -113,7 +113,7 @@ interface DelegateTest : IDispatch { A function pointer can be dereferenced, just as any other unmanaged function pointer can be dereferenced. -In this example, when the two delegates are marshaled as , the result is an `int` and a pointer to an `int`. Because delegate types are being marshaled, `int` here represents a pointer to a void (`void*`), which is the address of the delegate in memory. In other words, this result is specific to 32-bit Windows systems, since `int` here represents the size of the function pointer. +In this example, when the two delegates are marshalled as , the result is an `int` and a pointer to an `int`. Because delegate types are being marshalled, `int` here represents a pointer to a void (`void*`), which is the address of the delegate in memory. In other words, this result is specific to 32-bit Windows systems, since `int` here represents the size of the function pointer. > [!NOTE] > A reference to the function pointer to a managed delegate held by unmanaged code does not prevent the common language runtime from performing garbage collection on the managed object. @@ -160,9 +160,9 @@ internal class DelegateTest { } ``` -## Default marshaling for value types +## Default marshalling for value types - Most value types, such as integers and floating-point numbers, are [blittable](blittable-and-non-blittable-types.md) and do not require marshaling. Other [non-blittable](blittable-and-non-blittable-types.md) types have dissimilar representations in managed and unmanaged memory and do require marshaling. Still other types require explicit formatting across the interoperation boundary. + Most value types, such as integers and floating-point numbers, are [blittable](blittable-and-non-blittable-types.md) and do not require marshalling. Other [non-blittable](blittable-and-non-blittable-types.md) types have dissimilar representations in managed and unmanaged memory and do require marshalling. Still other types require explicit formatting across the interoperation boundary. This section provides information on the following formatted value types: @@ -170,7 +170,7 @@ internal class DelegateTest { - [Value Types Used in COM Interop](#value-types-used-in-com-interop) - In addition to describing formatted types, this topic identifies [System Value Types](#system-value-types) that have unusual marshaling behavior. + In addition to describing formatted types, this topic identifies [System Value Types](#system-value-types) that have unusual marshalling behavior. A formatted type is a complex type that contains information that explicitly controls the layout of its members in memory. The member layout information is provided using the attribute. The layout can be one of the following enumeration values: @@ -221,7 +221,7 @@ public struct Rect { } ``` - When marshaled to unmanaged code, these formatted types are marshaled as C-style structures. This provides an easy way of calling an unmanaged API that has structure arguments. For example, the `POINT` and `RECT` structures can be passed to the Microsoft Windows API **PtInRect** function as follows: + When marshalled to unmanaged code, these formatted types are marshalled as C-style structures. This provides an easy way of calling an unmanaged API that has structure arguments. For example, the `POINT` and `RECT` structures can be passed to the Microsoft Windows API **PtInRect** function as follows: ```cpp BOOL PtInRect(const RECT *lprc, POINT pt); @@ -247,9 +247,9 @@ internal static class NativeMethods The `Rect` value type must be passed by reference because the unmanaged API is expecting a pointer to a `RECT` to be passed to the function. The `Point` value type is passed by value because the unmanaged API expects the `POINT` to be passed on the stack. This subtle difference is very important. References are passed to unmanaged code as pointers. Values are passed to unmanaged code on the stack. > [!NOTE] -> When a formatted type is marshaled as a structure, only the fields within the type are accessible. If the type has methods, properties, or events, they are inaccessible from unmanaged code. +> When a formatted type is marshalled as a structure, only the fields within the type are accessible. If the type has methods, properties, or events, they are inaccessible from unmanaged code. - Classes can also be marshaled to unmanaged code as C-style structures, provided they have fixed member layout. The member layout information for a class is also provided with the attribute. The main difference between value types with fixed layout and classes with fixed layout is the way in which they are marshaled to unmanaged code. Value types are passed by value (on the stack) and consequently any changes made to the members of the type by the callee are not seen by the caller. Reference types are passed by reference (a reference to the type is passed on the stack); consequently, all changes made to blittable-type members of a type by the callee are seen by the caller. + Classes can also be marshalled to unmanaged code as C-style structures, provided they have fixed member layout. The member layout information for a class is also provided with the attribute. The main difference between value types with fixed layout and classes with fixed layout is the way in which they are marshalled to unmanaged code. Value types are passed by value (on the stack) and consequently any changes made to the members of the type by the callee are not seen by the caller. Reference types are passed by reference (a reference to the type is passed on the stack); consequently, all changes made to blittable-type members of a type by the callee are seen by the caller. > [!NOTE] > If a reference type has members of non-blittable types, conversion is required twice: the first time when an argument is passed to the unmanaged side and the second time on return from the call. Due to this added overhead, In/Out parameters must be explicitly applied to an argument if the caller wants to see changes made by the callee. @@ -308,7 +308,7 @@ internal static class NativeMethods Notice that the `SystemTime` argument is not typed as a reference argument because `SystemTime` is a class, not a value type. Unlike value types, classes are always passed by reference. - The following code example shows a different `Point` class that has a method called `SetXY`. Because the type has sequential layout, it can be passed to unmanaged code and marshaled as a structure. However, the `SetXY` member is not callable from unmanaged code, even though the object is passed by reference. + The following code example shows a different `Point` class that has a method called `SetXY`. Because the type has sequential layout, it can be passed to unmanaged code and marshalled as a structure. However, the `SetXY` member is not callable from unmanaged code, even though the object is passed by reference. ```vb Public Class Point @@ -350,14 +350,14 @@ interface _Graphics { } ``` - The same rules used to marshal values and references to platform invoke calls are used when marshaling through COM interfaces. For example, when an instance of the `Point` value type is passed from the .NET Framework to COM, the `Point` is passed by value. If the `Point` value type is passed by reference, a pointer to a `Point` is passed on the stack. The interop marshaler does not support higher levels of indirection (**Point** \*\*) in either direction. + The same rules used to marshal values and references to platform invoke calls are used when marshalling through COM interfaces. For example, when an instance of the `Point` value type is passed from the .NET Framework to COM, the `Point` is passed by value. If the `Point` value type is passed by reference, a pointer to a `Point` is passed on the stack. The interop marshallerdoes not support higher levels of indirection (**Point** \*\*) in either direction. > [!NOTE] > Structures having the enumeration value set to **Explicit** cannot be used in COM interop because the exported type library cannot express an explicit layout. ### System Value Types - The namespace has several value types that represent the boxed form of the runtime primitive types. For example, the value type structure represents the boxed form of **ELEMENT_TYPE_I4**. Instead of marshaling these types as structures, as other formatted types are, you marshal them in the same way as the primitive types they box. **System.Int32** is therefore marshaled as **ELEMENT_TYPE_I4** instead of as a structure containing a single member of type **long**. The following table contains a list of the value types in the **System** namespace that are boxed representations of primitive types. + The namespace has several value types that represent the boxed form of the runtime primitive types. For example, the value type structure represents the boxed form of **ELEMENT_TYPE_I4**. Instead of marshalling these types as structures, as other formatted types are, you marshal them in the same way as the primitive types they box. **System.Int32** is therefore marshalled as **ELEMENT_TYPE_I4** instead of as a structure containing a single member of type **long**. The following table contains a list of the value types in the **System** namespace that are boxed representations of primitive types. |System value type|Element type| |-----------------------|------------------| @@ -377,7 +377,7 @@ interface _Graphics { ||**ELEMENT_TYPE_I**| ||**ELEMENT_TYPE_U**| - Some other value types in the **System** namespace are handled differently. Because the unmanaged code already has well-established formats for these types, the marshaler has special rules for marshaling them. The following table lists the special value types in the **System** namespace, as well as the unmanaged type they are marshaled to. + Some other value types in the **System** namespace are handled differently. Because the unmanaged code already has well-established formats for these types, the marshaller has special rules for marshalling them. The following table lists the special value types in the **System** namespace, as well as the unmanaged type they are marshalled to. |System value type|IDL type| |-----------------------|--------------| @@ -446,6 +446,6 @@ interface IValueTypes : IDispatch { - [Blittable and Non-Blittable Types](blittable-and-non-blittable-types.md) - [Copying and Pinning](copying-and-pinning.md) -- [Default Marshaling for Arrays](default-marshaling-for-arrays.md) -- [Default Marshaling for Objects](default-marshaling-for-objects.md) -- [Default Marshaling for Strings](default-marshaling-for-strings.md) +- [Default Marshalling for Arrays](default-marshalling-for-arrays.md) +- [Default Marshalling for Objects](default-marshalling-for-objects.md) +- [Default Marshalling for Strings](default-marshalling-for-strings.md) diff --git a/docs/framework/interop/default-marshaling-for-arrays.md b/docs/framework/interop/default-marshalling-for-arrays.md similarity index 78% rename from docs/framework/interop/default-marshaling-for-arrays.md rename to docs/framework/interop/default-marshalling-for-arrays.md index fa3ab9689badc..9a9b9ff99f4f5 100644 --- a/docs/framework/interop/default-marshaling-for-arrays.md +++ b/docs/framework/interop/default-marshalling-for-arrays.md @@ -1,18 +1,18 @@ --- -title: "Default Marshaling for Arrays" -description: Understand default marshaling for arrays. Review managed arrays, unmanaged arrays, passing array parameters to .NET code, and passing arrays to COM. +title: "Default Marshalling for Arrays" +description: Understand default marshalling for arrays. Review managed arrays, unmanaged arrays, passing array parameters to .NET code, and passing arrays to COM. ms.date: "03/30/2017" dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "interop marshaling, arrays" - - "arrays, interop marshaling" + - "interop marshalling, arrays" + - "arrays, interop marshalling" ms.assetid: 8a3cca8b-dd94-4e3d-ad9a-9ee7590654bc --- -# Default Marshaling for Arrays +# Default Marshalling for Arrays -In an application consisting entirely of managed code, the common language runtime passes array types as In/Out parameters. In contrast, the interop marshaler passes an array as In parameters by default. +In an application consisting entirely of managed code, the common language runtime passes array types as In/Out parameters. In contrast, the interop marshaller passes an array as In parameters by default. With [pinning optimization](copying-and-pinning.md), a blittable array can appear to operate as an In/Out parameter when interacting with objects in the same apartment. However, if you later export the code to a type library used to generate the cross-machine proxy, and that library is used to marshal your calls across apartments, the calls can revert to true In parameter behavior. @@ -34,7 +34,7 @@ In an application consisting entirely of managed code, the common language runti ## Unmanaged Arrays - Unmanaged arrays are either COM-style safe arrays or C-style arrays with fixed or variable length. Safe arrays are self-describing arrays that carry the type, rank, and bounds of the associated array data. C-style arrays are one-dimensional typed arrays with a fixed lower bound of 0. The marshaling service has limited support for both types of arrays. + Unmanaged arrays are either COM-style safe arrays or C-style arrays with fixed or variable length. Safe arrays are self-describing arrays that carry the type, rank, and bounds of the associated array data. C-style arrays are one-dimensional typed arrays with a fixed lower bound of 0. The marshalling service has limited support for both types of arrays. ## Passing Array Parameters to .NET Code @@ -42,7 +42,7 @@ In an application consisting entirely of managed code, the common language runti |Unmanaged type|Imported type| |--------------------|-------------------| -|**SafeArray(** *Type* **)**|**ELEMENT_TYPE_SZARRAY** **\<** *ConvertedType* **>**

Rank = 1, lower bound = 0. Size is known only if provided in the managed signature. Safe arrays that are not rank = 1 or lower bound = 0 cannot be marshaled as **SZARRAY**.| +|**SafeArray(** *Type* **)**|**ELEMENT_TYPE_SZARRAY** **\<** *ConvertedType* **>**

Rank = 1, lower bound = 0. Size is known only if provided in the managed signature. Safe arrays that are not rank = 1 or lower bound = 0 cannot be marshalled as **SZARRAY**.| |*Type* **[]**|**ELEMENT_TYPE_SZARRAY** **\<** *ConvertedType* **>**

Rank = 1, lower bound = 0. Size is known only if provided in the managed signature.| ### Safe Arrays @@ -78,7 +78,7 @@ void New3([MarshalAs(UnmanagedType.SafeArray, SafeArraySubType=VT_BSTR)] ref String[] ar); ``` - Multidimensional, or nonzero-bound safe arrays, can be marshaled into managed code if the method signature produced by Tlbimp.exe is modified to indicate an element type of **ELEMENT_TYPE_ARRAY** instead of **ELEMENT_TYPE_SZARRAY**. Alternatively, you can use the **/sysarray** switch with Tlbimp.exe to import all arrays as objects. In cases where the array being passed is known to be multidimensional, you can edit the Microsoft intermediate language (MSIL) code produced by Tlbimp.exe and then recompile it. For details about how to modify MSIL code, see [Customizing Runtime Callable Wrappers](/previous-versions/dotnet/netframework-4.0/e753eftz(v=vs.100)). + Multidimensional, or nonzero-bound safe arrays, can be marshalled into managed code if the method signature produced by Tlbimp.exe is modified to indicate an element type of **ELEMENT_TYPE_ARRAY** instead of **ELEMENT_TYPE_SZARRAY**. Alternatively, you can use the **/sysarray** switch with Tlbimp.exe to import all arrays as objects. In cases where the array being passed is known to be multidimensional, you can edit the Microsoft intermediate language (MSIL) code produced by Tlbimp.exe and then recompile it. For details about how to modify MSIL code, see [Customizing Runtime Callable Wrappers](/previous-versions/dotnet/netframework-4.0/e753eftz(v=vs.100)). ### C-Style Arrays @@ -86,7 +86,7 @@ void New3([MarshalAs(UnmanagedType.SafeArray, SafeArraySubType=VT_BSTR)] The array element type is determined from the type library and preserved during the import. The same conversion rules that apply to parameters also apply to array elements. For example, an array of **LPStr** types becomes an array of **String** types. Tlbimp.exe captures the array element type and applies the attribute to the parameter. - The array rank is assumed to equal 1. If the rank is greater than 1, the array is marshaled as a one-dimensional array in column-major order. The lower bound always equals 0. + The array rank is assumed to equal 1. If the rank is greater than 1, the array is marshalled as a one-dimensional array in column-major order. The lower bound always equals 0. Type libraries can contain arrays of fixed or variable length. Tlbimp.exe can import only fixed-length arrays from type libraries because type libraries lack the information needed to marshal variable-length arrays. With fixed-length arrays, the size is imported from the type library and captured in the **MarshalAsAttribute** that is applied to the parameter. @@ -119,7 +119,7 @@ void New2([MarshalAs(UnmanagedType.LPArray, ArraySubType=UnmanagedType.LPWStr, SizeConst=10)] String[] ar); ``` - Although you can apply the **size_is** or **length_is** attributes to an array in Interface Definition Language (IDL) source to convey the size to a client, the Microsoft Interface Definition Language (MIDL) compiler does not propagate that information to the type library. Without knowing the size, the interop marshaling service cannot marshal the array elements. Consequently, variable-length arrays are imported as reference arguments. For example: + Although you can apply the **size_is** or **length_is** attributes to an array in Interface Definition Language (IDL) source to convey the size to a client, the Microsoft Interface Definition Language (MIDL) compiler does not propagate that information to the type library. Without knowing the size, the interop marshalling service cannot marshal the array elements. Consequently, variable-length arrays are imported as reference arguments. For example: **Unmanaged signature** @@ -143,7 +143,7 @@ void New2(ref double ar); void New3(ref String ar); ``` - You can provide the marshaler with the array size by editing the Microsoft intermediate language (MSIL) code produced by Tlbimp.exe and then recompiling it. For details about how to modify MSIL code, see [Customizing Runtime Callable Wrappers](/previous-versions/dotnet/netframework-4.0/e753eftz(v=vs.100)). To indicate the number of elements in the array, apply the type to the array parameter of the managed method definition in one of the following ways: + You can provide the marshaller with the array size by editing the Microsoft intermediate language (MSIL) code produced by Tlbimp.exe and then recompiling it. For details about how to modify MSIL code, see [Customizing Runtime Callable Wrappers](/previous-versions/dotnet/netframework-4.0/e753eftz(v=vs.100)). To indicate the number of elements in the array, apply the type to the array parameter of the managed method definition in one of the following ways: - Identify another parameter that contains the number of elements in the array. The parameters are identified by position, starting with the first parameter as number 0. @@ -171,12 +171,12 @@ void New3(ref String ar); [MarshalAs(UnmanagedType.LPArray, SizeConst=128)] int[] ar ); ``` - When marshaling arrays from unmanaged code to managed code, the marshaler checks the **MarshalAsAttribute** associated with the parameter to determine the array size. If the array size is not specified, only one element is marshaled. + When marshalling arrays from unmanaged code to managed code, the marshallerchecks the **MarshalAsAttribute** associated with the parameter to determine the array size. If the array size is not specified, only one element is marshalled. > [!NOTE] -> The **MarshalAsAttribute** has no effect on marshaling managed arrays to unmanaged code. In that direction, the array size is determined by examination. There is no way to marshal a subset of a managed array. +> The **MarshalAsAttribute** has no effect on marshalling managed arrays to unmanaged code. In that direction, the array size is determined by examination. There is no way to marshal a subset of a managed array. - The interop marshaler uses the **CoTaskMemAlloc** and **CoTaskMemFree** methods to allocate and retrieve memory. Memory allocation performed by unmanaged code must also use these methods. + The interop marshaller uses the **CoTaskMemAlloc** and **CoTaskMemFree** methods to allocate and retrieve memory. Memory allocation performed by unmanaged code must also use these methods. ## Passing Arrays to COM @@ -188,7 +188,7 @@ void New3(ref String ar); |**ELEMENT_TYPE_ARRAY** **\<** *type* **>** **\<** *rank* **>**[**\<** *bounds* **>**]|**UnmanagedType.SafeArray(** *type* **)**

**UnmanagedType.LPArray**

Type, rank, bounds are provided in the signature. Size is always known at run time.| |**ELEMENT_TYPE_CLASS** **\<****>**|**UT_Interface**

**UnmanagedType.SafeArray(** *type* **)**

Type, rank, bounds, and size are always known at run time.| - There is a limitation in OLE Automation relating to arrays of structures that contain LPSTR or LPWSTR. Therefore, **String** fields have to be marshaled as **UnmanagedType.BSTR**. Otherwise, an exception will be thrown. + There is a limitation in OLE Automation relating to arrays of structures that contain LPSTR or LPWSTR. Therefore, **String** fields have to be marshalled as **UnmanagedType.BSTR**. Otherwise, an exception will be thrown. ### ELEMENT_TYPE_SZARRAY @@ -215,7 +215,7 @@ HRESULT New([in] SAFEARRAY( BSTR ) ar); The rank of the safe arrays is always 1 and the lower bound is always 0. The size is determined at run time by the size of the managed array being passed. - The array can also be marshaled as a C-style array by using the attribute. For example: + The array can also be marshalled as a C-style array by using the attribute. For example: #### Managed signature @@ -247,7 +247,7 @@ HRESULT New(BSTR ar[]); HRESULT New(LPStr ar[]); ``` - Although the marshaler has the length information needed to marshal the array, the array length is usually passed as a separate argument to convey the length to the callee. + Although the marshaller has the length information needed to marshal the array, the array length is usually passed as a separate argument to convey the length to the callee. ### ELEMENT_TYPE_ARRAY @@ -274,7 +274,7 @@ HRESULT New([in] SAFEARRAY( BSTR ) ar); The rank, size, and bounds of the safe arrays are determined at run time by the characteristics of the managed array. - The array can also be marshaled as a C-style array by applying the attribute. For example: + The array can also be marshalled as a C-style array by applying the attribute. For example: #### Managed signature @@ -301,7 +301,7 @@ HRESULT New(long ar[]); HRESULT New(LPStr ar[]); ``` - Nested arrays cannot be marshaled. For example, the following signature generates an error when exported with the [Type Library Exporter (Tlbexp.exe)](../tools/tlbexp-exe-type-library-exporter.md). + Nested arrays cannot be marshalled. For example, the following signature generates an error when exported with the [Type Library Exporter (Tlbexp.exe)](../tools/tlbexp-exe-type-library-exporter.md). #### Managed signature @@ -315,7 +315,7 @@ void New(long [][][] ar ); ### ELEMENT_TYPE_CLASS \ - When a method containing a parameter is exported from a .NET assembly to a type library, the array parameter is converted to an **_Array** interface. The contents of the managed array are accessible only through the methods and properties of the **_Array** interface. **System.Array** can also be marshaled as a **SAFEARRAY** by using the attribute. When marshaled as a safe array, the array elements are marshaled as variants. For example: + When a method containing a parameter is exported from a .NET assembly to a type library, the array parameter is converted to an **_Array** interface. The contents of the managed array are accessible only through the methods and properties of the **_Array** interface. **System.Array** can also be marshalled as a **SAFEARRAY** by using the attribute. When marshalled as a safe array, the array elements are marshalled as variants. For example: #### Managed signature @@ -338,7 +338,7 @@ HRESULT New([in] SAFEARRAY(VARIANT) ar); ### Arrays within Structures - Unmanaged structures can contain embedded arrays. By default, these embedded array fields are marshaled as a SAFEARRAY. In the following example, `s1` is an embedded array that is allocated directly within the structure itself. + Unmanaged structures can contain embedded arrays. By default, these embedded array fields are marshalled as a SAFEARRAY. In the following example, `s1` is an embedded array that is allocated directly within the structure itself. #### Unmanaged representation @@ -348,7 +348,7 @@ struct MyStruct { } ``` - Arrays can be marshaled as , which requires you to set the field. The size can be set only as a constant. The following code shows the corresponding managed definition of `MyStruct`. + Arrays can be marshalled as , which requires you to set the field. The size can be set only as a constant. The following code shows the corresponding managed definition of `MyStruct`. ```vb Public Structure MyStruct @@ -366,7 +366,7 @@ public struct MyStruct { ## See also -- [Default Marshaling Behavior](default-marshaling-behavior.md) +- [Default Marshalling Behavior](default-marshalling-behavior.md) - [Blittable and Non-Blittable Types](blittable-and-non-blittable-types.md) - [Directional Attributes](/previous-versions/dotnet/netframework-4.0/77e6taeh(v=vs.100)) - [Copying and Pinning](copying-and-pinning.md) diff --git a/docs/framework/interop/default-marshaling-for-objects.md b/docs/framework/interop/default-marshalling-for-objects.md similarity index 67% rename from docs/framework/interop/default-marshaling-for-objects.md rename to docs/framework/interop/default-marshalling-for-objects.md index 133a8dcdc40ef..006a069727426 100644 --- a/docs/framework/interop/default-marshaling-for-objects.md +++ b/docs/framework/interop/default-marshalling-for-objects.md @@ -1,16 +1,16 @@ --- -title: "Default Marshaling for Objects" -description: Understand default marshaling for objects. Review marshaling options. Marshal objects to interfaces or variants, variants to objects, and ByRef variants. +title: "Default Marshalling for Objects" +description: Understand default marshalling for objects. Review marshalling options. Marshal objects to interfaces or variants, variants to objects, and ByRef variants. ms.date: "03/30/2017" dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "objects, interop marshaling" - - "interop marshaling, objects" + - "objects, interop marshalling" + - "interop marshalling, objects" ms.assetid: c2ef0284-b061-4e12-b6d3-6a502b9cc558 --- -# Default Marshaling for Objects +# Default Marshalling for Objects Parameters and fields typed as can be exposed to unmanaged code as one of the following types: @@ -18,11 +18,11 @@ Parameters and fields typed as - An interface when the object is a structure field. -Only COM interop supports marshaling for object types. The default behavior is to marshal objects to COM variants. These rules apply only to the type **Object** and do not apply to strongly typed objects that derive from the **Object** class. +Only COM interop supports marshalling for object types. The default behavior is to marshal objects to COM variants. These rules apply only to the type **Object** and do not apply to strongly typed objects that derive from the **Object** class. -## Marshaling Options +## Marshalling Options -The following table shows the marshaling options for the **Object** data type. The attribute provides several enumeration values to marshal objects. +The following table shows the marshalling options for the **Object** data type. The attribute provides several enumeration values to marshal objects. |Enumeration type|Description of unmanaged format| |----------------------|-------------------------------------| @@ -82,7 +82,7 @@ interface MarshalObject { ``` > [!NOTE] -> The interop marshaler automatically frees any allocated object inside the variant after the call. +> The interop marshaller automatically frees any allocated object inside the variant after the call. The following example shows a formatted value type. @@ -109,21 +109,21 @@ struct ObjectHolder { } ``` -## Marshaling Object to Interface +## Marshalling Object to Interface When an object is exposed to COM as an interface, that interface is the class interface for the managed type (the **_Object** interface). This interface is typed as an **IDispatch** () or an **IUnknown** (**UnmanagedType.IUnknown**) in the resulting type library. COM clients can dynamically invoke the members of the managed class or any members implemented by its derived classes through the **_Object** interface. The client can also call **QueryInterface** to obtain any other interface explicitly implemented by the managed type. -## Marshaling Object to Variant +## Marshalling Object to Variant -When an object is marshaled to a variant, the internal variant type is determined at run time, based on the following rules: +When an object is marshalled to a variant, the internal variant type is determined at run time, based on the following rules: -- If the object reference is null (**Nothing** in Visual Basic), the object is marshaled to a variant of type **VT_EMPTY**. +- If the object reference is null (**Nothing** in Visual Basic), the object is marshalled to a variant of type **VT_EMPTY**. -- If the object is an instance of any type listed in the following table, the resulting variant type is determined by the rules built into the marshaler and shown in the table. +- If the object is an instance of any type listed in the following table, the resulting variant type is determined by the rules built into the marshaller and shown in the table. -- Other objects that need to explicitly control the marshaling behavior can implement the interface. In that case, the variant type is determined by the type code returned from the method. Otherwise, the object is marshaled as a variant of type **VT_UNKNOWN**. +- Other objects that need to explicitly control the marshalling behavior can implement the interface. In that case, the variant type is determined by the type code returned from the method. Otherwise, the object is marshalled as a variant of type **VT_UNKNOWN**. -### Marshaling System Types to Variant +### Marshalling System Types to Variant The following table shows managed object types and their corresponding COM variant types. These types are converted only when the signature of the method being called is of type . @@ -176,7 +176,7 @@ mo.SetVariant((single)27.0); // Marshal as variant of type VT_R4. mo.SetVariant((double)27.0); // Marshal as variant of type VT_R8. ``` -COM types that do not have corresponding managed types can be marshaled using wrapper classes such as , , , and . The following code example demonstrates how to use these wrappers to pass various types of variants to a COM server. +COM types that do not have corresponding managed types can be marshalled using wrapper classes such as , , , and . The following code example demonstrates how to use these wrappers to pass various types of variants to a COM server. ```vb Imports System.Runtime.InteropServices @@ -204,9 +204,9 @@ mo.SetVariant(new CurrencyWrapper(new Decimal(5.25))); The wrapper classes are defined in the namespace. -### Marshaling the IConvertible Interface to Variant +### Marshalling the IConvertible Interface to Variant -Types other than those listed in the previous section can control how they are marshaled by implementing the interface. If the object implements the **IConvertible** interface, the COM variant type is determined at run time by the value of the enumeration returned from the method. +Types other than those listed in the previous section can control how they are marshalled by implementing the interface. If the object implements the **IConvertible** interface, the COM variant type is determined at run time by the value of the enumeration returned from the method. The following table shows the possible values for the **TypeCode** enumeration and the corresponding COM variant type for each value. @@ -237,11 +237,11 @@ The following table shows the possible values for the **TypeCode** enumeration a |Not supported.|**VT_CY**| |Not supported.|**VT_VARIANT**| -The value of the COM variant is determined by calling the **IConvertible.To** *Type* interface, where **To** *Type* is the conversion routine that corresponds to the type that was returned from **IConvertible.GetTypeCode**. For example, an object that returns **TypeCode.Double** from **IConvertible.GetTypeCode** is marshaled as a COM variant of type **VT_R8**. You can obtain the value of the variant (stored in the **dblVal** field of the COM variant) by casting to the **IConvertible** interface and calling the method. +The value of the COM variant is determined by calling the **IConvertible.To** *Type* interface, where **To** *Type* is the conversion routine that corresponds to the type that was returned from **IConvertible.GetTypeCode**. For example, an object that returns **TypeCode.Double** from **IConvertible.GetTypeCode** is marshalled as a COM variant of type **VT_R8**. You can obtain the value of the variant (stored in the **dblVal** field of the COM variant) by casting to the **IConvertible** interface and calling the method. -## Marshaling Variant to Object +## Marshalling Variant to Object -When marshaling a variant to an object, the type, and sometimes the value, of the marshaled variant determines the type of object produced. The following table identifies each variant type and the corresponding object type that the marshaler creates when a variant is passed from COM to the .NET Framework. +When marshalling a variant to an object, the type, and sometimes the value, of the marshalled variant determines the type of object produced. The following table identifies each variant type and the corresponding object type that the m marshallerreates when a variant is passed from COM to the .NET Framework. |COM variant type|Object type| |----------------------|-----------------| @@ -271,37 +271,37 @@ When marshaling a variant to an object, the type, and sometimes the value, of th |**VT_RECORD**|Corresponding boxed value type.| |**VT_VARIANT**|Not supported.| -Variant types passed from COM to managed code and then back to COM might not retain the same variant type for the duration of the call. Consider what happens when a variant of type **VT_DISPATCH** is passed from COM to the .NET Framework. During marshaling, the variant is converted to a . If the **Object** is then passed back to COM, it is marshaled back to a variant of type **VT_UNKNOWN**. There is no guarantee that the variant produced when an object is marshaled from managed code to COM will be the same type as the variant initially used to produce the object. +Variant types passed from COM to managed code and then back to COM might not retain the same variant type for the duration of the call. Consider what happens when a variant of type **VT_DISPATCH** is passed from COM to the .NET Framework. During marshalling, the variant is converted to a . If the **Object** is then passed back to COM, it is marshalled back to a variant of type **VT_UNKNOWN**. There is no guarantee that the variant produced when an object is marshalled from managed code to COM will be the same type as the variant initially used to produce the object. -## Marshaling ByRef Variants +## Marshalling ByRef Variants -Although variants themselves can be passed by value or by reference, the **VT_BYREF** flag can also be used with any variant type to indicate that the contents of the variant are being passed by reference instead of by value. The difference between marshaling variants by reference and marshaling a variant with the **VT_BYREF** flag set can be confusing. The following illustration clarifies the differences: +Although variants themselves can be passed by value or by reference, the **VT_BYREF** flag can also be used with any variant type to indicate that the contents of the variant are being passed by reference instead of by value. The difference between marshalling variants by reference and marshalling a variant with the **VT_BYREF** flag set can be confusing. The following illustration clarifies the differences: ![Diagram that shows variant passed on the stack.](./media/default-marshaling-for-objects/interop-variant-passed-value-reference.gif) Variants passed by value and by reference -**Default behavior for marshaling objects and variants by value** +**Default behavior for marshalling objects and variants by value** -- When passing objects from managed code to COM, the contents of the object are copied into a new variant created by the marshaler, using the rules defined in [Marshaling Object to Variant](#marshaling-object-to-variant). Changes made to the variant on the unmanaged side are not propagated back to the original object on return from the call. +- When passing objects from managed code to COM, the contents of the object are copied into a new variant created by the marshaller, using the rules defined in [Marshalling Object to Variant](#marshalling-object-to-variant). Changes made to the variant on the unmanaged side are not propagated back to the original object on return from the call. -- When passing variants from COM to managed code, the contents of the variant are copied to a newly created object, using the rules defined in [Marshaling Variant to Object](#marshaling-variant-to-object). Changes made to the object on the managed side are not propagated back to the original variant on return from the call. +- When passing variants from COM to managed code, the contents of the variant are copied to a newly created object, using the rules defined in [Marshalling Variant to Object](#marshalling-variant-to-object). Changes made to the object on the managed side are not propagated back to the original variant on return from the call. -**Default behavior for marshaling objects and variants by reference** +**Default behavior for marshalling objects and variants by reference** To propagate changes back to the caller, the parameters must be passed by reference. For example, you can use the **ref** keyword in C# (or **ByRef** in Visual Basic managed code) to pass parameters by reference. In COM, reference parameters are passed using a pointer such as a **variant \***. -- When passing an object to COM by reference, the marshaler creates a new variant and copies the contents of the object reference into the variant before the call is made. The variant is passed to the unmanaged function where the user is free to change the contents of the variant. On return from the call, any changes made to the variant on the unmanaged side are propagated back to the original object. If the type of the variant differs from the type of the variant passed to the call, then the changes are propagated back to an object of a different type. That is, the type of the object passed into the call can differ from the type of the object returned from the call. +- When passing an object to COM by reference, the marshaller creates a new variant and copies the contents of the object reference into the variant before the call is made. The variant is passed to the unmanaged function where the user is free to change the contents of the variant. On return from the call, any changes made to the variant on the unmanaged side are propagated back to the original object. If the type of the variant differs from the type of the variant passed to the call, then the changes are propagated back to an object of a different type. That is, the type of the object passed into the call can differ from the type of the object returned from the call. -- When passing a variant to managed code by reference, the marshaler creates a new object and copies the contents of the variant into the object before making the call. A reference to the object is passed to the managed function, where the user is free to change the object. On return from the call, any changes made to the referenced object are propagated back to the original variant. If the type of the object differs from the type of the object passed in to the call, the type of the original variant is changed and the value is propagated back into the variant. Again, the type of the variant passed into the call can differ from the type of the variant returned from the call. +- When passing a variant to managed code by reference, the marshaller creates a new object and copies the contents of the variant into the object before making the call. A reference to the object is passed to the managed function, where the user is free to change the object. On return from the call, any changes made to the referenced object are propagated back to the original variant. If the type of the object differs from the type of the object passed in to the call, the type of the original variant is changed and the value is propagated back into the variant. Again, the type of the variant passed into the call can differ from the type of the variant returned from the call. - **Default behavior for marshaling a variant with the VT_BYREF flag set** + **Default behavior for marshalling a variant with the VT_BYREF flag set** -- A variant being passed to managed code by value can have the **VT_BYREF** flag set to indicate that the variant contains a reference instead of a value. In this case, the variant is still marshaled to an object because the variant is being passed by value. The marshaler automatically dereferences the contents of the variant and copies it into a newly created object before making the call. The object is then passed into the managed function; however, on return from the call, the object is not propagated back into the original variant. Changes made to the managed object are lost. +- A variant being passed to managed code by value can have the **VT_BYREF** flag set to indicate that the variant contains a reference instead of a value. In this case, the variant is still marshalled to an object because the variant is being passed by value. The marshallerautomatically dereferences the contents of the variant and copies it into a newly created object before making the call. The object is then passed into the managed function; however, on return from the call, the object is not propagated back into the original variant. Changes made to the managed object are lost. > [!CAUTION] > There is no way to change the value of a variant passed by value, even if the variant has the **VT_BYREF** flag set. -- A variant being passed to managed code by reference can also have the **VT_BYREF** flag set to indicate that the variant contains another reference. If it does, the variant is marshaled to a **ref** object because the variant is being passed by reference. The marshaler automatically dereferences the contents of the variant and copies it into a newly created object before making the call. On return from the call, the value of the object is propagated back to the reference within the original variant only if the object is the same type as the object passed in. That is, propagation does not change the type of a variant with the **VT_BYREF** flag set. If the type of the object is changed during the call, an occurs on return from the call. +- A variant being passed to managed code by reference can also have the **VT_BYREF** flag set to indicate that the variant contains another reference. If it does, the variant is marshalled to a **ref** object because the variant is being passed by reference. The marshallerautomatically dereferences the contents of the variant and copies it into a newly created object before making the call. On return from the call, the value of the object is propagated back to the reference within the original variant only if the object is the same type as the object passed in. That is, propagation does not change the type of a variant with the **VT_BYREF** flag set. If the type of the object is changed during the call, an occurs on return from the call. The following table summarizes the propagation rules for variants and objects. @@ -316,7 +316,7 @@ The following table summarizes the propagation rules for variants and objects. ## See also -- [Default Marshaling Behavior](default-marshaling-behavior.md) +- [Default Marshalling Behavior](default-marshalling-behavior.md) - [Blittable and Non-Blittable Types](blittable-and-non-blittable-types.md) - [Directional Attributes](/previous-versions/dotnet/netframework-4.0/77e6taeh(v=vs.100)) - [Copying and Pinning](copying-and-pinning.md) diff --git a/docs/framework/interop/default-marshaling-for-strings.md b/docs/framework/interop/default-marshalling-for-strings.md similarity index 85% rename from docs/framework/interop/default-marshaling-for-strings.md rename to docs/framework/interop/default-marshalling-for-strings.md index 40094a0ef7007..bfd5b039faf1f 100644 --- a/docs/framework/interop/default-marshaling-for-strings.md +++ b/docs/framework/interop/default-marshalling-for-strings.md @@ -1,24 +1,24 @@ --- -title: "Default Marshaling for Strings" -description: Review the default marshaling behavior for strings in interfaces, platform invoke, structures, & fixed-length string buffers in .NET. +title: "Default Marshalling for Strings" +description: Review the default marshalling behavior for strings in interfaces, platform invoke, structures, & fixed-length string buffers in .NET. ms.date: 10/04/2021 dev_langs: - "csharp" - "vb" helpviewer_keywords: - - "strings, interop marshaling" - - "interop marshaling, strings" + - "strings, interop marshalling" + - "interop marshalling, strings" ms.assetid: 9baea3ce-27b3-4b4f-af98-9ad0f9467e6f --- -# Default marshaling for strings +# Default marshalling for strings -Both the and classes have similar marshaling behavior. +Both the and classes have similar marshalling behavior. -Strings are marshaled as a COM-style `BSTR` type or as a null-terminated string (a character array that ends with a null character). The characters within the string can be marshaled as Unicode (the default on Windows systems) or ANSI. +Strings are marshalled as a COM-style `BSTR` type or as a null-terminated string (a character array that ends with a null character). The characters within the string can be marshalled as Unicode (the default on Windows systems) or ANSI. ## Strings Used in Interfaces -The following table shows the marshaling options for the string data type when marshaled as a method argument to unmanaged code. The attribute provides several enumeration values to marshal strings to COM interfaces. +The following table shows the marshalling options for the string data type when marshalled as a method argument to unmanaged code. The attribute provides several enumeration values to marshal strings to COM interfaces. |Enumeration type|Description of unmanaged format| |----------------------|-------------------------------------| @@ -79,7 +79,7 @@ When the CharSet is Unicode or a string argument is explicitly marked as [Marsha Native code is only responsible for releasing the memory when the string is passed by reference and it assigns a new value. Otherwise, the .NET runtime owns the memory and will release it after the call. -The following table lists the marshaling options for strings when marshaled as a method argument of a platform invoke call. The attribute provides several enumeration values to marshal strings. +The following table lists the marshalling options for strings when marshalled as a method argument of a platform invoke call. The attribute provides several enumeration values to marshal strings. |Enumeration type|Description of unmanaged format| |----------------------|-------------------------------------| @@ -137,7 +137,7 @@ End Class ## Strings Used in Structures -Strings are valid members of structures; however, buffers are invalid in structures. The following table shows the marshaling options for the data type when the type is marshaled as a field. The attribute provides several enumeration values to marshal strings to a field. +Strings are valid members of structures; however, buffers are invalid in structures. The following table shows the marshalling options for the data type when the type is marshalled as a field. The attribute provides several enumeration values to marshal strings to a field. |Enumeration type|Description of unmanaged format| |----------------------|-------------------------------------| @@ -227,7 +227,7 @@ End Structure In some circumstances, a fixed-length character buffer must be passed into unmanaged code to be manipulated. Simply passing a string does not work in this case because the callee cannot modify the contents of the passed buffer. Even if the string is passed by reference, there is no way to initialize the buffer to a given size. -The solution is to pass a as the argument instead of a . The buffer created when marshaling a `StringBuilder` can be dereferenced and modified by the callee, provided it does not exceed the capacity of the `StringBuilder`. It can also be initialized to a fixed length. For example, if you initialize a `StringBuilder` buffer to a capacity of `N`, the marshaler provides a buffer of size (`N`+1) characters. The +1 accounts for the fact that the unmanaged string has a null terminator while `StringBuilder` does not. +The solution is to pass a as the argument instead of a . The buffer created when marshalling a `StringBuilder` can be dereferenced and modified by the callee, provided it does not exceed the capacity of the `StringBuilder`. It can also be initialized to a fixed length. For example, if you initialize a `StringBuilder` buffer to a capacity of `N`, the marshallerprovides a buffer of size (`N`+1) characters. The +1 accounts for the fact that the unmanaged string has a null terminator while `StringBuilder` does not. For example, the Windows [`GetWindowText`](/windows/desktop/api/winuser/nf-winuser-getwindowtextw) API function (defined in *winuser.h*) requires that the caller pass a fixed-length character buffer to which the function writes the window's text. `LpString` points to a caller-allocated buffer of size `nMaxCount`. The caller is expected to allocate the buffer and set the `nMaxCount` argument to the size of the allocated buffer. The following example shows the `GetWindowText` function declaration as defined in *winuser.h*. @@ -284,8 +284,8 @@ End Class ## See also -- [Default Marshaling Behavior](default-marshaling-behavior.md) -- [Marshaling Strings](marshaling-strings.md) +- [Default Marshalling Behavior](default-marshalling-behavior.md) +- [Marshalling Strings](marshalling-strings.md) - [Blittable and Non-Blittable Types](blittable-and-non-blittable-types.md) - [Directional Attributes](/previous-versions/dotnet/netframework-4.0/77e6taeh(v=vs.100)) - [Copying and Pinning](copying-and-pinning.md) diff --git a/docs/framework/interop/how-to-implement-callback-functions.md b/docs/framework/interop/how-to-implement-callback-functions.md index ebed44a659469..6e3570180b75e 100644 --- a/docs/framework/interop/how-to-implement-callback-functions.md +++ b/docs/framework/interop/how-to-implement-callback-functions.md @@ -32,7 +32,7 @@ The following procedure and example demonstrate how a managed application, using 4. Ensure that the garbage collector does not reclaim the delegate before the callback function completes its work. When you pass a delegate as a parameter, or pass a delegate contained as a field in a structure, it remains uncollected for the duration of the call. So, as is the case in the following enumeration example, the callback function completes its work before the call returns and requires no additional action by the managed caller. - If, however, the callback function can be invoked after the call returns, the managed caller must take steps to ensure that the delegate remains uncollected until the callback function finishes. For detailed information about preventing garbage collection, see [Interop Marshaling](interop-marshaling.md) with Platform Invoke. + If, however, the callback function can be invoked after the call returns, the managed caller must take steps to ensure that the delegate remains uncollected until the callback function finishes. For detailed information about preventing garbage collection, see [Interop Marshaling](interop-marshalling.md) with Platform Invoke. ## Example diff --git a/docs/framework/interop/how-to-map-hresults-and-exceptions.md b/docs/framework/interop/how-to-map-hresults-and-exceptions.md index ed660506feaa0..480bdaeaf098e 100644 --- a/docs/framework/interop/how-to-map-hresults-and-exceptions.md +++ b/docs/framework/interop/how-to-map-hresults-and-exceptions.md @@ -40,7 +40,7 @@ COM methods report errors by returning HRESULTs; .NET methods report them by thr } ``` - You might encounter a program (in any programming language) that uses both managed and unmanaged code at the same time. For example, the custom marshaler in the following code example uses the `Marshal.ThrowExceptionForHR(int HResult)` method to throw an exception with a specific HRESULT value. The method looks up the HRESULT and generates the appropriate exception type. For example, the HRESULT in the following code fragment generates `ArgumentException`. + You might encounter a program (in any programming language) that uses both managed and unmanaged code at the same time. For example, the custom marshaller in the following code example uses the `Marshal.ThrowExceptionForHR(int HResult)` method to throw an exception with a specific HRESULT value. The method looks up the HRESULT and generates the appropriate exception type. For example, the HRESULT in the following code fragment generates `ArgumentException`. ```cpp CMyClass::MethodThatThrows diff --git a/docs/framework/interop/how-to-register-primary-interop-assemblies.md b/docs/framework/interop/how-to-register-primary-interop-assemblies.md index d47e60fc6c306..79bbd98240bf3 100644 --- a/docs/framework/interop/how-to-register-primary-interop-assemblies.md +++ b/docs/framework/interop/how-to-register-primary-interop-assemblies.md @@ -9,7 +9,7 @@ ms.assetid: 4b2fcf8a-429d-43ce-8334-e026040be8bb --- # How to: Register Primary Interop Assemblies -Classes can be marshaled only by COM interop and are always marshaled as interfaces. In some cases the interface used to marshal the class is known as the class interface. For information about overriding the class interface with an interface of your choice, see [COM Callable Wrapper](../../standard/native-interop/com-callable-wrapper.md). +Classes can be marshalled only by COM interop and are always marshalled as interfaces. In some cases the interface used to marshal the class is known as the class interface. For information about overriding the class interface with an interface of your choice, see [COM Callable Wrapper](../../standard/native-interop/com-callable-wrapper.md). Although any developer who wants to use COM types from a .NET Framework application can generate an interop assembly, doing so creates a problem. Each time a developer imports and signs a COM type library, that developer creates a set of unique types that are incompatible with those imported and signed by another developer. The solution to this type incompatibility problem is for each developer to obtain the vendor-supplied and signed primary interop assembly. diff --git a/docs/framework/interop/identifying-functions-in-dlls.md b/docs/framework/interop/identifying-functions-in-dlls.md index 16226fb2ab6db..1ea7a47fe7a9f 100644 --- a/docs/framework/interop/identifying-functions-in-dlls.md +++ b/docs/framework/interop/identifying-functions-in-dlls.md @@ -37,7 +37,7 @@ The identity of a DLL function consists of the following elements: |Kernel32.dll|Low-level operating system functions for memory management and resource handling.| |User32.dll|Windows management functions for message handling, timers, menus, and communications.| - For complete documentation on the Windows API, see the Platform SDK. For examples that demonstrate how to construct .NET-based declarations to be used with platform invoke, see [Marshaling Data with Platform Invoke](marshaling-data-with-platform-invoke.md). + For complete documentation on the Windows API, see the Platform SDK. For examples that demonstrate how to construct .NET-based declarations to be used with platform invoke, see [Marshalling Data with Platform Invoke](marshalling-data-with-platform-invoke.md). ## See also diff --git a/docs/framework/interop/index.md b/docs/framework/interop/index.md index 812bae212bb2f..eb03a1aadf5da 100644 --- a/docs/framework/interop/index.md +++ b/docs/framework/interop/index.md @@ -29,8 +29,8 @@ Describes how to use .NET Framework components from COM applications. [Consuming Unmanaged DLL Functions](consuming-unmanaged-dll-functions.md) Describes how to call unmanaged DLL functions using platform invoke. -[Interop Marshaling](interop-marshaling.md) -Describes marshaling for COM interop and platform invoke. +[Interop Marshaling](interop-marshalling.md) +Describes marshalling for COM interop and platform invoke. [How to: Map HRESULTs and Exceptions](how-to-map-hresults-and-exceptions.md) Describes the mapping between exceptions and HRESULTs. diff --git a/docs/framework/interop/interop-marshaling.md b/docs/framework/interop/interop-marshalling.md similarity index 56% rename from docs/framework/interop/interop-marshaling.md rename to docs/framework/interop/interop-marshalling.md index 5ee4fa397471a..dfa31d9bc1795 100644 --- a/docs/framework/interop/interop-marshaling.md +++ b/docs/framework/interop/interop-marshalling.md @@ -1,20 +1,20 @@ --- title: "Interop Marshaling" -description: Get started with interop marshaling, which governs how data is passed in method arguments and return values between managed and unmanaged memory during calls. +description: Get started with interop marshalling, which governs how data is passed in method arguments and return values between managed and unmanaged memory during calls. ms.date: "03/30/2017" helpviewer_keywords: - "marshaling, COM interop" - - "interop marshaling" - - "interop marshaling, about interop marshaling" + - "interop marshalling" + - "interop marshalling, about interop marshalling" ms.assetid: 115f7a2f-d422-4605-ab36-13a8dd28142a --- # Interop Marshaling -Interop marshaling governs how data is passed in method arguments and return values between managed and unmanaged memory during calls. Interop marshaling is a run-time activity performed by the common language runtime's marshaling service. +Interop marshalling governs how data is passed in method arguments and return values between managed and unmanaged memory during calls. Interop marshalling is a run-time activity performed by the common language runtime's marshalling service. -Most data types have common representations in both managed and unmanaged memory. The interop marshaler handles these types for you. Other types can be ambiguous or not represented at all in managed memory. +Most data types have common representations in both managed and unmanaged memory. The interop marshaller handles these types for you. Other types can be ambiguous or not represented at all in managed memory. -An ambiguous type can have either multiple unmanaged representations that map to a single managed type, or missing type information, such as the size of an array. For ambiguous types, the marshaler provides a default representation and alternative representations where multiple representations exist. You can supply explicit instructions to the marshaler on how it is to marshal an ambiguous type. +An ambiguous type can have either multiple unmanaged representations that map to a single managed type, or missing type information, such as the size of an array. For ambiguous types, the marshaller provides a default representation and alternative representations where multiple representations exist. You can supply explicit instructions to the marshaller on how it is to marshal an ambiguous type. ## Platform Invoke and COM Interop Models @@ -23,30 +23,30 @@ The common language runtime provides two mechanisms for interoperating with unma - Platform invoke, which enables managed code to call functions exported from an unmanaged library. - COM interop, which enables managed code to interact with Component Object Model (COM) objects through interfaces. -Both platform invoke and COM interop use interop marshaling to accurately move method arguments between caller and callee and back, if required. As the following illustration shows, a platform invoke method call flows from managed to unmanaged code and never the other way, except when [callback functions](callback-functions.md) are involved. Even though platform invoke calls can flow only from managed to unmanaged code, data can flow in both directions as input or output parameters. COM interop method calls can flow in either direction. +Both platform invoke and COM interop use interop marshalling to accurately move method arguments between caller and callee and back, if required. As the following illustration shows, a platform invoke method call flows from managed to unmanaged code and never the other way, except when [callback functions](callback-functions.md) are involved. Even though platform invoke calls can flow only from managed to unmanaged code, data can flow in both directions as input or output parameters. COM interop method calls can flow in either direction. ![Platform invoke](./media/interop-marshaling/interop-marshaling-invoke-and-com.png "Platform invoke and COM interop call flow") -At the lowest level, both mechanisms use the same interop marshaling service; however, certain data types are supported exclusively by COM interop or platform invoke. For details, see [Default Marshaling Behavior](default-marshaling-behavior.md). +At the lowest level, both mechanisms use the same interop marshalling service; however, certain data types are supported exclusively by COM interop or platform invoke. For details, see [Default Marshalling Behavior](default-marshalling-behavior.md). -## Marshaling and COM Apartments +## Marshalling and COM Apartments -The interop marshaler marshals data between the common language runtime heap and the unmanaged heap. Marshaling occurs whenever the caller and callee cannot operate on the same instance of data. The interop marshaler makes it possible for the caller and callee to appear to be operating on the same data even if they have their own copy of the data. +The interop marshaller marshals data between the common language runtime heap and the unmanaged heap. Marshalling occurs whenever the caller and callee cannot operate on the same instance of data. The interop marshaller makes it possible for the caller and callee to appear to be operating on the same data even if they have their own copy of the data. -COM also has a marshaler that marshals data between COM apartments or different COM processes. When calling between managed and unmanaged code within the same COM apartment, the interop marshaler is the only marshaler involved. When calling between managed code and unmanaged code in a different COM apartment or a different process, both the interop marshaler and the COM marshaler are involved. +COM also has a marshaller that marshals data between COM apartments or different COM processes. When calling between managed and unmanaged code within the same COM apartment, the interop marshaller is the only marshaller involved. When calling between managed code and unmanaged code in a different COM apartment or a different process, both the interop marshaller and the COM marshaller are involved. ### COM Clients and Managed Servers An exported managed server with a type library registered by the [Regasm.exe (Assembly Registration Tool)](../tools/regasm-exe-assembly-registration-tool.md) has a `ThreadingModel` registry entry set to `Both`. This value indicates that the server can be activated in a single-threaded apartment (STA) or a multithreaded apartment (MTA). The server object is created in the same apartment as its caller, as shown in the following table: -|COM client|.NET server|Marshaling requirements| +|COM client|.NET server|Marshalling requirements| |----------------|-----------------|-----------------------------| -|STA|`Both` becomes STA.|Same-apartment marshaling.| -|MTA|`Both` becomes MTA.|Same-apartment marshaling.| +|STA|`Both` becomes STA.|Same-apartment marshalling.| +|MTA|`Both` becomes MTA.|Same-apartment marshalling.| -Because the client and server are in the same apartment, the interop marshaling service automatically handles all data marshaling. The following illustration shows the interop marshaling service operating between managed and unmanaged heaps within the same COM-style apartment. +Because the client and server are in the same apartment, the interop marshalling service automatically handles all data marshalling. The following illustration shows the interop marshalling service operating between managed and unmanaged heaps within the same COM-style apartment. -![Interop marshaling between managed and unmanaged heaps](./media/interop-marshaling/interop-heaps-managed-and-unmanaged.gif "Same-apartment marshaling process") +![Interop marshalling between managed and unmanaged heaps](./media/interop-marshaling/interop-heaps-managed-and-unmanaged.gif "Same-apartment marshalling process") If you plan to export a managed server, be aware that the COM client determines the apartment of the server. A managed server called by a COM client initialized in an MTA must ensure thread safety. @@ -54,37 +54,37 @@ If you plan to export a managed server, be aware that the COM client determines The default setting for managed client apartments is MTA; however, the application type of the .NET client can change the default setting. For example, a Visual Basic client apartment setting is STA. You can use the , the , the property, or the property to examine and change the apartment setting of a managed client. -The author of the component sets the thread affinity of a COM server. The following table shows the combinations of apartment settings for .NET clients and COM servers. It also shows the resulting marshaling requirements for the combinations. +The author of the component sets the thread affinity of a COM server. The following table shows the combinations of apartment settings for .NET clients and COM servers. It also shows the resulting marshalling requirements for the combinations. -|.NET client|COM server|Marshaling requirements| +|.NET client|COM server|Marshalling requirements| |-----------------|----------------|-----------------------------| -|MTA (default)|MTA

STA|Interop marshaling.

Interop and COM marshaling.| -|STA|MTA

STA|Interop and COM marshaling.

Interop marshaling.| +|MTA (default)|MTA

STA|Interop marshalling.

Interop and COM marshalling.| +|STA|MTA

STA|Interop and COM marshalling.

Interop marshalling.| -When a managed client and unmanaged server are in the same apartment, the interop marshaling service handles all data marshaling. However, when client and server are initialized in different apartments, COM marshaling is also required. The following illustration shows the elements of a cross-apartment call: +When a managed client and unmanaged server are in the same apartment, the interop marshalling service handles all data marshalling. However, when client and server are initialized in different apartments, COM marshalling is also required. The following illustration shows the elements of a cross-apartment call: ![Cross-apartment call between a .NET client and COM object](./media/interop-marshaling/single-process-across-multi-apartment.gif) -For cross-apartment marshaling, you can do the following: +For cross-apartment marshalling, you can do the following: -- Accept the overhead of the cross-apartment marshaling, which is noticeable only when there are many calls across the boundary. You must register the type library of the COM component for calls to successfully cross the apartment boundary. -- Alter the main thread by setting the client thread to STA or MTA. For example, if your C# client calls many STA COM components, you can avoid cross-apartment marshaling by setting the main thread to STA. +- Accept the overhead of the cross-apartment marshalling, which is noticeable only when there are many calls across the boundary. You must register the type library of the COM component for calls to successfully cross the apartment boundary. +- Alter the main thread by setting the client thread to STA or MTA. For example, if your C# client calls many STA COM components, you can avoid cross-apartment marshalling by setting the main thread to STA. > [!NOTE] - > Once the thread of a C# client is set to STA, calls to MTA COM components will require cross-apartment marshaling. + > Once the thread of a C# client is set to STA, calls to MTA COM components will require cross-apartment marshalling. For instructions on explicitly selecting an apartment model, see [Managed and Unmanaged Threading](/previous-versions/dotnet/netframework-4.0/5s8ee185(v=vs.100)). -## Marshaling Remote Calls +## Marshalling Remote Calls -As with cross-apartment marshaling, COM marshaling is involved in each call between managed and unmanaged code whenever the objects reside in separate processes. For example: +As with cross-apartment marshalling, COM marshalling is involved in each call between managed and unmanaged code whenever the objects reside in separate processes. For example: - A COM client that invokes a managed server on a remote host uses distributed COM (DCOM). - A managed client that invokes a COM server on a remote host uses DCOM. -The following illustration shows how interop marshaling and COM marshaling provide communications channels across process and host boundaries: +The following illustration shows how interop marshalling and COM marshalling provide communications channels across process and host boundaries: -![Cross-process marshaling](./media/interop-marshaling/interop-and-com-marshaling.gif) +![Cross-process marshalling](./media/interop-marshaling/interop-and-com-marshaling.gif) ### Preserving Identity @@ -115,9 +115,9 @@ Some unmanaged calls can be channeled through SOAP, such as the calls between se |Title|Description| |-----------|-----------------| -|[Default Marshaling Behavior](default-marshaling-behavior.md)|Describes the rules that the interop marshaling service uses to marshal data.| -|[Marshaling Data with Platform Invoke](marshaling-data-with-platform-invoke.md)|Describes how to declare method parameters and pass arguments to functions exported by unmanaged libraries.| -|[Marshaling Data with COM Interop](marshaling-data-with-com-interop.md)|Describes how to customize COM wrappers to alter marshaling behavior.| +|[Default Marshalling Behavior](default-marshalling-behavior.md)|Describes the rules that the interop marshalling service uses to marshal data.| +|[Marshalling Data with Platform Invoke](marshalling-data-with-platform-invoke.md)|Describes how to declare method parameters and pass arguments to functions exported by unmanaged libraries.| +|[Marshalling Data with COM Interop](marshalling-data-with-com-interop.md)|Describes how to customize COM wrappers to alter marshalling behavior.| |[How to: Migrate Managed-Code DCOM to WCF](how-to-migrate-managed-code-dcom-to-wcf.md)|Describes how to migrate from DCOM to WCF.| |[How to: Map HRESULTs and Exceptions](how-to-map-hresults-and-exceptions.md)|Describes how to map custom exceptions to HRESULTs and provides the complete mapping from each HRESULT to its comparable exception class in the .NET Framework.| |[Interoperating Using Generic Types](/previous-versions/dotnet/netframework-4.0/ms229590(v=vs.100))|Describes which actions are supported when using generic types for COM interoperability.| diff --git a/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md b/docs/framework/interop/marshalling-a-delegate-as-a-callback-method.md similarity index 84% rename from docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md rename to docs/framework/interop/marshalling-a-delegate-as-a-callback-method.md index ec85e1c292128..9cbea1e5cce93 100644 --- a/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md +++ b/docs/framework/interop/marshalling-a-delegate-as-a-callback-method.md @@ -1,5 +1,5 @@ --- -title: "Marshaling a Delegate as a Callback Method" +title: "Marshalling a Delegate as a Callback Method" description: Learn to marshal a delegate as a callback method. See an example of how to pass delegates to an unmanaged function that's expecting function pointers. ms.date: "03/30/2017" dev_langs: @@ -7,11 +7,11 @@ dev_langs: - "vb" - "cpp" helpviewer_keywords: - - "data marshaling, Callback sample" + - "data marshalling, Callback sample" - "marshaling, Callback sample" ms.assetid: 6ddd7866-9804-4571-84de-83f5cc017a5a --- -# Marshaling a Delegate as a Callback Method +# Marshalling a Delegate as a Callback Method This sample demonstrates how to pass delegates to an unmanaged function expecting function pointers. A delegate is a class that can hold a reference to a method and is equivalent to a type-safe function pointer or a callback function. @@ -32,7 +32,7 @@ The Callback sample uses the following unmanaged functions, shown with their ori void TestCallBack2(FPTR2 pf2, char* value); ``` -[PinvokeLib.dll](marshaling-data-with-platform-invoke.md#pinvokelibdll) is a custom unmanaged library that contains an implementation for the previously listed functions. +[PinvokeLib.dll](marshalling-data-with-platform-invoke.md#pinvokelibdll) is a custom unmanaged library that contains an implementation for the previously listed functions. In this sample, the `NativeMethods` class contains managed prototypes for the `TestCallBack` and `TestCallBack2` methods. Both methods pass a delegate to a callback function as a parameter. The signature of the delegate must match the signature of the method it references. For example, the `FPtr` and `FPtr2` delegates have signatures that are identical to the `DoSomething` and `DoSomething2` methods. @@ -50,6 +50,6 @@ In this sample, the `NativeMethods` class contains managed prototypes for the `T ## See also -- [Miscellaneous Marshaling Samples](/previous-versions/dotnet/netframework-4.0/ss9sb93t(v=vs.100)) -- [Platform Invoke Data Types](marshaling-data-with-platform-invoke.md#platform-invoke-data-types) +- [Miscellaneous Marshalling Samples](/previous-versions/dotnet/netframework-4.0/ss9sb93t(v=vs.100)) +- [Platform Invoke Data Types](marshalling-data-with-platform-invoke.md#platform-invoke-data-types) - [Creating Prototypes in Managed Code](creating-prototypes-in-managed-code.md) diff --git a/docs/framework/interop/marshaling-classes-structures-and-unions.md b/docs/framework/interop/marshalling-classes-structures-and-unions.md similarity index 92% rename from docs/framework/interop/marshaling-classes-structures-and-unions.md rename to docs/framework/interop/marshalling-classes-structures-and-unions.md index 6a4e2f1255a2d..1e732e3c9cb6f 100644 --- a/docs/framework/interop/marshaling-classes-structures-and-unions.md +++ b/docs/framework/interop/marshalling-classes-structures-and-unions.md @@ -1,30 +1,30 @@ --- -title: "Marshaling Classes, Structures, and Unions" -description: Review how to marshal classes, structures, and unions. View samples of marshaling classes, structures with nested structures, arrays of structures, and unions. +title: "Marshalling Classes, Structures, and Unions" +description: Review how to marshal classes, structures, and unions. View samples of marshalling classes, structures with nested structures, arrays of structures, and unions. ms.date: "03/30/2017" dev_langs: - "csharp" - "vb" - "cpp" helpviewer_keywords: - - "data marshaling, classes" + - "data marshalling, classes" - "marshaling, unions" - "marshaling, structures" - "marshaling, samples" - - "data marshaling, structures" - - "platform invoke, marshaling data" + - "data marshalling, structures" + - "platform invoke, marshalling data" - "marshaling, classes" - - "data marshaling, unions" - - "data marshaling, samples" - - "data marshaling, platform invoke" + - "data marshalling, unions" + - "data marshalling, samples" + - "data marshalling, platform invoke" - "marshaling, platform invoke" ms.assetid: 027832a2-9b43-4fd9-9b45-7f4196261a4e --- -# Marshaling Classes, Structures, and Unions +# Marshalling Classes, Structures, and Unions Classes and structures are similar in the .NET Framework. Both can have fields, properties, and events. They can also have static and nonstatic methods. One notable difference is that structures are value types and classes are reference types. -The following table lists marshaling options for classes, structures, and unions; describes their usage; and provides a link to the corresponding platform invoke sample. +The following table lists marshalling options for classes, structures, and unions; describes their usage; and provides a link to the corresponding platform invoke sample. |Type|Description|Sample| |----------|-----------------|------------| @@ -33,7 +33,7 @@ The following table lists marshaling options for classes, structures, and unions |Structure by reference.|Passes structures as In/Out parameters.|[OSInfo sample](/previous-versions/dotnet/netframework-4.0/795sy883(v=vs.100))| |Structure with nested structures (flattened).|Passes a class that represents a structure with nested structures in the unmanaged function. The structure is flattened to one big structure in the managed prototype.|[FindFile sample](#findfile-sample)| |Structure with a pointer to another structure.|Passes a structure that contains a pointer to a second structure as a member.|[Structures Sample](#structures-sample)| -|Array of structures with integers by value.|Passes an array of structures that contain only integers as an In/Out parameter. Members of the array can be changed.|[Arrays Sample](marshaling-different-types-of-arrays.md)| +|Array of structures with integers by value.|Passes an array of structures that contain only integers as an In/Out parameter. Members of the array can be changed.|[Arrays Sample](marshalling-different-types-of-arrays.md)| |Array of structures with integers and strings by reference.|Passes an array of structures that contain integers and strings as an Out parameter. The called function allocates memory for the array.|[OutArrayOfStructs Sample](#outarrayofstructs-sample)| |Unions with value types.|Passes unions with value types (integer and double).|[Unions sample](#unions-sample)| |Unions with mixed types.|Passes unions with mixed types (integer and string).|[Unions sample](#unions-sample)| @@ -64,7 +64,7 @@ The Structs sample uses the following unmanaged functions, shown with their orig void TestArrayInStruct(MYARRAYSTRUCT* pStruct); ``` -[PinvokeLib.dll](marshaling-data-with-platform-invoke.md#pinvokelibdll) is a custom unmanaged library that contains implementations for the previously listed functions and four structures: **MYPERSON**, **MYPERSON2**, **MYPERSON3**, and **MYARRAYSTRUCT**. These structures contain the following elements: +[PinvokeLib.dll](marshalling-data-with-platform-invoke.md#pinvokelibdll) is a custom unmanaged library that contains implementations for the previously listed functions and four structures: **MYPERSON**, **MYPERSON2**, **MYPERSON3**, and **MYARRAYSTRUCT**. These structures contain the following elements: ```cpp typedef struct _MYPERSON @@ -184,7 +184,7 @@ The Unions sample uses the following unmanaged function, shown with its original void TestUnion(MYUNION u, int type); ``` -[PinvokeLib.dll](marshaling-data-with-platform-invoke.md#pinvokelibdll) is a custom unmanaged library that contains an implementation for the previously listed function and two unions, **MYUNION** and **MYUNION2**. The unions contain the following elements: +[PinvokeLib.dll](marshalling-data-with-platform-invoke.md#pinvokelibdll) is a custom unmanaged library that contains an implementation for the previously listed function and two unions, **MYUNION** and **MYUNION2**. The unions contain the following elements: ```cpp union MYUNION @@ -340,7 +340,7 @@ This sample shows how to pass an array of structures that contains integers and This sample demonstrates how to call a native function by using the class and by using unsafe code. -This sample uses a wrapper functions and platform invokes defined in [PinvokeLib.dll](marshaling-data-with-platform-invoke.md#pinvokelibdll), also provided in the source files. It uses the `TestOutArrayOfStructs` function and the `MYSTRSTRUCT2` structure. The structure contains the following elements: +This sample uses a wrapper functions and platform invokes defined in [PinvokeLib.dll](marshalling-data-with-platform-invoke.md#pinvokelibdll), also provided in the source files. It uses the `TestOutArrayOfStructs` function and the `MYSTRSTRUCT2` structure. The structure contains the following elements: ```cpp typedef struct _MYSTRSTRUCT2 @@ -378,6 +378,6 @@ As previously mentioned, C# allows unsafe code and Visual Basic does not. In the ## See also -- [Marshaling Data with Platform Invoke](marshaling-data-with-platform-invoke.md) -- [Marshaling Strings](marshaling-strings.md) -- [Marshaling Different Types of Arrays](marshaling-different-types-of-arrays.md) +- [Marshalling Data with Platform Invoke](marshalling-data-with-platform-invoke.md) +- [Marshalling Strings](marshalling-strings.md) +- [Marshalling Different Types of Arrays](marshalling-different-types-of-arrays.md) diff --git a/docs/framework/interop/marshaling-data-with-com-interop.md b/docs/framework/interop/marshalling-data-with-com-interop.md similarity index 74% rename from docs/framework/interop/marshaling-data-with-com-interop.md rename to docs/framework/interop/marshalling-data-with-com-interop.md index f30f864ad22e3..c4cca7d8390ac 100644 --- a/docs/framework/interop/marshaling-data-with-com-interop.md +++ b/docs/framework/interop/marshalling-data-with-com-interop.md @@ -1,22 +1,22 @@ --- -title: "Marshaling Data with COM Interop" -description: See articles covering the marshaling of data with COM interop. The Tlbimp.exe and Tlbexp.exe tools convert between a COM type library and an interop assembly. +title: "Marshalling Data with COM Interop" +description: See articles covering the marshalling of data with COM interop. The Tlbimp.exe and Tlbexp.exe tools convert between a COM type library and an interop assembly. ms.date: "09/07/2017" helpviewer_keywords: - - "COM interop, data marshaling" + - "COM interop, data marshalling" - "marshaling data, COM interop" --- -# Marshaling Data with COM Interop +# Marshalling Data with COM Interop -COM interop provides support for both using COM objects from managed code and exposing managed objects to COM. Support for marshaling data to and from COM is extensive and almost always provides the correct marshaling behavior. +COM interop provides support for both using COM objects from managed code and exposing managed objects to COM. Support for marshalling data to and from COM is extensive and almost always provides the correct marshalling behavior. The Windows SDK includes the following COM interop tools: -- [Type Library Importer (Tlbimp.exe)](../tools/tlbimp-exe-type-library-importer.md), which converts a COM type library to an interop assembly. From this assembly, the interop marshaling service generates wrappers that perform data marshaling between managed and unmanaged memory. +- [Type Library Importer (Tlbimp.exe)](../tools/tlbimp-exe-type-library-importer.md), which converts a COM type library to an interop assembly. From this assembly, the interop marshalling service generates wrappers that perform data marshalling between managed and unmanaged memory. -- [Type Library Exporter (Tlbexp.exe)](../tools/tlbexp-exe-type-library-exporter.md), which produces a COM type library from an assembly and generates a wrapper that performs marshaling during method calls. +- [Type Library Exporter (Tlbexp.exe)](../tools/tlbexp-exe-type-library-exporter.md), which produces a COM type library from an assembly and generates a wrapper that performs marshalling during method calls. - The following sections link to topics that describe the processes for customizing interop wrappers when you can (or must) supply the marshaler with additional type information. + The following sections link to topics that describe the processes for customizing interop wrappers when you can (or must) supply the marshaller with additional type information. ## In This Section @@ -35,7 +35,7 @@ Describes how to create a COM wrapper manually in managed source code. Describes how to explicitly marshal data types using the attribute at design time. [Customizing Runtime Callable Wrappers](/previous-versions/dotnet/netframework-4.0/e753eftz(v=vs.100)) - Describes how to adjust the marshaling behavior of types in an interop assembly and how to define COM types manually. + Describes how to adjust the marshalling behavior of types in an interop assembly and how to define COM types manually. [Advanced COM Interoperability](/previous-versions/dotnet/netframework-4.0/bd9cdfyx(v=vs.100)) Provides links to more information about incorporating COM components into your .NET Framework application. diff --git a/docs/framework/interop/marshaling-data-with-platform-invoke.md b/docs/framework/interop/marshalling-data-with-platform-invoke.md similarity index 93% rename from docs/framework/interop/marshaling-data-with-platform-invoke.md rename to docs/framework/interop/marshalling-data-with-platform-invoke.md index c4cbae9c323b8..4c8b27227bacd 100644 --- a/docs/framework/interop/marshaling-data-with-platform-invoke.md +++ b/docs/framework/interop/marshalling-data-with-platform-invoke.md @@ -1,16 +1,16 @@ --- -title: "Marshaling Data with Platform Invoke" +title: "Marshalling Data with Platform Invoke" description: Marshal data with platform invoke in .NET. See a list of data types used in Windows APIs and C-style functions, and find their .NET managed type equivalents. ms.date: "03/20/2019" dev_langs: - "cpp" helpviewer_keywords: - - "platform invoke, marshaling data" - - "data marshaling, platform invoke" + - "platform invoke, marshalling data" + - "data marshalling, platform invoke" - "marshaling, platform invoke" ms.assetid: dc5c76cf-7b12-406f-b79c-d1a023ec245d --- -# Marshaling Data with Platform Invoke +# Marshalling Data with Platform Invoke To call functions exported from an unmanaged library, a .NET Framework application requires a function prototype in managed code that represents the unmanaged function. To create a prototype that enables platform invoke to marshal data correctly, you must do the following: @@ -74,6 +74,6 @@ internal static extern int TestStructInStruct(ref MyPerson2 person2); For more information and examples, see the following articles: -- [Marshaling Classes, Structures, and Unions](marshaling-classes-structures-and-unions.md) -- [Marshaling Strings](marshaling-strings.md) -- [Marshaling Different Types of Arrays](marshaling-different-types-of-arrays.md) +- [Marshalling Classes, Structures, and Unions](marshalling-classes-structures-and-unions.md) +- [Marshalling Strings](marshalling-strings.md) +- [Marshalling Different Types of Arrays](marshalling-different-types-of-arrays.md) diff --git a/docs/framework/interop/marshaling-different-types-of-arrays.md b/docs/framework/interop/marshalling-different-types-of-arrays.md similarity index 82% rename from docs/framework/interop/marshaling-different-types-of-arrays.md rename to docs/framework/interop/marshalling-different-types-of-arrays.md index a6cef102d011b..36cafe05276d4 100644 --- a/docs/framework/interop/marshaling-different-types-of-arrays.md +++ b/docs/framework/interop/marshalling-different-types-of-arrays.md @@ -1,5 +1,5 @@ --- -title: "Marshaling Different Types of Arrays" +title: "Marshalling Different Types of Arrays" description: Marshal different array types, like integers by value or reference, 2-dimensional integers by value, strings by value, and structures with integers or strings. ms.date: "03/30/2017" dev_langs: @@ -7,14 +7,14 @@ dev_langs: - "vb" helpviewer_keywords: - "marshaling, Arrays sample" - - "data marshaling, Arrays sample" + - "data marshalling, Arrays sample" ms.assetid: c5ac9920-5b6e-4dc9-bf2d-1f6f8ad3b0bf --- -# Marshaling Different Types of Arrays +# Marshalling Different Types of Arrays An array is a reference type in managed code that contains one or more elements of the same type. Although arrays are reference types, they are passed as In parameters to unmanaged functions. This behavior is inconsistent with way managed arrays are passed to managed objects, which is as In/Out parameters. For additional details, see [Copying and Pinning](copying-and-pinning.md). - The following table lists marshaling options for arrays and describes their usage. + The following table lists marshalling options for arrays and describes their usage. |Array|Description| |-----------|-----------------| @@ -41,7 +41,7 @@ An array is a reference type in managed code that contains one or more elements - Array of structures with strings. - Unless an array is explicitly marshaled by reference, the default behavior marshals the array as an In parameter. You can change this behavior by applying the and attributes explicitly. + Unless an array is explicitly marshalled by reference, the default behavior marshals the array as an In parameter. You can change this behavior by applying the and attributes explicitly. The Arrays sample uses the following unmanaged functions, shown with their original function declaration: @@ -81,7 +81,7 @@ An array is a reference type in managed code that contains one or more elements int TestArrayOfStructs2 (MYPERSON* pPersonArray, int size); ``` - [PinvokeLib.dll](marshaling-data-with-platform-invoke.md#pinvokelibdll) is a custom unmanaged library that contains implementations for the previously listed functions and two structure variables, **MYPOINT** and **MYPERSON**. The structures contain the following elements: + [PinvokeLib.dll](marshalling-data-with-platform-invoke.md#pinvokelibdll) is a custom unmanaged library that contains implementations for the previously listed functions and two structure variables, **MYPOINT** and **MYPERSON**. The structures contain the following elements: ```cpp typedef struct _MYPOINT @@ -113,5 +113,5 @@ typedef struct _MYPERSON ## See also -- [Platform invoke data types](marshaling-data-with-platform-invoke.md#platform-invoke-data-types) +- [Platform invoke data types](marshalling-data-with-platform-invoke.md#platform-invoke-data-types) - [Creating Prototypes in Managed Code](creating-prototypes-in-managed-code.md) diff --git a/docs/framework/interop/marshaling-strings.md b/docs/framework/interop/marshalling-strings.md similarity index 68% rename from docs/framework/interop/marshaling-strings.md rename to docs/framework/interop/marshalling-strings.md index 0c694a013bb1c..50c815084771e 100644 --- a/docs/framework/interop/marshaling-strings.md +++ b/docs/framework/interop/marshalling-strings.md @@ -1,23 +1,23 @@ --- -title: "Marshaling Strings" -description: Review how to marshal strings. See options for marshaling strings by value or reference, as a result, in a structure or class by value or reference, and more. +title: "Marshalling Strings" +description: Review how to marshal strings. See options for marshalling strings by value or reference, as a result, in a structure or class by value or reference, and more. ms.date: "03/30/2017" helpviewer_keywords: - "marshaling, samples" - - "platform invoke, marshaling data" - - "data marshaling, strings" - - "data marshaling, samples" - - "data marshaling, platform invoke" + - "platform invoke, marshalling data" + - "data marshalling, strings" + - "data marshalling, samples" + - "data marshalling, platform invoke" - "marshaling. strings" - "marshaling, platform invoke" - - "sample applications [.NET Framework], marshaling strings" + - "sample applications [.NET Framework], marshalling strings" ms.assetid: e21b078b-70fb-4905-be26-c097ab2433ff --- -# Marshaling Strings +# Marshalling Strings Platform invoke copies string parameters, converting them from the .NET Framework format (Unicode) to the unmanaged format (ANSI), if needed. Because managed strings are immutable, platform invoke does not copy them back from unmanaged memory to managed memory when the function returns. - The following table lists marshaling options for strings, describes their usage, and provides a link to the corresponding .NET Framework sample. + The following table lists marshalling options for strings, describes their usage, and provides a link to the corresponding .NET Framework sample. |String|Description|Sample| |------------|-----------------|------------| @@ -29,13 +29,13 @@ Platform invoke copies string parameters, converting them from the .NET Framewor |In a structure by reference **(char[])**.|Passes strings in a structure that is an In/Out parameter. The unmanaged function expects an embedded character buffer.|[OSInfo](/previous-versions/dotnet/netframework-4.0/795sy883(v=vs.100))| |In a class by value **(char\*)**.|Passes strings in a class (a class is an In/Out parameter). The unmanaged function expects a pointer to a character buffer.|[OpenFileDlg](/previous-versions/dotnet/netframework-4.0/w5tyztk9(v=vs.100))| |In a class by value **(char[])**.|Passes strings in a class (a class is an In/Out parameter). The unmanaged function expects an embedded character buffer.|[OSInfo](/previous-versions/dotnet/netframework-4.0/795sy883(v=vs.100))| -|As an array of strings by value.|Creates an array of strings that is passed by value.|[Arrays](marshaling-different-types-of-arrays.md)| -|As an array of structures that contain strings by value.|Creates an array of structures that contain strings and the array is passed by value.|[Arrays](marshaling-different-types-of-arrays.md)| +|As an array of strings by value.|Creates an array of strings that is passed by value.|[Arrays](marshalling-different-types-of-arrays.md)| +|As an array of structures that contain strings by value.|Creates an array of structures that contain strings and the array is passed by value.|[Arrays](marshalling-different-types-of-arrays.md)| ## See also -- [Default Marshaling for Strings](default-marshaling-for-strings.md) -- [Marshaling Data with Platform Invoke](marshaling-data-with-platform-invoke.md) -- [Marshaling Classes, Structures, and Unions](marshaling-classes-structures-and-unions.md) -- [Marshaling Different Types of Arrays](marshaling-different-types-of-arrays.md) -- [Miscellaneous Marshaling Samples](/previous-versions/dotnet/netframework-4.0/ss9sb93t(v=vs.100)) +- [Default Marshalling for Strings](default-marshalling-for-strings.md) +- [Marshalling Data with Platform Invoke](marshalling-data-with-platform-invoke.md) +- [Marshalling Classes, Structures, and Unions](marshalling-classes-structures-and-unions.md) +- [Marshalling Different Types of Arrays](marshalling-different-types-of-arrays.md) +- [Miscellaneous Marshalling Samples](/previous-versions/dotnet/netframework-4.0/ss9sb93t(v=vs.100)) diff --git a/docs/framework/interop/msgbox-sample.md b/docs/framework/interop/msgbox-sample.md index cae0f1555651c..726b66dba13d0 100644 --- a/docs/framework/interop/msgbox-sample.md +++ b/docs/framework/interop/msgbox-sample.md @@ -8,7 +8,7 @@ dev_langs: - "cpp" helpviewer_keywords: - "marshaling, MsgBox sample" - - "data marshaling, MsgBox sample" + - "data marshalling, MsgBox sample" ms.assetid: 9e0edff6-cc0d-4d5c-a445-aecf283d9c3a --- # MsgBox Sample @@ -26,7 +26,7 @@ This sample demonstrates how to pass string types by value as In parameters and In this sample, the `NativeMethods` class contains a managed prototype for each unmanaged function called by the `MsgBoxSample` class. The managed prototype methods `MsgBox`, `MsgBox2`, and `MsgBox3` have different declarations for the same unmanaged function. - The declaration for `MsgBox2` produces incorrect output in the message box because the character type, specified as ANSI, is mismatched with the entry point `MessageBoxW`, which is the name of the Unicode function. The declaration for `MsgBox3` creates a mismatch between the **EntryPoint**, **CharSet**, and **ExactSpelling** fields. When called, `MsgBox3` throws an exception. For detailed information on string naming and name marshaling, see [Specifying a Character Set](specifying-a-character-set.md). + The declaration for `MsgBox2` produces incorrect output in the message box because the character type, specified as ANSI, is mismatched with the entry point `MessageBoxW`, which is the name of the Unicode function. The declaration for `MsgBox3` creates a mismatch between the **EntryPoint**, **CharSet**, and **ExactSpelling** fields. When called, `MsgBox3` throws an exception. For detailed information on string naming and name marshalling, see [Specifying a Character Set](specifying-a-character-set.md). ## Declaring Prototypes @@ -42,7 +42,7 @@ This sample demonstrates how to pass string types by value as In parameters and ## See also -- [Marshaling Strings](marshaling-strings.md) -- [Default Marshaling for Strings](default-marshaling-for-strings.md) +- [Marshalling Strings](marshalling-strings.md) +- [Default Marshalling for Strings](default-marshalling-for-strings.md) - [Creating Prototypes in Managed Code](creating-prototypes-in-managed-code.md) - [Specifying a Character Set](specifying-a-character-set.md) diff --git a/docs/framework/interop/platform-invoke-examples.md b/docs/framework/interop/platform-invoke-examples.md index c3490ab0fb570..73824c869c05b 100644 --- a/docs/framework/interop/platform-invoke-examples.md +++ b/docs/framework/interop/platform-invoke-examples.md @@ -17,13 +17,13 @@ ms.assetid: 15926806-f0b7-487e-93a6-4e9367ec689f --- # Platform Invoke Examples -The following examples demonstrate how to define and call the **MessageBox** function in User32.dll, passing a simple string as an argument. In the examples, the field is set to **Auto** to let the target platform determine the character width and string marshaling. +The following examples demonstrate how to define and call the **MessageBox** function in User32.dll, passing a simple string as an argument. In the examples, the field is set to **Auto** to let the target platform determine the character width and string marshalling. [!code-cpp[Conceptual.Interop.PInvoke#1](../../../samples/snippets/cpp/VS_Snippets_CLR/Conceptual.Interop.PInvoke/cpp/Example.cpp#1)] [!code-csharp[Conceptual.Interop.PInvoke#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.Interop.PInvoke/cs/Example1.cs#1)] [!code-vb[Conceptual.Interop.PInvoke#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.Interop.PInvoke/vb/Example1.vb#1)] - For additional examples, see [Marshaling Data with Platform Invoke](marshaling-data-with-platform-invoke.md). + For additional examples, see [Marshalling Data with Platform Invoke](marshalling-data-with-platform-invoke.md). ## See also diff --git a/docs/framework/interop/specifying-a-character-set.md b/docs/framework/interop/specifying-a-character-set.md index 81333e6fe9a6e..8eec8408cf7ba 100644 --- a/docs/framework/interop/specifying-a-character-set.md +++ b/docs/framework/interop/specifying-a-character-set.md @@ -14,7 +14,7 @@ ms.assetid: a8347eb1-295f-46b9-8a78-63331f9ecc50 --- # Specify a character set -The field controls string marshaling and determines how platform invoke finds function names in a DLL. This topic describes both behaviors. +The field controls string marshalling and determines how platform invoke finds function names in a DLL. This topic describes both behaviors. Some APIs export two versions of functions that take string arguments: narrow (ANSI) and wide (Unicode). The Windows API, for instance, includes the following entry-point names for the **MessageBox** function: @@ -26,13 +26,13 @@ The (default value) -- String marshaling +- String marshalling Platform invoke marshals strings from their managed format (Unicode) to ANSI format. @@ -44,7 +44,7 @@ The -- String marshaling +- String marshalling Platform invoke copies strings from their managed format (Unicode) to Unicode format. @@ -88,7 +88,7 @@ End Class ## Specify a character set in C# and C++ -The field identifies the underlying character set as ANSI or Unicode. The character set controls how string arguments to a method should be marshaled. Use one of the following forms to indicate the character set: +The field identifies the underlying character set as ANSI or Unicode. The character set controls how string arguments to a method should be marshalled. Use one of the following forms to indicate the character set: ```csharp [DllImport("DllName", CharSet = CharSet.Ansi)] @@ -148,4 +148,4 @@ extern "C" int MessageBox( - - [Creating Prototypes in Managed Code](creating-prototypes-in-managed-code.md) - [Platform Invoke Examples](platform-invoke-examples.md) -- [Marshaling Data with Platform Invoke](marshaling-data-with-platform-invoke.md) +- [Marshalling Data with Platform Invoke](marshalling-data-with-platform-invoke.md) diff --git a/docs/framework/interop/specifying-an-entry-point.md b/docs/framework/interop/specifying-an-entry-point.md index 0dc7e6817e1f1..482ae476fe865 100644 --- a/docs/framework/interop/specifying-an-entry-point.md +++ b/docs/framework/interop/specifying-an-entry-point.md @@ -91,4 +91,4 @@ extern "C" int MsgBox( - - [Creating Prototypes in Managed Code](creating-prototypes-in-managed-code.md) - [Platform Invoke Examples](platform-invoke-examples.md) -- [Marshaling Data with Platform Invoke](marshaling-data-with-platform-invoke.md) +- [Marshalling Data with Platform Invoke](marshalling-data-with-platform-invoke.md) diff --git a/docs/framework/interop/toc.yml b/docs/framework/interop/toc.yml index 7e72eb34b30a4..c20ab6d00319a 100644 --- a/docs/framework/interop/toc.yml +++ b/docs/framework/interop/toc.yml @@ -53,36 +53,36 @@ - name: "How to: Implement Callback Functions" href: how-to-implement-callback-functions.md - name: Interop Marshaling - href: interop-marshaling.md + href: /dotnet/framework/interop/interop-marshalling items: - - name: Default Marshaling Behavior - href: default-marshaling-behavior.md + - name: Default Marshalling Behavior + href: /dotnet/framework/interop/default-marshalling-behavior items: - name: Blittable and Non-Blittable Types href: blittable-and-non-blittable-types.md - name: Copying and Pinning href: copying-and-pinning.md - - name: Default Marshaling for Arrays - href: default-marshaling-for-arrays.md - - name: Default Marshaling for Objects - href: default-marshaling-for-objects.md - - name: Default Marshaling for Strings - href: default-marshaling-for-strings.md - - name: Marshaling Data with Platform Invoke - href: marshaling-data-with-platform-invoke.md + - name: Default Marshalling for Arrays + href: /dotnet/framework/interop/default-marshalling-for-arrays + - name: Default Marshalling for Objects + href: /dotnet/framework/interop/default-marshalling-for-objects + - name: Default Marshalling for Strings + href: /dotnet/framework/interop/default-marshalling-for-strings + - name: Marshalling Data with Platform Invoke + href: marshalling-data-with-platform-invoke.md items: - - name: Marshaling Strings - href: marshaling-strings.md + - name: Marshalling Strings + href: marshalling-strings.md - name: MsgBox Sample href: msgbox-sample.md - - name: Marshaling Classes, Structures, and Unions - href: marshaling-classes-structures-and-unions.md - - name: Marshaling Different Types of Arrays - href: marshaling-different-types-of-arrays.md - - name: Marshaling a Delegate as a Callback Method - href: marshaling-a-delegate-as-a-callback-method.md - - name: Marshaling Data with COM Interop - href: marshaling-data-with-com-interop.md + - name: Marshalling Classes, Structures, and Unions + href: marshalling-classes-structures-and-unions.md + - name: Marshalling Different Types of Arrays + href: marshalling-different-types-of-arrays.md + - name: Marshalling a Delegate as a Callback Method + href: marshalling-a-delegate-as-a-callback-method.md + - name: Marshalling Data with COM Interop + href: marshalling-data-with-com-interop.md items: - name: "How to: Create Wrappers Manually" href: how-to-create-wrappers-manually.md diff --git a/docs/framework/migration-guide/mitigation-deserialization-of-objects-across-app-domains.md b/docs/framework/migration-guide/mitigation-deserialization-of-objects-across-app-domains.md index d8b442166a095..f4ecb3c5c33df 100644 --- a/docs/framework/migration-guide/mitigation-deserialization-of-objects-across-app-domains.md +++ b/docs/framework/migration-guide/mitigation-deserialization-of-objects-across-app-domains.md @@ -28,7 +28,7 @@ In some cases, when an app uses two or more app domains with different applicati 3. The call to get evidence for the default app domain triggers a cross-app domain call from the non-default app domain to the default app domain. - 4. As part of the cross-app domain contract in the .NET Framework, the contents of the logical call context also have to be marshaled across app domain boundaries. + 4. As part of the cross-app domain contract in the .NET Framework, the contents of the logical call context also have to be marshalled across app domain boundaries. 6. Because the types that are in the logical call context cannot be resolved in the default app domain, an exception is thrown. diff --git a/docs/framework/migration-guide/net-framework-4-migration-issues.md b/docs/framework/migration-guide/net-framework-4-migration-issues.md index f7d52de69a168..a7864808c729a 100644 --- a/docs/framework/migration-guide/net-framework-4-migration-issues.md +++ b/docs/framework/migration-guide/net-framework-4-migration-issues.md @@ -121,7 +121,7 @@ Assembly: mscorlib (in mscorlib.dll) | ------- | ------------------------ | ------------------- | | **Buffer length** (unmanaged API) | To save memory, the functionality for the `pBufferLengthOffset` parameter for the [ICorProfilerInfo2::GetStringLayout](../unmanaged-api/profiling/icorprofilerinfo2-getstringlayout-method.md) method has been changed to match the `pStringLengthOffset` parameter. Both parameters now point to the offset location of the string's length. Buffer length has been removed from the representation of the string class. | Remove any dependency on the buffer length. | | **JIT debugging** | To simplify registration for just-in-time (JIT) debugging, the .NET Framework debugger now uses only the AeDebug registry key, which controls the JIT debugging behavior for native code. This change results in the following:

\* You can no longer register two different debuggers for managed and native code.
\* You can no longer start the debugger automatically for a non-interactive process, but you can prompt the user for an interactive process.
\* You are no longer notified when the debugger fails to start, or when there is no registered debugger that should be started.
\* Auto-launch policies that depend on the interactivity of the application are no longer supported. | Adjust debugging operations as required. | -| **Platform invoke** | To improve performance in interoperability with unmanaged code, incorrect calling conventions in a platform invoke now cause the application to fail. In previous versions, the marshaling layer resolved these errors up the stack. | Debugging your applications in Microsoft Visual Studio alerts you to these errors so you can correct them.

If you have binaries that cannot be updated, you can include the [\](../configure-apps/file-schema/runtime/netfx40-pinvokestackresilience-element.md) element in your application's configuration file to enable calling errors to be resolved up the stack as in earlier versions. However, this may affect the performance of your application. | +| **Platform invoke** | To improve performance in interoperability with unmanaged code, incorrect calling conventions in a platform invoke now cause the application to fail. In previous versions, the marshalling layer resolved these errors up the stack. | Debugging your applications in Microsoft Visual Studio alerts you to these errors so you can correct them.

If you have binaries that cannot be updated, you can include the [\](../configure-apps/file-schema/runtime/netfx40-pinvokestackresilience-element.md) element in your application's configuration file to enable calling errors to be resolved up the stack as in earlier versions. However, this may affect the performance of your application. | | **Removed interfaces** (unmanaged API) | To avoid developer confusion, the following interfaces were removed, because they did not provide any useful run-time scenarios, and the CLR did not provide or accept any implementations:

\* **INativeImageINativeImageDependency**
\* **INativeImageInstallInfo**
\* **INativeImageEvaluate**
\* **INativeImageConverter**
\* **ICorModule**
\* **IMetaDataConverter** | None. | ## Data diff --git a/docs/framework/reflection-and-codedom/collectible-assemblies.md b/docs/framework/reflection-and-codedom/collectible-assemblies.md index 889f8e320a31f..5f6c4d0c1c966 100644 --- a/docs/framework/reflection-and-codedom/collectible-assemblies.md +++ b/docs/framework/reflection-and-codedom/collectible-assemblies.md @@ -58,10 +58,10 @@ The following restrictions apply to collectible assemblies: No COM interfaces can be defined within a collectible assembly, and no instances of types within a collectible assembly can be converted into COM objects. A type in a collectible assembly cannot serve as a COM callable wrapper (CCW) or runtime callable wrapper (RCW). However, types in collectible assemblies can use objects that implement COM interfaces. - **Platform invoke** - Methods that have the attribute will not compile when they are declared in a collectible assembly. The instruction cannot be used in the implementation of a type in a collectible assembly, and such types cannot be marshaled to unmanaged code. However, you can call into native code by using an entry point that is declared in a non-collectible assembly. + Methods that have the attribute will not compile when they are declared in a collectible assembly. The instruction cannot be used in the implementation of a type in a collectible assembly, and such types cannot be marshalled to unmanaged code. However, you can call into native code by using an entry point that is declared in a non-collectible assembly. - **Marshaling** - Objects (in particular, delegates) that are defined in collectible assemblies cannot be marshaled. This is a restriction on all transient emitted types. + Objects (in particular, delegates) that are defined in collectible assemblies cannot be marshalled. This is a restriction on all transient emitted types. - **Assembly loading** Reflection emit is the only mechanism that is supported for loading collectible assemblies. Assemblies that are loaded by using any other form of assembly loading cannot be unloaded. diff --git a/docs/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios.md b/docs/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios.md index 4eedde05c615c..436d3136e335e 100644 --- a/docs/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios.md +++ b/docs/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios.md @@ -137,7 +137,7 @@ The following procedure explains how to define a class by using methods that can > [!NOTE] > If you use this code in Visual Studio, you must change the name of the class to include the namespace. By default, the namespace is the name of the project. For example, if the project is "PartialTrust", the class name must be "PartialTrust.Worker". -6. Add code to call the `SimpleEmitDemo` method. The call is marshaled across the application domain boundary, and the code is executed in the sandboxed application domain. +6. Add code to call the `SimpleEmitDemo` method. The call is marshalled across the application domain boundary, and the code is executed in the sandboxed application domain. [!code-csharp[HowToEmitCodeInPartialTrust#13](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEmitCodeInPartialTrust/cs/source.cs#13)] [!code-vb[HowToEmitCodeInPartialTrust#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEmitCodeInPartialTrust/vb/source.vb#13)] @@ -191,7 +191,7 @@ To prevent elevation of privilege, stack information for the emitting assembly i The following code example demonstrates the use of the flag to allow anonymously hosted dynamic methods to skip JIT visibility checks, but only when the target member is at an equal or lower level of trust than the assembly that emits the code. -The example defines a `Worker` class that can be marshaled across application domain boundaries. The class has two `AccessPrivateMethod` method overloads that emit and execute dynamic methods. The first overload emits a dynamic method that calls the private `PrivateMethod` method of the `Worker` class, and it can emit the dynamic method with or without JIT visibility checks. The second overload emits a dynamic method that accesses an `internal` property (`Friend` property in Visual Basic) of the class. +The example defines a `Worker` class that can be marshalled across application domain boundaries. The class has two `AccessPrivateMethod` method overloads that emit and execute dynamic methods. The first overload emits a dynamic method that calls the private `PrivateMethod` method of the `Worker` class, and it can emit the dynamic method with or without JIT visibility checks. The second overload emits a dynamic method that accesses an `internal` property (`Friend` property in Visual Basic) of the class. The example uses a helper method to create a grant set limited to `Internet` permissions, and then creates an application domain, using the method overload to specify that all code that executes in the domain uses this grant set. The example creates an instance of the `Worker` class in the application domain, and executes the `AccessPrivateMethod` method two times. diff --git a/docs/framework/unmanaged-api/debugging/icordebugchain-getcallee-method.md b/docs/framework/unmanaged-api/debugging/icordebugchain-getcallee-method.md index 99f539386dcd6..be875dba6612b 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugchain-getcallee-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugchain-getcallee-method.md @@ -36,7 +36,7 @@ HRESULT GetCallee ( ## Remarks - This chain will wait for the called chain to return before it resumes execution. The called chain may be on another thread in the case of cross-thread marshaled calls. + This chain will wait for the called chain to return before it resumes execution. The called chain may be on another thread in the case of cross-thread marshalled calls. ## Requirements diff --git a/docs/framework/unmanaged-api/debugging/icordebugchain-getcaller-method.md b/docs/framework/unmanaged-api/debugging/icordebugchain-getcaller-method.md index 54fb027124f0b..5d619b9d824c5 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugchain-getcaller-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugchain-getcaller-method.md @@ -38,7 +38,7 @@ HRESULT GetCaller ( ## Remarks - The calling chain may be on a different thread, if the call was marshaled across threads. + The calling chain may be on a different thread, if the call was marshalled across threads. ## Requirements diff --git a/docs/framework/unmanaged-api/debugging/icordebugstepper-interface.md b/docs/framework/unmanaged-api/debugging/icordebugstepper-interface.md index 41ead20a7fc34..d71b2c69db957 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugstepper-interface.md +++ b/docs/framework/unmanaged-api/debugging/icordebugstepper-interface.md @@ -45,7 +45,7 @@ Represents a step in code execution that is performed by a debugger, serves as a There can be more than one stepper per thread. For example, a breakpoint may be hit while stepping over a function, and the user may wish to start a new stepping operation inside that function. It is up to the debugger to determine how to handle this situation. The debugger may want to cancel the original stepping operation or nest the two operations. The `ICorDebugStepper` interface supports both choices. - A stepper may migrate between threads if the common language runtime (CLR) makes a cross-threaded, marshaled call. + A stepper may migrate between threads if the common language runtime (CLR) makes a cross-threaded, marshalled call. > [!NOTE] > This interface does not support being called remotely, either cross-machine or cross-process. diff --git a/docs/framework/unmanaged-api/hosting/comcallunmarshal-coclass.md b/docs/framework/unmanaged-api/hosting/comcallunmarshal-coclass.md index ff91265d02dca..6bd1331a43155 100644 --- a/docs/framework/unmanaged-api/hosting/comcallunmarshal-coclass.md +++ b/docs/framework/unmanaged-api/hosting/comcallunmarshal-coclass.md @@ -18,7 +18,7 @@ topic_type: --- # ComCallUnmarshal Coclass -Provides interfaces for managing the marshaling of interface pointers. +Provides interfaces for managing the marshalling of interface pointers. ## Syntax diff --git a/docs/framework/unmanaged-api/hosting/hosting-coclasses.md b/docs/framework/unmanaged-api/hosting/hosting-coclasses.md index b2f4036de34af..d6dee8e980612 100644 --- a/docs/framework/unmanaged-api/hosting/hosting-coclasses.md +++ b/docs/framework/unmanaged-api/hosting/hosting-coclasses.md @@ -18,7 +18,7 @@ This section describes the unmanaged API coclasses that the hosting API uses. Provides interfaces for managing code execution by the runtime. [ComCallUnmarshal Coclass](comcallunmarshal-coclass.md) - Provides interfaces for managing the marshaling of interface pointers. + Provides interfaces for managing the marshalling of interface pointers. [CorRuntimeHost Coclass](corruntimehost-coclass.md) Provides interfaces for managing applications that are being executed by the common language runtime. diff --git a/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-impersonateloggedonuser-method.md b/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-impersonateloggedonuser-method.md index fd95978afa15d..74bff93ef58c9 100644 --- a/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-impersonateloggedonuser-method.md +++ b/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-impersonateloggedonuser-method.md @@ -49,7 +49,7 @@ HRESULT ImpersonateLoggedOnUser ( Call `LogonUser` or a related Win32 function to get a handle to the credentials of the current user identity. - The `HANDLE` type is not COM-compliant, that is, its size is specific to an operating system, and it requires custom marshaling. Thus, this token is for use only within the process, between the CLR and the host. + The `HANDLE` type is not COM-compliant, that is, its size is specific to an operating system, and it requires custom marshalling. Thus, this token is for use only within the process, between the CLR and the host. ## Requirements diff --git a/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-openthreadtoken-method.md b/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-openthreadtoken-method.md index d5c9f7479b053..fb8d49e190fbf 100644 --- a/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-openthreadtoken-method.md +++ b/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-openthreadtoken-method.md @@ -57,7 +57,7 @@ HRESULT OpenThreadToken ( `IHostSecurityManager::OpenThreadToken` behaves similarly to the corresponding Win32 function of the same name, except that the Win32 function allows the caller to pass in a handle to an arbitrary thread, while `IHostSecurityManager::OpenThreadToken` opens only the token associated with the calling thread. - The `HANDLE` type is not COM-compliant, that is, its size is specific to the operating system, and it requires custom marshaling. Thus, this token is for use only within the process, between the CLR and the host. + The `HANDLE` type is not COM-compliant, that is, its size is specific to the operating system, and it requires custom marshalling. Thus, this token is for use only within the process, between the CLR and the host. ## Requirements diff --git a/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-setthreadtoken-method.md b/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-setthreadtoken-method.md index 34ad0e3fad9b8..82eccc9d768bd 100644 --- a/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-setthreadtoken-method.md +++ b/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-setthreadtoken-method.md @@ -49,7 +49,7 @@ HRESULT SetThreadToken ( `IHostSecurityManager::SetThreadToken` behaves similarly to the corresponding Win32 function of the same name, except that the Win32 function allows the caller to pass in a handle to an arbitrary thread, while `IHostSecurityManager::SetThreadToken` can associate a token only with the currently executing thread. - The `HANDLE` type is not COM-compliant; that is, its size is specific to an operating system and it requires custom marshaling. Thus, this token is for use only within the process, between the CLR and the host. + The `HANDLE` type is not COM-compliant; that is, its size is specific to an operating system and it requires custom marshalling. Thus, this token is for use only within the process, between the CLR and the host. ## Requirements diff --git a/docs/framework/unmanaged-api/hosting/imanagedobject-getserializedbuffer-method.md b/docs/framework/unmanaged-api/hosting/imanagedobject-getserializedbuffer-method.md index b9d98a2dc22a2..c0aaecd511870 100644 --- a/docs/framework/unmanaged-api/hosting/imanagedobject-getserializedbuffer-method.md +++ b/docs/framework/unmanaged-api/hosting/imanagedobject-getserializedbuffer-method.md @@ -36,7 +36,7 @@ HRESULT GetSerializedBuffer ( ## Remarks - The `GetSerializedBuffer` method serializes the object so it can be marshaled to the client. + The `GetSerializedBuffer` method serializes the object so it can be marshalled to the client. ## Requirements diff --git a/docs/framework/unmanaged-api/metadata/corfieldattr-enumeration.md b/docs/framework/unmanaged-api/metadata/corfieldattr-enumeration.md index 049e78dffb7b4..b8ecd21339fa1 100644 --- a/docs/framework/unmanaged-api/metadata/corfieldattr-enumeration.md +++ b/docs/framework/unmanaged-api/metadata/corfieldattr-enumeration.md @@ -72,7 +72,7 @@ typedef enum CorFieldAttr { |`fdPinvokeImpl`|Specifies that the field implementation is forwarded through PInvoke.| |`fdReservedMask`|Reserved for internal use by the common language runtime.| |`fdRTSpecialName`|Specifies that the common language runtime metadata internal APIs should check the encoding of the name.| -|`fdHasFieldMarshal`|Specifies that the field contains marshaling information.| +|`fdHasFieldMarshal`|Specifies that the field contains marshalling information.| |`fdHasDefault`|Specifies that the field has a default value.| |`fdHasFieldRVA`|Specifies that the field has a relative virtual address.| diff --git a/docs/framework/unmanaged-api/metadata/cornativetype-enumeration.md b/docs/framework/unmanaged-api/metadata/cornativetype-enumeration.md index 309e793a108bc..0d7bdbe719a47 100644 --- a/docs/framework/unmanaged-api/metadata/cornativetype-enumeration.md +++ b/docs/framework/unmanaged-api/metadata/cornativetype-enumeration.md @@ -127,7 +127,7 @@ typedef enum CorNativeType { |`NATIVE_TYPE_ASANY`|A reference to any native type.| |`NATIVE_TYPE_ARRAY`|A reference to an array with members of an unspecified type.| |`NATIVE_TYPE_LPSTRUCT`|A 32-bit integer pointer to a structure.| -|`NATIVE_TYPE_CUSTOMMARSHALER`|A custom marshaler native type.

This must be followed by a string of the following format: "Native type name/0Custom marshaler type name/0Optional cookie/0" or "{Native type GUID}/0Custom marshaler type name/0Optional cookie/0"| +|`NATIVE_TYPE_CUSTOMMARSHALER`|A custom marshaller native type.

This must be followed by a string of the following format: "Native type name/0Custom marshaller type name/0Optional cookie/0" or "{Native type GUID}/0Custom marshaller type name/0Optional cookie/0"| |`NATIVE_TYPE_ERROR`|COM Interop.

With ELEMENT_TYPE_I4 this type maps to VT_HRESULT.| |`NATIVE_TYPE_IINSPECTABLE`|A native `IInspectable` type.| |`NATIVE_TYPE_HSTRING`|A native `HString`.| diff --git a/docs/framework/unmanaged-api/metadata/corparamattr-enumeration.md b/docs/framework/unmanaged-api/metadata/corparamattr-enumeration.md index 48b780ac71d94..49f835e74ddef 100644 --- a/docs/framework/unmanaged-api/metadata/corparamattr-enumeration.md +++ b/docs/framework/unmanaged-api/metadata/corparamattr-enumeration.md @@ -47,7 +47,7 @@ typedef enum CorParamAttr { |`pdOptional`|Specifies that the parameter is optional.| |`pdReservedMask`|Reserved for internal use by the common language runtime.| |`pdHasDefault`|Specifies that the parameter has a default value.| -|`pdHasFieldMarshal`|Specifies that the parameter has marshaling information.| +|`pdHasFieldMarshal`|Specifies that the parameter has marshalling information.| |`pdUnused`|Unused.| ## Requirements diff --git a/docs/framework/unmanaged-api/metadata/corpinvokemap-enumeration.md b/docs/framework/unmanaged-api/metadata/corpinvokemap-enumeration.md index e6e1313963e94..8ec4fa5780ab5 100644 --- a/docs/framework/unmanaged-api/metadata/corpinvokemap-enumeration.md +++ b/docs/framework/unmanaged-api/metadata/corpinvokemap-enumeration.md @@ -72,8 +72,8 @@ typedef enum CorPinvokeMap { |`pmBestFitDisabled`|Do not perform best-fit mapping of Unicode characters. In this case, all unmappable characters will be replaced by a ‘?’.| |`pmBestFitMask`|Reserved.| |`pmThrowOnUnmappableCharUseAssem`|Reserved.| -|`pmThrowOnUnmappableCharEnabled`|Throw an exception when the interop marshaler encounters an unmappable character.| -|`pmThrowOnUnmappableCharDisabled`|Do not throw an exception when the interop marshaler encounters an unmappable character.| +|`pmThrowOnUnmappableCharEnabled`|Throw an exception when the interop marshaller encounters an unmappable character.| +|`pmThrowOnUnmappableCharDisabled`|Do not throw an exception when the interop marshaller encounters an unmappable character.| |`pmThrowOnUnmappableCharMask`|Reserved| |`pmSupportsLastError`|Allow the callee to call the Win32 `SetLastError` function before returning from the attributed method.| |`pmCallConvMask`|Reserved| diff --git a/docs/framework/unmanaged-api/metadata/imetadataemit-deletefieldmarshal-method.md b/docs/framework/unmanaged-api/metadata/imetadataemit-deletefieldmarshal-method.md index ccb2f3e702931..4fb511e628d50 100644 --- a/docs/framework/unmanaged-api/metadata/imetadataemit-deletefieldmarshal-method.md +++ b/docs/framework/unmanaged-api/metadata/imetadataemit-deletefieldmarshal-method.md @@ -19,7 +19,7 @@ topic_type: --- # IMetaDataEmit::DeleteFieldMarshal Method -Destroys the PInvoke marshaling metadata signature for the object referenced by the specified token. +Destroys the PInvoke marshalling metadata signature for the object referenced by the specified token. ## Syntax @@ -32,7 +32,7 @@ HRESULT DeleteFieldMarshal ( ## Parameters `tk` - [in] An `mdFieldDef` or `mdParamDef` token that represents the field or parameter for which to delete the marshaling metadata signature. + [in] An `mdFieldDef` or `mdParamDef` token that represents the field or parameter for which to delete the marshalling metadata signature. ## Requirements diff --git a/docs/framework/unmanaged-api/metadata/imetadataemit-interface.md b/docs/framework/unmanaged-api/metadata/imetadataemit-interface.md index 6df9c68e42454..1af10de0ad2ac 100644 --- a/docs/framework/unmanaged-api/metadata/imetadataemit-interface.md +++ b/docs/framework/unmanaged-api/metadata/imetadataemit-interface.md @@ -44,7 +44,7 @@ Provides methods to create, modify, and save metadata about the assembly in the |[DefineTypeRefByName Method](imetadataemit-definetyperefbyname-method.md)|Gets a metadata token for a type that is defined in another module outside the current scope.| |[DefineUserString Method](imetadataemit-defineuserstring-method.md)|Gets a metadata token for the specified literal string.| |[DeleteClassLayout Method](imetadataemit-deleteclasslayout-method.md)|Destroys the class layout metadata signature for the type referenced by the specified token.| -|[DeleteFieldMarshal Method](imetadataemit-deletefieldmarshal-method.md)|Destroys the PInvoke marshaling metadata signature for the object referenced by the specified token.| +|[DeleteFieldMarshal Method](imetadataemit-deletefieldmarshal-method.md)|Destroys the PInvoke marshalling metadata signature for the object referenced by the specified token.| |[DeletePinvokeMap Method](imetadataemit-deletepinvokemap-method.md)|Destroys the PInvoke mapping metadata for the object referenced by the specified token.| |[DeleteToken Method](imetadataemit-deletetoken-method.md)|Deletes the specified token from the current metadata scope.| |[GetSaveSize Method](imetadataemit-getsavesize-method.md)|Gets the estimated binary size of the assembly in the current scope.| @@ -58,7 +58,7 @@ Provides methods to create, modify, and save metadata about the assembly in the |[SetClassLayout Method](imetadataemit-setclasslayout-method.md)|Sets or updates the class layout signature of a type defined by a prior call to `IMetaDataEmit::DefineTypeDef`.| |[SetCustomAttributeValue Method](imetadataemit-setcustomattributevalue-method.md)|Sets or updates the value of a custom attribute defined by a prior call to `IMetaDataEmit::DefineCustomAttribute`.| |[SetEventProps Method](imetadataemit-seteventprops-method.md)|Sets or updates the specified feature of an event defined by a prior call to `IMetaDataEmit::DefineEvent`.| -|[SetFieldMarshal Method](imetadataemit-setfieldmarshal-method.md)|Sets the PInvoke marshaling information for the field, method return, or method parameter referenced by the specified token.| +|[SetFieldMarshal Method](imetadataemit-setfieldmarshal-method.md)|Sets the PInvoke marshalling information for the field, method return, or method parameter referenced by the specified token.| |[SetFieldProps Method](imetadataemit-setfieldprops-method.md)|Sets or updates the default value for the field referenced by the specified field token.| |[SetFieldRVA Method](imetadataemit-setfieldrva-method.md)|Sets a global variable value for the relative virtual address of the field referenced by the specified token.| |[SetHandler Method](imetadataemit-sethandler-method.md)|Sets the method referenced by the specified `IUnknown` pointer as a notification callback for token remaps.| diff --git a/docs/framework/unmanaged-api/metadata/imetadataemit-setfieldmarshal-method.md b/docs/framework/unmanaged-api/metadata/imetadataemit-setfieldmarshal-method.md index 26287717db1f1..2a65b79c400f1 100644 --- a/docs/framework/unmanaged-api/metadata/imetadataemit-setfieldmarshal-method.md +++ b/docs/framework/unmanaged-api/metadata/imetadataemit-setfieldmarshal-method.md @@ -19,7 +19,7 @@ topic_type: --- # IMetaDataEmit::SetFieldMarshal Method -Sets the PInvoke marshaling information for the field, method return, or method parameter referenced by the specified token. +Sets the PInvoke marshalling information for the field, method return, or method parameter referenced by the specified token. ## Syntax diff --git a/docs/framework/unmanaged-api/metadata/imetadataimport-getfieldmarshal-method.md b/docs/framework/unmanaged-api/metadata/imetadataimport-getfieldmarshal-method.md index 2f614b601992a..753375bf7dc76 100644 --- a/docs/framework/unmanaged-api/metadata/imetadataimport-getfieldmarshal-method.md +++ b/docs/framework/unmanaged-api/metadata/imetadataimport-getfieldmarshal-method.md @@ -34,7 +34,7 @@ HRESULT GetFieldMarshal ( ## Parameters `tk` - [in] The metadata token that represents the field to get interop marshaling information for. + [in] The metadata token that represents the field to get interop marshalling information for. `ppvNativeType` [out] A pointer to the metadata signature of the field's native type. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1417.md b/docs/fundamentals/code-analysis/quality-rules/ca1417.md index 26e8d14812f04..4eee9e4117b59 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1417.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1417.md @@ -31,7 +31,7 @@ The .NET runtime automatically performs [string interning](/dotnet/api/system.st ## How to fix violations -If marshaling of modified string data back to the caller is required, pass the string by reference instead. Otherwise, the can be removed without any other changes. +If marshalling of modified string data back to the caller is required, pass the string by reference instead. Otherwise, the can be removed without any other changes. ```csharp // Violation @@ -42,7 +42,7 @@ private static extern void Foo([Out] string s); [DllImport("MyLibrary")] private static extern void Foo(out string s); -// Fixed: marshaling data back to caller is not required +// Fixed: marshalling data back to caller is not required [DllImport("MyLibrary")] private static extern void Foo(string s); ``` diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1838.md b/docs/fundamentals/code-analysis/quality-rules/ca1838.md index 5a2ffac510be5..cd5495a0dbe57 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1838.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1838.md @@ -27,7 +27,7 @@ A [P/Invoke](../../../standard/native-interop/pinvoke.md) has a |[CA1835: Prefer the 'Memory'-based overloads for 'ReadAsync' and 'WriteAsync'](ca1835.md) | 'Stream' has a 'ReadAsync' overload that takes a 'Memory<Byte>' as the first argument, and a 'WriteAsync' overload that takes a 'ReadOnlyMemory<Byte>' as the first argument. Prefer calling the memory based overloads, which are more efficient. | > |[CA1836: Prefer `IsEmpty` over `Count` when available](ca1836.md) | Prefer `IsEmpty` property that is more efficient than `Count`, `Length`, or to determine whether the object contains or not any items. | > | [CA1837: Use `Environment.ProcessId` instead of `Process.GetCurrentProcess().Id`](ca1837.md) | `Environment.ProcessId` is simpler and faster than `Process.GetCurrentProcess().Id`. | -> | [CA1838: Avoid `StringBuilder` parameters for P/Invokes](ca1838.md) | Marshaling of 'StringBuilder' always creates a native buffer copy, resulting in multiple allocations for one marshaling operation. | +> | [CA1838: Avoid `StringBuilder` parameters for P/Invokes](ca1838.md) | Marshalling of 'StringBuilder' always creates a native buffer copy, resulting in multiple allocations for one marshalling operation. | > | [CA1839: Use Environment.ProcessPath instead of Process.GetCurrentProcess().MainModule.FileName](ca1839.md) | `Environment.ProcessPath` is simpler and faster than `Process.GetCurrentProcess().MainModule.FileName`. | > | [CA1840: Use Environment.CurrentManagedThreadId instead of Thread.CurrentThread.ManagedThreadId](ca1840.md) | `Environment.CurrentManagedThreadId` is more compact and efficient than `Thread.CurrentThread.ManagedThreadId`. | > | [CA1841: Prefer Dictionary Contains methods](ca1841.md) | Calling `Contains` on the `Keys` or `Values` collection may often be more expensive than calling `ContainsKey` or `ContainsValue` on the dictionary itself. | @@ -158,7 +158,7 @@ The following table lists code quality analysis rules. > | [CA2017: Parameter count mismatch](ca2017.md) | Number of parameters supplied in the logging message template do not match the number of named placeholders. | > | [CA2018: The `count` argument to `Buffer.BlockCopy` should specify the number of bytes to copy](ca2018.md) | When using `Buffer.BlockCopy`, the `count` argument specifies the number of bytes to copy. You should only use `Array.Length` for the `count` argument on arrays whose elements are exactly one byte in size. `byte`, `sbyte`, and `bool` arrays have elements that are one byte in size. | > | [CA2100: Review SQL queries for security vulnerabilities](ca2100.md) | A method sets the System.Data.IDbCommand.CommandText property by using a string that is built from a string argument to the method. This rule assumes that the string argument contains user input. A SQL command string that is built from user input is vulnerable to SQL injection attacks. | -> |[CA2101: Specify marshaling for P/Invoke string arguments](ca2101.md) | A platform invoke member allows partially trusted callers, has a string parameter, and does not explicitly marshal the string. This can cause a potential security vulnerability. | +> |[CA2101: Specify marshalling for P/Invoke string arguments](ca2101.md) | A platform invoke member allows partially trusted callers, has a string parameter, and does not explicitly marshal the string. This can cause a potential security vulnerability. | > | [CA2109: Review visible event handlers](ca2109.md) | A public or protected event-handling method was detected. Event-handling methods should not be exposed unless absolutely necessary. | > | [CA2119: Seal methods that satisfy private interfaces](ca2119.md) | An inheritable public type provides an overridable method implementation of an internal (Friend in Visual Basic) interface. To fix a violation of this rule, prevent the method from being overridden outside the assembly. | > |[CA2153: Avoid handling Corrupted State Exceptions](ca2153.md) | Corrupted State Exceptions (CSEs) indicate that memory corruption exists in your process. Catching these rather than allowing the process to crash can lead to security vulnerabilities if an attacker can place an exploit into the corrupted memory region. | diff --git a/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md b/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md index c3c4b0542350b..fed7b06c5e459 100644 --- a/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md +++ b/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md @@ -48,7 +48,7 @@ Performance rules support high-performance libraries and applications. | [CA1835: Prefer the 'Memory'-based overloads for 'ReadAsync' and 'WriteAsync'](ca1835.md) | 'Stream' has a 'ReadAsync' overload that takes a 'Memory<Byte>' as the first argument, and a 'WriteAsync' overload that takes a 'ReadOnlyMemory<Byte>' as the first argument. Prefer calling the memory based overloads, which are more efficient. | | [CA1836: Prefer `IsEmpty` over `Count` when available](ca1836.md) | Prefer `IsEmpty` property that is more efficient than `Count`, `Length`, or to determine whether the object contains or not any items. | | [CA1837: Use `Environment.ProcessId` instead of `Process.GetCurrentProcess().Id`](ca1837.md) | `Environment.ProcessId` is simpler and faster than `Process.GetCurrentProcess().Id`. | -| [CA1838: Avoid `StringBuilder` parameters for P/Invokes](ca1838.md) | Marshaling of `StringBuilder` always creates a native buffer copy, resulting in multiple allocations for one marshaling operation. | +| [CA1838: Avoid `StringBuilder` parameters for P/Invokes](ca1838.md) | Marshalling of `StringBuilder` always creates a native buffer copy, resulting in multiple allocations for one marshalling operation. | | [CA1839: Use Environment.ProcessPath instead of Process.GetCurrentProcess().MainModule.FileName](ca1837.md) | `Environment.ProcessPath` is simpler and faster than `Process.GetCurrentProcess().MainModule.FileName`. | | [CA1840: Use Environment.CurrentManagedThreadId instead of Thread.CurrentThread.ManagedThreadId](ca1837.md) | `Environment.CurrentManagedThreadId` is more compact and efficient than `Thread.CurrentThread.ManagedThreadId`. | | [CA1841: Prefer Dictionary Contains methods](ca1841.md) | Calling `Contains` on the `Keys` or `Values` collection may often be more expensive than calling `ContainsKey` or `ContainsValue` on the dictionary itself. | diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index 0a636a88069f5..143683a428c4e 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -2767,17 +2767,17 @@ items: displayName: Native interop - name: P/Invoke href: ../standard/native-interop/pinvoke.md - - name: Type marshaling - href: ../standard/native-interop/type-marshaling.md - - name: Customize structure marshaling - href: ../standard/native-interop/customize-struct-marshaling.md - - name: Customize parameter marshaling - href: ../standard/native-interop/customize-parameter-marshaling.md + - name: Type marshalling + href: /dotnet/standard/native-interop/type-marshalling + - name: Customize structure marshalling + href: /dotnet/standard/native-interop/customize-struct-marshalling + - name: Customize parameter marshalling + href: /dotnet/standard/native-interop/customize-parameter-marshalling - name: Cross platform P/Invoke href: ../standard/native-interop/cross-platform.md - name: Interop guidance href: ../standard/native-interop/best-practices.md - - name: Charsets and marshaling + - name: Charsets and marshalling href: ../standard/native-interop/charset.md - name: Expose .NET components to COM href: ../core/native-interop/expose-components-to-com.md diff --git a/docs/standard/asynchronous-programming-patterns/best-practices-for-implementing-the-event-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/best-practices-for-implementing-the-event-based-asynchronous-pattern.md index 61e445b8cfedc..a42bd25c7473a 100644 --- a/docs/standard/asynchronous-programming-patterns/best-practices-for-implementing-the-event-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/best-practices-for-implementing-the-event-based-asynchronous-pattern.md @@ -121,7 +121,7 @@ private void Form1_MethodNameCompleted(object sender, MethodNameCompletedEventAr provides one method, , which returns an . Your MethodName**Async** method calls and your class uses the returned to track the lifetime of the asynchronous task. - To report progress, incremental results, and completion to the client, call the and methods on the . is responsible for marshaling calls to the client's event handlers to the proper thread or context. + To report progress, incremental results, and completion to the client, call the and methods on the . is responsible for marshalling calls to the client's event handlers to the proper thread or context. > [!NOTE] > You can circumvent these rules if you explicitly want to go against the policy of the application model, but still benefit from the other advantages of using the Event-based Asynchronous Pattern. For example, you may want a class operating in Windows Forms to be free threaded. You can create a free threaded class, as long as developers understand the implied restrictions. Console applications do not synchronize the execution of calls. This can cause `ProgressChanged` events to be raised out of order. If you wish to have serialized execution of calls, implement and install a class. diff --git a/docs/standard/asynchronous-programming-patterns/implementing-the-task-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/implementing-the-task-based-asynchronous-pattern.md index 8bf38c6a16de2..7f773cf8a4523 100644 --- a/docs/standard/asynchronous-programming-patterns/implementing-the-task-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/implementing-the-task-based-asynchronous-pattern.md @@ -20,7 +20,7 @@ You can implement the Task-based Asynchronous Pattern (TAP) in three ways: by us ### Using the compilers -Starting with .NET Framework 4.5, any method that is attributed with the `async` keyword (`Async` in Visual Basic) is considered an asynchronous method, and the C# and Visual Basic compilers perform the necessary transformations to implement the method asynchronously by using TAP. An asynchronous method should return either a or a object. For the latter, the body of the function should return a `TResult`, and the compiler ensures that this result is made available through the resulting task object. Similarly, any exceptions that go unhandled within the body of the method are marshaled to the output task and cause the resulting task to end in the state. The exception to this rule is when an (or derived type) goes unhandled, in which case the resulting task ends in the state. +Starting with .NET Framework 4.5, any method that is attributed with the `async` keyword (`Async` in Visual Basic) is considered an asynchronous method, and the C# and Visual Basic compilers perform the necessary transformations to implement the method asynchronously by using TAP. An asynchronous method should return either a or a object. For the latter, the body of the function should return a `TResult`, and the compiler ensures that this result is made available through the resulting task object. Similarly, any exceptions that go unhandled within the body of the method are marshalled to the output task and cause the resulting task to end in the state. The exception to this rule is when an (or derived type) goes unhandled, in which case the resulting task ends in the state. ### Generating TAP methods manually diff --git a/docs/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md b/docs/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md index 9d3e4ec37c187..e6bb5a3035d36 100644 --- a/docs/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md +++ b/docs/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md @@ -70,7 +70,7 @@ TAP uses a single method to represent the initiation and completion of an asynch Some asynchronous operations benefit from providing progress notifications; these are typically used to update a user interface with information about the progress of the asynchronous operation. - In TAP, progress is handled through an interface, which is passed to the asynchronous method as a parameter that is usually named `progress`. Providing the progress interface when the asynchronous method is called helps eliminate race conditions that result from incorrect usage (that is, when event handlers that are incorrectly registered after the operation starts may miss updates). More importantly, the progress interface supports varying implementations of progress, as determined by the consuming code. For example, the consuming code may only care about the latest progress update, or may want to buffer all updates, or may want to invoke an action for each update, or may want to control whether the invocation is marshaled to a particular thread. All these options may be achieved by using a different implementation of the interface, customized to the particular consumer's needs. As with cancellation, TAP implementations should provide an parameter only if the API supports progress notifications. + In TAP, progress is handled through an interface, which is passed to the asynchronous method as a parameter that is usually named `progress`. Providing the progress interface when the asynchronous method is called helps eliminate race conditions that result from incorrect usage (that is, when event handlers that are incorrectly registered after the operation starts may miss updates). More importantly, the progress interface supports varying implementations of progress, as determined by the consuming code. For example, the consuming code may only care about the latest progress update, or may want to buffer all updates, or may want to invoke an action for each update, or may want to control whether the invocation is marshalled to a particular thread. All these options may be achieved by using a different implementation of the interface, customized to the particular consumer's needs. As with cancellation, TAP implementations should provide an parameter only if the API supports progress notifications. For example, if the `ReadAsync` method discussed earlier in this article is able to report intermediate progress in the form of the number of bytes read thus far, the progress callback could be an interface: diff --git a/docs/standard/metadata-and-self-describing-components.md b/docs/standard/metadata-and-self-describing-components.md index 73c5baac91251..e6d762845820e 100644 --- a/docs/standard/metadata-and-self-describing-components.md +++ b/docs/standard/metadata-and-self-describing-components.md @@ -54,7 +54,7 @@ Metadata is the key to a simpler programming model, and eliminates the need for - Language interoperability and easier component-based design. - Metadata provides all the information required about compiled code for you to inherit a class from a PE file written in a different language. You can create an instance of any class written in any managed language (any language that targets the common language runtime) without worrying about explicit marshaling or using custom interoperability code. + Metadata provides all the information required about compiled code for you to inherit a class from a PE file written in a different language. You can create an instance of any class written in any managed language (any language that targets the common language runtime) without worrying about explicit marshalling or using custom interoperability code. - Attributes. diff --git a/docs/standard/native-interop/apply-interop-attributes.md b/docs/standard/native-interop/apply-interop-attributes.md index b91287a78560e..394712d7c80a1 100644 --- a/docs/standard/native-interop/apply-interop-attributes.md +++ b/docs/standard/native-interop/apply-interop-attributes.md @@ -27,7 +27,7 @@ The namespace provides three categories of |Attribute|Description| |---------------|-----------------| -||Specifies whether the type should be marshaled using the Automation marshaler or a custom proxy and stub.| +||Specifies whether the type should be marshalled using the Automation marshalleror a custom proxy and stub.| ||Controls the type of interface generated for a class.| ||Identifies the CLSID of the original coclass imported from a type library.

COM interop tools typically apply this attribute.| ||Indicates that a coclass or interface definition was imported from a COM type library. The runtime uses this flag to know how to activate and marshal the type. This attribute prohibits the type from being exported back to a type library.

COM interop tools typically apply this attribute.| @@ -40,13 +40,13 @@ The namespace provides three categories of ||Indicates the physical position of each field within a class when used with the **StructLayoutAttribute**, and the **LayoutKind** is set to Explicit.| ||Specifies the globally unique identifier (GUID) of a class, interface, or an entire type library. The string passed to the attribute must be a format that is an acceptable constructor argument for the type **System.Guid**.

COM interop tools can apply this attribute.| ||Indicates which **IDispatch** interface implementation the common language runtime uses when exposing dual interfaces and dispinterfaces to COM.| -||Indicates that data should be marshaled in to the caller. Can be used to attribute parameters.| +||Indicates that data should be marshalled in to the caller. Can be used to attribute parameters.| ||Controls how a managed interface is exposed to COM clients (Dual, IUnknown-derived, or IDispatch only).

COM interop tools can apply this attribute.| ||Indicates that an unmanaged method signature expects an LCID parameter.

COM interop tools can apply this attribute.| -||Indicates how the data in fields or parameters should be marshaled between managed and unmanaged code. The attribute is always optional because each data type has default marshaling behavior.

COM interop tools can apply this attribute.| +||Indicates how the data in fields or parameters should be marshalled between managed and unmanaged code. The attribute is always optional because each data type has default marshalling behavior.

COM interop tools can apply this attribute.| ||Indicates that a parameter is optional.

COM interop tools can apply this attribute.| -||Indicates that the data in a field or parameter must be marshaled from a called object back to its caller.| -||Suppresses the HRESULT or retval signature transformation that normally takes place during interoperation calls. The attribute affects marshaling as well as type library exporting.

COM interop tools can apply this attribute.| +||Indicates that the data in a field or parameter must be marshalled from a called object back to its caller.| +||Suppresses the HRESULT or retval signature transformation that normally takes place during interoperation calls. The attribute affects marshalling as well as type library exporting.

COM interop tools can apply this attribute.| ||Specifies the ProgID of a .NET class. Can be used to attribute classes.| ||Controls the physical layout of the fields of a class.

COM interop tools can apply this attribute.| diff --git a/docs/standard/native-interop/best-practices.md b/docs/standard/native-interop/best-practices.md index 80598adcc2738..297d0c71556e0 100644 --- a/docs/standard/native-interop/best-practices.md +++ b/docs/standard/native-interop/best-practices.md @@ -54,7 +54,7 @@ If you *do* use `StringBuilder`, one last gotcha is that the capacity does **not ✔️ CONSIDER using `char[]`s from an `ArrayPool`. -For more information on string marshalling, see [Default Marshalling for Strings](../../framework/interop/default-marshaling-for-strings.md) and [Customizing string marshalling](customize-parameter-marshaling.md#customizing-string-parameters). +For more information on string marshalling, see [Default Marshalling for Strings](../../framework/interop/default-marshalling-for-strings.md) and [Customizing string marshalling](customize-parameter-marshalling.md#customizing-string-parameters). > __Windows Specific__ > For `[Out]` strings the CLR will use `CoTaskMemFree` by default to free strings or `SysStringFree` for strings that are marked @@ -68,7 +68,7 @@ as `UnmanagedType.BSTR`. ## Boolean parameters and fields -Booleans are easy to mess up. By default, a .NET `bool` is marshalled to a Windows `BOOL`, where it's a 4-byte value. However, the `_Bool`, and `bool` types in C and C++ are a *single* byte. This can lead to hard to track down bugs as half the return value will be discarded, which will only *potentially* change the result. For more for information on marshalling .NET `bool` values to C or C++ `bool` types, see the documentation on [customizing boolean field marshalling](customize-struct-marshaling.md#customizing-boolean-field-marshalling). +Booleans are easy to mess up. By default, a .NET `bool` is marshalled to a Windows `BOOL`, where it's a 4-byte value. However, the `_Bool`, and `bool` types in C and C++ are a *single* byte. This can lead to hard to track down bugs as half the return value will be discarded, which will only *potentially* change the result. For more for information on marshalling .NET `bool` values to C or C++ `bool` types, see the documentation on [customizing boolean field marshalling](customize-struct-marshalling.md#customizing-boolean-field-marshalling). ## GUIDs @@ -139,7 +139,7 @@ These rules differ from the built-in system primarily in situations where `bool` For more information, see: - [Blittable and Non-Blittable Types](../../framework/interop/blittable-and-non-blittable-types.md) -- [Type Marshalling](type-marshaling.md) +- [Type Marshalling](type-marshalling.md) ## Keeping managed objects alive diff --git a/docs/standard/native-interop/charset.md b/docs/standard/native-interop/charset.md index 2169498cad46f..3c8b66e990edd 100644 --- a/docs/standard/native-interop/charset.md +++ b/docs/standard/native-interop/charset.md @@ -1,16 +1,16 @@ --- -title: Charsets and marshaling - .NET +title: Charsets and marshalling - .NET description: Learn how different values of CharSet can change how .NET marshals your data to native code. ms.date: 01/18/2019 --- -# Charsets and marshaling +# Charsets and marshalling -The way `char` values, `string` objects, and `System.Text.StringBuilder` objects are marshaled depends on the value of the `CharSet` field on either the P/Invoke or structure. You can set the `CharSet` of a P/Invoke by setting the field when declaring your P/Invoke. To set the `CharSet` for a type, set the field on your class or struct declaration. When these attribute fields are not set, it is up to the language compiler to determine which `CharSet` to use. C#, Visual Basic, and F# use the charset by default, which has the same behavior as the charset. +The way `char` values, `string` objects, and `System.Text.StringBuilder` objects are marshalled depends on the value of the `CharSet` field on either the P/Invoke or structure. You can set the `CharSet` of a P/Invoke by setting the field when declaring your P/Invoke. To set the `CharSet` for a type, set the field on your class or struct declaration. When these attribute fields are not set, it is up to the language compiler to determine which `CharSet` to use. C#, Visual Basic, and F# use the charset by default, which has the same behavior as the charset. If the is applied on the module in C# or Visual Basic code, then the C# or Visual Basic compiler will emit the provided `CharSet` by default instead of using `CharSet.None`. F# does not support the `DefaultCharSetAttribute`, and always emits `CharSet.None` by default. -The following table shows a mapping between each charset and how a character or string is represented when marshaled with that charset: +The following table shows a mapping between each charset and how a character or string is represented when marshalled with that charset: | `CharSet` value | Windows | .NET Core 2.2 and earlier on Unix | .NET Core 3.0 and later and Mono on Unix | |-----------------|--------------------|-----------------------------------|------------------------------------------| diff --git a/docs/standard/native-interop/com-wrappers.md b/docs/standard/native-interop/com-wrappers.md index 923cc231f3f99..f89e9e8f83731 100644 --- a/docs/standard/native-interop/com-wrappers.md +++ b/docs/standard/native-interop/com-wrappers.md @@ -25,7 +25,7 @@ COM differs from the .NET runtime object model in several important ways: ![COM wrapper overview](./media/com-wrappers/bidirectional-com-overview.gif) - In most cases, the standard RCW or CCW generated by the runtime provides adequate marshaling for calls that cross the boundary between COM and the .NET runtime. Using custom attributes, you can optionally adjust the way the runtime represents managed and unmanaged code. + In most cases, the standard RCW or CCW generated by the runtime provides adequate marshalling for calls that cross the boundary between COM and the .NET runtime. Using custom attributes, you can optionally adjust the way the runtime represents managed and unmanaged code. ## See also diff --git a/docs/standard/native-interop/customize-parameter-marshaling.md b/docs/standard/native-interop/customize-parameter-marshalling.md similarity index 88% rename from docs/standard/native-interop/customize-parameter-marshaling.md rename to docs/standard/native-interop/customize-parameter-marshalling.md index 4356e950a2895..6ec029da37d6f 100644 --- a/docs/standard/native-interop/customize-parameter-marshaling.md +++ b/docs/standard/native-interop/customize-parameter-marshalling.md @@ -36,11 +36,11 @@ If you're interacting with WinRT APIs, you can use the unmanaged type. If the values in the array need customized marshalling, you can use the field on the `[MarshalAs]` attribute for that. -If you're using COM APIs, you'll likely have to marshal your array parameters as `SAFEARRAY*`s. To do so, you can use the unmanaged type. The default type of the elements of the `SAFEARRAY` can be seen in the table on [customizing `object` fields](./customize-struct-marshaling.md#marshal-systemobject). You can use the and fields to customize the exact element type of the `SAFEARRAY`. +If you're using COM APIs, you'll likely have to marshal your array parameters as `SAFEARRAY*`s. To do so, you can use the unmanaged type. The default type of the elements of the `SAFEARRAY` can be seen in the table on [customizing `object` fields](customize-struct-marshalling.md#marshal-systemobject). You can use the and fields to customize the exact element type of the `SAFEARRAY`. ## Customizing boolean or decimal parameters -For information on marshalling boolean or decimal parameters, see [Customizing structure marshalling](customize-struct-marshaling.md). +For information on marshalling boolean or decimal parameters, see [Customizing structure marshalling](customize-struct-marshalling.md). ## Customizing object parameters (Windows-only) @@ -58,7 +58,7 @@ Additionally, if your type is marked `[ComVisible(true)]` or you're marshalling ### Marshalling to a `VARIANT` -If your native API takes a Win32 `VARIANT`, you can use the format on your `object` parameter to marshal your objects as `VARIANT`s. See the documentation on [customizing `object` fields](customize-struct-marshaling.md#marshal-systemobject) for a mapping between .NET types and `VARIANT` types. +If your native API takes a Win32 `VARIANT`, you can use the format on your `object` parameter to marshal your objects as `VARIANT`s. See the documentation on [customizing `object` fields](customize-struct-marshalling.md#marshal-systemobject) for a mapping between .NET types and `VARIANT` types. ### Custom marshallers diff --git a/docs/standard/native-interop/customize-struct-marshaling.md b/docs/standard/native-interop/customize-struct-marshalling.md similarity index 98% rename from docs/standard/native-interop/customize-struct-marshaling.md rename to docs/standard/native-interop/customize-struct-marshalling.md index bbcbf5f4d9964..ea7566a9cb84e 100644 --- a/docs/standard/native-interop/customize-struct-marshaling.md +++ b/docs/standard/native-interop/customize-struct-marshalling.md @@ -259,7 +259,7 @@ struct BString }; ``` -When using a WinRT-based API, you may need to marshal a string as an `HSTRING`. Using the value, you can marshal a string as a `HSTRING`. `HSTRING` marshalling is only suppported on runtimes with built-in WinRT support. WinRT support was [removed in .NET 5](../../core/compatibility/interop/5.0/built-in-support-for-winrt-removed.md), so `HSTRING` marshalling is not supported in .NET 5.0 or newer. +When using a WinRT-based API, you may need to marshal a string as an `HSTRING`. Using the value, you can marshal a string as a `HSTRING`. `HSTRING` marshalling is only supported on runtimes with built-in WinRT support. WinRT support was [removed in .NET 5](../../core/compatibility/interop/5.0/built-in-support-for-winrt-removed.md), so `HSTRING` marshalling is not supported in .NET 5 or newer. ```csharp public struct HString diff --git a/docs/standard/native-interop/disabled-marshalling.md b/docs/standard/native-interop/disabled-marshalling.md index e3f2867d50936..ced8b0c705af9 100644 --- a/docs/standard/native-interop/disabled-marshalling.md +++ b/docs/standard/native-interop/disabled-marshalling.md @@ -25,7 +25,7 @@ When the `DisableRuntimeMarshallingAttribute` is applied to an assembly, the fol ## Default rules for marshalling common types -When marshalling is disabled, the rules for default marshalling change to much simpler rules. These rules are described below. As mentioned in the [interop best practices documentation](best-practices.md#blittable-types), blittable types are types with the same layout in managed and native code and as such do not require any marshalling. Additionally, these rules cannot be customized with the tools mentioned in [the documentation on customizing parameter marshalling](customize-parameter-marshaling.md). +When marshalling is disabled, the rules for default marshalling change to much simpler rules. These rules are described below. As mentioned in the [interop best practices documentation](best-practices.md#blittable-types), blittable types are types with the same layout in managed and native code and as such do not require any marshalling. Additionally, these rules cannot be customized with the tools mentioned in [the documentation on customizing parameter marshalling](customize-parameter-marshalling.md). | C# keyword | .NET Type | Native Type | |------------|------------------|--------------------| @@ -41,7 +41,7 @@ When marshalling is disabled, the rules for default marshalling change to much s | `nint` | `System.IntPtr` | `intptr_t` | | `nuint` | `System.UIntPtr` | `uintptr_t` | | | `System.Boolean` | `bool` | -| | User-defined [C# `unmanaged`](../../csharp/language-reference/builtin-types/unmanaged-types.md) type with no fields with `LayoutKind.Auto` | Treated as a blittable type. All [customized struct marshalling](customize-struct-marshaling.md) is ignored. | +| | User-defined [C# `unmanaged`](../../csharp/language-reference/builtin-types/unmanaged-types.md) type with no fields with `LayoutKind.Auto` | Treated as a blittable type. All [customized struct marshalling](customize-struct-marshalling.md) is ignored. | | | All other types | unsupported | ## Examples diff --git a/docs/standard/native-interop/index.md b/docs/standard/native-interop/index.md index 4d392823927c3..deced08bac0d4 100644 --- a/docs/standard/native-interop/index.md +++ b/docs/standard/native-interop/index.md @@ -21,6 +21,6 @@ The previous list doesn't cover all of the potential situations and scenarios in ## See also - [Platform Invoke (P/Invoke)](pinvoke.md) -- [Type marshalling](type-marshaling.md) +- [Type marshalling](type-marshalling.md) - [Native interoperability best practices](best-practices.md) - [Disabled runtime marshalling](disabled-marshalling.md) diff --git a/docs/standard/native-interop/pinvoke.md b/docs/standard/native-interop/pinvoke.md index 9d39dbd713e9a..42634c72962db 100644 --- a/docs/standard/native-interop/pinvoke.md +++ b/docs/standard/native-interop/pinvoke.md @@ -56,7 +56,7 @@ macOS example uses the same function, and the only difference is the argument to [!code-csharp[ftw macOS](~/samples/snippets/standard/interop/pinvoke/ftw-macos.cs)] -Both of the previous examples depend on parameters, and in both cases, the parameters are given as managed types. Runtime does the "right thing" and processes these into its equivalents on the other side. Learn about how types are marshaled to native code in our page on [Type marshaling](type-marshaling.md). +Both of the previous examples depend on parameters, and in both cases, the parameters are given as managed types. Runtime does the "right thing" and processes these into its equivalents on the other side. Learn about how types are marshalled to native code in our page on [Type marshalling](type-marshalling.md). ## More resources diff --git a/docs/standard/native-interop/runtime-callable-wrapper.md b/docs/standard/native-interop/runtime-callable-wrapper.md index 0937d050160d4..24cd7be964346 100644 --- a/docs/standard/native-interop/runtime-callable-wrapper.md +++ b/docs/standard/native-interop/runtime-callable-wrapper.md @@ -22,11 +22,11 @@ The following image shows the process for accessing COM objects through the runt Using metadata derived from a type library, the runtime creates both the COM object being called and a wrapper for that object. Each RCW maintains a cache of interface pointers on the COM object it wraps and releases its reference on the COM object when the RCW is no longer needed. The runtime performs garbage collection on the RCW. - Among other activities, the RCW marshals data between managed and unmanaged code, on behalf of the wrapped object. Specifically, the RCW provides marshaling for method arguments and method return values whenever the client and server have different representations of the data passed between them. + Among other activities, the RCW marshals data between managed and unmanaged code, on behalf of the wrapped object. Specifically, the RCW provides marshalling for method arguments and method return values whenever the client and server have different representations of the data passed between them. - The standard wrapper enforces built-in marshaling rules. For example, when a .NET client passes a `string` type as part of an argument to an unmanaged object, the wrapper converts the `string` to a `BSTR` type. Should the COM object return a `BSTR` to its managed caller, the caller receives a `string`. Both the client and the server send and receive data that is familiar to them. Other types require no conversion. For instance, a standard wrapper will always pass a 4-byte integer between managed and unmanaged code without converting the type. + The standard wrapper enforces built-in marshalling rules. For example, when a .NET client passes a `string` type as part of an argument to an unmanaged object, the wrapper converts the `string` to a `BSTR` type. Should the COM object return a `BSTR` to its managed caller, the caller receives a `string`. Both the client and the server send and receive data that is familiar to them. Other types require no conversion. For instance, a standard wrapper will always pass a 4-byte integer between managed and unmanaged code without converting the type. -## Marshaling selected interfaces +## Marshalling selected interfaces The primary goal of the [runtime callable wrapper](runtime-callable-wrapper.md) (RCW) is to hide the differences between the managed and unmanaged programming models. To create a seamless transition, the RCW consumes selected COM interfaces without exposing them to the .NET client, as shown in the following illustration. diff --git a/docs/standard/native-interop/type-marshaling.md b/docs/standard/native-interop/type-marshalling.md similarity index 96% rename from docs/standard/native-interop/type-marshaling.md rename to docs/standard/native-interop/type-marshalling.md index 49ce14ac7ffb3..db6104a6c0a26 100644 --- a/docs/standard/native-interop/type-marshaling.md +++ b/docs/standard/native-interop/type-marshalling.md @@ -73,7 +73,7 @@ Some types can only be marshalled as parameters and not as fields. These types a | `System.Runtime.InteropServices.ArrayWithOffset` | `void*` | | `System.Runtime.InteropServices.HandleRef` | `void*` | -If these defaults don't do exactly what you want, you can customize how parameters are marshalled. The [parameter marshalling](customize-parameter-marshaling.md) article walks you through how to customize how different parameter types are marshalled. +If these defaults don't do exactly what you want, you can customize how parameters are marshalled. The [parameter marshalling](customize-parameter-marshalling.md) article walks you through how to customize how different parameter types are marshalled. ## Default marshalling in COM scenarios @@ -131,4 +131,4 @@ typedef struct _SYSTEMTIME { } SYSTEMTIME, *PSYSTEMTIME; ``` -Sometimes the default marshalling for your structure doesn't do what you need. The [Customizing structure marshalling](./customize-struct-marshaling.md) article teaches you how to customize how your structure is marshalled. +Sometimes the default marshalling for your structure doesn't do what you need. The [Customizing structure marshalling](customize-struct-marshalling.md) article teaches you how to customize how your structure is marshalled. diff --git a/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md b/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md index c53f04f4d29a2..60385b970d969 100644 --- a/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md +++ b/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md @@ -48,7 +48,7 @@ A managed thread can be marked to indicate that it will host a [single-threaded] > [!IMPORTANT] > For application startup code, the only way to control apartment state is to apply the or the to the entry point procedure. - Managed objects that are exposed to COM behave as if they had aggregated the free-threaded marshaler. In other words, they can be called from any COM apartment in a free-threaded manner. The only managed objects that do not exhibit this free-threaded behavior are those objects that derive from or . + Managed objects that are exposed to COM behave as if they had aggregated the free-threaded marshaller. In other words, they can be called from any COM apartment in a free-threaded manner. The only managed objects that do not exhibit this free-threaded behavior are those objects that derive from or . In the managed world, there is no support for the unless you use contexts and context-bound managed instances. If you are using Enterprise Services, then your object must derive from (which is itself derived from ). diff --git a/docs/standard/threading/mutexes.md b/docs/standard/threading/mutexes.md index 0d41c535d5b3e..eaf6ea00c1241 100644 --- a/docs/standard/threading/mutexes.md +++ b/docs/standard/threading/mutexes.md @@ -12,7 +12,7 @@ ms.assetid: 9dd06e25-12c0-4a9e-855a-452dc83803e2 # Mutexes -You can use a object to provide exclusive access to a resource. The class uses more system resources than the class, but it can be marshaled across application domain boundaries, it can be used with multiple waits, and it can be used to synchronize threads in different processes. For a comparison of managed synchronization mechanisms, see [Overview of Synchronization Primitives](overview-of-synchronization-primitives.md). +You can use a object to provide exclusive access to a resource. The class uses more system resources than the class, but it can be marshalled across application domain boundaries, it can be used with multiple waits, and it can be used to synchronize threads in different processes. For a comparison of managed synchronization mechanisms, see [Overview of Synchronization Primitives](overview-of-synchronization-primitives.md). For code examples, see the reference documentation for the constructors. diff --git a/docs/visual-basic/developing-apps/creating-and-using-components.md b/docs/visual-basic/developing-apps/creating-and-using-components.md index 1582695eec07f..03fd31525e116 100644 --- a/docs/visual-basic/developing-apps/creating-and-using-components.md +++ b/docs/visual-basic/developing-apps/creating-and-using-components.md @@ -18,11 +18,11 @@ A *component* is a class that implements the , or derive from a class that directly or indirectly implements . - The and classes are base implementations of the interface. The main difference between these classes is that the class is marshaled by reference, while is marshaled by value. The following list provides broad guidelines for implementers. + The and classes are base implementations of the interface. The main difference between these classes is that the class is marshalled by reference, while is marshalled by value. The following list provides broad guidelines for implementers. -- If your component needs to be marshaled by reference, derive from . +- If your component needs to be marshalled by reference, derive from . -- If your component needs to be marshaled by value, derive from . +- If your component needs to be marshalled by value, derive from . - If your component cannot derive from one of the base implementations due to single inheritance, implement . diff --git a/docs/visual-basic/language-reference/modifiers/ansi.md b/docs/visual-basic/language-reference/modifiers/ansi.md index 1d51228633024..a69dc5a147ff7 100644 --- a/docs/visual-basic/language-reference/modifiers/ansi.md +++ b/docs/visual-basic/language-reference/modifiers/ansi.md @@ -5,7 +5,7 @@ ms.date: 07/20/2015 f1_keywords: - "vb.Ansi" helpviewer_keywords: - - "Declare statement [Visual Basic], marshaling strings [Visual Basic]" + - "Declare statement [Visual Basic], marshalling strings [Visual Basic]" - "ANSI, Visual Basic" - "ANSI" ms.assetid: 4f1fa6ff-5557-41ab-b6da-90baf4c15917 @@ -16,7 +16,7 @@ Specifies that Visual Basic should marshal all strings to American National Stan When you call a procedure defined outside your project, the Visual Basic compiler does not have access to the information it needs to call the procedure correctly. This information includes where the procedure is located, how it is identified, its calling sequence and return type, and the string character set it uses. The [Declare Statement](../statements/declare-statement.md) creates a reference to an external procedure and supplies this necessary information. - The `charsetmodifier` part in the `Declare` statement supplies the character set information for marshaling strings during a call to the external procedure. It also affects how Visual Basic searches the external file for the external procedure name. The `Ansi` modifier specifies that Visual Basic should marshal all strings to ANSI values and should look up the procedure without modifying its name during the search. + The `charsetmodifier` part in the `Declare` statement supplies the character set information for marshalling strings during a call to the external procedure. It also affects how Visual Basic searches the external file for the external procedure name. The `Ansi` modifier specifies that Visual Basic should marshal all strings to ANSI values and should look up the procedure without modifying its name during the search. If no character set modifier is specified, `Ansi` is the default. diff --git a/docs/visual-basic/language-reference/modifiers/auto.md b/docs/visual-basic/language-reference/modifiers/auto.md index 9e819084ae400..795813fd3fb9d 100644 --- a/docs/visual-basic/language-reference/modifiers/auto.md +++ b/docs/visual-basic/language-reference/modifiers/auto.md @@ -6,9 +6,9 @@ f1_keywords: - "vb.Auto" helpviewer_keywords: - "Auto keyword [Visual Basic], external references" - - "Declare statement [Visual Basic], marshaling strings" + - "Declare statement [Visual Basic], marshalling strings" - "Auto keyword [Visual Basic]" - - "Auto keyword [Visual Basic], marshaling strings" + - "Auto keyword [Visual Basic], marshalling strings" ms.assetid: bf79ba95-a62c-48a5-916f-0ac7a52c13ec --- # Auto (Visual Basic) @@ -17,7 +17,7 @@ Specifies that Visual Basic should marshal strings according to .NET Framework r When you call a procedure defined outside your project, the Visual Basic compiler does not have access to the information it must have to call the procedure correctly. This information includes where the procedure is located, how it is identified, its calling sequence and return type, and the string character set it uses. The [Declare Statement](../statements/declare-statement.md) creates a reference to an external procedure and supplies this necessary information. - The `charsetmodifier` part in the `Declare` statement supplies the character set information for marshaling strings during a call to the external procedure. It also affects how Visual Basic searches the external file for the external procedure name. The `Auto` modifier specifies that Visual Basic should marshal strings according to .NET Framework rules, and that it should determine the base character set of the run-time platform and possibly modify the external procedure name if the initial search fails. For more information, see "Character Sets" in [Declare Statement](../statements/declare-statement.md). + The `charsetmodifier` part in the `Declare` statement supplies the character set information for marshalling strings during a call to the external procedure. It also affects how Visual Basic searches the external file for the external procedure name. The `Auto` modifier specifies that Visual Basic should marshal strings according to .NET Framework rules, and that it should determine the base character set of the run-time platform and possibly modify the external procedure name if the initial search fails. For more information, see "Character Sets" in [Declare Statement](../statements/declare-statement.md). If no character set modifier is specified, `Ansi` is the default. diff --git a/docs/visual-basic/language-reference/modifiers/unicode.md b/docs/visual-basic/language-reference/modifiers/unicode.md index 161d0b5643094..56cfa462ddf55 100644 --- a/docs/visual-basic/language-reference/modifiers/unicode.md +++ b/docs/visual-basic/language-reference/modifiers/unicode.md @@ -6,9 +6,9 @@ f1_keywords: - "vb.Unicode" helpviewer_keywords: - "Unicode, external references" - - "Declare statement [Visual Basic], marshaling strings" + - "Declare statement [Visual Basic], marshalling strings" - "Unicode keyword [Visual Basic]" - - "Unicode, marshaling strings" + - "Unicode, marshalling strings" ms.assetid: 0021d5ff-3209-444e-8497-420f3e6ee075 --- # Unicode (Visual Basic) diff --git a/docs/visual-basic/misc/bc32510.md b/docs/visual-basic/misc/bc32510.md index e61558832e9fd..01c00750b83a8 100644 --- a/docs/visual-basic/misc/bc32510.md +++ b/docs/visual-basic/misc/bc32510.md @@ -11,7 +11,7 @@ ms.assetid: e2eec233-6e0b-4f2f-a801-b0274e579c0e --- # Attribute 'System.Runtime.InteropServices.DefaultCharSetAttribute' is not supported in this version -The attribute allows you to specify the character set to be used in marshaled strings. Its value takes a member of the enumeration. +The attribute allows you to specify the character set to be used in marshalled strings. Its value takes a member of the enumeration. The current version of Visual Basic does not support this attribute. Support is possible in future versions. diff --git a/docs/visual-basic/programming-guide/com-interop/com-interoperability-in-net-framework-applications.md b/docs/visual-basic/programming-guide/com-interop/com-interoperability-in-net-framework-applications.md index fdc59e7e5c124..577d332d71e16 100644 --- a/docs/visual-basic/programming-guide/com-interop/com-interoperability-in-net-framework-applications.md +++ b/docs/visual-basic/programming-guide/com-interop/com-interoperability-in-net-framework-applications.md @@ -23,5 +23,5 @@ The links on this page provide details on the interactions between COM and .NET | [COM Interop](index.md) | Provides links to topics covering COM interoperability in Visual Basic, including COM objects, ActiveX controls, Win32 DLLs, managed objects, and inheritance of COM objects. | | [Interoperating with Unmanaged Code](../../../framework/interop/index.md) | Briefly describes some of the interaction issues between managed and unmanaged code, and provides links for further study. | | [COM Wrappers](../../../standard/native-interop/com-wrappers.md) | Discusses runtime callable wrappers, which allow managed code to call COM methods, and COM callable wrappers, which allow COM clients to call .NET object methods. | -| [Advanced COM Interoperability](../../../framework/interop/index.md) | Provides links to topics covering COM interoperability with respect to wrappers, exceptions, inheritance, threading, events, conversions, and marshaling. | +| [Advanced COM Interoperability](../../../framework/interop/index.md) | Provides links to topics covering COM interoperability with respect to wrappers, exceptions, inheritance, threading, events, conversions, and marshalling. | | [Tlbimp.exe (Type Library Importer)](../../../framework/tools/tlbimp-exe-type-library-importer.md) | Discusses the tool you can use to convert the type definitions found within a COM type library into equivalent definitions in a common language runtime assembly. | diff --git a/docs/visual-basic/programming-guide/com-interop/introduction-to-com-interop.md b/docs/visual-basic/programming-guide/com-interop/introduction-to-com-interop.md index 2dedbfa1003b3..4a9677e5addf7 100644 --- a/docs/visual-basic/programming-guide/com-interop/introduction-to-com-interop.md +++ b/docs/visual-basic/programming-guide/com-interop/introduction-to-com-interop.md @@ -47,11 +47,11 @@ The Component Object Model (COM) lets an object expose its functionality to othe ## Interop Assemblies - Interop assemblies are .NET Framework assemblies that bridge between managed and unmanaged code, mapping COM object members to equivalent .NET Framework managed members. Interop assemblies created by Visual Basic .NET handle many of the details of working with COM objects, such as interoperability marshaling. + Interop assemblies are .NET Framework assemblies that bridge between managed and unmanaged code, mapping COM object members to equivalent .NET Framework managed members. Interop assemblies created by Visual Basic .NET handle many of the details of working with COM objects, such as interoperability marshalling. -## Interoperability Marshaling +## Interoperability Marshalling - All .NET Framework applications share a set of common types that enable interoperability of objects, regardless of the programming language that is used. The parameters and return values of COM objects sometimes use data types that differ from those used in managed code. *Interoperability marshaling* is the process of packaging parameters and return values into equivalent data types as they move to and from COM objects. For more information, see [Interop Marshaling](../../../framework/interop/interop-marshaling.md). + All .NET Framework applications share a set of common types that enable interoperability of objects, regardless of the programming language that is used. The parameters and return values of COM objects sometimes use data types that differ from those used in managed code. *Interoperability marshalling* is the process of packaging parameters and return values into equivalent data types as they move to and from COM objects. For more information, see [Interop Marshaling](../../../framework/interop/interop-marshalling.md). ## See also @@ -62,5 +62,5 @@ The Component Object Model (COM) lets an object expose its functionality to othe - [Assemblies in .NET](../../../standard/assembly/index.md) - [Tlbimp.exe (Type Library Importer)](../../../framework/tools/tlbimp-exe-type-library-importer.md) - [Tlbexp.exe (Type Library Exporter)](../../../framework/tools/tlbexp-exe-type-library-exporter.md) -- [Interop Marshaling](../../../framework/interop/interop-marshaling.md) +- [Interop Marshaling](../../../framework/interop/interop-marshalling.md) - [Registration-Free COM Interop](../../../framework/interop/registration-free-com-interop.md) diff --git a/docs/visual-basic/programming-guide/com-interop/troubleshooting-interoperability.md b/docs/visual-basic/programming-guide/com-interop/troubleshooting-interoperability.md index 901febc5f5dbf..07aa0992e3beb 100644 --- a/docs/visual-basic/programming-guide/com-interop/troubleshooting-interoperability.md +++ b/docs/visual-basic/programming-guide/com-interop/troubleshooting-interoperability.md @@ -22,7 +22,7 @@ ms.assetid: b324cc1e-b03c-4f39-aea6-6a6d5bfd0e37 When you interoperate between COM and the managed code of the .NET Framework, you may encounter one or more of the following common issues. -## Interop Marshaling +## Interop Marshalling At times, you may have to use data types that are not part of the .NET Framework. Interop assemblies handle most of the work for COM objects, but you may have to control the data types that are used when managed objects are exposed to COM. For example, structures in class libraries must specify the `BStr` unmanaged type on strings sent to COM objects created by Visual Basic 6.0 and earlier versions. In such cases, you can use the attribute to cause managed types to be exposed as unmanaged types. diff --git a/docs/visual-basic/programming-guide/com-interop/walkthrough-calling-windows-apis.md b/docs/visual-basic/programming-guide/com-interop/walkthrough-calling-windows-apis.md index 0782c60e98ebc..1ebea13b72bb0 100644 --- a/docs/visual-basic/programming-guide/com-interop/walkthrough-calling-windows-apis.md +++ b/docs/visual-basic/programming-guide/com-interop/walkthrough-calling-windows-apis.md @@ -62,7 +62,7 @@ Windows APIs are dynamic-link libraries (DLLs) that are part of the Windows oper #### Argument and Data Type Declarations - Declare the arguments and their data types. This part can be challenging because the data types that Windows uses do not correspond to Visual Studio data types. Visual Basic does a lot of the work for you by converting arguments to compatible data types, a process called *marshaling*. You can explicitly control how arguments are marshaled by using the attribute defined in the namespace. + Declare the arguments and their data types. This part can be challenging because the data types that Windows uses do not correspond to Visual Studio data types. Visual Basic does a lot of the work for you by converting arguments to compatible data types, a process called *marshaling*. You can explicitly control how arguments are marshalled by using the attribute defined in the namespace. > [!NOTE] > Previous versions of Visual Basic allowed you to declare parameters `As Any`, meaning that data of any data type could be used. Visual Basic requires that you use a specific data type for all `Declare` statements. @@ -93,9 +93,9 @@ Windows APIs are dynamic-link libraries (DLLs) that are part of the Windows oper 3. Run the project by pressing F5. The message box is displayed with both **Yes** and **No** response buttons. Click either one. -#### Data Marshaling +#### Data Marshalling - Visual Basic automatically converts the data types of parameters and return values for Windows API calls, but you can use the `MarshalAs` attribute to explicitly specify unmanaged data types that an API expects. For more information about interop marshaling, see [Interop Marshaling](../../../framework/interop/interop-marshaling.md). + Visual Basic automatically converts the data types of parameters and return values for Windows API calls, but you can use the `MarshalAs` attribute to explicitly specify unmanaged data types that an API expects. For more information about interop marshalling, see [Interop Marshaling](../../../framework/interop/interop-marshalling.md). ##### To use Declare and MarshalAs in an API call @@ -105,7 +105,7 @@ Windows APIs are dynamic-link libraries (DLLs) that are part of the Windows oper [!code-vb[VbVbalrInterop#13](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#13)] -3. Add a function prototype for the imported function to the class or module you are using, and apply the `MarshalAs` attribute to the parameters or return value. In the following example, an API call that expects the type `void*` is marshaled as `AsAny`: +3. Add a function prototype for the imported function to the class or module you are using, and apply the `MarshalAs` attribute to the parameters or return value. In the following example, an API call that expects the type `void*` is marshalled as `AsAny`: [!code-vb[VbVbalrInterop#14](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#14)] @@ -135,7 +135,7 @@ Windows APIs are dynamic-link libraries (DLLs) that are part of the Windows oper [!code-vb[VbVbalrInterop#16](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrInterop/VB/Class1.vb#16)] - Your function can have any valid procedure name; the `DllImport` attribute specifies the name in the DLL. It also handles interoperability marshaling for the parameters and return values, so you can choose Visual Studio data types that are similar to the data types the API uses. + Your function can have any valid procedure name; the `DllImport` attribute specifies the name in the DLL. It also handles interoperability marshalling for the parameters and return values, so you can choose Visual Studio data types that are similar to the data types the API uses. 8. Apply the `DllImport` attribute to the empty function. The first parameter is the name and location of the DLL containing the function you are calling. You do not need to specify the path for files located in the Windows system directories. The second parameter is a named argument that specifies the name of the function in the Windows API. In this example, the `DllImport` attribute forces calls to `MoveFile` to be forwarded to `MoveFileW` in KERNEL32.DLL. The `MoveFileW` method copies a file from the path `src` to the path `dst`. @@ -160,4 +160,4 @@ Windows APIs are dynamic-link libraries (DLLs) that are part of the Windows oper - [Alias](../../language-reference/statements/alias-clause.md) - [COM Interop](index.md) - [Creating Prototypes in Managed Code](../../../framework/interop/creating-prototypes-in-managed-code.md) -- [Marshaling a Delegate as a Callback Method](../../../framework/interop/marshaling-a-delegate-as-a-callback-method.md) +- [Marshalling a Delegate as a Callback Method](../../../framework/interop/marshalling-a-delegate-as-a-callback-method.md) diff --git a/docs/visual-basic/programming-guide/com-interop/walkthrough-implementing-inheritance-with-com-objects.md b/docs/visual-basic/programming-guide/com-interop/walkthrough-implementing-inheritance-with-com-objects.md index 4d97aca50a030..b07d028e616c8 100644 --- a/docs/visual-basic/programming-guide/com-interop/walkthrough-implementing-inheritance-with-com-objects.md +++ b/docs/visual-basic/programming-guide/com-interop/walkthrough-implementing-inheritance-with-com-objects.md @@ -69,7 +69,7 @@ The following procedure shows how to use Visual Basic 6.0 to create a COM object ## Interop Assemblies -In the following procedure, you will create an interop assembly, which acts as a bridge between unmanaged code (such as a COM object) and the managed code Visual Studio uses. The interop assembly that Visual Basic creates handles many of the details of working with COM objects, such as *interop marshaling*, the process of packaging parameters and return values into equivalent data types as they move to and from COM objects. The reference in the Visual Basic application points to the interop assembly, not the actual COM object. +In the following procedure, you will create an interop assembly, which acts as a bridge between unmanaged code (such as a COM object) and the managed code Visual Studio uses. The interop assembly that Visual Basic creates handles many of the details of working with COM objects, such as *interop marshalling*, the process of packaging parameters and return values into equivalent data types as they move to and from COM objects. The reference in the Visual Basic application points to the interop assembly, not the actual COM object. ### To use a COM object with Visual Basic 2005 and later versions diff --git a/docs/visual-basic/walkthroughs.md b/docs/visual-basic/walkthroughs.md index 0e196c1ed0b3d..63d74983ba39b 100644 --- a/docs/visual-basic/walkthroughs.md +++ b/docs/visual-basic/walkthroughs.md @@ -35,7 +35,7 @@ Walkthroughs give step-by-step instructions for common scenarios, which makes th Demonstrates how to create a class that implements the `IEnumerable(Of String)` interface and a class that implements the `IEnumerator(Of String)` interface to read a text file one line at a time. - [Calling Windows APIs](programming-guide/com-interop/walkthrough-calling-windows-apis.md) - Explains how to use `Declare` statements and call Windows APIs. Includes information about using attributes to control marshaling for the API call and how to expose an API call as a method of a class. + Explains how to use `Declare` statements and call Windows APIs. Includes information about using attributes to control marshalling for the API call and how to expose an API call as a method of a class. - [Creating COM Objects with Visual Basic](programming-guide/com-interop/walkthrough-creating-com-objects.md) Demonstrates how to create COM objects in Visual Basic, both with and without the COM class template.