diff --git a/docs/core/porting/cpp-cli.md b/docs/core/porting/cpp-cli.md index 80a1bde41fa31..0418a21b2e0c1 100644 --- a/docs/core/porting/cpp-cli.md +++ b/docs/core/porting/cpp-cli.md @@ -1,52 +1,57 @@ --- -title: Migrate C++/CLI projects to .NET Core and .NET 5+ -description: Learn about porting C++/CLI projects to .NET Core and .NET 5 and later versions. +title: Migrate C++/CLI projects to .NET +description: Learn about porting C++/CLI projects to .NET. author: mjrousos -ms.date: 10/27/2023 +ms.date: 01/23/2024 --- -# How to port a C++/CLI project to .NET Core or .NET 5+ +# How to port a C++/CLI project to .NET -Beginning with .NET Core 3.1 and Visual Studio 2019, [C++/CLI projects](/cpp/dotnet/dotnet-programming-with-cpp-cli-visual-cpp) can target .NET Core. This support makes it possible to port Windows desktop applications with C++/CLI interop layers to .NET Core/.NET 5+. This article describes how to port C++/CLI projects from .NET Framework to .NET Core 3.1. +Beginning with Visual Studio 2019, [C++/CLI projects](/cpp/dotnet/dotnet-programming-with-cpp-cli-visual-cpp) can target .NET. This support makes it possible to port Windows desktop applications with C++/CLI interop layers from .NET Framework to .NET. This article describes how to port C++/CLI projects from .NET Framework to .NET. ## C++/CLI .NET Core limitations -There are some important limitations to porting C++/CLI projects to .NET Core compared to other languages: +There are some important limitations with C++/CLI projects and .NET compared to .NET Framework: -- C++/CLI support for .NET Core is Windows only. -- C++/CLI projects can't target .NET Standard, only .NET Core or .NET Framework. -- C++/CLI projects don't support the new SDK-style project file format. Instead, even when targeting .NET Core, C++/CLI projects use the existing *.vcxproj* file format. -- C++/CLI projects can't multitarget multiple .NET platforms. If you need to build a C++/CLI project for both .NET Framework and .NET Core, use separate project files. -- .NET Core doesn't support `-clr:pure` or `-clr:safe` compilation, only the new `-clr:netcore` option (which is equivalent to `-clr` for .NET Framework). +- Compiling a C++/CLI project to an executable isn't supported. You must compile to a DLL. +- C++/CLI support for .NET is Windows only. +- C++/CLI projects can't target .NET Standard. +- C++/CLI projects don't support the newer SDK-style project file format. Instead, C++/CLI projects use the same _.vcxproj_ file format that other Visual Studio C++ projects use. +- C++/CLI projects can't target multiple .NET platforms. If you need to build a C++/CLI project for both .NET and .NET Framework, use separate project files. +- .NET doesn't support `-clr:pure` or `-clr:safe` compilation, only the newer `-clr:netcore` option (which is equivalent to `-clr` for .NET Framework). ## Port a C++/CLI project -To port a C++/CLI project to .NET Core, make the following changes to the *.vcxproj* file. These migration steps differ from the steps needed for other project types because C++/CLI projects don't use SDK-style project files. +To port a C++/CLI project to .NET, make the following changes to the _.vcxproj_ file. These migration steps differ from the steps needed for other project types because C++/CLI projects don't use SDK-style project files. -1. Replace `true` properties with `NetCore`. This property is often in configuration-specific property groups, so you might need to replace it in multiple places. -2. Replace `` properties with `netcoreapp3.1`. Be sure to change the tag as well as the value. -3. Remove any .NET Framework references to `System`, `System.Data`, `System.Windows.Forms`, and `System.Xml`, like ``. .NET Core SDK assemblies are automatically referenced when using `NetCore`. -4. Update API usage in *.cpp* files, as necessary, to remove APIs unavailable to .NET Core. Because C++/CLI projects tend to be fairly thin interop layers, there are often not many changes needed. You can use the [.NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md) to identify unsupported .NET APIs used by C++/CLI binaries just as with purely managed binaries. +01. Replace `true` properties with `NetCore`. This property is often in configuration-specific property groups, so you might need to replace it in multiple places. +01. Replace `` properties with `net8.0`. Be sure to change the tag and value. +01. Remove any .NET Framework references to `System`, `System.Data`, `System.Windows.Forms`, and `System.Xml`, like ``. .NET SDK assemblies are automatically referenced when using `NetCore`. +01. Update API usage in _.cpp_ files, as necessary, to remove APIs unavailable to .NET. Because C++/CLI projects tend to be fairly thin interop layers, there are often not many changes needed. You can use the [.NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md) to identify unsupported .NET APIs used by C++/CLI binaries. +01. If your project was an executable, perform the following steps: + 01. Change the project type to a library. + 01. Create a new .NET executable project. + 01. In the .NET executable project, add reference the C++/CLI .NET library. ### WPF and Windows Forms usage -.NET Core C++/CLI projects can use Windows Forms and WPF APIs. To use these Windows desktop APIs, you need to add explicit framework references to the UI libraries. SDK-style projects that use Windows desktop APIs reference the necessary framework libraries automatically by using the `Microsoft.NET.Sdk.WindowsDesktop` SDK. Because C++/CLI projects don't use the SDK-style project format, they need to add explicit framework references when targeting .NET Core. +.NET C++/CLI projects can use Windows Forms and WPF APIs. To use these Windows desktop APIs, you need to add explicit framework references to the UI libraries. SDK-style projects that use Windows desktop APIs reference the necessary framework libraries automatically by using the `Microsoft.NET.Sdk.WindowsDesktop` SDK. Because C++/CLI projects don't use the SDK-style project format, they need to add explicit framework references when targeting .NET Core. -To use Windows Forms APIs, add this reference to the *.vcxproj* file: +To use Windows Forms APIs, add this reference to the _.vcxproj_ file: ```xml ``` -To use WPF APIs, add this reference to the *.vcxproj* file: +To use WPF APIs, add this reference to the _.vcxproj_ file: ```xml ``` -To use both Windows Forms and WPF APIs, add this reference to the *.vcxproj* file: +To use both Windows Forms and WPF APIs, add this reference to the _.vcxproj_ file: ```xml