Skip to content

Commit eda9366

Browse files
nkolev92nkolev92
authored
PackageReference support for .NET Core C++/CLI projects (#10299)
1 parent def41b4 commit eda9366

File tree

1 file changed

+177
-0
lines changed

1 file changed

+177
-0
lines changed

‎proposed/2021/NuGet-CPPCLI-Support.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# NuGet C++/CLI support
2+
3+
- Author Name [Nikolche Kolev](https://github.com/nkolev92)
4+
- Start Date 2021-04-01
5+
- GitHub Issue [8195](https://github.com/NuGet/Home/issues/8195) and [10194](https://github.com/NuGet/Home/issues/10194)
6+
7+
## Summary
8+
9+
## Goals
10+
11+
* Cooperate with the respective partner team to enable PackageReference support for C++/CLI projects on the commandline and in Visual Studio.
12+
* C++/CLI binaries are managed binaries not native. They can consume native code, but they themselves are managed.
13+
* Ensure NuGet is interpreting the correct framework, to fullfill the primary goal of enabling the consumption of both `managed` packages `native` packages.
14+
15+
## Non-Goals
16+
17+
* PackageReference support for .NET Framework C++/CLI projects.
18+
* packages.config support for C++/CLI projects.
19+
* PackageReference support for native C++ projects.
20+
21+
22+
## Motivation
23+
24+
C++/CLI is a project type that allows C++ programs to use .NET classes. This effort captures the NuGet side of enabling PackageReference for .NET Core C++\CLI projects.
25+
There are multiple components involved in this work:
26+
27+
- NuGet
28+
- project-system
29+
- MSBuild & SDK
30+
- C++
31+
32+
Currently NuGet special cases C++ projects by looking at the extension and treating every vcxproj as packages.config `native`.
33+
The packages.config/PackageReference support story is owned by the C++ team and as of VS 16.8, all C++ projects are `packages.config`.
34+
35+
When discussing the changes here is a summary from a member on the C++ team.
36+
37+
```md
38+
TargetFramework*/TargetPlatform* properties for C++/CLI are pretty much the same as for c#, so they should be used in nuget instead of just checking for .vcxproj extension. Also, C++/CLI can use/reference not only managed, but native code as well, so “native” packages should be allowed together with the appropriate managed ones.
39+
You can use the following properties to distinguish vc projects:
40+
TargetPlatformIdentifier/Version/Moniker should be defined for all vc projects.
41+
CLRSupport
42+
False or empty – native project
43+
NetCore – C++/CLI .NET Core project
44+
Everything else (true, safe, etc) - C++/CLI .NET Framework project
45+
TargetFramework is only defined for C++/CLI .NET Core projects.
46+
TargetFrameworkIdentifier/Version/Moniker properties are defined for C++/CLI .NET Framework projects. Note, that they are also confusingly defined for pure native ones too (in msbuild common targets, at least, they used to be), so you need to check other properties first (i.e. TargetPlatformIdentifier and CLRSupport). You can also use project capabilities: “native” vs “managed”
47+
```
48+
49+
C++/CLI projects produce managed binaries (which can be used in other managed projects) and (if there are native exports) native import libraries (which can be used in native or c++/CLI projects).
50+
51+
## Explanation
52+
53+
### Functional explanation
54+
55+
Installing managed packages in C++/CLI .NET Core projects is currently not possible.
56+
The work here is largely technical, and it involves enabling that functionality through coordination of C++, .NET Core SDK, project-system & NuGet.
57+
58+
### Technical explanation
59+
60+
### What is PackageReference support
61+
62+
The PackageReference integration as a project style involves several scenarios that are not immediately obvious for a packages.config user.
63+
Supporting PackageReference includes the following:
64+
65+
- Installation of NuGet packages most compatible asset selection with a given pivot framework, such as .NET 5.0.
66+
- Allowing redistribution of a PackageReference project through `pack`. `pack` should be able to create a NuGet package that can later be used by a different project.
67+
- PackageReference transitivity; Given a project, Project1, that references a package, `PackageA`, that is compatible with said project, any project that references `Project1` should be able to restore `PackageA` as well.
68+
- [ProjectReference protocol](https://github.com/dotnet/msbuild/blob/main/documentation/ProjectReference-Protocol.md). The framework to framework compatibility is owned by NuGet, so as such when 2 projects have different frameworks, NuGet participates in this compatibility check.
69+
70+
All of this boils down to the fact that, given a project, NuGet needs to interpret an effective target framework, and then use that target framework in *all* of the above scenarios.
71+
72+
### C++/CLI target framework inference
73+
74+
In managed projects, NuGet interprets the effective framework by looking at `TargetFrameworkMoniker`, `TargetPlatformMoniker` and in UWP cases, `TargetPlatformMinVersion`.
75+
C++\CLI projects have an additional property `CLRSupport`.
76+
77+
Currently the steps for NuGet framework inference for project types still actively supported are as follows:
78+
79+
1. Does the project file extension end with `.vcxproj`? Then `native0.0`
80+
1. Does `TargetPlatformMoniker` start with `UAP`? Then the framework is `UAP{version}`, where `TargetPlatformMinVersion` is preferred over `TargetPlatformVersion`.
81+
1. `TargetPlatformMoniker`, unless the framework is `.NETCoreApp` with version greater than 5.0, then it's the combination of `TargetFrameworkMoniker` and `TargetPlatformMoniker`.
82+
83+
C++/CLI projects are supposed to support installing both managed and native packages. This would require some amendments to NuGet's framework model.
84+
85+
When a package contains `managed` and `native` assets, the managed ones will be preferred.
86+
87+
To understand the proposed changes, here's a mapping of all `C++` project types and the property value for the appropriate ones.
88+
89+
| Project type | TargetFrameworkIdentifier | TargetPlatformIdentifier | CLRSupport | Effective NuGet framework | Notes |
90+
|--------------|---------------------------|--------------------------|------------|---------------------------|-------|
91+
| Native C++ | .NETFramework,Version=v4.0 | Windows,Version=10.0.19041.0 | false | native | NuGet will continue special casing vcxproj. |
92+
| C++ UWP App | | UAP,Version=10.0.18362.0 | false | native | NuGet will continue special casing vcxproj. |
93+
| CLR C++ | .NETFramework,Version=v4.7.2 | Windows,Version=7.0 | true | ??? | This project has .NET Framework CLR support. This is not a focus scenario |
94+
| Core CLR C++ | .NETCoreApp,Version=v5.0 | Windows,Version=10.0.19041.0 | NetCore | ??? | Dual compatibility. Supports everything that net5.0-windows support & everything native supports |
95+
96+
Worth noting that, `native` framework is not compatible with anything but `native` and that will remain.
97+
From C++/SDK perspective, net5.0-windows projects will be supported. NuGet would normally not special case which .NET target frameworks are supported.
98+
99+
### Project to project and project to package scenarios
100+
101+
C++/CLI projects don't have the same scenarios as purely managed project types. As such the important scenarios are limited.
102+
103+
- .NET Core C++/CLI projects can only build libraries and not exes.
104+
- .NET Core C++/CLI projects are not packable by the standard `pack` target. This will be disabled in the projects, but we can consider disabling it in the NuGet.targets as well.
105+
106+
```cli
107+
C# project -> C++/CLI project -> ManagedPackage 1.0.0
108+
```
109+
110+
- Project to Project transitivity applies and ManagedPackage would be consumed in the C# project
111+
- The C++/CLI project is not packable, but the C# project is. The burden in on the package author to ensure all the correct dependencies are carried on.
112+
113+
```cli
114+
C# project -> C++/CLI project -> NativePackage 1.0.0
115+
```
116+
117+
- Given that all the projects are PackageReference enabled, NuGet will apply the package transitively.
118+
- There are compatibility concerns here, but given that most native packages only have a build folder, it is likely they will install correctly in the managed project.
119+
- If it does fail, the guidance is that `PrivateAssets=all` is specified on the NativePackage's PackageReference.
120+
121+
```cli
122+
- C++ project -> C++/CLI -> NativePackage 1.0.0
123+
```
124+
125+
- C++/CLI projects can consume native packages.
126+
- A C++ project is packages.config, so the project reference protocol does not apply.
127+
- This is not expected to be a super common scenario, you'd likely have native projects only.
128+
129+
```cli
130+
C++ project -> C++/CLI project -> ManagedPackage 1.0.0
131+
```
132+
133+
- Given that the C++ project is not PackageReference compatibility, the transitivity concerns do not apply here.
134+
- At this point, the burden is on the consumer to ensure that the project author works.
135+
- This is not expected to be a common scenario.
136+
137+
## Drawbacks
138+
139+
<!-- Why should we not do this? -->
140+
141+
- The limitations of the proposal is that NuGet does not have a framework that's only supported in projects. Given that this is not a real `target`, it is counter to what NuGet frameworks are.
142+
- This scenario is not extremely common, and the distribution story is not coherent. As such the project to project scenarios have a lot of caveats.
143+
144+
## Rationale and alternatives
145+
146+
<!-- Why is this the best design compared to other designs? -->
147+
<!-- What other designs have been considered and why weren't they chosen? -->
148+
<!-- What is the impact of not doing this? -->
149+
150+
### AssetTargetFallback
151+
152+
NuGet has a fallback compatibility mode.
153+
For example: .NET Core projects have a fallback to .NET Framework with a warning. This is also callled `Asset Target Fallback`.
154+
If a package supports .NET Core or .NET Standard, it's fully compatible with a .NET Core project. Otherwise if a package has .NET Framework assets, the package is installed, but with a *warning*. This fallback model is not appropriate for the C++/CLI scenario as the warning being raised is inappropriate.
155+
156+
The `Asset Target Fallback` implementation currently suffers from a bug where the dependencies are not pulled in correctly, see [5957](https://github.com/NuGet/Home/issues/5957).
157+
158+
This would require project type changes. The project type would specify which target framework to fall back to. This likely requires fixing [5957](https://github.com/NuGet/Home/issues/5957).
159+
160+
[Asset Target Fallback design document](https://github.com/NuGet/Home/wiki/Enable-.NET-Core-2.0-projects-to-work-with-.NET-Framework-4.6.1-compatible-packages)
161+
[AssetTargetFallback docs](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#assettargetfallback)
162+
163+
## Prior Art
164+
165+
- [AssetTargetFallback](#assettargetfallback) represents a similar functionality.
166+
167+
## Unresolved Questions
168+
169+
<!-- What parts of the proposal do you expect to resolve before this gets accepted? -->
170+
<!-- What parts of the proposal need to be resolved before the proposal is stabilized? -->
171+
<!-- What related issues would you consider out of scope for this proposal but can be addressed in the future? -->
172+
173+
- Currently C++/CLI projects can only build against .NET Core assemblies, and not .NET Standard ones. This is *not* a scenario NuGet supports right now.
174+
175+
## Future Possibilities
176+
177+
<!-- What future possibilities can you think of that this proposal would help with? -->

0 commit comments

Comments
 (0)