Portieren eines C++/CLI-Projekts zu .NET

Ab Visual Studio 2019 können C++/CLI-Projekte auf .NET abzielen. Diese Unterstützung ermöglicht das Portieren von Windows-Desktopanwendungen mit C++/CLI-Interopebenen von .NET Framework zu .NET. In diesem Artikel wird beschrieben, wie Sie C++/CLI-Projekte von .NET Framework zu .NET portieren.

C++/CLI .NET Core-Einschränkungen

Es gibt einige wichtige Einschränkungen bei C++/CLI-Projekten und .NET im Vergleich zu .NET Framework:

• Das Kompilieren eines C++/CLI-Projekts zu einer ausführbaren Datei wird nicht unterstützt. Sie müssen zu einer DLL kompilieren.
• C++/CLI-Unterstützung für .NET ist nur auf Windows verfügbar.
• C++/CLI-Projekte können nicht auf .NET Standard abzielen.
• C++/CLI-Projekte unterstützen das neuere PROJECT-Dateiformat im SDK-Stil nicht. Stattdessen verwenden C++/CLI-Projekte das gleiche .vcxproj Dateiformat, das andere Visual Studio C++-Projekte verwenden.
• C++/CLI-Projekte können nicht auf mehrere .NET-Plattformen ausgerichtet werden. Wenn Sie ein C++/CLI-Projekt für .NET und .NET Framework erstellen müssen, verwenden Sie separate Projektdateien.
• .NET unterstützt keine -clr:pure- oder -clr:safe-Kompilierung, sondern nur die neuere -clr:netcore-Option (die gleichwertig mit -clr für .NET Framework ist).

Portieren eines C++/CLI-Projekts

Um ein C++/CLI-Projekt zu .NET zu portieren, nehmen Sie die folgenden Änderungen an der .vcxproj Datei vor. Diese Migrationsschritte unterscheiden sich von den Schritten, die für andere Projekttypen erforderlich sind, da C++/CLI-Projekte keine PROJEKTDATEIEN im SDK-Stil verwenden.

1. Ersetzen von <CLRSupport>true</CLRSupport> Eigenschaften durch <CLRSupport>NetCore</CLRSupport>. Diese Eigenschaft befindet sich häufig in konfigurationsspezifischen Eigenschaftengruppen, daher müssen Sie sie möglicherweise an mehreren Stellen ersetzen.
2. Ersetzen von <TargetFrameworkVersion> Eigenschaften durch <TargetFramework>net8.0</TargetFramework>. Achten Sie darauf, das Tag und den Wert zu ändern.
3. Entfernen Sie alle .NET Framework-Verweise auf System, System.Data, System.Windows.Formsund System.Xml, wie <Reference Include="System" />. .NET SDK-Assemblies werden automatisch referenziert, wenn <CLRSupport>NetCore</CLRSupport> verwendet wird.
4. Aktualisieren Sie die API-Verwendung in .cpp Dateien nach Bedarf, um APIs zu entfernen, die für .NET nicht verfügbar sind. Da C++/CLI-Projekte eher dünne Interopebenen sind, sind häufig nicht viele Änderungen erforderlich. Sie können die .NET-Portabilitätsanalyse verwenden, um nicht unterstützte .NET-APIs zu identifizieren, die von C++/CLI-Binärdateien verwendet werden.
5. Wenn Ihr Projekt eine ausführbare Datei war, führen Sie die folgenden Schritte aus:
   1. Ändern Sie den Projekttyp in eine Bibliothek.
   2. Erstellen Sie ein neues ausführbares .NET-Projekt.
   3. Fügen Sie im ausführbaren .NET-Projekt einen Verweis auf die C++/CLI .NET-Bibliothek hinzu.

WPF- und Windows Forms-Verwendung

.NET C++/CLI-Projekte können Windows Forms- und WPF-APIs verwenden. Um diese Windows-Desktop-APIs zu verwenden, müssen Sie explizite Frameworkverweise zu den UI-Bibliotheken hinzufügen. SDK-Stilprojekte, die Windows-Desktop-APIs verwenden, verweisen automatisch mithilfe des Microsoft.NET.Sdk.WindowsDesktop SDK auf die erforderlichen Frameworkbibliotheken. Da C++/CLI-Projekte das PROJEKTformat im SDK-Stil nicht verwenden, müssen sie explizite Frameworkverweise hinzufügen, wenn sie auf .NET Core abzielen.

Um Windows Forms-APIs zu verwenden, fügen Sie diesen Verweis auf die datei .vcxproj hinzu:

<!-- Reference all of Windows Forms -->
<FrameworkReference Include="Microsoft.WindowsDesktop.App.WindowsForms" />

Um WPF-APIs zu verwenden, fügen Sie diesen Verweis auf die datei .vcxproj hinzu:

<!-- Reference all of WPF -->
<FrameworkReference Include="Microsoft.WindowsDesktop.App.WPF" />

Um sowohl Windows Forms- als auch WPF-APIs zu verwenden, fügen Sie diesen Verweis auf die datei .vcxproj hinzu:

<!-- Reference the entirety of the Windows desktop framework:
     Windows Forms, WPF, and the types that provide integration between them -->
<FrameworkReference Include="Microsoft.WindowsDesktop.App" />

Derzeit ist es nicht möglich, diese Verweise mithilfe des Referenz-Managers von Visual Studio hinzuzufügen. Aktualisieren Sie stattdessen die Projektdatei, indem Sie sie manuell bearbeiten. In Visual Studio müssen Sie das Projekt zuerst entladen. Sie können auch einen anderen Editor wie Visual Studio Code verwenden.

Erstellen ohne MSBuild

Es ist auch möglich, C++/CLI-Projekte zu erstellen, ohne MSBuild zu verwenden. Führen Sie die folgenden Schritte aus, um ein C++/CLI-Projekt für .NET Core direkt mit cl.exe und link.exezu erstellen:

1. Übergeben Sie beim Kompilieren -clr:netcore an cl.exe.

2. Verweisen Sie auf erforderliche Referenzassemblys für .NET.

3. Stellen Sie beim Verknüpfen das .NET-App-Hostverzeichnis als LibPath, sodass ijwhost.lib gefunden werden kann.

4. Kopieren Sie ijwhost.dll aus dem .NET-App-Hostverzeichnis in das Ausgabeverzeichnis des Projekts.

5. Stellen Sie sicher, dass für die erste Komponente der Anwendung, die verwalteten Code ausführt, eine runtimeconfig.json Datei vorhanden ist. Für die neuesten Versionen von Visual Studio wird automatisch eine runtime.config Datei erstellt und kopiert.

   Für ältere Versionen von Visual Studio müssen Sie, wenn die Anwendung über einen systemeigenen Einstiegspunkt verfügt, manuell die folgende runtimeconfig.json Datei für die erste C++/CLI-Bibliothek erstellen, um die .NET-Laufzeit zu verwenden. Wenn eine C++/CLI-Bibliothek von einem verwalteten Einstiegspunkt aufgerufen wird, benötigt die Bibliothek keine runtimeconfig.json Datei, da die Einstiegspunktassembly eine hat, die beim Starten der Laufzeit verwendet wird.

   {
      "runtimeOptions": {
         "tfm": "net8.0",
         "framework": {
         "name": "Microsoft.NETCore.App",
         "version": "8.0.0"
         }
      }
   }
   

Hinweis

C++/CLI-Assemblys, die auf .NET 7 oder eine höhere Version abzielen, werden immer in die Standardversion AssemblyLoadContextgeladen. In .NET 6 und früheren Versionen können C++/CLI-Assemblys jedoch mehrmals geladen werden, jedes Mal in eine neue AssemblyLoadContext. Wenn der verwaltete Code zum ersten Mal in einer C++/CLI-Assembly ausgeführt wird:

• Stammt von einem systemeigenen Aufrufer, wird die Assembly in eine separate AssemblyLoadContextgeladen.
• Stammt von einem verwalteten Aufrufer, wird die Assembly in die gleiche AssemblyLoadContext wie der Aufrufer geladen, in der Regel die Standardeinstellung.

Damit Ihre C++/CLI-Assembly immer in den standardmäßigen AssemblyLoadContext geladen wird, können Sie der Assembly einen initialize-Aufruf von der Einstiegspunktassembly hinzufügen. Weitere Informationen finden Sie in diesem dotnet/runtime-Issue.