Wiki missing info - Obtaining the Concord API headers

akbyrd commented 2 years ago

This page mentions 2 ways to get the headers and libs: the Visual Studio Extensibility workload and nuget. https://github.com/Microsoft/ConcordExtensibilitySamples/wiki/Obtaining-the-Concord-API-headers,-libraries,-etc

I'm using the first method and that page doesn't describe how to actually reference the headers and libs from a C++ project. I can find the files in paths below, but they are not part of the set of resolved paths in a default C++ project.

C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VSSDK\VisualStudioIntegration\Common\Inc C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VSSDK\VisualStudioIntegration\Common\Lib\x64 etc

Nor do I see any new macros that include VSSDK or VisualStudioIntegration paths. It's not clear to me what the intended way to get at those files is. I can use $(VsInstallDir) and manually add the header and lib dirs I need. Is that the intended way?

Additional Include Directories: $(VSInstallDir)VSSDK\VisualStudioIntegration\Common\Inc Additional Library Directories: $(VSInstallDir)VSSDK\VisualStudioIntegration\Common\Lib\$(PlatformTarget)

akbyrd commented 2 years ago

I'm working through how to get set up for Concord extensibility from scratch. Here's my experience so far. Apologies for any silly mistakes - I'm kinda just stumbling my way through. Once I'm done my hope is that some of this process can make it into the wiki. I can create a pull request if desired.

Workflow 1 - Visual Studio Extensibility workload

Install the Visual Studio extension development workload (VSSDK)
Create a solution and C++ project (for the extension code)
Project > Build Dependencies > Build Customizations... > Find Existing... > VSSDK\VisualStudioIntegration\Tools\Bin\Microsoft.VSSDK.Debugger.VSDConfigTool.targets
The VSSDK doesn't come with Microsoft.VSSDK.Debugger.VSDebugEng.targets so add some paths manually Question Should the VSSDK come with VSDebugEng.targets?
- Additional Include Directories: $(VSInstallDir)VSSDK\VisualStudioIntegration\Common\Inc
- Additional Library Directories: $(VSInstallDir)VSSDK\VisualStudioIntegration\Common\Lib\$(PlatformTarget)
Add a vsdconfigxml. Question Is the intent to edit the project file by hand to add vsdconfigxml files?

I don't see any templates or content types for this. The vcxproj in this repo uses <VsdConfigXmlFiles> but I don't see a way to add that through the Visual Studio UI.
```
<ItemGroup>
  <VsdConfigXmlFiles Include="natvis.vsdconfigxml" />
</ItemGroup>
```
Note that you still need to use Add Existing Item to see the xsd in the Solution Explorer. Intellisense for the vsdconfigxml schema works out of the box as soon as you add the xmlns.
```
<?xml version="1.0" encoding="utf-8"?>
<Configuration xmlns="http://schemas.microsoft.com/vstudio/vsdconfig/2008">
</Configuration>
```

Workflow 2 - Nuget

Add nuget package: Microsoft.VSSDK.Debugger.VSDebugEng
Add nuget package: Microsoft.VSSDK.Debugger.VSDConfigTool
- This fails to build. VSDConfigTool adds vsdconfig.xsd to the solution automatically. This file causes an error. I can find the dll on my system in C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\PublicAssemblies and it has the correct public key token. It looks like xsd.exe is deprecated starting with VS2017. The dll is no longer installed to the GAC and has to be installed manually to be used. Adding an XML schema through New Item sets Exclude from build by default. I've done the same to allow the project to build - though I could install the assembly if I ended up needing to build the xsd.
  
  The CodeDom provider type "Microsoft.VisualC.CppCodeProvider, CppCodeProvider, Version=10.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" could not be located.
Add a vsdconfigxml. This starts out the same way as Workflow 1.
- Except that if happen to have the extensibility workload installed intellisense will not work. The problem is that VS finds 2 matching schemas: the one installed with the workload and the one added to the project via nuget (it doesn't seem to find the schema copy inside the packages folder). To fix this:
  - Open the file
  - Go to Xml > Schemas...
  - You should see 2 copies of vsdconfig.xsd set to "Use this schema". This shows up as a black check mark.
  - Uncheck one of the copies by setting it to "Automatic" or "Do not use this schema"
  This is fragile. The setting is stored in the .vs folder, not in the project or filter files. Deleting that folder will break intellisense again. Removing and re-adding the vsdconfigxml file will also re-detect the schema and break intellisense. Each developer that touches the extension will need to deal with this locally.
  
  In theory you could also use schemaLocation to let VS know which of the two matching schemas to use. It looks like it works - only one schema is checked when you look at Xml > Schemas... - but intellisense just doesn't work.
```
<?xml version="1.0" encoding="utf-8"?>
<Configuration
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://schemas.microsoft.com/vstudio/vsdconfig/2008 vsdconfig.xsd">
</Configuration>
```

To be continued

I'll add another post when I get further.

akbyrd commented 2 years ago

Actually, I think that's it for getting the headers and libs. Lots more to the process, but not particularly relevant here.

gregg-miskelly commented 2 years ago

Hi @akbyrd, I am just getting back from vacation.

The documentation that you linked to is incorrect for VS 2022 -- Concord headers and libs are now only available via nuget.

For your 'Workflow 2' questions:

VSDConfigTool adds vsdconfig.xsd to the solution automatically. This file causes an error.

I don't know why you would be seeing an error about vsdconfig.xsd or what would be adding it. This is an XML schema there to make it easier to edit your .vsdconfigxml files. It is useful, but optional.

akbyrd commented 2 years ago

Installing the Microsoft.VSSDK.Debugger.VSDConfigTool adds the vsd to the project. It has its content type set to XML Data Generator Tool. This causes it to be run through xsd.exe which relies on CppCodeProvider.dll to be in the GAC. If you've never installed an older version of VS or manually added that dll to the GAC then it won't be there and it causes a build error.

gregg-miskelly commented 2 years ago

Are you seeing this in the samples? Or just your own project? What version of VS are you using? If you are using the samples, are you using master or the VS17 branch?

Are you sure that it the package reference to VSDConfigTool that adds it to the project and not the project file itself? I don't see anything in the package that would add that. The sample projects do include that file as a None item (see here), though I don't have any idea why that would somehow kick in the XSD tool.

akbyrd commented 2 years ago

My own project. VS 2019 16.11.8. I can repro it by making a new solution, grabbing the nuget package, and compiling. But it'll only happen if you've never installed VS 2017 or earlier, so probably easier to repro in a VM.

It's an issue with the nuget package I assume. Not this repo.

I've attached a project following those steps. Here's the package manager output.

Attempting to gather dependency information for package 'Microsoft.VSSDK.Debugger.VSDConfigTool.17.0.1110801' with respect to project 'VSDCT Package Issue', targeting 'native,Version=v0.0'
  GET https://api.nuget.org/v3/registration5-gz-semver2/microsoft.vssdk.debugger.vsdconfigtool/index.json
  OK https://api.nuget.org/v3/registration5-gz-semver2/microsoft.vssdk.debugger.vsdconfigtool/index.json 228ms
Total number of results gathered : 1
Gathering dependency information took 270 ms
Summary of time taken to gather dependencies per source :
https://api.nuget.org/v3/index.json -   248 ms
Attempting to resolve dependencies for package 'Microsoft.VSSDK.Debugger.VSDConfigTool.17.0.1110801' with DependencyBehavior 'Lowest'
Resolving dependency information took 0 ms
Resolving actions to install package 'Microsoft.VSSDK.Debugger.VSDConfigTool.17.0.1110801'
Resolved actions to install package 'Microsoft.VSSDK.Debugger.VSDConfigTool.17.0.1110801'
Retrieving package 'Microsoft.VSSDK.Debugger.VSDConfigTool 17.0.1110801' from 'nuget.org'.
For adding package 'Microsoft.VSSDK.Debugger.VSDConfigTool.17.0.1110801' to project 'VSDCT Package Issue' that targets 'native'.
For adding package 'Microsoft.VSSDK.Debugger.VSDConfigTool.17.0.1110801' to project 'VSDCT Package Issue' that targets 'native'.
Adding package 'Microsoft.VSSDK.Debugger.VSDConfigTool.17.0.1110801' to folder 'C:\Users\akbyrd\Desktop\VSDCT Package Issue\packages'
Added package 'Microsoft.VSSDK.Debugger.VSDConfigTool.17.0.1110801' to folder 'C:\Users\akbyrd\Desktop\VSDCT Package Issue\packages'
Added package 'Microsoft.VSSDK.Debugger.VSDConfigTool.17.0.1110801' to folder 'C:\Users\akbyrd\Desktop\VSDCT Package Issue\packages' from source 'https://api.nuget.org/v3/index.json'
Added file 'vsdconfig.xsd'.
Added file 'vsdconfig.xsd' to project 'VSDCT Package Issue'.
Added package 'Microsoft.VSSDK.Debugger.VSDConfigTool.17.0.1110801' to 'packages.config'
Added file 'packages.config' to project 'VSDCT Package Issue'.
Successfully installed 'Microsoft.VSSDK.Debugger.VSDConfigTool 17.0.1110801' to VSDCT Package Issue
Executing nuget actions took 3.14 sec
Time Elapsed: 00:00:04.1888893
========== Finished ==========

VSDCT Package Issue.zip

gregg-miskelly commented 2 years ago

Got it. The nuget package manager apparently has a behavior that I wasn't aware of where it will copy and add an Xsd item when adding a reference. Fortunately, this is trivial to work around: undo the damage that the nuget package manager did by deleting the copied vsdconfig.xsd.

Since there is a lot of discussion in this issue about various things I am breaking out this bug into a new issue: https://github.com/microsoft/ConcordExtensibilitySamples/issues/74

akbyrd commented 2 years ago

The documentation that you linked to is incorrect for VS 2022 -- Concord headers and libs are now only available via nuget.

I grabbed 2022 to start testing my extension against it. I noticed the headers, lib, and one of the targets files are still included with the VSSDK. Are you saying that shouldn't be there anymore or that it will go away in the future?

gregg-miskelly commented 2 years ago

Well, there was a plan to remove it that I thought happened, but apparently only the work to remove the .NET reference assemblies actually happened. I am not sure what the future is for it. I will update the docs accordingly, but I would recommend sticking with nuget packages unless you have an existing project that you don't want to touch.

akbyrd commented 2 years ago

Sounds good. Thank you.

microsoft / ConcordExtensibilitySamples