Skip to content
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.

Sign up for GitHub

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

User config file description update #9900

Merged
merged 4 commits into from
Jan 10, 2024
Merged

User config file description update #9900

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
eb93ccf
Added a bit more info on .user file
maridematte Dec 5, 2023
24b9ab2
Changed a bit the supported projects part
maridematte Dec 5, 2023
ca42e07
Changed wording to be clearer
maridematte Dec 15, 2023
7c24d70
Update docs/msbuild/customize-your-local-build.md
ghogen Jan 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs/msbuild/customize-your-local-build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,12 @@ When you work in a team that used a code repository like GitHub, source control,

## .user file

*Microsoft.Common.CurrentVersion.targets* imports `$(MSBuildProjectFullPath).user` if it exists, so you can create a file next to your project with that additional extension. For long-term changes you plan to check into source control, prefer changing the project itself, so that future maintainers do not have to know about this extension mechanism.
Using `$(MSBuildProjectFullPath).user`, also referred as `.user` file in this context, is also an option. This file is intended to keep extensions, options, or variables that are specific to your local machine. It is not intended to be uploaded to source control, and it is automatically checked on `.gitignore`. For more extensive changes prefer changing the project itself, so that future maintainers do not have to know about this extension mechanism.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Using `$(MSBuildProjectFullPath).user`, also referred as `.user` file in this context, is also an option. This file is intended to keep extensions, options, or variables that are specific to your local machine. It is not intended to be uploaded to source control, and it is automatically checked on `.gitignore`. For more extensive changes prefer changing the project itself, so that future maintainers do not have to know about this extension mechanism.
Using `$(MSBuildProjectFullPath).user`, also referred as `.user` file in this context, is also an option. This file is intended to keep extensions, options, or variables that are specific to your local machine. It is not intended to be uploaded to source control, and it is automatically excluded in the default Visual Studio `.gitignore`. For more extensive changes prefer changing the project itself, so that future maintainers do not have to know about this extension mechanism.


On supported multitargeted projects the `.user` file is automatically imported in inner builds and outer builds, so you can just create the file within the solution. If you are working on another type of build, you can still use the `.user` file. You can create it within your solution and then import it in your project file.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"inner" and "outer" builds are not generally user-facing concepts, so I'm not sure this is the best way to phrase this. @ghogen, what happened is that prior to 17.9, the .user file was imported only for the inner build, so it wasn't usable to tweak things like packaging. @maridematte made it more consistent for 17.9+. See dotnet/msbuild#9131 / dotnet/msbuild#9558. Can you think of a way to say that that's a bit more friendly?

```xml
<Import Project="$(MSBuildProjectFullPath).user" Condition="Exists('$(MSBuildProjectFullPath).user')"/>
```
Comment on lines +23 to +26
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What motivated the "do it manually for a custom project type" stuff @maridematte? It's good advice but I'm not sure if users will be looking for that kind of thing in the context of this document.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this is one of the only places that mention .user files I thought to add this bit here as it would feel out of place anywhere else. I think it is a useful bit of information to have in the docs and since it is short enough I think it is ok to add here even if it doesn't completely fit with the context of the document.


## MSBuildExtensionsPath and MSBuildUserExtensionsPath

Expand Down