Project-system: *Please* provide public documentation for CPS

[wjk]

Currently, there is no public documentation for how to use CPS to create or extend project types. As I have indicated in previous issues, the VSProjectSystem repo is dead as a doornail (it has not been committed to since March, and issues there are ignored by MS contributors). When I saw “for more information, consult our private repository” in #6724, which introduces public documentation, I became most irritated.

The CPS NuGet packages on nuget.org provide some API in the form of IntelliSense member-documentation XML files. This is the only documentation I can find _anywhere_ for how to use CPS. Unfortunately, those NuGet packages have not been updated since June 2019. Newer versions of CPS are only distributed in a (supposedly) public NuGet feed hosted in Azure DevOps, but it is clear that the feed is really intended for MS-internal use only. (I don’t even know which NuGet feed it is, as there are several listed).

I (and others) have asked this question multiple times in the past; usually all we get in response is crickets. To put it bluntly, I am sick and tired of MS ignoring our community input. Over the past few months or so, Microsoft’s open source projects have become just one big “Please wait, announcement coming soon” sign. (Project Reunion — big talk, little code, and there has been zero progress towards making that code usable without major modifications. WinUI 3 — neither talk nor code in recent memory. Furthermore, the CsWinRT component used alongside WinUI 3 is now incompatible with it. The only response given as to how to fix that is “use WinUI 3 preview 3” — except that preview 3 has not been released to anyone outside MS. And so on.)

I could have filed this issue in a number of repos across Microsoft, but I am filing it here because the “see private repository” comment is the straw that broke my camel’s back. Please do something about this. Thank you.

[KirillOsenkov]

@jmarolf do we have a sample of hosting CPS outside of VS?

[lifengl]

Thanks to report those gaps. We will follow up on document issues a little bit later.

We can consider publishing new NuGet packages to NuGet.org. One problem is that CPS and other packages have cross dependencies, so aligning them might be a problem during quick releases. It is important to aware that those NuGet packages are representing contracts to newly released VS updates. So, if your extension depends on 16.5 version of the package, you need assume that your package can only be used with VS when 16.5 above updates are installed. In reality, most extension developers do not want to take that dependency, so it is fairly rare that they want a newer version of our NuGet package. (BTW, I don't remember anything to declare the public NuGet feed hosted in Azure DevOps for Microsoft internal use only. Internal packages are in different feeds, and are not used by open source projects. I will follow up on that.)

There are only a few new APIs added since 16.2, and most of them are added to support specific features, and unlikely useful to other extensions. That include:

Out of process host object supporting (which is to support host object infrastructures used by some code generations through msbuild tasks, we don't think any extension should do it again).

File nesting features (this is not yet enabled in the product),

Read-only VC project file support (it is a feature being tested, and we don't suggest any extension to consume it),

Some additional contract for project reloading and external dependencies (like watching the asset file). (Generally, project systems should add msbuild items instead of adding a new component using the contract)

Other than those new contracts, we did expose some help classes in new updates, which may be useful for extensions heavily uses dataflow. One useful change to all extensions is that CPS now uses the new nullable language feature in the contract, which can help extensions to find potential bugs.

You should only use new CPS packages if you need take advantage of some of those changes.

[lifengl]

@jmarolf do we have a sample of hosting CPS outside of VS?

no, actually, only contract assemblies are shipped in the NuGet package, so no party outside of Microsoft can host CPS outside of VS legally.

[jjmew]

We have reached out to the platform team who owns CPS and we are waiting for guidance