-
Notifications
You must be signed in to change notification settings - Fork 392
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update docs #9522
Merged
tmeschter
merged 3 commits into
dotnet:main
from
tmeschter:240812-UpdateProjectSelectorDocumentation
Aug 15, 2024
Merged
Update docs #9522
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,12 +1,51 @@ | ||
# Opening with the new project system | ||
|
||
## Background | ||
|
||
The solution (.sln) file specifies which project system should be used to open each project. For example: | ||
|
||
``` | ||
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Library3", "Library3.csproj", "{ADFEAAF5-225C-4E13-8B65-77057AAC44B8}" | ||
EndProject | ||
``` | ||
|
||
Here the "Library3.csproj" project should be opened with the project system designated by the "FAE04EC0-301F-11D3-BF4B-00C04F79EFBC" GUID. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. is the other GUID relevant? ADFEAAF5-225C-4E13-8B65-77057AAC44B8 |
||
|
||
While the solution file entry associates a specific project with a specific project system, ultimately this information comes from the [ProviderProjectFactoryAttribute](https://learn.microsoft.com/en-us/dotnet/api/microsoft.visualstudio.shell.provideprojectfactoryattribute)--or the equivalent entries in a .pkgdef file--which associates a file extension (like .csproj) with a project system. | ||
tmeschter marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## Problem | ||
|
||
There may be situations where more than one project system is capable of loading project files with a particular extension, or where the choice of project system needs to be dynamically determined. In this case the solution file itself does not contain enough information for the correct project system to be determined. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. nit: |
||
|
||
## General Solution | ||
|
||
One option is to provide some sort of upgrade tool that can analyze the solution file and project, recommend the user switch that project to a different project system, and then make the required changes to the solution file on their behalf. However, this requires interactions with the user (which may become noisy if there are a lot of projects to upgrade) changes to the solution file (which the user may not understand) and reloading the project. This is also not a particularly dynamic approach as the change to the project system is persisted in the solution file. | ||
|
||
To better address the situation where you may need to dynamically choose the project system, VS provides the [IVSProjectSelector](https://learn.microsoft.com/en-us/dotnet/api/microsoft.visualstudio.shell.interop.ivsprojectselector) interface. Implementations of this interface are associated with a particular project system, and are called before a project is loaded in order to redirect the load to a different project system. | ||
tmeschter marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
When an IVSProjectSelector is in play, the following sequence of events occurs before a project is loaded: | ||
|
||
1. The solution loader reads the project system GUID specified in the .sln file. | ||
2. If an implementation of IVSProjectSelector has been associated with that project system GUID it is invoked with the following information: | ||
1. The original project system GUID | ||
2. The path to the project file | ||
3. The selector can respond in one of two ways: | ||
1. Decline the request, in which case the project will be loaded with the project system in the .sln file. | ||
2. Return the GUID of a different project system, in which case it will be used to load the project. | ||
|
||
## C#/VB/F# Specifics | ||
|
||
### Our IVSProjectSelector implementation | ||
|
||
The implementation of our IVSProjectSelector lives in the VS repo as it is associated with the older CSProj project system. However, the registry keys that actually associated the selector with the CSProj project system can be found in [ProjectSelectors.pkgdef](https://github.com/dotnet/project-system/blob/1aa6689827ba43e8cd7b9d29a6d15b3eabf6842c/setup/ProjectSystemSetup/ProjectSelectors.pkgdef); we only want the selector to be active when this project system is installed. | ||
|
||
***NOTE:** The behaviors listed below are subject to change as we add support for more project types in the new project system.* | ||
|
||
## When does a project open with the new project system versus the legacy project system? | ||
### When does a project open with the new project system versus the legacy project system? | ||
|
||
Because both the new project system and legacy project systems use the same file extensions (csproj, vbproj and fsproj), two factors determine whether a project will open in one or the other. | ||
|
||
### TargetFramework/TargetFrameworks properties | ||
#### TargetFramework/TargetFrameworks properties | ||
|
||
*Applies to C# and Visual Basic only* | ||
|
||
|
@@ -45,7 +84,7 @@ Whereas, the following csproj or vbproj will open in the legacy project system: | |
</Project> | ||
``` | ||
|
||
### SDKs | ||
#### SDKs | ||
|
||
*Applies to F# in 16.3 and earlier, and to F#, C#, and Visual Basic in 16.4 and later* | ||
|
||
|
@@ -91,7 +130,7 @@ Whereas the following will open in the legacy project system: | |
</Project> | ||
``` | ||
|
||
### Project Type GUIDs | ||
#### Project Type GUIDs | ||
|
||
Inside the solution, there are GUIDs associated with a project called a "project type". By default, all csproj, vbproj and fsproj point to the following three GUIDs (the first GUID in the line): | ||
|
||
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Users reading this might be interested in other project type GUIDs too. We don't have an official doc that lists these that I know of, but this source file does a decent job of enumerating the ones that are most likely interesting to the reader:
https://github.com/dotnet/project-system/blob/1aa6689827ba43e8cd7b9d29a6d15b3eabf6842c/src/Microsoft.VisualStudio.ProjectSystem.Managed.VS/ProjectSystem/ProjectType.cs