diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 000000000..a8838bc78 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,14 @@ +# These owners will be the default owners for everything in +# the repo. Unless a later match takes precedence, +# review when someone opens a pull request. +# For more on how to customize the CODEOWNERS file - https://help.github.com/en/articles/about-code-owners +* @NuGet/nuget-client @NuGet/nuget-pm + +# @NuGet/core-team owns any file in the `/docs/nuget-org/` directory +# in the root of your repository and any of its subdirectories. +/docs/nuget-org/ @NuGet/nuget-client @NuGet/nuget-pm @NuGet/gallery-team +/docs/api/ @NuGet/nuget-client @NuGet/nuget-pm @NuGet/gallery-team + +# @NuGet/core-team owns any file in the `/docs/policies/` directory +# in the root of your repository and any of its subdirectories. +/docs/policies/ @NuGet/nuget-client @NuGet/nuget-pm @NuGet/gallery-team diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..344d2e2ad --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,56 @@ +# .NET Documentation Guidelines + +## Disclosure + +For any Markdown files generated by AI, always disclose that they were created with the assistance of AI. Add the following frontmatter key/value pair: + +```markdown +ai-usage: ai-generated +``` + +## Terminology + +Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework). + +## Writing Style + +Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) with these specifics: + +### Voice and Tone + +- Active voice, second person addressing reader directly. +- Conversational tone with contractions. +- Present tense for instructions/descriptions. +- Imperative mood for instructions ("Call the method" not "You should call the method"). +- Use "might" instead of "may" for possibility. +- Use "can" instead of "may" for permissible actions. +- Avoid "we"/"our" referring to documentation authors or product teams. + +### Structure and Format + +- Sentence case headings (no gerunds in titles). +- Be concise, break up long sentences. +- Oxford comma in lists. +- Use bullets for unordered lists. +- Number all ordered list items as "1." (not sequential numbering like "1.", "2.", "3.", etc.) +- Ordered and unordered lists should use complete sentences with proper punctuation, ending with a period if it's more than three words. +- Avoid "etc." or "and so on" - provide complete lists or use "for example". +- Use "for example" instead of "e.g.". +- Use "that is" instead of "i.e.". +- No consecutive headings without content between them. + +### Formatting Conventions + +- **Bold** for UI elements. +- `Code style` for file names, folders, custom types, non-localizable text. +- Raw URLs in angle brackets. +- Use relative links for files in this repo. +- Remove `https://learn.microsoft.com/en-us` from learn.microsoft.com links. + +## File Naming + +New Markdown files: lowercase with hyphens, omit filler words (the, a, etc.). + +## Special Cases + +- When you (Copilot) are assigned an issue in GitHub, after you've completed your work and the workflows (status checks) have run, check to make sure there are no build warnings under the OpenPublishing.Build status check. If there are, open the build report (under View Details) and resolve any build warnings you introduced. diff --git a/.github/fabricbot.json b/.github/fabricbot.json new file mode 100644 index 000000000..8dc051bb6 --- /dev/null +++ b/.github/fabricbot.json @@ -0,0 +1,410 @@ +{ + "version": "1.0", + "tasks": [ + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssueCommentResponder", + "version": "1.0", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "isAction", + "parameters": { + "action": "created" + } + }, + { + "name": "hasLabel", + "parameters": { + "label": "WaitingForCustomer" + } + }, + { + "name": "isOpen", + "parameters": {} + }, + { + "operator": "or", + "operands": [ + { + "operator": "and", + "operands": [ + { + "name": "hasLabel", + "parameters": { + "label": "Transferred issue" + } + }, + { + "operator": "not", + "operands": [ + { + "name": "activitySenderHasPermissions", + "parameters": { + "permissions": "write" + } + } + ] + } + ] + }, + { + "name": "isActivitySender", + "parameters": { + "user": { + "type": "author" + } + } + } + ] + } + ] + }, + "eventType": "issue", + "eventNames": [ + "issue_comment" + ], + "taskName": "[Manage \"WaitingFor\" labels] Replace tag \"WaitingForCustomer\" with \"WaitingForNuGetTeam\" when the author comments on an issue. Also remove `Status:No recent activity` if it's been set.", + "actions": [ + { + "name": "removeLabel", + "parameters": { + "label": "WaitingForCustomer" + } + }, + { + "name": "addLabel", + "parameters": { + "label": "WaitingForNuGetTeam" + } + }, + { + "name": "removeLabel", + "parameters": { + "label": "Status:No recent activity" + } + } + ] + }, + "disabled": false + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssuesOnlyResponder", + "version": "1.0", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "isAction", + "parameters": { + "action": "closed" + } + }, + { + "operator": "or", + "operands": [ + { + "name": "hasLabel", + "parameters": { + "label": "WaitingForNuGetTeam" + } + }, + { + "name": "hasLabel", + "parameters": { + "label": "WaitingForCustomer" + } + } + ] + } + ] + }, + "eventType": "issue", + "eventNames": [ + "issues", + "project_card" + ], + "taskName": "[Manage \"WaitingFor\" labels] Remove any \"WaitingFor\" label when the issue is closed", + "actions": [ + { + "name": "removeLabel", + "parameters": { + "label": "WaitingForNuGetTeam" + } + }, + { + "name": "removeLabel", + "parameters": { + "label": "WaitingForCustomer" + } + } + ] + }, + "disabled": false + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssueCommentResponder", + "version": "1.0", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "isAction", + "parameters": { + "action": "created" + } + }, + { + "name": "hasLabel", + "parameters": { + "label": "WaitingForNuGetTeam" + } + }, + { + "name": "isOpen", + "parameters": {} + }, + { + "name": "activitySenderHasPermissions", + "parameters": { + "permissions": "write" + } + } + ] + }, + "eventType": "issue", + "eventNames": [ + "issue_comment" + ], + "taskName": "[Manage \"WaitingFor\" labels] Replace tag \"WaitingForNuGetTeam\" with \"WaitingForCustomer\" when NuGet team comments on an issue.", + "actions": [ + { + "name": "removeLabel", + "parameters": { + "label": "WaitingForNuGetTeam" + } + }, + { + "name": "addLabel", + "parameters": { + "label": "WaitingForCustomer" + } + } + ] + }, + "disabled": false + }, + { + "taskType": "scheduled", + "capabilityId": "ScheduledSearch", + "subCapability": "ScheduledSearch", + "version": "1.0", + "config": { + "frequency": [ + { + "weekDay": 0, + "hours": [ + 6 + ], + "timezoneOffset": -7 + }, + { + "weekDay": 1, + "hours": [ + 6 + ], + "timezoneOffset": -7 + }, + { + "weekDay": 2, + "hours": [ + 6 + ], + "timezoneOffset": -7 + }, + { + "weekDay": 3, + "hours": [ + 6 + ], + "timezoneOffset": -7 + }, + { + "weekDay": 4, + "hours": [ + 6 + ], + "timezoneOffset": -7 + }, + { + "weekDay": 5, + "hours": [ + 6 + ], + "timezoneOffset": -7 + }, + { + "weekDay": 6, + "hours": [ + 6 + ], + "timezoneOffset": -7 + } + ], + "searchTerms": [ + { + "name": "hasLabel", + "parameters": { + "label": "WaitingForCustomer" + } + }, + { + "name": "noActivitySince", + "parameters": { + "days": 14 + } + }, + { + "name": "isIssue", + "parameters": {} + }, + { + "name": "isOpen", + "parameters": {} + }, + { + "name": "noLabel", + "parameters": { + "label": "Status:No recent activity" + } + } + ], + "taskName": "[Manage stale WaitingForCustomer issues] Search for WaitingForCustomer issues with no activity over 14 days and warn.", + "actions": [ + { + "name": "addLabel", + "parameters": { + "label": "Status:No recent activity" + } + }, + { + "name": "addReply", + "parameters": { + "comment": "This issue has been automatically marked as stale because we have not received a response in 14 days. It will be closed if no further activity occurs within another 14 days of this comment." + } + } + ] + } + }, + { + "taskType": "scheduled", + "capabilityId": "ScheduledSearch", + "subCapability": "ScheduledSearch", + "version": "1.0", + "config": { + "frequency": [ + { + "weekDay": 0, + "hours": [ + 6 + ], + "timezoneOffset": -7 + }, + { + "weekDay": 1, + "hours": [ + 6 + ], + "timezoneOffset": -7 + }, + { + "weekDay": 2, + "hours": [ + 6 + ], + "timezoneOffset": -7 + }, + { + "weekDay": 3, + "hours": [ + 6 + ], + "timezoneOffset": -7 + }, + { + "weekDay": 4, + "hours": [ + 6 + ], + "timezoneOffset": -7 + }, + { + "weekDay": 5, + "hours": [ + 6 + ], + "timezoneOffset": -7 + }, + { + "weekDay": 6, + "hours": [ + 6 + ], + "timezoneOffset": -7 + } + ], + "searchTerms": [ + { + "name": "hasLabel", + "parameters": { + "label": "Status:No recent activity" + } + }, + { + "name": "noActivitySince", + "parameters": { + "days": 14 + } + }, + { + "name": "isIssue", + "parameters": {} + }, + { + "name": "isOpen", + "parameters": {} + } + ], + "taskName": "[Close stale WaitingForCustomer issues] Search for stale WaitingForCustomer issues with no activity over 14 days and warn.", + "actions": [ + { + "name": "closeIssue", + "parameters": {} + }, + { + "name": "removeLabel", + "parameters": { + "label": "Status:No recent activity" + } + }, + { + "name": "addLabel", + "parameters": { + "label": "Resolution:NeedMoreInfo" + } + } + ] + } + } + ], + "userGroups": [] + } \ No newline at end of file diff --git a/.github/stale.yml b/.github/stale.yml deleted file mode 100644 index f9f9cd560..000000000 --- a/.github/stale.yml +++ /dev/null @@ -1,16 +0,0 @@ -# Number of days of inactivity before an issue becomes stale -daysUntilStale: 60 -# Number of days of inactivity before a stale issue is closed -daysUntilClose: 0 -# Issues with these labels will never be considered stale -exemptLabels: - - pinned - - security -# Label to use when marking an issue as stale -staleLabel: autoclose -# Comment to post when marking an issue as stale. Set to `false` to disable -markComment: false -# Comment to post when closing a stale issue. Set to `false` to disable -closeComment: > - This issue has been automatically marked as stale and closed because it has not had - recent activity. Thank you for your contributions. diff --git a/.gitignore b/.gitignore index 42594a1c0..13ade8981 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,7 @@ _themes/ _themes.MSDN.Modern/ _themes.VS.Modern/ +# Visual Studio +.vs/ + .openpublishing.buildcore.ps1 \ No newline at end of file diff --git a/.openpublishing.build.ps1 b/.openpublishing.build.ps1 deleted file mode 100644 index aadef7620..000000000 --- a/.openpublishing.build.ps1 +++ /dev/null @@ -1,17 +0,0 @@ -param( - [string]$buildCorePowershellUrl = "https://opbuildstorageprod.blob.core.windows.net/opps1container/.openpublishing.buildcore.ps1", - [string]$parameters -) -# Main -$errorActionPreference = 'Stop' - -# Step-1: Download buildcore script to local -echo "download build core script to local with source url: $buildCorePowershellUrl" -$repositoryRoot = Split-Path -Parent $MyInvocation.MyCommand.Definition -$buildCorePowershellDestination = "$repositoryRoot\.openpublishing.buildcore.ps1" -Invoke-WebRequest $buildCorePowershellUrl -OutFile "$buildCorePowershellDestination" - -# Step-2: Run build core -echo "run build core script with parameters: $parameters" -& "$buildCorePowershellDestination" "$parameters" -exit $LASTEXITCODE diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index a646e7a6c..39be778c5 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -18,41 +18,51 @@ } ], "notification_subscribers": [], + "sync_notification_subscribers": null, "branches_to_filter": [], "git_repository_url_open_to_public_contributors": "https://github.com/NuGet/docs.microsoft.com-nuget", - "git_repository_branch_open_to_public_contributors": "master", + "git_repository_branch_open_to_public_contributors": "main", "skip_source_output_uploading": false, + "need_preview_pull_request": true, "contribution_branch_mappings": {}, "dependent_repositories": [ { "path_to_root": "_themes", "url": "https://github.com/Microsoft/templates.docs.msft", - "branch": "master", + "branch": "main", "branch_mapping": {} }, { "path_to_root": "_themes.pdf", "url": "https://github.com/Microsoft/templates.docs.msft.pdf", - "branch": "master", + "branch": "main", + "branch_mapping": {} + }, + { + "path_to_root": "nuget-samples", + "url": "https://github.com/NuGet/Samples", + "branch": "main", "branch_mapping": {} } ], - "branch_target_mapping": { - "live": [ - "Publish", - "Pdf" + "branch_target_mapping": { + "live": [ + "Publish", + "Pdf" ], - "master": [ + "main": [ "Publish", "PDF" ] }, "need_generate_pdf_url_template": true, - "need_preview_pull_request": true, "Targets": { "Pdf": { "template_folder": "_themes.pdf" } }, - "need_generate_pdf": false -} + "need_generate_pdf": false, + "docs_build_engine": { + "name": "docfx_v3" + } +} \ No newline at end of file diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 7d54ebd69..be80d09e9 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -27,7 +27,7 @@ }, { "source_path": "docs/create-packages/Dependency-Versions.md", - "redirect_url": "/nuget/reference/package-versioning", + "redirect_url": "/nuget/concepts/package-versioning", "redirect_document_id": false }, { @@ -62,7 +62,7 @@ }, { "source_path": "docs/Schema/analyzers-conventions.md", - "redirect_url": "/nuget/reference/analyzers-conventions", + "redirect_url": "/nuget/guides/analyzers-conventions", "redirect_document_id": false }, { @@ -99,7 +99,7 @@ "source_path": "docs/Quickstart/Create-and-publish-a-package.md", "redirect_url": "/nuget/quickstart/create-and-publish-a-package-using-visual-studio", "redirect_document_id": false - }, + }, { "source_path": "docs/Quickstart/Use-a-Package.md", "redirect_url": "/nuget/quickstart/install-and-use-a-package-in-visual-studio", @@ -107,7 +107,7 @@ }, { "source_path": "docs/policies/command-line-reference.md", - "redirect_url": "/nuget/tools/nuget-exe-cli-reference", + "redirect_url": "/nuget/reference/nuget-exe-cli-reference", "redirect_document_id": false }, { @@ -364,6 +364,31 @@ "source_path": "docs/tools/ps-ref-update-package.md", "redirect_url": "/nuget/reference/ps-reference/ps-ref-update-package", "redirect_document_id": false + }, + { + "source_path": "docs/reference/errors-and-warnings/NU1901.md", + "redirect_url": "/nuget/reference/errors-and-warnings/NU1901-NU1904", + "redirect_document_id": false + }, + { + "source_path": "docs/reference/errors-and-warnings/NU1902.md", + "redirect_url": "/nuget/reference/errors-and-warnings/NU1901-NU1904", + "redirect_document_id": false + }, + { + "source_path": "docs/reference/errors-and-warnings/NU1903.md", + "redirect_url": "/nuget/reference/errors-and-warnings/NU1901-NU1904", + "redirect_document_id": false + }, + { + "source_path": "docs/reference/errors-and-warnings/NU1904.md", + "redirect_url": "/nuget/reference/errors-and-warnings/NU1901-NU1904", + "redirect_document_id": false + }, + { + "source_path": "docs/guides/create-packages-for-xamarin.md", + "redirect_url": "/nuget", + "redirect_document_id": false } ] } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..2f1b58d08 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,39 @@ +# Contributing + +No contribution is too big or too small. + +1. Visit the page to edit in the [NuGet documentation](https://learn.microsoft.com/nuget/), then click the **Edit** button on the top right. This brings you to the appropriate markdown page in the repo. +1. Edit the markdown: + 1. If you're including images (use PNGs, generally), place them in the media folder that's in the topic's folder. Links are then `media/.png`. + 1. Relative links to other pages in this docset should be in the form `..//.md` including the training `.md`. If you're linking to another topic in the same folder, then `..//` can be omitted. When using anchors, always remember to include the `.md` before the `#`. + 1. When using external links, especially to Microsoft Learn, omit any language tag like "en-us" so that a reader in another language lands on a target page in that same language if it's available. +1. When you're done, enter a commit message below, and click **Propose file change**. +1. Send a pull request for your change. We review PRs on a regular basis. +1. Thank you! + +If you're creating a new topic, keep the following in mind as well: + +1. Always place the new topic in an appropriate subfolder, and follow the conventions for filenames as you see them used here. + +1. You must include a metadata block as you see on other topics. Typical defaults (such as for `ms.workload` and `ms.reviewer`) are set within `docs/docjx.json`, so you need only change the following: + + - title: The title that appears in search results. For SEO, this ideally isn't the same as the top-level # (H1) of the article. + - description: The abstract of the article that appears in search results. + - author: the author's GitHub ID, to which issues files for this article are assigned. + - ms.author: if the author is a Microsoft employee, this is the Microsoft alias. Used for reporting and forwarding feedback from other channels. + - manager: Microsoft alias of the author's manager, if applicable. + - ms.date: the date of the last revision or review of the article in mm/dd/yyyy format (use leading zeros). This is a communication to the reader about freshness, so it's not updated for minor changes, only for more significant revisions OR when the article has reverified even if there are no changes. + - ms.topic: used to categorize the article in reports. See table below. Most articles are "conceptual". + +1. In addition to adding your page, edit `docs/TOC.md` to add a link to that page. + +1. If you're adding a top-level node to the TOC, also make an entry for it in `docs/index.md`. + +| ms.topic category | Description | +| --- | --- | +| conceptual | Use for any content that doesn't fall into another. This is set as the default in docfx.json. | +| overview | Use for any overview or user-guide articles, typically only those that live under an "Overview" node in the TOC. | +| quickstart | Anything under the "Quickstart" node in the TOC that's authored according to Quickstart guidelines. | +| tutorial | Anything under the "Tutorial" node in the TOC that's authored according to Tutorial guidelines. | +| reference | Any reference-type article that isn't auto-generated. | +| article | Use for community-contributed content (that is, anything from outside the engineering team or the content team at Microsoft. | diff --git a/README.md b/README.md index 087489c93..36a0aa314 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,51 @@ -# docs.microsoft.com-nuget +# NuGet Docs -The NuGet documentation contained in this repository is hosted on docs.microsoft.com/nuget. This repository was migrated from the former NuGetDocs repository, https://github.com/NuGet/NuGetDocs, which is no longer in active use. +The NuGet documentation contained in this repository is hosted in [NuGet documentation](https://learn.microsoft.com/nuget/). This repository was migrated from the former NuGetDocs repository, https://github.com/NuGet/NuGetDocs, which is no longer in active use. -Contributions to this docset are welcome. Please submit PRs to the *master* branch. (The master branch is used for staging changes which is periodically merged into the *live* branch which is what's published to the live docs site.) +Contributions to this docset are welcome. Please submit PRs to the *main* branch. The main branch is used for staging changes which is periodically merged into the *live* branch which is what's published to the live Microsoft Learn site. NuGet follows the [.NET Foundation Contributors Code of Conduct](https://github.com/dotnet/home/blob/master/guidance/be-nice.md). Please take a few minutes to review it. -## Respository structure +## Repository structure -- All markdown files are in the docs folder and various subfolders. -- The docs/index.md file defines the landing (hub) page as it appears on docs.microsoft.com/nuget. -- The docs/TOC.md file defines the left-hand navigation panel that appears when you navigate to any page other than the hub page. +- All markdown files are in the `docs` folder and various subfolders. +- The `docs/index.md` file defines the landing (hub) page as it appears in the [NuGet documentation](https://learn.microsoft.com/nuget). +- The `docs/TOC.md` file defines the left-hand navigation panel that appears when you navigate to any page other than the hub page. - Images are contained within media folders within each subfolder. -- The docs/docfx.json file contains various defaults, especially for metadata. -- The docs/.openpublishing.redirection.json file contains redirects for old filenames; if you rename a file, create an entry here that maps the old to the new. -- The docs/_breadcrumb/toc.yml file defines the breadcrumbs that appear on the site and their target pages. Be mindful of this if you make changes to filenames or placement of articles. +- The `docs/docfx.json` file contains various defaults, especially for metadata. +- The `docs/.openpublishing.redirection.json` file contains redirects for old filenames; if you rename a file, create an entry here that maps the old to the new. +- The `docs/_breadcrumb/toc.yml` file defines the breadcrumbs that appear on the site and their target pages. Be mindful of this if you make changes to filenames or placement of articles. ## Contribution workflow -No contribution is too big or too small-- +No contribution is too big or too small. -1. Visit the page to edit on [docs.microsoft.com/nuget](https://docs.microsoft.com/nuget/), then click the **Edit** button on the top right. This brings you to the appropriate markdown page in the repo. +1. Visit the page to edit in [NuGet documentation](https://learn.microsoft.com/nuget/), then click the **Edit** button on the top right. This brings you to the appropriate markdown page in the repo. 1. Edit the markdown: 1. If you're including images (use PNGs, generally), place them in the media folder that's in the topic's folder. Links are then `media/.png`. - 1. Relative links to other pages in this docset should be in the form `..//.md` including the training `.md`. If you're linking to another topic in the same folder, then `..//` can be omitted. When using anchors, always remember to include the `.md` before the `#`. - 1. When using external links, especially to docs.microsoft.com (or msdn.microsoft.com for any older content), omit any language tag like "en-us" so that a reader in another language lands on a target page in that same language if it's available. + 1. Relative links to other pages in this docset should be in the form `..//.md` including the trailing `.md`. If you're linking to another topic in the same folder, then `..//` can be omitted. When using anchors, always remember to include the `.md` before the `#`. + 1. When using external links, especially to Microsoft Learn, omit any language tag like "en-us" so that a reader in another language lands on a target page in that same language if it's available. 1. When you're done, enter a commit message below, and click **Propose file change**. -1. Send a pull request for your change. We review PRs on a regular basis. +1. Send a pull request for your change. Review requests are automatic and we review PRs on a regular basis. 1. Thank you! If you're creating a new topic, keep the following in mind as well: 1. Always place the new topic in an appropriate subfolder, and follow the conventions for filenames as you see them used here. -1. You must include a metadata block as you see on other topics. Typical defaults (such as for ms.workload and ms.reviewer) are set within docs/docjx.json, so you need only change the following: - - - title: The title that appears in search results. For SEO, this ideally isn't the same as the top-level # (H1) of the article. - - description: The abstract of the article that appears in search results. - - author: the author's GitHub ID, to which issues files for this article are assigned. - - ms.author: if the author is a Microsoft employee, this is the Microsoft alias. Used for reporting and forwarding feedback from other channels. - - manager: Microsoft alias of the author's manager, if applicable. - - ms.date: the date of the last revision or review of the article in mm/dd/yyyy format (use leading zeros). This is a communication to the reader about freshness, so it's not updated for minor changes, only for more significant revisions OR when the article has reverified even if there are no changes. - - ms.topic: used to categorize the article in reports. See table below. Most articles are "conceptual". -1. In addition to adding your page, edit docs/TOC.md to add a link to that page. -1. If you're adding a top-level node to the TOC, also make an entry for it in docs/index.md. + +1. You must include a metadata block as you see on other topics. Typical defaults (such as for `ms.workload` and `ms.reviewer`) are set within `docs/docjx.json`, so you need only change the following: + + - title: The title that appears in search results. For SEO, this ideally isn't the same as the top-level # (H1) of the article. + - description: The abstract of the article that appears in search results. + - author: the author's GitHub ID, to which issues files for this article are assigned. + - ms.author: if the author is a Microsoft employee, this is the Microsoft alias. Used for reporting and forwarding feedback from other channels. + - manager: Microsoft alias of the author's manager, if applicable. + - ms.date: the date of the last revision or review of the article in mm/dd/yyyy format (use leading zeros). This is a communication to the reader about freshness, so it's not updated for minor changes, only for more significant revisions OR when the article has reverified even if there are no changes. + - ms.topic: used to categorize the article in reports. See table below. Most articles are "conceptual". + +1. In addition to adding your page, edit `docs/TOC.md` to add a link to that page. + +1. If you're adding a top-level node to the TOC, also make an entry for it in `docs/index.md`. | ms.topic category | Description | | --- | --- | @@ -51,7 +54,14 @@ If you're creating a new topic, keep the following in mind as well: | quickstart | Anything under the "Quickstart" node in the TOC that's authored according to Quickstart guidelines. | | tutorial | Anything under the "Tutorial" node in the TOC that's authored according to Tutorial guidelines. | | reference | Any reference-type article that isn't auto-generated. | -| article | Use for community-contributed content (that is, anything from outside the engineering team or the docs team at Microsoft. | +| article | Use for community-contributed content (that is, anything from outside the engineering team or the content team at Microsoft. | + +## Merging to the live branch + +NuGet team members have permissions to merge to `live` branch manually, at their own discretion. +Otherwise, a regular (about once a month) Reverse Integration (RI) will be performed from `main` -> `live` branch. +Based on the urgency of the docs, this may happen frequently. +It is very important that the RI pull requests are *merged* and *not squashed*. ## Conventions @@ -59,7 +69,7 @@ In general, if you don't see something described here, look in editing markdown ## Language level and terms -Because our docs can be localized into many languages other than English, topics should be written at what's called the "fifth-grade" reading level, or what a typical 11-12-year-old child would understand. In other words, avoid using college-level words if possible. +Because content can be localized into many languages other than English, topics should be written at what's called the "fifth-grade" reading level, or what a typical 11-12-year-old child would understand. In other words, avoid using college-level words if possible. To keep the tone more casual, use contractions like "you'll" and "don't". @@ -96,7 +106,7 @@ With boldface used for UI elements, use *italics* for emphasis in the text. ### Tables -Use standard markdown tables, starting with "| heading | heading | heading |", followed by "| --- | --- | --- |", followed by your rows. The row with "---" is necessary for docs.microsoft.com to read the markdown as a table. +Use standard markdown tables, starting with "| heading | heading | heading |", followed by "| --- | --- | --- |", followed by your rows. The row with "---" is necessary for Microsoft Learn to read the markdown as a table. Items in the first column are bolded by default, so you don't need to do that explicitly. @@ -128,7 +138,7 @@ Markdown and HTML are ignored within inline code. ### Code blocks -Code blocks on docs.microsoft.com are delineated by with three grave accents (backticks), ```, at the beginning and the end. You do not need to indent code blocks unless they are contained within a list. +Code blocks on Microsoft Learn are delineated by with three grave accents (backticks), ```, at the beginning and the end. You do not need to indent code blocks unless they are contained within a list. The opening ``` should be followed by a language code for proper syntax coloring, such as "xml", "json", "csharp", etc. Use "cli" for command-line examples and "output" for command-line results. @@ -136,27 +146,27 @@ The only case when you should use ``` without a language tag is when creating a ### Callouts -docs.microsoft.com uses blockquotes for callouts, that is, lines starting with ">". +Microsoft Learn uses blockquotes for callouts, that is, lines starting with ">". -Callout sections with ">" only will appear with a solid gray line to the left. See [Creating NuGet packages](https://docs.microsoft.com/nuget/create-packages/creating-a-package) for examples. +Callout sections with ">" only will appear with a solid gray line to the left. See [Creating NuGet packages](https://learn.microsoft.com/nuget/create-packages/creating-a-package) for examples. You can also use one of the following callout tags on the first line that will create a shaded callout in the indicated color: | Tag | Callout use | Topic with examples | | --- | --- | --- | -| `> [!Note]` | Callouts without any special emphasis. | [Creating NuGet packages](https://docs.microsoft.com/nuget/create-packages/creating-a-package) | -| `> [!Tip]` | Callouts that share special tips and tricks or other helpful knowledge. | [Package consumption overview](https://docs.microsoft.com/nuget/consume-packages/overview-and-workflow) | -| `> [!Important]` | Callouts that describe cautions. | [NuGet.Server](https://docs.microsoft.com/nuget/hosting-packages/nuget-server) | -| `> [!Warning]` | Callouts that warn readers about situations that could cause data loss or unexpected consequences. | [Dependency resolution](https://docs.microsoft.com/nuget/consume-packages/dependency-resolution) | +| `> [!Note]` | Callouts without any special emphasis. | [Creating NuGet packages](https://learn.microsoft.com/nuget/create-packages/creating-a-package) | +| `> [!Tip]` | Callouts that share special tips and tricks or other helpful knowledge. | [Package consumption overview](https://learn.microsoft.com/nuget/consume-packages/overview-and-workflow) | +| `> [!Important]` | Callouts that describe cautions. | [NuGet.Server](https://learn.microsoft.com/nuget/hosting-packages/nuget-server) | +| `> [!Warning]` | Callouts that warn readers about situations that could cause data loss or unexpected consequences. | [Dependency resolution](https://learn.microsoft.com/nuget/consume-packages/dependency-resolution) | ### Links - In general, always use the title of the target page as the link text rather than words like "see here" or "this documentation". - Relative links to other pages in this docset should be in the form `..//.md` including the trailing `.md`. -- Links to other markdown files on docs.microsoft.com are case-insensitive (unlike links to files in GitHub, which are). +- Links to other markdown files on Microsoft Learn are case-insensitive (unlike links to files in GitHub, which are). - If you're linking to another topic in the same folder, then `..//` can be omitted. - When using anchors, always remember to include the `.md` before the `#`. -- When using external links, especially to docs.microsoft.com (or msdn.microsoft.com for any older content), omit any language tag like "en-us" so that a reader in another language lands on a target page in that same language if it's available. +- When using external links, especially to Microsoft Learn, omit any language tag like "en-us" so that a reader in another language lands on a target page in that same language if it's available. - Bare URLs are not automatically converted into links. ### Inline HTML diff --git a/docs.sln b/docs.sln new file mode 100644 index 000000000..a90cea1da --- /dev/null +++ b/docs.sln @@ -0,0 +1,38 @@ + +Microsoft Visual Studio Solution File, Format Version 12.00 +# Visual Studio Version 18 +VisualStudioVersion = 18.3.11122.13 +MinimumVisualStudioVersion = 10.0.40219.1 +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "docs", "docs\docs.csproj", "{718966AB-D840-C99F-BC8C-757012BE68AA}" +EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{C2962E4E-20FC-4C00-858E-D0C62611CBFB}" + ProjectSection(SolutionItems) = preProject + .gitignore = .gitignore + .openpublishing.publish.config.json = .openpublishing.publish.config.json + .openpublishing.redirection.json = .openpublishing.redirection.json + CONTRIBUTING.md = CONTRIBUTING.md + global.json = global.json + LICENSE = LICENSE + LICENSE-CODE = LICENSE-CODE + README.md = README.md + ThirdPartyNotices = ThirdPartyNotices + EndProjectSection +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Any CPU = Debug|Any CPU + Release|Any CPU = Release|Any CPU + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {718966AB-D840-C99F-BC8C-757012BE68AA}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {718966AB-D840-C99F-BC8C-757012BE68AA}.Debug|Any CPU.Build.0 = Debug|Any CPU + {718966AB-D840-C99F-BC8C-757012BE68AA}.Release|Any CPU.ActiveCfg = Release|Any CPU + {718966AB-D840-C99F-BC8C-757012BE68AA}.Release|Any CPU.Build.0 = Release|Any CPU + EndGlobalSection + GlobalSection(SolutionProperties) = preSolution + HideSolutionNode = FALSE + EndGlobalSection + GlobalSection(ExtensibilityGlobals) = postSolution + SolutionGuid = {C4A337AF-69A4-496C-97FF-300C3489A718} + EndGlobalSection +EndGlobal diff --git a/docs/TOC.md b/docs/TOC.md index 51b9b9f47..a49bb6178 100644 --- a/docs/TOC.md +++ b/docs/TOC.md @@ -1,4 +1,3 @@ -# [Docs at a glance](index.md) # [What is NuGet?](what-is-nuget.md) # Get started ## [Install NuGet client tools](install-nuget-client-tools.md) @@ -6,7 +5,7 @@ ## [Install and use a package (Visual Studio)](quickstart/install-and-use-a-package-in-visual-studio.md) ## [Install and use a package (Visual Studio for Mac)](quickstart/install-and-use-a-package-in-visual-studio-mac.md) ## [Create and publish a NET Standard package (dotnet CLI)](quickstart/create-and-publish-a-package-using-the-dotnet-cli.md) -## [Create and publish a NET Standard package (Visual Studio)](quickstart/create-and-publish-a-package-using-visual-studio.md) +## [Create and publish a NET NuGet package (Visual Studio)](quickstart/create-and-publish-a-package-using-visual-studio.md) ## [Create and publish a NET Framework package (Visual Studio)](quickstart/create-and-publish-a-package-using-visual-studio-net-framework.md) # Consume packages ## [Overview and workflow](consume-packages/overview-and-workflow.md) @@ -18,55 +17,70 @@ ### [nuget.exe CLI](consume-packages/install-use-packages-nuget-cli.md) ### [Package Manager Console (PowerShell)](consume-packages/install-use-packages-powershell.md) ## Configure NuGet +### [Visual Studio options](consume-packages/nuget-visual-studio-options.md) +### [NuGet HTTPS Everywhere](consume-packages/nuget-https-everywhere.md) ### Package restore options #### [Restore packages](consume-packages/package-restore.md) #### [Troubleshooting](consume-packages/package-restore-troubleshooting.md) +### [Package source mapping](consume-packages/package-source-mapping.md) ### [Reinstall and update packages](consume-packages/reinstalling-and-updating-packages.md) ### [Manage global packages and cache folders](consume-packages/managing-the-global-packages-and-cache-folders.md) ### [Manage package trust boundaries](consume-packages/installing-signed-packages.md) +### [Work with authenticated Feeds](consume-packages/consuming-packages-authenticated-feeds.md) ### [Work with source control systems](consume-packages/packages-and-source-control.md) ### [Common NuGet configurations](consume-packages/configuring-nuget-behavior.md) +### [PackageDownload functionality](consume-packages/packagedownload-functionality.md) ## Reference packages in your project -### [Package references in project files](consume-packages/package-references-in-project-files.md) +### [PackageReference in project files](consume-packages/package-references-in-project-files.md) ### [Migrate packages.config to PackageReference](consume-packages/migrate-packages-config-to-package-reference.md) ### [packages.config](reference/packages-config.md) +### [Central Package Management](consume-packages/Central-Package-Management.md) # Create packages ## [Overview and workflow](create-packages/overview-and-workflow.md) ## [Create a package (dotnet CLI)](create-packages/creating-a-package-dotnet-cli.md) ## [Create a package (nuget.exe CLI)](create-packages/creating-a-package.md) ## [Create a package (MSBuild)](create-packages/creating-a-package-msbuild.md) -## [Support multiple target frameworks in your project file](create-packages/multiple-target-frameworks-project-file.md) +## [Package authoring best practices](create-packages/Package-authoring-best-practices.md) ## [Build a prerelease package](create-packages/prerelease-packages.md) ## [Create a symbol package](create-packages/symbol-packages-snupkg.md) +## [Support multiple target frameworks in your project file](create-packages/multiple-target-frameworks-project-file.md) ## Advanced tasks ### [Support multiple target frameworks](create-packages/supporting-multiple-target-frameworks.md) ### [Modify source code and config files](create-packages/source-and-config-file-transformations.md) ### [Select assemblies referenced by projects](create-packages/select-assemblies-referenced-by-projects.md) ### [Set package type](create-packages/set-package-type.md) ### [Create a localized package](create-packages/creating-localized-packages.md) +### [.NET Packages containing native libraries](create-packages/native-files-in-net-packages.md) ## Guides for specific content -### [Create a UWP package](guides/create-uwp-packages.md) +### [Create a UWP package (C++)](guides/create-uwp-packages.md) +### [Create a UWP package (C#)](guides/create-uwp-packages-CS.md) ### [Create a native package](guides/native-packages.md) ### [Create UI controls as a NuGet package](guides/create-UI-controls.md) ### [Create an analyzer as a NuGet package](guides/analyzers-conventions.md) -### [Create a package for Xamarin with Visual Studio 2015](guides/create-packages-for-xamarin.md) ### [Create a package with COM interop assemblies](create-packages/author-packages-with-COM-interop-assemblies.md) ## Sign packages ### [Sign a package](create-packages/sign-a-package.md) -### [Signed package signatures and requirements](reference/signed-packages-reference.md) +### [Signed-package signatures and requirements](reference/signed-packages-reference.md) +### [Signed-package verification options](reference/Signed-Package-Verification-Options.md) # Publish packages ## Publish to NuGet.org ### [Publish a package](nuget-org/publish-a-package.md) ### [API keys](nuget-org/scoped-api-keys.md) ## Publish to a private feed ### [Overview](hosting-packages/overview.md) -### [Azure artifacts](/azure/devops/artifacts/nuget/publish?view=azure-devops) +### [Azure artifacts](/azure/devops/artifacts/nuget/publish) ### [NuGet.Server](hosting-packages/nuget-server.md) ### [Local feeds](hosting-packages/local-feeds.md) # Concepts ## [Package installation process](concepts/package-installation-process.md) ## [Package versioning](concepts/package-versioning.md) ## [Dependency resolution](concepts/dependency-resolution.md) +## [Auditing package dependencies for security vulnerabilities](concepts/Auditing-Packages.md) +## [Best practices for a secure software supply chain](concepts/Security-Best-Practices.md) +## [MSBuild .props and .targets](concepts/MSBuild-props-and-targets.md) +## [Troubleshooting Installed Packages](concepts/troubleshooting-installed-packages.md) +## [MCP servers in NuGet packages](concepts/nuget-mcp.md) +## [Configuring the NuGet MCP Server](concepts/NuGet-MCP-Server.md) # Reference ## [.nuspec](reference/nuspec.md) ## [nuget.config file](reference/nuget-config-file.md) @@ -86,6 +100,7 @@ ### [pack](reference/cli-reference/cli-ref-pack.md) ### [push](reference/cli-reference/cli-ref-push.md) ### [restore](reference/cli-reference/cli-ref-restore.md) +### [search](reference/cli-reference/cli-ref-search.md) ### [setapikey](reference/cli-reference/cli-ref-setapikey.md) ### [sign](reference/cli-reference/cli-ref-sign.md) ### [sources](reference/cli-reference/cli-ref-sources.md) @@ -107,6 +122,7 @@ ### [Update-Package](reference/ps-reference/ps-ref-update-package.md) ## NuGet Server API ### [Overview](api/overview.md) +### [Server Implementation Guide](api/implementation-guide.md) ### Resources #### [Autocomplete](api/search-autocomplete-service-resource.md) #### [Catalog](api/catalog-resource.md) @@ -115,20 +131,33 @@ #### [Package metadata](api/registration-base-url-resource.md) #### [Push and delete](api/package-publish-resource.md) #### [Push symbol packages](api/symbol-package-publish-resource.md) +#### [README URI](api/readme-template-resource.md) #### [Report abuse URL](api/report-abuse-resource.md) #### [Repository signatures](api/repository-signatures-resource.md) #### [Search](api/search-query-service-resource.md) #### [Service index](api/service-index.md) +#### [Vulnerability info](api/vulnerability-info.md) ### [How-to: query for all packages using the API](guides/api/query-for-all-published-packages.md) ### [Rate limits](api/rate-limits.md) ### [nuget.org protocols](api/nuget-protocols.md) ### [tools.json](api/tools-json.md) -## [NuGet client SDK](reference/nuget-client-sdk.md) +## [NuGet Client SDK](reference/nuget-client-sdk.md) ## [Errors and Warnings](reference/Errors-and-Warnings.md) ### [NU1000](reference/errors-and-warnings/NU1000.md) ### [NU1001](reference/errors-and-warnings/NU1001.md) ### [NU1002](reference/errors-and-warnings/NU1002.md) ### [NU1003](reference/errors-and-warnings/NU1003.md) +### [NU1004](reference/errors-and-warnings/NU1004.md) +### [NU1005](reference/errors-and-warnings/NU1005.md) +### [NU1006](reference/errors-and-warnings/NU1006.md) +### [NU1007](reference/errors-and-warnings/NU1007.md) +### [NU1008](reference/errors-and-warnings/NU1008.md) +### [NU1009](reference/errors-and-warnings/NU1009.md) +### [NU1010](reference/errors-and-warnings/NU1010.md) +### [NU1011](reference/errors-and-warnings/NU1011.md) +### [NU1012](reference/errors-and-warnings/NU1012.md) +### [NU1014](reference/errors-and-warnings/NU1014.md) +### [NU1015](reference/errors-and-warnings/NU1015.md) ### [NU1100](reference/errors-and-warnings/NU1100.md) ### [NU1101](reference/errors-and-warnings/NU1101.md) ### [NU1102](reference/errors-and-warnings/NU1102.md) @@ -138,14 +167,32 @@ ### [NU1106](reference/errors-and-warnings/NU1106.md) ### [NU1107](reference/errors-and-warnings/NU1107.md) ### [NU1108](reference/errors-and-warnings/NU1108.md) +### [NU1109](reference/errors-and-warnings/NU1109.md) +### [NU1110](reference/errors-and-warnings/NU1110.md) ### [NU1201](reference/errors-and-warnings/NU1201.md) ### [NU1202](reference/errors-and-warnings/NU1202.md) ### [NU1203](reference/errors-and-warnings/NU1203.md) +### [NU1204](reference/errors-and-warnings/NU1204.md) +### [NU1211](reference/errors-and-warnings/NU1211.md) +### [NU1212](reference/errors-and-warnings/NU1212.md) +### [NU1213](reference/errors-and-warnings/NU1213.md) +### [NU1301](reference/errors-and-warnings/NU1301.md) +### [NU1302](reference/errors-and-warnings/NU1302.md) ### [NU1401](reference/errors-and-warnings/NU1401.md) +### [NU1402](reference/errors-and-warnings/NU1402.md) +### [NU1403](reference/errors-and-warnings/NU1403.md) ### [NU1500](reference/errors-and-warnings/NU1500.md) ### [NU1501](reference/errors-and-warnings/NU1501.md) ### [NU1502](reference/errors-and-warnings/NU1502.md) ### [NU1503](reference/errors-and-warnings/NU1503.md) +### [NU1504](reference/errors-and-warnings/NU1504.md) +### [NU1505](reference/errors-and-warnings/NU1505.md) +### [NU1506](reference/errors-and-warnings/NU1506.md) +### [NU1507](reference/errors-and-warnings/NU1507.md) +### [NU1508](reference/errors-and-warnings/NU1508.md) +### [NU1509](reference/errors-and-warnings/NU1509.md) +### [NU1510](reference/errors-and-warnings/NU1510.md) +### [NU1511](reference/errors-and-warnings/NU1511.md) ### [NU1601](reference/errors-and-warnings/NU1601.md) ### [NU1602](reference/errors-and-warnings/NU1602.md) ### [NU1603](reference/errors-and-warnings/NU1603.md) @@ -153,7 +200,17 @@ ### [NU1605](reference/errors-and-warnings/NU1605.md) ### [NU1608](reference/errors-and-warnings/NU1608.md) ### [NU1701](reference/errors-and-warnings/NU1701.md) +### [NU1702](reference/errors-and-warnings/NU1702.md) +### [NU1703](reference/errors-and-warnings/NU1703.md) +### [NU1900](reference/errors-and-warnings/NU1900.md) +### [NU1901](reference/errors-and-warnings/NU1901-NU1904.md) +### [NU1902](reference/errors-and-warnings/NU1901-NU1904.md) +### [NU1903](reference/errors-and-warnings/NU1901-NU1904.md) +### [NU1904](reference/errors-and-warnings/NU1901-NU1904.md) +### [NU1905](reference/errors-and-warnings/NU1905.md) ### [NU1801](reference/errors-and-warnings/NU1801.md) +### [NU1802](reference/errors-and-warnings/NU1802.md) +### [NU1803](reference/errors-and-warnings/NU1803.md) ### [NU3000](reference/errors-and-warnings/NU3000.md) ### [NU3001](reference/errors-and-warnings/NU3001.md) ### [NU3002](reference/errors-and-warnings/NU3002.md) @@ -194,6 +251,8 @@ ### [NU3037](reference/errors-and-warnings/NU3037.md) ### [NU3038](reference/errors-and-warnings/NU3038.md) ### [NU3040](reference/errors-and-warnings/NU3040.md) +### [NU3042](reference/errors-and-warnings/NU3042.md) +### [NU3043](reference/errors-and-warnings/NU3043.md) ### [NU5000](reference/errors-and-warnings/NU5000.md) ### [NU5001](reference/errors-and-warnings/NU5001.md) ### [NU5002](reference/errors-and-warnings/NU5002.md) @@ -231,9 +290,12 @@ ### [NU5035](reference/errors-and-warnings/NU5035.md) ### [NU5036](reference/errors-and-warnings/NU5036.md) ### [NU5037](reference/errors-and-warnings/NU5037.md) +### [NU5042](reference/errors-and-warnings/NU5042.md) +### [NU5045](reference/errors-and-warnings/NU5045.md) ### [NU5046](reference/errors-and-warnings/NU5046.md) ### [NU5047](reference/errors-and-warnings/NU5047.md) ### [NU5048](reference/errors-and-warnings/NU5048.md) +### [NU5049](reference/errors-and-warnings/NU5049.md) ### [NU5100](reference/errors-and-warnings/NU5100.md) ### [NU5101](reference/errors-and-warnings/NU5101.md) ### [NU5102](reference/errors-and-warnings/NU5102.md) @@ -259,12 +321,14 @@ ### [NU5123](reference/errors-and-warnings/NU5123.md) ### [NU5124](reference/errors-and-warnings/NU5124.md) ### [NU5125](reference/errors-and-warnings/NU5125.md) +### [NU5126](reference/errors-and-warnings/NU5126.md) ### [NU5127](reference/errors-and-warnings/NU5127.md) ### [NU5128](reference/errors-and-warnings/NU5128.md) -### [NU5128](reference/errors-and-warnings/NU5129.md) +### [NU5129](reference/errors-and-warnings/NU5129.md) ### [NU5130](reference/errors-and-warnings/NU5130.md) ### [NU5131](reference/errors-and-warnings/NU5131.md) ### [NU5500](reference/errors-and-warnings/NU5500.md) +### [NU5501](reference/errors-and-warnings/NU5501.md) ## Archived content ### [project.json management format](archive/project-json.md) ### [project.json and UWP](archive/project-json-and-uwp.md) @@ -286,7 +350,32 @@ ### [NuGet.org policies](nuget-org/policies/data-requests.md) ## Release notes ### [Known Issues](release-notes/known-issues.md) + +### NuGet 6.x +#### [NuGet 6.14](release-notes/NuGet-6.14.md) +#### [NuGet 6.13](release-notes/NuGet-6.13.md) +#### [NuGet 6.12](release-notes/NuGet-6.12.md) +#### [NuGet 6.11](release-notes/NuGet-6.11.md) +#### [NuGet 6.10](release-notes/NuGet-6.10.md) +#### [NuGet 6.9](release-notes/NuGet-6.9.md) +#### [NuGet 6.8](release-notes/NuGet-6.8.md) +#### [NuGet 6.7](release-notes/NuGet-6.7.md) +#### [NuGet 6.6](release-notes/NuGet-6.6.md) +#### [NuGet 6.5](release-notes/NuGet-6.5.md) +#### [NuGet 6.4](release-notes/NuGet-6.4.md) +#### [NuGet 6.3](release-notes/NuGet-6.3.md) +#### [NuGet 6.2](release-notes/NuGet-6.2.md) +#### [NuGet 6.1](release-notes/NuGet-6.1.md) +#### [NuGet 6.0](release-notes/NuGet-6.0.md) ### NuGet 5.x +#### [NuGet 5.11](release-notes/NuGet-5.11.md) +#### [NuGet 5.10](release-notes/NuGet-5.10.md) +#### [NuGet 5.9](release-notes/NuGet-5.9.md) +#### [NuGet 5.8](release-notes/NuGet-5.8.md) +#### [NuGet 5.7](release-notes/NuGet-5.7.md) +#### [NuGet 5.6](release-notes/NuGet-5.6.md) +#### [NuGet 5.5](release-notes/NuGet-5.5.md) +#### [NuGet 5.4](release-notes/NuGet-5.4.md) #### [NuGet 5.3](release-notes/NuGet-5.3.md) #### [NuGet 5.2](release-notes/NuGet-5.2-RTM.md) #### [NuGet 5.1](release-notes/NuGet-5.1-RTM.md) @@ -353,6 +442,6 @@ #### [NuGet 1.3](release-notes/NuGet-1.3.md) #### [NuGet 1.2](release-notes/NuGet-1.2.md) #### [NuGet 1.1](release-notes/NuGet-1.1.md) -## [FAQs](resources/nuget-faq.md) +## [FAQs](resources/nuget-faq.yml) ## [Project format](resources/check-project-format.md) # [NuGet.org](nuget-org/overview-nuget-org.md) diff --git a/docs/api/NuGet-Protocols.md b/docs/api/NuGet-Protocols.md index c64921739..ab00ae0cd 100644 --- a/docs/api/NuGet-Protocols.md +++ b/docs/api/NuGet-Protocols.md @@ -3,8 +3,8 @@ title: nuget.org Protocols description: The evolving nuget.org protocols to interact with NuGet clients. author: anangaur ms.author: anangaur -ms.date: 10/30/2017 -ms.topic: conceptual +ms.date: 01/21/2021 +ms.topic: article ms.reviewer: kraigb --- @@ -37,7 +37,9 @@ be used to validate that the package belongs to a particular user (account) on n Clients are required to pass the following header when they make API calls to **push** packages to nuget.org: - X-NuGet-Protocol-Version: 4.1.0 +``` +X-NuGet-Protocol-Version: 4.1.0 +``` Note that the `X-NuGet-Client-Version` header has similar semantics but is reserved to only be used by the official NuGet client. Third party clients should use the `X-NuGet-Protocol-Version` header and value. @@ -52,7 +54,9 @@ If a client interacts with external services and needs to validate whether a pac This API is used to get a verify-scope key for a nuget.org author to validate a package owned by him/her. - POST api/v2/package/create-verification-key/{ID}/{VERSION} +``` +POST api/v2/package/create-verification-key/{ID}/{VERSION} +``` #### Request parameters @@ -75,7 +79,9 @@ X-NuGet-ApiKey | Header | string | yes | For example, `X-NuGet-ApiKey: {USE This API is used to validate a verify-scope key for package owned by the nuget.org author. - GET api/v2/verifykey/{ID}/{VERSION} +``` +GET api/v2/verifykey/{ID}/{VERSION} +``` #### Request parameters diff --git a/docs/api/_data/catalog-package-details.json b/docs/api/_data/catalog-package-details.json index 5cf343fed..f5cdc865e 100644 --- a/docs/api/_data/catalog-package-details.json +++ b/docs/api/_data/catalog-package-details.json @@ -28,6 +28,13 @@ "packageHash": "2edCwKLcbcgFJpsAwa883BLtOy8bZpWwbQpiIb71E74k5t2f2WzXEGWbPwntRleUEgSrcxJrh9Orm/TAmgO4NQ==", "packageHashAlgorithm": "SHA512", "packageSize": 118348, + "packageTypes": [ + { + "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#packagetypes/DotnetTool", + "@type": "PackageType", + "name": "DotnetTool" + } + ], "projectUrl": "https://github.com/NuGet/NuGetGallery", "published": "1900-01-01T00:00:00Z", "requireLicenseAcceptance": false, @@ -65,5 +72,13 @@ "V3", "Protocol", "Example" + ], + "vulnerabilities": [ + { + "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json#vulnerability/GitHub/999", + "@type": "Vulnerability", + "advisoryUrl": "https://github.com/advisories/ABCD-1234-5678-9012", + "severity": "2" + } ] } diff --git a/docs/api/_data/package-registration-index.json b/docs/api/_data/package-registration-index.json index 59d3ae709..641dfcfa1 100644 --- a/docs/api/_data/package-registration-index.json +++ b/docs/api/_data/package-registration-index.json @@ -2,11 +2,11 @@ "count": 1, "items": [ { - "@id": "https://api.nuget.org/v3/registration3/nuget.server.core/index.json#page/3.0.0-beta/3.0.0-beta", + "@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json#page/3.0.0-beta/3.0.0-beta", "count": 1, "items": [ { - "@id": "https://api.nuget.org/v3/registration3/nuget.server.core/3.0.0-beta.json", + "@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/3.0.0-beta.json", "catalogEntry": { "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json", "authors": ".NET Foundation", @@ -18,7 +18,7 @@ "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup/nuget.core", "id": "NuGet.Core", "range": "[2.14.0, )", - "registration": "https://api.nuget.org/v3/registration3/nuget.core/index.json" + "registration": "https://api.nuget.org/v3/registration-sample/nuget.core/index.json" } ] } @@ -37,10 +37,16 @@ "summary": "", "tags": [ "" ], "title": "", - "version": "3.0.0-beta" + "version": "3.0.0-beta", + "vulnerabilities": [ + { + "advisoryUrl": "https://github.com/advisories/ABCD-1234-5678-9012", + "severity": "2" + } + ] }, "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg", - "registration": "https://api.nuget.org/v3/registration3/nuget.server.core/index.json" + "registration": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json" } ], "lower": "3.0.0-beta", diff --git a/docs/api/_data/package-registration-leaf.json b/docs/api/_data/package-registration-leaf.json index 7eac0c826..ebcc2d92e 100644 --- a/docs/api/_data/package-registration-leaf.json +++ b/docs/api/_data/package-registration-leaf.json @@ -1,8 +1,8 @@ { - "@id": "https://api.nuget.org/v3/registration3/nuget.versioning/4.3.0.json", + "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json", "catalogEntry": "https://api.nuget.org/v3/catalog0/data/2017.08.11.18.24.22/nuget.versioning.4.3.0.json", "listed": true, "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.versioning/4.3.0/nuget.versioning.4.3.0.nupkg", "published": "2017-08-11T18:24:14.36+00:00", - "registration": "https://api.nuget.org/v3/registration3/nuget.versioning/index.json" + "registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json" } \ No newline at end of file diff --git a/docs/api/_data/package-registration-page.json b/docs/api/_data/package-registration-page.json index 77fd6726f..3ca362518 100644 --- a/docs/api/_data/package-registration-page.json +++ b/docs/api/_data/package-registration-page.json @@ -1,11 +1,11 @@ { "count": 2, "lower": "1.0.531", - "parent": "https://api.nuget.org/v3/registration3/nuget.protocol.v3.example/index.json", + "parent": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json", "upper": "1.0.729-unstable", "items": [ { - "@id": "https://api.nuget.org/v3/registration3/nuget.protocol.v3.example/1.0.531.json", + "@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.531.json", "@type": "Package", "commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1", "commitTimeStamp": "2017-10-26T14:12:19.3439088Z", @@ -25,10 +25,10 @@ "version": "1.0.531" }, "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg", - "registration": "https://api.nuget.org/v3/registration3/nuget.protocol.v3.example/index.json" + "registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json" }, { - "@id": "https://api.nuget.org/v3/registration3/nuget.protocol.v3.example/1.0.729-unstable.json", + "@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.729-unstable.json", "@type": "Package", "commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1", "commitTimeStamp": "2017-10-26T14:12:19.3439088Z", @@ -38,7 +38,7 @@ "authors": "NuGet.org Team", "deprecation": { "reasons": [ - "HasCriticalBugs" + "CriticalBugs" ], "message": "This package is unstable and broken!", "alternatePackage": { @@ -59,7 +59,7 @@ "version": "1.0.729-Unstable" }, "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg", - "registration": "https://api.nuget.org/v3/registration3/nuget.protocol.v3.example/index.json" + "registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json" } ] } diff --git a/docs/api/_data/repository-signatures-index.json b/docs/api/_data/repository-signatures-index.json index 5f8ccc84d..b80fc8d76 100644 --- a/docs/api/_data/repository-signatures-index.json +++ b/docs/api/_data/repository-signatures-index.json @@ -1,5 +1,5 @@ { - "allRepositorySigned": false, + "allRepositorySigned": true, "signingCertificates": [ { "fingerprints": { @@ -10,6 +10,26 @@ "notBefore": "2018-04-10T00:00:00.0000000Z", "notAfter": "2021-04-14T12:00:00.0000000Z", "contentUrl": "https://api.nuget.org/v3-index/repository-signatures/certificates/0e5f38f57dc1bcc806d8494f4f90fbcedd988b46760709cbeec6f4219aa6157d.crt" + }, + { + "fingerprints": { + "2.16.840.1.101.3.4.2.1": "5a2901d6ada3d18260b9c6dfe2133c95d74b9eef6ae0e5dc334c8454d1477df4" + }, + "subject": "CN=NuGet.org Repository by Microsoft, O=NuGet.org Repository by Microsoft, L=Redmond, S=Washington, C=US", + "issuer": "CN=DigiCert SHA2 Assured ID Code Signing CA, OU=www.digicert.com, O=DigiCert Inc, C=US", + "notBefore": "2021-02-16T00:00:00.0000000Z", + "notAfter": "2024-05-15T23:59:59.0000000Z", + "contentUrl": "https://api.nuget.org/v3-index/repository-signatures/certificates/5a2901d6ada3d18260b9c6dfe2133c95d74b9eef6ae0e5dc334c8454d1477df4.crt" + }, + { + "fingerprints": { + "2.16.840.1.101.3.4.2.1": "1f4b311d9acc115c8dc8018b5a49e00fce6da8e2855f9f014ca6f34570bc482d" + }, + "subject": "CN=NuGet.org Repository by Microsoft, O=NuGet.org Repository by Microsoft, L=Redmond, S=Washington, C=US", + "issuer": "CN=DigiCert Trusted G4 Code Signing RSA4096 SHA384 2021 CA1, O=\"DigiCert, Inc.\", C=US", + "notBefore": "2024-02-23T00:00:00.0000000Z", + "notAfter": "2027-05-18T23:59:59.0000000Z", + "contentUrl": "https://api.nuget.org/v3-index/repository-signatures/certificates/1f4b311d9acc115c8dc8018b5a49e00fce6da8e2855f9f014ca6f34570bc482d.crt" } ] } \ No newline at end of file diff --git a/docs/api/_data/search-result.json b/docs/api/_data/search-result.json index 32f675558..b58fbdaa4 100644 --- a/docs/api/_data/search-result.json +++ b/docs/api/_data/search-result.json @@ -2,7 +2,7 @@ "totalHits": 2, "data": [ { - "registration": "https://api.nuget.org/v3/registration3/nuget.versioning/index.json", + "registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json", "id": "NuGet.Versioning", "version": "4.4.0", "description": "NuGet's implementation of Semantic Versioning.", @@ -13,33 +13,38 @@ "authors": [ "NuGet" ], "totalDownloads": 141896, "verified": true, + "packageTypes": [ + { + "name": "Dependency" + } + ], "versions": [ { "version": "3.3.0", "downloads": 50343, - "@id": "https://api.nuget.org/v3/registration3/nuget.versioning/3.3.0.json" + "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.3.0.json" }, { "version": "3.4.3", "downloads": 27932, - "@id": "https://api.nuget.org/v3/registration3/nuget.versioning/3.4.3.json" + "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/3.4.3.json" }, { "version": "4.0.0", "downloads": 63004, - "@id": "https://api.nuget.org/v3/registration3/nuget.versioning/4.0.0.json" + "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.0.0.json" }, { "version": "4.4.0", "downloads": 617, - "@id": "https://api.nuget.org/v3/registration3/nuget.versioning/4.4.0.json" + "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.4.0.json" } ] }, { - "@id": "https://api.nuget.org/v3/registration3/nerdbank.gitversioning/index.json", + "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json", "@type": "Package", - "registration": "https://api.nuget.org/v3/registration3/nerdbank.gitversioning/index.json", + "registration": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/index.json", "id": "Nerdbank.GitVersioning", "version": "2.0.41", "description": "Stamps your assemblies with semver 2.0 compliant git commit specific version information and provides NuGet versioning information as well.", @@ -55,12 +60,12 @@ { "version": "1.6.35", "downloads": 10229, - "@id": "https://api.nuget.org/v3/registration3/nerdbank.gitversioning/1.6.35.json" + "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/1.6.35.json" }, { "version": "2.0.41", "downloads": 1677, - "@id": "https://api.nuget.org/v3/registration3/nerdbank.gitversioning/2.0.41.json" + "@id": "https://api.nuget.org/v3/registration-sample/nerdbank.gitversioning/2.0.41.json" } ] } diff --git a/docs/api/catalog-resource.md b/docs/api/catalog-resource.md index 6f78b826e..e9a347be3 100644 --- a/docs/api/catalog-resource.md +++ b/docs/api/catalog-resource.md @@ -59,7 +59,9 @@ Catalog items are always added to the catalog in a monotonically increasing, chr The following request fetches the catalog index. - GET {@id} +``` +GET {@id} +``` The catalog index is a JSON document that contains an object with the following properties: @@ -96,7 +98,9 @@ URL. ### Sample request - GET https://api.nuget.org/v3/catalog0/index.json +``` +GET https://api.nuget.org/v3/catalog0/index.json +``` ### Sample response @@ -158,7 +162,9 @@ For more details about what each type means, see the [corresponding items type]( ### Sample request - GET https://api.nuget.org/v3/catalog0/page2926.json +``` +GET https://api.nuget.org/v3/catalog0/page2926.json +``` ### Sample response @@ -196,9 +202,12 @@ version combination). A package details catalog item is produced when a package following scenarios: 1. A package is **pushed**. -1. A package is **listed**. +1. A package is **relisted**. 1. A package is **unlisted**. +1. A package is **deprecated**. +1. A package is **undeprecated**. 1. A package is **reflowed**. +1. A package's **vulnerability status** is updated. A package reflow is an administrative gesture that essentially generates a fake push of an existing package with no changes to the package itself. On nuget.org, a reflow is used after fixing a bug in one of the background jobs @@ -227,6 +236,7 @@ minClientVersion | string | no | packageHash | string | yes | The hash of the package, encoding using [standard base 64](https://tools.ietf.org/html/rfc4648#section-4) packageHashAlgorithm | string | yes | packageSize | integer | yes | The size of the package .nupkg in bytes +packageTypes | array of objects | no | The package types specified by the author. projectUrl | string | no | releaseNotes | string | no | requireLicenseAgreement | boolean | no | Assume `false` if excluded @@ -234,6 +244,7 @@ summary | string | no | tags | array of strings | no | title | string | no | verbatimVersion | string | no | The version string as it's originally found in the .nuspec +vulnerabilities | array of objects | no | The security vulnerabilities of the package The package `version` property is the full version string after normalization. This means that SemVer 2.0.0 build data can be included here. @@ -244,14 +255,34 @@ time before the catalog item's commit timestamp. The `packageHashAlgorithm` is a string defined by the server implementation representing the hashing algorithm used to produce the `packageHash`. nuget.org always used the `packageHashAlgorithm` value of `SHA512`. +The `packageTypes` property will only be present if a package type was specified by the author. If it is present, it will always have at least one (1) entry. Each item in the `packageTypes` array is a JSON object with the following properties: + +Name | Type | Required | Notes +--------- | ------- | -------- | ----- +name | string | yes | The name of the package type. +version | string | no | The version of the package type. Only present if the author explicitly specified a version in the nuspec. + The `published` timestamp is the time when the package was last listed. > [!Note] > On nuget.org, the `published` value is set to the year 1900 when the package is unlisted. +#### Vulnerabilities + +An array of `vulnerability` objects. Each vulnerability has the following properties: + +Name | Type | Required | Notes +------------ | ------ | -------- | ----- +advisoryUrl | string | yes | Location of security advisory for the package +severity | string | yes | Severity of advisory: "0" = Low, "1" = Moderate, "2" = High, "3" = Critical + +If the `severity` property contains values other than those listed here, the severity of the advisory is to be treated as Low. + #### Sample request +``` GET https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json +``` #### Sample response @@ -279,7 +310,9 @@ item's commit timestamp. #### Sample request +``` GET https://api.nuget.org/v3/catalog0/data/2017.11.02.00.40.00/netstandard1.4_lib.1.0.0-test.json +``` #### Sample response diff --git a/docs/api/implementation-guide.md b/docs/api/implementation-guide.md new file mode 100644 index 000000000..6bc08aa28 --- /dev/null +++ b/docs/api/implementation-guide.md @@ -0,0 +1,153 @@ +--- +title: NuGet Server Implementation Guide +description: Guidelines and recommendations to anyone implementing the NuGet Server API in their own package repository +author: zivkan +ms.author: zivkan +ms.date: 07/29/2023 +ms.topic: article +--- + +# NuGet Server Implementation Guide + +In some cases, you may want to implement your own NuGet package feed. +Many [existing implementations exist](../hosting-packages/Overview.md) which allow you to host your own feed in a variety way, but the protocol between the official NuGet client software and a package feed is documented allowing you to build your own feed implementation from scratch. + +The protocol does evolve over time and this guide is aimed at those that wish to or already have implemented a NuGet package server. + +Since the initial release of the NuGet V3 protocol in 2015, NuGet has evolved to provide developers with a richer experience, and this requires package repositories to do additional work in order to provide the additional value their package consumers, beyond simply exacting metadata from hosted packages and returning the metadata in various forms. +For example, the search and package metadata endpoints contain more than just metadata found in the nupkg's nuspec file. + +Note that this guide is focused on the NuGet V3 protocol since the V2 protocol is essentially undocumented and, since 2015, the recommended protocol for NuGet client and server communication is the V3 protocol. For more information read about protocol versioning. + +## Chronology + +To assist authors of existing NuGet repositories keep up to date with NuGet's newest features, here is the chronology of the relevant features mentioned in the remainder of the document. + +|Year|Feature| +|--|--| +|2013|[A blog post explaining how to manage package owners on nuget.org](https://devblogs.microsoft.com/nuget/managing-package-owners/) clarified the owners shown on the website are the accounts that have permission to upload new versions, and therefore [the `owners` metadata in the package is ignored](#owner-field)| +|2017|[Added `verified` to `SearchQueryService` responses.](#verified-search-response-field)| +||[Semantic Versioning 2.0.0 support](#semantic-versioning-200-support) +|2018|[Embedded licenses](#embedded-files)| +|2019|[Embedded icons](#embedded-files)| +||[Package deprecation in `RegistrationBaseUrl` (package metadata resource)](#known-vulnerability-and-deprecation-data)| +|2020|[Package vulnerability information in `RegistrationsBaseUrl` (package metadata resource)](#known-vulnerability-and-deprecation-data)| +||Added `packageTypes` query parameter to `SearchQueryService` requests| +|2021|[Embedded readme](#embedded-files)| +|2023|[PreAuthenticate authenticated requests](#url-structure-for-authenticated-feeds)
[`VulnerabilityInfo` resource](#known-vulnerabilities-database-vulnerabilityinfo)| +|2025|[Enable embedded README downloads](#enable-embedded-readme-downloads)| + +## Owner field + +Consider two of the [package manifest file (`.nuspec`)](../reference/nuspec.md) fields, `` and ``. +Package authors who are packaging third-party content often put the third-party name in the `` field. +The `` field was intended to denote who published the package on a repository, and therefore who should be contacted in case of packing issues or questions. + +This was explained in [a blog post from 2013](https://devblogs.microsoft.com/nuget/managing-package-owners/), so the `` field is considered deprecated in the `.nuspec` file. +If package's manifest contain this metadata, it should be ignored. +Do not return the value of the `.nuspec` file's `` field in the `owners` property in the [search resource](./search-query-service-resource.md) or [package metadata resource](./registration-base-url-resource.md) JSON response. + +If your repository has per-package permissions, it is recommended to report the accounts that have permissions to publish new versions in the `owner` metadata for search and package metadata resources JSON responses. + +## `verified` search response field + +Visual Studio's Package Manager UI shows a blue checkmark next to packages in [search service](./search-query-service-resource.md) results, when a new field `verified` is set to `true`. + +NuGet.org uses this with package prefix data (server side data, not part of the NuGet API), so that this checkmark is only shown to customers when the account that owns the package uploaded the package. +For example, any package with prefix `microsoft.*` is verified only when the package is owned by [the Microsoft account on nuget.org](https://www.nuget.org/profiles/Microsoft). +Anyone who uploaded a package with package id starting with `microsoft.` before reserved prefixes were implemented, will not have this verified checkmark. +NuGet.org also allows prefixes not to be exclusive, so that anyone can upload a package under `Contoso.ToolWithPlugins.Community.*`, but will not get a verified checkmark. + +## Semantic Versioning 2.0.0 support + +NuGet supports [a hybrid between `System.Version` and Semantic Version](../concepts/Package-Versioning.md#where-nugetversion-diverges-from-semantic-versioning), but support for Semantic Version 2.0.0 was added in 2017. +Therefore, NuGet API resources that return versions to client versions lower than 3.6.0 must not return packages that use Semantic 2.0.0 features that are incompatible with Semantic Versioning 1.0.0. + +The most important differences between the two versions are the pre-release labels, and metadata string. +The [Semantic Versioning 1.0.0 spec](https://semver.org/spec/v1.0.0.html) provides `[0-9A-Za-z-]` as a sample Regular Expression string for the only characters allowed as part of the pre-release label, and does not support metadata strings. +The [Semantic Versioning 2.0.0 spec](https://semver.org/spec/v2.0.0.html) allows pre-release identifiers to be separated by `.` characters (and forbids a numeric identifier from having a leading zero), and additionally allows build metadata to be added following a `+`. + +In the [package metadata resource (`RegistrationsBaseUrl`)](./registration-base-url-resource.md), resource versions below 3.6.0 must only return packages that comply with .NET's `System.Version` or Semantic Versioning 1.0.0. +This means packages whose versions are only compliant with Semantic Versioning 2.0.0 are invisible to these client versions. + +Similarly, the [search query service (`SearchQueryService`)](./search-query-service-resource.md) and [autocomplete service (`SearchAutocompleteService`)](./search-autocomplete-service-resource.md) added `&semVerLevel={version}` query parameters. +When `semVerLevel` is missing, assume the value `1.0.0`. +Like the package metadata resource, packages whose version is compatible only with Semantic Versioning 2.0.0 must not be returned when the `semVerLevel` value is below 2.0.0. + +## Embedded files + +Package [icons](../reference/nuspec.md#icon), [license](../reference/nuspec.md#license), and [readme](../reference/nuspec.md#readme) files can be (and are recommended to be) embedded in the package. +These files need a URL endpoint, either extracted and put on a static file server, or a URL that dynamically extracts the files from the `.nupkg` on request, so that they can be viewed without downloading the entire `nupkg`. +If your package repository provides package browsing and viewing package details, you can use the URLs to show customers the embedded content on your website. + +Finally, the [package metadata resource](./registration-base-url-resource.md) and [search resource](./search-query-service-resource.md) must contain the hosted URL in the `iconUrl`, `licenseUrl`, and/or `readmeUrl` properties of the JSON response. +Packages (`.nupkg` files) must not be modified, as client features (lock files and signed packages) will detect modifications as the package having been tampered with. + +Note that the license could be an SPDX expression, or an embedded file (but not both). +Packages that use a license expression, when represented in search and package metadata results, can have the `licenseUrl` set to the license expression, URL encoded, and appended to the end of https://licenses.nuget.org/. +For example, https://licenses.nuget.org/Apache-2.0. +The NuGet.org server team have additional [documentation on licenses.nuget.org](../nuget-org/licenses.nuget.org.md). + +## Known vulnerability and deprecation data + +### Package Metadata Resource (`RegistrationsBaseUrl`) + +The [Package Metadata Resource](./registration-base-url-resource.md) can contain [deprecation](./registration-base-url-resource.md#package-deprecation) and [vulnerability](./registration-base-url-resource.md#vulnerabilities) information. +This allows customers browsing packages in Visual Studio's Package Manager User Interface, or equivalent in other IDEs, to be notified of important security or maintenance issues. + +If your package repository is "up-sourcing" packages from another repository, in order to mirror packages in your own feed, we recommend periodically checking the original source if there is deprecation or vulnerability data, and mirror that metadata in your own repository. +If your package repository is up-sourcing from nuget.org specifically, by keeping state of the last time you checked (a "cursor"), you can use [the `Catalog` resource](./catalog-resource.md) to efficiently check if there are any package updates for packages you're mirroring, without having to download a large number of package metadata JSON files from the upstream feed. +There is [a guide on using the catalog resource](../guides/api/query-for-all-published-packages.md) with sample code that can help you get started. + +### Known Vulnerabilities Database (`VulnerabilityInfo`) + +In order to provide high-performance vulnerability scanning during package restore, NuGet downloads the full list of known vulnerabilities from [the `VulnerabilityInfo` resource](./vulnerability-info.md). +Nuget.org provides vulnerability data for all GitHub reviewed advisories from the [GitHub Advisories database](https://github.com/advisories), which includes packages that are not hosted on nuget.org. + +If your package repository is hosting first-party packages, and you would like to provide vulnerability information to customers using your own feed, but don't yet have any disclosed package vulnerabilities, you should provide a [vulnerability index](./vulnerability-info.md#vulnerability-index) with one or more [vulnerability pages](./vulnerability-info.md#vulnerability-page) whose contents are an empty JSON array (`[]`). + +#### Reusing nuget.org's vulnerability data + +NuGet does not require that resources in the [service index](./service-index.md), or [the vulnerability index](./vulnerability-info.md#vulnerability-index), must be on the same server as the service index itself. +However, there are several reasons why some companies choose to block nuget.org at the firewall, or have on-prem feeds on a disconnected network. +To avoid connectivity issues, we recommend serving vulnerability data from your own web app, so that NuGet clients only make HTTP connections to the host the feed is installed on. + +✔️ DO cache or proxy the vulnerability pages in your own web app + +❌ DO NOT advertise api.nuget.org in your service index or vulnerability index without a configuration to turn this off. + +## `packageTypes` search query + +The .NET CLI allows searching for .NET tool packages with the `dotnet tool search` command. +This is implemented by adding a `&packageTypes={value}` query parameter to the [search query resource](./search-query-service-resource.md), that reads values from the package's `.nuspec` file `` field. + +## URL structure for authenticated feeds + +As described in [the overview of the NuGet API](./overview.md), the starting URL for all NuGet server communication is [the service index](./service-index.md). +This document contains the URLs for all other resources that NuGet clients will query. +As of NuGet 6.7 (Visual Studio & MSBuild 17.7, and .NET SDK 7.0.400), NuGet uses [.NET's `HttpClientHandler.PreAuthenticate`](/dotnet/api/system.net.http.httpclienthandler.preauthenticate), which only avoids anonymous HTTP requests when subsequent URLs are in the same virtual directory, or a subdirectory, of a URL that has previously been authenticated. +This will dramatically reduce the number of unauthenticated HTTP requests sent to the server, and therefore will reduce your server workload. + +Here are some examples: + +|URL|Will PreAuthenticate?| +|--|--| +|https://pkgs.contoso.com/nuget/v3/feed/index.json|N/A, this is the service index.| +|https://pkgs.contoso.com/nuget/v3/search|No, not in the same or sub-directory as the service index.| +|https://search.pkgs.contoso.com/nuget/v3/feed/|No, not on the same host name as the service index.| +|https://pkgs.contoso.com/nuget/v3/feed/search|Yes, in the same directory as the service index.| +|https://pkgs.contoso.com/nuget/v3/registration/|No, not in a subdirectory of the service index.| +|https://pkgs.contoso.com/nuget/v3/feed/registration/|Yes, in a subdirectory of the service index.| +|https://pkgs.contoso.com/nuget/v3/{guid}/registration/|See below| + +In the last example, the server might have a canonical (in this example a guid) name, and have one or more aliases. +If the service index request was authenticated on a non-canonical URL (the "friendly" name, in our example `feed`), then no, any requests to resources under the canonical URL will not match `HttpClientHandler`'s rules for `PreAuthenticate`. +However, if the non-canonical URL is an HTTP redirection to the canonical URL, https://pkgs.contoso.com/nuget/v3/{guid}/index.json, then this URL will be used in `HttpClientHandler`'s credential cache. +In this case, every request to the service index will have additional latency, due to the redirection. + +While NuGet's V3 API was designed to work on a static file server, the search resource is the exception that always requires a dynamic web service to process requests. +If you wish to host search, or indeed any other NuGet API resource, on different servers, in order to benefit from `HttpClientHandler`'s `PreAuthenticate`, you will need to use a reverse proxy to ensure all customer facing URLs in the service index meet the "same or subdirectory" rule. + +## Enable embedded README downloads + +A [new resource](./readme-template-resource.md) was documented for constructing a URL that can be used to download a README for a given package. This will allow client, like the Package Management UI in VS, to display the embedded README for packages which haven't been previously installed by the user. The client will construct this URL and attempt to download the README, using the response to the request to determine if a README is available. This means servers should expect multiple requests to the constructed endpoint as users navigate the PM UI. diff --git a/docs/api/overview.md b/docs/api/overview.md index 7201f6431..ecf2fd22c 100644 --- a/docs/api/overview.md +++ b/docs/api/overview.md @@ -20,6 +20,8 @@ Note in some cases, nuget.org has additional requirements that are not enforced For a simple enumeration and download of available nuget.exe versions, see the [tools.json](tools-json.md) endpoint. +If you are implementing a NuGet package repository, also see [the implementation guide](./implementation-guide.md) for additional requirements and recommendations. + ## Service index The entry point for the API is a JSON document in a well known location. This document is called the **service index**. The location of the service index for nuget.org is `https://api.nuget.org/v3/index.json`. @@ -59,12 +61,14 @@ Resource name | Required [PackageBaseAddress](package-base-address-resource.md) | yes | Get package content (.nupkg). [PackageDetailsUriTemplate](package-details-template-resource.md) | no | Construct a URL to access a package details web page. [PackagePublish](package-publish-resource.md) | yes | Push and delete (or unlist) packages. +[ReadmeUriTemplate](readme-template-resource.md) | no | Construct a URL to access a package's README. [RegistrationsBaseUrl](registration-base-url-resource.md) | yes | Get package metadata. [ReportAbuseUriTemplate](report-abuse-resource.md) | no | Construct a URL to access a report abuse web page. [RepositorySignatures](repository-signatures-resource.md) | no | Get certificates used for repository signing. [SearchAutocompleteService](search-autocomplete-service-resource.md) | no | Discover package IDs and versions by substring. [SearchQueryService](search-query-service-resource.md) | yes | Filter and search for packages by keyword. [SymbolPackagePublish](symbol-package-publish-resource.md) | no | Push symbol packages. +[VulnerabilityInfo](vulnerability-info.md) | no | Packages with known vulnerabilities. In general, all non-binary data returned by a API resource are serialized using JSON. The response schema returned by each resource in the service index is defined individually for that resource. For more information about diff --git a/docs/api/package-base-address-resource.md b/docs/api/package-base-address-resource.md index ee90b7c38..56416a5d6 100644 --- a/docs/api/package-base-address-resource.md +++ b/docs/api/package-base-address-resource.md @@ -28,22 +28,24 @@ PackageBaseAddress/3.0.0 | The initial release ## Base URL The base URL for the following APIs is the value of the `@id` property associated with the aforementioned -resource `@type` value. In the following document, the placeholder base URL `{@id}` will be used. +resource `@type` value. In the following document, the placeholder base URL `{@id}` will be used. The base URL may change based on implementation or infrastructure changes within the package source so it must be dynamically fetched from the [service index](service-index.md) by the client software. ## HTTP methods -All URLs found in the registration resource support the HTTP methods `GET` and `HEAD`. +All URLs found in the package content resource support the HTTP methods `GET` and `HEAD`. ## Enumerate package versions -If the client knows a package ID and wants to discover which package versions the package source has available, the -client can construct a predictable URL to enumerate all package versions. This list is meant to be a "directory -listing" for the package content API mentioned below. +If the client knows a package ID and wants to discover which package versions the package source has available, the client can construct a predictable URL to enumerate all package versions. +Every version listed in this list must be available for download. +This list is meant to be a "directory listing" for the package content API mentioned below. > [!Note] > This list contains both listed and unlisted package versions. - GET {@id}/{LOWER_ID}/index.json +``` +GET {@id}/{LOWER_ID}/index.json +``` ### Request parameters @@ -52,7 +54,7 @@ Name | In | Type | Required | Notes LOWER_ID | URL | string | yes | The package ID, lowercased The `LOWER_ID` value is the desired package ID lowercased using the rules implemented by .NET's -[`System.String.ToLowerInvariant()`](/dotnet/api/system.string.tolowerinvariant?view=netstandard-2.0#System_String_ToLowerInvariant) method. +[`System.String.ToLowerInvariant()`](/dotnet/api/system.string.tolowerinvariant?view=netstandard-2.0#System_String_ToLowerInvariant&preserve-view=true) method. ### Response @@ -74,7 +76,11 @@ in the following endpoints. ### Sample request - GET https://api.nuget.org/v3-flatcontainer/owin/index.json +``` +GET https://api.nuget.org/v3-flatcontainer/owin/index.json +``` + +Make sure to fetch the base URL (`https://api.nuget.org/v3-flatcontainer/` in this sample) from the service index as mentioned in the [base URL](#base-url) section. ### Sample response @@ -85,7 +91,9 @@ in the following endpoints. If the client knows a package ID and version and wants to download the package content, they only need to construct the following URL: - GET {@id}/{LOWER_ID}/{LOWER_VERSION}/{LOWER_ID}.{LOWER_VERSION}.nupkg +``` +GET {@id}/{LOWER_ID}/{LOWER_VERSION}/{LOWER_ID}.{LOWER_VERSION}.nupkg +``` ### Request parameters @@ -95,7 +103,7 @@ LOWER_ID | URL | string | yes | The package ID, lowercase LOWER_VERSION | URL | string | yes | The package version, normalized and lowercased Both `LOWER_ID` and `LOWER_VERSION` are lowercased using the rules implemented by .NET's -[`System.String.ToLowerInvariant()`](/dotnet/api/system.string.tolowerinvariant?view=netstandard-2.0#System_String_ToLowerInvariant) +[`System.String.ToLowerInvariant()`](/dotnet/api/system.string.tolowerinvariant?view=netstandard-2.0#System_String_ToLowerInvariant&preserve-view=true) method. The `LOWER_VERSION` is the desired package version normalized using NuGet's version @@ -111,7 +119,11 @@ If the package does not exist on the package source, a 404 status code is return ### Sample request - GET https://api.nuget.org/v3-flatcontainer/newtonsoft.json/9.0.1/newtonsoft.json.9.0.1.nupkg +``` +GET https://api.nuget.org/v3-flatcontainer/newtonsoft.json/9.0.1/newtonsoft.json.9.0.1.nupkg +``` + +Make sure to fetch the base URL (`https://api.nuget.org/v3-flatcontainer/` in this sample) from the service index as mentioned in the [base URL](#base-url) section. ### Sample response @@ -122,7 +134,9 @@ The binary stream that is the .nupkg for Newtonsoft.Json 9.0.1. If the client knows a package ID and version and wants to download the package manifest, they only need to construct the following URL: - GET {@id}/{LOWER_ID}/{LOWER_VERSION}/{LOWER_ID}.nuspec +``` +GET {@id}/{LOWER_ID}/{LOWER_VERSION}/{LOWER_ID}.nuspec +``` ### Request parameters @@ -132,7 +146,7 @@ LOWER_ID | URL | string | yes | The package ID, lowercase LOWER_VERSION | URL | string | yes | The package version, normalized and lowercased Both `LOWER_ID` and `LOWER_VERSION` are lowercased using the rules implemented by .NET's -[`System.String.ToLowerInvariant()`](/dotnet/api/system.string.tolowerinvariant?view=netstandard-2.0#System_String_ToLowerInvariant) method. +[`System.String.ToLowerInvariant()`](/dotnet/api/system.string.tolowerinvariant?view=netstandard-2.0#System_String_ToLowerInvariant&preserve-view=true) method. The `LOWER_VERSION` is the desired package version normalized using NuGet's version [normalization rules](../concepts/package-versioning.md#normalized-version-numbers). This means that build metadata @@ -147,7 +161,11 @@ If the package does not exist on the package source, a 404 status code is return ### Sample request - GET https://api.nuget.org/v3-flatcontainer/newtonsoft.json/6.0.4/newtonsoft.json.nuspec +``` +GET https://api.nuget.org/v3-flatcontainer/newtonsoft.json/6.0.4/newtonsoft.json.nuspec +``` + +Make sure to fetch the base URL (`https://api.nuget.org/v3-flatcontainer/` in this sample) from the service index as mentioned in the [base URL](#base-url) section. ### Sample response diff --git a/docs/api/package-details-template-resource.md b/docs/api/package-details-template-resource.md index c696879d9..b2c7928f3 100644 --- a/docs/api/package-details-template-resource.md +++ b/docs/api/package-details-template-resource.md @@ -55,14 +55,18 @@ Name | Type | Required | Notes The server should accept `{id}` and `{version}` values with any casing. In addition, the server should not be sensitive to whether the version is -[normalized](https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#normalized-version-numbers). In other +[normalized](../concepts/package-versioning.md#normalized-version-numbers). In other words, the server should accept also accept non-normalized versions. For example, nuget.org's package details template looks like this: - https://www.nuget.org/packages/{id}/{version} +```http +https://www.nuget.org/packages/{id}/{version} +``` If the client implementation needs to display a link to the package details for NuGet.Versioning 4.3.0, it would produce the following URL and provide it to the user: - https://www.nuget.org/packages/NuGet.Versioning/4.3.0 +```http +https://www.nuget.org/packages/NuGet.Versioning/4.3.0 +``` diff --git a/docs/api/package-publish-resource.md b/docs/api/package-publish-resource.md index 1b59da972..57ffa8e46 100644 --- a/docs/api/package-publish-resource.md +++ b/docs/api/package-publish-resource.md @@ -42,7 +42,9 @@ endpoint, see below. nuget.org supports pushing new packages using the following API. If the package with the provided ID and version already exists, nuget.org will reject the push. Other package sources may support replacing an existing package. - PUT https://www.nuget.org/api/v2/package +``` +PUT https://www.nuget.org/api/v2/package +``` ### Request parameters @@ -84,7 +86,9 @@ implementations are free to interpret this signal as a hard delete, soft delete, [NuGet.Server](https://www.nuget.org/packages/NuGet.Server) (a server implementation only supporting the older V2 API) supports handling this request as either an unlist or a hard delete based on a configuration option. - DELETE https://www.nuget.org/api/v2/package/{ID}/{VERSION} +``` +DELETE https://www.nuget.org/api/v2/package/{ID}/{VERSION} +``` ### Request parameters @@ -109,7 +113,9 @@ HTTP method instead of the `DELETE` method. If the package is already listed, the request still succeeds. - POST https://www.nuget.org/api/v2/package/{ID}/{VERSION} +``` +POST https://www.nuget.org/api/v2/package/{ID}/{VERSION} +``` ### Request parameters diff --git a/docs/api/rate-limits.md b/docs/api/rate-limits.md index 854f5f127..f738504b6 100644 --- a/docs/api/rate-limits.md +++ b/docs/api/rate-limits.md @@ -36,10 +36,9 @@ The following tables list the rate limits for the NuGet.org API. ## Package search > [!Note] -> We recommend using NuGet.org's [V3 APIs](https://docs.microsoft.com/nuget/api/search-query-service-resource) for search that are performant and do not have any limit currently. For V1 and V2 search APIs, the followins limits apply: +> We recommend using NuGet.org's [V3 search APIs](search-query-service-resource.md) as it is not rate limited currently. For V1 and V2 search APIs, the following limits apply: - -| API | Limit Type | Limit Value | API usecase | +| API | Limit Type | Limit Value | API Use Case | |:---|:---|:---|:---| **GET** `/api/v1/Packages` | IP | 1000 / minute | Query NuGet package metadata via v1 OData `Packages` collection | **GET** `/api/v1/Search()` | IP | 3000 / minute | Search for NuGet packages via v1 Search endpoint | @@ -48,7 +47,15 @@ The following tables list the rate limits for the NuGet.org API. ## Package Push and Unlist -| API | Limit Type | Limit Value | API usecase | +| API | Limit Type | Limit Value | API Use Case | |:---|:---|:---|:--- | **PUT** `/api/v2/package` | API Key | 350 / hour | Upload a new NuGet package (version) via v2 push endpoint **DELETE** `/api/v2/package/{id}/{version}` | API Key | 250 / hour | Unlist a NuGet package (version) via v2 endpoint + +## nuget.org website page views + +If you are accessing the nuget.org web pages programmatically, consider investigating our documented [V3 APIs](overview.md). These endpoints allow for simpler access to package metadata and content. The V3 API has better availability and has higher performance than accessing the NuGet Gallery web pages, which are designed for web browser interaction. + +| API | Limit Type | Limit Value | API Use Case | +|:---|:---|:---|:--- | +**GET** `/package/{id}/{version}` | IP | 50 / minute | Display package (version) details page. diff --git a/docs/api/readme-template-resource.md b/docs/api/readme-template-resource.md new file mode 100644 index 000000000..565789ea7 --- /dev/null +++ b/docs/api/readme-template-resource.md @@ -0,0 +1,62 @@ +--- +title: README Uri Template, NuGet API +description: The README uri template allows clients to download the readme for a package, if available. +author: jgonz120 +ms.author: jongonza +ms.date: 1/6/2025 +ms.topic: reference +ms.reviewer: +--- + +# README Uri Template + +It is possible for a client to build a URL that can be used to download a README for a specific package. +This will enable the clients to render the package's README without downloading the entire package. + +The resource used for building this URL is the `ReadmeUriTemplate` resource found in the +[service index](service-index.md). + +## Versioning + +The following `@type` values are used: + +@type value | Notes +--------------------------------- | ----- +ReadmeUriTemplate/6.13.0 | The initial release + +## URL template + +The URL for the following API is the value of the `@id` property associated with one of the aforementioned +resource `@type` values. + +## HTTP methods + +The constructed URL must support the HTTP method `GET` + +## Construct the URL + +Given a known package ID and version, the client implementation can construct a URL to download the README. + +The value of the `@id` is a URL string containing any of the following placeholder tokens: + +### URL placeholders + +Name | Type | Required | Notes +----------- | ------- | -------- | ----- +`{lower_id}` | string | yes | The package ID, lowercased +`{lower_version}` | string | yes | The package version, lowercased + +Both `lower_id` and `lower_version` are lowercased using the rules implemented by .NET's +[`System.String.ToLowerInvariant()`](/dotnet/api/system.string.tolowerinvariant?view=netstandard-2.0#System_String_ToLowerInvariant&preserve-view=true) +method. + +The `lower_version` is the desired package version normalized using NuGet's version +[normalization rules](../concepts/package-versioning.md#normalized-version-numbers). This means that build metadata +that is allowed by the SemVer 2.0.0 specification must be excluded in this case. + +### Response body + +If the package has a readme, a 200 status code is returned. The response body will be the readme +content itself. + +If the package does not have a readme, a 404 status code is returned. diff --git a/docs/api/registration-base-url-resource.md b/docs/api/registration-base-url-resource.md index 9cb23606e..d76d47d2f 100644 --- a/docs/api/registration-base-url-resource.md +++ b/docs/api/registration-base-url-resource.md @@ -15,7 +15,11 @@ metadata can be fetched using the `RegistrationsBaseUrl` resource found in the [ The collection of the documents found under `RegistrationsBaseUrl` are often called "registrations" or "registration blobs". The set of documents under a single `RegistrationsBaseUrl` is referred to as a "registration hive". A -registration hive contains all metadata about every package available on a package source. +registration hive contains metadata about every package available on a package source. + +> [!Note] +> The package metadata resource does not contain all metadata for packages. +> Use the [search resource](search-query-service-resource.md) to find packages' owners, downloads, or prefix reservation status. ## Versioning @@ -50,7 +54,7 @@ For more information about SemVer 2.0.0, see ## Base URL The base URL for the following APIs is the value of the `@id` property associated with the aforementioned -resource `@type` values. In the following document, the placeholder base URL `{@id}` will be used. +resource `@type` values. In the following document, the placeholder base URL `{@id}` will be used. The base URL may change based on implementation or infrastructure changes within the package source so it must be dynamically fetched from the [service index](service-index.md) by the client software. ## HTTP methods @@ -85,9 +89,12 @@ other hand, if the server implementation immediately stores registration leaves must perform more HTTP requests to get the information it needs. The heuristic that nuget.org uses is as follows: if there are 128 or more versions of a package, break the leaves -into pages of size 64. If there are less than 128 versions, inline all leaves into the registration index. +into pages of size 64. If there are less than 128 versions, inline all leaves into the registration index. Note that +this means packages with 65 to 127 versions will have two pages in the index but both pages will be inlined. - GET {@id}/{LOWER_ID}/index.json +``` +GET {@id}/{LOWER_ID}/index.json +``` ### Request parameters @@ -96,7 +103,7 @@ Name | In | Type | Required | Notes LOWER_ID | URL | string | yes | The package ID, lowercased The `LOWER_ID` value is the desired package ID lowercased using the rules implemented by .NET's -[`System.String.ToLowerInvariant()`](/dotnet/api/system.string.tolowerinvariant?view=netstandard-2.0#System_String_ToLowerInvariant) method. +[`System.String.ToLowerInvariant()`](/dotnet/api/system.string.tolowerinvariant?view=netstandard-2.0#System_String_ToLowerInvariant&preserve-view=true) method. ### Response @@ -126,7 +133,7 @@ The `lower` and `upper` bounds of the page object are useful when the metadata f These bounds can be used to fetch the only registration page needed. The version strings adhere to [NuGet's version rules](../concepts/package-versioning.md). The version strings are normalized and do not include build metadata. As with all versions in the NuGet ecosystem, comparison of version strings is implemented using -[SemVer 2.0.0's version precedence rules](http://semver.org/spec/v2.0.0.html#spec-item-11). +[SemVer 2.0.0's version precedence rules](https://semver.org/spec/v2.0.0.html#spec-item-11). The `parent` property will only appear if the registration page object has the `items` property. @@ -160,24 +167,28 @@ The `catalogEntry` property in the registration leaf object has the following pr Name | Type | Required | Notes ------------------------ | -------------------------- | -------- | ----- -@id | string | yes | The URL to document used to produce this object +@id | string | yes | The URL to the document used to produce this object authors | string or array of strings | no | dependencyGroups | array of objects | no | The dependencies of the package, grouped by target framework deprecation | object | no | The deprecation associated with the package description | string | no | iconUrl | string | no | id | string | yes | The ID of the package +language | string | no | licenseUrl | string | no | licenseExpression | string | no | listed | boolean | no | Should be considered as listed if absent minClientVersion | string | no | +packageContent | string | no | Duplicate of the same property in the parent object, included only for legacy reasons projectUrl | string | no | published | string | no | A string containing a ISO 8601 timestamp of when the package was published +readmeUrl | string | no | A URL for the rendered (HTML web page) view of the package README requireLicenseAcceptance | boolean | no | summary | string | no | -tags | string or array of string | no | +tags | string or array of strings | no | title | string | no | version | string | yes | The full version string after normalization +vulnerabilities | array of objects | no | The security vulnerabilities of the package The package `version` property is the full version string after normalization. This means that SemVer 2.0.0 build data can be included here. @@ -187,7 +198,10 @@ framework. If the package has no dependencies, the `dependencyGroups` property i `dependencies` property of all groups is empty or missing. The value of the `licenseExpression` property complies with -[NuGet license expression syntax](https://docs.microsoft.com/en-us/nuget/reference/nuspec#license). +[NuGet license expression syntax](../reference/nuspec.md#license). + +> [!Note] +> On nuget.org, the `published` value is set to year 1900 when the package is unlisted. #### Package dependency group @@ -211,11 +225,11 @@ Each package dependency has the following properties: Name | Type | Required | Notes ------------ | ------ | -------- | ----- id | string | yes | The ID of the package dependency -range | object | no | The allowed [version range](../concepts/package-versioning.md#version-ranges-and-wildcards) of the dependency +range | object | no | The allowed [version range](../concepts/package-versioning.md#version-ranges) of the dependency registration | string | no | The URL to the registration index for this dependency If the `range` property is excluded or an empty string, the client should default to the version range `(, )`. That is, -any version of the dependency is allowed. +any version of the dependency is allowed. The value of `*` is not allowed for the `range` property. #### Package deprecation @@ -225,7 +239,7 @@ Name | Type | Required | Notes ---------------- | ---------------- | -------- | ----- reasons | array of strings | yes | The reasons why the package was deprecated message | string | no | The additional details about this deprecation -alternatePackage | object | no | The package dependency that should be used instead +alternatePackage | object | no | The alternate package that should be used instead The `reasons` property must contain at least one string and should only contains strings from the following table: @@ -237,9 +251,31 @@ Other | The package is deprecated due to a reason not on this list If the `reasons` property contains strings that are not from the known set, they should be ignored. The strings are case-insensitive, so `legacy` should be treated the same as `Legacy`. There is no ordering restriction on the array, so the strings can arranged in any arbitrary order. Additionally, if the property contains only strings that are not from the known set, it should be treated as if it only contained the "Other" string. +#### Alternate package + +The alternate package object has the following properties: + +Name | Type | Required | Notes +------------ | ------ | -------- | ----- +id | string | yes | The ID of the alternate package +range | object | no | The allowed [version range](../concepts/package-versioning.md#version-ranges), or `*` if any version is allowed + +#### Vulnerabilities + +An array of `vulnerability` objects. Each vulnerability has the following properties: + +Name | Type | Required | Notes +------------ | ------ | -------- | ----- +advisoryUrl | string | yes | Location of security advisory for the package +severity | string | yes | Severity of advisory: "0" = Low, "1" = Moderate, "2" = High, "3" = Critical + ### Sample request - GET https://api.nuget.org/v3/registration3/nuget.server.core/index.json +``` +GET https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json +``` + +Make sure to fetch the base URL (`https://api.nuget.org/v3/registration-sample/` in this sample) from the service index as mentioned in the [base URL](#base-url) section. ### Sample response @@ -251,7 +287,13 @@ fetch metadata about individual package versions. ## Registration page The registration page contains registration leaves. The URL to fetch a registration page is determined by the `@id` -property in the [registration page object](#registration-page-object) mentioned above. +property in the [registration page object](#registration-page-object) mentioned above. The URL is not meant to be +predictable and should always be discovered by means of the index document. + +> [!Warning] +> On nuget.org, the URL for the registration page document coincidentally contains the lower and upper bound of the +> page. However this assumption should never be made by a client since server implementations are free to change the +> shape of the URL as long as the index document has a valid link. When the `items` array is not provided in the registration index, an HTTP GET request of the `@id` value will return a JSON document which has an object as its root. The object has the following properties: @@ -270,7 +312,11 @@ The shape of the registration leaf objects is the same as in the registration in ## Sample request - GET https://api.nuget.org/v3/registration3/ravendb.client/page/1.0.531/1.0.729-unstable.json +``` +GET https://api.nuget.org/v3/registration-sample/ravendb.client/page/1.0.531/1.0.729-unstable.json +``` + +Make sure to fetch the base URL (`https://api.nuget.org/v3/registration-sample/` in this sample) from the service index as mentioned in the [base URL](#base-url) section. ## Sample response @@ -284,7 +330,13 @@ version may not be available in this document. Package metadata should be fetche the registration index). The URL to fetch a registration leaf is obtained from the `@id` property of a registration leaf object in either a -registration index or registration page. +registration index or registration page. As with the page document. the URL is not meant to be predictable and should +always be discovered by means of the registration page object. + +> [!Warning] +> On nuget.org, the URL for the registration leaf document coincidentally contains the package version. However this +> assumption should never be made by a client since server implementations are free to change the shape of the URL as +> long as the parent document has a valid link. The registration leaf is a JSON document with a root object with the following properties: @@ -302,7 +354,11 @@ registration | string | no | The URL to the registration index ### Sample request - GET https://api.nuget.org/v3/registration3/nuget.versioning/4.3.0.json +``` +GET https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json +``` + +Make sure to fetch the base URL (`https://api.nuget.org/v3/registration-sample/` in this sample) from the service index as mentioned in the [base URL](#base-url) section. ### Sample response diff --git a/docs/api/report-abuse-resource.md b/docs/api/report-abuse-resource.md index b058dd0b6..dd052189a 100644 --- a/docs/api/report-abuse-resource.md +++ b/docs/api/report-abuse-resource.md @@ -57,9 +57,13 @@ whether the version is normalized. For example, nuget.org's report abuse template looks like this: - https://www.nuget.org/packages/{id}/{version}/ReportAbuse +``` +https://www.nuget.org/packages/{id}/{version}/ReportAbuse +``` If the client implementation needs to display a link to the report abuse form for NuGet.Versioning 4.3.0, it would produce the following URL and provide it to the user: - https://www.nuget.org/packages/NuGet.Versioning/4.3.0/ReportAbuse +``` +https://www.nuget.org/packages/NuGet.Versioning/4.3.0/ReportAbuse +``` diff --git a/docs/api/repository-signatures-resource.md b/docs/api/repository-signatures-resource.md index 4edb39e67..4d8befdd0 100644 --- a/docs/api/repository-signatures-resource.md +++ b/docs/api/repository-signatures-resource.md @@ -58,7 +58,9 @@ signing certificate list. The following request fetches the repository signatures index. - GET {@id} +``` +GET {@id} +``` The repository signature index is a JSON document that contains an object with the following properties: @@ -107,7 +109,9 @@ All hash values must be lowercase, hex-encoded string representations of the has ### Sample request - GET https://api.nuget.org/v3-index/repository-signatures/index.json +``` +GET https://api.nuget.org/v3-index/repository-signatures/5.0.0/index.json +``` ### Sample response diff --git a/docs/api/search-autocomplete-service-resource.md b/docs/api/search-autocomplete-service-resource.md index 3ee54679f..5f8efe82a 100644 --- a/docs/api/search-autocomplete-service-resource.md +++ b/docs/api/search-autocomplete-service-resource.md @@ -22,11 +22,15 @@ The following `@type` values are used: SearchAutocompleteService | The initial release SearchAutocompleteService/3.0.0-beta | Alias of `SearchAutocompleteService` SearchAutocompleteService/3.0.0-rc | Alias of `SearchAutocompleteService` +SearchAutocompleteService/3.5.0 | Includes support for `packageType` query parameter + +### SearchAutocompleteService/3.5.0 +This version introduces support for the `packageType` query parameter, allowing filtering by author defined package types. It is fully backwards compatible with queries to `SearchAutocompleteService`. ## Base URL The base URL for the following APIs is the value of the `@id` property associated with one of the aforementioned -resource `@type` values. In the following document, the placeholder base URL `{@id}` will be used. +resource `@type` values. In the following document, the placeholder base URL `{@id}` will be used. The base URL may change based on implementation or infrastructure changes within the package source so it must be dynamically fetched from the [service index](service-index.md) by the client software. ## HTTP Methods @@ -39,7 +43,9 @@ a package typeahead feature in a user interface integrated with a NuGet package A package with only unlisted versions will not appear in the results. - GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL} +``` +GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}&packageType={PACKAGETYPE} +``` ### Request parameters @@ -50,9 +56,10 @@ skip | URL | integer | no | The number of results to skip, for p take | URL | integer | no | The number of results to return, for pagination prerelease | URL | boolean | no | `true` or `false` determining whether to include [pre-release packages](../create-packages/prerelease-packages.md) semVerLevel | URL | string | no | A SemVer 1.0.0 version string +packageType | URL | string | no | The package type to use to filter packages (added in `SearchAutocompleteService/3.5.0`) The autocomplete query `q` is parsed in a manner that is defined by the server implementation. nuget.org supports -querying for the prefix of package ID tokens, which are pieces of the ID produced by spliting the original by camel +querying for the prefix of package ID tokens, which are pieces of the ID produced by splitting the original by camel case and symbol characters. The `skip` parameter defaults to 0. @@ -69,6 +76,10 @@ If `semVerLevel=2.0.0` is provided, both SemVer 1.0.0 and SemVer 2.0.0 compatibl [SemVer 2.0.0 support for nuget.org](https://github.com/NuGet/Home/wiki/SemVer2-support-for-nuget.org-%28server-side%29) for more information. +The `packageType` parameter is used to further filter the autocomplete results to only packages that have at least one package type matching the package type name. +If the provided package type is not a valid package type as defined by the [Package Type document](https://github.com/NuGet/Home/wiki/Package-Type-%5BPacking%5D), an empty result will returned. +If the provided package type is empty, no filter will be applied. In other words, passing no value to the `packageType` parameter will behave as if the parameter was not passed. + ### Response The response is JSON document containing up to `take` autocomplete results. @@ -82,7 +93,11 @@ data | array of strings | yes | The package IDs matched by the request ### Sample request - GET https://api-v2v3search-0.nuget.org/autocomplete?q=storage&prerelease=true +``` +GET https://search-sample.nuget.org/autocomplete?q=storage&prerelease=true +``` + +Make sure to fetch the base URL (`https://search-sample.nuget.org/autocomplete` in this sample) from the service index as mentioned in the [base URL](#base-url) section. ### Sample response @@ -95,7 +110,9 @@ versions for a provided package ID. A package version that is unlisted will not appear in the results. - GET {@id}?id={ID}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL} +``` +GET {@id}?id={ID}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL} +``` ### Request parameters @@ -128,7 +145,9 @@ The package versions in the `data` array may contain SemVer 2.0.0 build metadata ### Sample request - GET https://api-v2v3search-0.nuget.org/autocomplete?id=nuget.protocol&prerelease=true +``` +GET https://api-v2v3search-0.nuget.org/autocomplete?id=nuget.protocol&prerelease=true +``` ### Sample response diff --git a/docs/api/search-query-service-resource.md b/docs/api/search-query-service-resource.md index b1c4dd05f..e4466d5e1 100644 --- a/docs/api/search-query-service-resource.md +++ b/docs/api/search-query-service-resource.md @@ -22,11 +22,15 @@ The following `@type` values are used: SearchQueryService | The initial release SearchQueryService/3.0.0-beta | Alias of `SearchQueryService` SearchQueryService/3.0.0-rc | Alias of `SearchQueryService` +SearchQueryService/3.5.0 | Includes support for `packageType` query parameter + +### SearchQueryService/3.5.0 +This version introduces support for the `packageType` query parameter and the `packageTypes` response property, allowing filtering by author defined package types. It is fully backwards compatible with queries to `SearchQueryService`. ## Base URL The base URL for the following API is the value of the `@id` property associated with one of the aforementioned -resource `@type` values. In the following document, the placeholder base URL `{@id}` will be used. +resource `@type` values. In the following document, the placeholder base URL `{@id}` will be used. The base URL may change based on implementation or infrastructure changes within the package source so it must be dynamically fetched from the [service index](service-index.md) by the client software. ## HTTP methods @@ -41,7 +45,9 @@ package metadata fields may also be considered. An unlisted package should never appear in search results. - GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL} +``` +GET {@id}?q={QUERY}&skip={SKIP}&take={TAKE}&prerelease={PRERELEASE}&semVerLevel={SEMVERLEVEL}&packageType={PACKAGETYPE} +``` ### Request parameters @@ -52,6 +58,7 @@ skip | URL | integer | no | The number of results to skip, for p take | URL | integer | no | The number of results to return, for pagination prerelease | URL | boolean | no | `true` or `false` determining whether to include [pre-release packages](../create-packages/prerelease-packages.md) semVerLevel | URL | string | no | A SemVer 1.0.0 version string +packageType | URL | string | no | The package type to use to filter packages (added in `SearchQueryService/3.5.0`) The search query `q` is parsed in a manner that is defined by the server implementation. nuget.org supports basic filtering on a [variety of fields](../consume-packages/finding-and-choosing-packages.md#search-syntax). If no @@ -62,6 +69,9 @@ The `skip` parameter defaults to 0. The `take` parameter should be an integer greater than zero. The server implementation may impose a maximum value. +> [!Note] +> nuget.org limits the `skip` parameter to 3,000 and the `take` parameter to 1,000. + If `prerelease` is not provided, pre-release packages are excluded. The `semVerLevel` query parameter is used to opt-in to @@ -72,6 +82,10 @@ If `semVerLevel=2.0.0` is provided, both SemVer 1.0.0 and SemVer 2.0.0 compatibl [SemVer 2.0.0 support for nuget.org](https://github.com/NuGet/Home/wiki/SemVer2-support-for-nuget.org-%28server-side%29) for more information. +The `packageType` parameter is used to further filter the search results to only packages that have at least one package type matching the package type name. +If the provided package type is not a valid package type as defined by the [Package Type document](https://github.com/NuGet/Home/wiki/Package-Type-%5BPacking%5D), an empty result will returned. +If the provided package type is empty, no filter will be applied. In other words, passing no value to the packageType parameter will behave as if the parameter was not passed. + ### Response The response is JSON document containing up to `take` search results. Search results are grouped by package ID. @@ -97,7 +111,7 @@ versions | array of objects | yes | All of the versions of authors | string or array of strings | no | iconUrl | string | no | licenseUrl | string | no | -owners | string or array of strings | no | +owners | string or array of strings | no | A string represents a single owner's username projectUrl | string | no | registration | string | no | The absolute URL to the associated [registration index](registration-base-url-resource.md#registration-index) summary | string | no | @@ -105,10 +119,11 @@ tags | string or array of strings | no | title | string | no | totalDownloads | integer | no | This value can be inferred by the sum of downloads in the `versions` array verified | boolean | no | A JSON boolean indicating whether the package is [verified](../nuget-org/id-prefix-reservation.md) +packageTypes | array of objects | yes | The package types defined by the package author (added in `SearchQueryService/3.5.0`) On nuget.org, a verified package is one which has a package ID matching a reserved ID prefix and owned by one of the reserved prefix's owners. For more information, see the -[documentation about ID prefix reservation](../reference/id-prefix-reservation.md). +[documentation about ID prefix reservation](../nuget-org/id-prefix-reservation.md). The metadata contained in the search result object is taken from the latest package version. Each item in the `versions` array is a JSON object with the following properties: @@ -119,9 +134,19 @@ Name | Type | Required | Notes version | string | yes | The full SemVer 2.0.0 version string of the package (could contain build metadata) downloads | integer | yes | The number of downloads for this specific package version +The `packageTypes` array will always consist of at least one (1) item. Package type for a given package ID is considered to be the package types defined by the latest version of the package with respect to the other search parameters. Each item in the `packageTypes` array is a JSON object with the following properties: + +Name | Type | Required | Notes +--------- | ------- | -------- | ----- +name | string | yes | The name of the package type. + ### Sample request - GET https://azuresearch-usnc.nuget.org/query?q=NuGet.Versioning&prerelease=false&semVerLevel=2.0.0 +``` +GET https://search-sample.nuget.org/query?q=NuGet.Versioning&prerelease=false&semVerLevel=2.0.0 +``` + +Make sure to fetch the base URL (`https://search-sample.nuget.org/query` in this sample) from the service index as mentioned in the [base URL](#base-url) section. ### Sample response diff --git a/docs/api/service-index.md b/docs/api/service-index.md index a5a9f5888..369bdbc16 100644 --- a/docs/api/service-index.md +++ b/docs/api/service-index.md @@ -50,7 +50,9 @@ The `@id` is a URL that must be absolute and must either have the HTTP or HTTPS The `@type` is used to identify the specific protocol to use when interacting with resource. The type of the resource is an opaque string but generally has the format: - {RESOURCE_NAME}/{RESOURCE_VERSION} +``` +{RESOURCE_NAME}/{RESOURCE_VERSION} +``` Clients are expected to hard code the `@type` values that they understand and look them up in a package source's service index. The exact `@type` values in use today are enumerated on the individual resource reference documents @@ -63,9 +65,15 @@ There is no requirement that each resource has a unique `@id` or `@type`. It is determine which resource to prefer over another. One possible implementation is that resources of the same or compatible `@type` can be used in a round-robin fashion in case of connection failure or server error. +A resource can use a different host or domain than the service index, but this may cause issues in environments with strict network rules. +In particular, if your service index adds resources that point directly to nuget.org (rather than proxying or caching through your own feed), your feed will not work where access to nuget.org is blocked. +If your feed is going to delegate particular resources to nuget.org, we recommend adding a configuration so that when your feed is deployed, the direct nuget.org reference can be removed from the service index. + ### Sample request - GET https://api.nuget.org/v3/index.json +``` +GET https://api.nuget.org/v3/index.json +``` ### Sample response diff --git a/docs/api/symbol-package-publish-resource.md b/docs/api/symbol-package-publish-resource.md index 3ea1dd082..77d7106c9 100644 --- a/docs/api/symbol-package-publish-resource.md +++ b/docs/api/symbol-package-publish-resource.md @@ -1,13 +1,10 @@ --- title: Push Symbol Packages, NuGet API | Microsoft Docs author: cristinamanum -ms.author: -- cmanu -- kraigb +ms.author: cmanu manager: skofman ms.date: 10/30/2018 ms.topic: reference -ms.prod: nuget ms.technology: null description: The publish service allows clients to publish new symbol packages. keywords: NuGet API push symbol package @@ -41,7 +38,9 @@ The `PUT` HTTP method is supported by this resource. nuget.org supports pushing new symbol packages format ([snupkg](../create-packages/Symbol-Packages-snupkg.md)) using the following API. - PUT https://www.nuget.org/api/v2/symbolpackage +``` +PUT https://www.nuget.org/api/v2/symbolpackage +``` Symbol packages with the same ID and version can be submitted multiple times. A symbol package will be rejected in the following cases. diff --git a/docs/api/tools-json.md b/docs/api/tools-json.md index 28ac7e479..f42b5c70c 100644 --- a/docs/api/tools-json.md +++ b/docs/api/tools-json.md @@ -4,7 +4,7 @@ description: The endpoint for author: jver ms.author: jver ms.date: 08/16/2018 -ms.topic: conceptual +ms.topic: article ms.reviewer: kraigb --- @@ -29,11 +29,15 @@ unauthenticated HTTP requests. The endpoint can be fetched using the `GET` method: - GET https://dist.nuget.org/tools.json +``` +GET https://dist.nuget.org/tools.json +``` -The [JSON schema](http://json-schema.org/) for the endpoint is available here: +The [JSON schema](https://json-schema.org/) for the endpoint is available here: - GET https://dist.nuget.org/tools.schema.json +``` +GET https://dist.nuget.org/tools.schema.json +``` ## Response @@ -77,7 +81,9 @@ The `NuGet.CommandLine` package on nuget.org is typically only updated with `Rel ### Sample request - GET https://dist.nuget.org/tools.json +``` +GET https://dist.nuget.org/tools.json +``` ### Sample response diff --git a/docs/api/vulnerability-info.md b/docs/api/vulnerability-info.md new file mode 100644 index 000000000..abddc2eaf --- /dev/null +++ b/docs/api/vulnerability-info.md @@ -0,0 +1,128 @@ +--- +title: Vulnerability Info, NuGet API +description: The data that allows clients to check packages for known vulnerabilities. +author: zivkan +ms.author: zivkan +ms.date: 06/16/2023 +ms.topic: reference +--- + +# Vulnerability information + +NuGet client, starting from version 6.7, can download known package vulnerability information to use in scenarios such as checking packages during restore operations. +While the [package metadata resource](./registration-base-url-resource.md) also contains known vulnerability information, if an app needs to check a large number of packages for known vulnerabilities, it's much faster to download a file of known vulnerabilities and lookup locally, rather than making a large number of HTTP requests. +For example, this enables NuGet Restore to quickly check restored packages for known vulnerabilities, which historically never downloaded package details from the package metadata resource. + +The API consists of at least two files, the [vulnerability index](#vulnerability-index) and one or more [vulnerability page files](#vulnerability-page). +Known vulnerability data can be partitioned into multiple files, and the vulnerability index provides clients with information needed to cache files, and update the cache, efficiently. + +The resource used for building this URL is the `VulnerabilityInfo` resource found in the [service index](service-index.md). + +## Suggested partitioning strategy + +The pages listed in the vulnerability index should ideally be optimized to maximize caching, and therefore minimize updates to large files. +This will allow clients to minimize the frequency it needs to download updates. + +A suggested strategy for vulnerability data partitioning is to have two pages, `base.json` and `updates.json`. +The `base.json` file is updated periodically (for example once a month), and contains all known vulnerabilities at the time the file is regenerated. +The `updates.json` file should contain any new advisories published since `base.json` was last regenerated. +This will allow clients to download the large `base.json` infrequently, while the frequently changing `updates.json` file is always relatively small. + +NuGet clients combine the data from multiple files additively, and may load the files in any order. +The data file schema does not allow for modification or redaction of known vulnerability from another file. +Therefore if a server's vulnerability data source (for example the [GitHub Advisories Database](https://github.com/advisories)) modifies an existing advisory, the NuGet server must modify the page that the vulnerability information was previously reported. +One way to achieve this with the suggested partition scheme is to treat all vulnerability modifications and deletions as a trigger to regenerate the complete `base.json` file, and empty `updates.json`. + +If you intend to use nuget.org's vulnerability data in your own NuGet server implementation, you should take into consideration developers who do not have direct access to nuget.org. +[See our implementation guide for more details](./implementation-guide.md#reusing-nugetorgs-vulnerability-data). + +## Versioning + +The following `@type` values are used: + +@type value | Notes +--------------------------------- | ----- +VulnerabilityInfo/6.7.0 | The initial release + +## Vulnerability index + +The vulnerability index is a JSON array of objects with the following properties: + +Name | Type | Required | Notes +-------- | ---------| -------- | ----- +@name | string | yes | A short name for the file, used as a cache key. +@id | string | yes | The full (absolute) URL to a vulnerability data file. +@updated | string | yes | An ISO 8601 string representing the date and time the file was last updated, ideally with the UTC timezone. +comment | string | no | A optional descriptive string. + +The following restrictions apply: + +* The index must be an array of objects with between 1 and 16 items. + If the server does not have any vulnerability data (zero pages), then must remove the `VulnerabilityInfo` resource from the `ServiceIndex`. +* `@name` must be unique within the index, must be between 1 and 32 characters long, and can only use the characters `A` to `Z`, `a` to `z`, `0` to `9`, `-`, or `_`. +* `@id` must be an absolute URL, not a relative URL. + +## Vulnerability page + +Vulnerability page files are a JSON object used as a dictionary. +Property keys are the lower-case package id and property values are an array of the following object with the following properties: + +Name | Type | Required | Notes +-------- | ------- | -------- | ----- +severity | integer | yes | 0 means low, 1 means medium, 2 means high, 3 means critical. +url | string | yes | URL where users can get more information about the vulnerability. +versions | string | yes | The version range that is vulnerable, using [NuGet's version range syntax](../concepts/package-versioning.md#version-ranges). + +Package IDs (the root object's keys) must be lowercased with [`String.ToLowerInvariant`](/dotnet/api/system.string.tolowerinvariant). + +The list of known vulnerabilities for a package should be sorted in descending order of the max version of the version range, followed by descending version of the min version, followed by the ascending order of the URL. +Ranges with null min or max versions (unbounded) in a version range should be sorted to before non-null (bounded) versions. + +An empty page, one that does not provide any known vulnerabilities, must be an empty JSON array (`[]`). + +## Samples + +Here is a sample of a vulnerability index: + +```json +[ + { + "@name": "base", + "@id": "https://nuget.contoso.com/v3/vulnerabilities/3bb6b300-2f74-45bc-af06-746fd21c024b.json", + "@updated": "2023-06-01T06:14:58.4159909Z", + "comment": "The base data for vulnerability update periodically" + }, + { + "@name": "update", + "@id": "https://nuget.contoso.com/v3/vulnerabilities/ffd572cd-33f3-4372-8714-a9cab2e86b45.json", + "@updated": "2023-06-14T11:35:30.3155764Z", + "comment": "The patch data for the vulnerability. Contains all the vulnerabilities since base was last updated." + } +] +``` + +Here is a sample of a vulnerability data file: + +```json +{ + "contoso.library": [ + { + "url": "https://cve.contoso.com/advisories/1", + "severity": 1, + "versions": "(, 2.0.0)" + }, + { + "url": "https://cve.contoso.com/advisories/2", + "severity": 2, + "versions": "(1.0.0, 2.0.0)" + } + ], + "contoso.utilities": [ + { + "url": "https://cve.contoso.com/advisories/3", + "severity": 3, + "versions": "(, 1.0.0)" + } + ] +} +``` diff --git a/docs/archive/config-priority-order.md b/docs/archive/config-priority-order.md deleted file mode 100644 index ff7e66e55..000000000 --- a/docs/archive/config-priority-order.md +++ /dev/null @@ -1,29 +0,0 @@ -### Priority ordering - -It can also help to think about the "priority order" in which settings are applied, which is essentially the reverse of the processing order. For example, if a project is located in `c:\A\B\C`, then NuGet applies settings in the following priority order, meaning settings found higher up in the order win: - - (For solution-level packages only in NuGet 2.x; ignored in NuGet 3.x) - c:\A\B\C\.nuget\NuGet.Config - - (For all version of NuGet) - c:\A\B\C\NuGet.Config - c:\A\B\NuGet.Config - c:\A\NuGet.Config - c:\NuGet.Config - - configFile, if specified - - (Ignored in NuGet 3.4 and later if -configFile is used) - %AppData%\NuGet\NuGet.Config - - (NuGet 2.6 to 3.5) - %ProgramData%\NuGet\Config\{IDE}\{Version}\{SKU}\NuGet.Config - %ProgramData%\NuGet\Config\{IDE}\{Version}\NuGet.Config - %ProgramData%\NuGet\Config\{IDE}\NuGet.Config - %ProgramData%\NuGet\Config\NuGet.Config - - (NuGet 4.0+) - %ProgramFiles(x86)%\NuGet\Config\{IDE}\{Version}\{SKU}\NuGet.Config - %ProgramFiles(x86)%\NuGet\Config\{IDE}\{Version}\NuGet.Config - %ProgramFiles(x86)%\NuGet\Config\{IDE}\NuGet.Config - %ProgramFiles(x86)%\NuGet\Config\NuGet.Config \ No newline at end of file diff --git a/docs/archive/media/project-json-migrator.png b/docs/archive/media/project-json-migrator.png new file mode 100644 index 000000000..4328dfa7f Binary files /dev/null and b/docs/archive/media/project-json-migrator.png differ diff --git a/docs/archive/project-json-and-uwp.md b/docs/archive/project-json-and-uwp.md index f25a464dd..898f98a53 100644 --- a/docs/archive/project-json-and-uwp.md +++ b/docs/archive/project-json-and-uwp.md @@ -1,16 +1,19 @@ --- title: NuGet project.json file with UWP projects description: Description of how the project.json file is used to track NuGet dependencies in Universal Windows Platform (UWP) projects. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 07/17/2017 -ms.topic: conceptual +ms.topic: article --- # project.json and UWP > [!Important] -> This content is deprecated. Projects should use either the `packages.config` or PackageReference formats. +> This content is deprecated. Projects should use the PackageReference formats. +> Learn how to [migrate your project.json project to PackageReference](./project-json.md#migrate-projectjson-to-packagereference). +> Visual Studio 2026 automatically migrates project.json at solution load time. +> [.NET 10 SDK & NuGet.exe 7.0](../release-notes/NuGet-7.0.md) do not support project.json projects. This document describes the package structure that employs features in NuGet 3+ (Visual Studio 2015 and later). The `minClientVersion` property of your `.nuspec` can be used to state that you require the features described here by setting it to 3.1. @@ -68,11 +71,13 @@ The behavior of the `lib` folder hasn't changed significantly in NuGet v3. Howev An example lib structure: - lib - ├───net40 - │ MyLibrary.dll - └───wp81 - MyLibrary.dll +``` +lib +├───net40 +│ MyLibrary.dll +└───wp81 + MyLibrary.dll +``` The `lib` folder contains assemblies that are used at runtime. For most packages a folder under `lib` for each of the target TxMs is all that is required. @@ -86,23 +91,25 @@ Mechanically, the assemblies included in the `ref` folder are the reference asse The structure of the `ref` folder is the same as `lib`, for example: - └───MyImageProcessingLib - ├───lib - │ ├───net40 - │ │ MyImageProcessingLibrary.dll - │ │ - │ ├───net451 - │ │ MyImageProcessingLibrary.dll - │ │ - │ └───win81 - │ MyImageProcessingLibrary.dll - │ - └───ref - ├───net40 - │ MyImageProcessingLibrary.dll - │ - └───portable-net451-win81 - MyImageProcessingLibrary.dll +``` +└───MyImageProcessingLib + ├───lib + │ ├───net40 + │ │ MyImageProcessingLibrary.dll + │ │ + │ ├───net451 + │ │ MyImageProcessingLibrary.dll + │ │ + │ └───win81 + │ MyImageProcessingLibrary.dll + │ + └───ref + ├───net40 + │ MyImageProcessingLibrary.dll + │ + └───portable-net451-win81 + MyImageProcessingLibrary.dll +``` In this example the assemblies in the `ref` directories would all be identical. @@ -114,27 +121,29 @@ The runtimes folder contains assemblies and native libraries required to run on The following example shows a package that has a purely managed implementation for several platforms, but uses native helpers on Windows 8 where it can call into Windows 8-specific native APIs. - └───MyLibrary - ├───lib - │ └───net40 - │ MyLibrary.dll - │ - └───runtimes - ├───win8-x64 - │ ├───lib - │ │ └───net40 - │ │ MyLibrary.dll - │ │ - │ └───native - │ MyNativeLibrary.dll - │ - └───win8-x86 - ├───lib - │ └───net40 - │ MyLibrary.dll - │ - └───native - MyNativeLibrary.dll +``` +└───MyLibrary + ├───lib + │ └───net40 + │ MyLibrary.dll + │ + └───runtimes + ├───win8-x64 + │ ├───lib + │ │ └───net40 + │ │ MyLibrary.dll + │ │ + │ └───native + │ MyNativeLibrary.dll + │ + └───win8-x86 + ├───lib + │ └───net40 + │ MyLibrary.dll + │ + └───native + MyNativeLibrary.dll +``` Given the above package the following things happen: @@ -150,23 +159,25 @@ Only a single `lib` folder is ever be picked, so if there is a runtime specific Another way to use runtimes is to ship a package that is purely a managed wrapper over a native assembly. In this scenario you create a package like the following: - └───MyLibrary - └───runtimes - ├───win8-x64 - │ ├───lib - │ │ └───net451 - │ │ MyLibrary.dll - │ │ - │ └───native - │ MyImplementation.dll - │ - └───win8-x86 - ├───lib - │ └───net451 - │ MyLibrary.dll - │ - └───native - MyImplementation.dll +``` +└───MyLibrary + └───runtimes + ├───win8-x64 + │ ├───lib + │ │ └───net451 + │ │ MyLibrary.dll + │ │ + │ └───native + │ MyImplementation.dll + │ + └───win8-x86 + ├───lib + │ └───net451 + │ MyLibrary.dll + │ + └───native + MyImplementation.dll +``` In this case there is no top-level `lib` folder as that folder as there is no implementation of this package that doesn't rely on the corresponding native assembly. If the managed assembly, `MyLibrary.dll`, was exactly the same in both of these cases then we could put it in a top level `lib` folder, but because the lack of a native assembly doesn't cause the package to fail installing if it was installed on a platform that wasn't win-x86 or win-x64 then the top level lib would be used but no native assembly would be copied. diff --git a/docs/archive/project-json-archive.md b/docs/archive/project-json-archive.md deleted file mode 100644 index b3acfc153..000000000 --- a/docs/archive/project-json-archive.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: NuGet project.json archive content -description: Miscellaneous bits of project.json content removed from other areas of the NuGet documentation. -author: karann-msft -ms.author: karann -ms.date: 01/17/2018 -ms.topic: conceptual ---- - -# project.json archive - -The `project.json` management format was introduced with NuGet 3.x and used for certain project types. It was deprecated with the introduction of the PackageReference format, in which dependencies are listed directly in a project file. - -Also see: - -- [project.json schema](project-json.md) -- [project.json impact on package authors](project-json-impact.md) -- [project.json and UWP](project-json-and-uwp.md) - -## project.json management format - -*Originally in [Package restore](../what-is-nuget.md).* - -In the list of management formats: - -- [`project.json`](project-json.md): *(deprecated)* A JSON file that maintains a list of the project's dependencies with an overall package graph in an associated file, `project.lock.json`. This format is deprecated in favor of PackageReference. - -## nuget restore on Mono - -*Originally in [Install NuGet client tools](../install-nuget-client-tools.md).* - -Works with `project.json`. - -## Constraining package versions with restore - -*Originally in [Package restore](../consume-packages/package-restore.md#constrain-package-versions-with-restore).* - -- `project.json`: Specify a version range directly with the dependency's version number. For example: - - ```json - "Newtonsoft.json": "[6, 7)" - ``` - -## NuGet CLI commands - -- `nuget install` does not work with `project.json`. -- `nuget restore`: with projects using `project.json`, generates a `project.lock.json` file and a `.nuget.props` file, if needed. (Both files can be omitted from source control.) The `` argument can point a `project.json` file and has the same behavior as pointing to a `packages.config` or project file. In the priority order for package folders, `%userprofile%\.nuget\packages` is searched first when using `project.json`. -- `nuget update`: On Mono, this command does not work with projects using `project.json`. - -## Dependency resolution with PackageReference - -*Originally in [Dependency resolution](../concepts/dependency-resolution.md#dependency-resolution-with-packagereference).* - -The behavior of PackageReference applies also to `project.json`. NuGet restore writes the dependency graph into a file named `project.lock.json` alongside `project.json`. - -## Managing dependency assets - -*Originally in [Dependency resolution](../concepts/dependency-resolution.md#managing-dependency-assets).* - -When using the `project.json` format, you can control which assets from dependencies flow into the top-level project. For details, see [project.json](project-json.md). - -## Excluding references - -*Originally in [Dependency resolution](../concepts/dependency-resolution.md#excluding-references).* - -- `project.json`: add `"exclude" : "all"` in the dependency for PackageC: - - ```json - { - "dependencies": { - "PackageC": { - "version": "1.0.0", - "exclude": "all" - } - } - } - ``` - -## Resolving incompatible package errors - -*Originally in [Dependency resolution](../concepts/dependency-resolution.md#resolving-incompatible-package-errors).* - -An added means of resolving errors: - -- **Not recommended**: as a temporary solution while you work with the package author, projects targeting `netcore`, `netstandard`, and `netcoreapp` can denote other frameworks as being compatible, thereby allowing packages targeting those other frameworks to be used. See [project.json imports](project-json.md#imports) and [MSBuild restore target PackageTargetFallback](../reference/msbuild-targets.md#packagetargetfallback). This can cause unexpected behaviors, so again, it's best to resolve package incompatibilities by working with the package author on an update. - -## Target frameworks - -*Originally in [Target frameworks](../reference/target-frameworks.md).* - -- [project.json](project-json.md): The `frameworks` node specifies the framework versions that the project can be compiled against. - -## Creating a package - -*Originally in [Creating a package](../create-packages/creating-a-package.md)* - -### Setting a package type - -With .NET Core 1.x, when a DotnetCliTool package is installed, Visual Studio places the package in the `project.json` `tools` node instead of the `dependencies` node. - -Package types are set in `project.json`. - -- `project.json`: Indicate the package type within a `packOptions.packageType` property json: - - ```json - { - // ... - "packOptions": { - "packageType": "DotnetCliTool" - } - } - ``` - -### Adding targets and props for MSBuild - -*Originally in [Create .NET Standard NuGet Packages with Visual Studio 2015](../guides/create-net-standard-packages-vs2015.md).* - -When using `project.json`, targets are not added to the project but are made available through the `project.lock.json`. - -### Package versioning - -*Originally in [Package versioning](../concepts/package-versioning.md).* - -When using the `project.json` format, NuGet also supports using a wildcard notation, \*, for Major, Minor, Patch, and pre-release suffix parts of the number. - -### NuGet.Config reference - -*Originally in [NuGet.Config reference](../reference/nuget-config-file.md).* - -`globalPackagesFolder` applies only to `project.json`. (Added note: also applies to PackageReference.) - -### nuspec file reference - -*Originally in [nuspec reference](../reference/nuspec.md).* - -The `` element is used instead of `` with `project.json`. - -### Package manager options control - -*Originally in [Package Manager UI reference](../consume-packages/install-use-packages-visual-studio.md).* - -Projects using `project.json` management format show only the **Show preview window** option. - -### Visual Studio Templates - -*Originally in [NuGet Packages in Visual Studio templates](../visual-studio-extensibility/visual-studio-templates.md).* - -Best practices: templates do not include a `project.json` file, and do not include or any references or content that would be added when NuGet packages are installed. \ No newline at end of file diff --git a/docs/archive/project-json-impact.md b/docs/archive/project-json-impact.md index 0363b82eb..98569678f 100644 --- a/docs/archive/project-json-impact.md +++ b/docs/archive/project-json-impact.md @@ -1,16 +1,19 @@ --- title: project.json impact on NuGet package authors description: Details on how the implementation of project.json in NuGet 3.x affects package authors, such as unsupported features, content, and package format. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 -ms.topic: conceptual +ms.topic: concept-article --- # Impact of project.json when creating packages > [!Important] -> This content is deprecated. Projects should use either the `packages.config` or PackageReference formats. +> This content is deprecated. Projects should use the PackageReference formats. +> Learn how to [migrate your project.json project to PackageReference](./project-json.md#migrate-projectjson-to-packagereference). +> Visual Studio 2026 automatically migrates project.json at solution load time. +> [.NET 10 SDK & NuGet.exe 7.0](../release-notes/NuGet-7.0.md) do not support project.json projects. The `project.json` system used in NuGet 3+ affects package authors in several ways as described in the following sections. diff --git a/docs/archive/project-json.md b/docs/archive/project-json.md index 9284cbd8c..6e039d251 100644 --- a/docs/archive/project-json.md +++ b/docs/archive/project-json.md @@ -1,15 +1,21 @@ --- title: project.json File Reference for NuGet description: In some project types, project.json maintains the list of NuGet packages used in the project. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 07/27/2017 ms.topic: reference --- # project.json reference -*NuGet 3.x+* +> [!Important] +> This content is deprecated. Projects should use the PackageReference formats. +> Learn how to [migrate your project.json project to PackageReference](#migrate-projectjson-to-packagereference). +> Visual Studio 2026 automatically migrates project.json at solution load time. +> [.NET 10 SDK & NuGet.exe 7.0](../release-notes/NuGet-7.0.md) do not support project.json projects. + +*NuGet 3.x* The `project.json` file maintains a list of packages used in a project, known as a package management format. It supersedes `packages.config` but is in turn superseded by [PackageReference](../consume-packages/package-references-in-project-files.md) with NuGet 4.0+. @@ -34,6 +40,38 @@ The [`project.lock.json`](#projectlockjson) file (described below) is also used } ``` +## Migrate project.json to PackageReference + +The migration between project.json and PackageReference is straightforward. + +### Automatic migration in Visual Studio 2026 + +Visual Studio 2026 and later automatically migrates project.json projects to PackageReference when you open a solution containing project.json projects. +The migration happens at solution load time: + +1. Open a solution containing project.json projects in Visual Studio 2026 or later. +1. Visual Studio automatically detects project.json files and migrates them to PackageReference format. +1. To check migration status, open the [Output Window](/visualstudio/ide/output-window) and select Show output from "Package Manager". +You should see messages like "Migrating project.json project..." followed by "Migration Succeeded" for each project. +Any errors will appear in the Error List. +1. A backup of the original project file and project.json file is created in a `Backup` folder in the root of the project directory. +1. The migration converts all package dependencies to PackageReference format in the project file. + + +### Manual migration in Visual Studio 2022 + +For Visual Studio 2022 and earlier, you can use the built-in migrator: + +1. Load the project.json project in Visual Studio. +1. Go to the solution explorer of the project.json project and find the dependencies node. +1. Right-click and select `Migrate project.json to PackageReference...` + +![Migrating from project.json to PackageReference](media/project-json-migrator.png) + +### Alternative migration methods + +Alternatively, you may use the [dotnet migrate](/dotnet/core/tools/dotnet-migrate) command-line tool, or do the migration manually by taking all of the content from the project.json file and replacing it with the equivalent [PackageReference syntax](../consume-packages/Package-References-in-Project-Files.md). + ## Dependencies Lists the NuGet package dependencies of your project in the following form: diff --git a/docs/archive/readme.md b/docs/archive/readme.md deleted file mode 100644 index 3b83194e7..000000000 --- a/docs/archive/readme.md +++ /dev/null @@ -1 +0,0 @@ -This folder a holding location for content being removed from the main documentation, typically material that applies to earlier versions that will likely be moved into a permanent archive location. \ No newline at end of file diff --git a/docs/concepts/Auditing-Packages.md b/docs/concepts/Auditing-Packages.md new file mode 100644 index 000000000..72d185b5a --- /dev/null +++ b/docs/concepts/Auditing-Packages.md @@ -0,0 +1,295 @@ +--- +title: Auditing package dependencies for security vulnerabilities +description: How to audit package dependencies for security vulnerabilities and acting on security audit reports. +author: JonDouglas +ms.author: jodou +ms.topic: how-to +ms.date: 10/01/2025 +--- + +# Auditing package dependencies for security vulnerabilities + +## About security audits + +A security audit for package managers like NuGet is a process that involves analyzing the security of the packages that are included in a software project. +This involves identifying vulnerabilities, evaluating risks, and making recommendations for improving security. +The audit can include a review of the packages themselves, as well as any dependencies and their associated risks. +The goal of the audit is to identify and mitigate any security vulnerabilities that could be exploited by attackers, such as code injection or cross-site scripting attacks. + +### Feature availability + +| NuGet | .NET SDK | Visual Studio | Feature | +|-------|----------|---------------|---------| +| [5.9](../release-notes/NuGet-5.9.md) | .NET 5 SDK (5.0.200) | N/A | [`dotnet list package --vulnerable`](#dotnet-list-package---vulnerable) | +| [6.8](../release-notes/NuGet-6.8.md) | .NET 8 SDK (8.0.100) | Visual Studio 2022 17.8 | [NuGetAudit](#running-a-security-audit-with-restore) for PackageReference | +| [6.10](../release-notes/NuGet-6.10.md) | N/A | Visual Studio 2022 17.10 | [NuGetAudit](#running-a-security-audit-with-restore) for packages.config| +| [6.11](../release-notes/NuGet-6.11.md) | .NET 8 SDK (8.0.400) | Visual Studio 2022 17.11 | [NuGetAuditSuppress](#excluding-advisories) for PackageReference | +| [6.12](../release-notes/NuGet-6.12.md) | .NET 9 SDK (9.0.100) | Visual Studio 2022 17.12 | [Audit sources](#audit-sources). [NuGetAuditSuppress](#excluding-advisories) for packages.config. | +| [7.0](../release-notes/NuGet-7.0.md) | .NET 10 SDK (10.0.100) | Visual Studio 2026 | [NuGetAuditMode default changes for .NET 10](#configuring-nuget-audit). [`dotnet package update --vulnerable`](#security-vulnerabilities-found-with-updates) | + +## Running a security audit with `restore` + +The `restore` command automatically runs when you do a common package operation such as loading a project for the first time, adding a new package, updating a package version, or removing a package from your project in your favorite IDE. +Your dependencies are checked against a list of known vulnerabilities provided by your [audit sources](#audit-sources). + +1. On the command line, navigate to your project or solution directory. +1. Run `restore` using your preferred tooling (i.e. dotnet, MSBuild, NuGet.exe, VisualStudio etc). +1. Review the warnings and address the known security vulnerabilities. + +### Configuring NuGet Audit + +Audit can be configured via MSBuild properties in a `.csproj` or MSBuild file being evaluated as part of your project. +We recommend that audit is configured at a repository level. + +| MSBuild Property | Default | Possible values | Notes | +|------------------|---------|-----------------|-------| +| NuGetAuditMode | See 1 below | `direct` and `all` | If you'd like to audit top-level dependencies only, you can set the value to `direct`. NuGetAuditMode is not applicable for packages.config projects. | +| NuGetAuditLevel | low | `low`, `moderate`, `high`, and `critical` | The minimum severity level to report. If you'd like to see `moderate`, `high`, and `critical` advisories (exclude `low`), set the value to `moderate` | +| NuGetAudit | true | `true` and `false` | If you wish to not receive security audit reports, you can opt-out of the experience entirely by setting the value to `false` | + +1. `NuGetAuditMode` defaults to `all` when a project targets `net10.0` or higher. + Otherwise `NuGetAuditMode` defaults to `direct`. + When a project multi-targets, if any one target framework selects `all`, then audit will use this value for all target frameworks. + +#### Audit Sources + +Restore downloads a server's [`VulnerabilityInfo` resource](../api/vulnerability-info.md) to check against the list of packages each project is using. +The list of sources are defined by [the `auditSources` element in NuGet.Config](../reference/nuget-config-file.md#auditsources), and [warning NU1905](#warning-codes) is raised if any of the audit sources do not provide any vulnerability info. +If `auditSources` is not defined or is cleared without adding any sources, then `packageSources` will be used and warning NU1905 is suppressed. + +Since a common mitigation for package substitution attacks is [to use a single package source that upstreams from nuget.org, so that NuGet is not configured to use nuget.org as a package source](Security-Best-Practices.md#nuget-feeds), audit sources can be used to use nuget.org (or any other source that provides vulnerability information) without also using it as a package source. + +The data source for nuget.org's vulnerability database is [GitHub Advisory Database](https://github.com/advisories?query=type%3Areviewed+ecosystem%3Anuget). +Note that the [V2 protocol is deprecated](../nuget-org/overview-nuget-org.md#api-endpoint-for-nugetorg), so if your nuget.config is still using the V2 endpoint, you must migrate to the V3 endpoint. + +```xml + + + + + + +``` + +**Note**: The table below lists features that support Audit Sources. + +| Introduced In | Feature Supporting Audit Sources | +| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| [NuGet 6.12, .NET 9.0.100 SDK, and Visual Studio 2022 17.12](../release-notes/NuGet-6.12.md) | Restore | +| [NuGet 6.14, .NET 9.0.300 SDK](../release-notes/NuGet-6.14.md) | `dotnet package list --vulnerable` | +| [NuGet 7.0 and Visual Studio 2026](../release-notes/NuGet-7.0.md) | NuGet AuditSources support in the Visual Studio Package Manager UI | + +### Warning codes + +| Warning Code | Reason | +|--------------|----------| +| [NU1900](../reference/errors-and-warnings/NU1900.md) | Error communicating with package source, while getting vulnerability information. | +| [NU1901](../reference/errors-and-warnings/NU1901-NU1904.md) | Package with low severity detected | +| [NU1902](../reference/errors-and-warnings/NU1901-NU1904.md) | Package with moderate severity detected | +| [NU1903](../reference/errors-and-warnings/NU1901-NU1904.md) | Package with high severity detected | +| [NU1904](../reference/errors-and-warnings/NU1901-NU1904.md) | Package with critical severity detected | +| [NU1905](../reference/errors-and-warnings/NU1905.md) | An audit source does not provide a vulnerability database | + +You can customize your build to treat these warnings as errors to [treat warnings as errors, or treat warnings not as errors](/dotnet/csharp/language-reference/compiler-options/errors-warnings#warningsaserrors-and-warningsnotaserrors). +For example, if you're already using `` to treat all (C#, NuGet, MSBuild, etc) warnings as errors, you can use `$(WarningsNotAsErrors);NU1901;NU1902;NU1903;NU1904` to prevent vulnerabilities discovered in the future from breaking your build. +Alternatively, if you want to keep low and moderate vulnerabilities as warnings, but treat high and critical vulnerabilities as errors, and you're not using `TreatWarningsAsErrors`, you can use `$(WarningsAsErrors);NU1903;NU1904`. + +> [!NOTE] +> MSBuild properties for message severity such as `NoWarn` and `TreatWarningsAsErrors` are not supported for packages.config projects. + +#### Excluding advisories + +You can exclude advisories by adding a new `NuGetAuditSuppress` MSBuild item for each advisory. +Define a `NuGetAuditSuppress` item with the `Include=` metadata set to the advisory URL you wish to suppress. + +```xml + + + +``` + +Similar to the other NuGet audit configuration properties, `NuGetAuditSuppress` items can be defined at the project or repository level. + +`NuGetAuditSuppress` is available for PackageReference projects starting from [NuGet 6.11, Visual Studio 17.11, and the .NET 8.0.400 SDK](../release-notes/NuGet-6.11.md). +It is available for packages.config from [Visual Studio 17.12 and NuGet 6.12](../release-notes/NuGet-6.12.md). + +##### When to exclude advisories + +In scenarios where you have analyzed a specific advisory and have determined that it either does not apply to your scenario, or you are comfortable with the risks it imposes, you can choose to exclude specific advisories from the audit report. +Note that this would completely suppress the advisories, even for packages that share the advisory that may not be part of your project. +`NuGetAuditSuppress` should be considered a last resort for managing advisories. + +## Actions when packages with known vulnerabilities are reported + +Getting a warning about packages with known vulnerabilities is only part of the process. +Once discovered, action needs to be taken to remove the potential vulnerability from your solution. + +The easiest case is when a package you reference directly has the known vulnerability. +In this situation, update the package version to one that fixes the vulnerability. + +Package vulnerabilities may be reported in both direct and transitive package references. +The action you take to resolve may be different because of that. + +### Security vulnerabilities found with updates + +If security vulnerabilities are found and updates are available for the package, you can do one of the following: + +- Edit the `.csproj` or other package version location (`Directory.Packages.props`) with a newer version containing a security fix. +- Use the NuGet package manager user interface in Visual Studio to update the individual package. +- Run the `dotnet package update --vulnerable` command to update all vulnerable packages in a project to the first version without known vulnerabilities. +- Run the `dotnet package update` or `dotnet package add` commands with the respective package ID to update to the latest version. Use [`dotnet add package` when using .NET 9 or earlier](/dotnet/core/whats-new/dotnet-10/sdk#more-consistent-command-order). +- Use the NuGet Model Context Protocol (MCP) server that has the ability to update packages in your project to versions that resolve known vulnerabilities. +See [Fixing package vulnerabilities](NuGet-MCP-Server.md#fixing-package-vulnerabilities) for more information. + +#### Transitive Packages + +Often a vulnerability will be in a transitive dependency. +Our recommendation is to prefer updates to packages "closest" to your direct references. +Though, there's nothing wrong with just upgrading the package with known vulnerability either. + +For example, say your project references package A. +Package A has a dependency on package B, which in turn has a dependency on package C. +In this example, we'll consider that package C version 1.0.0 has a known vulnerability, fixed in version 2.0.0. +Our recommendation is to first try upgrading package A. +If that doesn't resolve the audit warning, then try upgrading package B. +If that doesn't resolve the audit warning, then upgrade C directly. +To aid with this, you'll [need to find the transitive package path](#finding-the-transitive-package-path). + +In summary, if a known vulnerability exists in a top-level package's transitive dependencies, you have these options: + +- Check if the top-level package contains an update that does not have a transitive vulnerability and update that instead. +- Update the closest package to your direct references that does not reference a vulnerability. +- Add the fixed package version as a direct package reference. **Note:** Be sure to remove this reference when a new package version update becomes available and be sure to maintain the defined attributes for the expected behavior. +- Use [Central Package Management with the transitive pinning functionality](../consume-packages/Central-Package-Management.md#transitive-pinning). + Note that if you pack your project into your own package to share with others, [CPM with transitive pinning will cause packages to become dependencies](../consume-packages/Central-Package-Management.md#transitive-pinning-and-pack), even if your project doesn't directly call APIs on that package. +- [Suppress the advisory](#excluding-advisories) until it can be addressed. +- File an issue in the top-level package's tracker to request an update. + +##### Finding the transitive package path + +There are several ways to find the package path. +Which method you prefer depends on what tools you normally use during your development. + +###### dotnet nuget why + +On the command line, you can use the [`dotnet nuget why` command](/dotnet/core/tools/dotnet-nuget-why) to understand why transitive packages are being included in your project's package graph. + +![dotnet nuget why example](media/dotnet-nuget-why-1.png) + +###### Visual Studio Solution Explorer + +SDK style projects also provide the full package graph under the project's Dependency node. +It's also searchable! +Expand search options and enable “search external files”. + +![Visual Studio Solution Explorer Search Options](media/vs-solution-explorer-search-options-1.png) + +Search the package name, and it will show you all instances under each project's Dependencies node. + +![Visual Studio Solution Explorer Search Results](media/vs-solution-explorer-search-results-1.png) + +###### Visual Studio NuGet Package Manager UI + +When you look at the Installed tab in Visual Studio's package manager UI, when the project uses PackageReference for package management, it will show both direct and transitive packages. +Currently, this only happens when you manage packages for a project, not for the solution. + +If you mouse hover over a package in the package list, the tooltip will include the name of one direct package that has caused that transitive package to be included in the project. + +![Visual Studio Package Manager UI tooltip](media/pm-ui-transitive-tooltip-1.png) + +### Security vulnerabilities found with no updates + +In the case that a known vulnerability exists in a package without a security fix, you can do the following. + +- Check for any mitigating factors outlined in the advisory report. +- Use a suggested package if the package is marked deprecated or is abandoned. +- If the package is open source, consider contributing a fix. +- Open an issue in the package's issue tracker. + +#### Check for mitigating factors + +Review the security advisor for any mitigating factors that may allow you to continue using the package with the vulnerability. +The vulnerability may only exist when the code is used on a specific framework, operating system, or a special function is called. + +#### Use a suggested package + +In the case that a security advisory is reported for the package you're using and the package is marked deprecated or seems abandoned, consider using any suggested alternate package the package author has declared or a package comprising of similar functionality that is maintained. + +#### Contribute a fix + +If a fix does not exist for the security advisory, you may want to suggest changes that addresses the vulnerability in a pull request on package's open source repository or contact the author through the `Contact owners` section on the NuGet.org package detail page. + +#### Open an issue + +If you do not want to fix the vulnerability or are unable to update or replace the package, open an issue in the package's issue tracker or preferred contact method. +On NuGet.org, you can navigate to the package details page and click `Report package` which will guide you to get in contact with the author. + +### No security vulnerabilities found + +If no security vulnerabilities are found, this means that packages with known vulnerabilities were not found in your package graph at the present moment of time you checked. +Since the advisory database can be updated at any time, we recommend regularly checking your `dotnet restore` output and ensuring the same in your continuous integration process. + +## Running NuGet Audit in CI + +### Separating Errors from Warnings with a Dedicated Auditing Pipeline + +You can use MSBuild's conditional statements to configure a dedicated CI pipeline for running audits, without audit warnings being treated as errors in other pipelines or on local builds. +Depending on your CI system and team processes, you can have failed runs of the audit pipeline email the team, or you may have a dashboard where you can show a badge of the most recent run of the pipeline. + +Like many things in programming, there are multiple ways to achieve the outcome. +One option is to treat NuGet Audit warnings as errors only in an audit pipeline. + +```xml + + NU1900;NU1901;NU1902;NU1903;NU1904;NU1905 + $(WarningsAsErrors);$(NuGetAuditCodes) + $(WarningsNotAsErrors);$(NuGetAuditCodes) + +``` + +Then in your pipeline, you run restore specifying the property used by the condition. +For example, using GitHub Actions syntax: + +```yml +- name: Restore with NuGet Auditing + run: dotnet restore -p:AuditPipeline=true +``` + +The property name `AuditPipeline` is only an example, and you can customize it as you wish, as long as the name is the same in both the MSBuild condition and the command line. +MSBuild also uses environment variables when reading a property that has not yet been defined, so an environment variable is an alternative to the command line parameter. + +By using conditions to selectively cause NuGet Audit warnings to fail a restore, you can have a dedicated pipeline to check packages for known vulnerabilities, while preventing new security advisories from blocking your bug fixes at inconvenient times. +Keeping NuGet Audit warnings enabled for local builds allows developers to get a non-blocking notification about new security advisories and can encourage upgrading package versions to fix the vulnerabilities more quickly than waiting for someone to check the audit pipeline status. + +### Ensure restore audited projects + +NuGet in MSBuild 17.13 and .NET 9.0.200 added output properties `RestoreProjectCount`, `RestoreSkippedCount` and `RestoreProjectsAuditedCount` on the restore task. +This can be used to enforce that audit ran during a restore. +Note that these output properties are not available with [static graph restore](../reference/msbuild-targets.md#restoring-with-msbuild-static-graph-evaluation). + +Since MSBuild is a scripting language, this can be achieved a number of different ways, but also has the same restrictions as MSBuild has. +One example is to create a file *Directory.Solution.targets* in the same directory as your solution file, whose contents has a target similar to the following. +Note that *Directory.Build.props* is commonly used, but is imported by projects. +However, NuGet's restore target and task runs at the solution level, so needs to be in MSBuild's solution extensibility file, not the project/build file. + +```xml + + + + + +``` + +Depending on your use-case, you may wish to use condition `'$(RestoreProjectCount)' != '$([MSBuild::Add($(RestoreProjectsAuditedCount), $(RestoreSkippedCount))'` on the error message, to account for projects that restore skipped because they were already up to date. +Similarly, think about if you want this error to happen everywhere, or only in CI pipelines, and what environment variables are defined in your CI environment, and factor this into the target's condition. +Again, since MSBuild is a scripting language, you can use any of its capabilities to customize your repo however you want. +Viewing [MSBuild's metaproj](/visualstudio/msbuild/how-to-build-specific-targets-in-solutions-by-using-msbuild-exe#troubleshooting) and [binlogs](/visualstudio/msbuild/msbuild-command-line-reference#switches-for-loggers) are useful to develop and troubleshoot solution level targets. + +## `dotnet list package --vulnerable` + +[`dotnet list package`](/dotnet/core/tools/dotnet-list-package) has a `--vulnerable` argument to filter the packages based on which packages have known vulnerabilities. +Note that `--include-transitive` is not default, so should be included. diff --git a/docs/concepts/Dependency-Resolution.md b/docs/concepts/Dependency-Resolution.md index 2f738f058..97f63ebae 100644 --- a/docs/concepts/Dependency-Resolution.md +++ b/docs/concepts/Dependency-Resolution.md @@ -1,10 +1,10 @@ --- title: NuGet Package Dependency Resolution description: Details on the process through which a NuGet package's dependencies are resolved and installed in both NuGet 2.x and NuGet 3.x+. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 08/14/2017 -ms.topic: conceptual +ms.topic: article --- # How NuGet resolves package dependencies @@ -17,19 +17,20 @@ When multiple packages have the same dependency, then the same package ID can ap ## Dependency resolution with PackageReference -When installing packages into projects using the PackageReference format, NuGet adds references to a flat package graph in the appropriate file and resolves conflicts ahead of time. This process is referred to as *transitive restore*. Reinstalling or restoring packages is then a process of downloading the packages listed in the graph, resulting in faster and more predictable builds. You can also take advantage of wildcard (floating) versions, such as 2.8.\*, avoiding expensive and error prone calls to `nuget update` on the client machines and build servers. +When installing packages into projects using the PackageReference format, NuGet adds references to a flat package graph in the appropriate file and resolves conflicts ahead of time. This process is referred to as *transitive restore*. Reinstalling or restoring packages is then a process of downloading the packages listed in the graph, resulting in faster and more predictable builds. -When the NuGet restore process runs prior to a build, it resolves dependencies first in memory, then writes the resulting graph to a file called `project.assets.json`. It also writes the resolved dependencies to a lock file named `packages.lock.json`, if the [lock file functionality is enabled](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#locking-dependencies). -The assets file is located at `MSBuildProjectExtensionsPath`, which defaults to the project's 'obj' folder. +You can also take advantage of floating versions, such as 2.8.\*, to avoid modifying the project to use the latest version of a package. When using floating versions, we recommend enabling the [lock file functionality](../consume-packages/package-references-in-project-files.md#locking-dependencies) to ensure repeatability. + +When the NuGet restore process runs prior to a build, it resolves dependencies first in memory, then writes the resulting graph to a file called `project.assets.json`. + +The assets file is located at `MSBuildProjectExtensionsPath`, which defaults to the project's 'obj' folder. MSBuild then reads this file and translates it into a set of folders where potential references can be found, and then adds them to the project tree in memory. The `project.assets.json` file is temporary and should not be added to source control. It's listed by default in both `.gitignore` and `.tfignore`. See [Packages and source control](../consume-packages/packages-and-source-control.md). ### Dependency resolution rules -Transitive restore applies four main rules to resolve dependencies: lowest applicable version, floating versions, nearest-wins, and cousin dependencies. - - +Transitive restore applies four main rules to resolve dependencies: [lowest applicable version](#lowest-applicable-version), [floating versions](#floating-versions), [direct-dependency-wins](#direct-dependency-wins), and [cousin dependencies](#cousin-dependencies). #### Lowest applicable version @@ -37,60 +38,95 @@ The lowest applicable version rule restores the lowest possible version of a pac In the following figure, for example, 1.0-beta is considered lower than 1.0 so NuGet chooses the 1.0 version: -![Choosing the lowest applicable version](media/projectJson-dependency-1.png) +![Choosing the lowest applicable version](media/lowest-applicable-version-1.png) In the next figure, version 2.1 is not available on the feed but because the version constraint is >= 2.1 NuGet picks the next lowest version it can find, in this case 2.2: -![Choosing the next lowest version available on the feed](media/projectJson-dependency-2.png) +![Choosing the next lowest version available on the feed](media/lowest-applicable-version-2.png) When an application specifies an exact version number, such as 1.2, that is not available on the feed, NuGet fails with an error when attempting to install or restore the package: -![NuGet generates an error when an exact package version is not available](media/projectJson-dependency-3.png) +![NuGet generates an error when an exact package version is not available](media/lowest-applicable-version-3.png) - +#### Floating versions -#### Floating (wildcard) versions +A floating dependency version is specified with the \* character. For example, `6.0.*`. This version specification says "use the latest 6.0.x version"; `4.*` means "use the latest 4.x version." Using a floating version reduces changes to the project file, while keeping up to date with the latest version of a dependency. +Floating versions can only be specified at the project level. -A floating or wildcard dependency version is specified with the \* wildcard, as with 6.0.\*. This version specification says "use the latest 6.0.x version"; 4.\* means "use the latest 4.x version." Using a wildcard allows a dependency package to continue evolving without requiring a change to the consuming application (or package). +When using a floating version, NuGet resolves the highest version of a package that matches the version pattern, for example `6.0.*` gets the highest version of a package that starts with 6.0: -When using a wildcard, NuGet resolves the highest version of a package that matches the version pattern, for example 6.0.\* gets the highest version of a package that starts with 6.0: +![Choosing version 6.0.1 when a floating version 6.0.* is requested](media/floating-versions-1.png) -![Choosing version 6.0.1 when a floating version 6.0.* is requested](media/projectJson-dependency-4.png) +| Version | Versions present on server | Resolution | Reason | Notes | +|----------|--------------|-------------|-------------|-------------| +| * | 1.1.0
1.1.1
1.2.0
1.3.0-alpha | 1.2.0 | The highest stable version. | +| 1.1.* | 1.1.0
1.1.1
1.1.2-alpha
1.2.0-alpha | 1.1.1 | The highest stable version that respects the specified pattern.| +| \*-\* | 1.1.0
1.1.1
1.1.2-alpha
1.3.0-beta | 1.3.0-beta | The highest version including the not stable versions. | Available in Visual Studio version 16.6, NuGet version 5.6, .NET Core SDK version 3.1.300 | +| 1.1.\*-\* | 1.1.0
1.1.1
1.1.2-alpha
1.1.2-beta
1.3.0-beta | 1.1.2-beta | The highest version respecting the pattern and including the not stable versions. | Available in Visual Studio version 16.6, NuGet version 5.6, .NET Core SDK version 3.1.300 | +| 1.2.0-rc.* | 1.1.0
1.2.0-rc.1
1.2.0-rc.2
1.2.0 | 1.2.0 | Despite this being a version range with a prerelease part, stables are allowed if they match the stable part. Given that 1.2.0 > 1.2.0-rc.2, it is chosen. | | > [!Note] -> For information on the behavior of wildcards and pre-release versions, see [Package versioning](package-versioning.md#version-ranges-and-wildcards). +> Floating version resolution does not take into account whether or not a package is listed. +> Floating version resolution will be resolved locally if the conditions can be satisfied with packages in the Global Package Folder. + +#### Direct dependency wins +When the package graph for an application contains different versions of a package in the same subgraph, and one of those versions is a direct dependency in that subgraph, that version would be chosen for that subgraph and the rest will be ignored. +This behavior allows an application to override any particular package version in the dependency graph. - +In the example below, the application depends directly on Package B with a version constraint of >=2.0.0. The application also depends on Package A which in turn also depends on Package B, but with a >=1.0.0 constraint. Because the dependency on Package B 2.0.0 is direct dependency to the application in the graph, that version is used: -#### Nearest wins +![Application using the Direct dependency wins rule](media/direct-dependency-1.png) -When the package graph for an application contains different versions of the same package, NuGet chooses the package that's closest to the application in the graph and ignores all others. This behavior allows an application to override any particular package version in the dependency graph. +>[!Warning] +> The Direct dependency wins rule can result in a downgrade of the package version, thus potentially breaking other dependencies in the graph. When a package is downgraded, NuGet adds a [warning to alert the user](..\reference\errors-and-warnings\NU1605.md). -In the example below, the application depends directly on Package B with a version constraint of >=2.0. The application also depends on Package A which in turn also depends on Package B, but with a >=1.0 constraint. Because the dependency on Package B 2.0 is nearer to the application in the graph, that version is used: +This rule also results in greater efficiency with a large dependency graph. +When a closer dependency in the same subgraph has a higher version than a further one, then NuGet ignores that dependency, and NuGet also ignores all remaining dependencies on that branch of the graph. -![Application using the Nearest Wins rule](media/projectJson-dependency-5.png) +In the diagram below, for example, because Package C 2.0.0 is used, NuGet ignores any branches in that subgraph that refer to an earlier version of Package C: ->[!Warning] -> The Nearest Wins rule can result in a downgrade of the package version, thus potentially breaking other dependencies in the graph. Hence this rule is applied with a warning to alert the user. +![When NuGet ignores a package in the graph, it ignores that entire branch](media/direct-dependency-2.png) -This rule also results in greater efficiency with a large dependency graph (such as those with the BCL packages) because once a given dependency is ignored, NuGet also ignores all remaining dependencies on that branch of the graph. In the diagram below, for example, because Package C 2.0 is used, NuGet ignores any branches in the graph that refer to an older version of Package C: +Through this rule, NuGet tries to honor the intent of the package author. +In the diagram below, the author of Package A has explicitly downgraded to Package C 1.0.0 from Package C 2.0.0. -![When NuGet ignores a package in the graph, it ignores that entire branch](media/projectJson-dependency-6.png) +![When a package author explicitly downgrades, NuGet honors that.](media/direct-dependency-3.png) - +The application owner can choose to upgrade Package C to a version higher than 2.0.0, thus no further downgrading the version for Package C. In this case, no warning is raised. + +![When an application honor adds a direct dependency for a downgraded package, NuGet honors that.](media/direct-dependency-4.png) #### Cousin dependencies -When different package versions are referred to at the same distance in the graph from the application, NuGet uses the lowest version that satisfies all version requirements (as with the [lowest applicable version](#lowest-applicable-version) and [floating versions](#floating-versions) rules). In the image below, for example, version 2.0 of Package B satisfies the other >=1.0 constraint, and is thus used: +When different package versions are referred in different subgraphs in the graph from the application, NuGet uses the lowest version that satisfies all version requirements (as with the [lowest applicable version](#lowest-applicable-version) and [floating versions](#floating-versions) rules). In the image below, for example, version 2.0.0 of Package B satisfies the other >=1.0.0 constraint, and is thus used: + +![Resolving cousin dependencies using the lower version that satisfies all constraints](media/cousin-dependencies-1.png) -![Resolving cousin dependencies using the lower version that satisfies all constraints](media/projectJson-dependency-7.png) +Note that the packages do not need to be on the same distance for the cousin dependencies rule to apply. In the diagram below, Package D 2.0.0 is chosen in the Package C subgraph and Package D 3.0.0 is chosen in the subgraph of Package A. In the Application subgraph, there is no direct dependency to Package D, so the the [lowest applicable version](#lowest-applicable-version) rule is applied and version 3.0.0 is chosen. -In some cases, it's not possible to meet all version requirements. As shown below, if Package A requires exactly Package B 1.0 and Package C requires Package B >=2.0, then NuGet cannot resolve the dependencies and gives an error. +![Resolving cousin dependencies using the lower version that satisfies all constraints at different distances](media/cousin-dependencies-2.png) -![Unresolvable dependencies due to an exact version requirement](media/projectJson-dependency-8.png) +In some cases, it's not possible to meet all version requirements. As shown below, if Package A requires exactly Package B 1.0.0 and Package C requires Package B >=2.0.0, then NuGet cannot resolve the dependencies and gives an error. -In these situations, the top-level consumer (the application or package) should add its own direct dependency on Package B so that the [Nearest Wins](#nearest-wins) rule applies. +![Unresolvable dependencies due to an exact version requirement](media/cousin-dependencies-3.png) + +In these situations, the top-level consumer (the application or package) should add its own direct dependency on Package B so that the [Direct dependency wins](#direct-dependency-wins) rule applies. + +### Version ranges and prerelease versions with PackageReference + +It is not unusual for a package to have both stable and prerelease versions available. +When resolving a dependency graph, NuGet decides whether to consider prerelease versions for a package based on a single rule: +`If the project or any packages within the graph request a prerelease version of a package, then include both prerelease or stable versions, otherwise consider stable versions only.` + +In practice, under the lowest applicable rule, this means: + +| Version Range | Available versions | Selected version | +|---------------|--------------------|------------------| +| [1.0.0, 2.0.0) | 1.2.0-beta.1, 1.2.0, | 1.2.0 | +| [1.0.0, 2.0.0-0) | 1.2.0-beta.1, 1.2.0, | 1.2.0-beta.1 | +| [1.0.0, 2.0.0) | 1.2.0-beta.1, 2.0.0-beta.3 | None, [NU1103](../reference/errors-and-warnings/NU1103.md) is raised. | +| [1.0.0, 2.0.0-rc) | 1.2.0-beta.1, 2.0.0-beta.3 | 1.2.0-beta.1 | ## Dependency resolution with packages.config @@ -98,10 +134,15 @@ With `packages.config`, a project's dependencies are written to `packages.config With `packages.config`, NuGet attempts to resolve dependency conflicts during the installation of each individual package. That is, if Package A is being installed and depends on Package B, and Package B is already listed in `packages.config` as a dependency of something else, NuGet compares the versions of Package B being requested and attempts to find a version that satisfies all version constraints. Specifically, NuGet selects the lower *major.minor* version that satisfies dependencies. -By default, NuGet 2.8 looks for the lowest patch version (see [NuGet 2.8 release notes](../release-notes/nuget-2.8.md#patch-resolution-for-dependencies)). You can control this setting through the `DependencyVersion` attribute in `Nuget.Config` and the `-DependencyVersion` switch on the command line. +By default, NuGet 2.8 looks for the lowest patch version (see [NuGet 2.8 release notes](../release-notes/nuget-2.8.md#patch-resolution-for-dependencies)). You can control this setting through the `DependencyVersion` attribute in `NuGet.Config` and the `-DependencyVersion` switch on the command line. The `packages.config` process for resolving dependencies gets complicated for larger dependency graphs. Each new package installation requires a traversal of the whole graph and raises the chance for version conflicts. When a conflict occurs, installation is stopped, leaving the project in an indeterminate state, especially with potential modifications to the project file itself. This is not an issue when using other package management formats. +### Version ranges and prerelease versions with packages.config + +packages.config resolution does not allow mixing of stable and pre-release dependency in a graph. +If a dependency is expressed with a range like `[1.0.0, 2.0.0)`, pre-release packages are not allowed in the graph. + ## Managing dependency assets When using the PackageReference format, you can control which assets from dependencies flow into the top-level project. For details, see [PackageReference](../consume-packages/package-references-in-project-files.md#controlling-dependency-assets). @@ -153,3 +194,4 @@ To resolve incompatibilities, do one of the following: - Retarget your project to a framework that is supported by the packages you want to use. - Contact the author of the packages and work with them to add support for your chosen framework. Each package listing page on [nuget.org](https://www.nuget.org/) has a **Contact Owners** link for this purpose. +[!INCLUDE [nugetsolver-tool](../includes/nugetsolver-tool.md)] diff --git a/docs/concepts/MSBuild-props-and-targets.md b/docs/concepts/MSBuild-props-and-targets.md new file mode 100644 index 000000000..1f40da97a --- /dev/null +++ b/docs/concepts/MSBuild-props-and-targets.md @@ -0,0 +1,78 @@ +--- +title: MSBuild props and targets in a package +description: Describes MSBuild props and targets in NuGet packages +author: nkolev92 +ms.author: nikolev +ms.date: 07/13/2022 +ms.topic: article +--- + +# MSBuild .props and .targets in a package + +In additional to the more traditional assemblies, NuGet packages may sometimes add custom build targets or properties to projects that consume that package. +This can be achieved by adding a valid MSBuild file, in the form `.targets` or `.props` (such as `Contoso.Utility.UsefulStuff.targets`) within the build folders of the project. + +## Build folders + +As NuGet has evolved, various different folders for build `.props` and `.targets` have been added. + +| Folder | NuGet Version | Use | +|--------|---------------|-----| +| build | 2.5+ | Build logic for every framework of a project. | +| buildMultiTargeting | 4.0+ | Build logic for the `outer build` for projects that target multiple frameworks. PackageReference only. | +| buildTransitive | 5.0+ | Build logic for assets that flow transitively to any consuming project. See the [feature](https://github.com/NuGet/Home/wiki/Allow-package--authors-to-define-build-assets-transitive-behavior) page. PackageReference only. | + +## Framework specific build folder + +All 3 build folder follow the same pattern for deciding the most suitable file based on the project target framework. + +Files in the root build folder, `build/.targets` and `build/.props` are considered suitable for all target frameworks. + +To provide framework-specific files, first place them within appropriate subfolders, such as the following: + +```text + \build + \netstandard1.4 + \Contoso.Utility.UsefulStuff.props + \Contoso.Utility.UsefulStuff.targets + \net462 + \Contoso.Utility.UsefulStuff.props + \Contoso.Utility.UsefulStuff.targets +``` + +Prefer using framework-specific build folders whenever appropriate to avoid false positive installations in projects that may not be supported by your package. + +Note that if a package does not have any files in the `lib` or `ref` folders and only files under a framework specific build folder, that package will be considered compatible with all projects. Up to date versions of the pack tooling, raise the [NU5127](..\reference\errors-and-warnings\NU5127.md) warning when such packages are created. + +## Projects consuming packages with build files + +### PackageReference projects + +`.props` and `.targets` are not added to the project file but are instead made available through `{projectName}.nuget.g.targets` and `{projectName}.nuget.g.props`. These files are automatically generated when restore is run. + +When a project targets more than one framework, the imports to these files are conditioned on the target framework name. + +MSBuild `.props` and `.targets` files for multi-framework targeting can be placed in the `\buildMultiTargeting` folder. +When the imports are generated, a condition that the MSBuild property `$(TargetFramework)` is empty is set. + +### packages.config projects + +When NuGet installs a package with `\build` files, it adds MSBuild `` elements in the project file pointing to the `.targets` and `.props` files. (`.props` is added at the top of the project file; `.targets` is added at the bottom.) A separate conditional MSBuild `` element is added for each target framework. + +## Authoring packages with MSBuild props and targets + +You can use any of the following tools to include MSBuild `.props` and `.targets` in your package. + +- [NuGet.exe pack](..\create-packages\Creating-a-Package.md#include-msbuild-props-and-targets-in-a-package) +- [dotnet.exe pack](..\create-packages\creating-a-package-dotnet-cli.md) +- [MSBuild.exe pack](..\create-packages\creating-a-package-msbuild.md) + +### Guidance for the content of MSBuild props and targets + +NuGet does not limit how you author `.props` and `.targets` as they will vary based on the need of the package author and the target projects themselves. + +There are a few things that must not be done in packages' `.props` and `.targets`, such as not specifying properties and items that affect restore, as those will be automatically excluded. + +- Some examples of properties that must not be added or updated: TargetFramework, TargetFrameworkMoniker, TargetPlatformMoniker, AssetTargetFallback etc. + +- Some examples of items that must not be added or updated: PackageReference, PackageVersion, PackageDownload, etc. diff --git a/docs/concepts/NuGet-MCP-Server.md b/docs/concepts/NuGet-MCP-Server.md new file mode 100644 index 000000000..ccbd97e63 --- /dev/null +++ b/docs/concepts/NuGet-MCP-Server.md @@ -0,0 +1,182 @@ +--- +title: Using the NuGet Model Context Protocol (MCP) Server +description: How to configure and use the NuGet Model Context Protocol (MCP) server. +author: jeffkl +ms.author: jeffkl +ms.topic: conceptual +ms.date: 10/01/2025 +--- + +# Using the NuGet Model Context Protocol (MCP) Server + +## Requirements + +To run the MCP server, you must have **[.NET 10 SDK or later](https://dotnet.microsoft.com/en-us/download/dotnet/10.0)** installed. +This version of .NET adds a command, `dnx`, which is used to download, install, and run the MCP server from [nuget.org](https://nuget.org). + +To verify your .NET version, run the following command in your terminal: +```bash +dotnet --info +``` + +## Getting started in Visual Studio 2026 + +In Visual Studio 2026, the NuGet MCP server is built-in but must be enabled once in order to use its functionality. + +To enable the NuGet MCP server, follow these steps: +1. Open Visual Studio 2026. +1. Open the GitHub Copilot Chat window and make sure you are signed in. +1. Click the tools icon in the bottom toolbar to bring up the Tools menu. +1. Find the MCP server named "nuget" and check the box to enable it. + +![GitHub Copilot Chat Tools window in Visual Studio 2026](./media/copilot-tools-menu.png) + +## Getting started in Visual Studio 2022 + +> [!NOTE] +> You must have Visual Studio 2022 17.14 or later in order to configure an MCP server. + +In Visual Studio 2022, you must manually add the NuGet MCP server to your configuration. +There are several configuration files that Visual Studio 2022 uses to define MCP servers. +See [Use MCP Servers](/visualstudio/ide/mcp-servers) for more information on which file to configure. + +Once you have identified the correct configuration file, add the following JSON snippet to your `mcp.json`: +```json +{ + "servers": { + "nuget": { + "type": "stdio", + "command": "dnx", + "args": [ "NuGet.Mcp.Server", "--source", "https://api.nuget.org/v3/index.json", "--yes" ] + } + } +} +``` + +This will configure Visual Studio 2022 to use the latest version of the NuGet MCP server from nuget.org. +To verify that the MCP server is working correctly, open the GitHub Copilot Chat window and make sure you are signed in. +Then click the Tools icon in the bottom toolbar to bring up the Tools menu. +You should see the MCP server named "nuget" in the list of available servers. + +![GitHub Copilot Chat Tools window in Visual Studio 2022](./media/copilot-tools-menu-2022.png) + +## Getting started in VS Code + +To configure the NuGet MCP server in VS Code click the appropriate button below and it will be set up. + +[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)]( +https://vscode.dev/redirect/mcp/install?name=NuGet&config=%7B%22name%22%3A%22NuGet.Mcp.Server%22%2C%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22NuGet.Mcp.Server%22%2C%22https%3A%2F%2Fapi.nuget.org%2Fv3%2Findex.json%22%2Cnull%2Cnull%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=NuGet&config=%7B%22name%22%3A%22NuGet.Mcp.Server%22%2C%22command%22%3A%22dnx%22%2C%22args%22%3A%5B%22NuGet.Mcp.Server%22%2C%22https%3A%2F%2Fapi.nuget.org%2Fv3%2Findex.json%22%2Cnull%2Cnull%5D%7D&quality=insiders) + +> ![GitHub Copilot Chat Tools window in VS Code](./media/copilot-tools-menu-vs-code.png) + +To verify that the MCP server is working correctly, open the GitHub Copilot Chat window and make sure you are signed in. +Then click the Tools icon in the bottom toolbar to bring up the Tools menu. +You should see the MCP server named "nuget" in the list of available servers. + +## Getting started in GitHub Copilot Agent + +You can also configure the MCP Server to work with GitHub Copilot as a Coding Agent in your repositories. +Ensure that you configured your repository to use [GitHub Copilot Coding Agents](https://github.com/settings/copilot/coding_agent). + +Browse to your repository and click the Settings tab. +Expand the Copilot section and click on Coding Agents. + +![GitHub Copilot coding agent settings](./media/github-copilot-agent-settings.png) + +Scroll down to the **Model Context Protocol (MCP)** section and add the following JSON snippet to your `mcpServers` configuration: + +```json +{ + "mcpServers": { + "NuGet": { + "type": "local", + "command": "dnx", + "args": ["NuGet.Mcp.Server", "--yes"], + "tools": ["*"], + "env": {} + } + } +} +``` + +This will make all of NuGet's MCP server tools available. If you want specific tools, you can list them in the `"tools"` parameter array. + +Finally, click the **Save MCP configuration** button to save your changes. + +Now that the NuGet MCP is configured, you will also need to create a GitHub Actions workflow to install .NET 10 Preview 6 or higher so that the `dnx` command is available to run the MCP server. +You can do this by creating the following workflow file in your repository at + +`.github/workflows/copilot-setup-steps.yml` + +The contents of this workflow file should be as follows: + +```yml +name: "Copilot Setup Steps" + +# Automatically run the setup steps when they are changed to allow for easy validation, and +# allow manual testing through the repository's "Actions" tab +on: + workflow_dispatch: + push: + paths: + - .github/workflows/copilot-setup-steps.yml + pull_request: + paths: + - .github/workflows/copilot-setup-steps.yml + +jobs: + # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot. + copilot-setup-steps: + runs-on: ubuntu-latest + + # Set the permissions to the lowest permissions possible needed for your steps. + # Copilot will be given its own token for its operations. + permissions: + # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete. + contents: read + + # You can define any steps you want, and they will run before the agent starts. + # If you do not check out your code, Copilot will do this for you. + steps: + - name: Install .NET 10.x + uses: actions/setup-dotnet@v5 + with: + dotnet-version: | + 10.x + dotnet-quality: preview + + - name: dotnet --info + run: dotnet --info +``` + +This will ensure that the `dnx` command is available to run the NuGet MCP server when GitHub Copilot runs as a coding agent in your repository. + +## Fixing package vulnerabilities + +The NuGet MCP server can help you identify and fix package vulnerabilities in your project. +To use the MCP server to fix vulnerabilities, enter the following prompt in the GitHub Copilot Chat window: + +> Fix my package vulnerabilities + +The MCP server will analyze your project's dependencies and suggest updates to packages that have known vulnerabilities. + +## Updating all packages + +The NuGet MCP server can also update your packages to the latest compatible versions. +To use the MCP server to update all packages, enter the following prompt in the GitHub Copilot Chat window: + +> Update all my packages to the latest compatible versions + +The MCP server will analyze your project's target framework(s) and suggest updates to the latest version of packages that are compatible with your project. + +## Update a package to a specific version + +The NuGet MCP server can update a specific package to a version you specify. +To do so, enter the following prompt in the GitHub Copilot Chat window: + +> Update the package [PackageName] to version [VersionNumber] + +## Support + +If you experience an issue with the NuGet MCP server or have any other feedback, please open an issue on the [NuGet GitHub repository](https://github.com/NuGet/Home/issues/new?template=MCPSERVER.yml). +Please provide the requested information in the issue template so that we can better understand and address your issue or suggestion. \ No newline at end of file diff --git a/docs/concepts/Package-Versioning.md b/docs/concepts/Package-Versioning.md index 1cdb27091..eb29a1da6 100644 --- a/docs/concepts/Package-Versioning.md +++ b/docs/concepts/Package-Versioning.md @@ -1,8 +1,8 @@ --- title: NuGet Package Version Reference description: Exact details on specifying version numbers and ranges for other packages upon which a NuGet package depends, and how dependencies are installed. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 03/23/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,11 +14,15 @@ A specific package is always referred to using its package identifier and an exa When creating a package, you assign a specific version number with an optional pre-release text suffix. When consuming packages, on the other hand, you can specify either an exact version number or a range of acceptable versions. +The following document follows the [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) standard, supported by NuGet 4.3.0+ and Visual Studio 2017 version 15.3+. +Certain [semantics of SemVer v2.0.0](#semantic-versioning-200) are not supported in older clients. + In this topic: - [Version basics](#version-basics) including pre-release suffixes. -- [Version ranges and wildcards](#version-ranges-and-wildcards) +- [Version ranges](#version-ranges) - [Normalized version numbers](#normalized-version-numbers) +- [Semantic Versioning 2.0.0](#semantic-versioning-200) ## Version basics @@ -27,14 +31,16 @@ A specific version number is in the form *Major.Minor.Patch[-Suffix]*, where the - *Major*: Breaking changes - *Minor*: New features, but backwards compatible - *Patch*: Backwards compatible bug fixes only -- *-Suffix* (optional): a hyphen followed by a string denoting a pre-release version (following the [Semantic Versioning or SemVer 1.0 convention](http://semver.org/spec/v1.0.0.html)). +- *-Suffix* (optional): a hyphen followed by a string denoting a pre-release version (following the [Semantic Versioning or SemVer](https://semver.org/) convention). **Examples:** - 1.0.1 - 6.11.1231 - 4.3.1-rc - 2.2.44-beta1 +``` +1.0.1 +6.11.1231 +4.3.1-rc +2.2.44-beta.1 +``` > [!Important] > nuget.org rejects any package upload that lacks an exact version number. The version must be specified in the `.nuspec` or project file used to create the package. @@ -49,57 +55,58 @@ That said, package developers generally follow recognized naming conventions: - `-beta`: Beta release, typically one that is feature complete for the next planned release, but may contain known bugs. - `-rc`: Release candidate, typically a release that's potentially final (stable) unless significant bugs emerge. -> [!Note] -> NuGet 4.3.0+ supports [SemVer 2.0.0](http://semver.org/spec/v2.0.0.html), which supports pre-release numbers with dot notation, as in *1.0.1-build.23*. Dot notation is not supported with NuGet versions before 4.3.0. You can use a form like *1.0.1-build23*. - -When resolving package references and multiple package versions differ only by suffix, NuGet chooses a version without a suffix first, then applies precedence to pre-release versions in reverse alphabetical order. For example, the following versions would be chosen in the exact order shown: +When ordering versions by precedence, NuGet follows the SemVer standard and chooses a version without a suffix first, then applies precedence to pre-release versions in reverse alphabetical order and treats dot notation numbers with numerical order. - 1.0.1 - 1.0.1-zzz - 1.0.1-rc - 1.0.1-open - 1.0.1-beta - 1.0.1-alpha2 - 1.0.1-alpha - 1.0.1-aaa - -## Semantic Versioning 2.0.0 - -With NuGet 4.3.0+ and Visual Studio 2017 version 15.3+, NuGet supports [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html). +> [!Note] +> Prerelease numbers with dot notation, as in *1.0.1-build.23*, are considered part of the [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html) standard, and as such are [only supported with NuGet 4.3.0+](#semantic-versioning-200). -Certain semantics of SemVer v2.0.0 are not supported in older clients. NuGet considers a package version to be SemVer v2.0.0 specific if either of the following statements is true: +### [SemVer 2.0 sorting](#tab/semver20sort) -- The pre-release label is dot-separated, for example, *1.0.0-alpha.1* -- The version has build-metadata, for example, *1.0.0+githash* +``` +1.0.1 +1.0.1-zzz +1.0.1-rc.10 +1.0.1-rc.2 +1.0.1-open +1.0.1-beta +1.0.1-alpha2 +1.0.1-alpha10 +1.0.1-aaa +``` -For nuget.org, a package is defined as a SemVer v2.0.0 package if either of the following statements is true: +Note that 1.0.1-alpha10 is sorted strictly in reverse alphabetical order, whereas 1.0.1-rc.10 is greater precedence than 1.0.1-rc.2. -- The package's own version is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, as defined above. -- Any of the package's dependency version ranges has a minimum or maximum version that is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, defined above; for example, *[1.0.0-alpha.1, )*. +### [SemVer 1.0 sorting](#tab/semver10sort) -If you upload a SemVer v2.0.0-specific package to nuget.org, the package is invisible to older clients and available to only the following NuGet clients: +``` +1.0.1 +1.0.1-zzz +1.0.1-open +1.0.1-beta05 +1.0.1-beta02 +1.0.1-beta +1.0.1-alpha2 +1.0.1-alpha10 +1.0.1-aaa +``` -- NuGet 4.3.0+ -- Visual Studio 2017 version 15.3+ -- Visual Studio 2015 with [NuGet VSIX v3.6.0](https://dist.nuget.org/visualstudio-2015-vsix/latest/NuGet.Tools.vsix) -- dotnet - - dotnetcore.exe (.NET SDK 2.0.0+) +Note that versions such as `1.0.1-rc.10` and `1.0.1-rc.2` are not parsable by older versions of the client, and such packages with those versions won't be available for download with those clients. -Third-party clients: +If you use numerical suffixes with pre-release tags that might use double-digit numbers (or more), use leading zeroes as in beta01 and beta05 to ensure that they sort correctly when the numbers get larger. +This recommendation only applies this schema. -- JetBrains Rider -- Paket version 5.0+ +Despite the ordering shown above, NuGet does not always consider both stable & prerelease packages during dependency resolution. Those rules are detailed in [Dependency Resolution](./Dependency-Resolution.md). - - +--- -## Version ranges and wildcards +## Version ranges When referring to package dependencies, NuGet supports using interval notation for specifying version ranges, summarized as follows: | Notation | Applied rule | Description | |----------|--------------|-------------| | 1.0 | x ≥ 1.0 | Minimum version, inclusive | +| [1.0,) | x ≥ 1.0 | Minimum version, inclusive | | (1.0,) | x > 1.0 | Minimum version, exclusive | | [1.0] | x == 1.0 | Exact version match | | (,1.0] | x ≤ 1.0 | Maximum version, inclusive | @@ -109,38 +116,43 @@ When referring to package dependencies, NuGet supports using interval notation f | [1.0,2.0) | 1.0 ≤ x < 2.0 | Mixed inclusive minimum and exclusive maximum version | | (1.0) | invalid | invalid | -When using the PackageReference format, NuGet also supports using a wildcard notation, \*, for Major, Minor, Patch, and pre-release suffix parts of the number. Wildcards are not supported with the `packages.config` format. - -> [!Note] -> Version ranges in PackageReference include pre-release versions. By design, floating versions do not resolve prerelease versions unless opted into. For the status of the related feature request, see [issue 6434](https://github.com/NuGet/Home/issues/6434#issuecomment-358782297). - -### Examples +### Best Practice -Always specify a version or version range for package dependencies in project files, `packages.config` files, and `.nuspec` files. Without a version or version range, NuGet 2.8.x and earlier chooses the latest available package version when resolving a dependency, whereas NuGet 3.x and later chooses the lowest package version. Specifying a version or version range avoids this uncertainty. +Always specify a version or version range for package dependencies in project files, `packages.config` files, and `.nuspec` files. Without a version or version range, when resolving a dependency, consistent restore results are not guaranteed. +Avoid specifying an upper bound to version ranges to packages you don't own unless you know of a compatibility problem. Upper bounds to version ranges harm adoption, discourage consumers from getting valuable updates to dependencies, and in some cases may lead them to use unsupported versions of dependencies. #### References in project files (PackageReference) ```xml - + - + - + + + + used to guarantee a dependency with a specific bug fix. + Will resolve to the smallest acceptable stable version.--> + recommended because it can be difficult to determine the lowest version. + Will resolve to the smallest acceptable stable version. + --> - + - + ``` @@ -202,21 +214,60 @@ The `version` attribute in a `` element describes the range versions ## Normalized version numbers > [!Note] -> This is a breaking change for NuGet 3.4 and later. +> This is a breaking change for NuGet 3.4+. When obtaining packages from a repository during install, reinstall, or restore operations, NuGet 3.4+ treats version numbers as follows: - Leading zeroes are removed from version numbers: - - 1.00 is treated as 1.0 - 1.01.1 is treated as 1.1.1 - 1.00.0.1 is treated as 1.0.0.1 + - 1.00 is treated as 1.0 + - 1.01.1 is treated as 1.1.1 + - 1.00.0.1 is treated as 1.0.0.1 - A zero in the fourth part of the version number will be omitted + - 1.0.0.0 is treated as 1.0.0 + - 1.0.01.0 is treated as 1.0.1 - 1.0.0.0 is treated as 1.0.0 - 1.0.01.0 is treated as 1.0.1 +- SemVer 2.0.0 build metadata is removed + - 1.0.7+r3456 is treated as 1.0.7 `pack` and `restore` operations normalize versions whenever possible. For packages already built, this normalization does not affect the version numbers in the packages themselves; it affects only how NuGet matches versions when resolving dependencies. However, NuGet package repositories must treat these values in the same way as NuGet to prevent package version duplication. Thus a repository that contains version *1.0* of a package should not also host version *1.0.0* as a separate and different package. + +## Semantic Versioning 2.0.0 + +Certain semantics of SemVer v2.0.0 are not supported in older clients. +NuGet considers a package version to be SemVer v2.0.0 specific if either of the following statements is true: + +- The pre-release label is dot-separated, for example, *1.0.0-alpha.1* +- The version has build-metadata, for example, *1.0.0+githash* + +For nuget.org, a package is defined as a SemVer v2.0.0 package if either of the following statements is true: + +- The package's own version is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, as defined above. +- Any of the package's dependency version ranges has a minimum or maximum version that is SemVer v2.0.0 compliant but not SemVer v1.0.0 compliant, defined above; for example, *[1.0.0-alpha.1, )*. + +If you upload a SemVer v2.0.0-specific package to nuget.org, the package is invisible to older clients and available to only the following NuGet clients: + +- NuGet 4.3.0+ +- Visual Studio 2017 version 15.3+ +- Visual Studio 2015 with [NuGet VSIX v3.6.0](https://dist.nuget.org/visualstudio-2015-vsix/latest/NuGet.Tools.vsix) +- .NET SDK 2.0.0+ + +Third-party clients: + +- JetBrains Rider +- Paket version 5.0+ + + + + +## Where NuGetVersion diverges from Semantic Versioning + +If you want to programatically use NuGet package versions, it is strongly recommended to use [the package NuGet.Versioning](https://www.nuget.org/packages/NuGet.Versioning). The static method `NuGetVersion.Parse(string)` can be used to parse the version strings, and `VersionComparer` can be used to sort `NuGetVersion` instances. + +If you are implementing NuGet functionality in a language that does not run on .NET, here are the known list of differences between `NuGetVersion` and Semantic Versioning, and the reasons why an existing Semantic Versioning library might not work for packages already published on nuget.org. + +1. `NuGetVersion` supports a 4th version segment, `Revision`, to be compatible with, or a superset of, [`System.Version`](/dotnet/api/system.version). Therefore, excluding prerelease and metadata labels, a version string is `Major.Minor.Patch.Revision`. As per version normalization described above, if `Revision` is zero, it is omitted from the normalized version string. +2. `NuGetVersion` only requires the major segment to be defined. All others are optional, and are equivalent to zero. This means that `1`, `1.0`, `1.0.0`, and `1.0.0.0` are all accepted and equal. +3. `NuGetVersion` uses case insensitive string comparisons for pre-release components. This means that `1.0.0-alpha` and `1.0.0-Alpha` are equal. diff --git a/docs/concepts/Security-Best-Practices.md b/docs/concepts/Security-Best-Practices.md new file mode 100644 index 000000000..d28f60fb0 --- /dev/null +++ b/docs/concepts/Security-Best-Practices.md @@ -0,0 +1,319 @@ +--- +title: Best practices for a secure software supply chain +description: Best practices for securing your software supply chain using NuGet & GitHub. +author: JonDouglas +ms.author: jodou +ms.topic: best-practice +--- + +# Best practices for a secure software supply chain + +Open Source is everywhere. +It is in many proprietary codebases and community projects. +For organizations and individuals, the question today is not whether you are or are not using open-source code, but what open-source code you are using, and how much. + +If you're not aware of what is in your software supply chain, an upstream vulnerability in one of your dependencies can be fatal, making you, and your customers, vulnerable to a potential compromise. +In this document, we will dive deeper into what the term “software supply chain” means, why it matters, and how you can help secure your project’s supply chain with best practices. + +![The State of the Octoverse 2020 - Open Source](media/opensource-percent.png) + +## Dependencies + +The term software supply chain is used to refer to everything that goes into your software and where it comes from. +It is the dependencies and properties of your dependencies that your software supply chain depends on. +A dependency is what your software needs to run. +It can be code, binaries, or other components, and where they come from, such as a repository or package manager. + +It includes who wrote the code, when it was contributed, how it was reviewed for security issues, known vulnerabilities, supported versions, license information, and just about anything that touches it at any point of the process. + +Your supply chain also encompasses other parts of your stack beyond a single application, such as your build and packaging scripts or the software that runs the infrastructure your application relies on. + +## Vulnerabilities + +Today, software dependencies are pervasive. +It is quite common for your projects to use hundreds of open-source dependencies for functionality that you did not have to write yourself. +This may mean that most of your application consists of code that you did not author. + +![The State of the Octoverse 2020 - Dependencies](media/dependencies.png) + +Possible vulnerabilities in your third-party or open-source dependencies, are presumably dependencies you cannot control as tightly as the code you write, which can create potential security risks in your supply chain. + +If one of these dependencies has a vulnerability, the chances are you have a vulnerability as well. +This can be scary as one of your dependencies may change without you even knowing. +Even if a vulnerability exists in a dependency today, but is not exploitable, it can be exploitable in the future. + +Being able to leverage the work of thousands of open-source developers and library authors means that thousands of strangers can effectively contribute directly to your production code. +Your product, through your software supply chain, is affected by unpatched vulnerabilities, innocent mistakes, or even malicious attacks against dependencies. + +## Supply chain compromises + +The traditional definition of a supply chain comes from manufacturing; it is the chain of processes required to make and supply something. +It includes planning, supply of materials, manufacturing, and retail. +A software supply chain is similar, except instead of materials, it is code. +Instead of manufacturing, it is development. +Instead of digging ore from the ground, code is sourced from suppliers, commercial or open source, and, in general, the open-source code comes from repositories. +Adding code from a repository means your product takes a dependency on that code. + +One example of a software supply chain attack occurs when malicious code is purposefully added to a dependency, using the supply chain of that dependency to distribute the code to its victims. +Supply chain attacks are real. +There are many methods to attack a supply chain, from directly inserting malicious code as a new contributor, to taking over a contributor’s account without others noticing, or even compromising a signing key to distribute software that is not officially part of the dependency. + +A software supply chain attack is in and of itself rarely the end goal, rather it is the beginning of an opportunity for an attacker to insert malware or provide a backdoor for future access. + +![The State of the Octoverse 2020 - Vulnerability Lifecycle](media/vulnerability-lifecycle.png) + +## Unpatched software + +The use of open source today is significant and is not expected to slow down anytime soon. +Given that we are not going to stop using open-source software, the threat to supply chain security is unpatched software. +Knowing that, how can you address the risk that a dependency of your project has a vulnerability? + +- **Knowing what is in your environment.** This requires discovering your dependencies and any transitive dependencies to understand the risks of those dependencies such as vulnerabilities or licensing restrictions. +- **Manage your dependencies.** When a new security vulnerability is discovered, you must determine whether you are impacted, and if so, update to the latest version and security patch available. + This is especially important to review changes that introduce new dependencies or regularly auditing older dependencies. +- **Monitor your supply chain.** This is by auditing the controls you have in place to manage your dependencies. + This will help you enforce more restrictive conditions to be met for your dependencies. + +![The State of the Octoverse 2020 - Advisories](media/advisories.png) + +We will cover various tools and techniques that NuGet and GitHub provides, which you can use today to address potential risks inside your project. + +## Knowing what is in your environment + +### Packages with known vulnerabilities + +**📦 Package Consumer | 📦🖊 Package Author** + +.NET 8 and Visual Studio 17.8 added [NuGetAudit](Auditing-Packages.md), which will warn about direct packages with known vulnerabilities during restore. +.NET 9 and Visual Studio 17.12 changed the default to warn about transitive packages as well. + +NuGetAudit requires a source to provide a known vulnerabilities database, so if you're not using nuget.org as a package source, you should add it as an [audit source](Auditing-Packages.md#audit-sources). + +By the time that NuGet is warning you, the vulnerability is publicly known. +Attackers can use this public disclosure to develop attacks for targets who have not patched their applications. +Therefore, when you get a warning that a package your project is using has a known vulnerability, you should quickly take action. + +### NuGet dependency graph + +**📦 Package Consumer** + +You can view your NuGet dependencies in your project by looking directly at the respective project file. + +This is typically found in one of two places: + +- [`packages.config`](../reference/packages-config.md) – Located in the project root. +- [``](../consume-packages/package-references-in-project-files.md) – Located in the project file. + +Depending on what method you use to manage your NuGet dependencies, you can also use Visual Studio to view your dependencies directly in [Solution Explorer](/visualstudio/ide/solutions-and-projects-in-visual-studio#solution-explorer) or [NuGet Package Manager](../consume-packages/install-use-packages-visual-studio.md). + +For CLI environments, you can use the [`dotnet list package` command](/dotnet/core/tools/dotnet-list-package) to list out your project or solution’s dependencies. +You can also use the [`dotnet nuget why` command](/dotnet/core/tools/dotnet-nuget-why) to understand why transitive packages (those not directly referenced by your project) are being included in your project's package graph. + +For more information on managing NuGet dependencies, [see the following documentation](../consume-packages/overview-and-workflow.md). + +### GitHub dependency graph + +**📦 Package Consumer | 📦🖊 Package Author** + +You can use GitHub’s dependency graph to see the packages your project depends on and the repositories that depend on it. +This can help you see any vulnerabilities detected in its dependencies. + +For more information on GitHub repository dependencies, [see the following documentation](https://github.co/dependency-graph). + +### Dependency versions + +**📦 Package Consumer | 📦🖊 Package Author** + +To ensure a secure supply chain of dependencies, you will want to ensure that all of your dependencies & tooling are regularly updated to the latest stable version as they will often include the latest functionality and security patches to known vulnerabilities. +Your dependencies can include code you depend on, binaries you consume, tooling you use, and other components. +This may include: + +- [Visual Studio](https://visualstudio.microsoft.com/downloads/) +- [.NET SDK & Runtime](https://dotnet.microsoft.com/download) +- [NuGet](https://www.nuget.org/downloads) +- [NuGet packages](../consume-packages/reinstalling-and-updating-packages.md) + +## Manage your dependencies + +### NuGet deprecated and vulnerable dependencies + +**📦 Package Consumer | 📦🖊 Package Author** + +You can use the [dotnet CLI](/dotnet/core/tools/dotnet-list-package) to list any known deprecated or vulnerable dependencies you may have inside your project or solution. +You can use the command `dotnet list package --deprecated` or `dotnet list package --vulnerable` to provide you a list of any known deprecations or vulnerabilities. +[NuGetAudit](Auditing-Packages.md) can warn you about known vulnerable dependencies, and is enabled by default when [a source provides a vulnerabilities database](Auditing-Packages.md#audit-sources). + +### GitHub vulnerable dependencies + +**📦 Package Consumer | 📦🖊 Package Author** + +If your project is hosted on GitHub, you can leverage [GitHub Security](https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/automatically-scanning-your-code-for-vulnerabilities-and-errors) to find security vulnerabilities and errors in your project and Dependabot will fix them by opening up a pull request against your codebase. + +Catching vulnerable dependencies before they are introduced is one goal of the [“Shift Left”](https://en.wikipedia.org/wiki/Shift-left_testing) movement. +Being able to have information about your dependencies such as their license, transitive dependencies, and the age of dependencies helps you do just that. + +For more information about Dependabot alerts & security updates, [see the following documentation](https://docs.github.com/en/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies). + +## NuGet Configuration + +**📦 Package Consumer** + +Add a `nuget.config` file in the root of your project repository. This is considered a best practice as it promotes repeatability and ensures that different users have the same NuGet configuration. +We recommend adding `clear` elements to ensure no user or machine specific configuration is applied. [Read more about how settings are applied](../consume-packages/configuring-nuget-behavior.md#how-settings-are-applied). + +For example: + +```xml + + + + + + + + + +``` + +### NuGet feeds + +**📦 Package Consumer** + +Use package sources that you trust. +When using multiple public & private NuGet source feeds, a package can be downloaded from any of the feeds. +To ensure your build is predictable and secure from known attacks such as [Dependency Confusion](https://medium.com/@alex.birsan/dependency-confusion-4a5d60fec610), knowing what specific feed(s) your packages are coming from is a best practice. +You can use a single feed or private feed with upstreaming capabilities for protection. + +For more information to secure your package feeds, see [3 Ways to Mitigate Risk When Using Private Package Feeds](https://azure.microsoft.com/resources/3-ways-to-mitigate-risk-using-private-package-feeds/en-us/). + +When using a private feed, refer to the [security best practices for managing credentials](../consume-packages/consuming-packages-authenticated-feeds.md#security-best-practices-for-managing-credentials). + +### Client trust policies + +**📦 Package Consumer** + +There are policies that you can opt-into in which you require the packages you use to be signed. +This allows you to trust a package author, as long as it is author signed, or trust a package if it is owned by a specific user or account that is repository signed by NuGet.org. + +To configure client trust policies, [see the following documentation](../consume-packages/installing-signed-packages.md). + +### Lock files + +**📦 Package Consumer** + +Lock files store the hash of your package’s content. +If the content hash of a package you want to install matches with the lock file, it will ensure package repeatability. + +To enable lock files, [see the following documentation](../consume-packages/package-references-in-project-files.md#locking-dependencies). + +### Package Source mapping + +**📦 Package Consumer** + +Package Source Mapping allows you to centrally declare which source each package in your solution should restore from in your nuget.config file. + +To enable package source mapping, [see the following documentation](../consume-packages/package-source-mapping.md). + +## Secure computers + +### Directory permissions + +**📦 Package Consumer** + +On Windows and Mac, and some Linux distributions, user account home directories are private by default. +However, some Linux distributions make user directories readable by other accounts on the same computer by default. +Additionally, there are [multiple configuration options to redirect NuGet's global packages folder and HTTP cache to non-default locations](../consume-packages/managing-the-global-packages-and-cache-folders.md). +Solutions, projects, and repositories might also be created outside of the user's home directory. + +If you use any packages that are not on nuget.org, then if any other account on the computer can read NuGet's global packages or HTTP cache directories, or the project's build output directory, then these packages might be disclosed to people who should not have access to those packages. + +On Linux, `dotnet nuget update source` will change *nuget.config* file permissions to make it only readable by the file owner. +However, if you edit the *nuget.config* file in any other way, and the file is in a location that other accounts can read the file, there might be information disclosure about package source URL or package source credentials. +You should ensure any nuget.config file cannot be read by other users of the same computer. + +### Solutions within the downloads directory + +**📦 Package Consumer** + +Extra care should be taken if working on solutions or projects in your downloads directory. +NuGet will [accumulate settings from multiple config files](../consume-packages/configuring-nuget-behavior.md), and MSBuild will typically import *Directory.Build.props*, *Directory.NuGet.props*, *Directory.Build.targets*, and potentially other files, from any parent directory, right up to the filesystem root. + +The downloads folder has additional risk, since it's usually the default location that web browsers will download files from the internet + +### Build Agents + +**📦 Package Consumer** + +Build agents (CI agents) that are not reset to an initial state after every build have multiple risks that must be considered. + +To learn about secure ways to manage credentials, [see the docs on consuming packages from authenticated feeds](../consume-packages/consuming-packages-authenticated-feeds.md). + +To learn about modifying the directories that NuGet stores data in, see [the docs on managing the global packages, cache, and temp folders](../consume-packages/managing-the-global-packages-and-cache-folders.md). +These directories should be configured to a directory that the CI agent cleans after every build. + +Note that any packages used by your project might be left in your project's build output directory. +If your project uses packages from authenticated sources, then other users of the same CI agent might gain unauthorized access to the package assemblies. +Therefore, you should also clean your repo at the end of your build, even when the build fails or is cancelled. + +## Monitor your supply chain + +### GitHub secret scanning + +**📦🖊 Package Author** + +GitHub scans repositories for NuGet API keys to prevent fraudulent uses of secrets that were accidentally committed. + +To learn more about secret scanning, see [About secret scanning](https://docs.github.com/en/github/administering-a-repository/about-secret-scanning). + +### Author Package Signing + +**📦🖊 Package Author** + +[Author signing](../reference/signed-packages-reference.md) allows a package author to stamp their identity on a package and for a consumer to verify it came from you. +This protects you against content tampering and serves as a single source of truth about the origin of the package and the package authenticity. +When combined with client trust policies, you can verify a package came from a specific author. + +To author sign a package, see [Sign a package](../create-packages/sign-a-package.md). + +### Reproducible Builds + +**📦🖊 Package Author** + +Reproducible builds creates binaries that are byte-for-byte identical each time you build it, and contain source code links and compiler metadata that enable a package consumer to recreate the binary directly and validate that the build environment has not been compromised. + +To learn more about reproducible builds, see [Producing Packages with Source Link](https://devblogs.microsoft.com/dotnet/producing-packages-with-source-link/) and the [Reproducible Build Validation](https://github.com/dotnet/designs/blob/main/accepted/2020/reproducible-builds.md) spec. + +### Two-Factor Authentication (2FA) + +**📦🖊 Package Author** + +Every account on nuget.org has 2FA enabled. +This adds an extra layer of security when [logging into your GitHub account](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa) or your [NuGet.org account](../nuget-org/individual-accounts.md#add-a-new-individual-account). + +### Package ID prefix reservation + +**📦🖊 Package Author** + +To protect the identity of your packages, you can reserve a package ID prefix with your respective namespace to associate a matching owner if your package ID prefix properly falls under the [specified criteria](../nuget-org/id-prefix-reservation.md#id-prefix-reservation-criteria). + +To learn about reserving ID prefixes, see [Package ID prefix reservation](../nuget-org/id-prefix-reservation.md). + +### Deprecating and unlisting a vulnerable package + +**📦🖊 Package Author** + +To protect the .NET package ecosystem when you are aware of a vulnerability in a package you have authored, do your best to deprecate and unlist the package so it is hidden from users searching for packages. +If you are consuming a package that is deprecated and unlisted, you should avoid using the package. + +To learn how to deprecate and unlist a package, see the following documentation on [deprecating](../nuget-org/deprecate-packages.md) and [unlisting packages](../nuget-org/policies/deleting-packages.md#unlisting-a-package). + +Also consider reporting the known to the [GitHub Advisories Database](https://github.com/advisories). + +## Summary + +Your software supply chain is anything that goes into or affects your code. +Even though supply chain compromises are real and growing in popularity, they are still rare; so the most important thing you can do is protect your supply chain by **being aware of your dependencies, managing your dependencies** and **monitoring your supply chain.** + +You learned about various methods that NuGet and [GitHub](/training/modules/maintain-secure-repository-github/) provide that are available to you today to be more effective in viewing, managing, and monitoring your supply chain. + +For more information about securing the world's software, see [The State of the Octoverse 2020 Security Report](https://octoverse.github.com/static/github-octoverse-2020-security-report.pdf). diff --git a/docs/concepts/media/advisories.png b/docs/concepts/media/advisories.png new file mode 100644 index 000000000..8856d78f8 Binary files /dev/null and b/docs/concepts/media/advisories.png differ diff --git a/docs/concepts/media/copilot-tools-menu-2022.png b/docs/concepts/media/copilot-tools-menu-2022.png new file mode 100644 index 000000000..3fe2bdfb5 Binary files /dev/null and b/docs/concepts/media/copilot-tools-menu-2022.png differ diff --git a/docs/concepts/media/copilot-tools-menu-vs-code.png b/docs/concepts/media/copilot-tools-menu-vs-code.png new file mode 100644 index 000000000..995a86948 Binary files /dev/null and b/docs/concepts/media/copilot-tools-menu-vs-code.png differ diff --git a/docs/concepts/media/copilot-tools-menu.png b/docs/concepts/media/copilot-tools-menu.png new file mode 100644 index 000000000..ec5033751 Binary files /dev/null and b/docs/concepts/media/copilot-tools-menu.png differ diff --git a/docs/concepts/media/cousin-dependencies-1.png b/docs/concepts/media/cousin-dependencies-1.png new file mode 100644 index 000000000..fc228e49e Binary files /dev/null and b/docs/concepts/media/cousin-dependencies-1.png differ diff --git a/docs/concepts/media/cousin-dependencies-2.png b/docs/concepts/media/cousin-dependencies-2.png new file mode 100644 index 000000000..e6314a155 Binary files /dev/null and b/docs/concepts/media/cousin-dependencies-2.png differ diff --git a/docs/concepts/media/cousin-dependencies-3.png b/docs/concepts/media/cousin-dependencies-3.png new file mode 100644 index 000000000..807623a38 Binary files /dev/null and b/docs/concepts/media/cousin-dependencies-3.png differ diff --git a/docs/concepts/media/dependencies.png b/docs/concepts/media/dependencies.png new file mode 100644 index 000000000..ee5ff5b9b Binary files /dev/null and b/docs/concepts/media/dependencies.png differ diff --git a/docs/concepts/media/direct-dependency-1.png b/docs/concepts/media/direct-dependency-1.png new file mode 100644 index 000000000..3004ef451 Binary files /dev/null and b/docs/concepts/media/direct-dependency-1.png differ diff --git a/docs/concepts/media/direct-dependency-2.png b/docs/concepts/media/direct-dependency-2.png new file mode 100644 index 000000000..98290bc38 Binary files /dev/null and b/docs/concepts/media/direct-dependency-2.png differ diff --git a/docs/concepts/media/direct-dependency-3.png b/docs/concepts/media/direct-dependency-3.png new file mode 100644 index 000000000..f4f38b64b Binary files /dev/null and b/docs/concepts/media/direct-dependency-3.png differ diff --git a/docs/concepts/media/direct-dependency-4.png b/docs/concepts/media/direct-dependency-4.png new file mode 100644 index 000000000..596475c18 Binary files /dev/null and b/docs/concepts/media/direct-dependency-4.png differ diff --git a/docs/concepts/media/dotnet-nuget-why-1.png b/docs/concepts/media/dotnet-nuget-why-1.png new file mode 100644 index 000000000..b8422c44e Binary files /dev/null and b/docs/concepts/media/dotnet-nuget-why-1.png differ diff --git a/docs/concepts/media/floating-versions-1.png b/docs/concepts/media/floating-versions-1.png new file mode 100644 index 000000000..95b23a6b0 Binary files /dev/null and b/docs/concepts/media/floating-versions-1.png differ diff --git a/docs/concepts/media/github-copilot-agent-settings.png b/docs/concepts/media/github-copilot-agent-settings.png new file mode 100644 index 000000000..2b998ee35 Binary files /dev/null and b/docs/concepts/media/github-copilot-agent-settings.png differ diff --git a/docs/concepts/media/lowest-applicable-version-1.png b/docs/concepts/media/lowest-applicable-version-1.png new file mode 100644 index 000000000..c0fec1d60 Binary files /dev/null and b/docs/concepts/media/lowest-applicable-version-1.png differ diff --git a/docs/concepts/media/lowest-applicable-version-2.png b/docs/concepts/media/lowest-applicable-version-2.png new file mode 100644 index 000000000..360d5de64 Binary files /dev/null and b/docs/concepts/media/lowest-applicable-version-2.png differ diff --git a/docs/concepts/media/lowest-applicable-version-3.png b/docs/concepts/media/lowest-applicable-version-3.png new file mode 100644 index 000000000..92079bfcf Binary files /dev/null and b/docs/concepts/media/lowest-applicable-version-3.png differ diff --git a/docs/concepts/media/opensource-percent.png b/docs/concepts/media/opensource-percent.png new file mode 100644 index 000000000..8c09e2d72 Binary files /dev/null and b/docs/concepts/media/opensource-percent.png differ diff --git a/docs/concepts/media/pm-ui-transitive-tooltip-1.png b/docs/concepts/media/pm-ui-transitive-tooltip-1.png new file mode 100644 index 000000000..d83e6bced Binary files /dev/null and b/docs/concepts/media/pm-ui-transitive-tooltip-1.png differ diff --git a/docs/concepts/media/projectJson-dependency-1.png b/docs/concepts/media/projectJson-dependency-1.png deleted file mode 100644 index 50f1c7b77..000000000 Binary files a/docs/concepts/media/projectJson-dependency-1.png and /dev/null differ diff --git a/docs/concepts/media/projectJson-dependency-2.png b/docs/concepts/media/projectJson-dependency-2.png deleted file mode 100644 index badc8fef0..000000000 Binary files a/docs/concepts/media/projectJson-dependency-2.png and /dev/null differ diff --git a/docs/concepts/media/projectJson-dependency-3.png b/docs/concepts/media/projectJson-dependency-3.png deleted file mode 100644 index 8f5c85f67..000000000 Binary files a/docs/concepts/media/projectJson-dependency-3.png and /dev/null differ diff --git a/docs/concepts/media/projectJson-dependency-4.png b/docs/concepts/media/projectJson-dependency-4.png deleted file mode 100644 index d17973c52..000000000 Binary files a/docs/concepts/media/projectJson-dependency-4.png and /dev/null differ diff --git a/docs/concepts/media/projectJson-dependency-5.png b/docs/concepts/media/projectJson-dependency-5.png deleted file mode 100644 index 5e0df0b07..000000000 Binary files a/docs/concepts/media/projectJson-dependency-5.png and /dev/null differ diff --git a/docs/concepts/media/projectJson-dependency-6.png b/docs/concepts/media/projectJson-dependency-6.png deleted file mode 100644 index 5925eebd0..000000000 Binary files a/docs/concepts/media/projectJson-dependency-6.png and /dev/null differ diff --git a/docs/concepts/media/projectJson-dependency-7.png b/docs/concepts/media/projectJson-dependency-7.png deleted file mode 100644 index 7158cd1a6..000000000 Binary files a/docs/concepts/media/projectJson-dependency-7.png and /dev/null differ diff --git a/docs/concepts/media/projectJson-dependency-8.png b/docs/concepts/media/projectJson-dependency-8.png deleted file mode 100644 index 980604f43..000000000 Binary files a/docs/concepts/media/projectJson-dependency-8.png and /dev/null differ diff --git a/docs/concepts/media/vs-solution-explorer-search-options-1.png b/docs/concepts/media/vs-solution-explorer-search-options-1.png new file mode 100644 index 000000000..870c39a8a Binary files /dev/null and b/docs/concepts/media/vs-solution-explorer-search-options-1.png differ diff --git a/docs/concepts/media/vs-solution-explorer-search-results-1.png b/docs/concepts/media/vs-solution-explorer-search-results-1.png new file mode 100644 index 000000000..00e30fedd Binary files /dev/null and b/docs/concepts/media/vs-solution-explorer-search-results-1.png differ diff --git a/docs/concepts/media/vulnerability-lifecycle.png b/docs/concepts/media/vulnerability-lifecycle.png new file mode 100644 index 000000000..179d33e3a Binary files /dev/null and b/docs/concepts/media/vulnerability-lifecycle.png differ diff --git a/docs/concepts/nuget-mcp.md b/docs/concepts/nuget-mcp.md new file mode 100644 index 000000000..42eeaa5af --- /dev/null +++ b/docs/concepts/nuget-mcp.md @@ -0,0 +1,81 @@ +--- +title: MCP servers in NuGet packages +description: How can MCP servers be distributed using NuGet? +author: joelverhagen +ms.author: jver +ms.topic: article +ms.date: 07/23/2025 +--- + +# MCP servers in NuGet packages + +NuGet provides a convenient way to package and distribute MCP servers written in .NET. The C# MCP SDK and .NET offer a robust platform for building MCP servers, and NuGet is ideal for delivering your MCP server to end users as a local tool. Self-contained, platform-specific packages reduce runtime compatibility issues, and AOT compilation can further improve the end-user experience. + +For more information about the Model Context Protocol (MCP) in general, see the [introduction on the MCP website](https://modelcontextprotocol.io/introduction). To create your own MCP server and package it using NuGet, see the [quickstart guide](/dotnet/ai/quickstarts/build-mcp-server). + +## Applicable scenarios + +Shipping your MCP server via NuGet does not apply to all situations. The term "MCP client" is used in this document and refers to an application that orchestrates the interaction between an AI agent or LLM and calls made to an MCP server. Some example MCP clients are [Visual Studio Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers), [Visual Studio](/visualstudio/ide/mcp-servers), [GitHub Copilot coding agent](https://docs.github.com/copilot/concepts/coding-agent/about-copilot-coding-agent), Claude Code, or Cursor. + +Consider the following criteria to determine whether shipping your MCP server as a NuGet package makes sense: + +- ✅ You want your MCP server to run **locally** on the user's system (i.e., in the same context as the MCP client). + - Local MCP servers, such as those shipped in NuGet packages, run in the same context as the MCP client and communicate with the MCP client via standard IO (stdio) transport. The MCP client is responsible for launching the local MCP server process. +- ✅ The .NET SDK is available to the MCP client. + - NuGet MCP servers are [.NET tool packages](/dotnet/core/tools/global-tools), which are installed and executed using `dnx` from the .NET SDK. +- ✅ You have a NuGet package feed to host your MCP server package. + - NuGet.org can be used to publish MCP server packages and provides a tailored MCP browsing and consumption experience. However, any NuGet package feed, such as Azure Artifacts, can be used for hosting MCP servers if you wish to keep your MCP server package private. + +## Benefits of using .NET and NuGet for MCP servers + +There are several benefits to using NuGet for hosting your MCP server: + +- **Official SDK** - the [MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk) provides a familiar interface for implementing your MCP server in C# and makes it easy to expose tools to MCP clients. +- **Flexible runtime options** - the .NET SDK provides several options for how your MCP server is compiled and packaged. See the [runtime requirements](#runtime-requirements) section for details. +- **Discoverability and distribution** - NuGet.org provides a way to showcase your MCP server, allowing potential users to find your MCP server and easily use it from inside VS Code or Visual Studio. NuGet.org encourages the use of an embedded [`.mcp/server.json`](https://github.com/modelcontextprotocol/registry/blob/main/docs/server-json/README.md) to declare inputs and an `McpServer` package type to allow MCP servers to be differentiated from other tool or dependency packages. +- **Familiar authoring workflows** - if you already use NuGet for creating dependency packages, creating and publishing an MCP server will be a very similar experience. + +## Package download and execution + +To fetch a local MCP server, the code for the server must be located and downloaded using a mechanism (protocol) specific to the package ecosystem. This is generally done with a "single-shot" command which takes the package name and arguments to download and then execute the package as a command-line application. + +For NuGet-based MCP servers, we recommend using `dnx` (a new command shipped in .NET 10 Preview 6) to acquire and execute the package. `dnx` currently ships with the .NET SDK, but there [is discussion to include `dnx` in the .NET runtime](https://github.com/dotnet/sdk/issues/49796). + +A command to start an MCP server would look something like this: + +```bash +dnx NuGet.Mcp.Server@0.1.2-preview --yes +``` + +Environment variables and command-line arguments can both be used to configure your MCP server in custom ways. These inputs allow you to customize the behavior of your MCP server to suit specific needs. + +This will download the `NuGet.Mcp.Server` package of version `0.1.2-preview` from your configured package sources (NuGet.org by default), and launch the contained CLI tool. For an MCP server, you may see log messages appear in stderr, but the process will appear to hang. This is expected, since the process is waiting for MCP protocol messages over stdin from your MCP client. + +Typically, your MCP client will invoke this command via tool-specific MCP configuration, such as the `mcp.json` file used by Visual Studio Code and Visual Studio. + +All of these tools support installing alternate sources. For example, `dnx` supports installing from Azure DevOps using the `--source` parameter, allowing consumption of private MCP servers, as long as the needed credential or credential providers are configured. + +## Runtime requirements + +Once the package is downloaded, a runtime is needed to execute the code inside the package. .NET tool packages (and by extension NuGet-based MCP servers) support a variety of options for how the tool is compiled and packaged. These options allow you, the MCP server author, to decide which runtime requirements should be placed on the users of your MCP server. + +There are three main options for how to package your MCP server: + +1. **Framework-dependent**: Requires that the MCP client has access to a compatible .NET runtime. If `dnx` is being used to download and execute the package, a runtime will be available. +2. **Self-contained**: Bundles the runtime with the package. [Using trimming](/dotnet/core/deploying/trimming/trimming-options) can reduce the size of the package. Self-contained .NET tools use `true`. +3. **Ahead-of-time (AOT) compiled**: A self-contained package with AOT compilation enabled. See [native AOT deployment](/dotnet/core/deploying/native-aot/) for more information. AOT .NET tools use `true`. + +For MCP servers, we recommend using option #2 (self-contained package without AOT) because it eliminates the need for any specific .NET runtime version present in the user's environment. If you can guarantee a compatible runtime version on the intended execution environment, option #1 is reasonable. Option #3 (using AOT) is also a good option, but it forces you or your dependencies to make your code compatible with AOT compilation. The C# MCP SDK is AOT compatible, but other dependencies you intend to use may not yet be AOT compatible. + +Consider using the `mcpserver` template in the [Microsoft.Extensions.AI.Templates](https://www.nuget.org/packages/Microsoft.Extensions.AI.Templates) template package to use the latest recommended defaults. + +## Comparison to other ecosystems + +Other ecosystems have similar requirements and workflows for packaging and running MCP servers: + +- **NuGet/.NET**: Uses the `dnx` command to download and execute .NET tool packages. Requires the .NET SDK for `dnx`. Additional runtime dependencies can be bundled into the package. +- **npm**: Uses the `npx` command to download and execute npm packages, and install dependencies transitively. Requires Node.js. +- **Python**: Uses the `uvx` command to download and execute Python packages, and install dependencies transitively. Requires a Python runtime. +- **Docker**: Uses the `docker run` command to download and execute images. Requires the Docker Engine. Docker images can target multiple CPU architectures and provide excellent isolation, but are generally larger than NuGet, npm, or Python packages. + +In all of these cases, the MCP client needs to have the necessary ecosystem-specific tool (e.g., `dnx`, `npx`) to download and execute the package-based MCP server. diff --git a/docs/concepts/package-installation-process.md b/docs/concepts/package-installation-process.md index abf4a8b8d..76074a1c4 100644 --- a/docs/concepts/package-installation-process.md +++ b/docs/concepts/package-installation-process.md @@ -1,10 +1,10 @@ --- title: What happens when a package is installed? description: Detailed information about the package installation process -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 06/20/2019 -ms.topic: conceptual +ms.topic: article --- # What happens when a NuGet package is installed? @@ -20,7 +20,10 @@ The general process is as follows: 2. Acquire the package: - Check if the package (by exact identifer and version number) is already installed in the *global-packages* folder as described on [Managing the global packages and cache folders](../consume-packages/managing-the-global-packages-and-cache-folders.md). - - If the package is not in the *global-packages* folder, attempt to retrieve it from the sources listed listed in the [configuration files](../consume-packages/Configuring-NuGet-Behavior.md). For online sources, attempt first to retrieve the package from the HTTP cache unless `-NoCache` is specified with `nuget.exe` commands or `--no-cache` is specified with `dotnet restore`. (Visual Studio and `dotnet add package` always use the cache.) If a package is used from the cache, "CACHE" appears in the output. The cache has an expiration time of 30 minutes. + - If the package is not in the *global-packages* folder, attempt to retrieve it from the sources listed in the [configuration files](../consume-packages/Configuring-NuGet-Behavior.md). [Package Source Mapping](../consume-packages/package-source-mapping.md) configurations are applied at this point. For online sources, attempt first to retrieve the package from the HTTP cache unless `-NoHttpCache` is specified with `nuget.exe` commands or `--no-http-cache` is specified with `dotnet restore`. (Visual Studio and `dotnet add package` always use the cache.) If a package is used from the cache, "CACHE" appears in the output. The cache has an expiration time of 30 minutes. + + - If the package has been specified using a [floating version](../consume-packages/Package-References-in-Project-Files.md#floating-versions), or without a minimum version, NuGet *will* contact all sources to figure out the best match. + Example: `1.*`, `(, 2.0.0]`. - If the package is not in the HTTP cache, attempt to download it from the sources listed in the configuration. If a package is downloaded, "GET" and "OK" appear in the output. NuGet logs http traffic on normal verbosity. diff --git a/docs/concepts/troubleshooting-installed-packages.md b/docs/concepts/troubleshooting-installed-packages.md new file mode 100644 index 000000000..d06dfcebc --- /dev/null +++ b/docs/concepts/troubleshooting-installed-packages.md @@ -0,0 +1,87 @@ +--- +title: Troubleshooting Installed Packages +description: How to find which package source was used for individual packages +author: JonDouglas +ms.author: jodou +ms.date: 03/26/2021 +ms.topic: troubleshooting-general +--- + +# Troubleshooting Installed Packages + +Sometimes you might want to validate which source a specific package was installed from. Here are some ways you can check. + +> [!Note] +> Some package sources support a concept known as upstream sources. For example, [Azure Artifacts upstream sources](/azure/devops/artifacts/concepts/upstream-sources). NuGet clients do not know whether a package came from an upstream source. Therefore, any logging of the package source will list the configured source, not the upstream source. + +## `.nupkg.metadata` file in global packages folder + +When a package is extracted into the *global-packages* folder, a file `.nupkg.metadata` is written. Starting from NuGet 5.9.0, NuGet will add the package source. See below to map NuGet versions to Visual Studio or .NET SDK versions. For example: + +```json +{ + "version": 2, + "contentHash": "bw3R9q8cVNhWXNpnvWb0OGP4HadS4zvClq+T1zf7AF+tLY1haZ2AvbHidQekf4PDv1T40c6brZeT/V0IBq7cEQ==", + "source": "https://api.nuget.org/v3/index.json" +} +``` + +> [!Note] +> If your *global-packages* folder has packages extracted before you upgraded to a newer version of tools that has NuGet 5.9.0, the `.nupkg.metadata` file will be version 1 and will not contain the package source. You can [clear your *global-packages* folder](../consume-packages/managing-the-global-packages-and-cache-folders.md#clearing-local-folders) to ensure all packages will contain the package source. + +> [!Tip] +> NuGet writes the `.nupkg.metadata` file to the *global-packages* folder only. Projects using `packages.config` use a solution packages folder, which does not create a `.nupkg.metadata` file. + +## Installed package log message + +Starting from NuGet 5.9.0, NuGet outputs the package source in the restore message informing that a package was installed. For example: + +```text +Installed Moq 4.16.1 from https://api.nuget.org/v3/index.json with content hash bw3R9q8cVNhWXNpnvWb0OGP4HadS4zvClq+T1zf7AF+tLY1haZ2AvbHidQekf4PDv1T40c6brZeT/V0IBq7cEQ==. +``` + +> [!Tip] +> This message is output at normal/informational verbosity. Visual Studio and the `dotnet` CLI default to minimal verbosity, so this message will not be visible by default. The `msbuild` and `nuget` CLI tools default to normal verbosity, so this message will be visible by default. + +## HTTP log message + +When a package is not available locally, either in the *global-packages* folder, a fallback folder, or a local file source, NuGet will download it from any configured package source over HTTP. HTTP requests and responses are logged at the normal verbosity level, and you should see only a single request and response per package version. For example: + +```text +info : GET https://api.nuget.org/v3-flatcontainer/moq/index.json +info : OK https://api.nuget.org/v3-flatcontainer/moq/index.json 56ms +info : GET https://api.nuget.org/v3-flatcontainer/moq/4.16.1/moq.4.16.1.nupkg +info : OK https://api.nuget.org/v3-flatcontainer/moq/4.16.1/moq.4.16.1.nupkg 3ms +``` + +If the files were recently downloaded, they might be retrieved from NuGet's *http-cache* + +```text +CACHE https://api.nuget.org/v3-flatcontainer/moq/index.json +CACHE https://api.nuget.org/v3-flatcontainer/moq/4.16.1/moq.4.16.1.nupkg +``` + +The URL format may be different for different NuGet HTTP server implementations, and whether it's implementing NuGet V2 or V3 HTTP protocol. + +If your `nuget.config` has multiple HTTP sources defined, you will see multiple requests to each package's `index.json` file, one for each source. But there will be only a single `nupkg` download for each version of the package. + +## Package signature log message + +If the package being downloaded is signed, NuGet will validate the signature and will log the following message at detailed verbosity: + +```text +PackageSignatureVerificationLog: PackageIdentity: Moq.4.16.1 Source: https://api.nuget.org/v3/index.json PackageSignatureValidity: True +``` + +This message will be reported whether the package was downloaded from an HTTP package source, or copied from a local package source. It will not be output if the package is already available in the *global-packages* folder or a fallback folder. + +> [!Important] +> Due to [removal of trust of VeriSign CA](https://github.com/dotnet/announcements/issues/180) NuGet has disabled signed package verification on certain platforms, in certain versions of NuGet and the .NET SDK. Therefore, the same packages may have `PackageSignatureVerificationLog` logs, or those logs may be missing, depending on what platform you're running restore on, and which version of .NET or NuGet you're using. + +## NuGet Version Map + +The following versions of NuGet have important changes regarding package source logging: + +|NuGet Version|Visual Studio Version|.NET SDK Version| +|---|---|---| +|NuGet 5.9.0|Visual Studio 2019 16.9.0|.NET 5 SDK 5.0.200| diff --git a/docs/consume-packages/Central-Package-Management.md b/docs/consume-packages/Central-Package-Management.md new file mode 100644 index 000000000..66f7e9744 --- /dev/null +++ b/docs/consume-packages/Central-Package-Management.md @@ -0,0 +1,275 @@ +--- +title: Central Package Management +description: Manage your dependencies in a central location and learn how to get started with Central Package Management. +author: jondouglas +ms.author: jodou +ms.date: 05/09/2022 +ms.topic: article +--- + +# Central Package Management (CPM) + +Dependency management is a core feature of NuGet. +While managing dependencies for a single project is straightforward, it becomes increasingly complex as the number of projects in a solution grows. + +If you manage common dependencies for many different projects, you can leverage NuGet's Central Package Management (CPM) features to do all of this from a single, central location. + +Central Package Management applies to all ``-based MSBuild projects (including [legacy CSPROJ](https://github.com/dotnet/project-system/blob/main/docs/feature-comparison.md)). + +## Enabling Central Package Management + +To get started with Central Package Management, create a `Directory.Packages.props` file at the root of your repository and set the MSBuild property `ManagePackageVersionsCentrally` to `true`. + +You can create it manually, or use the .NET CLI: + +```shell +dotnet new packagesprops +``` + +Inside `Directory.Packages.props`, define `` elements to specify the package IDs and versions used by your projects. + +```xml + + + true + + + + + + +``` + +In each project file, define `` elements without the `Version` attribute. +The version will be resolved from the corresponding `` entry in `Directory.Packages.props`. + +```xml + + + net6.0 + + + + + +``` + +Now you're using Central Package Management and managing your versions in a central location! + +## Central Package Management Rules + +The `Directory.Packages.props` file has specific rules regarding its location and context within a repository. +Only one `Directory.Packages.props` file is evaluated for a given project by default. + +If you have multiple `Directory.Packages.props` files in your repository, the file closest to a given project's directory will be evaluated for it. +This allows extra control at various levels of your repository. + +Consider the following repository directory structure: + +``` +📂 (root) + ├─📄 Directory.Packages.props + | + ├─📂Solution1 + | ├─ 📄Directory.Packages.props + | | + | └─ 📂 Project1 + | └─📄Project1.csproj + | + └─ 📂 Solution2 + └─ 📂 Project2 + └─ 📄 Project2.csproj +``` + +`Project1.csproj` will use the `Directory.Packages.props` file in the `Repository\Solution1\` directory. +If you want to include settings from a parent `Directory.Packages.props`, you must manually import it. + +```xml + + + + + + +``` + +`Project2.csproj` will evaluate the `Directory.Packages.props` file in the root directory. + +> [!NOTE] +> MSBuild will only automatically import the first `Directory.Packages.props` file it finds in the project directory or any parent directory. +> If you have multiple such files, you must manually import parent files as needed. + +## Getting Started + +To fully onboard your repository, follow these steps: + +1. Create a new file at the root of your repository named `Directory.Packages.props` that declares your centrally defined package versions and set the MSBuild property `ManagePackageVersionsCentrally` to `true`. +2. Declare `` items in your `Directory.Packages.props`. +3. Declare `` items without `Version` attributes in your project files. + +For an example of how Central Package Management may look, refer to our [samples repository](https://github.com/NuGet/Samples/tree/main/CentralPackageManagementExample). + +## Using Different Versions for Different Target Frameworks + +As NuGet packages evolve, package owners may drop support for older target frameworks. +This can cause issues for developers of libraries that still target older frameworks but want to reference newer versions of packages for newer target frameworks. + +For example, if your project targets .NET Standard 2.0, .NET 8.0, and .NET Framework 4.7.2, but `PackageA` no longer supports .NET Standard 2.0 in its latest version, you can specify different versions for each target framework. + +```xml + + + netstandard2.0;net8.0;net472 + + + + + +``` + +In this case, define different versions for each target framework in your `Directory.Packages.props` using [MSBuild conditions](/visualstudio/msbuild/msbuild-conditions): + +```xml + + + true + + + + + + +``` + +## Transitive Pinning + +You can automatically override a transitive package version without an explicit top-level `` item by opting into a feature known as transitive pinning. +This promotes a transitive dependency to a top-level dependency implicitly on your behalf when necessary. + +Note that downgrades are not allowed when transitive pinning a package. +If you attempt to pin a package to a lower version than the one requested by your dependencies, restore will raise a [NU1109](../reference/errors-and-warnings/NU1109.md) error. + +You can enable this feature by setting the MSBuild property `CentralPackageTransitivePinningEnabled` to `true` in a project or in a `Directory.Packages.props` or `Directory.Build.props` import file: + +```xml + + true + +``` + +### Transitive Pinning and Pack + +When a package is transitively pinned, your project uses a higher version than the one requested by your dependencies. +If you create a package from your project, to ensure that your package will work, NuGet will promote the transitively pinned dependencies to explicit dependencies in the nuspec. + +In the following example, `PackageA 1.0.0` has a dependency on `PackageB 1.0.0`. + +```xml + + + + + + +``` + +```xml + + + true + net6.0 + + + + + +``` + +When you use the pack command to create a package, both packages will appear in the dependency group. + +```xml + + + + +``` + +Because of this, the use of transitive pinning should be carefully evaluated when authoring a library, as it may lead to dependencies you did not expect. + +## Overriding Package Versions + +You can override an individual package version by using the `VersionOverride` property on a `` item. +This will take precedence over any centrally defined ``. + +```xml + + + + + + +``` + +```xml + + + net6.0 + + + + + +``` + +You can disable this feature by setting the MSBuild property `CentralPackageVersionOverrideEnabled` to `false` in a project or in a `Directory.Packages.props` or `Directory.Build.props` import file: + +```xml + + false + +``` + +When this feature is disabled, specifying a `VersionOverride` on any `` item will result in an error at restore time indicating that the feature is disabled. + +## Disabling Central Package Management + +To disable Central Package Management for a specific project, set the MSBuild property `ManagePackageVersionsCentrally` to `false`: + +```xml + + false + +``` + +## Global Package References + +> [!NOTE] +> This feature is only available in Visual Studio 2022 17.4 or higher, .NET SDK 7.0.100.preview7 or higher, and NuGet 6.4 or higher. + +A global package reference is used to specify that a package will be used by every project in a repository. +This includes packages that do versioning, extend your build, or any other packages that are needed by all projects. +Global package references are added to the PackageReference item group with the following metadata: + +* `IncludeAssets="Runtime;Build;Native;contentFiles;Analyzers"`
+ This ensures that the package is only used as a development dependency and prevents it from being included as a compile-time assembly reference. +* `PrivateAssets="All"`
+ This prevents global package references from being picked up by downstream dependencies. + +`GlobalPackageReference` items should be placed in your `Directory.Packages.props` to be used by every project in a repository: + +```xml + + + + + +``` + +## NU1507 Warning When Using Multiple Package Sources + +When using Central Package Management, NuGet will log an [`NU1507`](../reference/errors-and-warnings/nu1507.md) warning if more than one package source is defined in your configuration. +To resolve this warning, map your package sources with [package source mapping](https://aka.ms/nuget-package-source-mapping) or specify a single package source. + +``` +There are 3 package sources defined in your configuration. When using Central Package Management, please map your package sources with package source mapping (https://aka.ms/nuget-package-source-mapping) or specify a single package source. +``` diff --git a/docs/consume-packages/Finding-and-Choosing-Packages.md b/docs/consume-packages/Finding-and-Choosing-Packages.md index 3c84bf586..fef94e0cd 100644 --- a/docs/consume-packages/Finding-and-Choosing-Packages.md +++ b/docs/consume-packages/Finding-and-Choosing-Packages.md @@ -1,140 +1,202 @@ --- -title: Finding and Choosing NuGet Packages -description: An overview of how to find and choose the best NuGet packages for a project including details on the NuGet search syntax. -author: karann-msft -ms.author: karann -ms.date: 06/04/2018 -ms.topic: conceptual +title: Find and evaluate NuGet packages +description: Find and evaluate publicly available NuGet packages for your project by using advanced nuget.org search filters and syntax. +author: JonDouglas +ms.author: jodou +ms.date: 03/03/2025 +ms.topic: how-to --- -# Finding and evaluating NuGet packages for your project +# Find and evaluate NuGet packages for your project -When starting any .NET project, or whenever you identify a functional need for your app or service, you can save yourself lots of time and trouble by using existing NuGet packages that fulfill that need. These packages can come from the public collection on [nuget.org](http://www.nuget.org/packages/), or a private source that's provided by your organization or another third party. +When you start a .NET project, or identify a functional need in your app or service, you can often install existing NuGet packages to save the time and trouble of [creating your own packages](../create-packages/overview-and-workflow.md). Existing packages can come from the [nuget.org](https://www.nuget.org/packages) public collection, or from private sources that your organization or another party provide. -## Finding packages +## Find packages -When you visit nuget.org or open the Package Manager UI in Visual Studio, you see a list of packages sorted by total downloads. This immediately shows you the most widely-used packages across the millions of .NET projects. There's a good chance, then, that at least some of the packages listed on the first few pages will be useful in your projects. +You can find packages directly at [https://nuget.org/packages](https://www.nuget.org/packages), or from the [Visual Studio Package Manager UI](install-use-packages-visual-studio.md) or [Package Manager Console](install-use-packages-powershell.md) with nuget.org as a source. All packages from nuget.org are routinely scanned for viruses. -![Default view of nuget.org/packages showing the most popular packages](media/Finding-01-Popularity.png) +At [nuget.org/packages](https://www.nuget.org/packages), you see a list of NuGet packages with the most popular packages across all .NET projects listed first. Some of these packages might be useful for your projects. -Notice the **Include prerelease** option on the upper right of the page. When selected, nuget.org shows all versions of packages including beta and other early releases. To show only stable released, clear the option. +![Screenshot that shows the default view of nuget.org/packages with the most popular packages at the top.](media/Finding-07-MostPopular.png) -For specific needs, searching by tags (within the Visual Studio Package Manager or on a portal like nuget.org) is the most common means of discovering a suitable package. For example, searching on "json" lists all NuGet packages that are tagged with that keyword and thus have some relationship to the JSON data format. +To search for a package, enter the package name or search terms in the Search box at the top of the page. You can use [advanced search syntax](#search-syntax) to filter your search. -![Search results for 'json' on nuget.org](media/Finding-02-SearchResults.png) +### Advanced filtering and sorting -You can also search using the package ID, if you know it. See [Search Syntax](#search-syntax) below. +At nuget.org/packages, you can refine your search results by making use of the advanced filtering and sorting options. -At this time, search results are sorted only by relevance, so you generally want to look through at least the first few pages of results for packages that suit your needs, or refine your search terms to be more specific. +![Screenshot that shows the filtering and sorting options on nuget.org.](media/Finding-08-FiltersAndSorts.png) -### Does the package support my project's target framework? +Use the **Frameworks** filters to show packages targeting specific .NET frameworks (To learn more, see [Target Frameworks](/dotnet/standard/frameworks)): -NuGet installs a package into a project only if that package's supported frameworks include the project's target framework. If the package is not compatible, NuGet issues an error. +- Selecting one of the .NET framework generation checkboxes would filter the search results to packages compatible with any of the individual Target Frameworks within that generation. For example, selecting `.NET` will return packages compatible with any of the modern .NET frameworks, including `net5.0` through `net8.0`. -Some packages list their supported frameworks directly in the nuget.org gallery, but because such data is not required, many packages do not include that list. At present there is no means to search nuget.org for packages that support a specific target framework (the feature is under consideration, see [NuGet Issue 2936](https://github.com/NuGet/NuGetGallery/issues/2936)). + ![Screenshot that shows the Framework filters on nuget.org.](media/Finding-09-FrameworkFilterPanel.png) -Fortunately, you can determine supported frameworks through two other means: +- Expanding one of these framework generations with the arrows on the right will show you individual Target Framework Monikers (TFMs) that you can filter your results by. For example, selecting `net5.0` will return packages compatible with the '.NET 5.0' framework. +- By default, packages are filtered by their expanded list of computed compatible frameworks. If you want to filter packages purely by the asset frameworks they explicitly target, deselect the **Include compatible frameworks** checkbox. +- Combining multiple framework filters will show you search results that match all of your selected filters, i.e. packages that fall in the intersection of your selections. For example, selecting `netcoreapp3.1` and `net45` together will show packages that target **both** '.NET Core 3.1' and '.NET Framework 4.5'. Selecting the `.NET Core` framework generation checkbox and the `net45` checkbox together will return packages that target '.NET Framework 4.5', and at least one of the '.NET Core' TFMs (`netcoreapp1.0` through `netcoreapp3.1`). + - Alternatively, if you want to see packages matching **any one** of your framework filters, select the **Any** radio button on the **Framework Filter Mode** option. Now, selecting `netcoreapp3.1` and `net5.0` will show packages that target **either** '.NET Core 3.1' or '.NET 5.0'. Selecting the `netcoreapp3.1` checkbox and the `.NET` framework generation checkbox together will return packages that target '.NET Core 3.1' or any one of the '.NET' TFMs (`net5.0` through `net8.0`). +- You can learn more on how to evaluate a package's supported frameworks and its compatibility with your project [here](#determine-supported-frameworks). -1. Attempt to install a package into a project using the [`Install-Package`](../reference/ps-reference/ps-ref-install-package.md) command in the NuGet Package Manager Console. If the package is incompatible, this command shows you the package's supported frameworks. +Use the **Package type** filter to show packages of a specific type: -1. Download the package from its page on nuget.org using the **Manual download** link under **Info**. Change the extension from `.nupkg` to `.zip`, and open the file to examine the content of its `lib` folder. There you see subfolders for each of the supported frameworks, where each subfolder is named with a target framework moniker (TFM; see [Target Frameworks](../reference/target-frameworks.md)). If you see no subfolders under `lib` and only a single DLL, then you must attempt to install the package in your project to discover its compatibility. +- **All types** is the default and shows all packages regardless of type. +- **Dependency** filters to regular NuGet packages that you can install into your project. +- **.NET tool** filters to [.NET tools](/dotnet/core/tools/global-tools) packages that contain console applications. +- **Template** filters to [.NET templates](/dotnet/core/install/templates) that you can use to create new projects with the [dotnet new](/dotnet/core/tools/dotnet-new) command. -## Pre-release packages +By default, NuGet lists all versions of packages, including prerelease and beta versions. In the **Options** section, deselect the **Include prerelease** checkbox to list only stable, released package versions. -Many package authors make preview and beta releases available as they continue to make improvements and seek feedback on their latest revisions. +To apply changes, select **Apply**. To get back to the defaults, select **Reset**. -By default, nuget.org shows pre-release packages in search results. To search only stable releases, clear the **Include prerelease** option on the upper right of the page +Use the **Sort by** dropdown on the top-right of the page to sort the list by several criteria: -![Include prerelease checkbox on nuget.org](media/Finding-06-include-prerelease.png) +- **Relevance** is the default, and sorts results according to an internal scoring algorithm. +- **Downloads** sorts the search results by the total number of downloads, in descending order. +- **Recently updated** sorts the search results by the latest package version creation date, in descending chronological order. -In Visual Studio, and when using the NuGet and dotnet CLI tools, NuGet does not include pre-release versions by default. To change this behavior, do the following steps: +### Search syntax -- **Package Manager UI in Visual Studio**: In the **Manage NuGet Packages** UI, set the **Include prerelease** box. Setting or clearing this box refreshes the Package Manager UI and the list of available versions you can install. +Package search queries at nuget.org, from the NuGet CLI, and from within Visual Studio all use the same syntax. Other package sources, like Azure Artifacts or GitHub Package Repository, might use different syntax or might not support advanced filtering. - ![The Include prerelease checkbox in Visual Studio](media/Prerelease_02-CheckPrerelease.png) +- You can search the package `id`, `packageid`, `version`, `title`, `tags`, `author`, `description`, `summary`, or `owner` properties by using the syntax `:`. -- **Package Manager Console**: Use the `-IncludePrerelease` switch with the `Find-Package`, `Get-Package`, `Install-Package`, `Sync-Package`, and `Update-Package` commands. Refer to the [PowerShell Reference](../reference/powershell-reference.md). +- Search applies to keywords and descriptions, and is case-insensitive. For example, the following strings all search the `id` property for the string `nuget.core`: -- **nuget.exe CLI**: Use the `-prerelease` switch with the `install`, `update`, `delete`, and `mirror` commands. Refer to the [NuGet CLI reference](../reference/nuget-exe-cli-reference.md) + `id:NuGet.Core`
`ID:nuget.core`
`Id:NUGET.CORE` -- **dotnet.exe CLI**: Specify the exact pre-release version using the `-v` argument. Refer to the [dotnet add package reference](/dotnet/core/tools/dotnet-add-package). +- Searches on the `id` property match substrings, while `packageid` and `owner` use exact, case-insensitive matches. For example: - + `PackageId:jquery` searches for the exact package ID `jquery`.
`Id:jquery` searches for all package IDs that contain the string `jquery`. + +- You can search for multiple values or properties at the same time. For example: + + `id:jquery id:ui` searches for multiple terms in the `id` property.
`id:jquery tags:validation` searches for multiple properties. + +- Search ignores unsupported properties, so `invalid:jquery ui` is the same as searching for `ui`, and `invalid:jquery` returns all packages. + +### Determine supported frameworks + +NuGet installs a package into a project only if the package's supported .NET frameworks include the project's target frameworks. If the package isn't compatible, NuGet issues an error. + +There are several ways to determine the frameworks that a package supports: + +- On the search page, a package's supported frameworks will appear as badges below the package ID. These badges show the lowest supported framework versions from the **.NET**, **.NET Core**, **.NET Standard**, and **.NET Framework** generations. The package will be compatible with any framework version that's equal to or higher than the badge version shown. + + 'Dark blue' badges represent explicitly targeted frameworks, while 'light blue' badges represent computed compatible frameworks. + + Clicking on a badge will redirect you to the package's details page on nuget.org. The **Frameworks** tab on the package's page will show the full list of supported frameworks. + + ![Screenshot of the Framework badges on nuget.org's search page.](media/Finding-10-FrameworkBadgesInSearch.png) + +- On the package's page at nuget.org, supported frameworks appear below the package ID and on the **Frameworks** tab, but not all packages show supported frameworks. + + ![Screenshot of the Frameworks UI and tab on the package page at nuget.org.](media/supported-frameworks.png) + +- Download the package manually by selecting **Download package** under **About**. Change the file extension of the downloaded package from *.nupkg* to *.zip*, open the *.zip* folder, and examine its *lib* folder. There are subfolders for each supported framework, each named with a target framework moniker (TFM). For more information, see [Target Frameworks](../reference/target-frameworks.md). If there aren't any subfolders under *lib* and there's only a single DLL, try to install the package to discover its compatibility. +- Try to install the package into a project by using [Install-Package](../reference/ps-reference/ps-ref-install-package.md) in the Visual Studio Package Manager Console. If the package is incompatible, the console output shows the package's supported frameworks. + +### Prerelease packages + +Many package authors provide preview and beta releases as they continue to improve and seek feedback on latest revisions. By default, nuget.org shows prerelease packages in its package list and search results. + +To list and search only stable releases: + + - At nuget.org, deselect the **Include prerelease** checkbox in the advanced search panel. + - In the Visual Studio NuGet Package Manager UI, deselect the **Include prerelease** checkbox next to the Search box. + +The Visual Studio Package Manager Console, NuGet CLI, and dotnet CLI tools don't include prerelease versions by default. To include prerelease versions: + +- In the Package Manager Console, use the `-IncludePrerelease` switch with the `Find-Package`, `Get-Package`, `Install-Package`, `Sync-Package`, and `Update-Package` commands. For more information, see the [PowerShell Reference](../reference/powershell-reference.md). + +- For the NuGet CLI, use the `-prerelease` switch with the `install`, `update`, `delete`, and `mirror` commands. For more information, see the [NuGet CLI reference](../reference/nuget-exe-cli-reference.md). + +- For the dotnet CLI, specify a prerelease version with the `-v` argument. For more information, see the [dotnet add package reference](/dotnet/core/tools/dotnet-add-package). + + ### Native C++ packages -NuGet supports native C++ packages can that can be used in C++ projects in Visual Studio. This enables the **Manage NuGet Packages** context-menu command for projects, introduces a `native` target framework, and provides MSBuild integration. +Visual Studio C++ projects can use native C++ NuGet packages. Installing these packages enable the **Manage NuGet Packages** context-menu command, exposes a `native` target framework, and provides MSBuild integration. + +To find native packages on nuget.org/packages, search by using `tag:native`. Such packages typically provide *.targets* and *.props* files, which NuGet imports automatically when adding the packages. + +## Evaluate packages + +The best way to evaluate a package's usefulness is to try it out. You take a dependency on a package when you use it, so you must make sure it's robust and reliable. However, installing a package and directly testing it is time-consuming. You can learn a lot about a package's quality by using the information on the package's page at nuget.org/packages. -To find native packages on [nuget.org](https://www.nuget.org/packages), search using `tag:native`. Such packages typically provide `.targets` and `.props` files, which NuGet imports automatically when the package is added to a project. +- The **Prefix Reserved** checkmark next to the package ID on the packages list and the package page means the package owners have applied for and been granted a [reserved package ID prefix](../nuget-org/id-prefix-reservation.md). To meet the [ID prefix reservation criteria](../nuget-org/id-prefix-reservation.md#id-prefix-reservation-criteria), package owners must clearly identify themselves and their packages. -## Evaluating packages + ![Screenshot that shows Prefix Reserved on a package's page.](media/prefix-reserved.png) + +- **Downloads** in the package page's right column shows **Total**, **Current version**, and **Per day average** downloads. Large numbers indicate that the package has proven itself among many developers. -The best way to evaluate the usefulness of a package is to download it and try it out in your code (all packages on nuget.org are routinely scanned for viruses, by the way). After all, every highly popular package got started with only a few developers using it, and you might be one of the early adopters! + ![Screenshot that shows Download statistics on a package's page.](media/Finding-03-Downloads.png) + + Select **Full stats** next to **Downloads** to see a page that shows package downloads for the past six weeks by version number. Versions that more developers are using are typically better choices. -At the same time, using a NuGet package means taking a dependency on it, so you want to make sure it's robust and reliable. Because installing and directly testing a package is time-consuming, you can also learn a lot about a package's quality by using the information on a package's listing page: +- The **Used By** tab on the package page shows the top five most popular nuget.org packages and GitHub repositories that depend on this package. Packages and repos that depend on this package are called *dependents*. Dependent packages and repos can be seen as endorsing this package, because they chose to trust and depend on it. -- *Downloads statistics*: on the package page on nuget.org, the **Statistics** section shows total downloads, downloads of the most recent version, and average downloads per day. Larger numbers indicate that many other developers have taken a dependency on the package, which means that it has proven itself. + ![Screenshot that shows the Used By list.](media/Used-By-section-Humanizer.png) + + The *latest stable version* of a dependent package must depend on any version of this package. This definition ensures that listed dependent packages are an up-to-date reflection of package authors' decisions to trust and depend on the package. The dependents list doesn't show prerelease dependents, because they're not considered wholehearted endorsements yet. The following examples show which packages show as dependents: - ![Download statistics on a package's listing page](media/Finding-03-Downloads.png) + | Dependent package version | Dependent package listed as a dependent? | + |-|-| + | v1.0.0
v1.1.0 (latest stable) depends on this package
v1.2.0-preview | TRUE, latest stable version depends on this package | + | v1.0.0 depends on this package
v1.1.0 (latest stable)
v1.2.0-preview | FALSE, latest stable version doesn't depend on this package | + | v1.0.0 depends on this package
v1.1.0 (latest stable)
v1.2.0-preview depends on this package | FALSE, latest stable version doesn't depend on this package | -- *GitHub Usage*: on the package page, the **GitHub Usage** section lists the top GitHub repositories that depend on this package. A package that many popular GitHub repositories depend on is typically a better choice. + The number of stars for a GitHub repository indicates its popularity with GitHub users. For more information about the GitHub star and repository ranking system, see [About stars](https://help.github.com/github/getting-started-with-github/saving-repositories-with-stars#about-stars). - ![GitHub Usage](media/GitHub-Usage.png) + > [!Note] + > The **Used By** section is automatically generated periodically, without human review, and solely for informational purposes. -- *Version history*: on the package page, look under **Info** for the date of the most recent update and examine the **Version History**. A well-maintained package has recent updates and a rich version history. Neglected packages have few updates and often haven't been updated in some time. +- The **Versions** tab on the package page shows the **Versions**, **Downloads**, **Last Updated** dates, and serious vulnerabilities of package versions. The version you install shouldn't have any high-severity vulnerabilities. A well-maintained package has recent updates and a long version history. Neglected packages have few and long-ago updates. - ![Version history on a package's listing page](media/Finding-04-VersionHistory.png) + ![Screenshot that shows the Versions list.](media/Finding-04-VersionHistory.png) -- *Recent installs*: on the package page under **Statistics**, select **View full stats**. The full stats page shows the package installs over the last six weeks by version number. A package that other developers are actively using is typically a better choice than one that's not. +The right column of the package page has other informative links: -- *Support*: on the package page under **Info**, select **Project Site** (if available) to see what support options the author provides. A project with a dedicated site is generally better supported. +:::row::: + :::column span=""::: +![Screenshot that shows the right column of the package page.](media/right-column.png) + :::column-end::: + :::column span="2"::: +- Select **Project website**, if available, to see what support options the author provides. A project with a dedicated site is generally well supported. -- *Developer history*: on the package page under **Owners**, select an owner to see what other packages they've published. Those with multiple packages are more likely to continue supporting their work in the future. +- Select **Source repository** to go to the Git source code repository for the package. Many authors maintain their packages in open-source repositories, so users can directly contribute bug fixes and feature improvements. The package's contribution history is a good indicator of how many developers are actively involved. -- *Open source contributions*: many packages are maintained in open-source repositories, making it possible for developers depending on them to directly contribute bug fixes and feature improvements. The contribution history of any given package is also a good indicator of how many developers are actively involved. +- Select **\ license** to see the package's MIT or other license. If a package doesn't specify license terms, contact the package owner. -- *Interview the owners*: new developers can certainly be equally committed to producing great packages for you to use, and it's good to give them a chance to bring something new to the NuGet ecosystem. With this in mind, reach out directly to the package developers through the **Contact Owners** option under **Info** on the listing page. Chances are, they'll be happy to work with you to serve your needs! +- Select any of the package owners under **Owners** to see other packages they've published. Owners with multiple packages are more likely to continue supporting their work. Select **Contact owners** next to **Owners** to reach out directly to the package developers. -- *Reserved Package ID Prefixes*: many package owners have applied for and have been granted a [reserved package ID prefix](../nuget-org/id-prefix-reservation.md). When you see the visual checkmark next to a package ID on [nuget.org](https://www.nuget.org/), or in Visual Studio, that means that the package owner has met our [criteria](../nuget-org/id-prefix-reservation.md#id-prefix-reservation-criteria) for ID prefix reservation. This means the package owner is being clear on identifying themselves and their package. + :::column-end::: +:::row-end::: -> [!Note] -> Always be mindful of a package's license terms, which you can see by selecting **License Info** on a package's listing page on nuget.org. If a package does not specify license terms, contact the package owner directly using the **Contact owners** link on the package page. Microsoft does not license any intellectual property to you from third party package providers and is not responsible for information provided by third parties. +## Retrieve license information -## License URL deprecation -As we transition from [licenseUrl](../reference/nuspec.md#licenseurl) to [license](../reference/nuspec.md#license), some NuGet clients and NuGet feeds may not yet have the ability to surface licensing information in some cases. To maintain backward compatibility, the license URL points to this document which talks about how to retrieve the license information in such cases. +Some NuGet clients and NuGet feeds might not be able to surface licensing information. To maintain backward compatibility in such cases, the license URL points to this document about how to retrieve the license information. -If clicking on the license URL for a package brought you to this page, it implies the package contains a license file and -* You are connected to a feed that does not yet know how to interpret and surface the new license information to the client -**OR** -* You are using a client that does not yet know how to interpret and read the new license information that is potentially provided by the feed -**OR** -* A combination of both +If selecting the license URL for a package brings you to this page, it implies the package contains a license file and: -Here is how you could read the information contained in the license file inside the package: -1. Download the NuGet package, and unzip its contents to a folder. -1. Open the `.nuspec` file which would be at the root of that folder. -1. It should have a tag like `license\license.txt`. This implies the license file is named `license.txt` and it is inside a folder called `license` which would also be at the root of that folder. -1. Navigate to the `license` folder and open the `license.txt` file. +- You're connected to a feed that doesn't know how to interpret and surface the license information to the client, or +- You're using a client that doesn't know how to interpret and read the license information the feed provides, or +- A combination of both of these scenarios. -For the MSBuild equivalent to setting the license in the `.nuspec`, take a look at [Packing a license expression or a license file](/nuget/reference/msbuild-targets#packing-a-license-expression-or-a-license-file). +To read the information in the license file inside the package: -## Search Syntax +1. Manually download the package, and unzip its contents to a folder. +1. Open the *.nuspec* file at the root of the folder. +1. Examine the `` tag, such as `license\license.txt`. The example tag states that the license file is named *license.txt* and is inside a subfolder called *license*. +1. Navigate to the specified location and open the specified file. -NuGet package search works the same on nuget.org, from the NuGet CLI, and within the NuGet Package Manager extension in Visual Studio. In general, search is applied to keywords as well as package descriptions. +For information about the MSBuild equivalent to setting the license in the *.nuspec*, see [Packing a license expression or a license file](../reference/msbuild-targets.md#packing-a-license-expression-or-a-license-file). -- **Keywords**: Search looks for relevant packages that contain any of the provided keywords. Example: `modern UI`. To search for packages that contain all of the provided keywords, use "+" between the terms, such as `modern+UI`. -- **Phrases**: Entering terms within quotation marks looks for exact case-insensitive matches to those terms. Example: `"modern UI" package` -- **Filtering**: You can apply a search term to a specific property by using the syntax `:` where `` (case-insensitive) can be `id`, `packageid`, `version`, `title`, `tags`, `author`, `description`, `summary`, and `owner`. Terms can be contained in quotes if needed, and you can search for multiple properties at the same time. Also, searches on the `id` property are substring matches, whereas `packageid` uses an exact match. Examples: +## Next steps - ``` - id:NuGet.Core # Match any part of the id property - Id:"Nuget.Core" - ID:jQuery - title:jquery # Searches title as shown on the package listing - PackageId:jquery # Match the package id exactly - id:jquery id:ui # Search for multiple terms in the id - id:jquery tags:validation # Search multiple properties - id:"jquery.ui" # Phrase search - invalid:jquery ui # Unsupported properties are ignored, so this - # is the same as searching on jquery ui - ``` +- [Ways to install a NuGet package](overview-and-workflow.md#ways-to-install-a-nuget-package) +- [Install and manage packages in Visual Studio using the NuGet Package Manager](install-use-packages-visual-studio.md) +- [Install and manage packages with the Package Manager Console in Visual Studio](install-use-packages-powershell.md) +- [Install and manage packages with the dotnet CLI](install-use-packages-dotnet-cli.md) diff --git a/docs/consume-packages/Overview-and-Workflow.md b/docs/consume-packages/Overview-and-Workflow.md index 0c7733d33..b9bc8f527 100644 --- a/docs/consume-packages/Overview-and-Workflow.md +++ b/docs/consume-packages/Overview-and-Workflow.md @@ -1,10 +1,10 @@ --- title: Overview and workflow of using NuGet packages description: An overview of the process of consuming NuGet packages in a project, with links to other specific parts of the process. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 03/22/2018 -ms.topic: conceptual +ms.topic: concept-article --- # Package consumption workflow @@ -34,15 +34,15 @@ When adding project code to a source repository, you typically don't include NuG Occasionally it's necessary to reinstall packages that are already included in a project, which may also reinstall dependencies. This is easy to do using the `nuget reinstall` command or the NuGet Package Manager Console. For details, see [Reinstalling and Updating Packages](../consume-packages/reinstalling-and-updating-packages.md). -Finally, NuGet's behavior is driven by `Nuget.Config` files. Multiple files can be used to centralize certain settings at different levels, as explained in [Configuring NuGet Behavior](../consume-packages/configuring-nuget-behavior.md). +Finally, NuGet's behavior is driven by `NuGet.Config` files. Multiple files can be used to centralize certain settings at different levels, as explained in [Configuring NuGet Behavior](../consume-packages/configuring-nuget-behavior.md). ## Ways to install a NuGet Package NuGet packages are downloaded and installed using any of the methods in the following table. -| Tool | Description | -| --- | --- | -| [dotnet.exe CLI](install-use-packages-dotnet-cli.md) | (All platforms) CLI tool for .NET Core and .NET Standard libraries, and for SDK-style projects that target .NET Framework (see [SDK attribute](/dotnet/core/tools/csproj#additions)). Retrieves the package identified by \ and adds a reference to the project file. Also retrieves and installs dependencies. | -| Visual Studio | (Windows and Mac) Provides a UI through which you can browse, select, and install packages and their dependencies into a project from a specified package source. Adds references to installed packages to the project file.
  • [Install and manage packages using Visual Studio](install-use-packages-visual-studio.md)
  • [Including a NuGet package in your project (Mac)](/visualstudio/mac/nuget-walkthrough)
| -| [Package Manager Console (Visual Studio)](install-use-packages-powershell.md) | (Windows only) Retrieves and installs the package identified by \ from a selected source into a specified project in the solution, then adds a reference to the project file. Also retrieves and installs dependencies. | -| [nuget.exe CLI](install-use-packages-nuget-cli.md) | (All platforms) CLI tool for .NET Framework libraries and non-SDK-style projects that target .NET Standard libraries. Retrieves the package identified by \ and expands its contents into a folder in the current directory; can also retrieve all packages listed in a `packages.config` file. Also retrieves and installs dependencies, but makes no changes to project files or `packages.config`. | +| Tool | Platforms | Description | +| --- | --- | --- | +| [dotnet CLI](install-use-packages-dotnet-cli.md) | All | CLI tool for .NET Core and .NET Standard libraries, and for SDK-style projects that target .NET Framework (see [SDK attribute](/dotnet/core/tools/csproj#additions)). Retrieves the package identified by \ and adds a reference to the project file. Also retrieves and installs dependencies. | +| Visual Studio | Windows and Mac | Provides a UI through which you can browse, select, and install packages and their dependencies into a project from a specified package source. Adds references to installed packages to the project file.
  • [Install and manage packages using Visual Studio](install-use-packages-visual-studio.md)
  • [Including a NuGet package in your project (Mac)](/visualstudio/mac/nuget-walkthrough)
| +| [Package Manager Console (Visual Studio)](install-use-packages-powershell.md) | Windows only | Retrieves and installs the package identified by \ from a selected source into a specified project in the solution, then adds a reference to the project file. Also retrieves and installs dependencies. | +| [nuget.exe CLI](install-use-packages-nuget-cli.md) | All | CLI tool for .NET Framework libraries and non-SDK-style projects that target .NET Standard libraries. Retrieves the package identified by \ and expands its contents into a folder in the current directory; can also retrieve all packages listed in a `packages.config` file. Also retrieves and installs dependencies, but makes no changes to project files or `packages.config`. | diff --git a/docs/consume-packages/Package-References-in-Project-Files.md b/docs/consume-packages/Package-References-in-Project-Files.md index b5bd5caa8..d9290e3cd 100644 --- a/docs/consume-packages/Package-References-in-Project-Files.md +++ b/docs/consume-packages/Package-References-in-Project-Files.md @@ -1,23 +1,23 @@ --- -title: NuGet PackageReference format (package references in project files) +title: NuGet PackageReference in project files description: Details on NuGet PackageReference in project files as supported by NuGet 4.0+ and VS2017 and .NET Core 2.0 -author: karann-msft -ms.author: karann -ms.date: 03/16/2018 -ms.topic: conceptual +author: nkolev92 +ms.author: nikolev +ms.date: 4/6/2022 +ms.topic: article --- -# Package references (PackageReference) in project files +# `PackageReference` in project files -Package references, using the `PackageReference` node, manage NuGet dependencies directly within project files (as opposed to a separate `packages.config` file). Using PackageReference, as it's called, doesn't affect other aspects of NuGet; for example, settings in `NuGet.config` files (including package sources) are still applied as explained in [Common NuGet configurations](configuring-nuget-behavior.md). +Package references, using `` MSBuild items, specify NuGet package dependencies directly within project files, as opposed to having a separate `packages.config` file. Use of PackageReference doesn't affect other aspects of NuGet; for example, settings in `NuGet.Config` files (including package sources) are still applied as explained in [Common NuGet configurations](configuring-nuget-behavior.md). -With PackageReference, you can also use MSBuild conditions to choose package references per target framework, configuration, platform, or other groupings. It also allows for fine-grained control over dependencies and content flow. (See For more details [NuGet pack and restore as MSBuild targets](../reference/msbuild-targets.md).) +With PackageReference, you can also use MSBuild conditions to choose package references per target framework, or other groupings. It also allows for fine-grained control over dependencies and content flow. (For more information, see [NuGet pack and restore as MSBuild targets](../reference/msbuild-targets.md).) ## Project type support -By default, PackageReference is used for .NET Core projects, .NET Standard projects, and UWP projects targeting Windows 10 Build 15063 (Creators Update) and later, with the exception of C++ UWP projects. .NET Framework projects support PackageReference, but currently default to `packages.config`. To use PackageReference, [migrate](../consume-packages/migrate-packages-config-to-package-reference.md) the dependencies from `packages.config` into your project file, then remove packages.config. +By default, PackageReference is used for .NET projects, .NET Standard projects, and UWP projects targeting Windows 10 Build 15063 (Creators Update) and later, with the exception of C++ UWP projects. .NET Framework projects support PackageReference, but currently default to `packages.config`. To use PackageReference in a .NET Framework project, [migrate](../consume-packages/migrate-packages-config-to-package-reference.md) the dependencies from `packages.config` into your project file, then remove packages.config. -ASP.NET apps targeting the full .NET Framework include only [limited support](https://github.com/NuGet/Home/issues/5877) for PackageReference. C++ and JavaScript project types are unsupported. +ASP.NET apps that target the full .NET Framework include only [limited support](https://github.com/NuGet/Home/issues/5877) for PackageReference. C++ and JavaScript project types are unsupported. ## Adding a PackageReference @@ -43,10 +43,12 @@ The convention for specifying the version of a package is the same as when using ``` -In the example above, 3.6.0 means any version that is >=3.6.0 with preference for the lowest version, as described on [Package versioning](../concepts/package-versioning.md#version-ranges-and-wildcards). +In the example above, 3.6.0 means any version that is >=3.6.0 with preference for the lowest version, as described in [Package versioning](../concepts/package-versioning.md#version-ranges). + +## Using PackageReference for a project with no package dependencies -## Using PackageReference for a project with no PackageReferences Advanced: If you have no packages installed in a project (no PackageReferences in project file and no packages.config file), but want the project to be restored as PackageReference style, you can set a Project property RestoreProjectStyle to PackageReference in your project file. + ```xml @@ -54,7 +56,12 @@ Advanced: If you have no packages installed in a project (no PackageReferences i ``` -This may be useful, if you reference projects which are PackageReference styled (existing csproj or SDK-style projects). This will enable packages that those projects refer to, to be "transitively" referenced by your project. + +This might be useful if you reference projects that are PackageReference styled (existing csproj or SDK-style projects). This will enable packages that those projects refer to, to be "transitively" referenced by your project. + +## PackageReference and sources + +In PackageReference projects, the transitive dependency versions are resolved at restore time. As such, in PackageReference projects, all sources need to be available for all restores. ## Floating Versions @@ -64,7 +71,7 @@ This may be useful, if you reference projects which are PackageReference styled - + ``` @@ -87,13 +94,13 @@ You might be using a dependency purely as a development harness and might not wa The following metadata tags control dependency assets: -| Tag | Description | Default Value | -| --- | --- | --- | -| IncludeAssets | These assets will be consumed | all | -| ExcludeAssets | These assets will not be consumed | none | +| Tag | Description | Default Value | +|---------------|--------------------------------------------------------------------|------------------------------| +| IncludeAssets | These assets will be consumed | all | +| ExcludeAssets | These assets will not be consumed | none | | PrivateAssets | These assets will be consumed but won't flow to the parent project | contentfiles;analyzers;build | -Allowable values for these tags are as follows, with multiple values separated by a semicolon except with `all` and `none` which must appear by themselves: +Allowable values for these tags are as follows, with multiple values separated by a semicolon except for `all` and `none`, which must appear by themselves: | Value | Description | | --- | --- @@ -108,18 +115,23 @@ Allowable values for these tags are as follows, with multiple values separated b | none | None of the above are used. | | all | All of the above (except `none`) | -In the following example, everything except the content files from the package would be consumed by the project and everything except content files and analyzers would flow to the parent project. - ```xml - + + - all + all contentFiles contentFiles;analyzers - + + + + + compile + contentFiles + ``` @@ -131,9 +143,9 @@ Note that because `build` is not included with `PrivateAssets`, targets and prop ## Adding a PackageReference condition -You can use a condition to control whether a package is included, where conditions can use any MSBuild variable or a variable defined in the targets or props file. However, at presently, only the `TargetFramework` variable is supported. +You can use a condition to control whether a package is included. Conditions can use any MSBuild variable or a variable defined in the targets or props file. However, at present, only the `TargetFramework` variable is supported. -For example, say you're targeting `netstandard1.4` as well as `net452` but have a dependency that is applicable only for `net452`. In this case you don't want a `netstandard1.4` project that's consuming your package to add that unnecessary dependency. To prevent this, you specify a condition on the `PackageReference` as follows: +For example, say you're targeting `netstandard1.4` as well as `net452` but have a dependency that's applicable only for `net452`. In this case you don't want a `netstandard1.4` project that consumes your package to add that unnecessary dependency. To prevent this, you specify a condition on the `PackageReference` as follows: ```xml @@ -158,23 +170,156 @@ Conditions can also be applied at the `ItemGroup` level and will apply to all ch ``` +## GeneratePathProperty + +This feature is available with NuGet **5.0** or above and with Visual Studio 2019 **16.0** or above. + +Sometimes it is desirable to reference files in a package from an MSBuild target. +In `packages.config` based projects, the packages are installed in a folder relative to the project file. However in PackageReference, the packages are [consumed](../concepts/package-installation-process.md) from the *global-packages* folder, which can vary from machine to machine. + +To bridge that gap, NuGet introduced a property that points to the location from which the package will be consumed. + +Example: + +```xml + + + + + + + +```` + +Additionally NuGet automatically generates properties for packages containing a tools folder. + +```xml + + + + + + + +``` + +MSBuild properties and package identities do not have the same restrictions so the package identity needs to be changed to an MSBuild friendly name, prefixed by the word `Pkg`. +To verify the exact name of the property generated, look at the generated [nuget.g.props](../reference/msbuild-targets.md#restore-outputs) file. + +## PackageReference aliases + +In some rare instances, different packages will contain classes in the same namespace. Starting with NuGet 5.7 & Visual Studio 2019 Update 7, equivalent to ProjectReference, PackageReference supports [`Aliases`](/dotnet/api/microsoft.codeanalysis.projectreference.aliases). +By default, no aliases are provided. When an alias is specified, *all* assemblies coming from the annotated package need to be referenced with an alias. + +You can look at sample usage at [NuGet\Samples](https://github.com/NuGet/Samples/tree/main/PackageReferenceAliasesExample). + +In the project file, specify the aliases as follows: + +```xml + + + +``` + +And in the code, use it as follows: + +```cs +extern alias ExampleAlias; + +namespace PackageReferenceAliasesExample +{ +... + { + var version = ExampleAlias.NuGet.Versioning.NuGetVersion.Parse("5.0.0"); + Console.WriteLine($"Version : {version}"); + } +... +} + +``` + +## NuGet warnings and errors + +*This feature is available with NuGet **4.3** or above and with Visual Studio 2017 **15.3** or above.* + +For many pack and restore scenarios, all NuGet warnings and errors are coded, and start with `NU****`. All NuGet warnings and errors are listed in the [reference](../reference/errors-and-warnings.md) documentation. + +NuGet observes the following warning properties: + +- `TreatWarningsAsErrors`, treat all warnings as errors. +- `WarningsAsErrors`, treat specific warnings as errors. +- `NoWarn`, hide specific warnings, either project-wide or package-wide. + +Examples: + +```xml + + true + +... + + $(WarningsAsErrors);NU1603;NU1605 + +... + + $(NoWarn);NU5124 + +... + + + +``` + +### Suppressing NuGet warnings + +While it is recommended that you resolve all NuGet warnings during your pack and restore operations, in certain situations suppressing them is warranted. +To suppress a warning project wide, consider doing: + +```xml + + 5.0.0 + $(NoWarn);NU5104 + + + + +``` + +Sometimes warnings apply only to a certain package in the graph. You can choose to suppress that warning more selectively by adding a `NoWarn` on the PackageReference item. + +```xml + + 5.0.0 + + + + +``` + +#### Suppressing NuGet package warnings in Visual Studio + +When in Visual Studio, you can also [suppress warnings](/visualstudio/ide/how-to-suppress-compiler-warnings#suppress-warnings-for-nuget-packages +) through the IDE. + ## Locking dependencies + *This feature is available with NuGet **4.9** or above and with Visual Studio 2017 **15.9** or above.* -Input to NuGet restore is a set of Package References from the project file (top-level or direct dependencies) and the output is a full closure of all the package dependencies including transitive dependencies. NuGet tries to always produce the same full closure of package dependencies if the input PackageReference list has not changed. However, there are some scenarios where it is unable to do so. For example: +Input to NuGet restore is a set of `PackageReference` items from the project file (top-level or direct dependencies) and the output is a full closure of all the package dependencies including transitive dependencies. NuGet tries to always produce the same full closure of package dependencies if the input PackageReference list has not changed. However, there are some scenarios where it is unable to do so. For example: + +- When you use floating versions like ``. While the intention here is to float to the latest version on every restore of packages, there are scenarios where users require the graph to be locked to a certain latest version and float to a later version, if available, upon an explicit gesture. +- A newer version of the package matching PackageReference version requirements is published. For example: -* When you use floating versions like ``. While the intention here is to float to the latest version on every restore of packages, there are scenarios where users require the graph to be locked to a certain latest version and float to a later version, if available, upon an explicit gesture. -* A newer version of the package matching PackageReference version requirements is published. E.g. + - Day 1: if you specified `` but the versions available on the + NuGet repositories were 4.1.0, 4.2.0, and 4.3.0. In this case, NuGet would have resolved to 4.1.0 (nearest minimum version). - * Day 1: if you specified `` but the versions available on the - NuGet repositories were 4.1.0, 4.2.0 and 4.3.0. In this case, NuGet would have resolved to 4.1.0 (nearest minimum version) + - Day 2: Version 4.0.0 gets published. NuGet will now find the exact match and start resolving to 4.0.0. - * Day 2: Version 4.0.0 gets published. NuGet will now find the exact match and start resolving to 4.0.0 +- A given package version is removed from the repository. Though nuget.org does not allow package deletions, not all package repositories have this constraint. This results in NuGet finding the best match when it cannot resolve to the deleted version. -* A given package version is removed from the repository. Though nuget.org does not allow package deletions, not all package repositories have this constraints. This results in NuGet finding the best match when it cannot resolve to the deleted version. +### Enabling the lock file -### Enabling lock file -In order to persist the full closure of package dependencies you can opt-in to the lock file feature by setting the MSBuild property `RestorePackagesWithLockFile` for your project: +In order to persist the full closure of package dependencies, you can opt-in to the lock file feature by setting the MSBuild property `RestorePackagesWithLockFile` for your project: ```xml @@ -184,29 +329,33 @@ In order to persist the full closure of package dependencies you can opt-in to t ``` -If this property is set, NuGet restore will generate a lock file - `packages.lock.json` file at the project root directory that lists all the package dependencies. +If this property is set, NuGet restore will generate a lock file (`packages.lock.json`) at the project root directory that lists all the package dependencies. > [!Note] > Once a project has `packages.lock.json` file in its root directory, the lock file is always used with restore even if the property `RestorePackagesWithLockFile` is not set. So another way to opt-in to this feature is to create a dummy blank `packages.lock.json` file in the project's root directory. ### `restore` behavior with lock file -If a lock file is present for project, NuGet uses this lock file to run `restore`. NuGet does a quick check to see if there were any changes in the package dependencies as mentioned in the project file (or dependent projects' files) and if there were no changes it just restores the packages mentioned in the lock file. There is no re-evaluation of package dependencies. + +If a lock file is present for a project, NuGet uses this lock file to run `restore`. NuGet does a quick check to see if there were any changes in the package dependencies as mentioned in the project file (or dependent projects' files), and if there were no changes, it just restores the packages mentioned in the lock file. There is no re-evaluation of package dependencies. If NuGet detects a change in the defined dependencies as mentioned in the project file(s), it re-evaluates the package graph and updates the lock file to reflect the new package closure for the project. For CI/CD and other scenarios, where you would not want to change the package dependencies on the fly, you can do so by setting the `lockedmode` to `true`: For dotnet.exe, run: + ``` > dotnet.exe restore --locked-mode ``` For msbuild.exe, run: + ``` > msbuild.exe -t:restore -p:RestoreLockedMode=true ``` -You may also set this conditional MSBuild property in your project file: +You can also set this conditional MSBuild property in your project file: + ```xml @@ -217,26 +366,193 @@ You may also set this conditional MSBuild property in your project file: If locked mode is `true`, restore will either restore the exact packages as listed in the lock file or fail if you updated the defined package dependencies for the project after lock file was created. +#### Lock files and PrunePackageReference + +[PrunePackageReference](#prunepackagereference) changes the dependencies of a project, by removing unnecessary transitive packages. +While removing these packages should not have an impact at runtime, it will affect lock files. +If you enable pruning for an existing project, whenever the lock file gets regenerated, it may lead to fewer packages than before pruning. +The lock file up to date check that powers locked mode is pruning aware, which means if you enabled pruning on a project, the check will account for packages that are pruned. +However the next time the lock file is regenerated, it will exclude the pruned packages, so you may see a diff that's larger than usual. + ### Make lock file part of your source repository -If you are building an application, an executable and the project in question is at the start of the dependency chain then do check in the lock file to the source code repository so that NuGet can make use of it during restore. -However, if your project is a library project that you do not ship or a common code project on which other projects depend upon, you **should not** check in the lock file as part of your source code. There is no harm in keeping the lock file but the locked package dependencies for the common code project may not be used, as listed in the lock file, during the restore/build of a project that depends on this common-code project. +If you are building an application, an executable, and the project in question is at the start of the dependency chain, then do check in the lock file to the source code repository so that NuGet can make use of it during restore. + +However, if your project is a library project that you do not ship or a common code project on which other projects depend, you **should not** check in the lock file as part of your source code. There is no harm in keeping the lock file, but the locked package dependencies for the common code project can't be used, as listed in the lock file, during the restore/build of a project that depends on this common-code project. + +Example: -Eg. ``` ProjectA |------> PackageX 2.0.0 |------> ProjectB |------>PackageX 1.0.0 ``` + If `ProjectA` has a dependency on a `PackageX` version `2.0.0` and also references `ProjectB` that depends on `PackageX` version `1.0.0`, then the lock file for `ProjectB` will list a dependency on `PackageX` version `1.0.0`. However, when `ProjectA` is built, its lock file will contain a dependency on `PackageX` version **`2.0.0`** and **not** `1.0.0` as listed in the lock file for `ProjectB`. Thus, the lock file of a common code project has little say over the packages resolved for projects that depend on it. ### Lock file extensibility + You can control various behaviors of restore with lock file as described below: -| Option | MSBuild equivalent option | -|:--- |:--- | -| `--use-lock-file` | Bootstraps use of lock file for a project. You can alternatively set `RestorePackagesWithLockFile` property in the project file | -| `--locked-mode` | Enables locked mode for restore. This is useful in CI/CD scenarios where you would like to get the repeatable builds. This can be also by setting the `RestoreLockedMode` MSBuild property to `true` | -| `--force-evaluate` | This option is useful with packages with floating version defined in the project. By default, NuGet restore will not update the package version automatically upon each restore unless you run restore with `--force-evaluate` option. | -| `--lock-file-path` | Defines a custom lock file location for a project. This can be also achieved by setting the MSBuild property `NuGetLockFilePath`. By default, NuGet supports `packages.lock.json` at the root directory. If you have multiple projects in the same directory, NuGet supports project specific lock file `packages..lock.json` | +| NuGet.exe option | dotnet option | MSBuild equivalent option | Description | +|:--- |:--- |:--- |:--- | +| `-UseLockFile` |`--use-lock-file` | RestorePackagesWithLockFile | Opts into the usage of a lock file. | +| `-LockedMode` | `--locked-mode` | RestoreLockedMode | Enables locked mode for restore. This is useful in CI/CD scenarios where you want repeatable builds.| +| `-ForceEvaluate` | `--force-evaluate` | RestoreForceEvaluate | This option is useful with packages with floating version defined in the project. By default, NuGet restore will not update the package version automatically upon each restore unless you run restore with this option. | +| `-LockFilePath` | `--lock-file-path` | NuGetLockFilePath | Defines a custom lock file location for a project. By default, NuGet supports `packages.lock.json` at the root directory. If you have multiple projects in the same directory, NuGet supports project specific lock file `packages..lock.json` | + +## NuGet Dependency Resolver + +The NuGet dependency resolver follows the [four rules as described in the dependency resolution document](../../docs/concepts/Dependency-Resolution.md). + +In order to improve the performance and scalability of the restore operation, the restore algorithm was rewritten in the 6.12 release. +As of the 6.12 release, the new restore algorithm is enabled by default for all PackageReference projects. +While the new restore algorithm is is functionally equivalent to the previous one, as with any software, bugs are possible. +To revert to the previous implementation, set the MSBuild property `RestoreUseLegacyDependencyResolver` to `true`. + +Should you face restore failures in 6.12, .NET 9 or 17.12, that weren't reproducing in earlier versions, please [file an issue on GitHub](https://github.com/NuGet/Home/issues/). +Any differences between the old and new algorithms may have different impacts, such as during compilation or at runtime. +There's also a chance that changes don't lead to failures, but different package versions being restored. +If you think you might be impacted by any changes, here are the steps you can take to verify whether the changes in the NuGet restore algorithm are the root cause. + +Restore writes its results in the `MSBuildProjectExtensionsPath` directory, which can be compared with the new and old algorithms to find differences. +Usually this is the `obj` folder of your build. +You can use `msbuild.exe` or `dotnet.exe` for the next steps. + +1. Remove the `obj` folder for your project. +1. Run `msbuild -t:restore` +1. Save the contents of the `obj` to a location indicating that it's the `new` behavior. +1. Run `msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true"`. +1. Save the contents of the `obj` to a location indicating that it's the `legacy` behavior. +1. Compare the files in the two directories, particularly *project.assets.json*. + + Tools that can highlight differences are especially useful for this (for example, in Visual Studio Code, open both files, and use the right-click "select for compare" and "compare to selected"). + +If you follow the above method, there should be exactly 1 difference between the `project.assets.json` files: + +```diff + "projectStyle": "PackageReference", ++ "restoreUseLegacyDependencyResolver": true, + "fallbackFolders": [ +``` + +If there are any more differences, please [file an issue on GitHub](https://github.com/NuGet/Home/issues/) with all the details. + +## AssetTargetFallback + +The `AssetTargetFallback` property lets you specify additional compatible framework versions for projects that your project references and NuGet packages that your project consumes. + +If you specify a package dependency using `PackageReference` but that package doesn't contain assets that are compatible with your projects's target framework, the `AssetTargetFallback` property comes into play. The compatibility of the referenced package is rechecked using each target framework that's specified in `AssetTargetFallback`. +When a `project` or a `package` is referenced through `AssetTargetFallback`, the [NU1701](../reference/errors-and-warnings/NU1701.md) warning will be raised. + +Refer to the table below for examples of how `AssetTargetFallback` affects compatibility. + +| Project framework | AssetTargetFallback | Package frameworks | Result | +|-------------------|---------------------|--------------------|--------| +| .NET Framework 4.7.2 | | .NET Standard 2.0 | .NET Standard 2.0 | +| .NET Core App 3.1 | | .NET Standard 2.0, .NET Framework 4.7.2 | .NET Standard 2.0 | +| .NET Core App 3.1 | | .NET Framework 4.7.2 | Incompatible, fail with [`NU1202`](../reference/errors-and-warnings/NU1202.md) | +| .NET Core App 3.1 | net472;net471 | .NET Framework 4.7.2 | .NET Framework 4.7.2 with [`NU1701`](../reference/errors-and-warnings/NU1701.md) | + +Multiple frameworks can be specified using `;` as a delimiter. To add a fallback framework you can do the following: + +```xml + + $(AssetTargetFallback);net472;net471 + +``` + +You can leave off `$(AssetTargetFallback)` if you wish to overwrite, instead of add to the existing `AssetTargetFallback` values. + +> [!NOTE] +> If you are using a [.NET SDK based project](/dotnet/core/sdk), appropriate `$(AssetTargetFallback)` values are configured and you do not need to set them manually. +> +> `$(PackageTargetFallback)` was an earlier feature that attempted to address this challenge, but it is fundamentally broken and *should* not be used. To migrate from `$(PackageTargetFallback)` to `$(AssetTargetFallback)`, simply change the property name. + +## PrunePackageReference + +The .NET Runtime is constantly evolving, with performance improvements and new APIs each release. +New features added to .NET are also sometimes provided as packages, so that developers using older target frameworks can use the library, such as [System.Text.Json](https://www.nuget.org/packages/System.Text.Json). +This can often lead to a `System.Text.Json 8.0.0` in a project targeting `.NET 9` or `.NET 8`. This dependency is unnecessary and the build conflict resolution would not use the assembly coming from the package since it's already available in the .NET Runtime. +Starting in [NuGet version 6.13](..\release-notes\NuGet-6.13.md) and .NET SDK 9.0.200, `PrunePackageReference` enables the pruning of these packages at restore time for .NET SDK based projects. +The first iteration of pruning affected transitive packages only, but starting with .NET SDK 10, package pruning affects direct packages as well. + +Package pruning is available as an opt-in feature with the .NET 9 SDK, and is enabled by default for all frameworks of a project that targets `>= .NET 10.0` in the .NET 10 SDK. + +Package pruning is only available with the default dependency resolver as [released in 6.12](#nuget-dependency-resolver). + +### PrunePackageReference specification + +The list of packages to be pruned is defined with the `PrunePackageReference` item. + +| Attributes | Description | +|------------|-------------| +| Version | Specifies the maximum version to be pruned. `1.0.0` means that all packages up to and including 1.0.0 will be pruned. For `1.0.0`, `0.9.0` and `1.0.0` will be pruned, but `1.0.1` would not. | + +The following properties can be used to modify the pruning behavior. + +| PropertyName | Description | +|--------------|-------------| +| RestoreEnablePackagePruning | Enables package pruning for the packages specified with `PrunePackageReference`. This property is per target framework and the valid values are `true` and `false`. Defaults may differ based on the .NET SDK as defined above. | + +The .NET SDK predefines the list of packages to be pruned for you. + +### How PrunePackageReference works + +When a package is specified to be pruned during restore, it is removed from the dependency graph. +When a package is pruned, there is a message, visible at detailed verbosity, indicating that the package has been removed for the given target framework. + +For transitive packages, meaning dependencies of other packages or projects, the packages are not downloaded and do not appear in any of the outputs of NuGet. + +For direct packages, `PrivateAssets='all'` and `IncludeAssets='none'` are implicitly applied. + +- `IncludeAssets='none'` ensures that the assemblies from this package are not used during the build. Before pruning existed, the conflict resolution during the build ensured that platform assemblies were preferred over those coming from the packages. +- `PrivateAssets='all'` ensures that the packages aren't included in packages or through project references. + +Example: + +A project like below: + +```xml + + net9.0;netstandard2.0 + + + + + +``` + +will have a nuspec with the following dependencies: + +```xml + + + + + + + +``` + +When a direct PackageReference can be completely removed from your project, and one of the project frameworks are .NET 10 or newer, [NU1510](../reference/errors-and-warnings/NU1510.md) will be raised asking you to remove the package. +Following this suggestion will reduce the complexity of your project graph. + +The following table summarizes all the package pruning behaviors. + +| Dependency disposition | Behavior | +|-----------------|----------| +| Matches the ID of a transitive package coming through another package | Prune | +| Matches the ID of a transitive package coming through another project | Prune | +| Matches the ID of a direct `PackageReference` | Apply `PrivateAssets='all'` and `IncludeAssets='none'` and raise the [NU1510](../reference/errors-and-warnings/NU1510.md) warning when the package can be removed from all frameworks and the project targets .NET 10. | +| Matches the ID of a `ProjectReference` | Do not prune and raise the [NU1511](../reference/errors-and-warnings/NU1511.md) warning when the project targets .NET 10 | + +### PrunePackageReference applications + +The benefits of package pruning are two-fold: + +- Performance benefits, by virtue of reducing the number of packages within a dependency graph +- Reduction of false positives by component scanners such as `NuGetAudit` + +Pruning is particularly valuable when [auditing](./../concepts/Auditing-Packages.md) packages with `NuGetAuditMode` set to `all`. If you are using .NET 9, we recommend you try out pruning by setting `RestoreEnablePackagePruning` to `true`. diff --git a/docs/consume-packages/Package-Restore.md b/docs/consume-packages/Package-Restore.md index 9f92b3b18..62f1f673f 100644 --- a/docs/consume-packages/Package-Restore.md +++ b/docs/consume-packages/Package-Restore.md @@ -1,220 +1,226 @@ --- title: NuGet Package Restore -description: An overview of how NuGet restores packages a project depends on, including how to disable restore and constrain versions. -author: karann-msft -ms.author: karann -ms.date: 08/05/2019 -ms.topic: conceptual +description: See an overview of how NuGet restores packages a project depends on, including how to disable restore and constrain versions. +author: JonDouglas +ms.author: jodou +ms.date: 10/20/2023 +ms.topic: how-to --- -# Restore packages using Package Restore +# Restore packages with NuGet Package Restore -To promote a cleaner development environment and to reduce repository size, NuGet **Package Restore** installs all of a project's dependencies listed in either the project file or `packages.config`. The .NET Core 2.0+ `dotnet build` and `dotnet run` commands do an automatic package restore. Visual Studio can restore packages automatically when it builds a project, and you can restore packages at any time through Visual Studio, `nuget restore`, `dotnet restore`, and xbuild on Mono. +NuGet Package Restore restores all of a project's dependencies that are listed in either a project file or a *packages.config* file. You can restore packages manually with `nuget restore`, `dotnet restore`, `msbuild -t:restore`, or through Visual Studio. The `dotnet build` and `dotnet run` commands automatically restore packages, and you can configure Visual Studio to restore packages automatically when it builds a project. -Package Restore makes sure that all a project's dependencies are available, without having to store them in source control. To configure your source control repository to exclude the package binaries, see [Packages and source control](../consume-packages/packages-and-source-control.md). +To promote a cleaner development environment and to reduce repository size, Package Restore makes all of a project's dependencies available without having to store them in source control. To configure your source control repository to exclude package binaries, see [Packages and source control](../consume-packages/packages-and-source-control.md). -## Package Restore overview +## Package Restore behavior -Package Restore first installs the direct dependencies of a project as needed, then installs any dependencies of those packages throughout the entire dependency graph. +Package Restore tries to install all package dependencies to the state that matches the ``s in a project file, such as *.csproj*, or ``s in a *packages.config* file. Package Restore first installs the direct dependencies of a project as needed, then installs any dependencies of those packages throughout the entire dependency graph. -If a package isn't already installed, NuGet first attempts to retrieve it from the [cache](../consume-packages/managing-the-global-packages-and-cache-folders.md). If the package isn't in the cache, NuGet tries to download the package from all enabled sources in the list at **Tools** > **Options** > **NuGet Package Manager** > **Package Sources** in Visual Studio. During restore, NuGet ignores the order of package sources, and uses the package from whichever source is first to respond to requests. For more information about how NuGet behaves, see [Common NuGet configurations](Configuring-NuGet-Behavior.md). +If a needed package isn't already installed, NuGet first attempts to retrieve it from the local [global packages or HTTP cache folders](../consume-packages/managing-the-global-packages-and-cache-folders.md). If the package isn't in the local folders, NuGet tries to download it from all sources configured in Visual Studio at **Tools** > **Options** > **NuGet Package Manager** > **Package Sources**. -> [!Note] -> NuGet doesn't indicate a failure to restore a package until all the sources have been checked. At that time, NuGet reports a failure for only the last source in the list. The error implies that the package wasn't present on *any* of the other sources, even though errors aren't shown for each of those sources individually. +During restore, NuGet ignores the order of package sources, and uses the package from the first source that responds to requests. If restore fails, NuGet doesn't indicate the failure until after it checks all sources. NuGet then reports a failure for only the last source in the list. The error implies that the package wasn't present on any of the sources, even though it doesn't list the other failures individually. + +For more information about NuGet behavior, see [Common NuGet configurations](Configuring-NuGet-Behavior.md). ## Restore packages -Package Restore tries to install all package dependencies to the correct state matching the package references in your project file (*.csproj*) or your *packages.config* file. (In Visual Studio, the references appear in Solution Explorer under the **Dependencies \ NuGet** or the **References** node.) +If the package references in your project file or *packages.config* file are correct, use your preferred tool to restore packages: -1. If the package references in your project file are correct, use your preferred tool to restore packages. +- [Visual Studio](#restore-using-visual-studio) +- [dotnet CLI](#restore-using-the-dotnet-cli) +- [nuget.exe CLI](#restore-using-the-nugetexe-cli) +- [MSBuild](#restore-using-msbuild) +- [Azure Pipelines or Azure DevOps Server](#restore-using-azure-pipelines) - - [Visual Studio](#restore-using-visual-studio) ([automatic restore](#restore-packages-automatically-using-visual-studio) or [manual restore](#restore-packages-manually-using-visual-studio)) - - [dotnet CLI](#restore-using-the-dotnet-cli) - - [nuget.exe CLI](#restore-using-the-nugetexe-cli) - - [MSBuild](#restore-using-msbuild) - - [Azure Pipelines](#restore-using-azure-pipelines) - - [Azure DevOps Server](#restore-using-azure-devops-server) +After a successful restore: - If the package references in your project file (*.csproj*) or your *packages.config* file are incorrect (they do not match your desired state following Package Restore), then you need to either install or update packages instead. +- For projects that use ``, the package is present in the local *global-packages* folder, and the project *obj/project.assets.json* file is recreated. +- For projects that use *packages.config*, the package appears in the project's *packages* folder. +- The project should now build successfully. - For projects using PackageReference, after a successful restore, the package should be present in the *global-packages* folder and the `obj/project.assets.json` file is recreated. For projects using `packages.config`, the package should appear in the project's `packages` folder. The project should now build successfully. +If the package references in your project file or your *packages.config* file are incorrect and don't match your desired state, install or update the correct packages instead of using Package Restore. -2. After running Package Restore, if you still experience missing packages or package-related errors (such as error icons in Solution Explorer in Visual Studio), you may need to follow instructions described in [Troubleshooting Package Restore errors](package-restore-troubleshooting.md) or, alternatively, [reinstall and update packages](../consume-packages/reinstalling-and-updating-packages.md). +If you have missing packages or package-related errors after you run Package Restore, such as error icons in Solution Explorer, follow the instructions in [Troubleshooting Package Restore errors](package-restore-troubleshooting.md), or [reinstall or update](../consume-packages/reinstalling-and-updating-packages.md) the packages. In Visual Studio, the Package Manager Console provides several options for reinstalling packages. For more information, see [Use Package-Update](reinstalling-and-updating-packages.md#update-package-command). - In Visual Studio, the Package Manager Console provides several flexible options for reinstalling packages. See [Using Package-Update](reinstalling-and-updating-packages.md#using-update-package). + -## Restore using Visual Studio +## Restore packages in Visual Studio -In Visual Studio on Windows, either: +In Visual Studio on Windows, you can restore packages automatically or manually. First, configure Package Restore through **Tools** > **Options** > **NuGet Package Manager**. -- Restore packages automatically, or +### Configure Visual Studio Package Restore options -- Restore packages manually +Configure the following Package Restore options at **Tools** > **Options** > **NuGet Package Manager** > **General**. -### Restore packages automatically using Visual Studio +![Screenshot that shows the NuGet Package Manager options.](media/vsoptions/general.png) -Package Restore happens automatically when you create a project from a template or build a project, subject to the options in [Enable and disable package restore](#enable-and-disable-package-restore-in-visual-studio). In NuGet 4.0+, restore also happens automatically when you make changes to a SDK-style project (typically a .NET Core or .NET Standard project). + -1. Enable automatic package restore by choosing **Tools** > **Options** > **NuGet Package Manager**, and then selecting **Automatically check for missing packages during build in Visual Studio** under **Package Restore**. +#### Allow NuGet to download missing packages - For non-SDK-style projects, you first need to select **Allow NuGet to download missing packages** to enable the automatic restore option. +Select **Allow NuGet to download missing packages** to enable package restore and the **Restore NuGet Packages** command. This selection sets the `packageRestore/enabled` setting to `True` in the [packageRestore section](../reference/nuget-config-file.md#packagerestore-section) of the global *NuGet.Config* file, at *%AppData%\\Roaming\\NuGet* on Windows or *~/.nuget/NuGet/* on Mac or Linux. -1. Build the project. +```xml + + + + + +``` - If one or more individual packages still aren't installed properly, **Solution Explorer** shows an error icon. Right-click and select **Manage NuGet Packages**, and use **Package Manager** to uninstall and reinstall the affected packages. For more information, see [Reinstall and update packages](../consume-packages/reinstalling-and-updating-packages.md) +> [!Note] +> To globally override the `packageRestore/enabled` setting, you can set the environment variable **EnableNuGetPackageRestore** to True or False before you open Visual Studio or start a build. - If you see the error "This project references NuGet package(s) that are missing on this computer," or "One or more NuGet packages need to be restored but couldn't be because consent has not been granted," [enable automatic restore](#enable-and-disable-package-restore-in-visual-studio). For older projects, also see [Migrate to automatic package restore](#migrate-to-automatic-package-restore-visual-studio). Also see [Package Restore troubleshooting](Package-restore-troubleshooting.md). +To enable or disable Package Restore for all users on a computer, you can add the configuration settings to the global *NuGet.Config* file in Windows at *%ProgramData%\NuGet\Config*, sometimes under a specific *\\\\\\\* Visual Studio folder, or in Mac/Linux at *~/.local/share*. Individual users can then selectively enable restore as needed on a project level. For more details on how NuGet prioritizes multiple config files, see [Common NuGet configurations](../consume-packages/configuring-nuget-behavior.md#how-settings-are-applied). -### Restore packages manually using Visual Studio +> [!Important] +> If you edit the `packageRestore` settings in *NuGet.Config* directly, restart Visual Studio so that the **Options** show the current values. -1. Enable package restore by choosing **Tools** > **Options** > **NuGet Package Manager**. Under **Package Restore** options, select **Allow NuGet to download missing packages**. +#### Automatically check for missing packages during build -1. In **Solution Explorer**, right click the solution and select **Restore NuGet Packages**. +Select **Automatically check for missing packages during build in Visual Studio** to automatically restore any missing packages when you run a build from Visual Studio. This setting doesn't affect builds run from the MSBuild command line. This selection sets the `packageRestore/automatic` setting to `True` in the `packageRestore` section of the *NuGet.Config* file. - If one or more individual packages still aren't installed properly, **Solution Explorer** shows an error icon. Right-click and select **Manage NuGet Packages**, and then use **Package Manager** to uninstall and reinstall the affected packages. For more information, see [Reinstall and update packages](../consume-packages/reinstalling-and-updating-packages.md) +```xml + + + + + +``` - If you see the error "This project references NuGet package(s) that are missing on this computer," or "One or more NuGet packages need to be restored but couldn't be because consent has not been granted," [enable automatic restore](#enable-and-disable-package-restore-in-visual-studio). For older projects, also see [Migrate to automatic package restore](#migrate-to-automatic-package-restore-visual-studio). Also see [Package Restore troubleshooting](Package-restore-troubleshooting.md). +You must select **Allow NuGet to download missing packages** as well as **Automatically check for missing packages during build in Visual Studio** in **Options** to enable package restore during build. -### Enable and disable package restore in Visual Studio + -In Visual Studio, you control Package Restore primarily through **Tools** > **Options** > **NuGet Package Manager**: +#### Choose the default package management format -![Control Package Restore through NuGet Package Manager options](media/Restore-01-AutoRestoreOptions.png) +NuGet has two package management formats, [PackageReference](Package-References-in-Project-Files.md) and [packages.config](../reference/packages-config.md). Select the format you want to use from the dropdown list under **Package Management**. You can also select whether to allow format selection on first package install. -- **Allow NuGet to download missing packages** controls all forms of package restore by changing the `packageRestore/enabled` setting in the [packageRestore section](../reference/nuget-config-file.md#packagerestore-section) of the `NuGet.Config` file, at `%AppData%\NuGet\` on Windows, or `~/.nuget/NuGet/` on Mac/Linux. This setting also enables the **Restore NuGet Packages** command on the solution's context menu in Visual Studio, . +> [!Note] +> +> - If a project doesn't support both package management formats, NuGet uses the package management format that's compatible with the project, which might not be the default you set in the options. NuGet then won't prompt for selection on first install, even if you selected that option. +> +> - If you use Package Manager Console to install the first package in a project, NuGet doesn't prompt for format selection, even if that option is selected in **Options**. - ```xml - - - - - - - ``` - - > [!Note] - > To globally override the `packageRestore/enabled` setting, set the environment variable **EnableNuGetPackageRestore** with a value of True or False before launching Visual Studio or starting a build. + + -- **Automatically check for missing packages during build in Visual Studio** controls automatic restore by changing the `packageRestore/automatic` setting in the [packageRestore section](../reference/nuget-config-file.md#packagerestore-section) of the `NuGet.Config` file. When this option is set to True, running a build from Visual Studio automatically restores any missing packages. This setting doesn't affect builds run from the MSBuild command line. +### Restore packages manually or automatically - ```xml - ... - - - - - - - ``` +After you enable package restore in **Options**, you can right-click the solution in **Solution Explorer** and select **Restore NuGet Packages** to restore packages anytime. -To enable or disable Package Restore for all users on a computer, a developer or company can add the configuration settings to the global `nuget.config` file. The global `nuget.config` is in Windows at `%ProgramData%\NuGet\Config`, sometimes under a specific `\{IDE}\{Version}\{SKU}\` Visual Studio folder, or in Mac/Linux at `~/.local/share`. Individual users can then selectively enable restore as needed on a project level. For more details on how NuGet prioritizes multiple config files, see [Common NuGet configurations](../consume-packages/configuring-nuget-behavior.md#how-settings-are-applied). +If you enabled automatic restore in **Options**, Package Restore happens automatically when you create a project from a template or build a project. For NuGet 4.0+, restore also happens automatically when you make changes to a SDK-style project. -> [!Important] -> If you edit the `packageRestore` settings directly in `nuget.config`, restart Visual Studio, so that the **Options** dialog box shows the current values. +For projects that use ``, you can see the package references in Visual Studio **Solution Explorer** under **Dependencies** > **Packages**. Packages that don't install properly when you manually restore or run a build display error icons in **Solution Explorer**. Right-click the project, select **Manage NuGet Packages**, and use the **NuGet Package Manager** to uninstall and reinstall the affected packages. For more information, see [Reinstall and update packages](../consume-packages/reinstalling-and-updating-packages.md). + +If you see the error **This project references NuGet package(s) that are missing on this computer**, or **One or more NuGet packages need to be restored but couldn't be because consent has not been granted**, make sure you enabled automatic restore. For older projects, see [Migrate to automatic package restore](#migrate-to-automatic-package-restore-visual-studio). Also see [Troubleshooting package restore errors](Package-restore-troubleshooting.md). -## Restore using the dotnet CLI + + +## Restore by using the dotnet CLI [!INCLUDE [restore-dotnet-cli](includes/restore-dotnet-cli.md)] > [!IMPORTANT] -> To add a missing package reference to the project file, use [dotnet add package](/dotnet/core/tools/dotnet-add-package?tabs=netcore2x), which also runs the `restore` command. +> To add a missing package reference to the project file, use [dotnet add package](/dotnet/core/tools/dotnet-add-package), which also runs `restore`. + + -## Restore using the nuget.exe CLI +## Restore by using the NuGet CLI [!INCLUDE [restore-nuget-exe-cli](includes/restore-nuget-exe-cli.md)] -> [!IMPORTANT] -> The `restore`command does not modify a project file or *packages.config*. To add a dependency, either add a package through the Package Manager UI or Console in Visual Studio, or modify *packages.config* and then run either `install` or `restore`. + -## Restore using MSBuild +## Restore by using MSBuild -To restore packages listed in the project file with PackageReference, use the the [msbuild -t:restore](../reference/msbuild-targets.md#restore-target) command. This command is available only in NuGet 4.x+ and MSBuild 15.1+, which are included with Visual Studio 2017 and higher versions. Both `nuget restore` and `dotnet restore` use this command for applicable projects. +You can use [msbuild -t:restore](../reference/msbuild-targets.md#restore-target) to restore packages in NuGet 4.x+ and MSBuild 15.1+, which are included with Visual Studio 2017 and higher. -1. Open a Developer command prompt (In the **Search** box, type **Developer command prompt**). +This command restores packages in projects that use [PackageReference](package-references-in-project-files.md) for package references. Starting with MSBuild 16.5+, the command also supports [packages.config](/nuget/reference/packages-config) package references, when used with `-p:RestorePackagesConfig=true`. - You typically want to start the Developer Command Prompt for Visual Studio from the **Start** menu, as it will be configured with all the necessary paths for MSBuild. +To use MSBuild restore: -2. Switch to the folder containing the project file and type the following command. +1. Open a Developer Command Prompt by searching for *developer command prompt* and starting the prompt from the Windows **Start** menu, which configures all the necessary paths for MSBuild. - ```cmd - # Uses the project file in the current folder by default - msbuild -t:restore - ``` +1. Switch to the project folder, and enter `msbuild -t:restore`. -3. Type the following command to rebuild the project. +1. After the restore completes, enter `msbuild` to rebuild the project. Make sure the MSBuild output indicates that the build completed successfully. - ```cmd - msbuild - ``` +> [!Note] +> You can use `msbuild -restore` to run `restore`, reload the project, and build, since build is the default target. For more information, see [Restore and build with one MSBuild command](../reference/msbuild-targets.md#restoring-and-building-with-one-msbuild-command). - Make sure that the MSBuild output indicates that the build completed successfully. + + -## Restore using Azure Pipelines +## Restore with Azure Pipelines or Azure DevOps Server -When you create a build definition in Azure Pipelines, include the NuGet [restore](/azure/devops/pipelines/tasks/package/nuget#restore-nuget-packages) or .NET Core [restore](/azure/devops/pipelines/tasks/build/dotnet-core-cli?view=azure-devops) task in the definition before any build tasks. Some build templates include the restore task by default. +When you create a build definition in Azure Pipelines, you can include the [NuGet CLI restore](/azure/devops/pipelines/tasks/package/nuget#restore-nuget-packages) or [dotnet CLI restore](/azure/devops/pipelines/tasks/build/dotnet-core-cli) task in the definition before any build tasks. Some build templates include the restore task by default. -## Restore using Azure DevOps Server +Azure DevOps Server and TFS 2013 and later automatically restore packages during build, if you use a TFS 2013 or later Team Build template. You can also include a build step to run a command-line restore option, or optionally migrate the build template to a later version. For more information, see [Set up package restore with Team Foundation Build](../consume-packages/team-foundation-build.md). -Azure DevOps Server and TFS 2013 and later automatically restore packages during build, if you're using a TFS 2013 or later Team Build template. For earlier TFS versions, you can include a build step to run a command-line restore option, or optionally migrate the build template to a later version. For more information, see [Set up package restore with Team Foundation Build](../consume-packages/team-foundation-build.md). +## Constrain package versions -## Constrain package versions with restore +NuGet restore through any method honors any version constraints you specify in *packages.config* or the project file. -When NuGet restores packages through any method, it honors any constraints you specified in `packages.config` or the project file: +- In *packages.config*, you can specify an `allowedVersions` range in the dependency. For more information, see [Constraints on upgrade versions](../consume-packages/reinstalling-and-updating-packages.md#constraints-on-upgrade-versions). For example: -- In `packages.config`, you can specify a version range in the `allowedVersion` property of the dependency. See [Constrain upgrade versions](../consume-packages/reinstalling-and-updating-packages.md#constraining-upgrade-versions) for more information. For example: + ```xml + + ``` - ```xml - - ``` +- In a project file, you can specify the version range in the `Version` property of the dependency. For example: -- In a project file, you can use PackageReference to specify a dependency's range directly. For example: + ```xml + + ``` - ```xml - - ``` +In both cases, use the notation described in [Package versioning](../concepts/package-versioning.md). -In all cases, use the notation described in [Package versioning](../concepts/package-versioning.md). +## Force restore from remote package sources -## Force restore from package sources +By default, NuGet restore operations use packages from the local *global-packages* and *http-cache* folders, as described in [Manage the global packages and cache folders](managing-the-global-packages-and-cache-folders.md). To avoid using these local packages, use the following options. -By default, NuGet restore operations use packages from the *global-packages* and *http-cache* folders, which are described in [Manage the global packages and cache folders](managing-the-global-packages-and-cache-folders.md). +To clear all local caches: -To avoid using the *global-packages* folder, do one of the following: +- In Visual Studio, select the **Clear All NuGet Cache(s)** button at **Tools** > **Options** > **NuGet Package Manager** > **General**. +- In the dotnet CLI, use `dotnet nuget locals all --clear`. +- In the NuGet CLI, use `nuget locals all -clear`. -- Clear the folder using `nuget locals global-packages -clear` or `dotnet nuget locals global-packages --clear`. -- Temporarily change the location of the *global-packages* folder before the restore operation, using one of the following methods: - - Set the NUGET_PACKAGES environment variable to a different folder. - - Create a `NuGet.Config` file that sets `globalPackagesFolder` (if using PackageReference) or `repositoryPath` (if using `packages.config`) to a different folder. For more information, see [configuration settings](../reference/nuget-config-file.md#config-section). - - MSBuild only: Specify a different folder with the `RestorePackagesPath` property. +To avoid using the packages in the *global-packages* folder: -To avoid using the cache for HTTP sources, do one of the following: +- Clear the folder by using `nuget locals global-packages -clear` or `dotnet nuget locals global-packages --clear`. +- Temporarily set the **NUGET_PACKAGES** environment variable to a different folder. +- Create a *NuGet.Config* file that sets `globalPackagesFolder` for `PackageReference`, or `repositoryPath` for *packages.config*, to a different folder. For more information, see [configuration settings](../reference/nuget-config-file.md#config-section). +- For MSBuild only, specify a different folder with the `RestorePackagesPath` property. -- Use the `-NoCache` option with `nuget restore`, or the `--no-cache` option with `dotnet restore`. These options don't affect restore operations through the Visual Studio Package Manager or console. -- Clear the cache using `nuget locals http-cache -clear` or `dotnet nuget locals http-cache --clear`. -- Temporarily set the NUGET_HTTP_CACHE_PATH environment variable to a different folder. +To avoid using packages in the HTTP cache: -## Migrate to automatic package restore (Visual Studio) +- Clear the cache by using `nuget locals http-cache -clear` or `dotnet nuget locals http-cache --clear`. +- Temporarily set the **NUGET_HTTP_CACHE_PATH** environment variable to a different folder. +- For `nuget restore`, use the `-NoHttpCache` option, or for `dotnet restore`, use the `--no-http-cache` option. These options don't affect restore operations through the Visual Studio Package Manager or Console. -For NuGet 2.6 and earlier, an MSBuild-integrated package restore was previously supported but that is no longer true. (It was typically enabled by right-clicking a solution in Visual Studio and selecting **Enable NuGet Package Restore**). If your project uses the deprecated MSBuild-integrated package restore, please migrate to automatic package restore. + -Projects that use MSBuild-Integrated package restore typically contain a *.nuget* folder with three files: *NuGet.config*, *nuget.exe*, and *NuGet.targets*. The presence of a *NuGet.targets* file determines whether NuGet will continue to use the MSBuild-untegrated approach, so this file must be removed during the migration. +## Migrate to automatic package restore + +Earlier versions of NuGet supported an MSBuild-integrated package restore. Projects that use the deprecated MSBuild-integrated package restore should migrate to automatic package restore. + +These projects typically contain a *.nuget* folder with three files: *NuGet.config*, *nuget.exe*, and *NuGet.targets*. The *NuGet.targets* file causes NuGet to use the MSBuild-integrated approach, so it must be removed. To migrate to automatic package restore: +1. Enable automatic package restore. 1. Close Visual Studio. -2. Delete *.nuget/nuget.exe* and *.nuget/NuGet.targets*. -3. For each project file, remove the `` element and remove any reference to *NuGet.targets*. +1. Delete *.nuget/nuget.exe* and *.nuget/NuGet.targets*. +1. For each project file, remove the `` element, and remove any references to *NuGet.targets*. -To test the automatic package restore: +To test automatic package restore: 1. Remove the *packages* folder from the solution. -2. Open the solution in Visual Studio and start a build. - - Automatic package restore should download and install each dependency package, without adding them to source control. +1. Open the solution in Visual Studio and start a build. Automatic package restore should download and install each dependency package, without adding it to source control. -## Troubleshooting +## Next steps -See [Troubleshoot package restore](package-restore-troubleshooting.md). +- [Troubleshoot package restore](Package-restore-troubleshooting.md) +- [Manage the global packages, cache, and temp folders](managing-the-global-packages-and-cache-folders.md) diff --git a/docs/consume-packages/Package-Source-Mapping.md b/docs/consume-packages/Package-Source-Mapping.md new file mode 100644 index 000000000..5386bb61d --- /dev/null +++ b/docs/consume-packages/Package-Source-Mapping.md @@ -0,0 +1,177 @@ +--- +title: Package Source Mapping +description: Describes package source mapping functionality and how to onboard +author: nkolev92 +ms.author: nikolev +ms.date: 10/18/2023 +ms.topic: how-to +--- + +# Package Source Mapping + +Package Source Mapping is a tool that can be used to improve your supply chain security, especially if you use a mix of public and private package sources. + +By default, NuGet will search all configured package sources when it needs to download a package. +When a package exists on multiple sources, it may not be deterministic which source the package will be downloaded from. +With Package Source Mapping, you can filter, per package, which source(s) NuGet will search. + +We also have suggestions for other [best practices](..\concepts\Security-Best-Practices.md) to help you fortify your supply chain against attacks. + +Package Source Mapping was added in [NuGet 6.0](..\release-notes\NuGet-6.0.md). +Starting with Visual Studio 17.5, you can add and remove Package Source Mappings with the Visual Studio Options Dialog. +For detailed information on all Visual Studio NuGet options, see [NuGet Options in Visual Studio](nuget-visual-studio-options.md). + +### Visual Studio support + +| Visual Studio | Package Source Mapping | Support in Tools -> Options | Support in Package Manager UI | +|-----|---------------------|---------------------|---------------------| +| 17.0 - 17.4 | ✅ Available | ❌ Not available | ❌ Not available | +| 17.5 | ✅ Available | ✅ Available | ❌ Not available | +| 17.7 Preview 3| ✅ Available | ✅ Available | ✅ Status displayed | + +The feature is available across all NuGet integrated tooling. + +* [Visual Studio 2022 and later](https://visualstudio.microsoft.com/downloads/) +* [.NET SDK 6.0.100 and later](https://dotnet.microsoft.com/download/dotnet/6.0) +* [nuget.exe 6.0.0 and later](https://www.nuget.org/downloads) + +Older tooling will ignore the Package Source Mapping configuration. To use this feature, ensure all your build environments use compatible tooling versions. + +Package Source Mappings will apply to all project types – including .NET Framework – as long as compatible tooling is used. + +## Video walkthrough + +For a video-based overview of the Package Source Mapping feature, consider watching the [Secure your NuGet packages with Package Source Mapping](https://www.youtube.com/watch?v=G6P38Dn69Ro) video on YouTube. + +## Enabling Package Source Mapping + +To opt into this feature, you must have a `nuget.config` file. Having a single `nuget.config` at the root of your repository is considered a best practice. See [nuget.config documentation](../reference/nuget-config-file.md) to learn more. + +### Enable by using Visual Studio Options Dialog + +1. Open your solution in Visual Studio. +2. Navigate to the `Package Source Mappings` Options Dialog. + +_From the Package Manager UI_ + +* Select a package from the list to show it in the Details Pane. +* Press the `Configure` button to open the Package Source Mappings options page. + +![The NuGet Package Manager window in Visual Studio showing a selected package, and a highlight around the "Package source mapping is off" status with a `Configure` button.](media/packageSourceMapping_PMUI_Status_Off_Annotated.png) + +_From the Visual Studio Options Dialog_ + +* Go to the `Tools` menu in the main Visual Studio toolbar, and choose `NuGet Package Manager` -> `Package Manager Settings`. +* Navigate to the `Package Source Mappings` page. + +For details about managing NuGet package source mappings, see [NuGet Options in Visual Studio](nuget-visual-studio-options.md#package-source-mapping). + +The NuGet Package Manager window will refresh and reflect the new status of the selected package's source mappings. +![The NuGet Package Manager window in Visual Studio showing a selected package with the "Package source mapping found" status with a `Configure` button.](media/packageSourceMapping_PMUI_Status_Mapped.png) + +### Enable by manually editing `nuget.config` + +* Declare your desired package sources in your `nuget.config` file. +* Following your source declarations, add a `` element that specifies the desired mappings for each source. +* Declare exactly one `packageSource` element for each source in use. + * Add as many patterns as you find necessary. + +```xml + + + + + + + + + + + + + + + + + + + + + + + + +``` + +Package Source Mapping settings are applied following [nuget.config precedence rules](configuring-nuget-behavior.md#how-settings-are-applied) when multiple `nuget.config` files at various levels (machine-level, user-level, repo-level) are present. + +## Package Source Mapping rules + +For maximum flexibility and control, NuGet requires that all packages match a package pattern through a well defined precedence. + +### Package Pattern requirements + +All requested packages must map to one or more sources by matching a defined package pattern. In other words, once you have defined a `packageSourceMapping` element you must explicitly define which sources _every_ package - _including transitive packages_ - will be restored from. + +* Both top-level _and transitive_ packages must match defined patterns. There is no requirement that a top level package and its dependencies come from the same source. +* The same ID pattern can be defined on multiple sources, allowing matching package IDs to be restored from any of the feeds that define the pattern. However, this isn't recommended due to the impact on restore predictability (a given package could come from multiple sources). This may be a valid configuration if you trust all respective sources. + +### Package Pattern Syntax + +| Pattern | Example syntax | Description | +|---------|---------|-------------| +| Package prefix pattern | `*`, `NuGet.*` | Must end with a `*`, where `*` matches 0 or more characters. `*` is the shortest allowed prefix pattern and matches all packages ids. | +| Package ID pattern | `NuGet.Common`, `Contoso.Contracts` | Exact package ID. | + +### Package Pattern precedence + +When multiple unique patterns match a package ID, the most specific one will be preferred. Package ID patterns always have the highest precedence while the generic `*` always has the lowest precedence. For package prefix patterns, the longest has precedence. + +![Package Pattern Precedence Examples](media/Package-Pattern-Examples.png) + +### Setting default sources + +The `*` pattern can be used to make a declare a de-facto default source - meaning any package that doesn't match other specified patterns will be restored from that source without throwing an error. +This configuration is advantageous if you primarily use packages from say, `nuget.org`, and only have a few internal packages, or use standard prefixes for all internal packages like `Contoso.*`. + +If your team doesn't use standard prefixes for internal package IDs or vets `nuget.org` packages prior to installation, then making a private source the default will suit your needs better. + +> [!Note] +> When the requested package already exists in the global packages folder, no source look-up will happen and the mappings will be ignored. Consider declaring a [global packages folder for your repo](../reference/nuget-config-file.md#config-section) to gain the full security benefits of this feature. Work to improve the experience with the default global packages folder is planned for a next iteration. +To learn more about how package installation works, see [the conceptual document.](../concepts/package-installation-process.md) + +### Get started + +There are 2 ways you can fully onboard your repository, [manually](#manual-onboarding) or using the [NuGet.PackageSourceMapper tool](#automated-onboarding-using-tool). + +#### Manual onboarding + +For manual onboarding you may take the following steps: + +1. Declare a new [global packages folder for your repo](../reference/nuget-config-file.md#config-section). +1. Run [dotnet restore](/dotnet/core/tools/dotnet-restore) to restore dependencies. +1. Run [`dotnet list package --include-transitive`](/dotnet/core/tools/dotnet-list-package#synopsis) to view all top-level and transitive packages in your solution. + * For .NET framework projects using [`packages.config`](../reference/packages-config.md), the `packages.config` file will have a flat list of all direct and transitive packages. +1. Define mappings such that every package ID in your solution - _including transitive packages_ - matches a pattern for the target source. +1. Run [dotnet nuget locals global-packages -c](/dotnet/core/tools/dotnet-nuget-locals) to clear global-packages directory. +1. Run restore to validate that you have configured your mappings correctly. If your mappings don't fully cover every package ID in your solution, the error messages will help you identify the issue. +1. When restore succeeds, you are done! Optionally consider: + * Simplifying the configuration to fewer declarations by using broader package ID prefixes or [setting a default source](#setting-default-sources) where possible. + * Verifying the source each package was restored from by checking the [metadata files in the global packages folder or reviewing the restore logs](https://devblogs.microsoft.com/nuget/performance-and-polish-with-nuget-5-9/). + +#### Automated onboarding using tool + +Many repositories have a large number of packages and doing the work manually can be time consuming. The [NuGet.PackageSourceMapper tool](https://www.nuget.org/packages/NuGet.PackageSourceMapper) can automatically generate a NuGet.config for you, based on your project's known packages and sources. + +The package source mapper tool requires you to have completed a successful package restore in which it will read each respective `.nupkg.metadata` file generated as part of your build to best understand how you map your respective packages and sources. Tool not only covers top dependencies it also considers all the transitive dependencies when generating mapping. + +Tool has several option how to generate mapping pattern depending on your need, please check [blog post](https://devblogs.microsoft.com/nuget/quickly-map-your-nuget-packages-to-sources) and tool's [readme instruction](https://www.nuget.org/packages/NuGet.PackageSourceMapper#readme-body-tab) for more details. + +For an idea of how your source mappings may look like, refer to our [samples repo](https://github.com/NuGet/Samples/tree/main/PackageSourceMappingExample). + +> [!Note] +> +> * There are no nuget.exe or dotnet.exe commands for managing the package source mapping configuration, see [NuGet/Home#10735](https://github.com/NuGet/Home/issues/10735). +> * There are no means of mapping packages at package installation time, see [NuGet/Home#10730](https://github.com/NuGet/Home/issues/10730). +> * There is a limitation when using the `DotNetCoreCLI@2` Azure Pipelines task which can be worked around by using `feed-` prefixes in your source mapping configuration. It is recommended however to use `NuGetAuthenticate` for your authentication needs and call the dotnet cli directly from a script task. See [microsoft/azure-pipelines-tasks#15542](https://github.com/microsoft/azure-pipelines-tasks/issues/15542). diff --git a/docs/consume-packages/Package-restore-troubleshooting.md b/docs/consume-packages/Package-restore-troubleshooting.md index b21474eb9..1bac3ac4f 100644 --- a/docs/consume-packages/Package-restore-troubleshooting.md +++ b/docs/consume-packages/Package-restore-troubleshooting.md @@ -1,15 +1,15 @@ --- title: Troubleshooting NuGet Package Restore in Visual Studio description: A description of common NuGet restore errors in Visual Studio and how to troubleshoot them. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 05/25/2018 -ms.topic: conceptual +ms.topic: troubleshooting-general --- # Troubleshooting package restore errors -This article focuses on common errors when restoring packages and steps to resolve them. +This article focuses on common errors when restoring packages and steps to resolve them. Package Restore tries to install all package dependencies to the correct state matching the package references in your project file (*.csproj*) or your *packages.config* file. (In Visual Studio, the references appear in Solution Explorer under the **Dependencies \ NuGet** or the **References** node.) To follow the required steps to restore packages, see [Restore packages](../consume-packages/package-restore.md#restore-packages). If the package references in your project file (*.csproj*) or your *packages.config* file are incorrect (they do not match your desired state following Package Restore), then you need to either install or update packages instead of using Package Restore. @@ -24,9 +24,9 @@ If you're using Visual Studio, first enable package restore as follows. Otherwis 1. Select **OK**. 1. Build your project again. -![Enable NuGet package restore in Tool/Options](../consume-packages/media/restore-01-autorestoreoptions.png) +![Enable NuGet package restore in Tool/Options](../consume-packages/media/vsoptions/general.png) -These settings can also be changed in your `NuGet.config` file; see the [consent](#consent) section. If your project is an older project that uses the MSBuild-integrated package restore, you may need to [migrate](package-restore.md#migrate-to-automatic-package-restore-visual-studio) to automatic package restore. +These settings can also be changed in your `NuGet.Config` file; see the [consent](#consent) section. If your project is an older project that uses the MSBuild-integrated package restore, you may need to [migrate](package-restore.md#migrate-to-automatic-package-restore-visual-studio) to automatic package restore. @@ -41,7 +41,7 @@ Use NuGet Package Restore to download them. The missing file is {name}. This error occurs when you attempt to build a project that contains references to one or more NuGet packages, but those packages are not presently installed on the computer or in the project. -- When using the [PackageReference](package-references-in-project-files.md) management format, the error means that the package is not installed in the *global-packages* folder as described on [Managing the global packages and cache folders](managing-the-global-packages-and-cache-folders.md). +- When using the [PackageReference](package-references-in-project-files.md) management format, this error might be a leftover from a packages.config to PackageReference migration and needs to be [manually removed](/nuget/resources/nuget-faq#working-with-packages) from the project file. - When using [packages.config](../reference/packages-config.md), the error means that the package is not installed in the `packages` folder at the solution root. This situation commonly occurs when you obtain the project's source code from source control or another download. Packages are typically omitted from source control or downloads because they can be restored from package feeds like nuget.org (see [Packages and source control](Packages-and-Source-Control.md)). Including them would otherwise bloat the repository or create unnecessarily large .zip files. @@ -109,7 +109,7 @@ You can also edit these settings directly in the applicable `nuget.config` file ## Other potential conditions -- You may encounter build errors due to missing files, with a message saying to use NuGet restore to download them. However, running a restore might say, "All packages are already installed and there is nothing to restore." In this case, delete the `packages` folder (when using `packages.config`) or the `obj/project.assets.json` file (when using PackageReference) and run restore again. If the error still persists, use `nuget locals all -clear` or `dotnet locals all --clear` from the command line to clear the *global-packages* and cache folders as described on [Managing the global packages and cache folders](managing-the-global-packages-and-cache-folders.md). +- You may encounter build errors due to missing files, with a message saying to use NuGet restore to download them. However, running a restore might say, "All packages are already installed and there is nothing to restore." In this case, delete the `packages` folder (when using `packages.config`) or the `obj/project.assets.json` file (when using PackageReference) and run restore again. If the error still persists, use `nuget locals all -clear` or `dotnet nuget locals all --clear` from the command line to clear the *global-packages* and cache folders as described on [Managing the global packages and cache folders](managing-the-global-packages-and-cache-folders.md). - When obtaining a project from source control, your project folders may be set to read-only. Change the folder permissions and try restoring packages again. diff --git a/docs/consume-packages/PackageDownload-Functionality.md b/docs/consume-packages/PackageDownload-Functionality.md new file mode 100644 index 000000000..8b5bb01b3 --- /dev/null +++ b/docs/consume-packages/PackageDownload-Functionality.md @@ -0,0 +1,77 @@ +--- +title: Download packages with PackageDownload +description: Describes the PackageDownload feature, which is a complement to PackageReference. +author: nkolev92 +ms.author: nikolev +ms.date: 12/22/2021 +ms.topic: article +--- + +# PackageDownload + +Starting with Visual Studio 2017 and .NET SDK 1.0.0, NuGet [PackageReference](Package-References-in-Project-Files.md) functionality was added. + +`PackageReference` allows you to manage your package dependencies directly in your project file. +When you run restore, the transitive dependencies are resolved automatically and the applicable references are chosen for each package in the project graph. + +In [NuGet version 5.3](..\release-notes\NuGet-5.3.md) a companion feature was introduced for [.NET SDK-style projects](..\resources\check-project-format.md) called `PackageDownload`, which allows you to download the package without including its files in the project. + +## PackageDownload specification + +PackageDownload is a utility feature for all .NET SDK-style projects, and it works along side `PackageReference`. + +`PackageDownload` items support different attributes compared to `PackageReference`. Only attributes listed in the below table are supported. + +| Attributes | Description | Example | +|------------|-------------|---------| +| Version | Only exact versions, surrounded with `[]` are supported. Multiple versions can be specified separated by `;` | `[1.0.0]`, `[1.0.0];[2.0.0]` | + +Packages acquired through PackageDownload will undergo the same [installation process](..\concepts\package-installation-process.md) as packages acquired through PackageReference. +This means [package signatures](installing-signed-packages.md) are validated, [package source mapping](Package-Source-Mapping.md) is considered. +All newly acquired PackageDownload packages will be installed in the global packages folder. + +| Feature | PackageReference | PackageDownload | +|-|------------------|-----------------| +| Package assets selection | Assemblies from packages are automatically added to the project and can be used for compile and runtime | No assets from the package are included in the project. | +| Dependencies | Automatically resolved, and flattened to a single version | Not considered at all | +| pack | Included in the package specification | Not included in the package specification. | +| Transitivity | PackageReference items are automatically propagated to dependant projects | PackageDownload items are ignored by dependant projects | +| Version | Version ranges such as `1.0.0` or `[1.0.0, )` are supported. Exactly 1 version is allowed. | Only exact versions are supported. More than 1 version can be downloaded. | +| dotnet list package | All dependencies are included | PackageDownload packages are not shown by `dotnet list package`. | + +Due to the fact that PackageDownload are not tied to the project in any way beyond acquisition, multiple versions of the same package can be downloaded. + +### PackageDownload limitations + +Given that this is an advanced feature with limited applicability, it doesn't have a tooling support equivalent to PackageReference. + +- There is no VisualStudio or dotnet.exe functionality to modify PackageDownload items. You can only change them manually in your project files. +- dotnet add, remove, and list commands do not account for PackageDownload items. +- PackageDownload items are *not* part of the [packages lock file](package-references-in-project-files.md#locking-dependencies). + +### PackageDownload applications + +The primary application of PackageDownload is downloading packages that do not follow the traditional NuGet package structure and primarily carry build time dependencies. + +Ideally, all your dependencies are expressed through PackageReference, but in scenarios where that's not possible, or often times not practical yet, you can use this feature to simply `download` packages to a certain location, in a similar way that you could achieve that with a `packages.config` file not tied to a project. + +Example: + +```xml + + + + + packages/ + $(RestorePackagesPath)obj/ + net5.0 + true + false + + + + + + + +``` diff --git a/docs/consume-packages/Packages-and-Source-Control.md b/docs/consume-packages/Packages-and-Source-Control.md index e3d29df6b..2d7cb5516 100644 --- a/docs/consume-packages/Packages-and-Source-Control.md +++ b/docs/consume-packages/Packages-and-Source-Control.md @@ -1,10 +1,10 @@ --- title: NuGet Packages and Source Control description: Considerations for how to treat NuGet packages within version control and source control systems, and how to omit packages with git and TFVC. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 03/16/2018 -ms.topic: conceptual +ms.topic: how-to --- # Omitting NuGet packages in source control systems @@ -75,7 +75,7 @@ To disable source control integration with TFVC for selected files: 1. If you are using TFS 2010 or earlier, cloak the `packages` folder in your workspace mappings. -1. On TFS 2012 or later, or with Visual Studio Team Services, create a `.tfignore` file as described on [Add Files to the Server](/vsts/tfvc/add-files-server?view=vsts#tfignore). In that file, include the content below to explicitly ignore modifications to the `\packages` folder on the repository level and a few other intermediate files. (You can create the file in Windows Explorer using the name a `.tfignore.` with the trailing dot, but you might need to disable the "Hide known file extensions" option first.): +1. On TFS 2012 or later, or with Visual Studio Team Services, create a `.tfignore` file as described on [Add Files to the Server](/vsts/tfvc/add-files-server?view=vsts#tfignore&preserve-view=true). In that file, include the content below to explicitly ignore modifications to the `\packages` folder on the repository level and a few other intermediate files. (You can create the file in Windows Explorer using the name a `.tfignore.` with the trailing dot, but you might need to disable the "Hide known file extensions" option first.): ```cli # Ignore NuGet Packages diff --git a/docs/consume-packages/Reinstalling-and-Updating-Packages.md b/docs/consume-packages/Reinstalling-and-Updating-Packages.md index 36cd8a30b..f4465e821 100644 --- a/docs/consume-packages/Reinstalling-and-Updating-Packages.md +++ b/docs/consume-packages/Reinstalling-and-Updating-Packages.md @@ -1,49 +1,75 @@ --- -title: Reinstalling and Updating NuGet Packages -description: Details on when it's necessary to reinstall and update packages, as with broken package references in Visual Studio. -author: karann-msft -ms.author: karann -ms.date: 12/07/2017 -ms.topic: conceptual +title: Reinstall and update NuGet packages in Visual Studio +description: Learn how to reinstall and update NuGet packages to address broken package references and broken projects in Visual Studio. +author: JonDouglas +ms.author: jodou +ms.date: 11/03/2023 +ms.topic: how-to --- -# How to reinstall and update packages +# Reinstall and update NuGet packages in Visual Studio -There are a number of situations, described below under [When to Reinstall a Package](#when-to-reinstall-a-package), where references to a package might get broken within a Visual Studio project. In these cases, uninstalling and then reinstalling the same version of the package will restore those references to working order. Updating a package simply means installing an updated version, which often restores a package to working order. +Sometimes package references can break within a Visual Studio project. Uninstalling and reinstalling the same version of the package often restores the references to working order. Updating a package, which installs an updated version, can also resolve the issue. This article describes how to reinstall and update NuGet packages to address broken package references and broken projects. -In Visual Studio, the Package Manager Console provides many flexible options for updating and reinstalling packages. +> [!NOTE] +> The guidance in this article applies only to projects that use the [packages.config](../reference/packages-config.md) management format. For [PackageReference](../consume-packages/Package-References-in-Project-Files.md) projects, a restore operation automatically fixes broken references. -Updating and reinstalling packages is accomplished as follows: +## Common scenarios -| Method | Update | Reinstall | -| --- | --- | --- | -| Package Manager console (described in [Using Update-Package](#using-update-package)) | `Update-Package` command | `Update-Package -reinstall` command | -| Package Manager UI | On the **Updates** tab, select one or more packages and select **Update** | On the **Installed** tab, select a package, record its name, then select **Uninstall**. Switch to the **Browse** tab, search for the package name, select it, then select **Install**). | -| nuget.exe CLI | `nuget update` command | For all packages, delete the package folder, then run `nuget install`. For a single package, delete the package folder and use `nuget install ` to reinstall the same one. | +Here are some common scenarios where you might encounter broken package references in your Visual Studio project. -> [!NOTE] -> For the dotnet CLI, the equivalent procedure is not required. In a similar scenario, you can [restore packages with the dotnet CLI](package-restore.md#restore-using-the-dotnet-cli). +| Scenario | Description | Resolution | +|---|---|---| +| **Broken references after package restore** | You open your Visual Studio project and restore NuGet packages, but broken package references remain. | To fix the references, try reinstalling each package separately. | +| **Broken project due to deleted files** | Deleted (missing) package files cause your project to break. NuGet doesn't prevent deleting items that you add from packages. It can be easy to inadvertently modify contents installed from a package and break your project. | To restore your project, try reinstalling the affected packages. | +| **Broken project after package update** | A package update breaks your project. Companion updates to a dependency package generally cause this type of failure. | To restore the state of the dependency to its previous working order, try reinstalling the specific dependent package. | +| **Broken references after project retarget or upgrade** | A project retarget or upgrade process causes broken package references. After you retarget your project, NuGet shows a build error. Build warnings list packages that might need to be reinstalled. Or, after you upgrade your project, NuGet shows an error in the project upgrade log. The log file lists packages that might need to be reinstalled. | To resolve issues due to a change in target framework, try reinstalling one or more packages. | +| **Package changes under development** | Package authors often need to reinstall the same version of a package they're currently developing to test their changes. | The NuGet Package Manager Console in Visual Studio provides flexible options for updating and reinstalling packages. To reinstall a package under development, you can use the `Update-Package -reinstall` command. | + +## Implementation options + +You have several choices for how to update and reinstall NuGet packages. Common methods include NuGet Package Manager UI options, the NuGet Package Manager Console, and the NuGet (Command Line Interface) CLI. + +### Package Manager UI + +In addition to the Console interface, the Package Manager UI also provides menu options to install, update, and uninstall packages. + +- To update a package, open the **Updates** tab, choose one or more packages, then select **Update**. + +- To reinstall a package, first uninstall the package and then install it again. Open the **Installed** tab, choose a package and record its name, then select **Uninstall**. Switch to the **Browse** tab and search for the package name, choose the package, then select **Install**. + +### Package Manager Console + +You can access the Package Manager Console under **Tools** > **NuGet Package Manager** > **Package Manager Console**. -In this article: +- To update a package, the Package Manager Console provides the `Update-Package` command. -- [When to Reinstall a Package](#when-to-reinstall-a-package) -- [Constraining upgrade versions](#constraining-upgrade-versions) +- To reinstall a package, you can use the same command with the `-reinstall` parameter. This approach is the easiest option, if it's compatible with your configuration. -## When to Reinstall a Package +For more information, see the [Update-Package command](#update-package-command) and [Package reinstall considerations](#package-reinstall-considerations) sections. -1. **Broken references after package restore**: If you've opened a project and restored NuGet packages, but still see broken references, try reinstalling each of those packages. -1. **Project is broken due to deleted files**: NuGet does not prevent you from removing items added from packages, so it's easy to inadvertently modify contents installed from a package and break your project. To restore the project, reinstall the affected packages. -1. **Package update broke the project**: If an update to a package breaks a project, the failure is generally caused by a dependency package which may have also been updated. To restore the state of the dependency, reinstall that specific package. -1. **Project retargeting or upgrade**: This can be useful when a project has been retargeted or upgraded and if the package requires reinstallation due to the change in target framework. NuGet shows a build error in such cases immediately after project retargeting, and subsequent build warnings let you know that the package may need to be reinstalled. For project upgrade, NuGet shows an error in the Project Upgrade Log. -1. **Reinstalling a package during its development**: Package authors often need to reinstall the same version of package they're developing to test the behavior. The `Install-Package` command does not provide an option to force a reinstall, so use `Update-Package -reinstall` instead. +### NuGet CLI -## Constraining upgrade versions +The NuGet CLI, `nuget.exe`, is the command-line utility for Windows that provides all NuGet capabilities. -By default, reinstalling or updating a package *always* installs the latest version available from the package source. +- To update an installed package, run the `nuget update` command. -In projects using the `packages.config` management format, however, you can specifically constrain the version range. For example, if you know that your application works only with version 1.x of a package but not 2.0 and above, perhaps due to a major change in the package API, then you'd want to constrain upgrades to 1.x versions. This prevents accidental updates that would break the application. +- To reinstall all NuGet packages, delete the package folder and then run the `nuget install` command. -To set a constraint, open `packages.config` in a text editor, locate the dependency in question, and add the `allowedVersions` attribute with a version range. For example, to constrain updates to version 1.x, set `allowedVersions` to `[1,2)`: +- To reinstall a single package, delete the package folder and then run the `nuget install ` command, where the `` argument is the ID of the specific package. + +> [!NOTE] +> For the **dotnet CLI**, the equivalent procedure isn't required. When you run the `dotnet restore` command, the dotnet CLI uses NuGet to determine dependencies and download any necessary NuGet packages. For more information, see [Restore NuGet packages with the dotnet CLI](package-restore.md#restore-using-the-dotnet-cli). + +## Constraints on upgrade versions + +By default, reinstalling or updating a package _always_ installs the latest version available from the package source. However, projects that use the `packages.config` management format can specifically limit the allowed NuGet package version range. + +Suppose your application works only with version 1.x of a package, but not with version 2.0 or later, due to a major change in the package API. To ensure your application works as expected, you want to constrain NuGet package upgrades to versions 1.x only. The limitation helps to prevent accidental updates that might break your application. + +To set a constraint, open the `packages.config` file in a text editor. Locate the dependency that you want to limit, and add the `allowedVersions` attribute with your desired version range. + +The following example shows how to constrain updates to version 1.x by setting the `allowedVersions` attribute to `[1,2)`: ```xml @@ -54,65 +80,106 @@ To set a constraint, open `packages.config` in a text editor, locate the depende ``` -In all cases, use the notation described in [Package versioning](../concepts/package-versioning.md#version-ranges-and-wildcards). +In all cases, use the notation described in [Package versioning](../concepts/package-versioning.md#version-ranges). + +## Update-Package command + +The [Update-Package command](../reference/ps-reference/ps-ref-update-package.md) in the Package Manager Console is the easiest way to reinstall a package and address broken references. However, this approach isn't usable in all scenarios. You can use the command to update an installed package, but not to do an initial install. If you try to update or reinstall a package that isn't already installed in the configuration, the command returns an error. Be sure to review the [Package reinstall considerations](#package-reinstall-considerations) section before working with the command. -## Using Update-Package +Updating packages in a project or solution by using [PackageReference](../Consume-Packages/Package-References-in-Project-Files.md) always updates to the latest version of the package (excluding prerelease packages). Projects that use the `packages.config` management format can limit upgrade versions as described in [Constraints on upgrade versions](#constraints-on-upgrade-versions). -Being mindful of the [Considerations](#considerations) described below, you can easily reinstall any package using the [Update-Package command](../reference/ps-reference/ps-ref-update-package.md) in the Visual Studio Package Manager Console (**Tools** > **NuGet Package Manager** > **Package Manager Console**). +The following sections provide examples for working with the command. -```ps +### Reinstall package options + +Here's a basic usage of the command to do a reinstall. To identify a specific NuGet package, you can use the optional `-Id` parameter. + +```powershell +# Reinstall the package named Update-Package -Id –reinstall ``` -Using this command is much easier than removing a package and then trying to locate the same package in the NuGet gallery with the same version. Note that the `-Id` switch is optional. +Using the `Update-Package` command is easier than removing a package and then trying to locate the same package in the NuGet gallery with the same version. + +### Update package options -The same command without `-reinstall` updates a package to a newer version, if applicable. The command gives an error if the package in question is not already installed in a project; that is, `Update-Package` does not install packages directly. +The same command without the `-reinstall` parameter updates a package to a newer version, if applicable. The command returns an error if the specified package isn't already installed in a project. -```ps +```powershell +# Update the package named Update-Package ``` -By default, `Update-Package` affects all projects in a solution. To limit the action to a specific project, use the `-ProjectName` switch, using the name of the project as it appears in Solution Explorer: +### Project and solution options + +By default, the `Update-Package` command affects all projects in a solution. To limit the action to a specific project, use the `-ProjectName` parameter. Provide the name of the project as it appears in Visual Studio Solution Explorer. + +The following command reinstalls a NuGet package for a specific project in your solution. The name of the specific NuGet package to reinstall is provided in the `` parameter. -```ps -# Reinstall the package in just MyProject +```powershell +# Reinstall the package named in MyProject only Update-Package -ProjectName MyProject -reinstall ``` -To *update* all packages in a project (or reinstall using `-reinstall`), use `-ProjectName` without specifying any particular package: +If you want to reinstall all packages in your project, use the `-ProjectName` parameter by don't specify any particular package. You can follow this same approach to update the packages in your project, as shown in this example: -```ps +```powershell +# Update all packages in MyProject only Update-Package -ProjectName MyProject ``` -To update all packages in a solution, just use `Update-Package` by itself with no other arguments or switches. Use this form carefully, because it can take considerable time to perform all the updates: +To update all packages in a solution, just use the `Update-Package` command by itself with no other arguments or parameters. -```ps -# Updates all packages in all projects in the solution +> [!IMPORTANT] +> Be sure to use the following form of the command carefully. The command process can take considerable time to perform all of the updates. + +```powershell +# Update all packages in all projects in the solution Update-Package ``` -Updating packages in a project or solution using [PackageReference](../Consume-Packages/Package-References-in-Project-Files.md) always updates to the latest version of the package (excluding pre-release packages). Projects that use `packages.config` can, if desired, limit update versions as described below in [Constraining upgrade versions](#constraining-upgrade-versions). +## Package reinstall considerations + +If you intend to use the `Update-Package` command to reinstall packages, review the following considerations to ensure compatibility with your configuration scenario. + +- Packages and their dependencies might not support a retargeted project target framework. +- When the `requireReinstallation` attribute is set to `true`, Visual Studio issues build warnings for affected packages. +- Reinstall of a package and version constraints can introduce dependency version compatibility issues. +- Reinstall of a specific package can cause dependent packages to break. + +### Package doesn't support project target framework + +If you retarget your project target framework, one or more packages might not support the new target configuration. + +Usually, reinstalling a package with the `Update-Package –reinstall ` command works. A package installed against an old target framework is uninstalled and the same package is installed against the new target framework of the project. + +In some cases, a package might not support the new target framework. Here are some of the issues you might encounter: + +- If a package supports portable class libraries (PCLs), and you retarget the project to a combination of platforms no longer supported by the package, references to the package can be missing after reinstalling. + +- This issue can surface for packages you use directly or for packages installed as dependencies. Any package that you use directly might support the new target framework while their dependencies don't. + +- If reinstalling packages after retargeting your application results in build or runtime errors, you might need to revert your target framework or search for alternative packages that properly support your new target framework. + +### requireReinstallation attribute set to true + +After you retarget your project target framework or upgrade NuGet packages, NuGet might add the `requireReinstallation` attribute to the `packages.config` file for your project. If NuGet detects affected packages during the retargeting or upgrading process, it adds a `requireReinstallation="true"` attribute to the `packages.config` file for all affected package references. As a result, each subsequent build of your project in Visual Studio raises build warnings for those packages. The warnings are presented as a reminder to reinstall the affected package. + +### Package dependency version incompatibility -For full details on the command, see the [Update-Package](../reference/ps-reference/ps-ref-update-package.md) reference. +The `Update-Package –reinstall` command reinstalls the **same** version of an installed package and the **latest** version of any dependencies. To address version incompatibility issues, you can set version range constraints to control the configuration. NuGet adheres to the constraints and updates the package dependencies to newer versions only as required to fix an issue. -### Considerations +- If your constraint settings cause a dependency to revert to an earlier version during package reinstall, you can address the issue with the `Update-Package ` command. This command reinstalls the specified dependency without affecting the dependent package. -The following may be affected when reinstalling a package: +- You can also use the `Update-Package –reinstall -ignoreDependencies` command. This option reinstalls the same version of the original package, but it doesn't reinstall dependencies. Use this approach when updating package dependencies might result in a broken configuration state. -1. **Reinstalling packages according to project target framework retargeting** - - In a simple case, just reinstalling a package using `Update-Package –reinstall ` works. A package that is installed against an old target framework gets uninstalled and the same package gets installed against the current target framework of the project. - - In some cases, there may be a package that does not support the new target framework. - - If a package supports portable class libraries (PCLs) and the project is retargeted to a combination of platforms no longer supported by the package, references to the package will be missing after reinstalling. - - This can surface for packages you're using directly or for packages installed as dependencies. It's possible for the package you're using directly to support the new target framework while its dependency does not. - - If reinstalling packages after retargeting your application results in build or runtime errors, you may need to revert your target framework or search for alternative packages that properly support your new target framework. +### Broken dependent package -1. **requireReinstallation attribute added in packages.config after project retargeting or upgrade** - - If NuGet detects that packages were affected by retargeting or upgrading a project, it adds a `requireReinstallation="true"` attribute in `packages.config` to all affected package references. Because of this, each subsequent build in Visual Studio raises build warnings for those packages so you can remember to reinstall them. +When you reinstall a specific package, any installed packages that depend on the reinstalled package aren't updated. The versions of these other installed packages remain the same. As a result, reinstalling a dependency can break a dependent package. -1. **Reinstalling packages with dependencies** - - `Update-Package –reinstall` reinstalls the same version of the original package, but installs the latest version of dependencies unless specific version constraints are provided. This allows you to update only the dependencies as required to fix an issue. However, if this rolls a dependency back to an earlier version, you can use `Update-Package ` to reinstall that one dependency without affecting the dependent package. - - `Update-Package –reinstall -ignoreDependencies` reinstalls the same version of the original package but does not reinstall dependencies. Use this when updating package dependencies might result in a broken state +## Related articles -1. **Reinstalling packages when dependent versions are involved** - - As explained above, reinstalling a package does not change versions of any other installed packages that depend on it. It's possible, then, that reinstalling a dependency could break the dependent package. +- Review the [packages.config](../reference/packages-config.md) management format. +- Implement [PackageReference](../consume-packages/Package-References-in-Project-Files.md) in project files. +- Use the [Update-Package command](../reference/ps-reference/ps-ref-update-package.md) in the NuGet Package Manager Console in Visual Studio. +- Explore [package versioning](../concepts/package-versioning.md#version-ranges) notation formats. diff --git a/docs/consume-packages/Team-Foundation-Build.md b/docs/consume-packages/Team-Foundation-Build.md index 174450244..7b631ef7e 100644 --- a/docs/consume-packages/Team-Foundation-Build.md +++ b/docs/consume-packages/Team-Foundation-Build.md @@ -1,10 +1,10 @@ --- title: Walkthrough of NuGet Package Restore with Team Foundation Build description: A walkthrough of how NuGet package restore with with Team Foundation Build (both TFS and Visual Studio Team Services). -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/09/2017 -ms.topic: conceptual +ms.topic: concept-article --- # Setting up package restore with Team Foundation Build @@ -26,7 +26,7 @@ If you're using Visual Studio Team Services or Team Foundation Server 2013 with An advantage of using NuGet is that you can use it to avoid checking in binaries to your version control system. -This is especially interesting if you are using a [distributed version control](http://en.wikipedia.org/wiki/Distributed_revision_control) system like git because developers need to clone the entire repository, including the full history, before they can start working locally. Checking in binaries can cause significant repository bloat as binary files are typically stored without delta compression. +This is especially interesting if you are using a [distributed version control](https://en.wikipedia.org/wiki/Distributed_revision_control) system like git because developers need to clone the entire repository, including the full history, before they can start working locally. Checking in binaries can cause significant repository bloat as binary files are typically stored without delta compression. NuGet has supported [restoring packages](../consume-packages/package-restore.md) as part of the build for a long time now. The previous implementation had a chicken-and-egg problem for packages that want to extend the build process because NuGet restored packages while building the project. However, MSBuild doesn't allow extending the build during the build; one could argue that this an issue in MSBuild but I would argue that this is an inherent problem. Depending on which aspect you need to extend it might be too late to register by the time your package is restored. @@ -45,30 +45,32 @@ The following demo project shows how to set up the build in such a way that the ## Repository structure -Our demo project is a simple command line tool that uses the command line argument to query Bing. It targets the .NET Framework 4 and uses many of the [BCL packages](http://www.nuget.org/profiles/dotnetframework/) ([Microsoft.Net.Http](http://www.nuget.org/packages/Microsoft.Net.Http), [Microsoft.Bcl](http://www.nuget.org/packages/Microsoft.Bcl), [Microsoft.Bcl.Async](http://www.nuget.org/packages/Microsoft.Bcl.Async), and [Microsoft.Bcl.Build](http://www.nuget.org/packages/Microsoft.Bcl.Build)). +Our demo project is a simple command line tool that uses the command line argument to query Bing. It targets the .NET Framework 4 and uses many of the [BCL packages](https://www.nuget.org/profiles/dotnetframework/) ([Microsoft.Net.Http](https://www.nuget.org/packages/Microsoft.Net.Http), [Microsoft.Bcl](https://www.nuget.org/packages/Microsoft.Bcl), [Microsoft.Bcl.Async](https://www.nuget.org/packages/Microsoft.Bcl.Async), and [Microsoft.Bcl.Build](https://www.nuget.org/packages/Microsoft.Bcl.Build)). The structure of the repository looks as follows: - - │ .gitignore - │ .tfignore - │ build.proj - │ - ├───src - │ │ BingSearcher.sln - │ │ - │ └───BingSearcher - │ │ App.config - │ │ BingSearcher.csproj - │ │ packages.config - │ │ Program.cs - │ │ - │ └───Properties - │ AssemblyInfo.cs - │ - └───tools - └───NuGet - nuget.exe +``` + + │ .gitignore + │ .tfignore + │ build.proj + │ + ├───src + │ │ BingSearcher.sln + │ │ + │ └───BingSearcher + │ │ App.config + │ │ BingSearcher.csproj + │ │ packages.config + │ │ Program.cs + │ │ + │ └───Properties + │ AssemblyInfo.cs + │ + └───tools + └───NuGet + nuget.exe +``` You can see that we haven't checked-in the `packages` folder nor any `.targets` files. @@ -79,7 +81,7 @@ The source code is under the `src` folder. Although our demo only uses a single ### Ignore files > [!Note] -> There is currently a [known bug in the NuGet client](https://nuget.codeplex.com/workitem/4072) that causes the client to still add the `packages` folder to version control. A workaround is to disable the source control integration. In order to do that, you need a `Nuget.Config ` file in the `.nuget` folder that is parallel to your solution. If this folder doesn't exist yet, you need to create it. In [`Nuget.Config`](../consume-packages/configuring-nuget-behavior.md), add the following content: +> There is currently a `[known bug in the NuGet client](https://nuget.codeplex.com/workitem/4072)` that causes the client to still add the `packages` folder to version control. A workaround is to disable the source control integration. In order to do that, you need a `Nuget.Config ` file in the `.nuget` folder that is parallel to your solution. If this folder doesn't exist yet, you need to create it. In [`Nuget.Config`](../consume-packages/configuring-nuget-behavior.md), add the following content: ```xml @@ -93,33 +95,39 @@ To communicate to version control that we don’t intent to check-in the **packa The `.gitignore` file looks as follows: - syntax: glob - *.user - *.suo - bin - obj - packages - *.nupkg - project.lock.json - project.assets.json +``` +syntax: glob +*.user +*.suo +bin +obj +packages +*.nupkg +project.lock.json +project.assets.json +``` The `.gitignore` file is [quite powerful](https://www.kernel.org/pub/software/scm/git/docs/gitignore.html). For example, if you want to generally not check-in the contents of the `packages` folder but want to go with previous guidance of checking in the `.targets` files you could have the following rule instead: - packages - !packages/**/*.targets +``` +packages +!packages/**/*.targets +``` This will exclude all `packages` folders but will re-include all contained `.targets` files. By the way, you can find a template for `.gitignore` files that is specifically tailored for the needs of Visual Studio developers [here](https://github.com/github/gitignore/blob/master/VisualStudio.gitignore). TF version control supports a very similar mechanism via the [.tfignore](/vsts/tfvc/add-files-server#customize-which-files-are-ignored-by-version-control) file. The syntax is virtually the same: - *.user - *.suo - bin - obj - packages - *.nupkg - project.lock.json - project.assets.json +``` +*.user +*.suo +bin +obj +packages +*.nupkg +project.lock.json +project.assets.json +``` ## build.proj diff --git a/docs/consume-packages/configuring-nuget-behavior.md b/docs/consume-packages/configuring-nuget-behavior.md index bf3f5b90e..388cafd94 100644 --- a/docs/consume-packages/configuring-nuget-behavior.md +++ b/docs/consume-packages/configuring-nuget-behavior.md @@ -1,34 +1,51 @@ --- title: Common NuGet configurations -description: NuGet.Config files control NuGet's behavior both globally and on a per-project basis, and are modified with nuget config command. -author: karann-msft -ms.author: karann -ms.date: 10/25/2017 -ms.topic: conceptual +description: NuGet.Config files control NuGet's behavior, and can be modified with nuget config command. +author: JonDouglas +ms.author: jodou +ms.date: 01/10/2022 +ms.topic: article --- # Common NuGet configurations -NuGet's behavior is driven by the accumulated settings in one or more `NuGet.Config` (XML) files that can exist at project-, user-, and computer-wide levels. A global `NuGetDefaults.Config` file also specifically configures package sources. Settings apply to all commands issued in the CLI, the Package Manager Console, and the Package Manager UI. +NuGet's behavior is driven by the accumulated settings in one or more config (XML) files that can exist at solution- (project if no solution is used), user-, and computer-wide levels. ## Config file locations and uses -| Scope | NuGet.Config file location | Description | +| Scope | `NuGet.Config` file location | Description | | --- | --- | --- | -| Solution | Current folder (aka Solution folder) or any folder up to the drive root.| In a solution folder, settings apply to all projects in subfolders. Note that if a config file is placed in a project folder, it has no effect on that project. | -| User | Windows: `%appdata%\NuGet\NuGet.Config`
Mac/Linux: `~/.config/NuGet/NuGet.Config` or `~/.nuget/NuGet/NuGet.Config` (varies by OS distribution) | Settings apply to all operations, but are overridden by any project-level settings. | -| Computer | Windows: `%ProgramFiles(x86)%\NuGet\Config`
Mac/Linux: `$XDG_DATA_HOME`. If `$XDG_DATA_HOME` is null or empty, `~/.local/share` or `/usr/local/share` will be used (varies by OS distribution) | Settings apply to all operations on the computer, but are overridden by any user- or project-level settings. | +| Solution | Current folder (aka Solution folder) or any folder up to the drive root.| In a solution folder, settings apply to all projects in subfolders. Note that if a config file is placed in a project folder, it has no effect on that project. When restoring a project on the command line, the project's directory is treated as the solution directory, which can lead to differences in behaviour when restoring the project vs solution. | +| User | **Windows:** `%appdata%\NuGet\NuGet.Config`
**Mac/Linux:** `~/.config/NuGet/NuGet.Config` or `~/.nuget/NuGet/NuGet.Config` (varies by tooling)
Additional configs are supported on all platforms. These configs cannot be edited by the tooling.
**Windows:** `%appdata%\NuGet\config\*.Config`
**Mac/Linux:** `~/.config/NuGet/config/*.config` or `~/.nuget/config/*.config` | Settings apply to all operations, but are overridden by any solution-level settings. | +| Computer | **Windows:** `%ProgramFiles(x86)%\NuGet\Config`
**Mac/Linux:** `/etc/opt/NuGet/Config` (Linux) or `/Library/Application Support` (Mac) by default. If `$NUGET_COMMON_APPLICATION_DATA` is neither null nor empty, then `$NUGET_COMMON_APPLICATION_DATA/NuGet/Config` instead | Settings apply to all operations on the computer, but are overridden by any user- or solution-level settings. | + +> [!Note] +> On Mac/Linux, the user config file location varies by tooling. .NET CLI uses `~/.nuget/NuGet` folder, while Mono uses `~/.config/NuGet` folder. + +### On Mac/Linux, the user-level config file location varies by tooling +On Mac/Linux, the user config file location varies by tooling. +Majority of users use tools that look for the user config file under the `~/.nuget/NuGet` folder. +These other tools look for the user config file under the `~/.config/NuGet` folder: +* Mono +* NuGet.exe +* Visual Studio 2019 for Mac (and earlier versions) +* Visual Studio 2022 for Mac (and later versions), only when working on classic Mono projects. + +If the tooling you use involves both locations, consider consolidating them by following these steps to allow you to work with only one user-level config file: +1. Check the contents of the two user-level config files and keep the one you want under `~/.nuget/NuGet` folder. +2. Set symbolic link from `~/.nuget/NuGet` to `~/.config/NuGet`. E.g. Run bash command: `ln -s ~/.nuget/NuGet ~/.config/NuGet`. + Notes for earlier versions of NuGet: - NuGet 3.3 and earlier used a `.nuget` folder for solution-wide settings. This folder is not used in NuGet 3.4+. -- For NuGet 2.6 to 3.x, the computer-level config file on Windows was located in %ProgramData%\NuGet\Config[\\{IDE}[\\{Version}[\\{SKU}]]]\NuGet.Config, where *{IDE}* can be *VisualStudio*, *{Version}* was the Visual Studio version such as *14.0*, and *{SKU}* is either *Community*, *Pro*, or *Enterprise*. To migrate settings to NuGet 4.0+, simply copy the config file to %ProgramFiles(x86)%\NuGet\Config. On Linux, this previous location was /etc/opt, and on Mac, /Library/Application Support. +- For NuGet 2.6 to 3.x, the computer-level config file on Windows was located in `%ProgramData%\NuGet\Config[\{IDE}[\{Version}[\{SKU}]]]\NuGet.Config`, where `{IDE}` can be `VisualStudio`, `{Version}` was the Visual Studio version such as `14.0`, and `{SKU}` is either `Community`, `Pro`, or `Enterprise`. To migrate settings to NuGet 4.0+, simply copy the config file to `%ProgramFiles(x86)%\NuGet\Config`. On Linux, this previous location was `/etc/opt`, and on Mac, `/Library/Application Support`. ## Changing config settings A `NuGet.Config` file is a simple XML text file containing key/value pairs as described in the [NuGet Configuration Settings](../reference/nuget-config-file.md) topic. Settings are managed using the NuGet CLI [config command](../reference/cli-reference/cli-ref-config.md): -- By default, changes are made to the user-level config file. +- By default, changes are made to the user-level config file. (On Mac/Linux, the location of user-level config file varies by tooling) - To change settings in a different file, use the `-configFile` switch. In this case files can use any filename. - Keys are always case sensitive. - Elevation is required to change settings in the computer-level settings file. @@ -41,29 +58,35 @@ Settings are managed using the NuGet CLI [config command](../reference/cli-refer Windows: ```cli -# Set repositoryPath in the user-level config file -nuget config -set repositoryPath=c:\packages +# Set globalPackagesFolder in the user-level config file +dotnet nuget config set globalPackagesFolder "C:\packages" -# Set repositoryPath in project-level files -nuget config -set repositoryPath=c:\packages -configfile c:\my.Config -nuget config -set repositoryPath=c:\packages -configfile .\myApp\NuGet.Config +# Set repositoryPath (available for packages.config only) in the user-level config file +dotnet nuget config set repositoryPath "C:\packages" + +# Set repositoryPath in solution-level files +dotnet nuget config set repositoryPath "C:\packages" --configfile "C:\my.config" +dotnet nuget config set repositoryPath "c:\packages" --configfile "..\..\my.config" # Set repositoryPath in the computer-level file (requires elevation) -nuget config -set repositoryPath=c:\packages -configfile %ProgramFiles(x86)%\NuGet\Config\NuGet.Config +dotnet nuget config set repositoryPath "c:\packages" --configfile "%appdata%\NuGet\NuGet.Config" ``` Mac/Linux: ```cli -# Set repositoryPath in the user-level config file -nuget config -set repositoryPath=/home/packages +# Set globalPackagesFolder in the user-level config file +dotnet nuget config set globalPackagesFolder /home/packages + +# Set repositoryPath (available for packages.config only) in the user-level config file +dotnet nuget config set repositoryPath /home/packages -# Set repositoryPath in project-level files -nuget config -set repositoryPath=/home/projects/packages -configfile /home/my.Config -nuget config -set repositoryPath=/home/packages -configfile home/myApp/NuGet.Config +# Set repositoryPath in solution-level files +dotnet nuget config set repositoryPath /home/projects/packages --configfile /home/my.Config +dotnet nuget config set repositoryPath /home/packages --configfile home/myApp/NuGet.Config # Set repositoryPath in the computer-level file (requires elevation) -nuget config -set repositoryPath=/home/packages -configfile $XDG_DATA_HOME/NuGet.Config +dotnet nuget config set repositoryPath /home/packages --configfile $XDG_DATA_HOME/NuGet.Config ``` > [!Note] @@ -83,7 +106,10 @@ nuget config -set repositoryPath= -configfile /home/my.Config ### Creating a new config file -Copy the template below into the new file and then use `nuget config -configFile ` to set values: +Using the .NET CLI, create a default nuget.config by running `dotnet new nugetconfig`. +For more information, see [dotnet CLI commands](../reference/dotnet-commands.md#package-consumption). + +Alternatively, manually copy the template below into the new file and then use `nuget config -configFile ` to set values: ```xml @@ -93,36 +119,42 @@ Copy the template below into the new file and then use `nuget config -configFile ## How settings are applied -Multiple `NuGet.Config` files allow you to store settings in different locations so that they apply to a single project, a group of projects, or all projects. These settings collectively apply to any NuGet operation invoked from the command line or from Visual Studio, with settings that exist "closest" to a project or the current folder taking precedence. +Multiple `NuGet.Config` files allow you to store settings in different locations so that they apply to a single solution, or a group of solutions. +These settings collectively apply to any NuGet operation invoked from the command line or from Visual Studio, with settings that exist "closest" to a solution or the current folder taking precedence. +If a command line tool is used on a project file, rather than a solution file, then the project directory is used as the "solution directory", which can lead to inconsistent behaviour when there is a `NuGet.Config` file in a subdirectory of the solution file. -Specifically, NuGet loads settings from the different config files in the following order: +Specifically, when a config file is not specified explicitly on the command line, NuGet loads settings from the different config files in the following order: -1. The [NuGetDefaults.Config file](#nuget-defaults-file), which contains settings related only to package sources. +1. (*Uncommon*) The [`NuGetDefaults.Config` file](#nuget-defaults-file), which contains settings related only to package sources. 1. The computer-level file. 1. The user-level file. -1. The file specified with `-configFile`. -1. Files found in every folder in the path from the drive root to the current folder (where nuget.exe is invoked or the folder containing the Visual Studio project). For example, if a command is invoked in c:\A\B\C, NuGet looks for and loads config files in c:\, then c:\A, then c:\A\B, and finally c:\A\B\C. +1. Files found in every folder in the path from the drive root to the current folder (where `nuget.exe` is invoked or the folder containing the Visual Studio solution). For example, if a command is invoked in `c:\A\B\C`, NuGet looks for and loads config files in `c:\`, then `c:\A`, then `c:\A\B`, and finally `c:\A\B\C`. -As NuGet finds settings in these files, they are applied as follows: +When a config file is explicitly specified on the command line, for example `nuget -configFile my.config` or `dotnet restore --configfile my.config`, only the settings from the specified file will be used. -1. For single-item elements, NuGet replaced any previously-found value for the same key. This means that settings that are "closest" to the current folder or project override any others found earlier. For example, the `defaultPushSource` setting in `NuGetDefaults.Config` is overridden if it exists in any other config file. +As NuGet finds settings in these files, they are applied as follows: +1. For single-item elements, NuGet replaced any previously-found value for the same key. This means that settings that are "closest" to the current folder or solution override any others found earlier. For example, the `defaultPushSource` setting in `NuGetDefaults.Config` is overridden if it exists in any other config file. 1. For collection elements (such as ``), NuGet combines the values from all configuration files into a single collection. - 1. When `` is present for a given node, NuGet ignores previously defined configuration values for that node. +> [!Tip] +> Add a `nuget.config` file in the root of your solution repository. This is considered a best practice as it promotes repeatability and ensures that different users have the same NuGet configuration. + ### Settings walkthrough Let's say you have the following folder structure on two separate drives: - disk_drive_1 - User - disk_drive_2 - Project1 - Source - Project2 - Source - tmp +``` +disk_drive_1 + User +disk_drive_2 + Project1 + Source + Project2 + Source + tmp +``` You then have four `NuGet.Config` files in the following locations with the given content. (The computer-level file is not included in this example, but would behave similarly to the user-level file.) @@ -131,13 +163,13 @@ File A. User-level file, (`%appdata%\NuGet\NuGet.Config` on Windows, `~/.config/ ```xml - - - + + + ``` -File B. disk_drive_2/NuGet.Config: +File B. `disk_drive_2/NuGet.Config`: ```xml @@ -151,7 +183,7 @@ File B. disk_drive_2/NuGet.Config: ``` -File C. disk_drive_2/Project1/NuGet.Config: +File C. `disk_drive_2/Project1/NuGet.Config`: ```xml @@ -167,7 +199,7 @@ File C. disk_drive_2/Project1/NuGet.Config: ``` -File D. disk_drive_2/Project2/NuGet.Config: +File D. `disk_drive_2/Project2/NuGet.Config`: ```xml @@ -181,39 +213,53 @@ File D. disk_drive_2/Project2/NuGet.Config: NuGet then loads and applies settings as follows, depending on where it's invoked: -- **Invoked from disk_drive_1/users**: Only the default repository listed in the user-level configuration file (A) is used, because that's the only file found on disk_drive_1. +- **Invoked from `disk_drive_1/users`**: Only the default repository listed in the user-level configuration file (A) is used, because that's the only file found on `disk_drive_1`. + +- **Invoked from `disk_drive_2/` or `disk_drive_/tmp`**: The user-level file (A) is loaded first, then NuGet goes to the root of `disk_drive_2` and finds file (B). NuGet also looks for a configuration file in `/tmp` but does not find one. As a result, the default repository on `nuget.org` is used, package restore is enabled, and packages get expanded in `disk_drive_2/tmp`. -- **Invoked from disk_drive_2/ or disk_drive_/tmp**: The user-level file (A) is loaded first, then NuGet goes to the root of disk_drive_2 and finds file (B). NuGet also looks for a configuration file in /tmp but does not find one. As a result, the default repository on nuget.org is used, package restore is enabled, and packages get expanded in disk_drive_2/tmp. +- **Invoked from `disk_drive_2/Project1` or `disk_drive_2/Project1/Source`**: The user-level file (A) is loaded first, then NuGet loads file (B) from the root of `disk_drive_2`, followed by file (C). Settings in (C) override those in (B) and (A), so the `repositoryPath` where packages get installed is `disk_drive_2/Project1/External/Packages` instead of `disk_drive_2/tmp`. Also, because (C) clears ``, nuget.org is no longer available as a source leaving only `https://MyPrivateRepo/ES/nuget`. -- **Invoked from disk_drive_2/Project1 or disk_drive_2/Project1/Source**: The user-level file (A) is loaded first, then NuGet loads file (B) from the root of disk_drive_2, followed by file (C). Settings in (C) override those in (B) and (A), so the `repositoryPath` where packages get installed is disk_drive_2/Project1/External/Packages instead of *disk_drive_2/tmp*. Also, because (C) clears ``, nuget.org is no longer available as a source leaving only `https://MyPrivateRepo/ES/nuget`. +- **Invoked from `disk_drive_2/Project2` or `disk_drive_2/Project2/Source`**: The user-level file (A) is loaded first followed by file (B) and file (D). Because `packageSources` is not cleared, both `nuget.org` and `https://MyPrivateRepo/DQ/nuget` are available as sources. Packages get expanded in `disk_drive_2/tmp` as specified in (B). -- **Invoked from disk_drive_2/Project2 or disk_drive_2/Project2/Source**: The user-level file (A) is loaded first followed by file (B) and file (D). Because `packageSources` is not cleared, both `nuget.org` and `https://MyPrivateRepo/DQ/nuget` are available as sources. Packages get expanded in disk_drive_2/tmp as specified in (B). +## Additional user wide configuration + +Starting with 5.7, NuGet has added support for additional user wide configuration files. This allows third-party vendors to add additional user configuration files without elevation. +These configuration files are found in the standard user wide configuration folder within a `config` subfolder. +All files ending with `.config` or `.Config` will be considered. +These files cannot be edited by the standard tooling. + +| OS Platform | Additional Configurations | +| --- | --- | +| Windows | `%appdata%\NuGet\config\*.Config` | +| Mac/Linux | `~/.config/NuGet/config/*.config` or `~/.nuget/config/*.config` | ## NuGet defaults file -The `NuGetDefaults.Config` file exists to specify package sources from which packages are installed and updated, and to control the default target for publishing packages with `nuget push`. Because administrators can conveniently (using Group Policy, for example) deploy consistent `NuGetDefaults.Config` files to developer and build machines, they can ensure that everyone in the organization is using the correct package sources rather than nuget.org. +The `NuGetDefaults.Config` is uncommon and can only specify package sources from which packages are installed and updated, or control the default target for publishing packages with `nuget push`. + +Because administrators can conveniently (using Group Policy, for example) deploy consistent `NuGetDefaults.Config` files to developer and build machines, they can ensure that everyone in the organization is using consistent package sources, whether or not that includes nuget.org. > [!Important] > The `NuGetDefaults.Config` file never causes a package source to be removed from a developer's NuGet configuration. That means if the developer has already used NuGet and therefore has the nuget.org package source registered, it won't be removed after the creation of a `NuGetDefaults.Config` file. > > Furthermore, neither `NuGetDefaults.Config` nor any other mechanism in NuGet can prevent access to package sources like nuget.org. If an organization wishes to block such access, it must use other means such as firewalls to do so. -### NuGetDefaults.Config location +### `NuGetDefaults.Config` location The following table describes where the `NuGetDefaults.Config` file should be stored, depending on the target OS: -| OS Platform | NuGetDefaults.Config Location | +| OS Platform | `NuGetDefaults.Config` Location | | --- | --- | -| Windows | **Visual Studio 2017 or NuGet 4.x+:** `%ProgramFiles(x86)%\NuGet\Config`
**Visual Studio 2015 and earlier or NuGet 3.x and earlier:** `%PROGRAMDATA%\NuGet` | +| Windows | **Visual Studio 2017 or NuGet 4.x+:** `%ProgramFiles(x86)%\NuGet`
**Visual Studio 2015 and earlier or NuGet 3.x and earlier:** `%PROGRAMDATA%\NuGet` | | Mac/Linux | `$XDG_DATA_HOME` (typically `~/.local/share` or `/usr/local/share`, depending on OS distribution)| ### NuGetDefaults.Config settings - `packageSources`: this collection has the same meaning as `packageSources` in regular config files and specifies the default sources. NuGet uses the sources in order when installing or updating packages in projects using the `packages.config` management format. For projects using the PackageReference format, NuGet uses local sources first, then sources on network shares, then HTTP sources, regardless of the order in the configuration files. NuGet always ignores the order of sources with restore operations. -- `disabledPackageSources`: this collection also has the same meaning as in `NuGet.Config` files, where each affected source is listed by its name and a true/false value indicating whether it's disabled. This allows the source name and URL to remain in `packageSources` without having it turned on by default. Individual developers can then re-enable the source by setting the source's value to false in other `NuGet.Config` files without having to find the correct URL again. This is also useful to supply developers with a full list of internal source URLs for an organization while enabling only an individual team's source by default. +- `disabledPackageSources`: this collection also has the same meaning as in `NuGet.Config` files, where each affected source is listed by its name and a `true`/`false` value indicating whether it's disabled. This allows the source name and URL to remain in `packageSources` without having it turned on by default. Individual developers can then re-enable the source by setting the source's value to `false` in other `NuGet.Config` files without having to find the correct URL again. This is also useful to supply developers with a full list of internal source URLs for an organization while enabling only an individual team's source by default. -- `defaultPushSource`: specifies the default target for `nuget push` operations, overriding the built-in default of nuget.org. Administrators can deploy this setting to avoid publishing internal packages to the public nuget.org by accident, as developers specifically need to use `nuget push -Source` to publish to nuget.org. +- `defaultPushSource`: specifies the default target for `nuget push` operations, overriding the built-in default of `nuget.org`. Administrators can deploy this setting to avoid publishing internal packages to the public `nuget.org` by accident, as developers specifically need to use `nuget push -Source` to publish to `nuget.org`. ### Example NuGetDefaults.Config and application diff --git a/docs/consume-packages/consuming-packages-authenticated-feeds.md b/docs/consume-packages/consuming-packages-authenticated-feeds.md new file mode 100644 index 000000000..126662636 --- /dev/null +++ b/docs/consume-packages/consuming-packages-authenticated-feeds.md @@ -0,0 +1,149 @@ +--- +title: Consuming packages from authenticated feeds +description: Consuming packages from authenticated feeds in all NuGet client scenarios +author: nkolev92 +ms.author: nikolev +ms.date: 12/22/2023 +ms.topic: how-to +ms.custom: sfi-ropc-nochange +--- + +# Consuming packages from authenticated feeds + +Many NuGet operations, such as restore and install, require communication with one or more package sources, which [can be configured in *nuget.config* files](../reference/nuget-config-file.md#packagesources). + +> [!NOTE] +> Use package sources that you trust. + +For HTTP feeds, NuGet will make an unauthenticated request, and if the server responds with an HTTP 401 response, NuGet will search for credentials in the following order: + +1. [An environment variable `NuGetPackageSourceCredentials_{name}`](#credentials-in-environment-variables). +1. [Credentials in *nuget.config* files](#credentials-in-nugetconfig-files). +1. [Use a NuGet credential provider, if your package source provides one](#credential-providers). + +The credentials you need to use are determined by the package source. +Therefore, unless you're using a credential provider, you should check with your package source for what credentials to use. +It is very common for package sources to forbid you from using your password (that you log into the website with) with NuGet. +Typically you need to create a Personal Access Token to use as NuGet's password, but you should check the documentation for the NuGet server you're using. +Some package sources, such as Azure DevOps and GitHub, have scoped access tokens, so you may need to ensure that any tokens you create include the required scope. + +## Security best practices for managing credentials + +Although NuGet searches for credentials in the order mentioned above, we recommend the following sequence for securely managing credentials when authenticating with private feeds: + +1. **Credential Provider**: It is highly recommended to use a credential provider whenever possible. +This approach avoids storing secrets in plain text and minimizes the risk of accidentally exposing secrets through source control. +Moreover, it generally reduces the number of places you need to update when a credential expires or changes. +If the credential provider supports single sign-on, it may decrease the frequency of logins or the number of places where credentials need to be saved. +Refer to the [credential providers](#credential-providers) section for more information. + +1. **Encrypted Credentials in nuget.config**: If a credential provider is not available, you should consider using encrypted credentials. +This approach provides an extra layer of security by storing the credentials in an encrypted format. +For more information, refer to the section on [credentials in *nuget.config* files](#credentials-in-nugetconfig-files). + + > [!NOTE] + > Be aware that encrypted passwords are only supported on Windows. + > Moreover, they can only be decrypted on the same machine and by the same user who originally encrypted them. + +1. **Using Environment Variable Macros in nuget.config**: If using encrypted credentials is not possible, consider storing the credentials in the *nuget.config* file with environment variable macros. +This approach allows you to reference environment variables that contain the actual credentials. +It enhances transparency and helps end users understand how their credentials are configured. +For more information, refer to the section on [credentials in *nuget.config* files](#credentials-in-nugetconfig-files). + +1. **Using Environment Variables Directly**: As a fallback option, you can store the credentials directly in environment variables. +However, be aware that this approach may offer less visibility and control compared to using environment variable macros in the *nuget.config* file. +For more information, refer to the section on [credentials in environment variables](#credentials-in-environment-variables). + +1. **Clear Text Credentials in NuGet.Config**: It is highly recommended to use one of the previously mentioned options. +If these options are not feasible, you can store the credentials in the *nuget.config* file. +However, this option should only be used in environments where no other secure option is available. +For more information, refer to the section on [credentials in *nuget.config* files](#credentials-in-nugetconfig-files). + + > [!WARNING] + > Storing credentials in clear text in the *nuget.config* file, especially when saving the file in source control, is risky as it increases the chances of accidental credential leaks. + > If you must store credentials in the *nuget.config* file, consider using one of the more secure options mentioned above. + +By adhering to these best practices, you can securely authenticate private feeds while minimizing the risk of sensitive information exposure. + +## Credentials in environment variables + +NuGet will search for an environment variable named `NuGetPackageSourceCredentials_{name}`, where `{name}` is the value of `key="name"` in your *nuget.config* file's package source. +The value of the environment variable must be `Username={username};Password={password}`, and may optionally include `;ValidAuthenticationTypes={types}`. +If the environment variable doesn't match NuGet's convention, or the value doesn't meet NuGet's expected pattern, NuGet will silently ignore the environment variable, and continue searching for credentials for the package source elsewhere. +There are no logs to signal that NuGet uses the credential from the environment variable, which can cause difficulties in debugging authentication problems if the environment variable contains an expired secret, and the new secret is added to a *nuget.config* file, since the config file has lower precedence. + +> [!TIP] +> Using environment variables in CI/CD pipelines is an excellent choice to minimize the risk of secrets being captured in logs. + +For example, consider the following *nuget.config* file: + +```xml + + + + + + +``` + +In this case, the source name is `Contoso` and NuGet will look for the environment variable name `NuGetPackageSourceCredentials_Contoso`. +Some platforms are case-sensitive, so take care about using the correct upper and lower case characters for the environment name and the source name, as defined in your *nuget.config* file. + +If the username is `nugetUser` and the password is `secret123`, the environment variable's value should be set to `Username=nugetUser;Password=secret123`. +If NuGet should only use this credential for HTTP Basic authentication, but not other authentication schemes, you can set the environment variable's value to `Username=nugetUser;Password=secret123;ValidAuthenticationTypes=Basic`. +For more information about valid authentication types, see [the docs on package credentials in *nuget.config* files](../reference/nuget-config-file.md#packagesourcecredentials). + +> [!NOTE] +> Environment variables have restrictions on allowed characters, and different operating systems may have different restrictions. +> For example, spaces are not allowed. +> Therefore, you use this environment variable feature to specify NuGet credentials for package sources that use any characters that are invalid for your platform's environment variables. +> In such cases, you should rename the package source in your *nuget.config* file. + +## Credentials in *nuget.config* files + +*nuget.config* files can contain package source credentials. +See [the *nuget.config* file reference doc section on package source credentials](../reference/nuget-config-file.md#packagesourcecredentials) for more information, including syntax. +However, it's easier to use [`dotnet nuget update source`](/dotnet/core/tools/dotnet-nuget-update-source) on the command line to set the credentials. + +> [!WARNING] +> Take care when setting credentials in *nuget.config* files, especially when saving the credential as plain text. +> If the credential is written to a *nuget.config* file that is in source control, there is an increased risk of accidentally leaking the secret. +> +> As [NuGet accumulates settings from multiple files](../consume-packages/configuring-nuget-behavior.md), it is recommended to save credentials to your user *nuget.config* file. +> We also recommend to save package sources in the solution (source code repository) *nuget.config* file, including a `` element, for build reliability. + +The username and plain text password in a *nuget.config* file can use an environment variable by adding `%` to the beginning and end of the environment variable name you would like to use. +For more information, see [the *nuget.config* reference docs on using environment variables](../reference/nuget-config-file.md#using-environment-variables). + +## Credential providers + +NuGet has an extensibility model, allowing [plugins to provide NuGet credentials](../reference/extensibility/NuGet-Cross-Platform-Authentication-Plugin.md). +The [path that credential providers must be installed](../reference/extensibility/NuGet-Cross-Platform-Plugins.md#plugin-installation-and-discovery), for NuGet to discover, is different for .NET Framework (NuGet.exe, MSBuild, and Visual Studio), and the .NET SDK (running on the .NET 5+ runtime). + +NuGet has a concept of being run in interactive mode or non-interactive mode. +When in non-interactive mode, credential providers are asked not to block NuGet. +While in interactive mode, the credential provider may prompt you to log in. +Different tools have different defaults, so interactive mode may need to be opt-in or opt-out, depending on your scenario. + +|Tool|Default|Toggle| +|--|--|--| +|`dotnet` CLI|non-interactive|`--interactive` argument. For example, `dotnet restore --interactive`.| +|MSBuild|non-interactive|`NuGetInteractive` MSBuild property. For example, `msbuild -t:restore -p:NuGetInteractive=true`.| +|NuGet.exe|interactive|`-NonInteractive` argument. For example, `nuget.exe restore -NonInteractive`.| +|Visual Studio|interactive|not possible to run in non-interactive mode.| + +[NuGet.exe supports both V1 and V2 credential providers](../reference/extensibility/nuget-exe-Credential-Providers.md), while MSBuild and the .NET SDK only support the cross platform (V2) plugins. + +In Visual Studio, NuGet has a [Visual Studio Credential Provider interface](../reference/extensibility/NuGet-Credential-Providers-for-Visual-Studio.md), which credential providers can use to provide a graphical login experience, or call Visual Studio APIs if necessary. +NuGet in Visual Studio will fall back to the command line credential providers if it can't find a Visual Studio credential provider that handles the source. + +Visual Studio 2017 version 15.9, and above, includes a credential provider for [Azure Artifacts](/azure/devops/artifacts/), that works within Visual Studio, MSBuild, and NuGet.exe. +However, the credential provider for the .NET SDK is not included by Visual Studio, so [must be installed separately](https://github.com/microsoft/artifacts-credprovider?tab=readme-ov-file#setup) to work with the `dotnet` CLI. + +### List of credential providers + +Here is a list of credential providers we are aware of: + +* [AWS CodeArtifact NuGet Credential Provider](https://docs.aws.amazon.com/codeartifact/latest/ug/nuget-cli.html#nuget-configure-cli) +* [Azure Artifacts Credential Provider](https://github.com/microsoft/artifacts-credprovider). This link is just for the command line credential provider. +* [MyGet Credential Provider for Visual Studio](http://docs.myget.org/docs/reference/credential-provider-for-visual-studio). diff --git a/docs/consume-packages/includes/restore-dotnet-cli.md b/docs/consume-packages/includes/restore-dotnet-cli.md index a5240d1b3..6d3b8bd98 100644 --- a/docs/consume-packages/includes/restore-dotnet-cli.md +++ b/docs/consume-packages/includes/restore-dotnet-cli.md @@ -1,9 +1,9 @@ -Use the [dotnet restore](/dotnet/core/tools/dotnet-restore?tabs=netcore2x) command, which restores packages listed in the project file (see [PackageReference](../../consume-packages/package-references-in-project-files.md)). With .NET Core 2.0 and later, restore is done automatically with `dotnet build` and `dotnet run`. As of NuGet 4.0, this runs the same code as `nuget restore`. +The [dotnet restore](/dotnet/core/tools/dotnet-restore) command restores packages that the project file lists with ``. For more information, see [PackageReference in project files](../../consume-packages/package-references-in-project-files.md). -As with the other `dotnet` CLI commands, first open a command line and switch to the directory that contains your project file. +.NET Core 2.0 and later `dotnet build` and `dotnet run` commands restore packages automatically. As of NuGet 4.0, `dotnet restore` runs the same code as `nuget restore`. -To restore a package using `dotnet restore`: +To restore a package with `dotnet restore`: + +1. Open a command line and switch to the directory that contains your project file. +1. Run `dotnet restore`. -```cli -dotnet restore -``` \ No newline at end of file diff --git a/docs/consume-packages/includes/restore-nuget-exe-cli.md b/docs/consume-packages/includes/restore-nuget-exe-cli.md index 363dab71e..e3fd938b2 100644 --- a/docs/consume-packages/includes/restore-nuget-exe-cli.md +++ b/docs/consume-packages/includes/restore-nuget-exe-cli.md @@ -1,13 +1,21 @@ -Use the [restore](../../reference/cli-reference/cli-ref-restore.md) command, which downloads and installs any packages missing from the *packages* folder. +The NuGet CLI [restore](../../reference/cli-reference/cli-ref-restore.md) command downloads and installs any missing packages. The command works on projects that use either [PackageReference](/nuget/consume-packages/package-references-in-project-files) or [packages.config](/nuget/reference/packages-config) for package references. -For projects migrated to PackageReference, use [msbuild -t:restore](../package-restore.md#restore-using-msbuild) to restore packages instead. +Like `install`, the `restore` command only adds packages to disk, but doesn't modify the project file or *packages.config*. To add project dependencies, use the Visual Studio Package Manager UI or Console. -`restore` only adds packages to disk but does not change a project's dependencies. To restore project dependencies, modify `packages.config`, then use the `restore` command. +To restore packages, run the following command: -As with the other `nuget.exe` CLI commands, first open a command line and switch to the directory that contains your project file. +```cli +nuget restore +``` + +The `restore` command uses a solution file or a *package.config* file in the specified project path. -To restore a package using `restore`: +For example, to restore all packages for *MySolution.sln* in the current directory, run: ```cli nuget restore MySolution.sln -``` \ No newline at end of file +``` + +> [!NOTE] +> For non-SDK-style projects that use `PackageReference`, use [msbuild -t:restore](../package-restore.md#restore-using-msbuild) to restore packages instead. + diff --git a/docs/consume-packages/install-use-packages-dotnet-cli.md b/docs/consume-packages/install-use-packages-dotnet-cli.md index 8d5c514c3..44e878149 100644 --- a/docs/consume-packages/install-use-packages-dotnet-cli.md +++ b/docs/consume-packages/install-use-packages-dotnet-cli.md @@ -1,92 +1,96 @@ --- -title: Install and manage NuGet packages using the dotnet CLI -description: Instructions for using the dotnet CLI to work with NuGet packages. +title: Install and manage NuGet packages with the dotnet CLI +description: See how to use the dotnet CLI to install, list, remove, and update NuGet packages. author: mikejo5000 ms.author: mikejo -ms.date: 06/03/2019 -ms.topic: conceptual +ms.date: 03/03/2025 +ms.topic: install-set-up-deploy --- -# Install and manage packages using the dotnet CLI +# Install and manage NuGet packages with the dotnet CLI -The CLI tool allows you to easily install, uninstall, and update NuGet packages in projects and solutions. It runs on Windows, Mac OS X, and Linux. +You can use the dotnet CLI tool on Windows, macOS, or Linux to easily install, uninstall, and update NuGet packages in .NET projects and solutions. This article describes the most common dotnet CLI commands for managing NuGet packages. -The dotnet CLI is for use in your .NET Core and .NET Standard project (SDK-style project types), and for any other SDK-style projects (for example, an SDK-style project that targets .NET Framework). For more information, see [SDK attribute](/dotnet/core/tools/csproj#additions). +The dotnet CLI runs on .NET, .NET Core, .NET Standard SDK-style projects, and any other SDK-style projects, for example those that target .NET Framework. For more information, see [.NET project SDKs](/dotnet/core/project-sdk/overview). -This article shows you basic usage for a few of the most common dotnet CLI commands. For most of these commands, the CLI tool looks for a project file in the current directory, unless a project file is specified in the command (the project file is an optional switch). For a complete list of commands and the arguments you may use, see the [.NET Core command-line interface (CLI) tools](../reference/dotnet-commands.md). +For most commands, the CLI tool looks for a project file in the current directory, unless a different project file is specified as an optional switch in the command. For a complete list of commands and their arguments, see [dotnet CLI commands](../reference/dotnet-commands.md). ## Prerequisites -- The [.NET Core SDK](https://www.microsoft.com/net/download/), which provides the `dotnet` command-line tool. Starting in Visual Studio 2017, the dotnet CLI is automatically installed with any .NET Core related workloads. +- The [.NET Core SDK](https://www.microsoft.com/net/download/), which provides the `dotnet` command-line tool. Starting in Visual Studio 2017, the dotnet CLI automatically installs with all .NET and .NET Core related workloads. -## Install a package +## Install or update a package -[dotnet add package](/dotnet/core/tools/dotnet-add-package?tabs=netcore2x) adds a package reference to the project file, then runs `dotnet restore` to install the package. +The [dotnet add package](/dotnet/core/tools/dotnet-add-package) command adds a package reference to the project file, and then runs `dotnet restore` to install the package. 1. Open a command line and switch to the directory that contains your project file. -2. Use the following command to install a Nuget package: +1. Use the following command to install a NuGet package: - ```cli + ```dotnetcli dotnet add package ``` For example, to install the `Newtonsoft.Json` package, use the following command - ```cli + ```dotnetcli dotnet add package Newtonsoft.Json ``` -3. After the command completes, look at the project file to make sure the package was installed. +1. After the command completes, you can open the project file to see the package reference. - You can open the `.csproj` file to see the added reference: + For example, open the *.csproj* file to see the added `Newtonsoft.Json` package reference: ```xml - - - + + + ``` ## Install a specific version of a package -If the version is not specified, NuGet installs the latest version of the package. You can also use the [dotnet add package](/dotnet/core/tools/dotnet-add-package?tabs=netcore2x) command to install a specific version of a Nuget package: +The `dotnet add package` command installs the latest version of the package unless you specify a different version. -```cli +To install a specific version of a NuGet package, use the optional `-v` or `--version` switch: + +```dotnetcli dotnet add package -v ``` For example, to add version 12.0.1 of the `Newtonsoft.Json` package, use this command: -```cli -dotnet add package Newtonsoft.Json -v 12.0.1 +```dotnetcli +dotnet add package Newtonsoft.Json --version 12.0.1 ``` ## List package references -You can list the package references for your project using the [dotnet list package](/dotnet/core/tools/dotnet-list-package?tabs=netcore2x) command. +List the package references and versions for your project by using the [dotnet list package](/dotnet/core/tools/dotnet-list-package) command: -```cli +```dotnetcli dotnet list package ``` ## Remove a package -Use the [dotnet remove package](/dotnet/core/tools/dotnet-remove-package?tabs=netcore2x) command to remove a package reference from the project file. +Use the [dotnet remove package](/dotnet/core/tools/dotnet-remove-package) command to remove a package reference from the project file. -```cli +```dotnetcli dotnet remove package ``` -For example, to remove the `Newtonsoft.Json` package, use the following command +For example, to remove the `Newtonsoft.Json` package, use the following command: -```cli +```dotnetcli dotnet remove package Newtonsoft.Json ``` -## Update a package - -NuGet installs the latest version of the package when you use the `dotnet add package` command unless you specify the package version (`-v` switch). - ## Restore packages [!INCLUDE [restore-dotnet-cli](includes/restore-dotnet-cli.md)] + +## Next steps + +- [.NET CLI overview](/dotnet/core/tools) +- [Install and manage packages in Visual Studio using the NuGet Package Manager](install-use-packages-visual-studio.md) +- [Install and manage packages with the Package Manager Console](install-use-packages-powershell.md) diff --git a/docs/consume-packages/install-use-packages-nuget-cli.md b/docs/consume-packages/install-use-packages-nuget-cli.md index 1067aa7b2..3b6639dc4 100644 --- a/docs/consume-packages/install-use-packages-nuget-cli.md +++ b/docs/consume-packages/install-use-packages-nuget-cli.md @@ -1,118 +1,123 @@ --- -title: Manage NuGet packages using the nuget.exe CLI -description: Instructions for using the nuget.exe CLI to work with NuGet packages. +title: Manage NuGet packages with the NuGet CLI +description: Instructions for using the NuGet CLI, nuget.exe, to manage NuGet packages. author: mikejo5000 ms.author: mikejo -ms.date: 06/03/2019 -ms.topic: conceptual +ms.date: 03/03/2025 +ms.topic: how-to --- -# Manage packages using the nuget.exe CLI +# Manage NuGet packages with the NuGet CLI -The CLI tool allows you to easily update and restore NuGet packages in projects and solutions. This tool provides all NuGet capabilities on Windows, and also provides most features on Mac and Linux when running under Mono. +You can use the `nuget.exe` CLI tool to manage NuGet packages in Visual Studio projects and solutions. This article describes the most common NuGet CLI commands for managing NuGet packages. All these commands work on Windows, and most work on Mac and on Linux with Mono. -The `nuget.exe` CLI is for your .NET Framework project and non-SDK-style projects (for example, a non-SDK style project that targets .NET Standard libraries). If you are using a non-SDK-style project that has been migrated to `PackageReference`, use the `dotnet` CLI instead. The `nuget.exe` CLI requires a [packages.config](../reference/packages-config.md) file for package references. +The NuGet CLI runs on .NET Framework and non-SDK-style projects, for example non-SDK style projects that target .NET Standard libraries. The NuGet CLI commands can use a project [packages.config](../reference/packages-config.md) file that lists package references. For non-SDK-style projects that use `PackageReference` instead of *packages.config* for package references, use the [dotnet CLI](install-use-packages-dotnet-cli.md) instead. > [!NOTE] -> In most scenarios, we recommend [migrating non-SDK-style projects](../consume-packages/migrate-packages-config-to-package-reference.md) that use `packages.config` to PackageReference, and then you can use the `dotnet` CLI instead of the `nuget.exe` CLI. Migration is not currently available for C++ and ASP.NET projects. +> For most non-SDK-style projects that use *packages.config*, it's best to [migrate packages.config to PackageReference](migrate-packages-config-to-package-reference.md), and then use the dotnet CLI instead of the NuGet CLI to manage packages. However, you can't migrate C++ or ASP.NET projects. -This article shows you basic usage for a few of the most common `nuget.exe` CLI commands. For most of these commands, the CLI tool looks for a project file in the current directory, unless a project file is specified in the command. For a complete list of commands and the arguments you may use, see the [nuget.exe CLI reference](../reference/nuget-exe-cli-reference.md). +For most commands, the NuGet CLI tool uses the current directory, unless you specify a different location in the command. To run NuGet CLI commands, open a command line and switch to the directory that contains your project file. + +For a complete list of commands and their arguments, see the [NuGet CLI reference](../reference/nuget-exe-cli-reference.md). ## Prerequisites -- Install the `nuget.exe` CLI by downloading it from [nuget.org](https://dist.nuget.org/win-x86-commandline/latest/nuget.exe), saving that `.exe` file to a suitable folder, and adding that folder to your PATH environment variable. +Download the NuGet CLI from [nuget.org](https://dist.nuget.org/win-x86-commandline/latest/nuget.exe). Save the *nuget.exe* file to a suitable directory, and make sure the directory is in your PATH environment variable. + +> [!NOTE] +> You can also use the [winget](/windows/package-manager/winget) tool for Windows or [Homebrew](https://brew.sh/) for macOS. + +To find out your NuGet CLI version, open a command line and run `nuget help`, or to avoid having to scroll up, use `nuget help | more`. The first line in the help output shows the version. ## Install a package -The [install](../reference/cli-reference/cli-ref-install.md) command downloads and installs a package into a project, defaulting to the current folder, using specified package sources. Install new packages into the *packages* folder in your project root directory. +The NuGet CLI [install](../reference/cli-reference/cli-ref-install.md) command downloads and installs specified NuGet packages. > [!IMPORTANT] -> The `install`command does not modify a project file or *packages.config*; in this way it's similar to `restore` in that it only adds packages to disk but does not change a project's dependencies. To add a dependency, either add a package through the Package Manager UI or Console in Visual Studio, or modify *packages.config* and then run either `install` or `restore`. +> The `install` command doesn't modify the project file or *packages.config* file. The `install` and `restore` commands only add packages to disk, but don't add dependencies to projects. To add project dependencies, add packages through the [Visual Studio Package Manager UI](install-use-packages-visual-studio.md) or [Package Manager Console](install-use-packages-powershell.md), then run `install` or `restore`. -1. Open a command line and switch to the directory that contains your project file. +Use the `-OutputDirectory` option to install packages to a specific directory. If you don't specify an output directory, `install` uses the current directory. -2. Use the following command to install a NuGet package to the *packages* folder. +```cli +nuget install -OutputDirectory +``` - ```cli - nuget install -OutputDirectory packages - ``` +For example, to install the `Newtonsoft.json` package to the *packages* subdirectory, use the following command: - To install the `Newtonsoft.json` package to the *packages* folder, use the following command: +```cli +nuget install Newtonsoft.Json -OutputDirectory packages +``` + +Instead of specifying a package to install, you can specify an existing *packages.config* file in the current or another directory. The `install` command installs all the packages listed in the *packages.config* file. - ```cli - nuget install Newtonsoft.Json -OutputDirectory packages - ``` +```cli +nuget install packages.config +``` -Alternatively, you can use the following command to install a NuGet package using an existing `packages.config` file to the *packages* folder. This does not add the package to your project dependencies, but installs it locally. +For example, the following command installs all the packages listed in *packages.config* in the *config* subdirectory to the *packages* subdirectory: ```cli -nuget install packages.config -OutputDirectory packages +nuget install config\packages.config -OutputDirectory packages + ``` ## Install a specific version of a package -If the version is not specified when you use the [install](../reference/cli-reference/cli-ref-install.md) command, NuGet installs the latest version of the package. You can also install a specific version of a Nuget package: +The `install` command installs the latest version of a package unless you specify a different version. To install a specific version of a package, use the `-Version` option: ```cli nuget install -Version ``` -For example, to add version 12.0.1 of the `Newtonsoft.json` package, use this command: +For example, to install version 12.0.1 of the `Newtonsoft.json` package, use: ```cli nuget install Newtonsoft.Json -Version 12.0.1 ``` -For more information on the limitations and behavior of `install`, see [Install a package](#install-a-package). - -## Remove a package - -To delete one or more packages, delete the packages you want to remove from the *packages* folder. - -If you want to reinstall packages, use the `restore` or `install` command. - ## List packages -You can display a list of packages from a given source using the [list](../reference/cli-reference/cli-ref-list.md) command. Use the `-Source` option to restrict the search. +Use the [list](../reference/cli-reference/cli-ref-list.md) command to display a list of packages installed in the packages folders. Use the `-Source` option to restrict the list. ```cli nuget list -Source ``` -For example, list packages in the *packages* folder. +For example, to list packages in the *packages* subdirectory of *MyProject*, use: ```cli -nuget list -Source C:\Users\username\source\repos\MyProject\packages +nuget list -Source C:\Users\%USERNAME%\source\repos\MyProject\packages ``` -If you use a search term, the search includes names of packages, tags, and package descriptions. +You can also use a search term to search for package names, tags, or descriptions: ```cli -nuget list +nuget list <"search term"> -Source ``` -## Update an individual package - -NuGet installs the latest version of the package when you use the `install` command unless you specify the package version. - ## Update all packages -Use the [update](../reference/cli-reference/cli-ref-update.md) command to update all packages. Updates all packages in a project (using `packages.config`) to their latest available versions. It is recommended to run `restore` before running `update`. +Use the [update](../reference/cli-reference/cli-ref-update.md) command to update all packages in a project *packages.config* file to their latest available versions. It's best to run `restore` before you run `update`. ```cli nuget update ``` +## Remove a package + +To remove a package, delete that package from the project folder. To reinstall packages, use the `restore` or `install` commands. + +Deleting packages from disk doesn't update the project, *packages.config*, or *NuGet.Config* files. The best way to remove packages is through the Visual Studio [Package Manager UI](install-use-packages-visual-studio.md) or [Package Manager Console](install-use-packages-powershell.md). + ## Restore packages [!INCLUDE [restore-nuget-exe-cli](includes/restore-nuget-exe-cli.md)] -## Get the CLI version +For more information, see [Restore packages](package-restore.md). -Use this command: - -```cli -nuget help -``` +## Next steps -The first line in the help output shows the version. To avoid scrolling up, use `nuget help | more` instead. \ No newline at end of file +- [NuGet CLI reference](../reference/nuget-exe-cli-reference.md) +- [Install and manage packages in Visual Studio using the NuGet Package Manager](install-use-packages-visual-studio.md) +- [Migrate from packages.config to PackageReference](migrate-packages-config-to-package-reference.md) +- [Manage packages with the dotnet CLI](install-use-packages-dotnet-cli.md) diff --git a/docs/consume-packages/install-use-packages-powershell.md b/docs/consume-packages/install-use-packages-powershell.md index 8637f7e9d..0e7881326 100644 --- a/docs/consume-packages/install-use-packages-powershell.md +++ b/docs/consume-packages/install-use-packages-powershell.md @@ -1,175 +1,205 @@ --- -title: Install and manage NuGet packages using the console in Visual Studio -description: Instructions for using the NuGet Package Manager Console in Visual Studio for working with packages. -author: karann-msft -ms.author: karann -ms.date: 07/08/2019 -ms.topic: conceptual +title: Manage NuGet packages with the Visual Studio Package Manager Console +description: See how to work with NuGet packages by using PowerShell commands in the Visual Studio Package Manager Console. +author: JonDouglas +ms.author: jodou +ms.date: 03/03/2025 +ms.topic: how-to f1_keywords: - "vs.nuget.packagemanager.console" --- -# Install and manage packages with the Package Manager Console in Visual Studio (PowerShell) +# Manage packages with the Visual Studio Package Manager Console (PowerShell) -The NuGet Package Manager Console lets you use [NuGet PowerShell commands](../reference/powershell-reference.md) to find, install, uninstall, and update NuGet packages. Using the console is necessary in cases where the Package Manager UI does not provide a way to perform an operation. To use `nuget.exe` CLI commands in the console, see [Using the nuget.exe CLI in the console](#use-the-nugetexe-cli-in-the-console). +The Package Manager Console in Visual Studio uses PowerShell commands to interact with NuGet packages. You can use the console when there's no way to do an operation through the [Package Manager UI](install-use-packages-visual-studio.md). You can also use [dotnet CLI](../reference/dotnet-commands.md) or [NuGet CLI](#use-the-nugetexe-cli-in-the-console) commands in the console. -The console is built into Visual Studio on Windows. It is not included with Visual Studio for Mac or Visual Studio Code. +This article describes how to find, install, update, and uninstall NuGet packages with PowerShell commands in the Package Manager Console. For the complete Package Manager Console PowerShell command reference, see [PowerShell reference](../reference/powershell-reference.md). -## Find and install a package +> [!IMPORTANT] +> The PowerShell commands and arguments in this article are specific to the Visual Studio Package Manager Console. These commands differ from the [PackageManagement module commands](/powershell/module/packagemanagement) you can use in a general PowerShell environment. Each environment has commands that aren't available in the other, and commands with the same name might differ in their specific arguments. -For example, finding and installing a package is done with three easy steps: +## Console availability -1. Open the project/solution in Visual Studio, and open the console using the **Tools > NuGet Package Manager > Package Manager Console** command. +Starting in Visual Studio 2017, NuGet and the NuGet Package Manager install automatically when you create any .NET-related workloads in Visual Studio. You can also install the Package Manager by selecting **Individual components** > **Code tools** > **NuGet package manager** in the Visual Studio Installer. -1. Find the package you want to install. If you already know this, skip to step 3. +You can also search for the NuGet Package Manager extension under the **Tools** > **Extensions and Updates** or **Extensions** menus. If you're unable to use the extensions installer in Visual Studio, you can download the extension directly from [https://dist.nuget.org/index.html](https://dist.nuget.org/index.html). - ```ps - # Find packages containing the keyword "elmah" +The Package Manager Console is built into the Package Manager for Visual Studio on Windows. Visual Studio Code and Visual Studio for Mac don't include the console. Visual Studio for Mac has a UI for managing NuGet packages, and the equivalent console commands are available through the [NuGet CLI](../reference/nuget-exe-CLI-reference.md). For more information, see [Install and manage NuGet packages in Visual Studio for Mac](/visualstudio/mac/nuget-walkthrough). + +## Quickly find and install a package + +To use the Package Manager Console to quickly find and install a package: + +1. Open your project or solution in Visual Studio, and select **Tools** > **NuGet Package Manager** > **Package Manager Console** to open the Package Manager Console window. + +1. In the console, enter `Find-Package` with a keyword to find the package you want to install. For example, to find packages that contain the keyword `elmah`, run the following command. If you already know the package name you want, skip this step. + + ```powershell Find-Package elmah ``` -1. Run the install command: +1. Once you find the name, use the `Install-Package` command to install the package. For example, to install the `Elmah.MVC` package, enter: - ```ps - # Install the Elmah package to the project named MyProject. - Install-Package Elmah -ProjectName MyProject + ```powershell + Install-Package Elmah.MVC ``` -> [!Important] -> All operations that are available in the console can also be done with the [NuGet CLI](../reference/nuget-exe-cli-reference.md). However, console commands operate within the context of Visual Studio and a saved project/solution and often accomplish more than their equivalent CLI commands. For example, installing a package through the console adds a reference to the project whereas the CLI command does not. For this reason, developers working in Visual Studio typically prefer using the console to the CLI. +For more details about these commands, see the [Find a package](#find-a-package) and [Install a package](#install-a-package) sections. > [!Tip] -> Many console operations depend on having a solution opened in Visual Studio with a known path name. If you have an unsaved solution, or no solution, you can see the error, "Solution is not opened or not saved. Please ensure you have an open and saved solution." This indicates that the console cannot determine the solution folder. Saving an unsaved solution, or creating and saving a solution if you don't have one open, should correct the error. +> Many console operations depend on having a solution with a known path name open in Visual Studio. If you have an unsaved solution, or no solution, you see the error **Solution is not opened or not saved. Please ensure you have an open and saved solution.** To correct the error, create and save a solution, or save an unsaved solution. -## Opening the console and console controls +## Console controls -1. Open the console in Visual Studio using the **Tools > NuGet Package Manager > Package Manager Console** command. The console is a Visual Studio window that can be arranged and positioned however you like (see [Customize window layouts in Visual Studio](/visualstudio/ide/customizing-window-layouts-in-visual-studio)). +To open the Package Manager Console in Visual Studio, select **Tools** > **NuGet Package Manager** > **Package Manager Console** from the top menu. The console is a Visual Studio window that you can arrange and position as you like. For more information, see [Customize window layouts in Visual Studio](/visualstudio/ide/customizing-window-layouts-in-visual-studio). -1. By default, console commands operate against a specific package source and project as set in the control at the top of the window: +By default, console commands operate against the specific package source and project shown in the controls at the top of the window: - ![Package Manager Console controls for package source and project](media/PackageManagerConsoleControls1.png) +:::image type="content" source="media/PackageManagerConsoleControls1.png" alt-text="Screenshot that shows the Package Manager Console controls for package source and project."::: -1. Selecting a different package source and/or project changes those defaults for subsequent commands. To overrride these settings without changing the defaults, most commands support `-Source` and `-ProjectName` options. +Selecting a different package source or project changes the defaults for subsequent commands. To override these settings for single commands without changing the defaults, most console commands support `-Source` and `-ProjectName` options. -1. To manage package sources, select the gear icon. This is a shortcut to the **Tools > Options > NuGet Package Manager > Package Sources** dialog box as described on the [Package Manager UI](install-use-packages-visual-studio.md#package-sources) page. Also, the control to the right of the project selector clears the console's contents: +To manage package sources, select the gear icon, which opens the **Tools** > **Options** > **NuGet Package Manager** > **Package Sources** dialog box. The control next to the project selector clears the console's contents. - ![Package Manager Console settings and clear controls](media/PackageManagerConsoleControls2.png) +:::image type="content" source="media/PackageManagerConsoleControls2.png" alt-text="Screenshot that shows the Package Manager Console settings and clear controls."::: -1. The rightmost button interrupts a long-running command. For example, running `Get-Package -ListAvailable -PageSize 500` lists the top 500 packages on the default source (such as nuget.org), which could take several minutes to run. +The button on the far right interrupts a long-running command. For example, running `Get-Package -ListAvailable -PageSize 500` lists the top 500 available packages on the default source, such as nuget.org, which could take several minutes. - ![Package Manager Console stop control](media/PackageManagerConsoleControls3.png) +:::image type="content" source="media/PackageManagerConsoleControls3.png" alt-text="Screenshot that shows the Package Manager Console stop control."::: -## Install a package +## Find a package -```ps -# Add the Elmah package to the default project as specified in the console's project selector -Install-Package Elmah +To find a package in the default source, use [Find-Package](../reference/ps-reference/ps-ref-find-package.md). -# Add the Elmah package to a project named UtilitiesLib that is not the default -Install-Package Elmah -ProjectName UtilitiesLib -``` +- To find and list packages that contain certain keywords: -See [Install-Package](../reference/ps-reference/ps-ref-install-package.md). + ```powershell + Find-Package + Find-Package + ``` -Installing a package in the console performs the same steps as described on [What happens when a package is installed](../concepts/package-installation-process.md), with the following additions: +- To find and list packages whose name begins with a string: -- The Console displays applicable license terms in its window with implied agreement. If you do not agree to the terms, you should uninstall the package immediately. -- Also a reference to the package is added to the project file and appears in **Solution Explorer** under the **References** node, you need to save the project to see the changes in the project file directly. + ```powershell + Find-Package -StartWith + ``` -## Uninstall a package +- By default, `Find-Package` returns a list of 20 packages. Use `-First` to show more packages. For example, to show the first 100 packages, use: -```ps -# Uninstalls the Elmah package from the default project -Uninstall-Package Elmah + ```powershell + Find-Package -First 100 + ``` -# Uninstalls the Elmah package and all its unused dependencies -Uninstall-Package Elmah -RemoveDependencies +- To list all versions of a certain package: -# Uninstalls the Elmah package even if another package depends on it -Uninstall-Package Elmah -Force + ```powershell + Find-Package -AllVersions -ExactMatch + ``` + +## Install a package + +To install a package into the default project, use `Install-Package `. The [Install-Package](../reference/ps-reference/ps-ref-install-package.md) console command takes the following actions: + +- Does the steps in [What happens when a NuGet package is installed](../concepts/package-installation-process.md). +- Displays applicable license terms in the console window with implied agreement. If you don't agree to the terms, you should uninstall the package. +- Adds a reference to the package in the project file and in **Solution Explorer** under the **References** node. You must save the project before you can see the changes in the project file. + +By default, `Install-Package` adds the package to the default project the console window specifies. To add the package to a project that isn't the default, use the `-ProjectName` option. For example, to add the `Elmah.MVC` package to the non-default `UtilitiesLib` project, run the following command: + +```powershell +Install-Package Elmah.MVC -ProjectName UtilitiesLib ``` -See [Uninstall-Package](../reference/ps-reference/ps-ref-uninstall-package.md). Use [Get-Package](../reference/ps-reference/ps-ref-get-package.md) to see all packages currently installed in the default project if you need to find an identifier. +## Uninstall a package + +To uninstall a package from the default project, use `Uninstall-Package `. If you need to find the package name, use [Get-Package](../reference/ps-reference/ps-ref-get-package.md) to see all packages installed in the default project. -Uninstalling a package performs the following actions: +[Uninstall-Package](../reference/ps-reference/ps-ref-uninstall-package.md) takes the following actions: -- Removes references to the package from the project (and whatever management format is in use). References no longer appear in **Solution Explorer**. (You might need to rebuild the project to see it removed from the **Bin** folder.) -- Reverses any changes made to `app.config` or `web.config` when the package was installed. +- Removes references to the package from the project and any management formats. References no longer appear in **Solution Explorer**. You might need to rebuild the project to remove the reference in the *bin* folder. +- Reverses any changes that installing the package made to *app.config* or *web.config*. - Removes previously-installed dependencies if no remaining packages use those dependencies. +To uninstall a package and all its unused dependencies, run: + +```powershell +Uninstall-Package -RemoveDependencies +``` + +To uninstall a package even if other packages depend on it, run: + +```powershell +Uninstall-Package -Force +``` + ## Update a package -```ps -# Checks if there are newer versions available for any installed packages -Get-Package -updates +To update a package, use [Get-Package](../reference/ps-reference/ps-ref-get-package.md) and [Update-Package](../reference/ps-reference/ps-ref-update-package.md). You can run the following commands: -# Updates a specific package using its identifier, in this case jQuery -Update-Package jQuery +- To check if there are newer versions available for any installed packages: -# Update all packages in the project named MyProject (as it appears in Solution Explorer) -Update-Package -ProjectName MyProject + ```powershell + Get-Package -updates + ``` -# Update all packages in the solution -Update-Package -``` +- To update a specific package: -See [Get-Package](../reference/ps-reference/ps-ref-get-package.md) and [Update-Package](../reference/ps-reference/ps-ref-update-package.md) + ```powershell + Update-Package + ``` -## Find a package +- To update all packages in a project: -```ps -# Find packages containing keywords -Find-Package elmah -Find-Package logging + ```powershell + Update-Package -ProjectName + ``` -# List packages whose ID begins with Elmah -Find-Package Elmah -StartWith +- To update all packages in the solution: -# By default, Get-Package returns a list of 20 packages; use -First to show more -Find-Package logging -First 100 + ```powershell + Update-Package + ``` -# List all versions of the package with the ID of "jquery" -Find-Package jquery -AllVersions -ExactMatch -``` + +## Use the NuGet CLI in the console -See [Find-Package](../reference/ps-reference/ps-ref-find-package.md). In Visual Studio 2013 and earlier, use [Get-Package](../reference/ps-reference/ps-ref-get-package.md) instead. +You can also do most console operations with the [NuGet CLI](../reference/nuget-exe-cli-reference.md). However, the PowerShell console commands operate within the context of Visual Studio saved project and solution, and often do more than their equivalent NuGet CLI commands. For example, installing a package through `Install-Package` adds a reference to the project file, but the NuGet CLI command doesn't. For this reason, developers working in Visual Studio typically prefer to use the console commands rather than the NuGet CLI. -## Availability of the console +To use NuGet CLI commands in the Package Manager Console, install the [NuGet.CommandLine](https://www.nuget.org/packages/NuGet.CommandLine) package. -Starting in Visual Studio 2017, NuGet and the NuGet Package Manager are automatically installed when you select any .NET-related workloads; you can also install it individually by checking the **Individual components > Code tools > NuGet package manager** option in the Visual Studio installer. +```powershell +Install-Package NuGet.CommandLine +``` -Also, if you're missing the NuGet Package Manager in Visual Studio 2015 and earlier, check **Tools > Extensions and Updates...** and search for the NuGet Package Manager extension. If you're unable to use the extensions installer in Visual Studio, you can download the extension directly from [https://dist.nuget.org/index.html](https://dist.nuget.org/index.html). +The preceding command installs the latest version of the NuGet CLI. To install a specific version, use the `-Version` option. For example, to install Version 4.4.1, enter: -The Package Manager Console is not presently available with Visual Studio for Mac. The equivalent commands, however, are available through the [NuGet CLI](../reference/nuget-exe-CLI-reference.md). Visual Studio for Mac does have a UI for managing NuGet packages. See [Including a NuGet package in your project](/visualstudio/mac/nuget-walkthrough). +```powershell +Install-Package NuGet.CommandLine -Version 4.4.1 +``` -The Package Manager Console is not included with Visual Studio Code. +After you install the `NuGet.CommandLine` package, you can run all NuGet CLI commands through the Package Manager Console. ## Extend the Package Manager Console -Some packages install new commands for the console. For example, `MvcScaffolding` creates commands like `Scaffold` shown below, which generates ASP.NET MVC controllers and views: +Some packages install new commands for the console. For example, `MvcScaffolding` creates commands like `Scaffold`, which generates ASP.NET MVC controllers and views: -![Installing and using MvcScaffold](media/PackageManagerConsoleInstall.png) +:::image type="content" source="media/PackageManagerConsoleInstall.png" alt-text="Screenshot that shows NuGet CLI commands available after installing the NuGet.CommandLine package."::: ## Set up a NuGet PowerShell profile -A PowerShell profile lets you make commonly-used commands available wherever you use PowerShell. NuGet supports a NuGet-specific profile typically found at the following location: +You can create a PowerShell profile to make your commonly-used commands available in all PowerShell contexts, so you don't lose your PowerShell settings between sessions. NuGet supports a NuGet-specific profile, usually at *%UserProfile%\Documents\WindowsPowerShell\NuGet_profile.ps1*. - %UserProfile%\Documents\WindowsPowerShell\NuGet_profile.ps1 +To find your user profile location, enter `$profile` in the console: -To find the profile, type `$profile` in the console: - -```ps +```powershell $profile C:\Users\\Documents\WindowsPowerShell\NuGet_profile.ps1 ``` -For more details, refer to [Windows PowerShell Profiles](https://technet.microsoft.com/library/bb613488.aspx). - -## Use the nuget.exe CLI in the console +To determine whether a profile exists at that location, enter `test-path $profile`. If the command returns `False`, you need to create the profile with the specified name at that location. For more information, see [Windows PowerShell Profiles](/previous-versions//bb613488(v=vs.85)). -To make the [`nuget.exe` CLI](../reference/nuget-exe-cli-reference.md) available in the Package Manager Console, install the [NuGet.CommandLine](http://www.nuget.org/packages/NuGet.CommandLine/) package from the console: +## Next steps -```ps -# Other versions are available, see http://www.nuget.org/packages/NuGet.CommandLine/ -Install-Package NuGet.CommandLine -Version 4.4.1 -``` +- [Install and manage NuGet packages with the dotnet CLI](install-use-packages-dotnet-cli.md) +- [Manage packages using the nuget.exe CLI](install-use-packages-nuget-cli.md) +- [Install and manage packages in Visual Studio using the NuGet Package Manager](install-use-packages-visual-studio.md) diff --git a/docs/consume-packages/install-use-packages-visual-studio.md b/docs/consume-packages/install-use-packages-visual-studio.md index d0e870fb1..db1eb5d54 100644 --- a/docs/consume-packages/install-use-packages-visual-studio.md +++ b/docs/consume-packages/install-use-packages-visual-studio.md @@ -1,165 +1,191 @@ --- -title: Install and manage NuGet packages in Visual Studio -description: Instructions for using the NuGet Package Manager UI in Visual Studio for working with NuGet packages. -author: karann-msft -ms.author: karann -ms.date: 07/08/2019 -ms.topic: conceptual +title: Install and manage packages in Visual Studio using the NuGet Package Manager +description: Learn how to use the NuGet Package Manager UI in Visual Studio for working with NuGet packages. +author: JonDouglas +ms.author: jodou +ms.date: 03/03/2025 +ms.topic: install-set-up-deploy f1_keywords: - - "vs.toolsoptionspages.nuget_package_manager" - - "vs.toolsoptionspages.nuget_package_manager.general" - - "vs.toolsoptionspages.nuget_package_manager.package_sources" - "vs.nuget.packagemanager.ui" --- # Install and manage packages in Visual Studio using the NuGet Package Manager -The NuGet Package Manager UI in Visual Studio on Windows allows you to easily install, uninstall, and update NuGet packages in projects and solutions. For the experience in Visual Studio for Mac, see [Including a NuGet package in your project](/visualstudio/mac/nuget-walkthrough?toc=/nuget/toc.json). The Package Manager UI is not included with Visual Studio Code. +The NuGet Package Manager UI in Microsoft Visual Studio for Windows allows you to easily install, uninstall, and update NuGet packages in projects and solutions. -> [!NOTE] -> If you're missing the NuGet Package Manager in Visual Studio 2015, check **Tools > Extensions and Updates...** and search for the *NuGet Package Manager* extension. If you're unable to use the extensions installer in Visual Studio, download the extension directly from [https://dist.nuget.org/index.html](https://dist.nuget.org/index.html). -> -> Starting in Visual Studio 2017, NuGet and the NuGet Package Manager are automatically installed with any .NET-related workloads. Install it individually by selecting the **Individual components > Code tools > NuGet package manager** option in the Visual Studio installer. +The article is for Windows users only. If you're using Visual Studio for Mac, see [Including a NuGet package in your project](/visualstudio/mac/nuget-walkthrough?toc=/nuget/toc.json). + +## Prerequisites + +- Install Visual Studio 2022 for Windows with any .NET-related workload. + + You can install the 2022 Community edition for free from [visualstudio.microsoft.com](https://visualstudio.microsoft.com/), or use the Professional or Enterprise edition. + + Visual Studio 2017 and higher automatically includes NuGet Package Manager when a .NET-related workload is installed. To install it individually in Visual Studio Installer, select the **Individual components** tab, and then select **NuGet package manager** under **Code tools** . + + For Visual Studio 2015, if you're missing the NuGet Package Manager, check **Tools** > **Extensions and Updates** and search for the *NuGet Package Manager* extension. If you're unable to use the extensions installer in Visual Studio, download the extension directly from [https://dist.nuget.org/index.html](https://dist.nuget.org/index.html). + +- [Register for a free account on nuget.org](../nuget-org/individual-accounts.md#add-a-new-individual-account) if you don't have one already. You must register and confirm the account before you can upload a NuGet package. ## Find and install a package -1. In **Solution Explorer**, right-click either **References** or a project and select **Manage NuGet Packages...**. +To find and install a NuGet package with Visual Studio, follow these steps: - ![Manage NuGet Packages menu option](media/ManagePackagesUICommand.png) +1. Load a project in **Solution Explorer**, and then select **Project** > **Manage NuGet Packages**. -1. The **Browse** tab displays packages by popularity from the currently selected source (see [package sources](#package-sources)). Search for a specific package using the search box on the upper left. Select a package from the list to display its information, which also enables the **Install** button along with a version-selection drop-down. + The **NuGet Package Manager** window opens. - ![Manage NuGet Packages Dialog Browse tab](media/Search.png) +1. Select the **Browse** tab to display packages by popularity from the currently selected source (see [Package sources](#package-sources)). -1. Select the desired version from the drop-down and select **Install**. Visual Studio installs the package and its dependencies into the project. You may be asked to accept license terms. When installation is complete, the added packages appear on the **Installed** tab. Packages are also listed in the **References** node of Solution Explorer, indicating that you can refer to them in the project with `using` statements. + - To search for a specific package, use the search box on the upper left. + - Abbreviated information may be shown beside each package ID to help identify the correct package, and varies based on the selected package source(s). + Examples include package download count, author, or owner profile hyperlinks. - ![References in Solution Explorer](media/References.png) + > [!Note] + > In Visual Studio 17.11 and higher, package owners are shown as profile hyperlinks when supported by the selected package source. + > Package ownership is defined by the package source. For example, see [Manage package owners on nuget.org](../nuget-org/publish-a-package.md#manage-package-owners-on-nugetorg). + > + > In Visual Studio 17.10 and earlier, the package *author* metadata is shown, which appears as plain-text. + > For more information, see [Authors package metadata](../create-packages/package-authoring-best-practices.md#authors). -> [!Tip] -> To include prerelease versions in the search, and to make prerelease versions available in the version drop-down, select the **Include prerelease** option. + - Select a package to see detailed package information. + The details pane on the right appears and enables you to select a version to install. + ![Screenshot showing the NuGet Package Manager window with the Browse tab, details pane, and "Package Details" tab selected.](media/package-manager-package-details.png) + You can see package metadata, information about the owner(s), author(s), license, etc., in the Package Details tab and the package README file (if it is provided by the package author) in the README tab. + ![Screenshot showing the NuGet Package Manager window with the README tab selected.](media/package-manager-package-readme.png) + +1. In the right pane, select a **Version** from the dropdown list. If you want to include prerelease versions in the **Version** list, select **Include prerelease**. + +1. To install the NuGet package, select **Install**. You might be asked to accept license terms or prompted to verify the installation. + + Visual Studio installs the package and its dependencies in the project. When installation is complete, the added packages appear on the **Installed** tab. You can also find packages in the **Dependencies** > **Packages** node of your project in **Solution Explorer**. After you install a package, you can refer to it in the project with a `using` statement. + +1. (Optional) NuGet has two formats in which a project can use packages: [PackageReference](package-references-in-project-files.md) and [packages.config](../reference/packages-config.md). To set the default format, select **Tools** > **Options**, expand **NuGet Package Manager**, select **General**, and then choose the **Default package management format**. For more information, see [Choose default package management format](package-restore.md#choose-default-package-management-format). ## Uninstall a package -1. In **Solution Explorer**, right-click either **References** or the desired project, and select **Manage NuGet Packages...**. -1. Select the **Installed** tab. -1. Select the package to uninstall (using search to filter the list if necessary) and select **Uninstall**. +To uninstall a NuGet package, follow these steps: + +1. Load a project in **Solution Explorer**, select **Project** > **Manage NuGet Packages**, and then select the **Installed** tab. - ![Uninstalling a package](media/UninstallPackage.png) +1. Select the package to uninstall in the left pane (use the **Search** box to find it, if necessary), and then select **Uninstall** from the right pane. -1. Note that the **Include prerelease** and **Package source** controls have no effect when uninstalling packages. + ![Screenshot showing the NuGet Package Manager with a package selected and its Uninstall button highlighted.](media/uninstall-package.png) ## Update a package -1. In **Solution Explorer**, right-click either **References** or the desired project, and select **Manage NuGet Packages...**. (In web site projects, right-click the **Bin** folder.) -1. Select the **Updates** tab to see packages that have available updates from the selected package sources. Select **Include prerelease** to include prerelease packages in the update list. -1. Select the package to update, select the desired version from the drop-down on the right, and select **Update**. +To update a NuGet package, follow these steps: - ![Updating a package](media/UpdatePackages.png) +1. Load a project in **Solution Explorer**, and then select **Project** > **Manage NuGet Packages**. For website projects, select the **Bin** folder first. -1. For some packages, the **Update** button is disabled and a message appears saying that it's "Implicitly referenced by an SDK" (or "AutoReferenced"). This message indicates that the package is part of a larger framework or SDK and should not be updated independently. (Such packages are internally marked with `True`.) For example, `Microsoft.NETCore.App` is part of the .NET Core SDK, and the package version is not the same as the version of the runtime framework used by the application. You need to [update your .NET Core installation](https://aka.ms/dotnet-download) to get new versions of the ASP.NET Core and .NET Core runtime. [See this document for more details on .NET Core metapackages and versioning](/dotnet/core/packages). This applies to the following commonly used packages: - * Microsoft.AspNetCore.All - * Microsoft.AspNetCore.App - * Microsoft.NETCore.App - * NETStandard.Library +1. Select the **Updates** tab to see packages that have available updates from the selected **Package source**. Select **Include prerelease** to include prerelease packages in the update list. - ![Example package marked as Implicitly references or AutoReferenced](media/PackageManagerUIAutoReferenced.png) +1. Select the package to update. On the right pane, select the desired **Version** from the dropdown list, and then select **Update**. -1. To update multiple packages to their newest versions, select them in the list and select the **Update** button above the list. -1. You can also update an individual package from the **Installed** tab. In this case, the details for the package include a version selector (subject to the **Include prerelease** option) and an **Update** button. + ![Screenshot showing the NuGet Package Manager with a package selected and its Update button highlighted.](media/update-package.png) -## Manage packages for the solution +1. For some packages, the **Update** button is disabled and the following message appears: *Implicitly referenced by an SDK. To update the package, update the SDK to which it belongs.* This message indicates that the package is part of a larger framework or SDK and can't be updated independently. Such packages are internally marked with `True`. For example, `Microsoft.NETCore.App` is part of the .NET Core SDK, and the package version is different than the version of the runtime framework used by the application. To download a new version of the .NET Core, [update your .NET Core installation](https://aka.ms/dotnet-download). For more information, see [.NET Core metapackages and versioning](/dotnet/core/packages). This scenario applies to the following commonly used packages: + - Microsoft.AspNetCore.All + - Microsoft.AspNetCore.App + - Microsoft.NETCore.App + - NETStandard.Library -Managing packages for a solution is a convenient means to work with multiple projects simultaneously. + ![Screenshot showing a NuGet package with the Update button disabled.](media/package-update-disabled.png) -1. Select the **Tools > NuGet Package Manager > Manage NuGet Packages for Solution...** menu command, or right-click the solution and select **Manage NuGet Packages...**: +1. To update multiple packages to their latest versions, choose them in the NuGet package list, and then select **Update**. - ![Manage NuGet packages for the solution](media/ManagePackagesSolutionUICommand.png) +1. You can also update an individual package from the **Installed** tab. For this case, you can also select a **Version** and the **Include prerelease** option. -1. When managing packages for the solution, the UI lets you select the projects that are affected by the operations: - - ![Project selector when managing packages for the solution](media/SolutionPackagesUI.png) +## Manage packages for the solution -### Consolidate tab +Managing packages for a solution is a convenient means to work with multiple projects simultaneously: -Developers typically consider it bad practice to use different versions of the same NuGet package across different projects in the same solution. When you choose to manage packages for a solution, the Package Manager UI provides a **Consolidate** tab on which you can easily see where packages with distinct version numbers are used by different projects in the solution: +1. Select a solution in **Solution Manager**, and then select **Tools** > **NuGet Package Manager** > **Manage NuGet Packages for Solution**. -![Package Manager UI Consolidate tab](media/ConsolidateTab.png) +1. In the **Manage NuGet Packages for Solution** window, select the projects that are affected by the operations. -In this example, the ClassLibrary1 project is using EntityFramework 6.2.0, whereas ConsoleApp1 is using EntityFramework 6.1.0. To consolidate package versions, do the following: + ![Screenshot showing the Manage Packages for Solution window with multiple projects selected.](media/manage-packages-for-solution.png) -- Select the projects to update in the project list. -- Select the version to use in all those projects in the **Version** control, such as EntityFramework 6.2.0. -- Select the **Install** button. +### Consolidate tab -The Package Manager installs the selected package version into all selected projects, after which the package no longer appears on the **Consolidate** tab. +Developers typically consider it bad practice to use different versions of the same NuGet package across different projects in the same solution. Visual Studio allows you to use a common version for your NuGet packages. To do so, use the **Consolidate** tab of the **NuGet Package Manager** window to discover where packages with distinct version numbers are used by different projects in the solution. -## Package sources +![Screenshot showing the Manage Packages for Solution window with the Consolidate tab selected.](media/consolidate-tab.png) -To change the source from which Visual Studio obtains packages, select one from the source selector: +In this example, the ClassLibrary1 project is using EntityFramework 6.2.0, whereas ConsoleApp1 is using EntityFramework 6.1.0. To consolidate package versions, follow these steps: -![Package source selector in the package manager UI](media/PackageSourceDropDown.png) +1. From the **Consolidate** tab, select the projects to update in the project list. -To manage package sources: +1. Select the version to use for all these projects in the **Version** list. -1. Select the **Settings** icon in the Package Manager UI outlined below or use the **Tools > Options** command and scroll to **NuGet Package Manager**: +1. Select **Install**. - ![Package manager UI settings icon](media/PackageSourceSettings.png) + The NuGet Package Manager installs the selected package version into all the selected projects, after which the package no longer appears on the **Consolidate** tab. -1. Select the **Package Sources** node: +## Package sources - ![Package Sources options](media/options.png) +Visual Studio ignores the order of package sources, and uses the package from whichever source is the first to respond to a request. For more information, see [Restore packages](package-restore.md). For information about how to load a package from a specific source, see [Package source mapping](package-source-mapping.md). -1. To add a source, select **+**, edit the name, enter the URL or path in the **Source** control, and select **Update**. The source now appears in the selector drop-down. -1. To change a package source, select it, make edits in the **Name** and **Source** boxes, and select **Update**. -1. To disable a package source, clear the box to the left of the name in the list. -1. To remove a package source, select it and then select the **X** button. -1. Using the up and down arrow buttons does not change the priority order of the package sources. Visual Studio ignores the order of package sources, using the package from whichever source is first to respond to requests. For more information, see [Package restore](../consume-packages/package-restore.md). +1. To change the source from which Visual Studio loads package metadata, select a source from the **Package source** selector. -> [!Tip] -> If a package source reappears after deleting it, it may be listed in a computer-level or user-level `NuGet.Config` files. See [Common NuGet configurations](../consume-packages/configuring-nuget-behavior.md) for the location of these files, then remove the source by editing the files manually or using the [nuget sources command](../reference/nuget-exe-CLI-reference.md). + ![Screenshot showing the Package source selector highlighted.](media/package-source-selector.png) -## Package manager Options control +1. To manage your package sources, select the **Settings** icon or select **Tools** > **Options**. -When a package is selected, the Package Manager UI displays a small, expandable **Options** control below the version selector (shown here both collapsed and expanded). Note that for some project types, only the **Show preview window** option is provided. + ![Screenshot showing the Package source settings icon highlighted.](media/package-source-settings.png) -![Package manager options](media/PackageManagerUIOptions.png) +1. To manage NuGet package sources, see [NuGet Options in Visual Studio](nuget-visual-studio-options.md#package-sources). -The following sections explain these options. +## NuGet Package Manager Options control -### Show preview window +When you select a package, the NuGet Package Manager displays an expandable **Options** control below the **Version** selector. For most project types, only the **Show preview window** option is provided. -When selected, a modal window displays which the dependencies of a chosen package before the package is installed: +![Screenshot showing the NuGet Package manager Options control expanded.](media/package-manager-options.png) -![Example Preview Dialog](media/InstallPreviewDialog.png) +The following sections explain the available options. -### Install and Update Options +### Install and update options -(Not available for all project types.) +These options are available only for certain project types: -**Dependency behavior** configures how NuGet decides which versions of dependent packages to install: +- **Dependency behavior**: This option configures how NuGet decides which versions of dependent packages to install. It has the following settings: -- *Ignore dependencies* skips installing any dependencies, which typically breaks the package being installed. -- *Lowest* [Default] installs the dependency with the minimal version number that meets the requirements of the primary chosen package. -- *Highest Patch* installs the version with the same major and minor version numbers, but the highest patch number. For example, if version 1.2.2 is specified then the highest version that starts with 1.2 will be installed -- *Highest Minor* installs the version with the same major version number but the highest minor number and patch number. If version 1.2.2 is specified, then the highest version that starts with 1 will be installed -- *Highest* installs the highest available version of the package. + - **Ignore dependencies** skips the installation of dependencies, which typically breaks the package being installed. + - **Lowest** [Default] installs the dependency with the minimal version number that meets the requirements of the primary chosen package. + - **Highest Patch** installs the version with the same major and minor version numbers, but the highest patch number. For example, if version 1.2.2 is specified then the highest version that starts with 1.2 will be installed + - **Highest Minor** installs the version with the same major version number but the highest minor number and patch number. If version 1.2.2 is specified, then the highest version that starts with 1 will be installed + - **Highest** installs the highest available version of the package. -**File conflict action** specifies how NuGet should handle packages that already exist in the project or local machine: +- **File conflict action**: This option specifies how NuGet should handle packages that already exist in the project or local machine. It has the following settings: -- *Prompt* instructs NuGet to ask whether to keep or overwrite existing packages. -- *Ignore All* instructs NuGet to skip overwriting any existing packages. -- *Overwrite All* instructs NuGet to overwrite any existing packages. + - **Prompt** instructs NuGet to ask whether to keep or overwrite existing packages. + - **Ignore All** instructs NuGet to skip overwriting any existing packages. + - **Overwrite All** instructs NuGet to overwrite any existing packages. -### Uninstall Options +### Uninstall options + +These options are available only for certain project types: + +- **Remove dependencies**: When selected, removes any dependent packages if they're not referenced elsewhere in the project. + +- **Force uninstall even if there are dependencies on it**: When selected, uninstalls a package even if it's still being referenced in the project. This option is typically used in combination with **Remove dependencies** to remove a package and whatever dependencies it installed. Using this option may, however, lead to broken references in the project. In such a case, you might need to [reinstall those other packages](../consume-packages/reinstalling-and-updating-packages.md). + +## Related video + +- Find NuGet videos on [Channel 9](/shows/nuget-101/) and [YouTube](https://www.youtube.com/playlist?list=PLdo4fOcmZ0oVLvfkFk8O9h6v2Dcdh2bh_). -(Not available for all project types.) +## See also -**Remove dependencies**: when selected, removes any dependent packages if they're not referenced elsewhere in the project. +For more information about NuGet, see the following articles: -**Force uninstall even if there are dependencies on it**: when selected, uninstalls a package even if it's still being referenced in the project. This is typically used in combination with **Remove dependencies** to remove a package and whatever dependencies it installed. Using this option may, however, lead to broken references in the project. In such cases, you may need to [reinstall those other packages](../consume-packages/reinstalling-and-updating-packages.md). +- [What is NuGet?](../what-is-nuget.md) +- [Package consumption workflow](overview-and-workflow.md) +- [Find and choose packages](finding-and-choosing-packages.md) +- [Package references in project files](package-references-in-project-files.md) +- [Install and use a package using the .NET CLI](../quickstart/install-and-use-a-package-using-the-dotnet-cli.md). diff --git a/docs/consume-packages/installing-signed-packages.md b/docs/consume-packages/installing-signed-packages.md index 2706438c4..ad5e83f29 100644 --- a/docs/consume-packages/installing-signed-packages.md +++ b/docs/consume-packages/installing-signed-packages.md @@ -1,10 +1,10 @@ --- title: Manage package trust boundaries description: Describes the process of installing signed NuGet packages and configuring package signature trust settings. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/29/2018 -ms.topic: conceptual +ms.topic: install-set-up-deploy --- # Manage package trust boundaries @@ -90,7 +90,7 @@ In some situations you may want to enable verification using certificates that d ### Sync repository certificates -Package repositories should announce the certificates they use in their [service index](../api/service-index.md). Eventually the repository will update these certificates, e.g. when the certificate expires. When that happens, clients with specific policies will require an update to the configuration to include the newly added certificate. You can easily upgrade the trusted signers associated to a repository by using the `nuget.exe` [trusted-signers sync command](../reference/cli-reference/cli-ref-trusted-signers.md#nuget-trusted-signers-sync--name-). +Package repositories should announce the certificates they use in their [service index](../api/service-index.md). Eventually the repository will update these certificates, e.g. when the certificate expires. When that happens, clients with specific policies will require an update to the configuration to include the newly added certificate. You can easily upgrade the trusted signers associated to a repository by using the `nuget.exe` [trusted-signers sync command](../reference/cli-reference/cli-ref-trusted-signers.md#nuget-trusted-signers-sync--name-name). ### Schema reference diff --git a/docs/consume-packages/managing-the-global-packages-and-cache-folders.md b/docs/consume-packages/managing-the-global-packages-and-cache-folders.md index d2660fae7..faac424cd 100644 --- a/docs/consume-packages/managing-the-global-packages-and-cache-folders.md +++ b/docs/consume-packages/managing-the-global-packages-and-cache-folders.md @@ -1,32 +1,80 @@ --- title: How to manage the global packages, cache, temp folders in NuGet description: How to manage the global package installation folder, the package cache, and the temp folders that exist on a computer, which are used when installing, restoring, and updating packages. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 03/19/2018 -ms.topic: conceptual +ms.topic: how-to --- # Managing the global packages, cache, and temp folders Whenever you install, update, or restore a package, NuGet manages packages and package information in several folders outside of your project structure: -| Name | Description and Location (per user)| +| Name | Location | | --- | --- | -| global‑packages | The *global-packages* folder is where NuGet installs any downloaded package. Each package is fully expanded into a subfolder that matches the package identifier and version number. Projects using the [PackageReference](package-references-in-project-files.md) format always use packages directly from this folder. When using the [packages.config](../reference/packages-config.md), packages are installed to the *global-packages* folder, then copied into the project's `packages` folder.
  • Windows: `%userprofile%\.nuget\packages`
  • Mac/Linux: `~/.nuget/packages`
  • Override using the NUGET_PACKAGES environment variable, the `globalPackagesFolder` or `repositoryPath` [configuration settings](../reference/nuget-config-file.md#config-section) (when using PackageReference and `packages.config`, respectively), or the `RestorePackagesPath` MSBuild property (MSBuild only). The environment variable takes precedence over the configuration setting.
| -| http‑cache | The Visual Studio Package Manager (NuGet 3.x+) and the `dotnet` tool store copies of downloaded packages in this cache (saved as `.dat` files), organized into subfolders for each package source. Packages are not expanded, and the cache has an expiration time of 30 minutes.
  • Windows: `%localappdata%\NuGet\v3-cache`
  • Mac/Linux: `~/.local/share/NuGet/v3-cache`
  • Override using the NUGET_HTTP_CACHE_PATH environment variable.
| -| temp | A folder where NuGet stores temporary files during its various operations.
  • Windows: `%temp%\NuGetScratch`
  • Mac/Linux: `/tmp/NuGetScratch`
    • | -| plugins-cache **4.8+** | A folder where NuGet stores the results from the operation claims request.
    • Windows: `%localappdata%\NuGet\plugins-cache`
    • Mac/Linux: `~/.local/share/NuGet/plugins-cache`
    • Override using the NUGET_PLUGINS_CACHE_PATH environment variable.
    | +| [global-packages](#global-packages) |
    • Windows: `%userprofile%\.nuget\packages`
    • Mac/Linux: `~/.nuget/packages`
    • Override using the NUGET_PACKAGES environment variable, the `globalPackagesFolder` or `repositoryPath` [configuration settings](../reference/nuget-config-file.md#config-section) (when using PackageReference and `packages.config`, respectively), or the `RestorePackagesPath` MSBuild property (MSBuild only). The environment variable takes precedence over the configuration setting.
    | +| [http-cache](#http-cache) |
    • Windows: `%localappdata%\NuGet\v3-cache`
    • Mac/Linux: `~/.local/share/NuGet/v3-cache`
    • Override using the NUGET_HTTP_CACHE_PATH environment variable.
    | +| [temp](#temp) |
  • Windows: `%temp%\NuGetScratch`
  • Mac: `/tmp/NuGetScratch`
  • Linux: `/tmp/NuGetScratch`
  • Override using the NUGET_SCRATCH environment variable.
    • | +| [plugins-cache](#plugin-cache) **4.8+** |
    • Windows: `%localappdata%\NuGet\plugins-cache`
    • Mac/Linux: `~/.local/share/NuGet/plugins-cache`
    • Override using the NUGET_PLUGINS_CACHE_PATH environment variable.
    | > [!Note] > NuGet 3.5 and earlier uses *packages-cache* instead of the *http-cache*, which is located in `%localappdata%\NuGet\Cache`. By using the cache and *global-packages* folders, NuGet generally avoids downloading packages that already exist on the computer, improving the performance of install, update, and restore operations. When using PackageReference, the *global-packages* folder also avoids keeping downloaded packages inside project folders, where they might be inadvertently added to source control, and reduces NuGet's overall impact on computer storage. -When asked to retrieve a package, NuGet first looks in the *global-packages* folder. If the exact version of package is not there, then NuGet checks all non-HTTP package sources. If the package is still not found, NuGet looks for the package in the *http-cache* unless you specify `--no-cache` with `dotnet.exe` commands or `-NoCache` with `nuget.exe` commands. If the package is not in the cache, or the cache isn't used, NuGet then retrieves the package over HTTP . +When asked to retrieve a package, NuGet first looks in the *global-packages* folder. If the exact version of package is not there, then NuGet checks all non-HTTP package sources. If the package is still not found, NuGet looks for the package in the *http-cache* unless you specify `--no-http-cache` with `dotnet.exe` commands or `-NoHttpCache` with `nuget.exe` commands. If the package is not in the cache, or the cache isn't used, NuGet then retrieves the package over HTTP . For more information, see [What happens when a package is installed?](../concepts/package-installation-process.md). +## global-packages + +The *global-packages* folder is where NuGet installs any downloaded package. +Each package is fully expanded into a subfolder that matches the package identifier and version number. +Projects using the [PackageReference](package-references-in-project-files.md) format always use packages directly from this folder. +When using the [packages.config](../reference/packages-config.md), packages are installed to the *global-packages* folder, then copied into the project's `packages` folder. + +### Cleaning the global-packages directory + +The global-packages directory needs to be manually cleaned to remove packages that are no longer used. +You can do this with the `dotnet nuget locals global-packages --clean` command, or the "clear NuGet local resources" button in Visual Studio's options (equivalent to `dotnet nuget locals all --clear`). +After clearing the global-packages directory, you will need to restore your projects again to redownload all required packages. +In Visual Studio, you may need to reload your solution to clear NuGet's "up to date restores" cache, or alternatively do a command line restore (for example, within Visual Studio's terminal window) with `msbuild -t:restore your.sln`. + +To clean only unused packages, it's a two step process. +First, there is a [nuget.config setting `updatePackageLastAccessTime`](../reference/nuget-config-file.md) that should be enabled. +This setting will cause NuGet to update each package's `.nupkg.metadata` file when it is used in a restore. +When restore runs, but a project is considered already up to date, the package timestamps are *not* updated. +The `.nupkg.metadata` file is the last file that NuGet will create when downloading and extracting packages during a restore or install, and is the file that restore uses to check if a package has been extracted successfully. + +Second, run a tool to perform the cleanup. +After the `updatePackageLastAccessTime` setting is enabled, we recommend waiting a few days to make sure that all the packages you use regularly have had their timestamps updated. + +At this time, NuGet does not provide a tool or command to do this. +You can [add a 👍 reaction to this GitHub issue](https://github.com/NuGet/Home/issues/4980) to signal your interest. +Some community members have created their own open source NuGet cleaner tools that you can search for. + +If you are going to write your own cleanup tool, it is important that the `.nupkg.metadata` file is deleted if any of the other package files are deleted, so we recommend that this file is deleted first. +Otherwise projects referencing the package may have unexpected behavior. +If writing a cleanup tool in .NET, consider using `ConcurrencyUtilities.ExecuteWithFileLocked[Async](..)` from the [NuGet.Common package](https://www.nuget.org/packages/NuGet.Common), passing the full nupkg path of the package directory you're going to delete as the key, to avoid deleting a package that restore is trying to extract at the same time. +The global packages directory can be programatically found with the [NuGet.Configuration package](https://www.nuget.org/packages/NuGet.Configuration). +Use `Settings.LoadDefaultSettings(path)` to get an `ISettings` instance (you can pass `null` as the path, or pass a directory if you want to handle solutions with a nuget.config that redirects the global-packages directory), and then use `SettingsUtility.GetGlobalPackagesFolder(settings)`. +Alternatively, you can run `dotnet nuget locals global-packages --list` as a child process and parse the output. + +## http-cache + +NuGet will cache copies of most NuGet feed communications (excluding search), organized into subfolders for each package source. +Packages are not expanded, and files with a last modified date older than 30 minutes are typically considered expired. + +## temp + +A folder where NuGet may store temporary files during its various operations. + +## plugin-cache + +A folder where NuGet stores the results from the operation claims request. +See the [cross platform plugins reference](../reference/extensibility/NuGet-Cross-Platform-Plugins.md) for more information. + ## Viewing folder locations You can view locations using the [nuget locals command](../reference/cli-reference/cli-ref-locals.md): @@ -49,11 +97,11 @@ plugins-cache: C:\Users\user1\AppData\Local\NuGet\plugins-cache You can also view folder locations using the [dotnet nuget locals command](/dotnet/core/tools/dotnet-nuget-locals): -```cli +```dotnetcli dotnet nuget locals all --list ``` -Typical output (Mac/Linux; "user1" is the current username): +Typical output (Mac; "user1" is the current username): ```output info : http-cache: /home/user1/.local/share/NuGet/v3-cache @@ -62,10 +110,21 @@ info : temp: /tmp/NuGetScratch info : plugins-cache: /home/user1/.local/share/NuGet/plugins-cache ``` +Typical output (Linux; "user1" is the current username): + +```output +info : http-cache: /home/user1/.local/share/NuGet/v3-cache +info : global-packages: /home/user1/.nuget/packages/ +info : temp: /tmp/NuGetScratchuser1 +info : plugins-cache: /home/user1/.local/share/NuGet/plugins-cache +``` + To display the location of a single folder, use `http-cache`, `global-packages`, `temp`, or `plugins-cache` instead of `all`. ## Clearing local folders +### Command-line + If you encounter package installation problems or otherwise want to ensure that you're installing packages from a remote gallery, use the `locals --clear` option (dotnet.exe) or `locals -clear` (nuget.exe), specifying the folder to clear, or `all` to clear all folders: ```cli @@ -95,19 +154,33 @@ nuget locals all -clear Any packages used by projects that are currently open in Visual Studio are not cleared from the *global-packages* folder. -Starting in Visual Studio 2017, use the **Tools > NuGet Package Manager > Package Manager Settings** menu command, then select **Clear All NuGet Cache(s)**. Managing the cache isn't presently available through the Package Manager Console. In Visual Studio 2015, use the CLI commands instead. +### Visual Studio + +Visual Studio supports clearing all local folders in the "NuGet Package Manager" options found under the **Tools > NuGet Package Manager > Package Manager Settings** menu command. + +On the General page, select **Clear NuGet local resources**. +Once started, this action cannot be cancelled. +A progress bar will be shown and will contain the final status of the command. + +The [Output Window](/visualstudio/ide/output-window) when selecting Show output from "Package Manager" will show additional details about the clear command, including any error messages. + +### Clear NuGet Local Resources + +![Clear NuGet local resources button highlighted in the General page of NuGet options](media/vsoptions/general.png) + +Managing the cache isn't presently available through the Package Manager Console. -![NuGet option command for clearing caches](media/options-clear-caches.png) +For more information, see [NuGet Options in Visual Studio](nuget-visual-studio-options.md#clear-nuget-local-resources). ## Troubleshooting errors The following errors can occur when using `nuget locals` or `dotnet nuget locals`: -- *Error: The process cannot access the file because it is being used by another process* or *Clearing local resources failed: Unable to delete one or more files* +- *Error: The process cannot access the file \ because it is being used by another process* or *Clearing local resources failed: Unable to delete one or more files* One or more files in the folder are in use by another process; for example, a Visual Studio project is open that refers to packages in the *global-packages* folder. Close those processes and try again. -- *Error: Access to the path is denied* or *The directory is not empty* +- *Error: Access to the path \ is denied* or *The directory is not empty* You don't have permission to delete files in the cache. Change the folder permissions, if possible, and try again. Otherwise, contact your system administrator. diff --git a/docs/consume-packages/media/Finding-01-Popularity.png b/docs/consume-packages/media/Finding-01-Popularity.png index 06fbfc690..d50fbecf5 100644 Binary files a/docs/consume-packages/media/Finding-01-Popularity.png and b/docs/consume-packages/media/Finding-01-Popularity.png differ diff --git a/docs/consume-packages/media/Finding-02-SearchResults.png b/docs/consume-packages/media/Finding-02-SearchResults.png index 5e0d72df8..8563e48ac 100644 Binary files a/docs/consume-packages/media/Finding-02-SearchResults.png and b/docs/consume-packages/media/Finding-02-SearchResults.png differ diff --git a/docs/consume-packages/media/Finding-03-Downloads.png b/docs/consume-packages/media/Finding-03-Downloads.png index 0bca8f786..7cdd4b5e9 100644 Binary files a/docs/consume-packages/media/Finding-03-Downloads.png and b/docs/consume-packages/media/Finding-03-Downloads.png differ diff --git a/docs/consume-packages/media/Finding-04-VersionHistory.png b/docs/consume-packages/media/Finding-04-VersionHistory.png index 1a2cdf8bc..f03adbe65 100644 Binary files a/docs/consume-packages/media/Finding-04-VersionHistory.png and b/docs/consume-packages/media/Finding-04-VersionHistory.png differ diff --git a/docs/consume-packages/media/Finding-05-OperationChart.png b/docs/consume-packages/media/Finding-05-OperationChart.png deleted file mode 100644 index 6258d2830..000000000 Binary files a/docs/consume-packages/media/Finding-05-OperationChart.png and /dev/null differ diff --git a/docs/consume-packages/media/Finding-06-include-prerelease.png b/docs/consume-packages/media/Finding-06-include-prerelease.png index 3b6734714..0befb604f 100644 Binary files a/docs/consume-packages/media/Finding-06-include-prerelease.png and b/docs/consume-packages/media/Finding-06-include-prerelease.png differ diff --git a/docs/consume-packages/media/Finding-07-MostPopular.png b/docs/consume-packages/media/Finding-07-MostPopular.png new file mode 100644 index 000000000..ac05cde3d Binary files /dev/null and b/docs/consume-packages/media/Finding-07-MostPopular.png differ diff --git a/docs/consume-packages/media/Finding-08-FiltersAndSorts.png b/docs/consume-packages/media/Finding-08-FiltersAndSorts.png new file mode 100644 index 000000000..3f4ef4dfd Binary files /dev/null and b/docs/consume-packages/media/Finding-08-FiltersAndSorts.png differ diff --git a/docs/consume-packages/media/Finding-09-FrameworkFilterPanel.png b/docs/consume-packages/media/Finding-09-FrameworkFilterPanel.png new file mode 100644 index 000000000..e8a2ba20a Binary files /dev/null and b/docs/consume-packages/media/Finding-09-FrameworkFilterPanel.png differ diff --git a/docs/consume-packages/media/Finding-10-FrameworkBadgesInSearch.png b/docs/consume-packages/media/Finding-10-FrameworkBadgesInSearch.png new file mode 100644 index 000000000..fd8703fe3 Binary files /dev/null and b/docs/consume-packages/media/Finding-10-FrameworkBadgesInSearch.png differ diff --git a/docs/consume-packages/media/Options.png b/docs/consume-packages/media/Options.png deleted file mode 100644 index 20d91f19e..000000000 Binary files a/docs/consume-packages/media/Options.png and /dev/null differ diff --git a/docs/consume-packages/media/Package-Pattern-Examples.png b/docs/consume-packages/media/Package-Pattern-Examples.png new file mode 100644 index 000000000..3a9e81b6f Binary files /dev/null and b/docs/consume-packages/media/Package-Pattern-Examples.png differ diff --git a/docs/consume-packages/media/PackageManagerConsoleControls.png b/docs/consume-packages/media/PackageManagerConsoleControls.png deleted file mode 100644 index aed369a18..000000000 Binary files a/docs/consume-packages/media/PackageManagerConsoleControls.png and /dev/null differ diff --git a/docs/consume-packages/media/PackageManagerConsoleInstall.png b/docs/consume-packages/media/PackageManagerConsoleInstall.png index 716e941e0..dbb5f979e 100644 Binary files a/docs/consume-packages/media/PackageManagerConsoleInstall.png and b/docs/consume-packages/media/PackageManagerConsoleInstall.png differ diff --git a/docs/consume-packages/media/Restore-01-AutoRestoreOptions.png b/docs/consume-packages/media/Restore-01-AutoRestoreOptions.png deleted file mode 100644 index 1e5f04321..000000000 Binary files a/docs/consume-packages/media/Restore-01-AutoRestoreOptions.png and /dev/null differ diff --git a/docs/consume-packages/media/Restore-02-VSTSBuild.png b/docs/consume-packages/media/Restore-02-VSTSBuild.png deleted file mode 100644 index 2b66a9f3a..000000000 Binary files a/docs/consume-packages/media/Restore-02-VSTSBuild.png and /dev/null differ diff --git a/docs/consume-packages/media/Symbols_01-AddingSource.png b/docs/consume-packages/media/Symbols_01-AddingSource.png deleted file mode 100644 index 7d5960461..000000000 Binary files a/docs/consume-packages/media/Symbols_01-AddingSource.png and /dev/null differ diff --git a/docs/consume-packages/media/Used-By-section-Humanizer.png b/docs/consume-packages/media/Used-By-section-Humanizer.png new file mode 100644 index 000000000..594658790 Binary files /dev/null and b/docs/consume-packages/media/Used-By-section-Humanizer.png differ diff --git a/docs/consume-packages/media/ConsolidateTab.png b/docs/consume-packages/media/consolidate-tab.png similarity index 100% rename from docs/consume-packages/media/ConsolidateTab.png rename to docs/consume-packages/media/consolidate-tab.png diff --git a/docs/consume-packages/media/SolutionPackagesUI.png b/docs/consume-packages/media/manage-packages-for-solution.png similarity index 100% rename from docs/consume-packages/media/SolutionPackagesUI.png rename to docs/consume-packages/media/manage-packages-for-solution.png diff --git a/docs/consume-packages/media/options-clear-caches.png b/docs/consume-packages/media/options-clear-caches.png deleted file mode 100644 index 0a99c9b38..000000000 Binary files a/docs/consume-packages/media/options-clear-caches.png and /dev/null differ diff --git a/docs/consume-packages/media/package-manager-browse-tab.png b/docs/consume-packages/media/package-manager-browse-tab.png new file mode 100644 index 000000000..d48ddbd1b Binary files /dev/null and b/docs/consume-packages/media/package-manager-browse-tab.png differ diff --git a/docs/consume-packages/media/package-manager-install-tab.png b/docs/consume-packages/media/package-manager-install-tab.png new file mode 100644 index 000000000..253bf15f5 Binary files /dev/null and b/docs/consume-packages/media/package-manager-install-tab.png differ diff --git a/docs/consume-packages/media/PackageManagerUIOptions.png b/docs/consume-packages/media/package-manager-options.png similarity index 100% rename from docs/consume-packages/media/PackageManagerUIOptions.png rename to docs/consume-packages/media/package-manager-options.png diff --git a/docs/consume-packages/media/package-manager-package-details.png b/docs/consume-packages/media/package-manager-package-details.png new file mode 100644 index 000000000..4ec7cc9a7 Binary files /dev/null and b/docs/consume-packages/media/package-manager-package-details.png differ diff --git a/docs/consume-packages/media/package-manager-package-readme.png b/docs/consume-packages/media/package-manager-package-readme.png new file mode 100644 index 000000000..855595145 Binary files /dev/null and b/docs/consume-packages/media/package-manager-package-readme.png differ diff --git a/docs/consume-packages/media/PackageSourceDropDown.png b/docs/consume-packages/media/package-source-selector.png similarity index 100% rename from docs/consume-packages/media/PackageSourceDropDown.png rename to docs/consume-packages/media/package-source-selector.png diff --git a/docs/consume-packages/media/PackageSourceSettings.png b/docs/consume-packages/media/package-source-settings.png similarity index 100% rename from docs/consume-packages/media/PackageSourceSettings.png rename to docs/consume-packages/media/package-source-settings.png diff --git a/docs/consume-packages/media/PackageManagerUIAutoReferenced.png b/docs/consume-packages/media/package-update-disabled.png similarity index 100% rename from docs/consume-packages/media/PackageManagerUIAutoReferenced.png rename to docs/consume-packages/media/package-update-disabled.png diff --git a/docs/consume-packages/media/packageSourceMapping_PMUI_Status_Mapped.png b/docs/consume-packages/media/packageSourceMapping_PMUI_Status_Mapped.png new file mode 100644 index 000000000..e27bf3920 Binary files /dev/null and b/docs/consume-packages/media/packageSourceMapping_PMUI_Status_Mapped.png differ diff --git a/docs/consume-packages/media/packageSourceMapping_PMUI_Status_Off_Annotated.png b/docs/consume-packages/media/packageSourceMapping_PMUI_Status_Off_Annotated.png new file mode 100644 index 000000000..c2d698f20 Binary files /dev/null and b/docs/consume-packages/media/packageSourceMapping_PMUI_Status_Off_Annotated.png differ diff --git a/docs/consume-packages/media/prefix-reserved.png b/docs/consume-packages/media/prefix-reserved.png new file mode 100644 index 000000000..8396d40e0 Binary files /dev/null and b/docs/consume-packages/media/prefix-reserved.png differ diff --git a/docs/consume-packages/media/right-column.png b/docs/consume-packages/media/right-column.png new file mode 100644 index 000000000..453d7419a Binary files /dev/null and b/docs/consume-packages/media/right-column.png differ diff --git a/docs/consume-packages/media/supported-frameworks.png b/docs/consume-packages/media/supported-frameworks.png new file mode 100644 index 000000000..22be75e34 Binary files /dev/null and b/docs/consume-packages/media/supported-frameworks.png differ diff --git a/docs/consume-packages/media/UninstallPackage.png b/docs/consume-packages/media/uninstall-package.png similarity index 100% rename from docs/consume-packages/media/UninstallPackage.png rename to docs/consume-packages/media/uninstall-package.png diff --git a/docs/consume-packages/media/UpdatePackages.png b/docs/consume-packages/media/update-package.png similarity index 100% rename from docs/consume-packages/media/UpdatePackages.png rename to docs/consume-packages/media/update-package.png diff --git a/docs/consume-packages/media/vsoptions/configuration-files.png b/docs/consume-packages/media/vsoptions/configuration-files.png new file mode 100644 index 000000000..73d576337 Binary files /dev/null and b/docs/consume-packages/media/vsoptions/configuration-files.png differ diff --git a/docs/consume-packages/media/vsoptions/general.png b/docs/consume-packages/media/vsoptions/general.png new file mode 100644 index 000000000..debce051c Binary files /dev/null and b/docs/consume-packages/media/vsoptions/general.png differ diff --git a/docs/consume-packages/media/vsoptions/package-source-add.png b/docs/consume-packages/media/vsoptions/package-source-add.png new file mode 100644 index 000000000..69113b750 Binary files /dev/null and b/docs/consume-packages/media/vsoptions/package-source-add.png differ diff --git a/docs/consume-packages/media/vsoptions/package-source-http-error.png b/docs/consume-packages/media/vsoptions/package-source-http-error.png new file mode 100644 index 000000000..9ce2f2722 Binary files /dev/null and b/docs/consume-packages/media/vsoptions/package-source-http-error.png differ diff --git a/docs/consume-packages/media/vsoptions/package-source-http-warn.png b/docs/consume-packages/media/vsoptions/package-source-http-warn.png new file mode 100644 index 000000000..f1a4569d4 Binary files /dev/null and b/docs/consume-packages/media/vsoptions/package-source-http-warn.png differ diff --git a/docs/consume-packages/media/vsoptions/package-source-machine-wide.png b/docs/consume-packages/media/vsoptions/package-source-machine-wide.png new file mode 100644 index 000000000..aae8df7eb Binary files /dev/null and b/docs/consume-packages/media/vsoptions/package-source-machine-wide.png differ diff --git a/docs/consume-packages/media/vsoptions/package-source-mapping-add.png b/docs/consume-packages/media/vsoptions/package-source-mapping-add.png new file mode 100644 index 000000000..7c9fc5183 Binary files /dev/null and b/docs/consume-packages/media/vsoptions/package-source-mapping-add.png differ diff --git a/docs/consume-packages/media/vsoptions/package-source-mapping-missing-source.png b/docs/consume-packages/media/vsoptions/package-source-mapping-missing-source.png new file mode 100644 index 000000000..120c2374b Binary files /dev/null and b/docs/consume-packages/media/vsoptions/package-source-mapping-missing-source.png differ diff --git a/docs/consume-packages/media/vsoptions/package-source-mapping.png b/docs/consume-packages/media/vsoptions/package-source-mapping.png new file mode 100644 index 000000000..eb4c24d0b Binary files /dev/null and b/docs/consume-packages/media/vsoptions/package-source-mapping.png differ diff --git a/docs/consume-packages/media/vsoptions/package-sources-page.png b/docs/consume-packages/media/vsoptions/package-sources-page.png new file mode 100644 index 000000000..8edf71c39 Binary files /dev/null and b/docs/consume-packages/media/vsoptions/package-sources-page.png differ diff --git a/docs/consume-packages/migrate-packages-config-to-package-reference.md b/docs/consume-packages/migrate-packages-config-to-package-reference.md index f9f56fffb..1bb9a436f 100644 --- a/docs/consume-packages/migrate-packages-config-to-package-reference.md +++ b/docs/consume-packages/migrate-packages-config-to-package-reference.md @@ -1,10 +1,10 @@ --- -title: Migrating from package.config to PackageReference formats -description: Details on how to migrate a project from the package.config management format to PackageReference as supported by NuGet 4.0+ and VS2017 and .NET Core 2.0 -author: karann-msft -ms.author: karann -ms.date: 05/24/2019 -ms.topic: conceptual +title: Migrating from packages.config to PackageReference formats +description: Details on how to migrate a project from the packages.config management format to PackageReference as supported by NuGet 4.0+ and VS2017 and .NET Core 2.0 +author: JonDouglas +ms.author: jodou +ms.date: 08/23/2021 +ms.topic: upgrade-and-migration-article --- # Migrate from packages.config to PackageReference @@ -17,7 +17,7 @@ Visual Studio 2017 Version 15.7 and later supports migrating a project from the * **Uncluttered view of top-level dependencies**: Unlike packages.config, PackageReference lists only those NuGet packages you directly installed in the project. As a result, the NuGet Package Manager UI and the project file aren't cluttered with down-level dependencies. * **Performance improvements**: When using PackageReference, packages are maintained in the *global-packages* folder (as described on [Managing the global packages and cache folders](../consume-packages/managing-the-global-packages-and-cache-folders.md) rather than in a `packages` folder within the solution. As a result, PackageReference performs faster and consumes less disk space. * **Fine control over dependencies and content flow**: Using the existing features of MSBuild allows you to [conditionally reference a NuGet package](../consume-packages/Package-References-in-Project-Files.md#adding-a-packagereference-condition) and choose package references per target framework, configuration, platform, or other pivots. -* **PackageReference is under active development**: See [PackageReference issues on GitHub](https://aka.ms/nuget-pr-improvements). packages.config is no longer under active development. + ### Limitations @@ -25,6 +25,8 @@ Visual Studio 2017 Version 15.7 and later supports migrating a project from the * Migration is not currently available for C++ and ASP.NET projects. * Some packages may not be fully compatible with PackageReference. For more information, see [package compatibility issues](#package-compatibility-issues). +In addition, there are some differences in how PackageReferences work compared to packages.config. For example, [Constraints on upgrade versions](../consume-packages/reinstalling-and-updating-packages.md#constraints-on-upgrade-versions) is not supported by PackageReference, but PackageReference adds support for [Floating Versions](../consume-packages/package-references-in-project-files.md#floating-versions). + ### Known Issues 1. The `Migrate packages.config to PackageReference...` option is not available in the right-click context menu @@ -85,7 +87,9 @@ You should now be able to see the migration option. Note that this option is not ## Create a package after migration -Once the migration is complete, we recommend that you add a reference to the [nuget.build.tasks.pack](https://www.nuget.org/packages/nuget.build.tasks.pack) nuget package, and then use [msbuild -t:pack](../reference/msbuild-targets.md#pack-target) to create the package. Although in some scenarios you could use `dotnet.exe pack` instead of `msbuild -t:pack`, it is not recommended. +Once the migration is complete, we recommend that you copy your package metadata from a `.nuspec` file to [MSBuild properties](../reference/msbuild-targets.md#pack-target), and then you can use `msbuild -t:pack` to create the package. +If you are using Visual Studio 2022 or earlier, you will also need to install the NuGet.Build.Tasks.Pack package. +From Visual Studio 2026, pack is built into MSBuild. ## Package compatibility issues @@ -93,31 +97,27 @@ Some aspects that were supported in packages.config are not supported in Package ### "install.ps1" scripts are ignored when the package is installed after the migration -| | | -| --- | --- | -| **Description** | With PackageReference, install.ps1 and uninstall.ps1 PowerShell scripts are not executed while installing or uninstalling a package. | -| **Potential impact** | Packages that depend on these scripts to configure some behavior in the destination project might not work as expected. | +* **Description**: With PackageReference, install.ps1 and uninstall.ps1 PowerShell scripts are not executed while installing or uninstalling a package. + +* **Potential impact**: Packages that depend on these scripts to configure some behavior in the destination project might not work as expected. ### "content" assets are not available when the package is installed after the migration -| | | -| --- | --- | -| **Description** | Assets in a package's `content` folder are not supported with PackageReference and are ignored. PackageReference adds support for `contentFiles` to have better transitive support and shared content. | -| **Potential impact** | Assets in `content` are not copied into the project and project code that depends on the presence of those assets requires refactoring. | +* **Description**: Assets in a package's `content` folder are not supported with PackageReference and are ignored. PackageReference adds support for `contentFiles` to have better transitive support and shared content. + +* **Potential impact**: Assets in `content` are not copied into the project and project code that depends on the presence of those assets requires refactoring. ### XDT transforms are not applied when the package is installed after the upgrade -| | | -| --- | --- | -| **Description** | XDT transforms are not supported with PackageReference and `.xdt` files are ignored when installing or uninstalling a package. | -| **Potential impact** | XDT transforms are not applied to any project XML files, most commonly, `web.config.install.xdt` and `web.config.uninstall.xdt`, which means the project's` web.config` file is not updated when the package is installed or uninstalled. | +* **Description**: XDT transforms are not supported with PackageReference and `.xdt` files are ignored when installing or uninstalling a package. + +* **Potential impact**: XDT transforms are not applied to any project XML files, most commonly, `web.config.install.xdt` and `web.config.uninstall.xdt`, which means the project's `web.config` file is not updated when the package is installed or uninstalled. ### Assemblies in the lib root are ignored when the package is installed after the migration -| | | -| --- | --- | -| **Description** | With PackageReference, assemblies present at the root of `lib` folder without a target framework specific sub-folder are ignored. NuGet looks for a sub-folder matching the target framework moniker (TFM) corresponding to the project’s target framework and installs the matching assemblies into the project. | -| **Potential impact** | Packages that do not have a sub-folder matching the target framework moniker (TFM) corresponding to the project’s target framework may not behave as expected after the transition or fail installation during the migration | +* **Description**: With PackageReference, assemblies present at the root of `lib` folder without a target framework specific sub-folder are ignored. NuGet looks for a sub-folder matching the target framework moniker (TFM) corresponding to the project’s target framework and installs the matching assemblies into the project. + +* **Potential impact**: Packages that do not have a sub-folder matching the target framework moniker (TFM) corresponding to the project’s target framework may not behave as expected after the transition or fail installation during the migration. ## Found an issue? Report it! diff --git a/docs/consume-packages/nuget-https-everywhere.md b/docs/consume-packages/nuget-https-everywhere.md new file mode 100644 index 000000000..47c97e01d --- /dev/null +++ b/docs/consume-packages/nuget-https-everywhere.md @@ -0,0 +1,97 @@ +--- +title: NuGet HTTPS Everywhere +description: Learn why NuGet enforces HTTPS connections for package sources, what errors like NU1302 mean, and how to safely allow HTTP feeds when necessary. +author: Nigusu-Allehu +ms.author: nyenework +ms.date: 10/28/2025 +ms.topic: conceptual +ai-usage: ai-generated +--- + +# NuGet HTTPS Everywhere + +NuGet requires all package sources to use **HTTPS** instead of **HTTP**. +This enforcement protects the software supply chain by preventing tampering and interception during package restore and related operations. +NuGet enforces this requirement by producing an error and stopping the operation when an HTTP source is used. + +## Understanding the HTTP Error + +This error occurs when one or more package sources in your configuration use an **HTTP** URL instead of **HTTPS**. + +In earlier NuGet versions, this scenario produced a **warning** ([`NU1803`](../reference/errors-and-warnings/nu1803.md)). +Beginning with [**NuGet 6.12**](../release-notes/NuGet-6.12.md) and later, it now results in an **error** unless the use of HTTP sources is explicitly permitted. + +### Recommended Resolution + +Before allowing HTTP connections, confirm whether your package source supports HTTPS. +If it does, update the feed URL to use the secure protocol: + +```xml + +``` + +Switching to HTTPS ensures end-to-end encryption and is the recommended and more secure approach. + +### Allowing Insecure HTTP Feeds (Opt-Out) + +If HTTPS is not available and you operate in a trusted or isolated environment, you can explicitly allow HTTP sources. + +#### Option 1: Set allowInsecureConnections in your `NuGet.Config` + +* **Use Visual Studio** + + Enable or disable allowing insecure HTTP connections with the [Package Sources settings](/nuget/consume-packages/nuget-visual-studio-options#allow-insecure-connections) under the Visual Studio options > **NuGet Package Manager**. + +* **Edit `NuGet.Config` manually** + + Add the `allowInsecureConnections="true"` attribute to the affected source: + + ```xml + + + + + + + ``` + +#### Option 2: Use the Command-Line Parameter + +For commands that support it, include the following flag to temporarily permit HTTP connections: + +For **dotnet** commands: + +```bash +--allow-insecure-connections +``` + +For **NuGet.exe** commands, use: + +```powershell +-AllowInsecureConnections +``` + +#### Commands that support opt-out options + +| Tool | Commands | Support for Allow Insecure Connection | +| -------------- | ------------------------- | ------------------------------------- | +| **nuget.exe** | `push` | NuGet **7.0** | +| **dotnet CLI** | `dotnet nuget push` | .NET **10.0.1xx** and newer | +| **dotnet CLI** | `dotnet nuget add source` | .NET **9.0.1xx** and newer | + +## HTTPS Enforcement Rollout Across Tools + +NuGet’s HTTPS enforcement was introduced gradually across releases. +The following table summarizes the progression from [**warnings (NU1803)**](../reference/errors-and-warnings/nu1803.md) to [**errors (NU1302)**](../reference/errors-and-warnings/nu1302.md). + +| Versions Affected | Behavior | +| ----------------------------------------------------- | --------------------------------------------------------------------- | +| [NuGet.exe 6.3](../release-notes/NuGet-6.3.md)+, Visual Studio 17.3+, .NET 6.0.100+ | ⚠️ **Warning (NU1803)** – HTTP sources allowed but discouraged | +| [NuGet.exe 6.12](../release-notes/NuGet-6.12.md)+, Visual Studio 17.12+, .NET 9.0.100+ | ❌ **Error (NU1302)** – HTTP sources blocked unless explicitly allowed| + +## See Also + +* [NU1302](../reference/errors-and-warnings/nu1302.md) +* [NU1803](../reference/errors-and-warnings/nu1803.md) +* [NuGet.Config Reference](../reference/nuget-config-file.md#packagesources) +* [NuGet Visual Studio Options](../consume-packages/nuget-visual-studio-options.md) diff --git a/docs/consume-packages/nuget-visual-studio-options.md b/docs/consume-packages/nuget-visual-studio-options.md new file mode 100644 index 000000000..b773e33e8 --- /dev/null +++ b/docs/consume-packages/nuget-visual-studio-options.md @@ -0,0 +1,161 @@ +--- +title: NuGet Options in Visual Studio +description: Reference guide for NuGet Package Manager options in Visual Studio, including General, Configuration Files, Package Sources, and Package Source Mapping settings. +author: donnie-msft +ms.author: eagoodso +ms.date: 10/03/2025 +ms.topic: reference +f1_keywords: + - "vs.toolsoptionspages.nuget_package_manager" + - "vs.toolsoptionspages.nuget_package_manager.general" + - "vs.toolsoptionspages.nuget_package_manager.configuration_files" + - "vs.toolsoptionspages.nuget_package_manager.package_sources" + - "vs.toolsoptionspages.nuget_package_manager.package_source_mapping" +--- + +# NuGet Package Manager Options in Visual Studio + +Visual Studio provides several options pages for configuring NuGet Package Manager behavior. +Configuration settings for NuGet are stored in your [NuGet.Config file(s)](../reference/nuget-config-file.md). + +## Accessing NuGet Options + +There are multiple ways to access NuGet Package Manager options: + +1. **From the main menu**: Go to **Tools > Options**, then expand **NuGet Package Manager** in the left pane. +1. **From the NuGet menu** found under the **Tools > NuGet Package Manager > Package Manager Settings** menu command. +1. **Quick search**: Use [Visual Studio search](/visualstudio/ide/visual-studio-search) to search for "NuGet" or a NuGet-related setting name to quickly jump to its Options page. +1. **From Package Manager UI**: Press the settings (gear) icon in the Package Manager UI toolbar. +1. **From Package Manager Console**: Click the settings (gear) icon in the Package Manager Console toolbar. + +## General + +The General options page contains settings that control NuGet's package management behavior. + +![Clear NuGet local resources button highlighted in the General page of NuGet options](media/vsoptions/general.png) + +### Package Restore + +Settings for automatic package restore during build operations: + +- **Allow NuGet to download missing packages**: Select to enable package restore and the Restore NuGet Packages command. +- **Automatically check for missing packages during build in Visual Studio**: Select to automatically restore any missing packages when you run a build from Visual Studio. + +See [Package Restore](Package-Restore.md) for more information on package restore behavior. + +### Binding Redirects + +- **Skip applying binding redirects**: When enabled, NuGet will not automatically add or update binding redirects in app.config or web.config files during package installation or updates + +### Package Management + +- **Default package management format**: Choose between the NuGet formats [PackageReference](package-references-in-project-files.md) (recommended for most projects) and [packages.config](../reference/packages-config.md) (legacy format for older projects). + For more information, see [Choose default package management format](package-restore.md#choose-default-package-management-format). + + - **PackageReference**: Stores package references directly in project files. This is the modern format that supports better dependency resolution and is required for SDK-style projects + - **packages.config**: Legacy XML file format that stores package information separately from the project file + +- **Prompt for format selection on first package install**: When enabled, Visual Studio will ask you to choose between PackageReference and packages.config the first time you install a package in a project that doesn't already have packages. + +### Clear NuGet Local Resources + +The **Clear NuGet Local Resources** command button allows you to clear NuGet's local caches, including: + +- **http-cache**: Downloaded package metadata and packages +- **global-packages**: Installed packages folder +- **temp**: Temporary files +- **plugins-cache**: Plugin operation results + +For more information on NuGet caches and folders, see [Managing the global packages, cache, and temp folders](managing-the-global-packages-and-cache-folders.md). + +## Configuration Files + +The Configuration Files options page displays the NuGet.Config files that apply to your current solution and allows you to open them directly in Visual Studio for editing. + +To edit a file, select a File Path and press the "Open" button. +The file will open in a new tab in Visual Studio where it may be edited directly. + +![Configuration files page of NuGet options with the Open button highlighted](media/vsoptions/configuration-files.png) + +Configuration files are listed in order from highest to lowest priority. +NuGet uses a hierarchical configuration system where settings from multiple config files are merged. +For more information, see [Common NuGet configurations](configuring-nuget-behavior.md). + +## Package Sources + +The Package Sources options page allows you to manage the sources from which NuGet downloads packages. + +![Package Sources page of NuGet options](media/vsoptions/package-sources-page.png) + +### Managing Package Sources + +Lists all configured package sources according to your NuGet.Config files. + +- **Name**: Display name for the source +- **Source**: URL or file path for the package source +- **Enabled checkbox**: Enable or disable a source without removing it. +- **Allow Insecure Connections**: Enable or disable allowing insecure HTTP connections + +To modify, use the **Add, Edit, and Remove buttons** below the table. +Checkboxes may be toggled directly in the table. +Press "Save" on the Add/Edit dialog and the changes will be updated in the relevant NuGet.Config file. + +![Add dialog on the Package Sources page](media/vsoptions/package-source-add.png) + +### Machine-wide Package Sources + +Package sources defined at the machine level appear in a dedicated section below. +These are generally provisioned by Visual Studio workloads and can only be enabled or disabled using the checkbox in the Enabled column. + +![Machine-wide sources table on the Package Sources page](media/vsoptions/package-source-machine-wide.png) + +### Allow Insecure Connections + +For security reasons, NuGet enforces the use of HTTPS sources by default. +If you need to use an HTTP source, you must explicitly allow it. +When an HTTP source is used, the first column of the Package Sources table will show an icon with information about a warning or an error with the package source in that row. + +⚠️ When an HTTP package source is used and Allow Insecure Connections is enabled, a warning is shown in the leftmost status column: + +> HTTP sources are insecure. Consider using HTTPS instead. 'AllowInsecureConnections' is enabled, permitting HTTP access. + +![Package Sources page with an HTTP source Warning and Allow Insecure Connections enabled](media/vsoptions/package-source-http-warn.png) + +❌ When an HTTP source is used and Allow Insecure Connections is disabled, an error is shown in the leftmost status column and NuGet restore will fail: + +> NuGet requires HTTPS sources. To use an HTTP source, you must explicitly set 'allowInsecureConnections' to true in your NuGet.Config file. + +![Package Sources page with an HTTP source Error and Allow Insecure Connections disabled](media/vsoptions/package-source-http-error.png) + +For more information on configuring HTTP source permissions, see . + +## Package Source Mapping + +Package Source Mapping allows you to control which package sources are used for specific packages, improving supply chain security. + +![Package Source Mapping page of NuGet options](media/vsoptions//package-source-mapping.png) + +To modify, use the **Add, Edit, and Remove buttons** below the table. + +### Managing Package Source Mappings + +Lists all configured package source mappings according to your NuGet.Config files. + +- **Package pattern**: Package pattern that is currently mapped (e.g., `Microsoft.*` or `Contoso.Contracts`) +- **Source**: One or more package sources mapped to the package pattern. + Package sources must be enabled to be shown. + +To modify, use the **Add, Edit, and Remove buttons** below the table. +Press "Save" on the Add/Edit dialog and the changes will be updated in the relevant NuGet.Config file. + +![Package Source Mapping add dialog](media/vsoptions/package-source-mapping-add.png) + +For more information, see [Package Source Mapping](Package-Source-Mapping.md). + +### Invalid Source Mappings + +If a package source listed in your existing source mapping isn't enabled in your NuGet.Config file(s), an error will appear in the leftmost column. + +Make sure all Source values in your mappings refer to package sources that are both available and enabled. Otherwise, the mapping may not work as expected. + +![Package Source Mapping with an invalid package source](media/vsoptions/package-source-mapping-missing-source.png) diff --git a/docs/create-packages/Creating-Localized-Packages.md b/docs/create-packages/Creating-Localized-Packages.md index 8bdd9dd20..92f7e6d15 100644 --- a/docs/create-packages/Creating-Localized-Packages.md +++ b/docs/create-packages/Creating-Localized-Packages.md @@ -1,10 +1,10 @@ --- title: How to Create a Localized NuGet Package description: Details on the two ways to create localized NuGet packages, either by including all assemblies in a single package or publishing separate assemblies. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 -ms.topic: conceptual +ms.topic: how-to --- # Creating localized NuGet packages @@ -22,34 +22,36 @@ Including localized resource assemblies in a single package is typically the sim For example, the following folder structure supports, German (de), Italian (it), Japanese (ja), Russian (ru), Chinese (Simplified) (zh-Hans), and Chinese (Traditional) (zh-Hant): - lib - └───net40 - │ Contoso.Utilities.dll - │ Contoso.Utilities.xml - │ - ├───de - │ Contoso.Utilities.resources.dll - │ Contoso.Utilities.xml - │ - ├───it - │ Contoso.Utilities.resources.dll - │ Contoso.Utilities.xml - │ - ├───ja - │ Contoso.Utilities.resources.dll - │ Contoso.Utilities.xml - │ - ├───ru - │ Contoso.Utilities.resources.dll - │ Contoso.Utilities.xml - │ - ├───zh-Hans - │ Contoso.Utilities.resources.dll - │ Contoso.Utilities.xml - │ - └───zh-Hant - Contoso.Utilities.resources.dll - Contoso.Utilities.xml +``` +lib +└───net40 + │ Contoso.Utilities.dll + │ Contoso.Utilities.xml + │ + ├───de + │ Contoso.Utilities.resources.dll + │ Contoso.Utilities.xml + │ + ├───it + │ Contoso.Utilities.resources.dll + │ Contoso.Utilities.xml + │ + ├───ja + │ Contoso.Utilities.resources.dll + │ Contoso.Utilities.xml + │ + ├───ru + │ Contoso.Utilities.resources.dll + │ Contoso.Utilities.xml + │ + ├───zh-Hans + │ Contoso.Utilities.resources.dll + │ Contoso.Utilities.xml + │ + └───zh-Hant + Contoso.Utilities.resources.dll + Contoso.Utilities.xml +``` You can see that the languages are all listed underneath the `net40` target framework folder. If you're [supporting multiple frameworks](../create-packages/supporting-multiple-target-frameworks.md), then you have a folder under `lib` for each variant. @@ -66,7 +68,7 @@ With these folders in place, you then reference all the files in your `.nuspec`: ``` -One example package that uses this approach is [Microsoft.Data.OData 5.4.0](http://nuget.org/packages/Microsoft.Data.OData/5.4.0). +One example package that uses this approach is [Microsoft.Data.OData 5.4.0](https://nuget.org/packages/Microsoft.Data.OData/5.4.0). ### Advantages and disadvantages (localized resource assemblies) @@ -87,10 +89,12 @@ Similar to how .NET Framework supports satellite assemblies, this method separat Do to this, your primary package uses the naming convention `{identifier}.{version}.nupkg` and contains the assembly for the default language (such as en-US). For example, `ContosoUtilities.1.0.0.nupkg` would contain the following structure: - lib - └───net40 - ContosoUtilities.dll - ContosoUtilities.xml +``` +lib +└───net40 + ContosoUtilities.dll + ContosoUtilities.xml +``` A satellite assembly then uses the naming convention `{identifier}.{language}.{version}.nupkg`, such as `ContosoUtilities.de.1.0.0.nupkg`. The identifier **must** exactly match that of the primary package. @@ -100,11 +104,13 @@ The satellite assembly **must** also declare an exact version of the primary pac The satellite package's structure must then include the resource assembly and XML IntelliSense file in a subfolder that matches `{language}` in the package filename: - lib - └───net40 - └───de - ContosoUtilities.resources.dll - ContosoUtilities.xml +``` +lib +└───net40 + └───de + ContosoUtilities.resources.dll + ContosoUtilities.xml +``` **Note**: unless specific subcultures such as `ja-JP` are necessary, always use the higher level language identifier, like `ja`. @@ -114,11 +120,11 @@ When all of these conventions are met, NuGet will recognize the package as a sat You would create additional satellite assemblies in the same way for each supported language. For an example, examine the set of ASP.NET MVC packages: -- [Microsoft.AspNet.Mvc](http://nuget.org/packages/Microsoft.AspNet.Mvc) (English primary) -- [Microsoft.AspNet.Mvc.de](http://nuget.org/packages/Microsoft.AspNet.Mvc.de) (German) -- [Microsoft.AspNet.Mvc.ja](http://nuget.org/packages/Microsoft.AspNet.Mvc.ja) (Japanese) -- [Microsoft.AspNet.Mvc.zh-Hans](http://nuget.org/packages/Microsoft.AspNet.Mvc.zh-Hans) (Chinese (Simplified)) -- [Microsoft.AspNet.Mvc.zh-Hant](http://nuget.org/packages/Microsoft.AspNet.Mvc.zh-Hant) (Chinese (Traditional)) +- [Microsoft.AspNet.Mvc](https://nuget.org/packages/Microsoft.AspNet.Mvc) (English primary) +- [Microsoft.AspNet.Mvc.de](https://nuget.org/packages/Microsoft.AspNet.Mvc.de) (German) +- [Microsoft.AspNet.Mvc.ja](https://nuget.org/packages/Microsoft.AspNet.Mvc.ja) (Japanese) +- [Microsoft.AspNet.Mvc.zh-Hans](https://nuget.org/packages/Microsoft.AspNet.Mvc.zh-Hans) (Chinese (Simplified)) +- [Microsoft.AspNet.Mvc.zh-Hant](https://nuget.org/packages/Microsoft.AspNet.Mvc.zh-Hant) (Chinese (Traditional)) ### Summary of required conventions @@ -133,7 +139,7 @@ You would create additional satellite assemblies in the same way for each suppor Using satellite packages has a few benefits: 1. **Package size**: The overall footprint of the primary package is minimized, and consumers only incur the costs of each language they want to use. -1. **Separate metadata**: Each satellite package has its own `.nuspec` file and thus its own localized metadata because. This can allow some consumers to find packages more easily by searching nuget.org with localized terms. +1. **Separate metadata**: Each satellite package has its own `.nuspec` file and thus its own localized metadata. This can allow some consumers to find packages more easily by searching nuget.org with localized terms. 1. **Decoupled releases**: Satellite assemblies can be released over time, rather than all at once, allowing you to spread out your localization efforts. However, satellite packages have their own set of disadvantages: diff --git a/docs/create-packages/Creating-a-Package.md b/docs/create-packages/Creating-a-Package.md index 265941974..d853b0e8b 100644 --- a/docs/create-packages/Creating-a-Package.md +++ b/docs/create-packages/Creating-a-Package.md @@ -1,10 +1,10 @@ --- title: Create a NuGet package using nuget.exe CLI -description: A detailed guide to the process of designing and creating a NuGet package, including key decision points like files and versioning. -author: karann-msft -ms.author: karann -ms.date: 07/09/2019 -ms.topic: conceptual +description: A detailed guide on designing and creating a NuGet package, including files and versioning. +author: JonDouglas +ms.author: jodou +ms.date: 03/03/2025 +ms.topic: how-to --- # Create a package using the nuget.exe CLI @@ -63,8 +63,8 @@ Common optional properties: - A short description for the [Package Manager UI in Visual Studio](../consume-packages/install-use-packages-visual-studio.md) - A locale ID - Project URL -- License as an expression or file (`licenseUrl` is being deprecated, use the [`license` nuspec metadata element](../reference/nuspec.md#license)) -- An icon URL +- License as an expression or file (`licenseUrl` is deprecated, use [`license` nuspec metadata element](../reference/nuspec.md#license) instead) +- An icon file (`iconUrl` is deprecated use [`icon` nuspec metadata element](../reference/nuspec.md#icon) instead) - Lists of dependencies and references - Tags that assist in gallery searches @@ -72,13 +72,13 @@ The following is a typical (but fictitious) `.nuspec` file, with comments descri ```xml - + - + Contoso.Utility.UsefulStuff - - 1.8.3-beta + + 1.8.3 Dejana Tesic, Rajeev Dey @@ -96,8 +96,8 @@ The following is a typical (but fictitious) `.nuspec` file, with comments descri Apache-2.0 - - http://github.com/contoso/UsefulStuff/nuget_icon.png + + icon.png + ``` @@ -271,9 +272,9 @@ The package identifier (`` element) and the version number (`` elem > The following series of brief blog posts are also helpful to understand versioning: > -> - [Part 1: Taking on DLL Hell](http://blog.davidebbo.com/2011/01/nuget-versioning-part-1-taking-on-dll.html) -> - [Part 2: The core algorithm](http://blog.davidebbo.com/2011/01/nuget-versioning-part-2-core-algorithm.html) -> - [Part 3: Unification via Binding Redirects](http://blog.davidebbo.com/2011/01/nuget-versioning-part-3-unification-via.html) +> - [Part 1: Taking on DLL Hell](https://blog.davidebbo.com/2011/01/nuget-versioning-part-1-taking-on-dll.html) +> - [Part 2: The core algorithm](https://blog.davidebbo.com/2011/01/nuget-versioning-part-2-core-algorithm.html) +> - [Part 3: Unification via Binding Redirects](https://blog.davidebbo.com/2011/01/nuget-versioning-part-3-unification-via.html) ## Add a readme and other files @@ -281,7 +282,7 @@ To directly specify files to include in the package, use the `` node in t ```xml - + @@ -307,17 +308,10 @@ When you include a file named `readme.txt` in the package root, Visual Studio di ## Include MSBuild props and targets in a package -In some cases, you might want to add custom build targets or properties in projects that consume your package, such as running a custom tool or process during build. You do this by placing files in the form `.targets` or `.props` (such as `Contoso.Utility.UsefulStuff.targets`) within the `\build` folder of the project. +In some cases, you might want to add custom build targets or properties in projects that consume your package, such as running a custom tool or process during build. +You can learn more about [MSBuild props and targets in NuGet packages](..\concepts\MSBuild-props-and-targets.md) -Files in the root `\build` folder are considered suitable for all target frameworks. To provide framework-specific files, first place them within appropriate subfolders, such as the following: - - \build - \netstandard1.4 - \Contoso.Utility.UsefulStuff.props - \Contoso.Utility.UsefulStuff.targets - \net462 - \Contoso.Utility.UsefulStuff.props - \Contoso.Utility.UsefulStuff.targets +Create `.targets` or `.props` (such as `Contoso.Utility.UsefulStuff.targets`) within the build folders of the project. Then in the `.nuspec` file, be sure to refer to these files in the `` node: @@ -337,13 +331,7 @@ Then in the `.nuspec` file, be sure to refer to these files in the `` nod ``` -Including MSBuild props and targets in a package was [introduced with NuGet 2.5](../release-notes/NuGet-2.5.md#automatic-import-of-msbuild-targets-and-props-files), therefore it is recommended to add the `minClientVersion="2.5"` attribute to the `metadata` element, to indicate the minimum NuGet client version required to consume the package. - -When NuGet installs a package with `\build` files, it adds MSBuild `` elements in the project file pointing to the `.targets` and `.props` files. (`.props` is added at the top of the project file; `.targets` is added at the bottom.) A separate conditional MSBuild `` element is added for each target framework. - -MSBuild `.props` and `.targets` files for cross-framework targeting can be placed in the `\buildMultiTargeting` folder. During package installation, NuGet adds the corresponding `` elements to the project file with the condition, that the target framework is not set (the MSBuild property `$(TargetFramework)` must be empty). - -With NuGet 3.x, targets are not added to the project but are instead made available through `{projectName}.nuget.g.targets` and `{projectName}.nuget.g.props`. +When packages are added to a project, NuGet will automatically include these props and targets. ## Run nuget pack to generate the .nupkg file @@ -429,4 +417,4 @@ You might also want to extend the capabilities of your package or otherwise supp Finally, there are additional package types to be aware of: - [Native Packages](../guides/native-packages.md) -- [Symbol Packages](../create-packages/symbol-packages.md) +- [Symbol Packages](../create-packages/symbol-packages-snupkg.md) diff --git a/docs/create-packages/Overview-and-Workflow.md b/docs/create-packages/Overview-and-Workflow.md index cb4be7514..ddda6fd80 100644 --- a/docs/create-packages/Overview-and-Workflow.md +++ b/docs/create-packages/Overview-and-Workflow.md @@ -1,10 +1,10 @@ --- title: Overview and workflow of creating NuGet packages description: An overview of the process of creating and publishing a NuGet package, with links to other specific parts of the process. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 07/26/2017 -ms.topic: conceptual +ms.topic: concept-article --- # Package creation workflow diff --git a/docs/create-packages/Package-authoring-best-practices.md b/docs/create-packages/Package-authoring-best-practices.md new file mode 100644 index 000000000..f4451cbe0 --- /dev/null +++ b/docs/create-packages/Package-authoring-best-practices.md @@ -0,0 +1,180 @@ +--- +title: Package authoring best practices +description: A general guide of best practices for creating high quality NuGet packages. +author: nkolev92 +ms.author: nikolev +ms.date: 11/15/2021 +ms.topic: best-practice +--- + +# Package authoring best practices + +This guidance is intended to give NuGet package authors a lightweight reference to create and publish high-quality packages. It will primarily focus on package-specific best practices such as metadata and packing. For more in-depth suggestions for building high quality libraries, see the .NET [Open-source library guidance](/dotnet/standard/library-guidance/). + +## Types of recommendations + +Each article presents four types of recommendations: **Do**, **Consider**, **Avoid**, and **Do not**. The type of recommendation indicates how closely it should be followed. + +You should almost always follow a **Do** recommendation. For example: + +✔️ DO include a short description for your package that describes what it's for. + +On the other hand, **Consider** recommendations should generally be followed, but there are legitimate exceptions to the rule: + +✔️ CONSIDER choosing a NuGet package name with a prefix that meets NuGet's prefix reservation [criteria](../nuget-org/id-prefix-reservation.md). + +**Avoid** recommendations mention things that are generally not a good idea, but breaking the rule sometimes makes sense: + +❌ AVOID NuGet package references that demand an exact version. + +And finally, **Do not** recommendations indicate something you should almost never do: + +❌ DO NOT use the `LicenseUrl` metadata property. + +## Create a NuGet package + +The latest recommended way to to create a NuGet package is from an [SDK-style project](../resources/check-project-format.md). SDK-style project properties, including [target framework](/dotnet/standard/frameworks) and [package metadata](#package-metadata), are defined in the [project file](/visualstudio/ide/solutions-and-projects-in-visual-studio#project-file). + +Create a package from your SDK-style project by defining the required properties and packing in [Visual Studio](../quickstart/create-and-publish-a-package-using-visual-studio.md?tabs=netcore-cli) or the [dotnet CLI](../quickstart/create-and-publish-a-package-using-the-dotnet-cli.md). + +✔️ DO create an SDK-style project and create (pack) your package using Visual Studio or the dotnet CLI. + +For more detailed guidance regarding package creation including necessary client tools, project file example, and commands, see [Create a NuGet package using the dotnet CLI](./creating-a-package-dotnet-cli.md). + +To help decide which .NET frameworks to target, see our [latest guidance for cross-platform targeting](/dotnet/standard/library-guidance/cross-platform-targeting). + +## Package metadata + +Metadata is a foundational component of any NuGet package. The quality of your metadata can vastly influence the discoverability, usability, and trustworthiness of your package. + +In Visual Studio, the recommended way to specify package metadata is to go Project > [Project Name] Properties > Package. + +Package metadata elements can also be [specified directly in the project file](./creating-a-package-msbuild.md#set-properties). + +Below is a table mapping and describing available package metadata elements: + +| Visual Studio property name | [Project file/ MSBuild property name](/dotnet/core/tools/csproj#packagereleasenotes) | [Nuspec property name](/nuget/reference/nuspec#general-form-and-schema) | Description | +|----------------------------------------------- |----------------------------------------------------------------------------------------------------------------------------------------- |--------------------------------------------------------------------------------------------------- |------------------------------------------------------------------------------------------------------------------- | +| [`Package id`](#package-id) | [`PackageId`](/nuget/reference/msbuild-targets#pack-target) | [`id`](/nuget/reference/nuspec#id) | The package name or identifier. | +| [`Package version`](#package-version) | [`PackageVersion`](/nuget/reference/msbuild-targets#pack-target) | [`version`](/nuget/reference/nuspec#version) | NuGet package version. | +| [`Authors`](#authors) | [`Authors`](/nuget/reference/msbuild-targets#pack-target) | [`authors`](/nuget/reference/nuspec#authors) | A comma-separated list of package authors, often using the individual's or an organization's "pretty name." | +| [`Description`](#description) | [`Description`](/nuget/reference/msbuild-targets#pack-target) | [`description`](/nuget/reference/nuspec#description) | A description of the package. | +| [`Copyright`](#copyright) | [`Copyright`](/nuget/reference/msbuild-targets#pack-target) | [`copyright`](/nuget/reference/nuspec#copyright) | Copyright details for the package. | +| [`Project URL`](#project-url) | [`PackageProjectUrl`](/nuget/reference/msbuild-targets#pack-target) | [`projectUrl`](/nuget/reference/nuspec#projecturl) | A URL for the project homepage. | +| [`Icon File`](#icon) | [`PackageIcon`](/nuget/reference/msbuild-targets#packing-an-icon-image-file) | [`icon`](/nuget/reference/nuspec#icon) | Path to the package icon image file. | +| [`README`](#readme) | [`PackageReadmeFile`](/nuget/reference/msbuild-targets#packagereadmefile) | [`readme`](/nuget/reference/nuspec#readme) | Path to the package README markdown file. | +| [`Repository URL`](#repository-type-and-url) | [`RepositoryUrl`](/nuget/reference/msbuild-targets#pack-target) | [`repository url`](/nuget/reference/nuspec#repository) | URL to the repository from which the package was built. | +| [`Repository type`](#repository-type-and-url) | [`RepositoryType`](/nuget/reference/msbuild-targets#pack-target) | [`repository type`](/nuget/reference/nuspec#repository) | Type of repository the repository URL is pointing to (i.e. "git"). | +| [`Tags`](#tags) | [`PackageTags`](/nuget/reference/msbuild-targets#pack-target) | [`tags`](/nuget/reference/nuspec#tags) | A space-delimited list of tags and keywords that describe the package. Tags are used when searching for packages. | +| [`Release notes`](#release-notes) | [`PackageReleaseNotes`](/nuget/reference/msbuild-targets#pack-target) | [`releaseNotes`](/nuget/reference/nuspec#releasenotes) | A description of the changes made in this release of the package. | +| [`Licensing - Expression`](#licensing) | [`PackageLicenseExpression`](/nuget/reference/msbuild-targets#packing-a-license-expression-or-a-license-file) | [`license type="expression"`](/nuget/reference/nuspec#license) | An SPDX license expression. | +| [`Licensing - File`](#licensing) | [`PackageLicenseFile`](/nuget/reference/msbuild-targets#packing-a-license-expression-or-a-license-file) | [`license type="file"`](/nuget/reference/nuspec#license) | Path to a custom license file. | +### Package ID + +If you're publishing a completely new package: + +✔️ DO choose a package ID that is unique and clearly differentiated from existing packages on NuGet.org. +> You can check if a package ID is unique and differentiable by searching for the ID on NuGet.org or checking if the following link exists: https://www.nuget.org/packages/. + +✔️ CONSIDER choosing a NuGet package name with a prefix that meets NuGet's [prefix reservation criteria](../nuget-org/id-prefix-reservation.md#id-prefix-reservation-criteria). +> Reserving the prefix ID for your package will let you get the verified check mark: +> ![image](media/Verified-check-mark.png) +> +> Check out the [Package ID prefix reservation docs](../nuget-org/id-prefix-reservation.md) to learn more. + +### Package Version + +✔️ CONSIDER using [SemVer](https://semver.org/) to version your NuGet package. +> Essentially, this means using the Major.Minor.Patch[-prerelease] format. + +✔️ DO publish a package as a [pre-release package](./prerelease-packages.md) if it is non-stable or a preview. + +See the [.NET library versioning guide](/dotnet/standard/library-guidance/versioning) for more advanced guidance. + +### Authors + +✔️ DO use the author field for your or your organization's "pretty name." +> For example, if my NuGet.org username is "jdoe" then using "Jane Doe" for the author field may help consumers recognize me as an author. If my organization's NuGet.org username is "ContosoToolkit" then using "Contoso Corporation" may be more recognizable and inspire more consumer trust. + +### Description + +✔️ DO include a short description (up to 4000 characters) to describe your package. +> Package descriptions are one of the most prominent fields surfaced in NuGet search and will likely be the first thing potential consumers looks at to determine if a package is right for them. + +### Copyright + +✔️ DO add a copyright notice to your package with "Copyright (c) ." +> A copyright notice essentially indicates that your work cannot be copied without your permission. Including a copyright notice in your package is easy and won't do any harm! + +Example: Copyright (c) Contoso 2020 + +### Project URL + +✔️ DO include a link to an associated project, repository, or company website. +> Your project site should have everything users need to know about your package and will likely be where users look for documentation. + +### Icon + +✔️ CONSIDER [including an icon with your package](../reference/msbuild-targets.md#packing-an-icon-image-file) to help visually differentiate it. It's a relatively small addition that can improve perception of package quality. +> Icons can be specific to individual packages or be a brand logo. + +✔️ DO use an image that is 128x128 and has a transparent background (PNG) for best viewing results. +> NuGet will automatically scale your image to the client it is being displayed on. + +❌ DO NOT use the deprecated `IconUrl` metadata property. + +### README +✔️ DO [add a README markdown file](/nuget/reference/msbuild-targets#packagereadmefile) that provides an overview of what your package does and how to get started. +> A package README will significantly improve the quality perception of your package as well as new user onboarding. Also consider [previewing your README](../nuget-org/package-readme-on-nuget-org.md#preview-your-readme) before you upload it! See [how to include a README file in your NuGet package](/nuget/reference/msbuild-targets#packagereadmefile) for more details. + +### Repository Type and URL + +✔️ CONSIDER setting up [Source Link](/dotnet/standard/library-guidance/sourcelink) to automatically add source control metadata to your NuGet package and make your library easier to debug. +> Source Link automatically adds `Repository URL` and `Repository Type` to the package metadata. It also adds the specific commit associated with your package version. + +### Tags + +✔️ DO include several tags with key terms related to your package to enhance discoverability. +> Tags are taken into account in NuGet.org's search algorithm and are especially helpful for terms that are not in the Package ID but are relevant. + +For example, if I published a package to log strings to the console, I would include: "logging, log, console, string, output" + +### Release notes + +✔️ DO include release notes with each update describing what changes were made. +> While there is no specific format required for release notes, we recommend including: +> +> 1. Breaking changes +> 2. New features +> 3. Bug fixes +> +> If you already track release notes or a changelog in your repo, you can also include a link to the relevant file. + +### Licensing + +✔️ DO [include a license expression or license file in your package](../reference/msbuild-targets.md#packing-a-license-expression-or-a-license-file). +> [!IMPORTANT] +> A project without a license defaults to [exclusive copyright](https://choosealicense.com/no-permission/), meaning that you have not granted anyone permission to use your project. + +❌ DO NOT use the deprecated `LicenseUrl` metadata property. +> This presents legal ambiguity as license changes at the URL will retroactively change the displayed license for previous package versions. + +#### If your package is [open source](https://opensource.org/osd) + +✔️ DO [choose an open source license](https://choosealicense.com/) to make your package open source. +> *"Open source licenses are licenses that comply with the Open Source Definition — in brief, they allow software to be freely used, modified, and shared."* - Open Source Initiative. To learn more about open source software and the Open Source Initiative, check out https://opensource.org/. + +✔️ CONSIDER [including a license expression in your package](../reference/msbuild-targets.md#packing-a-license-expression-or-a-license-file). +> License expressions are surfaced the most clearly and make it more obvious to consumers if they can use your package or if the license has changed. +> [!Note] +> NuGet.org only accepts license expressions for licenses that are approved by the Open Source Initiative or the Free Software Foundation. + +#### If your package is not open source + +✔️ DO [include a license file in your package](../reference/msbuild-targets.md#packing-a-license-expression-or-a-license-file). +> Any license file (.txt or .md) can be added to your package, including non-standard licenses. + +## Related topics + +- [Create and publish a package (dotnet CLI)](../quickstart/create-and-publish-a-package-using-the-dotnet-cli.md) +- [Create and publish a package (Visual Studio)](../quickstart/create-and-publish-a-package-using-visual-studio.md?tabs=netcore-cli) diff --git a/docs/create-packages/Prerelease-Packages.md b/docs/create-packages/Prerelease-Packages.md index 49141db43..89ffc0d19 100644 --- a/docs/create-packages/Prerelease-Packages.md +++ b/docs/create-packages/Prerelease-Packages.md @@ -1,10 +1,10 @@ --- title: Pre-release versions in NuGet packages description: Guidance for building pre-release packages -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 08/14/2017 -ms.topic: conceptual +ms.topic: concept-article --- # Building pre-release packages @@ -19,7 +19,7 @@ To support the software release lifecycle, NuGet 1.6 and later allows for the di You can specify such versions using one of the following ways: -- **If your project uses [`PackageReference`](../consume-packages/package-references-in-project-files.md)**: include the semantic version suffix in the `.csproj` file's [`PackageVersion`](/dotnet/core/tools/csproj.md#packageversion) element: +- **If your project uses [`PackageReference`](../consume-packages/package-references-in-project-files.md)**: include the semantic version suffix in the `.csproj` file's [`PackageVersion`](/dotnet/core/tools/csproj#packageversion) element: ```xml @@ -51,37 +51,5 @@ By default, NuGet does not include pre-release versions when working with packag ## Semantic versioning -The [Semantic Versioning or SemVer convention](http://semver.org/spec/v1.0.0.html) describes how to utilize strings in version numbers to convey the meaning of the underlying code. - -In this convention, each version has three parts, `Major.Minor.Patch`, with the following meaning: - -- `Major`: Breaking changes -- `Minor`: New features, but backwards compatible -- `Patch`: Backwards compatible bug fixes only - -Pre-release versions are then denoted by appending a hyphen and a string after the patch number. Technically speaking, you can use *any* string after the hyphen and NuGet will treat the package as pre-release. NuGet then displays the full version number in the applicable UI, leaving consumers to interpret the meaning for themselves. - -With this in mind, it's generally good to follow recognized naming conventions such as the following: - -- `-alpha`: Alpha release, typically used for work-in-progress and experimentation -- `-beta`: Beta release, typically one that is feature complete for the next planned release, but may contain known bugs. -- `-rc`: Release candidate, typically a release that's potentially final (stable) unless significant bugs emerge. - -> [!Note] -> NuGet 4.3.0+ supports [Semantic Versioning v2.0.0](http://semver.org/spec/v2.0.0.html), which supports pre-release numbers with dot notation, as in `1.0.1-build.23`. Dot notation is not supported with NuGet versions before 4.3.0. In earlier versions of NuGet, you could use a form like `1.0.1-build23` but this was always considered a pre-release version. - -Whatever suffixes you use, however, NuGet will give them precedence in reverse alphabetical order: - - 1.0.1 - 1.0.1-zzz - 1.0.1-rc - 1.0.1-open - 1.0.1-beta.12 - 1.0.1-beta.5 - 1.0.1-beta - 1.0.1-alpha.2 - 1.0.1-alpha - -As shown, the version without any suffix will always take precedence over pre-release versions. - -Leading 0s are not needed with semver2, but they are with the old version schema. If you use numerical suffixes with pre-release tags that might use double-digit numbers (or more), use leading zeroes as in beta.01 and beta.05 to ensure that they sort correctly when the numbers get larger. This recommendation only applies to the old version schema. +The [Semantic Versioning or SemVer convention](https://semver.org/spec/v1.0.0.html) describes how to utilize strings in version numbers to convey the meaning of the underlying code. +[Learn more](../concepts/Package-Versioning.md) about the package versioning basics. diff --git a/docs/create-packages/Select-assemblies-referenced-by-projects.md b/docs/create-packages/Select-assemblies-referenced-by-projects.md index 66f46f884..6eebd9a66 100644 --- a/docs/create-packages/Select-assemblies-referenced-by-projects.md +++ b/docs/create-packages/Select-assemblies-referenced-by-projects.md @@ -4,27 +4,62 @@ description: Make a subset of assemblies in the package available to the compile author: zivkan ms.author: zivkan ms.date: 05/24/2019 -ms.topic: conceptual +ms.topic: how-to --- # Select Assemblies Referenced By Projects -Explicit assembly references allows a subset of assemblies to be used for IntelliSense and compiling, while all assemblies are available at run-time. `PackageReference` and `packages.config` work differently, and as a result package authors need to take care to create the package to be compatible with both project types. +Assemblies are used in two different ways during a build. The first is for compile, which allows the package consumer's code to compile against APIs in the assembly, and for Intellisense to give suggestions. The second is runtime, where the assembly is copied to the `bin` directory and is used during program execution. Some package authors would like only their own assemblies (or a subset of their assemblies) available to their package consumers at compile time, but need to provide all their dependencies for runtime. This document looks at ways to achieve this outcome. -> [!Note] -> Explicit assembly references are related to .NET assemblies. It is not a method to distribute native assemblies that are P/Invoked by a managed assembly. +## Recommended: One assembly per package -## `PackageReference` support +Our recommendation is to have one package per assembly, and package dependencies to other assemblies. When NuGet restores a project, it does asset selection and supports including, excluding, and making private different asset classes. In order to prevent your package's dependencies from becoming compile time assets for anyone using your package, you can make `compile` assets private. In the generated package, that will cause `compile` to be excluded from the dependency. Note that the default private assets when none is supplied is `contentfiles;build;analyzers`. Therefore, you should use `PrivateAssets="compile;contentfiles;build;analyzers"` in your `PackageReference` or `ProjectReference`. -When a project uses a package with `PackageReference` and the package contains a `ref\\` directory, NuGet will classify those assembles as compile-time assets, while the `lib\\` assemblies are classified as runtime assets. Assemblies in `ref\\` are not used at runtime. This means it is necessary for any assembly in `ref\\` to have a matching assembly in either `lib\\` or a relevant `runtime\` directory, otherwise runtime errors will likely occur. Since assemblies in `ref\\` are not used at runtime, they may be [metadata-only assemblies](https://github.com/dotnet/roslyn/blob/master/docs/features/refout.md) to reduce package size. +```xml + + + + +``` -> [!Important] -> If a package contains the nuspec `` element (used by `packages.config`, see below) and does not contain assemblies in `ref\\`, NuGet will advertise the assemblies listed in the nuspec `` element as both the compile and runtime assets. This means there will be runtime exceptions when the referenced assemblies need to load any other assembly in the `lib\\` directory. +If you are creating a package from a custom `nuspec` file, rather than letting NuGet auto-generate one for you, your `nuspec` should use the `exclude` XML attribute . -> [!Note] -> If the package contains a `runtime\` directory, NuGet may not use the assets in the `lib\` directory. +```xml + + + + + + +``` + +There are three reasons why this is the recommended solution. + +Firstly, useful assemblies often get referenced by new assemblies/packages. While a utility assembly might be intended to only be used by a single package today, making it tempting to ship both assemblies in a single package, if a second package wants to use the "private" utility assembly in the future, either the utility assembly needs to be moved into a new package and the old package needs to be updated to declare it as a dependency, or the utility package needs to ship in both the existing and the new package. If the assembly ships in two different packages, and a project references both packages, if there are different versions of the utility assembly in the two packages, NuGet will be unable to assist in version management. + +Secondly, there may be times that the developers using your package want to also use APIs from your dependencies. For example, consider the package [Microsoft.ServiceHub.Client version 3.0.3078](https://www.nuget.org/packages/Microsoft.ServiceHub.Client/3.0.3078). If you download the package and check the `nuspec` file, you can see that it lists two packages starting with `Microsoft.VisualStudio.` as dependencies, meaning it needs them at runtime, but it also excludes their compile assets. This means that projects using Microsoft.ServiceHub.Client will not have the Visual Studio APIs available in IntelliSense or if they build the project, unless the project explicit installs those packages. And this is the advantage that a package dependency with an exclude asset has. Projects using your package, if they want to use your dependencies as well, they can add a reference to the package to make the APIs available to themselves. + +Finally, some package authors have been confused in the past about NuGet's assembly selection for packages supporting more than one target framework when their package also contains multiple assemblies. If your main assembly supports different target frameworks to your utility assembly, it may not be obvious which `lib/` directories to put all of the assemblies into. By separating each package by assembly name, it's more intuitive which `lib/` folders each assembly should go into. Note, this does not mean having `Package1.net48` and `Package1.net6.0` packages. It means having `lib/net48/Package1.dll` and `lib/net6.0/Package6.0` in `Package1`, and `lib/netstandard2.0/Package2.dll` and `lib/net5.0/Package2.dll` in `Package2`. When Nuget restores a project, Nuget will independently do asset selection for the two packages. + +Also note that dependency include/exclude assets is only used by projects using PackageReference. Any project installing your package using `packages.config` will install your dependencies and have its APIs available as well. `packages.config` is only supported by Visual Studio's older .NET Framework project templates. SDK style projects, even those targeting .NET Framework, do not support `packages.config`, and therefore do support dependency include/exclude assets. -## `packages.config` support +## Not recommended: Multiple assemblies in one package + +`PackageReference` and `packages.config` have different features available. Whether you want to support your package consumers who use `PackageReference`, `packages.config`, or both, changes how you must author your package. + +NuGet's MSBuild Pack target does not support automatically including project references in the package. It will only list those referenced projects as package dependencies. There is [an issue on GitHub](https://github.com/NuGet/Home/issues/3891), where community members shared ways they achieved this outcome, which usually involves using `PackagePath` MSBuild item metadata to place files anywhere in the package, as described in [the docs on including content in a package](../reference/msbuild-targets.md#including-content-in-a-package), and using [`SuppressDependenciesWhenPacking` to avoid the project references becoming package dependencies](../reference/msbuild-targets.md#pack-target-inputs). There also exist community developed tools that can be used as an alternative to NuGet's official pack, which support this feature. + +### `PackageReference` support + +When a package consumer uses `PackageReference`, NuGet selects compile and runtime assets independently, as previously described. + +Compile assets prefer `ref//*.dll` (for example `ref/net6.0/*.dll`), but if that does not exist, then it will fall back to `lib//*.dll` (for example `lib/net6.0/*.dll`). + +Runtime assets prefer `runtimes//lib//*.dll` (for example (`runtimes/win11-x64/lib/net6.0/*.dll`)), but if that does not exist, then it will fall back to `lib//*.dll`. + +Since assemblies in `ref\\` are not used at runtime, they may be [metadata-only assemblies](https://github.com/dotnet/roslyn/blob/main/docs/features/refout.md) to reduce package size. + +### `packages.config` support Projects using `packages.config` to manage NuGet packages normally add references to all assemblies in the `lib\\` directory. The `ref\` directory was added to support `PackageReference` and therefore isn't considered when using `packages.config`. To explicitly set which assemblies are referenced for projects using `packages.config`, the package must use the [`` element in the nuspec file](../reference/nuspec.md#explicit-assembly-references). For example: @@ -36,10 +71,17 @@ Projects using `packages.config` to manage NuGet packages normally add reference ``` +The MSBuild pack targets don't support the `` element. See [the docs on packing using a .nuspec file](../reference/msbuild-targets.md#packing-using-a-nuspec-file) when using MSBuild pack. + > [!Note] -> `packages.config` project use a process called [ResolveAssemblyReference](https://github.com/Microsoft/msbuild/blob/master/documentation/wiki/ResolveAssemblyReference.md) to copy assemblies to the `bin\\` output directory. Your project's assembly is copied, then the build system looks at the assembly manifest for referenced assemblies, then copies those assemblies and recursively repeats for all assemblies. This means that if any of the assemblies in your `lib\\` directory are not listed in any other assembly's manifest as a dependency (if the assembly is loaded at runtime using `Assembly.Load`, MEF or another dependency injection framework), then it may not be copied to your project's `bin\\` output directory despite being in `bin\\`. +> `packages.config` project use a process called [ResolveAssemblyReference](https://github.com/Microsoft/msbuild/blob/main/documentation/wiki/ResolveAssemblyReference.md) to copy assemblies to the `bin\\` output directory. Your project's assembly is copied, then the build system looks at the assembly manifest for referenced assemblies, then copies those assemblies and recursively repeats for all assemblies. This means that if any of the assemblies loaded only by reflection (`Assembly.Load`, MEF or another dependency injection framework), then it may not be copied to your project's `bin\\` output directory despite being in `bin\\`. This also means that this only works for .NET assemblies, not for native code called with P/Invoke. + +### Supporting both `PackageReference` and `packages.config` + +> [!Important] +> If a package contains the nuspec `` element and does not contain assemblies in `ref\\`, NuGet will advertise the assemblies listed in the nuspec `` element as both the compile and runtime assets. This means there will be runtime exceptions when the referenced assemblies need to load any other assembly in the `lib\\` directory. Therefore, it is important to use both the nuspec `` for `packages.config` support, as well as duplicating assemblies in the `ref/` folder for `PackageReference` support. The `runtimes/` package folder does not need to be used, it was added to the above section for completeness. -## Example +#### Example My package will contain three assemblies, `MyLib.dll`, `MyHelpers.dll` and `MyUtilities.dll`, which are targeting the .NET Framework 4.7.2. `MyUtilities.dll` contains classes intended to be used only by the other two assemblies, so I don't want to make those classes available in IntelliSense or at compile time to projects using my package. My `nuspec` file needs to contain the following XML elements: @@ -52,7 +94,7 @@ My package will contain three assemblies, `MyLib.dll`, `MyHelpers.dll` and `MyUt ``` -and the files in the package will be: +I need to ensure my package contents are: ```text lib\net472\MyLib.dll diff --git a/docs/create-packages/Sign-a-Package.md b/docs/create-packages/Sign-a-Package.md index a174a8719..098353fe7 100644 --- a/docs/create-packages/Sign-a-Package.md +++ b/docs/create-packages/Sign-a-Package.md @@ -4,17 +4,26 @@ description: Explains how signed packages can be used to enable content integrit author: rido-min ms.author: rmpablos ms.date: 03/06/2018 -ms.topic: conceptual +ms.topic: how-to ms.reviewer: anangaur +ms.custom: sfi-image-nochange --- -# Signing NuGet Packages +# Sign a NuGet package -Signed packages allows for content integrity verification checks which provides protection against content tampering. The package signature also serves as the single source of truth about the actual origin of the package and bolsters package authenticity for the consumer. This guide assumes you have already [created a package](creating-a-package.md). +A signed package allows for content integrity verification checks, which provides protection against content tampering. The package signature also serves as the single source of truth about the actual origin of the package and bolsters package authenticity for the consumer. This guide assumes you have already [created a package](creating-a-package.md). ## Get a code signing certificate -Valid certificates may be obtained from a public certificate authority such as [Symantec](https://trustcenter.websecurity.symantec.com/process/trust/productOptions?productType=SoftwareValidationClass3), [DigiCert](https://www.digicert.com/code-signing/), [Go Daddy](https://www.godaddy.com/web-security/code-signing-certificate), [Global Sign](https://www.globalsign.com/en/code-signing-certificate/), [Comodo](https://www.comodo.com/e-commerce/code-signing/code-signing-certificate.php), [Certum](https://www.certum.eu/certum/cert,offer_en_open_source_cs.xml), etc. The complete list of certification authorities trusted by Windows can be obtained from [http://aka.ms/trustcertpartners](http://aka.ms/trustcertpartners). +Valid certificates can be obtained from a public certificate authority such as: + +- [Certum](https://www.certum.eu/certum/cert,offer_en_open_source_cs.xml) +- [Comodo](https://www.comodo.com/e-commerce/code-signing/code-signing-certificate.php) +- [DigiCert](https://www.digicert.com/code-signing/) +- [GlobalSign](https://www.globalsign.com/en/code-signing-certificate/) +- [SSL.com](https://www.ssl.com/certificates/code-signing/) + +The complete list of certification authorities trusted by Windows can also be obtained from [http://aka.ms/trustcertpartners](/security/trusted-root/participants-list). You can use self-issued certificates for testing purposes. However, packages signed using self-issued certificates are not accepted by NuGet.org. Learn more about [creating a test certificate](#create-a-test-certificate) @@ -24,14 +33,19 @@ You can use self-issued certificates for testing purposes. However, packages sig ![Certificate Export Wizard](../reference/media/CertificateExportWizard.png) -* You can also export the certificate using the [Export-Certificate PowerShell command](/powershell/module/pkiclient/export-certificate). +* You can also export the certificate using the [Export-Certificate PowerShell command](/powershell/module/pki/export-certificate). ## Sign the package -> [!note] -> Requires nuget.exe 4.6.0 or later. dotnet.exe support is coming soon - [#7939](https://github.com/NuGet/Home/issues/7939) +Sign the package using [dotnet nuget sign](/dotnet/core/tools/dotnet-nuget-sign) (requires .NET 6.0.100 SDK or later). -Sign the package using [nuget sign](../reference/cli-reference/cli-ref-sign.md): +```cli +dotnet nuget sign MyPackage.nupkg --certificate-path --timestamper +``` + +or + +Sign the package using [nuget sign](../reference/cli-reference/cli-ref-sign.md) (requires nuget.exe 4.6.0 or later): ```cli nuget sign MyPackage.nupkg -CertificatePath -Timestamper @@ -49,23 +63,24 @@ nuget sign MyPackage.nupkg -CertificatePath -Timestamper To publish a signed package, you must first register the certificate with NuGet.org. You need the certificate as a `.cer` file in a binary DER format. 1. [Sign in](https://www.nuget.org/users/account/LogOn?returnUrl=%2F) to NuGet.org. -1. Go to `Account settings` (or `Manage Organization` **>** `Edit Organziation` if you would like to register the certificate with an Organization account). +1. Go to `Account settings` (or `Manage Organization` **>** `Edit Organization` if you would like to register the certificate with an Organization account). 1. Expand the `Certificates` section and select `Register new`. 1. Browse and select the certficate file that was exported earlier. ![Registered Certificates](../reference/media/registered-certs.png) -**Note** -* One user can submit multiple certificates and the same certificate can be registered by multiple users. -* Once a user has a certificate registered, all future package submissions **must** be signed with one of the certificates. See [Manage signing requirements for your package on NuGet.org](#manage-signing-requirements-for-your-package-on-nugetorg) -* Users can also remove a registered certificate from the account. Once a certificate is removed, new packages signed with that certificate will fail at submission. Existing packages aren't affected. +> [!NOTE] +> +> * One user can submit multiple certificates and the same certificate can be registered by multiple users. +> * Once a user has a certificate registered, all future package submissions **must** be signed with one of the certificates. See [Manage signing requirements for your package on NuGet.org](#manage-signing-requirements-for-your-package-on-nugetorg) +> * Users can also remove a registered certificate from the account. Once a certificate is removed, new packages signed with that certificate will fail at submission. Existing packages aren't affected. ## Publish the package -You are now ready to publish the package to NuGet.org. See [Publishing packages](../nuget-org/Publish-a-package.md). +You're now ready to publish the package to NuGet.org. See [Publishing packages](../nuget-org/Publish-a-package.md). ## Create a test certificate -You can use self-issued certificates for testing purposes. To create a self-issued certificate, use the [New-SelfSignedCertificate PowerShell command](/powershell/module/pkiclient/new-selfsignedcertificate). +You can use self-issued certificates for testing purposes. To create a self-issued certificate, use the [New-SelfSignedCertificate PowerShell command](/powershell/module/pki/new-selfsignedcertificate). ```ps New-SelfSignedCertificate -Subject "CN=NuGet Test Developer, OU=Use for testing purposes ONLY" ` @@ -85,14 +100,15 @@ This command creates a testing certificate available in the current user's perso > NuGet.org does not accept packages signed with self-issued certificates. ## Manage signing requirements for your package on NuGet.org + 1. [Sign in](https://www.nuget.org/users/account/LogOn?returnUrl=%2F) to NuGet.org. 1. Go to `Manage Packages` ![Configure package signers](../reference/media/configure-package-signers.png) -* If you are the sole owner of a package, you are the required signer i.e. you can use any of the registered certificates to sign and publish your packages to NuGet.org. +* If you are the sole owner of a package, you are the required signer, that is, you can use any of the registered certificates to sign and publish your packages to NuGet.org. -* If a package has multiple owners, by default, "Any" owner's certificates can be used to sign the package. As a co-owner of the package, you can override "Any" with yourself or any other co-owner to be the required signer. If you make an owner who does not have any certificate registered, then unsigned packages will be allowed. +* If a package has multiple owners, by default, "Any" owner's certificates can be used to sign the package. As a co-owner of the package, you can override "Any" with yourself or any other co-owner to be the required signer. If you make an owner who does not have any certificate registered, then unsigned packages will be allowed. * Similarly, if the default "Any" option is selected for a package where one owner has a certificate registered and another owner does not have any certificate registered, then NuGet.org accepts either a signed package with a signature registered by one of its owners or an unsigned package (because one of the owners does not have any certificate registered). @@ -100,3 +116,4 @@ This command creates a testing certificate available in the current user's perso - [Manage package trust boundaries](../consume-packages/installing-signed-packages.md) - [Signed Packages Reference](../reference/Signed-Packages-Reference.md) +- [.NET signed package verification](/dotnet/core/tools/nuget-signed-package-verification) diff --git a/docs/create-packages/Source-and-Config-File-Transformations.md b/docs/create-packages/Source-and-Config-File-Transformations.md index ad1bb50a7..65f9f7659 100644 --- a/docs/create-packages/Source-and-Config-File-Transformations.md +++ b/docs/create-packages/Source-and-Config-File-Transformations.md @@ -1,18 +1,16 @@ --- title: Source and config file transformations for NuGet packages description: Details on the ability for NuGet packages to transform source code and configuration (XML) files when installed. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 04/24/2017 -ms.topic: conceptual +ms.topic: how-to ms.reviewer: anangaur --- # Transforming source code and configuration files -For projects using `packages.config`, NuGet supports the ability to make transformations to source code and configuration files at package install and uninstall times. Only Source code transformations are applied when a package is installed in a project using [PackageReference](../consume-packages/package-references-in-project-files.md). - -A **source code transformation** applies one-way token replacement to files in the package's `content` or `contentFiles` folder (`content` for customers using `packages.config` and `contentFiles` for `PackageReference`) when the package is installed, where tokens refer to Visual Studio [project properties](/dotnet/api/vslangproj.projectproperties?view=visualstudiosdk-2017&viewFallbackFrom=netframework-4.7). This allows you to insert a file into the project's namespace, or to customize code that would typically go into `global.asax` in an ASP.NET project. +A **source code transformation** applies one-way token replacement to files in the package's `content` or `contentFiles` folder (`content` for customers using `packages.config` and `contentFiles` for `PackageReference`) when the package is installed, where tokens refer to Visual Studio [project properties](/dotnet/api/vslangproj.projectproperties). This allows you to insert a file into the project's namespace, or to customize code that would typically go into `global.asax` in an ASP.NET project. A **config file transformation** allows you to modify files that already exist in a target project, such as `web.config` and `app.config`. For example, your package might need to add an item to the `modules` section in the config file. This transformation is done by including special files in the package that describe the sections to add to the configuration files. When a package is uninstalled, those same changes are then reversed, making this a two-way transformation. @@ -42,14 +40,14 @@ A **config file transformation** allows you to modify files that already exist i Upon installation, NuGet replaces `$rootnamespace$` with `Fabrikam` assuming the target project's whose root namespace is `Fabrikam`. -The `$rootnamespace$` token is the most commonly used project property; all others are listed in [project properties](/dotnet/api/vslangproj.projectproperties?view=visualstudiosdk-2017&viewFallbackFrom=netframework-4.7). Be mindful, of course, that some properties might be specific to the project type. +The `$rootnamespace$` token is the most commonly used project property; all others are listed in [project properties](/dotnet/api/vslangproj.projectproperties). Be mindful, of course, that some properties might be specific to the project type. ## Specifying config file transformations As described in the sections that follow, config file transformations can be done in two ways: - Include `app.config.transform` and `web.config.transform` files in your package's `content` folder, where the `.transform` extension tells NuGet that these files contain the XML to merge with existing config files when the package is installed. When a package is uninstalled, that same XML is removed. -- Include `app.config.install.xdt` and `web.config.install.xdt` files in your package's `content` folder, using [XDT syntax](https://msdn.microsoft.com/library/dd465326.aspx) to describe the desired changes. With this option you can also include a `.uninstall.xdt` file to reverse changes when the package is removed from a project. +- Include `app.config.install.xdt` and `web.config.install.xdt` files in your package's `content` folder, using [XDT syntax](/previous-versions/aspnet/dd465326(v=vs.110)) to describe the desired changes. With this option you can also include a `.uninstall.xdt` file to reverse changes when the package is removed from a project. > [!Note] > Transformations are not applied to `.config` files referenced as a link in Visual Studio. @@ -109,7 +107,10 @@ To see the effect of installing and uninstalling the package, create a new ASP.N ### XDT transforms -You can modify config files using [XDT syntax](https://msdn.microsoft.com/library/dd465326.aspx). You can also have NuGet replace tokens with [project properties](/dotnet/api/vslangproj.projectproperties?view=visualstudiosdk-2017&viewFallbackFrom=netframework-4.7) by including the property name within `$` delimiters (case-insensitive). +> [!Note] +> As mentioned in the [package compatibility issues section of the docs for migrating from `packages.config` to `PackageReference`](../consume-packages/migrate-packages-config-to-package-reference.md#package-compatibility-issues), XDT transformations as described below are only supported by `packages.config`. If you add the below files to your package, consumers using your package with `PackageReference` will not have the transformations applied (refer to [this sample](https://github.com/NuGet/Samples/tree/main/XDTransformExample) to make XDT transforms work with`PackageReference`). + +You can modify config files using [XDT syntax](/previous-versions/aspnet/dd465326(v=vs.110)). You can also have NuGet replace tokens with [project properties](/dotnet/api/vslangproj.projectproperties) by including the property name within `$` delimiters (case-insensitive). For example, the following `app.config.install.xdt` file will insert an `appSettings` element into `app.config` containing the `FullPath`, `FileName`, and `ActiveConfigurationSettings` values from the project: diff --git a/docs/create-packages/Supporting-Multiple-Target-Frameworks.md b/docs/create-packages/Supporting-Multiple-Target-Frameworks.md index 3adb50e68..14fc9ffe4 100644 --- a/docs/create-packages/Supporting-Multiple-Target-Frameworks.md +++ b/docs/create-packages/Supporting-Multiple-Target-Frameworks.md @@ -1,17 +1,17 @@ --- title: Multi-targeting for NuGet Packages description: Description of the various methods to target multiple .NET Framework versions from within a single NuGet package. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 07/15/2019 -ms.topic: conceptual +ms.topic: concept-article --- # Support multiple .NET versions Many libraries target a specific version of the .NET Framework. For example, you might have one version of your library that's specific to UWP, and another version that takes advantage of features in .NET Framework 4.6. To accommodate this, NuGet supports putting multiple versions of the same library in a single package. -This article describes the layout of a NuGet package, regardless of how the package or assemblies are built (that is, the layout is the same whether using multiple non-SDK-style *.csproj* files and a custom *.nuspec* file, or a single multi-targetecd SDK-style *.csproj*). For an SDK-style project, NuGet [pack targets](../reference/msbuild-targets.md) knows how the package must be layed out and automates putting the assemblies in the correct lib folders and creating dependency groups for each target framework (TFM). For detailed instructions, see [Support multiple .NET Framework versions in your project file](multiple-target-frameworks-project-file.md). +This article describes the layout of a NuGet package, regardless of how the package or assemblies are built (that is, the layout is the same whether using multiple non-SDK-style *.csproj* files and a custom *.nuspec* file, or a single multi-targeted SDK-style *.csproj*). For an SDK-style project, NuGet [pack targets](../reference/msbuild-targets.md) knows how the package must be layed out and automates putting the assemblies in the correct lib folders and creating dependency groups for each target framework (TFM). For detailed instructions, see [Support multiple .NET Framework versions in your project file](multiple-target-frameworks-project-file.md). You must manually lay out the package as described in this article when using the convention-based working directory method described in [Creating a package](../create-packages/creating-a-package.md#from-a-convention-based-working-directory). For an SDK-style project, the automated method is recommended, but you may also choose to manually lay out the package as described in this article. @@ -19,7 +19,9 @@ You must manually lay out the package as described in this article when using th When building a package that contains only one version of a library or target multiple frameworks, you always make subfolders under `lib` using different case-sensitive framework names with the following convention: - lib\{framework name}[{version}] +``` +lib\{framework name}[{version}] +``` For a complete list of supported names, see the [Target Frameworks reference](../reference/target-frameworks.md#supported-frameworks). @@ -27,15 +29,17 @@ You should never have a version of the library that is not specific to a framewo For example, the following folder structure supports four versions of an assembly that are framework-specific: - \lib - \net46 - \MyAssembly.dll - \net461 - \MyAssembly.dll - \uap - \MyAssembly.dll - \netcore - \MyAssembly.dll +``` +\lib + \net46 + \MyAssembly.dll + \net461 + \MyAssembly.dll + \uap + \MyAssembly.dll + \netcore + \MyAssembly.dll +``` To easily include all these files when building the package, use a recursive `**` wildcard in the `` section of your `.nuspec`: @@ -49,24 +53,26 @@ To easily include all these files when building the package, use a recursive `** If you have architecture-specific assemblies, that is, separate assemblies that target ARM, x86, and x64, you must place them in a folder named `runtimes` within sub-folders named `{platform}-{architecture}\lib\{framework}` or `{platform}-{architecture}\native`. For example, the following folder structure would accommodate both native and managed DLLs targeting Windows 10 and the `uap10.0` framework: - \runtimes - \win10-arm - \native - \lib\uap10.0 - \win10-x86 - \native - \lib\uap10.0 - \win10-x64 - \native - \lib\uap10.0 +``` +\runtimes + \win10-arm + \native + \lib\uap10.0 + \win10-x86 + \native + \lib\uap10.0 + \win10-x64 + \native + \lib\uap10.0 +``` -These assemblies will only be available at runtime, so if you want to provide the corresponding compile time assembly as well then have `AnyCPU` assembly in `/ref{tfm}` folder. +These assemblies will only be available at runtime, so if you want to provide the corresponding compile time assembly as well then have `AnyCPU` assembly in `/ref/{tfm}` folder. -Please note, NuGet always picks these compile or runtime assets from one folder so if there are some compatible assets from `/ref` then `/lib` will be ignored to add compile-time assemblies. Similarly, if there are some compatbile assets from `/runtime` then also `/lib` will be ignored for runtime. +Please note, NuGet always picks these compile or runtime assets from one folder so if there are some compatible assets from `/ref` then `/lib` will be ignored to add compile-time assemblies. Similarly, if there are some compatible assets from `/runtimes` then also `/lib` will be ignored for runtime. See [Create UWP Packages](../guides/create-uwp-packages.md) for an example of referencing these files in the `.nuspec` manifest. -Also, see [Packing a Windows store app component with NuGet](https://blogs.msdn.microsoft.com/mim/2013/09/02/packaging-a-windows-store-apps-component-with-nuget-part-2) +Also, see [Packing a Windows store app component with NuGet](/archive/blogs/mim/packaging-a-windows-store-apps-component-with-nuget-part-2) ## Matching assembly versions and the target framework in a project @@ -76,11 +82,13 @@ If a match is not found, NuGet copies the assembly for the highest version that For example, consider the following folder structure in a package: - \lib - \net45 - \MyAssembly.dll - \net461 - \MyAssembly.dll +``` +\lib + \net45 + \MyAssembly.dll + \net461 + \MyAssembly.dll +``` When installing this package in a project that targets .NET Framework 4.6, NuGet installs the assembly in the `net45` folder, because that's the highest available version that's less than or equal to 4.6. @@ -92,12 +100,14 @@ If the project targets .NET framework 4.0 and earlier, NuGet throws an appropria NuGet copies assemblies from only a single library folder in the package. For example, suppose a package has the following folder structure: - \lib - \net40 - \MyAssembly.dll (v1.0) - \MyAssembly.Core.dll (v1.0) - \net45 - \MyAssembly.dll (v2.0) +``` +\lib + \net40 + \MyAssembly.dll (v1.0) + \MyAssembly.Core.dll (v1.0) + \net45 + \MyAssembly.dll (v2.0) +``` When the package is installed in a project that targets .NET Framework 4.5, `MyAssembly.dll` (v2.0) is the only assembly installed. `MyAssembly.Core.dll` (v1.0) is not installed because it's not listed in the `net45` folder. NuGet behaves this way because `MyAssembly.Core.dll` might have merged into version 2.0 of `MyAssembly.dll`. @@ -107,7 +117,7 @@ If you want `MyAssembly.Core.dll` to be installed for .NET Framework 4.5, place NuGet also supports targeting a specific framework profile by appending a dash and the profile name to the end of the folder. - lib\{framework name}-{profile} +lib\{framework name}-{profile} The supported profiles are as follows: @@ -146,8 +156,8 @@ The following example shows different variations of the `` element: When packaging libraries targeting the Portable Class Library it can be tricky to determine which NuGet target you should use in your folder names and `.nuspec` file, especially if targeting only a subset of the PCL. The following external resources will help you with this: -- [Framework profiles in .NET](http://blog.stephencleary.com/2012/05/framework-profiles-in-net.html) (stephencleary.com) -- [Portable Class Library profiles](http://embed.plnkr.co/03ck2dCtnJogBKHJ9EjY/preview) (plnkr.co): Table enumerating PCL profiles and their equivalent NuGet targets +- [Framework profiles in .NET](https://blog.stephencleary.com/2012/05/framework-profiles-in-net.html) (stephencleary.com) +- [Portable Class Library profiles](https://embed.plnkr.co/03ck2dCtnJogBKHJ9EjY/preview) (plnkr.co): Table enumerating PCL profiles and their equivalent NuGet targets - [Portable Class Library profiles tool](https://github.com/StephenCleary/PortableLibraryProfiles) (github.com): command line tool for determining PCL profiles available on your system ## Content files and PowerShell scripts @@ -157,22 +167,24 @@ When packaging libraries targeting the Portable Class Library it can be tricky t With `packages.config`, content files and PowerShell scripts can be grouped by target framework using the same folder convention inside the `content` and `tools` folders. For example: - \content - \net46 - \MyContent.txt - \net461 - \MyContent461.txt - \uap - \MyUWPContent.html - \netcore - \tools - init.ps1 - \net46 - install.ps1 - uninstall.ps1 - \uap - install.ps1 - uninstall.ps1 +``` +\content + \net46 + \MyContent.txt + \net461 + \MyContent461.txt + \uap + \MyUWPContent.html + \netcore +\tools + init.ps1 + \net46 + install.ps1 + uninstall.ps1 + \uap + install.ps1 + uninstall.ps1 +``` If a framework folder is left empty, NuGet doesn't add assembly references or content files or run the PowerShell scripts for that framework. diff --git a/docs/create-packages/Symbol-Packages-snupkg.md b/docs/create-packages/Symbol-Packages-snupkg.md index 47484162a..ea43a75f9 100644 --- a/docs/create-packages/Symbol-Packages-snupkg.md +++ b/docs/create-packages/Symbol-Packages-snupkg.md @@ -1,11 +1,10 @@ --- title: How to publish NuGet symbol packages using the new symbol package format '.snupkg'| Microsoft Docs -author: cristinamanu -ms.author: cristinamanu +author: JonDouglas +ms.author: jodou manager: skofman ms.date: 10/30/2018 ms.topic: reference -ms.prod: nuget ms.technology: null description: How to create NuGet symbol packages (snupkg). keywords: NuGet symbol packages, NuGet package debugging, supporting NuGet debugging, package symbols, symbol package conventions @@ -16,28 +15,31 @@ ms.reviewer: # Creating symbol packages (.snupkg) -Symbol packages allow you to improve the debugging experience of your NuGet packages. +A good debugging experience relies on the presence of debug symbols as they provide critical information like the association between the compiled and the source code, names of local variables, stack traces, and more. You can use symbol packages (.snupkg) to distribute these symbols and improve the debugging experience of your NuGet packages. + +> Note that symbol package isn't the only strategy to make the debug symbols available to the consumers of your library. It's also [possible to `embed`](/dotnet/core/deploying/single-file#include-pdb-files-inside-the-bundle) them in the `dll` or `exe` with the following project property: +> `embedded` ## Prerequisites -[nuget.exe v4.9.0 or above](https://www.nuget.org/downloads) or [dotnet.exe v2.2.0 or above](https://www.microsoft.com/net/download/dotnet-core/2.2), which implement the required [NuGet protocols](../api/nuget-protocols.md). +[nuget.exe v4.9.0 or above](https://www.nuget.org/downloads) or [dotnet CLI v2.2.0 or above](https://www.microsoft.com/net/download/dotnet-core/2.2), which implement the required [NuGet protocols](../api/nuget-protocols.md). ## Creating a symbol package -If you're using dotnet.exe or MSBuild, you need to set the `IncludeSymbols` and `SymbolPackageFormat` properties to create a .snupkg file in addition to the .nupkg file. +If you're using dotnet CLI or MSBuild, you need to set the `IncludeSymbols` and `SymbolPackageFormat` properties to create a .snupkg file in addition to the .nupkg file. * Either add the following properties to your .csproj file: ```xml - true - snupkg + true + snupkg ``` * Or specify these properties on the command-line: - ```cli + ```dotnetcli dotnet pack MyPackage.csproj -p:IncludeSymbols=true -p:SymbolPackageFormat=snupkg ``` @@ -49,7 +51,7 @@ If you're using dotnet.exe or MSBuild, you need to set the `IncludeSymbols` and If you're using NuGet.exe, you can use the following commands to create a .snupkg file in addition to the .nupkg file: -``` +```cli nuget pack MyPackage.nuspec -Symbols -SymbolPackageFormat snupkg nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg @@ -58,10 +60,13 @@ nuget pack MyPackage.csproj -Symbols -SymbolPackageFormat snupkg The [`SymbolPackageFormat`](/dotnet/core/tools/csproj#symbolpackageformat) property can have one of two values: `symbols.nupkg` (the default) or `snupkg`. If this property is not specified, a legacy symbol package will be created. > [!Note] -> The legacy format `.symbols.nupkg` is still supported but only for compatibility reasons (see [Legacy Symbol Packages](Symbol-Packages.md)). NuGet.org's symbol server only accepts the new symbol package format - `.snupkg`. +> The legacy format `.symbols.nupkg` is still supported but only for compatibility reasons like native packages (see [Legacy Symbol Packages](Symbol-Packages.md)). NuGet.org's symbol server only accepts the new symbol package format - `.snupkg`. ## Publishing a symbol package +> [!Note] +> [Azure Devops Artifacts](https://azure.microsoft.com/services/devops/artifacts) does not currently support debugging via `.snupkg` files. + 1. For convenience, first save your API key with NuGet (see [publish a package](../nuget-org/publish-a-package.md)). ```cli @@ -94,26 +99,29 @@ NuGet.org supports its own symbols server repository and only accepts the new sy NuGet.org has the following constraints for symbol packages: - Only the following file extensions are allowed in symbol packages: `.pdb`, `.nuspec`, `.xml`, `.psmdcp`, `.rels`, `.p7s` -- Only managed [Portable PDBs](https://github.com/dotnet/corefx/blob/master/src/System.Reflection.Metadata/specs/PortablePdb-Metadata.md) are supported on NuGet.org's symbol server. +- Only managed [Portable PDBs](https://github.com/dotnet/runtime/blob/87572a799bfd37779c079faf28544e3f9a16be58/src/libraries/System.Reflection.Metadata/specs/PortablePdb-Metadata.md) are supported on NuGet.org's symbol server. - The PDBs and their associated .nupkg DLLs need to be built with the compiler in Visual Studio version 15.9 or above (see [PDB crypto hash](https://github.com/dotnet/roslyn/issues/24429)) Symbol packages published to NuGet.org will fail validation if these constraints aren't met. +> [!NOTE] +> Native projects, such as C++ projects, produce Windows PDBs instead of Portable PDBs. These are not supported by NuGet.org's symbol server. Please use [Legacy Symbol Packages](Symbol-Packages.md) instead. + ### Symbol package validation and indexing Symbol packages published to [NuGet.org](https://www.nuget.org/) undergo several validations, including malware scanning. If a package fails a validation check, its package details page will display an error message. In addition, the package's owners will receive an email with instructions on how to fix the identified issues. -When the symbol package has passed all validations, the symbols will be indexed by NuGet.org's symbol servers. Once indexed, the symbol will be available for consumption from the NuGet.org symbol servers. +When the symbol package has passed all validations, the symbols will be indexed by NuGet.org's symbol servers and will be available for consumption. -Package validation and indexing usually takes under 15 minutes. If the package publishing is taking longer than expected, visit [status.nuget.org](https://status.nuget.org/) to check if NuGet.org is experiencing any interruptions. If all systems are operational and the package hasn't been successfully published within an hour, please login to nuget.org and contact us using the Contact Support link on the package details page. +Package validation and indexing usually takes under 15 minutes. If the package publishing takes longer than expected, visit [status.nuget.org](https://status.nuget.org/) to check if NuGet.org is experiencing any interruptions. If all systems are operational and the package hasn't been successfully published within an hour, please login to nuget.org and contact us using the Contact Support link on the package details page. ## Symbol package structure -The .nupkg file would be exactly the same as it is today, but the .snupkg file would have the following characteristics: +The symbol package (.snupkg) has the following characteristics: -1) The .snupkg will have the same id and version as the corresponding .nupkg. -2) The .snupkg will have the exact folder structure as the nupkg for any DLL or EXE files with the distinction that instead of DLLs/EXEs, their corresponding PDBs will be included in the same folder hierarchy. Files and folders with extensions other than PDB will be left out of the snupkg. -3) The .nuspec file in the .snupkg will also specify a new PackageType as below. This should the only one PackageType specified. +1) The .snupkg has the same id and version as its corresponding NuGet package (.nupkg). +2) The .snupkg has the same folder structure as its corresponding .nupkg for any DLL or EXE files with the distinction that instead of DLLs/EXEs, their corresponding PDBs will be included in the same folder hierarchy. Files and folders with extensions other than PDB will be left out of the snupkg. +3) The symbol package's .nuspec file has the `SymbolsPackage` package type: ```xml @@ -122,10 +130,10 @@ The .nupkg file would be exactly the same as it is today, but the .snupkg file w ``` 4) If an author decides to use a custom nuspec to build their nupkg and snupkg, the snupkg should have the same folder hierarchy and files detailed in 2). -5) ```authors``` and ```owners``` field will be excluded from the snupkg's nuspec. +5) The following fields will be excluded from the snupkg's nuspec: ```authors```, ```owners```, ```requireLicenseAcceptance```, ```license type```, ```licenseUrl```, and ```icon```. 6) Do not use the `````` element. A .snupkg is covered under the same license as the corresponding .nupkg. -## See Also +## See also Consider using Source Link to enable source code debugging of .NET assemblies. For more information, please refer to the [Source Link guidance](/dotnet/standard/library-guidance/sourcelink). diff --git a/docs/create-packages/Symbol-Packages.md b/docs/create-packages/Symbol-Packages.md index 322d20ffe..ae6f7387b 100644 --- a/docs/create-packages/Symbol-Packages.md +++ b/docs/create-packages/Symbol-Packages.md @@ -1,29 +1,27 @@ --- -title: How to create NuGet symbol packages +title: Creating legacy symbol packages (.symbols.nupkg) description: How to create NuGet packages that contain only symbols to support debugging of other NuGet packages in Visual Studio. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 09/12/2017 -ms.topic: conceptual +ms.topic: how-to ms.reviewer: anangaur --- -# Creating symbol packages (legacy) +# Creating legacy symbol packages (.symbols.nupkg) > [!Important] > The new recommended format for symbol packages is .snupkg. See [Creating symbol packages (.snupkg)](Symbol-Packages-snupkg.md).
    > .symbols.nupkg is still supported but only for compatibility reasons. -In addition to building packages for nuget.org or other sources, NuGet also supports creating associated symbol packages and publishing them to the SymbolSource repository. +In addition to building packages for nuget.org or other sources, NuGet also supports creating associated symbol packages that can be published to symbol servers. -Package consumers can then add `https://nuget.smbsrc.net` to their symbol sources in Visual Studio, which allows stepping into package code in the Visual Studio debugger. See [Specify symbol (.pdb) and source files in the Visual Studio debugger](/visualstudio/debugger/specify-symbol-dot-pdb-and-source-files-in-the-visual-studio-debugger) for details on that process. +## Creating a legacy symbol package -## Creating a symbol package - -To create a symbol package, follow these conventions: +To create a legacy symbol package, follow these conventions: - Name the primary package (with your code) `{identifier}.nupkg` and include all your files except `.pdb` files. -- Name the symbol package `{identifier}.symbols.nupkg` and include your assembly DLL, `.pdb` files, XMLDOC files, source files (see the sections that follow). +- Name the legacy symbol package `{identifier}.symbols.nupkg` and include your assembly DLL, `.pdb` files, XMLDOC files, source files (see the sections that follow). You can create both packages with the `-Symbols` option, either from a `.nuspec` file or a project file: @@ -35,52 +33,58 @@ nuget pack MyProject.csproj -Symbols Note that `pack` requires Mono 4.4.2 on Mac OS X and does not work on Linux systems. On a Mac, you must also convert Windows pathnames in the `.nuspec` file to Unix-style paths. -## Symbol package structure +## Legacy symbol package structure -A symbol package can target multiple target frameworks in the same way that a library package does, so the structure of the `lib` folder should be exactly the same as the primary package, only including `.pdb` files alongside the DLL. +A legacy symbol package can target multiple target frameworks in the same way that a library package does, so the structure of the `lib` folder should be exactly the same as the primary package, only including `.pdb` files alongside the DLL. -For example, a symbol package that targets .NET 4.0 and Silverlight 4 would have this layout: +For example, a legacy symbol package that targets .NET 4.0 and Silverlight 4 would have this layout: - \lib - \net40 - \MyAssembly.dll - \MyAssembly.pdb - \sl40 - \MyAssembly.dll - \MyAssembly.pdb +``` +\lib + \net40 + \MyAssembly.dll + \MyAssembly.pdb + \sl40 + \MyAssembly.dll + \MyAssembly.pdb +``` Source files are then placed in a separate special folder named `src`, which must follow the relative structure of your source repository. This is because PDBs contain absolute paths to source files used to compile the matching DLL, and they need to be found during the publishing process. A base path (common path prefix) can be stripped out. For example, consider a library built from these files: - C:\Projects - \MyProject - \Common - \MyClass.cs - \Full - \Properties - \AssemblyInfo.cs - \MyAssembly.csproj (producing \lib\net40\MyAssembly.dll) - \Silverlight - \Properties - \AssemblyInfo.cs - \MySilverlightExtensions.cs - \MyAssembly.csproj (producing \lib\sl4\MyAssembly.dll) - -Apart from the `lib` folder, a symbol package would need to contain this layout: - - \src +``` +C:\Projects + \MyProject \Common \MyClass.cs \Full \Properties \AssemblyInfo.cs + \MyAssembly.csproj (producing \lib\net40\MyAssembly.dll) \Silverlight \Properties \AssemblyInfo.cs \MySilverlightExtensions.cs + \MyAssembly.csproj (producing \lib\sl4\MyAssembly.dll) +``` + +Apart from the `lib` folder, a legacy symbol package would need to contain this layout: + +``` +\src + \Common + \MyClass.cs + \Full + \Properties + \AssemblyInfo.cs + \Silverlight + \Properties + \AssemblyInfo.cs + \MySilverlightExtensions.cs +``` ## Referring to files in the nuspec -A symbol package can be built by conventions, from a folder structure as described in the previous section, or by specifying its contents in the `files` section of the manifest. For example, to build the package shown in the previous section, use the following in the `.nuspec` file: +A legacy symbol package can be built by conventions, from a folder structure as described in the previous section, or by specifying its contents in the `files` section of the manifest. For example, to build the package shown in the previous section, use the following in the `.nuspec` file: ```xml @@ -92,40 +96,6 @@ A symbol package can be built by conventions, from a folder structure as describ ``` -## Publishing a symbol package - -> [!Important] -> To push packages to nuget.org you must use [nuget.exe v4.9.1 or above](https://www.nuget.org/downloads), which implements the required [NuGet protocols](../api/nuget-protocols.md). - -1. For convenience, first save your API key with NuGet (see [publish a package](../nuget-org/publish-a-package.md), which will apply to both nuget.org and symbolsource.org, because symbolsource.org will check with nuget.org to verify that you are the package owner. - - ```cli - nuget SetApiKey Your-API-Key - ``` - -2. After publishing your primary package to nuget.org, push the symbol package as follows, which will automatically use symbolsource.org as the target because of the `.symbols` in the filename: - - ```cli - nuget push MyPackage.symbols.nupkg - ``` - -3. To publish to a different symbol repository, or to push a symbol package that doesn't follow the naming convention, use the `-Source` option: - - ```cli - nuget push MyPackage.symbols.nupkg -source https://nuget.smbsrc.net/ - ``` - -4. You can also push both primary and symbol packages to both repositories at the same time using the following: - - ```cli - nuget push MyPackage.nupkg - ``` - - > [!Note] - > With nuget.exe 4.5.0 or above, the symbols packages are not automatically pushed to symbolsource.org. You would need to push the symbols packages separately as explained in the earlier steps. - -In this case, NuGet will publish `MyPackage.symbols.nupkg`, if present, to https://nuget.smbsrc.net/ (the push URL for symbolsource.org), after it publishes the primary package to nuget.org. - -## See Also +## See also -[Moving to the new SymbolSource engine](https://tripleemcoder.com/2015/10/04/moving-to-the-new-symbolsource-engine/) (symbolsource.org) +* [Creating symbol packages (.snupkg)](Symbol-Packages-snupkg.md) - The new recommended format for symbol packages diff --git a/docs/create-packages/author-packages-with-COM-interop-assemblies.md b/docs/create-packages/author-packages-with-COM-interop-assemblies.md index baedc7736..6c4a61385 100644 --- a/docs/create-packages/author-packages-with-COM-interop-assemblies.md +++ b/docs/create-packages/author-packages-with-COM-interop-assemblies.md @@ -1,15 +1,15 @@ --- title: Create packages with COM interop assemblies description: Describes how to create packages that contain COM interop assemblies -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 07/09/2019 -ms.topic: conceptual +ms.topic: article --- -## Create NuGet packages that contain COM interop assemblies +# Create NuGet packages that contain COM interop assemblies -Packages that contain COM interop assemblies must include an appropriate [targets file](creating-a-package.md#include-msbuild-props-and-targets-in-a-package) so that the correct `EmbedInteropTypes` metadata is added to projects using the PackageReference format. By default, the `EmbedInteropTypes` metadata is always false for all assemblies when PackageReference is used, so the targets file adds this metadata explicitly. To avoid conflicts, the target name should be unique; ideally, use a combination of your package name and the assembly being embedded, replacing the `{InteropAssemblyName}` in the example below with that value. (Also see [NuGet.Samples.Interop](https://github.com/NuGet/Samples/tree/master/NuGet.Samples.Interop) for an example.) +Packages that contain COM interop assemblies must include an appropriate [targets file](creating-a-package.md#include-msbuild-props-and-targets-in-a-package) so that the correct `EmbedInteropTypes` metadata is added to projects using the PackageReference format. By default, the `EmbedInteropTypes` metadata is always false for all assemblies when PackageReference is used, so the targets file adds this metadata explicitly. To avoid conflicts, the target name should be unique; ideally, use a combination of your package name and the assembly being embedded, replacing the `{InteropAssemblyName}` in the example below with that value. (Also see [NuGet.Samples.Interop](https://github.com/NuGet/Samples/tree/main/NuGet.Samples.Interop) for an example.) ```xml @@ -21,8 +21,8 @@ Packages that contain COM interop assemblies must include an appropriate [target ``` -Note that when using the `packages.config` management format, adding references to the assemblies from the packages causes NuGet and Visual Studio to check for COM interop assemblies and set the `EmbedInteropTypes` to true in the project file. In this case the targets are overriden. +Note that when using the `packages.config` management format, adding references to the assemblies from the packages causes NuGet and Visual Studio to check for COM interop assemblies and set the `EmbedInteropTypes` to true in the project file. In this case, the targets are overridden. Additionally, by default the [build assets do not flow transitively](../consume-packages/package-references-in-project-files.md#controlling-dependency-assets). Packages authored as described here work differently when they are pulled as a transitive dependency from a project to project reference. The package consumer can allow them to flow by modifying the PrivateAssets default value to not include build. - \ No newline at end of file + diff --git a/docs/create-packages/creating-a-package-dotnet-cli.md b/docs/create-packages/creating-a-package-dotnet-cli.md index a46923572..2917a2ec0 100644 --- a/docs/create-packages/creating-a-package-dotnet-cli.md +++ b/docs/create-packages/creating-a-package-dotnet-cli.md @@ -1,129 +1,134 @@ --- -title: Create a NuGet package using the dotnet CLI -description: A detailed guide to the process of designing and creating a NuGet package, including key decision points like files and versioning. -author: karann-msft -ms.author: karann -ms.date: 07/09/2019 -ms.topic: conceptual +title: Create a NuGet package with the dotnet CLI +description: Read a detailed guide about the process of designing and creating a NuGet package, including key decision points like files and versioning. +author: JonDouglas +ms.author: jodou +ms.date: 03/03/2025 +ms.topic: how-to --- -# Create a NuGet package using the dotnet CLI +# Create a NuGet package with the dotnet CLI -No matter what your package does or what code it contains, you use one of the CLI tools, either `nuget.exe` or `dotnet.exe`, to package that functionality into a component that can be shared with and used by any number of other developers. This article describes how to create a package using the dotnet CLI. To install the `dotnet` CLI, see [Install NuGet client tools](../install-nuget-client-tools.md). Starting in Visual Studio 2017, the dotnet CLI is included with .NET Core workloads. +NuGet packages contain code that developers can reuse in their projects. No matter what your code does or contains, you use a command-line tool, either `nuget.exe` or `dotnet.exe`, to create the NuGet package. -For .NET Core and .NET Standard projects that use the [SDK-style format](../resources/check-project-format.md), and any other SDK-style projects, NuGet uses information in the project file directly to create a package. For step-by-step tutorials, see [Create .NET Standard Packages with dotnet CLI](../quickstart/create-and-publish-a-package-using-the-dotnet-cli.md) or [Create .NET Standard Packages with Visual Studio](../quickstart/create-and-publish-a-package-using-visual-studio.md). +This article describes how to create a package by using the [dotnet CLI](). Starting in Visual Studio 2017, the dotnet CLI is included with all .NET and .NET Core workloads. If you need to install the dotnet CLI or other NuGet client tools, see [Install NuGet client tools](../install-nuget-client-tools.md). -`msbuild -t:pack` is functionality equivalent to `dotnet pack`. To build with MSBuild, see [Create a NuGet package using MSBuild](creating-a-package-msbuild.md). +This topic applies only to .NET and other projects that use the [SDK-style format](../resources/check-project-format.md). For these projects, NuGet uses information from the project file to create a package. For quickstart tutorials, see [Create packages with the dotnet CLI](../quickstart/create-and-publish-a-package-using-the-dotnet-cli.md) or [Create packages with Visual Studio](../quickstart/create-and-publish-a-package-using-visual-studio.md). -> [!IMPORTANT] -> This topic applies to [SDK-style](../resources/check-project-format.md) projects, typically .NET Core and .NET Standard projects. - -## Set properties +The MSBuild [msbuild -t:pack](creating-a-package-msbuild.md#run-the-msbuild--tpack-command) command is functionally equivalent to [dotnet pack](/dotnet/core/tools/dotnet-pack). For more information about creating a package with MSBuild, see [Create a NuGet package using MSBuild](creating-a-package-msbuild.md). -The following properties are required to create a package. +> [!NOTE] +> - To create and publish packages for non-SDK-style projects, typically .NET Framework projects, see [Create a package using the nuget.exe CLI](Creating-a-Package.md) or [Create and publish a package using Visual Studio (.NET Framework)](../quickstart/create-and-publish-a-package-using-visual-studio-net-framework.md). +> +> - For projects migrated from *packages.config* to [PackageReference](../consume-packages/package-references-in-project-files.md), use `msbuild -t:pack`. For more information, see [Create a package after migration](../consume-packages/migrate-packages-config-to-package-reference.md#create-a-package-after-migration). -- `PackageId`, the package identifier, which must be unique across the gallery that hosts the package. If not specified, the default value is `AssemblyName`. -- `Version`, a specific version number in the form *Major.Minor.Patch[-Suffix]* where *-Suffix* identifies [pre-release versions](prerelease-packages.md). If not specified, the default value is 1.0.0. -- The package title as it should appear on the host (like nuget.org) -- `Authors`, author and owner information. If not specified, the default value is `AssemblyName`. -- `Company`, your company name. If not specified, the default value is `AssemblyName`. +## Set properties -In Visual Studio, you can set these values in the project properties (right-click the project in Solution Explorer, choose **Properties**, and select the **Package** tab). You can also set these properties directly in the project files (`.csproj`). +You can create an example class library project by using the `dotnet new classlib` command, and package the project by using `dotnet pack`. The `dotnet pack` command uses the following properties. If you don't specify values in the project file, the command uses default values. -```xml - - AppLogger - 1.0.0 - your_name - your_company - -``` +- `PackageId`, the package identifier, must be unique across nuget.org and any other targets that host the package. If you don't specify a value, the command uses the `AssemblyName`. +- `Version` is a specific version number in the form `Major.Minor.Patch[-Suffix]`, where `-Suffix` identifies [prerelease versions](prerelease-packages.md). If not specified, the default value is `1.0.0`. +- `Authors` are the authors of the package. If not specified, the default value is the `AssemblyName`. +- `Company` is company information. If not specified, the default value is the `Authors` value. +- `Product` is product information. If not specified, the default value is the `AssemblyName`. -> [!Important] -> Give the package an identifier that's unique across nuget.org or whatever package source you're using. +In Visual Studio, you can set these values in the project properties. Right-click the project in **Solution Explorer**, select **Properties**, and then select the **Package** section. You can also add the properties directly to the *.csproj* or other project file. -The following example shows a simple, complete project file with these properties included. (You can create a new default project using the `dotnet new classlib` command.) +The following example shows a project file with package properties added. ```xml netstandard2.0 - AppLogger + UniqueID 1.0.0 - your_name - your_company + Author Name + Company Name + Product Name ``` -You can also set the optional properties, such as `Title`, `PackageDescription`, and `PackageTags`, as described in [MSBuild pack targets](../reference/msbuild-targets.md#pack-target), [Controlling dependency assets](../consume-packages/package-references-in-project-files.md#controlling-dependency-assets), and [NuGet metadata properties](/dotnet/core/tools/csproj#nuget-metadata-properties). +You can add other optional properties, such as `Title`, `PackageDescription`, and `PackageTags`. -> [!NOTE] -> For packages built for public consumption, pay special attention to the **PackageTags** property, as tags help others find your package and understand what it does. +>[!NOTE] +> For packages you build for public consumption, pay special attention to the `PackageTags` property. Tags help others find your package and understand what it does. -For details on declaring dependencies and specifying version numbers, see [Package references in project files](../consume-packages/package-references-in-project-files.md) and [Package versioning](../concepts/package-versioning.md). It is also possible to surface assets from dependencies directly in the package by using the `` and `` attributes. For more information, seee [Controlling dependency assets](../consume-packages/package-references-in-project-files.md#controlling-dependency-assets). +The `dotnet pack` command automatically converts `PackageReference`s in your project files to dependencies in the created package. You can control which assets to include through the `IncludeAssets`, `ExcludeAssets` and `PrivateAssets` tags. For more information, see [Controlling dependency assets](../consume-packages/package-references-in-project-files.md#controlling-dependency-assets). -## Choose a unique package identifier and set the version number +For more information about dependencies, optional properties, and versioning, see: + +- [Package references in project files](../consume-packages/package-references-in-project-files.md) +- [Package versioning](../concepts/package-versioning.md) +- [NuGet metadata properties](/dotnet/core/tools/csproj#nuget-metadata-properties) +- [MSBuild pack targets](../reference/msbuild-targets.md#pack-target) + +### Choose a unique package identifier and set the version number [!INCLUDE [choose-package-id](includes/choose-package-id.md)] +### Add an optional description field + +[!INCLUDE [add description to package](includes/add-description.md)] + ## Run the pack command -To build a NuGet package (a `.nupkg` file) from the project, run the `dotnet pack` command, which also builds the project automatically: +To build the NuGet package or *.nupkg* file, run the [dotnet pack](/dotnet/core/tools/dotnet-pack) command from the project folder, which also builds the project automatically. -```cli -# Uses the project file in the current folder by default +```dotnetcli dotnet pack ``` -The output shows the path to the `.nupkg` file. +The output shows the path to the *.nupkg* file: ```output -Microsoft (R) Build Engine version 15.5.180.51428 for .NET Core -Copyright (C) Microsoft Corporation. All rights reserved. - - Restore completed in 29.91 ms for D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj. - AppLogger -> D:\proj\AppLoggerNet\AppLogger\bin\Debug\netstandard2.0\AppLogger.dll +MSBuild version 17.3.0+92e077650 for .NET + Determining projects to restore... + Restored D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj (in 97 ms). Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'. ``` ### Automatically generate package on build -To automatically run `dotnet pack` when you run `dotnet build`, add the following line to your project file within ``: +To automatically run `dotnet pack` whenever you run `dotnet build`, add the following line to your project file in the `` tag: ```xml true ``` -When you run `dotnet pack` on a solution, this packs all the projects in the solution that are packable ([](/dotnet/core/tools/csproj#nuget-metadata-properties) property is set to `true`). - > [!NOTE] -> When you automatically generate the package, the time to pack increases the build time for your project. +> When you automatically generate the package, packing increases the build time for your project. + +Running `dotnet pack` on a solution packs all the projects in the solution that are packable, that is, have the `IsPackable` property set to `true`. ### Test package installation -Before publishing a package, you typically want to test the process of installing a package into a project. The tests make sure that the necessarily files all end up in their correct places in the project. +Before you publish a package, you should test installing the package into a project. Testing ensures that the necessary files end up in their correct places in the project. -You can test installations manually in Visual Studio or on the command line using the normal [package installation steps](../consume-packages/overview-and-workflow.md#ways-to-install-a-nuget-package). +Test the installation manually in Visual Studio or on the command line by using the normal [package installation process](../consume-packages/overview-and-workflow.md#ways-to-install-a-nuget-package). > [!IMPORTANT] -> Packages are immutable. If you correct a problem, change the contents of the package and pack again, when you retest you will still be using the old version of the package until you [clear your global packages](../consume-packages/managing-the-global-packages-and-cache-folders.md#clearing-local-folders) folder. This is especially relevant when testing packages that don't use a unique prerelease label on every build. +> - You can't change packages once created. If you correct a problem, change the package contents and repack. +> +> - After you recreate the package, retesting still uses the old version of the package until you [clear your global packages folder](../consume-packages/managing-the-global-packages-and-cache-folders.md#clearing-local-folders). Clearing the folder is especially important for packages that don't use a unique prerelease label on every build. + +## Next steps -## Next Steps +Once you create the package, you can publish the *.nupkg* file to the host of your choice. -Once you've created a package, which is a `.nupkg` file, you can publish it to the gallery of your choice as described on [Publishing a Package](../nuget-org/publish-a-package.md). +> [!div class="nextstepaction"] +> [Publish a package](../nuget-org/publish-a-package.md) -You might also want to extend the capabilities of your package or otherwise support other scenarios as described in the following topics: +See the following articles for ways to extend the capabilities of your package or support other scenarios: - [Package versioning](../concepts/package-versioning.md) - [Support multiple target frameworks](../create-packages/multiple-target-frameworks-project-file.md) +- [Add a package icon](../reference/nuspec.md#icon) - [Transformations of source and configuration files](../create-packages/source-and-config-file-transformations.md) - [Localization](../create-packages/creating-localized-packages.md) -- [Pre-release versions](../create-packages/prerelease-packages.md) +- [Prerelease versions](../create-packages/prerelease-packages.md) - [Set package type](../create-packages/set-package-type.md) +- [MSBuild props and targets](../concepts/MSBuild-props-and-targets.md) - [Create packages with COM interop assemblies](../create-packages/author-packages-with-COM-interop-assemblies.md) - -Finally, there are additional package types to be aware of: - -- [Native Packages](../guides/native-packages.md) -- [Symbol Packages](../create-packages/symbol-packages.md) +- [Create native packages](../guides/native-packages.md) +- [Create symbol packages (.snupkg)](symbol-packages-snupkg.md) diff --git a/docs/create-packages/creating-a-package-msbuild.md b/docs/create-packages/creating-a-package-msbuild.md index dc0551270..48f58e902 100644 --- a/docs/create-packages/creating-a-package-msbuild.md +++ b/docs/create-packages/creating-a-package-msbuild.md @@ -1,21 +1,24 @@ --- title: Create a NuGet package using MSBuild -description: A detailed guide to the process of designing and creating a NuGet package, including key decision points like files and versioning. -author: karann-msft -ms.author: karann -ms.date: 08/05/2019 -ms.topic: conceptual +description: A detailed guide to the process of designing and creating a NuGet package using MSBuild, including key decision points like files and versioning. +author: JonDouglas +ms.author: jodou +ms.date: 08/17/2023 +ms.topic: how-to --- # Create a NuGet package using MSBuild -When you create a NuGet package from your code, you package that functionality into a component that can be shared with and used by any number of other developers. This article describes how to create a package using MSBuild. MSBuild comes preinstalled with every Visual Studio workload that contains NuGet. Additionally you can also use MSBuild through the dotnet CLI with [dotnet msbuild](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-msbuild) +When you create a NuGet package from your code, you package that functionality into a component that can be shared with and used by any number of other developers. This article describes how to create a package using MSBuild. MSBuild comes preinstalled with every Visual Studio workload that contains NuGet. Additionally you can also use MSBuild through the dotnet CLI with [dotnet msbuild](/dotnet/core/tools/dotnet-msbuild). For .NET Core and .NET Standard projects that use the [SDK-style format](../resources/check-project-format.md), and any other SDK-style projects, NuGet uses information in the project file directly to create a package. For a non-SDK-style project that uses ``, NuGet also uses the project file to create a package. -SDK-style projects have the pack functionality available by default. For non SDK-style PackageReference projects, you need to add the NuGet.Build.Tasks.Pack package to the project dependencies. For detailed information about MSBuild pack targets, see [NuGet pack and restore as MSBuild targets](../reference/msbuild-targets.md). +SDK-style projects have the pack functionality available by default. +For non-SDK-style PackageReference projects, it is also available by default starting from Visual Studio 2026. +In earlier versions of Visual Studio you need to add the NuGet.Build.Tasks.Pack package to the project dependencies and we recommend removing this package reference when upgrading to Visual Studio 2026. +For detailed information about MSBuild pack targets, see [NuGet pack and restore as MSBuild targets](../reference/msbuild-targets.md). -The command that creates a package, `msbuild -t:pack`, is functionality equivalent to `dotnet pack`. +For SDK-style projects, `msbuild -t:pack` is functionally equivalent to `dotnet pack`. > [!IMPORTANT] > This topic applies to [SDK-style](../resources/check-project-format.md) projects, typically .NET Core and .NET Standard projects, and to non-SDK-style projects that use PackageReference. @@ -30,6 +33,10 @@ The following properties are required to create a package. - `Authors`, author and owner information. If not specified, the default value is `AssemblyName`. - `Company`, your company name. If not specified, the default value is `AssemblyName`. +Additionally if you are packing non-SDK-style projects that use PackageReference, the following is required: + +- `PackageOutputPath`, the output folder for the package generated when calling pack. + In Visual Studio, you can set these values in the project properties (right-click the project in Solution Explorer, choose **Properties**, and select the **Package** tab). You can also set these properties directly in the project files (*.csproj*). ```xml @@ -65,29 +72,53 @@ You can also set the optional properties, such as `Title`, `PackageDescription`, For details on declaring dependencies and specifying version numbers, see [Package references in project files](../consume-packages/package-references-in-project-files.md) and [Package versioning](../concepts/package-versioning.md). It is also possible to surface assets from dependencies directly in the package by using the `` and `` attributes. For more information, seee [Controlling dependency assets](../consume-packages/package-references-in-project-files.md#controlling-dependency-assets). +## Add an optional description field + +[!INCLUDE [add description to package](includes/add-description.md)] + ## Choose a unique package identifier and set the version number [!INCLUDE [choose-package-id](includes/choose-package-id.md)] -## Add the NuGet.Build.Tasks.Pack package +## Configure project for pack + +SDK-style projects do not require any additional configuration. + +Non-SDK-style projects either need at least one package installed (via PackageReference, not packages.config), or the project explicitly needs to instruct NuGet to treat the project as a PackageReference project via the `RestoreProjectStyle` property. -If you are using MSBuild with a non-SDK-style project and PackageReference, add the NuGet.Build.Tasks.Pack package to your project. +Visual Studio 2022 and earlier does not have pack built-in, so you also need to install the NuGet.Build.Tasks.Pack package. +When upgrading to Visual Studio 2026 or later, we recommend uninstalling the package, so that you benefit from new features and bug fixes. + +1. Edit the project file. + + If you want to explicitly instruct NuGet to treat the project as PackageReference (the project does not have any packages installed), find or add a `` that does not have any `Condition` statement, and add: + + ```xml + + + PackageReference + + + ``` -1. Open the project file and add the following after the `` element: + If you are using Visual Studio 2022 or earlier, add the following after the `` element: ```xml - + ``` + + > [!NOTE] + > [Consider using the latest version of this package available.](https://www.nuget.org/packages/nuget.build.tasks.pack) 2. Open a Developer command prompt (In the **Search** box, type **Developer command prompt**). You typically want to start the Developer Command Prompt for Visual Studio from the **Start** menu, as it will be configured with all the necessary paths for MSBuild. -3. Switch to the folder containing the project file and type the following command to install the NuGet.Build.Tasks.Pack package. +3. Switch to the folder containing the project file and type the following command to restore the NuGet.Build.Tasks.Pack package. ```cmd # Uses the project file in the current folder by default @@ -144,7 +175,7 @@ To automatically run `msbuild -t:pack` when you build or restore the project, ad true ``` -When you run `msbuild -t:pack` on a solution, this packs all the projects in the solution that are packable ([](/dotnet/core/tools/csproj#nuget-metadata-properties) property is set to `true`). +When you run `msbuild -t:pack` on a solution, this packs all the projects in the solution that are packable ([``](/dotnet/core/tools/csproj#nuget-metadata-properties) property is set to `true`). > [!NOTE] > When you automatically generate the package, the time to pack increases the build time for your project. @@ -171,9 +202,10 @@ You might also want to extend the capabilities of your package or otherwise supp - [Localization](../create-packages/creating-localized-packages.md) - [Pre-release versions](../create-packages/prerelease-packages.md) - [Set package type](../create-packages/set-package-type.md) +- [MSBuild props and targets](../concepts/MSBuild-props-and-targets.md) - [Create packages with COM interop assemblies](../create-packages/author-packages-with-COM-interop-assemblies.md) Finally, there are additional package types to be aware of: - [Native Packages](../guides/native-packages.md) -- [Symbol Packages](../create-packages/symbol-packages.md) +- [Symbol Packages](../create-packages/symbol-packages-snupkg.md) diff --git a/docs/create-packages/includes/add-description.md b/docs/create-packages/includes/add-description.md new file mode 100644 index 000000000..62111c133 --- /dev/null +++ b/docs/create-packages/includes/add-description.md @@ -0,0 +1,21 @@ +The package's optional description appears on the **README** tab of the package's nuget.org page. The description pulls from the `` in the project file or the `$description` in the [.nuspec file](../../reference/nuspec.md). + +The following example shows a `Description` in the *.csproj* file for a .NET package: + +```xml + + + Azure.Storage.Blobs + 12.4.0 + Microsoft Azure Storage Blobs;Microsoft;Azure;Blobs;Blob;Storage;StorageScalable + + This client library enables working with the Microsoft Azure Storage Blob service for storing binary and text data. + For this release see notes - https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/README.md and https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/CHANGELOG.md + in addition to the breaking changes https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/storage/Azure.Storage.Blobs/BreakingChanges.txt + Microsoft Azure Storage quickstarts and tutorials - https://learn.microsoft.com/azure/storage/ + Microsoft Azure Storage REST API Reference - https://learn.microsoft.com/rest/api/storageservices/ + REST API Reference for Blob Service - https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api + + + +``` diff --git a/docs/create-packages/includes/choose-package-id.md b/docs/create-packages/includes/choose-package-id.md index ade53948e..6e6c5f436 100644 --- a/docs/create-packages/includes/choose-package-id.md +++ b/docs/create-packages/includes/choose-package-id.md @@ -1,18 +1,22 @@ -The package identifier and the version number are the two most important values in the project because they uniquely identify the exact code that's contained in the package. +The package identifier and the version number uniquely identify the exact code that's contained in the package. -**Best practices for the package identifier:** +Follow these best practices to create the package identifier: -- **Uniqueness**: The identifier must be unique across nuget.org or whatever gallery hosts the package. Before deciding on an identifier, search the applicable gallery to check if the name is already in use. To avoid conflicts, a good pattern is to use your company name as the first part of the identifier, such as `Contoso.`. -- **Namespace-like names**: Follow a pattern similar to namespaces in .NET, using dot notation instead of hyphens. For example, use `Contoso.Utility.UsefulStuff` rather than `Contoso-Utility-UsefulStuff` or `Contoso_Utility_UsefulStuff`. Consumers also find it helpful when the package identifier matches the namespaces used in the code. -- **Sample Packages**: If you produce a package of sample code that demonstrates how to use another package, attach `.Sample` as a suffix to the identifier, as in `Contoso.Utility.UsefulStuff.Sample`. (The sample package would of course have a dependency on the other package.) When creating a sample package, use the `contentFiles` value in ``. In the `content` folder, arrange the sample code in a folder called `\Samples\` as in `\Samples\Contoso.Utility.UsefulStuff.Sample`. +- The identifier must be *unique* across nuget.org and all other locations that host the package. To avoid conflicts, a good pattern is to use your company name as the first part of the identifier. +- Follow a *.NET namespace-like naming convention*, using dot notation. For example, use `Contoso.Utility.UsefulStuff` rather than `Contoso-Utility-UsefulStuff` or `Contoso_Utility_UsefulStuff`. It's also helpful for consumers if you match the package identifier to the namespace the code uses. +- If you produce a package of *sample code* that demonstrates how to use another package, append `.Sample` to the identifier, as in `Contoso.Utility.UsefulStuff.Sample`. -**Best practices for the package version:** + The sample package has a dependency on the original package. When you create the sample package, add `` with the `contentFiles` value. In the *content* folder, arrange the sample code in a folder called *\\Samples\\\*, such as *\\Samples\\Contoso.Utility.UsefulStuff.Sample*. -- In general, set the version of the package to match the project (or assembly), though this is not strictly required. This is a simple matter when you limit a package to a single assembly. Overall, remember that NuGet itself deals with package versions when resolving dependencies, not assembly versions. -- When using a non-standard version scheme, be sure to consider the NuGet versioning rules as explained in [Package versioning](../../concepts/package-versioning.md). NuGet is mostly [semver 2 compliant](../../concepts/package-versioning.md#semantic-versioning-200). +Follow these best practices to set the package version: -> For information on dependency resolution, see [Dependency resolution with PackageReference](../../concepts/dependency-resolution.md#dependency-resolution-with-packagereference). For older information that may also be helpful to better understand versioning, see this series of blog posts. +- In general, set the package version to *match the project or assembly version*, although this isn't strictly required. Matching the version is simple when you limit a package to a single assembly. NuGet itself deals with package versions when resolving dependencies, not assembly versions. + +- If you use a non-standard version scheme, be sure to consider the *NuGet versioning rules* as explained in [Package versioning](../../concepts/package-versioning.md). NuGet is mostly [Semantic Versioning 2.0.0](../../concepts/package-versioning.md#semantic-versioning-200)-compliant. + +>[!NOTE] +> For more information about dependency resolution, see [Dependency resolution with PackageReference](../../concepts/dependency-resolution.md#dependency-resolution-with-packagereference). For information that might help you understand versioning, see this series of blog posts: > -> - [Part 1: Taking on DLL Hell](http://blog.davidebbo.com/2011/01/nuget-versioning-part-1-taking-on-dll.html) -> - [Part 2: The core algorithm](http://blog.davidebbo.com/2011/01/nuget-versioning-part-2-core-algorithm.html) -> - [Part 3: Unification via Binding Redirects](http://blog.davidebbo.com/2011/01/nuget-versioning-part-3-unification-via.html) \ No newline at end of file +> - [Part 1: Taking on DLL Hell](https://blog.davidebbo.com/2011/01/nuget-versioning-part-1-taking-on-dll.html) +> - [Part 2: The core algorithm](https://blog.davidebbo.com/2011/01/nuget-versioning-part-2-core-algorithm.html) +> - [Part 3: Unification via binding redirects](https://blog.davidebbo.com/2011/01/nuget-versioning-part-3-unification-via.html) diff --git a/docs/create-packages/media/Verified-check-mark.png b/docs/create-packages/media/Verified-check-mark.png new file mode 100644 index 000000000..655262af9 Binary files /dev/null and b/docs/create-packages/media/Verified-check-mark.png differ diff --git a/docs/create-packages/media/publish_APIKey.png b/docs/create-packages/media/publish_APIKey.png deleted file mode 100644 index d9dd46836..000000000 Binary files a/docs/create-packages/media/publish_APIKey.png and /dev/null differ diff --git a/docs/create-packages/multiple-target-frameworks-project-file.md b/docs/create-packages/multiple-target-frameworks-project-file.md index 3568b6664..bd321d0d1 100644 --- a/docs/create-packages/multiple-target-frameworks-project-file.md +++ b/docs/create-packages/multiple-target-frameworks-project-file.md @@ -1,10 +1,10 @@ --- title: Multi-targeting for NuGet Packages in your project file -description: Description of the various methods to target multiple .NET Framework versions from within a single NuGet package. -author: karann-msft -ms.author: karann +description: Description of the various methods to target multiple .NET Framework versions from within a single NuGet package in your project file. +author: JonDouglas +ms.author: jodou ms.date: 07/15/2019 -ms.topic: conceptual +ms.topic: how-to --- # Support multiple .NET Framework versions in your project file @@ -32,7 +32,7 @@ For SDK-style projects, you can configure support for multiple targets framework Make sure that you change the XML element changed from singular to plural (add the "s" to both the open and close tags). -3. If you have any code that only works in one TFM, you can use `#if NET45` or `#if NETSTANDARD20` to separate TFM-dependent code. (For more information, see [How to multitarget](/dotnet/core/tutorials/libraries#how-to-multitarget).) For example, you can use the following code: +3. If you have any code that only works in one TFM, you can use `#if NET45` or `#if NETSTANDARD2_0` to separate TFM-dependent code. (For more information, see [How to multitarget](/dotnet/core/tutorials/libraries#how-to-multitarget).) For example, you can use the following code: ```csharp public string Platform { diff --git a/docs/create-packages/native-files-in-net-packages.md b/docs/create-packages/native-files-in-net-packages.md new file mode 100644 index 000000000..2b4d6ef95 --- /dev/null +++ b/docs/create-packages/native-files-in-net-packages.md @@ -0,0 +1,183 @@ +--- +title: Native files in .NET packages +description: How to pack native libraries in .NET packages +author: zivkan +ms.author: zivkan +ms.date: 09/26/2023 +ms.topic: concept-article +--- + +# Including native libraries in .NET packages + +This document explains how to create packages that work for projects targeting .NET (5+), where a .NET managed assembly uses [Platform Invoke (P/Invoke)](/dotnet/standard/native-interop/pinvoke) from a .NET managed language project, with the .NET runtime using [probing paths](/dotnet/core/dependency-loading/default-probing) to load and locate the native library. + +If you wish to support .NET Framework with your package, see the [section on projects targeting .NET Framework](#projects-targeting-net-framework). +In general, your best option is to package your own [MSBuild props and targets files](../concepts/MSBuild-props-and-targets.md), and handle build and publish targets yourself. +By not using NuGet and the .NET runtime's built in feature, you need to be sufficiently knowledgeable in MSBuild and the build systems for the relevant project types. + +While NuGet has a [`contentFiles/` feature](../reference/msbuild-targets.md#including-content-in-a-package), it is not recommended to use this, as it doesn't support per-RID selection, and therefore doesn't participate in the .NET runtime's probing paths features. + +## Background + +First we'll consider a project referencing packages. +When the app is published for a specific [Runtime Identifier (RID)](/dotnet/core/rid-catalog), then NuGet package assets for that RID will be copied into the output directory. +When the app is published without a specific RID, all RID specific content will be published in subdirectories, and a `{project}.deps.json` file is created that the .NET runtime loads to determine which directory to use as a probing path. + +Also, be aware that .NET 8 introduces breaking changes regarding [how it determines compatible RIDs from the `.deps.json` file](/dotnet/core/compatibility/deployment/8.0/rid-asset-list) and [which RIDs are recognized by the SDK](/dotnet/core/compatibility/sdk/8.0/rid-graph). + +## Understanding NuGet package asset selection + +There are three types of assets in a NuGet file that are most relevant to this scenario: compile, runtime, and native assets. +For a complete list of asset types, see the docs on [controlling dependency assets in `PackageReference` projects](../consume-packages/Package-References-in-Project-Files.md#controlling-dependency-assets). + +|Asset type|Short Description| +|--|--| +|[compile](#compile-assets)|Managed assemblies passed to the compiler. `ref/{tfm}/` if it exists, otherwise `lib/{tfm}/`.| +|[runtime](#runtime-assets)|Managed assemblies copied to the output directory. `runtimes/{rid}/lib/{tfm}/` if it exists, otherwise `lib/{tfm}/`.| +|[native](#native-assets)|Native libraries copied to the output directory. `runtimes/{rid}/native/`.| + +In all cases, NuGet chooses the "most compatible" directory for a given RID and Target Framework, and only the files in that directory are copied. +Therefore, you cannot put common assets in an inherited RID (such as `any`), because if any other RID is a better match, the `any` RID contents will not be considered. + +To inspect the implementation of NuGet's asset selection, see [`NuGet.Client`'s `ManagedCodeConventions.cs` file](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.Packaging/ContentModel/ManagedCodeConventions.cs). + +### Compile assets + +Compile assets are passed to the compiler, and therefore must only contain .NET assemblies. +NuGet will select compile assets from `ref/{tfm}/`, and if that directory does not exist, it will fall back to `lib/{tfm}`, where `{tfm}` is the target framework that is the closest match the project referencing the package. +However, in this scenario of creating a .NET package with native libraries, it is recommended to use `ref/` because if `lib/` is used, NuGet will think the package is compatible with projects using `packages.config`, but those projects will fail at runtime because the native files will not be copied. + +The .NET compiler will generate warnings when an assembly targets a different architecture than what the current compilation is targeting, so your package consumers will have the best experience if your `ref/` or `lib/` assemblies target `AnyCPU`. + +If your assembly contains a lot of managed code, not just P/Invoke method definitions, you can save space by making the `ref/` assembly a [reference assembly](/dotnet/standard/assembly/reference-assemblies#generating-reference-assemblies), but be sure to include it under `ref/` in your package, not `lib/`. + +Therefore, there is no capability to provide different compile-time assemblies for different RIDs, you will need to provide the same API surface for all RIDs, and do runtime checks (for example, throw `PlatformNotSupportedException`). + +### Runtime assets + +Runtime assets are .NET managed assemblies copied to the output directory on build and publish, and the .NET SDK generates the `deps.json` with all the RID-specific asset information. +NuGet will select runtime assets from `runtimes/{rid}/lib/{tfm}/`, and if that doesn't exist, then it will fall back to `lib/{tfm}/`. +The best `{rid}` directory is selected first, followed by `{tfm}`. +However, in this scenario of creating a .NET package with native libraries, it is recommended to use `runtimes/` because if `lib/` is used, NuGet will think the package is compatible with projects using `packages.config`, but those projects will fail at runtime because the native assets will not be copied. + +### Native assets + +Native assets are also copied to the output directory on build and publish, and are present in the `deps.json` file. +NuGet will select native assets from the `runtimes/{rid}/native/` directory. + +> [!NOTE] +> The [.NET SDK flattens any directory structure](https://github.com/dotnet/sdk/issues/9643) under `runtimes/{rid}/native/` when copying to the output directory. + +## Putting it together + +How to build any binaries native libraries is out of scope of this document. +It is assumed that all the native binaries and the .NET assemblies have been completed and copied to a machine for packing. + +When packing with [NuGet's MSBuild Pack target](../reference/msbuild-targets.md#pack-target), you can include arbitrary files in arbitrary package paths using `Pack="true" PackagePath="{path}"` metadata on MSBuild items. +For example, ``. + +Consider a package `Contoso.Native` that provides .NET APIs to `contoso.dll` on Windows, `libcontoso.dylib` on OSX, and `libcontoso.so` on Linux, using `[DllImport("contoso")]`. +The package contents should be (excluding files required by the [Open Packaging Conventions](https://en.wikipedia.org/wiki/Open_Packaging_Conventions)) + +### Example 1 + +If `Contoso.Native` is built as AnyCPU: + +```text +Contoso.Native.1.0.0.nuspec +ref/net8.0/Contoso.Native.dll +runtimes/any/lib/net8.0/Contoso.Native.dll +runtimes/linux-arm64/native/libcontoso.so +runtimes/linux-x64/native/libcontoso.so +runtimes/osx-arm64/native/libcontoso.dylib +runtimes/osx-x64/native/libcontoso.dylib +runtimes/win-arm64/native/contoso.dll +runtimes/win-x64/native/contoso.dll +``` + +While the `ref/` and `runtimes/any/lib` copies of `Contoso.Native.dll` could be deduplicated into a single `lib/net8.0/Contoso.Native.dll` file, this is not recommended because NuGet will believe this package is compatible with projects using `packages.config`, and these projects will fail at runtime when the native `contoso.dll` is not found. + +### Example 2 + +If `Contoso.Native` has any differences between architectures. +For example, but not limited to, using `#if` to compile difference code for different RIDs, or using `` (or anything else that causes `-platform:` to be passed to the compiler) with a value other than `AnyCPU`. + +```text +Contoso.Native.1.0.0.nuspec +ref/net8.0/Contoso.Native.dll +runtimes/linux-arm64/lib/net8.0/Contoso.Native.dll +runtimes/linux-arm64/native/libcontoso.so +runtimes/linux-x64/lib/net8.0/Contoso.Native.dll +runtimes/linux-x64/native/libcontoso.so +runtimes/osx-arm64/lib/net8.0/Contoso.Native.dll +runtimes/osx-arm64/native/libcontoso.dylib +runtimes/osx-x64/lib/net8.0/Contoso.Native.dll +runtimes/osx-x64/native/libcontoso.dylib +runtimes/win-arm64/lib/net8.0/Contoso.Native.dll +runtimes/win-arm64/native/contoso.dll +runtimes/win-x64/lib/net8.0/Contoso.Native.dll +runtimes/win-x64/native/contoso.dll +``` + +### Example 3 + +If `Contoso.Native` has conditional compilation per operating system, but not per CPU architecture. + +```text +Contoso.Native.1.0.0.nuspec +ref/net8.0/Contoso.Native.dll +runtimes/linux/lib/net8.0/Contoso.Native.dll +runtimes/linux-arm64/native/libcontoso.so +runtimes/linux-x64/native/libcontoso.so +runtimes/osx/lib/net8.0/Contoso.Native.dll +runtimes/osx-arm64/native/libcontoso.dylib +runtimes/osx-x64/native/libcontoso.dylib +runtimes/win/lib/net8.0/Contoso.Native.dll +runtimes/win-arm64/native/contoso.dll +runtimes/win-x64/native/contoso.dll +``` + +## Projects Targeting .NET Framework + +.NET has evolved over time, causing project and package incompatibility when certain features are used. +What was described above assumes that the project using the package targets .NET 5 or higher, or .NET Core (`netcoreapp`), which uses the maximum features to simplify the package contents as much as possible. +Projects targeting .NET Standard are not particularly relevant to this document, as those projects can only be class libraries, which cannot be run directly. +However, projects targeting .NET Framework can use either SDK style or non-SDK style projects, and non-SDK style projects may use either `PackageReference` or `packages.config` to use NuGet packages. +All of these combinations have different levels of support, and impose constraints on package authors who wish to support .NET Framework projects using the package. + +Our recommendation is to split the package into 3 packages. +The first is a meta-package (a package with no contents/assets, only dependencies to other packages), that has dependencies to one of the other two packages, depending on target framework. +The second package contains the .NET 5+ `ref/*` and `runtimes/*` assets as described above. +The last package will contain the .NET Framework assets, and will not use the `ref/*` or `runtime/*` conventions. +This is due to the build system having (partial) support for these NuGet conventions, but the runtime working sufficiently differently that it's easier to avoid it, to maximize project compatibility. + +The package with .NET Framework native libraries should have custom [MSBuild targets and props files](../concepts/MSBuild-props-and-targets.md), under `buildTransitive//.[props|targets]`. +For example, `buildTransitive/net472/Contoso.Native.targets`. +To support `packages.config` projects, also have a `build//.[props|targets]` which imports the `buildTransitive` file. +This MSBuild script should copy the native library to subdirectories. +Alternatively, the native libraries should have different filenames per CPU architecture, so they can all be copied into the same directory. + +Finally, the managed library, that uses P/Invoke to call into the native library, it should have runtime checks to determine what platform the current executable is running in (x86, x64, or ARM64), and then P/Invoke into the native library with the correct filename or in the correct subdirectory. + +### SDK style projects targeting .NET Framework + +When the .NET SDK builds a project targeting the .NET Framework, if one of `RuntimeIdentifier` or `PlatformTarget` is set, the .NET SDK will set the other property to an appropriate value, and package `runtimes/` contents (that [follow NuGet's conventions](#understanding-nuget-package-asset-selection)) will be copied to the output directory. +If the project does not set either `RuntimeIdentifier` or `PlatformTarget`, but any package contains RID specific contents, then the .NET SDK will set `PlatformTarget` to `x86`. +Therefore, SDK style projects targeting .NET Framework will only use `AnyCPU` by default when none of the packages contain RID specific content. + +`dotnet build -r `, or the `publish` equivalent (for example, `dotnet publish -r win-arm64`) can be used to explicitly build or publish for a specific platform. + +In order to support `AnyCPU` projects, package authors must not use the `runtimes/` conventions in their package, and must use the MSBuild targets/props files [as suggested above](#projects-targeting-net-framework). + +### Non-SDK style projects targeting .NET Framework with `PackageReference` + +If you test a non-SDK style `PackageReference` project with a package using the `runtimes/*` convention, the following behavior occurs. +If the project's configuration targets the "Any CPU" platform, the build will not copy any of the RID specific assets from the package, and the app will fail at runtime. +Using Visual Studio's Configuration Manager, the .NET projects can be changed to target x64, x86, or ARM64, instead of "Any CPU", in which case the app will work correctly at runtime. + +In order to support `AnyCPU` projects, package authors must use the MSBuild targets/props files [as suggested above](#projects-targeting-net-framework). + +### `packages.config` + +NuGet's original restore style, `packages.config`, does not support `ref/*` or `runtimes/*` conventions. +Therefore, package authors must create their own MSBuild props and targets file to support projects still using `packages.config`. diff --git a/docs/create-packages/set-package-type.md b/docs/create-packages/set-package-type.md index 89acf41e1..ee8847234 100644 --- a/docs/create-packages/set-package-type.md +++ b/docs/create-packages/set-package-type.md @@ -1,34 +1,136 @@ --- title: Set a NuGet package type description: Describes packages types to indicate intended use of a package. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 07/09/2019 -ms.topic: conceptual +ms.topic: how-to --- # Set a NuGet package type -With NuGet 3.5+, packages can be marked with a specific *package type* to indicate its intended use. Packages not marked with a type, including all packages created with earlier versions of NuGet, default to the `Dependency` type. +Packages can be marked with one more more *package types* to indicate its intended use. + +## Known package types - `Dependency` type packages add build- or run-time assets to libraries and applications, and can be installed in any project type (assuming they are compatible). -- `DotnetCliTool` type packages are extensions to the [dotnet CLI](/dotnet/articles/core/tools/index) and are invoked from the command line. Such packages can be installed only in .NET Core projects and have no effect on restore operations. More details about these per-project extensions are available in the [.NET Core extensibility](/dotnet/articles/core/tools/extensibility#per-project-based-extensibility) documentation. +- `DotnetTool` type packages are .NET tools that can be installed by the [dotnet CLI](/dotnet/articles/core/tools/index). + +- `MSBuildSdk` type packages are [MSBuild project SDKs](/visualstudio/msbuild/how-to-use-project-sdk) that simplifies using software development kits. + +- `Template` type packages provide [custom templates](/dotnet/core/tools/custom-templates) that can be used to create files or projects like an app, service, tool, or class library. + +- `McpServer` type packages contain MCP servers. This package type is always accompanied by the `DotnetTool` package type, because a local MCP server is distributed as a .NET tool. For information on MCP server and NuGet, see [MCP servers in NuGet packages](../concepts/nuget-mcp.md). + +Packages not marked with a type, including all packages created with earlier versions of NuGet, default to the `Dependency` type. + +> [!NOTE] +> Support for package types was added in NuGet 3.5. +> If you don't need a custom package type, it's best to *not* explicitly set the package type. +> NuGet defaults to the `Dependency` type when no type is specified. + +## Custom package types + +You can mark your package with one or more custom package types if its use does not fit the [known package types](#known-package-types). + +For example, imagine that customers of the `Contoso` app can install extensions. The app could require extension authors to use the custom package type `ContosoExtension` to identify their packages as proper extensions that follow the required conventions. + +> [!WARNING] +> A package with a custom package type cannot be installed by Visual Studio or nuget.exe. See [NuGet/Home#10468](https://github.com/NuGet/Home/issues/10468) for more information. + +# [Using dotnet CLI](#tab/dotnet) + +Package types can be set in the project file (`.csproj`): + +```xml + + + + net5.0 + + ContosoExtension + + + +``` + +Packages with multiple intended uses can be marked with multiple package types using the `;` delimiter: + +```xml + + + + net5.0 + + PackageType1;PackageType2 + -- Custom type packages use an arbitrary type identifier that conforms to the same format rules as package IDs. Any type other than `Dependency` and `DotnetCliTool`, however, are not recognized by the NuGet Package Manager in Visual Studio. + +``` -Package types are set in the `.nuspec` file. It's best for backwards compatibility to *not* explicitly set the `Dependency` type and to instead rely on NuGet assuming this type when no type is specified. +Package types can be versioned using a `,` delimiter between the package type and its [`Version`](/dotnet/api/system.version) string: -- `.nuspec`: Indicate the package type within a `packageTypes\packageType` node under the `` element: +```xml + - ```xml - - - + + net5.0 + + PackageType1, 1.0.0.0;PackageType2 + + + +``` + +# [Using nuget.exe](#tab/nugetexe) + +Package types are set in the `.nuspec` file within a `packageTypes\packageType` node under the `` element: + +```xml + + + + + + + + + +``` + +Packages with multiple intended uses may be marked with multiple package types: + +```xml + + + - + + - - - ``` + + +``` + +Package types can be versioned using a [`Version`](/dotnet/api/system.version) string: + +```xml + + + + + + + + + + +``` + +--- + +The format of a package type string is exactly like a package ID. That is, a package type is a case-insensitive string matching the regular expression `^\w+([_.-]\w+)*$` having at least one character and at most 100 characters. + +If provided, the package type version is a [`Version`](/dotnet/api/system.version) string. The package type version is optional and defaults to `0.0`. diff --git a/docs/docfx.json b/docs/docfx.json index 0fad5c872..33e9af360 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -4,7 +4,7 @@ { "files": [ "**/*.md", - "**/**.yml" + "**/*.yml" ], "exclude": [ "**/obj/**", @@ -33,18 +33,21 @@ "overwrite": [], "externalReference": [], "globalMetadata": { - "feedback_system": "GitHub", + "ms.service": "nuget", + "uhfHeaderId": "MSDocsHeader-DotNet", + "feedback_system": "Standard", "feedback_github_repo": "NuGet/docs.microsoft.com-nuget", "feedback_product_url": "https://github.com/NuGet/Home/issues/", "breadcrumb_path": "~/_breadcrumb/toc.yml", "ROBOTS": "INDEX,FOLLOW", "ms.topic": "conceptual", - "ms.prod": "nuget", - "author": "karann-msft", - "ms.author": "karann", + "author": "JonDouglas", + "ms.author": "jodou", "ms.reviewer": [ - "karann", - "unnir" + "anangaur", + "jodou", + "chgill", + "jiacjian" ], "ms.workload": [ "dotnet", @@ -54,7 +57,6 @@ "searchScope": [ "NuGet" ], - "uhfHeaderId": "MSDocsHeader-NuGet" }, "fileMetadata": {}, "template": [], diff --git a/docs/docs.csproj b/docs/docs.csproj new file mode 100644 index 000000000..e63c1c5b9 --- /dev/null +++ b/docs/docs.csproj @@ -0,0 +1,5 @@ + + + net472 + + \ No newline at end of file diff --git a/docs/guides/Create-NET-Standard-Packages-VS2015.md b/docs/guides/Create-NET-Standard-Packages-VS2015.md index a3ba81dbe..8d4e839dc 100644 --- a/docs/guides/Create-NET-Standard-Packages-VS2015.md +++ b/docs/guides/Create-NET-Standard-Packages-VS2015.md @@ -1,8 +1,8 @@ --- title: Create .NET Standard and .NET Framework NuGet Packages with Visual Studio 2015 description: An end-to-end walkthrough of creating .NET Standard and .NET Framework NuGet packages using NuGet 3.x and Visual Studio 2015. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 02/02/2018 ms.topic: tutorial --- @@ -164,7 +164,7 @@ Note that `pack` requires Mono 4.4.2 on Mac OS X and does not work on Linux syst - [Supporting multiple .NET framework versions](../create-packages/supporting-multiple-target-frameworks.md) - [Include MSBuild props and targets in a package](../create-packages/creating-a-package.md#include-msbuild-props-and-targets-in-a-package) - [Creating localized packages](../create-packages/creating-localized-packages.md) -- [Symbol packages](../create-packages/symbol-packages.md) +- [Symbol packages](../create-packages/symbol-packages-snupkg.md) - [Package versioning](../concepts/package-versioning.md) - [.NET Standard Library documentation](/dotnet/articles/standard/library) - [Porting to .NET Core from .NET Framework](/dotnet/articles/core/porting/index) diff --git a/docs/guides/Create-UI-Controls.md b/docs/guides/Create-UI-Controls.md index 04fe7e4a7..80a7b7c8f 100644 --- a/docs/guides/Create-UI-Controls.md +++ b/docs/guides/Create-UI-Controls.md @@ -1,15 +1,15 @@ --- title: How to package UI controls with NuGet description: How to create NuGet packages that contain UWP or WPF controls, including the necessary metadata and supporting files for the Visual Studio and Blend designers. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 05/23/2018 ms.topic: tutorial --- # Creating UI controls as NuGet packages -Starting with Visual Studio 2017, you can take advantage of added capabilities for UWP and WPF controls that you deliver in NuGet packages. This guide walks you through these capabilities in context of UWP controls using the [ExtensionSDKasNuGetPackage sample](https://github.com/NuGet/Samples/tree/master/ExtensionSDKasNuGetPackage). The same applies to WPF controls unless mentioned otherwise. +Starting with Visual Studio 2017, you can take advantage of added capabilities for UWP and WPF controls that you deliver in NuGet packages. This guide walks you through these capabilities in context of UWP controls using the [ExtensionSDKasNuGetPackage sample](https://github.com/NuGet/Samples/tree/main/ExtensionSDKasNuGetPackage). The same applies to WPF controls unless mentioned otherwise. ## Prerequisites @@ -31,17 +31,19 @@ Alternately, edit the the project file to add `true - + @@ -56,6 +58,7 @@ where: - *your_package_file*: the name of your control file, such as `ManagedPackage.winmd` ("ManagedPackage" is an arbitrary named used for this example and has no other meaning). - *vs_category*: The label for the group in which the control should appear in the Visual Studio designer’s toolbox. A `VSCategory` is necessary for the control to appear in the toolbox. +*ui_framework*: The name of the Framework, such as 'WPF', note that `UIFramework` attribute is required on ToolboxItems nodes on Visual Studio 16.7 Preview 3 or above for the control to appear in toolbox. - *blend_category*: The label for the group in which the control should appear in the Blend designer’s Assets pane. A `BlendCategory` is necessary for the control to appear in Assets. - *type_full_name_n*: The fully-qualified name for each control, including the namespace, such as `ManagedPackage.MyCustomControl`. Note that the dot format is used for both managed and native types. @@ -66,7 +69,7 @@ In the following example, the control implemented in `ManagedPackage.winmd` will ```xml - + @@ -82,13 +85,13 @@ In the following example, the control implemented in `ManagedPackage.winmd` will ## Add custom icons to your controls -To display a custom icon in the toolbox/assets pane, add an image to your project or the corresponding `design.dll` project with the name “Namespace.ControlName.extension” and set the build action to “Embedded Resource”. You must also ensure that the associated `AssemblyInfo.cs` specifies the ProvideMetadata attribute - `[assembly: ProvideMetadata(typeof(RegisterMetadata))]`. See this [sample](https://github.com/NuGet/Samples/blob/master/ExtensionSDKasNuGetPackage/NativePackage.Design/Properties/AssemblyInfo.cs#L20). +To display a custom icon in the toolbox/assets pane, add an image to your project or the corresponding `design.dll` project with the name “Namespace.ControlName.extension” and set the build action to “Embedded Resource”. You must also ensure that the associated `AssemblyInfo.cs` specifies the ProvideMetadata attribute - `[assembly: ProvideMetadata(typeof(RegisterMetadata))]`. See this [sample](https://github.com/NuGet/Samples/blob/main/ExtensionSDKasNuGetPackage/NativePackage.Design/Properties/AssemblyInfo.cs#L20). Supported formats are `.png`, `.jpg`, `.jpeg`, `.gif`, and `.bmp`. The recommended format is BMP24 in 16 pixels by 16 pixels. ![Tool box icon sample](https://raw.githubusercontent.com/NuGet/docs.microsoft.com-nuget/live/docs/guides/media/ColorPicker_16x16x24.bmp) -The pink background is replaced at runtime. The icons are recolored when the Visual Studio theme is changed and that background color is expected. For more information, please reference [Images and Icons for Visual Studio](https://docs.microsoft.com/en-us/visualstudio/extensibility/ux-guidelines/images-and-icons-for-visual-studio). +The pink background is replaced at runtime. The icons are recolored when the Visual Studio theme is changed and that background color is expected. For more information, please reference [Images and Icons for Visual Studio](/visualstudio/extensibility/ux-guidelines/images-and-icons-for-visual-studio). In the example below, the project contains an image file named “ManagedPackage.MyCustomControl.png”. @@ -103,38 +106,45 @@ UWP packages have a TargetPlatformVersion (TPV) and TargetPlatformMinVersion (TP For example, let’s say you’ve set the TPMinV for your controls package to Windows 10 Anniversary Edition (10.0; Build 14393), so you want to ensure that the package is consumed only by UWP projects that match that lower bound. To allow your package to be consumed by UWP projects, you must package your controls with the following folder names: - \lib\uap10.0.14393\* - \ref\uap10.0.14393\* +``` +\lib\uap10.0.14393\* +\ref\uap10.0.14393\* +``` NuGet will automatically check the TPMinV of the consuming project, and fail installation if it is lower than Windows 10 Anniversary Edition (10.0; Build 14393) In case of WPF, let's say you would like your WPF controls package to be consumed by projects targeting .NET Framework v4.6.1 or higher. To enforce that, you must package your controls with the following folder names: - \lib\net461\* - \ref\net461\* +``` +\lib\net461\* +\ref\net461\* +``` ## Add design-time support To configure where the control properties show up in the property inspector, add custom adorners, etc., place your `design.dll` file inside the `lib\uap10.0.14393\Design` folder as appropriate to the target platform. Also, to ensure that the **[Edit Template > Edit a Copy](/windows/uwp/controls-and-patterns/xaml-styles#modify-the-default-system-styles)** feature works, you must include the `Generic.xaml` and any resource dictionaries that it merges in the `\Themes` folder (again, using your actual assembly name). (This file has no impact on the runtime behavior of a control.) The folder structure would thus appear as follows: - \lib - \uap10.0.14393 - \Design - \MyControl.design.dll - \your_assembly_name - \Themes - Generic.xaml - +``` +\lib + \uap10.0.14393 + \Design + \MyControl.design.dll + \your_assembly_name + \Themes + Generic.xaml +``` For WPF, continuing with the example where you would like your WPF controls package to be consumed by projects targeting .NET Framework v4.6.1 or higher: - \lib - \net461 - \Design - \MyControl.design.dll - \your_assembly_name - \Themes - Generic.xaml +``` +\lib + \net461 + \Design + \MyControl.design.dll + \your_assembly_name + \Themes + Generic.xaml +``` > [!Note] > By default, control properties will show up under the Miscellaneous category in the property inspector. @@ -143,7 +153,7 @@ For WPF, continuing with the example where you would like your WPF controls pack You can embed string resources (`.resw`) in your package that can be used by your control or the consuming UWP project, set the **Build Action** property of the `.resw` file to **PRIResource**. -For an example, refer to [MyCustomControl.cs](https://github.com/NuGet/Samples/blob/master/ExtensionSDKasNuGetPackage/ManagedPackage/MyCustomControl.cs) in the ExtensionSDKasNuGetPackage sample. +For an example, refer to [MyCustomControl.cs](https://github.com/NuGet/Samples/blob/main/ExtensionSDKasNuGetPackage/ManagedPackage/MyCustomControl.cs) in the ExtensionSDKasNuGetPackage sample. > [!Note] > This is applicable only to UWP controls. @@ -151,4 +161,4 @@ For an example, refer to [MyCustomControl.cs](https://github.com/NuGet/Samples/b ## See also - [Create UWP Packages](create-uwp-packages.md) -- [ExtensionSDKasNuGetPackage sample](https://github.com/NuGet/Samples/tree/master/ExtensionSDKasNuGetPackage) +- [ExtensionSDKasNuGetPackage sample](https://github.com/NuGet/Samples/tree/main/ExtensionSDKasNuGetPackage) diff --git a/docs/guides/Create-UWP-Packages-CS.md b/docs/guides/Create-UWP-Packages-CS.md new file mode 100644 index 000000000..1efb113a9 --- /dev/null +++ b/docs/guides/Create-UWP-Packages-CS.md @@ -0,0 +1,218 @@ +--- +title: Create NuGet Packages for the UWP Platform (C#) +description: An end-to-end walkthrough of creating NuGet packages using a Windows Runtime Component for the Universal Windows Platform in C#. +author: JonDouglas +ms.author: jodou +ms.date: 11/01/2023 +ms.topic: tutorial +--- + +# Create UWP packages (C#) + +The [Universal Windows Platform (UWP)](/windows/uwp) provides a common app platform for every device that runs Windows 10. Within this model, UWP apps can call both the WinRT APIs that are common to all devices, and also APIs (including Win32 and .NET) that are specific to the device family on which the app is running. + +In this walkthrough you create a NuGet package with a C# UWP component (including a XAML control) that can be used in both Managed and Native projects. + +## Prerequisites + +1. Visual Studio 2019. Install the 2019 Community edition for free from [visualstudio.com](https://www.visualstudio.com/). You can also use the Professional and Enterprise editions. + +1. NuGet CLI. Download the latest version of `nuget.exe` from [nuget.org/downloads](https://nuget.org/downloads) and save the tool to a location of your choice. (The download is the `.exe` file directly.) Add the tool file location to your PATH environment variable, if it isn't already. For more information, see [Installing nuget.exe](../reference/nuget-exe-cli-reference.md#installing-nugetexe). + +## Create a UWP Windows Runtime component + +1. In Visual Studio, select **File > New > Project**, and search for "uwp c#". Select the **Windows Runtime Component (Universal Windows)** template and select **Next**. Change the name to ImageEnhancer, and select **Create**. Accept the default values for Target Version and Minimum Version when prompted. + + ![Creating a new UWP Windows Runtime Component project](media/UWP-NewProject-CS.png) + +1. Right-click the project in Solution Explorer, select **Add > New Item**, select **Templated Control**, change the name to AwesomeImageControl.cs, and select **Add**: + + ![Adding a new XAML Templated Control item to the project](media/UWP-NewXAMLControl-CS.png) + +1. Right-click the project in Solution Explorer and select **Properties.** In the Properties page, choose **Build** tab and enable **XML Documentation File**: + + ![Setting Generate XML Documentation Files to Yes](media/UWP-GenerateXMLDocFiles-CS.png) + +1. Right-click the *solution* and select **Batch Build**. Select the five build boxes, as shown in the following image. This makes sure that when you do a build, you generate a full set of artifacts for each of the target systems that Windows supports. + + ![Batch Build](media/UWP-BatchBuild-CS.png) + +1. In the Batch Build dialog, and select **Build** to verify the project and create the output files that you need for the NuGet package. + +> [!Note] +> In this walkthrough you use the Debug artifacts for the package. For non-debug package, check the Release options in the Batch Build dialog instead, and refer to the resulting Release folders in the steps that follow. + +## Create and update the .nuspec file + +To create the initial `.nuspec` file, complete the following steps. The subsequent sections guide you through other necessary updates. + +1. Open a command prompt and browse to the folder that contains the `ImageEnhancer.csproj` file, which should be a subfolder of the folder that contains the solution file. + +1. Run the [`NuGet spec`](../reference/cli-reference/cli-ref-spec.md) command to generate the `ImageEnhancer.nuspec` file. The name of the file is taken from the name of the `.csroj` file. + + ```cli + nuget spec + ``` + +1. Open `ImageEnhancer.nuspec` in an editor and update it to match the following, replacing YOUR_NAME with an appropriate value. Don't leave any of the $propertyName$ values. The `` value, specifically, must be unique across nuget.org (see the naming conventions described in [Creating a package](../create-packages/creating-a-package.md#choose-a-unique-package-identifier-and-setting-the-version-number)). Also note that you must also update the author and description tags or you get an error during the packing step. + + ```xml + + + + ImageEnhancer.YOUR_NAME + 1.0.0 + ImageEnhancer + YOUR_NAME + YOUR_NAME + false + Awesome Image Enhancer + First release + Copyright 2020 + image enhancer imageenhancer + + + ``` + +> [!Note] +> For packages built for public consumption, pay special attention to the `` element, as these tags help others find your package and understand what it does. + +### Adding Windows metadata to the package + +A Windows Runtime Component requires metadata that describes all of its publicly available types, which makes it possible for other apps and libraries to consume the component. This metadata is contained in a .winmd file, which is created when you compile the project and must be included in your NuGet package. An XML file with IntelliSense data is also built at the same time, and should be included as well. + +Add the following `` node to the `.nuspec` file: + +```xml + + + ... + + + + + + + + +``` + +### Adding XAML content + +To include a XAML control with your component, you need to add the XAML file that has the default template for the control (as generated by the project template). This also goes in the `` section: + +```xml + + + + ... + + + ... + + + + + + +``` + +### Adding the native implementation libraries + +Within your component, the core logic of the ImageEnhancer type is in native code, which is contained in the various `ImageEnhancer.winmd` assemblies that are generated for each target runtime (ARM, ARM64, x86, and x64). To include these in the package, reference them in the `` section along with their associated .pri resource files: + +```xml + + + + ... + + + ... + + + + + + + + + + + + + + + + +``` + +### Final .nuspec + +Your final `.nuspec` file should now look like the following, where again YOUR_NAME should be replaced with an appropriate value: + +```xml + + + + ImageEnhancer.YOUR_NAME + 1.0.0 + ImageEnhancer + YOUR_NAME + YOUR_NAME + false + Awesome Image Enhancer + First Release + Copyright 2020 + image enhancer imageenhancer + + + + + + + + + + + + + + + + + + + + + + + + +``` + +## Package the component + +With the completed `.nuspec` referencing all the files you need to include in the package, you're ready to run the [`nuget pack`](../reference/cli-reference/cli-ref-pack.md) command: + +```cli +nuget pack ImageEnhancer.nuspec +``` + +This generates `ImageEnhancer.YOUR_NAME.1.0.0.nupkg`. Opening this file in a tool like the [NuGet Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer) and expanding all the nodes, you see the following contents: + +![NuGet Package Explorer showing the ImageEnhancer package](media/UWP-PackageExplorer.png) + +> [!Tip] +> A `.nupkg` file is just a ZIP file with a different extension. You can also examine package contents, then, by changing `.nupkg` to `.zip`, but remember to restore the extension before uploading a package to nuget.org. + +To make your package available to other developers, follow the instructions on [Publish a package](../nuget-org/publish-a-package.md). + +## Related topics + +- [.nuspec Reference](../reference/nuspec.md) +- [Symbol packages](../create-packages/symbol-packages-snupkg.md) +- [Package versioning](../concepts/package-versioning.md) +- [Supporting Multiple .NET Framework Versions](../create-packages/supporting-multiple-target-frameworks.md) +- [Include MSBuild props and targets in a package](../create-packages/creating-a-package.md#include-msbuild-props-and-targets-in-a-package) +- [Creating Localized Packages](../create-packages/creating-localized-packages.md) \ No newline at end of file diff --git a/docs/guides/Create-UWP-Packages.md b/docs/guides/Create-UWP-Packages.md index eecaa5ed0..dcb17dc79 100644 --- a/docs/guides/Create-UWP-Packages.md +++ b/docs/guides/Create-UWP-Packages.md @@ -1,8 +1,8 @@ --- title: Create NuGet Packages for the Universal Windows Platform description: An end-to-end walkthrough of creating NuGet packages using a Windows Runtime Component for the Universal Windows Platform. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 03/21/2017 ms.topic: tutorial --- @@ -248,7 +248,7 @@ To make your package available to other developers, follow the instructions on ## Related topics - [.nuspec Reference](../reference/nuspec.md) -- [Symbol packages](../create-packages/symbol-packages.md) +- [Symbol packages](../create-packages/symbol-packages-snupkg.md) - [Package versioning](../concepts/package-versioning.md) - [Supporting Multiple .NET Framework Versions](../create-packages/supporting-multiple-target-frameworks.md) - [Include MSBuild props and targets in a package](../create-packages/creating-a-package.md#include-msbuild-props-and-targets-in-a-package) diff --git a/docs/guides/Native-Packages.md b/docs/guides/Native-Packages.md index f4864c1c6..68f42f4a7 100644 --- a/docs/guides/Native-Packages.md +++ b/docs/guides/Native-Packages.md @@ -1,10 +1,10 @@ --- title: Creating Native NuGet Packages description: Details on creating native NuGet packages that contains C++ code instead of managed code, for use in C++ projects. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/09/2017 -ms.topic: conceptual +ms.topic: concept-article --- # Creating native packages @@ -16,6 +16,6 @@ To be consumable in a C++ project, a package must target the `native` framework. > [!Note] > Be sure to include *native* in the `` section of your `.nuspec` to help other developers find your package by searching on that tag. -Native NuGet packages targeting `native` then provide files in `\build`, `\content`, and `\tools` folders; `\lib` is not used in this case (NuGet cannot directly add references to a C++ project). A package may also include targets and props files in `\build` that NuGet will automatically import into projects that consume the package. Those files must be named the same as the package ID with the `.targets` and/or `.props` extensions. For example, the [cpprestsdk](https://nuget.org/packages/cpprestsdk/) package includes a `cpprestsdk.targets` file in its `\build` folder. +Native NuGet packages targeting `native` then provide files in `\build`, `\content`, and `\tools` folders; `\lib` is not used in this case (NuGet cannot directly add references to a C++ project). A package may also include targets and props files in `\build` that NuGet will automatically import into projects that consume the package. Those files must be named the same as the package ID with the `.targets` and/or `.props` extensions. For example, the [Microsoft.Web.WebView2](https://www.nuget.org/packages/Microsoft.Web.WebView2) package includes a `Microsoft.Web.WebView2.targets` file in its `\build` folder. The `\build` folder can be used for all NuGet packages and not just native packages. The `\build` folder respects target frameworks just like the `\content`, `\lib`, and `\tools` folders. This means you can create a `\build\net40` folder and a `\build\net45` folder and NuGet will import the appropriate props and targets files into the project. (Use of PowerShell scripts to import MSBuild targets is not needed.) diff --git a/docs/guides/analyzers-conventions.md b/docs/guides/analyzers-conventions.md index eebfb9767..78156098d 100644 --- a/docs/guides/analyzers-conventions.md +++ b/docs/guides/analyzers-conventions.md @@ -1,15 +1,15 @@ --- title: .NET Compiler Platform Analyzer Formats for NuGet description: Conventions for .NET analyzers that are packaged and distributed with NuGet packages that implement an API or library. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/09/2017 -ms.topic: conceptual +ms.topic: article --- # Analyzer NuGet formats -The .NET Compiler Platform (also known as "Roslyn") allows developers to create [analyzers](https://github.com/dotnet/roslyn/wiki/How-To-Write-a-C%23-Analyzer-and-Code-Fix) that examine the syntax tree and semantics of code as it's being written. This provides developers with a way to create domain-specific analysis tools, such as those that would help guide the use of a particular API or library. You can find more information on the [.NET/Roslyn](https://github.com/dotnet/roslyn/wiki) GitHub wiki. Also see the article, [Use Roslyn to Write a Live Code Analyzer for your API](https://msdn.microsoft.com/magazine/dn879356.aspx) in MSDN Magazine. +The .NET Compiler Platform (also known as "Roslyn") allows developers to create [analyzers](https://github.com/dotnet/roslyn/blob/main/docs/wiki/How-To-Write-a-C%23-Analyzer-and-Code-Fix.md) that examine the syntax tree and semantics of code as it's being written. This provides developers with a way to create domain-specific analysis tools, such as those that would help guide the use of a particular API or library. You can find more information on the [.NET/Roslyn](https://github.com/dotnet/roslyn/wiki) GitHub wiki. Also see the article, [Use Roslyn to Write a Live Code Analyzer for your API](/archive/msdn-magazine/2014/special-issue/csharp-and-visual-basic-use-roslyn-to-write-a-live-code-analyzer-for-your-api) in MSDN Magazine. Analyzers themselves are typically packaged and distributed as part of the NuGet packages that implement the API or library in question. @@ -38,9 +38,11 @@ Also note that because this package has no platform-specific requirements, the ` The use of the `analyzers` folder is similar to that used for [target frameworks](../create-packages/supporting-multiple-target-frameworks.md), except the specifiers in the path describe development host dependencies instead of build-time. The general format is as follows: - $/analyzers/{framework_name}{version}/{supported_architecture}/{supported_language}/{analyzer_name}.dll +``` +$/analyzers/{framework_name}{version}/{supported_architecture}/{supported_language}/{analyzer_name}.dll +``` -- **framework_name**: the *optional* API surface area of the .NET Framework that the contained DLLs need to run. `dotnet` is presently the only valid value because Roslyn is the only host that can run analyzers. If no target is specified, DLLs are assumed to apply to *all* targets. +- **framework_name** and **version**: the *optional* API surface area of the .NET Framework that the contained DLLs need to run. `dotnet` is presently the only valid value because Roslyn is the only host that can run analyzers. If no target is specified, DLLs are assumed to apply to *all* targets. - **supported_language**: the language for which the DLL applies, one of `cs` (C#) and `vb` (Visual Basic), and `fs` (F#). The language indicates that the analyzer should be loaded only for a project using that language. If no language is specified then the DLL is assumed to apply to *all* languages that support analyzers. - **analyzer_name**: specifies the DLLs of the analyzer. If you need additional files beyond DLLs, they must be included through a targets or properties files. diff --git a/docs/guides/api/query-for-all-published-packages.md b/docs/guides/api/query-for-all-published-packages.md index ea7a78af6..6d747555e 100644 --- a/docs/guides/api/query-for-all-published-packages.md +++ b/docs/guides/api/query-for-all-published-packages.md @@ -49,7 +49,9 @@ DateTime cursor = DateTime.UtcNow.AddHours(-1); The location of every resource (endpoint) in the NuGet API should be discovered using the [service index](../../api/service-index.md). Because this guide focuses on nuget.org, we'll be using nuget.org's service index. - GET https://api.nuget.org/v3/index.json +``` +GET https://api.nuget.org/v3/index.json +``` The service document is JSON document containing all of the resources on nuget.org. Look for the resource having the `@type` property value of `Catalog/3.0.0`. The associated `@id` property value is the URL to the catalog index itself. @@ -57,13 +59,17 @@ The service document is JSON document containing all of the resources on nuget.o Using the `@id` property value found in the previous step, download the catalog index: - GET https://api.nuget.org/v3/catalog0/index.json +``` +GET https://api.nuget.org/v3/catalog0/index.json +``` Deserialize the [catalog index](../../api/catalog-resource.md#catalog-index). Filter out all [catalog page objects](../../api/catalog-resource.md#catalog-page-object-in-the-index) with `commitTimeStamp` less than or equal to your current cursor value. For each remaining catalog page, download the full document using the `@id` property. - GET https://api.nuget.org/v3/catalog0/page2926.json +``` +GET https://api.nuget.org/v3/catalog0/page2926.json +``` Deserialize the [catalog page](../../api/catalog-resource.md#catalog-page). Filter out all [catalog leaf objects](../../api/catalog-resource.md#catalog-item-object-in-a-page) with `commitTimeStamp` less than or equal to your current cursor value. @@ -73,9 +79,11 @@ After you have downloaded all of the catalog pages not filtered out, you have a At this point, you can perform any custom processing you'd like on the catalog items. If all you need is the ID and version of the package, you can inspect the `nuget:id` and `nuget:version` properties on the catalog item objects found in the pages. Make sure to look at the `@type` property to know if the catalog item concerns an existing package or a deleted package. -If you are interested in the metadata about the package (such at the description, dependencies, .nupkg size, etc), you can fetch the [catalog leaf document](../../api/catalog-resource.md#catalog-leaf) using the `@id` property. +If you are interested in the metadata about the package (such as the description, dependencies, .nupkg size, etc), you can fetch the [catalog leaf document](../../api/catalog-resource.md#catalog-leaf) using the `@id` property. - GET https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json +``` +GET https://api.nuget.org/v3/catalog0/data/2015.02.01.11.18.40/windowsazure.storage.1.0.0.json +``` This document has all of the metadata included in the [package metadata resource](../../api/registration-base-url-resource.md), and more! @@ -97,7 +105,7 @@ If, for some reason, you have a bug in how you process catalog leaves, you can s Because the catalog is a set of JSON documents available over HTTP, it can be interacted with using any programming language that has an HTTP client and JSON deserializer. -C# samples are available in the [NuGet/Samples repository](https://github.com/NuGet/Samples/tree/master/CatalogReaderExample). +C# samples are available in the [NuGet/Samples repository](https://github.com/NuGet/Samples/tree/main/CatalogReaderExample). ```cli git clone https://github.com/NuGet/Samples.git @@ -105,11 +113,11 @@ git clone https://github.com/NuGet/Samples.git ### Catalog SDK -The easiest way to consume the catalog is to use the pre-release .NET catalog SDK package: [NuGet.Protocol.Catalog](https://dotnet.myget.org/feed/nuget-build/package/nuget/NuGet.Protocol.Catalog). This package is available on the `nuget-build` MyGet feed, for which you use the NuGet package source URL `https://dotnet.myget.org/F/nuget-build/api/v3/index.json`. +The easiest way to consume the catalog is to use the pre-release .NET catalog SDK package `NuGet.Protocol.Catalog`, which is available on Azure Artifacts using the following NuGet package source URL: `https://pkgs.dev.azure.com/dnceng/public/_packaging/nuget-build/nuget/v3/index.json`. You can install this package to a project compatible with `netstandard1.3` or greater (such as .NET Framework 4.6). -A sample using this package is available on GitHub in the [NuGet.Protocol.Catalog.Sample project](https://github.com/NuGet/Samples/tree/master/CatalogReaderExample/NuGet.Protocol.Catalog.Sample). +A sample using this package is available on GitHub in the [NuGet.Protocol.Catalog.Sample project](https://github.com/NuGet/Samples/tree/main/CatalogReaderExample/NuGet.Protocol.Catalog.Sample). #### Sample output @@ -147,9 +155,9 @@ warn: NuGet.Protocol.Catalog.CatalogProcessor[0] ### Minimal sample -For an example with fewer dependencies that illustrates the interaction with the catalog in more detail, see the [CatalogReaderExample sample project](https://github.com/NuGet/Samples/tree/master/CatalogReaderExample/CatalogReaderExample). The project targets `netcoreapp2.0` and depends on the [NuGet.Protocol 4.4.0](https://www.nuget.org/packages/NuGet.Protocol/4.4.0) (for resolving the service index) and [Newtonsoft.Json 9.0.1](https://www.nuget.org/packages/Newtonsoft.Json/9.0.1) (for JSON deserialization). +For an example with fewer dependencies that illustrates the interaction with the catalog in more detail, see the [CatalogReaderExample sample project](https://github.com/NuGet/Samples/tree/main/CatalogReaderExample/CatalogReaderExample). The project targets `netcoreapp2.0` and depends on the [NuGet.Protocol 4.4.0](https://www.nuget.org/packages/NuGet.Protocol/4.4.0) (for resolving the service index) and [Newtonsoft.Json 9.0.1](https://www.nuget.org/packages/Newtonsoft.Json/9.0.1) (for JSON deserialization). -The main logic of the code is visible in the [Program.cs file](https://github.com/NuGet/Samples/blob/master/CatalogReaderExample/CatalogReaderExample/Program.cs). +The main logic of the code is visible in the [Program.cs file](https://github.com/NuGet/Samples/blob/main/CatalogReaderExample/CatalogReaderExample/Program.cs). #### Sample output diff --git a/docs/guides/create-packages-for-xamarin.md b/docs/guides/create-packages-for-xamarin.md deleted file mode 100644 index a0af5c212..000000000 --- a/docs/guides/create-packages-for-xamarin.md +++ /dev/null @@ -1,267 +0,0 @@ ---- -title: Create NuGet Packages for Xamarin (for iOS, Android, and Windows) with Visual Studio 2015 -description: An end-to-end walkthrough of creating NuGet packages for Xamarin that use native APIs on iOS, Android, and Windows. -author: karann-msft -ms.author: karann -ms.date: 01/09/2017 -ms.topic: tutorial ---- - -# Create packages for Xamarin with Visual Studio 2015 - -A package for Xamarin contains code that uses native APIs on iOS, Android, and Windows, depending on the run-time operating system. Although this is straightforward to do, it's preferable to let developers consume the package from a PCL or .NET Standard libraries through a common API surface area. - -In this walkthrough you use Visual Studio 2015 create a cross-platform NuGet package that can be used in mobile projects on iOS, Android, and Windows. - -1. [Prerequisites](#prerequisites) -1. [Create the project structure and abstraction code](#create-the-project-structure-and-abstraction-code) -1. [Write your platform-specific code](#write-your-platform-specific-code) -1. [Create and update the .nuspec file](#create-and-update-the-nuspec-file) -1. [Package the component](#package-the-component) -1. [Related topics](#related-topics) - -## Prerequisites - -1. Visual Studio 2015 with Universal Windows Platform (UWP) and Xamarin. Install the Community edition for free from [visualstudio.com](https://www.visualstudio.com/); you can use the Professional and Enterprise editions as well, of course. To include UWP and Xamarin tools, select a Custom install and check the appropriate options. -1. NuGet CLI. Download the latest version of nuget.exe from [nuget.org/downloads](https://nuget.org/downloads), saving it to a location of your choice. Then add that location to your PATH environment variable if it isn't already. - -> [!Note] -> nuget.exe is the CLI tool itself, not an installer, so be sure to save the downloaded file from your browser instead of running it. - -## Create the project structure and abstraction code - -1. Download and run the [Plugin for Xamarin Templates extension](https://marketplace.visualstudio.com/items?itemName=vs-publisher-473885.PluginForXamarinTemplates) for Visual Studio. These templates will make it easy to create the necessary project structure for this walkthrough. -1. In Visual Studio, **File > New > Project**, search for `Plugin`, select the **Plugin for Xamarin** template, change the name to LoggingLibrary, and click OK. - - ![New Blank App (Xamarin.Forms Portable) project in Visual Studio](media/CrossPlatform-NewProject.png) - -The resulting solution contains two PCL projects, along with a variety of platform-specific projects: - -- The PCL named `Plugin.LoggingLibrary.Abstractions (Portable)`, defines the public interface (the API surface area) of the component, in this case the `ILoggingLibrary` interface contained in the ILoggingLibrary.cs file. This is where you define the interface to your library. -- The other PCL, `Plugin.LoggingLibrary (Portable)`, contains code in CrossLoggingLibrary.cs that will locate a platform-specific implementation of the abstract interface at run time. You typically don't need to modify this file. -- The platform-specific projects, such as `Plugin.LoggingLibrary.Android`, each contain contain a native implementation of the interface in their respective LoggingLibraryImplementation.cs files. This is where you build out your library's code. - -By default, the ILoggingLibrary.cs file of the Abstractions project contains an interface definition, but no methods. For the purposes of this walkthrough, add a `Log` method as follows: - -```cs -using System; - -namespace Plugin.LoggingLibrary.Abstractions -{ - /// - /// Interface for LoggingLibrary - /// - public interface ILoggingLibrary - { - /// - /// Log a message - /// - void Log(string text); - } -} -``` - -## Write your platform-specific code - -To implement a platform-specific implementation of the `ILoggingLibrary` interface and its methods, do the following: - -1. Open the `LoggingLibraryImplementation.cs` file of each platform project and add the necessary code. For example (using the `Plugin.LoggingLibrary.Android` project): - - ```cs - using Plugin.LoggingLibrary.Abstractions; - using System; - - namespace Plugin.LoggingLibrary - { - /// - /// Implementation for Feature - /// - public class LoggingLibraryImplementation : ILoggingLibrary - { - /// - /// Log a message - /// - public void Log(string text) - { - throw new NotImplementedException("Called Log on Android"); - } - } - } - ``` - -1. Repeat this implementation in the projects for each platform you want to support. -1. Right-click the iOS project, select **Properties**, click the **Build** tab, and remove "\iPhone" from the **Output path** and **XML documentation file** settings. This is just for later convenience in this walkthrough. Save the file when done. -1. Right-click the solution, select **Configuration Manager...**, and check the **Build** boxes for the PCLs and each platform you're supporting. -1. Right-click the solution and select **Build Solution** to check your work and produce the artifacts that you package next. If you get errors about missing references, right-click the solution, select **Restore NuGet Packages** to install dependencies, and rebuild. - -> [!Note] -> To build for iOS you need a networked Mac connected to Visual Studio as described on [Introduction to Xamarin.iOS for Visual Studio](https://developer.xamarin.com/guides/ios/getting_started/installation/windows/introduction_to_xamarin_ios_for_visual_studio/). If you don't have a Mac available, clear the iOS project in the configuration manager (step 3 above). - -## Create and update the .nuspec file - -1. Open a command prompt, navigate to the `LoggingLibrary` folder that's one level below where the `.sln` file is, and run the NuGet `spec` command to create the initial `Package.nuspec` file: - - ```cli - nuget spec - ``` - -1. Rename this file to `LoggingLibrary.nuspec` and open it in an editor. -1. Update the file to match the following, replacing YOUR_NAME with an appropriate value. The `` value, specifically, must be unique across nuget.org (see the naming conventions described in [Creating a package](../create-packages/creating-a-package.md#choose-a-unique-package-identifier-and-setting-the-version-number)). Also note that you must also update the author and description tags or you get an error during the packing step. - - ```xml - - - - LoggingLibrary.YOUR_NAME - 1.0.0 - LoggingLibrary - YOUR_NAME - YOUR_NAME - false - Awesome application logging utility - First release - Copyright 2016 - logger logging logs - - - ``` - -> [!Tip] -> You can suffix your package version with `-alpha`, `-beta` or `-rc` to mark your package as pre-release, check [Pre-release versions](../create-packages/prerelease-packages.md) for more information about pre-release versions. - -### Add reference assemblies - -To include platform-specific reference assemblies, add the following to the `` element of `LoggingLibrary.nuspec` as appropriate for your supported platforms: - -```xml - - - - - - - - - - - - - - - - - - - - -``` - -> [!Note] -> To shorten the names of the DLL and XML files, right-click on any given project, select the **Library** tab, and change the assembly names. - -### Add dependencies - -If you have specific dependencies for native implementations, use the `` element with `` elements to specify them, for example: - -```xml - - - - - - - - - - - - -``` - -For example, the following would set iTextSharp as a dependency for the UAP target: - -```xml - - - - - -``` - -### Final .nuspec - -Your final `.nuspec` file should now look like the following, where again YOUR_NAME should be replaced with an appropriate value: - -```xml - - - - LoggingLibrary.YOUR_NAME - 1.0.0 - LoggingLibrary - YOUR_NAME - YOUR_NAME - false - Awesome application logging utility - First release - Copyright 2016 - logger logging logs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - -## Package the component - -With the completed `.nuspec` referencing all the files you need to include in the package, you're ready to run the `pack` command: - -```cli -nuget pack LoggingLibrary.nuspec -``` - -This will generate `LoggingLibrary.YOUR_NAME.1.0.0.nupkg`. Opening this file in a tool like the [NuGet Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer) and expanding all the nodes, you see the following contents: - -![NuGet Package Explorer showing the LoggingLibrary package](media/Cross-Platform-PackageExplorer.png) - -> [!Tip] -> A `.nupkg` file is just a ZIP file with a different extension. You can also examine package contents, then, by changing `.nupkg` to `.zip`, but remember to restore the extension before uploading a package to nuget.org. - -To make your package available to other developers, follow the instructions on [Publish a package](../nuget-org/publish-a-package.md). - -## Related topics - -- [Nuspec Reference](../reference/nuspec.md) -- [Symbol packages](../create-packages/symbol-packages.md) -- [Package versioning](../concepts/package-versioning.md) -- [Supporting Multiple .NET Framework Versions](../create-packages/supporting-multiple-target-frameworks.md) -- [Include MSBuild props and targets in a package](../create-packages/creating-a-package.md#include-msbuild-props-and-targets-in-a-package) -- [Creating Localized Packages](../create-packages/creating-localized-packages.md) \ No newline at end of file diff --git a/docs/guides/media/BetaChannel-ExtensionUpdate.png b/docs/guides/media/BetaChannel-ExtensionUpdate.png deleted file mode 100644 index af96fe2f9..000000000 Binary files a/docs/guides/media/BetaChannel-ExtensionUpdate.png and /dev/null differ diff --git a/docs/guides/media/BetaChannel-ToolsSettings.png b/docs/guides/media/BetaChannel-ToolsSettings.png deleted file mode 100644 index c5afdc858..000000000 Binary files a/docs/guides/media/BetaChannel-ToolsSettings.png and /dev/null differ diff --git a/docs/guides/media/CrossPlatform-NewProject.png b/docs/guides/media/CrossPlatform-NewProject.png deleted file mode 100644 index 449fa4d0c..000000000 Binary files a/docs/guides/media/CrossPlatform-NewProject.png and /dev/null differ diff --git a/docs/guides/media/NuGet4-01-Workload.png b/docs/guides/media/NuGet4-01-Workload.png deleted file mode 100644 index 67a102c9d..000000000 Binary files a/docs/guides/media/NuGet4-01-Workload.png and /dev/null differ diff --git a/docs/guides/media/NuGet4-02-NewProject.png b/docs/guides/media/NuGet4-02-NewProject.png deleted file mode 100644 index b4f082347..000000000 Binary files a/docs/guides/media/NuGet4-02-NewProject.png and /dev/null differ diff --git a/docs/guides/media/NuGet4-03-PackageExplorer.png b/docs/guides/media/NuGet4-03-PackageExplorer.png deleted file mode 100644 index 30d385833..000000000 Binary files a/docs/guides/media/NuGet4-03-PackageExplorer.png and /dev/null differ diff --git a/docs/guides/media/UWP-BatchBuild-CS.png b/docs/guides/media/UWP-BatchBuild-CS.png new file mode 100644 index 000000000..c0af0602c Binary files /dev/null and b/docs/guides/media/UWP-BatchBuild-CS.png differ diff --git a/docs/guides/media/UWP-GenerateXMLDocFiles-CS.png b/docs/guides/media/UWP-GenerateXMLDocFiles-CS.png new file mode 100644 index 000000000..aee1fe27c Binary files /dev/null and b/docs/guides/media/UWP-GenerateXMLDocFiles-CS.png differ diff --git a/docs/guides/media/UWP-NewProject-CS.png b/docs/guides/media/UWP-NewProject-CS.png new file mode 100644 index 000000000..f99e7c4e6 Binary files /dev/null and b/docs/guides/media/UWP-NewProject-CS.png differ diff --git a/docs/guides/media/UWP-NewXAMLControl-CS.png b/docs/guides/media/UWP-NewXAMLControl-CS.png new file mode 100644 index 000000000..9f580af74 Binary files /dev/null and b/docs/guides/media/UWP-NewXAMLControl-CS.png differ diff --git a/docs/hosting-packages/Local-Feeds.md b/docs/hosting-packages/Local-Feeds.md index 35fb0580b..6b422460f 100644 --- a/docs/hosting-packages/Local-Feeds.md +++ b/docs/hosting-packages/Local-Feeds.md @@ -1,10 +1,10 @@ --- title: Setting up Local NuGet Feeds description: How to create a local feed for NuGet packages using folders on your local network -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 12/06/2017 -ms.topic: conceptual +ms.topic: how-to --- # Local feeds @@ -20,11 +20,13 @@ To enable the source, add its pathname (such as `\\myserver\packages`) to the li The hierarchical versioned folder tree has the following general structure: - \\myserver\packages - └─ - └─ - ├─..nupkg - └─ +``` +\\myserver\packages + └─ + └─ + ├─..nupkg + └─ +``` NuGet creates this structure automatically when you use the [`nuget add`](../reference/cli-reference/cli-ref-add.md) command to copy a package to the feed: diff --git a/docs/hosting-packages/NuGet-Server.md b/docs/hosting-packages/NuGet-Server.md index e901e89ff..b79f0a22e 100644 --- a/docs/hosting-packages/NuGet-Server.md +++ b/docs/hosting-packages/NuGet-Server.md @@ -1,10 +1,10 @@ --- title: Using NuGet.Server to Host NuGet Feeds description: How to create and host a NuGet package feed on any server running IIS using NuGet.Server, making packages available through HTTP and OData. -author: karann-msft -ms.author: karann -ms.date: 03/13/2018 -ms.topic: conceptual +author: JonDouglas +ms.author: jodou +ms.date: 07/11/2023 +ms.topic: how-to --- # NuGet.Server @@ -12,6 +12,7 @@ ms.topic: conceptual NuGet.Server is a package provided by the .NET Foundation that creates an ASP.NET application that can host a package feed on any server that runs IIS. Simply said, NuGet.Server makes a folder on the server available through HTTP(S) (specifically OData). It's easy to set up and is best for simple scenarios. 1. Create an empty ASP.NET Web application in Visual Studio and add the NuGet.Server package to it. + - If you are using Visual Studio 2022, you must add the .NET Framework development tools. You need this so that you can create a new **ASP.NET Web Application (.NET Framework)** project. 1. Configure the `Packages` folder in the application and add packages. 1. Deploy the application to a suitable server. @@ -21,54 +22,39 @@ If you have further questions about NuGet.Server, create an issue on [https://gi ## Create and deploy an ASP.NET Web application with NuGet.Server -1. In Visual Studio, select **File > New > Project**, search for "ASP.NET", select the **ASP.NET Web Application (.NET Framework)** template for C#, and set **Framework** to ".NET Framework 4.6": +1. In Visual Studio, select **File > New > Project**, search for "ASP.NET Web Application (.NET Framework)", select the matching template for **C#**. + + ![Select the .NET Framework web project template](media/Hosting_00-NuGet.Server-ProjectType.png) + +1. Set **Framework** to ".NET Framework 4.6". ![Setting the target framework for a new project](media/Hosting_01-NuGet.Server-Set4.6.png) 1. Give the application a suitable name *other* than NuGet.Server, select OK, and in the next dialog select the **Empty** template, then select **OK**. + ![Select the empty web project](media/Hosting_02-NuGet.Server-Empty.png) + 1. Right-click the project, select **Manage NuGet Packages**. 1. In the Package Manager UI, select the **Browse** tab, then search and install the latest version of the NuGet.Server package if you're targeting .NET Framework 4.6. (You can also install it from the Package Manager Console with `Install-Package NuGet.Server`.) Accept the license terms if prompted. - ![Installing the NuGet.Server package](media/Hosting_02-NuGet.Server-Package.png) + ![Installing the NuGet.Server package](media/Hosting_03-NuGet.Server-Package.png) 1. Installing NuGet.Server converts the empty Web application into a package source. It installs a variety of other packages, creates a `Packages` folder in the application, and modifies `web.config` to include additional settings (see the comments in that file for details). > [!Important] > Carefully inspect `web.config` after the NuGet.Server package has completed its modifications to that file. NuGet.Server may not overwrite existing elements but instead create duplicate elements. Those duplicates will cause an "Internal Server Error" when you later try to run the project. For example, if your `web.config` contains `` before installing NuGet.Server, the package doesn't overwrite it but inserts a second ``. In that case, delete the element with the older framework version. -1. To make packages available in the feed when you publish the application to a server, add each `.nupkg` files to the `Packages` folder in Visual Studio, then set each one's **Build Action** to **Content** and **Copy to Output Directory** to **Copy always**: - - ![Copying packages to the Packages folder in the project](media/Hosting_03-NuGet.Server-Package-Folder.png) - -1. Run the site locally in Visual Studio (using **Debug > Start Without Debugging** or Ctrl+F5). The home page provides the package feed URLs as shown below. If you see errors, carefully inspect your `web.config` for duplicate elements are noted earlier with step 5. +1. Run the site locally in Visual Studio (using **Debug > Start Without Debugging** or Ctrl+F5). The home page provides the package feed URLs as shown below. If you see errors, carefully inspect your `web.config` for duplicate elements as noted earlier. ![Default home page for an application with NuGet.Server](media/Hosting_04-NuGet.Server-FeedHomePage.png) -1. Click on **here** in the area outlined above to see the OData feed of packages. - -1. The first time you run the application, NuGet.Server restructures the `Packages` folder to contain a folder for each package. This matches the [local storage layout](http://blog.nuget.org/20151118/nuget-3.3.html#folder-based-repository-commands) introduced with NuGet 3.3 to improve performance. When adding more packages, continue to follow this structure. +1. The first time you run the application, NuGet.Server restructures the `Packages` folder to contain a folder for each package. This matches the [local storage layout](https://blog.nuget.org/20151118/nuget-3.3.html#folder-based-repository-commands) introduced with NuGet 3.3 to improve performance. When adding more packages, continue to follow this structure. 1. Once you've tested your local deployment, deploy the application to any other internal or external site as needed. 1. Once deployed to `http://`, the URL that you use for the package source will be `http:///nuget`. -## Configuring the Packages folder - -With `NuGet.Server` 1.5 and later, you can more specifically configure the package folder using the `appSetting/packagesPath` value in `web.config`: - -```xml - - - - -``` - -`packagesPath` can be an absolute or virtual path. - -When `packagesPath` is omitted or left blank, the packages folder is the default `~/Packages`. - ## Adding packages to the feed externally Once a NuGet.Server site is running, you can add packages using [nuget push](../reference/cli-reference/cli-ref-push.md) provided that you set an API key value in `web.config`. @@ -87,7 +73,7 @@ To enable this capability, set the `apiKey` to a value (ideally a strong passwor ```xml - + @@ -97,12 +83,45 @@ To enable this capability, set the `apiKey` to a value (ideally a strong passwor If your server is already secured or you do not otherwise require an API key (for example, when using a private server on a local team network), you can set `requireApiKey` to `false`. All users with access to the server can then push packages. +Starting with NuGet.Server 3.0.0, the URL for pushing packages was change to `http:///nuget`. Prior to the +3.0.0 release, the push URL was `http:///api/v2/package`. + +With NuGet 3.2.1 and newer, this legacy URL `/api/v2/package` is enabled in addition to `/nuget` by default via +`enableLegacyPushRoute: true` option in your startup config (`NuGetODataConfig.cs` by default). Note that this feature +does not work when multiple feeds are hosted in the same project. + ## Removing packages from the feed With NuGet.Server, the [nuget delete](../reference/cli-reference/cli-ref-delete.md) command removes a package from the repository provided that you include the API key with the comment. If you want to change the behavior to delist the package instead (leaving it available for package restore), change the `enableDelisting` key in `web.config` to true. +## Configuring the Packages folder + +With `NuGet.Server` 1.5 and later, you can customize the package folder using the `appSettings/packagesPath` value in `web.config`: + +```xml + + + + +``` + +`packagesPath` can be an absolute or virtual path. + +When `packagesPath` is omitted or left blank, the packages folder is the default `~/Packages`. + +## Making packages available when you publish the web app + +To make packages available in the feed when you publish the application to a server, add each `.nupkg` files to the `Packages` folder in Visual Studio, then set each one's **Build Action** to **Content** and **Copy to Output Directory** to **Copy always**: + +![Copying packages to the Packages folder in the project](media/Hosting_05-NuGet.Server-Package-Folder.png) + +## Release Notes + +Release notes for NuGet.Server are available on the [GitHub release page](https://github.com/NuGet/NuGet.Server/releases). +This includes details about bug fixes and new features that are added. + ## NuGet.Server support -For additional help using NuGet.Server, create an issue on [https://github.com/nuget/NuGetGallery/issues](https://github.com/nuget/NuGetGallery/issues). \ No newline at end of file +For additional help using NuGet.Server, create an issue on [https://github.com/nuget/NuGetGallery/issues](https://github.com/nuget/NuGetGallery/issues). diff --git a/docs/hosting-packages/Overview.md b/docs/hosting-packages/Overview.md index 843a72bd3..9d98050e0 100644 --- a/docs/hosting-packages/Overview.md +++ b/docs/hosting-packages/Overview.md @@ -1,10 +1,10 @@ --- title: Overview of Hosting Your Own NuGet Feeds -description: An overview of opens for hosting your own NuGet package feeds or galleries either locally or remotely. -author: karann-msft -ms.author: karann -ms.date: 08/25/2017 -ms.topic: conceptual +description: An overview of options for hosting your own NuGet package feeds or galleries either locally or remotely. +author: JonDouglas +ms.author: jodou +ms.date: 3/2/2022 +ms.topic: concept-article ms.reviewer: anangaur --- @@ -23,15 +23,26 @@ There are also several other NuGet hosting products such as [Azure Artifacts](ht - [Artifactory](https://www.jfrog.com/artifactory/) from JFrog. - [Azure Artifacts](https://www.visualstudio.com/docs/package/nuget/publish), which is also available on Team Foundation Server 2017 and later. - [BaGet](https://github.com/loic-sharma/BaGet), an open-source implementation of NuGet V3 server built on ASP.NET Core +- [BaGetter](https://github.com/bagetter/BaGetter), an open-source and community driven fork of BaGet +- [Bytesafe](https://docs.bytesafe.dev/package-managers/nuget/) A fully managed package and supply chain security platform - [Cloudsmith](https://cloudsmith.io/l/nuget-feed/), a fully managed package management SaaS +- [Feedz.io](https://feedz.io) a fully managed package management SaaS +- [Gitea](https://gitea.io), an open-source, self-hostable Git service supports NuGet as a [package registry](https://docs.gitea.io/en-us/usage/packages/nuget/) - [GitHub package registry](https://help.github.com/articles/configuring-nuget-for-use-with-github-package-registry) +- [GitLab Package Registry](https://docs.gitlab.com/ee/user/packages/nuget_repository/) +- [JetBrains Space](https://www.jetbrains.com/help/space/nuget-feed.html) - [LiGet](https://github.com/ai-traders/liget), an open-source implementation of NuGet V2 server that runs on kestrel in docker -- [MyGet](http://myget.org) -- [Nexus](http://www.sonatype.org/nexus/) from Sonatype. -- [NuGet Server (Open Source)](http://nuget-server.net), an open-source implementation similar to Inedo's NuGet Server +- [MyGet](https://myget.org) +- [Nexus Repository OSS](https://www.sonatype.com/products/sonatype-nexus-oss-download) from Sonatype. +- [NuGet Server (Open Source)](https://github.com/svenkle/nuget-server), an open-source implementation similar to Inedo's NuGet Server - [NuGet Server](http://nugetserver.net/), a community project from Inedo -- [ProGet](http://inedo.com/proget) from Inedo +- [ProGet](https://inedo.com/proget) from Inedo - [Sleet](https://github.com/emgarten/sleet), an open-source NuGet V3 static feed generator - [TeamCity](https://www.jetbrains.com/teamcity/) from JetBrains. +- [RepoFlow](https://www.repoflow.io), a simple and easy-to-use package management platform. Regardless of how packages are hosted, you access them by adding them to the list of available sources in `NuGet.Config`. This can be done in Visual Studio as described in [Package Sources](../consume-packages/install-use-packages-visual-studio.md#package-sources), or from the command line using [`nuget sources`](../reference/cli-reference/cli-ref-sources.md). The path to a source can be a local folder pathname, a network name, or a URL. + +[NuGet's V3 protocol](../api/overview.md) uses a [service index](../api//service-index.md) that contains a list of URLs used by various NuGet operations. +All of the URLs in the service index must be accessible by developer and CI machines to avoid unexpected errors. +When installing any NuGet feed, it is important to validate that none of the service index resources are blocked by a company firewall, or if your network is disconnected from the Internet, that all service index resources are available on your private network. diff --git a/docs/hosting-packages/media/Hosting_00-NuGet.Server-ProjectType.png b/docs/hosting-packages/media/Hosting_00-NuGet.Server-ProjectType.png new file mode 100644 index 000000000..423722608 Binary files /dev/null and b/docs/hosting-packages/media/Hosting_00-NuGet.Server-ProjectType.png differ diff --git a/docs/hosting-packages/media/Hosting_01-NuGet.Server-Set4.6.png b/docs/hosting-packages/media/Hosting_01-NuGet.Server-Set4.6.png index 90592325e..cfab83a18 100644 Binary files a/docs/hosting-packages/media/Hosting_01-NuGet.Server-Set4.6.png and b/docs/hosting-packages/media/Hosting_01-NuGet.Server-Set4.6.png differ diff --git a/docs/hosting-packages/media/Hosting_02-NuGet.Server-Empty.png b/docs/hosting-packages/media/Hosting_02-NuGet.Server-Empty.png new file mode 100644 index 000000000..daf3094bf Binary files /dev/null and b/docs/hosting-packages/media/Hosting_02-NuGet.Server-Empty.png differ diff --git a/docs/hosting-packages/media/Hosting_02-NuGet.Server-Package.png b/docs/hosting-packages/media/Hosting_02-NuGet.Server-Package.png deleted file mode 100644 index 1ecc47dca..000000000 Binary files a/docs/hosting-packages/media/Hosting_02-NuGet.Server-Package.png and /dev/null differ diff --git a/docs/hosting-packages/media/Hosting_03-NuGet.Server-Package-Folder.png b/docs/hosting-packages/media/Hosting_03-NuGet.Server-Package-Folder.png deleted file mode 100644 index 97566ebfa..000000000 Binary files a/docs/hosting-packages/media/Hosting_03-NuGet.Server-Package-Folder.png and /dev/null differ diff --git a/docs/hosting-packages/media/Hosting_03-NuGet.Server-Package.png b/docs/hosting-packages/media/Hosting_03-NuGet.Server-Package.png new file mode 100644 index 000000000..ee3e8e95f Binary files /dev/null and b/docs/hosting-packages/media/Hosting_03-NuGet.Server-Package.png differ diff --git a/docs/hosting-packages/media/Hosting_04-NuGet.Server-FeedHomePage.png b/docs/hosting-packages/media/Hosting_04-NuGet.Server-FeedHomePage.png index b5eafb057..24e82a334 100644 Binary files a/docs/hosting-packages/media/Hosting_04-NuGet.Server-FeedHomePage.png and b/docs/hosting-packages/media/Hosting_04-NuGet.Server-FeedHomePage.png differ diff --git a/docs/hosting-packages/media/Hosting_05-NuGet.Server-Package-Folder.png b/docs/hosting-packages/media/Hosting_05-NuGet.Server-Package-Folder.png new file mode 100644 index 000000000..b3eb68d0c Binary files /dev/null and b/docs/hosting-packages/media/Hosting_05-NuGet.Server-Package-Folder.png differ diff --git a/docs/includes/install-cli.md b/docs/includes/install-cli.md index 6d6429b71..f8a68be7b 100644 --- a/docs/includes/install-cli.md +++ b/docs/includes/install-cli.md @@ -1,30 +1,53 @@ -#### Windows +--- +title: Include +description: Installation steps for the nuget.exe CLI tool on Windows, macOS, and Linux. +author: JonDouglas +ms.author: jodou +ms.date: 11/03/2023 +ms.topic: include +--- -> [!Note] -> NuGet.exe 5.0 and later require .NET Framework 4.7.2 or later to execute. +# [Windows](#tab/windows) -1. Visit [nuget.org/downloads](https://nuget.org/downloads) and select NuGet 3.3 or higher (2.8.6 is not compatible with Mono). The latest version is always recommended, and 4.1.0+ is required to publish packages to nuget.org. -1. Each download is the `nuget.exe` file directly. Instruct your browser to save the file to a folder of your choice. The file is *not* an installer; you won't see anything if you run it directly from the browser. -1. Add the folder where you placed `nuget.exe` to your PATH environment variable to use the CLI tool from anywhere. +Always install the **latest** version of the tool that supports your configuration. -#### macOS/Linux +- You can download the latest recommended version at `https://dist.nuget.org/win-x86-commandline/latest/nuget.exe`. +- If you already have the `nuget.exe` CLI tool installed, you can update the tool to the latest version with the command `nuget update -self`. +- For compatibility with older continuous integration systems, a previous URL, `https://nuget.org/nuget.exe` currently provides the [deprecated version 2.8.6](https://github.com/NuGet/NuGetGallery/issues/5381) of the CLI tool. -Behaviors may vary slightly by OS distribution. +1. Visit [nuget.org/downloads](https://nuget.org/downloads) and download NuGet version 3.3 or later. -1. Install [Mono 4.4.2 or later](http://www.mono-project.com/docs/getting-started/install/). + - Version 5.0 and later requires the .NET Framework version 4.7.2 or later. + - Version 4.1.0 and later is required to publish packages to `nuget.org`. + - Version 2.8.6 isn't compatible with [Mono](https://www.mono-project.com/docs/getting-started/install/). + +1. Each download is the `nuget.exe` file directly. Instruct your browser to save the file to a folder of your choice. The download file isn't an installer, so you don't see anything if you run the file directly from the browser. + +1. To use the CLI tool from anywhere, add the folder location for the `nuget.exe` file to your PATH environment variable. + +# [macOS / Linux](#tab/macos+linux) + +Behaviors can vary slightly based on your operating system distribution. + +> [!NOTE] +> Visual Studio for Mac is scheduled for retirement by August 31, 2024 in accordance with [Microsoft's Modern Lifecycle Policy](/lifecycle/policies/modern). For more information, see [What's happening to Visual Studio for Mac](/visualstudio/mac/what-happened-to-vs-for-mac). + +1. Install [Mono version 4.4.2 or later](https://www.mono-project.com/docs/getting-started/install/). 1. Execute the following command at a shell prompt: - ```bash - # Download the latest stable `nuget.exe` to `/usr/local/bin` - sudo curl -o /usr/local/bin/nuget.exe https://dist.nuget.org/win-x86-commandline/latest/nuget.exe - ``` + ```bash + # Download the latest stable `nuget.exe` to `/usr/local/bin` + sudo curl -o /usr/local/bin/nuget.exe https://dist.nuget.org/win-x86-commandline/latest/nuget.exe + ``` + +1. Create an alias by adding the following script to the appropriate file for your operating system (typically `~/.bash_aliases` or `~/.bash_profile`): -1. Create an alias by adding the following script to the appropriate file for your OS (typically `~/.bash_aliases` or `~/.bash_profile`): + ```bash + # Create as alias for nuget + alias nuget="mono /usr/local/bin/nuget.exe" + ``` - ```bash - # Create as alias for nuget - alias nuget="mono /usr/local/bin/nuget.exe" - ``` +1. Reload the shell. Test the installation by entering the command `nuget` with no parameters. NuGet CLI help should display. -1. Reload the shell. Test the installation by entering `nuget` with no parameters. NuGet CLI help should display. +--- \ No newline at end of file diff --git a/docs/includes/nugetsolver-tool.md b/docs/includes/nugetsolver-tool.md new file mode 100644 index 000000000..3b06bad0e --- /dev/null +++ b/docs/includes/nugetsolver-tool.md @@ -0,0 +1,12 @@ +--- +title: Include +description: Suggest NuGetSolver experimental tool. +author: ErickYondon +ms.author: eryondon +ms.date: 1/16/2024 +ms.topic: include +--- + +> [!Tip] +> **Alternative solution**: NuGetSolver is a Visual Studio Extension developed by Microsoft DevLabs, designed to assist in resolving dependency conflicts. It automates the process of identifying and addressing these issues. For further details, visit the [NuGetSolver](https://marketplace.visualstudio.com/items?itemName=vsext.NuGetSolver) page on the Visual Studio Marketplace and we'd love to hear your feedback about your experience. + diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index a7fcc8c04..000000000 --- a/docs/index.md +++ /dev/null @@ -1,262 +0,0 @@ ---- -title: NuGet Documentation -description: NuGet is the package manager for Microsoft development platforms including .NET. The NuGet client tools provide the ability to create and consume packages. -author: karann-msft -ms.author: karann -ms.date: 02/12/2018 -ms.topic: overview -layout: HubPage -ms.topic: hub-page -hide_bc: true ---- - -
    -
    -

    NuGet Documentation

    -

    NuGet is the package manager for .NET. It enables developers to create, share, and consume useful .NET libraries. NuGet client tools provide the ability to produce and consume these libraries as "packages".

    - - -
    -
    diff --git a/docs/index.yml b/docs/index.yml new file mode 100644 index 000000000..602660403 --- /dev/null +++ b/docs/index.yml @@ -0,0 +1,148 @@ +### YamlMime:Hub +title: NuGet documentation +summary: NuGet is the package manager for .NET. It enables developers to create, share, and consume useful .NET libraries. NuGet client tools provide the ability to produce and consume these libraries as "packages". +brand: nuget +metadata: + title: NuGet documentation | Microsoft Docs + titleSuffix: "" + description: NuGet is the package manager for Microsoft development platforms including .NET. The NuGet client tools provide the ability to create and consume packages. + ms.topic: hub-page + author: JonDouglas + ms.author: jodou + ms.date: 03/03/2025 + +highlightedContent: + items: + - title: What is NuGet? + itemType: overview + url: ./what-is-nuget.md + - title: Install NuGet client tools + itemType: download + url: ./install-nuget-client-tools.md + - title: Learn NuGet + itemType: video + url: https://aka.ms/Nuget101 + - title: NuGet.org + itemType: overview + url: ./nuget-org/overview-nuget-org.md + + +conceptualContent: + title: Consume, create, and publish packages + items: + - title: Get started + links: + - text: Install NuGet client tools + itemType: download + url: ./install-nuget-client-tools.md + - text: Install and use a package - dotnet CLI + itemType: quickstart + url: ./quickstart/install-and-use-a-package-using-the-dotnet-cli.md + - text: Install and use a package - Visual Studio + itemType: quickstart + url: ./quickstart/install-and-use-a-package-in-visual-studio.md + - text: Create a package - dotnet CLI + itemType: quickstart + url: ./quickstart/create-and-publish-a-package-using-the-dotnet-cli.md + - text: Create a package - Visual Studio + itemType: quickstart + url: ./quickstart/create-and-publish-a-package-using-visual-studio.md + - text: Create a .NET Framework package - Visual Studio + itemType: quickstart + url: ./quickstart/create-and-publish-a-package-using-visual-studio-net-framework.md + - title: Consume packages + links: + - text: Workflow (overview) + itemType: overview + url: ./consume-packages/overview-and-workflow.md + - text: Find and choose packages + itemType: get-started + url: ./consume-packages/finding-and-choosing-packages.md + - text: Use Visual Studio + itemType: how-to-guide + url: ./consume-packages/install-use-packages-visual-studio.md + - text: Use dotnet CLI + itemType: how-to-guide + url: ./consume-packages/install-use-packages-dotnet-cli.md + - text: Use nuget.exe CLI + itemType: how-to-guide + url: ./consume-packages/install-use-packages-nuget-cli.md + - text: Use Package Manager Console + itemType: how-to-guide + url: ./consume-packages/install-use-packages-powershell.md + - title: Create packages + links: + - text: Workflow (overview) + itemType: overview + url: ./create-packages/overview-and-workflow.md + - text: Use Visual Studio + itemType: how-to-guide + url: ./quickstart/create-and-publish-a-package-using-visual-studio.md + - text: Use dotnet CLI + itemType: how-to-guide + url: ./create-packages/creating-a-package-dotnet-cli.md + - text: Use nuget.exe CLI + itemType: how-to-guide + url: ./create-packages/creating-a-package.md + - text: Use MSBuild + itemType: how-to-guide + url: ./create-packages/creating-a-package-msbuild.md + - text: Support multiple target frameworks + itemType: reference + url: ./create-packages/multiple-target-frameworks-project-file.md + - title: Publish packages + links: + - text: Publish to NuGet.org + itemType: overview + url: ./nuget-org/publish-a-package.md + - text: Publish to a private feed + itemType: overview + url: ./hosting-packages/overview.md + +additionalContent: + sections: + - title: Reference and resources + items: + - title: NuGet.org + links: + - text: Overview + url: ./nuget-org/overview-nuget-org.md + - text: Individual accounts + url: ./nuget-org/individual-accounts.md + - text: Organizations + url: ./nuget-org/organizations-on-nuget-org.md + - text: API keys + url: ./nuget-org/scoped-api-keys.md + - text: Publish a package + url: ./nuget-org/publish-a-package.md + - title: Reference + links: + - text: dotnet CLI + url: ./reference/dotnet-commands.md + - text: nuget.exe CLI + url: ./reference/nuget-exe-cli-reference.md + - text: Package references + url: ./consume-packages/package-references-in-project-files.md + - text: pack and restore as MSBuild targets + url: ./reference/msbuild-targets.md + - text: .nuspec + url: ./reference/nuspec.md + - text: nuget.config + url: ./reference/nuget-config-file.md + - text: NuGet API + url: ./api/overview.md + - title: Resources + links: + - text: Policies - NuGet + url: ./policies/governance.md + - text: Policies - NuGet.org + url: ./nuget-org/policies/data-requests.md + - text: Release notes + url: ./release-notes/known-issues.md + - text: FAQ - NuGet + url: ./resources/nuget-faq.yml + - text: FAQ - NuGet.org + url: ./nuget-org/nuget-org-faq.yml + + + footer: "[Blogs](https://devblogs.microsoft.com/nuget/) - [Twitter](https://twitter.com/nuget) - [Stack Overflow](https://stackoverflow.com/questions/tagged/nuget)" \ No newline at end of file diff --git a/docs/install-nuget-client-tools.md b/docs/install-nuget-client-tools.md index fc026f4ca..1a2915b63 100644 --- a/docs/install-nuget-client-tools.md +++ b/docs/install-nuget-client-tools.md @@ -1,9 +1,9 @@ --- -title: Installing NuGet client tools -description: Guidance on installing client tools, the dotnet and nuget command-line interfaces (CLI), and the Package Manager for Visual Studio. -author: karann-msft -ms.author: karann -ms.date: 06/20/2019 +title: Install NuGet client tools +description: Learn how to install and use the dotnet and NuGet client command-line interface (CLI) tools and the Package Manager tool for Visual Studio. +author: JonDouglas +ms.author: jodou +ms.date: 03/03/2025 ms.topic: quickstart --- @@ -11,98 +11,132 @@ ms.topic: quickstart > **Looking to install a package? See [Ways to install NuGet packages](consume-packages/overview-and-workflow.md#ways-to-install-a-nuget-package).** -To work with NuGet, as a package consumer or creator, you can use command-line interface (CLI) tools as well as NuGet features in Visual Studio. This article briefly outlines the capabilities of the different tools, how to install them, and their comparative [feature availability](#feature-availability). To get started using NuGet to consume packages, see [Install and use a package (dotnet CLI)](quickstart/install-and-use-a-package-using-the-dotnet-cli.md) and [Install and use a package (Visual Studio)](quickstart/install-and-use-a-package-in-visual-studio.md). To get started creating NuGet packages, see [Create and publish a NET Standard package (dotnet CLI)](quickstart/create-and-publish-a-package-using-the-dotnet-cli.md) and [Create and publish a NET Standard package (Visual Studio)](quickstart/create-and-publish-a-package-using-visual-studio.md). +To work with NuGet as a package consumer or creator, you can use command-line interface (CLI) tools and NuGet features in Visual Studio. This article briefly outlines the capabilities of the different tools, how to install them, and their comparative [feature availability](#feature-availability). -| Tool                | Description | Download          | -|:------------- |:-------------|:-----| -| [dotnet.exe](#dotnetexe-cli) | CLI tool for .NET Core and .NET Standard libraries, and for any [SDK-style project](resources/check-project-format.md) such as one that targets .NET Framework. Included with the .NET Core SDK and provides core NuGet features on all platforms. (Starting in Visual Studio 2017, the dotnet CLI is automatically installed with any .NET Core related workloads.)| [.NET Core SDK](https://www.microsoft.com/net/download/) | -| [nuget.exe](#nugetexe-cli) | CLI tool for .NET Framework libraries and for any [non-SDK-style project](resources/check-project-format.md) such as one that targets .NET Standard libraries. Provides all NuGet capabilities on Windows, provides most features on Mac and Linux when running under Mono. | [nuget.exe](https://dist.nuget.org/win-x86-commandline/latest/nuget.exe) | -| [Visual Studio](#visual-studio) | On Windows, provides NuGet capabilities through the Package Manager UI and Package Manager Console; included with .NET-related workloads. On Mac, provides certain features through the UI. In Visual Studio Code, NuGet features are provided through extensions. | [Visual Studio](https://www.visualstudio.com/downloads/) | +To get started using NuGet to consume packages, see the following articles: -The [MSBuild CLI](reference/msbuild-targets.md) also provides the ability to restore and create packages, which is primarily useful on build servers. MSBuild is not a general-purpose tool for working with NuGet. +- [Install and use a package (dotnet CLI)](quickstart/install-and-use-a-package-using-the-dotnet-cli.md) +- [Install and use a package (Visual Studio on Windows)](quickstart/install-and-use-a-package-in-visual-studio.md) -## CLI tools +To get started creating NuGet packages, see these articles: -The two NuGet CLI tools are `dotnet.exe` and `nuget.exe`. See [feature availability](#feature-availability) for a comparison. +- [Create and publish a NET Standard package (dotnet CLI)](quickstart/create-and-publish-a-package-using-the-dotnet-cli.md) +- [Create and publish a NET Standard package (Visual Studio on Windows)](quickstart/create-and-publish-a-package-using-visual-studio.md) -* To target .NET Core or .NET Standard, use the dotnet CLI. The `dotnet` CLI is required for the SDK-style project format, which uses the [SDK attribute](/dotnet/core/tools/csproj#additions). -* To target .NET Framework (non-SDK-style project only), use the `nuget.exe` CLI. If the project is migrated from `packages.config` to PackageReference, use the dotnet CLI. +| Tool | Description | Download | +|---|---|---| +| [dotnet SDK](#dotnet-sdk) | The CLI tool for .NET Core and .NET Standard libraries, and for any [SDK-style project](resources/check-project-format.md) such as one that targets the .NET Framework. This CLI tool is included with the .NET Core SDK and provides core NuGet features on all platforms. In Visual Studio 2017 and later, the dotnet CLI is automatically installed with any .NET Core related workloads. | [.NET Core SDK](https://www.microsoft.com/net/download/) | +| [nuget.exe](#nugetexe-cli) | The CLI tool for .NET Framework libraries and for any [**non**-SDK-style project](resources/check-project-format.md) such as one that targets .NET Standard libraries. This CLI tool provides all NuGet capabilities on Windows and most features on Mac and Linux when running under [Mono](https://www.mono-project.com/docs/getting-started/install/). | [nuget.exe](https://dist.nuget.org/win-x86-commandline/latest/nuget.exe) | +| [Visual Studio](#visual-studio) | On Windows, the **NuGet Package Manager** is included with Visual Studio 2012 and later. Visual Studio provides the [Package Manager UI](consume-packages/install-use-packages-visual-studio.md) and the [Package Manager Console (PowerShell on Windows)](consume-packages/install-use-packages-powershell.md). You can use these tools to run most NuGet operations. | [Visual Studio](https://www.visualstudio.com/downloads/) | +| [Visual Studio for Mac](/visualstudio/mac/nuget-walkthrough) | On Mac, certain NuGet capabilities are built in directly. Package Manager Console isn't currently available. For other capabilities, use the dotnet SDK or `nuget.exe` CLI tools. | [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/) | +| [Visual Studio Code](https://code.visualstudio.com/docs) | On Windows, Mac, and Linux, NuGet capabilities are available through marketplace extensions, or use the dotnet SDK or `nuget.exe` CLI tools. | [Visual Studio Code](https://code.visualstudio.com/Download/) | -### dotnet.exe CLI +> [!NOTE] +> Visual Studio for Mac is scheduled for retirement by August 31, 2024 in accordance with [Microsoft's Modern Lifecycle Policy](/lifecycle/policies/modern). For more information, see [What's happening to Visual Studio for Mac](/visualstudio/mac/what-happened-to-vs-for-mac). -The .NET Core 2.0 CLI, `dotnet.exe`, works on all platforms (Windows, Mac, and Linux) and provides core NuGet features such as installing, restoring, and publishing packages. `dotnet` provides direct integration with .NET Core project files (such as `.csproj`), which is helpful in most scenarios. `dotnet` is also built directly for each platform and does not require you to install Mono. +The [MSBuild CLI](reference/msbuild-targets.md) also restores and creates packages. MSBuild isn't a general-purpose tool for working with NuGet. This CLI tool is primarily useful on build servers. -Installation: +Package Manager Console commands work only within Visual Studio on Windows and don't work within other PowerShell environments. -- On developer computers, install the [.NET Core SDK](https://aka.ms/dotnetcoregs). Starting in Visual Studio 2017, the dotnet CLI is automatically installed with any .NET Core related workloads. -- For build servers, follow the instructions on [Using .NET Core SDK and tools in Continuous Integration](/dotnet/core/tools/using-ci-with-cli). +## Support policy -To learn how to use basic commands with the dotnet CLI, see [Install and use packages using the dotnet CLI](consume-packages/install-use-packages-dotnet-cli.md). +The Visual Studio for Windows support policy can be found at [Visual Studio Product Lifecycle and Servicing](/visualstudio/productinfo/vs-servicing). -### nuget.exe CLI -The `nuget.exe` CLI, `nuget.exe`, is the command-line utility for Windows that provides all NuGet capabilities; it can also be run on Mac OSX and Linux using [Mono](http://www.mono-project.com/docs/getting-started/install/) with some limitations. +The most recent version of NuGet.exe is fully supported and can be relied on for bug fixes, updates, and enhancements. +For more information on NuGet.exe's support policy, see the [Microsoft Modern Lifecycle Policy](https://aka.ms/lifecycle). -To learn how to use basic commands with the `nuget.exe` CLI, see [Install and use packages using the nuget.exe CLI](consume-packages/install-use-packages-nuget-cli.md). -Installation: +The .NET SDK support policy can be found at [.NET and .NET Core Support Policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core). -[!INCLUDE [install-cli](includes/install-cli.md)] +### Patch Releases -> [!Tip] -> Use `nuget update -self` on Windows to update an existing nuget.exe to the latest version. +Patched versions of NuGet.exe will be released exclusively when critical security fixes are required for a long-term support (LTS) version of Visual Studio or .NET SDK. -> [!Note] -> The latest recommended NuGet CLI is always available at `https://dist.nuget.org/win-x86-commandline/latest/nuget.exe`. For compatibility purposes with older continuous integration systems, a previous URL, `https://nuget.org/nuget.exe` currently provides the [deprecated 2.8.6 CLI tool](https://github.com/NuGet/NuGetGallery/issues/5381). +All security bugs should be reported to the Microsoft Security Response Center (MSRC) at [MSRC's report page](https://aka.ms/opensource/security/create-report). +Also, see the [security policy in the NuGet.Client repo](https://github.com/NuGet/NuGet.Client/blob/dev/SECURITY.md). + +### NuGet.exe unlisting + +Out-of-support, deprecated, or vulnerable NuGet.exe versions will be removed from [tools.json](./api/tools-json.md). ## Visual Studio -- Visual Studio Code: NuGet capabilities are available through marketplace extensions, or use the `dotnet.exe` or `nuget.exe` CLI tools. +In Visual Studio 2017 and later, the Visual Studio installer includes the NuGet Package Manager with any workload that employs .NET. + +You can also install the Package Manager separately or verify your installation. Run the Visual Studio installer and check the option setting under **Individual Components > Code tools > NuGet package manager**. For more information, see [Install and manage packages in Visual Studio by using the NuGet Package Manager](consume-packages/install-use-packages-visual-studio.md). + +> [!NOTE] +> For earlier versions of Visual Studio, you can download NuGet extensions at [https://dist.nuget.org/index.html](https://dist.nuget.org/index.html). + +## CLI tools + +You can use either the dotnet CLI or the `nuget.exe` CLI to support NuGet features in the Visual Studio IDE. The dotnet CLI is installed with some Visual Studio workloads, such as .NET Core. The `nuget.exe` CLI must be installed separately as described earlier. For a feature comparison of the tools, see the [feature availability](#feature-availability) section. + +- To target .NET Core or .NET Standard, use the dotnet SDK CLI tool. This CLI is required for the SDK-style project format, which uses the [SDK attribute](/dotnet/core/tools/csproj#additions). + +- To target the .NET Framework (non-SDK-style project only), use the `nuget.exe` CLI tool. If the project is migrated from `packages.config` to PackageReference, use the dotnet SDK CLI tool instead. -- Visual Studio for Mac: certain NuGet capabilities are built in directly. See [Including a NuGet package in your project](/visualstudio/mac/nuget-walkthrough) for a walkthrough. For other capabilities, use the `dotnet.exe` or `nuget.exe` CLI tools. +### dotnet SDK -- Visual Studio on Windows: The **NuGet Package Manager** is included with Visual Studio 2012 and later. Visual Studio provides the [Package Manager UI](consume-packages/install-use-packages-visual-studio.md) and the [Package Manager Console](consume-packages/install-use-packages-powershell.md), through which you can run most NuGet operations. - - Starting in Visual Studio 2017, the installer includes the NuGet Package Manager with any workload that employs .NET. To install separately, or to verify that the Package Manager is installed, run the Visual Studio installer and check the option under **Individual Components > Code tools > NuGet package manager**. - - The Package Manager UI and Console are unique to Visual Studio on Windows. They are not presently available on Visual Studio for Mac. - - A CLI tool is required to support NuGet features in the IDE. You can use either the `dotnet` CLI or the the `nuget.exe` CLI. The `dotnet` CLI is installed with some Visual Studio workloads, such as .NET Core. The `nuget.exe` CLI must be installed separately as described earlier. - - Package Manager Console commands work only within Visual Studio on Windows and do not work within other PowerShell environments. - - For Visual Studio 2010 and earlier, install the "NuGet Package Manager for Visual Studio" extension. - - NuGet Extensions for Visual Studio 2013 and 2015 can also be downloaded from [https://dist.nuget.org/index.html](https://dist.nuget.org/index.html). - - If you'd like to preview upcoming NuGet features, install a [Visual Studio Preview](https://www.visualstudio.com/vs/preview/), which works side-by-side with stable releases of Visual Studio. To report problems or share ideas for previews, open an issue on the [NuGet GitHub repository](https://github.com/Nuget/Home/issues). +The dotnet SDK is the .NET Core 2.0 CLI tool, which works on all platforms (Windows, Mac, and Linux) and provides core NuGet features such as installing, restoring, and publishing packages. The dotnet CLI provides direct integration with .NET Core project files (such as `.csproj`), which is helpful in most scenarios. This CLI is also built directly for each platform and doesn't require installation of [Mono](https://www.mono-project.com/docs/getting-started/install/). + +#### Install the dotnet SDK + +- On developer computers, install the [.NET Core SDK](https://aka.ms/dotnetcoregs). In Visual Studio 2017 and later, the dotnet CLI is automatically installed with any .NET Core related workloads. + +- For build servers, follow the instructions to [Use the .NET Core SDK and tools in continuous integration](/dotnet/core/tools/using-ci-with-cli). + +To learn how to use basic commands with the dotnet SDK CLI tool, see [Install and manage NuGet packages with the dotnet CLI](consume-packages/install-use-packages-dotnet-cli.md). + +### nuget.exe CLI + +The NuGet CLI, `nuget.exe`, is the command-line utility for Windows that provides all NuGet capabilities. This CLI can also run on Mac OSX and Linux by using [Mono](https://www.mono-project.com/docs/getting-started/install/) with some limitations. + +To learn how to use basic commands with the `nuget.exe` CLI tool, see [Manage NuGet packages with the nuget.exe CLI](consume-packages/install-use-packages-nuget-cli.md). + +#### Install nuget.exe + +[!INCLUDE [install-cli](includes/install-cli.md)] ## Feature availability +The following table compares the available features for the dotnet and `nuget.exe` CLI tools for supported platforms. + | Feature | dotnet CLI | nuget CLI (Windows) | nuget CLI (Mono) | Visual Studio (Windows) | Visual Studio for Mac | | --- | --- | --- | --- | --- | --- | -| Search packages | | ✔ | ✔ | ✔ | ✔ | -| Install/uninstall packages | ✔ | ✔(1) | ✔ | ✔ | ✔ | +| Search packages | ✔ | ✔ | ✔ | ✔ | ✔ | +| Install/uninstall packages | ✔ | ✔ (1) | ✔ | ✔ | ✔ | | Update packages | ✔ | ✔ | | ✔ | ✔ | -| Restore packages | ✔ | ✔ | ✔(2) | ✔ | ✔ | -| Manage package feeds (sources) | | ✔ | ✔ | ✔ | ✔ | +| Restore packages | ✔ | ✔ | ✔ (2) | ✔ | ✔ | +| Manage package feeds (sources) | ✔ | ✔ | ✔ | ✔ | ✔ | | Manage packages on a feed | ✔ | ✔ | ✔ | | | | Set API keys for feeds | | ✔ | ✔ | | | -| Create packages(3) | ✔ | ✔ | ✔(4) | ✔ | | +| Create packages (3) | ✔ | ✔ | ✔ (4) | ✔ | | | Publish packages | ✔ | ✔ | ✔ | ✔ | | -| Replicate packages | | ✔ | ✔ | | | +| Replicate packages | | ✔ | ✔ | | | | Manage *global-package* and cache folders | ✔ | ✔ | ✔ | | | -| Manage NuGet configuration | | ✔ | ✔ | | | +| Manage NuGet configuration | ✔ | ✔ | ✔ | | | -(1) Does not affect project files; use `dotnet.exe` instead. +**Feature notes** -(2) Works only with `packages.config` file and not with solution (`.sln`) files. +- (1) Doesn't affect project files. Use the dotnet SDK CLI tool instead. +- (2) Works only with `packages.config` file and not with solution (`.sln`) files. +- (3) Various advanced package features are available through the CLI only as they aren't represented in the Visual Studio UI tools. +- (4) Works with `.nuspec` files but not with project files. -(3) Various advanced package features are available through the CLI only as they aren't represented in the Visual Studio UI tools. +## Upcoming features -(4) Works with `.nuspec` files but not with project files. +If you want to preview upcoming NuGet features, install a [Visual Studio Preview](https://www.visualstudio.com/vs/preview/), which works side-by-side with stable releases of Visual Studio. To report problems or share ideas for previews, open an issue on the [NuGet GitHub repository](https://github.com/Nuget/Home/issues). -### Related topics +## Related articles -- [Install and manage packages using Visual Studio](consume-packages/install-use-packages-visual-studio.md) -- [Install and manage packages using PowerShell](consume-packages/install-use-packages-powershell.md) -- [Install and manage packages using dotnet CLI](consume-packages/install-use-packages-dotnet-cli.md) -- [Install and manage packages using nuget.exe CLI](consume-packages/install-use-packages-nuget-cli.md) +- [Install and manage packages by using Visual Studio](consume-packages/install-use-packages-visual-studio.md) +- [Install and manage packages by using the dotnet CLI](consume-packages/install-use-packages-dotnet-cli.md) +- [Install and manage packages by using the nuget.exe CLI](consume-packages/install-use-packages-nuget-cli.md) +- [Install and manage packages by using PowerShell](consume-packages/install-use-packages-powershell.md) +- [Create a package by using the nuget.exe CLI](create-packages/creating-a-package.md) +- [Publish NuGet packages](nuget-org/publish-a-package.md) - [Package Manager Console PowerShell reference](reference/powershell-reference.md) -- [Creating a package](create-packages/creating-a-package.md) -- [Publishing a Package](nuget-org/publish-a-package.md) -Developers working on Windows can also explore the [NuGet Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer), an open-source, stand-alone tool to visually explore, create, and edit NuGet packages. It's very helpful, for example, to make experimental changes to a package structure without rebuilding the package. +Developers working on Windows can also explore the [NuGet Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer). This application is an open-source standalone tool that lets you visually explore, create, and edit NuGet packages. It's helpful for many scenarios, such as making experimental changes to a package structure without rebuilding the package. diff --git a/docs/media/hub/nuget-get-started-consume-packages.svg b/docs/media/hub/nuget-get-started-consume-packages.svg deleted file mode 100644 index 5fa3f7e11..000000000 --- a/docs/media/hub/nuget-get-started-consume-packages.svg +++ /dev/null @@ -1,118 +0,0 @@ - - - - - nuget-get-started-consume-packages - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/media/hub/nuget-get-started-create-packages.svg b/docs/media/hub/nuget-get-started-create-packages.svg deleted file mode 100644 index 2312f695e..000000000 --- a/docs/media/hub/nuget-get-started-create-packages.svg +++ /dev/null @@ -1,144 +0,0 @@ - - - - - nuget-get-started-create-packages - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/media/hub/nuget-get-started-guides.svg b/docs/media/hub/nuget-get-started-guides.svg deleted file mode 100644 index e5df6c263..000000000 --- a/docs/media/hub/nuget-get-started-guides.svg +++ /dev/null @@ -1,149 +0,0 @@ - - - - - nuget-get-started-guides - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/media/hub/nuget-get-started-host-packages.svg b/docs/media/hub/nuget-get-started-host-packages.svg deleted file mode 100644 index 36acde6a4..000000000 --- a/docs/media/hub/nuget-get-started-host-packages.svg +++ /dev/null @@ -1,88 +0,0 @@ - - - - - nuget-get-started-host-packages - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/media/hub/nuget-get-started-quickstarts.svg b/docs/media/hub/nuget-get-started-quickstarts.svg deleted file mode 100644 index 8a79d7c4d..000000000 --- a/docs/media/hub/nuget-get-started-quickstarts.svg +++ /dev/null @@ -1,82 +0,0 @@ - - - - - nuget-get-started-quickstarts - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/media/hub/nuget-get-started-what-is-nuget.svg b/docs/media/hub/nuget-get-started-what-is-nuget.svg deleted file mode 100644 index 7fdc205e4..000000000 --- a/docs/media/hub/nuget-get-started-what-is-nuget.svg +++ /dev/null @@ -1,77 +0,0 @@ - - - - - nuget-get-started-what-is-nuget - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/media/hub/nuget-tools-api.svg b/docs/media/hub/nuget-tools-api.svg deleted file mode 100644 index 85c58eb16..000000000 --- a/docs/media/hub/nuget-tools-api.svg +++ /dev/null @@ -1,73 +0,0 @@ - - - - - nuget-tools-api - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/media/hub/nuget-tools-policies.svg b/docs/media/hub/nuget-tools-policies.svg deleted file mode 100644 index 46503b2da..000000000 --- a/docs/media/hub/nuget-tools-policies.svg +++ /dev/null @@ -1,105 +0,0 @@ - - - - - nuget-tools-policies - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/media/hub/nuget-tools-reference.svg b/docs/media/hub/nuget-tools-reference.svg deleted file mode 100644 index b1935c8e3..000000000 --- a/docs/media/hub/nuget-tools-reference.svg +++ /dev/null @@ -1,94 +0,0 @@ - - - - - nuget-tools-reference - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/media/hub/nuget-tools-tools.svg b/docs/media/hub/nuget-tools-tools.svg deleted file mode 100644 index d45a6b273..000000000 --- a/docs/media/hub/nuget-tools-tools.svg +++ /dev/null @@ -1,95 +0,0 @@ - - - - - nuget-tools-tools - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/media/hub/nuget-tools-vs-extensibility.svg b/docs/media/hub/nuget-tools-vs-extensibility.svg deleted file mode 100644 index 76f787687..000000000 --- a/docs/media/hub/nuget-tools-vs-extensibility.svg +++ /dev/null @@ -1,65 +0,0 @@ - - - - - nuget-tools-vs-extensibility - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/nuget-org/Deprecate-packages.md b/docs/nuget-org/Deprecate-packages.md index c677115ee..e3a365978 100644 --- a/docs/nuget-org/Deprecate-packages.md +++ b/docs/nuget-org/Deprecate-packages.md @@ -4,7 +4,7 @@ description: Detailed description on the process of deprecating packages and how author: anangaur ms.author: anangaur ms.date: 09/23/2019 -ms.topic: conceptual +ms.topic: how-to ms.reviewer: karann-msft --- @@ -40,7 +40,7 @@ Once a package has been deprecated, its consumers are notified about it in the f ### Visual Studio *Available starting in Visual Studio 2019 version 16.3* -Visual Studio warns about a deprecated package's usage on the `Installed` tab.It will lead you to the package and its deprecation information (including the reason it was deprecated and the alternate package to use instead, if present). +Visual Studio warns about a deprecated package's usage on the `Installed` tab. It will show a warning for the package and its deprecation information (including the reason it was deprecated and the alternate package to use instead, if present). ![Deprecated packages on Visual Studio installed tab of package manager](media/deprecation-vs.png) @@ -61,3 +61,81 @@ Project `My.Test.Project` has the following deprecated packages > My.Sample.Lib 6.0.0 Legacy My.Awesome.Package ``` + +## Transfer popularity to a newer package + +Package authors who have deprecated a legacy package can choose to transfer its "popularity" to a newer package to boost the newer package's search ranking. This helps customers discover the newer package instead of the deprecated package. + +For example, let's say I have two packages: + +* My deprecated legacy package, `Contoso.Legacy` with 3 million downloads +* My latest package, `Contoso.Latest` with 5 downloads + +NuGet.org prefers search results with higher downloads/popularity. Given the search query "Contoso", my deprecated package `Contoso.Legacy` would likely rank above my latest package `Contoso.Latest` in search results. + +To solve this problem, I can apply to transfer the popularity of my deprecated legacy package to my latest package. This would cause `Contoso.Latest` to rank higher in search results, while `Contoso.Legacy` would rank lower. Only the internal popularity scores for the packages is impacted, the actual download count for each package will not be affected. + +> [!Note] +> Popularity transfers can make it significantly harder for consumers to find the legacy package. + +See the table below to get a concrete idea of how a popularity transfer may impact search rankings for the query "Contoso": + +| Search ranking | Before popularity transfer | After popularity transfer | +|---------------- |-------------------------------- |-------------------------------- | +| 1 | *Contoso.Legacy, 3M downloads* | *Contoso.Latest, 5 downloads* | +| 2 | Contoso.Scanner, 2M downloads | Contoso.Scanner, 2M downloads | +| 3 | Contoso.Core, 1.5M downloads | Contoso.Core, 1.5M downloads | +| 4 | Contoso.UI, 1M downloads | Contoso.UI, 1M downloads | +| ... | ... | ... | +| 20 | *Contoso.Latest, 5 downloads* | *Contoso.Legacy, 3M downloads* | + +### Popularity transfer application process + +1. Review the [popularity transfer requirements](#popularity-transfer-requirements). +2. Email [account@nuget.org](mailto:account@nuget.org) with the deprecated package whose popularity should be transferred, and, the list of stable package(s) that should receive the popularity transfer. + +After the application is submitted, we will notify you of your application's acceptance or rejection (with the criteria that caused rejection). We may need to ask additional identifying questions to confirm owner identity. + +#### Popularity transfer requirements + +* The legacy packages and new packages must share all owners. +* The new packages must be clearly related to the legacy packages in naming and function (i.e. an evolution or next generation). +* All versions of the legacy packages must be deprecated and point to the new packages receiving the transfer. +* The popularity transfer must not cause confusion for NuGet users or worsen the NuGet search experience. +* The new packages must have a stable version. +* The legacy package must not receive popularity transfers from another deprecated package. + +### Advanced popularity transfer scenarios + +#### Package consolidations + +I can transfer the popularity of multiple deprecated packages in favor of a single new package. For example, let's say I have 3 packages: + +* My first deprecated legacy package, `Contoso.Legacy1` +* My second deprecated legacy package, `Contoso.Legacy2` +* My new consolidated package, `Contoso.Latest` + +After I deprecate `Contoso.Legacy1` and `Contoso.Legacy2`, I can apply to transfer their popularity to `Contoso.Latest`. + +#### Package splits + +A deprecated package's popularity can be transferred to, and divided among, up to 5 newer packages. This is useful if the functionality of a deprecated package has been split among multiple new packages. For example, let's say I have 3 packages: + +* My deprecated legacy package, `Contoso.Legacy` +* My first new package, `Contoso.Web` +* My second new package, `Contoso.Cloud` + +`Contoso.Legacy` includes both web and cloud functionality, but I decided to separate that functionality into different packages for the next generation. After I deprecate `Contoso.Legacy`, I can apply to transfer its popularity to both `Contoso.Web` and `Contoso.Cloud`. + +> [!Warning] +> The transferred popularity will be split evenly between all new packages. As a result, we recommend transferring your deprecated package's popularity to as few packages as possible. + +#### Popularity transfer chains + +A deprecated package cannot transfer its popularity if it is already receiving popularity from another deprecated package. For example, say I have 3 packages: + +* My deprecated legacy package, `Contoso.First` +* My deprecated legacy package, `Contoso.Second` +* My new package, `Contoso.Latest` + +If `Contoso.First` transfers its popularity to `Contoso.Second,` then `Contoso.Second` cannot transfer its popularity to `Contoso.Latest`. Instead, we recommend transferring the popularity of both `Contoso.First` and `Contoso.Second` to `Contoso.Latest`, as per the [Package consolidations](#package-consolidations) scenario. diff --git a/docs/nuget-org/Publish-a-package.md b/docs/nuget-org/Publish-a-package.md index a8ff524af..3dfe32091 100644 --- a/docs/nuget-org/Publish-a-package.md +++ b/docs/nuget-org/Publish-a-package.md @@ -1,119 +1,140 @@ --- -title: How to Publish a NuGet Package -description: Detailed instructions for how to publish a NuGet package to nuget.org or private feeds, and how to manage package ownership on nuget.org. -author: karann-msft -ms.author: karann -ms.date: 05/18/2018 -ms.topic: conceptual +title: How to publish NuGet packages +description: See detailed instructions about how to publish a NuGet package and manage package ownership on nuget.org. +author: JonDouglas +ms.author: jodou +ms.date: 8/29/2022 +ms.topic: how-to ms.reviewer: anangaur --- -# Publishing packages +# Publish NuGet packages -Once you have created a package and have your `.nupkg` file in hand, it's a simple process to make it available to other developers, either publicly or privately: +Once you create a NuGet package and have a *.nupkg* file, you can make the package available to other developers either publicly or privately. This article describes how to share public packages globally through [nuget.org](https://www.nuget.org/packages/manage/upload). -- Public packages are made available to all developers globally through [nuget.org](https://www.nuget.org/packages/manage/upload) as described in this article (requires NuGet 4.1.0+). -- Private packages are available to only a team or organization, by hosting them either a file share, a private NuGet server, [Azure Artifacts](https://www.visualstudio.com/docs/package/nuget/publish), or a third-party repository such as myget, ProGet, Nexus Repository, and Artifactory. For additional details, see [Hosting Packages Overview](../hosting-packages/overview.md). - -This article covers publishing to nuget.org; for publishing to Azure Artifacts, see [Package Management](https://www.visualstudio.com/docs/package/nuget/publish). +You can also make private packages available to only a team or organization by hosting them on a file share, a private NuGet server, or a third-party repository such as myget, ProGet, Nexus Repository, or Artifactory. For more information, see [Host your own NuGet feeds](../hosting-packages/overview.md). For publishing with [Azure Artifacts](https://www.visualstudio.com/docs/package/nuget/publish), see [Publish packages to NuGet.org](/azure/devops/artifacts/nuget/publish-to-nuget-org). ## Publish to nuget.org -For nuget.org, you must sign in with a Microsoft account, with which you'll be asked to register the account with nuget.org. You can also sign in with a nuget.org account created using older versions of the portal. +To publish on nuget.org, sign in to nuget.org with a Microsoft account, and use it to create a free nuget.org account. Follow the instructions at [Add a new individual account](individual-accounts.md#add-a-new-individual-account). + +![Screenshot that shows the NuGet sign in link.](media/publish-nuget-signin.png) + +Once you have an account, you can publish a package to nuget.org by using the nuget.org web portal, the dotnet CLI, or the NuGet CLI version 4.1.0 or above. You can also publish packages through Azure Pipelines. -![NuGet sign in location](media/publish_NuGetSignIn.png) +### Upload to the nuget.org web portal -Next, you can either upload the package through the nuget.org web portal, push to nuget.org from the command line (requires `nuget.exe` 4.1.0+) , or publish as part of a CI/CD process through Azure DevOps Services, as described in the following sections. +To upload a package to the nuget.org website: -### Web portal: use the Upload Package tab on nuget.org +1. Select **Upload** on the top menu at nuget.org, browse to the package on your computer, and select **Open**. -1. Select **Upload** on the top menu of nuget.org and browse to the package location. + ![Screenshot that shows the Upload dialog on nuget.org](media/publish-upload-package.png) - ![Upload a package on nuget.org](media/publish_UploadYourPackage.PNG) + If the package ID already exists on nuget.org, you get an error. Change the package identifier in your project, repack, and try the upload again. -1. nuget.org tells you if the package name is available. If it isn't, change the package identifier in your project, rebuild, and try the upload again. +1. If the package name is available, the **Verify** section opens so you can review the metadata from the package manifest. If you included a [readme file](../nuget-org/package-readme-on-nuget-org.md) in your package, select **Preview** to make sure all content renders properly. -1. If the package name is available, nuget.org opens a **Verify** section in which you can review the metadata from the package manifest. To change any of the metadata, edit your project (project file or `.nuspec` file), rebuild, recreate the package, and upload again. + To change any of the metadata, edit your project file or *.nuspec* file, rebuild, repack, and upload again. -1. Under **Import Documentation** you can paste Markdown, point to your docs with a URL, or upload a documentation file. +1. When all the information is ready, select **Submit**. -1. When all the information is ready, select the **Submit** button +### Push by using a command line -### Command line +To push packages to nuget.org with a command line, you can use either `dotnet.exe` or `nuget.exe` v4.1.0 or above, which implement the required NuGet protocols. For more information, see [NuGet protocols](../api/nuget-protocols.md). -To push packages to nuget.org you must use [nuget.exe v4.1.0 or above](https://www.nuget.org/downloads), which implements the required [NuGet protocols](../api/nuget-protocols.md). You also need an API key, which is created on nuget.org. +To use either command line, you first need to get an API key from nuget.org. -#### Create API keys +#### Create an API key -[!INCLUDE [publish-api-key](../quickstart/includes/publish-api-key.md)] +[!INCLUDE [publish-api-key](../quickstart/includes/publish-api-key-with-link.md)] -#### Publish with dotnet nuget push +#### Use the dotnet CLI [!INCLUDE [publish-dotnet](../quickstart/includes/publish-dotnet.md)] -#### Publish with nuget push +#### Use the NuGet CLI -1. At a command prompt, run the following command, replacing `` with the key obtained from nuget.org: +1. At a command prompt, run the following command, replacing `` with the key you got from nuget.org: ```cli nuget setApiKey ``` - This command stores your API key in your NuGet configuration so that you need repeat this step again on the same computer. + This command stores your API key in your NuGet configuration so you don't need to enter the API key again on the same computer. -1. Push your package to NuGet Gallery using the following command: + > [!NOTE] + > This API key isn't used to authenticate with private feeds. To manage credentials for authenticating with these sources, see the [nuget sources command](../reference/cli-reference/cli-ref-sources.md). + +1. Push the package by using the following command: ```cli nuget push YourPackage.nupkg -Source https://api.nuget.org/v3/index.json ``` -#### Publish signed packages +### Publish with Azure Pipelines + +You can push packages to nuget.org with Azure Pipelines as part of your continuous integration/continuous deployment (CI/CD) process. For more information, see [Publish NuGet packages with Azure Pipelines](/azure/devops/pipelines/artifacts/nuget). + +### Publish a signed package + +To submit a signed package, you must first [register the certificate](../create-packages/Sign-a-Package.md#register-the-certificate-on-nugetorg) you used to sign the package. If you don't meet the [signed package requirements](../reference/Signed-Packages-Reference.md#signature-requirements-on-nugetorg), nuget.org rejects the package. + +### Package size limits + +Nuget.org has a package size limit of about 250 MB. When a package exceeding that limit is uploaded the following error is displayed: -To submit signed packages, you must first [register the certificate](../create-packages/Sign-a-Package.md#register-the-certificate-on-nugetorg) used for signing the packages. +> The package file exceeds the size limit. Please try again. -> [!Warning] -> nuget.org rejects packages that don't satisfy the [signed package requirements](../reference/Signed-Packages-Reference.md#signature-requirements-on-nugetorg). +If such package is pushed from the command line, the following output is produced: -### Package validation and indexing +```text + RequestEntityTooLarge https://www.nuget.org/api/v2/package/ 13903ms +error: Response status code does not indicate success: 413 (The package file exceeds the size limit. Please try again.). +``` -Packages pushed to nuget.org undergo several validations, such as virus checks. (All packages on nuget.org are periodically scanned.) +If you are getting this errors consider revising the package content to reduce its size. If you are packing debug symbols into your package consider publishing them [separately](../create-packages/Symbol-Packages-snupkg.md). Other assets can be published separately as one or more dependency packages to spread them into smaller chunks. -When the package has passed all validation checks, it might take a while for it to be indexed and appear in search results. Once indexing is complete, you receive an email confirming that the package was successfully published. If the package fails a validation check, the package details page will update to display the associated error and you also receive an email notifying you about it. +## Package validation and indexing -Package validation and indexing usually takes under 15 minutes. If the package publishing is taking longer than expected, visit [status.nuget.org](https://status.nuget.org/) to check if nuget.org is experiencing any interruptions. If all systems are operational and the package hasn't been successfully published within an hour, please login to nuget.org and contact us using the Contact Support link on the package page. +Packages pushed to nuget.org undergo several validations, such as virus checks, and existing packages are periodically scanned. When the package passes all validation checks, it might take awhile to be indexed and appear in search results. While the package is being indexed, it appears under **Unlisted Packages**, and you see the following message on the package page: -To see the status of a package, select **Manage packages** under your account name on nuget.org. You receive a confirmation email when validation is complete. +![Screenshot of a message indicating that a package isn't yet published.](media/publish_NotYetIndexed.png) -Note that it might take a while for your package to be indexed and appear in search results where others can find it, during which time you see the following message on your package page: +Once validation and indexing are complete, you receive an email that the package was successfully published. If the package fails a validation check, the package page updates to display the associated error, and you receive a notification email. -![Message indicating a package is not yet published](media/publish_NotYetIndexed.png) +Package validation and indexing usually take less than 15 minutes. If package publishing is taking longer than expected, check nuget.org status at [status.nuget.org](https://status.nuget.org/). If all systems are operational and the package isn't successfully published within an hour, contact nuget.org by using the **Contact support** link on the package page. -### Azure DevOps Services (CI/CD) +To see package status, select **Manage packages** under your account name at upper right on nuget.org, and select the package from **Published Packages** or **Unlisted Packages**. -If you push packages to nuget.org using Azure DevOps Services as part of your Continuous Integration/Deployment process, you must use `nuget.exe` 4.1 or above in the NuGet tasks. Details can be found on [Using the latest NuGet in your build](https://blogs.msdn.microsoft.com/devops/2017/09/29/using-the-latest-nuget-in-your-build/) (Microsoft DevOps blog). + +## Manage package owners on nuget.org -## Managing package owners on nuget.org +Package owners have full permissions for the package, including adding and removing other owners and publishing updates. -Although each NuGet package's `.nuspec` file defines the package's authors, the nuget.org gallery does not use that metadata to define ownership. Instead, nuget.org assigns initial ownership to the person who publishes the package. This is either the logged-in user who uploaded the package through the nuget.org UI, or the users whose API key was used with `nuget SetApiKey` or `nuget push`. +Although the NuGet package's *.nuspec* file defines the package's authors, nuget.org doesn't use that metadata to define ownership. Instead, nuget.org assigns ownership to the person who publishes the package, either the signed-in user who uploaded the package, or the user whose API key was used with `dotnet push`, `nuget SetApiKey`, or `nuget push`. -All package owners have full permissions for the package, including adding and removing other owners, and publishing updates. +To change ownership of a package: -To change ownership of a package, do the following: +1. Sign in to nuget.org with the account that currently owns the package. +1. Select your account name at upper right, select **Manage packages**, and expand **Published Packages**. +1. Select the package you want to manage, and on the right side of the package page, select **Manage package**. +1. On the package management page, select **Owners**. +1. Take one of the following actions: -1. Sign in to nuget.org with the account that is the current owner of the package. -1. Select your account name, select **Manage packages**, and expand **Published Packages**. -1. Select on the package you want to manage, then on the right side select **Manage owners**. + - Select **Remove** to remove the current owner. + - Add an owner under **Add owner** by entering their user name and a message, and selecting **Add**. -From here you have several options: + This action sends an email to the new co-owner with a confirmation link. Once confirmed, that person has full permissions to add and remove owners. Until confirmed, the **Current owners** section shows pending approval for that person. -1. Remove any owner listed under **Current Owners**. -1. Add an owner under **Add Owner** by entering their user name, a message, and selecting **Add**. This action sends an email to that new co-owner with a confirmation link. Once confirmed, that person has full permissions to add and remove owners. (Until confirmed, the **Current Owners** section indicates pending approval for that person.) -1. To transfer ownership (as when ownership changes or a package was published under the wrong account), add the new owner, and once they've confirmed ownership they can remove you from the list. +To transfer ownership, as when ownership changes or a package publishes under the wrong account, add the new owner. Once they confirm ownership, they can remove the old owner from the list. -To assign ownership to a company or group, create a nuget.org account using an email alias that is forwarded to the appropriate team members. For example, various Microsoft ASP.NET packages are co-owned by the [microsoft](http://nuget.org/profiles/microsoft) and [aspnet](http://nuget.org/profiles/aspnet) accounts, which simply such aliases. +To assign ownership to a company or group, create a nuget.org account with an email alias that forwards to the appropriate team members. For example, various Microsoft ASP.NET packages are co-owned by the [microsoft](https://nuget.org/profiles/microsoft) and [aspnet](https://nuget.org/profiles/aspnet) accounts. -### Recovering package ownership +Occasionally, a package might not have an active owner. For example, the original owner might have left the company that produced the package. If you're the rightful owner of a package and need to regain ownership, use the [contact form](https://www.nuget.org/policies/Contact) on nuget.org to explain your situation to the NuGet team. The team follows a process to verify your ownership, including trying to locate the existing owner, and can send you a new invitation to become the package owner. -Occasionally, a package may not have an active owner. For example, the original owner may have left the company that produces the package, nuget.org credentials are lost, or earlier bugs in the gallery left a package ownerless. +## Next steps -If you are the rightful owner of a package and need to regain ownership, use the [contact form](https://www.nuget.org/policies/Contact) on nuget.org to explain your situation to the NuGet team. We then follow a process to verify your ownership of the package, including trying to locate the existing owner through the package's Project URL, Twitter, email, or other means. But if all else fails, we can send you a new invite to become an owner. +- [Package readme on NuGet.org](package-readme-on-nuget-org.md) +- [Package ID prefix reservation](id-prefix-reservation.md) +- [Deprecate packages](deprecate-packages.md) +- [Host your own NuGet feeds](../hosting-packages/overview.md) diff --git a/docs/nuget-org/TOC.md b/docs/nuget-org/TOC.md index b3ce19bca..4c01db05f 100644 --- a/docs/nuget-org/TOC.md +++ b/docs/nuget-org/TOC.md @@ -7,6 +7,8 @@ ## [Publish a package](publish-a-package.md) ## [Package ID prefix reservation](id-prefix-reservation.md) ## [Package deprecation](deprecate-packages.md) +## [Package readme](package-readme-on-nuget-org.md) +## [Package sponsorship](package-sponsorship-on-nuget-org.md) # Policies ## [Data Requests](policies/Data-requests.md) ## [Dispute resolution](policies/dispute-resolution.md) @@ -16,4 +18,4 @@ ## [NuGet API](../api/overview.md) ## [licenses.nuget.org](licenses.nuget.org.md) # Resources -## [FAQ](nuget-org-faq.md) +## [FAQ](nuget-org-faq.yml) diff --git a/docs/nuget-org/id-prefix-reservation.md b/docs/nuget-org/id-prefix-reservation.md index 121c88662..3715dcf3c 100644 --- a/docs/nuget-org/id-prefix-reservation.md +++ b/docs/nuget-org/id-prefix-reservation.md @@ -1,8 +1,8 @@ --- title: ID Prefix Reservation description: Package ID Prefix Reservation feature description and author guide. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 09/07/2019 ms.topic: reference ms.reviewer: karann @@ -68,27 +68,27 @@ After the application is submitted, you are notified of acceptance or rejection ### ID prefix reservation criteria -When reviewing any application for ID prefix reservation, the [nuget.org](https://www.nuget.org/) team will evaluate the application against the below criteria. Not all criteria needs to be met for a prefix to be reserved, but the application may be denied if there is not substantial evidence of the criteria being met (with an explanation given): +When reviewing any application for ID prefix reservation, the [NuGet.org](https://www.nuget.org) team will evaluate the application against the below criteria. Please note that not all criteria need to be met for a prefix to be reserved, but the application may be denied if there is not substantial evidence of the criteria being met (with an explanation given): -1. Does the package ID prefix properly and clearly identify the package owner? +1. Does the package ID prefix properly and clearly identify the reservation owner? -1. Has the package owner [enabled 2FA for their NuGet.org account](individual-accounts.md#enable-two-factor-authentication-2fa)? +1. Is the package ID prefix something common that should not belong to any individual owner or organization? Avoid ID prefix reservations that are shorter than four characters and avoid common or generic words. -1. Are a significant number of the packages that have already been submitted by the owner under the package ID prefix? +1. Would *not* reserving the package ID prefix cause ambiguity, confusion, or other harm to the community? -1. Is the package ID prefix something common that should not belong to any individual owner or organization? - -1. Would *not* reserving the package ID prefix cause ambiguity and confusion for the community? +When publishing packages to NuGet.org within your ID prefix reservation, the following best practices must be considered: 1. Are the identifying properties of the packages that match the package ID prefix clear and consistent (especially the package author)? 1. Do the packages have a license (using the [license](../reference/nuspec.md#license) metadata element and NOT licenseUrl which is being deprecated)? -1. If the packages have an icon (using the iconUrl metadata element), are they also using the [icon](../reference/nuspec.md#icon) metadata element (it is not a requirement to remove the iconUrl)? +1. If the packages have an icon (using the iconUrl metadata element), are they also using the [icon](../reference/nuspec.md#icon) metadata element? It is not a requirement to remove the iconUrl but embedded icons must be used. + +Consider reviewing the full [package authoring best practices guide](../create-packages/package-authoring-best-practices.md) in addition to the points above. ## Third party feed provider scenarios -If a third party feed provider is interested in implementing their own service to provide prefix reservations, you can do so by modifying the search service in the NuGet V3 feed providers. The addition in the feed search service is to add the *verified* property, with examples for the V3 feeds below. The NuGet client will not support the added property in the V2 feed. +If a third party feed provider is interested in implementing their own service to provide prefix reservations, they can do so by modifying the search service in the NuGet V3 feed providers. The change in the feed search service is to add the `verified` property. The NuGet client will not support the added property in the V2 feed. For more information, see the [documentation about the API's search service](../api/search-query-service-resource.md). diff --git a/docs/nuget-org/individual-accounts.md b/docs/nuget-org/individual-accounts.md index 637130b3e..f45e1b841 100644 --- a/docs/nuget-org/individual-accounts.md +++ b/docs/nuget-org/individual-accounts.md @@ -4,7 +4,8 @@ description: Individual acccounts on NuGet.org are required to publish packages author: mikejo5000 ms.author: mikejo ms.date: 06/05/2019 -ms.topic: conceptual +ms.topic: article +ms.custom: sfi-image-nochange --- # Individual accounts on NuGet.org @@ -19,7 +20,12 @@ An organization account has one or more individual accounts as its members. Thes ## Add a new individual account -To create a NuGet.org account, you need to have a personal Microsoft account (MSA) or an Azure Active Directory (AAD) account. If you do not have one, you can [create](https://signup.live.com) one. Follow the following steps if you have an MSA or AAD account. +To create a NuGet.org account, you need to have a personal Microsoft account (MSA) or an Azure Active Directory (AAD) account. If you do not have one, you can [create](https://signup.live.com) one. NuGet.org requires all accounts to have two-factor authentication (2FA) enabled on your MSA or AAD account. You can update your settings in advance using the following links: + +* Microsoft Account (MSA): [Turning two-step verification on or off for your Microsoft account](https://support.microsoft.com/account-billing/turning-two-step-verification-on-or-off-for-your-microsoft-account-b1a56fc2-caf3-a5a1-f7e3-4309e99987ca). +* Work or school Account (AAD): [Set up Security info from a sign-in page](https://support.microsoft.com/account-billing/set-up-security-info-from-a-sign-in-page-28180870-c256-4ebf-8bd7-5335571bf9a8). + +Follow the following steps if you have an MSA or AAD account. 1. Go to the [NuGet.org login page](https://www.nuget.org/users/account/LogOn). @@ -31,6 +37,8 @@ To create a NuGet.org account, you need to have a personal Microsoft account (MS ![Giving permissions to NuGet.org](media/nuget-org-permissions.png) +1. Follow two-factor authentication (2FA) setup steps if you do not have it already enabled. + 1. You will be redirected to *nuget.org*, and asked to register a username. 1. Specify the username in the input box. Please note that the username **is** case sensitive and cannot be changed or renamed later. @@ -41,30 +49,12 @@ To create a NuGet.org account, you need to have a personal Microsoft account (MS You now have a NuGet.org account. You can perform account management on the [account settings](https://www.nuget.org/account) page. -## Enable two-factor authentication (2FA) - -To better protect your account, enable two-factor authentication (recommended). - -1. When logged into your account, open your profile and choose **Enable** under **Login Account**. - - ![Enable 2FA](media/nuget-org-register-2fa.png) - - You will see a message that tells you that the next time you sign in to *nuget.org*, you will be asked for additional credentials. - -2. To complete the authentication at this time, sign out and then sign in again. - -3. When you sign in, choose either text or e-mail as a second form of authentication. - - Verify the phone number or e-mail that is already associated with your Microsoft account. You may need to enter a new phone number or e-mail for your account. If so, enter the required information as instructed, and click **Next**. - - ![Enable 2FA](media/nuget-org-sign-in-2fa.png) - -4. Check your device or e-mail account, and enter the code that you were just sent. - - ![Enable 2FA](media/nuget-org-enter-code-2fa.png) +> [!Note] +> Two-factor authentication, or 2FA, is an extra layer of security used when logging into websites or apps. With 2FA, you have to log in with your Microsoft Account (MSA) and provide another form of authentication that only you know or have access to. -5. Follow any additional instructions to complete Two-factor authentication. +> [!Note] +> 2FA for your NuGet.org account does not impact authentication settings for other accounts or services that may be linked to the Microsoft account you use to login to NuGet.org. ## Delete a NuGet.org account -For help with additional account-related tasks, such as deleting a NuGet.org account, see [NuGet.org account management](nuget-org-faq.md#nugetorg-account-management). +For help with additional account-related tasks, such as deleting a NuGet.org account, see [NuGet.org account management](/nuget/nuget-org/nuget-org-faq#nuget.org-account-management). diff --git a/docs/nuget-org/licenses.nuget.org.md b/docs/nuget-org/licenses.nuget.org.md index 735955e00..f1c85a295 100644 --- a/docs/nuget-org/licenses.nuget.org.md +++ b/docs/nuget-org/licenses.nuget.org.md @@ -1,7 +1,10 @@ --- title: licenses.nuget.org +description: Protocol and display information for licenses.nuget.org. Describes the SPDX data source and rationale. author: agr -ms.date: 02/22/2019 +ms.author: angrigor +ms.date: 03/02/2023 +ms.topic: article --- # licenses.nuget.org @@ -18,6 +21,18 @@ specify their license using a license expression. `nuget pack` or packing with o the [`licenseUrl`](../reference/nuspec.md#licenseurl) element to point to licenses.nuget.org to provide backwards compatibility with older clients that don't support the `license` element. +## License and exception text + +The license and license exception information displayed on licenses.nuget.org is copied from the SPDX project's [license list data repository](https://github.com/spdx/license-list-data). The format that the information is displayed closely mimics the format used by the SPDX website itself, e.g. see [MIT on licenses.nuget.org](https://licenses.nuget.org/MIT) and [MIT on SPDX.org](https://spdx.org/licenses/MIT.html). + +Licenses that are not approved by Open Source Initiative or the Free Software Foundation are not hosted on licenses.nuget.org and are excluded. + +Several styles in addition to plain text are used in the display of the license. According to the [SPDX license list data FAQ](https://github.com/spdx/license-list-XML/blob/main/DOCS/faq.md#what-does-the-blue-text-and-red-text-mean-in-the-license-list-entry), red text is considered replaceable and blue text is considered omitable. For more generally information about the SPDX license list data, see their [FAQ](https://github.com/spdx/license-list-XML/blob/main/DOCS/faq.md) and the [SPDX license template specification](https://spdx.github.io/spdx-spec/v2.3/license-matching-guidelines-and-templates/). + +Note that the data is copied from SPDX to licenses.nuget.org by the nuget.org on an ad hoc basis. If a license identifier is approved by the Open Source Initiative or the Free Software Foundation but does not appear on licenses.nuget.org, please [report an issue](https://github.com/NuGet/NuGetGallery/issues/new/choose), and the nuget.org team work to update licenses.nuget.org and nuget.org package upload validation with the latest data from SPDX. + +If you, as a package author, are not satisfied with the shared license text available on licenses.nuget.org, you can consider using [embedded license text](../reference/nuspec.md#license) (``) instead of a license expression for your NuGet package. This allows you to fully customize your licensing terms and include the customized text within the package. + ## Protocol Licenses.nuget.org is intended to be viewed by people in their browsers, no machine-readable responses are provided. @@ -40,7 +55,7 @@ licenses.nuget.org. | (LGPL-2.0-only WITH FLTK-exception OR Apache-2.0+) | | The service supports only license identifiers and license exception identifiers that are accepted by -nuget.org. All license expressions that contain unsupported license identifiers +nuget.org. Notably, this means only license identifiers that are approved by the Open Source Initiative or the Free Software Foundation will be accepted. All license expressions that contain unsupported license identifiers or license exception identifiers or that does not conform to license expression syntax are considered invalid. @@ -74,4 +89,4 @@ license exception identifier may present in the path portion of the URL. Licenses.nuget.org responds to a request with a known license exception identifier with a HTTP 200 response and a web page containing the reference text for the specified license exception. -Any request containing an unsupported license exception identifier results in an HTTP 404 response. \ No newline at end of file +Any request containing an unsupported license exception identifier results in an HTTP 404 response. diff --git a/docs/nuget-org/media/deprecation-vs.png b/docs/nuget-org/media/deprecation-vs.png index 743573c4a..3ea68d429 100644 Binary files a/docs/nuget-org/media/deprecation-vs.png and b/docs/nuget-org/media/deprecation-vs.png differ diff --git a/docs/nuget-org/media/nuget-org-enter-code-2fa.png b/docs/nuget-org/media/nuget-org-enter-code-2fa.png deleted file mode 100644 index 76c5614ee..000000000 Binary files a/docs/nuget-org/media/nuget-org-enter-code-2fa.png and /dev/null differ diff --git a/docs/nuget-org/media/nuget-org-permissions.png b/docs/nuget-org/media/nuget-org-permissions.png index 024b5ecce..6ab466f4d 100644 Binary files a/docs/nuget-org/media/nuget-org-permissions.png and b/docs/nuget-org/media/nuget-org-permissions.png differ diff --git a/docs/nuget-org/media/nuget-org-register-2fa.png b/docs/nuget-org/media/nuget-org-register-2fa.png deleted file mode 100644 index eadbdcb64..000000000 Binary files a/docs/nuget-org/media/nuget-org-register-2fa.png and /dev/null differ diff --git a/docs/nuget-org/media/nuget-org-register.png b/docs/nuget-org/media/nuget-org-register.png index b159da110..bed06b459 100644 Binary files a/docs/nuget-org/media/nuget-org-register.png and b/docs/nuget-org/media/nuget-org-register.png differ diff --git a/docs/nuget-org/media/nuget-org-sign-in-2fa.png b/docs/nuget-org/media/nuget-org-sign-in-2fa.png deleted file mode 100644 index 589fda9e8..000000000 Binary files a/docs/nuget-org/media/nuget-org-sign-in-2fa.png and /dev/null differ diff --git a/docs/nuget-org/media/publish-nuget-signin.png b/docs/nuget-org/media/publish-nuget-signin.png new file mode 100644 index 000000000..3d302e056 Binary files /dev/null and b/docs/nuget-org/media/publish-nuget-signin.png differ diff --git a/docs/nuget-org/media/publish-upload-package.png b/docs/nuget-org/media/publish-upload-package.png new file mode 100644 index 000000000..735e7da6e Binary files /dev/null and b/docs/nuget-org/media/publish-upload-package.png differ diff --git a/docs/nuget-org/media/publish_NuGetSignIn.PNG b/docs/nuget-org/media/publish_NuGetSignIn.PNG deleted file mode 100644 index cb0ae27cc..000000000 Binary files a/docs/nuget-org/media/publish_NuGetSignIn.PNG and /dev/null differ diff --git a/docs/nuget-org/media/publish_UploadYourPackage.PNG b/docs/nuget-org/media/publish_UploadYourPackage.PNG deleted file mode 100644 index 1a75d990b..000000000 Binary files a/docs/nuget-org/media/publish_UploadYourPackage.PNG and /dev/null differ diff --git a/docs/nuget-org/media/readme-upload-preview.PNG b/docs/nuget-org/media/readme-upload-preview.PNG new file mode 100644 index 000000000..6c280ce8f Binary files /dev/null and b/docs/nuget-org/media/readme-upload-preview.PNG differ diff --git a/docs/nuget-org/media/sponsorship-add-link.png b/docs/nuget-org/media/sponsorship-add-link.png new file mode 100644 index 000000000..3274427db Binary files /dev/null and b/docs/nuget-org/media/sponsorship-add-link.png differ diff --git a/docs/nuget-org/media/sponsorship-button-package-details-page.png b/docs/nuget-org/media/sponsorship-button-package-details-page.png new file mode 100644 index 000000000..a01f0644f Binary files /dev/null and b/docs/nuget-org/media/sponsorship-button-package-details-page.png differ diff --git a/docs/nuget-org/media/sponsorship-display-links.png b/docs/nuget-org/media/sponsorship-display-links.png new file mode 100644 index 000000000..c959b3972 Binary files /dev/null and b/docs/nuget-org/media/sponsorship-display-links.png differ diff --git a/docs/nuget-org/media/sponsorship-link-error-manage-package.png b/docs/nuget-org/media/sponsorship-link-error-manage-package.png new file mode 100644 index 000000000..8862f267a Binary files /dev/null and b/docs/nuget-org/media/sponsorship-link-error-manage-package.png differ diff --git a/docs/nuget-org/media/sponsorship-section-manage-package-page.png b/docs/nuget-org/media/sponsorship-section-manage-package-page.png new file mode 100644 index 000000000..7f9acd289 Binary files /dev/null and b/docs/nuget-org/media/sponsorship-section-manage-package-page.png differ diff --git a/docs/nuget-org/media/trusted-publishing.png b/docs/nuget-org/media/trusted-publishing.png new file mode 100644 index 000000000..8cd0ecfbf Binary files /dev/null and b/docs/nuget-org/media/trusted-publishing.png differ diff --git a/docs/nuget-org/media/unmanaged-aad-tenant.png b/docs/nuget-org/media/unmanaged-aad-tenant.png index 03e74d160..166896024 100644 Binary files a/docs/nuget-org/media/unmanaged-aad-tenant.png and b/docs/nuget-org/media/unmanaged-aad-tenant.png differ diff --git a/docs/nuget-org/nuget-org-faq.md b/docs/nuget-org/nuget-org-faq.md deleted file mode 100644 index 070419c02..000000000 --- a/docs/nuget-org/nuget-org-faq.md +++ /dev/null @@ -1,264 +0,0 @@ ---- -title: NuGet.org Frequently-Asked Questions -description: Common questions and answers for working with the NuGet gallery. -author: shishirx34 -ms.author: shishirh -ms.date: 06/05/2019 -ms.topic: conceptual ---- - -# NuGet.org frequently-asked questions - -## License terms - -**What are the default license terms if a package doesn't provide specific license information?** - -Each package is governed by the terms that are included with the package. You should review the applicable terms before accessing, downloading, or acquiring any packages. On NuGet.org, use the **License Info** link on the package page. - -If a package does not specify the licensing terms, contact the package owner directly using the **Contact owners** link on the NuGet.org package page. Microsoft does not license any intellectual property to you from third party package providers and is not responsible for information provided by third parties. - -## Managing packages on NuGet.org - -**Can I edit package metadata after it's been uploaded?** - -NuGet recommends all packages to be signed. A design principle of package signing is that signed package content must be immutable, which includes the nuspec. Editing the package metadata results in changes to the nuspec, invalidating existing signatures. We recommend modifying existing workflows to not require editing the package metadata after the package has been created. - -Note that dependencies listed for your package are generated automatically from the package itself and cannot be edited. - -In addition, uploading packages to [int.nugettest.org](https://int.nugettest.org) is a great way to test and validate your package without making a package available in the public gallery. API Endpoint: https://apiint.nugettest.org/v3/index.json - -**Can I delete a package published to NuGet.org?** - -In general, we do not support deleting a package published to NuGet.org. Read more about our [policy on deleting packages](policies/deleting-packages.md). - -**Is it possible to reserve names for packages that will be published in future?** - -Yes. You can reserve IDs for packages on [NuGet.org](https://www.nuget.org/) by requesting a package ID prefix for your account. In order to request a package ID prefix, follow the instructions in the [documentation](id-prefix-reservation.md). - -**How do I claim ownership for packages ?** - -See [Managing package owners on NuGet.org](../nuget-org/publish-a-package.md#managing-package-owners-on-nugetorg). - -**How do I deal with a package owner who is violating my software license?** - -We encourage the NuGet community to work together to resolve any disputes that may arise between package owners and the owners of other software. We have crafted a [dispute resolution process](policies/dispute-resolution.md) to follow before asking NuGet.org administrators to intercede. - -**Is it recommended to upload my test packages to NuGet.org?** - -For test purposes, you can use [int.nugettest.org](https://int.nugettest.org), or alternative public NuGet servers like [myget.org](https://myget.org) or [Azure DevOps](https://blogs.msdn.microsoft.com/visualstudioalm/2015/08/27/announcing-package-management-support-for-vsotfs/). - -Note that packages uploaded to int.nugettest.org may not be preserved. - -**What is the maximum size of packages I can upload to NuGet.org?** - -NuGet.org allows packages up to 250MB, but we recommend keeping packages under 1MB if possible and using dependencies to link packages together. As a rule of thumb, packages contain only one assembly to avoid collisions. - -NuGet uses HTTP to download packages, so larger packages have a higher likelihood of failed installs than smaller ones. - -It is possible to share dependencies between multiple packages, making the total download size for consumers of your NuGet packages smaller. - -Dependencies are mostly static and never change. When fixing a bug in code, the dependencies may not need to be updated. If you bundle dependencies, you end up reshipping larger packages every time. By splitting NuGet packages into related dependencies, upgrades are much more fine-grained for consumers of your package. - -## NuGet.org not accessible - -**Why can't I download packages from or upload packages to NuGet.org?** - -First, make sure you're using the latest versions of NuGet. If that version continues to fail, [contact support](https://www.nuget.org/policies/Contact) and provide additional connection troubleshooting information including: - -- The version of NuGet you're using -- The package sources you're using -- A restore log with detailed verbosity -- MTR or a Fiddler traces (see below) -- Your geographical area -- Whether your machine is behind a proxy or firewall? -- Is your machine located on a cloud providers' data center (Azure, AWS etc)? If yes, please provide the name of the provider and the region. - -*To capture MTR:* - -- Download [WinMTR](https://sourceforge.net/projects/winmtr/files/WinMTR-v092.zip/download). -- Enter `api.nuget.org` as the hostname and click **Start**. -- Wait until the **Sent** column is >= 100. - - ![Capturing MTR](media/mtr.png) - -- Copy text to clipboard. - -*To capture Fiddler:* - -- Install the latest version of [Fiddler](http://www.telerik.com/download/fiddler). -- Start Fiddler and disable capturing traffic using the **File > Capture Traffic** menu. -- Remove all sessions (select all items in the list, press the **Delete** key). -- Configure Fiddler to capture HTTPS traffic by checking **Decrypt HTTPS traffic** in the **HTTPS** tab of the **Tools > Fiddler Options...** menu. -- Close Visual Studio. -- Enable the **File > Capture Traffic** menu. -- Start Visual Studio or nuget.exe .exe and perform the actions that are not working. The traffic generated by these actions should show up in Fiddler. -- Once the actions have run, use **File > Save > All Sessions** to store the captured sessions. - -Note: it may be required to set the `HTTP_PROXY` environment variable to `http://127.0.0.1:8888` for routing NuGet traffic through Fiddler. - -If that fails, try the [tips mentioned in this StackOverflow post](http://stackoverflow.com/questions/21049908/using-fiddler-to-sniff-visual-studio-2013-requests-proxy-firewall). - -## NuGet.org account management - -### How to recover NuGet.org password login? - -Please note that the [NuGet.org Password login has been discontinued](https://blog.nuget.org/20180515/NuGet.org-will-only-support-MSA-AAD-starting-June.html) and the only way to log in to NuGet.org is with a personal Microsoft account (MSA) or Azure Active Directory (AAD) account. However, in case you are unable to access your associated MSA/AAD accounts you might need to use password login for recovering your NuGet.org account. In this situation follow the steps below. -- **Requirement:** You will need to have access to the email that is associated with the account for which you need to recover the password. -- Go to the [Forgot password page](https://www.nuget.org/account/ForgotPassword) -- Enter the **email** address that is associated with the NuGet.org account you wish to recover. -- Click the **Send** button. -- You will get an email to the specified email address account with a link to reset your password. Click on this link and set the new password. If you can't find the mail check your "junk" folder. -- Once done, you can now login with username/password on NuGet. -- To login with username/password, use the **Sign in using Nuget.org account** link on the [NuGet.org login page](https://www.nuget.org/users/account/LogOn). - -### Which Microsoft account is linked to my NuGet.org account? - -If you have forgotten which Microsoft account is associated with your NuGet.org account, please follow the steps below to get assistance. -1. Go to [NuGet.org login page](https://www.nuget.org/users/account/LogOn) and click on **Need assistance signing in?** link. -1. This will show you the pop-up dialog box for assistance. Follow the steps in this dialog box to understand the associated Microsoft account(s) for your NuGet.org account. - -### How to change the Microsoft account I use for NuGet.org login? -If you wish to change the Microsoft account for NuGet.org user, follow the steps below. Lets say your Microsoft account with email `account1@outlook.com` is associated with your NuGet.org account with username `MyNuGetAccount`. You wish to change the login to another Microsoft account with email `account2@outlook.com` -1. Please sign in using **currently associated Microsoft account** i.e. `account1@outlook.com` on the [login page](https://www.nuget.org/users/account/LogOn) after clicking **Sign in with Microsoft**. -1. Once logged in, go to your [account settings](https://www.nuget.org/account) page. -1. Expand the section for **Login Account**. Click on the **Change Account** button. -1. You will now be redirected to the microsoft login page. Please sign in with the account that you wish to change the association to i.e. `account2@outlook.com`. **Note**: you might need to click on **Sign out and sign in with different account** during the sign in flow to be able to login with a different Microsoft account. -1. If you see an error like below, see [Microsoft account is linked with another NuGet.org account](#microsoft-account-is-linked-with-another-nugetorg-account) for more details. - >_Failed to update the Microsoft account with 'account2 '. This could happen if it is already linked to another NuGet account. Contact support for more information._ - -1. Once you have successfully signed in with your second account, you will be redirected back to your NuGet.org account settings page and you should now see the new Microsoft account associated as the login account. Going forward you should use this account when signing into NuGet.org. - -### Microsoft account is linked with another NuGet.org account. - -If you tried changing your Microsoft login and saw the error below: -> _Failed to update the Microsoft account with 'account2 '. This could happen if it is already linked to another NuGet account. Contact support for more information._ - -Lets say you were trying to change Microsoft account login from `account1@outlook.com` for NuGet.org user with username `MyNuGetAccount1` to another Microsoft account with email `account2@outlook.com`. And you see the error above. - -**What does the error above mean?** - -It means that there is another NuGet.org account which is associated with the Microsoft account that you are trying to change it to i.e. in above example the Microsoft account with email `` is associated with another NuGet.org account with, say, username `MyNuGetAccount2`. - -You cannot change the associated login with a Microsoft account that is linked to a different NuGet.org account. - -**I forgot I had another NuGet.org account, how do I find out which NuGet.org account it is?** - -Login with the second Microsoft account on the [login page](https://www.nuget.org/users/account/LogOn?returnUrl=%2F# "login page"). This will log you into the NuGet.org account that is currently associated with the second Microsoft account. You can then view the uploaded packages and perform account management on this account. - -**I do not care about this second NuGet.org account, I want to change my login for first NuGet.org account with the second Microsoft account. What do I do?** - -If you wish to not care about the second NuGet.org account and still want to re-use the associated Microsoft account with email `account2@outlook.com`. - -You can release the association between the Microsoft account and NuGet.org account by deleting the NuGet.org account. -1. Follow the steps to [delete user](#how-to-delete-my-nugetorg-account) for the second NuGet.org account `MyNuGetAccount2`. -1. Once this account is deleted, you can retry the steps to [change Microsoft account login](#how-to-change-the-microsoft-account-i-use-for-nugetorg-login). - -**Wait, I care about this second account too. I do not want to lose this account but change my associated account logins for first account.** - -You will need to create/use a third Microsoft account, say, with email `account3@outlook.com`. -1. First you should login with your second Microsoft account, `account2@outlook.com` on NuGet.org. Follow the steps above to change associated logins and associate the third Microsoft account with this NuGet.org account. -1. Once done, your second Microsoft account with email `account2@outlook.com` is free to be associated to your first NuGet.org account, `MyNuGetAccount1`. Follow the same steps above to change microsoft logins to the second Microsoft account. - -### Signing in with Microsoft account shows me my email is linked to another Microsoft account - -If you tried to sign in with your Microsoft account, say, with email `account1@outlook.com` and you see an error like below: -> _The account with email 'account1@outlook.com' is linked with another microsoft account._ -> -> _If you would like to update the linked Microsoft account you can do so from the account settings page._ - -**What does the error above mean?** - -When an account is created on NuGet.org, there is a communication email address associated with that account. This is usually same as the email address that is used for associated Microsoft account. However, you could choose to specify a different email address for communication. So, technically, you could have a different Microsoft account, say with `account2@outlook.com` that is linked to NuGet.org account with communication email address as `account1@outlook.com`. - -So the error above means that there already exists NuGet.org account with communication email address `account1@outlook.com` but is associated with another Microsoft account with email **that is not** `account1@outlook.com`. - -**How do I find which Microsoft account is linked to this NuGet.org account?** - -You should use the [sign in assistance](#which-microsoft-account-is-linked-to-my-nugetorg-account) flow to figure out which Microsoft account is linked to the NuGet.org account with the email address `account1@outlook.com`. - -**I want to override that account with my Microsoft account** - -Follow the steps in [Unable to use microsoft login, how do I recover my NuGet.org account](#unable-to-use-microsoft-login-how-do-i-recover-my-nugetorg-account) section to associate your Microsoft account with the existing NuGet.org account. - -### Unable to use microsoft login, how do I recover my NuGet.org account? - -If you tried using the [sign in assistance](#which-microsoft-account-is-linked-to-my-nugetorg-account) and you do not have access to the Microsoft account that is associated with your NuGet.org account, please follow the steps below to link a new Microsoft account to your NuGet.org account. -1. **Requirement**: You will need access to a Microsoft account which is not associated with any existing NuGet.org accounts. If you do not have one, you can [create](https://signup.live.com) one. -2. If you've forgotten your username and password for your NuGet.org account, follow the [steps to recover your password login](#how-to-recover-nugetorg-password-login). -3. [Login to NuGet.org](https://www.nuget.org/users/account/LogOnNuGetAccount) using the username/password login. -4. Once logged in, you will see the popup dialog show up like below. This is the password discontinuation dialog box. -5. **NOTE**: Please ignore the instruction to login with the specified Microsoft account. You can now link your NuGet.org account to any other Microsoft login. -6. Click on the button **Sign in with Microsoft** and login with the Microsoft account that you have an access to, as mentioned in step 1. -7. Your account will now be linked to the new Microsoft account, which you can use to log into NuGet.org going forward. - - ![Link MSA Dialog](media/link-msa-dialog.png) - -### How to transform my NuGet.org account to an organization? - -If you want to transform your account to an organization, and this account is already associated with a Microsoft account login, please follow the steps given in the documentation for [organizations on nuget org](organizations-on-nuget-org.md). - -If, however, your NuGet.org account is not associated/linked with a Microsoft account, you can follow the steps below to transform this account to an organization. -1. **Requirement**: You need to have an individual account first created on NuGet.org to be used as an admin on the org account. If you do not have one, please [create a new NuGet.org account](individual-accounts.md) -2. Follow the [steps to recover your password login](#how-to-recover-nugetorg-password-login) for your NuGet.org account if you do not have password login for it, if you do, skip this step. -3. [Login to NuGet.org](https://www.nuget.org/users/account/LogOnNuGetAccount) using the username/password login. -4. Once logged in, you will see the popup dialog show up like below. This is the password discontinuation dialog box. - > [!Important] - > Ignore this dialog box, **do not** click on the **Sign in with microsoft** button. - -5. Go to [https://www.nuget.org/account/transform](https://www.nuget.org/account/transform). This will allow you to convert the NuGet.org account to an org without linking to a Microsoft account. -6. Specify the admin username for your personal NuGet.org account/the account you created in Step 1. -7. Follow the instructions to complete transformation of this account to an organization. - - ![Link MSA Dialog](media/link-msa-dialog.png) - -### NuGet.org login issues for AAD accounts with unmanaged tenant? - -If you see an error like below during your login flow with your email account domain(@yourdomain.com), see the steps below to recover your NuGet.org account. - -

    - -

    - -**What is this unmanaged state thing during login? And why is this happening now?** - -Your account seems to be previously registered as a personal Microsoft account and it worked fine, however, now it seems like your account has been registered as an "Unmanaged" tenant in the Azure Active Directory (the identity service which we use to authenticate Microsoft accounts). - -This could have happened if you or someone from your organization(with @yourdomain.com email address) registered with one of the AAD integrated services or did a [self-service signup for Azure Active Directory](https://docs.microsoft.com/en-us/azure/active-directory/users-groups-roles/directory-self-service-signup), which creates such an "Unmanaged" tenant for the used Microsoft account domain(@yourdomain.com in your case). - -**What can I do to recover my account?** - -At this moment there is not a way for us (NuGet.org) to authenticate accounts with such "Unmanaged" tenant accounts in Azure Active directory. We are looking in to a better way to authenticate such accounts. - -If you want to login to NuGet.org with your Microsoft account(@yourdomain.com), you(or an administrator at your company) will need to claim the ownership of the AAD by doing a DNS validation to authenticate users with email address "@yourdomain.com". Please follow the steps for [domains admin takeover](https://docs.microsoft.com/en-us/azure/active-directory/users-groups-roles/domains-admin-takeover) documented by the Azure Active directory. Once this is done, your normal login should start working. - -**I don’t want to do all that, what is the other way to recover my account?** - -You can [create](https://www.microsoft.com/en-us/account) a new Microsoft account (with an email **not** associated with @yourdomain.com). Follow steps given in [recover your NuGet.org account](#unable-to-use-microsoft-login-how-do-i-recover-my-nugetorg-account) section. - -### How do I change my NuGet.org account username? - -You cannot. As a matter of policy we do not allow the change of usernames as of yet. The only way to change your username is to create a new account with the desired username. We recommend you delete your existing account before you create a new one, otherwise you will not be able to reuse your registered Microsoft account. -> [!Important] -> Deleting the user will still **reserve** the `username`. You will not be able to reuse the same username again and **this includes the change of casings**. As an example if you created a user with username `mycoolname` and you want to change this to `MyCoolName`(casing changes), it will not be possible after deleting the user. - -Follow the steps given in [delete your NuGet.org account](#how-to-delete-my-nugetorg-account) section and to [register a new account](individual-accounts.md) with correct username. - -### How to delete my NuGet.org account? - -To delete your account, please note that we recommend that you transfer the ownership of any packages where you are the sole owner. You can read more about [managing package owners](https://docs.microsoft.com/en-us/nuget/create-packages/publish-a-package#managing-package-owners-on-nugetorg) on how to do it. This will also help us expedite your request. - -If you are looking to transform your account to an organization, follow the steps given in [transform my NuGet.org account to an organization](#how-to-transform-my-nugetorg-account-to-an-organization). - -> [!Important] -> Deleting the user will result in following: -> 1. Your username will be reserved and no one will be able to re-use it to create an individual account or an organization account -> 1. Revoke associated API key(s). -> 1. Remove the account as an owner for any child packages. -> 1. Dissociate all previously existent ID prefix reservations with this account. -> 1. Remove the account as a member of any organizations. - -Follow the following steps to proceed with account deletion. -1. [Login to NuGet.org](https://www.nuget.org/users/account/LogOn) with the account you wish to delete. -2. Click on this url: [https://www.nuget.org/account/delete](https://www.nuget.org/account/delete) and follow the steps to submit the request for deleting the account. - -Our customer support will process this request and perform the account deletion. diff --git a/docs/nuget-org/nuget-org-faq.yml b/docs/nuget-org/nuget-org-faq.yml new file mode 100644 index 000000000..0a8f1bf36 --- /dev/null +++ b/docs/nuget-org/nuget-org-faq.yml @@ -0,0 +1,271 @@ +### YamlMime:FAQ +metadata: + title: NuGet.org Frequently-Asked Questions + description: Common questions and answers for working with the NuGet gallery. + author: shishirx34 + ms.author: shishirh + ms.date: 06/05/2019 + ms.topic: faq + ms.custom: sfi-image-nochange + +title: NuGet.org frequently-asked questions +summary: | + +sections: + - name: License terms + questions: + - question: What are the default license terms if a package doesn't provide specific license information? + answer: | + Each package is governed by the terms that are included with the package. You should review the applicable terms before accessing, downloading, or acquiring any packages. On NuGet.org, use the **License Info** link on the package page. + + If a package does not specify the licensing terms, contact the package owner directly using the **Contact owners** link on the NuGet.org package page. Microsoft does not license any intellectual property to you from third party package providers and is not responsible for information provided by third parties. + + - name: Managing packages on NuGet.org + questions: + - question: Can I edit package metadata after it's been uploaded? + answer: | + NuGet recommends all packages to be signed. A design principle of package signing is that signed package content must be immutable, which includes the nuspec. Editing the package metadata results in changes to the nuspec, invalidating existing signatures. We recommend modifying existing workflows to not require editing the package metadata after the package has been created. + + Note that dependencies listed for your package are generated automatically from the package itself and cannot be edited. + + In addition, uploading packages to [int.nugettest.org](https://int.nugettest.org) is a great way to test and validate your package without making a package available in the public gallery. API Endpoint: https://apiint.nugettest.org/v3/index.json + + - question: Can I delete a package published to NuGet.org? + answer: | + In general, we do not support deleting a package published to NuGet.org. Read more about our [policy on deleting packages](policies/deleting-packages.md). + + - question: Is it possible to reserve names for packages that will be published in future? + answer: | + Yes. You can reserve IDs for packages on [NuGet.org](https://www.nuget.org/) by requesting a package ID prefix for your account. In order to request a package ID prefix, follow the instructions in the [documentation](id-prefix-reservation.md). + + - question: How do I claim ownership for packages ? + answer: | + See [Managing package owners on NuGet.org](../nuget-org/publish-a-package.md#managing-package-owners-on-nugetorg). + + - question: How do I deal with a package owner who is violating my software license? + answer: | + We encourage the NuGet community to work together to resolve any disputes that may arise between package owners and the owners of other software. We have crafted a [dispute resolution process](policies/dispute-resolution.md) to follow before asking NuGet.org administrators to intercede. + + - question: Is it recommended to upload my test packages to NuGet.org? + answer: | + For test purposes, you can use [int.nugettest.org](https://int.nugettest.org), or alternative public NuGet servers like [myget.org](https://myget.org) or [Azure DevOps](https://blogs.msdn.microsoft.com/visualstudioalm/2015/08/27/announcing-package-management-support-for-vsotfs/). + + Note that packages uploaded to int.nugettest.org may not be preserved. + + - question: What is the maximum size of packages I can upload to NuGet.org? + answer: | + NuGet.org allows packages up to 250MB, but we recommend keeping packages under 1MB if possible and using dependencies to link packages together. As a rule of thumb, packages contain only one assembly to avoid collisions. + + NuGet uses HTTP to download packages, so larger packages have a higher likelihood of failed installs than smaller ones. + + It is possible to share dependencies between multiple packages, making the total download size for consumers of your NuGet packages smaller. + + Dependencies are mostly static and never change. When fixing a bug in code, the dependencies may not need to be updated. If you bundle dependencies, you end up reshipping larger packages every time. By splitting NuGet packages into related dependencies, upgrades are much more fine-grained for consumers of your package. + + - name: NuGet.org not accessible + questions: + - question: What SSL/TLS version and cipher suites does NuGet.org support? + answer: | + NuGet.org supports TLS 1.2 and the following cipher suites: + - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 + - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 + - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 + - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 + + - question: Why can't I restore packages from NuGet.org? + answer: | + If you meet transient failures when restoring packages from NuGet.org, we suggest you: + - use the latest versions of NuGet clients with a better resilience support. + - use environment variables of NuGet clients to enhance the retry policy on CI machines. + + | Environment Variable | Description | Remarks | + | --- | --- | --- | + | NUGET_ENHANCED_MAX_NETWORK_TRY_COUNT | Configures the maximum number of times an HTTP connection should be retried when enhanced retries are enabled. | A number representing how many retries to perform, the default value is `6`. | + | NUGET_ENHANCED_NETWORK_RETRY_DELAY_MILLISECONDS | Configures the amount of time to wait in milliseconds before retrying an HTTP connection when enhanced retries are enabled. | Number of milliseconds to wait, the default value is `1000`. | + + > [!Note] + > These environment variables are available since [.NET CLI](https://learn.microsoft.com/nuget/reference/dotnet-commands) (.NET SDK) 6.0.100, [NuGet CLI](https://learn.microsoft.com/nuget/reference/nuget-exe-cli-reference) 6.0, Visual Studio 2022 version 17.0 and corresponding MSBuild version. See [NuGet Release Notes](https://learn.microsoft.com/nuget/release-notes/). + + > [!Important] + > NuGet.org recommends Alpine Linux users to upgrade to Alpine Linux 3.18.0 or newer. These versions support TCP fallback in the DNS resolver. If you use older versions of Alpine Linux that only support DNS over UDP, you may encounter DNS failures when accessing the [V3 API](https://learn.microsoft.com/nuget/nuget-org/overview-nuget-org#api-endpoint-for-nugetorg). + + If that version of NuGet client continues to fail, [contact support](https://www.nuget.org/policies/Contact) and provide additional connection troubleshooting information including: + - !!! Your geographical area + - The package sources you're using + - The version of NuGet client you're using + - A restore log with detailed verbosity + - MTR or a Fiddler traces (see below) + - Whether your machine is behind a proxy or firewall? + - Is your machine located on a cloud providers' data center (Azure, AWS etc)? If yes, please provide the name of the provider and the region. + + *To capture MTR:* + + - Download [WinMTR](https://sourceforge.net/projects/winmtr/files/WinMTR-v092.zip/download). + - Enter `api.nuget.org` as the hostname and click **Start**. + - Wait until the **Sent** column is >= 100. + + ![Capturing MTR](media/mtr.png) + + - Copy text to clipboard. + + *To capture Fiddler:* + + - Install the latest version of [Fiddler](https://www.telerik.com/download/fiddler). + - Start Fiddler and disable capturing traffic using the **File > Capture Traffic** menu. + - Remove all sessions (select all items in the list, press the **Delete** key). + - Configure Fiddler to capture HTTPS traffic by checking **Decrypt HTTPS traffic** in the **HTTPS** tab of the **Tools > Fiddler Options...** menu. + - Close Visual Studio. + - Enable the **File > Capture Traffic** menu. + - Start Visual Studio or nuget.exe .exe and perform the actions that are not working. The traffic generated by these actions should show up in Fiddler. + - Once the actions have run, use **File > Save > All Sessions** to store the captured sessions. + + Note: it may be required to set the `HTTP_PROXY` environment variable to `http://127.0.0.1:8888` for routing NuGet traffic through Fiddler. + + If that fails, try the [tips mentioned in this StackOverflow post](https://stackoverflow.com/questions/21049908/using-fiddler-to-sniff-visual-studio-2013-requests-proxy-firewall). + + - name: NuGet.org account management + questions: + - question: How to recover NuGet.org password login? + answer: | + Please note that the [NuGet.org Password login has been discontinued](https://blog.nuget.org/20180515/NuGet.org-will-only-support-MSA-AAD-starting-June.html). Unfortunately, NuGet.org has no way to recover password accounts, you can only log in to NuGet.org with a personal Microsoft account (MSA) or Azure Active Directory (AAD) account. + + If you are unable to use Microsoft login, [please follow the steps to recover your NuGet.org account](#unable-to-use-microsoft-login--how-do-i-recover-my-nuget-org-account). + + Please let us know if you need assistance in transferring ownership of your packages to a different account by sending an email to [support@nuget.org](mailto:support@nuget.org). + + - question: Which Microsoft account is linked to my NuGet.org account? + answer: | + If you have forgotten which Microsoft account is associated with your NuGet.org account, please follow the steps below to get assistance. + 1. Go to [NuGet.org login page](https://www.nuget.org/users/account/LogOn) and click on **Need assistance signing in?** link. + 1. This will show you the pop-up dialog box for assistance. Follow the steps in this dialog box to understand the associated Microsoft account(s) for your NuGet.org account. + + - question: How to change the Microsoft account I use for NuGet.org login? + answer: | + If you wish to change the Microsoft account for NuGet.org user, follow the steps below. Lets say your Microsoft account with email `account1@outlook.com` is associated with your NuGet.org account with username `MyNuGetAccount`. You wish to change the login to another Microsoft account with email `account2@outlook.com` + 1. Please sign in using **currently associated Microsoft account** i.e. `account1@outlook.com` on the [login page](https://www.nuget.org/users/account/LogOn) after clicking **Sign in with Microsoft**. + 1. Once logged in, go to your [account settings](https://www.nuget.org/account) page. + 1. Expand the section for **Login Account**. Click on the **Change Account** button. + 1. You will now be redirected to the microsoft login page. Please sign in with the account that you wish to change the association to i.e. `account2@outlook.com`. **Note**: you might need to click on **Sign out and sign in with different account** during the sign in flow to be able to login with a different Microsoft account. + 1. If you see an error like below, see [Microsoft account is linked with another NuGet.org account](#microsoft-account-is-linked-with-another-nuget-org-account) for more details. + >_Failed to update the Microsoft account with 'account2 '. This could happen if it is already linked to another NuGet account. Contact support for more information._ + + 1. Once you have successfully signed in with your second account, you will be redirected back to your NuGet.org account settings page and you should now see the new Microsoft account associated as the login account. Going forward you should use this account when signing into NuGet.org. + + - question: Microsoft account is linked with another NuGet.org account. + answer: | + If you tried changing your Microsoft login and saw the error below: + > _Failed to update the Microsoft account with 'account2 '. This could happen if it is already linked to another NuGet account. Contact support for more information._ + + Lets say you were trying to change Microsoft account login from `account1@outlook.com` for NuGet.org user with username `MyNuGetAccount1` to another Microsoft account with email `account2@outlook.com`. And you see the error above. + + **What does the error above mean? + + It means that there is another NuGet.org account which is associated with the Microsoft account that you are trying to change it to i.e. in above example the Microsoft account with email `` is associated with another NuGet.org account with, say, username `MyNuGetAccount2`. + + You cannot change the associated login with a Microsoft account that is linked to a different NuGet.org account. + + - question: I forgot I had another NuGet.org account, how do I find out which NuGet.org account it is? + answer: | + Login with the second Microsoft account on the [login page](https://www.nuget.org/users/account/LogOn?returnUrl=%2F# "login page"). This will log you into the NuGet.org account that is currently associated with the second Microsoft account. You can then view the uploaded packages and perform account management on this account. + + - question: I do not care about this second NuGet.org account, I want to change my login for first NuGet.org account with the second Microsoft account. What do I do? + answer: | + If you wish to not care about the second NuGet.org account and still want to re-use the associated Microsoft account with email `account2@outlook.com`. + + You can release the association between the Microsoft account and NuGet.org account by deleting the NuGet.org account. + 1. Follow the steps to [delete user](#how-to-delete-my-nuget-org-account) for the second NuGet.org account `MyNuGetAccount2`. + 1. Once this account is deleted, you can retry the steps to [change Microsoft account login](#how-to-change-the-microsoft-account-i-use-for-nuget-org-login). + + - question: Wait, I care about this second account too. I do not want to lose this account but change my associated account logins for first account. + answer: | + You will need to create/use a third Microsoft account, say, with email `account3@outlook.com`. + 1. First you should login with your second Microsoft account, `account2@outlook.com` on NuGet.org. Follow the steps above to change associated logins and associate the third Microsoft account with this NuGet.org account. + 1. Once done, your second Microsoft account with email `account2@outlook.com` is free to be associated to your first NuGet.org account, `MyNuGetAccount1`. Follow the same steps above to change microsoft logins to the second Microsoft account. + + - question: Signing in with Microsoft account shows me my email is linked to another Microsoft account + answer: | + If you tried to sign in with your Microsoft account, say, with email `account1@outlook.com` and you see an error like below: + > _The account with email 'account1@outlook.com' is linked with another microsoft account._ + > + > _If you would like to update the linked Microsoft account you can do so from the account settings page._ + + - question: What does the error above mean? + answer: | + When an account is created on NuGet.org, there is a communication email address associated with that account. This is usually same as the email address that is used for associated Microsoft account. However, you could choose to specify a different email address for communication. So, technically, you could have a different Microsoft account, say with `account2@outlook.com` that is linked to NuGet.org account with communication email address as `account1@outlook.com`. + + So the error above means that there already exists NuGet.org account with communication email address `account1@outlook.com` but is associated with another Microsoft account with email **that is not** `account1@outlook.com`. + + - question: How do I find which Microsoft account is linked to this NuGet.org account? + answer: | + You should use the [sign in assistance](#which-microsoft-account-is-linked-to-my-nuget-org-account) flow to figure out which Microsoft account is linked to the NuGet.org account with the email address `account1@outlook.com`. + + - question: Unable to use Microsoft login, how do I recover my NuGet.org account? + answer: | + If you tried using the [sign in assistance](#which-microsoft-account-is-linked-to-my-nuget-org-account) and you do not have access to the Microsoft account that is associated with your NuGet.org account, please contact your Microsoft account support: + + - Microsoft Account (MSA): [Get help with your Microsoft account](https://support.microsoft.com/account-billing/get-help-with-your-microsoft-account-ace6f3b3-e2d3-aeb1-6b96-d2e9e7e52133) + - Work or school account (AAD): [Work or school account help](https://support.microsoft.com/account-billing/work-or-school-account-help-718b3d92-a8a7-4656-8a05-c0228d346b7d) or contact your admin tenant. + + - question: How to transform my NuGet.org account to an organization? + answer: | + If you want to transform your account to an organization, please follow the steps given in the documentation for [organizations on nuget.org](organizations-on-nuget-org.md). + + - question: NuGet.org login issues for AAD accounts with unmanaged tenant? + answer: | + If you see an error like below during your login flow with your email account domain(@yourdomain.com), see the steps below to recover your NuGet.org account. + + ![Error during login for AAD accounts](media/unmanaged-aad-tenant.png) + + - question: What is this unmanaged state thing during login? And why is this happening now? + answer: | + Your account seems to be previously registered as a personal Microsoft account and it worked fine, however, now it seems like your account has been registered as an "Unmanaged" tenant in the Azure Active Directory (the identity service which we use to authenticate Microsoft accounts). + + This could have happened if you or someone from your organization(with @yourdomain.com email address) registered with one of the AAD integrated services or did a [self-service signup for Azure Active Directory](/azure/active-directory/users-groups-roles/directory-self-service-signup), which creates such an "Unmanaged" tenant for the used Microsoft account domain(@yourdomain.com in your case). + + - question: What can I do to recover my account? + answer: | + At this moment there is not a way for us (NuGet.org) to authenticate accounts with such "Unmanaged" tenant accounts in Azure Active directory. We are looking in to a better way to authenticate such accounts. + + If you want to login to NuGet.org with your Microsoft account(@yourdomain.com), you(or an administrator at your company) will need to claim the ownership of the AAD by doing a DNS validation to authenticate users with email address "@yourdomain.com". Please follow the steps for [domains admin takeover](/azure/active-directory/users-groups-roles/domains-admin-takeover) documented by the Azure Active directory. Once this is done, your normal login should start working. + + - question: How do I change my NuGet.org account username? + answer: | + You can request a username change by sending an email to [support@nuget.org](mailto:support@nuget.org) from the email address that is attached to the account you want to update. + Be sure to include the old username and the new username you would like to change to. + We will then review your request and, upon approval, get confirmation from you that we are about to take the correct action and that you understand the consequences. + Once you have confirmed, we will change your username. + + > [!Important] + > - The old username will still be **reserved**. You will not be able to reuse the old username again and **this includes the change of casings**. + > - As a consequence of the above, we will not be able to revert this change either. + > - Any links to your old username profile page (e.g. ```https://www.nuget.org/profiles/OldUsername```) will not be redirected to your new profile. + > - Package versions currently owned by your account will still contain the old username in the repository signature. New package versions will contain the new username. + > - Any author-provided metadata in the existing package versions referring to the old username or other identifying information will not be changed. + > - NuGet client policies asserting trust of your old username will not implicitly trust packages published by your new username. Package consumers with these client policies configured will need to manual update them to trust your new username when they attempt to update to a newly published package version. + + - question: How to delete my NuGet.org account? + answer: | + To delete your account, please note that we recommend that you transfer the ownership of any packages where you are the sole owner. You can read more about [managing package owners](../nuget-org/publish-a-package.md#managing-package-owners-on-nugetorg) on how to do it. This will also help us expedite your request. + + If you are looking to transform your account to an organization, follow the steps given in [transform my NuGet.org account to an organization](#how-to-transform-my-nuget-org-account-to-an-organization). + + > [!Important] + > Deleting the user will result in following: + > 1. Your username will be reserved and no one will be able to re-use it to create an individual account or an organization account + > 1. Revoke associated API key(s). + > 1. Remove the account as an owner for any child packages. + > 1. Dissociate all previously existent ID prefix reservations with this account. + > 1. Remove the account as a member of any organizations. + + Follow the following steps to proceed with account deletion. + 1. [Login to NuGet.org](https://www.nuget.org/users/account/LogOn) with the account you wish to delete. + 2. Click on this url: [https://www.nuget.org/account/delete](https://www.nuget.org/account/delete) and follow the steps to submit the request for deleting the account. + + Our customer support will process this request and perform the account deletion. + + - question: What happens to my NuGet.org account when my Microsoft account gets deleted? + answer: | + When the Microsoft or Azure Active Directory account you use to sign in to your nuget.org account is deleted, your nuget.org account will be deleted as well. The account delete action is completed by the nuget.org customer support within 30 days from the date of the Microsoft account deletion. + + If you have packages associated with your account, we will notify you 3 business days before proceeding with deletion and offer assistance to transfer the packages to a different nuget.org account. + diff --git a/docs/nuget-org/organizations-on-nuget-org.md b/docs/nuget-org/organizations-on-nuget-org.md index 4129a65e9..36a65d2d3 100644 --- a/docs/nuget-org/organizations-on-nuget-org.md +++ b/docs/nuget-org/organizations-on-nuget-org.md @@ -4,10 +4,11 @@ description: Organizations on NuGet.org helps you to manage packages published b author: anangaur ms.author: anangaur ms.date: 04/10/2018 -ms.topic: conceptual +ms.topic: article ms.reviewer: - kraigb - camsoper +ms.custom: sfi-image-nochange --- # Your organization on NuGet.org @@ -101,4 +102,4 @@ You can delete an organization account by clicking the **Delete** button shown i ![Deleting an organization](media/org-delete-option.png) -To delete the organizaiton, you must confirm it by clicking the **Delete organization** confirmation button. +To delete the organization, you must confirm it by clicking the **Delete organization** confirmation button. diff --git a/docs/nuget-org/overview-nuget-org.md b/docs/nuget-org/overview-nuget-org.md index 43a0376c4..aa160a850 100644 --- a/docs/nuget-org/overview-nuget-org.md +++ b/docs/nuget-org/overview-nuget-org.md @@ -4,7 +4,7 @@ description: Overview of NuGet.org author: mikejo5000 ms.author: mikejo ms.date: 06/05/2019 -ms.topic: conceptual +ms.topic: concept-article --- # Overview of NuGet.org @@ -33,6 +33,10 @@ Once you have a NuGet package (*.nupkg* file) to publish, you publish it to NuGe When you [publish a package](../create-packages/creating-a-package.md), you include the API key value in the CLI command. +## Trusted publishing + +NuGet.org supports [Trusted Publishing](trusted-publishing.md), which is a secure and streamlined way to publish NuGet packages. + ## ID prefixes When you publish packages, you can reserve and protect your identity by [reserving ID prefixes](id-prefix-reservation.md). When installing a package, package consumers are provided with additional information indicating that the package they are consuming is not deceptive in its identifying properties. @@ -45,4 +49,4 @@ To use NuGet.org as a package repository with NuGet clients, you should use the Older clients can still use the V2 protocol to reach NuGet.org. However, please note, NuGet clients 3.0 or later will have slower and less reliable service using the V2 protocol: -`https://www.nuget.org/api/v2` (**The V2 prototcol is deprecated!**) +`https://www.nuget.org/api/v2` (**The V2 protocol is deprecated!**) diff --git a/docs/nuget-org/package-readme-on-nuget-org.md b/docs/nuget-org/package-readme-on-nuget-org.md new file mode 100644 index 000000000..f4ecd173c --- /dev/null +++ b/docs/nuget-org/package-readme-on-nuget-org.md @@ -0,0 +1,137 @@ +--- +title: Package readme on NuGet.org +description: Detailed explanation of how readme files on NuGet.org are rendered and what to do when you run into issues. +author: nkolev92 +ms.author: nikolev +ms.date: 08/31/2022 +ms.topic: article +ms.reviewer: anangaur +--- + +# Package readme on NuGet.org + +[Include a readme file in your NuGet package](/nuget/reference/msbuild-targets#packagereadmefile) to make your package details richer and more informative for your users! + +This is likely one of the first elements users will see when they view your package details page on NuGet.org and is essential to making a good impression! + +> [!IMPORTANT] +> NuGet.org only supports readme files in [Markdown](https://daringfireball.net/projects/markdown/) and images from a limited set of domains. See our [allowed domains for images](#allowed-domains-for-images-and-badges) and [supported Markdown features](#supported-markdown-features) to ensure your readme renders correctly on NuGet.org. + +## What should my readme include? + +Consider including the following items in your readme: +* An introduction to what your package is and does - what problems does it solve? +* How to get started with your package - are there any specific requirements? +* Links to more comprehensive documentation if not included in the readme itself. +* At least a few code snippets/samples or example images. +* Where and how to leave feedback such as link to the project issues, Twitter, bug tracker, or other platform. +* How to contribute, if applicable. + +For example, you can start with this package README template: + +```text +# Package readme title, e.g., display name or title of the package (optional) + +Start with a clear and concise description: A brief overview of what your package is and does, also what problem it solves. + +## Getting started + +Explain how to use your package, provide clear and concise getting started instructions, including any necessary steps. + +### Prerequisites + +What are specific minimum requirements to use your packages? Consider excluding this section if your package works without any additional setup beyond simple package installation. + +## Usage + +Examples about how to use your package by providing code snippets/example images, or samples links on GitHub if applicable. + +- Provide sample code using code snippets +- Include screenshots, diagrams, or other visual help users better understand how to use your package + +## Additional documentation + +Provide links to more resources: List links such as detailed documentation, tutorial videos, blog posts, or any other relevant documentation to help users get the most out of your package. + +## Feedback + +Where and how users can leave feedback? + +- Links to a GitHub repository where could open issues, Twitter, a Discord channel, bug tracker, or other platforms where a package consumer can connect with the package author. +``` + +Keep in mind, high quality readmes can come in a wide variety of formats, shapes, and sizes! If you already have a package available on NuGet.org, chances are that you already have a `readme.md` or other documentation file in your repository that would be a great addition to your NuGet.org details page. + +> [!Note] +> Read through our [blog on writing a high-quality README](https://devblogs.microsoft.com/nuget/write-a-high-quality-readme-for-nuget-packages/) for some best practices. + +## Preview your readme + +To preview your readme file before it's live on NuGet.org, upload your package using the [Upload Package web portal on NuGet.org](/nuget/nuget-org/publish-a-package#web-portal-use-the-upload-package-tab-on-nugetorg) and scroll down to the "Readme File" section of the metadata preview. It should look something like this: + +![Readme File preview](media\readme-upload-preview.PNG) + +Consider taking time to review and preview your readme file for [image compliance](#allowed-domains-for-images-and-badges) and [supported formatting](#supported-markdown-features) to make sure it gives a great first impression to potential users! To correct mistakes on your package readme once it's published to NuGet.org, you will need to push an updated package version with the fix. Making sure everything looks good in advance may save you headache down the road. +## Allowed domains for images and badges + +Due to security and privacy concerns, NuGet.org restricts the domains from which images and badges can be rendered to trusted hosts. + +NuGet.org allows all images, including badges, from the following trusted domains to be rendered: +* api.codacy.com +* api.codeclimate.com +* api.dependabot.com +* api.reuse.software +* api.travis-ci.com +* app.codacy.com +* app.deepsource.com +* avatars.githubusercontent.com +* badgen.net +* badges.gitter.im +* camo.githubusercontent.com +* caniuse.bitsofco.de +* cdn.jsdelivr.net +* cdn.syncfusion.com +* ci.appveyor.com +* circleci.com +* cloudback.it +* codecov.io +* codefactor.io +* coveralls.io +* dev.azure.com +* flat.badgen.net +* github.com/.../workflows/.../badge.svg +* gitlab.com +* i.imgur.com +* img.shields.io +* infragistics.com +* isitmaintained.com +* media.githubusercontent.com +* opencollective.com +* raw.github.com +* raw.githubusercontent.com +* snyk.io +* sonarcloud.io +* travis-ci.com +* travis-ci.org +* user-images.githubusercontent.com + +If you feel that another domain should be added to the allow-list, please feel free to [file an issue](https://github.com/NuGet/NuGetGallery/issues) and it will be reviewed by our engineering team for privacy and security compliance. Images with relative local paths and images hosted from unsupported domains will not be rendered and will produce a warning on the readme file preview and package details page that is only visible to the package owners. + +## Supported Markdown features +[Markdown](https://daringfireball.net/projects/markdown/) is a lightweight markup language with plain text formatting syntax. NuGet.org readmes support [CommonMark](https://commonmark.org/) compliant Markdown through the [Markdig](https://github.com/lunet-io/markdig) parsing engine. + +NuGet.org currently supports the following Markdown features: +* [Headers](https://spec.commonmark.org/0.29/#atx-headings) +* [Images](https://spec.commonmark.org/0.29/#images) +* [Extra emphasis](https://github.com/xoofx/markdig/blob/master/src/Markdig.Tests/Specs/EmphasisExtraSpecs.md) +* [Lists](https://spec.commonmark.org/0.29/#lists) +* [Links](https://spec.commonmark.org/0.29/#links) +* [Block quotes](https://spec.commonmark.org/0.29/#block-quotes) +* [Backslash escapes](https://spec.commonmark.org/0.29/#backslash-escapes) +* [Code spans](https://spec.commonmark.org/0.29/#code-spans) +* [Task lists](https://github.com/xoofx/markdig/blob/master/src/Markdig.Tests/Specs/TaskListSpecs.md) +* [Tables](https://github.com/xoofx/markdig/blob/master/src/Markdig.Tests/Specs/PipeTableSpecs.md) +* [Emojis](https://github.com/xoofx/markdig/blob/master/src/Markdig.Tests/Specs/EmojiSpecs.md) +* [Auto-links](https://github.com/xoofx/markdig/blob/master/src/Markdig.Tests/Specs/AutoLinks.md) + +We also support syntax highlighting, You can add an language identifier to enable syntax highlighting in your code spans. diff --git a/docs/nuget-org/package-sponsorship-on-nuget-org.md b/docs/nuget-org/package-sponsorship-on-nuget-org.md new file mode 100644 index 000000000..af1f6e111 --- /dev/null +++ b/docs/nuget-org/package-sponsorship-on-nuget-org.md @@ -0,0 +1,118 @@ +--- +title: Package sponsorship on NuGet.org +description: Learn how to add sponsorship links to your NuGet packages and support package maintainers through NuGet.org's sponsorship feature. +author: pranathibora14 +ms.author: prabora +ms.date: 10/15/2025 +ms.topic: how-to +ai-usage: ai-generated +--- + +# Package sponsorship on NuGet.org + +The NuGet.org sponsorship feature makes it easier for package consumers to recognize and support the authors behind their favorite packages. + +NuGet.org enables package authors to add sponsorship URLs to their packages. These links appear when the "Sponsor" button on the package details page is selected. + + +## Setting up sponsorship for package publishers + +### Prerequisites + +- You must be the owner or co-owner of a package on NuGet.org +- Your sponsorship link platform must be from the approved list: + - GitHub Sponsors + - Patreon + - Open Collective + - Ko-fi + - Tidelift + - Liberapay + +### Navigate to your package management page + +1. Go to [NuGet.org](https://nuget.org) and sign in to your account. +2. Select your username in the top right corner. +3. Select **Manage Packages** from the dropdown menu. +4. Find the package you want to add sponsorship information for and select the edit button. + +### Access sponsorship settings + +1. On your package management page, scroll down to find the **Sponsorship Links** section. +2. Select to expand the collapsible **Sponsorship Links** section. +3. You'll see a form where you can add sponsorship URLs. + + ![Screenshot of the manage package page with the Sponsorship Links section](media/sponsorship-section-manage-package-page.png) + +### Add your sponsorship URLs + +1. Enter your sponsorship URL in the text field: + - Example: `https://github.com/sponsors/yourusername` + - Example: `https://www.patreon.com/yourusername` + + ![Screenshot of the sponsorship URL form with example URL filled in](media/sponsorship-add-link.png) + +2. Select the **Add** button. +3. The system automatically validates that your URL is from an approved platform. +4. If any URLs are invalid or from non-approved platforms, you'll see error messages to correct them. Otherwise, you'll see a confirmation message that your sponsorship link has been saved. + + ![Screenshot of a URL from a platform that is not approved](media/sponsorship-link-error-manage-package.png) + +5. Each added sponsorship URL will have a **Remove** button next to it if you need to delete it. +6. You can add up to 10 different sponsorship URLs per package ID. + +### Verify your sponsorship URLs display correctly + +1. Navigate to your package's public page on NuGet.org. +2. Look for the **Sponsor** button in the package details **About** section. +3. Select the **Sponsor** button to test that your URLs appear correctly in the popup. + + ![Screenshot of a package details page with the sponsorship links popup open](media/sponsorship-display-links.png) + +## Finding and supporting packages + +### Identify packages that need sponsorship + +1. Browse to any package page on NuGet.org. +2. Look for packages displaying a **Sponsor** button in the package details section. +3. The **Sponsor** button indicates that the package maintainer is seeking financial support. + + ![Screenshot of a package details page with a Sponsor button](media/sponsorship-button-package-details-page.png) + +### View available sponsorship options + +1. Select the **Sponsor** button on the package page. +2. A popup window appears showing all available sponsorship links for that package. + + ![Screenshot of a package details page with the sponsorship links popup open](media/sponsorship-display-links.png) + +### Choose your preferred sponsorship platform + +1. Review the available sponsorship options in the popup. +2. Select your preferred platform to be redirected to the external sponsorship page. +3. The link opens in a new tab or window, keeping the NuGet package page open. + +> [!IMPORTANT] +> These links take you to third-party platforms. Microsoft isn't affiliated with or responsible for the content or practices of third-party platforms, and we don't endorse them. Microsoft reserves the right to remove any allowed third-party platforms. + +## Frequently asked questions + +**Can I add sponsorship information to older versions of my package?** + +Yes! Sponsorship information is managed at the package ID level, so it automatically applies to all versions of your package, including previously published versions. + +**What happens if my sponsorship platform URL changes?** + +You can update your sponsorship URLs anytime through the package management page. Changes take effect immediately across all versions. + +**Can I see analytics on how many people selected my sponsorship links?** + +No, NuGet.org doesn't track sponsorship link selections. You'll need to check analytics on your sponsorship platform directly. + +**Can I add custom sponsorship platforms not on the approved list?** + +Currently, only the approved list of platforms is supported. This helps ensure security and legitimacy of sponsorship links. If you'd like to request a new platform to be added to the approved list, you can open an issue on the [NuGet Gallery repository](https://github.com/NuGet/NuGetGallery/issues). + +**Does NuGet.org store my financial information?** + +No personal or financial data is stored by NuGet.org. All transactions occur on secure external platforms that a maintainer chooses for sponsoring their packages. + diff --git a/docs/nuget-org/policies/data-requests.md b/docs/nuget-org/policies/data-requests.md index 61166e32d..9c29231ef 100644 --- a/docs/nuget-org/policies/data-requests.md +++ b/docs/nuget-org/policies/data-requests.md @@ -1,10 +1,10 @@ --- title: User Data Requests description: Policies for requesting user data export and delete -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 05/01/2018 -ms.topic: conceptual +ms.topic: article --- # User Data Requests diff --git a/docs/nuget-org/policies/deleting-packages.md b/docs/nuget-org/policies/deleting-packages.md index 6d1221197..9e99d39ab 100644 --- a/docs/nuget-org/policies/deleting-packages.md +++ b/docs/nuget-org/policies/deleting-packages.md @@ -1,17 +1,17 @@ --- title: Deleting NuGet Packages from nuget.org description: Policies for unlisting packages from nuget.org; permanent deletion is not supported except when packages violate other policies. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 -ms.topic: conceptual +ms.topic: how-to --- # Deleting packages nuget.org does not support permanent deletion of packages. Doing so would break every project depending on the availability of the package, especially with build workflows that involve package restore. -nuget.org does supports *unlisting* a package, which can be done in the package management page on the web site. Unlisted packages don't appear on nuget.org or in the Visual Studio UI, and do not appear in search results. Unlisted packages, however, can still be downloaded and installed by using an exact version number, which supports package restore. In addition, unlisted packages may still be discovered in the following specific scenarios: +nuget.org does support [unlisting a package](#unlisting-a-package), which can be done in the package management page on the web site. Unlisted packages don't appear on nuget.org or in the Visual Studio UI, and do not appear in search results. Unlisted packages, however, can still be downloaded and installed by using an exact version number, which supports package restore. In addition, unlisted packages may still be discovered in the following specific scenarios: - Package restore using floating versions (for example, `1.0.0-*`), if the latest available package matching the version or dependency constraints is an unlisted package. - Replication of packages through the catalog (as the catalog also contains unlisted packages). @@ -30,7 +30,22 @@ Packages that meet any of the following criteria are not allowed on the public N - Contains illegal content. - Are being used to squat on package identifiers, including packages that have zero productive content. Packages must contain code or the owners must concede the identifier to someone who actually has a product to ship. - Attempt to make the gallery do something that it's not explicitly designed to do. +- Violates the [nuget.org Terms of Use or Code of Conduct](https://www.nuget.org/policies/Terms) in any way. Terms such as "unexpected", "discriminatory", "hateful", and "abusive" are evaluated and decided at the sole discretion of the NuGet team. If you find a package that is in violation of any of these items, click the **Report Abuse** link on the package details page and submit a report. Note that the NuGet team and the .NET Foundation reserves the right to change these criteria at any time. + +## Unlisting a package +Unlisting a package version hides it from search and from nuget.org package details page. This allows existing users of the package to continue using it but reduces new adoption since the package is not visible in search. + +Steps to unlist a package: + +1. Select `Your account name` (at the top right corner) >`Manage packages` > `Published packages` +1. Select the "Manage package" icon +1. Expand the "Listing" section and select the package version +1. Uncheck “List in search results” and select "Save" + +The specific package version has now been unlisted. In order to verify this, logout of your account and navigate to the package page (without the version part) e.g.: ```https://www.nuget.org/packages/YOUR-PACKAGE-NAME/```. You will see all versions of that package that have **not** been unlisted. However, the package owner, when logged in, can see all versions and their listing status. + +It's also possible to deprecate a package version (in case you can't delete a package version). For more information about deprecating package versions, see [Deprecating packages](../deprecate-packages.md). diff --git a/docs/nuget-org/policies/dispute-resolution.md b/docs/nuget-org/policies/dispute-resolution.md index a0812ca5c..c9342a827 100644 --- a/docs/nuget-org/policies/dispute-resolution.md +++ b/docs/nuget-org/policies/dispute-resolution.md @@ -1,10 +1,10 @@ --- title: "NuGet Package Name Dispute Resolution" description: The process for resolving disputes between NuGet package publishers related to branding, trademarks, and other conflict situations. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 -ms.topic: conceptual +ms.topic: how-to --- # Resolving disputes over NuGet package names @@ -15,7 +15,7 @@ For example, suppose that Northwind Traders makes a CRM system for which they pr In this scenario, Nancy does not appear to be acting with bad intentions, but is rather supporting Northwind's tools and customers by contributing her own time and code. At the same time, Northwind is the legitimate owner of the Northwind name. -By following the process below, Northwind and Nancy can work together to a suitable resolution, because both are interested in serving the developer community. It's typically not necessary for the NuGet team to become involved; collaboration usually works out best. In fact, every dispute brought to the NuGet team's attention to date has been worked out without the team needing to pass judgment. +By following the process below, Northwind and Nancy can work together to a suitable resolution, because both are interested in serving the developer community. It's typically not necessary for the NuGet team to become involved; collaboration usually works out best. ## Process diff --git a/docs/nuget-org/policies/export-control.md b/docs/nuget-org/policies/export-control.md index 2a79589f3..bc786531e 100644 --- a/docs/nuget-org/policies/export-control.md +++ b/docs/nuget-org/policies/export-control.md @@ -1,10 +1,10 @@ --- title: Export Control Policy description: Policies governing export control laws -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 06/27/2019 -ms.topic: conceptual +ms.topic: article --- # Export Control Policy @@ -23,4 +23,4 @@ As specified in the EAR (Part 742.15(b) & 734.3(b)(3)), the person or entity pro Release of publicly available source code from export control jurisdiction through the notification process described above *does not apply* to commercial software incorporating or derived from such items. You are solely responsible for compliance with Export Laws as applied to any commercial software incorporating or derived from source or object code hosted via NuGet.org. -For further information on export and geographic export restrictions, please visit https://www.microsoft.com/en-us/exporting. +For further information on export and geographic export restrictions, please visit [Microsoft Exporting](https://www.microsoft.com/exporting). diff --git a/docs/nuget-org/scoped-api-keys.md b/docs/nuget-org/scoped-api-keys.md index 66f2d4462..f5b22ad84 100644 --- a/docs/nuget-org/scoped-api-keys.md +++ b/docs/nuget-org/scoped-api-keys.md @@ -4,7 +4,7 @@ description: Take control of API keys that you use to push packages author: mikejo5000 ms.author: mikejo ms.date: 06/04/2019 -ms.topic: conceptual +ms.topic: article --- # Scoped API keys @@ -44,7 +44,7 @@ In the following example, you have an API key named `Contoso service CI` that ca If you are working on multiple packages and have a large list of packages to manage, you can choose to use globbing patterns to select multiple packages together. For example, if you wish to grant specific scopes to a key for all packages whose ID starts with `Fabrikam.Service`, you could do this by specifying `fabrikam.service.*` in the **Glob pattern** text box. -![Create API keys](media/scoped-api-keys-glob-pattern.png) +![Create API keys - 2](media/scoped-api-keys-glob-pattern.png) Using glob patterns to determine API key permissions also applies to new packages matching the glob pattern. For example, if you try to push a new package named `Fabrikam.Service.Framework`, you can do that with the key created previously, since the package matches the glob pattern `fabrikam.service.*`. @@ -52,19 +52,19 @@ Using glob patterns to determine API key permissions also applies to new package For security, a newly created key is never shown on the screen and is only available using the **Copy** button. Similarly, the key is not accessible after the page is refreshed. -![Create API keys](media/scoped-api-keys-obtain-keys.png) +![Create API keys - 3](media/scoped-api-keys-obtain-keys.png) ## Edit existing API keys You may also want to update the key permissions and scopes without changing the key itself. If you have a key with specific scope(s) for a single package, you can choose to apply the same scope(s) on one or many other packages. -![Create API keys](media/scoped-api-keys-edit.png) +![Create API keys - 4](media/scoped-api-keys-edit.png) ## Refresh or delete existing API keys The account owner can choose to refresh the key, in which case the permission (on packages), scope, and expiry remain the same, but a new key is issued making the old key unusable. This is helpful in managing stale keys or where there is any potential for an API key leakage. -![Create API keys](media/scoped-api-keys-refresh.png) +![Create API keys - 5](media/scoped-api-keys-refresh.png) You may also choose to delete these keys if they are not needed anymore. Deleting a key removes the key and makes it unusable. @@ -99,4 +99,4 @@ You cannot modify the scope, but you can edit the package list it is applicable ### How do I know if any of my keys expired or are getting expired? -If any key expires, we will let you know through a warning message at the top of the page. We also send a warning e-mail to the account holder ten days before the expiration of the key so that you can act on it well in advance. \ No newline at end of file +If any key expires, we will let you know through a warning message at the top of the page. We also send a warning e-mail to the account holder ten days before the expiration of the key so that you can act on it well in advance. diff --git a/docs/nuget-org/trusted-publishing.md b/docs/nuget-org/trusted-publishing.md new file mode 100644 index 000000000..ca9faff1c --- /dev/null +++ b/docs/nuget-org/trusted-publishing.md @@ -0,0 +1,121 @@ +--- +title: Trusted Publishing +description: Trusted Publishing on nuget.org +author: etvorun +ms.author: evgenyt +ms.date: 07/01/2025 +ms.topic: article +--- + +# Trusted Publishing on nuget.org + +Trusted Publishing is a better way to publish NuGet packages. You don’t need to manage long-lived API keys anymore. Instead, you use short-lived credentials issued by your CI/CD system, like GitHub Actions. + +This makes your publishing process safer by reducing the risk of leaked credentials. It also makes automation easier because you don’t need to rotate or store secrets. This approach is part of a broader industry shift toward secure, keyless publishing. If you're curious, check out the OpenSSF initiative: https://repos.openssf.org/trusted-publishers-for-all-package-repositories. + +> ⚠️ **Heads up:** If you don’t see the **Trusted Publishing** option in your nuget.org account, it might not be available to you yet. We’re rolling it out gradually. + +## How it works + +When your GitHub Actions workflow runs, it requests an encrypted OIDC token from github.com. This token +includes information about your repository and workflow, and is cryptographically signed by GitHub Actions to prevent +tampering. The workflow forwards this token to nuget.org, which securely validates the token’s +authenticity with github.com using industry-standard cryptographic methods. A token exchange endpoint on nuget.org then checks +that the token’s details match a trusted publishing policy you’ve configured. If everything matches, +nuget.org issues a short-lived API key for your workflow to use when publishing your package. + +**Here’s the basic flow** + +1. Your CI/CD system (like GitHub Actions) runs a workflow. +2. It issues a short-lived token. +3. That token is sent to nuget.org. +4. NuGet verifies it and returns a temporary API key. +5. Your workflow uses that key to push the package. + +![Screenshot that shows Trusted Publishing page.](media/trusted-publishing.png) + +NuGet’s temporary API keys are valid for **1 hour**, so your workflow should request the key shortly before publishing. +If you request it too early, it might expire before the push happens. + +Each short-lived token can only be used once to obtain a single temporary API key—one token, one API key. + +This setup gives you a secure and automated way to publish packages, without the risks that come with long-lived secrets. + + +## GitHub Actions Setup + +To get started: + +1. Log into **nuget.org**. +2. Click your username and choose **Trusted Publishing**. +3. Add a new trusted publishing policy. For a GitHub repository `https://github.com/contoso/contoso-sdk` + with a workflow file `.github/workflows/build.yml` enter the following trusted policy details (case‑insensitive): + - **Repository Owner:** `contoso` + - **Repository:** `contoso-sdk` + - **Workflow File:** `build.yml` + > This corresponds to your workflow at `.github/workflows/build.yml`. Enter the **file name only** (`build.yml`)—do not include the `.github/workflows/` path. + - **Environment (optional):** `release` + > Enter environment if your workflow uses e.g. `environment: release` and you want to restrict this policy to that environment. Leave this empty if you do not use GitHub Actions environments. +4. In your **GitHub repo**, update your workflow to request a short‑lived API key and push your package. +Here’s a basic example: + +```yaml +jobs: + build-and-publish: + permissions: + id-token: write # enable GitHub OIDC token issuance for this job + + steps: + # Build your artifacts/my-sdk.nupkg package here + + # Get a short-lived NuGet API key + - name: NuGet login (OIDC → temp API key) + uses: NuGet/login@v1 + id: login + with: + user: contoso-bot # Recommended: use a secret like ${{ secrets.NUGET_USER }} for your nuget.org username (profile name), NOT your email address + + # Push the package + - name: NuGet push + run: dotnet nuget push artifacts/my-sdk.nupkg --api-key ${{steps.login.outputs.NUGET_API_KEY}} --source https://api.nuget.org/v3/index.json +``` + + +## Policy Ownership + +When you create a Trusted Publishing policy, you need to choose who owns it. The owner can be either: + +- **You (an individual user)** +- **An organization you belong to** + +The policy will apply to all packages owned by the selected owner. That means it controls who can publish or modify those packages using Trusted Publishing. + +If you choose an organization, make sure you're an active member. If you leave the org later, the policy may become inactive until you're added back. + +Choosing the right owner helps ensure your publishing setup stays secure and aligned with your team’s structure. + + +## Policies Pending Full Activation + +Sometimes when you create a Trusted Publishing policy, it starts out as temporarily active for 7 days. This usually happens with private GitHub repos. You’ll see this status in the UI. During that time, it behaves like a regular policy. But if no publish happens within those 7 days, the policy automatically becomes inactive. You can restart the 7-day window at any time—even after it expires. + +Why is this temporary period necessary? Because NuGet needs GitHub repository and owner IDs to lock the policy to the original repo and owner. That helps prevent resurrection attacks. Without those IDs, someone could delete a repo, recreate it with the same name, and try to publish as if nothing changed. + +Once a successful publish provides the IDs (as part of GitHub’s short-lived token), the policy becomes permanently active. + + +## Policy Ownership Warnings + +Trusted Publishing policies are tied to a specific owner—either an individual user or an organization. +If something changes with that ownership, the policy might become inactive. When that happens, you'll see a warning in the UI. + +### Common cases + +- **User removed from organization** + If a policy is owned by an organization and the user who created it is later removed from that org, the policy becomes inactive. + If the user is added back to the organization, the policy will be active again automatically. + +- **Organization is no longer active** + If the organization that owns the policy is locked or deleted, the policy becomes inactive. + +These warnings help make sure that only active, secure policies are used when publishing packages. diff --git a/docs/policies/Ecosystem.md b/docs/policies/Ecosystem.md index cbe1f8b02..1431b870f 100644 --- a/docs/policies/Ecosystem.md +++ b/docs/policies/Ecosystem.md @@ -1,10 +1,10 @@ --- title: Overview of the NuGet Ecosystem description: Comprehensive resources in the NuGet ecosystem including NuGet sources, non-Microsoft NuGet projects, utilities, and training materials. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 -ms.topic: conceptual +ms.topic: concept-article --- # An overview of the NuGet ecosystem @@ -17,7 +17,7 @@ All of these projects are able to innovate because of developer contributions. J ## .NET Foundation projects -NuGet provides a free, open source package management system for the Microsoft development platform. It consists of a few client tools as well as the set of services that comprise the [official NuGet Gallery](http://www.nuget.org). Combined, these form the NuGet project which is governed by the [.NET Foundation](http://www.dotnetfoundation.org/). +NuGet provides a free, open source package management system for the Microsoft development platform. It consists of a few client tools as well as the set of services that comprise the [official NuGet Gallery](https://www.nuget.org). Combined, these form the NuGet project which is governed by the [.NET Foundation](https://www.dotnetfoundation.org/). The NuGet Organization contains various repositories on GitHub. [https://github.com/Nuget/Home](https://github.com/Nuget/Home) gives an overview of all the repositories and where to find the various NuGet components. @@ -33,14 +33,16 @@ Many other individuals and companies have made significant contributions to the - [Artifactory](https://www.jfrog.com/artifactory/) - [BoxStarter](http://boxstarter.org/) - [Chocolatey](https://chocolatey.org/) -- [CoApp](http://coapp.org/) +- [CoApp](https://github.com/coapp/coapp.org) - [JetBrains ReSharper](https://resharper-plugins.jetbrains.com/) +- [JetBrains Space](https://www.jetbrains.com/space/) - [JetBrains TeamCity](https://www.jetbrains.com/teamcity/) - [Klondike](https://github.com/themotleyfool/Klondike) - [MinimalNugetServer](https://github.com/TanukiSharp/MinimalNugetServer) - [MyGet (or NuGet-as-a-service)](http://www.myget.org/) - [NuGet Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer) - [NuGet Server](http://nugetserver.net/) +- [NuGetizer](https://github.com/devlooped/nugetizer) - [OctopusDeploy](https://octopus.com/) - [Paket](https://fsprojects.github.io/Paket/) - [ProGet (Inedo)](http://inedo.com/proget) @@ -54,24 +56,24 @@ Many other individuals and companies have made significant contributions to the These are tools and utilities built on NuGet: -- [Glimpse Extensions](http://getglimpse.com/Packages) (plug-ins are packages) +- [Glimpse Extensions](https://meetglimpse.com/) - [NuGetMustHaves.com](http://nugetmusthaves.com/) - [Orchard](http://www.orchardproject.net/) (CMS modules are fetched from a v1 NuGet feed hosted in the Orchard Gallery) - [Java implementation of NuGet Server](http://jonnyzzz.com/blog/2012/03/07/nuget-server-in-pure-java/) - [NuGetLatest](https://twitter.com/NuGetLatest) (Twitter bot tweeting new package publications) -- [DefinitelyTyped](http://definitelytyped.org/) ([Automatic](https://github.com/DefinitelyTyped/NugetAutomation/) TypeScript Type [Definitions published to NuGet](http://www.nuget.org/packages?q=DefinitelyTyped)) +- [DefinitelyTyped](http://definitelytyped.org/) ([Automatic](https://github.com/DefinitelyTyped/NugetAutomation/) TypeScript Type [Definitions published to NuGet](https://www.nuget.org/packages?q=DefinitelyTyped)) ## Training materials and references -Using a new tool or technology usually comes with a learning curve. Luckily for you, NuGet has no steep learning curve it all! In fact, anyone can [get started consuming packages](../quickstart/use-a-package.md) quickly. +Using a new tool or technology usually comes with a learning curve. Luckily for you, NuGet has no steep learning curve it all! In fact, anyone can [get started consuming packages](../quickstart/install-and-use-a-package-in-visual-studio.md) quickly. That said, authoring packages–and especially good packages–along with embracing NuGet in automated build and deployment processes, requires spending a little more time with the following resources: -- [NuGet Blog](http://blog.nuget.org/) -- [NuGet team on Twitter, @nuget](http://twitter.com/nuget) +- [NuGet Blog](https://devblogs.microsoft.com/nuget/) +- [NuGet team on Twitter, @nuget](https://twitter.com/nuget) - Books: - [Apress Pro NuGet](http://bit.ly/ProNuGet) - - [NuGet 2 Essentials](http://www.amazon.com/NuGet-2-Essentials-Damir-Arh-ebook/dp/B00GTQD5M4) + - [NuGet 2 Essentials](https://www.amazon.com/NuGet-2-Essentials-Damir-Arh/dp/178216586X) ## Documentation for individual packages diff --git a/docs/policies/Governance.md b/docs/policies/Governance.md index 885b91d84..d1e4e1dc8 100644 --- a/docs/policies/Governance.md +++ b/docs/policies/Governance.md @@ -1,10 +1,10 @@ --- title: NuGet Project Governance description: The governance model for NuGet, including roles and responsibilities for committers, contributors, and users. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 -ms.topic: conceptual +ms.topic: article --- # NuGet governance diff --git a/docs/quickstart/create-and-publish-a-package-using-the-dotnet-cli.md b/docs/quickstart/create-and-publish-a-package-using-the-dotnet-cli.md index 3d601f74a..1c662c94d 100644 --- a/docs/quickstart/create-and-publish-a-package-using-the-dotnet-cli.md +++ b/docs/quickstart/create-and-publish-a-package-using-the-dotnet-cli.md @@ -1,94 +1,88 @@ --- -title: Create and publish a NuGet package using the dotnet CLI -description: A walkthrough tutorial on creating and publishing a NuGet package using the .NET Core CLI, dotnet. -author: karann-msft -ms.author: karann -ms.date: 05/24/2019 +title: Create and publish a NuGet package with the dotnet CLI +description: Walk through quickly creating and publishing a NuGet package by using the dotnet CLI. +author: JonDouglas +ms.author: jodou +ms.date: 03/03/2025 ms.topic: quickstart --- -# Quickstart: Create and publish a package (dotnet CLI) +# Quickstart: Create and publish a package with the dotnet CLI -It's a simple process to create a NuGet package from a .NET Class Library and publish it to nuget.org using the `dotnet` command-line interface (CLI). +This quickstart shows you how to quickly create a NuGet package from a .NET class library and publish it to nuget.org by using the .NET command-line interface, or [dotnet CLI](/dotnet/core/tools). ## Prerequisites -1. Install the [.NET Core SDK](https://www.microsoft.com/net/download/), which includes the `dotnet` CLI. Starting in Visual Studio 2017, the dotnet CLI is automatically installed with any .NET Core related workloads. +- The [.NET SDK](https://www.microsoft.com/net/download), which provides the dotnet command-line tool. Starting in Visual Studio 2017, the dotnet CLI automatically installs with any .NET or .NET Core related workloads. -1. [Register for a free account on nuget.org](https://www.nuget.org/users/account/LogOn?returnUrl=%2F) if you don't have one already. Creating a new account sends a confirmation email. You must confirm the account before you can upload a package. +- A free account on nuget.org. Follow the instructions at [Add a new individual account](../nuget-org/individual-accounts.md#add-a-new-individual-account). ## Create a class library project -You can use an existing .NET Class Library project for the code you want to package, or create a simple one as follows: +You can use an existing .NET Class Library project for the code you want to package, or create a simple project as follows: -1. Create a folder called `AppLogger`. +1. Create a folder named *AppLogger*. +1. Open a command prompt and switch to the *AppLogger* folder. All the dotnet CLI commands in this quickstart run on the current folder by default. +1. Enter `dotnet new classlib`, which creates a project with the current folder name. -1. Open a command prompt and switch to the `AppLogger` folder. - -1. Type `dotnet new classlib`, which uses the name of the current folder for the project. - - This creates the new project. - -1. Use `dotnet run` to test that the app has been created properly. +For more information, see [dotnet new](/dotnet/core/tools/dotnet-new). ## Add package metadata to the project file -Every NuGet package needs a manifest that describes the package's contents and dependencies. In a final package, the manifest is a `.nuspec` file that is generated from the NuGet metadata properties that you include in the project file. +Every NuGet package has a manifest that describes the package's contents and dependencies. In the final package, the manifest is a *.nuspec* file, which uses the NuGet metadata properties you include in the project file. -1. Open your project file (`.csproj`) and add the following minimal properties inside the existing `` tag, changing the values as appropriate: +Open the *.csproj*, *.fsproj*, or *.vbproj* project file, and add the following properties inside the existing `` tag. Use your own values for name and company, and replace the package identifier with a unique value. - ```xml - AppLogger - 1.0.0 - your_name - your_company - ``` +```xml +Contoso.08.28.22.001.Test +1.0.0 +your_name +your_company +``` - > [!Important] - > Give the package an identifier that's unique across nuget.org or whatever host you're using. For this walkthrough we recommend including "Sample" or "Test" in the name as the later publishing step does make the package publicly visible (though it's unlikely anyone will actually use it). +> [!Important] +> The package identifier must be unique across nuget.org and other package sources. Publishing makes the package publicly visible, so if you use the example AppLogger library or other test library, use a unique name that includes `Sample` or `Test`. -1. Add any optional properties described on [NuGet metadata properties](/dotnet/core/tools/csproj#nuget-metadata-properties). +You can add any optional properties described in [NuGet metadata properties](../reference/msbuild-targets.md#pack-target). - > [!Note] - > For packages built for public consumption, pay special attention to the **PackageTags** property, as tags help others find your package and understand what it does. +> [!Note] +> For packages you build for public consumption, pay special attention to the `PackageTags` property. Tags help others find your package and understand what it does. ## Run the pack command -To build a NuGet package (a `.nupkg` file) from the project, run the `dotnet pack` command, which also builds the project automatically: +To build a NuGet package or *.nupkg* file from the project, run the [dotnet pack](/dotnet/core/tools/dotnet-pack) command, which also builds the project automatically. -```cli -# Uses the project file in the current folder by default +```dotnetcli dotnet pack ``` -The output shows the path to the `.nupkg` file: +The output shows the path to the *.nupkg* file: ```output -Microsoft (R) Build Engine version 15.5.180.51428 for .NET Core -Copyright (C) Microsoft Corporation. All rights reserved. - - Restore completed in 29.91 ms for D:\proj\AppLoggerNet\AppLogger\AppLogger.csproj. - AppLogger -> D:\proj\AppLoggerNet\AppLogger\bin\Debug\netstandard2.0\AppLogger.dll - Successfully created package 'D:\proj\AppLoggerNet\AppLogger\bin\Debug\AppLogger.1.0.0.nupkg'. -``` +MSBuild version 17.3.0+92e077650 for .NET + Determining projects to restore... + Restored C:\Users\myname\source\repos\AppLogger\AppLogger.csproj (in 64 ms). + AppLogger -> C:\Users\myname\source\repos\AppLogger\bin\Debug\net6.0\AppLogger.dll + Successfully created package 'C:\Users\myname\source\repos\AppLogger\bin\Debug\Contoso.08.28.22.001.Test.1.0.0.nupkg'. + ``` ### Automatically generate package on build -To automatically run `dotnet pack` when you run `dotnet build`, add the following line to your project file within ``: +To automatically run `dotnet pack` whenever you run `dotnet build`, add the following line to your project file within ``: ```xml -true + true ``` ## Publish the package -Once you have a `.nupkg` file, you publish it to nuget.org using the `dotnet nuget push` command along with an API key acquired from nuget.org. +Publish your *.nupkg* file to nuget.org by using the [dotnet nuget push](/dotnet/core/tools/dotnet-nuget-push) command with an API key you get from nuget.org. [!INCLUDE [publish-notes](includes/publish-notes.md)] -### Acquire your API key +### Get your API key -[!INCLUDE [publish-api-key](includes/publish-api-key.md)] +[!INCLUDE [publish-api-key](includes/publish-api-key-with-link.md)] ### Publish with dotnet nuget push @@ -102,19 +96,29 @@ Once you have a `.nupkg` file, you publish it to nuget.org using the `dotnet nug [!INCLUDE [publish-manage](includes/publish-manage.md)] +Congratulations on creating and publishing your first NuGet package! + +## Related video + +> [!VIDEO https://learn-video.azurefd.net/vod/player?show=dotnet-package-management-with-nuget-for-beginners&ep=creating-and-publishing-a-nuget-package-nuget-for-beginners] + +Find more NuGet videos on [Channel 9](/shows/NuGet-101/) and [YouTube](https://www.youtube.com/playlist?list=PLdo4fOcmZ0oVLvfkFk8O9h6v2Dcdh2bh_). + ## Next steps -Congratulations on creating your first NuGet package! + +See more details about how to create packages with the dotnet CLI: > [!div class="nextstepaction"] -> [Create a Package](../create-packages/creating-a-package-dotnet-cli.md) +> [Create a NuGet package with the dotnet CLI](../create-packages/creating-a-package-dotnet-cli.md) -To explore more that NuGet has to offer, select the links below. +Get more information about creating and publishing NuGet packages: -- [Publish a Package](../nuget-org/publish-a-package.md) -- [Pre-release Packages](../create-packages/Prerelease-Packages.md) +- [Publish a package](../nuget-org/publish-a-package.md) +- [Prerelease packages](../create-packages/Prerelease-Packages.md) - [Support multiple target frameworks](../create-packages/multiple-target-frameworks-project-file.md) - [Package versioning](../concepts/package-versioning.md) -- [Creating localized packages](../create-packages/creating-localized-packages.md) -- [Creating symbol packages](../create-packages/symbol-packages-snupkg.md) -- [Signing packages](../create-packages/Sign-a-package.md) +- [Add a license expression or file](../reference/msbuild-targets.md#packing-a-license-expression-or-a-license-file) +- [Create localized packages](../create-packages/creating-localized-packages.md) +- [Create symbol packages](../create-packages/symbol-packages-snupkg.md) +- [Sign packages](../create-packages/Sign-a-package.md) diff --git a/docs/quickstart/create-and-publish-a-package-using-visual-studio-net-framework.md b/docs/quickstart/create-and-publish-a-package-using-visual-studio-net-framework.md index bc2e04a5b..694fbab75 100644 --- a/docs/quickstart/create-and-publish-a-package-using-visual-studio-net-framework.md +++ b/docs/quickstart/create-and-publish-a-package-using-visual-studio-net-framework.md @@ -1,106 +1,111 @@ --- -title: Create and publish a .NET Framework NuGet package using Visual Studio on Windows -description: A walkthrough tutorial on creating and publishing a .NET Framework NuGet package using Visual Studio on Windows. -author: karann-msft -ms.author: karann -ms.date: 05/13/2018 +title: "Quickstart: Create and publish a package using Visual Studio (.NET Framework, Windows)" +description: A quickstart that shows how to create and publish a .NET Framework NuGet package using Visual Studio on Windows. +author: JonDouglas +ms.author: jodou +ms.date: 03/03/2025 ms.topic: quickstart --- # Quickstart: Create and publish a package using Visual Studio (.NET Framework, Windows) -Creating a NuGet package from a .NET Framework Class Library involves creating the DLL in Visual Studio on Windows, then using the nuget.exe command line tool to create and publish the package. +With Microsoft Visual Studio, you can create a NuGet package from a .NET Framework class library, and then publish it to nuget.org using the NuGet CLI tool. -> [!Note] -> This Quickstart applies to Visual Studio 2017 and higher versions for Windows only. Visual Studio for Mac does not include the capabilities described here. Use the [dotnet CLI tools](create-and-publish-a-package-using-the-dotnet-cli.md) instead. +The quickstart is for Windows users only. If you're using Visual Studio for Mac, see [dotnet CLI tools](create-and-publish-a-package-using-the-dotnet-cli.md) instead. ## Prerequisites -1. Install any edition of Visual Studio 2017 or higher from [visualstudio.com](https://www.visualstudio.com/) with any .NET-related workload. Visual Studio 2017 automatically includes NuGet capabilities when a .NET workload is installed. +- Install Visual Studio 2022 for Windows with any .NET-related workload. -1. Install the `nuget.exe` CLI by downloading it from [nuget.org](https://dist.nuget.org/win-x86-commandline/latest/nuget.exe), saving that `.exe` file to a suitable folder, and adding that folder to your PATH environment variable. + You can install the 2022 Community edition for free from [visualstudio.microsoft.com](https://visualstudio.microsoft.com/), or use the Professional or Enterprise edition. -1. [Register for a free account on nuget.org](https://www.nuget.org/users/account/LogOn?returnUrl=%2F) if you don't have one already. Creating a new account sends a confirmation email. You must confirm the account before you can upload a package. + Visual Studio 2017 and higher automatically includes NuGet capabilities when a .NET workload is installed. + +- [Register for a free account on nuget.org](../nuget-org/individual-accounts.md#add-a-new-individual-account) if you don't have one already. You must register and confirm the account before you can upload a NuGet package. + +- Install the NuGet CLI by downloading it from [nuget.org](https://dist.nuget.org/win-x86-commandline/latest/nuget.exe). Add the *nuget.exe* file to a suitable folder, and add that folder to your PATH environment variable. ## Create a class library project -You can use an existing .NET Framework Class Library project for the code you want to package, or create a simple one as follows: +To create a class library project, follow these steps: + +1. In Visual Studio, select **File** > **New** > **Project**. -1. In Visual Studio, choose **File > New > Project**, select the **Visual C#** node, select the "Class Library (.NET Framework)" template, name the project AppLogger, and click **OK**. +1. In the **Create a new project** window, select **C#**, **Windows**, and **Library** in the dropdown lists. -1. Right-click on the resulting project file and select **Build** to make sure the project was created properly. The DLL is found within the Debug folder (or Release if you build that configuration instead). +1. In the resulting list of project templates, select **Class Library (.NET Framework)**, and then select **Next**. -Within a real NuGet package, of course, you implement many useful features with which others can build applications. You can also set the target frameworks however you like. For example, see the guides for [UWP](../guides/create-uwp-packages.md) and [Xamarin](../guides/create-packages-for-xamarin.md). +1. In the **Configure your new project** window, enter *AppLogger* for the **Project name**, and then select **Create**. -For this walkthrough, however, you won't write any additional code because a class library from the template is sufficient to create a package. Still, if you'd like some functional code for the package, use the following: +1. To ensure the project was created properly, select **Build** > **Build Solution**. The DLL is found within the Debug folder (or Release if you build that configuration instead). -```cs -using System; +1. (Optional) For this quickstart, you don't need to write any additional code for the NuGet package because the template class library is sufficient to create a package. However, if you'd like some functional code for this sample package, include the following code: -namespace AppLogger -{ - public class Logger - { - public void Log(string text) - { - Console.WriteLine(text); - } - } -} -``` + ```csharp + namespace AppLogger + { + public class Logger + { + public void Log(string text) + { + Console.WriteLine(text); + } + } + } + ``` -> [!Tip] -> Unless you have a reason to choose otherwise, .NET Standard is the preferred target for NuGet packages, as it provides compatibility with the widest range of consuming projects. See [Create and publish a package using Visual Studio (.NET Standard)](create-and-publish-a-package-using-visual-studio.md). + Within a real-world NuGet package, you'd likely implement many useful features with which others can build applications. You can also set the target frameworks. For an example, see [UWP](../guides/create-uwp-packages.md). ## Configure project properties for the package -A NuGet package contains a manifest (a `.nuspec` file), that contains relevant metadata such as the package identifier, version number, description, and more. Some of these can be drawn from the project properties directly, which avoids having to separately update them in both the project and the manifest. This section describes where to set the applicable properties. +A NuGet package includes a manifest (a `.nuspec` file), that contains relevant metadata such as the package identifier, version number, description, and more. Some of this metadata can be drawn from the project properties directly, which avoids having to separately update them in both the project and the manifest. The following steps describe how to set the applicable properties: -1. Select the **Project > Properties** menu command, then select the **Application** tab. +1. Select **Project > Properties**, and then select the **Application** tab. -1. In the **Assembly name** field, give your package a unique identifier. +1. For **Assembly name**, give your package a unique identifier. If you attempt to publish a package with a name that already exists, you see an error. - > [!Important] - > You must give the package an identifier that's unique across nuget.org or whatever host you're using. For this walkthrough we recommend including "Sample" or "Test" in the name as the later publishing step does make the package publicly visible (though it's unlikely anyone will actually use it). - > - > If you attempt to publish a package with a name that already exists, you see an error. + > [!IMPORTANT] + > You must give the package an identifier that's unique across nuget.org or whatever host you're using. Otherwise, an error occurs. For this quickstart we recommend including *Sample* or *Test* in the name because the publishing step makes the package publicly visible. -1. Select the **Assembly Information...** button, which brings up a dialog box in which you can enter other properties that carry into the manifest (see [.nuspec file reference - replacement tokens](../reference/nuspec.md#replacement-tokens)). The most commonly used fields are **Title**, **Description**, **Company**, **Copyright**, and **Assembly version**. These properties ultimately appear with your package on a host like nuget.org, so make sure they're fully descriptive. +1. Select **Assembly Information**, which displays a dialog box in which you can enter other properties that carry into the manifest (see [Replacement tokens](../reference/nuspec.md#replacement-tokens)). The most commonly used fields are **Title**, **Description**, **Company**, **Copyright**, and **Assembly version**. Because these properties appear with your package on a host like nuget.org after you publish it, make sure they're fully descriptive. - ![Assembly information in a .NET Framework project in Visual Studio](media/qs_create-vs-01b-project-properties.png) + :::image type="content" source="media/qs-create-vs-assembly-information.png" alt-text="Screenshot showing the Assembly Information page in a .NET Framework project in Visual Studio."::: -1. Optional: to see and edit the properties directly, open the `Properties/AssemblyInfo.cs` file in the project. +1. (Optional) To see and edit the properties directly, open the *Properties/AssemblyInfo.cs* file in the project by selecting select **Project** > **Edit Project File**. -1. When the properties are set, set the project configuration to **Release** and rebuild the project to generate the updated DLL. +1. After you've set these properties, set the **Active solution configuration** in **Build** > **Configuration Manager** to **Release** and rebuild the project to generate the updated DLL. ## Generate the initial manifest -With a DLL in hand and project properties set, you now use the `nuget spec` command to generate an initial `.nuspec` file from the project. This step includes the relevant replacement tokens to draw information from the project file. +After you've set the project properties and created the DLL, you can now generate an initial *.nuspec* file from the project. This step includes the relevant replacement tokens to draw information from the project file. + +Run `nuget spec` only once to generate the initial manifest. If you update the package, either change values in your project, or edit the manifest directly: + +1. With your project open in **Solution Explorer**, open a command prompt by selecting **Tools** > **Command Line** > **Developer Command Prompt**. -You run `nuget spec` only once to generate the initial manifest. When updating the package, you either change values in your project or edit the manifest directly. + The command prompt opens in your project directory where the `AppLogger.csproj` file is located. -1. Open a command prompt and navigate to the project folder containing `AppLogger.csproj` file. +1. Run the following command: `nuget spec AppLogger.csproj`. -1. Run the following command: `nuget spec AppLogger.csproj`. By specifying a project, NuGet creates a manifest that matches the name of the project, in this case `AppLogger.nuspec`. It also include replacement tokens in the manifest. + NuGet creates a manifest that matches the name of the project, in this case `AppLogger.nuspec`. It also includes replacement tokens in the manifest. -1. Open `AppLogger.nuspec` in a text editor to examine its contents, which should appear as follows: +1. Open `AppLogger.nuspec` in a text editor to examine its contents, which will be similar to the following code: ```xml - $id$ - $version$ - $title$ - $author$ - $author$ - http://LICENSE_URL_HERE_OR_DELETE_THIS_LINE + Package + 1.0.0 + Your username + Your username + MIT + http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE - http://ICON_URL_HERE_OR_DELETE_THIS_LINE false - $description$ + Package description Summary of changes made in this release of the package. - Copyright 2018 + Copyright 2022 Tag1 Tag2 @@ -108,56 +113,63 @@ You run `nuget spec` only once to generate the initial manifest. When updating t ## Edit the manifest -1. NuGet produces an error if you try to create a package with default values in your `.nuspec` file, so you must edit the following fields before proceeding. See [.nuspec file reference - optional metadata elements](../reference/nuspec.md#optional-metadata-elements) for a description of how these are used. +1. Edit the following properties before proceeding. Otherwise, if you try to create a NuGet package with the default values in your `.nuspec` file, an error occurs. For information about these properties, see [Optional metadata elements](../reference/nuspec.md#optional-metadata-elements): - licenseUrl - projectUrl - - iconUrl - releaseNotes - tags -1. For packages built for public consumption, pay special attention to the **Tags** property, as tags help others find your package on sources like nuget.org and understand what it does. +1. For packages built for public consumption, pay special attention to the **Tags** property, as tags help others find your package and understand what it does. -1. You can also add any other elements to the manifest at this time, as described on [.nuspec file reference](../reference/nuspec.md). +1. You can also add any other elements to the manifest at this time, as described in [.nuspec file reference](../reference/nuspec.md). 1. Save the file before proceeding. ## Run the pack command -1. From a command prompt in the folder containing your `.nuspec` file, run the command `nuget pack`. +1. With your project open in **Solution Explorer**, open a command prompt by selecting **Tools** > **Command Line** > **Developer Command Prompt**. -1. NuGet generates a `.nupkg` file in the form of *identifier-version.nupkg*, which you'll find in the current folder. + The command prompt opens in your project directory. + +1. Run the following command: `nuget pack`. + + NuGet generates a *.nupkg* file in the form of *identifier.version.nupkg* in the current folder. ## Publish the package -Once you have a `.nupkg` file, you publish it to nuget.org using `nuget.exe` with an API key acquired from nuget.org. For nuget.org you must use `nuget.exe` 4.1.0 or higher. +After you've created a *.nupkg* file, publish it to nuget.org by using the NuGet CLI with an API key acquired from nuget.org. For nuget.org, you must use `nuget.exe` 4.1.0 or higher. + +If you'd like to test and validate your package before publishing it a public gallery, you can upload it to a test environment like [int.nugettest.org](https://int.nugettest.org) instead of nuget.org. Note that packages uploaded to int.nugettest.org may not be preserved. [!INCLUDE [publish-notes](includes/publish-notes.md)] ### Acquire your API key -[!INCLUDE [publish-api-key](includes/publish-api-key.md)] +[!INCLUDE [publish-api-key](includes/publish-api-key-with-link.md)] + +### Publish with the NuGet CLI -### Publish with nuget push +Using the NuGet CLI (*nuget.exe*) is an alternative to using the .NET CLI: -1. Open a command line and change to the folder containing the `.nupkg` file. +1. Open a command prompt and change to the folder containing the *.nupkg* file. -1. Run the following command, specifying your package name and replacing the key value with your API key: +1. Run the following command. Replace \ with the file name of your package and replace \ with your API key. The package filename is a concatenation of your package ID and version number with a *.nupkg* extension. For example, *AppLogger.1.0.0.nupkg*: ```cli - nuget push AppLogger.1.0.0.nupkg qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 -Source https://api.nuget.org/v3/index.json + nuget push -Source https://api.nuget.org/v3/index.json ``` -1. nuget.exe displays the results of the publishing process: + The result of the publishing process is displayed as follows: ```output - Pushing AppLogger.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'... + Pushing to 'https://www.nuget.org/api/v2/package'... PUT https://www.nuget.org/api/v2/package/ Created https://www.nuget.org/api/v2/package/ 6829ms Your package was pushed. ``` -See [nuget push](../reference/cli-reference/cli-ref-push.md). +For more information, see [nuget push](../reference/cli-reference/cli-ref-push.md). ### Publish errors @@ -169,15 +181,15 @@ See [nuget push](../reference/cli-reference/cli-ref-push.md). ## Next steps -Congratulations on creating your first NuGet package! +Congratulations on creating a NuGet package by using the Visual Studio .NET Framework. Advance to the next article to learn how to create a NuGet package with the NuGet CLI. > [!div class="nextstepaction"] -> [Create a Package](../create-packages/creating-a-package.md) +> [Create a package using the NuGet CLI](../create-packages/creating-a-package.md) -To explore more that NuGet has to offer, select the links below. +To explore more that NuGet has to offer, see the following articles: -- [Publish a Package](../nuget-org/publish-a-package.md) -- [Pre-release Packages](../create-packages/Prerelease-Packages.md) +- [Publish a package](../nuget-org/publish-a-package.md) +- [Build a prerelease package](../create-packages/Prerelease-Packages.md) - [Support multiple target frameworks](../create-packages/supporting-multiple-target-frameworks.md) - [Package versioning](../concepts/package-versioning.md) -- [Creating localized packages](../create-packages/creating-localized-packages.md) +- [Creating a localized package](../create-packages/creating-localized-packages.md) diff --git a/docs/quickstart/create-and-publish-a-package-using-visual-studio.md b/docs/quickstart/create-and-publish-a-package-using-visual-studio.md index d51e97111..dd1169c71 100644 --- a/docs/quickstart/create-and-publish-a-package-using-visual-studio.md +++ b/docs/quickstart/create-and-publish-a-package-using-visual-studio.md @@ -1,162 +1,187 @@ --- -title: Create and publish a .NET Standard NuGet package - Visual Studio on Windows -description: A walkthrough tutorial on creating and publishing a .NET Standard NuGet package using Visual Studio on Windows. -author: karann-msft -ms.author: karann -ms.date: 08/16/2019 +title: "Quickstart: Create and publish a NuGet package using Visual Studio (Windows only)" +description: A quickstart that shows how to create and publish a .NET NuGet package using Visual Studio for Windows. +author: JonDouglas +ms.author: jodou +ms.date: 03/03/2025 ms.topic: quickstart --- -# Quickstart: Create and publish a NuGet package using Visual Studio (.NET Standard, Windows only) +# Quickstart: Create and publish a NuGet package using Visual Studio (Windows only) -It's a simple process to create a NuGet package from a .NET Standard Class Library in Visual Studio on Windows, and then publish it to nuget.org using a CLI tool. +With Microsoft Visual Studio, you can create a NuGet package from a .NET class library, and then publish it to nuget.org using a CLI tool. -> [!Note] -> If you are using Visual Studio for Mac, refer to [this information](/xamarin/cross-platform/app-fundamentals/nuget-multiplatform-libraries/existing-library) on creating a NuGet package, or use the [dotnet CLI tools](create-and-publish-a-package-using-the-dotnet-cli.md). +The quickstart is for Windows users only. If you're using a Mac, use the [.NET CLI](create-and-publish-a-package-using-the-dotnet-cli.md). ## Prerequisites -1. Install any edition of Visual Studio 2019 from [visualstudio.com](https://www.visualstudio.com/) with a .NET Core related workload. +- Install Visual Studio 2022 for Windows with a .NET Core-related workload. -1. If it's not already installed, install the `dotnet` CLI. + You can install the 2022 Community edition for free from [visualstudio.microsoft.com](https://visualstudio.microsoft.com/), or use the Professional or Enterprise edition. - For the `dotnet` CLI, starting in Visual Studio 2017, the `dotnet` CLI is automatically installed with any .NET Core related workloads. Otherwise, install the [.NET Core SDK](https://www.microsoft.com/net/download/) to get the `dotnet` CLI. The `dotnet` CLI is required for .NET Standard projects that use the [SDK-style format](../resources/check-project-format.md) (SDK attribute). The default .NET Standard class library template in Visual Studio 2017 and higher, which is used in this article, uses the SDK attribute. - - > [!Important] - > If you are working with a non-SDK-style project, follow the procedures in [Create and publish a .NET Framework package (Visual Studio)](create-and-publish-a-package-using-visual-studio-net-framework.md) to create and publish the package instead. For this article, the `dotnet` CLI is recommended. Although you can publish any NuGet package using the `nuget.exe` CLI, some of the steps in this article are specific to SDK-style projects and the dotnet CLI. The nuget.exe CLI is used for [non-SDK-style projects](../resources/check-project-format.md) (typically .NET Framework). + Visual Studio 2017 and later automatically includes NuGet capabilities when you install a .NET-related workload. -1. [Register for a free account on nuget.org](https://docs.microsoft.com/en-us/nuget/nuget-org/individual-accounts#add-a-new-individual-account) if you don't have one already. Creating a new account sends a confirmation email. You must confirm the account before you can upload a package. +- Install the .NET CLI, if it's not already installed. + + For Visual Studio 2017 and later, the .NET CLI is automatically installed with any .NET Core-related workload. Otherwise, install the [.NET Core SDK](https://www.microsoft.com/net/download/) to get the .NET CLI. The .NET CLI is required for .NET projects that use the [SDK-style format](../resources/check-project-format.md) (SDK attribute). The default .NET class library template in Visual Studio 2017 and later uses the SDK attribute. + + > [!IMPORTANT] + > If you're working with a non-SDK-style project, follow the procedures in [Create and publish a .NET Framework package (Visual Studio)](create-and-publish-a-package-using-visual-studio-net-framework.md) instead to create and publish the package. For this article, the .NET CLI is recommended. Although you can publish any NuGet package using the NuGet CLI, some of the steps in this article are specific to SDK-style projects and the .NET CLI. The NuGet CLI is used for [non-SDK-style projects](../resources/check-project-format.md) (typically .NET Framework). + +- [Register for a free account on nuget.org](../nuget-org/individual-accounts.md#add-a-new-individual-account) if you don't have one already. You must register and confirm the account before you can upload a NuGet package. + +- Install the NuGet CLI by downloading it from [nuget.org](https://dist.nuget.org/win-x86-commandline/latest/nuget.exe). Add the *nuget.exe* file to a suitable folder, and add that folder to your PATH environment variable. ## Create a class library project -You can use an existing .NET Standard Class Library project for the code you want to package, or create a simple one as follows: +You can use an existing .NET Class Library project for the code you want to package, or create one as follows: -1. In Visual Studio, choose **File > New > Project**, expand the **Visual C# > .NET Standard** node, select the "Class Library (.NET Standard)" template, name the project AppLogger, and click **OK**. +1. In Visual Studio, select **File** > **New** > **Project**. - > [!Tip] - > Unless you have a reason to choose otherwise, .NET Standard is the preferred target for NuGet packages, as it provides compatibility with the widest range of consuming projects. +1. In the **Create a new project** window, select **C#**, **Windows**, and **Library** in the dropdown lists. -1. Right-click on the resulting project file and select **Build** to make sure the project was created properly. The DLL is found within the Debug folder (or Release if you build that configuration instead). +1. In the resulting list of project templates, select **Class Library** (with the description, *A project for creating a class library that targets .NET or .NET Standard*), and then select **Next**. -Within a real NuGet package, of course, you implement many useful features with which others can build applications. For this walkthrough, however, you won't write any additional code because a class library from the template is sufficient to create a package. Still, if you'd like some functional code for the package, use the following: +1. In the **Configure your new project** window, enter *AppLogger* for the **Project name**, and then select **Next**. -```cs -namespace AppLogger -{ - public class Logger - { - public void Log(string text) - { - Console.WriteLine(text); - } - } -} -``` +1. In the **Additional information** window, select an appropriate **Framework**, and then select **Create**. + + If you're unsure which framework to select, the latest is a good choice, and can be easily changed later. For information about which framework to use, see [When to target .NET 5.0 or .NET 6.0 vs. .NET Standard](/dotnet/standard/net-standard#when-to-target-net50-or-net60-vs-netstandard). + +1. To ensure the project was created properly, select **Build** > **Build Solution**. The DLL is found within the Debug folder (or Release if you build that configuration instead). + +1. (Optional) For this quickstart, you don't need to write any additional code for the NuGet package because the template class library is sufficient to create a package. However, if you'd like some functional code for the package, include the following code: + + ```csharp + namespace AppLogger + { + public class Logger + { + public void Log(string text) + { + Console.WriteLine(text); + } + } + } + ``` ## Configure package properties -1. Right-click the project in Solution Explorer, and choose **Properties** menu command, then select the **Package** tab. +After you've created your project, you can configure the NuGet package properties by following these steps: + +1. Select your project in **Solution Explorer**, and then select **Project** > **\ Properties**, where \ is the name of your project. + +1. Expand the **Package** node, and then select **General**. - The **Package** tab appears only for SDK-style projects in Visual Studio, typically .NET Standard or .NET Core class library projects; if you are targeting a non-SDK style project (typically .NET Framework), either [migrate the project](../consume-packages/migrate-packages-config-to-package-reference.md) or see [Create and publish a .NET Framework package](create-and-publish-a-package-using-visual-studio-net-framework.md) instead for step-by-step instructions. + The **Package** node appears only for SDK-style projects in Visual Studio. If you're' targeting a non-SDK style project (typically .NET Framework), either [migrate the project](../consume-packages/migrate-packages-config-to-package-reference.md), or see [Create and publish a .NET Framework package](create-and-publish-a-package-using-visual-studio-net-framework.md) for step-by-step instructions. - ![NuGet package properties in a Visual Studio project](media/qs_create-vs-01-package-properties.png) + :::image type="content" source="media/qs-create-vs-project-properties.png" alt-text="Screenshot showing NuGet package properties in a Visual Studio project."::: - > [!Note] - > For packages built for public consumption, pay special attention to the **Tags** property, as tags help others find your package and understand what it does. +1. For packages built for public consumption, pay special attention to the **Tags** property, as tags help others find your package and understand what it does. -1. Give your package a unique identifier and fill out any other desired properties. For a mapping of MSBuild properties (SDK-style project) to properties in a *.nuspec*, see [pack targets](../reference/msbuild-targets.md#pack-target). For descriptions of properties, see the [.nuspec file reference](../reference/nuspec.md). All of the properties here go into the `.nuspec` manifest that Visual Studio creates for the project. +1. Give your package a unique **Package ID** and fill out any other desired properties. For a table that shows how MSBuild properties (SDK-style projects) map to *.nuspec* file properties, see [pack targets](../reference/msbuild-targets.md#pack-target). For a description of *.nuspec* file properties, see the [.nuspec file reference](../reference/nuspec.md). All of these properties go into the `.nuspec` manifest that Visual Studio creates for the project. - > [!Important] - > You must give the package an identifier that's unique across nuget.org or whatever host you're using. For this walkthrough we recommend including "Sample" or "Test" in the name as the later publishing step does make the package publicly visible (though it's unlikely anyone will actually use it). - > - > If you attempt to publish a package with a name that already exists, you see an error. + > [!IMPORTANT] + > You must give the package an identifier that's unique across nuget.org or whatever host you're using. Otherwise, an error occurs. For this quickstart we recommend including *Sample* or *Test* in the name because the publishing step makes the package publicly visible. -1. (Optional) To see the properties directly in the project file, right-click the project in Solution Explorer and select **Edit AppLogger.csproj**. +1. (Optional) To see the properties directly in the *AppLogger.csproj* project file, select **Project** > **Edit Project File**. - This option is only available starting in Visual Studio 2017 for projects that use the SDK-style attribute. Otherwise, right-click the project and choose **Unload Project**. Then right-click the unloaded project and choose **Edit AppLogger.csproj**. + The **AppLogger.csproj** tab loads. + + This option is available starting in Visual Studio 2017 for projects that use the SDK-style attribute. For earlier Visual Studio versions, you must select **Project** > **Unload Project** before you can edit the project file. ## Run the pack command -1. Set the configuration to **Release**. +To create a NuGet package from your project, follow these steps: -1. Right click the project in **Solution Explorer** and select the **Pack** command: +1. Select **Build** > **Configuration Manager**, and then set the **Active solution configuration** to **Release**. - ![NuGet pack command on the Visual Studio project context menu](media/qs_create-vs-02-pack-command.png) +1. Select the AppLogger project in **Solution Explorer**, then select **Pack**. - If you don't see the **Pack** command, your project is probably not an SDK-style project and you need to use the `nuget.exe` CLI. Either [migrate the project](../consume-packages/migrate-packages-config-to-package-reference.md) and use `dotnet` CLI, or see [Create and publish a .NET Framework package](create-and-publish-a-package-using-visual-studio-net-framework.md) instead for step-by-step instructions. + Visual Studio builds the project and creates the *.nupkg* file. -1. Visual Studio builds the project and creates the `.nupkg` file. Examine the **Output** window for details (similar to the following), which contains the path to the package file. Note also that the built assembly is in `bin\Release\netstandard2.0` as befits the .NET Standard 2.0 target. +1. Examine the **Output** window for details, which contains the path to the package file. In this example, the built assembly is in *bin\Release\net6.0* as befits a .NET 6.0 target: ```output 1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------ - 1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\netstandard2.0\AppLogger.dll + 1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\net6.0\AppLogger.dll 1>Successfully created package 'd:\proj\AppLogger\AppLogger\bin\Release\AppLogger.1.0.0.nupkg'. ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ========== ``` +1. If you don't see the **Pack** command on the menu, your project is probably not an SDK-style project, and you need to use the NuGet CLI. Either [migrate the project](../consume-packages/migrate-packages-config-to-package-reference.md) and use .NET CLI, or see [Create and publish a .NET Framework package](create-and-publish-a-package-using-visual-studio-net-framework.md) for step-by-step instructions. + ### (Optional) Generate package on build -You can configure Visual Studio to automatically generate the NuGet package when you build the project. +You can configure Visual Studio to automatically generate the NuGet package when you build the project: -1. In Solution Explorer, right-click the project and choose **Properties**. +1. Select your project in **Solution Explorer**, and then select **Project** > **\ Properties**, where \ is the name of your project (AppLogger in this case). -2. In the **Package** tab, select **Generate NuGet package on build**. +1. Expand the **Package** node, select **General**, and then select **Generate NuGet package on build**. - ![Automatically generate package on build](media/qs_create-vs-05-generate-on-build.png) + :::image type="content" source="media/qs-create-vs-generate-on-build.png" alt-text="Screenshot showing package properties with Generate NuGet package on build selected."::: > [!NOTE] -> When you automatically generate the package, the time to pack increases the build time for your project. +> When you automatically generate the package, the extra time to pack increases the overall build time for your project. + +### (Optional) Pack with MSBuild -### (Optional) pack with MSBuild +As an alternative to using the **Pack** menu command, NuGet 4.x+ and MSBuild 15.1+ supports a `pack` target when the project contains the necessary package data: -As an alternate to using the **Pack** menu command, NuGet 4.x+ and MSBuild 15.1+ supports a `pack` target when the project contains the necessary package data. Open a command prompt, navigate to your project folder and run the following command. (You typically want to start the "Developer Command Prompt for Visual Studio" from the Start menu, as it will be configured with all the necessary paths for MSBuild.) +1. With your project open in **Solution Explorer**, open a command prompt by selecting **Tools** > **Command Line** > **Developer Command Prompt**. + + The command prompt opens in your project directory. + +1. Run the following command: `msbuild -t:pack`. For more information, see [Create a package using MSBuild](../create-packages/creating-a-package-msbuild.md). ## Publish the package -Once you have a `.nupkg` file, you publish it to nuget.org using either the `nuget.exe` CLI or the `dotnet.exe` CLI along with an API key acquired from nuget.org. +After you've created a *.nupkg* file, publish it to nuget.org by using either the .NET CLI or the NuGet CLI, along with an API key acquired from nuget.org. [!INCLUDE [publish-notes](includes/publish-notes.md)] ### Acquire your API key -[!INCLUDE [publish-api-key](includes/publish-api-key.md)] +Before you publish your NuGet package, create an API key: -### Publish with the dotnet CLI or nuget.exe CLI +[!INCLUDE [publish-api-key](includes/publish-api-key-with-link.md)] -Select the tab for your CLI tool, either **.NET Core CLI** (dotnet CLI) or **NuGet** (nuget.exe CLI). +### Publish with the .NET CLI or NuGet CLI -# [.NET Core CLI](#tab/netcore-cli) +Each of the following CLI tools allows you to push a package to the server and publish it. Select the tab for your CLI tool, either **.NET CLI** or **NuGet CLI**. -This step is the recommended alternative to using `nuget.exe`. +#### [.NET CLI](#tab/netcore-cli) -Before you can publish the package, you must first open a command line. +Using the .NET CLI (*dotnet.exe*) is the recommended alternative to using the NuGet CLI. [!INCLUDE [publish-dotnet](includes/publish-dotnet.md)] -# [NuGet](#tab/nuget) +#### [NuGet CLI](#tab/nuget) + +Using the NuGet CLI (*nuget.exe*) is an alternative to using the .NET CLI: -This step is an alternative to using `dotnet.exe`. +1. Open a command prompt and change to the folder containing the *.nupkg* file. -1. Open a command line and change to the folder containing the `.nupkg` file. +1. Run the following command. Replace \ with the file name of your package and replace \ with your API key. -1. Run the following command, specifying your package name (unique package ID) and replacing the key value with your API key: + The NuGet CLI generates a *.nupkg* file in the form of *package ID-version.nupkg*. For example, *AppLogger.1.0.0.nupkg*: - ```cli - nuget push AppLogger.1.0.0.nupkg qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 -Source https://api.nuget.org/v3/index.json + ```nuget + nuget push -Source https://api.nuget.org/v3/index.json ``` -1. nuget.exe displays the results of the publishing process: + The result of the publishing process is displayed as follows: ```output - Pushing AppLogger.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'... + Pushing to 'https://www.nuget.org/api/v2/package'... PUT https://www.nuget.org/api/v2/package/ Created https://www.nuget.org/api/v2/package/ 6829ms Your package was pushed. ``` -See [nuget push](../reference/cli-reference/cli-ref-push.md). +For more information, see [nuget push](../reference/cli-reference/cli-ref-push.md). --- @@ -168,9 +193,9 @@ See [nuget push](../reference/cli-reference/cli-ref-push.md). [!INCLUDE [publish-manage](includes/publish-manage.md)] -## Adding a readme and other files +## Add a readme or another file -To directly specify files to include in the package, edit the project file and use the `content` property: +To directly specify files to include in the package, edit the project file and add the `content` property: ```xml @@ -181,20 +206,46 @@ To directly specify files to include in the package, edit the project file and u ``` -This will include a file named `readme.txt` in the package root. Visual Studio displays the contents of that file as plain text immediately after installing the package directly. (Readme files are not displayed for packages installed as dependencies). For example, here's how the readme for the HtmlAgilityPack package appears: +In this example, the property specifies a file named *readme.txt* in the project root. Visual Studio displays the contents of that file as plain text immediately after it installs the package. Readme files aren't displayed for packages installed as dependencies. For example, here's the readme for the HtmlAgilityPack package: + +```output +1 ---------------------------------------------------- +2 ---------- Html Agility Pack Nuget Readme ---------- +3 ---------------------------------------------------- +4 +5 ----Silverlight 4 and Windows Phone 7.1+ projects----- +6 To use XPATH features: System.Xml.Xpath.dll from the 3 Silverlight 4 SDK must be referenced. +7 This is normally found at +8 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client +9 or +10 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client +11 +12 ----Silverlight 5 projects----- +13 To use XPATH features: System.Xml.Xpath.dll from the Silverlight 5 SDK must be referenced. +14 This is normally found at +15 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client +16 or +17 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client +``` + +> [!NOTE] +> If you only add *readme.txt* at the project root without including it in the `content` property of the project file, it won't be included in the package. + +## Related video + +Find NuGet videos on [Channel 9](/shows/NuGet-101/) and [YouTube](https://www.youtube.com/playlist?list=PLdo4fOcmZ0oVLvfkFk8O9h6v2Dcdh2bh_). -![The display of a readme file for a NuGet package upon installation](../create-packages/media/Create_01-ShowReadme.png) +Congratulations on creating a NuGet package by using a Visual Studio .NET class library. Advance to the next article to learn how to create a NuGet package with the Visual Studio .NET Framework. -> [!Note] -> Merely adding the readme.txt at the project root will not result in it being included in the resulting package. +> [!div class="nextstepaction"] +> [Create a package using the NuGet CLI](../create-packages/creating-a-package.md) -## Related topics +To explore more that NuGet has to offer, see the following articles: -- [Create a Package](../create-packages/creating-a-package-dotnet-cli.md) -- [Publish a Package](../nuget-org/publish-a-package.md) -- [Pre-release Packages](../create-packages/Prerelease-Packages.md) -- [Support multiple target frameworks](../create-packages/multiple-target-frameworks-project-file.md) +- [Create a NuGet package](../create-packages/creating-a-package-dotnet-cli.md) +- [Publish a package](../nuget-org/publish-a-package.md) +- [Build a prerelease package](../create-packages/Prerelease-Packages.md) +- [Support multiple .NET Framework versions](../create-packages/multiple-target-frameworks-project-file.md) - [Package versioning](../concepts/package-versioning.md) -- [Creating localized packages](../create-packages/creating-localized-packages.md) -- [.NET Standard Library documentation](/dotnet/articles/standard/library) +- [Create localized NuGet packages](../create-packages/creating-localized-packages.md) - [Porting to .NET Core from .NET Framework](/dotnet/articles/core/porting/index) diff --git a/docs/quickstart/includes/publish-api-key-with-link.md b/docs/quickstart/includes/publish-api-key-with-link.md new file mode 100644 index 000000000..b0162ee05 --- /dev/null +++ b/docs/quickstart/includes/publish-api-key-with-link.md @@ -0,0 +1,3 @@ +[!INCLUDE [publish-api-key](publish-api-key.md)] + +For more information, see [scoped API keys](../../nuget-org/scoped-api-keys.md). diff --git a/docs/quickstart/includes/publish-api-key.md b/docs/quickstart/includes/publish-api-key.md index d47a1a179..b2588b6be 100644 --- a/docs/quickstart/includes/publish-api-key.md +++ b/docs/quickstart/includes/publish-api-key.md @@ -1,15 +1,24 @@ -1. [Sign into your nuget.org account](https://www.nuget.org/users/account/LogOn?returnUrl=%2F) or create an account if you don't have one already. +1. [Sign into your nuget.org account](https://www.nuget.org/users/account/LogOn?returnUrl=%2F) or [create an account](../../nuget-org/individual-accounts.md#add-a-new-individual-account) if you don't have one already. - For more information on creating your account, see [Individual accounts](../../nuget-org/individual-accounts.md). +1. Select your user name at upper right, and then select **API Keys**. -1. Select your user name (on the upper right), then select **API Keys**. +1. Select **Create**, and provide a name for your key. -1. Select **Create**, provide a name for your key, select **Select Scopes > Push**. Enter * for **Glob pattern**, then select **Create**. (See below for more about scopes.) +1. Under **Select Scopes**, select **Push**. -1. Once the key is created, select **Copy** to retrieve the access key you need in the CLI: +1. Under **Select Packages** > **Glob Pattern**, enter \*. - ![Copying the API key to the clipboard](../media/QS_Create-02-APIKey.png) +1. Select **Create**. -1. **Important**: Save your key in a secure location because you cannot copy the key again later on. If you return to the API key page, you need to regenerate the key to copy it. You can also remove the API key if you no longer want to push packages via the CLI. +1. Select **Copy** to copy the new key. -Scoping allows you to create separate API keys for different purposes. Each key has its expiration timeframe and can be scoped to specific packages (or glob patterns). Each key is also scoped to specific operations: push of new packages and updates, push of updates only, or delisting. Through scoping, you can create API keys for different people who manage packages for your organization such that they have only the permissions they need. For more information, see [scoped API keys](../../nuget-org/scoped-api-keys.md). \ No newline at end of file + ![Screenshot that shows the new API key with the Copy link.](../media/qs-create-api-key.png) + +> [!IMPORTANT] +> +> - Always keep your API key a secret. The API key is like a password that allows anyone to manage packages on your behalf. Delete or regenerate your API key if it's accidentally revealed. +> - Save your key in a secure location, because you can't copy the key again later. If you return to the API key page, you need to regenerate the key to copy it. You can also remove the API key if you no longer want to push packages. + +*Scoping* lets you create separate API keys for different purposes. Each key has an expiration timeframe, and you can scope the key to specific packages or glob patterns. You also scope each key to specific operations: Push new packages and package versions, push only new package versions, or unlist. + +Through scoping, you can create API keys for different people who manage packages for your organization so they have only the permissions they need. \ No newline at end of file diff --git a/docs/quickstart/includes/publish-dotnet.md b/docs/quickstart/includes/publish-dotnet.md index 9223b9eff..eead5986d 100644 --- a/docs/quickstart/includes/publish-dotnet.md +++ b/docs/quickstart/includes/publish-dotnet.md @@ -1,18 +1,20 @@ -1. Change to the folder containing the `.nupkg` file. +From the folder that contains the *.nupkg* file, run the following command. Specify your *.nupkg* filename, and replace the key value with your API key. -1. Run the following command, specifying your package name (unique package ID) and replacing the key value with your API key: +```dotnetcli +dotnet nuget push Contoso.08.28.22.001.Test.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json +``` - ```cli - dotnet nuget push AppLogger.1.0.0.nupkg -k qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 -s https://api.nuget.org/v3/index.json - ``` +The output shows the results of the publishing process: -1. dotnet displays the results of the publishing process: +```output +Pushing Contoso.08.28.22.001.Test.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'... + PUT https://www.nuget.org/api/v2/package/ +warn : All published packages should have license information specified. Learn more: https://aka.ms/nuget/authoring-best-practices#licensing. + Created https://www.nuget.org/api/v2/package/ 1221ms +Your package was pushed. +``` - ```output - info : Pushing AppLogger.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'... - info : PUT https://www.nuget.org/api/v2/package/ - info : Created https://www.nuget.org/api/v2/package/ 12620ms - info : Your package was pushed. - ``` +For more information, see [dotnet nuget push](/dotnet/core/tools/dotnet-nuget-push). -See [dotnet nuget push](/dotnet/core/tools/dotnet-nuget-push). \ No newline at end of file +> [!NOTE] +> If you want to avoid your test package being live on nuget.org, you can push to the nuget.org test site at [https://int.nugettest.org](https://int.nugettest.org). Note that packages uploaded to int.nugettest.org might not be preserved. \ No newline at end of file diff --git a/docs/quickstart/includes/publish-errors.md b/docs/quickstart/includes/publish-errors.md index cfdb184cc..a6afe8686 100644 --- a/docs/quickstart/includes/publish-errors.md +++ b/docs/quickstart/includes/publish-errors.md @@ -1,10 +1,10 @@ -Errors from the `push` command typically indicate the problem. For example, you may have forgotten to update the version number in your project and are therefore trying to publish a package that already exists. +Errors from the `push` command typically indicate the problem. For example, you might have forgotten to update the version number in your project, so you're trying to publish a package that already exists. -You also see errors when trying to publish a package using an identifier that already exists on the host. The name "AppLogger", for example, already exists. In such a case, the `push` command gives the following error: +You also see errors if your API key is invalid or expired, or if you try to publish a package using an identifier that already exists on the host. Suppose, for example, the identifier `AppLogger-test` already exists on nuget.org. If you try to publish a package with that identifier, the `push` command gives the following error: -```output -Response status code does not indicate success: 403 (The specified API key is invalid, -has expired, or does not have permission to access the specified package.). -``` + ```output + Response status code does not indicate success: 403 (The specified API key is invalid, + has expired, or does not have permission to access the specified package.). + ``` -If you're using a valid API key that you just created, then this message indicates a naming conflict, which isn't entirely clear from the "permission" part of the error. Change the package identifier, rebuild the project, recreate the `.nupkg` file, and retry the `push` command. \ No newline at end of file +If you get this error, check that you're using a valid API key that hasn't expired. If you are, the error indicates the package identifier already exists on the host. To fix the error, change the package identifier to be unique, rebuild the project, recreate the *.nupkg* file, and retry the `push` command. diff --git a/docs/quickstart/includes/publish-manage.md b/docs/quickstart/includes/publish-manage.md index cde7211e3..bf1b8c8e6 100644 --- a/docs/quickstart/includes/publish-manage.md +++ b/docs/quickstart/includes/publish-manage.md @@ -1,17 +1,23 @@ -From your profile on nuget.org, select **Manage Packages** to see the one you just published. You also receive a confirmation email. Note that it might take a while for your package to be indexed and appear in search results where others can find it. During that time your package page shows the message below: +When your package successfully publishes, you receive a confirmation email. To see the package you just published, on [nuget.org](https://www.nuget.org/), select your user name at upper right, and then select **Manage Packages**. -![This package has not been indexed yet. It will appear in search results and will be available for install/restore after indexing is complete.](../media/QS_Create-03-NotIndexed.png) +> [!NOTE] +> It might take awhile for your package to be indexed and appear in search results where others can find it. During that time, your package appears under **Unlisted Packages**, and the package page shows the following message: +> +> ![Screenshot showing the publishing message that's displayed when you upload a package to nuget.org.](../media/qs-create-not-indexed.png) -And that's it! You've just published your first NuGet package to nuget.org that other developers can use in their own projects. +You've now published a NuGet package to nuget.org that other developers can use in their projects. -If in this walkthrough you created a package that isn't actually useful (such as a package created with an empty class library), you should *unlist* the package to hide it from search results: +If you've created a package that isn't useful (such as this sample package that was created with an empty class library), or you decide you don't want the package to be visible, you can *unlist* the package to hide it from search results: -1. On nuget.org, select your user name (upper right of the page), then select **Manage Packages**. +1. After the package appears under **Published Packages** on the **Manage Packages** page, select the pencil icon next to the package listing. -1. Locate the package you want to unlist under **Published** and select the trash can icon on the right: + ![Screenshot that shows the Edit icon for a package listing on nuget.org.](../media/qs-create-vs-edit-package.png) - ![Trash can icon shown for a package listing on nuget.org](../media/qs_create-vs-03-trash-can.png) +1. On the next page, select **Listing**, deselect the **List in search results** checkbox, and then select **Save**. -1. On the subsequent page, clear the box labeled **List (package-name) in search results** and select **Save**: + ![Screenshot that shows clearing the List checkbox for a package on nuget.org.](../media/qs-create-vs-unlist-package.png) - ![Clearing the List checkbox for a package on nuget.org](../media/qs_create-vs-04-unlist.png) \ No newline at end of file +The package now appears under **Unlisted Packages** in **Manage Packages** and no longer appears in search results. + +> [!NOTE] +> To avoid your test package being live on nuget.org, you can push to the nuget.org test site at [https://int.nugettest.org](https://int.nugettest.org). Note that packages uploaded to int.nugettest.org might not be preserved. diff --git a/docs/quickstart/includes/publish-notes.md b/docs/quickstart/includes/publish-notes.md index 383e4df4b..78007281b 100644 --- a/docs/quickstart/includes/publish-notes.md +++ b/docs/quickstart/includes/publish-notes.md @@ -1,4 +1,5 @@ -> [!Note] -> **Virus scanning**: All packages uploaded to nuget.org are scanned for viruses and rejected if any viruses are found. All packages listed on nuget.org are also scanned periodically. +> [!NOTE] > -> Packages published to nuget.org are also publicly visible to other developers unless you unlist them. To host packages privately, see [Hosting packages](../../hosting-packages/overview.md). \ No newline at end of file +> - Nuget.org scans all uploaded packages for viruses and rejects the packages if it finds any viruses. Nuget.org also scans all existing listed packages periodically. +> +> - Packages you publish to nuget.org are publicly visible to other developers unless you unlist them. To host packages privately, see [Host your own NuGet feeds](../../hosting-packages/overview.md). diff --git a/docs/quickstart/install-and-use-a-package-in-visual-studio-mac.md b/docs/quickstart/install-and-use-a-package-in-visual-studio-mac.md index 8151b05ee..4dd4766b6 100644 --- a/docs/quickstart/install-and-use-a-package-in-visual-studio-mac.md +++ b/docs/quickstart/install-and-use-a-package-in-visual-studio-mac.md @@ -9,7 +9,7 @@ ms.topic: quickstart # Quickstart: Install and use a package in Visual Studio for Mac -NuGet packages contain reusable code that other developers make available to you for use in your projects. See [What is NuGet?](../What-is-NuGet.md) for background. Packages are installed into a Visual Studio for Mac project using the NuGet Package Manager. This article demonstrates the process using the popular [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json/) package and a .NET Core console project. The same process applies to any other Xamarin or .NET Core project. +NuGet packages contain reusable code that other developers make available to you for use in your projects. See [What is NuGet?](../What-is-NuGet.md) for background. Packages are installed into a Visual Studio for Mac project using the NuGet Package Manager. This article demonstrates the process using the popular [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json/) package and a .NET Core console project. The same process applies to any other .NET Core project. Once installed, refer to the package in code with `using ` where \ is specific to the package you're using. Once the reference is made, you can call the package through its API. @@ -66,7 +66,7 @@ With the Newtonsoft.Json package in the project, you can call its `JsonConvert.S public string Email { get; set; } public DateTime DOB { get; set; } } - + class Program { static void Main(string[] args) diff --git a/docs/quickstart/install-and-use-a-package-in-visual-studio.md b/docs/quickstart/install-and-use-a-package-in-visual-studio.md index 4ed36c833..5a73bf2cc 100644 --- a/docs/quickstart/install-and-use-a-package-in-visual-studio.md +++ b/docs/quickstart/install-and-use-a-package-in-visual-studio.md @@ -1,78 +1,82 @@ --- -title: Install and use a NuGet package in Visual Studio -description: A walkthrough tutorial on the process of installing and using a NuGet package in a Visual Studio project. -author: karann-msft -ms.author: karann -ms.date: 07/24/2018 +title: "Quickstart: Install and use a NuGet package in Visual Studio (Windows only)" +description: In this quickstart, you learn how to install and use a NuGet package in a Visual Studio project for Windows. +author: JonDouglas +ms.author: jodou +ms.date: 03/03/2025 ms.topic: quickstart --- -# Quickstart: Install and use a package in Visual Studio (Windows only) +# Quickstart: Install and use a NuGet package in Visual Studio (Windows only) -NuGet packages contain reusable code that other developers make available to you for use in your projects. See [What is NuGet?](../What-is-NuGet.md) for background. Packages are installed into a Visual Studio project using the NuGet Package Manager or the Package Manager Console. This article demonstrates the process using the popular [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json/) package and a Windows Presentation Foundation (WPF) project. The same process applies to any other .NET or .NET Core project. +A *NuGet package* contains reusable code that other developers have made available to you for use in your projects. You can install a NuGet package in a Microsoft Visual Studio project by using the [NuGet Package Manager](../consume-packages/install-use-packages-visual-studio.md), the [Package Manager Console](../consume-packages/install-use-packages-powershell.md), or the [.NET CLI](install-and-use-a-package-using-the-dotnet-cli.md). This article demonstrates how to create a Windows Presentation Foundation (WPF) project with the popular `Newtonsoft.Json` package. The same process applies to any other .NET or .NET Core project. -Once installed, refer to the package in code with `using ` where \ is specific to the package you're using. Once the reference is made, you can call the package through its API. +After you install a NuGet package, you can then make a reference to it in your code with the `using ` statement, where \ is the name of package you're using. After you've made a reference, you can then call the package through its API. -> [!Tip] -> **Start with nuget.org**: Browsing *nuget.org* is how .NET developers typically find components they can reuse in their own applications. You can search *nuget.org* directly or find and install packages within Visual Studio as shown in this article. For general information, see [Find and evaluate NuGet packages](../consume-packages/finding-and-choosing-packages.md). +The article is for Windows users only. If you're using Visual Studio for Mac, see [Install and use a package in Visual Studio for Mac](install-and-use-a-package-in-visual-studio-mac.md). -## Prerequisites +> [!TIP] +> To find a NuGet package, start with *nuget.org*. Browsing nuget.org is how .NET developers typically find components they can reuse in their own applications. You can do a search of nuget.org directly or find and install packages within Visual Studio as shown in this article. For more information, see [Find and evaluate NuGet packages](../consume-packages/finding-and-choosing-packages.md). -- Visual Studio 2019 with the .NET Desktop Development workload. +## Prerequisites -You can install the 2019 Community edition for free from [visualstudio.com](https://www.visualstudio.com/) or use the Professional or Enterprise editions. +- Install Visual Studio 2022 for Windows with the .NET desktop development workload. -If you're using Visual Studio for Mac, see [Install and use a package in Visual Studio for Mac](install-and-use-a-package-in-visual-studio-mac.md). + You can install the 2022 Community edition for free from [visualstudio.microsoft.com](https://visualstudio.microsoft.com/), or use the Professional or Enterprise edition. ## Create a project -NuGet packages can be installed into any .NET project, provided that the package supports the same target framework as the project. +You can install a NuGet package into any .NET project if that package supports the same target framework as the project. However, for this quickstart you'll create a Windows Presentation Foundation (WPF) Application project. -For this walkthrough, use a simple WPF app. Create a project in Visual Studio using **File** > **New Project**, typing **.NET** in the search box, and then selecting the **WPF App (.NET Framework)**. Click **Next**. Accept the default values for **Framework** when prompted. +Follow these steps: -Visual Studio creates the project, which opens in Solution Explorer. +1. In Visual Studio, select **File** > **New** > **Project**. -## Add the Newtonsoft.Json NuGet package +1. In the **Create a new project** window, enter *WPF* in the search box and select **C#** and **Windows** in the dropdown lists. In the resulting list of project templates, select **WPF Application**, and then select **Next**. -To install the package, you can use either the NuGet Package Manager or the Package Manager Console. When you install a package, NuGet records the dependency in either your project file or a `packages.config` file (depending on the project format). For more information, see [Package consumption overview and workflow](../consume-packages/Overview-and-Workflow.md). +1. In the **Configure your new project** window, optionally update the **Project name** and the **Solution name**, and then select **Next**. -### NuGet Package Manager +1. In the **Additional information** window, select **.NET 6.0** (or the latest version) for **Framework**, and then select **Create**. -1. In Solution Explorer, right-click **References** and choose **Manage NuGet Packages**. + Visual Studio creates the project, and it appears in [Solution Explorer](/visualstudio/ide/use-solution-explorer). - ![Manage NuGet Packages command for project References](media/QS_Use-02-ManageNuGetPackages.png) +## Add the Newtonsoft.Json NuGet package -1. Choose "nuget.org" as the **Package source**, select the **Browse** tab, search for **Newtonsoft.Json**, select that package in the list, and select **Install**: +To install a NuGet package in this quickstart, you can use either the NuGet Package Manager or the Package Manager Console. Depending on your project format, the installation of a NuGet package records the dependency in either your project file or a *packages.config* file. For more information, see [Package consumption workflow](../consume-packages/overview-and-workflow.md). - ![Locating Newtonsoft.Json package](media/QS_Use-03-NewtonsoftJson.png) +### NuGet Package Manager + +To use the [NuGet Package Manager](../consume-packages/install-use-packages-visual-studio.md) to install the `Newtonsoft.Json` package in Visual Studio, follow these steps: - If you want more information on the NuGet Package Manager, see [Install and manage packages using Visual Studio](../consume-packages/install-use-packages-visual-studio.md). +1. Select **Project** > **Manage NuGet Packages**. -1. Accept any license prompts. +1. In the **NuGet Package Manager** page, choose **nuget.org** as the **Package source**. -1. (Visual Studio 2017 only) If prompted to select a package management format, select **PackageReference in project file**: +1. From the **Browse** tab, search for *Newtonsoft.Json*, select **Newtonsoft.Json** in the list, and then select **Install**. - ![Selecting a package management format](media/QS_Use-03b-SelectFormat.png) + :::image type="content" source="media/qs-use-install-package.png" alt-text="Screenshot showing the NuGet Package Manager window with the Newtonsoft.Json package selected."::: -1. If prompted to review changes, select **OK**. +1. If you're prompted to verify the installation, select **OK**. ### Package Manager Console -1. Select the **Tools** > **NuGet Package Manager** > **Package Manager Console** menu command. +Alternatively, to use the [Package Manager Console](../consume-packages/install-use-packages-powershell.md) in Visual Studio to install the `Newtonsoft.Json` package, follow these steps: -1. Once the console opens, check that the **Default project** drop-down list shows the project into which you want to install the package. If you have a single project in the solution, it is already selected. +1. From Visual Studio, select **Tools** > **NuGet Package Manager** > **Package Manager Console**. - ![Locating Newtonsoft.Json package](media/QS_Use-08-Console1.png) +1. After the **Package Manager Console** pane opens, verify that the **Default project** drop-down list shows the project in which you want to install the package. If you have a single project in the solution, it's preselected. -1. Enter the command `Install-Package Newtonsoft.Json` (see [Install-Package](../reference/ps-reference/ps-ref-install-package.md)). The console window shows output for the command. Errors typically indicate that the package isn't compatible with the project's target framework. + :::image type="content" source="media/qs-use-package-manager-console.png" alt-text="Screenshot showing the Package Manage Console window with Default project highlighted."::: - If you want more information on the Package Manager Console, see [Install and manage packages using Package Manager Console](../consume-packages/install-use-packages-powershell.md). +1. At the console prompt, enter the command `Install-Package Newtonsoft.Json`. For more information about this command, see [Install-Package](../reference/ps-reference/ps-ref-install-package.md). + + The console window shows the output for the command. Errors typically indicate that the package isn't compatible with the project's target framework. ## Use the Newtonsoft.Json API in the app -With the Newtonsoft.Json package in the project, you can call its `JsonConvert.SerializeObject` method to convert an object to a human-readable string. +With the `Newtonsoft.Json` package in the project, call its `JsonConvert.SerializeObject` method to convert an object to a human-readable string: -1. Open `MainWindow.xaml` and replace the existing `Grid` element with the following: +1. From **Solution Explorer**, open *MainWindow.xaml* and replace the existing `` element with the following code: ```xaml @@ -83,9 +87,9 @@ With the Newtonsoft.Json package in the project, you can call its `JsonConvert.S ``` -1. Open the `MainWindow.xaml.cs` file (located in Solution Explorer under the `MainWindow.xaml` node), and insert the following code inside the `MainWindow` class: +1. Open the *MainWindow.xaml.cs* file under the *MainWindow.xaml* node, and insert the following code inside the `MainWindow` class after the constructor: - ```cs + ```csharp public class Account { public string Name { get; set; } @@ -101,37 +105,48 @@ With the Newtonsoft.Json package in the project, you can call its `JsonConvert.S Email = "john@microsoft.com", DOB = new DateTime(1980, 2, 20, 0, 0, 0, DateTimeKind.Utc), }; - string json = JsonConvert.SerializeObject(account, Formatting.Indented); + string json = JsonConvert.SerializeObject(account, Newtonsoft.Json.Formatting.Indented); TextBlock.Text = json; } ``` -1. Even though you added the Newtonsoft.Json package to the project, red squiggles appears under `JsonConvert` because you need a `using` statement at the top of the code file: +1. To avoid an error for the `JsonConvert` object in the code (a red squiggle line will appear), add the following statement at the beginning of the code file: - ```cs + ```csharp using Newtonsoft.Json; ``` -1. Build and run the app by pressing F5 or selecting **Debug** > **Start Debugging**: +1. To build and run the app, press F5 or select **Debug** > **Start Debugging**. - ![Initial output of the WPF app](media/QS_Use-06-AppStart.png) + The following window appears: -1. Select on the button to see the contents of the TextBlock replaced with some JSON text: + ![Screenshot showing the initial output of the WPF app.](media/qs-use-wpf-app-start.png) - ![Output of the WPF app after selecting the button](media/QS_Use-07-AppEnd.png) +1. Select the **Click Me** button to see the contents of the `TextBlock` object replaced with JSON text. -## Next steps + ![Screenshot showing the output of the WPF app after selecting the button.](media/qs-use-wpf-app-end.png) -Congratulations on installing and using your first NuGet package! +## Related video -> [!div class="nextstepaction"] -> [Install and manage packages using Visual Studio](../consume-packages/install-use-packages-visual-studio.md) +- Find NuGet videos on [Channel 9](/shows/nuget-101/) and [YouTube](https://www.youtube.com/playlist?list=PLdo4fOcmZ0oVLvfkFk8O9h6v2Dcdh2bh_). -> [!div class="nextstepaction"] -> [Install and manage packages using Package Manager Console](../consume-packages/install-use-packages-powershell.md) +## See also -To explore more that NuGet has to offer, select the links below. +For more information about NuGet, see the following articles: -- [Overview and workflow of package consumption](../consume-packages/overview-and-workflow.md) -- [Finding and choosing packages](../consume-packages/finding-and-choosing-packages.md) +- [What is NuGet?](../what-is-nuget.md) +- [Package consumption workflow](../consume-packages/overview-and-workflow.md) +- [Find and choose packages](../consume-packages/finding-and-choosing-packages.md) - [Package references in project files](../consume-packages/package-references-in-project-files.md) +- [Install and use a package using the .NET CLI](install-and-use-a-package-using-the-dotnet-cli.md). +- [Newtonsoft.Json package](https://www.nuget.org/packages/newtonsoft.json) + +## Next steps + +Congratulations on installing and using your first NuGet package. Advance to the next article to learn more about installing and managing NuGet packages. + +> [!div class="nextstepaction"] +> [Install and manage packages using using the NuGet Package Manager](../consume-packages/install-use-packages-visual-studio.md) + +> [!div class="nextstepaction"] +> [Install and manage packages using the Package Manager Console](../consume-packages/install-use-packages-powershell.md) diff --git a/docs/quickstart/install-and-use-a-package-using-the-dotnet-cli.md b/docs/quickstart/install-and-use-a-package-using-the-dotnet-cli.md index 46053babb..b4ccfb956 100644 --- a/docs/quickstart/install-and-use-a-package-using-the-dotnet-cli.md +++ b/docs/quickstart/install-and-use-a-package-using-the-dotnet-cli.md @@ -1,94 +1,95 @@ --- -title: Install and use a NuGet package using the dotnet CLI -description: A walkthrough tutorial on the process of installing and using a NuGet package in a .NET Core project. -author: karann-msft -ms.author: karann -ms.date: 01/23/2018 +title: Install and use a NuGet package with the dotnet CLI +description: Get a quick tutorial on how to use the dotnet CLI to install and use a NuGet package in a .NET project. +author: JonDouglas +ms.author: jodou +ms.date: 03/03/2025 ms.topic: quickstart --- -# Quickstart: Install and use a package using the dotnet CLI +# Quickstart: Install and use a package with the dotnet CLI -NuGet packages contain reusable code that other developers make available to you for use in your projects. See [What is NuGet?](../What-is-NuGet.md) for background. Packages are installed into a .NET Core project using the `dotnet add package` command as described in this article for the popular [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json/) package. +NuGet packages contain compiled binary code that developers make available for other developers to use in their projects. For more information, see [What is NuGet](../What-is-NuGet.md). This quickstart describes how to install the popular [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json) NuGet package into a .NET project by using the [dotnet add package](/dotnet/core/tools/dotnet-add-package) command. -Once installed, refer to the package in code with `using ` where \ is specific to the package you're using. You can then use the package's API. +You refer to installed packages in code with a `using ` directive, where `` is often the package name. You can then use the package's API in your project. > [!Tip] -> **Start with nuget.org**: Browsing nuget.org is how .NET developers typically find components they can reuse in their own applications. You can search nuget.org directly or find and install packages within Visual Studio as shown in this article. +> Browse [nuget.org/packages](https://nuget.org/packages) to find packages you can reuse in your own applications. You can search directly at [https://nuget.org](https://nuget.org/packages), or find and install packages from within Visual Studio. For more information, see [Find and evaluate NuGet packages for your project](../consume-packages/finding-and-choosing-packages.md). ## Prerequisites -- The [.NET Core SDK](https://www.microsoft.com/net/download/), which provides the `dotnet` command-line tool. Starting in Visual Studio 2017, the dotnet CLI is automatically installed with any .NET Core related workloads. +- The [.NET SDK](https://www.microsoft.com/net/download), which provides the `dotnet` command-line tool. Starting in Visual Studio 2017, the dotnet CLI automatically installs with any .NET or .NET Core related workloads. ## Create a project -NuGet packages can be installed into a .NET project of some kind. For this walkthrough, create a simple .NET Core console project as follows: +You can install NuGet packages into a .NET project. For this walkthrough, create a simple .NET console project by using the dotnet CLI, as follows: -1. Create a folder for the project. +1. Create a folder named *Nuget.Quickstart* for the project. 1. Open a command prompt and switch to the new folder. -1. Create the project using the following command: +1. Create the project by using the following command: - ```cli + ```dotnetcli dotnet new console ``` -1. Use `dotnet run` to test that the app has been created properly. +1. Use `dotnet run` to test the app. You should see the output `Hello, World!`. ## Add the Newtonsoft.Json NuGet package 1. Use the following command to install the `Newtonsoft.json` package: - ```cli + ```dotnetcli dotnet add package Newtonsoft.Json ``` -2. After the command completes, open the `.csproj` file to see the added reference: +2. After the command completes, open the *Nuget.Quickstart.csproj* file in Visual Studio to see the added NuGet package reference: ```xml - - - + + + ``` ## Use the Newtonsoft.Json API in the app -1. Open the `Program.cs` file and add the following line at the top of the file: +1. In Visual Studio, open the *Program.cs* file and add the following line at the top of the file: ```cs using Newtonsoft.Json; ``` -1. Add the following code before the `class Program` line: +1. Add the following code to replace the `Console.WriteLine("Hello, World!");` statement: ```cs - public class Account + namespace Nuget.Quickstart { - public string Name { get; set; } - public string Email { get; set; } - public DateTime DOB { get; set; } - } - ``` - -1. Replace the `Main` function with the following: - - ```cs - static void Main(string[] args) - { - Account account = new Account + public class Account { - Name = "John Doe", - Email = "john@nuget.org", - DOB = new DateTime(1980, 2, 20, 0, 0, 0, DateTimeKind.Utc), - }; - - string json = JsonConvert.SerializeObject(account, Formatting.Indented); - Console.WriteLine(json); + public string? Name { get; set; } + public string? Email { get; set; } + public DateTime DOB { get; set; } + } + internal class Program + { + static void Main(string[] args) + { + Account account = new Account + { + Name = "John Doe", + Email = "john@nuget.org", + DOB = new DateTime(1980, 2, 20, 0, 0, 0, DateTimeKind.Utc), + }; + + string json = JsonConvert.SerializeObject(account, Formatting.Indented); + Console.WriteLine(json); + } + } } ``` -1. Build and run the app by using the `dotnet run` command. The output should be the JSON representation of the `Account` object in the code: +1. Save the file, then build and run the app by using the `dotnet run` command. The output is the JSON representation of the `Account` object in the code: ```output { @@ -98,15 +99,21 @@ NuGet packages can be installed into a .NET project of some kind. For this walkt } ``` +Congratulations on installing and using your first NuGet package! + +## Related video + +> [!VIDEO https://learn-video.azurefd.net/vod/player?show=dotnet-package-management-with-nuget-for-beginners&ep=installing-a-nuget-package-using-the-dotnet-cli-nuget-for-beginners] + +Find more NuGet videos on [Channel 9](/shows/NuGet-101/) and [YouTube](https://www.youtube.com/playlist?list=PLdo4fOcmZ0oVLvfkFk8O9h6v2Dcdh2bh_). + ## Next steps -Congratulations on installing and using your first NuGet package! +Learn more about installing and using NuGet packages with the dotnet CLI: > [!div class="nextstepaction"] -> [Install and use packages using the dotnet CLI](../consume-packages/install-use-packages-dotnet-cli.md) - -To explore more that NuGet has to offer, select the links below. +> [Install and use packages by using the dotnet CLI](../consume-packages/install-use-packages-dotnet-cli.md) - [Overview and workflow of package consumption](../consume-packages/overview-and-workflow.md) -- [Finding and choosing packages](../consume-packages/finding-and-choosing-packages.md) +- [Find and choose packages](../consume-packages/finding-and-choosing-packages.md) - [Package references in project files](../consume-packages/package-references-in-project-files.md) diff --git a/docs/quickstart/media/QS_Create-01-NewProject.png b/docs/quickstart/media/QS_Create-01-NewProject.png deleted file mode 100644 index d4eed29e0..000000000 Binary files a/docs/quickstart/media/QS_Create-01-NewProject.png and /dev/null differ diff --git a/docs/quickstart/media/QS_Create-02-APIKey.png b/docs/quickstart/media/QS_Create-02-APIKey.png deleted file mode 100644 index 5e98fc670..000000000 Binary files a/docs/quickstart/media/QS_Create-02-APIKey.png and /dev/null differ diff --git a/docs/quickstart/media/QS_Create-vs-01b-project-properties.png b/docs/quickstart/media/QS_Create-vs-01b-project-properties.png deleted file mode 100644 index 349f4fa60..000000000 Binary files a/docs/quickstart/media/QS_Create-vs-01b-project-properties.png and /dev/null differ diff --git a/docs/quickstart/media/QS_Restore-01-ToolsOptions.png b/docs/quickstart/media/QS_Restore-01-ToolsOptions.png deleted file mode 100644 index 46af08872..000000000 Binary files a/docs/quickstart/media/QS_Restore-01-ToolsOptions.png and /dev/null differ diff --git a/docs/quickstart/media/QS_Use-01-NewProject.png b/docs/quickstart/media/QS_Use-01-NewProject.png deleted file mode 100644 index 20f3df37e..000000000 Binary files a/docs/quickstart/media/QS_Use-01-NewProject.png and /dev/null differ diff --git a/docs/quickstart/media/QS_Use-02-ManageNuGetPackages.png b/docs/quickstart/media/QS_Use-02-ManageNuGetPackages.png deleted file mode 100644 index 5086d4fec..000000000 Binary files a/docs/quickstart/media/QS_Use-02-ManageNuGetPackages.png and /dev/null differ diff --git a/docs/quickstart/media/QS_Use-03-NewtonsoftJson.png b/docs/quickstart/media/QS_Use-03-NewtonsoftJson.png deleted file mode 100644 index 256cc4234..000000000 Binary files a/docs/quickstart/media/QS_Use-03-NewtonsoftJson.png and /dev/null differ diff --git a/docs/quickstart/media/QS_Use-03b-SelectFormat.png b/docs/quickstart/media/QS_Use-03b-SelectFormat.png deleted file mode 100644 index 6fcd5b34a..000000000 Binary files a/docs/quickstart/media/QS_Use-03b-SelectFormat.png and /dev/null differ diff --git a/docs/quickstart/media/QS_Use-04-ShowPotentialFixes.png b/docs/quickstart/media/QS_Use-04-ShowPotentialFixes.png deleted file mode 100644 index 43749d330..000000000 Binary files a/docs/quickstart/media/QS_Use-04-ShowPotentialFixes.png and /dev/null differ diff --git a/docs/quickstart/media/QS_Use-05-AddUsing.png b/docs/quickstart/media/QS_Use-05-AddUsing.png deleted file mode 100644 index ff40655f4..000000000 Binary files a/docs/quickstart/media/QS_Use-05-AddUsing.png and /dev/null differ diff --git a/docs/quickstart/media/QS_Use-06-AppStart.png b/docs/quickstart/media/QS_Use-06-AppStart.png deleted file mode 100644 index 4b82ee5ce..000000000 Binary files a/docs/quickstart/media/QS_Use-06-AppStart.png and /dev/null differ diff --git a/docs/quickstart/media/QS_Use-07-AppEnd.png b/docs/quickstart/media/QS_Use-07-AppEnd.png deleted file mode 100644 index b76893104..000000000 Binary files a/docs/quickstart/media/QS_Use-07-AppEnd.png and /dev/null differ diff --git a/docs/quickstart/media/QS_Use-08-Console1.png b/docs/quickstart/media/QS_Use-08-Console1.png deleted file mode 100644 index 2450415c3..000000000 Binary files a/docs/quickstart/media/QS_Use-08-Console1.png and /dev/null differ diff --git a/docs/quickstart/media/new-project-vs-mac.png b/docs/quickstart/media/new-project-vs-mac.png deleted file mode 100644 index bf74a916f..000000000 Binary files a/docs/quickstart/media/new-project-vs-mac.png and /dev/null differ diff --git a/docs/quickstart/media/qs-create-api-key.png b/docs/quickstart/media/qs-create-api-key.png new file mode 100644 index 000000000..9e0d1045b Binary files /dev/null and b/docs/quickstart/media/qs-create-api-key.png differ diff --git a/docs/quickstart/media/QS_Create-03-NotIndexed.png b/docs/quickstart/media/qs-create-not-indexed.png similarity index 100% rename from docs/quickstart/media/QS_Create-03-NotIndexed.png rename to docs/quickstart/media/qs-create-not-indexed.png diff --git a/docs/quickstart/media/qs-create-vs-assembly-information.png b/docs/quickstart/media/qs-create-vs-assembly-information.png new file mode 100644 index 000000000..8338c95da Binary files /dev/null and b/docs/quickstart/media/qs-create-vs-assembly-information.png differ diff --git a/docs/quickstart/media/qs-create-vs-edit-package.png b/docs/quickstart/media/qs-create-vs-edit-package.png new file mode 100644 index 000000000..57bab2cb5 Binary files /dev/null and b/docs/quickstart/media/qs-create-vs-edit-package.png differ diff --git a/docs/quickstart/media/qs-create-vs-generate-on-build.png b/docs/quickstart/media/qs-create-vs-generate-on-build.png new file mode 100644 index 000000000..f0b741899 Binary files /dev/null and b/docs/quickstart/media/qs-create-vs-generate-on-build.png differ diff --git a/docs/quickstart/media/qs-create-vs-project-properties.png b/docs/quickstart/media/qs-create-vs-project-properties.png new file mode 100644 index 000000000..d7d5264c3 Binary files /dev/null and b/docs/quickstart/media/qs-create-vs-project-properties.png differ diff --git a/docs/quickstart/media/qs-create-vs-unlist-package.png b/docs/quickstart/media/qs-create-vs-unlist-package.png new file mode 100644 index 000000000..0b2b1e8d7 Binary files /dev/null and b/docs/quickstart/media/qs-create-vs-unlist-package.png differ diff --git a/docs/quickstart/media/qs-use-install-package.png b/docs/quickstart/media/qs-use-install-package.png new file mode 100644 index 000000000..253bf15f5 Binary files /dev/null and b/docs/quickstart/media/qs-use-install-package.png differ diff --git a/docs/quickstart/media/qs-use-package-manager-console.png b/docs/quickstart/media/qs-use-package-manager-console.png new file mode 100644 index 000000000..4e1e344bd Binary files /dev/null and b/docs/quickstart/media/qs-use-package-manager-console.png differ diff --git a/docs/quickstart/media/qs-use-wpf-app-end.png b/docs/quickstart/media/qs-use-wpf-app-end.png new file mode 100644 index 000000000..0008262f9 Binary files /dev/null and b/docs/quickstart/media/qs-use-wpf-app-end.png differ diff --git a/docs/quickstart/media/qs-use-wpf-app-start.png b/docs/quickstart/media/qs-use-wpf-app-start.png new file mode 100644 index 000000000..3ab0561d5 Binary files /dev/null and b/docs/quickstart/media/qs-use-wpf-app-start.png differ diff --git a/docs/quickstart/media/qs_create-vs-01-package-properties.png b/docs/quickstart/media/qs_create-vs-01-package-properties.png deleted file mode 100644 index bcb8f159a..000000000 Binary files a/docs/quickstart/media/qs_create-vs-01-package-properties.png and /dev/null differ diff --git a/docs/quickstart/media/qs_create-vs-02-pack-command.png b/docs/quickstart/media/qs_create-vs-02-pack-command.png deleted file mode 100644 index 9d358915e..000000000 Binary files a/docs/quickstart/media/qs_create-vs-02-pack-command.png and /dev/null differ diff --git a/docs/quickstart/media/qs_create-vs-03-trash-can.png b/docs/quickstart/media/qs_create-vs-03-trash-can.png deleted file mode 100644 index a2b15fd26..000000000 Binary files a/docs/quickstart/media/qs_create-vs-03-trash-can.png and /dev/null differ diff --git a/docs/quickstart/media/qs_create-vs-04-unlist.png b/docs/quickstart/media/qs_create-vs-04-unlist.png deleted file mode 100644 index 656af5877..000000000 Binary files a/docs/quickstart/media/qs_create-vs-04-unlist.png and /dev/null differ diff --git a/docs/quickstart/media/qs_create-vs-05-generate-on-build.png b/docs/quickstart/media/qs_create-vs-05-generate-on-build.png deleted file mode 100644 index 48b229e90..000000000 Binary files a/docs/quickstart/media/qs_create-vs-05-generate-on-build.png and /dev/null differ diff --git a/docs/reference/Errors-and-Warnings.md b/docs/reference/Errors-and-Warnings.md index 8832e4950..3abf97dd5 100644 --- a/docs/reference/Errors-and-Warnings.md +++ b/docs/reference/Errors-and-Warnings.md @@ -1,8 +1,8 @@ --- title: NuGet Errors and Warnings Reference description: Complete reference for warnings and errors issued from NuGet during various NuGet operations. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 05/18/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,29 +14,42 @@ In NuGet 4.3.0+, errors and warnings are numbered as described in this topic and The errors and warnings listed here are available only with [PackageReference-based](../consume-packages/package-references-in-project-files.md) projects and NuGet 4.3.0+. NuGet also honors MSBuild properties to suppress warnings or elevate them to errors. For more information, see [How to: Suppress Compiler Warnings](/visualstudio/ide/how-to-suppress-compiler-warnings) in the Visual Studio documentation. +NuGet supports the following configuration properties. + +| Property | Scope | Description | +|----------|-------|-------------| +| TreatWarningsAsErrors | Project | Treats all NuGet warnings as errors | +| NoWarn | Project, PackageReference, ProjectReference | Suppress the warning for the current project, package or project reference | +| WarningsAsErrors | Project | Treat certain warnings as errors | +| WarningsNotAsErrors | Project | Treat certain warnings not as errors. Used in combination with `TreatWarningsAsErrors` set to true. | + ## Errors | Group | Error Numbers | | --- | --- | -| Invalid input errors | [NU1001](./errors-and-warnings/NU1001.md), [NU1002](./errors-and-warnings/NU1002.md), [NU1003](./errors-and-warnings/NU1003.md) | -| Missing package and project errors | [NU1100](./errors-and-warnings/NU1100.md), [NU1101](./errors-and-warnings/NU1101.md), [NU1102](./errors-and-warnings/NU1102.md), [NU1103](./errors-and-warnings/NU1103.md), [NU1104](./errors-and-warnings/NU1104.md), [NU1105](./errors-and-warnings/NU1105.md), [NU1106](./errors-and-warnings/NU1106.md), [NU1107](./errors-and-warnings/NU1107.md), [NU1108](./errors-and-warnings/NU1108.md) | -| Compatibility errors | [NU1201](./errors-and-warnings/NU1201.md), [NU1202](./errors-and-warnings/NU1202.md), [NU1203](./errors-and-warnings/NU1203.md), [NU1401](./errors-and-warnings/NU1401.md) | +| Invalid input errors | [NU1001](./errors-and-warnings/NU1001.md), [NU1002](./errors-and-warnings/NU1002.md), [NU1003](./errors-and-warnings/NU1003.md), [NU1004](./errors-and-warnings/NU1004.md), [NU1005](./errors-and-warnings/NU1005.md), [NU1006](./errors-and-warnings/NU1006.md), [NU1007](./errors-and-warnings/NU1007.md), [NU1008](./errors-and-warnings/NU1008.md), [NU1009](./errors-and-warnings/NU1009.md), [NU1010](./errors-and-warnings/NU1010.md), [NU1011](./errors-and-warnings/NU1011.md), [NU1012](./errors-and-warnings/NU1012.md), [NU1013](./errors-and-warnings/NU1013.md), [NU1014](./errors-and-warnings/NU1014.md), [NU1015](./errors-and-warnings/NU1015.md), [NU1016](./errors-and-warnings/NU1016.md), [NU1017](./errors-and-warnings/NU1017.md) | +| Missing package and project errors | [NU1100](./errors-and-warnings/NU1100.md), [NU1101](./errors-and-warnings/NU1101.md), [NU1102](./errors-and-warnings/NU1102.md), [NU1103](./errors-and-warnings/NU1103.md), [NU1104](./errors-and-warnings/NU1104.md), [NU1105](./errors-and-warnings/NU1105.md), [NU1106](./errors-and-warnings/NU1106.md), [NU1107](./errors-and-warnings/NU1107.md), [NU1108](./errors-and-warnings/NU1108.md), [NU1109](./errors-and-warnings/NU1109.md) | +| Package source mapping errors | [NU1110](./errors-and-warnings/NU1110.md) | +| Compatibility errors | [NU1201](./errors-and-warnings/NU1201.md), [NU1202](./errors-and-warnings/NU1202.md), [NU1203](./errors-and-warnings/NU1203.md), [NU1204](./errors-and-warnings/NU1204.md), [NU1401](./errors-and-warnings/NU1401.md), [NU1402](./errors-and-warnings/NU1402.md), [NU1403](./errors-and-warnings/NU1403.md) | +| Dotnet Tool restore errors | [NU1211](./errors-and-warnings/NU1211.md), [NU1212](./errors-and-warnings/NU1212.md), [NU1213](./errors-and-warnings/NU1213.md) | +| NuGet source errors | [NU1301](./errors-and-warnings/NU1301.md), [NU1302](./errors-and-warnings/NU1302.md) | | NuGet internal errors | [NU1000](./errors-and-warnings/NU1000.md) | | Signed packages errors (creation and verification) | [NU3001](./errors-and-warnings/NU3001.md), [NU3004](./errors-and-warnings/NU3004.md), [NU3005](./errors-and-warnings/NU3005.md), [NU3008](./errors-and-warnings/NU3008.md), [NU3034](./errors-and-warnings/NU3034.md)| -| Pack Errors | [NU5000](./errors-and-warnings/NU5000.md), [NU5001](./errors-and-warnings/NU5001.md), [NU5002](./errors-and-warnings/NU5002.md), [NU5003](./errors-and-warnings/NU5003.md), [NU5004](./errors-and-warnings/NU5004.md), [NU5005](./errors-and-warnings/NU5005.md), [NU5007](./errors-and-warnings/NU5007.md), [NU5008](./errors-and-warnings/NU5008.md), [NU5009](./errors-and-warnings/NU5009.md), [NU5010](./errors-and-warnings/NU5010.md), [NU5011](./errors-and-warnings/NU5011.md), [NU5012](./errors-and-warnings/NU5012.md), [NU5013](./errors-and-warnings/NU5013.md), [NU5014](./errors-and-warnings/NU5014.md), [NU5015](./errors-and-warnings/NU5015.md), [NU5016](./errors-and-warnings/NU5016.md), [NU5017](./errors-and-warnings/NU5017.md), [NU5018](./errors-and-warnings/NU5018.md), [NU5019](./errors-and-warnings/NU5019.md), [NU5020](./errors-and-warnings/NU5020.md), [NU5021](./errors-and-warnings/NU5021.md), [NU5022](./errors-and-warnings/NU5022.md), [NU5023](./errors-and-warnings/NU5023.md), [NU5024](./errors-and-warnings/NU5024.md), [NU5025](./errors-and-warnings/NU5025.md), [NU5026](./errors-and-warnings/NU5026.md), [NU5027](./errors-and-warnings/NU5027.md), [NU5028](./errors-and-warnings/NU5028.md), [NU5029](./errors-and-warnings/NU5029.md), [NU5036](./errors-and-warnings/NU5036.md) -| License specific Pack Errors | [NU5030](./errors-and-warnings/NU5030.md), [NU5031](./errors-and-warnings/NU5031.md), [NU5032](./errors-and-warnings/NU5032.md), [NU5033](./errors-and-warnings/NU5033.md), [NU5034](./errors-and-warnings/NU5034.md), [NU5035](./errors-and-warnings/NU5035.md) +| Pack Errors | [NU5000](./errors-and-warnings/NU5000.md), [NU5001](./errors-and-warnings/NU5001.md), [NU5002](./errors-and-warnings/NU5002.md), [NU5003](./errors-and-warnings/NU5003.md), [NU5004](./errors-and-warnings/NU5004.md), [NU5005](./errors-and-warnings/NU5005.md), [NU5007](./errors-and-warnings/NU5007.md), [NU5008](./errors-and-warnings/NU5008.md), [NU5009](./errors-and-warnings/NU5009.md), [NU5010](./errors-and-warnings/NU5010.md), [NU5011](./errors-and-warnings/NU5011.md), [NU5012](./errors-and-warnings/NU5012.md), [NU5013](./errors-and-warnings/NU5013.md), [NU5014](./errors-and-warnings/NU5014.md), [NU5015](./errors-and-warnings/NU5015.md), [NU5016](./errors-and-warnings/NU5016.md), [NU5017](./errors-and-warnings/NU5017.md), [NU5018](./errors-and-warnings/NU5018.md), [NU5019](./errors-and-warnings/NU5019.md), [NU5020](./errors-and-warnings/NU5020.md), [NU5021](./errors-and-warnings/NU5021.md), [NU5022](./errors-and-warnings/NU5022.md), [NU5023](./errors-and-warnings/NU5023.md), [NU5024](./errors-and-warnings/NU5024.md), [NU5025](./errors-and-warnings/NU5025.md), [NU5026](./errors-and-warnings/NU5026.md), [NU5027](./errors-and-warnings/NU5027.md), [NU5028](./errors-and-warnings/NU5028.md), [NU5029](./errors-and-warnings/NU5029.md), [NU5036](./errors-and-warnings/NU5036.md), [NU5042](./errors-and-warnings/NU5042.md), [NU5049](./errors-and-warnings/NU5049.md) | +| License specific Pack Errors | [NU5030](./errors-and-warnings/NU5030.md), [NU5031](./errors-and-warnings/NU5031.md), [NU5032](./errors-and-warnings/NU5032.md), [NU5033](./errors-and-warnings/NU5033.md), [NU5034](./errors-and-warnings/NU5034.md), [NU5035](./errors-and-warnings/NU5035.md) | +| NuGetAudit specific warnings | [NU1014](./errors-and-warnings/NU1014.md), [NU1900](./errors-and-warnings/NU1900.md), [NU1901, NU1902, NU1903, NU1904](./errors-and-warnings/NU1901-NU1904.md), [NU1905](./errors-and-warnings/NU1905.md) | ## Warnings | Group | Warning numbers | | --- | --- | -| Invalid input warnings | [NU1501](./errors-and-warnings/NU1501.md), [NU1502](./errors-and-warnings/NU1502.md), [NU1503](./errors-and-warnings/NU1503.md) | +| Invalid input warnings | [NU1501](./errors-and-warnings/NU1501.md), [NU1502](./errors-and-warnings/NU1502.md), [NU1503](./errors-and-warnings/NU1503.md), [NU1504](./errors-and-warnings/NU1504.md), [NU1505](./errors-and-warnings/NU1505.md), [NU1506](./errors-and-warnings/NU1506.md), [NU1507](./errors-and-warnings/NU1507.md), [NU1508](./errors-and-warnings/NU1508.md), [NU1509](./errors-and-warnings/NU1509.md), [NU1510](./errors-and-warnings/NU1510.md), [NU1511](./errors-and-warnings/NU1511.md) | | Unexpected package version warnings | [NU1601](./errors-and-warnings/NU1601.md), [NU1602](./errors-and-warnings/NU1602.md), [NU1603](./errors-and-warnings/NU1603.md), [NU1604](./errors-and-warnings/NU1604.md), [NU1605](./errors-and-warnings/NU1605.md), [NU1606](./errors-and-warnings/NU1108.md), [NU1607](./errors-and-warnings/NU1107.md) | | Resolver conflict warnings | [NU1608](./errors-and-warnings/NU1608.md) | -| Package fallback warnings | [NU1701](./errors-and-warnings/NU1701.md) | -| Feed warnings | [NU1801](./errors-and-warnings/NU1801.md) | +| Package fallback warnings | [NU1701](./errors-and-warnings/NU1701.md), [NU1702](./errors-and-warnings/NU1702.md), [NU1703](./errors-and-warnings/NU1703.md)| +| Feed warnings | [NU1801](./errors-and-warnings/NU1801.md), [NU1802](./errors-and-warnings/NU1802.md), [NU1803](./errors-and-warnings/NU1803.md) | | NuGet internal warnings | [NU1500](./errors-and-warnings/NU1500.md) | -| Signed packages warnings (creation and verification) | [NU3000](./errors-and-warnings/NU3000.md), [NU3002](./errors-and-warnings/NU3002.md), [NU3003](./errors-and-warnings/NU3003.md), [NU3006](./errors-and-warnings/NU3006.md), [NU3007](./errors-and-warnings/NU3007.md), [NU3009](./errors-and-warnings/NU3009.md), [NU3010](./errors-and-warnings/NU3010.md), [NU3011](./errors-and-warnings/NU3011.md), [NU3012](./errors-and-warnings/NU3012.md), [NU3013](./errors-and-warnings/NU3013.md), [NU3014](./errors-and-warnings/NU3014.md), [NU3015](./errors-and-warnings/NU3015.md), [NU3016](./errors-and-warnings/NU3016.md), [NU3017](./errors-and-warnings/NU3017.md), [NU3018](./errors-and-warnings/NU3018.md), [NU3019](./errors-and-warnings/NU3019.md), [NU3020](./errors-and-warnings/NU3020.md), [NU3021](./errors-and-warnings/NU3021.md), [NU3022](./errors-and-warnings/NU3022.md), [NU3023](./errors-and-warnings/NU3023.md), [NU3024](./errors-and-warnings/NU3024.md), [NU3025](./errors-and-warnings/NU3025.md), [NU3026](./errors-and-warnings/NU3026.md), [NU3027](./errors-and-warnings/NU3027.md), [NU3028](./errors-and-warnings/NU3028.md), [NU3029](./errors-and-warnings/NU3029.md), [NU3030](./errors-and-warnings/NU3030.md), [NU3031](./errors-and-warnings/NU3031.md), [NU3032](./errors-and-warnings/NU3032.md), [NU3033](./errors-and-warnings/NU3033.md), [NU3035](./errors-and-warnings/NU3035.md), [NU3036](./errors-and-warnings/NU3036.md), [NU3037](./errors-and-warnings/NU3037.md), [NU3038](./errors-and-warnings/NU3038.md), [NU3040](./errors-and-warnings/NU3040.md) | -| Pack Warnings | [NU5100](./errors-and-warnings/NU5100.md), [NU5101](./errors-and-warnings/NU5101.md), [NU5102](./errors-and-warnings/NU5102.md), [NU5103](./errors-and-warnings/NU5103.md), [NU5104](./errors-and-warnings/NU5104.md), [NU5105](./errors-and-warnings/NU5105.md), [NU5106](./errors-and-warnings/NU5106.md), [NU5107](./errors-and-warnings/NU5107.md), [NU5108](./errors-and-warnings/NU5108.md), [NU5109](./errors-and-warnings/NU5109.md), [NU5110](./errors-and-warnings/NU5110.md), [NU5111](./errors-and-warnings/NU5111.md), [NU5112](./errors-and-warnings/NU5112.md), [NU5114](./errors-and-warnings/NU5114.md), [NU5115](./errors-and-warnings/NU5115.md), [NU5116](./errors-and-warnings/NU5116.md), [NU5117](./errors-and-warnings/NU5117.md), [NU5118](./errors-and-warnings/NU5118.md), [NU5119](./errors-and-warnings/NU5119.md), [NU5120](./errors-and-warnings/NU5120.md), [NU5121](./errors-and-warnings/NU5121.md), [NU5122](./errors-and-warnings/NU5122.md), [NU5123](./errors-and-warnings/NU5123.md), [NU5127](./errors-and-warnings/NU5127.md), [NU5128](./errors-and-warnings/NU5128.md), [NU5129](./errors-and-warnings/NU5129.md), [NU5130](./errors-and-warnings/NU5130.md), [NU5131](./errors-and-warnings/NU5131.md), [NU5500](./errors-and-warnings/NU5500.md) -| License specific Pack Warnings | [NU5124](./errors-and-warnings/NU5124.md), [NU5125](./errors-and-warnings/NU5125.md) -| Icon specific Pack Warnings | [NU5046](./errors-and-warnings/NU5046.md), [NU5047](./errors-and-warnings/NU5047.md), [NU5048](./errors-and-warnings/NU5048.md) +| Signed packages warnings (creation and verification) | [NU3000](./errors-and-warnings/NU3000.md), [NU3002](./errors-and-warnings/NU3002.md), [NU3003](./errors-and-warnings/NU3003.md), [NU3006](./errors-and-warnings/NU3006.md), [NU3007](./errors-and-warnings/NU3007.md), [NU3009](./errors-and-warnings/NU3009.md), [NU3010](./errors-and-warnings/NU3010.md), [NU3011](./errors-and-warnings/NU3011.md), [NU3012](./errors-and-warnings/NU3012.md), [NU3013](./errors-and-warnings/NU3013.md), [NU3014](./errors-and-warnings/NU3014.md), [NU3015](./errors-and-warnings/NU3015.md), [NU3016](./errors-and-warnings/NU3016.md), [NU3017](./errors-and-warnings/NU3017.md), [NU3018](./errors-and-warnings/NU3018.md), [NU3019](./errors-and-warnings/NU3019.md), [NU3020](./errors-and-warnings/NU3020.md), [NU3021](./errors-and-warnings/NU3021.md), [NU3022](./errors-and-warnings/NU3022.md), [NU3023](./errors-and-warnings/NU3023.md), [NU3024](./errors-and-warnings/NU3024.md), [NU3025](./errors-and-warnings/NU3025.md), [NU3026](./errors-and-warnings/NU3026.md), [NU3027](./errors-and-warnings/NU3027.md), [NU3028](./errors-and-warnings/NU3028.md), [NU3029](./errors-and-warnings/NU3029.md), [NU3030](./errors-and-warnings/NU3030.md), [NU3031](./errors-and-warnings/NU3031.md), [NU3032](./errors-and-warnings/NU3032.md), [NU3033](./errors-and-warnings/NU3033.md), [NU3035](./errors-and-warnings/NU3035.md), [NU3036](./errors-and-warnings/NU3036.md), [NU3037](./errors-and-warnings/NU3037.md), [NU3038](./errors-and-warnings/NU3038.md), [NU3040](./errors-and-warnings/NU3040.md), [NU3042](./errors-and-warnings/NU3042.md), [NU3043](./errors-and-warnings/NU3043.md) | +| Pack Warnings | [NU5100](./errors-and-warnings/NU5100.md), [NU5101](./errors-and-warnings/NU5101.md), [NU5102](./errors-and-warnings/NU5102.md), [NU5103](./errors-and-warnings/NU5103.md), [NU5104](./errors-and-warnings/NU5104.md), [NU5105](./errors-and-warnings/NU5105.md), [NU5106](./errors-and-warnings/NU5106.md), [NU5107](./errors-and-warnings/NU5107.md), [NU5108](./errors-and-warnings/NU5108.md), [NU5109](./errors-and-warnings/NU5109.md), [NU5110](./errors-and-warnings/NU5110.md), [NU5111](./errors-and-warnings/NU5111.md), [NU5112](./errors-and-warnings/NU5112.md), [NU5114](./errors-and-warnings/NU5114.md), [NU5115](./errors-and-warnings/NU5115.md), [NU5116](./errors-and-warnings/NU5116.md), [NU5117](./errors-and-warnings/NU5117.md), [NU5118](./errors-and-warnings/NU5118.md), [NU5119](./errors-and-warnings/NU5119.md), [NU5120](./errors-and-warnings/NU5120.md), [NU5121](./errors-and-warnings/NU5121.md), [NU5122](./errors-and-warnings/NU5122.md), [NU5123](./errors-and-warnings/NU5123.md), [NU5127](./errors-and-warnings/NU5127.md), [NU5128](./errors-and-warnings/NU5128.md), [NU5129](./errors-and-warnings/NU5129.md), [NU5130](./errors-and-warnings/NU5130.md), [NU5131](./errors-and-warnings/NU5131.md), [NU5133](./errors-and-warnings/NU5133.md), [NU5500](./errors-and-warnings/NU5500.md), [NU5501](./errors-and-warnings/NU5501.md) | +| License specific Pack Warnings | [NU5124](./errors-and-warnings/NU5124.md), [NU5125](./errors-and-warnings/NU5125.md) | +| Icon specific Pack Warnings | [NU5046](./errors-and-warnings/NU5046.md), [NU5047](./errors-and-warnings/NU5047.md), [NU5048](./errors-and-warnings/NU5048.md) | diff --git a/docs/reference/NuGet-Client-SDK.md b/docs/reference/NuGet-Client-SDK.md index 58abb2fdb..e58bee9bf 100644 --- a/docs/reference/NuGet-Client-SDK.md +++ b/docs/reference/NuGet-Client-SDK.md @@ -1,37 +1,160 @@ --- title: NuGet Client SDK description: The API is evolving and not yet documented, but examples are available on Dave Glick's blog. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/09/2018 -ms.topic: conceptual +ms.topic: article --- # NuGet Client SDK -The *NuGet Client SDK* refers to a group of NuGet packages centered around [NuGet.Commands](https://www.nuget.org/packages/NuGet.Commands), [NuGet.Packaging](https://www.nuget.org/packages/NuGet.Packaging), and [NuGet.Protocol](https://www.nuget.org/packages/NuGet.Protocol). These packages replace the earlier [NuGet.Core](https://www.nuget.org/packages/NuGet.Core/) library. +The *NuGet Client SDK* refers to a group of NuGet packages: -We are working on having a stable surface area that we can document soon. +* [`NuGet.Indexing`](https://www.nuget.org/packages/NuGet.Indexing) - NuGet's indexing library for the Visual Studio client search functionality. +* [`NuGet.Commands`](https://www.nuget.org/packages/NuGet.Commands) - Complete commands common to command-line and GUI NuGet clients. +* [`NuGet.Common`](https://www.nuget.org/packages/NuGet.Common) - Common utilities and interfaces for all NuGet libraries. +* [`NuGet.Configuration`](https://www.nuget.org/packages/NuGet.Configuration) - NuGet's configuration settings implementation. +* [`NuGet.Credentials`](https://www.nuget.org/packages/NuGet.Credentials) - NuGet client's authentication models. +* [`NuGet.DependencyResolver.Core`](https://www.nuget.org/packages/NuGet.DependencyResolver.Core) - NuGet's PackageReference dependency resolver implementation. +* [`NuGet.Frameworks`](https://www.nuget.org/packages/NuGet.Frameworks) - NuGet's understanding of target frameworks. +* [`NuGet.LibraryModel`](https://www.nuget.org/packages/NuGet.LibraryModel) - NuGet's types and interfaces for understanding dependencies. +* [`NuGet.Localization`](https://www.nuget.org/packages/NuGet.Localization) - NuGet localization package. +* [`NuGet.PackageManagement`](https://www.nuget.org/packages/NuGet.PackageManagement) - NuGet Package Management functionality for Visual Studio installation flow. +* [`NuGet.Packaging`](https://www.nuget.org/packages/NuGet.Packaging) - Provides a set of APIs to interact with `.nupkg` and `.nuspec` files from a stream. `NuGet.Protocol` depends on this package. +* [`NuGet.ProjectModel`](https://www.nuget.org/packages/NuGet.ProjectModel) - NuGet's core types and interfaces for PackageReference-based restore, such as lock files, assets file and internal restore models. +* [`NuGet.Protocol`](https://www.nuget.org/packages/NuGet.Protocol) - Provides a set of APIs interact with HTTP and file-based NuGet feeds. +* [`NuGet.Resolver`](https://www.nuget.org/packages/NuGet.Resolver) - NuGet's dependency resolver for packages.config based projects. +* [`NuGet.Versioning`](https://www.nuget.org/packages/NuGet.Versioning) - NuGet's implementation of Semantic Versioning. + +You can find the source code for these packages in the [NuGet/NuGet.Client](https://github.com/NuGet/NuGet.Client) GitHub repository. > [!Note] -> For documentation on the NuGet server protocol, please refer to the [NuGet Server API](~/api/overview.md). +> For documentation on the NuGet server protocol, please refer to the [NuGet Server API](~/api/overview.md). + +## Support policy + +The most recent version of NuGet Client SDK is fully supported and can be relied on for bug fixes, updates, and enhancements. + +The recommendation is to use the latest versions of NuGet Client SDK packages, and to examine your project for dependencies on deprecated NuGet Client SDK packages. + +### Patch Releases + +Patched versions of NuGet Client SDK will be released exclusively when critical bugs or security fixes are required for a long-term support (LTS) version of Visual Studio or .NET SDK. + +All security bugs should be reported to the Microsoft Security Response Center (MSRC) at [MSRC's report page](https://aka.ms/opensource/security/create-report). +Also, see the [security policy in the NuGet.Client repo](https://github.com/NuGet/NuGet.Client/blob/dev/SECURITY.md). + +We do not guarantee API stability, as our team's responsibility is tooling, not libraries. +See the [NuGet SDK documentation in the NuGet.Client repo](https://github.com/NuGet/NuGet.Client/blob/dev/docs/nuget-sdk.md) for more information. + +### Package Deprecation + +Out-of-support NuGet Client SDK packages that are not tied to an LTS version of either Visual Studio or .NET will be [deprecated on nuget.org](../nuget-org/Deprecate-packages.md#client-experience-for-deprecated-packages). + +NuGet's package maintenance approach will align with the [.NET Package Maintenance (deprecation)](https://github.com/dotnet/announcements/issues/217) guidance. + +## NuGet.Protocol + +Install the `NuGet.Protocol` package to interact with HTTP and folder-based NuGet package feeds: + +```ps1 +dotnet add package NuGet.Protocol +``` + +You can find the source code for these examples on the [NuGet.Protocol.Samples](https://github.com/NuGet/Samples/tree/main/NuGetProtocolSamples) project on GitHub. + +> [!Tip] +> `Repository.Factory` is defined in the `NuGet.Protocol.Core.Types` namespace, and the `GetCoreV3` method is an extension method defined in the `NuGet.Protocol` namespace. Therefore, you will need to add `using` statements for both namespaces. + +### List package versions + +Find all versions of Newtonsoft.Json using the [NuGet V3 Package Content API](../api/package-base-address-resource.md#enumerate-package-versions): + +[!code-csharp[ListPackageVersions](~/../nuget-samples/NuGetProtocolSamples/Program.cs?name=ListPackageVersions)] + +### Download a package + +Download Newtonsoft.Json v12.0.1 using the [NuGet V3 Package Content API](../api/package-base-address-resource.md): + +[!code-csharp[DownloadPackage](~/../nuget-samples/NuGetProtocolSamples/Program.cs?name=DownloadPackage)] + +### Get package metadata + +Get the metadata for the "Newtonsoft.Json" package using the [NuGet V3 Package Metadata API](../api/registration-base-url-resource.md): + +[!code-csharp[GetPackageMetadata](~/../nuget-samples/NuGetProtocolSamples/Program.cs?name=GetPackageMetadata)] + +### Search packages + +Search for "json" packages using the [NuGet V3 Search API](../api/search-query-service-resource.md): + +[!code-csharp[SearchPackages](~/../nuget-samples/NuGetProtocolSamples/Program.cs?name=SearchPackages)] + +### Push a package + +Push a package using the [NuGet V3 Push and Delete API](../api/package-publish-resource.md): + +[!code-csharp[PushPackage](~/../nuget-samples/NuGetProtocolSamples/Program.cs?name=PushPackage)] + +### Delete a package + +Delete a package using the [NuGet V3 Push and Delete API](../api/package-publish-resource.md): + +> [!Note] +> NuGet servers are free to interpret a package delete request as a "hard delete", "soft delete", or "unlist". +> For example, nuget.org interprets the package delete request as an "unlist". For more information about this +> practice, see the [Deleting Packages](../nuget-org/policies/deleting-packages.md) policy. + +[!code-csharp[DeletePackage](~/../nuget-samples/NuGetProtocolSamples/Program.cs?name=DeletePackage)] + +### Work with authenticated feeds + +Use [`NuGet.Protocol`](https://www.nuget.org/packages/NuGet.Protocol) to work with authenticated feeds. + +[!code-csharp[AuthenticatedFeed](~/../nuget-samples/NuGetProtocolSamples/Program.cs?name=AuthenticatedFeed)] + +## NuGet.Packaging + +Install the `NuGet.Packaging` package to interact with `.nupkg` and `.nuspec` files from a stream: + +```ps1 +dotnet add package NuGet.Packaging +``` + +### Create a package + +Create a package, set metadata, and add dependencies using [`NuGet.Packaging`](https://www.nuget.org/packages/NuGet.Packaging). + +> [!IMPORTANT] +> It is strongly recommended that NuGet packages are created using the official NuGet tooling and **not** using this +> low-level API. There are a variety of characteristics important for a well-formed package and the latest version of +> tooling helps incorporate these best practices. +> +> For more information about creating NuGet packages, see the overview of the +> [package creation workflow](../create-packages/overview-and-workflow.md) and the documentation for official pack +> tooling (for example, [using the dotnet CLI](../create-packages/creating-a-package-dotnet-cli.md)). + +[!code-csharp[CreatePackage](~/../nuget-samples/NuGetProtocolSamples/Program.cs?name=CreatePackage)] + +### Read a package -## Source code +Read a package from a file stream using [`NuGet.Packaging`](https://www.nuget.org/packages/NuGet.Packaging). -The source code is published on GitHub in the project [NuGet/NuGet.Client](https://github.com/NuGet/NuGet.Client). +[!code-csharp[ReadPackage](~/../nuget-samples/NuGetProtocolSamples/Program.cs?name=ReadPackage)] ## Third-party documentation You can find examples and documentation for some of the API in the following blog series by Dave Glick, published 2016: -- [Exploring the NuGet v3 Libraries, Part 1: Introduction and concepts](http://daveaglick.com/posts/exploring-the-nuget-v3-libraries-part-1) -- [Exploring the NuGet v3 Libraries, Part 2: Searching for packages](http://daveaglick.com/posts/exploring-the-nuget-v3-libraries-part-2) -- [Exploring the NuGet v3 Libraries, Part 3: Installing packages](http://daveaglick.com/posts/exploring-the-nuget-v3-libraries-part-3) +* [Exploring the NuGet v3 Libraries, Part 1: Introduction and concepts](http://daveaglick.com/posts/exploring-the-nuget-v3-libraries-part-1) +* [Exploring the NuGet v3 Libraries, Part 2: Searching for packages](http://daveaglick.com/posts/exploring-the-nuget-v3-libraries-part-2) +* [Exploring the NuGet v3 Libraries, Part 3: Installing packages](http://daveaglick.com/posts/exploring-the-nuget-v3-libraries-part-3) > [!Note] > These blog posts were written shortly after the **3.4.3** version of the NuGet client SDK packages were released. > Newer versions of the packages may be incompatible with the information in the blog posts. -Martin Björkström did a follow-up blog post to Dave Glick's blog series where he introduces a different approach on using the NuGet Client SDK for installing NuGet packages: +Martin Björkström did a follow-up blog post to Dave Glick's blog series where he introduces a different approach on using the NuGet Client SDK to install NuGet packages: -- [Revisiting the NuGet v3 Libraries](https://martinbjorkstrom.com/posts/2018-09-19-revisiting-nuget-client-libraries) +* [Revisiting the NuGet v3 Libraries](https://martinbjorkstrom.com/posts/2018-09-19-revisiting-nuget-client-libraries) diff --git a/docs/reference/PowerShell-Reference.md b/docs/reference/PowerShell-Reference.md index 12a7b58ae..f455e63cb 100644 --- a/docs/reference/PowerShell-Reference.md +++ b/docs/reference/PowerShell-Reference.md @@ -1,8 +1,8 @@ --- title: NuGet PowerShell Reference description: The complete reference to PowerShell commands available in the NuGet Package Manager Console in Visual Studio. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 10/02/2017 ms.topic: reference --- @@ -15,7 +15,7 @@ The Package Manager Console provides a PowerShell interface within Visual Studio > All PowerShell commands relate only to package consumption. No PowerShell commands relate to creating and publishing packages except to the extent that a package can also be a consumer of other packages. > [!Important] -> The commands listed here are specific to the Package Manager Console in Visual Studio, and differ from the [Package Management module commands](/powershell/module/packagemanagement/?view=powershell-6) that are available in a general PowerShell environment. Specifically, each environment has commands that are not available in the other, and commands with the same name may also differ in their specific arguments. When using the Package Management Console in Visual Studio, the commands and arguments documented in this present topic apply. +> The commands listed here are specific to the Package Manager Console in Visual Studio, and differ from the [Package Management module commands](/powershell/module/packagemanagement) that are available in a general PowerShell environment. Specifically, each environment has commands that are not available in the other, and commands with the same name may also differ in their specific arguments. When using the Package Management Console in Visual Studio, the commands and arguments documented in this present topic apply. | Common Commands | Description | NuGet Version | | --- | --- | --- | @@ -39,7 +39,7 @@ For complete, detailed help on any of these commands within the console, just ru Get-Help -full ``` -All Package Manager Console commands support the following [common PowerShell parameters](http://go.microsoft.com/fwlink/?LinkID=113216): +All Package Manager Console commands support the following [common PowerShell parameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters): - Debug - ErrorAction @@ -51,4 +51,4 @@ All Package Manager Console commands support the following [common PowerShell pa - WarningAction - WarningVariable -For details, refer to [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216) in the PowerShell documentation. +For details, refer to [about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters) in the PowerShell documentation. \ No newline at end of file diff --git a/docs/reference/Signed-Package-Verification-Options.md b/docs/reference/Signed-Package-Verification-Options.md new file mode 100644 index 000000000..e7359b62e --- /dev/null +++ b/docs/reference/Signed-Package-Verification-Options.md @@ -0,0 +1,37 @@ +--- +title: NuGet Signed-Package Verification Options +description: Options for NuGet signed-package verification +author: dtivel +ms.author: dtivel +ms.date: 09/01/2023 +ms.topic: reference +--- + +# NuGet signed-package verification options + +## Retry untrusted root failures + +> [!Note] +> This issue only applies to Windows for root certificates in the [Microsoft Trusted Root Program](https://aka.ms/RootCert). + +During certificate chain building, Windows fetches relevant 3rd party root certificates on first use and adds them as locally trusted root certificates. Internally, Windows initiates this network fetch with an RPC call, and if the system is sufficiently busy, this RPC call may fail. This failure results in the root certificate not being locally trusted. This issue may occur the first time a root certificate is observed, but once the root certificate has been locally trusted, the issue will not recur for that certificate. Typically, chain building will succeed with retries. + +For NuGet users, symptoms of this issue are that the NuGet operation will typically succeed on retry and either of the following: + +* [NU3028](errors-and-warnings/NU3028.md) with a message like "A certification chain processed correctly but terminated in a root certificate that is not trusted by the trust provider." +* [NU3037](errors-and-warnings/NU3037.md) with a message like "The repository primary signature validity period has expired." + +> [!Note] +> This option is available starting from NuGet 6.0.0 and only applies to the Windows-specific failure described above. The option does not apply to any other scenario and has no effect on Linux or macOS. +> +> Before NuGet 6.8.0 and .NET 8 SDK, this option is disabled by default. +> +> Starting with NuGet 6.8.0 and .NET 8 SDK, this option is enabled by default on Windows. The environment variable does not need to be set explicitly unless you want to override the default value of `3,1000` or to opt out. To opt out, set the environment variable with a value of `0`. + +You can enable an experimental, automatic retry for untrusted root failures on Windows by setting an environment variable named `NUGET_EXPERIMENTAL_CHAIN_BUILD_RETRY_POLICY` with a value consisting of 2 comma-delimited positive integers representing retry count and sleep interval in milliseconds, respectively. You should pick values that are sensible for you. + +For example, setting the environment variable to a value of `3,1000` like so: + +
    set NUGET_EXPERIMENTAL_CHAIN_BUILD_RETRY_POLICY=3,1000
    + +...would try up to 4 times (initial try plus 3 retries) with 1 second (1,000 ms) between each try. \ No newline at end of file diff --git a/docs/reference/Signed-Packages-Reference.md b/docs/reference/Signed-Packages-Reference.md index fa262d99b..a91eae13e 100644 --- a/docs/reference/Signed-Packages-Reference.md +++ b/docs/reference/Signed-Packages-Reference.md @@ -15,13 +15,13 @@ ms.reviewer: ananguar NuGet packages can include a digital signature that provides protection against tampered content. This signature is produced from an X.509 certificate that also adds authenticity proofs to the actual origin of the package. Signed packages provide the strongest end-to-end validation. There are two different types of NuGet signatures: -- **Author Signature**. An author signature guarantees that the package has not been modified since the author signed the package, no matter from which repository or what transport method the package is delivered. Additionally, author-signed packages provide an extra authentication mechanism to the nuget.org publishing pipeline because the signing certificate must be registered ahead of time. For more information, see [Register certificates](#signature-requirements-on-nugetorg). -- **Repository Signature**. Repository signatures provide an integrity guarantee for **all** packages in a repository whether they are author signed or not, even if those packages are obtained from a different location than the original repository where they were signed. +- **Author signature**. An author signature guarantees that the package has not been modified since the author signed the package, no matter from which repository or what transport method the package is delivered. Additionally, author-signed packages provide an extra authentication mechanism to the nuget.org publishing pipeline because the signing certificate must be registered ahead of time. For more information, see [Register certificates](#signature-requirements-on-nugetorg). +- **Repository signature**. Repository signatures provide an integrity guarantee for **all** packages in a repository whether they are author signed or not, even if those packages are obtained from a different location than the original repository where they were signed. -For details on creating an author signed package, see [Signing Packages](../create-packages/Sign-a-package.md) and the [nuget sign command](../reference/cli-reference/cli-ref-sign.md). +For details on creating an author signed package, see [Signing Packages](../create-packages/Sign-a-package.md) and the [nuget sign command](../reference/cli-reference/cli-ref-sign.md). You can verify packages' signatures using the [dotnet nuget verify](/dotnet/core/tools/dotnet-nuget-verify) or [nuget verify](../reference/cli-reference/cli-ref-verify.md) commands. > [!Important] -> Package signing is currently supported only when using nuget.exe on Windows. Verification of signed packages is currently supported only when using nuget.exe or Visual Studio on Windows. +> Author signing packages is only supported by nuget.exe on Windows at this time. However, all packages uploaded to nuget.org are automatically repository signed. ## Certificate requirements @@ -52,4 +52,6 @@ nuget.org has additional requirements for accepting a signed package: ## Related articles - [Signing NuGet Packages](../create-packages/Sign-a-Package.md) +- [Verify signed packages using the dotnet CLI](/dotnet/core/tools/dotnet-nuget-verify) +- [Verify signed packages using nuget.exe](../reference/cli-reference/cli-ref-verify.md) - [Manage package trust boundaries](../consume-packages/installing-signed-packages.md) diff --git a/docs/reference/cli-reference/cli-ref-add.md b/docs/reference/cli-reference/cli-ref-add.md index 9bc8eb94e..1f34fcb31 100644 --- a/docs/reference/cli-reference/cli-ref-add.md +++ b/docs/reference/cli-reference/cli-ref-add.md @@ -1,8 +1,8 @@ --- title: NuGet CLI add command description: Reference for the nuget.exe add command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -13,12 +13,14 @@ ms.topic: reference Adds a specified package to a non-HTTP package source (a folder or UNC path) in a hierarchical layout, wherein folders are created for the package ID and version number. For example: - \\myserver\packages - └─ - └─ - ├─..nupkg - ├─..nupkg.sha512 - └─.nuspec +``` +\\myserver\packages + └─ + └─ + ├─..nupkg + ├─..nupkg.sha512 + └─.nuspec +``` When restoring or updating against the package source, hierarchical layout provides significantly better performance. @@ -34,14 +36,34 @@ where `` is the pathname to the package to add, and `` ## Options -| Option | Description | -| --- | --- | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| Expand | Adds all the files in the package to the package source. | -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Help | Displays help information for the command. | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. + +- **`-Expand`** + + Adds all the files in the package to the package source. + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. +Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-src|-Source`** + + Specifies the package source, which is a folder or UNC share, to which the nupkg will be added. Http sources are not supported. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. Also see [Environment variables](cli-ref-environment-variables.md) diff --git a/docs/reference/cli-reference/cli-ref-config.md b/docs/reference/cli-reference/cli-ref-config.md index 627bff590..229835f85 100644 --- a/docs/reference/cli-reference/cli-ref-config.md +++ b/docs/reference/cli-reference/cli-ref-config.md @@ -1,8 +1,8 @@ --- title: NuGet CLI config command description: Reference for the nuget.exe config command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -28,14 +28,34 @@ In NuGet 3.4+, `` can use [environment variables](cli-ref-environment-var ## Options -| Option | Description | -| --- | --- | -| AsPath | Returns the config value as a path, ignored when `-Set` is used. | -| ConfigFile | The NuGet configuration file to modify. If not specified, the default file is used -`%AppData%\NuGet\NuGet.Config` (Windows) or `~/.config/NuGet/NuGet.Config` (Mac/Linux) or `~/.nuget/NuGet/NuGet.Config` (varies by OS distribution).| -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Help | Displays help information for the command. | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | + +- **`AsPath`** + + Returns the config value as a path, ignored when `-Set` is used. + +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. See [On Mac/Linux, the user-level config file location varies by tooling.](../../consume-packages/configuring-nuget-behavior.md#on-maclinux-the-user-level-config-file-location-varies-by-tooling). + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-Set`** + + One on more key-value pairs to be set in config. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. Also see [Environment variables](cli-ref-environment-variables.md) diff --git a/docs/reference/cli-reference/cli-ref-delete.md b/docs/reference/cli-reference/cli-ref-delete.md index a9ac38b31..af7bc2c57 100644 --- a/docs/reference/cli-reference/cli-ref-delete.md +++ b/docs/reference/cli-reference/cli-ref-delete.md @@ -1,8 +1,8 @@ --- title: NuGet CLI delete command description: Reference for the nuget.exe delete command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -23,15 +23,40 @@ where `` and `` identify the exact package to delete ## Options -| Option | Description | -| --- | --- | -| ApiKey | The API key for the target repository. If not present, the one specified in the config file is used. | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Help | Displays help information for the command. | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| Source | Specifies the server URL. The URL for nuget.org is `https://api.nuget.org/v3/index.json`. For private feeds, substitute the host name, for example, *%hostname%/api/v3*. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | +- **`-ApiKey`** + + The API key for the target repository. If not present, the one specified in the config file is used. + +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + + - **`-np|-NoPrompt`** + + Do not prompt when deleting. + + - **`-NoServiceEndpoint`** + Does not append "api/v2/packages" to the source URL. + +- **`-src|-Source`** + + Specifies the server URL. The URL for nuget.org is `https://api.nuget.org/v3/index.json`. For private feeds, substitute the host name, for example, *%hostname%/api/v3*. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. Also see [Environment variables](cli-ref-environment-variables.md) diff --git a/docs/reference/cli-reference/cli-ref-environment-variables.md b/docs/reference/cli-reference/cli-ref-environment-variables.md index 77254b39f..e0c993671 100644 --- a/docs/reference/cli-reference/cli-ref-environment-variables.md +++ b/docs/reference/cli-reference/cli-ref-environment-variables.md @@ -1,8 +1,8 @@ --- title: NuGet CLI environment variables description: Reference for the nuget.exe environment variables -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -21,16 +21,21 @@ The list of properties documented in [NuGet pack and restore as MSBuild targets] | http_proxy | Http proxy used for NuGet HTTP operations. | This would be specified as `http://:@proxy.com`. | | no_proxy | Configures domains to bypass from using proxy. | Specified as domains separated by comma (,). | | EnableNuGetPackageRestore | Flag for if NuGet should implicitly grant consent if that's required by package on restore. | Specified flag is treated as *true* or *1*, any other value treated as flag not set. | +| NUGET_CLI_LANGUAGE | Changes nuget.exe output language | Available in 6.5 and higher versions. Supported values are [supported Visual Studio languages](/visualstudio/install/use-command-line-parameters-to-install-visual-studio?view=vs-2022&preserve-view=true#list-of-language-locales) locale names: `zh-cn`, `zh-tw`, `cs-cz`, `en-us`, `es-es`, `fr-fr`, `de-de`, `it-it`, `ja-jp`, `ko-kr`, `pl-pl`, `pt-br`, `ru-ru`, and `tr-tr`. | | NUGET_EXE_NO_PROMPT | Prevents the exe for prompting for credentials. | Any value except null or empty string will be treated as this flag set/true. | +| NUGET_MAX_RETRY_AFTER_DELAY_SECONDS | Maximum duration between retries when HTTP response contains Retry-After header | When NUGET_OBSERVE_RETRY_AFTER is enabled (as it is by default) and an HTTP response contains a Retry-After header, this environment variable sets the maximum duration that will be waited. Note that Retry-After can provide either a duration (delta) or a time stamp (date). If the server returns a time stamp and your machine's clock is out of sync with the server, the calculated duration might be very long (or negative). | | FORCE_NUGET_EXE_INTERACTIVE | Global environment variable to force interactive mode. | Any value except null or empty string will be treated as this flag set/true. | | NUGET_PACKAGES | Path to use for the *global-packages* folder as described on [Managing the global packages and cache folders](../../consume-packages/managing-the-global-packages-and-cache-folders.md). | Specified as absolute path. | | NUGET_FALLBACK_PACKAGES | Global fallback packages folders. | Absolute folder paths separated by semicolon (;). | | NUGET_HTTP_CACHE_PATH | Path to use for the *http-cache* folder as described on [Managing the global packages and cache folders](../../consume-packages/managing-the-global-packages-and-cache-folders.md). | Specified as absolute path. | -| NUGET_PERSIST_DG | Flag indicating if dg files (data collected from MSBuild) should be persisted. | Specified as *true* or *false* (default), if NUGET_PERSIST_DG_PATH not set will be stored to temporary directory (NuGetScratch folder in current environment temp directory). | -| NUGET_PERSIST_DG_PATH | Path to persist dg files. | Specified as absolute path, this option is only used when *NUGET_PERSIST_DG* is set to true. | +| NUGET_OBSERVE_RETRY_AFTER | Opt-out of using HTTP response message Retry-After delay durations | Prior to NuGet 6.5, NuGet would retry all failed requests with the same back-off strategy. Starting with NuGet 6.5, NuGet will by default use the Retry-After delay period provided by the server. Set this environment variable to `false` to ignore the Retry-After response header. Also see NUGET_MAX_RETRY_AFTER_DELAY_SECONDS | | NUGET_RESTORE_MSBUILD_ARGS | Sets additional MSBuild arguments. | Pass arguments identical to how you would pass them to msbuild.exe. An example of setting a project property Foo from the command line to value Bar would be /p:Foo=Bar | +| NUGET_RETRY_HTTP_429 | Change retry behavior on HTTP 429 responses | Prior to NuGet 6.5, NuGet would not retry requests that result in HTTP 429 on 408. The default value is `true`, and this environment variable can be set to `false` to opt-in to older NuGet behaviour (don't retry the request) | | NUGET_RESTORE_MSBUILD_VERBOSITY | Sets the MSBuild log verbosity. | Default is *quiet* ("/v:q"). Possible values *q[uiet]*, *m[inimal]*, *n[ormal]*, *d[etailed]*, and *diag[nostic]*. | | NUGET_SHOW_STACK | Determines whether the full exception (including stack trace) should be displayed to the user. | Specified as *true* or *false* (default). | +| NUGET_UPDATEFILETIME_MAXRETRIES | Sets the number of times NuGet will attempt to retry seting the file timestamp when extracting packages when the first attempt failed. | On Windows anti-virus software might temporarily open files, preventing NuGet from changing the timestamp. NuGet uses an exponential back-off where the wait duration between attempts is `Math.Pow(2, retryNumber)`. The default max retries is 9, meaning the default total wait duration before failure will be approximately one second. | | NUGET_XMLDOC_MODE | Determines how assemblies XML documentation file extraction should be handled. | Supported modes are *skip* (do not extract XML documentation files), *compress* (store XML doc files as a zip archive) or *none* (default, treat XML doc files as regular files). | | NUGET_CERT_REVOCATION_MODE | Determines how the revocation status check of the certificate used to sign a package, is performed when a signed package is installed or restored. When not set, defaults to `online`.| Possible values *online* (default), *offline*. Related to [NU3028](../errors-and-warnings/NU3028.md) | +| NUGET_ENHANCED_MAX_NETWORK_TRY_COUNT | Configures the maximum number of times an HTTP connection should be retried when enhanced retries are enabled. | A number representing how many retries to perform, the default value is `6`. | +| NUGET_ENHANCED_NETWORK_RETRY_DELAY_MILLISECONDS | Configures the amount of time to wait in milliseconds before retrying an HTTP connection when enhanced retries are enabled. | Number of millseconds to wait, the default value is `1000`. | diff --git a/docs/reference/cli-reference/cli-ref-help.md b/docs/reference/cli-reference/cli-ref-help.md index c57b36e4e..ddd222204 100644 --- a/docs/reference/cli-reference/cli-ref-help.md +++ b/docs/reference/cli-reference/cli-ref-help.md @@ -1,8 +1,8 @@ --- title: NuGet CLI help command description: Reference for the nuget.exe help command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -27,15 +27,33 @@ where [command] identifies a specific command for which to display help. ## Options -| Option | Description | -| --- | --- | -| All | Print detailed help for all available commands; ignored if a specific command is given. | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Help | Displays help information for the help command itself. | -| Markdown | Print detailed help in markdown format when used with `-All`. Ignored otherwise. | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | +- **`-All`** + + Print detailed help for all available commands; ignored if a specific command is given. + +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-Markdown`** + + Print detailed help in markdown format when used with `-All`. Ignored otherwise. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. Also see [Environment variables](cli-ref-environment-variables.md) diff --git a/docs/reference/cli-reference/cli-ref-init.md b/docs/reference/cli-reference/cli-ref-init.md index 1a30915f4..6b0289623 100644 --- a/docs/reference/cli-reference/cli-ref-init.md +++ b/docs/reference/cli-reference/cli-ref-init.md @@ -1,8 +1,8 @@ --- title: NuGet CLI init command description: Reference for the nuget.exe init command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -25,14 +25,29 @@ where `` is the folder containing packages and `` is the lo ## Options -| Option | Description | -| --- | --- | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Expand | Adds all files in each package that's added to the package source; same as `-Expand` with the `add` command. | -| Help | Displays help information for the command. | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. + +- **`-Expand`** + + Adds all files in each package that's added to the package source; same as `-Expand` with the `add` command. + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. Also see [Environment variables](cli-ref-environment-variables.md) diff --git a/docs/reference/cli-reference/cli-ref-install.md b/docs/reference/cli-reference/cli-ref-install.md index 99441f7d4..aa96d43bf 100644 --- a/docs/reference/cli-reference/cli-ref-install.md +++ b/docs/reference/cli-reference/cli-ref-install.md @@ -1,8 +1,8 @@ --- title: NuGet CLI install command description: Reference for the nuget.exe install command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -34,26 +34,81 @@ where `` names the package to install (using the latest version), or ## Options -| Option | Description | -| --- | --- | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| DependencyVersion | *(4.4+)* The version of the dependency packages to use, which can be one of the following:
    • *Lowest* (default): the lowest version
    • *HighestPatch*: the version with the lowest major, lowest minor, highest patch
    • *HighestMinor*: the version with the lowest major, highest minor, highest patch
    • *Highest*: the highest version
    | -| DisableParallelProcessing | Disables installing multiple packages in parallel. | -| ExcludeVersion | Installs the package to a folder named with only the package name and not the version number. | -| FallbackSource | *(3.2+)* A list of package sources to use as fallbacks in case the package isn't found in the primary or default source. | -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Framework | *(4.4+)* Target framework used for selecting dependencies. Defaults to 'Any' if not specified. | -| Help | Displays help information for the command. | -| NoCache | Prevents NuGet from using cached packages. See [Managing the global packages and cache folders](../../consume-packages/managing-the-global-packages-and-cache-folders.md). | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| OutputDirectory | Specifies the folder in which packages are installed. If no folder is specified, the current folder is used. | -| PackageSaveMode | Specifies the types of files to save after package installation: one of `nuspec`, `nupkg`, or `nuspec;nupkg`. | -| PreRelease | Allows prerelease packages to be installed. This flag is not required when restoring packages with `packages.config`. | -| RequireConsent | Verifies that restoring packages is enabled before downloading and installing the packages. For details, see [Package Restore](../../consume-packages/package-restore.md). | -| SolutionDirectory | Specifies root folder of the solution for which to restore packages. | -| Source | Specifies the list of package sources (as URLs) to use. If omitted, the command uses the sources provided in configuration files, see [Common NuGet configurations](../../consume-packages/configuring-nuget-behavior.md). | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | -| Version | Specifies the version of the package to install. | +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. + +- **`-DependencyVersion`** + + *(4.4+)* The version of the dependency packages to use, which can be one of the following:
    • *Lowest* (default): the lowest version
    • *HighestPatch*: the version with the lowest major, lowest minor, highest patch
    • *HighestMinor*: the version with the lowest major, highest minor, highest patch
    • *Highest*: the highest version
    • *Ignore*: No dependency packages will be used
    + +- **`-DirectDownload`** + + Download directly without populating any caches with metadata or binaries. + +- **`-DisableParallelProcessing`** + + Disables installing multiple packages in parallel. + +- **`-x|-ExcludeVersion`** + + Installs the package to a folder named with only the package name and not the version number. + +- **`-FallbackSource`** + + *(3.2+)* A list of package sources to use as fallbacks in case the package isn't found in the primary or default source. + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-Framework`** + + *(4.4+)* Target framework used for selecting dependencies. Defaults to 'Any' if not specified. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-NoHttpCache`** + + Prevents NuGet from using http cached packages. See [Managing the global packages and cache folders](../../consume-packages/managing-the-global-packages-and-cache-folders.md). + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-OutputDirectory`** + + Specifies the folder in which packages are installed. If no folder is specified, the current folder is used. + +- **`-PackageSaveMode`** + + Specifies the types of files to save after package installation: one of `nuspec`, `nupkg`, or `nuspec;nupkg`. + +- **`-PreRelease`** + + Allows prerelease packages to be installed. This flag is not required when restoring packages with `packages.config`. + +- **`-RequireConsent`** + + Verifies that restoring packages is enabled before downloading and installing the packages. For details, see [Package Restore](../../consume-packages/package-restore.md). + +- **`-SolutionDirectory`** + + Specifies root folder of the solution for which to restore packages. + +- **`-Source`** + + Specifies the list of package sources (as URLs) to use. If omitted, the command uses the sources provided in configuration files, see [Common NuGet configurations](../../consume-packages/configuring-nuget-behavior.md). + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. + +- **`-Version`** + + Specifies the version of the package to install. Also see [Environment variables](cli-ref-environment-variables.md) diff --git a/docs/reference/cli-reference/cli-ref-list.md b/docs/reference/cli-reference/cli-ref-list.md index cc04c4c1f..b2171fa5f 100644 --- a/docs/reference/cli-reference/cli-ref-list.md +++ b/docs/reference/cli-reference/cli-ref-list.md @@ -1,8 +1,8 @@ --- title: NuGet CLI list command description: Reference for the nuget.exe list command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -19,30 +19,67 @@ Displays a list of packages from a given source. If no sources are specified, al nuget list [search terms] [options] ``` -where the optional search terms will filter the displayed list. Search terms are applied to the names of packages, tags, and package descriptions just as they are when using them on nuget.org. +where the optional search terms will filter the displayed list. [Search terms](../../consume-packages/finding-and-choosing-packages.md#search-syntax) are applied to the names of packages, tags, and package descriptions just as they are when using them on nuget.org. ## Options -| Option | Description | -| --- | --- | -| AllVersions | List all versions of a package. By default, only the latest package version is displayed. | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Help | Displays help information for the command. | -| IncludeDelisted | *(3.2+)* Display unlisted packages. | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| PreRelease | Includes prerelease packages in the list. | -| Source | Specifies a list of packages sources to search. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | +- **`-AllVersions`** + + List all versions of a package. By default, only the latest package version is displayed. + +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-IncludeDelisted`** + + *(3.2+)* Display unlisted packages. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-PreRelease`** + + Includes prerelease packages in the list. + +- **`-Source`** + + The package source to search. You can specify multiple sources by using the `-Source` option multiple times. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. Also see [Environment variables](cli-ref-environment-variables.md) ## Examples -```cli +List all packages from configured feeds: +``` nuget list - -nuget list chinese korean -Verbosity detailed - -nuget list couchbase -AllVersions +``` +List Azure-related packages with detailed verbosity: +``` +nuget list Azure -Verbosity detailed +``` +List all versions of Azure-related packages from configured feeds: +``` +nuget list Azure -AllVersions +``` +List all versions of JSON-related packages from specified source/feed: +``` +nuget list JSON -AllVersions -Source "https://nuget.org/api/v2" +``` +List JSON-related packages from multiple sources/feeds: +``` +nuget list JSON -Source "https://nuget.org/api/v2" -Source "https://other-feed-url-goes-here/" ``` diff --git a/docs/reference/cli-reference/cli-ref-locals.md b/docs/reference/cli-reference/cli-ref-locals.md index 85efb5393..7baac4cea 100644 --- a/docs/reference/cli-reference/cli-ref-locals.md +++ b/docs/reference/cli-reference/cli-ref-locals.md @@ -1,8 +1,8 @@ --- title: NuGet CLI locals command description: Reference for the nuget.exe locals command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 03/19/2018 ms.topic: reference --- @@ -23,15 +23,33 @@ where `` is one of `all`, `http-cache`, `packages-cache` *(3.5 and earli ## Options -| Option | Description | -| --- | --- | -| Clear | Clears the specified folder. | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Help | Displays help information for the command. | -| List | Lists the location of the specified folder, or the locations of all folders when used with *all*. | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | +- **`-Clear`** + + Clears the specified folder. + +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-List`** + + Lists the location of the specified folder, or the locations of all folders when used with *all*. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. Also see [Environment variables](cli-ref-environment-variables.md) diff --git a/docs/reference/cli-reference/cli-ref-long-path.md b/docs/reference/cli-reference/cli-ref-long-path.md index 2d59d2d19..44e9fa572 100644 --- a/docs/reference/cli-reference/cli-ref-long-path.md +++ b/docs/reference/cli-reference/cli-ref-long-path.md @@ -34,6 +34,5 @@ Steps: > Enabling Other NuGet Tools to Support Long Paths > > - Dotnet CLI supports long paths regardless of the operating system or version. -> - Visual Studio or msbuild -t:restore does not yet support long paths. -> - Software that uses NuGet Libraries to execute restore and other commands, will support long paths on the same systems that NuGet.exe works on, if they also set longPathAware in their windows manifest and configure UseLegacyPathHandling to false via App.Config [See more information](https://blogs.msdn.microsoft.com/jeremykuhne/2016/07/30/net-4-6-2-and-long-paths-on-windows-10/) - +> - Visual Studio or `msbuild -t:restore` does not yet support long paths. +> - Software that uses NuGet Libraries to execute restore and other commands, will support long paths on the same systems that NuGet.exe works on, if they also set `longPathAware` in their windows manifest and configure `UseLegacyPathHandling` to `false` via App.Config [See more information](/archive/blogs/jeremykuhne/net-4-6-2-and-long-paths-on-windows-10) \ No newline at end of file diff --git a/docs/reference/cli-reference/cli-ref-mirror.md b/docs/reference/cli-reference/cli-ref-mirror.md index a7148f9a2..c1a186192 100644 --- a/docs/reference/cli-reference/cli-ref-mirror.md +++ b/docs/reference/cli-reference/cli-ref-mirror.md @@ -1,8 +1,8 @@ --- title: NuGet CLI mirror command description: Reference for the nuget.exe mirror command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -30,23 +30,44 @@ If your target repository is on `https://machine/repo` that's running [NuGet.Ser ## Options -| Option | Description | -| --- | --- | -| ApiKey | The API key for the target repository. If not present, the one specified in the config file is used (`%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux)). | -| Help | Displays help information for the command. | -| NoCache | Prevents NuGet from using cached packages. See [Managing the global packages and cache folders](../../consume-packages/managing-the-global-packages-and-cache-folders.md). | -| Noop | Logs what would be done but does not perform the actions; assumes success for push operations. | -| PreRelease | Includes prerelease packages in the mirroring operation. | -| Source | A list of package sources to mirror. If no sources are specified, the ones defined in the config file (see ApiKey above) are used, defaulting to nuget.org if none are specified. | -| Timeout | Specifies the timeout, in seconds, for pushing to a server. The default is 300 seconds (5 minutes). | -| Version | The version of the package to install. If not specified, the latest version is mirrored. | +- **`-ApiKey`** + + The API key for the target repository. If not present, the one specified in the config file is used (`%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux)). + +- **`-Help`** + + Displays help information for the command. + +- **`-NoHttpCache`** + + Prevents NuGet from using http cached packages. See [Managing the global packages and cache folders](../../consume-packages/managing-the-global-packages-and-cache-folders.md). + +- **`-Noop`** + + Logs what would be done but does not perform the actions; assumes success for push operations. + +- **`-PreRelease`** + + Includes prerelease packages in the mirroring operation. + +- **`-Source`** + + A list of package sources to mirror. If no sources are specified, the ones defined in the config file (see ApiKey above) are used, defaulting to nuget.org if none are specified. + +- **`-Timeout`** + + Specifies the timeout, in seconds, for pushing to a server. The default is 300 seconds (5 minutes). + +- **`-Version`** + + The version of the package to install. If not specified, the latest version is mirrored. Also see [Environment variables](cli-ref-environment-variables.md) ## Examples ```cli -nuget mirror packages.config https://MyRepo/nuget https://MyRepo/api/v2/package -source https://nuget.org/api/v2 -apikey myApiKey -nocache +nuget mirror packages.config https://MyRepo/nuget https://MyRepo/api/v2/package -source https://nuget.org/api/v2 -apikey myApiKey -nohttpcache nuget mirror Microsoft.AspNet.Mvc https://MyRepo/nuget https://MyRepo/api/v2/package -version 4.0.20505.0 diff --git a/docs/reference/cli-reference/cli-ref-pack.md b/docs/reference/cli-reference/cli-ref-pack.md index 6cd5bab64..c449c491d 100644 --- a/docs/reference/cli-reference/cli-ref-pack.md +++ b/docs/reference/cli-reference/cli-ref-pack.md @@ -1,8 +1,8 @@ --- title: NuGet CLI pack command description: Reference for the nuget.exe pack command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -14,6 +14,7 @@ ms.topic: reference Creates a NuGet package based on the specified [.nuspec](../nuspec.md) or project file. The `dotnet pack` command (see [dotnet Commands](../dotnet-Commands.md)) and `msbuild -t:pack` (see [MSBuild targets](../msbuild-targets.md)) may be used as alternates. > [!Important] +> Use [`dotnet pack`](../dotnet-Commands.md) or [`msbuild -t:pack`](../msbuild-targets.md) for [PackageReference](../../consume-packages/package-references-in-project-files.md) based projects. Starting with NuGet version 6.5+, the pack command will [error](../errors-and-warnings/NU5049.md) when attempting to pack these project types. Earlier versions would attempt to pack, but the generated package may not be correct. > Under Mono, creating a package from a project file is not supported. You also need to adjust non-local paths in the `.nuspec` file to Unix-style paths, as nuget.exe doesn't convert Windows pathnames itself. ## Usage @@ -25,29 +26,109 @@ nuget pack [options] [-Properties ...] where `` and `` specify the `.nuspec` or project file, respectively. ## Options +- **`-BasePath`** -| Option | Description | -| --- | --- | -| BasePath | Sets the base path of the files defined in the [.nuspec](../nuspec.md) file. | -| Build | Specifies that the project should be built before building the package. | -| Exclude | Specifies one or more wildcard patterns to exclude when creating a package. To specify more than one pattern, repeat the -Exclude flag. See example below. | -| ExcludeEmptyDirectories | Prevents inclusion of empty directories when building the package. | -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| ConfigFile | Specify the configuration file for the pack command. | -| Help | Displays help information for the command. | -| IncludeReferencedProjects | Indicates that the built package should include referenced projects either as dependencies or as part of the package. If a referenced project has a corresponding `.nuspec` file that has the same name as the project, then that referenced project is added as a dependency. Otherwise, the referenced project is added as part of the package. | -| MinClientVersion | Set the *minClientVersion* attribute for the created package. This value will override the value of the existing *minClientVersion* attribute (if any) in the `.nuspec` file. | -| MSBuildPath | *(4.0+)* Specifies the path of MSBuild to use with the command, taking precedence over `-MSBuildVersion`. | -| MSBuildVersion | *(3.2+)* Specifies the version of MSBuild to be used with this command. Supported values are 4, 12, 14, 15.1, 15.3, 15.4, 15.5, 15.6, 15.7, 15.8, 15.9. By default the MSBuild in your path is picked, otherwise it defaults to the highest installed version of MSBuild. | -| NoDefaultExcludes | Prevents default exclusion of NuGet package files and files and folders starting with a dot, such as `.svn` and `.gitignore`. | -| NoPackageAnalysis | Specifies that pack should not run package analysis after building the package. | -| OutputDirectory | Specifies the folder in which the created package is stored. If no folder is specified, the current folder is used. | -| Properties | Should appear last on the command line after other options. Specifies a list of properties that override values in the project file; see [Common MSBuild Project Properties](/visualstudio/msbuild/common-msbuild-project-properties) for property names. The Properties argument here is a list of token=value pairs, separated by semicolons, where each occurrence of `$token$` in the `.nuspec` file will be replaced with the given value. Values can be strings in quotation marks. Note that for the "Configuration" property, the default is "Debug". To change to a Release configuration, use `-Properties Configuration=Release`. | -| Suffix | *(3.4.4+)* Appends a suffix to the internally generated version number, typically used for appending build or other pre-release identifiers. For example, using `-suffix nightly` will create a package with a version number like `1.2.3-nightly`. Suffixes must start with a letter to avoid warnings, errors, and potential incompatibilities with different versions of NuGet and the NuGet Package Manager. | -| Symbols | Specifies that the package contains sources and symbols. When used with a `.nuspec` file, this creates a regular NuGet package file and the corresponding symbols package. By default it creates a [legacy symbol package](../../create-packages/Symbol-Packages.md). The new recommended format for symbol packages is .snupkg. See [Creating symbol packages (.snupkg)](../../create-packages/Symbol-Packages-snupkg.md). | -| Tool | Specifies that the output files of the project should be placed in the `tool` folder. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | -| Version | Overrides the version number from the `.nuspec` file. | + Sets the base path of the files defined in the [.nuspec](../nuspec.md) file. + +- **`-Build`** + + Specifies that the project should be built before building the package. + +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. + +- **`-Exclude`** + + Specifies one or more wildcard patterns to exclude when creating a package. To specify more than one pattern, repeat the -Exclude flag. See example below. + +- **`-ExcludeEmptyDirectories`** + + Prevents inclusion of empty directories when building the package. + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-IncludeReferencedProjects`** + + Indicates that the built package should include referenced projects either as dependencies or as part of the package. If a referenced project has a corresponding `.nuspec` file that has the same name as the project, then that referenced project is added as a dependency. Otherwise, the referenced project is added as part of the package. + +- **`-InstallPackageToOutputPath`** + + Specify if the command should prepare the package output directory to support share as feed. + +- **`-MinClientVersion`** + + Set the *minClientVersion* attribute for the created package. This value will override the value of the existing *minClientVersion* attribute (if any) in the `.nuspec` file. + +- **`-MSBuildPath`** + + *(4.0+)* Specifies the path of MSBuild to use with the command, taking precedence over `-MSBuildVersion`. + +- **`-MSBuildVersion`** + + *(3.2+)* Specifies the version of MSBuild to be used with this command. Supported values are 4, 12, 14, 15.1, 15.3, 15.4, 15.5, 15.6, 15.7, 15.8, 15.9. By default the MSBuild in your path is picked, otherwise it defaults to the highest installed version of MSBuild. + +- **`-NoDefaultExcludes`** + + Prevents default exclusion of NuGet package files and files and folders starting with a dot, such as `.svn` and `.gitignore`. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-NoPackageAnalysis`** + + Specifies that pack should not run package analysis after building the package. + +- **`-OutputDirectory`** + + Specifies the folder in which the created package is stored. If no folder is specified, the current folder is used. + +- **`-OutputFileNamesWithoutVersion`** + + Specify if the command should prepare the package output name without the version. + +- **`-PackagesDirectory`** + + Specifies the packages folder. + +- **`-p|-Properties`** + + Should appear last on the command line after other options. Specifies a list of properties that override values in the project file; see [Common MSBuild Project Properties](/visualstudio/msbuild/common-msbuild-project-properties) for property names. The Properties argument here is a list of token=value pairs, separated by semicolons, where each occurrence of `$token$` in the `.nuspec` file will be replaced with the given value. Values can be strings in quotation marks. Note that for the "Configuration" property, the default is "Debug". To change to a Release configuration, use `-Properties Configuration=Release`. **In general**, Properties should be the same that were used during the corresponding project build, in order to avoid potentially strange behavior. + +- **`-SolutionDirectory`** + + Specifies the solution directory. + +- **`-Suffix`** + + *(3.4.4+)* Appends a suffix to the internally generated version number, typically used for appending build or other pre-release identifiers. For example, using `-suffix nightly` will create a package with a version number like `1.2.3-nightly`. Suffixes must start with a letter to avoid warnings, errors, and potential incompatibilities with different versions of NuGet and the NuGet Package Manager. + +- **`-SymbolPackageFormat`** + + When creating a symbols package, allows to choose between the `snupkg` and `symbols.nupkg` format. + +- **`-Symbols`** + + Specifies that the package contains sources and symbols. When used with a `.nuspec` file, this creates a regular NuGet package file and the corresponding symbols package. By default it creates a [legacy symbol package](../../create-packages/Symbol-Packages.md). The new recommended format for symbol packages is .snupkg. See [Creating symbol packages (.snupkg)](../../create-packages/Symbol-Packages-snupkg.md). + +- **`-Tool`** + + Specifies that the output files of the project should be placed in the `tools` folder within the package. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. + +- **`-Version`** + + Overrides the version number from the `.nuspec` file. Also see [Environment variables](cli-ref-environment-variables.md) @@ -70,6 +151,14 @@ For example, consider the following `packages.config` file in the source project For this project, the package created by `nuget pack` will have a dependency on `jQuery` and `microsoft-web-helpers` but not `netfx-Guard`. +## Suppressing pack warnings + +While it is recommended that you resolve all NuGet warnings during your pack operations, in certain situations suppressing them is warranted. + +You can achieve that in the following way: + +> nuget.exe pack package.nuspec -Properties NoWarn=NU5104 + ## Examples ```cli @@ -95,3 +184,6 @@ nuget pack foo.nuspec -Version 1.0.0 -MinClientVersion 2.5 nuget pack Package.nuspec -exclude "*.exe" -exclude "*.bat" ``` + +> [!Note] +> The `pack` command for SDK-style projects is not supported, use `dotnet pack` or `msbuild -t:pack` to pack this those projects instead. diff --git a/docs/reference/cli-reference/cli-ref-push.md b/docs/reference/cli-reference/cli-ref-push.md index f7a027b7e..cdb3fef24 100644 --- a/docs/reference/cli-reference/cli-ref-push.md +++ b/docs/reference/cli-reference/cli-ref-push.md @@ -1,8 +1,8 @@ --- title: NuGet CLI push command description: Reference for the nuget.exe push command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -28,21 +28,65 @@ where `` identifies the package to push to the server. ## Options -| Option | Description | -| --- | --- | -| ApiKey | The API key for the target repository. If not present, the one specified in the config file is used. | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| DisableBuffering | Disables buffering when pushing to an HTTP(s) server to decrease memory usages. Caution: when this option is used, integrated Windows authentication might not work. | -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Help | Displays help information for the command. | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| NoSymbols | *(3.5+)* If a symbols package exists, it will not be pushed to a symbol server. | -| Source | Specifies the server URL. NuGet identifies a UNC or local folder source and simply copies the file there instead of pushing it using HTTP. Also, starting with NuGet 3.4.2, this is a mandatory parameter unless the `NuGet.Config` file specifies a *DefaultPushSource* value (see [Configuring NuGet behavior](../../consume-packages/configuring-nuget-behavior.md)). | -| SkipDuplicate | *(5.1+)* If a package and version already exists, skip it and continue with the next package in the push, if any. | -| SymbolSource | *(3.5+)* Specifies the symbol server URL; nuget.smbsrc.net is used when pushing to nuget.org | -| SymbolApiKey | *(3.5+)* Specifies the API key for the URL specified in `-SymbolSource`. | -| Timeout | Specifies the timeout, in seconds, for pushing to a server. The default is 300 seconds (5 minutes). | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | +- **`-AllowInsecureConnections`** + Allows pushing to HTTP sources (insecure). For more information, refer to https://aka.ms/nuget-https-everywhere. + +- **`-ApiKey`** + + The API key for the target repository. If not present, the one specified in the config file is used. + +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. + +- **`-DisableBuffering`** + + Disables buffering when pushing to an HTTP(s) server to decrease memory usages. Caution: when this option is used, integrated Windows authentication might not work. + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-NoServiceEndpoint`** + + Does not append `api/v2/packages` to the source URL. + +- **`-NoSymbols`** + + *(3.5+)* If a symbols package exists, it will not be pushed to a symbol server. + +- **`-src|-Source`** + + Specifies the server URL. NuGet identifies a UNC or local folder source and simply copies the file there instead of pushing it using HTTP. Also, starting with NuGet 3.4.2, this is a mandatory parameter unless the `NuGet.Config` file specifies a *DefaultPushSource* value (see [Configuring NuGet behavior](../../consume-packages/configuring-nuget-behavior.md)). + +- **`-SkipDuplicate`** + + *(5.1+)* If a package and version already exists, skip it and continue with the next package in the push, if any. This option is ignored if the package is being pushed to a UNC or local folder source. + +- **`-SymbolSource`** + + Specifies the symbol server URL. + +- **`-SymbolApiKey`** + + *(3.5+)* Specifies the API key for the URL specified in `-SymbolSource`. + +- **`-Timeout`** + + Specifies the timeout, in seconds, for pushing to a server. The default is 300 seconds (5 minutes). + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. + Also see [Environment variables](cli-ref-environment-variables.md) @@ -68,3 +112,5 @@ nuget push foo.nupkg 4003d786-cc37-4004-bfdf-c4f3e8ef9b3a -src https://customsou :: In the example below -SkipDuplicate will skip pushing the package if package "Foo" version "5.0.2" already exists on NuGet.org nuget push Foo.5.0.2.nupkg 4003d786-cc37-4004-bfdf-c4f3e8ef9b3a -src https://api.nuget.org/v3/index.json -SkipDuplicate ``` + +- For pushing to Azure Artifacts, [see Azure Artifacts' push documentation](/azure/devops/artifacts/nuget/publish#publish-packages). diff --git a/docs/reference/cli-reference/cli-ref-restore.md b/docs/reference/cli-reference/cli-ref-restore.md index ae9cbd909..b8c4d556e 100644 --- a/docs/reference/cli-reference/cli-ref-restore.md +++ b/docs/reference/cli-reference/cli-ref-restore.md @@ -1,8 +1,8 @@ --- title: NuGet CLI restore command description: Reference for the nuget.exe restore command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -25,27 +25,101 @@ where `` specifies the location of a solution or a `packages.config ## Options -| Option | Description | -| --- | --- | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| DirectDownload | *(4.0+)* Downloads packages directly without populating caches with any binaries or metadata. | -| DisableParallelProcessing | Disables restoring multiple packages in parallel. | -| FallbackSource | *(3.2+)* A list of package sources to use as fallbacks in case the package isn't found in the primary or default source. Use a semicolon to separate list entries. | -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Help | Displays help information for the command. | -| MSBuildPath | *(4.0+)* Specifies the path of MSBuild to use with the command, taking precedence over `-MSBuildVersion`. | -| MSBuildVersion | *(3.2+)* Specifies the version of MSBuild to be used with this command. Supported values are 4, 12, 14, 15.1, 15.3, 15.4, 15.5, 15.6, 15.7, 15.8, 15.9. By default the MSBuild in your path is picked, otherwise it defaults to the highest installed version of MSBuild. | -| NoCache | Prevents NuGet from using cached packages. See [Managing the global packages and cache folders](../../consume-packages/managing-the-global-packages-and-cache-folders.md). | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| OutputDirectory | Specifies the folder in which packages are installed. If no folder is specified, the current folder is used. Required when restoring with a `packages.config` file unless `PackagesDirectory` or `SolutionDirectory` is used.| -| PackageSaveMode | Specifies the types of files to save after package installation: one of `nuspec`, `nupkg`, or `nuspec;nupkg`. | -| PackagesDirectory | Same as `OutputDirectory`. Required when restoring with a `packages.config` file unless `OutputDirectory` or `SolutionDirectory` is used. | -| Project2ProjectTimeOut | Timeout in seconds for resolving project-to-project references. | -| Recursive | *(4.0+)* Restores all references projects for UWP and .NET Core projects. Does not apply to projects using `packages.config`. | -| RequireConsent | Verifies that restoring packages is enabled before downloading and installing the packages. For details, see [Package Restore](../../consume-packages/package-restore.md). | -| SolutionDirectory | Specifies the solution folder. Not valid when restoring packages for a solution. Required when restoring with a `packages.config` file unless `PackagesDirectory` or `OutputDirectory` is used. | -| Source | Specifies the list of package sources (as URLs) to use for the restore. If omitted, the command uses the sources provided in configuration files, see [Configuring NuGet behavior](../../consume-packages/configuring-nuget-behavior.md). Use a semicolon to separate list entries. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. + +- **`-DirectDownload`** + + *(4.0+)* Downloads packages directly without populating caches with any binaries or metadata. + +- **`-DisableParallelProcessing`** + + Disables restoring multiple packages in parallel. + +- **`-FallbackSource`** + + *(3.2+)* A list of package sources to use as fallbacks in case the package isn't found in the primary or default source. Use a semicolon to separate list entries. + +- **`-Force`** + + In PackageReference based projects, forces all dependencies to be resolved even if the last restore was successful. Specifying this flag is similar to deleting the `project.assets.json` file. This does not bypass the http-cache. + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-ForceEvaluate`** + + Forces restore to reevaluate all dependencies even if a lock file already exists. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-LockFilePath`** + + Output location where project lock file is written. By default, this is `PROJECT_ROOT\packages.lock.json`. + +- **`-LockedMode`** + + Don't allow updating project lock file. + +- **`-MSBuildPath`** + + *(4.0+)* Specifies the path of MSBuild to use with the command, taking precedence over `-MSBuildVersion`. + +- **`-MSBuildVersion`** + + *(3.2+)* Specifies the version of MSBuild to be used with this command. Supported values are 4, 12, 14, 15.1, 15.3, 15.4, 15.5, 15.6, 15.7, 15.8, 15.9. By default the MSBuild in your path is picked, otherwise it defaults to the highest installed version of MSBuild. + +- **`-NoHttpCache`** + + Prevents NuGet from using http cached packages. See [Managing the global packages and cache folders](../../consume-packages/managing-the-global-packages-and-cache-folders.md). + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-OutputDirectory`** + + Specifies the folder in which packages are installed. If no folder is specified, the current folder is used. Required when restoring with a `packages.config` file unless `PackagesDirectory` or `SolutionDirectory` is used. + +- **`-PackageSaveMode`** + + Specifies the types of files to save after package installation: one of `nuspec`, `nupkg`, or `nuspec;nupkg`. + +- **`-PackagesDirectory`** + + Same as `OutputDirectory`. Required when restoring with a `packages.config` file unless `OutputDirectory` or `SolutionDirectory` is used. + +- **`-Project2ProjectTimeOut`** + + Timeout in seconds for resolving project-to-project references. + +- **`-Recursive`** + + *(4.0+)* Restores all references projects for UWP and .NET Core projects. Does not apply to projects using `packages.config`. + +- **`-RequireConsent`** + + Verifies that restoring packages is enabled before downloading and installing the packages. For details, see [Package Restore](../../consume-packages/package-restore.md). + +- **`-SolutionDirectory`** + + Specifies the solution folder. Not valid when restoring packages for a solution. Required when restoring with a `packages.config` file unless `PackagesDirectory` or `OutputDirectory` is used. + +- **`-Source`** + + Specifies the list of package sources (as URLs) to use for the restore. If omitted, the command uses the sources provided in configuration files, see [Configuring NuGet behavior](../../consume-packages/configuring-nuget-behavior.md). Use a semicolon to separate list entries. + +- **`-UseLockFile`** + + Enables project lock file to be generated and used with restore. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. Also see [Environment variables](cli-ref-environment-variables.md) diff --git a/docs/reference/cli-reference/cli-ref-search.md b/docs/reference/cli-reference/cli-ref-search.md new file mode 100644 index 000000000..840a7600f --- /dev/null +++ b/docs/reference/cli-reference/cli-ref-search.md @@ -0,0 +1,63 @@ +--- +title: NuGet CLI search command +description: Reference for the nuget.exe search command +author: JonDouglas +ms.author: jodou +ms.date: 08/17/2020 +ms.topic: reference +--- + +# search command (NuGet CLI) + +**Applies to:** package consumption • **Supported versions:** 5.8+ + +Searches a given source using the query string provided. If no sources are specified, all sources defined in %AppData%\NuGet\NuGet.Config are used. + +## Usage + +```cli +nuget search [search terms] [options] +``` + +where the search terms are applied to the names of packages, tags, and package descriptions just as they are when using them on nuget.org. + +## Options + +| Name | Description | Usage | +| --- | --- | :-: | +| PreRelease | Pre-release packages are not included by default, but can be included by using this argument | -PreRelease | +| Source | Specific package source(s) to search instead of querying the default sources in __nuget.config__ | -Source ``| +| Take | The number of results to return. The default value is 20. | -Take `` | +| Verbosity | The level of detail to display in the output. The default is _normal_. (See the note below) | -Verbosity `` | +| Help | Displays help information for the command | -Help | + +Also see [Environment variables](cli-ref-environment-variables.md) + +> [!NOTE] +> Verbosity Levels: +> * _quiet_ - Package ID, Version +> * _normal_ - Package ID, Version, Downloads, Preview of Description +> * _detailed_ - Package ID, Version, Downloads, Full Description, Other information such as the query URL + +## Examples + +Search for *logging*-related packages from default sources: +``` +nuget search logging +``` +Search for *logging*-related packages with detailed verbosity: +``` +nuget search logging -Verbosity detailed +``` +Search for *logging*-related packages, and only show the top 5 results: +``` +nuget search logging -Take 5 +``` +Search for *JSON*-related packages, including pre-release versions, from specified source/feed: +``` +nuget search JSON -PreRelease -Source "https://api.nuget.org/v3/index.json" +``` +Search for *JSON*-related packages from multiple sources/feeds: +``` +nuget search JSON -Source "https://api.nuget.org/v3/index.json" -Source "https://other-feed-url-goes-here/" +``` diff --git a/docs/reference/cli-reference/cli-ref-setapikey.md b/docs/reference/cli-reference/cli-ref-setapikey.md index 47137d119..a594048e8 100644 --- a/docs/reference/cli-reference/cli-ref-setapikey.md +++ b/docs/reference/cli-reference/cli-ref-setapikey.md @@ -1,17 +1,17 @@ --- title: NuGet CLI setapikey command description: Reference for the nuget.exe setapikey command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- # setapikey command (NuGet CLI) -**Applies to:** package consumption, publishing • **Supported versions:** all +**Applies to:** publishing • **Supported versions:** all -Saves an API key for a given server URL into `NuGet.Config` so that it doesn't need to be entered for subsequent commands. +Saves an API key for a given server URL into `NuGet.Config` so that it doesn't need to be entered for subsequent push commands. ## Usage @@ -19,17 +19,39 @@ Saves an API key for a given server URL into `NuGet.Config` so that it doesn't n nuget setapikey -Source [options] ``` -where `` identifies the server and `` is the key or password to save. If `` is omitted, nuget.org is assumed. +where `` identifies the server and `` is the key to save. If `` is omitted, nuget.org is assumed. + +> [!NOTE] +> API key is not used for authenticating with the private feed. +> Refer to [`nuget sources` command](../cli-reference/cli-ref-sources.md) to manage credentials for authenticating with the source. +> API keys can be obtained from the individual NuGet servers. +> To create and manage APIKeys for nuget.org refer to [acquire-an-api-key](../../nuget-org/scoped-api-keys.md#acquire-an-api-key). ## Options -| Option | Description | -| --- | --- | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Help | Displays help information for the command. | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. See [On Mac/Linux, the user-level config file location varies by tooling.](../../consume-packages/configuring-nuget-behavior.md#on-maclinux-the-user-level-config-file-location-varies-by-tooling). + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-src|-Source`** + + Server URL where the API key is valid. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. Also see [Environment variables](cli-ref-environment-variables.md) diff --git a/docs/reference/cli-reference/cli-ref-sign.md b/docs/reference/cli-reference/cli-ref-sign.md index 332937b0a..e2fda227a 100644 --- a/docs/reference/cli-reference/cli-ref-sign.md +++ b/docs/reference/cli-reference/cli-ref-sign.md @@ -14,7 +14,8 @@ ms.reviewer: rmpablos Signs all the packages matching the first argument with a certificate. The certificate with the private key can be obtained from a file or from a certificate installed in a certificate store by providing a subject name or a thumbprint. -Package signing is not yet supported in .NET Core, under Mono, or on non-Windows platforms. +> [!Note] +> Package signing is not yet supported in .NET Core, under Mono, or on non-Windows platforms. ## Usage @@ -26,29 +27,81 @@ where `` is one or more `.nupkg` files. ## Options -| Option | Description | -| --- | --- | -| CertificateFingerprint | Specifies the SHA-1 fingerprint of the certificate used to search a local certificate store for the certificate. | -| CertificatePassword | Specifies the certificate password, if needed. If a certificate is password protected but no password is provided, the command will prompt for a password at run time, unless the -NonInteractive option is passed. | -| CertificatePath | Specifies the file path to the certificate to be used in signing the package. | -| CertificateStoreLocation | Specifies the name of the X.509 certificate store use to search for the certificate. Defaults to "CurrentUser", the X.509 certificate store used by the current user. This option should be used when specifying the certificate via -CertificateSubjectName or -CertificateFingerprint options. | -| CertificateStoreName | Specifies the name of the X.509 certificate store to use to search for the certificate. Defaults to "My", the X.509 certificate store for personal certificates. This option should be used when specifying the certificate via -CertificateSubjectName or -CertificateFingerprint options. | -| CertificateSubjectName | Specifies the subject name of the certificate used to search a local certificate store for the certificate. The search is a case-insensitive string comparison using the supplied value, which will find all certificates with the subject name containing that string, regardless of other subject values. The certificate store can be specified by -CertificateStoreName and -CertificateStoreLocation options. | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| ForceEnglishOutput | Forces nuget.exe to run using an invariant, English-based culture. | -| HashAlgorithm | Hash algorithm to be used to sign the package. Defaults to SHA256. | -| Help | Displays help information for the command. | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| OutputDirectory | Specifies the directory where the signed package should be saved. By default the original package is overwritten by the signed package. | -| Overwrite | Switch to indicate if the current signature should be overwritten. By default the command will fail if the package already has a signature. | -| Timestamper | URL to an RFC 3161 timestamping server. | -| TimestampHashAlgorithm | Hash algorithm to be used by the RFC 3161 timestamp server. Defaults to SHA256. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | +- **`-CertificateFingerprint`** + + Specifies the fingerprint to be used to search for the certificate in a local certificate store. + + Starting with NuGet.exe 6.12, this option can be used to specify the SHA-1, SHA-256, SHA-384, or SHA-512 fingerprint of the certificate. + However, a `NU3043` warning is raised when a SHA-1 certificate fingerprint is used because it is no longer considered secure. + In NuGet.exe 7.0 and later versions, the warning is elevated to an error. + Only SHA-2 family fingerprints (SHA-256, SHA-384, and SHA-512) are supported. + + All the previous versions of the NuGet.exe continue to accept only SHA-1 certificate fingerprint. + +- **`-CertificatePassword`** + + Specifies the certificate password, if needed. If a certificate is password protected but no password is provided, the command will prompt for a password at run time, unless the `-NonInteractive` option is passed. + +- **`-CertificatePath`** + + Specifies the file path to the certificate to be used in signing the package. + +- **`-CertificateStoreLocation`** + + Specifies the name of the X.509 certificate store use to search for the certificate. Defaults to "CurrentUser", the X.509 certificate store used by the current user. This option should be used when specifying the certificate via `-CertificateSubjectName` or `-CertificateFingerprint` options. + +- **`-CertificateStoreName`** + + Specifies the name of the X.509 certificate store to use to search for the certificate. Defaults to "My", the X.509 certificate store for personal certificates. This option should be used when specifying the certificate via `-CertificateSubjectName` or `-CertificateFingerprint` options. + +- **`-CertificateSubjectName`** + + Specifies the subject name of the certificate used to search a local certificate store for the certificate. The search is a case-insensitive string comparison using the supplied value, which will find all certificates with the subject name containing that string, regardless of other subject values. The certificate store can be specified by `-CertificateStoreName` and `-CertificateStoreLocation` options. + +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. + +- **`-ForceEnglishOutput`** + + Forces nuget.exe to run using an invariant, English-based culture. + +- **`-HashAlgorithm`** + + Hash algorithm to be used to sign the package. Defaults to SHA256. Possible values are SHA256, SHA384, and SHA512. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-OutputDirectory`** + + Specifies the directory where the signed package should be saved. By default the original package is overwritten by the signed package. + +- **`-Overwrite`** + + Switch to indicate if the current signature should be overwritten. By default the command will fail if the package already has a signature. + +- **`-Timestamper`** + + URL to an RFC 3161 timestamping server. + +- **`-TimestampHashAlgorithm`** + + Hash algorithm to be used by the RFC 3161 timestamp server. Defaults to SHA256. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. ## Examples ```cli -nuget sign MyPackage.nupkg -Timestamper http://timestamp.test +nuget sign MyPackage.nupkg -CertificatePath .\..\certificate.pfx -Timestamper http://timestamp.test -nuget sign .\..\MyPackage.nupkg -Timestamper http://timestamp.test -OutputDirectory .\..\Signed -``` \ No newline at end of file +nuget sign .\..\MyPackage.nupkg -CertificateStoreLocation CurrentUser -CertificateStoreName My -CertificateSubjectName 'subject name' -Timestamper http://timestamp.test -OutputDirectory .\..\Signed +``` diff --git a/docs/reference/cli-reference/cli-ref-sources.md b/docs/reference/cli-reference/cli-ref-sources.md index 0d88f65f9..56935e51b 100644 --- a/docs/reference/cli-reference/cli-ref-sources.md +++ b/docs/reference/cli-reference/cli-ref-sources.md @@ -1,8 +1,8 @@ --- title: NuGet CLI sources command description: Reference for the nuget.exe sources command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -13,6 +13,9 @@ ms.topic: reference Manages the list of sources located in the user scope configuration file or a specified configuration file. The user scope configuration file is located at `%appdata%\NuGet\NuGet.Config` (Windows) and `~/.nuget/NuGet/NuGet.Config` (Mac/Linux). +> [!NOTE] +> Use package sources that you trust. + Note that the source URL for nuget.org is `https://api.nuget.org/v3/index.json`. ## Usage @@ -25,20 +28,71 @@ where `` is one of *List, Add, Remove, Enable, Disable,* or *Update*, ## Options -| Option | Description | -| --- | --- | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Format | Applies to the `list` action and can be `Detailed` (the default) or `Short`. | -| Help | Displays help information for the command. | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| Password | Specifies the password for authenticating with the source. | -| StorePasswordInClearText | Indicates to store the password in unencrypted text instead of the default behavior of storing an encrypted form. | -| UserName | Specifies the user name for authenticating with the source. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | - -> [!Note] -> Make sure to add the sources' password under the same user context as the nuget.exe is later used to access the package source. The password will be stored encrypted in the config file and can only be decrypted in the same user context as it was encrypted. So for example when you use a build server to restore NuGet packages the password must be encrypted with the same Windows user under which the build server task will run. +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. See [On Mac/Linux, the user-level config file location varies by tooling.](../../consume-packages/configuring-nuget-behavior.md#on-maclinux-the-user-level-config-file-location-varies-by-tooling). + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-Format`** + + Applies to the `list` action and can be `Detailed` (the default) or `Short`. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-Name`** + + Name of the source. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-Password`** + + Specifies the password for authenticating with the source. + + > [!NOTE] + > Be aware that encrypted passwords are only supported on Windows. + > Moreover, they can only be decrypted on the same machine and by the same user who originally encrypted them. + +- **`-src|-Source`** + + Path to the package(s) source. + +- **`-StorePasswordInClearText`** + + Indicates to store the password in unencrypted text instead of the default behavior of storing an encrypted form. + + > [!WARNING] + > Storing passwords in clear text is strongly discouraged. + > For more information on managing credentials securely, refer to the [security best practices for consuming packages from private feeds](../../consume-packages/consuming-packages-authenticated-feeds.md#security-best-practices-for-managing-credentials). + +- **`-UserName`** + + Specifies the user name for authenticating with the source. + +- **`-ValidAuthenticationTypes`** + + Comma-separated list of valid authentication types for this source. By default, all authentication types are valid. Example: `basic,negotiate`. + +- **`-ProtocolVersion`** + + The NuGet server protocol version to be used. + See [NuGet.Config's packageSources documentation](../nuget-config-file.md#packagesources) for more information. + + Available in NuGet command line from version 6.8. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. + +- **`-AllowInsecureConnections`** + Allows HTTP connections for adding or updating packages. Note: This method is not secure. Available starting version 6.12. Also see [Environment variables](cli-ref-environment-variables.md) @@ -52,4 +106,8 @@ nuget sources Disable -Name "MyServer" nuget sources Enable -Name "nuget.org" nuget sources add -name foo.bar -source C:\NuGet\local -username foo -password bar -StorePasswordInClearText -configfile %AppData%\NuGet\my.config + +nuget sources add -name MyAzureDevOpsSource -source "https://pkgs.dev.azure.com/yourorgname/yourprojectname/_packaging/yourfeedname/nuget/v3/index.json" -username ignored -password + +nuget sources Update -Name "nuget.org" -ProtocolVersion 3 ``` diff --git a/docs/reference/cli-reference/cli-ref-spec.md b/docs/reference/cli-reference/cli-ref-spec.md index caacb05f1..e519b278b 100644 --- a/docs/reference/cli-reference/cli-ref-spec.md +++ b/docs/reference/cli-reference/cli-ref-spec.md @@ -1,8 +1,8 @@ --- title: NuGet CLI spec command description: Reference for the nuget.exe spec command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/18/2018 ms.topic: reference --- @@ -11,7 +11,7 @@ ms.topic: reference **Applies to:** package creation • **Supported versions:** all -Generates a `.nuspec` file for a new package. If run in the same folder as a project file (`.csproj`, `.vbproj`, `.fsproj`), `spec` creates a tokenized `.nuspec` file. For additional information, see [Creating a Package](../../create-packages/creating-a-package.md). +Generates a `.nuspec` file for a new package. If run in the same folder as a project file (`.csproj`, `.vbproj`, `.fsproj`), `spec` creates a tokenized `.nuspec` file, that defaults to the MIT License. For additional information, see [Creating a Package](../../create-packages/creating-a-package.md). ## Usage @@ -23,14 +23,30 @@ where `` is an optional package identifier to save in the `.nuspec` f ## Options -| Option | Description | -| --- | --- | -| AssemblyPath | Specifies the path to the assembly to use for metadata. | -| Force | Overwrites any existing `.nuspec` file. | -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Help | Displays help information for the command. | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | +- **`-AssemblyPath`** + + Specifies the path to the assembly to use for metadata. + +- **`-Force`** + + Overwrites any existing `.nuspec` file. + + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. Also see [Environment variables](cli-ref-environment-variables.md) diff --git a/docs/reference/cli-reference/cli-ref-trusted-signers.md b/docs/reference/cli-reference/cli-ref-trusted-signers.md index 8fef48187..20ebfc7f4 100644 --- a/docs/reference/cli-reference/cli-ref-trusted-signers.md +++ b/docs/reference/cli-reference/cli-ref-trusted-signers.md @@ -1,8 +1,8 @@ --- title: NuGet CLI trusted-signers command description: Reference for the nuget.exe trusted-signers command -author: patbel -ms.author: patbel +author: JonDouglas +ms.author: jodou ms.date: 11/12/2018 ms.topic: reference ms.reviewer: rmpablos @@ -37,10 +37,14 @@ Registered trusted signers: Service Index: https://api.nuget.org/v3/index.json Certificate fingerprint(s): SHA256 - 0E5F38F57DC1BCC806D8494F4F90FBCEDD988B46760709CBEEC6F4219AA6157D + SHA256 - 5A2901D6ADA3D18260B9C6DFE2133C95D74B9EEF6AE0E5DC334C8454D1477DF4 + SHA256 - 1F4B311D9ACC115C8DC8018B5A49E00FCE6DA8E2855F9F014CA6F34570BC482D 2. microsoft [author] Certificate fingerprint(s): SHA256 - 3F9001EA83C560D712C24CF213C3D312CB3BFF51EE89435D3430BD06B5D0EECE + SHA256 - AA12DA22A49BCE7D5C1AE64CC1F3D892F150DA76140F210ABD2CBFFCA2C18A27 + SHA256 - 566A31882BE208BE4422F7CFD66ED09F5D4524A5994F50CCC8B05EC0528C1353 3. myUntrustedAuthorSignature [author] Certificate fingerprint(s): @@ -55,17 +59,26 @@ Adds a trusted signer with the given name to the config. This option has differe ## Options for add based on a package ```cli -nuget trusted-signers add -Name [options] +nuget trusted-signers add -Name [options] ``` -where `` is one or more `.nupkg` files. +where `` is one signed `.nupkg` file. -| Option | Description | -| --- | --- | -| Author | Specifies that the author signature of the package(s) should be trusted. | -| Repository | Specifies that the repository signature or countersignature of the package(s) should be trusted. | -| AllowUntrustedRoot | Specifies if the certificate for the trusted signer should be allowed to chain to an untrusted root. | -| Owners | Semi-colon separated list of trusted owners to further restrict the trust of a repository. Only valid when using the `-Repository` option. | +- **`-Author`** + + Specifies that the author signature of the signed package should be trusted. + +- **`-AllowUntrustedRoot`** + + Specifies if the certificate for the trusted signer should be allowed to chain to an untrusted root. + +- **`-Owners`** + + Semi-colon separated list of trusted owners to further restrict the trust of a repository. Only valid when using the `-Repository` option. + +- **`-Repository`** + + Specifies that the repository signature or countersignature of the signed package should be trusted. Providing both `-Author` and `-Repository` at the same time is not supported. @@ -77,11 +90,17 @@ nuget trusted-signers add -Name [options] _Note_: This option will only add trusted repositories. -| Option | Description | -| --- | --- | -| ServiceIndex | Specifies the V3 service index of the repository to be trusted. This repository has to support the repository signatures resource. If not provided, the command will look for a package source with the same `-Name` and get the service index from there. | -| AllowUntrustedRoot | Specifies if the certificate for the trusted signer should be allowed to chain to an untrusted root. | -| Owners | Semi-colon separated list of trusted owners to further restrict the trust of a repository. | +- **`-AllowUntrustedRoot`** + + Specifies if the certificate for the trusted signer should be allowed to chain to an untrusted root. + +- **`-Owners`** + + Semi-colon separated list of trusted owners to further restrict the trust of a repository. + +- **`-ServiceIndex`** + + Specifies the V3 service index of the repository to be trusted. This repository has to support the repository signatures resource. If not provided, the command will look for a package source with the same `-Name` and get the service index from there. ## Options for add based on the certificate information @@ -91,17 +110,24 @@ nuget trusted-signers add -Name [options] _Note_: If a trusted signer with the given name already exists, the certificate item will be added to that signer. Otherwise a trusted author will be created with a certificate item from given certificate information. -| Option | Description | -| --- | --- | -| CertificateFingerprint | Specifies a certificate fingerprints of a certificate which signed packages must be signed with. A certificate fingerprint is a hash of the certificate. The hash algorithm used for calculating this hash should be specifies in the `FingerprintAlgorithm` option. | -| FingerprintAlgorithm | Specifies the hash algorithm used to calculate the certificate fingerprint. Defaults to `SHA256`. Values supported are `SHA256`, `SHA384` and `SHA512` | -| AllowUntrustedRoot | Specifies if the certificate for the trusted signer should be allowed to chain to an untrusted root. | -## nuget trusted-signers remove -Name +- **`-AllowUntrustedRoot`** + + Specifies if the certificate for the trusted signer should be allowed to chain to an untrusted root. + +- **`-CertificateFingerprint`** + + Specifies a certificate fingerprints of a certificate which signed packages must be signed with. A certificate fingerprint is a hash of the certificate. The hash algorithm used for calculating this hash should be specifies in the `FingerprintAlgorithm` option. + +- **`-FingerprintAlgorithm`** + + Specifies the hash algorithm used to calculate the certificate fingerprint. Defaults to `SHA256`. Values supported are `SHA256`, `SHA384` and `SHA512`. + +## nuget trusted-signers remove -Name \ Removes any trusted signers that match the given name. -## nuget trusted-signers sync -Name +## nuget trusted-signers sync -Name \ Requests the latest list of certificates used in a currently trusted repository to update the the existing certificate list in the trusted signer. @@ -109,12 +135,30 @@ _Note_: This gesture will delete the current list of certificates and replace th ## Options -| Option | Description | -| --- | --- | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| ForceEnglishOutput | Forces nuget.exe to run using an invariant, English-based culture. | -| Help | Displays help information for the command. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. See [On Mac/Linux, the user-level config file location varies by tooling.](../../consume-packages/configuring-nuget-behavior.md#on-maclinux-the-user-level-config-file-location-varies-by-tooling). + +- **`-ForceEnglishOutput`** + + Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-Name`** + + Name of the trusted signer. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. + ## Examples @@ -129,7 +173,7 @@ nuget trusted-signers Add -Name author1 -CertificateFingerprint CE40881FF5F0AD3E nuget trusted-signers Add -Repository .\..\MyRepositorySignedPackage.nupkg -Name TrustedRepo -nuget-trusted-signers Remove -Name TrustedRepo +nuget trusted-signers Remove -Name TrustedRepo -nuget-trusted-signers Sync -Name TrustedRepo +nuget trusted-signers Sync -Name TrustedRepo ``` diff --git a/docs/reference/cli-reference/cli-ref-update.md b/docs/reference/cli-reference/cli-ref-update.md index 474d513a3..69238df55 100644 --- a/docs/reference/cli-reference/cli-ref-update.md +++ b/docs/reference/cli-reference/cli-ref-update.md @@ -1,8 +1,8 @@ --- title: NuGet CLI update command description: Reference for the nuget.exe update command -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 12/07/2017 ms.topic: reference --- @@ -29,23 +29,71 @@ where `` identifies either a `packages.config` or solution file that ## Options -| Option | Description | -| --- | --- | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| FileConflictAction | Specifies the action to take when asked to overwrite or ignore existing files referenced by the project. Values are *overwrite, ignore, none*. | -| ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. | -| Help | Displays help information for the command. | -| Id | Specifies a list of package IDs to update. | -| MSBuildPath | *(4.0+)* Specifies the path of MSBuild to use with the command, taking precedence over `-MSBuildVersion`. | -| MSBuildVersion | *(3.2+)* Specifies the version of MSBuild to be used with this command. Supported values are 4, 12, 14, 15.1, 15.3, 15.4, 15.5, 15.6, 15.7, 15.8, 15.9. By default the MSBuild in your path is picked, otherwise it defaults to the highest installed version of MSBuild. | -| NonInteractive | Suppresses prompts for user input or confirmations. | -| PreRelease | Allows updating to prerelease versions. This flag is not required when updating prerelease packages that are already installed. | -| RepositoryPath | Specifies the local folder where packages are installed. | -| Safe | Specifies that only updates with the highest version available within the same major and minor version as the installed package will be installed. | -| Self | Updates nuget.exe to the latest version; all other arguments are ignored. | -| Source | Specifies the list of package sources (as URLs) to use for the updates. If omitted, the command uses the sources provided in configuration files, see [Common NuGet configurations](../../consume-packages/configuring-nuget-behavior.md). | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | -| Version | When used with one package ID, specifies the version of the package to update. | +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. + +- **`-DependencyVersion [Lowest, HighestPatch, HighestMinor, Highest, Ignore]`** + + Specifies the version of the dependency packages to use, which can be one of the following:
    • *Lowest* (default): the lowest version
    • *HighestPatch*: the version with the lowest major, lowest minor, highest patch
    • *HighestMinor*: the version with the lowest major, highest minor, highest patch
    • *Highest*: the highest version
    • *Ignore*: No dependency packages will be used
    + +- **`-FileConflictAction [PromptUser, Overwrite, Ignore]`** + + Specifies the default action when a file from a package already exists in the target project. Set to `Overwrite` to always overwrite files. Set to `Ignore` to skip files. + + The `PromptUser` action, the default, will prompt for each conflicting file unless `OverwriteAll` or `IgnoreAll` is provided, which will apply to all remaining files. + +- **`-ForceEnglishOutput`** + + *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-Id`** + + Specifies a list of package IDs to update. + +- **`-MSBuildPath`** + + *(4.0+)* Specifies the path of MSBuild to use with the command, taking precedence over `-MSBuildVersion`. + +- **`-MSBuildVersion`** + + *(3.2+)* Specifies the version of MSBuild to be used with this command. Supported values are 4, 12, 14, 15.1, 15.3, 15.4, 15.5, 15.6, 15.7, 15.8, 15.9. By default the MSBuild in your path is picked, otherwise it defaults to the highest installed version of MSBuild. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-PreRelease`** + + Allows updating to prerelease versions. This flag is not required when updating prerelease packages that are already installed. + +- **`-RepositoryPath`** + + Specifies the local folder where packages are installed. + +- **`-Safe`** + + Specifies that only updates with the highest version available within the same major and minor version as the installed package will be installed. + +- **`-Self`** + + Updates `nuget.exe` to the latest version. `-Source` can be used however all other arguments are ignored. If no source is provided, checks `nuget.org` for updates regardless of `NuGet.Config` settings. + +- **`-Source`** + + Specifies the list of package sources (as URLs) to use for the updates. If omitted, the command uses the sources provided in configuration files, see [Common NuGet configurations](../../consume-packages/configuring-nuget-behavior.md). + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. + +- **`-Version`** + + When used with one package ID, specifies the version of the package to update. Also see [Environment variables](cli-ref-environment-variables.md) diff --git a/docs/reference/cli-reference/cli-ref-verify.md b/docs/reference/cli-reference/cli-ref-verify.md index 4697454f7..def7a7c90 100644 --- a/docs/reference/cli-reference/cli-ref-verify.md +++ b/docs/reference/cli-reference/cli-ref-verify.md @@ -13,8 +13,9 @@ ms.reviewer: rmpablos **Applies to:** package consumption • **Supported versions:** 4.6+ Verifies a package. +Starting with [NuGet 7.0](../../release-notes/NuGet-7.0.md), the package's content hash will also be displayed. -Verification of signed packages is not yet supported in .NET Core, under Mono, or on non-Windows platforms. +Verification of signed packages is not yet supported under Mono. ## Usage @@ -34,18 +35,31 @@ Specifies that package signature verification should be performed. ## Options for "verify -Signatures" -| Option | Description | -| --- | --- | -| CertificateFingerprint | Specifies one or more SHA-256 certificate fingerprints of certificates(s) which signed packages must be signed with. A certificate SHA-256 fingerprint is a SHA-256 hash of the certificate. Multiple inputs should be semicolon separated. | +- **`-CertificateFingerprint`** + + Specifies one or more SHA-256 certificate fingerprints of certificates(s) which signed packages must be signed with. A certificate SHA-256 fingerprint is a SHA-256 hash of the certificate. Multiple inputs should be semicolon separated. ## Options -| Option | Description | -| --- | --- | -| ConfigFile | The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) is used.| -| ForceEnglishOutput | Forces nuget.exe to run using an invariant, English-based culture. | -| Help | Displays help information for the command. | -| Verbosity | Specifies the amount of detail displayed in the output: *normal*, *quiet*, *detailed*. | +- **`-ConfigFile`** + + The NuGet configuration file to apply. If not specified, `%AppData%\NuGet\NuGet.Config` (Windows), or `~/.nuget/NuGet/NuGet.Config` or `~/.config/NuGet/NuGet.Config` (Mac/Linux) is used. + +- **`-ForceEnglishOutput`** + + Forces nuget.exe to run using an invariant, English-based culture. + +- **`-?|-help`** + + Displays help information for the command. + +- **`-NonInteractive`** + + Suppresses prompts for user input or confirmations. + +- **`-Verbosity [normal|quiet|detailed]`** + + Specifies the amount of detail displayed in the output: `normal` (the default), `quiet`, or `detailed`. ## Examples diff --git a/docs/reference/dotnet-Commands.md b/docs/reference/dotnet-Commands.md index d0cd39df5..945538842 100644 --- a/docs/reference/dotnet-Commands.md +++ b/docs/reference/dotnet-Commands.md @@ -1,10 +1,10 @@ --- title: dotnet CLI NuGet commands description: A short reference for NuGet-related commands using the dotnet command-line interface. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 06/24/2019 -ms.topic: conceptual +ms.topic: article --- # dotnet CLI commands @@ -28,3 +28,4 @@ For the complete command reference on `dotnet` CLI, see [.NET Core command-line - [**dotnet pack**](/dotnet/core/tools/dotnet-pack?tabs=netcore2x): Packs the code into a NuGet package. - [**dotnet nuget push**](/dotnet/core/tools/dotnet-nuget-push): Publishes a package to a NuGet server. Applicable to nuget.org, Azure Artifacts, and [third-party NuGet servers](../hosting-packages/overview.md). - [**dotnet nuget delete**](/dotnet/core/tools/dotnet-nuget-delete): Deletes or unlists a package from a NuGet server. Applicable to nuget.org, Azure Artifacts, and [third-party NuGet servers](../hosting-packages/overview.md). +- [**dotnet nuget verify**](/dotnet/core/tools/dotnet-nuget-verify): Verifies a signed NuGet package. diff --git a/docs/reference/errors-and-warnings/NU1001.md b/docs/reference/errors-and-warnings/NU1001.md index 4b83c50c4..6d93d8643 100644 --- a/docs/reference/errors-and-warnings/NU1001.md +++ b/docs/reference/errors-and-warnings/NU1001.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Error NU1001 -
    The project 'Project' does not specify any target frameworks in 'ProjectFile'
    +> The project 'Project' does not specify any target frameworks in 'ProjectFile' ### Issue The project doesn't contain one or more frameworks. diff --git a/docs/reference/errors-and-warnings/NU1002.md b/docs/reference/errors-and-warnings/NU1002.md index 2b9e538cb..52f618153 100644 --- a/docs/reference/errors-and-warnings/NU1002.md +++ b/docs/reference/errors-and-warnings/NU1002.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Error NU1002 -
    'CLEAR' cannot be used in conjunction with other values
    +> 'CLEAR' cannot be used in conjunction with other values ### Issue Invalid combination of inputs along with a CLEAR keyword. diff --git a/docs/reference/errors-and-warnings/NU1003.md b/docs/reference/errors-and-warnings/NU1003.md index e23fe71e6..1f3802a3b 100644 --- a/docs/reference/errors-and-warnings/NU1003.md +++ b/docs/reference/errors-and-warnings/NU1003.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Error NU1003 -
    PackageTargetFallback and AssetTargetFallback cannot be used together. Remove PackageTargetFallback(deprecated) references from the project environment.
    +> PackageTargetFallback and AssetTargetFallback cannot be used together. Remove PackageTargetFallback(deprecated) references from the project environment. ### Issue `PackageTargetFallback` and `AssetTargetFallback` provide different behavior for selecting assets and cannot be used together. diff --git a/docs/reference/errors-and-warnings/NU1004.md b/docs/reference/errors-and-warnings/NU1004.md new file mode 100644 index 000000000..bf015e828 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1004.md @@ -0,0 +1,47 @@ +--- +title: NuGet Error NU1004 +description: NU1004 error code +author: nkolev92 +ms.author: nikolev +ms.date: 01/02/2022 +ms.topic: reference +f1_keywords: + - "NU1004" +--- + +# NuGet Error NU1004 + +## Scenario 1 + +> The project target frameworks are different than the lock file's target frameworks. Lock file target frameworks: net6.0,net5.0. Project target frameworks net6.0. +The packages lock file is inconsistent with the project dependencies so restore can't be run in locked mode. Disable the RestoreLockedMode MSBuild property or pass an explicit --force-evaluate option to run restore to update the lock file. + +### Issue + +When restore is run in locked mode, it ensures that the project dependencies have not changed since the last restore. +A new framework, `net5.0` has been added to the project. + +### Solution + +Consult the recommendations in the error message and do one of the following: + +- Rerun restore without locked mode to regenerate the lock file. +- Return the project to it's previous state, removing the additional net5.0 framework. + +## Scenario 2 + +> The package reference Contoso.Library version has changed from [2.0.0, ) to [1.2.3, ).The packages lock file is inconsistent with the project dependencies so restore can't be run + in locked mode. Disable the RestoreLockedMode MSBuild property or pass an explicit --force-evaluate option to run restore to update the lock file. + +### Issue + + +When restore is run in locked mode, it ensures that the project dependencies have not changed since the last restore. +Contoso.Library's version has been changed from `2.0.0` to `1.2.3`. + +### Solution + +Consult the recommendations in the error message and do one of the following: + +- Rerun restore without locked mode to regenerate the lock file. +- Return the project to it's previous state, changing the version back to `2.0.0`. diff --git a/docs/reference/errors-and-warnings/NU1005.md b/docs/reference/errors-and-warnings/NU1005.md new file mode 100644 index 000000000..456d2226d --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1005.md @@ -0,0 +1,41 @@ +--- +title: NuGet Error NU1005 +description: NU1005 error code +author: nkolev92 +ms.author: nikolev +ms.date: 01/02/2022 +ms.topic: reference +f1_keywords: + - "NU1005" +--- + +# NuGet Error NU1005 + +## Scenario 1 + +> Invalid restore input where RestorePackagesWithLockFile property is set to false but a packages lock file exists at C:\SourceCode\ContosoProject\Contoso.Library\packages.lock.json + +### Issue + +There are 2 opt-in methods the lock file functionality, by setting the RestorePackagesWithLockFile property, or create a packages.lock.json next to the project file, and they are conflicting. + +### Solution + +- If you wish to continue using the lock file functionality, change RestorePackagesWithLockFile to `true`. +- If you to wish to stop using the lock file functionality, remove the packages.lock.json file. + + +## Scenario 2 + +> RestoreForceEvaluate should not be used with RestoreLockedMode in the same command. + +### Issue + +The commands are contrary to each other. RestoreForceEvaluate forces restore to reevaluate the dependencies generating a new lock file, while RestoreLockedMode prevents updating the lock file. + +### Solution + +Consult the recommendations in the error message and do one of the following: + +- Rerun restore without locked mode to regenerate the lock file. +- Rerun restore without force evaluate to avoid changing the lock file. \ No newline at end of file diff --git a/docs/reference/errors-and-warnings/NU1006.md b/docs/reference/errors-and-warnings/NU1006.md new file mode 100644 index 000000000..747177f2a --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1006.md @@ -0,0 +1,22 @@ +--- +title: NuGet Error NU1006 +description: NU1006 error code +author: nkolev92 +ms.author: nikolev +ms.date: 01/02/2022 +ms.topic: reference +f1_keywords: + - "NU1006" +--- + +# NuGet Error NU1006 + +> NuGet.Config has an invalid package source value 'C:\PackageSource>\'. Reason: Illegal characters in path. + +### Issue + +The configuration file has an invalid package source value. + +### Solution + +Remove the illegal package source value. diff --git a/docs/reference/errors-and-warnings/NU1007.md b/docs/reference/errors-and-warnings/NU1007.md new file mode 100644 index 000000000..907ce6836 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1007.md @@ -0,0 +1,25 @@ +--- +title: NuGet Error NU1007 +description: NU1007 error code +author: nkolev92 +ms.author: nikolev +ms.date: 01/02/2022 +ms.topic: reference +f1_keywords: + - "NU1007" +--- + +# NuGet Error NU1007 + +> The runtime.json specified in the project 'C:\Program Files\dotnet\sdk\X.Y.Z00\RuntimeIdentifierGraph.json +' could not be parsed. + +### Issue + +The runtime.json specified in the project could not be parsed. +This is normally a .NET SDK, or a package issue. + +### Solution + +- If the path in question is from the .NET SDK, file an issue at [dotnet/sdk](https://github.com/dotnet/sdk/issues). +- If the path in question is from a package location, contact the package author. diff --git a/docs/reference/errors-and-warnings/NU1008.md b/docs/reference/errors-and-warnings/NU1008.md new file mode 100644 index 000000000..3be37802d --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1008.md @@ -0,0 +1,59 @@ +--- +title: NuGet Error NU1008 +description: NU1008 error code +author: nkolev92 +ms.author: nikolev +ms.date: 11/07/2022 +ms.topic: reference +f1_keywords: + - "NU1008" +--- + +# NuGet Error NU1008 + +> The following PackageReference items cannot define a value for Version: PackageName. Projects using Central Package Management must define a Version value on a PackageVersion item. + +## Issue + +A project is configured to use NuGet [Central Package Management](../../consume-packages/Central-Package-Management.md) and a `` item is defined which specifies a value for the `Version` attribute: + +```xml + + + +``` + +Alternatively, a `` item is defined with a child `` element that has a value specified: +```xml + + + 5.1.0 + + +``` + +Projects configured to use [Central Package Management](../../consume-packages/Central-Package-Management.md) should not define a version on `` items. +The version should be defined in on a corresponding `` item with the same identifier in [Directory.Packages.props](../../consume-packages/Central-Package-Management.md#enabling-central-package-management) file instead. + +## Solution + +- Remove the `Version` attribute or child `` element from the `` item: + + ```xml + + + + ``` + +- Define a `` item that specifies the version in the [Directory.Packages.props](../../consume-packages/Central-Package-Management.md#enabling-central-package-management) file with the same identifier as the `` item: + + ```xml + + + + ``` + +Alternatively, Central Package Management allows overriding centrally defined package versions. See [Overriding Package Versions](../../consume-packages/Central-Package-Management.md#overriding-package-versions) for more information. + +> [!NOTE] +> Note that metadata such as [IncludeAssets, PrivateAssets etc.](../../consume-packages/Package-References-in-Project-Files.md#controlling-dependency-assets) should remain on the PackageReference item. diff --git a/docs/reference/errors-and-warnings/NU1009.md b/docs/reference/errors-and-warnings/NU1009.md new file mode 100644 index 000000000..5c99ac709 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1009.md @@ -0,0 +1,39 @@ +--- +title: NuGet Error NU1009 +description: NU1009 error code +author: nkolev92 +ms.author: nikolev +ms.date: 11/07/2022 +ms.topic: reference +f1_keywords: + - "NU1009" +--- + +# NuGet Error NU1009 + +> The following PackageReference items are implicitly defined and cannot define a PackageVersion item: PackageName. Projects using Central Package Management require that implicit package versions be specified by the PackageReference item. + +## Issue + +A project is configured to use NuGet [Central Package Management](../../consume-packages/Central-Package-Management.md) and a `` item is defined in the [Directory.Packages.props](../../consume-packages/Central-Package-Management.md#enabling-central-package-management) file for a package that is [implicitly defined](https://aka.ms/sdkimplicitrefs). +Implicitly defined packages are generally declared by an SDK to include packages on your behalf. +For these packages, the owner of the SDK controls the version being used and a user should not define a version with [Central Package Management](../../consume-packages/Central-Package-Management.md). + +```xml + + + +``` + +## Solution + +- Remove the `PackageVersion` item from the [Directory.Packages.props](../../consume-packages/Central-Package-Management.md#enabling-central-package-management) file that corresponds to the implicitly defined package: + + ```xml + + + + ``` + +> [!NOTE] +> Some SDKs allow you to override the implicitly defined package version by setting a specific MSBuild property for that package and the SDK may have documentation on how to do so. diff --git a/docs/reference/errors-and-warnings/NU1010.md b/docs/reference/errors-and-warnings/NU1010.md new file mode 100644 index 000000000..046d4bdfb --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1010.md @@ -0,0 +1,37 @@ +--- +title: NuGet Error NU1010 +description: NU1010 error code +author: nkolev92 +ms.author: nikolev +ms.date: 11/07/2022 +ms.topic: reference +f1_keywords: + - "NU1010" +--- + +# NuGet Error NU1010 + +> The following PackageReference items do not define a corresponding PackageVersion item: PackageName. Projects using Central Package Management must declare PackageReference and PackageVersion items with matching names + +## Issue + +A project is configured to use NuGet [Central Package Management](../../consume-packages/Central-Package-Management.md) and a `` item is defined but a corresponding `` item with the same name is not defined in the [Directory.Packages.props](../../consume-packages/Central-Package-Management.md#enabling-central-package-management) file: + +```xml + + + +``` + +## Solution + +- Define a `` item that specifies the version in the [Directory.Packages.props](../../consume-packages/Central-Package-Management.md#enabling-central-package-management) file with the same identifier as the `` item: + + ```xml + + + + ``` +- If a `` item is properly defined and this error occurs in Visual Studio, check the Error List window for errors related to loading the project or failed [design time builds](https://github.com/dotnet/project-system/blob/main/docs/design-time-builds.md). +If Visual Studio is not able to successfully load the project or a design time build fails, NuGet may log this error because it does not have the required information to restore. +Resolving these underlying issues should fix this error. diff --git a/docs/reference/errors-and-warnings/NU1011.md b/docs/reference/errors-and-warnings/NU1011.md new file mode 100644 index 000000000..c093a2ef8 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1011.md @@ -0,0 +1,51 @@ +--- +title: NuGet Error NU1011 +description: NU1011 error code +author: nkolev92 +ms.author: nikolev +ms.date: 11/07/2022 +ms.topic: reference +f1_keywords: + - "NU1011" +--- + +# NuGet Error NU1011 + +> The following PackageVersion items cannot specify a floating version: PackageName. + +## Issue + +A project is configured to use NuGet [Central Package Management](../../consume-packages/Central-Package-Management.md) and a `` item is defined which specifies a [floating version](../../concepts/Package-Versioning.md#version-ranges) value for the `Version` attribute: + +```xml + + + +``` +By default, `` items cannot specify floating versions. +NuGet's [Central Package Management](../../consume-packages/Central-Package-Management.md) provides users the ability to manage package versions in a single location as well as deterministic and secure restores. +The use of floating versions introduces the possibility for a bad package to be introduced into your build after it has been pushed to a feed. +This can lead to a situation where you made no changes in your repository but suddenly something is broken due to a problem in a new package and there is no way for you to get back into a good state without removing the floating version or pushing a newer version of the package which is fixed. +Using non-floating versions means that every upgrade to a package is backed by a commit in your repository, making it easy to determine what change caused the break and allows you to revert a commit to get back into a good state. + +Also, when using the [transitive pinning](../../consume-packages/Central-Package-Management.md#transitive-pinning) feature of [Central Package Management](../../consume-packages/Central-Package-Management.md), using a floating version as an override could make restores of different projects end up with different versions for the package that what is supposed to be pinned, thus going against the promise of using the centrally defined version. + +NuGet recommends you use automation like [Dependabot](https://docs.github.com/code-security/dependabot/working-with-dependabot) to keep package versions up-to-date which provides +a streamlined way of updating package versions while integrating into your existing developer workflow of a pull request, automated build validation, and testing all backed by a commit in your repository. + +## Solution + +- It is recommended to change the floating version to a [non floating version range](../../concepts/Package-Versioning.md#version-ranges): +```xml + + + +``` + +- If that is not possible, or you wish to use floating versions with Central Package Management, you can do so by setting an MSBuild property: + +```xml + + true + +``` diff --git a/docs/reference/errors-and-warnings/NU1012.md b/docs/reference/errors-and-warnings/NU1012.md new file mode 100644 index 000000000..4d935401d --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1012.md @@ -0,0 +1,55 @@ +--- +title: NuGet Error NU1012 +description: NU1012 error code +author: nkolev92 +ms.author: nikolev +ms.date: 01/02/2022 +ms.topic: reference +f1_keywords: + - "NU1012" +--- + +# NuGet Error NU1012 + +## Scenario 1 + +> Platform version is not present for one or more target frameworks, even though they have specified a platform: net6.0-android. + +### Issue + +You have specified a target framework with a platform in your project file but the platform version is not available. + +### Solution + +- If you are specifying `TargetPlatformVersion` manually, please ensure a version is included. +- If you are using the .NET SDK, and the TargetFramework(s) property contains `net6.0-android`, the .NET SDK is supposed to automatically add a platform version. If you are experiencing this, file an issue at [dotnet/sdk](https://github.com/dotnet/sdk/issues). + +## Scenario 2 + +> Some dependency group TFMs are missing a platform version: net6.0-android + +### Issue + +When creating a package for a framework with a platform such as `android`, you need to specify the correct platform version. + +### Solution + +Specify the platform version in your nuspec. + +Example: `` + +If you are using the pack targets, the platform version will be automatically inferred. + +## Scenario 3 + +Some included files are included under TFMs which are missing a platform version: lib/net6.0-android/Foo.dll, build/net9.0-windows/Foo.props + +### Issue + +Some of the files being packaged according to the NuGet packaging conventions have framework parts that are missing a platform version. + +### Solution + +Specify the platform version in your nuspec or in the pack extensibility targets in your project file. + +Example: `lib/net6.0-android32.0/Foo.dll`, `build/net9.0-windows10.0.19041/Foo.props` diff --git a/docs/reference/errors-and-warnings/NU1013.md b/docs/reference/errors-and-warnings/NU1013.md new file mode 100644 index 000000000..d86b15dd9 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1013.md @@ -0,0 +1,38 @@ +--- +title: NuGet Error NU1013 +description: NU1013 error code +author: jeffkl +ms.author: jeffkl +ms.date: 03/24/2025 +ms.topic: reference +f1_keywords: + - "NU1013" +--- + +# NuGet Error NU1013 + +> The following PackageReference items cannot specify a value for VersionOverride: PackageName. Projects using Central Package Management are currently configured to disable this functionality. + +### Issue + +A project is configured to use NuGet [Central Package Management](../../consume-packages/Central-Package-Management.md) and a `` item is defined which specifies a value for the `VersionOverride` attribute but this functionality has been disabled: + +```xml + + false + + + + +``` + +### Solution +- Remove the `VersionOverride` attribute from the `` item: + +```xml + + + +``` + +- You can configure [Central Package Management](../../consume-packages/Central-Package-Management.md) to allow or disallow `VersionOverride` with the MSBuild property `CentralPackageVersionOverrideEnabled`. See [Overriding Package Versions](../../consume-packages/Central-Package-Management.md#overriding-package-versions) for more information. diff --git a/docs/reference/errors-and-warnings/NU1014.md b/docs/reference/errors-and-warnings/NU1014.md new file mode 100644 index 000000000..f4f601b8d --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1014.md @@ -0,0 +1,33 @@ +--- +title: NuGet Error NU1014 +description: NU1014 error code +author: zivkan +ms.author: zivkan +ms.date: 11/01/2023 +ms.topic: reference +f1_keywords: + - "NU1014" +--- + +# NuGet Error NU1014 + +## Scenario + +> Invalid NuGetAudit value 'sample'. Valid values: true, false. + +> Invalid NuGetAuditLevel value 'sample';. Valid values: low, moderate, high, critical. + +> Invalid NuGetAuditMode value 'sample'. Valid values: direct, all. + +### Issue + +Your project file, or a file it imports (for example `Directory.Build.props`) has defined the MSBuild property shown in the error message (either `NuGetAudit`, `NuGetAuditLevel`, or `NuGetAuditMode`) to an invalid value. + +### Solution + +- Remove the definition of the MSBuild property to use NuGet's default. +- Change the value of the MSBuild property to a value that the error lists as valid. + +For example, if one of your MSBuild files currently has `sample`, either delete the line, or change it to `low`. + +To find where the property is being defined, you can use [MSBuild's `-preprocess` command line argument](/visualstudio/msbuild/msbuild-command-line-reference). Also see [MSBuild's example on the page for customizing the build](/visualstudio/msbuild/customize-by-directory#example). diff --git a/docs/reference/errors-and-warnings/NU1015.md b/docs/reference/errors-and-warnings/NU1015.md new file mode 100644 index 000000000..e109d8636 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1015.md @@ -0,0 +1,34 @@ +--- +title: NuGet Error NU1015 +description: NU1015 error code +author: zivkan +ms.author: zivkan +ms.date: 06/04/2025 +ms.topic: reference +f1_keywords: + - "NU1015" +--- + +# NuGet Error NU1015 + +## Scenario + +> The following PackageReference item(s) do not have a version specified: Contoso.Utilities + +### Issue + +Your project file, or a file it imports (for example `Directory.Build.props`) has defined a `PackageReference` without a version. + +Projects using [Central Package Management (CPM)](../../consume-packages/Central-Package-Management.md) do not define a version on the PackageReference item, so this error could happen if a project has CPM disabled by accident, or if a project or `PackageReference` using CPM is copied into another solution that is not using CPM. + +### Solution + +- Add a version to the package reference + +If you edit your project, a package reference will generally look similar to ``, although [MSBuild allows multiple syntaxes to define item metadata](/visualstudio/msbuild/msbuild-items). +Add the `Version="1.2.3"` item metadata as defined. + +- Check Central Package Management configuration + +This NU1015 error only happens when CPM is disabled. +If Central Package Management (CPM) is intended to be enabled, check your configuration files to investigate why it is disabled. diff --git a/docs/reference/errors-and-warnings/NU1016.md b/docs/reference/errors-and-warnings/NU1016.md new file mode 100644 index 000000000..f8f297de7 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1016.md @@ -0,0 +1,38 @@ +--- +title: NuGet Error NU1016 +description: NU1016 error code +author: donnie-msft +ms.author: eagoodso +ms.date: 01/28/2025 +ms.topic: reference +f1_keywords: + - "NU1016" +--- + +# NuGet Error NU1016 + +> Managing packages with project.json is deprecated. Migrate to PackageReference. + +### Issue + +Managing packages with project.json is deprecated. Migrate to PackageReference. + +### Solution + +[Migrate your project from project.json to PackageReference](../../archive/project-json.md#migrate-projectjson-to-packagereference). + +**Visual Studio 2026 or later:** + +Your project.json project will be automatically migrated to PackageReference when you open the solution. Visual Studio will create a backup of the original files in a `Backup` folder in the project directory. + +**Visual Studio 2022:** + +You need to use the built-in migrator: + +1. Open your project.json project in Visual Studio +1. In Solution Explorer, find the project's Dependencies node +1. Right-click and select **Migrate project.json to PackageReference...** + +For detailed migration guidance, see the [project.json reference documentation](../../archive/project-json.md). + +For more information about package management formats, see [Package references in project files](../../consume-packages/Package-References-in-Project-Files.md). diff --git a/docs/reference/errors-and-warnings/NU1017.md b/docs/reference/errors-and-warnings/NU1017.md new file mode 100644 index 000000000..2e68f8e0b --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1017.md @@ -0,0 +1,51 @@ +--- +title: NuGet Error NU1017 +description: NU1017 error code +author: Nigusu-Allehu +ms.author: Nigusu-Allehu +ms.date: 09/23/2025 +ms.topic: reference +f1_keywords: + - "NU1017" +--- + +# NuGet Error NU1017 + +## Scenario + +> Invalid package id : `contoso../id`. + +### Issue + +The package ID is invalid because it does not match the required format. +NuGet validates package IDs using this regex: + +```regex +^\w+([.-]\w+)*$ +``` + +* The ID must **start with a letter or number**. +* It can only contain **letters, numbers, dots (`.`), and dashes (`-`)**. +* Dots or dashes must be followed by more letters or numbers. +* You can have multiple parts separated by `.` or `-`, like `Contoso.App.Service`. + +### Solution + +To fix this error: + +* Replace or remove any invalid characters from the package ID. Only letters, numbers, dots (`.`), and dashes (`-`) are allowed. +* Ensure the package ID starts with a letter or number. +* Dots (`.`) or dashes (`-`) must always be followed by another letter or number (no consecutive dots/dashes, and none at the end). +* For example, change `contoso../id` to `Contoso.Id`. + +Valid: + +```xml + +``` + +Invalid: + +```xml + +``` diff --git a/docs/reference/errors-and-warnings/NU1100.md b/docs/reference/errors-and-warnings/NU1100.md index 90c50fb34..b24fb6bd4 100644 --- a/docs/reference/errors-and-warnings/NU1100.md +++ b/docs/reference/errors-and-warnings/NU1100.md @@ -1,5 +1,5 @@ --- -title: NuGet Error NU1001 +title: NuGet Error NU1100 description: NU1100 error code author: zhili1208 ms.author: lzhi @@ -12,10 +12,36 @@ f1_keywords: # NuGet Error NU1100 -
    Unable to resolve 'Dependency dll' for 'TargetFramework'
    +## Scenario 1 + +> Unable to resolve 'Dependency (>= 1.0.0)' for 'TargetFramework' ### Issue -A dependency group not be resolved. This is a generic issue for types that are not packages or projects. + +A dependency could not be resolved. This is a generic issue for types that are not packages or projects. + +### Solution 1 + +Open the project file and examine the list of its dependencies. Check that each dependency exists on the package sources you're using, and that the package supports the project's target framework. + +### Solution 2 + +This issue may also be caused by the lack of configured NuGet sources. + +Sometimes a configuration may not specify any sources. You can verify this by running [`dotnet nuget list source`](/dotnet/core/tools/dotnet-nuget-list-source) from the project or solution directory. + +Check the content of the [user configuration](../../consume-packages/configuring-nuget-behavior.md#config-file-locations-and-uses) and add a source there. + +Alternatively, you can create a configuration file using [`dotnet new nugetconfig`](/dotnet/core/tools/dotnet-new). We recommend that you create this file at the repository level. + +## Scenario 2 + +> Unable to resolve 'Dependency (>= 1.0.0)' for 'TargetFramework'. PackageSourceMapping is enabled, the following source(s) were not considered: nuget. + +### Issue + +A dependency could not be resolved. PackageSourceMapping is enabled and there are no matching sources. ### Solution -Open the project file and examine the list of its dependencies. Check that each dependency exists on the package sources you're using, and that the package supports the project's target framework. \ No newline at end of file + +Check your [NuGet.Config](../../consume-packages/Configuring-NuGet-Behavior.md) for the [PackageSourceMapping](../../consume-packages/Package-Source-Mapping.md) configuration and ensure there's a matching pattern for the package in question. diff --git a/docs/reference/errors-and-warnings/NU1101.md b/docs/reference/errors-and-warnings/NU1101.md index d947f205d..d94f69103 100644 --- a/docs/reference/errors-and-warnings/NU1101.md +++ b/docs/reference/errors-and-warnings/NU1101.md @@ -12,10 +12,25 @@ f1_keywords: # NuGet Error NU1101 -
    Unable to find package 'PackageId'. No packages exist with this id in source(s): 'sourceA', 'sourceB', 'sourceC'
    +## Scenario 1 + +> Unable to find package 'PackageId'. No packages exist with this id in source(s): sourceA, sourceB, sourceC ### Issue The package cannot be found on any sources. ### Solution Examine the project's dependencies in Visual Studio to be sure you're using the correct package identifier and version number. Also check that the [NuGet configuration](../../consume-packages/Configuring-NuGet-Behavior.md) identifies the package sources you are expected to be using. If you use packages that have [Semantic Versioning 2.0.0](../../concepts/package-versioning.md#semantic-versioning-200), please make sure that you are using the V3 feed, `https://api.nuget.org/v3/index.json`, in the [NuGet configuration](../../consume-packages/Configuring-NuGet-Behavior.md). + +## Scenario 2 + +> Unable to find package 'PackageId'. No packages exist with this id in source(s): sourceA PackageSourceMapping is enabled, the following source(s) were not considered: sourceB, sourceC. + + +### Issue +The package cannot be found on any of the PackageSourceMapping configured sources. + +### Solution + +Examine the project's dependencies in Visual Studio to be sure you're using the correct package identifier and version number. +Check your [NuGet.Config](../../consume-packages/Configuring-NuGet-Behavior.md) for the [PackageSourceMapping](../../consume-packages/Package-Source-Mapping.md) configuration. The package in question may be available on a source that is not configured. diff --git a/docs/reference/errors-and-warnings/NU1102.md b/docs/reference/errors-and-warnings/NU1102.md index c772fea16..670b3bc97 100644 --- a/docs/reference/errors-and-warnings/NU1102.md +++ b/docs/reference/errors-and-warnings/NU1102.md @@ -1,5 +1,5 @@ --- -title: NuGet Errors and Warnings Reference +title: NuGet Error NU1102 description: NU1102 error code author: zhili1208 ms.author: lzhi @@ -12,10 +12,25 @@ f1_keywords: # NuGet Error NU1102 -
    Unable to find package 'PackageId' with version (>= 9.0.1)
      - Found 30 version(s) in 'sourceA' [ Nearest version: '4.0.0' ]
      - Found 10 version(s) in 'sourceB' [ Nearest version: '4.0.0-rc-2129' ]
      - Found 9 version(s) in 'sourceC' [ Nearest version: '3.0.0-beta-00032' ]
      - Found 0 version(s) in 'sourceD'
      - Found 0 version(s) in 'sourceE'
    +## Scenario 1 + +> Unable to find package 'PackageId' with version (>= 9.0.1)
    - Found 30 version(s) in 'sourceA' [ Nearest version: '4.0.0' ]
    - Found 10 version(s) in 'sourceB' [ Nearest version: '4.0.0-rc-2129' ]
    - Found 9 version(s) in 'sourceC' [ Nearest version: '3.0.0-beta-00032' ]
    - Found 0 version(s) in 'sourceD'
    - Found 0 version(s) in 'sourceE' ### Issue The package identifier is found but a version within the specified dependency range cannot be found on any of the sources. The range might be specified by a package and not the user. ### Solution Edit the project file to correct the package version. Also check that the [NuGet configuration](../../consume-packages/Configuring-NuGet-Behavior.md) identifies the package sources your expect to be using. You may need to change the requested version if this package is referenced by the project directly. + +## Scenario 2 + +> Unable to find package 'PackageId' with version (>= 9.0.1)
    - Found 30 version(s) in 'sourceA' [ Nearest version: '4.0.0' ]
    - Versions from sourceB were not considered + + +### Issue +The package identifier is found but a version within the specified dependency range cannot be found on any of the sources. The range might be specified by a package and not the user. + +### Solution + +Edit the project file to correct the package version. +Check your [NuGet.Config](../../consume-packages/Configuring-NuGet-Behavior.md) for the [PackageSourceMapping](../../consume-packages/Package-Source-Mapping.md) configuration. The package version in question may be available on a source that is not configured. diff --git a/docs/reference/errors-and-warnings/NU1103.md b/docs/reference/errors-and-warnings/NU1103.md index e062285ad..c34bc4864 100644 --- a/docs/reference/errors-and-warnings/NU1103.md +++ b/docs/reference/errors-and-warnings/NU1103.md @@ -12,10 +12,23 @@ f1_keywords: # NuGet Error NU1103 -
    Unable to find a stable package 'PackageId' with version (>= 3.0.0)
      - Found 10 version(s) in 'sourceA' [ Nearest version: '4.0.0-rc-2129' ]
      - Found 9 version(s) in 'sourceB' [ Nearest version: '3.0.0-beta-00032' ]
      - Found 0 version(s) in 'sourceC'
      - Found 0 version(s) in 'sourceD'
    +## Scenario 1 + +> Unable to find a stable package 'PackageId' with version (>= 3.0.0)
    - Found 10 version(s) in 'sourceA' [ Nearest version: '4.0.0-rc-2129' ]
    - Found 9 version(s) in 'sourceB' [ Nearest version: '3.0.0-beta-00032' ]
    - Found 0 version(s) in 'sourceC'
    - Found 0 version(s) in 'sourceD' + +### Issue +The project specified a stable version for the dependency range, but no stable versions were found in that range. Pre-release versions were found but are not allowed. + +### Solution +Edit the version range in the project file to include pre-release versions. See [Package versioning](../../concepts/package-versioning.md). + +## Scenario 2 + +> Unable to find a stable package 'PackageId' with version (>= 3.0.0)
    - Found 10 version(s) in 'sourceA' [ Nearest version: '4.0.0-rc-2129' ]
    - Versions from sourceB were not considered ### Issue The project specified a stable version for the dependency range, but no stable versions were found in that range. Pre-release versions were found but are not allowed. ### Solution -Edit the version range in the project file to include pre-release versions. See [Package versioning](../../concepts/package-versioning.md). \ No newline at end of file +Edit the version range in the project file to include pre-release versions. See [Package versioning](../../concepts/package-versioning.md). +Check your [NuGet.Config](../../consume-packages/Configuring-NuGet-Behavior.md) for the [PackageSourceMapping](../../consume-packages/Package-Source-Mapping.md) configuration. The package version in question may be available on a source that is not configured. diff --git a/docs/reference/errors-and-warnings/NU1104.md b/docs/reference/errors-and-warnings/NU1104.md index 6d5da8854..1ad9f91bf 100644 --- a/docs/reference/errors-and-warnings/NU1104.md +++ b/docs/reference/errors-and-warnings/NU1104.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Error NU1104 -
    Project reference does not exist 'ProjectFile'. Check that the project reference is valid and that the project file exists.
    +> Project reference does not exist 'ProjectFile'. Check that the project reference is valid and that the project file exists. ### Issue A ProjectReference points to a file that doesn't exist. diff --git a/docs/reference/errors-and-warnings/NU1105.md b/docs/reference/errors-and-warnings/NU1105.md index b0e32fa5e..3d6d26856 100644 --- a/docs/reference/errors-and-warnings/NU1105.md +++ b/docs/reference/errors-and-warnings/NU1105.md @@ -12,10 +12,42 @@ f1_keywords: # NuGet Error NU1105 -
    Unable to read project information for 'ProjectFile'. The project file may be invalid or missing targets required for restore.
    +## Scenario 1 + +> Unable to read project information for 'ProjectFile'. The project file may be invalid or missing targets required for restore. + +### Issue +The project file exists but no restore information was provided for it. Ensure you are [opening a project with the new project system or the legacy project system](https://github.com/dotnet/project-system/blob/main/docs/opening-with-new-project-system.md#opening-with-the-new-project-system). + +### Solution + +#### Command line + +From the command line this could mean that the file is corrupt or that the `NuGet.targets` are not imported. +To import the `NuGet.targets`, usually it's recommended to import the `Microsoft.Common.targets`. +To restore projects in solution using [.NET CLI](../../consume-packages/install-use-packages-dotnet-cli.md) use: +```dotnetcli +dotnet restore MySolution.sln +``` +#### Visual Studio + +In Visual Studio the error could mean that targets are not import similar to the command line scenario. + +The error could also mean that the project is unloaded. + +* If you are using Visual Studio 2019 or later, NuGet has the ability to re-use artifacts from the previous restore for unloaded projects. In order for this scenario to work, you need to ensure that all projects currently in the solution have been restored from the command line prior to loading them in Visual Studio. + +* Alternatively, reload the project. + +## Scenario 2 + +> Invalid target framework 'net.6.0' ### Issue -The project file exists but no restore information was provided for it. +The project file exists but specifies an invalid target framework: `'net.6.0'`. +This can occur due to a typo or use of an unsupported format. ### Solution -In Visual Studio, the error could mean that the project is unloaded, in which case reload the project. From the command line this could mean that the file is corrupt or that it doesn't contain the custom "after imports" target needed for restore to read the project. Check that the project file is valid and contains an "after imports" target. \ No newline at end of file + +Update the project file to use a valid target framework. In this case, replace `'net.6.0'` with `'net6.0'` (without the extra dot). +For a full list of supported frameworks and their correct formats, refer to the [.NET Target Frameworks](/dotnet/standard/frameworks) documentation. diff --git a/docs/reference/errors-and-warnings/NU1106.md b/docs/reference/errors-and-warnings/NU1106.md index cc85d27c3..892b43262 100644 --- a/docs/reference/errors-and-warnings/NU1106.md +++ b/docs/reference/errors-and-warnings/NU1106.md @@ -1,5 +1,5 @@ --- -title: NuGet Errors and Warnings Reference +title: NuGet Error NU1106 description: NU1106 error code author: zhili1208 ms.author: lzhi @@ -12,7 +12,7 @@ f1_keywords: # NuGet Error NU1106 -
    Unable to satisfy conflicting requests for 'PackageId': 'Conflict path' Framework: 'Target graph'
    +> Unable to satisfy conflicting requests for 'PackageId': 'Conflict path' Framework: 'Target graph' ### Issue Dependency constraints cannot be resolved. diff --git a/docs/reference/errors-and-warnings/NU1107.md b/docs/reference/errors-and-warnings/NU1107.md index 9888cbd4c..b9f3dbaef 100644 --- a/docs/reference/errors-and-warnings/NU1107.md +++ b/docs/reference/errors-and-warnings/NU1107.md @@ -13,7 +13,7 @@ f1_keywords: # NuGet Error NU1107 -
    Version conflict detected for 'PackageA'. Install/reference 'PackageA' v4.0.0 directly to resolve this issue.
      'PackageB' 3.5.0 -> 'PackageA' (= 3.5.0)
      'PackageC' 4.0.0 -> 'PackageA' (= 4.0.0)
    +> Version conflict detected for 'PackageA'. Install/reference 'PackageA' v4.0.0 directly to resolve this issue.
    'PackageB' 3.5.0 -> 'PackageA' (= 3.5.0)
    'PackageC' 4.0.0 -> 'PackageA' (= 4.0.0) ### Issue Unable to resolve dependency constraints between packages. Two different packages are asking for two different versions of 'PackageA'. The project needs to choose which version of 'PackageA' to use. @@ -29,5 +29,7 @@ To install a specific version, see the information for the tool that you're usin - [nuget.exe CLI](../../consume-packages/install-use-packages-nuget-cli.md#install-a-specific-version-of-a-package) - [Package Manager Console](../ps-reference/ps-ref-install-package.md) +[!INCLUDE [nugetsolver-tool](../../includes/nugetsolver-tool.md)] + ### Note Early versions of Visual Studio 2017 may have reported this as a warning (NU1607). diff --git a/docs/reference/errors-and-warnings/NU1108.md b/docs/reference/errors-and-warnings/NU1108.md index 80cb81a7f..965b6dd63 100644 --- a/docs/reference/errors-and-warnings/NU1108.md +++ b/docs/reference/errors-and-warnings/NU1108.md @@ -1,5 +1,5 @@ --- -title: NuGet Errors and Warnings Reference +title: NuGet Error NU1108 description: NU1108 error code author: zhili1208 ms.author: lzhi @@ -13,7 +13,7 @@ f1_keywords: # NuGet Error NU1108 -
    Cycle detected: A -> B -> A
    +> Cycle detected: A -> B -> A ### Issue A circular dependency was detected. diff --git a/docs/reference/errors-and-warnings/NU1109.md b/docs/reference/errors-and-warnings/NU1109.md new file mode 100644 index 000000000..c9efb8464 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1109.md @@ -0,0 +1,47 @@ +--- +title: NuGet Error NU1109 +description: NU1109 error code +author: nkolev92 +ms.author: nikolev +ms.date: 11/07/2022 +ms.topic: reference +f1_keywords: + - "NU1109" +--- + +# NuGet Error NU1109 + +> NU1109: Detected package downgrade: PackageB from 2.0.0 to centrally defined 1.0.0. Update the centrally managed package version to a higher version.
    +>   'Project' -> 'PackageA' 1.0.0 -> 'PackageB' (>= 2.0.0)
    +>   'Project' -> 'PackageB' (>= 1.0.0) + +## Issue + +A project is configured to use NuGet [Central Package Management](../../consume-packages/Central-Package-Management.md) and a transitive package dependency is pinned to a version lower than is specified by the dependency package. +When resolving packages, NuGet respects the [direct-dependency-wins](../../concepts/dependency-resolution.md#direct-dependency-wins) rule and the pinned package version overrides the version specified by the dependency package which results in a lower version of the package being resolved which could result in issues at runtime. + +```xml + + true + + + + + +``` + +## Solution +- Update the `PackageVersion` of `PackageB` to the higher version of the package. + +```xml + + + +``` + +- Disable Central Package Management transitive pinning to allow the package version specified by the dependency package to be used. +```xml + + false + +``` diff --git a/docs/reference/errors-and-warnings/NU1110.md b/docs/reference/errors-and-warnings/NU1110.md new file mode 100644 index 000000000..1a7c6aa58 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1110.md @@ -0,0 +1,35 @@ +--- +title: NuGet Error NU1110 +description: NU1110 error code +author: donnie-msft +ms.author: eagoodso +ms.date: 10/27/2023 +ms.topic: reference +f1_keywords: + - "NU1110" +--- + +# NuGet Error NU1110 + +> NU1110: The package `B` is available in the Global packages folder, but the source it came from `https://api.nuget.org/v3/index.json` is not one of the configured sources. + +### Issue + +A previous restore retrieved package `B` from a package source which your current solution does not have configured. + +While performing a package installation of package `A`, a dependent package `B` was needed transitively to complete the action. Restore found `B` in your [Global packages folder](../../consume-packages/managing-the-global-packages-and-cache-folders.md)), and the accompanying `nupkg.metadata` indicates a `Source` value which it cannot find in your solution. + +When [package source mapping](../../consume-packages/Package-Source-Mapping.md) is enabled, NuGet attempts to map transitive dependencies automatically by analyzing the source in the Global packages folder. + +### Solution + +#### Option 1. +Create a package source mapping for package `B`. + +#### Option 2. +Clear package `B` from your Global packages folder so that restore can download from one of your configured packages sources. For more information, see [Managing the global packages, cache, and temp folders](../../consume-packages/managing-the-global-packages-and-cache-folders.md). + +If your other solutions have different package sources and package source mapping configurations, this option may not be feasible. + +#### Option 3. +Consider enabling a package source which you know has package `B` available. \ No newline at end of file diff --git a/docs/reference/errors-and-warnings/NU1201.md b/docs/reference/errors-and-warnings/NU1201.md index 6fd890c0b..0a2ad3ddd 100644 --- a/docs/reference/errors-and-warnings/NU1201.md +++ b/docs/reference/errors-and-warnings/NU1201.md @@ -13,7 +13,7 @@ f1_keywords: # NuGet Error NU1201 ### Example 1 -
    Project 'ProjectA' is not compatible with 'TargetFramework'. Project 'ProjectA' supports:
      - 'TargetFrameworkA'
      - 'TargetFrameworkB'
    +> Project 'ProjectA' is not compatible with 'TargetFramework'. Project 'ProjectA' supports:
    - 'TargetFrameworkA'
    - 'TargetFrameworkB' ### Issue A dependency project doesn't contain a framework compatible with the current project. Typically, the project's target framework is a higher version than the consuming project. @@ -22,7 +22,7 @@ A dependency project doesn't contain a framework compatible with the current pro Change the project's target framework to an equal or lower version than the consuming project. ### Example 2 - NetStandard targetted projects cannot reference NetCoreApp targetted projects -
    Project 'ProjectB' is not compatible with netstandard2.0 (.NETStandard,Version=v2.0). Project 'ProjectB' supports: netcoreapp2.0 (.NETCoreApp,Version=v2.0)
    +> Project 'ProjectB' is not compatible with netstandard2.0 (.NETStandard,Version=v2.0). Project 'ProjectB' supports: netcoreapp2.0 (.NETCoreApp,Version=v2.0) ### Issue In this case: diff --git a/docs/reference/errors-and-warnings/NU1202.md b/docs/reference/errors-and-warnings/NU1202.md index 512cc5b50..86e50f8fb 100644 --- a/docs/reference/errors-and-warnings/NU1202.md +++ b/docs/reference/errors-and-warnings/NU1202.md @@ -12,10 +12,12 @@ f1_keywords: # NuGet Error NU1202 -
    Package 'PackageId' 4.0.11 is not compatible with 'TargetFramework'. Package 'PackageId' 4.0.11 supports:
      - 'TargetFrameworkA'
      - 'TargetFrameworkB'
      - 'TargetFrameworkC'
    +> Package 'PackageId' 4.0.11 is not compatible with 'TargetFramework'. Package 'PackageId' 4.0.11 supports:
    - 'TargetFrameworkA'
    - 'TargetFrameworkB'
    - 'TargetFrameworkC' ### Issue A dependency package doesn't contain any assets compatible with the project. ### Solution -Change the project's target framework to one that the package supports. \ No newline at end of file +Change the project's target framework to one that the package supports. + +[!INCLUDE [nugetsolver-tool](../../includes/nugetsolver-tool.md)] \ No newline at end of file diff --git a/docs/reference/errors-and-warnings/NU1203.md b/docs/reference/errors-and-warnings/NU1203.md index cf387a274..3d0e33e26 100644 --- a/docs/reference/errors-and-warnings/NU1203.md +++ b/docs/reference/errors-and-warnings/NU1203.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Error NU1203 -
    'PackageId' 1.0.0 provides a compile-time reference assembly for 'Foo.dll' on 'TargetFramework', but there is no compatible run-time assembly.
    +> 'PackageId' 1.0.0 provides a compile-time reference assembly for 'Foo.dll' on 'TargetFramework', but there is no compatible run-time assembly. ### Issue The package doesn't support the project's `RuntimeIdentifier`. diff --git a/docs/reference/errors-and-warnings/NU1204.md b/docs/reference/errors-and-warnings/NU1204.md new file mode 100644 index 000000000..ef386ec01 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1204.md @@ -0,0 +1,21 @@ +--- +title: NuGet Error NU1204 +description: NU1204 Error code +author: nkolev92 +ms.date: 02/02/2022 +ms.topic: reference +f1_keywords: + - NU1204 +--- + +# NuGet Warning NU1204 + +> Invalid tools package Contoso.Tool 1.0.0. Tools packages cannot contain more than one PackageType. + +### Issue + +The Contoso.Tool package has more than one package type. [DotnetTool](../../create-packages/set-package-type.md#known-package-types packages can only contain one PackageType. + +### Solution + +Consult the with the package author and ask them to [create a package](/dotnet/core/tools/global-tools-how-to-create) with the DotnetTool package type only. diff --git a/docs/reference/errors-and-warnings/NU1211.md b/docs/reference/errors-and-warnings/NU1211.md new file mode 100644 index 000000000..c0cf3e3ea --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1211.md @@ -0,0 +1,22 @@ +--- +title: NuGet Error NU1211 +description: NU1211 Error code +author: nkolev92 +ms.date: 02/02/2022 +ms.topic: reference +f1_keywords: + - NU1211 +--- + +# NuGet Warning NU1211 + +> Project `DotnelToolReferenceProject.csproj` must have a single package reference(s). + +### Issue + +The project you are attempting to restore has special restrictions and exactly 1 PackageReference package must be specified. + +### Solution + +Projects of this style are normally not ordinary projects and the [dotnet tool](/dotnet/core/tools/global-tools) commands should be used to manage your dotnet tools. +Alternatively, change your project to specify exactly 1 package. diff --git a/docs/reference/errors-and-warnings/NU1212.md b/docs/reference/errors-and-warnings/NU1212.md new file mode 100644 index 000000000..5a2d7b395 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1212.md @@ -0,0 +1,40 @@ +--- +title: NuGet Error NU1212 +description: NU1212 Error code +author: nkolev92 +ms.date: 02/02/2022 +ms.topic: reference +f1_keywords: + - NU1212 +--- + +# NuGet Warning NU1212 + +## Scenario 1 + +> Invalid project-package combination for Contoso.Library 1.0.0. DotnetToolReference project style can only contain references of the DotnetTool type + +### Issue + +`DotnetToolReference` project style can only reference .NET tools with the [DotnetTool](../../create-packages/set-package-type.md#known-package-types) package type. Either the project style is not `DotnetToolReference` or a referenced package is not of `DotnetTool` type. + +### Solution + +Projects of this style are normally not ordinary projects and the [dotnet tool](/dotnet/core/tools/global-tools) commands should be used to manage your dotnet tools. +Contoso.Library is not a `DotnetTool` package. +Use a different package that's of the `DotnetTool` type. + +## Scenario 2 + +> Invalid project-package combination for Contoso.Library 1.0.0. DotnetToolReference project style can only contain references of the DotnetTool type + +### Issue + +`DotnetToolReference` project style can only reference .NET tools with the [DotnetTool](../../create-packages/set-package-type.md#known-package-types) package type. Either the project style is not `DotnetToolReference` or a referenced package is not of `DotnetTool` type. + +### Solution + +Projects of this style are normally not ordinary projects and the [dotnet tool](/dotnet/core/tools/global-tools) commands should be used to manage your dotnet tools. + +The project in question is not a DotnetToolReference project, but the package is of the DotnetTool type. +Change the RestoreProjectStyle to DotnetToolReference. diff --git a/docs/reference/errors-and-warnings/NU1213.md b/docs/reference/errors-and-warnings/NU1213.md new file mode 100644 index 000000000..2b2eb288c --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1213.md @@ -0,0 +1,22 @@ +--- +title: NuGet Error NU1213 +description: NU1213 Error code +author: nkolev92 +ms.date: 02/02/2022 +ms.topic: reference +f1_keywords: + - NU1213 +--- + +# NuGet Warning NU1213 + +> The package Contoso.Platform 1.0.0 has a package type DotnetPlatform that is incompatible with this project. + +### Issue + +Certain [package types](../../create-packages/set-package-type.md) cannot be installed into standard projects. + +### Solution + +Packages of certain types cannot be installed into standard projects. +Do not install this package or contact the package author to learn about their motivation. diff --git a/docs/reference/errors-and-warnings/NU1301.md b/docs/reference/errors-and-warnings/NU1301.md new file mode 100644 index 000000000..60aa3e8c5 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1301.md @@ -0,0 +1,23 @@ +--- +title: NuGet Error NU1301 +description: NU1301 Error code +author: nkolev92 +ms.date: 03/31/2022 +ms.topic: reference +f1_keywords: + - NU1301 +--- + +# NuGet Error NU1301 + +> The local source 'C:\Code\Contoso\contosoLocalSource' doesn't exist. + +### Issue + +Restore could not be completed because the listed source is unavailable. + +### Solution + +Consult the error message for more details. You may need to inform the source owner as there might be issues that only they can address. + +Alternatively, you can try removing the source from the configuration retry again. The configured source may not be necessary for your build. diff --git a/docs/reference/errors-and-warnings/NU1302.md b/docs/reference/errors-and-warnings/NU1302.md new file mode 100644 index 000000000..2dd3803d8 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1302.md @@ -0,0 +1,88 @@ +--- +title: NuGet Error NU1302 +description: NU2302 Error code +author: Nigusu-Allehu +ms.date: 07/25/2024 +ms.topic: reference +f1_keywords: + - "NU1302" +--- + +# NuGet Error NU1302 + +## Scenario 1 + +> You are running the 'restore' operation with an 'HTTP' source: myHttpSource. NuGet requires HTTPS sources. To use an HTTP source, you must explicitly set 'allowInsecureConnections' to true in your NuGet.Config file. Please refer to https://aka.ms/nuget-https-everywhere for more information. + +### Issue + +`myHttpSource` is an insecure HTTP source. We recommend using an HTTPS source instead. + +### Solution + +#### Option 1: Update the Source to Use HTTPS + +If possible, update the package source to use `https://` instead of `http://`: + +```xml + + + + + +``` + +#### Option 2: Allow Insecure Connections (If Necessary) + +If the source must remain HTTP, explicitly allow insecure connections by adding the `AllowInsecureConnections` flag in the `NuGet.Config`: + +```xml + + + + + +``` + +#### Option 3: Consult SDK Analysis Level + +The [`SdkAnalysisLevel`](/dotnet/core/project-sdk/msbuild-props#sdkanalysislevel) property in your project can serve as a temporary workaround for managing HTTP sources. +If additional time is needed to resolve the HTTP error, you can lower the `SdkAnalysisLevel` to suppress errors temporarily. +Here's how it functions: + +- For SDK Analysis Level value **below 9.0.100**, using HTTP sources triggers a warning ([NU1803](NU1803.md)). +- Starting with SDK Analysis Level **9.0.100 or higher**, HTTP sources result in an error (NU1302) unless `AllowInsecureConnections` is explicitly enabled. + +> [!WARNING] +> Changing SdkAnalysisLevel has other side-effects. Refer to the [`SdkAnalysisLevel`](/dotnet/core/project-sdk/msbuild-props#sdkanalysislevel) for a summary of the full scope of .NET SDK features affected. + +## Scenario 2 + +> You are using a NuGet source 'https://contoso/v3/index.json' that contains an 'HTTP' service index resource endpoint: 'http://contoso/v3-flatcontainer/contoso/index.json'. This is insecure and not recommended. To allow HTTP resources, you must explicitly set 'allowInsecureConnections' to true in your NuGet.Config file. For more information, visit https://aka.ms/nuget-https-everywhere. + +### Issue + +A configured package source uses **HTTPS**, but one of its resources (indicated in the error message) uses **HTTP**. + +NuGet requires that all sources and their resources use HTTPS. +If you want to continue using this source despite its HTTP resource, you must set the `allowInsecureConnections` flag to true in your NuGet.config file. + +To learn more about package sources and resource endpoints, take a look at the [NuGet Server API](../../api/overview). + +#### Option 1: Update the Source to Use HTTPS + +Whenever possible, switch to a package source that provides only HTTPS resources. This is the recommended and most secure option. + +#### Option 2: Allow Insecure Connections (If Necessary) + +If you must use the source, explicitly allow insecure connections by adding the `allowInsecureConnections` flag in the `NuGet.Config`: + +For information about managing the setting in Visual Studio, see [NuGet Options in Visual Studio](../../consume-packages/nuget-visual-studio-options.md#allow-insecure-connections) + +```xml + + + + + +``` diff --git a/docs/reference/errors-and-warnings/NU1401.md b/docs/reference/errors-and-warnings/NU1401.md index f365872ae..a902b408a 100644 --- a/docs/reference/errors-and-warnings/NU1401.md +++ b/docs/reference/errors-and-warnings/NU1401.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Error NU1401 -
    The 'PackageId' package requires NuGet client version '5.0.0' or above, but the current NuGet version is '4.3.0'.
    +> The 'PackageId' package requires NuGet client version '5.0.0' or above, but the current NuGet version is '4.3.0'. ### Issue The package requires features or frameworks not currently supported by the installed version of NuGet. diff --git a/docs/reference/errors-and-warnings/NU1402.md b/docs/reference/errors-and-warnings/NU1402.md new file mode 100644 index 000000000..b503b03b6 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1402.md @@ -0,0 +1,22 @@ +--- +title: NuGet Error NU1402 +description: NU1402 error code +author: nkolev92 +ms.author: nikolev +ms.date: 11/07/2022 +ms.topic: reference +f1_keywords: + - "NU1402" +--- + +# NuGet Error NU1402 + +> NU1402: The package 'PackageId.1.0.0' contains an entry '../../foo.dll' which is unsafe for extraction. + +### Issue + +The package contains a file that is unsafe for extraction. + +### Solution + +This package is unsafe to be used. Contact the package owner to have the package fixed. diff --git a/docs/reference/errors-and-warnings/NU1403.md b/docs/reference/errors-and-warnings/NU1403.md new file mode 100644 index 000000000..44c5e8e50 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1403.md @@ -0,0 +1,26 @@ +--- +title: NuGet Error NU1403 +description: NU1403 error code +author: nkolev92 +ms.author: nikolev +ms.date: 11/07/2022 +ms.topic: reference +f1_keywords: + - "NU1403" +--- + +# NuGet Error NU1403 + +> Package content hash validation failed for PackageId.13.0.1. The package is different than the last restore. + +### Issue +The content of the package in the global packages folder is different from the value in the lock file. +The package on the source may have changed, or a multiple sources may have different instances of the same package id and version. + +### Solution + +* If you believe that the version you have installed locally is the up to date, correct one, run restore with the [force evaluate](../../consume-packages/Package-References-in-Project-Files.md#lock-file-extensibility) option to update the lock file to the local version of the package. + +* [Inspect the package in the global packages folder](../../concepts/troubleshooting-installed-packages.md#nupkgmetadata-file-in-global-packages-folder) and determine the source from which it was installed. If you own the source in quesiton, you may need to ensure the correct version of the package is available. Once you have figured out which package version you want, run restore with [force evaluate](../../consume-packages/Package-References-in-Project-Files.md#lock-file-extensibility). + +* If none of the above fixes work, the package may have been tampered with before it made it to your machine. diff --git a/docs/reference/errors-and-warnings/NU1501.md b/docs/reference/errors-and-warnings/NU1501.md index e315acc9d..8c87d199e 100644 --- a/docs/reference/errors-and-warnings/NU1501.md +++ b/docs/reference/errors-and-warnings/NU1501.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU1501 -
    The folder 'FolderPath' does not contain a project to restore.
    +> The folder 'FolderPath' does not contain a project to restore. ### Issue diff --git a/docs/reference/errors-and-warnings/NU1502.md b/docs/reference/errors-and-warnings/NU1502.md index ef225d101..a03595763 100644 --- a/docs/reference/errors-and-warnings/NU1502.md +++ b/docs/reference/errors-and-warnings/NU1502.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU1502 -
    Unknown Compatibility Profile: 'aaa'
    +> Unknown Compatibility Profile: 'aaa' ### Issue `RuntimeSupports` contains an invalid profile. Typically, the supports profile was not found in a `runtime.json` file from the current dependency packages. diff --git a/docs/reference/errors-and-warnings/NU1503.md b/docs/reference/errors-and-warnings/NU1503.md index 3e472cd1e..55a969055 100644 --- a/docs/reference/errors-and-warnings/NU1503.md +++ b/docs/reference/errors-and-warnings/NU1503.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU1503 -
    Skipping restore for project 'c:\a.csproj'. The project file may be invalid or missing targets required for restore.
    +> Skipping restore for project 'c:\a.csproj'. The project file may be invalid or missing targets required for restore. ### Issue A dependency project doesn't import NuGet's restore targets. This is similar to NU1105 but here the project is skipped and ignored instead of causing all of restore to fail. In complex solutions there are often other types of projects that may not support restore. diff --git a/docs/reference/errors-and-warnings/NU1504.md b/docs/reference/errors-and-warnings/NU1504.md new file mode 100644 index 000000000..0b1cb88ae --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1504.md @@ -0,0 +1,42 @@ +--- +title: NuGet Warning NU1504 +description: NU1504 warning code +author: nkolev92 +ms.author: nikolev +ms.date: 03/31/2022 +ms.topic: reference +f1_keywords: + - "NU1504" +--- + +# NuGet Warning NU1504 + +## Scenario 1 + +> Duplicate 'PackageReference' items found. Remove the duplicate items or use the Update functionality to ensure a consistent restore behavior. The duplicate 'PackageReference' items are: X 1.0.0, X 2.0.0. + +### Issue + +Sometimes when adding `PackageReference` items, you may end up adding an item for a particular package multiple times. + +Example: + +```xml + + + +... + + + + +``` + +This can cause an inconsistent restore behavior. + +### Solution + +Consult the recommendations in the warning message and do one of the following: + +- Remove the duplicate items +- Use item `Update` instead of item `Include` diff --git a/docs/reference/errors-and-warnings/NU1505.md b/docs/reference/errors-and-warnings/NU1505.md new file mode 100644 index 000000000..d767e2de0 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1505.md @@ -0,0 +1,42 @@ +--- +title: NuGet Warning NU1505 +description: NU1505 warning code +author: nkolev92 +ms.author: nikolev +ms.date: 03/31/2022 +ms.topic: reference +f1_keywords: + - "NU1505" +--- + +# NuGet Warning NU1505 + +## Scenario 1 + +> Duplicate 'PackageDownload' items found. Remove the duplicate items or use the Update functionality to ensure a consistent restore behavior. The duplicate 'PackageDownload' items are: X [1.0.0], X [2.0.0]. + +### Issue + +Sometimes when adding `PackageDownload` items, you may end up adding an item for a particular package multiple times. + +Example: + +```xml + + + +... + + + + +``` + +This can cause an inconsistent restore behavior. + +### Solution + +Consult the recommendations in the warning message and do one of the following: + +- Remove the duplicate items +- Use item `Update` instead of item `Include` diff --git a/docs/reference/errors-and-warnings/NU1506.md b/docs/reference/errors-and-warnings/NU1506.md new file mode 100644 index 000000000..e6fdc0f46 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1506.md @@ -0,0 +1,42 @@ +--- +title: NuGet Warning NU1506 +description: NU1506 warning code +author: nkolev92 +ms.author: nikolev +ms.date: 03/31/2022 +ms.topic: reference +f1_keywords: + - "NU1506" +--- + +# NuGet Warning NU1506 + +## Scenario 1 + +> Duplicate 'PackageVersion' items found. Remove the duplicate items or use the Update functionality to ensure a consistent restore behavior. The duplicate 'PackageVersion' items are: X [1.0.0], X [2.0.0]. + +### Issue + +Sometimes when adding `PackageVersion` items, you may end up adding an item for a particular package multiple times. + +Example: + +```xml + + + +... + + + + +``` + +This can cause an inconsistent restore behavior. + +### Solution + +Consult the recommendations in the warning message and do one of the following: + +- Remove the duplicate items +- Use item `Update` instead of item `Include` diff --git a/docs/reference/errors-and-warnings/NU1507.md b/docs/reference/errors-and-warnings/NU1507.md new file mode 100644 index 000000000..ba2ff2de0 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1507.md @@ -0,0 +1,31 @@ +--- +title: NuGet Warning NU1507 +description: NU1507 warning code +author: jeffkl +ms.author: jeffkl +ms.date: 09/01/2022 +ms.topic: reference +f1_keywords: + - "NU1507" +--- + +# NuGet Warning NU1507 + +> There are 2 package sources defined in your configuration. When using central package management, please map your package sources with package source mapping or specify a single package source. The following sources are defined: https://api.nuget.org/v3/index.json, https://contoso.myget.org/F/development/. + +## Issue + +A project is configured to use NuGet [Central Package Management](../../consume-packages/Central-Package-Management.md) and is not configured to use [Package Source Mapping](../../consume-packages/Package-Source-Mapping.md). +It is highly recommended to enable [Package Source Mapping](../../consume-packages/Package-Source-Mapping.md) because it safeguards your software supply chain when your project is consuming packages from multiple package sources by allowing you specify the source for each package. + +## Solution + +- Onboard to [Package Source Mapping](../../consume-packages/Package-Source-Mapping.md) if you have more than one HTTP-based NuGet package source configured when using Central Package Management. +- If you are unable to onboard to [Package Source Mapping](../../consume-packages/Package-Source-Mapping.md) but want to use Central Package Management, you can suppress the warning: + +```xml + + + $(NoWarn);NU1507 + +``` diff --git a/docs/reference/errors-and-warnings/NU1508.md b/docs/reference/errors-and-warnings/NU1508.md new file mode 100644 index 000000000..eb9f758aa --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1508.md @@ -0,0 +1,26 @@ +--- +title: NuGet Warning NU1508 +description: NU1508 warning code +author: zivkan +ms.author: zivkan +ms.date: 08/10/2024 +ms.topic: reference +f1_keywords: + - "NU1508" +--- + +# NuGet Warning NU1508 + +## Scenario 1 + +> Duplicate 'NuGetAuditSuppress' items found. Remove the duplicate items or use the Update functionality to ensure a consistent restore behavior. The duplicate 'NuGetAuditSuppress' items are: https://contoso.test/cve/1 , https://contoso.test/cve/1 . + +### Issue + +Sometimes when adding `NuGetAuditSuppress` items, you may end up adding an item for a particular package multiple times. + +MSBuild projects commonly import multiple `.props` and `.targets` files, so the duplicates might not be in the same file, but may be in imported files, such as `Directory.Build.props`, `Directory.Packages.props`, or `Directory.Build.targets`. + +### Solution + +Remove the duplicate item, so that it's included exactly once. diff --git a/docs/reference/errors-and-warnings/NU1509.md b/docs/reference/errors-and-warnings/NU1509.md new file mode 100644 index 000000000..cae01fdd4 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1509.md @@ -0,0 +1,28 @@ +--- +title: NuGet Warning NU1509 +description: NU1509 warning code +author: nkolev92 +ms.author: nikolev +ms.date: 02/04/2025 +ms.topic: reference +f1_keywords: + - "NU1509" +--- + +# NuGet Warning NU1509 + +## Scenario 1 + +> Duplicate 'PrunePackageReference' items found. Remove the duplicate items or use the Update functionality to ensure a consistent restore behavior. The duplicate 'PrunePackageReference' items are: X 1.0.0, X 2.0.0. + +### Issue + +Sometimes when adding `PrunePackageReference` items, you may end up adding an item for a particular package multiple times. + +MSBuild projects commonly import multiple `.props` and `.targets` files, so the duplicates might not be in the same file, but may be in imported files, such as `Directory.Build.props`, `Directory.Packages.props`, or `Directory.Build.targets`. + +The `.NET SDK` provides a of list `PrunePackageReference`, so the conflict may be happening because you have specified a `PrunePackageReference` or due to a bug with the `.NET SDK`. + +### Solution + +Remove the duplicate item, so that it's included exactly once. diff --git a/docs/reference/errors-and-warnings/NU1510.md b/docs/reference/errors-and-warnings/NU1510.md new file mode 100644 index 000000000..2b4dbf758 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1510.md @@ -0,0 +1,84 @@ +--- +title: NuGet Warning NU1510 +description: NU1510 warning code +author: nkolev92 +ms.author: nikolev +ms.date: 02/04/2025 +ms.topic: reference +f1_keywords: + - "NU1510" +--- + +# NuGet Warning NU1510 + +## Scenario + +> PackageReference System.Text.Json will not be pruned. Consider removing this package from your dependencies, as it is likely unnecessary. + +### Issue + +The package `System.Text.Json` has been specified for pruning through the [PrunePackageReference](../../consume-packages/Package-References-in-Project-Files.md#prunepackagereference) feature. +The `.NET SDK` generally specifies the list of packages to be pruned. The package is not needed as a direct PackageReference since the .NET runtime itself carries either the same or higher version of the assembly. + +This warning is *only* raised when the PackageReference in question *can be completely removed from the project*. + +#### Example 1 + +```xml + + net10.0 + + + + + +``` + +#### Example 2 + +```xml + + net9.0;net10.0 + + + + + + +``` + +Each conditional `PackageReference` for the `System.Text.Json` package can be removed because the package is already included in the respective .NET runtime versions for the frameworks it is declared for. + +#### Example 3 + +```xml + + net9.0;net10.0 + + + + + +``` + +The `System.Text.Json` package is within the pruning range of the only framework it's declared for. + +### Solution + +Remove the PackageReference as it's unnecessary. + +> [!NOTE] +> In order to allow for easier adoption of the PrunePackageReference feature, this warning is raised by default when a project targets the .NET 10 framework or newer. + +> [!NOTE] +> The warning will not be raised in scenarios in which at least one of the frameworks still needs the package, such as `net48` in the below example. +> +> ```xml +> +> net10.0;net48 +> +> +> +> +> +> ``` diff --git a/docs/reference/errors-and-warnings/NU1511.md b/docs/reference/errors-and-warnings/NU1511.md new file mode 100644 index 000000000..310a69a07 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1511.md @@ -0,0 +1,30 @@ +--- +title: NuGet Warning NU1511 +description: NU1511 warning code +author: nkolev92 +ms.author: nikolev +ms.date: 02/04/2025 +ms.topic: reference +f1_keywords: + - "NU1511" +--- + +# NuGet Warning NU1511 + +## Scenario 1 + +> A ProjectReference cannot be pruned, X. + +### Issue + +The project id `X` has been specified for pruning through the [PrunePackageReference](../../consume-packages/Package-References-in-Project-Files.md#prunepackagereference) feature. +Pruning of projects is not supported. + +### Solution + +- The `.NET SDK` generally specifies the list of packages to be pruned. It may mean that you have a project matching the id of a platform assembly. +In this scenario, change the name of the project. +- If the `PrunePackageReference` has been specified within your project, you may need to remove the `PrunePackageReference` + +> [!NOTE] +> In order to allow for easier adoption of the PrunePackageReference feature, this warning is raised by default when a project targets the .NET 10 framework or newer. diff --git a/docs/reference/errors-and-warnings/NU1601.md b/docs/reference/errors-and-warnings/NU1601.md index 174de7403..76d0d5704 100644 --- a/docs/reference/errors-and-warnings/NU1601.md +++ b/docs/reference/errors-and-warnings/NU1601.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU1601 -
    Dependency specified was 'PackageId' (>= 3.5.0) but ended up with 'PackageId' 4.0.0.
    +> Dependency specified was 'PackageId' (>= 3.5.0) but ended up with 'PackageId' 4.0.0. ### Issue A direct project dependency was bumped to a higher version than the project specified. diff --git a/docs/reference/errors-and-warnings/NU1602.md b/docs/reference/errors-and-warnings/NU1602.md index afcfaa095..e461722ef 100644 --- a/docs/reference/errors-and-warnings/NU1602.md +++ b/docs/reference/errors-and-warnings/NU1602.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU1602 -
    'PackageA' 4.0.0 does not provide an inclusive lower bound for dependency 'PackageB' (> 3.5.0). An approximate best match of 3.6.0 was resolved.
    +> 'PackageA' 4.0.0 does not provide an inclusive lower bound for dependency 'PackageB' (> 3.5.0). An approximate best match of 3.6.0 was resolved. ### Issue A package dependency is missing a lower bound. This doesn't allow restore to find the *best match*. Each restore will float downwards trying to find a lower version that can be used. This means that restore goes online to check all sources each time instead of using the packages that already exist in the user package folder. diff --git a/docs/reference/errors-and-warnings/NU1603.md b/docs/reference/errors-and-warnings/NU1603.md index 2b4e2ba4c..edb6d032f 100644 --- a/docs/reference/errors-and-warnings/NU1603.md +++ b/docs/reference/errors-and-warnings/NU1603.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU1603 -
    'PackageA' 4.0.0 depends on 'PackageB' (>= 4.0.0) but 4.0.0 was not found. An approximate best match of 5.0.0 was resolved.
    +> 'PackageA' 4.0.0 depends on 'PackageB' (>= 4.0.0) but 4.0.0 was not found. An approximate best match of 5.0.0 was resolved. ### Issue diff --git a/docs/reference/errors-and-warnings/NU1604.md b/docs/reference/errors-and-warnings/NU1604.md index 866088b3e..2c132af48 100644 --- a/docs/reference/errors-and-warnings/NU1604.md +++ b/docs/reference/errors-and-warnings/NU1604.md @@ -12,10 +12,71 @@ f1_keywords: # NuGet Warning NU1604 -
    Project dependency 'PackageA' (<= 9.0.0) does not contain an inclusive lower bound. Include a lower bound in the dependency version to ensure consistent restore results.
    +## Missing Package Version + +> Project dependency 'PackageA' does not contain an inclusive lower bound. Include a lower bound in the dependency version to ensure consistent restore results. ### Issue -A project dependency doesn't define a lower bound.

    This means that restore did not find the *best match*. Each restore will float downwards trying to find a lower version that can be used. This means that restore goes online to check all sources each time instead of using the packages that already exist in the user package folder. + +A project dependency doesn't define a version. + +This means that restore used the lowest available version. +Each restore will float downwards trying to find a lower version that can be used. +This means that restore goes online to check all sources each time instead of using the packages that already exist in the user package folder. + +### Solution + +Find the `PackageReference` item that does not define the `Version` attribute and add it: + +For example change from: + +> `` + +to: + +> `` + +If the project is using [NuGet's Central Package Management (CPM)](../../consume-packages/Central-Package-Management.md), you need to update the `` item in `Directory.Packages.props` and change from: + +> `` + +to: +> `` + +If a version is specified in a `` item and you still receive this warning, verify you've correctly [onboarded to central package management](../../consume-packages/Central-Package-Management.md#enabling-central-package-management). + +> [!Note] +> When using CPM and the file `Directory.Packages.props` is invalid, NU1604 is raised. + +## Missing Inclusive Lower Bound + +> Project dependency 'PackageA' (<= 9.0.0) does not contain an inclusive lower bound. Include a lower bound in the dependency version to ensure consistent restore results. + +### Issue +A project dependency doesn't define a lower bound. + +This means that restore did not find the *best match*. Each restore will float downwards trying to find a lower version that can be used. +This means that restore goes online to check all sources each time instead of using the packages that already exist in the user package folder. ### Solution Update the project's `PackageReference` `Version` attribute to include a lower bound. +For example change from: + +> `` + +to: + +> `` + +or + +> `` + +which implies a lower bound. + +If the project is using [NuGet's Central Package Management (CPM)](../../consume-packages/Central-Package-Management.md), you need to update the `` item in `Directory.Packages.props` and change from: + +> `` + +to: +> `` diff --git a/docs/reference/errors-and-warnings/NU1605.md b/docs/reference/errors-and-warnings/NU1605.md index cfdb9764a..d8197d284 100644 --- a/docs/reference/errors-and-warnings/NU1605.md +++ b/docs/reference/errors-and-warnings/NU1605.md @@ -14,33 +14,80 @@ f1_keywords: ## Example 1 -
    Detected package downgrade: 'PackageB' from 4.0.0 to 3.5.0. Reference the package directly from the project to select a different version.
      'PackageA' 3.5.0 -> 'PackageB' 3.5.0
      'PackageC' 4.0.0 -> 'PackageD' 4.0.0 -> 'PackageB' 4.0.0
    +> Detected package downgrade: 'PackageB' from 4.0.0 to 3.5.0. Reference the package directly from the project to select a different version.
    +>     'Project' -> 'PackageA' 4.0.0 -> 'PackageB' (>= 4.0.0)
    +>     'Project' -> 'PackageB' (>= 3.5.0) ### Issue -A dependency package specified a version constraint on a higher version of a package than restore ultimately resolved. That is because of the [nearest-wins](../../concepts/dependency-resolution.md#nearest-wins) rule - when resolving packages, the version of the nearer package in the graph will override that of the distant package with the same ID. + +A dependency package specified a version constraint on a higher version of a package than restore ultimately resolved. That is because of the [direct-dependency-wins](../../concepts/dependency-resolution.md#direct-dependency-wins) rule - when resolving packages, the direct package version in the subgraph will override that of the distant packages with the same ID. ### Solution -To the project exhibiting the restore error, add a package reference to the higher version of the package. -In the example above, you would add a package reference to Package B version 4.0.0: +To the project exhibiting the restore warning, add a package reference to the higher version of the package. -
    -  'PackageA' 3.5.0 -> 'PackageB' 3.5.0
    
-  'PackageC' 4.0.0 -> 'PackageD' 4.0.0 -> 'PackageB' 4.0.0
    
-  'PackageB' 4.0.0
-
    +In the example above, you would change the package reference to `PackageB` 4.0.0: -Since, [nearest-wins](../../concepts/dependency-resolution.md#nearest-wins), the direct package reference to PackageB v4.0.0, will take precedence over the transitive reference to PackageB v3.5.0. +> 'PackageA' 4.0.0 -> 'PackageB' 4.0.0
    +> 'PackageB' 4.0.0 ## Example 2 -
    Detected package downgrade: Microsoft.NETCore.App from 2.1.8 to 2.1.0. Reference the package directly from the project to select a different version.
    
-  test -> mvc -> Microsoft.NETCore.App (>= 2.1.8)
    
-  test -> Microsoft.NETCore.App (>= 2.1.0)
    
-
    +> Detected package downgrade: 'PackageC' from 2.0.0 to 1.1.0. Reference the package directly from the project to select a different version.
    +>     'Project' -> 'PackageA' 1.0.0 -> 'PackageB' 2.0.0 ->'PackageC' (>= 2.0.0)
    +>     'Project' -> 'PackageA' 1.0.0 -> 'PackageC' (>= 1.1.0) ### Issue -The mvc project specified a version constraint on a higher version of a package than restore ultimately resolved. That is because of the [nearest-wins](../../concepts/dependency-resolution.md#nearest-wins) rule - when resolving packages, the version of the nearer package in the graph will override that of the distant package with the same ID. + +A dependency package specified a version constraint on a higher version of a package than restore ultimately resolved. That is because of the [direct-dependency-wins](../../concepts/dependency-resolution.md#direct-dependency-wins) rule - when resolving packages, NuGet tries to honor the intent of the package author. +The author of `PackageA` has explicitly downgraded to `PackageC` 1.1.0 from `PackageC` 2.0.0. ### Solution -This specific error (with Microsoft.NETCore.App package) is improved my moving your .NET Core SDK to 2.2.100 or later. Microsoft.NETCore.App is an auto-referenced package that the .NET Core SDK before version 3.0.100 chooses to bring in automatically. Also see [Self-contained deployment runtime roll forward](/dotnet/core/deploying/runtime-patch-selection). + +To the project exhibiting the restore warning, add a package reference to the higher version of the package. + +In the example above, you would change the package reference to `PackageC` 2.0.0: + +> 'PackageA' 4.0.0 -> 'PackageB' 4.0.0
    +> 'PackageB' 4.0.0 + +## Example 3 + +> Detected package downgrade: System.IO.FileSystem.Primitives from 4.3.0 to 4.0.1. Reference the package directly from the project to select a different version.
    +>     Project -> System.IO.FileSystem 4.0.1 -> runtime.win.System.IO.FileSystem 4.3.0 -> System.IO.FileSystem.Primitives (>= 4.3.0)
    +>     Project -> System.IO.FileSystem 4.0.1 -> System.IO.FileSystem.Primitives (>= 4.0.1)
    + +### Issue + +Certain combinations of packages which shipped with .NET Core 1.0 and 1.1 are not compatible with each other when they are referenced together in a .NET Core 3.0 or higher project, and a RuntimeIdentifier is specified. The problematic packages generally start with `System.` or `Microsoft.`, and have version numbers between 4.0.0 and 4.3.1. In this case, the downgrade message will have a package starting with `runtime.` in the dependency chain. + +### Solution + +To work around this issue, add the following PackageReference: + +```xml + +``` + +You may choose to use the `version` matching the the major version of your SDK. + +## Example 4 + +> Detected package downgrade: Microsoft.NETCore.App from 2.1.8 to 2.1.0. Reference the package directly from the project to select a different version.
    +>     test -> mvc -> Microsoft.NETCore.App (>= 2.1.8)
    +>     test -> Microsoft.NETCore.App (>= 2.1.0) + +### Issue + +The mvc project specified a version constraint on a higher version of a package than restore ultimately resolved. That is because of the [direct-dependency-wins](../../concepts/dependency-resolution.md#direct-dependency-wins) rule - when resolving packages, the version of directly referenced package in the graph will override that of the distant package with the same ID. + +### Solution + +This specific error (with Microsoft.NETCore.App package) is improved by moving your .NET Core SDK to 2.2.100 or later. Microsoft.NETCore.App is an auto-referenced package that the .NET Core SDK before version 3.0.100 chooses to bring in automatically. Also see [Self-contained deployment runtime roll forward](/dotnet/core/deploying/runtime-patch-selection). + +> [!NOTE] +> While NU1605 is considered a warning by the NuGet tooling, the [.NET SDK](/dotnet/core/sdk) opts into treating this warning as an error through `WarningsAsErrors`. +> Your project may be upgrading this warning to an error by setting `TreatWarningsAsErrors` to `true`. +> While not recommended, as you are more likely to encounter runtime issues, you may choose to [suppress](../../consume-packages/Package-References-in-Project-Files.md#suppressing-nuget-warnings) this warning. + +[!INCLUDE [nugetsolver-tool](../../includes/nugetsolver-tool.md)] diff --git a/docs/reference/errors-and-warnings/NU1608.md b/docs/reference/errors-and-warnings/NU1608.md index 888d06a00..4a5590843 100644 --- a/docs/reference/errors-and-warnings/NU1608.md +++ b/docs/reference/errors-and-warnings/NU1608.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU1608 -
    Detected package version outside of dependency constraint: 'PackageA' 1.0.0 requires 'PackageB' (= 1.0.0) but version 'PackageB' 2.0.0 was resolved.
    +> Detected package version outside of dependency constraint: 'PackageA' 1.0.0 requires 'PackageB' (= 1.0.0) but version 'PackageB' 2.0.0 was resolved. ### Issue A resolved package is higher than a dependency constraint allows. This means that a package referenced directly by a project overrides dependency constraints from other packages. diff --git a/docs/reference/errors-and-warnings/NU1701.md b/docs/reference/errors-and-warnings/NU1701.md index 1b8e74965..0fd319446 100644 --- a/docs/reference/errors-and-warnings/NU1701.md +++ b/docs/reference/errors-and-warnings/NU1701.md @@ -1,5 +1,5 @@ --- -title: NuGet Errors and Warnings Reference +title: NuGet Warning NU1701 description: NU1701 warning code author: zhili1208 ms.author: lzhi @@ -12,10 +12,12 @@ f1_keywords: # NuGet Warning NU1701 -
    Package 'packageId' was restored using 'TargetFrameworkA' instead the project target framework 'TargetFrameworkB'. This package may not be fully compatible with your project.
    +> Package 'packageId' was restored using 'TargetFrameworkA' instead the project target framework 'TargetFrameworkB'. This package may not be fully compatible with your project. ### Issue -`PackageTargetFallback` / `AssetTargetFallback` was used to select assets from a package. The warning let users know that the assets may not be 100% compatible. +`AssetTargetFallback` was used to select assets from a package. The warning let users know that the assets may not be 100% compatible. ### Solution -Change the project's target framework to one that the package supports. \ No newline at end of file +Change the project's target framework to one that the package supports. + +[!INCLUDE [nugetsolver-tool](../../includes/nugetsolver-tool.md)] diff --git a/docs/reference/errors-and-warnings/NU1702.md b/docs/reference/errors-and-warnings/NU1702.md new file mode 100644 index 000000000..584570102 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1702.md @@ -0,0 +1,23 @@ +--- +title: NuGet Warning NU1702 +description: NU1702 warning code +author: nkolev92 +ms.date: 07/25/2024 +ms.topic: reference +f1_keywords: + - "NU1702" +--- + +# NuGet Warning NU1702 + +> ProjectReference 'C:\Code\Project2.csproj' was resolved using '.NETFramework,Version=v4.7.2' instead of the project target framework '.NETCoreApp,Version=v5.0'. +> This project may not be fully compatible with your project. + +### Issue + +`AssetTargetFallback` was used to select assets from a package. The warning lets users know that the assets may not be 100% compatible. + +### Solution + +Change the target framework of the projects to make them fully compatible. +Example: Change the target framework of Project2 to `.NET 5`, or change Project2 to target both `.NET 5` and `.NET Framework 4.7.2`. diff --git a/docs/reference/errors-and-warnings/NU1703.md b/docs/reference/errors-and-warnings/NU1703.md new file mode 100644 index 000000000..b1f40d7f0 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1703.md @@ -0,0 +1,23 @@ +--- +title: NuGet Warning NU1703 +description: NU1703 warning code +author: zkat +ms.author: kmarchan +ms.date: 07/01/2021 +ms.topic: reference +ms.reviewer: anangaur +f1_keywords: + - "NU1703" +--- + +# NuGet Warning NU1703 + +> 'packageId' was resolved as a dependency of 'project', but the dependency is using 'Xamarin.iOS' while 'project' is using 'net6.0-maccatalyst14.5' as its TargetFramework + +### Issue + +While `net6.0-maccatalyst` (and higher .NET versions) support using Xamarin.iOS dependencies, this is not guaranteed to be 100% compatible. + +### Solution + +Use a dependency that ships artifacts for `net6.0-maccatalyst` or a higher .NET version instead of relying on legacy Xamarin.iOS. diff --git a/docs/reference/errors-and-warnings/NU1801.md b/docs/reference/errors-and-warnings/NU1801.md index 161119c82..88f1be030 100644 --- a/docs/reference/errors-and-warnings/NU1801.md +++ b/docs/reference/errors-and-warnings/NU1801.md @@ -15,5 +15,7 @@ f1_keywords: ### Issue An error occurred when reading the feed when `IgnoreFailedSources` is set to true, converting it to a non-fatal warning. This could contain any message and is generic. +Note that if `IgnoreFailedSources` is not enabled, [NU1301](./NU1301.md) will be raised instead. + ### Solution -Edit your configuration to specify valid sources. \ No newline at end of file +Edit your configuration to specify valid sources. diff --git a/docs/reference/errors-and-warnings/NU1802.md b/docs/reference/errors-and-warnings/NU1802.md new file mode 100644 index 000000000..7e194460e --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1802.md @@ -0,0 +1,23 @@ +--- +title: NuGet Warning NU1802 +description: NU1802 warning code +author: nkolev92 +ms.author: nikolev +ms.date: 07/22/2022 +ms.topic: reference +f1_keywords: + - "NU1802" +--- + +# NuGet Warning NU1802 + +### Issue + +Updating last access time on file "C:\packages\contoso.library\1.0.0\.nupkg.metadata" failed with _various failure reasons_ + +### Solution + +You have enabled a feature that updates the last access of the .nupkg.metadata file in the NuGet global packages folder. +Failures are likely to be issues with permissions. +The details of the failure reason will be contained in the error message. +Consult that information for the exact action. diff --git a/docs/reference/errors-and-warnings/NU1803.md b/docs/reference/errors-and-warnings/NU1803.md new file mode 100644 index 000000000..a6c68ef29 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1803.md @@ -0,0 +1,36 @@ +--- +title: NuGet Warning NU1803 +description: NU1803 warning code +author: nkolev92 +ms.author: nikolev +ms.date: 07/22/2022 +ms.topic: reference +f1_keywords: + - "NU1803" +--- + +# NuGet Warning NU1803 + +### Issue + +You are running the 'restore' operation with an 'HTTP' source, 'http://api.source/index.json'. Non-HTTPS access will be removed in a future version. Consider migrating to an 'HTTPS' source. + +### Solution + +You may need to do one of the following: + +- Correct the specified url. You may have mistyped the source url. Change the url to explicitly request the `HTTPS` version of the source. +- Work with the owner of the source and ask them to migrate to `HTTPS`. +- If you are absolutely certain the 'HTTP' server you are connecting to is trustworthy, you may opt out of this warning by setting `allowInsecureConnections` to `true` for this package source, in [Package source sections](..\nuget-config-file.md#package-source-sections) of your NuGet.Config file. (Supported in NuGet 6.8+) + +**Example**: + +```xml + + + + + +``` + +To learn more, refer to the [HTTPS everywhere](https://devblogs.microsoft.com/nuget/https-everywhere) blog. diff --git a/docs/reference/errors-and-warnings/NU1900.md b/docs/reference/errors-and-warnings/NU1900.md new file mode 100644 index 000000000..046ba62ce --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1900.md @@ -0,0 +1,47 @@ +--- +title: NuGet Warning NU1900 +description: NU1900 Warning codes +author: zivkan +ms.author: zivkan +ms.date: 6/27/2023 +ms.topic: reference +f1_keywords: + - NU1900 +--- + +# NuGet Warning NU1900 + +## Example 1 + +```text +warning NU1900: Error occurred while getting package vulnerability data: (more information) +``` + +### Issue + +Vulnerability data could not be downloaded from one of the package sources. + +### Solution + +This warning generally means that there is a problem with the package source. + +If the error is related to networking, such as unable to connect to server, a timeout, a DNS error, and so on, then retrying after waiting a few minutes might resolve the issue. +If you use a hosted package source, try checking their server status page to see if there is a known outage. + +If the error is a JSON deserialization error, this suggests the package source returned invalid data to NuGet. +You can try clearing NuGet's HTTP cache (`dotnet nuget locals http-cache --clear` from the command line) and try again. +If issues persist, then contact the package source administrators. + +For more information, see [the documentation on auditing packages](../../concepts/Auditing-Packages.md). + +## Example 2 + +```text +warning NU1900: Package 'Contoso.Utilities' 1.0.0 has a known unknown severity vulnerability, https://cve.contoso.com/advisories/1 +``` + +### Issue + +The server provided vulnerability data for the package, but provided an invalid severity value. +If you know which package source provided the invalid data, you can contact the server administrators to inform them that their vulnerability data does not comply with [NuGet's server API](../../api/vulnerability-info.md). +Once packages have been restored into your global packages folder, you can comment out all but one package source in your `nuget.config` file, and re-run restore until you find which package source is providing the invalid data. diff --git a/docs/reference/errors-and-warnings/NU1901-NU1904.md b/docs/reference/errors-and-warnings/NU1901-NU1904.md new file mode 100644 index 000000000..4fb538434 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1901-NU1904.md @@ -0,0 +1,57 @@ +--- +title: NuGet Warnings NU1901, NU1902, NU1903, NU1904 +description: NU1901, NU1902, NU1903, NU1904 Warning codes +author: zivkan +ms.author: zivkan +ms.date: 7/19/2024 +ms.topic: reference +f1_keywords: + - NU1901 + - NU1902 + - NU1903 + - NU1904 +--- + +# NuGet Warnings NU1901, NU1902, NU1903, NU1904 + +> warning NU1902: Package 'NuGet.Protocol' 5.11.2 has a known moderate severity vulnerability, https://github.com/advisories/GHSA-g3q9-xf95-8hp5 + +The warning code changes depending on the known vulnerability severity level: + +|Warning Code|Severity| +|--|--| +|NU1901|low| +|NU1902|moderate| +|NU1903|high| +|NU1904|critical| + +### Issue + +A package restored for your project has a known vulnerability. + +For more information, see [the documentation on auditing packages](../../concepts/Auditing-Packages.md). + +### Solution + +We have [documentation on upgrading vulnerable packages](../../concepts/Auditing-Packages.md#actions-when-packages-with-known-vulnerabilities-are-reported) that goes in more detail about our recommended actions when your project uses a package with a known vulnerability, and tools that can help. + +Upgrading to a newer version of the package is likely to resolve the warning. +If your project does not reference the package directly (it's a transitive package), [`dotnet nuget why`](/dotnet/core/tools/dotnet-nuget-why) can be used to understand which package caused it to be included in your project. +You can check the URL provided by the vulnerability advisory to see what versions of the package have been fixed, or check your configured package source(s) to see what versions of the package are available. +Visual Studio's package manager UI can show which package versions are affected and which do not have known vulnerabilities. + +If these warnings are causing restore to fail because you are using `TreatWarningsAsErrors`, you can add `NU1901;NU1902;NU1903;NU1904` to allow these codes to remain as warnings. + +If you do not wish to be notified of vulnerabilities that are less severe than a level you are comfortable with, you can edit the project file and add an MSBuild property `NuGetAuditLevel`, with value set to `low`, `moderate`, `high`, or `critical`. +For example, `high`. + +If you would like to suppress a specific advisory, add an MSBuild [NuGetAuditSuppress](../../concepts/Auditing-Packages.md#excluding-advisories) item. +For example ``. +`NuGetAuditSuppress` is available from [VS 17.11 and .NET 8.0.400 SDK](../../release-notes/NuGet-6.11.md) for projects using `PackageReference`, and from [VS 17.12](../../release-notes/NuGet-6.12.md) for projects using `packages.config`. + +If you do not want NuGet to check for packages with known vulnerabilities during restore, add `false` inside a `` in your project file, or a [`Directory.Build.props` file](/visualstudio/msbuild/customize-by-directory). +If you would like to run NuGet Audit on developer machines, but disable it on CI pipelines, you can take advantage of MSBuild importing environment variables, and create a NuGetAudit environment variable set to `false` in your pipeline definition. + +For projects targeting the .NET 10 framework, the default setting for `NuGetAuditMode` is `all`. +This means that NuGet will report on transitive packages with known vulnerabilities for all frameworks in the project. +The value can be explicitly set to `direct` to revert back to .NET 9's default. diff --git a/docs/reference/errors-and-warnings/NU1905.md b/docs/reference/errors-and-warnings/NU1905.md new file mode 100644 index 000000000..9cc76f41d --- /dev/null +++ b/docs/reference/errors-and-warnings/NU1905.md @@ -0,0 +1,31 @@ +--- +title: NuGet Warning NU1905 +description: NU1905 Warning codes +author: zivkan +ms.author: zivkan +ms.date: 07/19/2024 +ms.topic: reference +f1_keywords: + - NU1905 +--- + +# NuGet Warning NU1905 + +```text +warning NU1905: Audit source 'Contoso' did not provide any vulnerability data. +``` + +### Issue + +A source specified in a [NuGet.Config `` element](../nuget-config-file.md#auditsources) did not provide a vulnerability database. + +### Solution + +Any NuGet source implementing [NuGet's V3 server API can provide vulnerability data via the `VulnerabilityInfo` resource](../../api/vulnerability-info.md), including by mirroring nuget.org's vulnerability data. +Any source defined in a NuGet.Config `` element is expected to provide this resource, and this warning is raised when it is not. +You can check if your package source administrators have a setting to enable vulnerability data. + +If you would like to treat this warning as an error, to cause build failures when vulnerability checks could not be performed, you can add `$(WarningAsError);NU1905` to your project file. +If you are using `TreatWarningsAsErrors` to cause all warnings to be treated as errors, you can add `$(NoWarn);NU1905` to your project file to suppress this warning message, or `NU1905` to prevent this warning from being treated as an error. + +For more information, see [the documentation on auditing packages](../../concepts/Auditing-Packages.md). diff --git a/docs/reference/errors-and-warnings/NU3000.md b/docs/reference/errors-and-warnings/NU3000.md index d3c68799e..d4419ce9d 100644 --- a/docs/reference/errors-and-warnings/NU3000.md +++ b/docs/reference/errors-and-warnings/NU3000.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3000 description: NU3000 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -17,7 +17,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature does not have a timestamp.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature does not have a timestamp. ### Issue @@ -32,7 +32,7 @@ To enable long-term signature validity after the signature certificate has expir ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': Multiple timestamps are not accepted.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': Multiple timestamps are not accepted. ### Issue @@ -47,7 +47,7 @@ Please ensure that each package signature contains no more than 1 timestamp. ## Scenario 3 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The repository countersignature does not have a timestamp.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The repository countersignature does not have a timestamp. ### Issue diff --git a/docs/reference/errors-and-warnings/NU3001.md b/docs/reference/errors-and-warnings/NU3001.md index 1637bbb48..69f27b47c 100644 --- a/docs/reference/errors-and-warnings/NU3001.md +++ b/docs/reference/errors-and-warnings/NU3001.md @@ -2,7 +2,7 @@ title: NuGet Error NU3001 description: NU3001 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,37 +14,31 @@ f1_keywords: ## Scenario 1 -
    Invalid password was provided for the certificate file 'certificate.pfx'. Please provide a valid password using the '-CertificatePassword' option.
    +> Invalid password was provided for the certificate file 'certificate.pfx'. Provide a valid password using the '-CertificatePassword' option. ### Issue A password protected certificate file was provided to the NuGet Sign operation. But an invalid or no password was provided. - ### Solution If you are using a password protected certificate file to sign a NuGet package, then please use the `-CertificatePassword` option to pass the correct password. - - ## Scenario 2 -
    Certificate file 'certificate.pfx' not found. For a list of accepted ways to provide a certificate, please visit https://docs.nuget.org/docs/reference/command-line-reference.
    +> Certificate file 'certificate.pfx' not found. For a list of accepted ways to provide a certificate, visit https://docs.nuget.org/docs/reference/command-line-reference. ### Issue A certificate file was provided to the NuGet Sign operation. But the file does not exist on disk. - ### Solution Please ensure that any certificate file being used to sign a NuGet package exists on disk. - - ## Scenario 3 -
    Certificate file 'random_file.txt' is invalid. For a list of accepted ways to provide a certificate, please visit https://docs.nuget.org/docs/reference/command-line-reference.
    +> Certificate file 'random_file.txt' is invalid. For a list of accepted ways to provide a certificate, visit https://docs.nuget.org/docs/reference/command-line-reference. ### Issue @@ -55,69 +49,56 @@ A certificate file was provided to the NuGet Sign operation, but the file is not Please ensure that any certificate file being used to sign a NuGet package is a valid certificate file. - - ## Scenario 4 -
    Multiple certificates were found that meet all the given criteria. Use the '-CertificateFingerprint' option with the hash of the desired certificate.
    +> Multiple certificates were found that meet all the given criteria. Use the '-CertificateFingerprint' option with the hash of the desired certificate. ### Issue -A certificate was suggested to the NuGet Sign command using the `-CertificateSubjectName` option. But multiple certificates were found to match the certificate subject name in the windows certificate store. - +A certificate was suggested to the NuGet Sign command using the `-CertificateSubjectName` option. But multiple certificates were found to match the certificate subject name in the Windows certificate store. ### Solution Please pass the '-CertificateFingerprint' option with the hash of the desired certificate to the NuGet Sign command to uniquely identify a certificate. - - ## Scenario 5 -
    No certificates were found that meet all the given criteria. For a list of accepted ways to provide a certificate, please visit https://docs.nuget.org/docs/reference/command-line-reference.
    +> No certificates were found that meet all the given criteria. For a list of accepted ways to provide a certificate, visit https://docs.nuget.org/docs/reference/command-line-reference. ### Issue -A certificate was suggested to the NuGet Sign command using the `-CertificateSubjectName` option. But no certificate was found to match the certificate subject name in the windows certificate store. - +A certificate was suggested to the NuGet Sign command using the `-CertificateSubjectName` option. But no certificate was found to match the certificate subject name in the Windows certificate store. ### Solution Please ensure that you passing the right subject name filter, otherwise pass the '-CertificateFingerprint' option with the hash of the desired certificate to the NuGet Sign command to uniquely identify a certificate. - ## Scenario 6 -
    The following certificate cannot be used for package signing as the private key provider is unsupported:
-  Subject Name: CN=Certificate Subject Name
-  SHA1 hash: HASH
-  SHA256 hash: HASH
-  Issued by: Issuer Subject Name
-  Valid from: 4/9/2016 5:00:00 PM to 4/14/2020 5:00:00 AM
    +> The following certificate cannot be used for package signing as the private key provider is unsupported: + Subject Name: CN=Certificate Subject Name
    + SHA1 hash: HASH
    + SHA256 hash: HASH
    + Issued by: Issuer Subject Name
    + Valid from: 4/9/2016 5:00:00 PM to 4/14/2020 5:00:00 AM ### Issue A certificate was passed to the NuGet Sign command which has an unsupported pribvate key provider. - ### Solution Currently, due to framework limitations, NuGet sign command does not support CNG key private key provider. Please use a certificate with a CAPI private key provider. - - ## Scenario 7 -
    The package already contains a signature. Please remove the existing signature before adding a new signature.
    +> The package already contains a signature. Remove the existing signature before adding a new signature. ### Issue NuGet Sign command was used to sign a package which already has a package signature. - ### Solution Please ensure that you are signing an unsigned package. If the package is already signed, then please use `-Overwrite` option to overwrite an existing signature. - - diff --git a/docs/reference/errors-and-warnings/NU3002.md b/docs/reference/errors-and-warnings/NU3002.md index 2d2cc9a8c..3b379ecd0 100644 --- a/docs/reference/errors-and-warnings/NU3002.md +++ b/docs/reference/errors-and-warnings/NU3002.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3002 description: NU3002 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU3002 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The '-Timestamper' option was not provided. The signed package will not be timestamped. To learn more about this option, please visit https://docs.nuget.org/docs/reference/command-line-reference.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The '-Timestamper' option was not provided. The signed package will not be timestamped. To learn more about this option, please visit https://docs.nuget.org/docs/reference/command-line-reference. ### Issue diff --git a/docs/reference/errors-and-warnings/NU3003.md b/docs/reference/errors-and-warnings/NU3003.md index 0f511cc54..67505254f 100644 --- a/docs/reference/errors-and-warnings/NU3003.md +++ b/docs/reference/errors-and-warnings/NU3003.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3003 description: NU3003 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package is not signed. Unable to verify signature from an unsigned package.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package is not signed. Unable to verify signature from an unsigned package. ### Issue @@ -29,7 +29,7 @@ Please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package signature is invalid or cannot be verified on this platform.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package signature is invalid or cannot be verified on this platform. ### Issue @@ -41,6 +41,5 @@ NuGet client tried to verify a package which contains an invalid package signatu Please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem and the platform on which the issue was encountered. > [!Note] -> When NuGet’s [signature validation mode](https://docs.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages#configure-package-signature-requirements) is set to accept (default), NU3003 is raised as a warning. +> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3003 is raised as a warning. > When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3003 is elevated from a warning to an error. - diff --git a/docs/reference/errors-and-warnings/NU3004.md b/docs/reference/errors-and-warnings/NU3004.md index ab4dcad2c..fdf2f1d1a 100644 --- a/docs/reference/errors-and-warnings/NU3004.md +++ b/docs/reference/errors-and-warnings/NU3004.md @@ -2,7 +2,7 @@ title: NuGet Error NU3004 description: NU3004 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -12,9 +12,10 @@ f1_keywords: # NuGet Error NU3004 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package is not signed.
    -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': signatureValidationMode is set to require, so packages are allowed only if signed by trusted signers; however, this package is unsigned.
    -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': This repository indicated that all its packages are repository signed; however, this package is unsigned.
    +## Scenario 1 + +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package is not signed.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': signatureValidationMode is set to require, so packages are allowed only if signed by trusted signers; however, this package is unsigned. ### Issue @@ -29,3 +30,18 @@ The `require` validation mode does not support unsigned package and an unsigned ### Solution Please ensure that any package intended to be installed or passed to `nuget verify -signatures` command contains a package signature. + +## Scenario 2 + +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': This repository indicated that all its packages are repository signed; however, this package is unsigned. + +### Issue + +The repository indicated that all its packages are repository signed. However, an unsigned package was downloaded. + +### Solution + +> [!Warning] +> This error may happen due to a bug when using multiple NuGet clients (see [NuGet/Home#7997](https://github.com/NuGet/Home/issues/7997)). Please upgrade to nuget.exe 5.1.0 or newer, Visual Studio 2019 16.1 or newer, and .NET SDK 2.1.70X or 2.2.30X or newer. + +You can check if a package is signed using the [`dotnet nuget verify`](/dotnet/core/tools/dotnet-nuget-verify) or [`nuget verify`](../cli-reference/cli-ref-verify.md) commands. If the package is unsigned, please contact the package source as this is unexpected. diff --git a/docs/reference/errors-and-warnings/NU3005.md b/docs/reference/errors-and-warnings/NU3005.md index bf5321d2e..a2c32aff2 100644 --- a/docs/reference/errors-and-warnings/NU3005.md +++ b/docs/reference/errors-and-warnings/NU3005.md @@ -2,7 +2,7 @@ title: NuGet Error NU3005 description: NU3005 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package contains an invalid package signature file.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package contains an invalid package signature file. ### Issue @@ -23,13 +23,13 @@ NuGet client tried to verify a package with a signature file which has an invali ### Solution -Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package). If the problem persists, then please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem. +Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md). If the problem persists, then please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem. ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package contains multiple package signature files.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package contains multiple package signature files. ### Issue @@ -38,13 +38,13 @@ NuGet client tried to verify a package which contains multiple signature files. ### Solution -Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package). If the problem persists, then please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem. +Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md). If the problem persists, then please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem. ## Scenario 3 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package does not contain a valid package signature file.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package does not contain a valid package signature file. ### Issue @@ -54,5 +54,3 @@ NuGet client tried to verify a package which does not contain a package signatur ### Solution Please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem. - - diff --git a/docs/reference/errors-and-warnings/NU3006.md b/docs/reference/errors-and-warnings/NU3006.md index 549f938e2..bb8000c35 100644 --- a/docs/reference/errors-and-warnings/NU3006.md +++ b/docs/reference/errors-and-warnings/NU3006.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3006 description: NU3006 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU3006 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': Signed Zip64 packages are not supported.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': Signed Zip64 packages are not supported. ### Issue diff --git a/docs/reference/errors-and-warnings/NU3007.md b/docs/reference/errors-and-warnings/NU3007.md index 9ad06dcb0..19077c226 100644 --- a/docs/reference/errors-and-warnings/NU3007.md +++ b/docs/reference/errors-and-warnings/NU3007.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3007 description: NU3007 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU3007 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package signature format version is not supported. Updating your client may solve this problem.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package signature format version is not supported. Updating your client may solve this problem. ### Issue diff --git a/docs/reference/errors-and-warnings/NU3008.md b/docs/reference/errors-and-warnings/NU3008.md index e9b0aef1a..fa8461f8d 100644 --- a/docs/reference/errors-and-warnings/NU3008.md +++ b/docs/reference/errors-and-warnings/NU3008.md @@ -2,7 +2,7 @@ title: NuGet Error NU3008 description: NU3008 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -12,17 +12,14 @@ f1_keywords: # NuGet Error NU3008 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package integrity check failed.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package integrity check failed. The package has changed since it was signed. Try clearing the local http-cache and run nuget operation again. ### Issue NuGet package being verified has changed since it was signed. - ### Solution -Please ensure that the package has not been tampered with since signing. If this was a temporary problem, then you can fix this by clearing your local cache(s) by running `nuget locals -Clear all` command. However, if the problem persists then please inform the package source and the package author. - -If this issue happened on a package which came from `nuget.org` then please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that caused this problem. - +Please ensure that the package has not been tampered with since signing. If this was a temporary problem, then you can fix this by clearing your local http-cache(s) by running `nuget locals http-cache -clear` or `dotnet nuget locals http-cache --clear` command. However, if the problem persists then please inform the package source and the package author. +If this issue happened on a package which came from `nuget.org` then please file an issue at [NuGet/NuGetGallery](https://github.com/NuGet/NuGetGallery/issues) along with the package that caused this problem. diff --git a/docs/reference/errors-and-warnings/NU3009.md b/docs/reference/errors-and-warnings/NU3009.md index 73ed8e14e..713c2ee4c 100644 --- a/docs/reference/errors-and-warnings/NU3009.md +++ b/docs/reference/errors-and-warnings/NU3009.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3009 description: NU3009 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU3009 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package signature file does not contain exactly one primary signature.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package signature file does not contain exactly one primary signature. ### Issue @@ -21,9 +21,9 @@ NuGet client tried to verify a package signature which contained multiple `Signe ### Solution -Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package). If the problem persists, then please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem. +Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md). If the problem persists, then please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem. > [!Note] -> When NuGet’s [signature validation mode](https://docs.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages#configure-package-signature-requirements) is set to accept (default), NU3009 is raised as a warning. +> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3009 is raised as a warning. > When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3009 is elevated from a warning to an error. diff --git a/docs/reference/errors-and-warnings/NU3010.md b/docs/reference/errors-and-warnings/NU3010.md index 415b7ccbb..e0616dd06 100644 --- a/docs/reference/errors-and-warnings/NU3010.md +++ b/docs/reference/errors-and-warnings/NU3010.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3010 description: NU3010 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU3010 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature does not have a signing certificate.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature does not have a signing certificate. ### Issue @@ -21,9 +21,9 @@ NuGet client tried to verify a package signature with a `SignerInfo` entry that ### Solution -Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package). If the problem persists, then please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem. +Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md). If the problem persists, then please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem. > [!Note] -> When NuGet’s [signature validation mode](https://docs.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages#configure-package-signature-requirements) is set to accept (default), NU3010 is raised as a warning. -> When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3010 is elevated from a warning to an error. \ No newline at end of file +> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3010 is raised as a warning. +> When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3010 is elevated from a warning to an error. diff --git a/docs/reference/errors-and-warnings/NU3011.md b/docs/reference/errors-and-warnings/NU3011.md index 3bbc83895..223a4794d 100644 --- a/docs/reference/errors-and-warnings/NU3011.md +++ b/docs/reference/errors-and-warnings/NU3011.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3011 description: NU3011 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU3011 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature is invalid.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature is invalid. ### Issue @@ -21,9 +21,9 @@ NuGet client was unable to read the certificate chain for the signing certificat ### Solution -Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package). If the problem persists, then please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem. +Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md). If the problem persists, then please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem. > [!Note] -> When NuGet’s [signature validation mode](https://docs.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages#configure-package-signature-requirements) is set to accept (default), NU3011 is raised as a warning. +> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3011 is raised as a warning. > When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3011 is elevated from a warning to an error. diff --git a/docs/reference/errors-and-warnings/NU3012.md b/docs/reference/errors-and-warnings/NU3012.md index 978631d45..9cecd28ac 100644 --- a/docs/reference/errors-and-warnings/NU3012.md +++ b/docs/reference/errors-and-warnings/NU3012.md @@ -2,7 +2,7 @@ title: NuGet Error NU3012 description: NU3012 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature validation failed.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature validation failed. ### Issue @@ -29,7 +29,7 @@ You can get more details about the problem by looking at the debug logs. If the ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature found a chain building issue:  A certificate chain processed, but terminated in a root certificate which is not trusted by the trust provider.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature found a chain building issue: A certificate chain processed, but terminated in a root certificate which is not trusted by the trust provider. ### Issue @@ -42,6 +42,5 @@ Please ensure that the package signature has a valid certificate chain. You can > [!Note] -> When NuGet’s [signature validation mode](https://docs.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages#configure-package-signature-requirements) is set to accept (default), NU3012 is raised as a warning in most cases. +> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3012 is raised as a warning in most cases. > When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3012 is elevated from a warning to an error. - diff --git a/docs/reference/errors-and-warnings/NU3013.md b/docs/reference/errors-and-warnings/NU3013.md index 9d7987655..bd2d3a0a5 100644 --- a/docs/reference/errors-and-warnings/NU3013.md +++ b/docs/reference/errors-and-warnings/NU3013.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3013 description: NU3013 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The signing certificate has an unsupported signature algorithm.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The signing certificate has an unsupported signature algorithm. ### Issue @@ -32,7 +32,7 @@ Please ensure that the signing certificate has one of the following signature al ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's certificate has an unsupported signature algorithm.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's certificate has an unsupported signature algorithm. ### Issue @@ -48,6 +48,5 @@ Please ensure that the package was signed using a certificate with one of the fo > [!Note] -> When NuGet’s [signature validation mode](https://docs.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages#configure-package-signature-requirements) is set to accept (default), NU3013 is raised as a warning. +> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3013 is raised as a warning. > When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3013 is elevated from a warning to an error. - diff --git a/docs/reference/errors-and-warnings/NU3014.md b/docs/reference/errors-and-warnings/NU3014.md index 915eac03f..e292ef72a 100644 --- a/docs/reference/errors-and-warnings/NU3014.md +++ b/docs/reference/errors-and-warnings/NU3014.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3014 description: NU3014 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The signing certificate does not meet a minimum public key length requirement.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The signing certificate does not meet a minimum public key length requirement. ### Issue @@ -29,7 +29,7 @@ Please ensure that the signing certificate has an RSA public key of length >= 20 ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's certificate does not meet a minimum public key length requirement.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's certificate does not meet a minimum public key length requirement. ### Issue @@ -42,5 +42,5 @@ Please ensure that the package was signed using a signing certificate with an RS > [!Note] -> When NuGet’s [signature validation mode](https://docs.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages#configure-package-signature-requirements) is set to accept (default), NU3014 is raised as a warning. +> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3014 is raised as a warning. > When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3014 is elevated from a warning to an error. diff --git a/docs/reference/errors-and-warnings/NU3015.md b/docs/reference/errors-and-warnings/NU3015.md index 19dabf7b9..5a04c73ef 100644 --- a/docs/reference/errors-and-warnings/NU3015.md +++ b/docs/reference/errors-and-warnings/NU3015.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3015 description: NU3015 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The lifetime signing EKU in the primary signature's certificate is not supported.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The lifetime signing EKU in the primary signature's certificate is not supported. ### Issue @@ -29,7 +29,7 @@ Please ensure that the signing certificate does not have lifetime signing Extend ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The lifetime signing EKU in the signing certificate is not supported.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The lifetime signing EKU in the signing certificate is not supported. ### Issue @@ -42,5 +42,5 @@ Please ensure that the package was signed using a signing certificate that does > [!Note] -> When NuGet’s [signature validation mode](https://docs.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages#configure-package-signature-requirements) is set to accept (default), NU3015 is raised as a warning. -> When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3015 is elevated from a warning to an error. \ No newline at end of file +> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3015 is raised as a warning. +> When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3015 is elevated from a warning to an error. diff --git a/docs/reference/errors-and-warnings/NU3016.md b/docs/reference/errors-and-warnings/NU3016.md index a0b1f053a..ac4c9d36f 100644 --- a/docs/reference/errors-and-warnings/NU3016.md +++ b/docs/reference/errors-and-warnings/NU3016.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3016 description: NU3016 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU3016 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package hash uses an unsupported hash algorithm.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package hash uses an unsupported hash algorithm. ### Issue @@ -28,5 +28,5 @@ Please ensure that the package was signed with one of the following hash algori > [!Note] -> When NuGet’s [signature validation mode](https://docs.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages#configure-package-signature-requirements) is set to accept (default), NU3016 is raised as a warning. -> When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3016 is elevated from a warning to an error. \ No newline at end of file +> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3016 is raised as a warning. +> When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3016 is elevated from a warning to an error. diff --git a/docs/reference/errors-and-warnings/NU3017.md b/docs/reference/errors-and-warnings/NU3017.md index 66d09b529..c8d255031 100644 --- a/docs/reference/errors-and-warnings/NU3017.md +++ b/docs/reference/errors-and-warnings/NU3017.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3017 description: NU3017 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The signing certificate is not yet valid.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The signing certificate is not yet valid. ### Issue @@ -29,7 +29,7 @@ Please ensure that the signing certificate is currently valid. ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's certificate is not yet valid.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's certificate is not yet valid. ### Issue @@ -38,9 +38,9 @@ The certificate used to sign the package has a validity in the future, but is no ### Solution -Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package) with a signing certificate which is currently valid. +Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md) with a signing certificate which is currently valid. > [!Note] -> When NuGet’s [signature validation mode](https://docs.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages#configure-package-signature-requirements) is set to accept (default), NU3017 is raised as a warning. -> When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3017 is elevated from a warning to an error. \ No newline at end of file +> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3017 is raised as a warning. +> When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3017 is elevated from a warning to an error. diff --git a/docs/reference/errors-and-warnings/NU3018.md b/docs/reference/errors-and-warnings/NU3018.md index 68bc84a75..93baa310a 100644 --- a/docs/reference/errors-and-warnings/NU3018.md +++ b/docs/reference/errors-and-warnings/NU3018.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3018 description: NU3018 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -12,18 +12,18 @@ f1_keywords: # NuGet Warning NU3018 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature found a chain building issue: A certificate chain processed, but terminated in a root certificate which is not trusted by the trust provider.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's signing certificate is not trusted by the trust provider. ### Issue NuGet client failed to verify the certificate chain for the signing certificate used to sign the package. - ### Solution -Please ensure that the package signature has a valid certificate chain. You can verify the package signature by running the `nuget verify -signatures` command on the package. If the problem persists, then please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem. - +Please ensure that the package signature has a valid certificate chain. You can verify the package signature by running the `nuget verify -signatures` or `dotnet nuget verify` command on the package. If the problem persists, then please file an issue at [NuGet/Home](https://github.com/NuGet/Home/issues) along with the package that generated this problem. > [!Note] -> When NuGet’s [signature validation mode](https://docs.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages#configure-package-signature-requirements) is set to accept (default), NU3018 is raised as a warning. -> When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3018 is elevated from a warning to an error in most cases. \ No newline at end of file +> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3018 is raised as a warning. +> When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3018 is elevated from a warning to an error in most cases. + +For Linux and macOS, see [NuGet signed-package verification](/dotnet/core/tools/nuget-signed-package-verification). Specifically for untrusted root certificate warnings/errors on Linux and macOS, also see [NU3042](NU3042.md). \ No newline at end of file diff --git a/docs/reference/errors-and-warnings/NU3019.md b/docs/reference/errors-and-warnings/NU3019.md index bd30c0a69..689208f87 100644 --- a/docs/reference/errors-and-warnings/NU3019.md +++ b/docs/reference/errors-and-warnings/NU3019.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3019 description: NU3019 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp integrity check failed.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp integrity check failed. ### Issue @@ -29,7 +29,7 @@ Please try to re-sign and timestamp the package. If the problem persists, contac ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp integrity check failed.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp integrity check failed. ### Issue @@ -38,7 +38,7 @@ The timestamp on the package signature has changed since it was generated by the ### Solution -Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package). If the problem persists, request the package author to contact the Timestamp Authority to discover the source of the problem. +Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md). If the problem persists, request the package author to contact the Timestamp Authority to discover the source of the problem. > [!Note] diff --git a/docs/reference/errors-and-warnings/NU3020.md b/docs/reference/errors-and-warnings/NU3020.md index e73df3f9b..cfca6be9a 100644 --- a/docs/reference/errors-and-warnings/NU3020.md +++ b/docs/reference/errors-and-warnings/NU3020.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3020 description: NU3020 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp does not have a signing certificate.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp does not have a signing certificate. ### Issue @@ -29,7 +29,7 @@ Please try to re-sign and timestamp the package. If the problem persists, contac ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp does not have a signing certificate.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp does not have a signing certificate. ### Issue @@ -38,8 +38,8 @@ The timestamp on the package signature does not contain a signing certificate. ### Solution -Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package). If the problem persists, request the package author to contact the Timestamp Authority to discover the source of the problem. +Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md). If the problem persists, request the package author to contact the Timestamp Authority to discover the source of the problem. > [!Note] -> When running the `nuget verify -signatures` command, NU3020 is raised as an error. Otherwise, NU3020 is raised as a warning. \ No newline at end of file +> When running the `nuget verify -signatures` command, NU3020 is raised as an error. Otherwise, NU3020 is raised as a warning. diff --git a/docs/reference/errors-and-warnings/NU3021.md b/docs/reference/errors-and-warnings/NU3021.md index 08ed98c34..c0655ce3d 100644 --- a/docs/reference/errors-and-warnings/NU3021.md +++ b/docs/reference/errors-and-warnings/NU3021.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3021 description: NU3021 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp signature validation failed.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp signature validation failed. ### Issue @@ -23,13 +23,13 @@ NuGet client failed to verify the `SignedCms` object inside the timestamp on the ### Solution -Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package). If the problem persists, request the package author to contact the Timestamp Authority to discover the source of the problem. +Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md). If the problem persists, request the package author to contact the Timestamp Authority to discover the source of the problem. ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp signature validation failed.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp signature validation failed. ### Issue @@ -42,4 +42,4 @@ Please try to re-sign and timestamp the package. If the problem persists, contac > [!Note] -> When running the `nuget verify -signatures` command, NU3021 is raised as an error. Otherwise, NU3021 is raised as a warning. \ No newline at end of file +> When running the `nuget verify -signatures` command, NU3021 is raised as an error. Otherwise, NU3021 is raised as a warning. diff --git a/docs/reference/errors-and-warnings/NU3022.md b/docs/reference/errors-and-warnings/NU3022.md index ed38a4297..bbe3e11f1 100644 --- a/docs/reference/errors-and-warnings/NU3022.md +++ b/docs/reference/errors-and-warnings/NU3022.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3022 description: NU3022 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp certificate has an unsupported signature algorithm.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp certificate has an unsupported signature algorithm. ### Issue @@ -32,7 +32,7 @@ Please ensure that the timestamp authority's signing certificate has one of the ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp certificate has an unsupported signature algorithm (SHA1). The following algorithms are supported: SHA256RSA, SHA384RSA, SHA512RSA.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp certificate has an unsupported signature algorithm (SHA1). The following algorithms are supported: SHA256RSA, SHA384RSA, SHA512RSA. ### Issue @@ -41,11 +41,11 @@ The certificate used to timestamp the package signature has an unsupported signa ### Solution -Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package) using the `-Timestamper` option such that the timestamp authority signing certificate has one of the following signature algorithms - +Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md) using the `-Timestamper` option such that the timestamp authority signing certificate has one of the following signature algorithms - * `sha256WithRSAEncryption` * `sha384WithRSAEncryption` * `sha512WithRSAEncryption` > [!Note] -> When running the `nuget verify -signatures` command, NU3022 is raised as an error. Otherwise, NU3022 is raised as a warning. \ No newline at end of file +> When running the `nuget verify -signatures` command, NU3022 is raised as an error. Otherwise, NU3022 is raised as a warning. diff --git a/docs/reference/errors-and-warnings/NU3023.md b/docs/reference/errors-and-warnings/NU3023.md index a68b07867..b984ba930 100644 --- a/docs/reference/errors-and-warnings/NU3023.md +++ b/docs/reference/errors-and-warnings/NU3023.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3023 description: NU3023 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp certificate does not meet a minimum public key length requirement.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp certificate does not meet a minimum public key length requirement. ### Issue @@ -29,7 +29,7 @@ Please ensure that the Timestamp Authority's signing certificate has an RSA pub ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp certificate does not meet a minimum public key length requirement.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp certificate does not meet a minimum public key length requirement. ### Issue diff --git a/docs/reference/errors-and-warnings/NU3024.md b/docs/reference/errors-and-warnings/NU3024.md index cb2c11193..373a01016 100644 --- a/docs/reference/errors-and-warnings/NU3024.md +++ b/docs/reference/errors-and-warnings/NU3024.md @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp signature has an unsupported digest algorithm. The following algorithms are supported: : SHA-2-256, SHA-2-384, SHA-2-512.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp signature has an unsupported digest algorithm. The following algorithms are supported: : SHA-2-256, SHA-2-384, SHA-2-512. ### Issue @@ -32,7 +32,7 @@ Ensure that the timestamp authority's signature has one of the following digest ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp signature has an unsupported digest algorithm.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp signature has an unsupported digest algorithm. ### Issue @@ -41,11 +41,11 @@ The timestamp's signature has an unsupported digest algorithm. ### Solution -Request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package) using the `-Timestamper` option such that the timestamp authority signing certificate has one of the following digest algorithms - +Request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md) using the `-Timestamper` option such that the timestamp authority signing certificate has one of the following digest algorithms - * `SHA-2-256` * `SHA-2-384` * `SHA-2-512` > [!Note] -> When running the `nuget verify -signatures` command, NU3024 is raised as an error. Otherwise, NU3024 is raised as a warning. \ No newline at end of file +> When running the `nuget verify -signatures` command, NU3024 is raised as an error. Otherwise, NU3024 is raised as a warning. diff --git a/docs/reference/errors-and-warnings/NU3025.md b/docs/reference/errors-and-warnings/NU3025.md index 21bf3e3e2..ea3569e9b 100644 --- a/docs/reference/errors-and-warnings/NU3025.md +++ b/docs/reference/errors-and-warnings/NU3025.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3025 description: NU3025 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp signing certificate is not yet valid.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp signing certificate is not yet valid. ### Issue @@ -29,7 +29,7 @@ Please ensure that the Timestamp Authority's signing certificate is currently va ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp signing certificate is not yet valid.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp signing certificate is not yet valid. ### Issue @@ -38,8 +38,8 @@ The certificate used to sign the package has a validity in the future, but is no ### Solution -Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package). If the problem persists, request the package author to contact the Timestamp Authority to discover the source of the problem. +Please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md). If the problem persists, request the package author to contact the Timestamp Authority to discover the source of the problem. > [!Note] -> When running the `nuget verify -signatures` command, NU3025 is raised as an error. Otherwise, NU3025 is raised as a warning. \ No newline at end of file +> When running the `nuget verify -signatures` command, NU3025 is raised as an error. Otherwise, NU3025 is raised as a warning. diff --git a/docs/reference/errors-and-warnings/NU3026.md b/docs/reference/errors-and-warnings/NU3026.md index 8d078a2d4..2fafbfb69 100644 --- a/docs/reference/errors-and-warnings/NU3026.md +++ b/docs/reference/errors-and-warnings/NU3026.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU3026 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp response is invalid. Nonces did not match.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp response is invalid. Nonces did not match. ### Issue diff --git a/docs/reference/errors-and-warnings/NU3027.md b/docs/reference/errors-and-warnings/NU3027.md index 4c93255ad..382dcad8f 100644 --- a/docs/reference/errors-and-warnings/NU3027.md +++ b/docs/reference/errors-and-warnings/NU3027.md @@ -2,7 +2,7 @@ title: NuGet Warning NU3027 description: NU3027 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/16/2018 ms.topic: reference ms.reviewer: anangaur @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU3027 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The signature should be timestamped to enable long-term signature validity after the certificate has expired.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The signature should be timestamped to enable long-term signature validity after the certificate has expired. ### Issue @@ -21,6 +21,4 @@ The package signature does not contain a timestamp. ### Solution -For long term signature validity, please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package) using the `-Timestamper` option. - - +For long term signature validity, please request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md) using the `-Timestamper` option. diff --git a/docs/reference/errors-and-warnings/NU3028.md b/docs/reference/errors-and-warnings/NU3028.md index 530a0a071..5ad0ba503 100644 --- a/docs/reference/errors-and-warnings/NU3028.md +++ b/docs/reference/errors-and-warnings/NU3028.md @@ -14,25 +14,35 @@ f1_keywords: *NuGet 4.6.0+* -
    The author primary signature's timestamp found a chain building issue: The revocation function was unable to check revocation because the revocation server could not be reached. For more information, visit https://aka.ms/certificateRevocationMode
    +> The author primary signature's timestamp found a chain building issue: The revocation function was unable to check revocation because the revocation server could not be reached. For more information, visit https://aka.ms/certificateRevocationMode ### Issue + Certificate chain building failed for the timestamp signature. The timestamp signing certificate is untrusted, revoked, or revocation information for the certificate is unavailable. +On Windows only, NU3028 may occur the first time a root certificate is observed and with the message "A certification chain processed correctly but terminated in a root certificate that is not trusted by the trust provider." If the issue is resolved with retries, [there is an option which may help](../Signed-Package-Verification-Options.md#retry-untrusted-root-failures). + ### Solution -Use a trusted and valid certificate. Check internet connectivity.gits -### Revocation check mode *(4.8.1+)* +Use a trusted and valid certificate. Check internet connectivity. + +For Linux and macOS, see [NuGet signed-package verification](/dotnet/core/tools/nuget-signed-package-verification). Specifically for untrusted root certificate warnings/errors on Linux and macOS, also see [NU3042](NU3042.md). + +#### Revocation check mode + +> [!Note] +> This option is available starting from NuGet 4.8.1. + If the machine has restricted internet access (such as a build machine in a CI/CD scenario), installing/restoring a signed nuget package will result in this warning since the revocation servers are not reachable. This is expected. However, in some cases, this may have unintended concequences such as the package install/restore taking longer than usual. If that happens, you can work around it by setting the `NUGET_CERT_REVOCATION_MODE` environment variable to `offline`. This will force NuGet to check the revocation status of the certificate only against the cached certificate revocation list, and NuGet will not attempt to reach revocation servers. > [!Warning] -> It is not recommended to switch the revocation check mode to offline under normal cirumstances. Doing so will cause NuGet to skip online revocation check and perform only an offline revocation check against the cached certificate revocation list which may be out of date. This means packages where the signing certificate may have been revoked, will continue to be installed/restored, which otherwise would have failed revocation check and would not have been installed. +> It is not recommended to switch the revocation check mode to offline under normal circumstances. Doing so will cause NuGet to skip an online revocation check and perform only an offline revocation check against the cached certificate revocation list which may be out of date. This means packages where the signing certificate may have been revoked, will continue to be installed/restored, which otherwise would have failed revocation check and would not have been installed. -When the revocation check mode is set to `offline`, the warning will be downgraded to an info. +When the revocation check mode is set to `offline`, the warning will be downgraded to an informational level. -
    The author primary signature's timestamp found a chain building issue: The revocation function was unable to check revocation because the certificate is not available in the cached certificate revocation list and NUGET_CERT_REVOCATION_MODE environment variable has been set to offline. For more information, visit https://aka.ms/certificateRevocationMode.
    +> The author primary signature's timestamp found a chain building issue: The revocation function was unable to check revocation because the certificate is not available in the cached certificate revocation list and NUGET_CERT_REVOCATION_MODE environment variable has been set to offline. For more information, visit https://aka.ms/certificateRevocationMode. > [!Note] > NU3028 is raised as an error in most cases. -> When NuGet’s [signature validation mode](https://docs.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages#configure-package-signature-requirements) is set to accept (default), NU3028 is raised as a warning in some cases. +> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), NU3028 is raised as a warning in some cases. diff --git a/docs/reference/errors-and-warnings/NU3029.md b/docs/reference/errors-and-warnings/NU3029.md index 689e83f96..7eb3898f4 100644 --- a/docs/reference/errors-and-warnings/NU3029.md +++ b/docs/reference/errors-and-warnings/NU3029.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU3029 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp signature is invalid.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp signature is invalid. ### Issue diff --git a/docs/reference/errors-and-warnings/NU3030.md b/docs/reference/errors-and-warnings/NU3030.md index 9d75a41da..1c1966246 100644 --- a/docs/reference/errors-and-warnings/NU3030.md +++ b/docs/reference/errors-and-warnings/NU3030.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU3030 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp's message imprint uses an unsupported hash algorithm.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp's message imprint uses an unsupported hash algorithm. ### Issue @@ -21,11 +21,11 @@ The primary signature's timestamp's message imprint uses an unsupported hash alg ### Solution -Request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package) using the `-Timestamper` option such that the timestamp's message imprint uses one of the following hash algorithms - +Request the package author to re-sign the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md) using the `-Timestamper` option such that the timestamp's message imprint uses one of the following hash algorithms - * `SHA-2-256` * `SHA-2-384` * `SHA-2-512` > [!Note] -> When running the `nuget verify -signatures` command, NU3030 is raised as an error. Otherwise, NU3030 is raised as a warning. \ No newline at end of file +> When running the `nuget verify -signatures` command, NU3030 is raised as an error. Otherwise, NU3030 is raised as a warning. diff --git a/docs/reference/errors-and-warnings/NU3031.md b/docs/reference/errors-and-warnings/NU3031.md index d590213c0..d065571b2 100644 --- a/docs/reference/errors-and-warnings/NU3031.md +++ b/docs/reference/errors-and-warnings/NU3031.md @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU3031 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The repository countersignature is invalid.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The repository countersignature is invalid. ### Issue diff --git a/docs/reference/errors-and-warnings/NU3032.md b/docs/reference/errors-and-warnings/NU3032.md index 447de425b..3265c81ad 100644 --- a/docs/reference/errors-and-warnings/NU3032.md +++ b/docs/reference/errors-and-warnings/NU3032.md @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package already contains a repository countersignature. Please remove the existing signature before adding a new repository countersignature.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package already contains a repository countersignature. Please remove the existing signature before adding a new repository countersignature. ### Issue @@ -29,7 +29,7 @@ Remove the existing signature before adding a new repository countersignature. ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package signature contains multiple repository countersignatures.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package signature contains multiple repository countersignatures. ### Issue diff --git a/docs/reference/errors-and-warnings/NU3033.md b/docs/reference/errors-and-warnings/NU3033.md index ffabc561a..9349057ee 100644 --- a/docs/reference/errors-and-warnings/NU3033.md +++ b/docs/reference/errors-and-warnings/NU3033.md @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': A repository primary signature must not have a repository countersignature.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': A repository primary signature must not have a repository countersignature. ### Issue @@ -28,7 +28,7 @@ Try to re-sign the package with either an author signature or a repository signa ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': A repository primary signature must not have a repository countersignature.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': A repository primary signature must not have a repository countersignature. ### Issue diff --git a/docs/reference/errors-and-warnings/NU3034.md b/docs/reference/errors-and-warnings/NU3034.md index c1c139fd9..43886c386 100644 --- a/docs/reference/errors-and-warnings/NU3034.md +++ b/docs/reference/errors-and-warnings/NU3034.md @@ -1,8 +1,8 @@ --- title: NuGet Error NU3034 description: NU3034 Error code -author: patbel -ms.author: patbel +author: JonDouglas +ms.author: jodou ms.date: 11/12/2018 ms.topic: reference ms.reviewer: rmpablos @@ -12,10 +12,13 @@ f1_keywords: # NuGet Error NU3034 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': signatureValidationMode is set to require, so packages are allowed only if signed by trusted signers; however, no trusted signers were specified.
    -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package signature certificate fingerprint does not match any certificate fingerprint in the allow list.
    -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': This repository indicated that all its packages are repository signed; however, it listed no signing certificates.
    -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': This package was not repository signed with a certificate listed by this repository.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': signatureValidationMode is set to require, so packages are allowed only if signed by trusted signers; however, no trusted signers were specified. + +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The package signature certificate fingerprint does not match any certificate fingerprint in the allow list. + +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': This repository indicated that all its packages are repository signed; however, it listed no signing certificates. + +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': This package was not repository signed with a certificate listed by this repository. ### Issue diff --git a/docs/reference/errors-and-warnings/NU3036.md b/docs/reference/errors-and-warnings/NU3036.md index f9aa7c5d9..854f65bdf 100644 --- a/docs/reference/errors-and-warnings/NU3036.md +++ b/docs/reference/errors-and-warnings/NU3036.md @@ -14,7 +14,7 @@ f1_keywords: ## Scenario 1 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp's generalized time is outside the timestamping certificate's validity period.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The timestamp's generalized time is outside the timestamping certificate's validity period. ### Issue @@ -29,7 +29,7 @@ Try to re-sign and timestamp the package. If the problem persists, contact the t ## Scenario 2 -
    Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp's generalized time is outside the timestamping certificate's validity period.
    +> Package 'SamplePackage v1.0.0' from source 'https://contoso.com/index.json': The primary signature's timestamp's generalized time is outside the timestamping certificate's validity period. ### Issue @@ -38,8 +38,8 @@ The certificate used to timestamp the package signature is invalid as the timest ### Solution -Request the package author to re-sign and timestamp the package using the `nuget sign` command as described in [NuGet docs](https://docs.microsoft.com/en-us/nuget/create-packages/sign-a-package). If the problem persists, request the package author to contact the timestamp authority to discover the source of the problem. +Request the package author to re-sign and timestamp the package using the `nuget sign` command as described in [NuGet docs](../../create-packages/sign-a-package.md). If the problem persists, request the package author to contact the timestamp authority to discover the source of the problem. > [!Note] -> When running the `nuget verify -signatures` command, NU3036 is raised as an error. Otherwise, NU3036 is raised as a warning. \ No newline at end of file +> When running the `nuget verify -signatures` command, NU3036 is raised as an error. Otherwise, NU3036 is raised as a warning. diff --git a/docs/reference/errors-and-warnings/NU3037.md b/docs/reference/errors-and-warnings/NU3037.md index 8d124ba3d..0ae04c9ef 100644 --- a/docs/reference/errors-and-warnings/NU3037.md +++ b/docs/reference/errors-and-warnings/NU3037.md @@ -18,6 +18,7 @@ A NuGet package signature has expired. A package signature shares the same validity period as the certificate used to generate the signature. A package signature is invalid outside of that validity period. To ensure long-term validity --- even beyond the signing certificate’s validity period --- a package signature should be timestamped with a trusted timestamp. Trusted timestamps must be added while a package signature is still valid and not expired. +On Windows only, NU3037 may occur the first time a root certificate is observed and with the message "The repository primary signature validity period has expired." If the issue is resolved with retries, [there is an option which may help](../Signed-Package-Verification-Options.md#retry-untrusted-root-failures). ### Solution @@ -25,5 +26,5 @@ To ensure long-term validity --- even beyond the signing certificate’s validit * For accept mode only, ignore the warning. > [!Note] -> When NuGet’s [signature validation mode](https://docs.microsoft.com/en-us/nuget/consume-packages/installing-signed-packages#configure-package-signature-requirements) is set to accept (default), a package with an expired package signature is treated as an unsigned package and installed anyway. NU3037 is raised as a warning. -> When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3037 is elevated from a warning to an error. \ No newline at end of file +> When NuGet’s [signature validation mode](../../consume-packages/installing-signed-packages.md#configure-package-signature-requirements) is set to accept (default), a package with an expired package signature is treated as an unsigned package and installed anyway. NU3037 is raised as a warning. +> When NuGet’s signature validation mode is set to require, or when running the `nuget verify -signatures` command, NU3037 is elevated from a warning to an error. diff --git a/docs/reference/errors-and-warnings/NU3040.md b/docs/reference/errors-and-warnings/NU3040.md index 0040b2619..95b15be40 100644 --- a/docs/reference/errors-and-warnings/NU3040.md +++ b/docs/reference/errors-and-warnings/NU3040.md @@ -1,8 +1,8 @@ --- title: NuGet Warning NU3040 description: NU3040 Warning code -author: patbel -ms.author: patbel +author: JonDouglas +ms.author: jodou ms.date: 11/12/2018 ms.topic: reference ms.reviewer: rmpablos @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU3040 -
    There are two certificates with conflicting allowUntrustedRoot attributes in the computed settings. The allowUntrustedRoot attribute is going to be set to false. Certificate: SHA256-3F9001EA83C560D712C24CF213C3D312CB3BFF51EE89435D3430BD06B5D0EECE
    +> There are two certificates with conflicting allowUntrustedRoot attributes in the computed settings. The allowUntrustedRoot attribute is going to be set to false. Certificate: SHA256-3F9001EA83C560D712C24CF213C3D312CB3BFF51EE89435D3430BD06B5D0EECE ### Issue diff --git a/docs/reference/errors-and-warnings/NU3042.md b/docs/reference/errors-and-warnings/NU3042.md new file mode 100644 index 000000000..04497a9f6 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU3042.md @@ -0,0 +1,46 @@ +--- +title: NuGet Warning NU3042 +description: NU3042 warning code +author: dtivel +ms.author: dtivel +ms.date: 03/22/2023 +ms.topic: reference +ms.reviewer: +f1_keywords: + - "NU3042" +--- + +# NuGet Warning NU3042 + +*NuGet 6.6.0+ on Linux and macOS only* + +> The following X.509 root certificate is untrusted because it is not present in the certificate bundle at <file-path>. For more information, see documentation for NU3042.
    +>     Subject: <certificate subject>
    +>     Fingerprint (SHA-256): <certificate fingerprint>
    +>     Certificate (PEM):
    +> <PEM-encoded certificate> + +### Issue + +Warning NU3042 is raised when signed package verification failed because a root certificate was not found in the appropriate trusted root certificate bundle, either code signing or timestamping. This warning will only be raised on Linux and macOS when signed package verification is enabled, never on Windows. NU3042 should accompany an [NU3018](NU3018.md) or [NU3028](NU3028.md). + +Each .NET 7+ SDK release contains two root certificate bundles sourced from the [Microsoft Trusted Root Program](https://aka.ms/RootCert). One certificate bundle contains all trusted roots valid for code signing, while the other contains all trusted roots valid for timestamping. NuGet uses these certificate bundles on Linux and macOS when signed package verification is enabled. + +On Linux, NuGet will prefer a system-wide code signing certificate bundle over the .NET SDK's code signing certificate bundle. + +The root cause for NU3042 is likely one of the following: + +* (Linux only) The system-wide code signing certificate bundle does not contain the root certificate referenced in the warning. +* The .NET SDK's certificate bundles are out of date. + +For more information, see [NuGet signed-package verification](/dotnet/core/tools/nuget-signed-package-verification). + +### Solution + +On Linux, if you trust the certificate and are using a system-wide code signing certificate bundle, consider adding the root certificate to the bundle. This solution may not be suitable because it will grant system-wide trust. + +If the .NET SDK's certificate bundles are out-of-date, update to a more recent release of the .NET SDK. + +If all else fails, opt out of signed package verification by setting the environment variable `DOTNET_NUGET_SIGNATURE_VERIFICATION` to `false` and [open an issue with the NuGet team](https://github.com/NuGet/Home/issues) to suggest how signed package verification can be improved on your platform. + +For more information, see [NuGet signed-package verification](/dotnet/core/tools/nuget-signed-package-verification). diff --git a/docs/reference/errors-and-warnings/NU3043.md b/docs/reference/errors-and-warnings/NU3043.md new file mode 100644 index 000000000..93cecd27d --- /dev/null +++ b/docs/reference/errors-and-warnings/NU3043.md @@ -0,0 +1,58 @@ +--- +title: NuGet Warning NU3043 +description: NU3043 warning code +author: kartheekp-ms +ms.date: 09/11/2024 +ms.topic: reference +f1_keywords: + - "NU3043" +--- + +# NuGet Warning NU3043 + +> Invalid value for `--certificate-fingerprint` option in the `dotnet nuget sign` command or the `CertificateFingerprint` option in the `NuGet.exe sign` command. +The value must be a SHA-256, SHA-384, or SHA-512 certificate fingerprint (in hexadecimal). + +This warning is promoted to an error in the .NET 10 SDK, and will be promoted to an error in NuGet.exe around .NET 10's release. + +## Issue + +Starting with .NET 9 and NuGet.exe 6.12, NU3043 warning is raised when a SHA-1 certificate fingerprint is passed to the sign commands. +SHA-1 is considered insecure and should no longer be used. + +## Solution + +To resolve this warning, ensure that you provide a valid SHA-256, SHA-384, or SHA-512 certificate fingerprint (in hexadecimal) for the `--certificate-fingerprint` option in the `dotnet nuget sign` command or the `CertificateFingerprint` option in the `NuGet.exe sign` command. + +You can use the following scripts to compute SHA-2 family hashes for certificates. + +### PowerShell +To use the script, you need to save the certificate to a local folder. + +```powershell +$certificate = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($certPath) +$stream = [System.IO.MemoryStream]::new($certificate.RawData) + +Try +{ + (Get-FileHash -Algorithm SHA256 $stream).Hash +} +Finally +{ + $stream.Dispose() + $certificate.Dispose() +} +``` +### OpenSSL (Linux/macOS) + +If the certificate is in PEM or CRT format: +```sh +openssl x509 -in path/to/certificate -outform der | sha256sum +``` + +If the certificate is already in DER format: +```sh +sha256sum path/to/certificate +``` +> [!TIP] +> For SHA-384 or SHA-512, replace sha256sum with sha384sum or sha512sum as needed. diff --git a/docs/reference/errors-and-warnings/NU5000.md b/docs/reference/errors-and-warnings/NU5000.md index 2d2dfa289..738ed464b 100644 --- a/docs/reference/errors-and-warnings/NU5000.md +++ b/docs/reference/errors-and-warnings/NU5000.md @@ -2,7 +2,7 @@ title: NuGet Error NU5000 description: NU5000 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur diff --git a/docs/reference/errors-and-warnings/NU5001.md b/docs/reference/errors-and-warnings/NU5001.md index b601f4c82..c5ec558be 100644 --- a/docs/reference/errors-and-warnings/NU5001.md +++ b/docs/reference/errors-and-warnings/NU5001.md @@ -2,7 +2,7 @@ title: NuGet Error NU5001 description: NU5001 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5001 -
    Unable to output resolved nuspec file because it would overwrite the original at 'F:\project\project.nuspec'.
    +> Unable to output resolved nuspec file because it would overwrite the original at 'F:\project\project.nuspec'. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5002.md b/docs/reference/errors-and-warnings/NU5002.md index 87581f8f6..24672a3ee 100644 --- a/docs/reference/errors-and-warnings/NU5002.md +++ b/docs/reference/errors-and-warnings/NU5002.md @@ -2,7 +2,7 @@ title: NuGet Error NU5002 description: NU5002 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5002 -
    Please specify a nuspec, project.json, or project file to use.
    +> Please specify a nuspec, project.json, or project file to use. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5003.md b/docs/reference/errors-and-warnings/NU5003.md index f25dc137c..415f01851 100644 --- a/docs/reference/errors-and-warnings/NU5003.md +++ b/docs/reference/errors-and-warnings/NU5003.md @@ -2,7 +2,7 @@ title: NuGet Error NU5003 description: NU5003 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5003 -
    Failed to build package because of an unsupported targetFramework value on 'System.Net'.
    +> Failed to build package because of an unsupported targetFramework value on 'System.Net'. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5004.md b/docs/reference/errors-and-warnings/NU5004.md index 888ab115e..2e008e785 100644 --- a/docs/reference/errors-and-warnings/NU5004.md +++ b/docs/reference/errors-and-warnings/NU5004.md @@ -2,7 +2,7 @@ title: NuGet Error NU5004 description: NU5004 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5004 -
    Failed to build package. Ensure 'F:\project\project.nuspec' includes assembly files. For help on building symbols package, visit http://docs.nuget.org/.
    +> Failed to build package. Ensure 'F:\project\project.nuspec' includes assembly files. For help on building symbols package, visit https://docs.nuget.org/. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5005.md b/docs/reference/errors-and-warnings/NU5005.md index a678000d2..ef54649f9 100644 --- a/docs/reference/errors-and-warnings/NU5005.md +++ b/docs/reference/errors-and-warnings/NU5005.md @@ -2,7 +2,7 @@ title: NuGet Error NU5005 description: NU5005 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5005 -
    Ensure 'F:\project\project.nuspec' includes source and symbol files. For help on building symbols package, visit http://docs.nuget.org/.
    +> Ensure 'F:\project\project.nuspec' includes source and symbol files. For help on building symbols package, visit https://docs.nuget.org/. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5007.md b/docs/reference/errors-and-warnings/NU5007.md index bde655b85..3b499e554 100644 --- a/docs/reference/errors-and-warnings/NU5007.md +++ b/docs/reference/errors-and-warnings/NU5007.md @@ -2,7 +2,7 @@ title: NuGet Error NU5007 description: NU5007 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5007 -
    No build found in F:\project\bin\Debug\net461\project.dll. Use the -Build option or build the project.
    +> No build found in F:\project\bin\Debug\net461\project.dll. Use the -Build option or build the project. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5008.md b/docs/reference/errors-and-warnings/NU5008.md index a59290e49..c837ed1a4 100644 --- a/docs/reference/errors-and-warnings/NU5008.md +++ b/docs/reference/errors-and-warnings/NU5008.md @@ -2,7 +2,7 @@ title: NuGet Error NU5008 description: NU5008 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5008 -
    Manifest file not found at 'F:\project\project.nuspec'
    +> Manifest file not found at 'F:\project\project.nuspec' ### Issue diff --git a/docs/reference/errors-and-warnings/NU5009.md b/docs/reference/errors-and-warnings/NU5009.md index bb88502a2..792d50a34 100644 --- a/docs/reference/errors-and-warnings/NU5009.md +++ b/docs/reference/errors-and-warnings/NU5009.md @@ -2,7 +2,7 @@ title: NuGet Error NU5009 description: NU5009 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5009 -
    Cannot find version of msbuild.
    +> Cannot find version of msbuild. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5010.md b/docs/reference/errors-and-warnings/NU5010.md index 27f805fb5..15c1a66f6 100644 --- a/docs/reference/errors-and-warnings/NU5010.md +++ b/docs/reference/errors-and-warnings/NU5010.md @@ -2,7 +2,7 @@ title: NuGet Error NU5010 description: NU5010 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5010 -
    Version string specified for package reference '9.9.9.9.9' is invalid.
    +> Version string specified for package reference '9.9.9.9.9' is invalid. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5011.md b/docs/reference/errors-and-warnings/NU5011.md index a1a5d9d7a..d437c1606 100644 --- a/docs/reference/errors-and-warnings/NU5011.md +++ b/docs/reference/errors-and-warnings/NU5011.md @@ -2,7 +2,7 @@ title: NuGet Error NU5011 description: NU5011 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5011 -
    Unable to extract metadata from 'project.csproj'.
    +> Unable to extract metadata from 'project.csproj'. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5012.md b/docs/reference/errors-and-warnings/NU5012.md index d8f2379db..ee612fa1c 100644 --- a/docs/reference/errors-and-warnings/NU5012.md +++ b/docs/reference/errors-and-warnings/NU5012.md @@ -2,7 +2,7 @@ title: NuGet Error NU5012 description: NU5012 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5012 -
    Unable to find 'F:\project\bin\Debug\net461\project.dll'. Make sure the project has been built.
    +> Unable to find 'F:\project\bin\Debug\net461\project.dll'. Make sure the project has been built. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5013.md b/docs/reference/errors-and-warnings/NU5013.md index 897ef33a4..187f889be 100644 --- a/docs/reference/errors-and-warnings/NU5013.md +++ b/docs/reference/errors-and-warnings/NU5013.md @@ -2,7 +2,7 @@ title: NuGet Error NU5013 description: NU5013 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5013 -
    Failed to build 'project.csproj'
    +> Failed to build 'project.csproj' ### Issue diff --git a/docs/reference/errors-and-warnings/NU5014.md b/docs/reference/errors-and-warnings/NU5014.md index 498163c4b..cb07c53ac 100644 --- a/docs/reference/errors-and-warnings/NU5014.md +++ b/docs/reference/errors-and-warnings/NU5014.md @@ -2,7 +2,7 @@ title: NuGet Error NU5014 description: NU5014 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5014 -
    Error occurred when processing file 'F:\project2\project2.csproj': The 'id' start tag on line 4 position 10 does not match the end tag of 'ids'. Line 4, position 20.
    +> Error occurred when processing file 'F:\project2\project2.csproj': The 'id' start tag on line 4 position 10 does not match the end tag of 'ids'. Line 4, position 20. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5015.md b/docs/reference/errors-and-warnings/NU5015.md index 35e8013a2..92c082f94 100644 --- a/docs/reference/errors-and-warnings/NU5015.md +++ b/docs/reference/errors-and-warnings/NU5015.md @@ -2,7 +2,7 @@ title: NuGet Error NU5015 description: NU5015 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,14 +11,16 @@ f1_keywords: --- # NuGet Error NU5015 -
    project.json cannot contain multiple Target Frameworks.
    + +> [!WARNING] +> project.json support has been removed starting with [NuGet 7.0](../../release-notes/NuGet-7.0.md) and this error will no longer be raised. + +> project.json cannot contain multiple Target Frameworks. ### Issue The project.json file passed to NuGet pack operation contains multiple target frameworks. - ### Solution Please fix the project.json file to contain only a single target framework. - diff --git a/docs/reference/errors-and-warnings/NU5016.md b/docs/reference/errors-and-warnings/NU5016.md index c1ce1a3e6..d70ed874c 100644 --- a/docs/reference/errors-and-warnings/NU5016.md +++ b/docs/reference/errors-and-warnings/NU5016.md @@ -2,7 +2,7 @@ title: NuGet Error NU5016 description: NU5016 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5016 -
    Package version constraints for 'NuGet.Versioning' return a version range that is empty.
    +> Package version constraints for 'NuGet.Versioning' return a version range that is empty. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5017.md b/docs/reference/errors-and-warnings/NU5017.md index dc3b06f97..67a3648c8 100644 --- a/docs/reference/errors-and-warnings/NU5017.md +++ b/docs/reference/errors-and-warnings/NU5017.md @@ -2,7 +2,7 @@ title: NuGet Error NU5017 description: NU5017 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5017 -
    Cannot create a package that has no dependencies nor content.
    +> Cannot create a package that has no dependencies nor content. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5018.md b/docs/reference/errors-and-warnings/NU5018.md index 6f4109482..d505d56ac 100644 --- a/docs/reference/errors-and-warnings/NU5018.md +++ b/docs/reference/errors-and-warnings/NU5018.md @@ -2,7 +2,7 @@ title: NuGet Error NU5018 description: NU5018 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5018 -
    Invalid assembly reference 'xunit.dll'. Ensure that a file named 'xunit.dll' exists in the lib directory.
    +> Invalid assembly reference 'xunit.dll'. Ensure that a file named 'xunit.dll' exists in the lib directory. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5019.md b/docs/reference/errors-and-warnings/NU5019.md index 69e0a6138..a5195e127 100644 --- a/docs/reference/errors-and-warnings/NU5019.md +++ b/docs/reference/errors-and-warnings/NU5019.md @@ -2,7 +2,7 @@ title: NuGet Error NU5019 description: NU5019 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5019 -
     File not found: 'bad_file.path'
    +> File not found: 'bad_file.path' ### Issue diff --git a/docs/reference/errors-and-warnings/NU5020.md b/docs/reference/errors-and-warnings/NU5020.md index 3a520d84e..56c685737 100644 --- a/docs/reference/errors-and-warnings/NU5020.md +++ b/docs/reference/errors-and-warnings/NU5020.md @@ -2,7 +2,7 @@ title: NuGet Error NU5020 description: NU5020 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5020 -
    A source file was added with an empty path.
    +> A source file was added with an empty path. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5021.md b/docs/reference/errors-and-warnings/NU5021.md index fcf414f21..d419bb941 100644 --- a/docs/reference/errors-and-warnings/NU5021.md +++ b/docs/reference/errors-and-warnings/NU5021.md @@ -2,7 +2,7 @@ title: NuGet Error NU5021 description: NU5021 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5021 -
    The project directory for the source file 'src/Project/Code.cs' could not be found.
    +> The project directory for the source file 'src/Project/Code.cs' could not be found. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5022.md b/docs/reference/errors-and-warnings/NU5022.md index 0cb36ee7a..1656f4f02 100644 --- a/docs/reference/errors-and-warnings/NU5022.md +++ b/docs/reference/errors-and-warnings/NU5022.md @@ -2,7 +2,7 @@ title: NuGet Error NU5022 description: NU5022 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/8/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5022 -
    MinClient Version string specified '9.9.9.9.9' is invalid.
    +> MinClient Version string specified '9.9.9.9.9' is invalid. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5023.md b/docs/reference/errors-and-warnings/NU5023.md index d951d7c2b..9b319ac03 100644 --- a/docs/reference/errors-and-warnings/NU5023.md +++ b/docs/reference/errors-and-warnings/NU5023.md @@ -2,7 +2,7 @@ title: NuGet Error NU5023 description: NU5023 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/8/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5023 -
    The assets file produced by restore does not exist. Try restoring the project again. The expected location of the assets file is F:\project\obj\project.assets.json.
    +> The assets file produced by restore does not exist. Try restoring the project again. The expected location of the assets file is F:\project\obj\project.assets.json. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5024.md b/docs/reference/errors-and-warnings/NU5024.md index 5ec378dbe..6350658f5 100644 --- a/docs/reference/errors-and-warnings/NU5024.md +++ b/docs/reference/errors-and-warnings/NU5024.md @@ -2,7 +2,7 @@ title: NuGet Error NU5024 description: NU5024 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5024 -
    PackageVersion string specified '9.9.9.9.9' is invalid.
    +> PackageVersion string specified '9.9.9.9.9' is invalid. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5025.md b/docs/reference/errors-and-warnings/NU5025.md index 8feacb2b3..3ed29ba0d 100644 --- a/docs/reference/errors-and-warnings/NU5025.md +++ b/docs/reference/errors-and-warnings/NU5025.md @@ -2,7 +2,7 @@ title: NuGet Error NU5025 description: NU5025 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/8/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5025 -
    The assets file found does not contain a valid package spec. Try restoring the project again. The location of the assets file is F:\project\obj\project.assets.json.
    +> The assets file found does not contain a valid package spec. Try restoring the project again. The location of the assets file is F:\project\obj\project.assets.json. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5026.md b/docs/reference/errors-and-warnings/NU5026.md index 6b207d54e..b1d9917cc 100644 --- a/docs/reference/errors-and-warnings/NU5026.md +++ b/docs/reference/errors-and-warnings/NU5026.md @@ -2,7 +2,7 @@ title: NuGet Error NU5026 description: NU5026 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5026 -
    The file ''F:\project\bin\Debug\net461\project.exe' to be packed was not found on disk.
    +> The file ''F:\project\bin\Debug\net461\project.exe' to be packed was not found on disk. ### Issue @@ -24,5 +24,5 @@ Please build the project before running dotnet pack operation or do not use `--n You may have written a project that does not output assemblies. If you intend to ship an assembly-free NuGet package, disable `dotnet pack`’s requirement for an output assembly. You can do this by setting the `IncludeBuildOutput` property to `false` in your project file. -Also see [related mbuild properties](../msbuild-targets.md#output-assemblies). +Also see [related msbuild properties](../msbuild-targets.md#output-assemblies). diff --git a/docs/reference/errors-and-warnings/NU5027.md b/docs/reference/errors-and-warnings/NU5027.md index c859518c3..8effdd12b 100644 --- a/docs/reference/errors-and-warnings/NU5027.md +++ b/docs/reference/errors-and-warnings/NU5027.md @@ -2,7 +2,7 @@ title: NuGet Error NU5027 description: NU5027 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/8/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5027 -
    Invalid target framework for the file 'F:\project\project.dll'.
    +> Invalid target framework for the file 'F:\project\project.dll'. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5028.md b/docs/reference/errors-and-warnings/NU5028.md index 49cfe2bf8..2b8e8b89e 100644 --- a/docs/reference/errors-and-warnings/NU5028.md +++ b/docs/reference/errors-and-warnings/NU5028.md @@ -2,7 +2,7 @@ title: NuGet Error NU5028 description: NU5028 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/8/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5028 -
    No project was provided to the PackTask.
    +> No project was provided to the PackTask. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5029.md b/docs/reference/errors-and-warnings/NU5029.md index 3241cf882..18e600f49 100644 --- a/docs/reference/errors-and-warnings/NU5029.md +++ b/docs/reference/errors-and-warnings/NU5029.md @@ -2,7 +2,7 @@ title: NuGet Error NU5029 description: NU5029 Error code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/8/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5029 -
    NuspecProperties should be in the form of 'key1=value1;key2=value2'.
    +> NuspecProperties should be in the form of 'key1=value1;key2=value2'. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5030.md b/docs/reference/errors-and-warnings/NU5030.md index d12bef452..e7e76da82 100644 --- a/docs/reference/errors-and-warnings/NU5030.md +++ b/docs/reference/errors-and-warnings/NU5030.md @@ -10,7 +10,7 @@ f1_keywords: --- # NuGet Error NU5030 -
    The license file 'LICENSE.txt' does not exist in the package.
    +> The license file 'LICENSE.txt' does not exist in the package. ### Issue @@ -22,6 +22,7 @@ The license file is referenced in the metadata with either PackageLicenseFile in Include the file in the package, for example: If pack with the targets: + ```xml LICENSE.txt @@ -33,6 +34,7 @@ If pack with the targets: ``` If packing with a nuspec: + ```xml diff --git a/docs/reference/errors-and-warnings/NU5031.md b/docs/reference/errors-and-warnings/NU5031.md index 01ccd5ea7..e87a11e57 100644 --- a/docs/reference/errors-and-warnings/NU5031.md +++ b/docs/reference/errors-and-warnings/NU5031.md @@ -10,7 +10,7 @@ f1_keywords: --- # NuGet Error NU5031 -
    The license file 'LICENSE.txt' has an invalid extension. Valid options are .txt, .md or none.
    +> The license file 'LICENSE.txt' has an invalid extension. Valid options are .txt, .md or none. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5032.md b/docs/reference/errors-and-warnings/NU5032.md index fc9428664..886e4c77e 100644 --- a/docs/reference/errors-and-warnings/NU5032.md +++ b/docs/reference/errors-and-warnings/NU5032.md @@ -10,7 +10,7 @@ f1_keywords: --- # NuGet Error NU5032 -
    The license expression 'MIT OR OR Apache-2.0' cannot be parsed succesfully. The license expression is invalid.
    +> The license expression 'MIT OR OR Apache-2.0' cannot be parsed succesfully. The license expression is invalid. ### Issue @@ -20,6 +20,7 @@ The license expression does not conform to the NuGet license expression grammar. In this case there are 2 'OR' operators. The operators have to be surrounded with operands. For example: + ``` MIT OR Apache-2.0 -``` \ No newline at end of file +``` diff --git a/docs/reference/errors-and-warnings/NU5033.md b/docs/reference/errors-and-warnings/NU5033.md index 3569d58db..0840e32dd 100644 --- a/docs/reference/errors-and-warnings/NU5033.md +++ b/docs/reference/errors-and-warnings/NU5033.md @@ -10,7 +10,7 @@ f1_keywords: --- # NuGet Error NU5033 -
    Invalid metadata. Cannot specify both a License Expression and a License File.
    +> Invalid metadata. Cannot specify both a License Expression and a License File. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5034.md b/docs/reference/errors-and-warnings/NU5034.md index 1db56fd9e..e44ae8707 100644 --- a/docs/reference/errors-and-warnings/NU5034.md +++ b/docs/reference/errors-and-warnings/NU5034.md @@ -10,7 +10,7 @@ f1_keywords: --- # NuGet Error NU5034 -
    The PackageLicenseExpressionVersion string '2.0.0-InvalidSystemVersion' is not a valid version.
    +> The PackageLicenseExpressionVersion string '2.0.0-InvalidSystemVersion' is not a valid version. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5035.md b/docs/reference/errors-and-warnings/NU5035.md index 472e217be..d2b8aa165 100644 --- a/docs/reference/errors-and-warnings/NU5035.md +++ b/docs/reference/errors-and-warnings/NU5035.md @@ -10,7 +10,7 @@ f1_keywords: --- # NuGet Error NU5035 -
    The PackageLicenseUrl cannot be used in conjunction with the PackageLicenseFile and PackageLicenseExpression.
    +> The PackageLicenseUrl cannot be used in conjunction with the PackageLicenseFile and PackageLicenseExpression. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5036.md b/docs/reference/errors-and-warnings/NU5036.md index 405c7a57f..bd3f14d75 100644 --- a/docs/reference/errors-and-warnings/NU5036.md +++ b/docs/reference/errors-and-warnings/NU5036.md @@ -2,7 +2,7 @@ title: NuGet Error NU5036 description: NU5036 Error code author: rrelyea -ms.author: karann +ms.author: jodou ms.date: 8/8/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Error NU5036 -
    This package has an improperly escaped Url in LicenseUrl
    +> This package has an improperly escaped Url in LicenseUrl ### Issue diff --git a/docs/reference/errors-and-warnings/NU5037.md b/docs/reference/errors-and-warnings/NU5037.md index 5904d395d..bf74dc5c8 100644 --- a/docs/reference/errors-and-warnings/NU5037.md +++ b/docs/reference/errors-and-warnings/NU5037.md @@ -11,7 +11,8 @@ f1_keywords: --- # NuGet Error NU5037 -
    The package is missing the required nuspec file.
    + +> The package is missing the required nuspec file. ### Issue @@ -28,13 +29,13 @@ Contact the package author. ## Scenario 2 Restore fails for a project managed with the `PackageReference` format. For example: -``` -The package is missing the required nuspec file. Path: C:\.\.\.nuget\packages\x\1.0.0.'x' represents package name and '1.0.0' represents package version. -``` + +> The package is missing the required nuspec file. Path: C:\.\.\.nuget\packages\x\1.0.0.'x' represents package name and '1.0.0' represents package version. ### Solution Delete the package folder specified in the error message and run the restore again. For example: + ``` Consider sample error message specified in the above section. Delete the package folder '1.0.0' from 'C:\.\.\.nuget\packages\x' directory and run the restore again. diff --git a/docs/reference/errors-and-warnings/NU5038.md b/docs/reference/errors-and-warnings/NU5038.md new file mode 100644 index 000000000..282d1f988 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU5038.md @@ -0,0 +1,22 @@ +--- +title: NuGet Error NU5038 +description: NU5038 Error code +author: nkolev92 +ms.author: nikolev +ms.date: 7/28/2020 +ms.topic: reference +ms.reviewer: +f1_keywords: + - NU5038 +--- + +# NuGet Error NU5038 +> The readme file 'readme.txt' has an invalid extension. It must end in .md. + +### Issue + +The readme file must be a markdown file, and must end in '*.md*'. + +### Solution + +Use a markdown file extension for the readme file. \ No newline at end of file diff --git a/docs/reference/errors-and-warnings/NU5039.md b/docs/reference/errors-and-warnings/NU5039.md new file mode 100644 index 000000000..ddc6034f1 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU5039.md @@ -0,0 +1,62 @@ +--- +title: NuGet Error NU5039 +description: NU5039 Error code +author: nkolev92 +ms.author: nikolev +ms.date: 7/28/2020 +ms.topic: reference +ms.reviewer: +f1_keywords: + - NU5039 +--- + +# NuGet Error NU5039 + +> The readme file 'readme.md' does not exist in the package. + + +### Issue + +NuGet is unable to find the readme file in the package. + + +### Solution + +- Make sure that the file that is marked as the package readme exists at the source and it is readable, and the target matches the path expected by the `readme` property. +- Ensure that the file is referenced in the nuspec or in the project file. + * When creating a package from an MSBuild project file, make sure to reference the readme file in the project, as follows: + + ```xml + + + ... + readme.md + ... + + + + ... + + ... + + + ``` + + * When you are creating a package from a nuspec file, make sure to include the readme file in the `` section: + + ```xml + + + ... + docs\readme.md + ... + + + ... + + ... + + + ``` + +[Learn more about packaging a readme file](../msbuild-targets.md#packagereadmefile). diff --git a/docs/reference/errors-and-warnings/NU5040.md b/docs/reference/errors-and-warnings/NU5040.md new file mode 100644 index 000000000..de314e8bb --- /dev/null +++ b/docs/reference/errors-and-warnings/NU5040.md @@ -0,0 +1,25 @@ +--- +title: NuGet Error NU5040 +description: NU5040 Error code +author: nkolev92 +ms.author: nikolev +ms.date: 7/28/2020 +ms.topic: reference +ms.reviewer: +f1_keywords: + - NU5040 +--- + +# NuGet Error NU5040 + +> The readme file 'readme.md' is empty. + + +### Issue + +The file that is specified as the package readme is empty. + + +### Solution + +Populate the contents of the readme file. diff --git a/docs/reference/errors-and-warnings/NU5041.md b/docs/reference/errors-and-warnings/NU5041.md new file mode 100644 index 000000000..a6278fb0c --- /dev/null +++ b/docs/reference/errors-and-warnings/NU5041.md @@ -0,0 +1,62 @@ +--- +title: NuGet Error NU5041 +description: NU5041 Error code +author: nkolev92 +ms.author: nikolev +ms.date: 7/28/2020 +ms.topic: reference +ms.reviewer: +f1_keywords: + - NU5041 +--- + +# NuGet Error NU5041 + +> Cannot open the readme file 'readme.md' + + +### Issue + +NuGet is unable to find and open the readme file in the package. + + +### Solution + +- Make sure that the file that is marked as the package readme exists at the source and it is readable, and the target matches the path expected by the `readme` property. +- Ensure that the file is referenced in the nuspec or in the project file. + * When creating a package from an MSBuild project file, make sure to reference the readme file in the project, as follows: + + ```xml + + + ... + readme.md + ... + + + + ... + + ... + + + ``` + + * When you are creating a package from a nuspec file, make sure to include the readme file in the `` section: + + ```xml + + + ... + docs\readme.md + ... + + + ... + + ... + + + ``` + +[Learn more about packaging a readme file](../msbuild-targets.md#packagereadmefile). diff --git a/docs/reference/errors-and-warnings/NU5042.md b/docs/reference/errors-and-warnings/NU5042.md new file mode 100644 index 000000000..9fd147aa3 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU5042.md @@ -0,0 +1,27 @@ +--- +title: NuGet Error NU5042 +description: NU5042 error code +author: nkolev92 +ms.author: nikolev +ms.date: 11/07/2022 +ms.topic: reference +f1_keywords: + - "NU5042" +--- + +# NuGet Error NU5042 (Obsolete) + +> [!WARNING] +> project.json support has been removed starting with [NuGet 7.0](../../release-notes/NuGet-7.0.md) and this error will no longer be raised. + +> `project.json` pack is disabled in the current NuGet version, and will be permanently removed in a future version. +> Please consider migrating 'MyProject' to `PackageReference` and using the pack targets. +> You can set the 'NUGET_ENABLE_LEGACY_PROJECT_JSON_PACK' environment variable to 'true' to temporarily reenable this functionality. + +### Issue + +NuGet.exe pack for project.json projects is not supported. + +### Solution + +[Migrate your project to PackageReference](../../archive/project-json.md#migrate-projectjson-to-packagereference) and use the pack targets instead. diff --git a/docs/reference/errors-and-warnings/NU5045.md b/docs/reference/errors-and-warnings/NU5045.md new file mode 100644 index 000000000..897e0f521 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU5045.md @@ -0,0 +1,21 @@ +--- +title: NuGet Error NU5045 +description: NU5045 Error code +author: nkolev92 +ms.date: 02/02/2022 +ms.topic: reference +f1_keywords: + - NU5045 +--- + +# NuGet Warning NU5045 + +> The 'icon' element 'icon.svg' has an invalid file extension. Valid options are .png, .jpg or .jpeg. + +### Issue + +The icon file provided does not have a supported extension. + +### Solution + +Consult the options in the error message and use one of those file types. diff --git a/docs/reference/errors-and-warnings/NU5046.md b/docs/reference/errors-and-warnings/NU5046.md index aa0130d9d..5825565ee 100644 --- a/docs/reference/errors-and-warnings/NU5046.md +++ b/docs/reference/errors-and-warnings/NU5046.md @@ -1,8 +1,8 @@ --- title: NuGet Error NU5046 description: NU5046 Error code -author: dominoFire -ms.author: feaguila +author: JonDouglas +ms.author: jodou ms.date: 9/4/2019 ms.topic: reference ms.reviewer: karann @@ -12,7 +12,7 @@ f1_keywords: # NuGet Error NU5046 -
    The icon file 'icon.png' does not exist in the package.
    +> The icon file 'icon.png' does not exist in the package. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5047.md b/docs/reference/errors-and-warnings/NU5047.md index dc8604639..44a3a86e2 100644 --- a/docs/reference/errors-and-warnings/NU5047.md +++ b/docs/reference/errors-and-warnings/NU5047.md @@ -1,8 +1,8 @@ --- title: NuGet Error NU5047 description: NU5047 Error code -author: dominoFire -ms.author: feaguila +author: JonDouglas +ms.author: jodou ms.date: 9/4/2019 ms.topic: reference ms.reviewer: karann @@ -12,7 +12,7 @@ f1_keywords: # NuGet Error NU5047 -
    The icon file size must not exceed 1 megabyte.
    +> The icon file size must not exceed 1 megabyte. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5048.md b/docs/reference/errors-and-warnings/NU5048.md index 26340e502..e948b398b 100644 --- a/docs/reference/errors-and-warnings/NU5048.md +++ b/docs/reference/errors-and-warnings/NU5048.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5048 description: NU5048 Warning code author: dominoFire -ms.author: feaguila +ms.author: jodou ms.date: 9/4/2019 ms.topic: reference ms.reviewer: karann @@ -12,7 +12,7 @@ f1_keywords: # NuGet Warning NU5048 -
    The 'PackageIconUrl'/'iconUrl' element is deprecated. Consider using the 'PackageIcon'/'icon' element instead. Learn more at https://aka.ms/deprecateIconUrl
    +> The 'PackageIconUrl'/'iconUrl' element is deprecated. Consider using the 'PackageIcon'/'icon' element instead. Learn more at https://aka.ms/deprecateIconUrl ### Issue diff --git a/docs/reference/errors-and-warnings/NU5049.md b/docs/reference/errors-and-warnings/NU5049.md new file mode 100644 index 000000000..4e186a366 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU5049.md @@ -0,0 +1,23 @@ +--- +title: NuGet Error NU5049 +description: NU5049 error code +author: nkolev92 +ms.author: nikolev +ms.date: 11/07/2022 +ms.topic: reference +f1_keywords: + - "NU5049" +--- + +# NuGet Error NU5049 + +> The `pack` command for SDK-style projects is not supported, use `dotnet pack` or `msbuild -t:pack` to pack this project instead. You can override this behavior by setting the 'NUGET_ENABLE_LEGACY_CSPROJ_PACK' environment variable to 'true'. + +### Issue + +NuGet.exe pack should not be used to generate packages for SDK-style projects. + +### Solution + +Use `dotnet pack` or `msbuild -t:pack` instead. +It recommended that you do not use the legacy csproj pack experience as it generates incomplete packages. diff --git a/docs/reference/errors-and-warnings/NU5100.md b/docs/reference/errors-and-warnings/NU5100.md index cd9185e7b..fe9fa082b 100644 --- a/docs/reference/errors-and-warnings/NU5100.md +++ b/docs/reference/errors-and-warnings/NU5100.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5100 description: NU5100 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5100 -
    The assembly 'bin\Debug\net461\project.dll' is not inside the 'lib' folder and hence it won't be added as a reference when the package is installed into a project. Move it into the 'lib' folder if it needs to be referenced.
    +> The assembly 'bin\Debug\net461\project.dll' is not inside the 'lib' folder and hence it won't be added as a reference when the package is installed into a project. Move it into the 'lib' folder if it needs to be referenced. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5101.md b/docs/reference/errors-and-warnings/NU5101.md index 8b459ef35..4f884638b 100644 --- a/docs/reference/errors-and-warnings/NU5101.md +++ b/docs/reference/errors-and-warnings/NU5101.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5101 description: NU5101 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -13,7 +13,7 @@ f1_keywords: # NuGet Warning NU5101 ## Scenario 1 -
    The assembly 'lib\project.dll' is placed directly under 'lib' folder. It is recommended that assemblies be placed inside a framework-specific folder. Move it into a framework-specific folder.
    +> The assembly 'lib\project.dll' is placed directly under 'lib' folder. It is recommended that assemblies be placed inside a framework-specific folder. Move it into a framework-specific folder. ### Issue @@ -26,7 +26,7 @@ While packaging a folder please ensure that all assembly files are placed inside ## Scenario 2 -
    The assembly 'lib\project.dll' will be ignored when the package is installed after the migration.
    +> The assembly 'lib\project.dll' will be ignored when the package is installed after the migration. ### Issue @@ -35,6 +35,4 @@ The package contains an assembly file that is directly under a `lib` folder. The ### Solution -Please request the package author to fix the package such that all assemblies are placed inside a framework-specific folder under a `lib` folder. You can read more about it in [NuGet docs](https://docs.microsoft.com/en-us/nuget/consume-packages/migrate-packages-config-to-package-reference). - - +Please request the package author to fix the package such that all assemblies are placed inside a framework-specific folder under a `lib` folder. You can read more about it in [NuGet docs](../../consume-packages/migrate-packages-config-to-package-reference.md). diff --git a/docs/reference/errors-and-warnings/NU5102.md b/docs/reference/errors-and-warnings/NU5102.md index 679baadc9..c95d23f99 100644 --- a/docs/reference/errors-and-warnings/NU5102.md +++ b/docs/reference/errors-and-warnings/NU5102.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5102 description: NU5102 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/8/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5102 -
    The value "http://project_url_here_or_delete_this_line/" for ProjectUrl is a sample value and should be removed. Replace it with an appropriate value or remove it and rebuild your package.
    +> The value "http://project_url_here_or_delete_this_line/" for ProjectUrl is a sample value and should be removed. Replace it with an appropriate value or remove it and rebuild your package. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5103.md b/docs/reference/errors-and-warnings/NU5103.md index 3e6a6ef48..ab9bd4c60 100644 --- a/docs/reference/errors-and-warnings/NU5103.md +++ b/docs/reference/errors-and-warnings/NU5103.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5103 description: NU5103 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/8/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5103 -
    The folder 'lib\random_tfm\temp.dll' under 'lib' is not recognized as a valid framework name or a supported culture identifier. Rename it to a valid framework name or culture identifier.
    +> The folder 'lib\random_tfm\temp.dll' under 'lib' is not recognized as a valid framework name or a supported culture identifier. Rename it to a valid framework name or culture identifier. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5104.md b/docs/reference/errors-and-warnings/NU5104.md index b374c1fc9..a25e8b315 100644 --- a/docs/reference/errors-and-warnings/NU5104.md +++ b/docs/reference/errors-and-warnings/NU5104.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5104 description: NU5104 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/8/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5104 -
    A stable release of a package should not have a prerelease dependency. Either modify the version spec of dependency "NuGet.Versioning [4.7.0-preview4.5065, )" or update the version field in the nuspec.
    +> A stable release of a package should not have a prerelease dependency. Either modify the version spec of dependency "NuGet.Versioning [4.7.0-preview4.5065, )" or update the version field in the nuspec. ### Issue @@ -22,3 +22,5 @@ The project or nuspec being packaged contains a dependency on a prerelease packa If you intend to create a prerelease package then please refer to SemVer2 guidelines and add a prerelease tag to the version property i.e. `1.0.0-pre`. If you intend to create a stable package then please update the specified dependency version to a stable version. +> [!NOTE] +> Mixing stable and prerelease packages may lead to unexpected behaviors at resolution time. Learn more about how [PackageReference](../../concepts/Dependency-Resolution.md#version-ranges-and-prerelease-versions-with-packagereference) and [packages.config](../../concepts/Dependency-Resolution.md#version-ranges-and-prerelease-versions-with-packagesconfig) projects handle this resolution. diff --git a/docs/reference/errors-and-warnings/NU5105.md b/docs/reference/errors-and-warnings/NU5105.md index d209f2b2c..da447a0c9 100644 --- a/docs/reference/errors-and-warnings/NU5105.md +++ b/docs/reference/errors-and-warnings/NU5105.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5105 description: NU5105 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/8/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5105 -
    The package version '1.2.3+semver2.metadata' uses SemVer 2.0.0 or components of SemVer 1.0.0 that are not supported on legacy clients. Change the package version to a SemVer 1.0.0 string. If the version contains a release label it must start with a letter. This message can be ignored if the package is not intended for older clients.
    +> The package version '1.2.3+semver2.metadata' uses SemVer 2.0.0 or components of SemVer 1.0.0 that are not supported on legacy clients. Change the package version to a SemVer 1.0.0 string. If the version contains a release label it must start with a letter. This message can be ignored if the package is not intended for older clients. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5106.md b/docs/reference/errors-and-warnings/NU5106.md index b4f7ec336..637373f03 100644 --- a/docs/reference/errors-and-warnings/NU5106.md +++ b/docs/reference/errors-and-warnings/NU5106.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5106 description: NU5106 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5106 -
    The file at 'lib\WinRT\temp.dll' uses the obsolete 'WinRT' as the framework folder. Replace 'WinRT' or 'WinRT45' with 'NetCore45'.
    +> The file at 'lib\WinRT\temp.dll' uses the obsolete 'WinRT' as the framework folder. Replace 'WinRT' or 'WinRT45' with 'NetCore45'. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5107.md b/docs/reference/errors-and-warnings/NU5107.md index a431df062..3ae39e017 100644 --- a/docs/reference/errors-and-warnings/NU5107.md +++ b/docs/reference/errors-and-warnings/NU5107.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5107 description: NU5107 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5107 -
    The file 'tools/subfolder/init.ps1' will be ignored by NuGet because it is not directly under 'tools' folder. Place the file directly under 'tools' folder.
    +> The file 'tools/subfolder/init.ps1' will be ignored by NuGet because it is not directly under 'tools' folder. Place the file directly under 'tools' folder. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5108.md b/docs/reference/errors-and-warnings/NU5108.md index 117581e97..ce801cc36 100644 --- a/docs/reference/errors-and-warnings/NU5108.md +++ b/docs/reference/errors-and-warnings/NU5108.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5108 description: NU5108 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5108 -
    The transform file 'other\code.pp' is outside the 'content' folder and hence will not be transformed during installation of this package. Move it into the 'content' folder.
    +> The transform file 'other\code.pp' is outside the 'content' folder and hence will not be transformed during installation of this package. Move it into the 'content' folder. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5109.md b/docs/reference/errors-and-warnings/NU5109.md index 4938d5d74..9641ff624 100644 --- a/docs/reference/errors-and-warnings/NU5109.md +++ b/docs/reference/errors-and-warnings/NU5109.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5109 description: NU5109 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5109 -
    The file at 'tools/_._' uses the symbol for empty directory '_._', but it is present in a directory that contains other files. Please remove this file from directories that contain other files.
    +> The file at 'tools/_._' uses the symbol for empty directory '_._', but it is present in a directory that contains other files. Please remove this file from directories that contain other files. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5110.md b/docs/reference/errors-and-warnings/NU5110.md index 7f4c635b8..191f63eab 100644 --- a/docs/reference/errors-and-warnings/NU5110.md +++ b/docs/reference/errors-and-warnings/NU5110.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5110 description: NU5110 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5110 -
    The script file 'other\init.ps1' is outside the 'tools' folder and hence will not be executed during installation of this package. Move it into the 'tools' folder.
    +> The script file 'other\init.ps1' is outside the 'tools' folder and hence will not be executed during installation of this package. Move it into the 'tools' folder. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5111.md b/docs/reference/errors-and-warnings/NU5111.md index d2bb3c732..fee3943e9 100644 --- a/docs/reference/errors-and-warnings/NU5111.md +++ b/docs/reference/errors-and-warnings/NU5111.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5111 description: NU5111 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5111 -
    The script file 'tools\random.ps1' is not recognized by NuGet and hence will not be executed during installation of this package. Rename it to install.ps1, uninstall.ps1 or init.ps1 and place it directly under 'tools'.
    +> The script file 'tools\random.ps1' is not recognized by NuGet and hence will not be executed during installation of this package. Rename it to install.ps1, uninstall.ps1 or init.ps1 and place it directly under 'tools'. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5112.md b/docs/reference/errors-and-warnings/NU5112.md index 7b48f4217..8b77a6fed 100644 --- a/docs/reference/errors-and-warnings/NU5112.md +++ b/docs/reference/errors-and-warnings/NU5112.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5112 description: NU5112 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5112 -
    The version of dependency 'NuGet.Versioning' is not specified. Specify the version of dependency and rebuild your package.
    +> The version of dependency 'NuGet.Versioning' is not specified. Specify the version of dependency and rebuild your package. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5114.md b/docs/reference/errors-and-warnings/NU5114.md index 4bda02de6..4a5d32b9b 100644 --- a/docs/reference/errors-and-warnings/NU5114.md +++ b/docs/reference/errors-and-warnings/NU5114.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5114 description: NU5114 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5114 -
    'SolutionDir' key already exists in Properties collection. Overriding value.
    +> 'SolutionDir' key already exists in Properties collection. Overriding value. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5115.md b/docs/reference/errors-and-warnings/NU5115.md index 7fee74c19..d9c6a8a3d 100644 --- a/docs/reference/errors-and-warnings/NU5115.md +++ b/docs/reference/errors-and-warnings/NU5115.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5115 description: NU5115 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5115 -
    Description was not specified. Using 'Description'.
    +> Description was not specified. Using 'Description'. ### Issue @@ -20,5 +20,5 @@ A property was not specified to the pack command, hence a default value was chos ### Solution -Please scpecify the mentioned property in the csproj as an msbuild property if using project file or in the nuspec file. +Please specify the mentioned property in the csproj as an msbuild property if using project file or in the nuspec file. diff --git a/docs/reference/errors-and-warnings/NU5116.md b/docs/reference/errors-and-warnings/NU5116.md index c92faef3d..469fbfc1a 100644 --- a/docs/reference/errors-and-warnings/NU5116.md +++ b/docs/reference/errors-and-warnings/NU5116.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5116 description: NU5116 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5116 -
     'Content\sample.txt' was included in the project but doesn't exist. Skipping...
    +> 'Content\sample.txt' was included in the project but doesn't exist. Skipping... ### Issue diff --git a/docs/reference/errors-and-warnings/NU5117.md b/docs/reference/errors-and-warnings/NU5117.md index d6f59dc04..187fb6c8b 100644 --- a/docs/reference/errors-and-warnings/NU5117.md +++ b/docs/reference/errors-and-warnings/NU5117.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5117 description: NU5117 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5117 -
     '$(MSBuildProjectDirectory)/tools/sample.txt' was included in the project but the path could not be resolved. Skipping...
    +> '$(MSBuildProjectDirectory)/tools/sample.txt' was included in the project but the path could not be resolved. Skipping... ### Issue diff --git a/docs/reference/errors-and-warnings/NU5118.md b/docs/reference/errors-and-warnings/NU5118.md index 763d47810..99b5e5242 100644 --- a/docs/reference/errors-and-warnings/NU5118.md +++ b/docs/reference/errors-and-warnings/NU5118.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5118 description: NU5118 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5118 -
    File 'F :\validation\test\proj\tools\readme.1.txt' is not added because the package already contains file 'tools\readme.txt'
    +> File 'F :\validation\test\proj\tools\readme.1.txt' is not added because the package already contains file 'tools\readme.txt' ### Issue diff --git a/docs/reference/errors-and-warnings/NU5119.md b/docs/reference/errors-and-warnings/NU5119.md index 82f997107..8b92ad1fa 100644 --- a/docs/reference/errors-and-warnings/NU5119.md +++ b/docs/reference/errors-and-warnings/NU5119.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5119 description: NU5119 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5119 -
    File 'F:\project\binary\Libuv.1.10.0.nupkg' was not added to the package. Files and folders starting with '.' or ending with '.nupkg' are excluded by default. To include this file, use -NoDefaultExcludes from the commandline
    +> File 'F:\project\binary\Libuv.1.10.0.nupkg' was not added to the package. Files and folders starting with '.' or ending with '.nupkg' are excluded by default. To include this file, use -NoDefaultExcludes from the commandline ### Issue @@ -20,5 +20,5 @@ The NuGet pack operation found a `.nupkg` file or a file/folder starting with `. ### Solution -If you intent to package a `.nupkg` file or a file/folder starting with `.` then please use `-NoDefaultExcludes` property to allow the packaging of those files/folders. +If you intend to package a `.nupkg` file or a file/folder starting with `.` then please use `-NoDefaultExcludes` property to allow the packaging of those files/folders. diff --git a/docs/reference/errors-and-warnings/NU5120.md b/docs/reference/errors-and-warnings/NU5120.md index 4551e2db4..18e7a1db9 100644 --- a/docs/reference/errors-and-warnings/NU5120.md +++ b/docs/reference/errors-and-warnings/NU5120.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5120 description: NU5120 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5120 -
    install.ps1 script will be ignored when the package is installed after the migration.
    +> install.ps1 script will be ignored when the package is installed after the migration. ### Issue @@ -20,5 +20,4 @@ The package contains an `install.ps1` file. The file will not be executed if the ### Solution -Please request the package author to fix the package such that it no longer contains an `install.ps1` file. You can read more about it in [NuGet docs](https://docs.microsoft.com/en-us/nuget/consume-packages/migrate-packages-config-to-package-reference). - +Please request the package author to fix the package such that it no longer contains an `install.ps1` file. You can read more about it in [NuGet docs](../../consume-packages/migrate-packages-config-to-package-reference.md). diff --git a/docs/reference/errors-and-warnings/NU5121.md b/docs/reference/errors-and-warnings/NU5121.md index eca5524c2..f2a3aeb8f 100644 --- a/docs/reference/errors-and-warnings/NU5121.md +++ b/docs/reference/errors-and-warnings/NU5121.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5121 description: NU5121 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5121 -
     'content' assets will not be available when the package is installed after the migration.
    +> 'content' assets will not be available when the package is installed after the migration. ### Issue @@ -20,5 +20,4 @@ The package contains an files under a `Content` folder. These assets will not be ### Solution -Please request the package author to fix the package such that it no longer contains an `Content` foler. You can read more about it in [NuGet docs](https://docs.microsoft.com/en-us/nuget/consume-packages/migrate-packages-config-to-package-reference). - +Please request the package author to fix the package such that it no longer contains an `Content` foler. You can read more about it in [NuGet docs](../../consume-packages/migrate-packages-config-to-package-reference.md). diff --git a/docs/reference/errors-and-warnings/NU5122.md b/docs/reference/errors-and-warnings/NU5122.md index 85ffead1c..01a31181a 100644 --- a/docs/reference/errors-and-warnings/NU5122.md +++ b/docs/reference/errors-and-warnings/NU5122.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5122 description: NU5122 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5122 -
    XDT transform file 'tools/transform.xdt' will not be applied when the package is installed after the migration.
    +> XDT transform file 'tools/transform.xdt' will not be applied when the package is installed after the migration. ### Issue @@ -20,5 +20,4 @@ The package contains an assembly file that is not under a target framework speci ### Solution -Please request the package author to fix the package such that it no longer contains an `install.ps1` file. You can read more about it in [NuGet docs](https://docs.microsoft.com/en-us/nuget/consume-packages/migrate-packages-config-to-package-reference). - +Please request the package author to fix the package such that it no longer contains an `install.ps1` file. You can read more about it in [NuGet docs](../../consume-packages/migrate-packages-config-to-package-reference.md). diff --git a/docs/reference/errors-and-warnings/NU5123.md b/docs/reference/errors-and-warnings/NU5123.md index b1886d552..3ac6486ea 100644 --- a/docs/reference/errors-and-warnings/NU5123.md +++ b/docs/reference/errors-and-warnings/NU5123.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5123 description: NU5123 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/14/2018 ms.topic: reference ms.reviewer: anangaur @@ -11,7 +11,7 @@ f1_keywords: --- # NuGet Warning NU5123 -
    The file 'content//readme.txt' path, name, or both are too long. Your package might not work without long file path support. Please shorten the file path or file name.
    +> The file 'content/<LongPath>/readme.txt' path, name, or both are too long. Your package might not work without long file path support. Please shorten the file path or file name. ### Issue @@ -20,5 +20,5 @@ A file was detected to have an installed path of longer than 200 characters. Ins ### Solution -Please ensure that the path `//target_file_path` for all the files included in the package are lesser than 200 characters, where `target_file_path` is defined in the `target` property of the`` section in the nuspec file. +Please ensure that the path `//target_file_path` for all the files included in the package are less than 200 characters, where `target_file_path` is defined in the `target` property of the`` section in the nuspec file. diff --git a/docs/reference/errors-and-warnings/NU5124.md b/docs/reference/errors-and-warnings/NU5124.md index 39fcaec77..522840ba3 100644 --- a/docs/reference/errors-and-warnings/NU5124.md +++ b/docs/reference/errors-and-warnings/NU5124.md @@ -10,7 +10,7 @@ f1_keywords: --- # NuGet Warning NU5124 -
    The license identifier 'Microsoft-SpecialLicense' is not recognized by the current toolset.
    +> The license identifier 'Microsoft-SpecialLicense' is not recognized by the current toolset. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5125.md b/docs/reference/errors-and-warnings/NU5125.md index d6a21b797..313f74c7a 100644 --- a/docs/reference/errors-and-warnings/NU5125.md +++ b/docs/reference/errors-and-warnings/NU5125.md @@ -10,7 +10,7 @@ f1_keywords: --- # NuGet Warning NU5125 -
    The 'licenseUrl' element will be deprecated. Consider using the 'license' element instead.
    +> The 'licenseUrl' element will be deprecated. Consider using the 'license' element instead. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5126.md b/docs/reference/errors-and-warnings/NU5126.md new file mode 100644 index 000000000..43224ecb2 --- /dev/null +++ b/docs/reference/errors-and-warnings/NU5126.md @@ -0,0 +1,21 @@ +--- +title: NuGet Error NU5126 +description: NU5126 Error code +author: nkolev92 +ms.date: 02/02/2022 +ms.topic: reference +f1_keywords: + - NU5126 +--- + +# NuGet Warning NU5126 + +> `project.json` pack is deprecated. Please consider migrating '{0}' to `PackageReference` and using the pack targets + +### Issue + +`project.json` as a package management style is no longer actively developed and was replaced by PackageReference and [pack targets](../msbuild-targets.md). + +### Solution + +Migrate your package management style to [PackageReference](../../consume-packages/package-references-in-project-files.md) and use the [pack targets](../msbuild-targets.md). diff --git a/docs/reference/errors-and-warnings/NU5127.md b/docs/reference/errors-and-warnings/NU5127.md index 8e1ba098f..5e50a7523 100644 --- a/docs/reference/errors-and-warnings/NU5127.md +++ b/docs/reference/errors-and-warnings/NU5127.md @@ -2,23 +2,31 @@ title: NuGet Warning NU5127 description: NU5127 Warning code author: zivkan -ms.date: 09/20/2019 +ms.date: 05/05/2025 ms.topic: reference -ms.reviewer: karann f1_keywords: - NU5127 --- # NuGet Warning NU5127 -
    This package does not contain a lib/ or ref/ folder, and will therefore be treated as compatible for all frameworks. Since framework specific files were found under the build/ directory for net45, netstandard2.0, consider creating the following empty files to correctly narrow the compatibility of the package:
--lib/net45/_._
--lib/netstandard2.0/_._
    +> This package does not contain a lib/ or ref/ folder, and will therefore be treated as compatible for all frameworks. Since framework specific files were found under the build/ directory for net45, netstandard2.0, consider creating the following empty files to correctly narrow the compatibility of the package:
    +> -lib/net45/_._
    +> -lib/netstandard2.0/_._ ### Issue -Projects using packages with `PackageReference` only use `lib/` and `ref/` assemblies to determine package compatibility. Therefore, a package without any `lib/` or `ref/` files will be considered compatible with all projects. However, if that package contains build files specific to one or more [Target Framework Monikers (TFMs)](../target-frameworks.md), a package consumer may expect the package to fail if none of the build files are used. +Projects using packages with `PackageReference` only use `lib/` and `ref/` assemblies to determine package compatibility. +Therefore, a package without any `lib/` or `ref/` files will be considered compatible with all projects. +However, packages containing MSBuild props or targets that are specific to one or more target frameworks show intent in only being compatible with those target frameworks. + +For example, consider a package `PackageA` contains a single file, `build/net8.0/PackageA.targets`. +If this package is referenced by a project targeting `net48` (.NET Framework, Version 4.8), NuGet will not emit any warnings or errors, but also will not select any assets from the package. +Therefore, the package consumer will not be notified that the package does not work correctly with their project. ### Solution -As the warning message suggests, create an empty file named `_._` in the lib folder for the TFMs listed. This will allow NuGet to fail the restore for `PackageReference` projects when the project is incompatible with the package. +As the warning message suggests, create an empty file named `_._` in the lib folder for the TFMs listed. +This will allow NuGet to fail the restore for `PackageReference` projects when the project is incompatible with the package. + +If your package is intended to be compatible with all target frameworks, but only take effect for certain target frameworks, create a file `build/{PackageId}.props` whose contents are ``. diff --git a/docs/reference/errors-and-warnings/NU5128.md b/docs/reference/errors-and-warnings/NU5128.md index 1d0703f94..c2b14d33a 100644 --- a/docs/reference/errors-and-warnings/NU5128.md +++ b/docs/reference/errors-and-warnings/NU5128.md @@ -13,8 +13,8 @@ f1_keywords: ## Scenario 1 -
    Some target frameworks declared in the dependencies group of the nuspec and the lib/ref folder do not have exact matches in the other location. Consult the list of actions below:
-- Add a dependency group for .NETStandard2.0 to the nuspec
    +> Some target frameworks declared in the dependencies group of the nuspec and the lib/ref folder do not have exact matches in the other location. Consult the list of actions below: +> - Add a dependency group for .NETStandard2.0 to the nuspec ### Issue @@ -41,7 +41,7 @@ Note that the TFM identifier used in the assembly paths use a different format t     ... - + ``` * Remove the `lib/` or `ref/` files @@ -50,8 +50,8 @@ If you do not wish your package to be compatible with the reported TFM, modify y ## Scenario 2 -
    Some target frameworks declared in the dependencies group of the nuspec and the lib/ref folder do not have exact matches in the other location. Consult the list of actions below:
-- Add lib or ref assemblies for the netstandard2.0 target framework
    +> Some target frameworks declared in the dependencies group of the nuspec and the lib/ref folder do not have exact matches in the other location. Consult the list of actions below: +> - Add lib or ref assemblies for the netstandard2.0 target framework ### Issue diff --git a/docs/reference/errors-and-warnings/NU5129.md b/docs/reference/errors-and-warnings/NU5129.md index 35129d7c6..3e75b385f 100644 --- a/docs/reference/errors-and-warnings/NU5129.md +++ b/docs/reference/errors-and-warnings/NU5129.md @@ -11,7 +11,7 @@ f1_keywords: # NuGet Warning NU5129 -
    At least one . file was found in '//', but '//.' was not.
    +> At least one .<extension> file was found in '<build_folder>/<tfm>/', but '<build_folder>/<tfm>/<package_id>.<extension>' was not. `` is one of: `targets`, `props`. `` is one of: `build`, `buildTransitive`, `buildCrossTargeting`, `buildMultiTargeting`. @@ -20,13 +20,16 @@ f1_keywords: Examples: -``` -At least one .targets file was found in 'build/netstandard2.0/', but 'build/netstandard2.0/MyPackage.targets' was not. -At least one .props file was found in 'build/netstandard2.0/', but 'build/netstandard2.0/MyPackage.props' was not. -At least one .props file was found in 'buildTransitive/net472/', but 'buildTransitive/net472/My.Package.Id.props' was not. -At least one .targets file was found in 'buildMultitargeting/netcoreapp3.0/', but 'buildMultitargeting/netcoreapp3.0/Contoso.Utilities.targets' was not. -At least one .props file was found in 'build/', but 'build/AdventureWorks.Tools.props' was not. -``` +> At least one .targets file was found in 'build/netstandard2.0/', but 'build/netstandard2.0/MyPackage.targets' was not. + +> At least one .props file was found in 'build/netstandard2.0/', but 'build/netstandard2.0/MyPackage.props' was not. + +> At least one .props file was found in 'buildTransitive/net472/', but 'buildTransitive/net472/My.Package.Id.props' was not. + +> At least one .targets file was found in 'buildMultitargeting/netcoreapp3.0/', but 'buildMultitargeting/netcoreapp3.0/Contoso.Utilities. +targets' was not. + +> At least one .props file was found in 'build/', but 'build/AdventureWorks.Tools.props' was not. ### Issue diff --git a/docs/reference/errors-and-warnings/NU5130.md b/docs/reference/errors-and-warnings/NU5130.md index e04d10328..af139a88a 100644 --- a/docs/reference/errors-and-warnings/NU5130.md +++ b/docs/reference/errors-and-warnings/NU5130.md @@ -11,8 +11,8 @@ f1_keywords: # NuGet Warning NU5130 -
    Some target frameworks declared in the dependencies group of the nuspec and the lib/ref folder have compatible matches, but not exact matches in the other location. Unless intentional, consult the list of actions below:
-- Add a dependency group for .NETFramework4.7.2 to the nuspec
    +> Some target frameworks declared in the dependencies group of the nuspec and the lib/ref folder have compatible matches, but not exact matches in the other location. Unless intentional, consult the list of actions below: +> - Add a dependency group for .NETFramework4.7.2 to the nuspec ### Issue diff --git a/docs/reference/errors-and-warnings/NU5131.md b/docs/reference/errors-and-warnings/NU5131.md index 22f090e87..26953b57d 100644 --- a/docs/reference/errors-and-warnings/NU5131.md +++ b/docs/reference/errors-and-warnings/NU5131.md @@ -11,12 +11,12 @@ f1_keywords: # NuGet Warning NU5131 -
    References were found in the nuspec, but some reference assemblies were not found in both the nuspec and ref folder. Add the following reference assemblies:
-- Add AssemblyName.dll to the ref/net472/ directory
    +> References were found in the nuspec, but some reference assemblies were not found in both the nuspec and ref folder. Add the following reference assemblies: +> - Add AssemblyName.dll to the ref/net472/ directory ### Issue -NuGet has a feature to allow package authors to [select which assemblies will be available at compile time](https://docs.microsoft.com/en-gb/nuget/create-packages/select-assemblies-referenced-by-projects) in projects that use the package. +NuGet has a feature to allow package authors to [select which assemblies will be available at compile time](../../create-packages/Select-assemblies-referenced-by-projects.md) in projects that use the package. If the required conventions are not followed, projects using the package with `PackageReference` may fail at runtime due to missing assemblies. @@ -43,7 +43,7 @@ The package author wants to prevent package consumers from writing code that dir     ``` -This works for projects using the package with `packages.config`, but to work as intended with `ProjectReference`, the project must also contain the following files: +This package will not work as intended when using `PackageReference`. To fix this, the package must also contain the following files: ```text ref\net472\MyLib.dll diff --git a/docs/reference/errors-and-warnings/NU5133.md b/docs/reference/errors-and-warnings/NU5133.md new file mode 100644 index 000000000..ea8282dda --- /dev/null +++ b/docs/reference/errors-and-warnings/NU5133.md @@ -0,0 +1,36 @@ +--- +title: NuGet Warning NU5133 +description: NU5133 Warning code +author: erdembayar +ms.author: eryondon +ms.date: 03/18/2022 +ms.topic: reference +ms.reviewer: +f1_keywords: + - NU5133 +--- + +# NuGet Warning NU5133 + +## Example + +> Warning NU5133: NuGet.exe file on path \Downloads\nuget.exe needs to be unblocked after downloading. + +### Issue +When downloading a file on Windows, in this case nuget.exe, through a web browser, the `Mark Of The Web` may be added. +This makes Windows consider that flag as potentially dangerous despite coming from a well known source such as nuget.org. +As a consequence some `nuget.exe pack` operations may work incorrectly. + +### Solution 1 +Right click on your downloaded copy of `nuget.exe` and select "Properties". + + ![NuGet Properties](../media/NuGetProperties.png) + +Now tick the `Unblock` then press apply. + + ![NuGet Unblock](../media/NuGetUnblock.png) + +Now try again the pack operation. + +### Solution 2 +From powershell terminal run `Unblock-File -Path .\Solution\nuget.exe` diff --git a/docs/reference/errors-and-warnings/NU5500.md b/docs/reference/errors-and-warnings/NU5500.md index 5259bd4cf..70b2b9401 100644 --- a/docs/reference/errors-and-warnings/NU5500.md +++ b/docs/reference/errors-and-warnings/NU5500.md @@ -2,7 +2,7 @@ title: NuGet Warning NU5500 description: NU5500 Warning code author: mishra14 -ms.author: karann +ms.author: jodou ms.date: 8/3/2018 ms.topic: reference ms.reviewer: anangaur @@ -14,7 +14,7 @@ f1_keywords: ### Issue -The NuGet pack operation had a problem. NU5000 is used when we haven't yet assigned a unique warning code for that issue. So we can improve, please feel free to file the issue with details of your error. +The NuGet pack operation had a problem. NU5500 is used when we haven't yet assigned a unique warning code for that issue. So we can improve, please feel free to file the issue with details of your error. ### Solution diff --git a/docs/reference/errors-and-warnings/NU5501.md b/docs/reference/errors-and-warnings/NU5501.md new file mode 100644 index 000000000..0df5db23b --- /dev/null +++ b/docs/reference/errors-and-warnings/NU5501.md @@ -0,0 +1,89 @@ +--- +title: NuGet Warning NU5501 +description: NU5501 Warning code +author: zkat +ms.author: kmarchan +ms.date: 10/6/2020 +ms.topic: reference +ms.reviewer: TBD +f1_keywords: + - NU5501 +--- + +# NuGet Warning NU5501 + +## Scenario 1 + +> The following dependency group(s) require(s) dots in the framework version: net50-windows7.0 + +### Issue + +The dependency group framework must included dots in their framework version number. This is required for frameworks newer than `net5.0`. + +This issue generally occurs when a nuspec is authored manually, like for example: + +```xml + + + + + + + +``` + +### Solution + +Change `net50` to `net5.0`. + +```xml + + + + + + + +``` + +## Scenario 2 + +> The following packaged file folder(s) require(s) dots in the framework version: contentFiles/any/net50/a.img. + +### Issue + +The folders denoting a framework must included dots in their framework version number. This is required for frameworks newer than `net5.0`. + +This issue generally occurs when manually adding items to a package, using something like the following in your `.csproj`: + +```xml + + + +``` + +or a nuspec: + +```xml + + + +``` + +### Solution + +Change `net50` to `net5.0`. + +```xml + + + +``` + +or the nuspec: + +```xml + + + +``` diff --git a/docs/reference/extensibility/NuGet-Credential-Providers-for-Visual-Studio.md b/docs/reference/extensibility/NuGet-Credential-Providers-for-Visual-Studio.md index 7cc759ae8..e567da4aa 100644 --- a/docs/reference/extensibility/NuGet-Credential-Providers-for-Visual-Studio.md +++ b/docs/reference/extensibility/NuGet-Credential-Providers-for-Visual-Studio.md @@ -1,10 +1,10 @@ --- title: NuGet credential providers for Visual Studio description: NuGet credential providers authenticate with feeds by implementing the IVsCredentialProvider interface in a Visual Studio extension. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/09/2017 -ms.topic: conceptual +ms.topic: how-to --- # Authenticating feeds in Visual Studio with NuGet credential providers @@ -12,26 +12,18 @@ ms.topic: conceptual The NuGet Visual Studio Extension 3.6+ supports credential providers, which enable NuGet to work with authenticated feeds. After you install a NuGet credential provider for Visual Studio, the NuGet Visual Studio extension will automatically acquire and refresh credentials for authenticated feeds as necessary. -A sample implementation can be found in [the VsCredentialProvider sample](https://github.com/NuGet/Samples/tree/master/VsCredentialProvider). +A sample implementation can be found in [the VsCredentialProvider sample](https://github.com/NuGet/Samples/tree/main/VsCredentialProvider). + +Within Visual Studio, NuGet uses an internal `VsCredentialProviderImporter` which also scans for plug-in credential providers. These plug-in credential providers must be discoverable as a MEF Export of type `IVsCredentialProvider`. Starting with 4.8+ NuGet in Visual Studio supports the new cross platform authentication plugins as well, but they are not the recommended approach for performance reasons. > [!Note] -> NuGet credential providers for Visual Studio must be installed as a regular Visual Studio extension and will require [Visual Studio 2017](http://aka.ms/vs/15/release/vs_enterprise.exe) or above. +> NuGet credential providers for Visual Studio must be installed as a regular Visual Studio extension and will require [Visual Studio 2017](https://aka.ms/vs/15/release/vs_enterprise.exe) or above. > > NuGet credential providers for Visual Studio work only in Visual Studio (not in dotnet restore or nuget.exe). For credential providers with nuget.exe, see [nuget.exe Credential Providers](nuget-exe-Credential-providers.md). > For credential providers in dotnet and msbuild see [NuGet cross platform plugins](nuget-cross-platform-authentication-plugin.md) -## Available NuGet credential providers for Visual Studio - -There is a credential provider built into the Visual Studio NuGet extension to support Visual Studio Team Services. - -The NuGet Visual Studio Extension uses an internal `VsCredentialProviderImporter` which also scans for plug-in credential providers. These plug-in credential providers must be discoverable as a MEF Export of type `IVsCredentialProvider`. - -Available plug-in credential providers include: - -- [MyGet Credential Provider for Visual Studio](http://docs.myget.org/docs/reference/credential-provider-for-visual-studio) - ## Creating a NuGet credential provider for Visual Studio The NuGet Visual Studio Extension 3.6+ implements an internal CredentialService that is used to acquire credentials. The CredentialService has a list of built-in and plug-in credential providers. Each provider is tried sequentially until credentials are acquired. @@ -39,8 +31,7 @@ The NuGet Visual Studio Extension 3.6+ implements an internal CredentialService During credential acquisition, the credential service will try credential providers in the following order, stopping as soon as credentials are acquired: 1. Credentials will be fetched from NuGet configuration files (using the built-in `SettingsCredentialProvider`). -1. If the package source is on Visual Studio Team Services, the `VisualStudioAccountProvider` will be used. -1. All other plug-in Visual Studio credential providers will be tried sequentially. +1. Visual Studio credential providers will be tried sequentially. 1. Try to use all NuGet cross platform credential providers sequentially. 1. If no credentials have been acquired yet, the user will be prompted for credentials using a standard basic authentication dialog. @@ -61,7 +52,7 @@ public interface IVsCredentialProvider } ``` -A sample implementation can be found in [the VsCredentialProvider sample](https://github.com/NuGet/Samples/tree/master/VsCredentialProvider). +A sample implementation can be found in [the VsCredentialProvider sample](https://github.com/NuGet/Samples/tree/main/VsCredentialProvider). Each NuGet credential provider for Visual Studio must: @@ -81,4 +72,4 @@ A custom NuGet credential provider for Visual Studio must implement the `IVsCred | bool nonInteractive | If true, the credential provider must suppress all user prompts and use default values instead. | | CancellationToken cancellationToken | This cancellation token should be checked to determine if the operation requesting credentials has been cancelled. | -**Return value**: A credentials object implementing the [`System.Net.ICredentials` interface](/dotnet/api/system.net.icredentials?view=netstandard-2.0). +**Return value**: A credentials object implementing the [`System.Net.ICredentials` interface](/dotnet/api/system.net.icredentials). diff --git a/docs/reference/extensibility/NuGet-Cross-Platform-Authentication-Plugin.md b/docs/reference/extensibility/NuGet-Cross-Platform-Authentication-Plugin.md index a0e8d027b..624db0a23 100644 --- a/docs/reference/extensibility/NuGet-Cross-Platform-Authentication-Plugin.md +++ b/docs/reference/extensibility/NuGet-Cross-Platform-Authentication-Plugin.md @@ -4,7 +4,7 @@ description: NuGet cross platform authentication plugins for NuGet.exe, dotnet.e author: nkolev92 ms.author: nikolev ms.date: 07/01/2018 -ms.topic: conceptual +ms.topic: article --- # NuGet cross platform authentication plugin @@ -58,10 +58,14 @@ The following table summarizes how the plugin should behave for all combinations | IsNonInteractive | CanShowDialog | Plugin behavior | | ---------------- | ------------- | --------------- | -| true | true | The IsNonInteractive switch takes precedence over the dialog switch. The plugin is not allowed to pop a dialog. This combination is only valid for .NET Framework plugins | -| true | false | The IsNonInteractive switch takes precedence over the dialog switch. The plugin is not allowed to block. This combination is only valid for .NET Core plugins | -| false | true | The plugin should show a dialog. This combination is only valid for .NET Framework plugins | -| false | false | The plugin should/can not show a dialog. The plugin should use device flow to authenticate by logging an instruction message via the logger. This combination is only valid for .NET Core plugins | +| true | true | The IsNonInteractive switch takes precedence over the dialog switch. The plugin is not allowed to block. | +| true | false | The IsNonInteractive switch takes precedence over the dialog switch. The plugin is not allowed to block. | +| false | true | The plugin can show a dialog if required. For example, interactive login, or account selection. | +| false | false | The plugin should/can not show a dialog. The plugin should use device flow to authenticate by logging an instruction message via the logger. | + +Prior to [NuGet 7.0](../../release-notes/NuGet-7.0.md), NuGet would always set `CanShowDialog` to false on the dotnet CLI, and true for MSBuild restore. +From 7.0, NuGet will always set `CanShowDialog` to true, but plugins should still detect when graphical interfaces are not available. +For example when running on Linux over an SSH connection without X forwarding, or a PowerShell remote session. Please refer to the following specs before writing a plugin. diff --git a/docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md b/docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md index da664fcea..3fd832a9e 100644 --- a/docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md +++ b/docs/reference/extensibility/NuGet-Cross-Platform-Plugins.md @@ -4,7 +4,7 @@ description: NuGet cross platform plugins for NuGet.exe, dotnet.exe, msbuild.exe author: nkolev92 ms.author: nikolev ms.date: 07/01/2018 -ms.topic: conceptual +ms.topic: article --- # NuGet cross platform plugins @@ -12,20 +12,11 @@ ms.topic: conceptual In NuGet 4.8+ support for cross platform plugins has been added. This was achieved with by building a new plugin extensibility model, that has to conform to a strict set of rules of operation. The plugins are self-contained executables (runnables in the .NET Core world), that the NuGet Clients launch in a separate process. -This is a true write once, run everywhere plugin. It will work with all NuGet client tools. -The plugins can be either .NET Framework (NuGet.exe, MSBuild.exe and Visual Studio), or .NET Core (dotnet.exe). -A versioned communication protocol between the NuGet Client and the plugin is defined. During the startup handshake, the 2 processes negotiate the protocol version. - -In order to cover all NuGet client tools scenarios, one would need both a .NET Framework and a .NET Core plugin. -The below describes the client/framework combinations of the plugins. - -| Client tool | Framework | -| ------------ | --------- | -| Visual Studio | .NET Framework | -| dotnet.exe | .NET Core | -| NuGet.exe | .NET Framework | -| MSBuild.exe | .NET Framework | -| NuGet.exe on Mono | .NET Framework | +This is a true write once, run everywhere plugin. +It will work with all NuGet client tools. +The plugins can be written in any programming language, but the easiest plugin development and installation experience will be with .NET. +A versioned communication protocol between the NuGet Client and the plugin is defined. +During the startup handshake, the 2 processes negotiate the protocol version. ## How does it work @@ -41,17 +32,22 @@ The high level workflow can be described as follows: The current protocol version is *2.0.0*. Under this version, the requirements are as follows: -- Have a valid, trusted Authenticode signature assemblies that will run on Windows and Mono. There is no special trust requirement for assemblies run on Linux and Mac yet. [Relevant issue](https://github.com/NuGet/Home/issues/6702) - Support stateless launching under the current security context of NuGet client tools. For example, NuGet client tools will not perform elevation or additional initialization outside of the plugin protocol described later. - Be non interactive, unless explicitly specified. - Adhere to the negotiated plugin protocol version. - Respond to all requests within a reasonable time period. - Honor cancellation requests for any in-progress operation. +Plugins discovered from the PATH environment variable (for example, installed via `dotnet tool`) additionally must match the filename pattern `nuget-plugin-*`. +The `nuget-plugin-` part must be written entirely in lowercase letters. + +NuGet 6.12 (MSBuild 17.12, and .NET SDK 9.0.100) and earlier also required plugins to be Authenticode signed on Windows. + The technical specification is described in more detail in the following specs: - [NuGet Package Download Plugin](https://github.com/NuGet/Home/wiki/NuGet-Package-Download-Plugin) - [NuGet cross plat authentication plugin](https://github.com/NuGet/Home/wiki/NuGet-cross-plat-authentication-plugin) +- [Dotnet Tools Plugins](https://github.com/NuGet/Home/blob/dev/accepted/2024/support-nuget-authentication-plugins-dotnet-tools.md) ## Client - Plugin interaction @@ -65,23 +61,27 @@ After 1 minute of inactivity a plugin is considered idle and is shut down. ## Plugin installation and discovery -The plugins will be discovered via a convention based directory structure. -CI/CD scenarios and power users can use environment variables to override the behavior. Note that `NUGET_NETFX_PLUGIN_PATHS` and `NUGET_NETCORE_PLUGIN_PATHS` are only available with 5.3+ version of the NuGet tooling and later. +NuGet searches for plugins from a convention based directory structure, and scanning the PATH environment variable. + +### Convention based discovery + +CI/CD scenarios and power users can use environment variables to override the behavior. +When using environment variables, only absolute paths are allowed. Note that `NUGET_NETFX_PLUGIN_PATHS` and `NUGET_NETCORE_PLUGIN_PATHS` are only available with 5.3+ version of the NuGet tooling and later. - `NUGET_NETFX_PLUGIN_PATHS` - defines the plugins that will be used by the .NET Framework based tooling (NuGet.exe/MSBuild.exe/Visual Studio). Takes precedence over `NUGET_PLUGIN_PATHS`. (NuGet version 5.3+ only) - `NUGET_NETCORE_PLUGIN_PATHS` - defines the plugins that will be used by the .NET Core based tooling (dotnet.exe). Takes precedence over `NUGET_PLUGIN_PATHS`. (NuGet version 5.3+ only) -- `NUGET_PLUGIN_PATHS` - defines the plugins that will be used for that NuGet process, priority reserved. If this environment variable is set, it overrides the convention based discovery. Ignored if either of the framework specific variables is specified. -- User-location, the NuGet Home location in `%UserProfile%/.nuget/plugins`. This location cannot be overriden. A different root directory will be used for .NET Core and .NET Framework plugins. +- `NUGET_PLUGIN_PATHS` - defines the plugins that will be used for that NuGet process, priority preserved. If this environment variable is set, it overrides the convention based discovery. Ignored if either of the framework specific variables is specified. +- User-location, the NuGet Home location in `%UserProfile%/.nuget/plugins`. This location cannot be overridden. A different root directory will be used for .NET Core and .NET Framework plugins. -| Framework | Root discovery location | -| ------- | ------------------------ | -| .NET Core | `%UserProfile%/.nuget/plugins/netcore` | -| .NET Framework | `%UserProfile%/.nuget/plugins/netfx` | +| Framework | Root discovery location | Used by | +| ------- | ------------------------ | ---- | +| .NET Core | `%UserProfile%/.nuget/plugins/netcore` | dotnet CLI | +| .NET Framework | `%UserProfile%/.nuget/plugins/netfx` | MSBuild, NuGet.exe, Visual Studio | Each plugin should be installed in its own folder. The plugin entry point will be the name of the installed folder, with the .dll extensions for .NET Core, and .exe extension for .NET Framework. -``` +```text .nuget plugins netfx @@ -96,8 +96,17 @@ The plugin entry point will be the name of the installed folder, with the .dll e ... ``` -> [!Note] -> There is currently no user story for the installation of the plugins. It's as simple as moving the required files into the predetermined location. +### PATH discovery + +Starting from [NuGet 6.13](../../release-notes/NuGet-6.13.md), NuGet will search each directory provided in the PATH environment variable for files matching the pattern `nuget-plugin-*`. +The pattern matching is case-sensitive, and `nuget-plugin-` must be written entirely in lowercase letters. +On Windows the file must have an `.exe` or `.bat` extension. +On Linux and Mac the file must have the executable bit set. + +This allows NuGet plugins to be installed via `dotnet tool` commands, WinGet, a Linux distribution's package manager, or any other method that can put executables on the user's PATH. +This also allows NuGet plugins to be written in any programming language (previously plugins for Linux and Mac must be written in .NET). + +We recommend plugins are developed in .NET, so that you can use the [NuGet.Protocol package](https://www.nuget.org/packages/NuGet.Protocol) to avoid needing to write the json RPC code, and to allow customers to discover your plugin via `dotnet package search nuget-plugin`. ## Supported operations diff --git a/docs/reference/extensibility/nuget-exe-Credential-Providers.md b/docs/reference/extensibility/nuget-exe-Credential-Providers.md index c6b6d1995..b0242a3b1 100644 --- a/docs/reference/extensibility/nuget-exe-Credential-Providers.md +++ b/docs/reference/extensibility/nuget-exe-Credential-Providers.md @@ -1,23 +1,19 @@ --- title: nuget.exe Credential Providers description: nuget.exe credential providers authenticate with a feed, and are implemented as command-line executables that follow specific conventions. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 12/12/2017 -ms.topic: conceptual +ms.topic: concept-article --- # Authenticating feeds with nuget.exe credential providers -*NuGet 3.3+* +In version `3.3` support was added for `nuget.exe` specific (v1) credential providers. Since then, in version `4.8` [support for (v2) credential providers](NuGet-Cross-Platform-Authentication-Plugin.md) that work across all command line scenarios (`nuget.exe`, `dotnet.exe`, `msbuild.exe`) was added. -When `nuget.exe` needs credentials to authenticate with a feed, it looks for them in the following manner: +See [Consuming Packages from authenticated feeds](../../consume-packages/consuming-packages-authenticated-feeds.md) for more details on all authentication approaches. -1. NuGet first looks for credentials in `Nuget.Config` files. -1. NuGet then uses plug-in credential providers, subject to the order given below. (And example is the [Visual Studio Team Services Credential Provider](https://www.visualstudio.com/docs/package/get-started/nuget/auth#vsts-credential-provider).) -1. NuGet then prompts the user for credentials on the command line. - -Note that the credential providers described here work only in `nuget.exe` and not in 'dotnet restore' or Visual Studio. For credential providers with Visual Studio, see [nuget.exe Credential Providers for Visual Studio](nuget-credential-providers-for-visual-studio.md) +## nuget.exe credential provider discovery nuget.exe credential providers can be used in 3 ways: @@ -36,7 +32,7 @@ A credential provider is a command-line executable, named in the form `Credentia A provider must do the following: - Determine whether it can provide credentials for the targeted URI before initiating credential acquisition. If not, it should return status code 1 with no credentials. -- Not modify `Nuget.Config` (such as setting credentials there). +- Not modify `NuGet.Config` (such as setting credentials there). - Handle HTTP proxy configuration on its own, as NuGet does not provide proxy information to the plugin. - Return credentials or error details to `nuget.exe` by writing a JSON response object (see below) to stdout, using UTF-8 encoding. - Optionally emit additional trace logging to stderr. No secrets should ever be written to stderr, since at verbosity levels "normal" or "detailed" such traces are echoed by NuGet to the console. @@ -69,9 +65,11 @@ A provider must do the following: Example stdout: - { "Username" : "freddy@example.com", - "Password" : "bwm3bcx6txhprzmxhl2x63mdsul6grctazoomtdb6kfbof7m3a3z", - "Message" : "" } +``` +{ "Username" : "freddy@example.com", + "Password" : "bwm3bcx6txhprzmxhl2x63mdsul6grctazoomtdb6kfbof7m3a3z", + "Message" : "" } +``` ## Troubleshooting a credential provider @@ -91,5 +89,3 @@ You can also do the following: } Debugger.Break(); ``` - -For further help, [submit a support request a nuget.org](https://www.nuget.org/policies/Contact). diff --git a/docs/reference/media/NuGetProperties.png b/docs/reference/media/NuGetProperties.png new file mode 100644 index 000000000..12e960b18 Binary files /dev/null and b/docs/reference/media/NuGetProperties.png differ diff --git a/docs/reference/media/NuGetUnblock.png b/docs/reference/media/NuGetUnblock.png new file mode 100644 index 000000000..92979e09b Binary files /dev/null and b/docs/reference/media/NuGetUnblock.png differ diff --git a/docs/reference/media/registered-certs.png b/docs/reference/media/registered-certs.png index 39a20e9eb..2b9cc1b64 100644 Binary files a/docs/reference/media/registered-certs.png and b/docs/reference/media/registered-certs.png differ diff --git a/docs/reference/msbuild-targets.md b/docs/reference/msbuild-targets.md index 294ec9fed..b4601c9c3 100644 --- a/docs/reference/msbuild-targets.md +++ b/docs/reference/msbuild-targets.md @@ -1,10 +1,11 @@ --- title: NuGet pack and restore as MSBuild targets description: NuGet pack and restore can work directly as MSBuild targets with NuGet 4.0+. -author: karann-msft -ms.author: karann -ms.date: 03/23/2018 -ms.topic: conceptual +author: nkolev92 +ms.author: nikolev +ms.date: 2/4/2022 +ms.topic: article +no-loc: [NuGet, MSBuild, .nuspec, nuspec] --- # NuGet pack and restore as MSBuild targets @@ -17,7 +18,7 @@ With MSBuild 15.1+, NuGet is also a first-class MSBuild citizen with the `pack` ## Target build order -Because `pack` and `restore` are MSBuild targets, you can access them to enhance your workflow. For example, let’s say you want to copy your package to a network share after packing it. You can do that by adding the following in your project file: +Because `pack` and `restore` are MSBuild targets, you can access them to enhance your workflow. For example, let's say you want to copy your package to a network share after packing it. You can do that by adding the following in your project file: ```xml @@ -35,90 +36,104 @@ Similarly, you can write an MSBuild task, write your own target and consume NuGe ## pack target -For .NET Standard projects using the PackageReference format, using `msbuild -t:pack` draws inputs from the project file to use in creating a NuGet package. +For .NET projects that use the `PackageReference` format, using `msbuild -t:pack` draws inputs from the project file to use in creating a NuGet package. -The table below describes the MSBuild properties that can be added to a project file within the first `` node. You can make these edits easily in Visual Studio 2017 and later by right-clicking the project and selecting **Edit {project_name}** on the context menu. For convenience the table is organized by the equivalent property in a [`.nuspec` file](../reference/nuspec.md). +Non-SDK-style projects will need to install the NuGet.Build.Tasks.Pack package when using Visual Studio 2022 or earlier. +We recommend uninstalling this package when upgrading to Visual Studio 2026 to ensure your project can use the latest pack features and bug fixes. -Note that the `Owners` and `Summary` properties from `.nuspec` are not supported with MSBuild. +The following table describes the MSBuild properties that can be added to a project file within the first `` node. You can make these edits easily in Visual Studio 2017 and later by right-clicking the project and selecting **Edit {project_name}** on the context menu. For convenience, the table is organized by the equivalent property in a [`.nuspec` file](../reference/nuspec.md). -| Attribute/NuSpec Value | MSBuild Property | Default | Notes | +> [!NOTE] +> `Owners` and `Summary` properties from `.nuspec` are not supported with MSBuild. + +| Attribute/nuspec Value | MSBuild Property | Default | Notes | |--------|--------|--------|--------| -| Id | PackageId | AssemblyName | $(AssemblyName) from MSBuild | -| Version | PackageVersion | Version | This is semver compatible, for example “1.0.0”, “1.0.0-beta”, or “1.0.0-beta-00345” | -| VersionPrefix | PackageVersionPrefix | empty | Setting PackageVersion overwrites PackageVersionPrefix | -| VersionSuffix | PackageVersionSuffix | empty | $(VersionSuffix) from MSBuild. Setting PackageVersion overwrites PackageVersionSuffix | -| Authors | Authors | Username of the current user | | -| Owners | N/A | Not present in NuSpec | | -| Title | Title | The PackageId| | -| Description | Description | "Package Description" | | -| Copyright | Copyright | empty | | -| RequireLicenseAcceptance | PackageRequireLicenseAcceptance | false | | -| license | PackageLicenseExpression | empty | Corresponds to `` | -| license | PackageLicenseFile | empty | Corresponds to ``. You may need to explicitly pack the referenced license file. | -| LicenseUrl | PackageLicenseUrl | empty | `PackageLicenseUrl` is deprecated, use the PackageLicenseExpression or PackageLicenseFile property | -| ProjectUrl | PackageProjectUrl | empty | | -| Icon | PackageIcon | empty | You may need to explicitly pack the referenced icon image file.| -| IconUrl | PackageIconUrl | empty | `PackageIconUrl` is deprecated, use the PackageIcon property | -| Tags | PackageTags | empty | Tags are semi-colon delimited. | -| ReleaseNotes | PackageReleaseNotes | empty | | -| Repository/Url | RepositoryUrl | empty | Repository URL used to clone or retrieve source code. Example: *https://github.com/NuGet/NuGet.Client.git* | -| Repository/Type | RepositoryType | empty | Repository type. Examples: *git*, *tfs*. | -| Repository/Branch | RepositoryBranch | empty | Optional repository branch information. *RepositoryUrl* must also be specified for this property to be included. Example: *master* (NuGet 4.7.0+) | -| Repository/Commit | RepositoryCommit | empty | Optional repository commit or changeset to indicate which source the package was built against. *RepositoryUrl* must also be specified for this property to be included. Example: *0e4d1b598f350b3dc675018d539114d1328189ef* (NuGet 4.7.0+) | -| PackageType | `DotNetCliTool, 1.0.0.0;Dependency, 2.0.0.0` | | | -| Summary | Not supported | | | +| `Id` | `PackageId` | `$(AssemblyName)` | `$(AssemblyName)` from MSBuild | +| `Version` | `PackageVersion` | Version | This is semver compatible, for example `1.0.0`, `1.0.0-beta`, or `1.0.0-beta-00345`. Defaults to `Version` if not set. | +| `VersionPrefix` | `VersionPrefix` | empty | Setting `PackageVersion` overwrites `VersionPrefix` | +| `VersionSuffix` | `VersionSuffix` | empty | Setting `PackageVersion` overwrites `VersionSuffix` | +| `Authors` | `Authors` | Username of the current user | A semicolon-separated list of packages authors, matching the profile names on nuget.org. These are displayed in the NuGet Gallery on nuget.org and are used to cross-reference packages by the same authors. | +| `Owners` | N/A | Not present in nuspec | +| `Title` | `Title` | `$(PackageId)` | A human-friendly title of the package, typically used in UI displays as on nuget.org and the Package Manager in Visual Studio. | +| `Description` | `Description` | "Package Description" | A long description for the assembly. If `PackageDescription` is not specified, then this property is also used as the description of the package. | +| `Copyright` | `Copyright` | empty | Copyright details for the package. | +| `RequireLicenseAcceptance` | `PackageRequireLicenseAcceptance` | `false` | A Boolean value that specifies whether the client must prompt the consumer to accept the package license before installing the package. | +| `license` | `PackageLicenseExpression` | empty | Corresponds to ``. See [Packing a license expression or a license file](#packing-a-license-expression-or-a-license-file). | +| `license` | `PackageLicenseFile` | empty | Path to a license file within the package if you're using a custom license or a license that hasn't been assigned an SPDX identifier. You need to explicitly pack the referenced license file. Corresponds to ``. See [Packing a license expression or a license file](#packing-a-license-expression-or-a-license-file). | +| `LicenseUrl` | `PackageLicenseUrl` | empty | `PackageLicenseUrl` is deprecated. Use `PackageLicenseExpression` or `PackageLicenseFile` instead. | +| `ProjectUrl` | `PackageProjectUrl` | empty | | +| `Icon` | `PackageIcon` | empty | A path to an image in the package to use as a package icon. You need to explicitly pack the referenced icon image file. For more information, see [Packing an icon image file](#packing-an-icon-image-file) and [`icon` metadata](./nuspec.md#icon). | +| `IconUrl` | `PackageIconUrl` | empty | `PackageIconUrl` is deprecated in favor of `PackageIcon`. However, for the best downlevel experience, you should specify `PackageIconUrl` in addition to `PackageIcon`. | +| `Readme` | `PackageReadmeFile` | empty | You need to explicitly pack the referenced readme file.| +| `Tags` | `PackageTags` | empty | A semicolon-delimited list of tags that designates the package. | +| `ReleaseNotes` | `PackageReleaseNotes` | empty | Release notes for the package. | +| `Repository/Url` | `RepositoryUrl` | empty | Repository URL used to clone or retrieve source code. Example: *https://github.com/NuGet/NuGet.Client.git*. | +| `Repository/Type` | `RepositoryType` | empty | Repository type. Examples: `git` (default), `tfs`. | +| `Repository/Branch` | `RepositoryBranch` | empty | Optional repository branch information. `RepositoryUrl` must also be specified for this property to be included. Example: *master* (NuGet 4.7.0+). | +| `Repository/Commit` | `RepositoryCommit` | empty | Optional repository commit or changeset to indicate which source the package was built against. `RepositoryUrl` must also be specified for this property to be included. Example: *0e4d1b598f350b3dc675018d539114d1328189ef* (NuGet 4.7.0+). | +| `PackageType` | `CustomType1, 1.0.0.0;CustomType2` | | Indicates the package's intended use. Package types use the same format as package IDs and are delimited by `;`. Package types may be versioned by appending a `,` and a [`Version`](/dotnet/api/system.version) string. See [Set a NuGet package type](../create-packages/set-package-type.md) (NuGet 3.5.0+). | +| `Summary` | Not supported | | | ### pack target inputs -- IsPackable -- SuppressDependenciesWhenPacking -- PackageVersion -- PackageId -- Authors -- Description -- Copyright -- PackageRequireLicenseAcceptance -- DevelopmentDependency -- PackageLicenseExpression -- PackageLicenseFile -- PackageLicenseUrl -- PackageProjectUrl -- PackageIconUrl -- PackageReleaseNotes -- PackageTags -- PackageOutputPath -- IncludeSymbols -- IncludeSource -- PackageTypes -- IsTool -- RepositoryUrl -- RepositoryType -- RepositoryBranch -- RepositoryCommit -- NoPackageAnalysis -- MinClientVersion -- IncludeBuildOutput -- IncludeContentInPack -- BuildOutputTargetFolder -- ContentTargetFolders -- NuspecFile -- NuspecBasePath -- NuspecProperties +| Property | Description | +| - | - | +| `IsPackable` | A Boolean value that specifies whether the project can be packed. The default value is `true`. | +| `SuppressDependenciesWhenPacking` | Set to `true` to suppress package dependencies from the generated NuGet package. | +| `PackageVersion` | Specifies the version that the resulting package will have. Accepts all forms of NuGet version string. Default is the value of `$(Version)`, that is, of the property `Version` in the project. | +| `PackageId` | Specifies the name for the resulting package. If not specified, the `pack` operation will default to using the `AssemblyName` or directory name as the name of the package. | +| `PackageDescription` | A long description of the package for UI display. | +| `Authors` | A semicolon-separated list of packages authors, matching the profile names on nuget.org. These are displayed in the NuGet Gallery on nuget.org and are used to cross-reference packages by the same authors. | +| `Description` | A long description for the assembly. If `PackageDescription` is not specified, then this property is also used as the description of the package. | +| `Copyright` | Copyright details for the package. | +| `PackageRequireLicenseAcceptance` | A Boolean value that specifies whether the client must prompt the consumer to accept the package license before installing the package. The default is `false`. | +| `DevelopmentDependency` | A Boolean value that specifies whether the package is marked as a development-only dependency, which prevents the package from being included as a dependency in other packages. With `PackageReference` (NuGet 4.8+), this flag also means that compile-time assets are excluded from compilation. For more information, see [DevelopmentDependency support for PackageReference](https://github.com/NuGet/Home/wiki/DevelopmentDependency-support-for-PackageReference). | +| `PackageLicenseExpression` | An [SPDX license identifier](https://spdx.org/licenses/) or expression, for example, `Apache-2.0`. For more information, see [Packing a license expression or a license file](#packing-a-license-expression-or-a-license-file). | +| `PackageLicenseFile` | Path to a license file within the package if you're using a custom license or a license that hasn't been assigned an SPDX identifier. | +| `PackageLicenseUrl` | `PackageLicenseUrl` is deprecated. Use `PackageLicenseExpression` or `PackageLicenseFile` instead. | +| `PackageProjectUrl` | | +| `PackageIcon` | Specifies the package icon path, relative to the root of the package. For more information, see [Packing an icon image file](#packing-an-icon-image-file). | +| `PackageReleaseNotes` | Release notes for the package. | +| `PackageReadmeFile` | Readme for the package. | +| `PackageTags` | A semicolon-delimited list of tags that designates the package. | +| `PackageOutputPath` | Determines the output path in which the packed package will be dropped. Default is `$(OutputPath)`. | +| `IncludeSymbols` | This Boolean value indicates whether the package should create an additional symbols package when the project is packed. The symbols package's format is controlled by the `SymbolPackageFormat` property. For more information, see [IncludeSymbols](#includesymbols). | +| `IncludeSource` | This Boolean value indicates whether the pack process should create a source package. The source package contains the library's source code as well as PDB files. Source files are put under the `src/ProjectName` directory in the resulting package file. For more information, see [IncludeSource](#includesource). | +| `PackageType` | | +| `IsTool` | Specifies whether all output files are copied to the *tools* folder instead of the *lib* folder. For more information, see [IsTool](#istool). | +| `RepositoryUrl` | Repository URL used to clone or retrieve source code. Example: *https://github.com/NuGet/NuGet.Client.git*. | +| `RepositoryType` | Repository type. Examples: `git` (default), `tfs`. | +| `RepositoryBranch` | Optional repository branch information. `RepositoryUrl` must also be specified for this property to be included. Example: *master* (NuGet 4.7.0+). | +| `RepositoryCommit` | Optional repository commit or changeset to indicate which source the package was built against. `RepositoryUrl` must also be specified for this property to be included. Example: *0e4d1b598f350b3dc675018d539114d1328189ef* (NuGet 4.7.0+). | +| `SymbolPackageFormat` | Specifies the format of the symbols package. If "symbols.nupkg", a legacy symbols package is created with a *.symbols.nupkg* extension containing PDBs, DLLs, and other output files. If "snupkg", a snupkg symbol package is created containing the portable PDBs. The default is "symbols.nupkg". | +| `NoPackageAnalysis` | Specifies that `pack` should not run package analysis after building the package. | +| `MinClientVersion` | Specifies the minimum version of the NuGet client that can install this package, enforced by nuget.exe and the Visual Studio Package Manager. | +| `IncludeBuildOutput` | This Boolean value specifies whether the build output assemblies should be packed into the *.nupkg* file or not. | +| `IncludeContentInPack` | This Boolean value specifies whether any items that have a type of `Content` are included in the resulting package automatically. The default is `true`. | +| `BuildOutputTargetFolder` | Specifies the folder where to place the output assemblies. The output assemblies (and other output files) are copied into their respective framework folders. For more information, see [Output assemblies](#output-assemblies). | +| `ContentTargetFolders` | Specifies the default location of where all the content files should go if `PackagePath` is not specified for them. The default value is "content;contentFiles". For more information, see [Including content in a package](#including-content-in-a-package). | +| `NuspecFile` | Relative or absolute path to the *.nuspec* file being used for packing. If specified, it's used **exclusively** for packaging information, and any information in the projects is not used. For more information, see [Packing using a .nuspec](#packing-using-a-nuspec-file). | +| `NuspecBasePath` | Base path for the *.nuspec* file. For more information, see [Packing using a .nuspec](#packing-using-a-nuspec-file). | +| `NuspecProperties` | Semicolon separated list of key=value pairs. For more information, see [Packing using a .nuspec](#packing-using-a-nuspec-file). | ## pack scenarios -### Suppress dependencies +### Suppressing dependencies To suppress package dependencies from generated NuGet package, set `SuppressDependenciesWhenPacking` to `true` which will allow skipping all the dependencies from generated nupkg file. -### PackageIconUrl +### `PackageIconUrl` + +`PackageIconUrl` is deprecated in favor of the [`PackageIcon`](#packageicon) property. Starting with NuGet 5.3 and Visual Studio 2019 version 16.3, `pack` raises the [NU5048](./errors-and-warnings/nu5048.md) warning if the package metadata only specifies `PackageIconUrl`. -> [!Important] -> PackageIconUrl is deprecated. Use [PackageIcon](#packing-an-icon-image-file) instead. +### `PackageIcon` -### Packing an icon image file +> [!Tip] +> To maintain backward compatibility with clients and sources that don't yet support `PackageIcon`, specify both `PackageIcon` and `PackageIconUrl`. Visual Studio supports `PackageIcon` for packages coming from a folder-based source. -When packing an icon image file, you need to use PackageIcon property to specify the package path, relative to the root of the package. In addition, you need to make sure that the file is included in the package. Image file size is limited to 1 MB. Supported file formats include JPEG and PNG. We recommend an image resolution of 64x64. +#### Packing an icon image file + +When packing an icon image file, use `PackageIcon` property to specify the icon file path, relative to the root of the package. In addition, make sure that the file is included in the package. Image file size is limited to 1 MB. Supported file formats include JPEG and PNG. We recommend an image resolution of 128x128. For example: @@ -136,10 +151,34 @@ For example: ``` -[Package Icon sample](https://github.com/NuGet/Samples/tree/master/PackageIconExample). +[Package Icon sample](https://github.com/NuGet/Samples/tree/main/PackageIconExample). For the nuspec equivalent, take a look at [nuspec reference for icon](nuspec.md#icon). +### PackageReadmeFile + +*Supported with **NuGet 5.10.0 preview 2** / **.NET SDK 5.0.300** and above* + +When packing a readme file, you need to use the `PackageReadmeFile` property to specify the package path, relative to the root of the package. In addition to this, you need to make sure that the file is included in the package. Supported file formats include only Markdown (*.md*). + +For example: + +```xml + + ... + readme.md + ... + + + + ... + + ... + +``` + +For the nuspec equivalent, take a look at [nuspec reference for readme](nuspec.md#readme). + ### Output assemblies `nuget pack` copies output files with extensions `.exe`, `.dll`, `.xml`, `.winmd`, `.json`, and `.pri`. The output files that are copied depend on what MSBuild provides from the `BuiltOutputProjectGroup` target. @@ -155,7 +194,7 @@ See [Package References in Project Files](../consume-packages/package-references ### Project to project references -Project to project references are considered by default as nuget package references, for example: +Project to project references are considered by default as NuGet package references. For example: ```xml @@ -220,8 +259,7 @@ If a file of type Compile, is outside the project folder, then it's just added t ### Packing a license expression or a license file -When using a license expression, the PackageLicenseExpression property should be used. -[License expression sample](https://github.com/NuGet/Samples/tree/master/PackageLicenseExpressionExample). +When using a license expression, use the `PackageLicenseExpression` property. For a sample, see [License expression sample](https://github.com/NuGet/Samples/tree/main/PackageLicenseExpressionExample). ```xml @@ -229,9 +267,9 @@ When using a license expression, the PackageLicenseExpression property should be ``` -[Learn more about license expressions and licenses that are accepted by NuGet.org](nuspec.md#license). +To learn more about license expressions and licenses that are accepted by NuGet.org, see [license metadata](nuspec.md#license). -When packing a license file, you need to use PackageLicenseFile property to specify the package path, relative to the root of the package. In addition, you need to make sure that the file is included in the package. For example: +When packing a license file, use `PackageLicenseFile` property to specify the package path, relative to the root of the package. In addition, make sure that the file is included in the package. For example: ```xml @@ -243,25 +281,47 @@ When packing a license file, you need to use PackageLicenseFile property to spec ``` -[License file sample](https://github.com/NuGet/Samples/tree/master/PackageLicenseFileExample). +For a sample, see [License file sample](https://github.com/NuGet/Samples/tree/main/PackageLicenseFileExample). + +> [!NOTE] +> Only one of `PackageLicenseExpression`, `PackageLicenseFile`, and `PackageLicenseUrl` can be specified at a time. + +### Packing a file without an extension + +In some scenarios, like when packing a license file, you might want to include a file without an extension. +For historical reasons, NuGet & MSBuild treat paths without an extension as directories. + +```xml + + netstandard2.0 + LICENSE + + + + + +``` + +[File without an extension sample](https://github.com/NuGet/Samples/blob/main/PackageLicenseFileExtensionlessExample/). ### IsTool When using `MSBuild -t:pack -p:IsTool=true`, all output files, as specified in the [Output Assemblies](#output-assemblies) scenario, are copied to the `tools` folder instead of the `lib` folder. Note that this is different from a `DotNetCliTool` which is specified by setting the `PackageType` in `.csproj` file. -### Packing using a .nuspec +### Packing using a `.nuspec` file -Although it is recommended that you [include all the properties](../reference/msbuild-targets.md#pack-target) that are usually in the `.nuspec` file in the project file instead, you can choose to use a `.nuspec` file to pack your project. For a non-SDK-style project that uses `PackageReference`, you must import `NuGet.Build.Tasks.Pack.targets` so that the pack task can be executed. You still need to restore the project before you can pack a nuspec file. (An SDK-style project includes the pack targets by default.) +Although it is recommended that you [include all the properties](../reference/msbuild-targets.md#pack-target) that are usually in the `.nuspec` file in the project file instead, you can choose to use a `.nuspec` file to pack your project. +You still need to restore the project before you can pack a nuspec file. (An SDK-style project includes the pack targets by default.) The target framework of the project file is irrelevant and not used when packing a nuspec. The following three MSBuild properties are relevant to packing using a `.nuspec`: 1. `NuspecFile`: relative or absolute path to the `.nuspec` file being used for packing. -1. `NuspecProperties`: a semicolon-separated list of key=value pairs. Due to the way MSBuild command-line parsing works, multiple properties must be specified as follows: `-p:NuspecProperties=\"key1=value1;key2=value2\"`. +1. `NuspecProperties`: a semicolon-separated list of key=value pairs. Due to the way MSBuild command-line parsing works, multiple properties must be specified as follows: `-p:NuspecProperties="key1=value1;key2=value2"`. 1. `NuspecBasePath`: Base path for the `.nuspec` file. If using `dotnet.exe` to pack your project, use a command like the following: -```cli +```dotnetcli dotnet pack -p:NuspecFile= -p:NuspecProperties=<> -p:NuspecBasePath= ``` @@ -295,7 +355,7 @@ The `pack` target provides two extension points that run in the inner, target fr - `TargetsForTfmSpecificBuildOutput` target: Use for files inside the `lib` folder or a folder specified using `BuildOutputTargetFolder`. - `TargetsForTfmSpecificContentInPackage` target: Use for files outside the `BuildOutputTargetFolder`. -#### TargetsForTfmSpecificBuildOutput +#### `TargetsForTfmSpecificBuildOutput` Write a custom target and specify it as the value of the `$(TargetsForTfmSpecificBuildOutput)` property. For any files that need to go into the `BuildOutputTargetFolder` (lib by default), the target should write those files into the ItemGroup `BuildOutputInPackage` and set the following two metadata values: @@ -318,7 +378,7 @@ Example: ``` -#### TargetsForTfmSpecificContentInPackage +#### `TargetsForTfmSpecificContentInPackage` Write a custom target and specify it as the value of the `$(TargetsForTfmSpecificContentInPackage)` property. For any files to include in the package, the target should write those files into the ItemGroup `TfmSpecificPackageFile` and set the following optional metadata: @@ -354,7 +414,11 @@ An example: 1. Download packages 1. Write assets file, targets, and props -The `restore` target works **only** for projects using the PackageReference format. It does **not** work for projects using the `packages.config` format; use [nuget restore](../reference/cli-reference/cli-ref-restore.md) instead. +The `restore` target works for projects using the PackageReference format. +`MSBuild 16.5+` also has [opt-in support](#restoring-packagereference-and-packagesconfig-projects-with-msbuild) for the `packages.config` format. + +> [!NOTE] +> The `restore` target [should not be run](#restoring-and-building-with-one-msbuild-command) in combination with the `build` target. ### Restore properties @@ -362,20 +426,32 @@ Additional restore settings may come from MSBuild properties in the project file | Property | Description | |--------|--------| -| RestoreSources | Semicolon-delimited list of package sources. | -| RestorePackagesPath | User packages folder path. | -| RestoreDisableParallel | Limit downloads to one at a time. | -| RestoreConfigFile | Path to a `Nuget.Config` file to apply. | -| RestoreNoCache | If true, avoids using cached packages. See [Managing the global packages and cache folders](../consume-packages/managing-the-global-packages-and-cache-folders.md). | -| RestoreIgnoreFailedSources | If true, ignores failing or missing package sources. | -| RestoreFallbackFolders | Fallback folders, used in the same way the user packages folder is used. | -| RestoreAdditionalProjectSources | Additional sources to use during restore. | -| RestoreAdditionalProjectFallbackFolders | Additional fallback folders to use during restore. | -| RestoreAdditionalProjectFallbackFoldersExcludes | Excludes fallback folders specified in `RestoreAdditionalProjectFallbackFolders` | -| RestoreTaskAssemblyFile | Path to `NuGet.Build.Tasks.dll`. | -| RestoreGraphProjectInput | Semicolon-delimited list of projects to restore, which should contain absolute paths. | -| RestoreUseSkipNonexistentTargets | When the projects are collected via MSBuild it determines whether they are collected using the `SkipNonexistentTargets` optimization. When not set, defaults to `true`. The consequence is a fail-fast behavior when a project's targets cannot be imported. | -| MSBuildProjectExtensionsPath | Output folder, defaulting to `BaseIntermediateOutputPath` and the `obj` folder. | +| `RestoreSources` | Semicolon-delimited list of package sources. | +| `RestorePackagesPath` | User packages folder path. | +| `RestoreDisableParallel` | Limit downloads to one at a time. | +| `RestoreConfigFile` | Path to a `Nuget.Config` file to apply. | +| `RestoreNoHttpCache` | If true, avoids using http cached packages. See [Managing the global packages and cache folders](../consume-packages/managing-the-global-packages-and-cache-folders.md). | +| `RestoreIgnoreFailedSources` | If true, ignores failing or missing package sources. | +| `RestoreFallbackFolders` | Fallback folders, used in the same way the user packages folder is used. | +| `RestoreAdditionalProjectSources` | Additional sources to use during restore. | +| `RestoreAdditionalProjectFallbackFolders` | Additional fallback folders to use during restore. | +| `RestoreAdditionalProjectFallbackFoldersExcludes` | Excludes fallback folders specified in `RestoreAdditionalProjectFallbackFolders` | +| `RestoreTaskAssemblyFile` | Path to `NuGet.Build.Tasks.dll`. | +| `RestoreGraphProjectInput` | Semicolon-delimited list of projects to restore, which should contain absolute paths. | +| `RestoreUseSkipNonexistentTargets` | When the projects are collected via MSBuild it determines whether they are collected using the `SkipNonexistentTargets` optimization. When not set, defaults to `true`. The consequence is a fail-fast behavior when a project's targets cannot be imported. | +| `MSBuildProjectExtensionsPath` | Output folder, defaulting to `BaseIntermediateOutputPath` and the `obj` folder. | +| `RestoreForce` | In PackageReference based projects, forces all dependencies to be resolved even if the last restore was successful. Specifying this flag is similar to deleting the `project.assets.json` file. This does not bypass the http-cache. | +| `RestorePackagesWithLockFile` | Opts into the usage of a lock file. | +| `RestoreLockedMode` | Run restore in locked mode. This means that restore will not reevaluate the dependencies. | +| `NuGetLockFilePath` | A custom location for the lock file. The default location is next to the project and is named `packages.lock.json`. | +| `RestoreForceEvaluate` | Forces restore to recompute the dependencies and update the lock file without any warning. | +| `RestorePackagesConfig` | An opt-in switch, that restores projects with packages.config. Support with `MSBuild -t:restore` only. | +| `RestoreRepositoryPath` | packages.config only. Specifies the packages directory to which the packages should be restored. `SolutionDirectory` will be used if not specified. | +| `RestoreUseStaticGraphEvaluation` | An opt-in switch to use static graph MSBuild evaluation instead of the standard evaluation. Static graph evaluation is an experimental feature that's significantly faster for large repos and solutions. | +| `RestoreUseLegacyDependencyResolver` | An opt-out to use the legacy dependency resolver. NuGet's dependency resolver implementation was rewritten in the [6.12 release](../../docs/release-notes/NuGet-6.12.md). This switch forces the previous algorithm to be used. | + +The `ExcludeRestorePackageImports` property is an internal property used by NuGet. +It should not be modified or set in any MSBuild files. #### Examples @@ -389,7 +465,7 @@ Project file: ```xml - true + true ``` @@ -420,26 +496,52 @@ msbuild -t:build -restore The same logic applies to other targets similar to `build`. -### PackageTargetFallback +### Restoring PackageReference and packages.config projects with MSBuild -The `PackageTargetFallback` element allows you to specify a set of compatible targets to be used when restoring packages. It's designed to allow packages that use a dotnet [TxM](../reference/target-frameworks.md) to work with compatible packages that don't declare a dotnet TxM. That is, if your project uses the dotnet TxM, then all the packages it depends on must also have a dotnet TxM, unless you add the `` to your project in order to allow non-dotnet platforms to be compatible with dotnet. +With MSBuild 16.5+, packages.config are also supported for `msbuild -t:restore`. -For example, if the project is using the `netstandard1.6` TxM, and a dependent package contains only `lib/net45/a.dll` and `lib/portable-net45+win81/a.dll`, then the project will fail to build. If what you want to bring in is the latter DLL, then you can add a `PackageTargetFallback` as follows to say that the `portable-net45+win81` DLL is compatible: +```cli +msbuild -t:restore -p:RestorePackagesConfig=true +``` -```xml - - portable-net45+win81 - +> [!NOTE] +> `packages.config` restore is only available with `MSBuild 16.5+`, and not with `dotnet.exe` + +### Restoring with MSBuild static graph evaluation + +> [!NOTE] +> With MSBuild 16.6+, NuGet has added an experimental feature to use static graph evaluation from the command line that significantly improves the restore time for large repositories. + +```cli +msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true ``` -To declare a fallback for all targets in your project, leave off the `Condition` attribute. You can also extend any existing `PackageTargetFallback` by including `$(PackageTargetFallback)` as shown here: +Alternatively you can enable it by setting the property in a Directory.Build.Props. ```xml - - $(PackageTargetFallback);portable-net45+win81 - + + + true + + +``` + +> [!NOTE] +> As of Visual Studio 2019.x and NuGet 5.x, this feature is considered experimental and opt-in. Follow [NuGet/Home#9803](https://github.com/NuGet/Home/issues/9803) for details on when this feature will be enabled by default. + +Static graph restore changes the msbuild part of restore, the project reading and evaluation, but not the restore algorithm! The restore algorithm is the same across all NuGet tools (NuGet.exe, MSBuild.exe, dotnet.exe and Visual Studio). + +In very few scenarios, static graph restore may behave differently from current restore and certain declared PackageReferences or ProjectReferences might be missing. + +To ease your mind, as a one time check, when migrating to static graph restore, consider running: + +```cli +msbuild.exe -t:restore -p:RestoreUseStaticGraphEvaluation=true +msbuild.exe -t:restore ``` +NuGet should *not* report any changes. If you do see a discrepancy, please file an issue at [NuGet/Home](https://github.com/nuget/home/issues/new). + ### Replacing one library from a restore graph If a restore is bringing the wrong assembly, it's possible to exclude that packages default choice, and replace it with your own choice. First with a top level `PackageReference`, exclude all assets: diff --git a/docs/reference/nuget-config-file.md b/docs/reference/nuget-config-file.md index 3a85084c6..83aa92383 100644 --- a/docs/reference/nuget-config-file.md +++ b/docs/reference/nuget-config-file.md @@ -1,15 +1,15 @@ --- title: nuget.config File Reference description: NuGet.Config file reference including the config, bindingRedirects, packageRestore, solution, and packageSource sections. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 08/13/2019 ms.topic: reference --- -# nuget.config reference +# `nuget.config` reference -NuGet behavior is controlled by settings in different `NuGet.Config` files as described in [Common NuGet configurations](../consume-packages/configuring-nuget-behavior.md). +NuGet behavior is controlled by settings in different `NuGet.Config` or `nuget.config` files as described in [Common NuGet configurations](../consume-packages/configuring-nuget-behavior.md). `nuget.config` is an XML file containing a top-level `` node, which then contains the section elements described in this topic. Each section contains zero or more items. See the [examples config file](#example-config-file). Setting names are case-insensitive, and values can use [environment variables](#using-environment-variables). @@ -18,6 +18,10 @@ NuGet behavior is controlled by settings in different `NuGet.Config` files as de +> [!Tip] +> Add a `nuget.config` file in the root of your project repository. This is considered a best practice as it promotes repeatability and ensures that different users have the same NuGet configuration. +> You may need to configure `clear` elements to ensure no user or machine specific configuration is applied. [Read more about how settings are applied](../consume-packages/configuring-nuget-behavior.md#how-settings-are-applied). + ## config section Contains miscellaneous configuration settings, which can be set using the [`nuget config` command](../reference/cli-reference/cli-ref-config.md). @@ -26,12 +30,14 @@ Contains miscellaneous configuration settings, which can be set using the [`nuge | Key | Value | | --- | --- | -| dependencyVersion (`packages.config` only) | The default `DependencyVersion` value for package install, restore, and update, when the `-DependencyVersion` switch is not specified directly. This value is also used by the NuGet Package Manager UI. Values are `Lowest`, `HighestPatch`, `HighestMinor`, `Highest`. | -| globalPackagesFolder (projects using PackageReference only) | The location of the default global packages folder. The default is `%userprofile%\.nuget\packages` (Windows) or `~/.nuget/packages` (Mac/Linux). A relative path can be used in project-specific `nuget.config` files. This setting is overridden by the NUGET_PACKAGES environment variable, which takes precedence. | -| repositoryPath (`packages.config` only) | The location in which to install NuGet packages instead of the default `$(Solutiondir)/packages` folder. A relative path can be used in project-specific `nuget.config` files. This setting is overridden by the NUGET_PACKAGES environment variable, which takes precedence. | | defaultPushSource | Identifies the URL or path of the package source that should be used as the default if no other package sources are found for an operation. | +| dependencyVersion (`packages.config` only) | The default `DependencyVersion` value for package install, restore, and update, when the `-DependencyVersion` switch is not specified directly. This value is also used by the NuGet Package Manager UI. Values are `Lowest`, `HighestPatch`, `HighestMinor`, `Highest`. | +| globalPackagesFolder | The location of the default global packages folder. The default is `%userprofile%\.nuget\packages` (Windows) or `~/.nuget/packages` (Mac/Linux). A relative path can be used in project-specific `nuget.config` files. This setting is overridden by the `NUGET_PACKAGES` environment variable, which takes precedence. | | http_proxy http_proxy.user http_proxy.password no_proxy | Proxy settings to use when connecting to package sources; `http_proxy` should be in the format `http://:@`. Passwords are encrypted and cannot be added manually. For `no_proxy`, the value is a comma-separated list of domains the bypass the proxy server. You can alternately use the http_proxy and no_proxy environment variables for those values. For additional details, see [NuGet proxy settings](http://skolima.blogspot.com/2012/07/nuget-proxy-settings.html) (skolima.blogspot.com). | -| signatureValidationMode | Specifies the validation mode used to verify package signatures for package install, and restore. Values are `accept`, `require`. Defaults to `accept`. +| maxHttpRequestsPerSource | Controls the maximum number of parallel requests sent from NuGet to every package source for package dependency resolution and downloads. The default value on `dotnet.exe` is `Int32.MaxValue` which is derived from `HttpClientHandler.MaxConnectionsPerServer` property. This setting has no impact on `dotnet.exe` for `Mac OS` because the throttling limit is set to `16` to avoid too many open files error. The default value for `NuGet client tools` that runs on `.NET Framework` such as `Visual Studio` and `nuget.exe` is `64` on `Windows` and `1` on `Mono`. The default value for `Packages.config` style projects is set to `Environment.ProcessorCount`. Configuring `maxHttpRequestsPerSource` property to a value less than the default could impact NuGet performance. | +| repositoryPath (`packages.config` only) | The location in which to install NuGet packages instead of the default `$(Solutiondir)/packages` folder. A relative path can be used in project-specific `nuget.config` files. | +| signatureValidationMode | Specifies the validation mode used to verify package signatures for package install, and restore. Values are `accept`, `require`. Defaults to `accept`. | +| updatePackageLastAccessTime | When set to `true`, restore will update the last access time of the `.nupkg.metadata` file in the global packages folder during restore. See [the documentation on the global packages folder for more information](../consume-packages/managing-the-global-packages-and-cache-folders.md#global-packages) | **Example**: @@ -42,6 +48,8 @@ Contains miscellaneous configuration settings, which can be set using the [`nuge + + ``` @@ -97,7 +105,7 @@ Controls whether the `packages` folder of a solution is included in source contr ## Package source sections -The `packageSources`, `packageSourceCredentials`, `apikeys`, `activePackageSource`, `disabledPackageSources` and `trustedSigners` all work together to configure how NuGet works with package repositories during install, restore, and update operations. +The `packageSources`, `packageSourceCredentials`, `apikeys`, `activePackageSource`, `disabledPackageSources`, `trustedSigners` and `packageSourceMapping` all work together to configure how NuGet works with package repositories during install, restore, and update operations. The [`nuget sources` command](../reference/cli-reference/cli-ref-sources.md) is generally used to manage these settings, except for `apikeys` which is managed using the [`nuget setapikey` command](../reference/cli-reference/cli-ref-setapikey.md), and `trustedSigners` which is managed using the [`nuget trusted-signers` command](../reference/cli-reference/cli-ref-trusted-signers.md). @@ -107,29 +115,72 @@ Note that the source URL for nuget.org is `https://api.nuget.org/v3/index.json`. Lists all known package sources. The order is ignored during restore operations and with any project using the PackageReference format. NuGet respects the order of sources for install and update operations with projects using `packages.config`. -| Key | Value | -| --- | --- | -| (name to assign to the package source) | The path or URL of the package source. | +| XML Attribute | Purpose | +| :-- | :-- | +| **Key** | (name to assign to the package source) | +| **Value** | The path or URL of the package source. | +| **protocolVersion** | The NuGet server protocol version to be used. The current version is "3". Defaults to version "2" when not pointing to a package source URL ending in `.json` (e.g. ). Supported in [NuGet 3.0+](/nuget/release-notes/nuget-3.0.0). See [NuGet Server API](/nuget/api/overview) for more information about the version 3 protocol. | +| **allowInsecureConnections** | When false, or not specified, NuGet will emit a warning when the source uses http, rather than https. If you are confident that communication with this source will never be at risk of interception attacks, you can set the value to true to suppress the warning. Supported in NuGet 6.8+. | +| **disableTLSCertificateValidation** | This configuration property allows you to disable SSL/TLS certificate validation for your HTTPS server. When set to true, the server will ignore any errors related to SSL/TLS certificates, such as expired or self-signed certificates, and establish the connection without validation. Supported in NuGet 6.11+. | **Example**: ```xml + + + ``` +> [!NOTE] +> Use package sources that you trust. + +> [!NOTE] +> When using the CLI, you can express a [`RestoreSources`](../reference/msbuild-targets.md#restore-properties) MSBuild property or [`--source`(.NET CLI)](/dotnet/core/tools/dotnet-restore#options) | [`-Source`(NuGet CLI)](/nuget/reference/cli-reference/cli-ref-restore#options) to override the `` defined in the NuGet.config. + +> [!Tip] +> When `` is present for a given node, NuGet ignores previously defined configuration values for that node. [Read more about how settings are applied](../consume-packages/configuring-nuget-behavior.md#how-settings-are-applied). + +### auditSources + +Lists all known audit sources, which [NuGet Audit](../concepts/Auditing-Packages.md#running-a-security-audit-with-restore) will use during restore. +If no audit sources are provided, restore will use package sources and suppress [NU1905](../reference/errors-and-warnings/NU1905.md). +`auditSources` was added to [NuGet 6.12](../release-notes/NuGet-6.12.md). + +Audit sources support the same attributes as `packageSources` (`protocolVersion`, `allowInsecureConnections`), and sources that require authentication are configured with `packageSourceCredentials`, the same way as `packageSources`. + +**Example**: +```xml + + + + +``` + ### packageSourceCredentials Stores usernames and passwords for sources, typically specified with the `-username` and `-password` switches with `nuget sources`. Passwords are encrypted by default unless the `-storepasswordincleartext` option is also used. +Optionally, valid authentication types can be specified with the `-validauthenticationtypes` switch. | Key | Value | | --- | --- | -| username | The user name for the source in plain text. | -| password | The encrypted password for the source. | -| cleartextpassword | The unencrypted password for the source. | +| username | The user name for the source in plain text. Note: environment variables can be used for improved security. | +| password | The encrypted password for the source. Encrypted passwords are only supported on Windows, and only can be decrypted when used on the same machine and via the same user as the original encryption. | +| cleartextpassword | The unencrypted password for the source. Note: environment variables can be used for improved security. | +| validauthenticationtypes | Comma-separated list of valid authentication types for this source. Set this to `basic` if the server advertises NTLM or Negotiate and your credentials must be sent using the Basic mechanism, for instance when using a PAT with on-premises Azure DevOps Server. Other valid values include `negotiate`, `kerberos`, `ntlm`, and `digest`, but these values are unlikely to be useful. | + +> [!WARNING] +> Storing passwords in clear text is strongly discouraged. +> Please note that encrypted passwords are only supported on Windows. +> Furthermore, they can only be decrypted when used on the same machine and by the same user who originally encrypted them. +> For more information on managing credentials securely, refer to the [security best practices for consuming packages from private feeds](../consume-packages/consuming-packages-authenticated-feeds.md#security-best-practices-for-managing-credentials). + +> [!Tip] +> If a non-encrypted password is passed for `password` the error message ["The parameter is incorrect" will occur](https://github.com/NuGet/Home/issues/3245). **Example:** @@ -148,7 +199,41 @@ In the config file, the `` element contains child node ``` +Additionally, valid authentication methods can be supplied. + +```xml + + + + + + + + + + + + +``` + +When using unencrypted passwords stored in an environment variable: + +```xml + + + + + + + + + + +``` + When using unencrypted passwords: +> [!WARNING] +> Storing passwords in clear text is strongly discouraged. ```xml @@ -181,7 +266,7 @@ Stores keys for sources that use API key authentication, as set with the [`nuget ### disabledPackageSources -Identified currently disabled sources. May be empty. +Identified currently disabled sources. May be empty. Unless specific sources are disabled in this section, they are enabled. | Key | Value | | --- | --- | @@ -198,6 +283,8 @@ Identified currently disabled sources. May be empty. ``` +In the example above, the package source `Contoso` is disabled and will not be used to download or install packages. + ### activePackageSource *(2.x only; deprecated in 3.x+)* @@ -222,7 +309,7 @@ Identifies to the currently active source or indicates the aggregate of all sour ## trustedSigners section -Stores trusted signers used to allow package while installing or restoring. This list cannot be empty when the user sets `signatureValidationMode` to `require`. +Stores trusted signers used to allow package while installing or restoring. This list cannot be empty when the user sets `signatureValidationMode` to `require`. This section can be updated with the [`nuget trusted-signers` command](../reference/cli-reference/cli-ref-trusted-signers.md). @@ -240,13 +327,17 @@ If a `certificate` specifies `allowUntrustedRoot` as `true` the given certificat ```xml - - - - - - microsoft;aspnet;nuget - + + + + + + + + + + microsoft;aspnet;nuget + ``` @@ -276,6 +367,42 @@ If a match is not found, then NuGet checks file sources, and then http sources, ``` +## Package source mapping section + +The `packageSourceMapping` section contains the details that help the NuGet package operations determine where a package id should be downloaded from. + +This section can only be managed manually right now. + +A `packageSourceMapping` section can only contain `packageSource` sections. + +### packageSource + +A sub section of the [`packageSourceMapping`](#package-source-mapping-section) section. Contains a mapping to help NuGet determine whether the source should be considered for downloading the package of interest. + +| Key | +| --- | +| Name of a package source declared in the [`packageSources`](#packagesources) section. The key must exactly match the the key of the package source. | + +The `packageSource` sections under `packageSourceMapping` are uniquely identified by the `key`. + +### package + +The `package` is part of the [`packageSource`](#packagesource) section. + +| Pattern | +| --- | +| A pattern as defined by the [syntax](../consume-packages/package-source-mapping.md) of Package Source mapping. | + +**Example**: + +```xml + + + + + +``` + ## packageManagement section Sets the default package management format, either *packages.config* or PackageReference. SDK-style projects always use PackageReference. @@ -294,19 +421,33 @@ Sets the default package management format, either *packages.config* or PackageR ``` +> [!Tip] +> When `` is present for a given node, NuGet ignores previously defined configuration values for that node. [Read more about how settings are applied](../consume-packages/configuring-nuget-behavior.md#how-settings-are-applied). + ## Using environment variables You can use environment variables in `nuget.config` values (NuGet 3.4+) to apply settings at run time. For example, if the `HOME` environment variable on Windows is set to `c:\users\username`, then the value of `%HOME%\NuGetRepository` in the configuration file resolves to `c:\users\username\NuGetRepository`. -Similarly, if `HOME` on Mac/Linux is set to `/home/myStuff`, then `%HOME%/NuGetRepository` in the configuration file resolves to `/home/myStuff/NuGetRepository`. +Note that you have to use Windows-style environment variables (starts and ends with %) even on Mac/Linux. Having `$HOME/NuGetRepository` in a configuration file will not resolve. On Mac/Linux the value of `%HOME%/NuGetRepository` will resolve to `/home/myStuff/NuGetRepository`. + +If an environment variable is not found, NuGet uses the literal value from the configuration file. For example `%MY_UNDEFINED_VAR%/NuGetRepository` will be resolved as `path/to/current_working_dir/$MY_UNDEFINED_VAR/NuGetRepository` + +The table below show environnment variable syntax and path separator support for NuGet.Config files. + +### `NuGet.Config` environment variable support -If an environment variable is not found, NuGet uses the literal value from the configuration file. +| Syntax | Dir separator | Windows nuget.exe | Windows dotnet.exe | Mac nuget.exe (in Mono) | Mac dotnet.exe | +|---|---|---|---|---|---| +| `%MY_VAR%` | `/` | Yes | Yes | Yes | Yes | +| `%MY_VAR%` | `\` | Yes | Yes | No | No | +| `$MY_VAR` | `/` | No | No | No | No | +| `$MY_VAR` | `\` | No | No | No | No | ## Example config file -Below is an example `nuget.config` file that illustrates a number of settings: +Below is an example `nuget.config` file that illustrates a number of settings including optional ones: ```xml @@ -317,10 +458,10 @@ Below is an example `nuget.config` file that illustrates a number of settings: See: nuget.exe help install See: nuget.exe help update - In this example, %PACKAGEHOME% is an environment variable. On Mac/Linux, - use $PACKAGE_HOME/External as the value. + In this example, %PACKAGEHOME% is an environment variable. + This syntax works on Windows/Mac/Linux --> - + + @@ -377,9 +519,13 @@ Below is an example `nuget.config` file that illustrates a number of settings: + + + + microsoft;aspnet;nuget diff --git a/docs/reference/nuget-exe-CLI-Reference.md b/docs/reference/nuget-exe-CLI-Reference.md index 1f4dd3444..7bebbea46 100644 --- a/docs/reference/nuget-exe-CLI-Reference.md +++ b/docs/reference/nuget-exe-CLI-Reference.md @@ -1,8 +1,8 @@ --- title: NuGet Command-Line Interface (CLI) Reference description: Command-line reference index for the nuget.exe CLI -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/23/2018 ms.topic: reference --- @@ -55,6 +55,7 @@ Available commands and applicability to package creation, package consumption, a | [install](cli-reference/cli-ref-install.md) | Consumption | All | Installs a package into the current project but does not modify projects or reference files. | | [list](cli-reference/cli-ref-list.md) | Consumption, perhaps Publishing | All | Displays packages from a given source. | | [mirror](cli-reference/cli-ref-mirror.md) | Publishing | Deprecated in 3.2+ | Mirrors a package and its dependencies from a source to a target repository. | +| [search](cli-reference/cli-ref-search.md) | Consumption | 5.8+ | Searches a given source using the query string provided. | | [sources](cli-reference/cli-ref-sources.md) | Consumption, Publishing | All | Manages package sources in configuration files. | | [update](cli-reference/cli-ref-update.md) | Consumption | All | Updates a project's packages to the latest available versions. Not supported when running on Mono. | @@ -64,7 +65,7 @@ NuGet CLI commands by applicable roles: | Role | Commands | | --- | --- | -| Consumption | `config`, `help`, `install`, `list`, `locals`, `restore`, `setapikey`, `sources`, `update` | +| Consumption | `config`, `help`, `install`, `list`, `locals`, `restore`, `search`, `setapikey`, `sources`, `update` | | Creation | `config`, `help`, `init`, `pack`, `spec` | | Publishing | `add`, `config`, `delete`, `help`, `list`, `push`, `setapikey`, `sources` | @@ -72,3 +73,8 @@ Developers concerned only with consuming packages, for example, need only unders > [!Note] > Command option names are case-insensitive. Options that are deprecated are not included in this reference, such as `NoPrompt` (replaced by `NonInteractive`) and `Verbose` (replaced by `Verbosity`). + +## Localization + +NuGet.exe's progress, warning and error messages are translated into the same locales as Visual Studio. +NuGet.exe ships as a single exe, and due to size considerations, only the most commonly surfaced messages are translated in all languages. diff --git a/docs/reference/nuspec.md b/docs/reference/nuspec.md index 8e72e0322..da7370ef6 100644 --- a/docs/reference/nuspec.md +++ b/docs/reference/nuspec.md @@ -1,8 +1,8 @@ --- title: .nuspec File Reference for NuGet description: The .nuspec file contains package metadata used when building a package and to provide information to package consumers. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 05/24/2019 ms.topic: reference ms.reviewer: anangaur @@ -29,13 +29,15 @@ In this topic: - A `.nuspec` file is not required to create packages for [SDK-style projects](../resources/check-project-format.md) (typically .NET Core and .NET Standard projects that use the [SDK attribute](/dotnet/core/tools/csproj#additions)). (Note that a `.nuspec` is generated when you create the package.) - If you are creating a package using `dotnet.exe pack` or `msbuild pack target`, we recommend that you [include all the properties](../reference/msbuild-targets.md#pack-target) that are usually in the `.nuspec` file in the project file instead. However, you can instead choose to [use a `.nuspec` file to pack using `dotnet.exe` or `msbuild pack target`](../reference/msbuild-targets.md#packing-using-a-nuspec). + If you are creating a package using `dotnet.exe pack` or `msbuild pack target`, we recommend that you [include all the properties](../reference/msbuild-targets.md#pack-target) that are usually in the `.nuspec` file in the project file instead. However, you can instead choose to [use a `.nuspec` file to pack using `dotnet.exe` or `msbuild pack target`](../reference/msbuild-targets.md#packing-using-a-nuspec-file). - For projects migrated from `packages.config` to [PackageReference](../consume-packages/package-references-in-project-files.md), a `.nuspec` file is not required to create the package. Instead, use [msbuild -t:pack](../consume-packages/migrate-packages-config-to-package-reference.md#create-a-package-after-migration). ## General form and schema -The current `nuspec.xsd` schema file can be found in the [NuGet GitHub repository](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.Packaging/compiler/resources/nuspec.xsd). +A `nuspec.xsd` schema file can be found in the [NuGet GitHub repository](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.Packaging/compiler/resources/nuspec.xsd). +Note, that this file only represents the most recent schema for a `.nuspec` file. +No officially published versions exists and no version of that file corresponds to any specific NuGet version. Within this schema, a `.nuspec` file has the following general form: @@ -60,6 +62,15 @@ For a clear visual representation of the schema, open the schema file in Visual ![Visual Studio Schema Explorer with nuspec.xsd open](media/SchemaExplorer.png) +All XML element names in the .nuspec file are case-sensitive, as is the case for XML in general. For example, using the +metadata element `` is correct and `` is not correct. The proper casing for each element name +is documented below. + +> [!Important] +> While the `.nuspec` file contains a reference to a schema +> (`xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"`), +> The NuGet-Team has never published a schema file that could be used for automatic schema validation. + ### Required metadata elements Although the following elements are the minimum requirements for a package, you should consider adding the [optional metadata elements](#optional-metadata-elements) to improve the overall experience developers have with your package. @@ -68,28 +79,51 @@ These elements must appear within a `` element. #### id The case-insensitive package identifier, which must be unique across nuget.org or whatever gallery the package resides in. IDs may not contain spaces or characters that are not valid for a URL, and generally follow .NET namespace rules. See [Choosing a unique package identifier](../create-packages/creating-a-package.md#choose-a-unique-package-identifier-and-setting-the-version-number) for guidance. + +When uploading a package to nuget.org, the `id` field is limited to 128 characters. + #### version The version of the package, following the *major.minor.patch* pattern. Version numbers may include a pre-release suffix as described in [Package versioning](../concepts/package-versioning.md#pre-release-versions). + +When uploading a package to nuget.org, the `version` field is limited to 64 characters. + #### description A description of the package for UI display. + +When uploading a package to nuget.org, the `description` field is limited to 4000 characters. + #### authors -A comma-separated list of packages authors, matching the profile names on nuget.org. These are displayed in the NuGet Gallery on nuget.org and are used to cross-reference packages by the same authors. +A comma-separated list of package authors. +The `authors` and the `owners` from the nuspec are ignored when uploading the package to nuget.org. +For setting package ownership on nuget.org, see [Managing package owners on nuget.org](../nuget-org/publish-a-package.md#managing-package-owners-on-nugetorg). ### Optional metadata elements #### owners -A comma-separated list of the package creators using profile names on nuget.org. This is often the same list as in `authors`, and is ignored when uploading the package to nuget.org. See [Managing package owners on nuget.org](../nuget-org/publish-a-package.md#managing-package-owners-on-nugetorg). +> [!Important] +> owners is deprecated. Use authors instead. + +A comma-separated list of package owners. +The `owners` from the nuspec is ignored when uploading the package to nuget.org. +For setting package ownership on nuget.org, see [Managing package owners on nuget.org](../nuget-org/publish-a-package.md#managing-package-owners-on-nugetorg). #### projectUrl A URL for the package's home page, often shown in UI displays as well as nuget.org. +When uploading a package to nuget.org, the `projectUrl` field is limited to 4000 characters. + #### licenseUrl > [!Important] > licenseUrl is deprecated. Use license instead. A URL for the package's license, often shown in UIs like nuget.org. +When uploading a package to nuget.org, the `licenseUrl` field is limited to 4000 characters. + #### license + +*Supported with **NuGet 4.9.0** and above* + An SPDX license expression or path to a license file within the package, often shown in UIs like nuget.org. If you're licensing the package under a common license, like MIT or BSD-2-Clause, use the associated [SPDX license identifier](https://spdx.org/licenses/). For example: @@ -98,7 +132,7 @@ If you're licensing the package under a common license, like MIT or BSD-2-Clause > [!Note] > NuGet.org only accepts license expressions that are approved by the Open Source Initiative or the Free Software Foundation. -If your package is licensed under multiple common licenses, you can specify a composite license using the [SPDX expression syntax version 2.0](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60). For example: +If your package is licensed under multiple common licenses, you can specify a composite license using the [SPDX expression syntax version 2.0](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/#d4-composite-license-expressions). For example: `BSD-2-Clause OR MIT` @@ -122,6 +156,7 @@ If you use a custom license that isn't supported by license expressions, you can For the MSBuild equivalent, take a look at [Packing a license expression or a license file](msbuild-targets.md#packing-a-license-expression-or-a-license-file). The exact syntax of NuGet's license expressions is described below in [ABNF](https://tools.ietf.org/html/rfc5234). + ```cli license-id = @@ -143,11 +178,15 @@ license-expression = 1*1(simple-expression / compound-expression / UNLICENSED) > [!Important] > iconUrl is deprecated. Use icon instead. -A URL for a 64x64 image with transparency background to use as the icon for the package in UI display. Be sure this element contains the *direct image URL* and not the URL of a web page containing the image. For example, to use an image from GitHub, use the raw file URL like https://github.com/\/\/raw/\/\. - +A URL for a 128x128 image with transparency background to use as the icon for the package in UI display. Be sure this element contains the *direct image URL* and not the URL of a web page containing the image. For example, to use an image from GitHub, use the raw file URL like https://github.com/\/\/raw/\/\. + +When uploading a package to nuget.org, the `iconUrl` field is limited to 4000 characters. + #### icon -It is a path to an image file within the package, often shown in UIs like nuget.org as the package icon. Image file size is limited to 1 MB. Supported file formats include JPEG and PNG. We recommend an image resoulution of 64x64. +*Supported with **NuGet 5.3.0** and above* + +It is a path to an image file within the package, often shown in UIs like nuget.org as the package icon. Image file size is limited to 1 MB. Supported file formats include JPEG and PNG. We recommend an image resolution of 128x128. For example, you would add the following to your nuspec when creating a package using nuget.exe: @@ -166,10 +205,38 @@ For example, you would add the following to your nuspec when creating a package     ``` -[Package Icon nuspec sample.](https://github.com/NuGet/Samples/tree/master/PackageIconNuspecExample) +[Package Icon nuspec sample.](https://github.com/NuGet/Samples/tree/main/PackageIconNuspecExample) For the MSBuild equivalent, take a look at [Packing an icon image file](msbuild-targets.md#packing-an-icon-image-file). +> [!Tip] +> To maintain backward compatibility with clients and sources that don't yet support `icon`, specify both `icon` and `iconUrl`. Visual Studio supports `icon` for packages coming from a folder-based source. + +#### readme + +*Supported with **NuGet 5.10.0 preview 2** and above* + +When packing a readme file, you need to use the `readme` element to specify the package path, relative to the root of the package. In addition to this, you need to make sure that the file is included in the package. Supported file formats include only Markdown (*.md*). + +For example, you would add the following to your nuspec in order to pack a readme file with your project: + +```xml + + + ... + docs\readme.md + ... + + + ... + + ... + + +``` + +For the MSBuild equivalent, take a look at [Packing a readme file](msbuild-targets.md#packagereadmefile). + #### requireLicenseAcceptance A Boolean value specifying whether the client must prompt the consumer to accept the package license before installing the package. @@ -182,18 +249,26 @@ A Boolean value specifying whether the client must prompt the consumer to accept A short description of the package for UI display. If omitted, a truncated version of `description` is used. +When uploading a package to nuget.org, the `summary` field is limited to 4000 characters. + #### releaseNotes *(1.5+)* A description of the changes made in this release of the package, often used in UI like the **Updates** tab of the Visual Studio Package Manager in place of the package description. +When uploading a package to nuget.org, the `releaseNotes` field is limited to 35,000 characters. + #### copyright *(1.5+)* Copyright details for the package. +When uploading a package to nuget.org, the `copyright` field is limited to 4000 characters. + #### language The locale ID for the package. See [Creating localized packages](../create-packages/creating-localized-packages.md). #### tags A space-delimited list of tags and keywords that describe the package and aid discoverability of packages through search and filtering. +When uploading a package to nuget.org, the `tags` field is limited to 4000 characters. + #### serviceable *(3.3+)* For internal NuGet use only. @@ -203,7 +278,7 @@ Repository metadata, consisting of four optional attributes: `type` and `url` *( For example: ```xml - + ... @@ -212,21 +287,32 @@ For example: ``` +When uploading a package to nuget.org, the `type` attribute is limited to 100 characters and the `url` attribute is +limited to 4000 characters. + #### title A human-friendly title of the package which may be used in some UI displays. (nuget.org and the Package Manager in Visual Studio do not show title) +When uploading a package to nuget.org, the `title` field is limited to 256 characters but is not used for any +display purposes. + #### Collection elements #### packageTypes *(3.5+)* A collection of zero or more `` elements specifying the type of the package if other than a traditional dependency package. Each packageType has attributes of *name* and *version*. See [Setting a package type](../create-packages/set-package-type.md). + #### dependencies A collection of zero or more `` elements specifying the dependencies for the package. Each dependency has attributes of *id*, *version*, *include* (3.x+), and *exclude* (3.x+). See [Dependencies](#dependencies-element) below. + #### frameworkAssemblies -*(1.2+)* A collection of zero or more `` elements identifying .NET Framework assembly references that this package requires, which ensures that references are added to projects consuming the package. Each frameworkAssembly has *assemblyName* and *targetFramework* attributes. See [Specifying framework assembly references GAC](#specifying-framework-assembly-references-gac) below. | +*(1.2+)* A collection of zero or more `` elements identifying .NET Framework assembly references that this package requires, which ensures that references are added to projects consuming the package. Each frameworkAssembly has *assemblyName* and *targetFramework* attributes. See [Specifying framework assembly references GAC](#specifying-framework-assembly-references-gac) below. + #### references *(1.5+)* A collection of zero or more `` elements naming assemblies in the package's `lib` folder that are added as project references. Each reference has a *file* attribute. `` can also contain a `` element with a *targetFramework* attribute, that then contains `` elements. If omitted, all references in `lib` are included. See [Specifying explicit assembly references](#specifying-explicit-assembly-references) below. + #### contentFiles *(3.3+)* A collection of `` elements that identify content files to include in the consuming project. These files are specified with a set of attributes that describe how they should be used within the project system. See [Specifying files to include in the package](#specifying-files-to-include-in-the-package) below. + #### files The `` node may contain a `` node as a sibling to ``, and a `` child under ``, to specify which assembly and content files to include in the package. See [Including assembly files](#including-assembly-files) and [Including content files](#including-content-files) later in this topic for details. @@ -237,7 +323,7 @@ Specifies the minimum version of the NuGet client that can install this package, ```xml - + dasdas 2.0.0 @@ -255,7 +341,7 @@ Specifies the minimum version of the NuGet client that can install this package, ## Replacement tokens -When creating a package, the [`nuget pack` command](../reference/cli-reference/cli-ref-pack.md) replaces $-delimited tokens in the `.nuspec` file's `` node with values that come from either a project file or the `pack` command's `-properties` switch. +When creating a package, the [`nuget pack` command](../reference/cli-reference/cli-ref-pack.md) replaces $-delimited tokens in the `.nuspec` file's `` and `` nodes with values that come from either a project file or the `pack` command's `-properties` switch. On the command line, you specify token values with `nuget pack -properties =;=`. For example, you can use a token such as `$owners$` and `$desc$` in the `.nuspec` and provide the values at packing time as follows: @@ -309,10 +395,13 @@ The `` element within `` contains any number of `` element without a `targetFramework` attribute is used as the defau > [!Important] > The group format cannot be intermixed with a flat list. +> [!Note] +> The format of [Target Framework Moniker (TFM)](../reference/target-frameworks.md) used in `lib/ref` folder is different when compared to the TFM used in `dependency groups`. If the target frameworks declared in the `dependencies group` and the `lib/ref` folder of `.nuspec` file do not have exact matches then `pack` command will raise [NuGet Warning NU5128](../reference/errors-and-warnings/nu5128.md). + The following example shows different variations of the `` element: ```xml @@ -365,12 +457,12 @@ The following example shows different variations of the `` element: - + - + ``` @@ -477,66 +569,76 @@ Each `` element specifies the following attributes: **Single assembly** - Source file: - library.dll +``` +Source file: + library.dll - .nuspec entry: - +.nuspec entry: + - Packaged result: - lib\library.dll +Packaged result: + lib\library.dll +``` **Single assembly specific to a target framework** - Source file: - library.dll +``` +Source file: + library.dll - .nuspec entry: - +.nuspec entry: + - Packaged result: - lib\net40\library.dll +Packaged result: + lib\net40\library.dll +``` **Set of DLLs using a wildcard** - Source files: - bin\release\libraryA.dll - bin\release\libraryB.dll +``` +Source files: + bin\release\libraryA.dll + bin\release\libraryB.dll - .nuspec entry: - +.nuspec entry: + - Packaged result: - lib\libraryA.dll - lib\libraryB.dll +Packaged result: + lib\libraryA.dll + lib\libraryB.dll +``` **DLLs for different frameworks** - Source files: - lib\net40\library.dll - lib\net20\library.dll +``` +Source files: + lib\net40\library.dll + lib\net20\library.dll - .nuspec entry (using ** recursive search): - +.nuspec entry (using ** recursive search): + - Packaged result: - lib\net40\library.dll - lib\net20\library.dll +Packaged result: + lib\net40\library.dll + lib\net20\library.dll +``` **Excluding files** - Source files: - \tools\fileA.bak - \tools\fileB.bak - \tools\fileA.log - \tools\build\fileB.log - - .nuspec entries: - - - - Package result: - (no files) +``` +Source files: + \tools\fileA.bak + \tools\fileB.bak + \tools\fileA.log + \tools\build\fileB.log + +.nuspec entries: + + + +Package result: + (no files) +``` ## Including content files @@ -557,108 +659,124 @@ For content files, simply use the same format as for assembly files, but specify **Basic content files** - Source files: - css\mobile\style1.css - css\mobile\style2.css +``` +Source files: + css\mobile\style1.css + css\mobile\style2.css - .nuspec entry: - +.nuspec entry: + - Packaged result: - content\css\mobile\style1.css - content\css\mobile\style2.css +Packaged result: + content\css\mobile\style1.css + content\css\mobile\style2.css +``` **Content files with directory structure** - Source files: - css\mobile\style.css - css\mobile\wp7\style.css - css\browser\style.css - - .nuspec entry: - - - Packaged result: - content\css\mobile\style.css - content\css\mobile\wp7\style.css - content\css\browser\style.css +``` +Source files: + css\mobile\style.css + css\mobile\wp7\style.css + css\browser\style.css + +.nuspec entry: + + +Packaged result: + content\css\mobile\style.css + content\css\mobile\wp7\style.css + content\css\browser\style.css +``` **Content file specific to a target framework** - Source file: - css\cool\style.css +``` +Source file: + css\cool\style.css - .nuspec entry - +.nuspec entry + - Packaged result: - content\style.css +Packaged result: + content\style.css +``` **Content file copied to a folder with dot in name** In this case, NuGet sees that the extension in `target` does not match the extension in `src` and thus treats that part of the name in `target` as a folder: - Source file: - images\picture.png +``` +Source file: + images\picture.png - .nuspec entry: - +.nuspec entry: + - Packaged result: - content\images\package.icons\picture.png +Packaged result: + content\images\package.icons\picture.png +``` **Content files without extensions** To include files without an extension, use the `*` or `**` wildcards: - Source file: - flags\installed +``` +Source file: + flags\installed - .nuspec entry: - +.nuspec entry: + - Packaged result: - flags\installed +Packaged result: + flags\installed +``` **Content files with deep path and deep target** In this case, because the file extensions of the source and target match, NuGet assumes that the target is a file name and not a folder: - Source file: - css\cool\style.css +``` +Source file: + css\cool\style.css - .nuspec entry: - - or: - +.nuspec entry: + + or: + - Packaged result: - content\css\cool\style.css +Packaged result: + content\css\cool\style.css +``` **Renaming a content file in the package** - Source file: - ie\css\style.css +``` +Source file: + ie\css\style.css - .nuspec entry: - +.nuspec entry: + - Packaged result: - content\css\ie.css +Packaged result: + content\css\ie.css +``` **Excluding files** - Source file: - docs\*.txt (multiple files) +``` +Source file: + docs\*.txt (multiple files) - .nuspec entry: - - or - +.nuspec entry: + + or + - Packaged result: - All .txt files from docs except admin.txt (first example) - All .txt files from docs except admin.txt and log.txt (second example) +Packaged result: + All .txt files from docs except admin.txt (first example) + All .txt files from docs except admin.txt and log.txt (second example) +``` @@ -686,7 +804,9 @@ When installing a package, NuGet applies the child elements of `` The package project should structure content using the following pattern: - /contentFiles/{codeLanguage}/{TxM}/{any?} +``` +/contentFiles/{codeLanguage}/{TxM}/{any?} +``` - `codeLanguages` may be `cs`, `vb`, `fs`, `any`, or the lowercase equivalent of a given `$(ProjectLanguage)` - `TxM` is any legal target framework moniker that NuGet supports (see [Target frameworks](../reference/target-frameworks.md)). @@ -694,19 +814,23 @@ The package project should structure content using the following pattern: For example: - Language- and framework-agnostic: - /contentFiles/any/any/config.xml +``` +Language- and framework-agnostic: + /contentFiles/any/any/config.xml - net45 content for all languages - /contentFiles/any/net45/config.xml +net45 content for all languages + /contentFiles/any/net45/config.xml - C#-specific content for net45 and up - /contentFiles/cs/net45/sample.cs +C#-specific content for net45 and up + /contentFiles/cs/net45/sample.cs +``` -Empty folders can use `.` to opt out of providing content for certain combinations of language and TxM, for example: +Empty folders can use `_._` to opt out of providing content for certain combinations of language and TxM, for example: - /contentFiles/vb/any/code.vb - /contentFiles/cs/any/. +``` +/contentFiles/vb/any/code.vb +/contentFiles/cs/any/_._ +``` #### Example contentFiles section @@ -736,6 +860,33 @@ Empty folders can use `.` to opt out of providing content for certain combinatio ``` +## Framework reference groups + +*Version 5.1+ wih PackageReference only* + +Framework References are a .NET Core concept representing shared frameworks such as WPF or Windows Forms. +By specifying a shared framework, the package ensures that all its framework dependencies are included in the referencing project. + +Each `` element requires a `targetFramework` attribute and zero or more `` elements. + +The following example shows a nuspec generated for a .NET Core WPF project. +Note that hand authoring nuspecs that contain framework references is not recommended. Consider using the [targets](msbuild-targets.md) pack instead, which will automatically infer them from the project. + +```xml + + + + + + + + + + + + +``` + ## Example nuspec files **A simple `.nuspec` that does not specify dependencies or files** diff --git a/docs/reference/packages-config.md b/docs/reference/packages-config.md index f611acca1..19b8ddb60 100644 --- a/docs/reference/packages-config.md +++ b/docs/reference/packages-config.md @@ -1,17 +1,17 @@ --- title: NuGet packages.config File Reference description: In some project types, packages.config maintains the list of NuGet packages used in the project. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 05/21/2018 ms.topic: reference --- # packages.config reference -The `packages.config` file is used in some project types to maintain the list of packages referenced by the project. This allows NuGet to easily restore the project's dependencies when the project to be transported to a different machine, such as a build server, without all those packages. +The `packages.config` file is used in some project types to maintain the list of packages referenced by the project. This allows NuGet to easily restore the project's dependencies when the project is to be transported to a different machine, such as a build server, without all those packages. -If used, `packages.config` is typically located in a project root. It's automatically created when the first NuGet operation is run, but can also be created manually before running any commands such as `nuget restore`. +If used, `packages.config` must be located in a project root. It's automatically created when the first NuGet operation is run, but can also be created manually before running any commands such as `nuget restore`. Projects that use [PackageReference](../consume-packages/Package-References-in-Project-Files.md) do not use `packages.config`. @@ -24,7 +24,7 @@ The schema is simple: following the standard XML header is a single `` | id | Yes | The identifier of the package, such as Newtonsoft.json or Microsoft.AspNet.Mvc. | | version | Yes | The exact version of the package to install, such as 3.1.1 or 4.2.5.11-beta. A version string must have at least three numbers; a fourth is optional, as is a pre-release suffix. Ranges are not allowed. | | targetFramework | No | The [target framework moniker (TFM)](target-frameworks.md) to apply when installing the package. This is initially set to the project's target when a package is installed. As a result, different `` elements can have different TFMs. For example, if you create a project targeting .NET 4.5.2, packages installed at that point will use the TFM of net452. If you ;later retarget the project to .NET 4.6 and add more packages, those will use TFM of net46. A mismatch between the project's target and `targetFramework` attributes will generate warnings, in which case you can reinstall the affected packages. | -| allowedVersions | No | A range of allowed versions for this package applied during package update (see [Constraining upgrade versions](../consume-packages/reinstalling-and-updating-packages.md#constraining-upgrade-versions). It does *not* affect what package is installed during an install or restore operation. See [Package versioning](../concepts/package-versioning.md#version-ranges-and-wildcards) for syntax. The PackageManager UI also disables all versions outside the allowed range. | +| allowedVersions | No | A range of allowed versions for this package applied during package update (see [Constraints on upgrade versions](../consume-packages/reinstalling-and-updating-packages.md#constraints-on-upgrade-versions). It does *not* affect what package is installed during an install or restore operation. See [Package versioning](../concepts/package-versioning.md#version-ranges) for syntax. The PackageManager UI also disables all versions outside the allowed range. | | developmentDependency | No | If the consuming project itself creates a NuGet package, setting this to `true` for a dependency prevents that package from being included when the consuming package is created. The default is `false`. | ## Examples diff --git a/docs/reference/ps-reference/ps-ref-add-bindingredirect.md b/docs/reference/ps-reference/ps-ref-add-bindingredirect.md index 4fbb27509..2160e5771 100644 --- a/docs/reference/ps-reference/ps-ref-add-bindingredirect.md +++ b/docs/reference/ps-reference/ps-ref-add-bindingredirect.md @@ -1,8 +1,8 @@ --- title: NuGet Add-BindingRedirect PowerShell Reference description: Reference for Add-BindingRedirect PowerShell command in the NuGet Package Manager Console in Visual Studio. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 12/07/2017 ms.topic: reference --- @@ -13,6 +13,9 @@ ms.topic: reference Examines all assemblies within the output path for a project and adds binding redirects to the application or web configuration file where necessary. This command is run automatically when installing a package. +> [!NOTE] +> This only applies to scenarios using a packages.config file. For more information, see [NuGet packages.config file reference](~/reference/packages-config.md). + For details on binding redirects and why they are used, see [Redirecting Assembly Versions](/dotnet/framework/configure-apps/redirect-assembly-versions) in the .NET documentation. ## Syntax @@ -31,7 +34,7 @@ None of these parameters accept pipeline input or wildcard characters. ## Common Parameters -`Add-BindingRedirect` supports the following [common PowerShell parameters](http://go.microsoft.com/fwlink/?LinkID=113216): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. +`Add-BindingRedirect` supports the following [common PowerShell parameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. ## Examples diff --git a/docs/reference/ps-reference/ps-ref-find-package.md b/docs/reference/ps-reference/ps-ref-find-package.md index 1d9a9a6e9..cb81ce65a 100644 --- a/docs/reference/ps-reference/ps-ref-find-package.md +++ b/docs/reference/ps-reference/ps-ref-find-package.md @@ -1,15 +1,15 @@ --- title: NuGet Find-Package PowerShell Reference description: Reference for Find-Package PowerShell command in the NuGet Package Manager Console in Visual Studio. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 6/1/2017 ms.topic: reference --- # Find-Package (Package Manager Console in Visual Studio) -*Version 3.0+; this topic describes the command within the [Package Manager Console](../../consume-packages/install-use-packages-powershell.md) in Visual Studio on Windows. For the generic PowerShell Find-Package command, see the [PowerShell PackageManagement reference](/powershell/module/packagemanagement/?view=powershell-6).* +*Version 3.0+; this topic describes the command within the [Package Manager Console](../../consume-packages/install-use-packages-powershell.md) in Visual Studio on Windows. For the generic PowerShell Find-Package command, see the [PowerShell PackageManagement reference](/powershell/module/packagemanagement).* Gets the set of remote packages with specified ID or keywords from the package source. @@ -37,7 +37,7 @@ None of these parameters accept pipeline input or wildcard characters. ## Common Parameters -`Find-Package` supports the following [common PowerShell parameters](http://go.microsoft.com/fwlink/?LinkID=113216): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. +`Find-Package` supports the following [common PowerShell parameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. ## Examples @@ -54,4 +54,4 @@ Find-Package logging -First 100 # List all versions of the package with the ID of "jquery" Find-Package jquery -AllVersions -ExactMatch -``` +``` \ No newline at end of file diff --git a/docs/reference/ps-reference/ps-ref-get-package.md b/docs/reference/ps-reference/ps-ref-get-package.md index 673f91327..e1438cb21 100644 --- a/docs/reference/ps-reference/ps-ref-get-package.md +++ b/docs/reference/ps-reference/ps-ref-get-package.md @@ -1,15 +1,15 @@ --- title: NuGet Get-Package PowerShell Reference description: Reference for Get-Package PowerShell command in the NuGet Package Manager Console in Visual Studio. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 12/07/2017 ms.topic: reference --- # Get-Package (Package Manager Console in Visual Studio) -*This topic describes the command within the [Package Manager Console](../../consume-packages/install-use-packages-powershell.md) in Visual Studio on Windows. For the generic PowerShell Get-Package command, see the [PowerShell PackageManagement reference](/powershell/module/packagemanagement/?view=powershell-6).* +*This topic describes the command within the [Package Manager Console](../../consume-packages/install-use-packages-powershell.md) in Visual Studio on Windows. For the generic PowerShell Get-Package command, see the [PowerShell PackageManagement reference](/powershell/module/packagemanagement).* Retrieves the list of packages installed in the local repository, lists packages available from a package source when used with the -ListAvailable switch, or lists available updates when used with the -Update switch. @@ -42,7 +42,7 @@ None of these parameters accept pipeline input or wildcard characters. ## Common Parameters -`Get-Package` supports the following [common PowerShell parameters](http://go.microsoft.com/fwlink/?LinkID=113216): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. +`Get-Package` supports the following [common PowerShell parameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. ## Examples @@ -70,4 +70,4 @@ Get-Package -Updates # Lists packages installed in a specific project that have available updates Get-Package -Updates -ProjectName MyProject -``` +``` \ No newline at end of file diff --git a/docs/reference/ps-reference/ps-ref-get-project.md b/docs/reference/ps-reference/ps-ref-get-project.md index 0249130a8..5d071be5a 100644 --- a/docs/reference/ps-reference/ps-ref-get-project.md +++ b/docs/reference/ps-reference/ps-ref-get-project.md @@ -1,8 +1,8 @@ --- title: NuGet Get-Project PowerShell Reference description: Reference for GetProject PowerShell command in the NuGet Package Manager Console in Visual Studio. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 12/07/2017 ms.topic: reference --- @@ -30,7 +30,7 @@ None of these parameters accept pipeline input or wildcard characters. ## Common Parameters -`Get-Project` supports the following [common PowerShell parameters](http://go.microsoft.com/fwlink/?LinkID=113216): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. +`Get-Project` supports the following [common PowerShell parameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. ## Examples diff --git a/docs/reference/ps-reference/ps-ref-install-package.md b/docs/reference/ps-reference/ps-ref-install-package.md index a65853871..87e6d59b8 100644 --- a/docs/reference/ps-reference/ps-ref-install-package.md +++ b/docs/reference/ps-reference/ps-ref-install-package.md @@ -1,15 +1,15 @@ --- title: NuGet Install-Package PowerShell Reference description: Reference for Install-Package PowerShell command in the NuGet Package Manager Console in Visual Studio. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 06/01/2017 ms.topic: reference --- # Install-Package (Package Manager Console in Visual Studio) -*This topic describes the command within the [Package Manager Console](../../consume-packages/install-use-packages-powershell.md) in Visual Studio on Windows. For the generic PowerShell Install-Package command, see the [PowerShell PackageManagement reference](/powershell/module/packagemanagement/?view=powershell-6).* +*This topic describes the command within the [Package Manager Console](../../consume-packages/install-use-packages-powershell.md) in Visual Studio on Windows. For the generic PowerShell Install-Package command, see the [PowerShell PackageManagement reference](/powershell/module/packagemanagement).* Installs a package and its dependencies into a project. @@ -45,7 +45,7 @@ None of these parameters accept pipeline input or wildcard characters. ## Common Parameters -`Install-Package` supports the following [common PowerShell parameters](http://go.microsoft.com/fwlink/?LinkID=113216): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. +`Install-Package` supports the following [common PowerShell parameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. ## Examples @@ -69,4 +69,4 @@ Install-Package c:\temp\packages\jQuery.1.10.2.nupkg # Installs the specific online package # Note: the URL must end with ".nupkg" Install-Package https://globalcdn.nuget.org/packages/microsoft.aspnet.mvc.5.2.3.nupkg -``` +``` \ No newline at end of file diff --git a/docs/reference/ps-reference/ps-ref-open-packagepage.md b/docs/reference/ps-reference/ps-ref-open-packagepage.md index 5c6c14b17..689de08f6 100644 --- a/docs/reference/ps-reference/ps-ref-open-packagepage.md +++ b/docs/reference/ps-reference/ps-ref-open-packagepage.md @@ -1,8 +1,8 @@ --- title: NuGet Open-PackagePage PowerShell Reference description: Reference for Open-PackagePage PowerShell command in the NuGet Package Manager Console in Visual Studio. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 12/07/2017 ms.topic: reference --- @@ -35,7 +35,7 @@ None of these parameters accept pipeline input or wildcard characters. ## Common Parameters -`Open-PackagePage` supports the following [common PowerShell parameters](http://go.microsoft.com/fwlink/?LinkID=113216): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. +`Open-PackagePage` supports the following [common PowerShell parameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. ## Examples diff --git a/docs/reference/ps-reference/ps-ref-register-tabexpansion.md b/docs/reference/ps-reference/ps-ref-register-tabexpansion.md index b79d61146..e92e7323c 100644 --- a/docs/reference/ps-reference/ps-ref-register-tabexpansion.md +++ b/docs/reference/ps-reference/ps-ref-register-tabexpansion.md @@ -1,8 +1,8 @@ --- title: NuGet Register-TabExpansion PowerShell Reference description: Reference for Register-TabExpansion PowerShell command in the NuGet Package Manager Console in Visual Studio. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 12/07/2017 ms.topic: reference --- @@ -30,7 +30,7 @@ None of these parameters accept pipeline input or wildcard characters. ## Common Parameters -`Register-TabExpansion` supports the following [common PowerShell parameters](http://go.microsoft.com/fwlink/?LinkID=113216): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. +`Register-TabExpansion` supports the following [common PowerShell parameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. ## Examples @@ -44,4 +44,4 @@ Register-TabExpansion Update-Package @{'ProjectName' = {'EventManager', 'Utiliti The developer can then type `Update-Package -ProjectName `, press Tab, and see the expansions offered as auto-completion options: -![Example of using Register-TabExpansion](media/Register-TabExpansion-Example.png) +![Example of using Register-TabExpansion](media/Register-TabExpansion-Example.png) \ No newline at end of file diff --git a/docs/reference/ps-reference/ps-ref-sync-package.md b/docs/reference/ps-reference/ps-ref-sync-package.md index cbd9a0260..b9a46e6c9 100644 --- a/docs/reference/ps-reference/ps-ref-sync-package.md +++ b/docs/reference/ps-reference/ps-ref-sync-package.md @@ -1,8 +1,8 @@ --- title: NuGet Sync-Package PowerShell Reference description: Reference for Sync-Package PowerShell command in the NuGet Package Manager Console in Visual Studio. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 12/07/2017 ms.topic: reference --- @@ -39,7 +39,7 @@ None of these parameters accept pipeline input or wildcard characters. ## Common Parameters -`Sync-Package` supports the following [common PowerShell parameters](http://go.microsoft.com/fwlink/?LinkID=113216): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. +`Sync-Package` supports the following [common PowerShell parameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. ## Examples @@ -55,4 +55,4 @@ Sync-Package Microsoft.Aspnet.Mvc -IgnoreDependencies # Sync jQuery.Validation and install the highest version of jQuery (a dependency) from the package source Sync-Package jQuery.Validation -DependencyVersion highest -``` +``` \ No newline at end of file diff --git a/docs/reference/ps-reference/ps-ref-uninstall-package.md b/docs/reference/ps-reference/ps-ref-uninstall-package.md index 319671895..cf8430a0f 100644 --- a/docs/reference/ps-reference/ps-ref-uninstall-package.md +++ b/docs/reference/ps-reference/ps-ref-uninstall-package.md @@ -1,15 +1,15 @@ --- title: NuGet Uninstall-Package PowerShell Reference description: Reference for Uninstall-Package PowerShell command in the NuGet Package Manager Console in Visual Studio. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 06/01/2017 ms.topic: reference --- # Uninstall-Package (Package Manager Console in Visual Studio) -*This topic describes the command within the [Package Manager Console](../../consume-packages/install-use-packages-powershell.md) in Visual Studio on Windows. For the generic PowerShell Uninstall-Package command, see the [PowerShell PackageManagement reference](/powershell/module/packagemanagement/?view=powershell-6).* +*This topic describes the command within the [Package Manager Console](../../consume-packages/install-use-packages-powershell.md) in Visual Studio on Windows. For the generic PowerShell Uninstall-Package command, see the [PowerShell PackageManagement reference](/powershell/module/packagemanagement).* Removes a package from a project, optionally removing its dependencies. If other packages depend on this package, the command will fail unless the –Force option is specified. @@ -37,7 +37,7 @@ None of these parameters accept pipeline input or wildcard characters. ## Common Parameters -`Uninstall-Package` supports the following [common PowerShell parameters](http://go.microsoft.com/fwlink/?LinkID=113216): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. +`Uninstall-Package` supports the following [common PowerShell parameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. ## Examples @@ -50,4 +50,4 @@ Uninstall-Package Elmah -RemoveDependencies # Uninstalls the Elmah package even if another package depends on it Uninstall-Package Elmah -Force -``` +``` \ No newline at end of file diff --git a/docs/reference/ps-reference/ps-ref-update-package.md b/docs/reference/ps-reference/ps-ref-update-package.md index a1a42f22e..b8af43043 100644 --- a/docs/reference/ps-reference/ps-ref-update-package.md +++ b/docs/reference/ps-reference/ps-ref-update-package.md @@ -1,8 +1,8 @@ --- title: NuGet Update-Package PowerShell Reference description: Reference for Update-Package PowerShell command in the NuGet Package Manager Console in Visual Studio. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 12/07/2017 ms.topic: reference --- @@ -49,7 +49,7 @@ None of these parameters accept pipeline input or wildcard characters. ### Common Parameters -`Update-Package` supports the following [common PowerShell parameters](http://go.microsoft.com/fwlink/?LinkID=113216): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. +`Update-Package` supports the following [common PowerShell parameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters): Debug, Error Action, ErrorVariable, OutBuffer, OutVariable, PipelineVariable, Verbose, WarningAction, and WarningVariable. ### Examples @@ -76,11 +76,11 @@ Update-Package Elmah -ProjectName MvcApplication1 -Safe # (subject to version constraints). If this command rolls a dependency back to an earlier version, # use Update-Package to reinstall that one dependency without affecting the # dependent package. -Update-Package ELmah –reinstall +Update-Package Elmah –reinstall # Reinstall the Elmah package in just MyProject Update-Package Elmah -ProjectName MyProject -reinstall # Reinstall the same version of the original package without touching dependencies. -Update-Package ELmah –reinstall -ignoreDependencies +Update-Package Elmah –reinstall -ignoreDependencies ``` diff --git a/docs/reference/target-frameworks.md b/docs/reference/target-frameworks.md index fb8f510a3..a2c1e0df5 100644 --- a/docs/reference/target-frameworks.md +++ b/docs/reference/target-frameworks.md @@ -1,8 +1,8 @@ --- title: Target Frameworks Reference for NuGet description: NuGet target framework references identify and isolate framework-dependent components of a package. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 12/11/2017 ms.topic: reference ms.reviewer: anangaur @@ -18,14 +18,18 @@ NuGet uses target framework references in a variety of places to specifically id - [packages.config](../reference/packages-config.md): The `targetframework` attribute of a dependency specifies the variant of a package to install. > [!Note] -> The NuGet client source code that calculates the tables below is found in the following locations: -> - Supported framework names: [FrameworkConstants.cs](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.Frameworks/FrameworkConstants.cs) -> - Framework precedence and mapping: [DefaultFrameworkMappings.cs](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.Frameworks/DefaultFrameworkMappings.cs) +> NuGet supports all of the modern .NET target frameworks: +> - For a list of the latest target frameworks, see the [Target frameworks in SDK-style projects](/dotnet/standard/frameworks) documentation. ## Supported frameworks A framework is typically referenced by a short target framework moniker or TFM. In .NET Standard this is also generalized to *TxM* to allow a single reference to multiple frameworks. +> [!Note] +> The NuGet client source code that calculates the tables below is found in the following locations: +> - Supported framework names: [FrameworkConstants.cs](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.Frameworks/FrameworkConstants.cs) +> - Framework precedence and mapping: [DefaultFrameworkMappings.cs](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.Frameworks/DefaultFrameworkMappings.cs) + The NuGet clients support the frameworks in the table below. Equivalents are shown within brackets []. Note that some tools, such as `dotnet`, might use variations of canonical TFMs in some files. For example, `dotnet pack` uses `.NETCoreApp2.0` in a `.nuspec` file rather than `netcoreapp2.0`. The various NuGet client tools handle these variations properly, but you should always use canonical TFMs when editing files directly. | Name | Abbreviation | TFMs/TxMs | @@ -73,13 +77,21 @@ Universal Windows Platform | uap | uap [uap10.0] | | | | netstandard1.5 | | | | netstandard1.6 | | | | netstandard2.0 | -.NET Core App | netcoreapp | netcoreapp1.0 | +| | | netstandard2.1 | +.NET 5+ (and .NET Core) | netcoreapp | netcoreapp1.0 | | | | netcoreapp1.1 | | | | netcoreapp2.0 | | | | netcoreapp2.1 | | | | netcoreapp2.2 | +| | | netcoreapp3.0 | +| | | netcoreapp3.1 | +| | net | net5.0 | +| | | net6.0 | +| | | net7.0 | +| | | net8.0 | Tizen | tizen | tizen3 | | | | tizen4 | +| Native | native | native | ## Deprecated frameworks @@ -276,7 +288,7 @@ Additional frameworks defined by third parties provide compatibility with other | | WindowsPhone 8.1 (UWP) | | | WindowsPhone 8.0 (SL) | -Additionally, NuGet packages targeting Xamarin can use additional Xamarin-defined frameworks. See [Creating NuGet packages for Xamarin](https://developer.xamarin.com/guides/cross-platform/advanced/nuget/). +Additionally, NuGet packages targeting Xamarin can use additional Xamarin-defined frameworks: | Name | Description | .NET Standard | | --- | --- | --- diff --git a/docs/release-notes/Index.md b/docs/release-notes/Index.md index c0ae31649..745e8f4db 100644 --- a/docs/release-notes/Index.md +++ b/docs/release-notes/Index.md @@ -1,16 +1,64 @@ --- title: Release Notes description: Index of NuGet release notes and known issues for all versions. -author: karann-msft -ms.author: karann -ms.date: 08/14/2017 -ms.topic: conceptual +author: donnie-msft +ms.author: eagoodso +ms.date: 05/25/2022 +ms.topic: release-notes --- # Release Notes [Known Issues](../release-notes/known-issues.md) +[NuGet 7.0](../release-notes/NuGet-7.0.md) + +[NuGet 6.14](../release-notes/NuGet-6.14.md) + +[NuGet 6.13](../release-notes/NuGet-6.13.md) + +[NuGet 6.12](../release-notes/NuGet-6.12.md) + +[NuGet 6.11](../release-notes/NuGet-6.11.md) + +[NuGet 6.10](../release-notes/NuGet-6.10.md) + +[NuGet 6.9](../release-notes/NuGet-6.9.md) + +[NuGet 6.8](../release-notes/NuGet-6.8.md) + +[NuGet 6.7](../release-notes/NuGet-6.7.md) + +[NuGet 6.6](../release-notes/NuGet-6.6.md) + +[NuGet 6.5](../release-notes/NuGet-6.5.md) + +[NuGet 6.4](../release-notes/NuGet-6.4.md) + +[NuGet 6.3](../release-notes/NuGet-6.3.md) + +[NuGet 6.2](../release-notes/NuGet-6.2.md) + +[NuGet 6.1](../release-notes/NuGet-6.1.md) + +[NuGet 6.0](../release-notes/NuGet-6.0.md) + +[NuGet 5.11](../release-notes/NuGet-5.11.md) + +[NuGet 5.10](../release-notes/NuGet-5.10.md) + +[NuGet 5.9](../release-notes/NuGet-5.9.md) + +[NuGet 5.8](../release-notes/NuGet-5.8.md) + +[NuGet 5.7](../release-notes/NuGet-5.7.md) + +[NuGet 5.6](../release-notes/NuGet-5.6.md) + +[NuGet 5.5](../release-notes/NuGet-5.5.md) + +[NuGet 5.4](../release-notes/NuGet-5.4.md) + [NuGet 5.3](../release-notes/NuGet-5.3.md) [NuGet 5.2](../release-notes/NuGet-5.2-RTM.md) diff --git a/docs/release-notes/Known-Issues.md b/docs/release-notes/Known-Issues.md index ccd8f2ad4..051862356 100644 --- a/docs/release-notes/Known-Issues.md +++ b/docs/release-notes/Known-Issues.md @@ -1,10 +1,10 @@ --- title: Known Issues description: Known issues with NuGet including authentication, package installation, and tools. -author: karann-msft -ms.author: karann -ms.date: 11/11/2016 -ms.topic: conceptual +author: JonDouglas +ms.author: jodou +ms.date: 06/06/2024 +ms.topic: troubleshooting-known-issue --- # Known Issues with NuGet @@ -14,6 +14,25 @@ These are the most common known issues with NuGet that are repeatedly reported. > [!Note] > Starting with NuGet 4.0, known issues are a part of the respective release notes. +## NuGet Audit settings may not be applied correctly for projects using packages.config in Visual Studio 17.10 + +NuGet Audit support was added for packages.config projects starting from NuGet 6.10 and Visual Studio 17.10. +Information on how to configure NuGet Audit can be found in our docs on [our docs on auditing packages](../concepts/Auditing-Packages.md). + +**Problem:** + +If two or more projects using packages.config in the solution use the same project name, then NuGet Audit will choose one and use the same NuGet Audit settings for both projects. + +The tracking issue to remove this limitation is [available on GitHub](https://github.com/NuGet/Home/issues/13466). + +**Workaround:** + +If all projects with the same name use the same configuration values, then there will be no functional difference when NuGet restores one project using a different project's configuration. + +NuGet.exe does not have this limitation, so you can [download NuGet.exe](../install-nuget-client-tools.md#nugetexe-cli) and run `NuGet.exe restore` on your solution to see if the NuGet Audit warnings are different on the command line to what Visual Studio is reporting. + +If it is feasible to rename the projects so they have different project names, then this problem scenario will not be encountered. + ## Authentication issues with NuGet feeds in VSTS with nuget.exe v3.4.3 **Problem:** @@ -64,11 +83,13 @@ This is caused by the type library for the `VSLangProj.dll` COM component being Run this command from an **elevated prompt** to re-register the type library for `VSLangProj.dll` - regsvr32 "C:\Program Files (x86)\Common Files\microsoft shared\MSEnv\VsLangproj.olb" +``` +regsvr32 "C:\Program Files (x86)\Common Files\microsoft shared\MSEnv\VsLangproj.olb" +``` If the command fails, check to see if the file exists in that location. -For more information about this error, see this [work item](https://nuget.codeplex.com/workitem/3609 "Work item 3609"). +For more information about this error, see this ```[work item](https://nuget.codeplex.com/workitem/3609 "Work item 3609")```. ## Build failure after package update in VS 2012 @@ -87,47 +108,51 @@ If you are running VS 2010 SP1, you might run into the following error message w When viewing the logs, you might see a mention of a `SignatureMismatchException`. To prevent this from occurring, there is a [Visual Studio 2010 SP1 hotfix](http://bit.ly/vsixcertfix) you can install. -Alternatively, the workaround is to simply uninstall NuGet (while running Visual Studio as Administrator) and then install it from the VS Extension Gallery. See [http://support.microsoft.com/kb/2581019](http://support.microsoft.com/kb/2581019) for more information. +Alternatively, the workaround is to simply uninstall NuGet (while running Visual Studio as Administrator) and then install it from the VS Extension Gallery. See for more information. ## Package Manager Console throws an exception when the Reflector Visual Studio Add-In is also installed. When running the Package Manager console, you may run into the following exception message if you have the Reflector VS Add-in installed. - The following error occurred while loading the extended type data file: - Microsoft.PowerShell.Core, C:\Windows\SysWOW64\WindowsPowerShell\v1.0\types.ps1xml(2950) : - Error in type "System.Security.AccessControl.ObjectSecurity": - Exception: Cannot convert the "Microsoft.PowerShell.Commands.SecurityDescriptorCommandsBase" - value of type "System.String" to type "System.Type". - System.Management.Automation.ActionPreferenceStopException: - Command execution stopped because the preference variable "ErrorActionPreference" or common parameter - is set to Stop: Unable to find type +``` +The following error occurred while loading the extended type data file: +Microsoft.PowerShell.Core, C:\Windows\SysWOW64\WindowsPowerShell\v1.0\types.ps1xml(2950) : +Error in type "System.Security.AccessControl.ObjectSecurity": +Exception: Cannot convert the "Microsoft.PowerShell.Commands.SecurityDescriptorCommandsBase" +value of type "System.String" to type "System.Type". +System.Management.Automation.ActionPreferenceStopException: +Command execution stopped because the preference variable "ErrorActionPreference" or common parameter +is set to Stop: Unable to find type +``` or - System.Management.Automation.CmdletInvocationException: Could not load file or assembly 'Scripts\nuget.psm1' or one of its dependencies.
    The parameter is incorrect. (Exception from HRESULT: 0x80070057 (E_INVALIDARG)) ---> System.IO.FileLoadException: Could not load file or
    assembly 'Scripts\nuget.psm1' or one of its dependencies. The parameter is incorrect. (Exception from HRESULT: 0x80070057 (E_INVALIDARG))
    ---> System.ArgumentException: Illegal characters in path. - at System.IO.Path.CheckInvalidPathChars(String path) - at System.IO.Path.Combine(String path1, String path2) - at Microsoft.VisualStudio.Platform.VsAppDomainManager.d__1.MoveNext() - at Microsoft.VisualStudio.Platform.VsAppDomainManager.InnerResolveHandler(String name) - at Microsoft.VisualStudio.Platform.VsAppDomainManager.ResolveHandler(Object sender, ResolveEventArgs args) - at System.AppDomain.OnAssemblyResolveEvent(RuntimeAssembly assembly, String assemblyFullName) - --- End of inner exception stack trace --- - at Microsoft.PowerShell.Commands.ModuleCmdletBase.LoadBinaryModule(Boolean trySnapInName, String moduleName, String fileName,
    Assembly assemblyToLoad, String moduleBase, SessionState ss, String prefix, Boolean loadTypes, Boolean loadFormats, Boolean& found) - at Microsoft.PowerShell.Commands.ModuleCmdletBase.LoadModuleNamedInManifest(String moduleName, String moduleBase,
    Boolean searchModulePath,
    String prefix, SessionState ss, Boolean loadTypesFiles, Boolean loadFormatFiles, Boolean& found) - at Microsoft.PowerShell.Commands.ModuleCmdletBase.LoadModuleManifest(ExternalScriptInfo scriptInfo, ManifestProcessingFlags
    manifestProcessingFlags, Version version) - at Microsoft.PowerShell.Commands.ModuleCmdletBase.LoadModule(String fileName, String moduleBase, String prefix, SessionState ss,
    Boolean& found) - at Microsoft.PowerShell.Commands.ImportModuleCommand.ProcessRecord() - at System.Management.Automation.Cmdlet.DoProcessRecord() - at System.Management.Automation.CommandProcessor.ProcessRecord() - --- End of inner exception stack trace --- - at System.Management.Automation.Runspaces.PipelineBase.Invoke(IEnumerable input) - at System.Management.Automation.Runspaces.Pipeline.Invoke() - at NuGetConsole.Host.PowerShell.Implementation.PowerShellHost.Invoke(String command, Object input, Boolean outputResults) - at NuGetConsole.Host.PowerShell.Implementation.PowerShellHostExtensions.ImportModule(PowerShellHost host, String modulePath) - at NuGetConsole.Host.PowerShell.Implementation.PowerShellHost.LoadStartupScripts() - at NuGetConsole.Host.PowerShell.Implementation.PowerShellHost.Initialize() - at NuGetConsole.Implementation.Console.ConsoleDispatcher.Start() - at NuGetConsole.Implementation.PowerConsoleToolWindow.MoveFocus(FrameworkElement consolePane) +``` +System.Management.Automation.CmdletInvocationException: Could not load file or assembly 'Scripts\nuget.psm1' or one of its dependencies.
    The parameter is incorrect. (Exception from HRESULT: 0x80070057 (E_INVALIDARG)) ---> System.IO.FileLoadException: Could not load file or
    assembly 'Scripts\nuget.psm1' or one of its dependencies. The parameter is incorrect. (Exception from HRESULT: 0x80070057 (E_INVALIDARG))
    ---> System.ArgumentException: Illegal characters in path. + at System.IO.Path.CheckInvalidPathChars(String path) + at System.IO.Path.Combine(String path1, String path2) + at Microsoft.VisualStudio.Platform.VsAppDomainManager.d__1.MoveNext() + at Microsoft.VisualStudio.Platform.VsAppDomainManager.InnerResolveHandler(String name) + at Microsoft.VisualStudio.Platform.VsAppDomainManager.ResolveHandler(Object sender, ResolveEventArgs args) + at System.AppDomain.OnAssemblyResolveEvent(RuntimeAssembly assembly, String assemblyFullName) + --- End of inner exception stack trace --- + at Microsoft.PowerShell.Commands.ModuleCmdletBase.LoadBinaryModule(Boolean trySnapInName, String moduleName, String fileName,
    Assembly assemblyToLoad, String moduleBase, SessionState ss, String prefix, Boolean loadTypes, Boolean loadFormats, Boolean& found) + at Microsoft.PowerShell.Commands.ModuleCmdletBase.LoadModuleNamedInManifest(String moduleName, String moduleBase,
    Boolean searchModulePath,
    String prefix, SessionState ss, Boolean loadTypesFiles, Boolean loadFormatFiles, Boolean& found) + at Microsoft.PowerShell.Commands.ModuleCmdletBase.LoadModuleManifest(ExternalScriptInfo scriptInfo, ManifestProcessingFlags
    manifestProcessingFlags, Version version) + at Microsoft.PowerShell.Commands.ModuleCmdletBase.LoadModule(String fileName, String moduleBase, String prefix, SessionState ss,
    Boolean& found) + at Microsoft.PowerShell.Commands.ImportModuleCommand.ProcessRecord() + at System.Management.Automation.Cmdlet.DoProcessRecord() + at System.Management.Automation.CommandProcessor.ProcessRecord() + --- End of inner exception stack trace --- + at System.Management.Automation.Runspaces.PipelineBase.Invoke(IEnumerable input) + at System.Management.Automation.Runspaces.Pipeline.Invoke() + at NuGetConsole.Host.PowerShell.Implementation.PowerShellHost.Invoke(String command, Object input, Boolean outputResults) + at NuGetConsole.Host.PowerShell.Implementation.PowerShellHostExtensions.ImportModule(PowerShellHost host, String modulePath) + at NuGetConsole.Host.PowerShell.Implementation.PowerShellHost.LoadStartupScripts() + at NuGetConsole.Host.PowerShell.Implementation.PowerShellHost.Initialize() + at NuGetConsole.Implementation.Console.ConsoleDispatcher.Start() + at NuGetConsole.Implementation.PowerConsoleToolWindow.MoveFocus(FrameworkElement consolePane) +``` We've contacted the author of the add-in in the hopes of working out a resolution. @@ -137,12 +162,14 @@ We've contacted the author of the add-in in the hopes of working out a resolutio You might see these errors when trying to open the Package Manager Console: - The following error occurred while loading the extended type data file: Microsoft.PowerShell.Core, C:\Windows\SysWOW64\WindowsPowerShell\v1.0\types.ps1xml(2977) : Error in type "System.Security.AccessControl.ObjectSecurity": Exception: The getter method should be public, non void, static, and have one parameter of type PSObject. - The following error occurred while loading the extended type data file: Microsoft.PowerShell.Core, C:\Windows\SysWOW64\WindowsPowerShell\v1.0\types.ps1xml(2984) : Error in type "System.Security.AccessControl.ObjectSecurity": Exception: The getter method should be public, non void, static, and have one parameter of type PSObject. - The following error occurred while loading the extended type data file: Microsoft.PowerShell.Core, C:\Windows\SysWOW64\WindowsPowerShell\v1.0\types.ps1xml(2991) : Error in type "System.Security.AccessControl.ObjectSecurity": Exception: The getter method should be public, non void, static, and have one parameter of type PSObject. - The following error occurred while loading the extended type data file: Microsoft.PowerShell.Core, C:\Windows\SysWOW64\WindowsPowerShell\v1.0\types.ps1xml(2998) : Error in type "System.Security.AccessControl.ObjectSecurity": Exception: The getter method should be public, non void, static, and have one parameter of type PSObject. - The following error occurred while loading the extended type data file: Microsoft.PowerShell.Core, C:\Windows\SysWOW64\WindowsPowerShell\v1.0\types.ps1xml(3005) : Error in type "System.Security.AccessControl.ObjectSecurity": Exception: The getter method should be public, non void, static, and have one parameter of type PSObject. - The term 'Get-ExecutionPolicy' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again. +``` +The following error occurred while loading the extended type data file: Microsoft.PowerShell.Core, C:\Windows\SysWOW64\WindowsPowerShell\v1.0\types.ps1xml(2977) : Error in type "System.Security.AccessControl.ObjectSecurity": Exception: The getter method should be public, non void, static, and have one parameter of type PSObject. +The following error occurred while loading the extended type data file: Microsoft.PowerShell.Core, C:\Windows\SysWOW64\WindowsPowerShell\v1.0\types.ps1xml(2984) : Error in type "System.Security.AccessControl.ObjectSecurity": Exception: The getter method should be public, non void, static, and have one parameter of type PSObject. +The following error occurred while loading the extended type data file: Microsoft.PowerShell.Core, C:\Windows\SysWOW64\WindowsPowerShell\v1.0\types.ps1xml(2991) : Error in type "System.Security.AccessControl.ObjectSecurity": Exception: The getter method should be public, non void, static, and have one parameter of type PSObject. +The following error occurred while loading the extended type data file: Microsoft.PowerShell.Core, C:\Windows\SysWOW64\WindowsPowerShell\v1.0\types.ps1xml(2998) : Error in type "System.Security.AccessControl.ObjectSecurity": Exception: The getter method should be public, non void, static, and have one parameter of type PSObject. +The following error occurred while loading the extended type data file: Microsoft.PowerShell.Core, C:\Windows\SysWOW64\WindowsPowerShell\v1.0\types.ps1xml(3005) : Error in type "System.Security.AccessControl.ObjectSecurity": Exception: The getter method should be public, non void, static, and have one parameter of type PSObject. +The term 'Get-ExecutionPolicy' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again. +``` If so, follow the solution [discussed on StackOverflow](http://stackoverflow.com/questions/12638289/embedding-powershell-v2-0-in-net-app-on-windows-8-rtm) to fix them. @@ -156,7 +183,7 @@ If you try to uninstall NuGet via the Visual Studio Extension Manager, you may n ## The Package Manager Console crashes when I open it in Windows XP. What's wrong? -NuGet requires Powershell 2.0 runtime. Windows XP, by default, doesn't have Powershell 2.0. You can download the Powershell 2.0 runtime from [http://support.microsoft.com/kb/968929](http://support.microsoft.com/kb/968929). After you install it, restart Visual Studio and you should be able to open Package Manager Console. +NuGet requires Powershell 2.0 runtime. Windows XP, by default, doesn't have Powershell 2.0. You can download the Powershell 2.0 runtime from [PowerShell 2.0 Download](https://devblogs.microsoft.com/powershell/tag/powershell-2-0-download/). After you install it, restart Visual Studio and you should be able to open Package Manager Console. ## Visual Studio 2010 SP1 Beta crashes on exit if the Package Manager Console is open. @@ -185,11 +212,13 @@ After following these steps, you should be able to continue. You might get the following error if you installs FluentNHibernate with the Package Manager console and then compile your project with "Code Analysis" turned on. - Error 3 CA0058 : The referenced assembly - 'NHibernate, Version=3.0.0.2001, Culture=neutral, PublicKeyToken=aa95f207798dfdb4' - could not be found. This assembly is required for analysis and was referenced by: - C:\temp\Scratch\src\MyProject.UnitTests\bin\Debug\MyProject.UnitTests.dll. - MyProject.UnitTests +``` +Error 3 CA0058 : The referenced assembly +'NHibernate, Version=3.0.0.2001, Culture=neutral, PublicKeyToken=aa95f207798dfdb4' +could not be found. This assembly is required for analysis and was referenced by: +C:\temp\Scratch\src\MyProject.UnitTests\bin\Debug\MyProject.UnitTests.dll. +MyProject.UnitTests +``` By default, FluentNHibernate requires NHibernate 3.0.0.2001. However, by design NuGet will install NHibernate 3.0.0.4000 in your project and add the appropriate binding redirects so that it will work. You project will compile just fine if code analysis is not turned on. In contrast to the compiler, code analysis tool doesn't properly follow the binding redirects to use 3.0.0.4000 instead of 3.0.0.2001. You can work around the issue by either installing NHibernate 3.0.0.2001 or tell the code analysis tool to behave the same as the compiler by doing the following: @@ -201,7 +230,9 @@ By default, FluentNHibernate requires NHibernate 3.0.0.2001. However, by design This is a known issue. Instead of calling Write-Error, try calling throw. - throw "My error message" +``` +throw "My error message" +``` ## Installing NuGet with restricted access on Windows 2003 can crash Visual Studio @@ -215,7 +246,9 @@ Clicking OK with that checked crashes Visual Studio. Make sure to uncheck that o Windows Phone Tools does not have support for the Visual Studio Extension Manager. In order to uninstall NuGet, run the following command. - vsixinstaller.exe /uninstall:NuPackToolsVsix.Microsoft.67e54e40-0ae3-42c5-a949-fddf5739e7a5 +``` +vsixinstaller.exe /uninstall:NuPackToolsVsix.Microsoft.67e54e40-0ae3-42c5-a949-fddf5739e7a5 +``` ## Changing the capitalization of NuGet package IDs breaks package restore diff --git a/docs/release-notes/NuGet-1.1.md b/docs/release-notes/NuGet-1.1.md index a9029e7b4..63b2c1586 100644 --- a/docs/release-notes/NuGet-1.1.md +++ b/docs/release-notes/NuGet-1.1.md @@ -1,10 +1,10 @@ --- title: NuGet 1.0 and 1.1 Release Notes description: Release notes for NuGet 1.1 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 1.0 and 1.1 Release Notes @@ -34,91 +34,91 @@ The NuGet Command Line Tool requires: ## Installation -To use this [latest release](http://nuget.codeplex.com/releases/view/52018): +To use this ```[latest release](http://nuget.codeplex.com/releases/view/52018)```: * First uninstall your older build. You need to run VS as administrator to do this. * Remove all the existing feeds that you have. -* Add a new feed pointing to [http://go.microsoft.com/fwlink/?LinkId=206669](http://go.microsoft.com/fwlink/?LinkId=206669). +* Add a new feed pointing to . ## NuGet 1.1 -The list of issues fixed in this release [can be found here](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%201.1&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0) +The list of issues fixed in this release ```[can be found here](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%201.1&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0)``` ## NuGet 1.0 RTM One issue was fixed for RTM since the RC. -* [Issue 474: Removing Packages Affects All Project In Solution](http://nuget.codeplex.com/workitem/474) +* ```[Issue 474: Removing Packages Affects All Project In Solution](http://nuget.codeplex.com/workitem/474)``` ## Release Candidate The following are the changes made in this Release Candidate since CTP 2. Visit the Issue Tracker to see the full list of bugs. -* [Updating Package from Console does not update dependencies.](http://nuget.codeplex.com/workitem/443) -* [Adding package picks up bin not package reference (CTP1)](http://nuget.codeplex.com/workitem/442) -* [Updating a package leaves broken references](http://nuget.codeplex.com/workitem/440) -* [Get-Package -Updates fails in the dialog, or when the 'All' aggregate source is selected in the console](http://nuget.codeplex.com/workitem/439) -* [Getting package verification errors](http://nuget.codeplex.com/workitem/426) -* [Warn users when a package cannot be installed from the Add Package Dialog](http://nuget.codeplex.com/workitem/425) -* [Get-Package -Updates throws when updating large number of packages](http://nuget.codeplex.com/workitem/424) -* [Improve error handling when nuspec files are authored incorrectly](http://nuget.codeplex.com/workitem/423) -* [Nuget pack ignores specified files](http://nuget.codeplex.com/workitem/422) -* [Removing the second-to-last package source and then clicking "Move Down" crashes VS](http://nuget.codeplex.com/workitem/418) -* [Remove assembly reference while installing packages](http://nuget.codeplex.com/workitem/413) -* [InvalidOperationException when opening Settings dialog](http://nuget.codeplex.com/workitem/411) -* [Access Key for Package Source in Package Manager Console doesn't work](http://nuget.codeplex.com/workitem/410) -* [NuGet VS Settings Dialog Access Keys Give Focus to Wrong Fields](http://nuget.codeplex.com/workitem/409) -* [Package ID intellisense should not query too many items](http://nuget.codeplex.com/workitem/404) -* [Failure adding package to project with a dot character in the Project name](http://nuget.codeplex.com/workitem/403) -* [Issue with specified files in nuspec](http://nuget.codeplex.com/workitem/400) -* [Correct official feed should get registered when using newer build](http://nuget.codeplex.com/workitem/399) -* [Tags should use spaces instead of #](http://nuget.codeplex.com/workitem/397) -* [IPackageMetadata lacks some useful information](http://nuget.codeplex.com/workitem/388) -* [Add Report Abuse Link to the Dialog](http://nuget.codeplex.com/workitem/386) -* [Using App_Data to unzip packages breaks in Visual Studio](http://nuget.codeplex.com/workitem/380) -* [Implement Tags](http://nuget.codeplex.com/workitem/376) -* [PackageBuilder allows empty package with no dependencies to be created](http://nuget.codeplex.com/workitem/373) -* [Add Owners Field for the Package](http://nuget.codeplex.com/workitem/365) -* [Update the VSIX manifest to say NuGet Package Manager rather than VSIX Tools](http://nuget.codeplex.com/workitem/364) -* [Get-Package command throws error when All source is selected](http://nuget.codeplex.com/workitem/359) -* [Allow ordering of package sources in Options dialog](http://nuget.codeplex.com/workitem/356) -* [Update-Package does not remove older version](http://nuget.codeplex.com/workitem/352) -* [Implement Version Range Specification for Dependencies](http://nuget.codeplex.com/workitem/347) -* [Visual Studio crashes when clicking "Add new package"](http://nuget.codeplex.com/workitem/346) -* [Display Downloads and Ratings in the Add Package Dialog](http://nuget.codeplex.com/workitem/345) -* [Changing between package sources in the Dialog doesn't update active source](http://nuget.codeplex.com/workitem/344) -* [Remove Key Binding for Package Manager Console Window](http://nuget.codeplex.com/workitem/339) -* [Install-Package is not recognized as the name of a cmdlet...](http://nuget.codeplex.com/workitem/338) -* [Installing a package from a local feed the dependencies on regular feeds are not resolved](http://nuget.codeplex.com/workitem/332) -* [RemoveDependencies should skip dependencies that are still in use](http://nuget.codeplex.com/workitem/331) -* [If cancelling page navigation, user cannot navigate to a different page while the original page request returns](http://nuget.codeplex.com/workitem/325) -* [Investigate performance of NuPack.Server for serving feeds with large number of packages.](http://nuget.codeplex.com/workitem/324) -* [The second time I filter for a package it uses the "New" package source, instead of the previously selected source.](http://nuget.codeplex.com/workitem/321) -* [Default package source should be selected when selecting the "Online" tab on the dialog.](http://nuget.codeplex.com/workitem/320) -* [List-Package should show installed packages by default](http://nuget.codeplex.com/workitem/309) -* [Assembly Reference HintPaths](http://nuget.codeplex.com/workitem/294) -* [Exception while opening Package Manager Console](http://nuget.codeplex.com/workitem/268) -* [Console intellisense downloads entire feed](http://nuget.codeplex.com/workitem/259) -* ['Default' package source should be renamed to 'Active'](http://nuget.codeplex.com/workitem/258) -* [Package sources UI: pressing OK should add the new source if Name/Source fields are non-empty](http://nuget.codeplex.com/workitem/257) -* [Dialog becomes super slow when the number of installed packages is large](http://nuget.codeplex.com/workitem/243) -* [Support Binding Redirects for Strong Named Assemblies](http://nuget.codeplex.com/workitem/238) -* [Add Package Reference... UI to include drop down for Package source](http://nuget.codeplex.com/workitem/226) -* [NuPack needs to support config transform agnostically of the config file name](http://nuget.codeplex.com/workitem/224) -* [Allows BasePath to be Overriden in NuPack.exe](http://nuget.codeplex.com/workitem/222) -* [Package Source Fallback Behavior](http://nuget.codeplex.com/workitem/204) -* [Crash on GUI](http://nuget.codeplex.com/workitem/201) -* [Add sorting options to Add Package Dialog](http://nuget.codeplex.com/workitem/179) -* [shortcut key to clear the Package Manager Console](http://nuget.codeplex.com/workitem/174) -* [PowerConsole causes NuPack Console to fail](http://nuget.codeplex.com/workitem/166) -* [Console and Add Package Dialog should set user agent in requests](http://nuget.codeplex.com/workitem/141) -* [Set version number of the VSIX and NuPack.exe in the build.](http://nuget.codeplex.com/workitem/134) -* [Hide common PowerShell parameters from -?](http://nuget.codeplex.com/workitem/118) -* [Add -detailed help for console commands](http://nuget.codeplex.com/workitem/110) -* [Add Package Dialog Should Allow Choosing the Current Package Source](http://nuget.codeplex.com/workitem/88) -* [Move NuPack.Core classes into different namespaces](http://nuget.codeplex.com/workitem/50) -* [Add help to cmdlets](http://nuget.codeplex.com/workitem/23) -* [Verify hash from feed after package download](http://nuget.codeplex.com/workitem/18) +* ```[Updating Package from Console does not update dependencies.](http://nuget.codeplex.com/workitem/443)``` +* ```[Adding package picks up bin not package reference (CTP1)](http://nuget.codeplex.com/workitem/442)``` +* ```[Updating a package leaves broken references](http://nuget.codeplex.com/workitem/440)``` +* ```[Get-Package -Updates fails in the dialog, or when the 'All' aggregate source is selected in the console](http://nuget.codeplex.com/workitem/439)``` +* ```[Getting package verification errors](http://nuget.codeplex.com/workitem/426)``` +* ```[Warn users when a package cannot be installed from the Add Package Dialog](http://nuget.codeplex.com/workitem/425)``` +* ```[Get-Package -Updates throws when updating large number of packages](http://nuget.codeplex.com/workitem/424)``` +* ```[Improve error handling when nuspec files are authored incorrectly](http://nuget.codeplex.com/workitem/423)``` +* ```[Nuget pack ignores specified files](http://nuget.codeplex.com/workitem/422)``` +* ```[Removing the second-to-last package source and then clicking "Move Down" crashes VS](http://nuget.codeplex.com/workitem/418)``` +* ```[Remove assembly reference while installing packages](http://nuget.codeplex.com/workitem/413)``` +* ```[InvalidOperationException when opening Settings dialog](http://nuget.codeplex.com/workitem/411)``` +* ```[Access Key for Package Source in Package Manager Console doesn't work](http://nuget.codeplex.com/workitem/410)``` +* ```[NuGet VS Settings Dialog Access Keys Give Focus to Wrong Fields](http://nuget.codeplex.com/workitem/409)``` +* ```[Package ID intellisense should not query too many items](http://nuget.codeplex.com/workitem/404)``` +* ```[Failure adding package to project with a dot character in the Project name](http://nuget.codeplex.com/workitem/403)``` +* ```[Issue with specified files in nuspec](http://nuget.codeplex.com/workitem/400)``` +* ```[Correct official feed should get registered when using newer build](http://nuget.codeplex.com/workitem/399)``` +* ```[Tags should use spaces instead of #](http://nuget.codeplex.com/workitem/397)``` +* ```[IPackageMetadata lacks some useful information](http://nuget.codeplex.com/workitem/388)``` +* ```[Add Report Abuse Link to the Dialog](http://nuget.codeplex.com/workitem/386)``` +* ```[Using App_Data to unzip packages breaks in Visual Studio](http://nuget.codeplex.com/workitem/380)``` +* ```[Implement Tags](http://nuget.codeplex.com/workitem/376)``` +* ```[PackageBuilder allows empty package with no dependencies to be created](http://nuget.codeplex.com/workitem/373)``` +* ```[Add Owners Field for the Package](http://nuget.codeplex.com/workitem/365)``` +* ```[Update the VSIX manifest to say NuGet Package Manager rather than VSIX Tools](http://nuget.codeplex.com/workitem/364)``` +* ```[Get-Package command throws error when All source is selected](http://nuget.codeplex.com/workitem/359)``` +* ```[Allow ordering of package sources in Options dialog](http://nuget.codeplex.com/workitem/356)``` +* ```[Update-Package does not remove older version](http://nuget.codeplex.com/workitem/352)``` +* ```[Implement Version Range Specification for Dependencies](http://nuget.codeplex.com/workitem/347)``` +* ```[Visual Studio crashes when clicking "Add new package"](http://nuget.codeplex.com/workitem/346)``` +* ```[Display Downloads and Ratings in the Add Package Dialog](http://nuget.codeplex.com/workitem/345)``` +* ```[Changing between package sources in the Dialog doesn't update active source](http://nuget.codeplex.com/workitem/344)``` +* ```[Remove Key Binding for Package Manager Console Window](http://nuget.codeplex.com/workitem/339)``` +* ```[Install-Package is not recognized as the name of a cmdlet...](http://nuget.codeplex.com/workitem/338)``` +* ```[Installing a package from a local feed the dependencies on regular feeds are not resolved](http://nuget.codeplex.com/workitem/332)``` +* ```[RemoveDependencies should skip dependencies that are still in use](http://nuget.codeplex.com/workitem/331)``` +* ```[If cancelling page navigation, user cannot navigate to a different page while the original page request returns](http://nuget.codeplex.com/workitem/325)``` +* ```[Investigate performance of NuPack.Server for serving feeds with large number of packages.](http://nuget.codeplex.com/workitem/324)``` +* ```[The second time I filter for a package it uses the "New" package source, instead of the previously selected source.](http://nuget.codeplex.com/workitem/321)``` +* ```[Default package source should be selected when selecting the "Online" tab on the dialog.](http://nuget.codeplex.com/workitem/320)``` +* ```[List-Package should show installed packages by default](http://nuget.codeplex.com/workitem/309)``` +* ```[Assembly Reference HintPaths](http://nuget.codeplex.com/workitem/294)``` +* ```[Exception while opening Package Manager Console](http://nuget.codeplex.com/workitem/268)``` +* ```[Console intellisense downloads entire feed](http://nuget.codeplex.com/workitem/259)``` +* ```['Default' package source should be renamed to 'Active'](http://nuget.codeplex.com/workitem/258)``` +* ```[Package sources UI: pressing OK should add the new source if Name/Source fields are non-empty](http://nuget.codeplex.com/workitem/257)``` +* ```[Dialog becomes super slow when the number of installed packages is large](http://nuget.codeplex.com/workitem/243)``` +* ```[Support Binding Redirects for Strong Named Assemblies](http://nuget.codeplex.com/workitem/238)``` +* ```[Add Package Reference... UI to include drop down for Package source](http://nuget.codeplex.com/workitem/226)``` +* ```[NuPack needs to support config transform agnostically of the config file name](http://nuget.codeplex.com/workitem/224)``` +* ```[Allows BasePath to be Overriden in NuPack.exe](http://nuget.codeplex.com/workitem/222)``` +* ```[Package Source Fallback Behavior](http://nuget.codeplex.com/workitem/204)``` +* ```[Crash on GUI](http://nuget.codeplex.com/workitem/201)``` +* ```[Add sorting options to Add Package Dialog](http://nuget.codeplex.com/workitem/179)``` +* ```[shortcut key to clear the Package Manager Console](http://nuget.codeplex.com/workitem/174)``` +* ```[PowerConsole causes NuPack Console to fail](http://nuget.codeplex.com/workitem/166)``` +* ```[Console and Add Package Dialog should set user agent in requests](http://nuget.codeplex.com/workitem/141)``` +* ```[Set version number of the VSIX and NuPack.exe in the build.](http://nuget.codeplex.com/workitem/134)``` +* ```[Hide common PowerShell parameters from -?](http://nuget.codeplex.com/workitem/118)``` +* ```[Add -detailed help for console commands](http://nuget.codeplex.com/workitem/110)``` +* ```[Add Package Dialog Should Allow Choosing the Current Package Source](http://nuget.codeplex.com/workitem/88)``` +* ```[Move NuPack.Core classes into different namespaces](http://nuget.codeplex.com/workitem/50)``` +* ```[Add help to cmdlets](http://nuget.codeplex.com/workitem/23)``` +* ```[Verify hash from feed after package download](http://nuget.codeplex.com/workitem/18)``` ## CTP 2 @@ -129,143 +129,143 @@ The following are the most significant changes made in CTP 2: * Updated the `.nuspec` Format. The `.nuspec` format now includes the *iconUrl* field for specifying a 32x32 png icon which will show up in the Add Package Dialog. So be sure to set that to distinguish your package. The `.nuspec` format also includes the new *projectUrl* field which you can use to point to a web page that provides more information about your package. This build will not work with old `.nupkg` files. If you get null reference exceptions, you're using an old `.nupkg` file and -need to rebuild it with the updated [NuGet command line tool](http://nuget.codeplex.com/releases/52017/download/165468). +need to rebuild it with the updated ```[NuGet command line tool](http://nuget.codeplex.com/releases/52017/download/165468)```. The following is a list of features and bugs that were fixed for NuGet CTP 2 (does not include bugs for minor code cleanups etc.). -* [Error unpacking package assemblies when specifiying the TargetFramework for an assembly.](http://nuget.codeplex.com/workitem/10) -* [Make NuPack Console window more discoverable](http://nuget.codeplex.com/workitem/14) -* [ILMerge the nupack.exe release](http://nuget.codeplex.com/workitem/19) -* [Better error/exception handling](http://nuget.codeplex.com/workitem/24) -* [[Nupack.Core]: PackageManager should gracefully handle feed-related errors](http://nuget.codeplex.com/workitem/28) -* [Need a new icon for the console](http://nuget.codeplex.com/workitem/29) -* [Localize strings in the Dialog](http://nuget.codeplex.com/workitem/38) -* [NuPack caches downloaded .nupack files in memory](http://nuget.codeplex.com/workitem/40) -* [NuPack Console: Change the default shortcut for displaying console](http://nuget.codeplex.com/workitem/48) -* [ProjectSystem should support default values for common properties](http://nuget.codeplex.com/workitem/49) -* [Running nupack.exe in a folder with just one nuspec file should use that nuspec](http://nuget.codeplex.com/workitem/52) -* [Project Menu Shows Up Even When No Project/Solution Is Loaded](http://nuget.codeplex.com/workitem/54) -* [build.cmd fails on a clean clone of the codebase](http://nuget.codeplex.com/workitem/56) -* [Updates available feature](http://nuget.codeplex.com/workitem/57) -* [Dialog: Adding a package through the dialog removes the prompt in the console](http://nuget.codeplex.com/workitem/73) -* [Adding a package by clicking 'Install' is often slow, with no visual feedback](http://nuget.codeplex.com/workitem/80) -* [There is no way to discover which of my installed packages have updates.](http://nuget.codeplex.com/workitem/82) -* [There is no way to update an installed package in the dialog.](http://nuget.codeplex.com/workitem/83) -* [There is no way to uninstall an installed package in the dialog](http://nuget.codeplex.com/workitem/84) -* [“Add Package Reference…” appears on the context menu of installed references](http://nuget.codeplex.com/workitem/85) -* [After updating a package from the console, it shows both the old version and the new version as installed](http://nuget.codeplex.com/workitem/86) -* [The activity in the console, when using the dialog, disappears after use](http://nuget.codeplex.com/workitem/87) -* [Cleanup command line parsing in nupack.exe](http://nuget.codeplex.com/workitem/89) -* [Add a friendly name to package sources](http://nuget.codeplex.com/workitem/98) -* [Update .nuspec to support including package icons](http://nuget.codeplex.com/workitem/103) -* [Feed UI doesn't allow copying the URL](http://nuget.codeplex.com/workitem/105) -* [Better remove-package error handling.](http://nuget.codeplex.com/workitem/107) -* [Typing in Console Window depends on cursor focus](http://nuget.codeplex.com/workitem/112) -* [Error messages look awful](http://nuget.codeplex.com/workitem/116) -* [The performance of Remove-Package for a package that isn't installed is bad](http://nuget.codeplex.com/workitem/117) -* [Removing a package fails when there are no package sources](http://nuget.codeplex.com/workitem/119) -* [Remove-Package fails when the package source is unavailable](http://nuget.codeplex.com/workitem/120) -* [Add Title to the package metadata and the feed.](http://nuget.codeplex.com/workitem/125) -* [Add the -Source parameter back to Add-Package](http://nuget.codeplex.com/workitem/127) -* [List-Package should have a -Source parameter](http://nuget.codeplex.com/workitem/128) -* [Update NuPack.Server to require NuPack User Agent To Download Package](http://nuget.codeplex.com/workitem/142) -* [License Acceptance Dialog Must List Licenses For All Dependencies That Require Acceptance](http://nuget.codeplex.com/workitem/145) -* [Log an error when a package throws in the feed](http://nuget.codeplex.com/workitem/150) -* [NuPack.exe should not allow an empty <licenseurl> element](http://nuget.codeplex.com/workitem/152) -* [Rename List-Package to Get-Package, Add-Package to Install-Package, and Remove-Package to Uninstall-Package](http://nuget.codeplex.com/workitem/155) -* [Using the Add Package Reference menu item from the Solution Navigator crashes Visual Studio](http://nuget.codeplex.com/workitem/158) -* ["Available package sources" label is missing a colon](http://nuget.codeplex.com/workitem/160) -* [Make .nuspec xml element casing consistently camel cased](http://nuget.codeplex.com/workitem/161) -* [The NuPack VSIX's manifest needs to turn on the 'admin' bit](http://nuget.codeplex.com/workitem/162) -* [If you run List-Package with no feeds, you get null ref error](http://nuget.codeplex.com/workitem/164) -* [nuget.exe: specify destination path](http://nuget.codeplex.com/workitem/171) -* [Powershell Errors Opening Package Management Console on WinXP](http://nuget.codeplex.com/workitem/175) -* [VS Crashes while trying to load package list](http://nuget.codeplex.com/workitem/176) -* [allow meta packages (no files, only dependencies)](http://nuget.codeplex.com/workitem/180) -* [Convert Powershell Script to Powershell 2.0 Module](http://nuget.codeplex.com/workitem/181) -* [PathResolver should discard path portion preceeding wildcard characters when target is specified](http://nuget.codeplex.com/workitem/183) -* [No dependencies](http://nuget.codeplex.com/workitem/186) -* [Error installing Elmah](http://nuget.codeplex.com/workitem/192) -* [Config transforms don't work correctly with <configsections>](http://nuget.codeplex.com/workitem/194) -* [The variable '$global:projectCache' cannot be retrieved because it has not been set](http://nuget.codeplex.com/workitem/203) -* [Add MSBuild task for creating NuPack packages](http://nuget.codeplex.com/workitem/205) -* [list-package needs to support searching/filtering](http://nuget.codeplex.com/workitem/206) -* [Always display a link to license if the package author provides a license URL](http://nuget.codeplex.com/workitem/208) -* [Occasional "Access Denied" exception with Remove-Package](http://nuget.codeplex.com/workitem/213) -* [Unit Tests Failing: InvalidPackageIsExcludedFromFeedItems & CreatingFeedConvertsPackagesToAtomEntries](http://nuget.codeplex.com/workitem/214) -* [Allow for a fallback/default set of files if a specfic framework version cannot be found](http://nuget.codeplex.com/workitem/223) -* [Add Package Reference... UI cannot remove a package](http://nuget.codeplex.com/workitem/225) -* [Add Package Reference crashes studio when one or more project is unloaded](http://nuget.codeplex.com/workitem/228) -* [Config transform does not appear to work on web.debug.config file](http://nuget.codeplex.com/workitem/229) -* [init.ps1 not firing on custom package](http://nuget.codeplex.com/workitem/237) -* [When adding paths to the feedlist, the default button is set to OK, so if I press ENTER it automatically closes](http://nuget.codeplex.com/workitem/240) -* [Attempt to uninstall a dependency will crash VS if attempted 2 times in a row](http://nuget.codeplex.com/workitem/241) -* [Display the Project URL in the Add Package dialog](http://nuget.codeplex.com/workitem/253) -* [Default the Add-Package dialog to Installed Packages](http://nuget.codeplex.com/workitem/254) -* [Change Add Package Dialog menu item.](http://nuget.codeplex.com/workitem/261) -* [Rename namespaces and assemblies](http://nuget.codeplex.com/workitem/274) -* [Rename the NuPack Project to NuGet](http://nuget.codeplex.com/workitem/282) -* [Add the following text under the list of dependencies](http://nuget.codeplex.com/workitem/288) -* [Change the license acceptance text in the License Acceptance Dialog](http://nuget.codeplex.com/workitem/291) -* [Change the text in the License Acceptance Dialog above the list of packages](http://nuget.codeplex.com/workitem/292) -* [OData doesn't work with an fwlink URL](http://nuget.codeplex.com/workitem/304) -* [Package Manager UI: Over aggressive caching of package count used for paging](http://nuget.codeplex.com/workitem/317) -* [NuPack / NuGet -> Package Manager Console error](http://nuget.codeplex.com/workitem/335) -* [Add Package Dialog shows License Acceptance For Already Installed Packaged](http://nuget.codeplex.com/workitem/336) +* ```[Error unpacking package assemblies when specifiying the TargetFramework for an assembly.](http://nuget.codeplex.com/workitem/10)``` +* ```[Make NuPack Console window more discoverable](http://nuget.codeplex.com/workitem/14)``` +* ```[ILMerge the nupack.exe release](http://nuget.codeplex.com/workitem/19)``` +* ```[Better error/exception handling](http://nuget.codeplex.com/workitem/24)``` +* ```[[Nupack.Core]: PackageManager should gracefully handle feed-related errors](http://nuget.codeplex.com/workitem/28)``` +* ```[Need a new icon for the console](http://nuget.codeplex.com/workitem/29)``` +* ```[Localize strings in the Dialog](http://nuget.codeplex.com/workitem/38)``` +* ```[NuPack caches downloaded .nupack files in memory](http://nuget.codeplex.com/workitem/40)``` +* ```[NuPack Console: Change the default shortcut for displaying console](http://nuget.codeplex.com/workitem/48)``` +* ```[ProjectSystem should support default values for common properties](http://nuget.codeplex.com/workitem/49)``` +* ```[Running nupack.exe in a folder with just one nuspec file should use that nuspec](http://nuget.codeplex.com/workitem/52)``` +* ```[Project Menu Shows Up Even When No Project/Solution Is Loaded](http://nuget.codeplex.com/workitem/54)``` +* ```[build.cmd fails on a clean clone of the codebase](http://nuget.codeplex.com/workitem/56)``` +* ```[Updates available feature](http://nuget.codeplex.com/workitem/57)``` +* ```[Dialog: Adding a package through the dialog removes the prompt in the console](http://nuget.codeplex.com/workitem/73)``` +* ```[Adding a package by clicking 'Install' is often slow, with no visual feedback](http://nuget.codeplex.com/workitem/80)``` +* ```[There is no way to discover which of my installed packages have updates.](http://nuget.codeplex.com/workitem/82)``` +* ```[There is no way to update an installed package in the dialog.](http://nuget.codeplex.com/workitem/83)``` +* ```[There is no way to uninstall an installed package in the dialog](http://nuget.codeplex.com/workitem/84)``` +* ```[“Add Package Reference…” appears on the context menu of installed references](http://nuget.codeplex.com/workitem/85)``` +* ```[After updating a package from the console, it shows both the old version and the new version as installed](http://nuget.codeplex.com/workitem/86)``` +* ```[The activity in the console, when using the dialog, disappears after use](http://nuget.codeplex.com/workitem/87)``` +* ```[Cleanup command line parsing in nupack.exe](http://nuget.codeplex.com/workitem/89)``` +* ```[Add a friendly name to package sources](http://nuget.codeplex.com/workitem/98)``` +* ```[Update .nuspec to support including package icons](http://nuget.codeplex.com/workitem/103)``` +* ```[Feed UI doesn't allow copying the URL](http://nuget.codeplex.com/workitem/105)``` +* ```[Better remove-package error handling.](http://nuget.codeplex.com/workitem/107)``` +* ```[Typing in Console Window depends on cursor focus](http://nuget.codeplex.com/workitem/112)``` +* ```[Error messages look awful](http://nuget.codeplex.com/workitem/116)``` +* ```[The performance of Remove-Package for a package that isn't installed is bad](http://nuget.codeplex.com/workitem/117)``` +* ```[Removing a package fails when there are no package sources](http://nuget.codeplex.com/workitem/119)``` +* ```[Remove-Package fails when the package source is unavailable](http://nuget.codeplex.com/workitem/120)``` +* ```[Add Title to the package metadata and the feed.](http://nuget.codeplex.com/workitem/125)``` +* ```[Add the -Source parameter back to Add-Package](http://nuget.codeplex.com/workitem/127)``` +* ```[List-Package should have a -Source parameter](http://nuget.codeplex.com/workitem/128)``` +* ```[Update NuPack.Server to require NuPack User Agent To Download Package](http://nuget.codeplex.com/workitem/142)``` +* ```[License Acceptance Dialog Must List Licenses For All Dependencies That Require Acceptance](http://nuget.codeplex.com/workitem/145)``` +* ```[Log an error when a package throws in the feed](http://nuget.codeplex.com/workitem/150)``` +* ```[NuPack.exe should not allow an empty <licenseurl> element](http://nuget.codeplex.com/workitem/152)``` +* ```[Rename List-Package to Get-Package, Add-Package to Install-Package, and Remove-Package to Uninstall-Package](http://nuget.codeplex.com/workitem/155)``` +* ```[Using the Add Package Reference menu item from the Solution Navigator crashes Visual Studio](http://nuget.codeplex.com/workitem/158)``` +* ```["Available package sources" label is missing a colon](http://nuget.codeplex.com/workitem/160)``` +* ```[Make .nuspec xml element casing consistently camel cased](http://nuget.codeplex.com/workitem/161)``` +* ```[The NuPack VSIX's manifest needs to turn on the 'admin' bit](http://nuget.codeplex.com/workitem/162)``` +* ```[If you run List-Package with no feeds, you get null ref error](http://nuget.codeplex.com/workitem/164)``` +* ```[nuget.exe: specify destination path](http://nuget.codeplex.com/workitem/171)``` +* ```[Powershell Errors Opening Package Management Console on WinXP](http://nuget.codeplex.com/workitem/175)``` +* ```[VS Crashes while trying to load package list](http://nuget.codeplex.com/workitem/176)``` +* ```[allow meta packages (no files, only dependencies)](http://nuget.codeplex.com/workitem/180)``` +* ```[Convert Powershell Script to Powershell 2.0 Module](http://nuget.codeplex.com/workitem/181)``` +* ```[PathResolver should discard path portion preceeding wildcard characters when target is specified](http://nuget.codeplex.com/workitem/183)``` +* ```[No dependencies](http://nuget.codeplex.com/workitem/186)``` +* ```[Error installing Elmah](http://nuget.codeplex.com/workitem/192)``` +* ```[Config transforms don't work correctly with <configsections>](http://nuget.codeplex.com/workitem/194)``` +* ```[The variable '$global:projectCache' cannot be retrieved because it has not been set](http://nuget.codeplex.com/workitem/203)``` +* ```[Add MSBuild task for creating NuPack packages](http://nuget.codeplex.com/workitem/205)``` +* ```[list-package needs to support searching/filtering](http://nuget.codeplex.com/workitem/206)``` +* ```[Always display a link to license if the package author provides a license URL](http://nuget.codeplex.com/workitem/208)``` +* ```[Occasional "Access Denied" exception with Remove-Package](http://nuget.codeplex.com/workitem/213)``` +* ```[Unit Tests Failing: InvalidPackageIsExcludedFromFeedItems & CreatingFeedConvertsPackagesToAtomEntries](http://nuget.codeplex.com/workitem/214)``` +* ```[Allow for a fallback/default set of files if a specfic framework version cannot be found](http://nuget.codeplex.com/workitem/223)``` +* ```[Add Package Reference... UI cannot remove a package](http://nuget.codeplex.com/workitem/225)``` +* ```[Add Package Reference crashes studio when one or more project is unloaded](http://nuget.codeplex.com/workitem/228)``` +* ```[Config transform does not appear to work on web.debug.config file](http://nuget.codeplex.com/workitem/229)``` +* ```[init.ps1 not firing on custom package](http://nuget.codeplex.com/workitem/237)``` +* ```[When adding paths to the feedlist, the default button is set to OK, so if I press ENTER it automatically closes](http://nuget.codeplex.com/workitem/240)``` +* ```[Attempt to uninstall a dependency will crash VS if attempted 2 times in a row](http://nuget.codeplex.com/workitem/241)``` +* ```[Display the Project URL in the Add Package dialog](http://nuget.codeplex.com/workitem/253)``` +* ```[Default the Add-Package dialog to Installed Packages](http://nuget.codeplex.com/workitem/254)``` +* ```[Change Add Package Dialog menu item.](http://nuget.codeplex.com/workitem/261)``` +* ```[Rename namespaces and assemblies](http://nuget.codeplex.com/workitem/274)``` +* ```[Rename the NuPack Project to NuGet](http://nuget.codeplex.com/workitem/282)``` +* ```[Add the following text under the list of dependencies](http://nuget.codeplex.com/workitem/288)``` +* ```[Change the license acceptance text in the License Acceptance Dialog](http://nuget.codeplex.com/workitem/291)``` +* ```[Change the text in the License Acceptance Dialog above the list of packages](http://nuget.codeplex.com/workitem/292)``` +* ```[OData doesn't work with an fwlink URL](http://nuget.codeplex.com/workitem/304)``` +* ```[Package Manager UI: Over aggressive caching of package count used for paging](http://nuget.codeplex.com/workitem/317)``` +* ```[NuPack / NuGet -> Package Manager Console error](http://nuget.codeplex.com/workitem/335)``` +* ```[Add Package Dialog shows License Acceptance For Already Installed Packaged](http://nuget.codeplex.com/workitem/336)``` ## CTP 1 The following is a list of features and bugs that were fixed for NuGet CTP 1. -* [Package extension should be renamed to .nupack](http://nuget.codeplex.com/workitem/1) -* [Move package file into folder](http://nuget.codeplex.com/workitem/2) -* [Merge install & Add PS commands](http://nuget.codeplex.com/workitem/3) -* [Create aliases for Verb-Noun cmdlets](http://nuget.codeplex.com/workitem/4) -* [NuPack gets confused when switching solution in VS](http://nuget.codeplex.com/workitem/6) -* [We should hide the 'packages' solution folder by default](http://nuget.codeplex.com/workitem/11) -* [Add support for token replacement in content items.](http://nuget.codeplex.com/workitem/12) -* [NuPack.UI should use the PackageSource API](http://nuget.codeplex.com/workitem/26) -* [[Nupack.Core]: PackageManager marks packages as installed prior to installing them](http://nuget.codeplex.com/workitem/27) -* [Deleting default project from solution still shows the deleted project as default](http://nuget.codeplex.com/workitem/30) -* [New-Package fails with "Cannot add part for the specified URI because it's already in the package."](http://nuget.codeplex.com/workitem/32) -* [Remove "NuPack" strings from Visual Studio GUI](http://nuget.codeplex.com/workitem/35) -* [Add Apache Header To a COPYRIGHT.txt file](http://nuget.codeplex.com/workitem/36) -* [Remove Update-PackageSource Command](http://nuget.codeplex.com/workitem/37) -* [Package Manager unusable when loading profile throws an exception](http://nuget.codeplex.com/workitem/39) -* [init.ps1, install.ps1 and uninstall.ps1 need to receive additional state](http://nuget.codeplex.com/workitem/41) -* [Combine Console and GUI Packages Into One Package](http://nuget.codeplex.com/workitem/42) -* [Xml transform logic doesn't work if applied to XML that isn't at the root](http://nuget.codeplex.com/workitem/43) -* [Manage package sources settings dialog not updating the NuPack console](http://nuget.codeplex.com/workitem/44) -* [NuPack Console UI: Rename 'Package feed' drop-down list to 'Package source'](http://nuget.codeplex.com/workitem/45) -* [NuPack Console Options: Rename 'Repository UI' to be consistent with NuPack Console](http://nuget.codeplex.com/workitem/46) -* [Add-Package fails against a website that was opened from IIS or a URL](http://nuget.codeplex.com/workitem/53) -* [Package Manager Source Doesn't Work With FwLink](http://nuget.codeplex.com/workitem/55) -* [Set the default package source](http://nuget.codeplex.com/workitem/59) -* [When adding package sources in option, when only one source is supplied, assume it's the default.](http://nuget.codeplex.com/workitem/60) -* [The Dialog UI shows fake "recent" packages](http://nuget.codeplex.com/workitem/62) -* [Options: Clicking cancel does not cancel changes](http://nuget.codeplex.com/workitem/63) -* [Add Package Reference Dialog Search should be case insensitive](http://nuget.codeplex.com/workitem/65) -* [Fix company metadata in AssemblyInfo.cs files](http://nuget.codeplex.com/workitem/67) -* [Version number for the VSIX](http://nuget.codeplex.com/workitem/71) -* [Remove-Package: Using -? displays help twice](http://nuget.codeplex.com/workitem/72) -* [Execute install/uninstall packages for project level packages](http://nuget.codeplex.com/workitem/74) -* [Server unable to create feed when one nupack fails validation](http://nuget.codeplex.com/workitem/90) -* [Need to Replace NuPack Icons](http://nuget.codeplex.com/workitem/94) -* [NTLM http proxy does not authenticate to the package feed.](http://nuget.codeplex.com/workitem/96) -* [The dialog doesn't always start centered in the VS window](http://nuget.codeplex.com/workitem/100) -* [Many of the fields in a packages details are not being populated in the dialog](http://nuget.codeplex.com/workitem/102) -* [Dialog UI doesn't show Authors' names](http://nuget.codeplex.com/workitem/108) -* [Why -Version for Remove-Package](http://nuget.codeplex.com/workitem/113) -* [Remove the Recent tab on the Dialog UI](http://nuget.codeplex.com/workitem/115) -* [VS crash when right click on solution folder after opening Dialog UI at least one.](http://nuget.codeplex.com/workitem/126) -* [Change the -Local parameter of List-Package to -Installed](http://nuget.codeplex.com/workitem/129) -* [Rename packages.xml to NuPack.config](http://nuget.codeplex.com/workitem/132) -* [Console forces cursor to the end of line](http://nuget.codeplex.com/workitem/135) -* [Remove-Package intellisense is broken](http://nuget.codeplex.com/workitem/136) -* [Add RequireLicenseAcceptance Flag to .nuspec and Feed](http://nuget.codeplex.com/workitem/137) -* [Add LicenseUrl to .nuspec Format and Package Feed](http://nuget.codeplex.com/workitem/138) -* [Clicking Install For Package That Requires Acceptance Should Show Acceptance Dialog](http://nuget.codeplex.com/workitem/139) -* [Add Disclaimer Text to the Add Package Dialog](http://nuget.codeplex.com/workitem/140) -* [Add Disclaimer When the Package Console is run the first time](http://nuget.codeplex.com/workitem/143) -* [Display Disclaimer After Installing Package In The Console](http://nuget.codeplex.com/workitem/144) -* [Rename the .nupack extension to .nupkg](http://nuget.codeplex.com/workitem/146) \ No newline at end of file +* ```[Package extension should be renamed to .nupack](http://nuget.codeplex.com/workitem/1)``` +* ```[Move package file into folder](http://nuget.codeplex.com/workitem/2)``` +* ```[Merge install & Add PS commands](http://nuget.codeplex.com/workitem/3)``` +* ```[Create aliases for Verb-Noun cmdlets](http://nuget.codeplex.com/workitem/4)``` +* ```[NuPack gets confused when switching solution in VS](http://nuget.codeplex.com/workitem/6)``` +* ```[We should hide the 'packages' solution folder by default](http://nuget.codeplex.com/workitem/11)``` +* ```[Add support for token replacement in content items.](http://nuget.codeplex.com/workitem/12)``` +* ```[NuPack.UI should use the PackageSource API](http://nuget.codeplex.com/workitem/26)``` +* ```[[Nupack.Core]: PackageManager marks packages as installed prior to installing them](http://nuget.codeplex.com/workitem/27)``` +* ```[Deleting default project from solution still shows the deleted project as default](http://nuget.codeplex.com/workitem/30)``` +* ```[New-Package fails with "Cannot add part for the specified URI because it's already in the package."](http://nuget.codeplex.com/workitem/32)``` +* ```[Remove "NuPack" strings from Visual Studio GUI](http://nuget.codeplex.com/workitem/35)``` +* ```[Add Apache Header To a COPYRIGHT.txt file](http://nuget.codeplex.com/workitem/36)``` +* ```[Remove Update-PackageSource Command](http://nuget.codeplex.com/workitem/37)``` +* ```[Package Manager unusable when loading profile throws an exception](http://nuget.codeplex.com/workitem/39)``` +* ```[init.ps1, install.ps1 and uninstall.ps1 need to receive additional state](http://nuget.codeplex.com/workitem/41)``` +* ```[Combine Console and GUI Packages Into One Package](http://nuget.codeplex.com/workitem/42)``` +* ```[Xml transform logic doesn't work if applied to XML that isn't at the root](http://nuget.codeplex.com/workitem/43)``` +* ```[Manage package sources settings dialog not updating the NuPack console](http://nuget.codeplex.com/workitem/44)``` +* ```[NuPack Console UI: Rename 'Package feed' drop-down list to 'Package source'](http://nuget.codeplex.com/workitem/45)``` +* ```[NuPack Console Options: Rename 'Repository UI' to be consistent with NuPack Console](http://nuget.codeplex.com/workitem/46)``` +* ```[Add-Package fails against a website that was opened from IIS or a URL](http://nuget.codeplex.com/workitem/53)``` +* ```[Package Manager Source Doesn't Work With FwLink](http://nuget.codeplex.com/workitem/55)``` +* ```[Set the default package source](http://nuget.codeplex.com/workitem/59)``` +* ```[When adding package sources in option, when only one source is supplied, assume it's the default.](http://nuget.codeplex.com/workitem/60)``` +* ```[The Dialog UI shows fake "recent" packages](http://nuget.codeplex.com/workitem/62)``` +* ```[Options: Clicking cancel does not cancel changes](http://nuget.codeplex.com/workitem/63)``` +* ```[Add Package Reference Dialog Search should be case insensitive](http://nuget.codeplex.com/workitem/65)``` +* ```[Fix company metadata in AssemblyInfo.cs files](http://nuget.codeplex.com/workitem/67)``` +* ```[Version number for the VSIX](http://nuget.codeplex.com/workitem/71)``` +* ```[Remove-Package: Using -? displays help twice](http://nuget.codeplex.com/workitem/72)``` +* ```[Execute install/uninstall packages for project level packages](http://nuget.codeplex.com/workitem/74)``` +* ```[Server unable to create feed when one nupack fails validation](http://nuget.codeplex.com/workitem/90)``` +* ```[Need to Replace NuPack Icons](http://nuget.codeplex.com/workitem/94)``` +* ```[NTLM http proxy does not authenticate to the package feed.](http://nuget.codeplex.com/workitem/96)``` +* ```[The dialog doesn't always start centered in the VS window](http://nuget.codeplex.com/workitem/100)``` +* ```[Many of the fields in a packages details are not being populated in the dialog](http://nuget.codeplex.com/workitem/102)``` +* ```[Dialog UI doesn't show Authors' names](http://nuget.codeplex.com/workitem/108)``` +* ```[Why -Version for Remove-Package](http://nuget.codeplex.com/workitem/113)``` +* ```[Remove the Recent tab on the Dialog UI](http://nuget.codeplex.com/workitem/115)``` +* ```[VS crash when right click on solution folder after opening Dialog UI at least one.](http://nuget.codeplex.com/workitem/126)``` +* ```[Change the -Local parameter of List-Package to -Installed](http://nuget.codeplex.com/workitem/129)``` +* ```[Rename packages.xml to NuPack.config](http://nuget.codeplex.com/workitem/132)``` +* ```[Console forces cursor to the end of line](http://nuget.codeplex.com/workitem/135)``` +* ```[Remove-Package intellisense is broken](http://nuget.codeplex.com/workitem/136)``` +* ```[Add RequireLicenseAcceptance Flag to .nuspec and Feed](http://nuget.codeplex.com/workitem/137)``` +* ```[Add LicenseUrl to .nuspec Format and Package Feed](http://nuget.codeplex.com/workitem/138)``` +* ```[Clicking Install For Package That Requires Acceptance Should Show Acceptance Dialog](http://nuget.codeplex.com/workitem/139)``` +* ```[Add Disclaimer Text to the Add Package Dialog](http://nuget.codeplex.com/workitem/140)``` +* ```[Add Disclaimer When the Package Console is run the first time](http://nuget.codeplex.com/workitem/143)``` +* ```[Display Disclaimer After Installing Package In The Console](http://nuget.codeplex.com/workitem/144)``` +* ```[Rename the .nupack extension to .nupkg](http://nuget.codeplex.com/workitem/146)``` diff --git a/docs/release-notes/NuGet-1.2.md b/docs/release-notes/NuGet-1.2.md index 3a7e1db10..f43a1121a 100644 --- a/docs/release-notes/NuGet-1.2.md +++ b/docs/release-notes/NuGet-1.2.md @@ -1,10 +1,10 @@ --- title: NuGet 1.2 Release Notes description: Release notes for NuGet 1.2 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 1.2 Release Notes @@ -68,12 +68,12 @@ you won’t need to specify it every time you push a package. For more details o ### Package Explorer Package Explorer has been updated to support NuGet 1.2. For more information, check out the -[Package Explorer release notes](http://nuget.codeplex.com/wikipage?title=New%20features%20in%20NuGet%20Package%20Explorer%201.0). +```[Package Explorer release notes](http://nuget.codeplex.com/wikipage?title=New%20features%20in%20NuGet%20Package%20Explorer%201.0)```. ## Other features/fixes The previous list were the most noticeable of the many features we implemented and bugs we fixed. All in all, we -implemented/fixed [59 work items](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%201.2&assignedTo=All&component=All&sortField=Votes&sortDirection=Descending&page=0) +implemented/fixed ```[59 work items](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%201.2&assignedTo=All&component=All&sortField=Votes&sortDirection=Descending&page=0)``` in this release. ## Known Issues @@ -87,4 +87,4 @@ need to update that project with the latest version of NuGet.Server. you need to uninstall NuGet first and then install it. This is listed in our [Known Issues page](../release-notes/known-issues.md) which provides more details. The issue only affects those running Visual Studio 2010 SP1 and have a version of NuGet 1.0 installed that was incorrectly signed. This version was only made available from the CodePlex website for a brief -period so this issue shouldn't affect too many people. \ No newline at end of file +period so this issue shouldn't affect too many people. diff --git a/docs/release-notes/NuGet-1.3.md b/docs/release-notes/NuGet-1.3.md index 0ef1a8c54..74115f60a 100644 --- a/docs/release-notes/NuGet-1.3.md +++ b/docs/release-notes/NuGet-1.3.md @@ -1,10 +1,10 @@ --- title: NuGet 1.3 Release Notes description: Release notes for NuGet 1.3 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 1.3 Release Notes @@ -25,31 +25,44 @@ The easy way to publish NuGet packages with sources. You can also watch a live d feature as part of the NuGet in Depth talk at Mix11. This feature is fully demonstrated starting at the 20 minute mark of the video. +> [!NOTE] +> The above is deprecated and no longer supported. + ### `Open-PackagePage` Command This command makes it easy to get to the project page for a package from within the Package Manager Console. It also provides options to open the license URL and the report abuse page for the package. The syntax for the command is: - Open-PackagePage -Id [-Version] [-Source] [-License] [-ReportAbuse] [-PassThru] +``` +Open-PackagePage -Id [-Version] [-Source] [-License] [-ReportAbuse] [-PassThru] +``` The `-PassThru` option is used to return the value of the specified URL. Examples: - PM> Open-PackagePage Ninject +``` +PM> Open-PackagePage Ninject +``` Opens a browser to the project URL specified in the Ninject package. - PM> Open-PackagePage Ninject -License +``` +PM> Open-PackagePage Ninject -License +``` Opens a browser to the license URL specified in the Ninject package. - PM> Open-PackagePage Ninject -ReportAbuse +``` +PM> Open-PackagePage Ninject -ReportAbuse +``` Opens a browser to the URL at the current package source used to report abuse for the specified package. - PM> $url = Open-PackagePage Ninject -License -WhatIf -PassThru +``` +PM> $url = Open-PackagePage Ninject -License -WhatIf -PassThru +``` Assigns the license URL to the variable, $url, without opening the URL in a browser. @@ -80,7 +93,7 @@ using two new flags: * __-Exclude__ is used to add other files/folders to exclude using a pattern. For example, to exclude all files with the '.bak' file extension -``` +```cli nuget Pack MyPackage.nuspec -Exclude **\*.bak ``` @@ -92,7 +105,7 @@ Thanks to community contributions, NuGet includes support for WiX project types ## Bug Fixes -For a full list of bug fixes, please view the [NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%201.3&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0). +For a full list of bug fixes, please view the ```[NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%201.3&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0)```. ## Bug fixes worth noting diff --git a/docs/release-notes/NuGet-1.4.md b/docs/release-notes/NuGet-1.4.md index 389525cb1..71514285b 100644 --- a/docs/release-notes/NuGet-1.4.md +++ b/docs/release-notes/NuGet-1.4.md @@ -1,10 +1,10 @@ --- title: NuGet 1.4 Release Notes description: Release notes for NuGet 1.4 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 1.4 Release Notes @@ -24,15 +24,21 @@ The `Update-Package` command now makes it easier to: #### Update all packages in a single project - Update-Package -Project MvcApplication1 +``` +Update-Package -Project MvcApplication1 +``` #### Update a package in all projects - Update-Package PackageId +``` +Update-Package PackageId +``` #### Update all packages in all projects - Update-Package +``` +Update-Package +``` #### Perform a "safe" update on all packages The `-Safe` flag constrains upgrades to only versions with the same Major and Minor version component. For example, @@ -40,7 +46,9 @@ if version 1.0.0 of a package is installed, and versions 1.0.1, 1.0.2, and 1.1 a flag updates the package to 1.0.2. Upgrading without the `-Safe` flag would upgrade the package to the latest version, 1.1. - Update-Package -Safe +``` +Update-Package -Safe +``` ### Managing Packages at the Solution Level Prior to NuGet 1.4, installing a package into multiple projects was cumbersome using the dialog. It required launching @@ -67,7 +75,7 @@ only work with version 2.* of a package, but not 3.0 and above. In order to prev `packages.config` file using the new `allowedVersions` attribute. For example, the following example shows how to lock the `SomePackage` package the version range 2.0 - 3.0 (exclusive). -The `allowedVersions` attribute accepts values using the [version range format](../concepts/package-versioning.md#version-ranges-and-wildcards). +The `allowedVersions` attribute accepts values using the [version range format](../concepts/package-versioning.md#version-ranges). ```xml @@ -152,24 +160,26 @@ so to install NuGet for Windows Phone Tools, you may need to download and run th To uninstall NuGet for Windows Phone Tools, run the following command. - vsixinstaller.exe /uninstall:NuPackToolsVsix.Microsoft.67e54e40-0ae3-42c5-a949-fddf5739e7a5 +``` +vsixinstaller.exe /uninstall:NuPackToolsVsix.Microsoft.67e54e40-0ae3-42c5-a949-fddf5739e7a5 +``` ## Bug Fixes NuGet 1.4 had a total of 88 work items fixed. 71 of those were marked as bugs. -For a full list of work items fixed in NuGet 1.4, please view the [NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%201.4&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0). +For a full list of work items fixed in NuGet 1.4, please view the ```[NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%201.4&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0)```. ## Bug fixes worth noting: -* [Issue 603](http://nuget.codeplex.com/workitem/603): Package dependencies across different repositories resolves +* ```[Issue 603](http://nuget.codeplex.com/workitem/603)```: Package dependencies across different repositories resolves correctly when specifying a specific package source. -* [Issue 1036](http://nuget.codeplex.com/workitem/1036): Adding `NuGet Pack SomeProject.csproj` to post-build event no longer causes an infinite loop. -* [Issue 961](http://nuget.codeplex.com/workitem/961): `-Source` flag supports relative paths. +* ```[Issue 1036](http://nuget.codeplex.com/workitem/1036)```: Adding `NuGet Pack SomeProject.csproj` to post-build event no longer causes an infinite loop. +* ```[Issue 961](http://nuget.codeplex.com/workitem/961)```: `-Source` flag supports relative paths. ## NuGet 1.4 Update Shortly after the release of NuGet 1.4, we found a couple of issues that were important to fix. The specific version number of this update to 1.4 is 1.4.20615.9020. ### Bug Fixes -* [Issue 1220](http://nuget.codeplex.com/workitem/1220): Update-Package doesnt execute `install.ps1`/`uninstall.ps1` in all projects when there is more than one project -* [Issue 1156](http://nuget.codeplex.com/workitem/1156): Package Manager Consol stuck on W2K3/XP (when Powershell 2 is not installed) +* ```[Issue 1220](http://nuget.codeplex.com/workitem/1220)```: Update-Package doesnt execute `install.ps1`/`uninstall.ps1` in all projects when there is more than one project +* ```[Issue 1156](http://nuget.codeplex.com/workitem/1156)```: Package Manager Consol stuck on W2K3/XP (when Powershell 2 is not installed) diff --git a/docs/release-notes/NuGet-1.5.md b/docs/release-notes/NuGet-1.5.md index 58ef46176..3bb052e73 100644 --- a/docs/release-notes/NuGet-1.5.md +++ b/docs/release-notes/NuGet-1.5.md @@ -1,10 +1,11 @@ --- title: NuGet 1.5 Release Notes description: Release notes for NuGet 1.5 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes +ms.custom: sfi-image-nochange --- # NuGet 1.5 Release Notes @@ -24,7 +25,7 @@ when the project template is invoked. This ability to include NuGet packages wit project template is now a feature of NuGet that _any_ project template can now take advantage of. -For more details about this feature, read this [blog post by the developer of the feature](http://blogs.msdn.com/b/marcinon/archive/2011/07/08/project-templates-and-preinstalled-nuget-packages.aspx). +For more details about this feature, read this [blog post by the developer of the feature](https://blogs.msdn.com/b/marcinon/archive/2011/07/08/project-templates-and-preinstalled-nuget-packages.aspx). ### Explicit Assembly References @@ -94,7 +95,9 @@ dependencies along with the package. ### `Get-Package` command improvement The `Get-Package` command now supports a `-ProjectName` parameter. So the command - Get-Package –ProjectName A +``` +Get-Package –ProjectName A +``` will list all packages installed in project A. @@ -133,13 +136,13 @@ not to include any file in the package. ## Bug Fixes NuGet 1.5 had a total of 107 work items fixed. 103 of those were marked as bugs. -For a full list of work items fixed in NuGet 1.5, please view the [NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%201.5&assignedTo=All&component=All&sortField=Summary&sortDirection=Descending&page=0). +For a full list of work items fixed in NuGet 1.5, please view the ```[NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%201.5&assignedTo=All&component=All&sortField=Summary&sortDirection=Descending&page=0)```. ## Bug fixes worth noting: -* [Issue 1273](http://nuget.codeplex.com/workitem/1273): Made `packages.config` more version control +* ```[Issue 1273](http://nuget.codeplex.com/workitem/1273)```: Made `packages.config` more version control friendly by sorting packages alphabetically and removing extra whitespace. -* [Issue 844](http://nuget.codeplex.com/workitem/844): Version numbers are now normalized so that +* ```[Issue 844](http://nuget.codeplex.com/workitem/844)```: Version numbers are now normalized so that `Install-Package 1.0` works on a package with the version `1.0.0`. -* [Issue 1060](http://nuget.codeplex.com/workitem/1060): When creating a package using nuget.exe, +* ```[Issue 1060](http://nuget.codeplex.com/workitem/1060)```: When creating a package using nuget.exe, the `-Version` flag overrides the `` element. diff --git a/docs/release-notes/NuGet-1.6.md b/docs/release-notes/NuGet-1.6.md index ebe25df56..4dd8dd1ca 100644 --- a/docs/release-notes/NuGet-1.6.md +++ b/docs/release-notes/NuGet-1.6.md @@ -1,10 +1,10 @@ --- title: NuGet 1.6 Release Notes description: Release notes for NuGet 1.6 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 1.6 Release Notes @@ -18,7 +18,7 @@ If you are running VS 2010 SP1, you might run into an installation error when at NuGet if you have an older version installed. The workaround is to simply uninstall NuGet and then install it from the VS Extension Gallery. See -[http://support.microsoft.com/kb/2581019](http://support.microsoft.com/kb/2581019) for more information. + for more information. Note: If Visual Studio won't allow you to uninstall the extension (the Uninstall button is disabled), then you likely need to restart Visual Studio using "Run as Administrator." @@ -59,4 +59,4 @@ NuGet 1.6 allows unchecking a package source to disable it, but keep it around. NuGet 1.6 had a total of 106 work items fixed. 95 of those were classified as bugs and 10 of those were features. -For a full list of work items fixed in NuGet 1.6, please view the [NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%201.6&assignedTo=All&component=All&sortField=Votes&sortDirection=Descending&page=0). +For a full list of work items fixed in NuGet 1.6, please view the ```[NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%201.6&assignedTo=All&component=All&sortField=Votes&sortDirection=Descending&page=0)```. diff --git a/docs/release-notes/NuGet-1.7.md b/docs/release-notes/NuGet-1.7.md index 3d5c30a1d..5a2f1b933 100644 --- a/docs/release-notes/NuGet-1.7.md +++ b/docs/release-notes/NuGet-1.7.md @@ -1,10 +1,10 @@ --- title: NuGet 1.7 Release Notes description: Release notes for NuGet 1.7 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 1.7 Release Notes @@ -18,7 +18,7 @@ If you are running VS 2010 SP1, you might run into an installation error when at NuGet if you have an older version installed. The workaround is to simply uninstall NuGet and then install it from the VS Extension Gallery. See -[http://support.microsoft.com/kb/2581019](http://support.microsoft.com/kb/2581019) for more information. + for more information. Note: If Visual Studio won't allow you to uninstall the extension (the Uninstall button is disabled), then you likely need to restart Visual Studio using "Run as Administrator." @@ -62,4 +62,4 @@ nuget.exe or the handy NuGet Package Explorer to create packages. NuGet 1.7 has fixed many bugs around the Package Restore workflow and Network/Source Control scenarios. -For a full list of work items fixed in NuGet 1.7, please view the [NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%201.7&assignedTo=All&component=All&sortField=Votes&sortDirection=Descending&page=0). +For a full list of work items fixed in NuGet 1.7, please view the ```[NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%201.7&assignedTo=All&component=All&sortField=Votes&sortDirection=Descending&page=0)```. diff --git a/docs/release-notes/NuGet-1.8.md b/docs/release-notes/NuGet-1.8.md index 7008f5ff4..6179df1c7 100644 --- a/docs/release-notes/NuGet-1.8.md +++ b/docs/release-notes/NuGet-1.8.md @@ -1,10 +1,10 @@ --- title: NuGet 1.8 Release Notes description: Release notes for NuGet 1.8 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 1.8 Release Notes @@ -18,7 +18,7 @@ If you are running VS 2010 SP1, you might run into an installation error when at NuGet if you have an older version installed. The workaround is to simply uninstall NuGet and then install it from the VS Extension Gallery. See -[http://support.microsoft.com/kb/2581019](http://support.microsoft.com/kb/2581019) for more information, or [go directly to the VS hotfix](http://bit.ly/vsixcertfix). + for more information, or [go directly to the VS hotfix](http://bit.ly/vsixcertfix). Note: If Visual Studio won't allow you to uninstall the extension (the Uninstall button is disabled), then you likely need to restart Visual Studio using "Run as Administrator." @@ -34,7 +34,7 @@ We have since released a hotfix that addresses this issue. By updating NuGet th ### Satellite Packages for Localized Resources NuGet 1.8 now supports the ability to create separate packages for localized resources, similar to the satellite assembly capabilities of the .NET Framework. A satellite package is created in the same way as any other NuGet package with the addition of a few conventions: -* The satellite package ID and file name should include a suffix that matches one of the standard [culture strings used by the .NET Framework](http://msdn.microsoft.com/goglobal/bb896001.aspx). +* The satellite package ID and file name should include a suffix that matches one of the standard [culture strings used by the .NET Framework](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c). * In its `.nuspec` file, the satellite package should define a language element with the same culture string used in the ID * The satellite package should define a dependency in its `.nuspec` file to its core package, which is simply the package with the same ID minus the language suffix. The core package needs to be available in the repository for successful installation. @@ -65,11 +65,11 @@ The second method is to set the environment variable “EnableNuGetPackageRestor Now, as stated above, we have only laid the groundwork for this feature in NuGet 1.8. Practically, this means that while we’ve added all of the logic to enable the feature, it's not currently enforced in this version. It will be enabled, however, in the next release of NuGet, so we wanted to make you aware of it as soon as possible so that you can configure your environments appropriately and therefore not be impacted when we start enforce the consent constraint. -For more details, please see the [team blog post](http://blog.nuget.org/20120518/package-restore-and-consent.html) on this feature. +For more details, please see the [team blog post](https://blog.nuget.org/20120518/package-restore-and-consent.html) on this feature. ### nuget.exe Performance Improvements By modifying the install command to download and install packages in parallel, NuGet 1.8 brings dramatic performance improvements to nuget.exe – and by extension package restore. High level testing shows that performance for installing 6 packages into a project improves by about 35% in NuGet 1.8. Increasing the number of packages to 25 shows a performance gain of about 60%. ## Bug Fixes NuGet 1.8 includes quite a few bug fixes with an emphasis on the package manager console and package restore workflow, particularly as it relates to package restore consent and Windows 8 Express integration. -For a full list of work items fixed in NuGet 1.8, please view the [NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%201.8&assignedTo=All&component=All&sortField=Votes&sortDirection=Descending&page=0). +For a full list of work items fixed in NuGet 1.8, please view the ```[NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%201.8&assignedTo=All&component=All&sortField=Votes&sortDirection=Descending&page=0)```. diff --git a/docs/release-notes/NuGet-2.0.md b/docs/release-notes/NuGet-2.0.md index 1663be34f..d37a46008 100644 --- a/docs/release-notes/NuGet-2.0.md +++ b/docs/release-notes/NuGet-2.0.md @@ -1,10 +1,10 @@ --- title: NuGet 2.0 Release Notes description: Release notes for NuGet 2.0 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.0 Release Notes @@ -18,14 +18,14 @@ If you are running VS 2010 SP1, you might run into an installation error when at NuGet if you have an older version installed. The workaround is to simply uninstall NuGet and then install it from the VS Extension Gallery. See -[http://support.microsoft.com/kb/2581019](http://support.microsoft.com/kb/2581019) for more information, or [go directly to the VS hotfix](http://bit.ly/vsixcertfix). + for more information, or [go directly to the VS hotfix](http://bit.ly/vsixcertfix). Note: If Visual Studio won't allow you to uninstall the extension (the Uninstall button is disabled), then you likely need to restart Visual Studio using "Run as Administrator." ## Package restore consent is now active -As described in this [post on package restore consent](http://blog.nuget.org/20120518/package-restore-and-consent.html), NuGet 2.0 will now require that consent be given to enable package restore to go online and download packages. Please ensure that you have provided consent via either the package manager configuration dialog or the EnableNuGetPackageRestore environment variable. +As described in this [post on package restore consent](https://blog.nuget.org/20120518/package-restore-and-consent.html), NuGet 2.0 will now require that consent be given to enable package restore to go online and download packages. Please ensure that you have provided consent via either the package manager configuration dialog or the EnableNuGetPackageRestore environment variable. ## Group dependencies by target frameworks @@ -68,23 +68,25 @@ Note that mixing the two formats is not allowed. For example, the following snip In addition to assembly references, content files and PowerShell scripts can also be grouped by target framework. The same folder structure found in the `lib` folder for specifying target framework can now be applied in the same way to the `content` and `tools` folders. For example: - \content - \net11 - \MyContent.txt - \net20 - \MyContent20.txt - \net40 - \sl40 - \MySilverlightContent.html - - \tools - \init.ps1 - \net40 - \install.ps1 - \uninstall.ps1 - \sl40 - \install.ps1 - \uninstall.ps1 +``` +\content + \net11 + \MyContent.txt + \net20 + \MyContent20.txt + \net40 + \sl40 + \MySilverlightContent.html + +\tools + \init.ps1 + \net40 + \install.ps1 + \uninstall.ps1 + \sl40 + \install.ps1 + \uninstall.ps1 +``` **Note**: Because `init.ps1` is executed at the solution level and is not dependent on any individual project, it must be placed directly under the `tools` folder. If placed within a framework-specific folder, it will be ignored. @@ -95,4 +97,4 @@ The tab completion feature in the NuGet Package Manager Console has been updated ## Bug Fixes NuGet 2.0 includes many bug fixes with an emphasis on package restore consent and performance. -For a full list of work items fixed in NuGet 2.0, please view the [NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%202.0&assignedTo=All&component=All&sortField=Votes&sortDirection=Descending&page=0). +For a full list of work items fixed in NuGet 2.0, please view the ```[NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%202.0&assignedTo=All&component=All&sortField=Votes&sortDirection=Descending&page=0)```. diff --git a/docs/release-notes/NuGet-2.1.md b/docs/release-notes/NuGet-2.1.md index f14c1f563..e2ed72aba 100644 --- a/docs/release-notes/NuGet-2.1.md +++ b/docs/release-notes/NuGet-2.1.md @@ -1,10 +1,11 @@ --- title: NuGet 2.1 Release Notes description: Release notes for NuGet 2.1 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes +ms.custom: sfi-image-nochange --- # NuGet 2.1 Release Notes @@ -17,14 +18,18 @@ NuGet 2.1 was released on October 4, 2012. NuGet 2.1 gives you greater flexibility in controlling NuGet settings by way of recursively walking up the folder structure looking for `NuGet.Config` files and then building the configuration from the set of all found files. As an example, consider the scenario where a team has an internal package repository for CI builds of other internal dependencies. The folder structure for an individual project might look like the following: - C:\ - C:\myteam\ - C:\myteam\solution1 - C:\myteam\solution1\project1 +``` +C:\ +C:\myteam\ +C:\myteam\solution1 +C:\myteam\solution1\project1 +``` Additionally, if package restore is enabled for the solution, the following folder will also exist: - C:\myteam\solution1\.nuget +``` +C:\myteam\solution1\.nuget +``` In order to have the team’s internal package repository available for all projects that the team works on, while not making it available for every project on the machine, we can create a new Nuget.Config file and place it in the c:\myteam folder. There is no way to specificy a packages folder per project. @@ -117,16 +122,20 @@ Over the past several iterations, changes have been introduced to the NuGet gall Prior to NuGet 2.1, NuGet would skip updating a package when there was a not a high version number. This introduced friction for certain scenarios – particularly in the case of build or CI scenarios where the team did not want to increment the package version number with each build. The desired behavior was to force an update regardless. NuGet 2.1 addresses this with the ‘reinstall’ flag. For example, previous versions of NuGet would result in the following when attempting to update a package that did not have a more recent package version: - PM> Update-Package Moq - No updates available for 'Moq' in project 'MySolution.MyConsole'. +``` +PM> Update-Package Moq +No updates available for 'Moq' in project 'MySolution.MyConsole'. +``` With the reinstall flag, the package will be updated regardless of whether there is a newer version. - PM> Update-Package Moq -Reinstall - Successfully removed 'Moq 4.0.10827' from MySolution.MyConsole. - Successfully uninstalled 'Moq 4.0.10827'. - Successfully installed 'Moq 4.0.10827'. - Successfully added 'Moq 4.0.10827' to MySolution.MyConsole. +``` +PM> Update-Package Moq -Reinstall +Successfully removed 'Moq 4.0.10827' from MySolution.MyConsole. +Successfully uninstalled 'Moq 4.0.10827'. +Successfully installed 'Moq 4.0.10827'. +Successfully added 'Moq 4.0.10827' to MySolution.MyConsole. +``` Another scenario where the reinstall flag proves beneficial is that of framework re-targeting. When changing the target framework of a project (for example, from .NET 4 to .NET 4.5), Update-Package -Reinstall can update references to the correct assemblies for all NuGet packages installed in the project. @@ -138,4 +147,4 @@ In previous versions of NuGet, updating a package source from within the Visual ## Bug Fixes -NuGet 2.1 includes many bug fixes. For a full list of work items fixed in NuGet 2.0, please view the [NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Fixed&type=All&priority=All&release=NuGet%202.1&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0). +NuGet 2.1 includes many bug fixes. For a full list of work items fixed in NuGet 2.0, please view the ```[NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Fixed&type=All&priority=All&release=NuGet%202.1&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0)```. diff --git a/docs/release-notes/NuGet-2.12-RC.md b/docs/release-notes/NuGet-2.12-RC.md index 1bf17f92c..57b3f680e 100644 --- a/docs/release-notes/NuGet-2.12-RC.md +++ b/docs/release-notes/NuGet-2.12-RC.md @@ -1,10 +1,10 @@ --- title: NuGet 2.12-RC Release Notes description: Release notes for NuGet 2.12 RC including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.12-RC Release Notes diff --git a/docs/release-notes/NuGet-2.12.md b/docs/release-notes/NuGet-2.12.md index 6a28a22e0..db1e010bb 100644 --- a/docs/release-notes/NuGet-2.12.md +++ b/docs/release-notes/NuGet-2.12.md @@ -1,10 +1,10 @@ --- title: NuGet 2.12 Release Notes description: Release notes for NuGet 2.12 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.12 Release Notes diff --git a/docs/release-notes/NuGet-2.2.1.md b/docs/release-notes/NuGet-2.2.1.md index 58c9a2ca2..84de48489 100644 --- a/docs/release-notes/NuGet-2.2.1.md +++ b/docs/release-notes/NuGet-2.2.1.md @@ -1,10 +1,10 @@ --- title: NuGet 2.2.1 Release Notes description: Release notes for NuGet 2.2.1 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.2.1 Release Notes @@ -39,7 +39,7 @@ If you produce Visual Studio templates, you can use NuGet to [preinstall package The main scenario for this feature is custom ASP.NET project templates. The built-in ASP.NET templates use preinstalled packages, pulling packages from local disk. You can now create a custom ASP.NET project template that uses the existing packages installed by ASP.NET but add extra NuGet packages into your template. ## Bug Fixes -NuGet 2.2.1 includes a few targeted bug fixes. For a list of work items fixed in NuGet 2.2.1, please view the [NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%202.2.1&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0). +NuGet 2.2.1 includes a few targeted bug fixes. For a list of work items fixed in NuGet 2.2.1, please view the ```[NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%202.2.1&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0)```. ## Known Issues diff --git a/docs/release-notes/NuGet-2.2.md b/docs/release-notes/NuGet-2.2.md index 60b814803..ea2296b2c 100644 --- a/docs/release-notes/NuGet-2.2.md +++ b/docs/release-notes/NuGet-2.2.md @@ -1,10 +1,10 @@ --- title: NuGet 2.2 Release Notes description: Release notes for NuGet 2.2 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.2 Release Notes @@ -34,8 +34,8 @@ NuGet 2.2 now allows you to specify an entire folder in the `` element of ## Known Issues ### Package installation fails for F# projects when using the package manager console -When attempting to install a NuGet package into an F# project using the package manager console, an InvalidOperationException is thrown. We are actively working with the F# team to resolve the issue, but in the meantime, the workaround is to install NuGet packages into F# projects via NuGet's package manager dialog rather than the console. [More information is available on CodePlex](http://nuget.codeplex.com/workitem/2873). +When attempting to install a NuGet package into an F# project using the package manager console, an InvalidOperationException is thrown. We are actively working with the F# team to resolve the issue, but in the meantime, the workaround is to install NuGet packages into F# projects via NuGet's package manager dialog rather than the console. ```[More information is available on CodePlex](http://nuget.codeplex.com/workitem/2873)```. ## Bug Fixes -NuGet 2.2 includes many bug fixes. For a full list of work items fixed in NuGet 2.2, please view the [NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%202.2&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0). +NuGet 2.2 includes many bug fixes. For a full list of work items fixed in NuGet 2.2, please view the ```[NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%202.2&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0)```. diff --git a/docs/release-notes/NuGet-2.5.md b/docs/release-notes/NuGet-2.5.md index c2956227f..afaa2e90b 100644 --- a/docs/release-notes/NuGet-2.5.md +++ b/docs/release-notes/NuGet-2.5.md @@ -1,51 +1,51 @@ --- title: NuGet 2.5 Release Notes description: Release notes for NuGet 2.5 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.5 Release Notes [NuGet 2.2.1 Release Notes](../release-notes/nuget-2.2.1.md) | [NuGet 2.6 Release Notes](../release-notes/nuget-2.6.md) -NuGet 2.5 was released on April 25, 2013. This release was so big, we felt compelled to skip versions 2.3 and 2.4! To date, this is the largest release we've had for NuGet, with over [160 work items](https://nuget.codeplex.com/workitem/list/advanced?release=NuGet%202.5&status=all) in the release. +NuGet 2.5 was released on April 25, 2013. This release was so big, we felt compelled to skip versions 2.3 and 2.4! To date, this is the largest release we've had for NuGet, with over ```[160 work items](https://nuget.codeplex.com/workitem/list/advanced?release=NuGet%202.5&status=all)``` in the release. ## Acknowledgements We would like to thank the following external contributors for their significant contributions to NuGet 2.5: -1. [Daniel Plaisted](https://www.codeplex.com/site/users/view/dsplaisted) ([@dsplaisted](https://twitter.com/dsplaisted)) - - [#2847](https://nuget.codeplex.com/workitem/2847) - Add MonoAndroid, MonoTouch, and MonoMac to the list of known target framework identifiers. -2. [Andres G. Aragoneses](https://www.codeplex.com/site/users/view/knocte) ([@knocte](https://twitter.com/knocte)) - - [#2865](https://nuget.codeplex.com/workitem/2865) - Fix spelling of `NuGet.targets` for a case-sensitive OS -3. [David Fowler](https://www.codeplex.com/site/users/view/dfowler) ([@davidfowl](https://twitter.com/davidfowl)) +1. ```[Daniel Plaisted](https://www.codeplex.com/site/users/view/dsplaisted)``` ([@dsplaisted](https://twitter.com/dsplaisted)) + - ```[#2847](https://nuget.codeplex.com/workitem/2847)``` - Add MonoAndroid, MonoTouch, and MonoMac to the list of known target framework identifiers. +2. ```[Andres G. Aragoneses](https://www.codeplex.com/site/users/view/knocte)``` ([@knocte](https://twitter.com/knocte)) + - ```[#2865](https://nuget.codeplex.com/workitem/2865)``` - Fix spelling of `NuGet.targets` for a case-sensitive OS +3. ```[David Fowler](https://www.codeplex.com/site/users/view/dfowler)``` ([@davidfowl](https://twitter.com/davidfowl)) - Make the solution build on Mono. -4. [Andrew Theken](https://www.codeplex.com/site/users/view/atheken) ([@atheken](https://twitter.com/atheken)) +4. ```[Andrew Theken](https://www.codeplex.com/site/users/view/atheken)``` ([@atheken](https://twitter.com/atheken)) - Fix unit tests failing on Mono. -5. [Olivier Dagenais](https://www.codeplex.com/site/users/view/OliIsCool) ([@OliIsCool](https://twitter.com/oliiscool)) - - [#2920](https://nuget.codeplex.com/workitem/2920) - nuget.exe pack command does not propagate Properties to MSBuild -6. [Miroslav Bajtos](https://www.codeplex.com/site/users/view/MiroslavBajtos) ([@bajtos](https://twitter.com/bajtos)) - - [#1511](https://nuget.codeplex.com/workitem/1511) - Modified XML handling code to preserve formatting. -7. [Adam Ralph](http://www.codeplex.com/site/users/view/adamralph) ([@adamralph](https://twitter.com/adamralph)) +5. ```[Olivier Dagenais](https://www.codeplex.com/site/users/view/OliIsCool)``` ([@OliIsCool](https://twitter.com/oliiscool)) + - ```[#2920](https://nuget.codeplex.com/workitem/2920)``` - nuget.exe pack command does not propagate Properties to MSBuild +6. ```[Miroslav Bajtos](https://www.codeplex.com/site/users/view/MiroslavBajtos)``` ([@bajtos](https://twitter.com/bajtos)) + - ```[#1511](https://nuget.codeplex.com/workitem/1511)``` - Modified XML handling code to preserve formatting. +7. ```[Adam Ralph](http://www.codeplex.com/site/users/view/adamralph)``` ([@adamralph](https://twitter.com/adamralph)) - Added recognized words to custom dictionary to allow build.cmd to succeed. -8. [Bruno Roggeri](https://www.codeplex.com/site/users/view/broggeri) +8. ```[Bruno Roggeri](https://www.codeplex.com/site/users/view/broggeri)``` - Fix unit tests when running in localized VS. -9. [Gareth Evans](https://www.codeplex.com/site/users/view/garethevans) +9. ```[Gareth Evans](https://www.codeplex.com/site/users/view/garethevans)``` - Extracted interface from PackageService -10. [Maxime Brugidou](https://www.codeplex.com/site/users/view/brugidou) ([@brugidou](https://twitter.com/brugidou)) - - [#936](https://nuget.codeplex.com/workitem/936) - Handle project dependencies when packing -11. [Xavier Decoster](https://www.codeplex.com/site/users/view/XavierDecoster) ([@XavierDecoster](https://twitter.com/xavierdecoster)) - - [#2991](https://nuget.codeplex.com/workitem/2991), [#3164](https://nuget.codeplex.com/workitem/3164) - Support Clear Text Password when storing package source credentials in nuget.cofig files -12. [James Manning](http://www.codeplex.com/site/users/view/jmanning) ([@manningj](https://twitter.com/manningj)) - - [#3190](http://nuget.codeplex.com/workitem/3190), [#3191](http://nuget.codeplex.com/workitem/3191) - Fix Get-Package help description +10. ```[Maxime Brugidou](https://www.codeplex.com/site/users/view/brugidou)``` ([@brugidou](https://twitter.com/brugidou)) + - ```[#936](https://nuget.codeplex.com/workitem/936)``` - Handle project dependencies when packing +11. ```[Xavier Decoster](https://www.codeplex.com/site/users/view/XavierDecoster)``` ([@XavierDecoster](https://twitter.com/xavierdecoster)) + - ```[#2991](https://nuget.codeplex.com/workitem/2991)```, ```[#3164](https://nuget.codeplex.com/workitem/3164)``` - Support Clear Text Password when storing package source credentials in nuget.cofig files +12. ```[James Manning](http://www.codeplex.com/site/users/view/jmanning)``` ([@manningj](https://twitter.com/manningj)) + - ```[#3190](http://nuget.codeplex.com/workitem/3190)```, ```[#3191](https://nuget.codeplex.com/workitem/3191)``` - Fix Get-Package help description We also appreciate the following individuals for finding bugs with NuGet 2.5 Beta/RC that were approved and fixed before the final release: -1. [Tony Wall](https://www.codeplex.com/site/users/view/CodeChief) ([@CodeChief](https://twitter.com/codechief)) - - [#3200](https://nuget.codeplex.com/workitem/3200) - MSTest broken with lastest NuGet 2.4 and 2.5 builds +1. ```[Tony Wall](https://www.codeplex.com/site/users/view/CodeChief)``` ([@CodeChief](https://twitter.com/codechief)) + - ```[#3200](https://nuget.codeplex.com/workitem/3200)``` - MSTest broken with lastest NuGet 2.4 and 2.5 builds ## Notable features in the release @@ -119,7 +119,7 @@ Now nuget.exe pack command processes referenced projects with the following rule This allows a referenced project to be treated as a dependency if there is a `.nuspec` file, otherwise, it becomes part of the package. More details here: -[http://nuget.codeplex.com/workitem/936](http://nuget.codeplex.com/workitem/936) +```[http://nuget.codeplex.com/workitem/936](http://nuget.codeplex.com/workitem/936)``` ### Add a 'Minimum NuGet Version' property to packages @@ -154,7 +154,7 @@ Starting with NuGet 2.5, if a dependency version is already satisfied, the depen * NuGet will no longer update B, because it detects that the existing version 1.0.0 satisfies the dependency version constraint. -For more background on this change, read the detailed [work item](http://nuget.codeplex.com/workitem/1681) as well as the related [discussion thread](http://nuget.codeplex.com/discussions/436712). +For more background on this change, read the detailed ```[work item](https://nuget.codeplex.com/workitem/1681)``` as well as the related ```[discussion thread](https://nuget.codeplex.com/discussions/436712)```. ### nuget.exe outputs http requests with detailed verbosity @@ -170,7 +170,7 @@ Starting with NuGet 2.5, if nuget.exe identifies a UNC/folder source, it will pe The following command will now work: -``` +```cli nuget push -source \\mycompany\repo\ mypackage.1.0.0.nupkg ``` @@ -180,12 +180,12 @@ nuget.exe commands that access configuration (all except 'spec' and 'pack') now Example: -``` +```cli nuget sources add -name test -source http://test -ConfigFile C:\test\.nuget\Nuget.Config ``` ### Support for Native projects -With NuGet 2.5, the NuGet tooling is now available for Native projects in Visual Studio. We expect most native packages will utilize the MSBuild imports feature above, using a tool created by the [CoApp project](http://coapp.org). For more information, read [the details about the tool](http://coapp.org/news/2013-03-27-The-Long-Awaited-post.html) on the coapp.org website. +With NuGet 2.5, the NuGet tooling is now available for Native projects in Visual Studio. We expect most native packages will utilize the MSBuild imports feature above, using a tool created by the [CoApp project](https://github.com/coapp). For more information, read [the details about the tool](https://github.com/coapp/coapp.org/blob/master/src/dynamic/news/2013-03-27-The-Long-Awaited-post.html.md) on the coapp.org website. The target framework name of "native" is introduced for packages to include files in \build, \content, and \tools when the package is installed into a native project. The \`lib` folder is not used for native projects. diff --git a/docs/release-notes/NuGet-2.6.1-for-WebMatrix.md b/docs/release-notes/NuGet-2.6.1-for-WebMatrix.md index e47fba975..e5abd798f 100644 --- a/docs/release-notes/NuGet-2.6.1-for-WebMatrix.md +++ b/docs/release-notes/NuGet-2.6.1-for-WebMatrix.md @@ -1,10 +1,10 @@ --- title: NuGet 2.6.1 for WebMatrix Release Notes description: Release notes for NuGet 2.6.1 for WebMatrix including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.6.1 for WebMatrix Release Notes @@ -35,7 +35,7 @@ This latest release provides compatibility with the newest NuGet packages, preve Some users have reported that after installing NuGet packages in WebMatrix that include DLLs that get copied to bin, that the DLLs show up in the `bin` folder as 0-byte files. This breaks the application at runtime. -[This issue](https://nuget.codeplex.com/workitem/4060) has now been fixed. +```[This issue](https://nuget.codeplex.com/workitem/4060)``` has now been fixed. ## Other Recent Improvements diff --git a/docs/release-notes/NuGet-2.6.md b/docs/release-notes/NuGet-2.6.md index 70781075a..b9a4db16c 100644 --- a/docs/release-notes/NuGet-2.6.md +++ b/docs/release-notes/NuGet-2.6.md @@ -1,10 +1,10 @@ --- title: NuGet 2.6 Release Notes -description: Release notes for NuGet 2.6.1 for WebMatrix including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +description: Release notes for NuGet 2.6 including known issues, bug fixes, added features, and DCRs. +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.6 Release Notes @@ -43,7 +43,7 @@ Studio build configuration transformations. In April 2013, we made two big announcements regarding NuGet support for XDT. The first was that the XDT library itself was being itself [released as a NuGet package](https://nuget.org/packages/Microsoft.Web.Xdt) -and [open sourced on CodePlex](http://xdt.codeplex.com/). This step enabled the XDT engine +and ```[open sourced on CodePlex](http://xdt.codeplex.com/)```. This step enabled the XDT engine to be used freely by other open-source software, including the NuGet client. The second announcement was the plan to support use of the XDT engine for transformations in the NuGet client. NuGet 2.6 includes this integration. @@ -67,7 +67,7 @@ applications in your project. #### What you can do with XDT -One of XDT’s greatest strengths is its [simple but powerful syntax](http://msdn.microsoft.com/library/dd465326.aspx) +One of XDT’s greatest strengths is its [simple but powerful syntax](/previous-versions/aspnet/dd465326(v=vs.110)) for manipulating the structure of an XML DOM. Rather than simply overlaying one fixed document structure onto another structure, XDT provides controls for matching elements in a variety of ways, from simple attribute name matching to full XPath support. Once a matching element or @@ -135,7 +135,7 @@ relevance boosting. ### Tracking Direct Installs vs. Dependency Installs -Package authors are relying more and more on the [Package Statistics](http://blog.nuget.org/20130226/Introducing-Package-Statistics.html) +Package authors are relying more and more on the [Package Statistics](https://blog.nuget.org/20130226/Introducing-Package-Statistics.html) provided on the NuGet Gallery. One significant missing data point that authors have asked for is a differentiation between direct package installs and dependency installs. Until now, the NuGet client did not send any context around the installation operation for whether the @@ -158,4 +158,4 @@ package authors to fully understand how developers are installing their packages ## Bug Fixes NuGet 2.6 also includes several bug fixes. For a full list of work items fixed in NuGet 2.6, please view -the [NuGet Issue Tracker for this release](https://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%202.6&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0&reasonClosed=All). \ No newline at end of file +the ```[NuGet Issue Tracker for this release](https://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%202.6&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0&reasonClosed=All)```. diff --git a/docs/release-notes/NuGet-2.7.1.md b/docs/release-notes/NuGet-2.7.1.md index aa067c0e2..b9b3ed7de 100644 --- a/docs/release-notes/NuGet-2.7.1.md +++ b/docs/release-notes/NuGet-2.7.1.md @@ -1,16 +1,16 @@ --- title: NuGet 2.7.1 Release Notes description: Release notes for NuGet 2.7.1 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.7.1 Release Notes [NuGet 2.7 Release Notes](../release-notes/nuget-2.7.md) | [NuGet 2.7.2 Release Notes](../release-notes/nuget-2.7.2.md) -NuGet 2.7.1 was released on October 7, 2013. This is a minor update to our recent 2.7 release with some targeted fixes to improve the experience of new 2.7 features. For a list of work items fixed in NuGet 2.7.1, please view the [NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%202.7.1&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0). +NuGet 2.7.1 was released on October 7, 2013. This is a minor update to our recent 2.7 release with some targeted fixes to improve the experience of new 2.7 features. For a list of work items fixed in NuGet 2.7.1, please view the ```[NuGet Issue Tracker for this release](http://nuget.codeplex.com/workitem/list/advanced?keyword=&status=Closed&type=All&priority=All&release=NuGet%202.7.1&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0)```. The complete set of features in 2.7 can be found in the [release notes](../release-notes/nuget-2.7.md) here. diff --git a/docs/release-notes/NuGet-2.7.2.md b/docs/release-notes/NuGet-2.7.2.md index 38aa3c31f..bc7b2a718 100644 --- a/docs/release-notes/NuGet-2.7.2.md +++ b/docs/release-notes/NuGet-2.7.2.md @@ -1,10 +1,10 @@ --- title: NuGet 2.7.2 Release Notes description: Release notes for NuGet 2.7.2 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.7.2 Release Notes @@ -20,11 +20,13 @@ For quite some time, Microsoft has included the NuGet packages for several popul To mitigate this issue, NuGet 2.7.2 allows the script author to include the license text block within a specially marked section which looks as follows. - /************** NUGET: BEGIN LICENSE TEXT ************** - * The following code is licensed under the MIT license - * Additional license information below is informational - * only. - ************** NUGET: END LICENSE TEXT ***************/ +``` +/************** NUGET: BEGIN LICENSE TEXT ************** + * The following code is licensed under the MIT license + * Additional license information below is informational + * only. + ************** NUGET: END LICENSE TEXT ***************/ +``` When updating packages with content files containing this block, NuGet does not factor the contents of the block into the comparison with the version on the NuGet gallery, and can therefore delete and update the content file as though it matches the original copy. @@ -40,4 +42,4 @@ When Xamarin's development tools are installed on a machine, they modify the sup When using hierarchical Nuget.Config files, the repositoryPath key was not being honored for Nuget.Config files closest to the solution root. In Visual Studio 2013, NuGet installs a custom Nuget.Config file at %ProgramData%\NuGet\Config\VisualStudio\12.0\Microsoft.VisualStudio.config in order to add the "Microsoft and .NET" package source. As a result, the work-around for using a custom repositoryPath in a solution was to delete the machine-level Nuget.Config - which also meant removing the "Microsoft and .NET" package source. NuGet 2.7.2 now honors the precedence rules for repositoryPath when using hierarchical Nuget.Config files. ## All Changes -For a full list of work items fixed in NuGet 2.7.2, please view the [NuGet Issue Tracker for this release](https://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%202.7.2&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0&reasonClosed=Fixed). +For a full list of work items fixed in NuGet 2.7.2, please view the ```[NuGet Issue Tracker for this release](https://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%202.7.2&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0&reasonClosed=Fixed)```. diff --git a/docs/release-notes/NuGet-2.7.md b/docs/release-notes/NuGet-2.7.md index 8ab77029f..6154bfff3 100644 --- a/docs/release-notes/NuGet-2.7.md +++ b/docs/release-notes/NuGet-2.7.md @@ -1,10 +1,10 @@ --- title: NuGet 2.7 Release Notes description: Release notes for NuGet 2.7 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.7 Release Notes @@ -17,37 +17,37 @@ NuGet 2.7 was released on August 22, 2013. We would like to thank the following external contributors for their significant contributions to NuGet 2.7: -1. [Mike Roth](http://www.codeplex.com/site/users/view/mxrss) ([@mxrss](https://twitter.com/mxrss)) +1. ```[Mike Roth](http://www.codeplex.com/site/users/view/mxrss)``` ([@mxrss](https://twitter.com/mxrss)) - Show License url when listing packages and verbosity is detailed. -2. [Adam Ralph](http://www.codeplex.com/site/users/view/adamralph) ([@adamralph](https://twitter.com/adamralph)) - - [#1956](http://nuget.codeplex.com/workitem/1956) - Add developmentDependency attribute to `packages.config` and use it in pack command to only include runtime packages -3. [Rafael Nicoletti](http://www.codeplex.com/site/users/view/tkrafael) ([@tkrafael](https://twitter.com/tkrafael)) +2. ```[Adam Ralph](http://www.codeplex.com/site/users/view/adamralph)``` ([@adamralph](https://twitter.com/adamralph)) + - ```[#1956](http://nuget.codeplex.com/workitem/1956)``` - Add developmentDependency attribute to `packages.config` and use it in pack command to only include runtime packages +3. ```[Rafael Nicoletti](http://www.codeplex.com/site/users/view/tkrafael)``` ([@tkrafael](https://twitter.com/tkrafael)) - Avoid duplicate Properties key in nuget.exe pack command. -4. [Ben Phegan](http://www.codeplex.com/site/users/view/benphegan) ([@BenPhegan](https://twitter.com/benphegan)) - - [#2610](http://nuget.codeplex.com/workitem/2610) - Increase machine cache size to 200. -5. [Slava Trenogin](http://www.codeplex.com/site/users/view/derigel) ([@derigel](https://twitter.com/derigel)) - - [#3217](http://nuget.codeplex.com/workitem/3217) - Fix NuGet dialog showing updates in the wrong tab +4. ```[Ben Phegan](http://www.codeplex.com/site/users/view/benphegan)``` ([@BenPhegan](https://twitter.com/benphegan)) + - ```[#2610](http://nuget.codeplex.com/workitem/2610)``` - Increase machine cache size to 200. +5. ```[Slava Trenogin](http://www.codeplex.com/site/users/view/derigel)``` ([@derigel](https://twitter.com/derigel)) + - ```[#3217](http://nuget.codeplex.com/workitem/3217)``` - Fix NuGet dialog showing updates in the wrong tab - Fix Project.TargetFramework can be null in ProjectManager - - [#3248](http://nuget.codeplex.com/workitem/3248) - Fix SharedPackageRepository FindPackage/FindPackagesById will fail on non-existent packageId -6. [Kevin Boyle](http://www.codeplex.com/site/users/view/KevinBoyleRG) ([@kevfromireland](https://twitter.com/kevfromireland)) - - [#3234](http://nuget.codeplex.com/workitem/3234) - Enable support for Nomad project -7. [Corin Blaikie](http://www.codeplex.com/site/users/view/corinblaikie) ([@corinblaikie](https://twitter.com/corinblaikie)) - - [#3252](http://nuget.codeplex.com/workitem/3252) - Fix push command fails with exit code 0 when file doesn't exist. -8. [Martin Veselý](http://www.codeplex.com/site/users/view/veselkamartin) - - [#3226](http://nuget.codeplex.com/workitem/3226) - Fix bug with Add-BindingRedirect command when a project references a database project. -9. [Miroslav Bajtos](http://www.codeplex.com/site/users/view/miroslavbajtos) ([@bajtos](https://twitter.com/bajtos)) - - [#2891](http://nuget.codeplex.com/workitem/2891) - Fix bug of nuget.pack parsing wildcard in the 'exclude' attribute incorrectly. -10. [Justin Dearing](http://www.codeplex.com/site/users/view/zippy1981) ([@zippy1981](https://twitter.com/zippy1981)) - - [#3307](http://nuget.codeplex.com/workitem/3307) - Fix bug `NuGet.targets` does not pass $(Platform) to nuget.exe when restoring packages. -11. [Brian Federici](http://www.codeplex.com/site/users/view/benerdin) - - [#3294](http://nuget.codeplex.com/workitem/3294) - Fix bug in nuget.exe package command which would allow adding files with the same name but different casing, eventually causing "Item already exists" exception. -12. [Daniel Cazzulino](http://www.codeplex.com/site/users/view/dcazzulino) ([@kzu](https://twitter.com/kzu)) - - [#2990](http://nuget.codeplex.com/workitem/2990) - Add Version property to NetPortableProfile class. -13. [David Simner](https://www.codeplex.com/site/users/view/DavidSimner) - - [#3460](https://nuget.codeplex.com/workitem/3460) - Fix bug NullReferenceException if requireApiKey = true, but the header X-NUGET-APIKEY isn't present -14. [Michael Friis](https://www.codeplex.com/site/users/view/friism) ([@friism](https://twitter.com/friism)) - - [#3278](https://nuget.codeplex.com/workitem/3278) - Fixes NuGet.Build targets file to so that it works correctly on MonoDevelop -15. [Pranav Krishnamoorthy](https://www.codeplex.com/site/users/view/pranavkm) ([@pranav_km](https://twitter.com/pranav_km)) + - ```[#3248](http://nuget.codeplex.com/workitem/3248)``` - Fix SharedPackageRepository FindPackage/FindPackagesById will fail on non-existent packageId +6. ```[Kevin Boyle](http://www.codeplex.com/site/users/view/KevinBoyleRG)``` ([@kevfromireland](https://twitter.com/kevfromireland)) + - ```[#3234](http://nuget.codeplex.com/workitem/3234)``` - Enable support for Nomad project +7. ```[Corin Blaikie](http://www.codeplex.com/site/users/view/corinblaikie)``` ([@corinblaikie](https://twitter.com/corinblaikie)) + - ```[#3252](http://nuget.codeplex.com/workitem/3252)``` - Fix push command fails with exit code 0 when file doesn't exist. +8. ```[Martin Veselý](http://www.codeplex.com/site/users/view/veselkamartin)``` + - ```[#3226](http://nuget.codeplex.com/workitem/3226)``` - Fix bug with Add-BindingRedirect command when a project references a database project. +9. ```[Miroslav Bajtos](http://www.codeplex.com/site/users/view/miroslavbajtos)``` ([@bajtos](https://twitter.com/bajtos)) + - ```[#2891](http://nuget.codeplex.com/workitem/2891)``` - Fix bug of nuget.pack parsing wildcard in the 'exclude' attribute incorrectly. +10. ```[Justin Dearing](http://www.codeplex.com/site/users/view/zippy1981)``` ([@zippy1981](https://twitter.com/zippy1981)) + - ```[#3307](http://nuget.codeplex.com/workitem/3307)``` - Fix bug `NuGet.targets` does not pass $(Platform) to nuget.exe when restoring packages. +11. ```[Brian Federici](http://www.codeplex.com/site/users/view/benerdin)``` + - ```[#3294](http://nuget.codeplex.com/workitem/3294)``` - Fix bug in nuget.exe package command which would allow adding files with the same name but different casing, eventually causing "Item already exists" exception. +12. ```[Daniel Cazzulino](http://www.codeplex.com/site/users/view/dcazzulino)``` ([@kzu](https://twitter.com/kzu)) + - ```[#2990](http://nuget.codeplex.com/workitem/2990)``` - Add Version property to NetPortableProfile class. +13. ```[David Simner](https://www.codeplex.com/site/users/view/DavidSimner)``` + - ```[#3460](https://nuget.codeplex.com/workitem/3460)``` - Fix bug NullReferenceException if requireApiKey = true, but the header X-NUGET-APIKEY isn't present +14. ```[Michael Friis](https://www.codeplex.com/site/users/view/friism)``` ([@friism](https://twitter.com/friism)) + - ```[#3278](https://nuget.codeplex.com/workitem/3278)``` - Fixes NuGet.Build targets file to so that it works correctly on MonoDevelop +15. ```[Pranav Krishnamoorthy](https://www.codeplex.com/site/users/view/pranavkm)``` ([@pranav_km](https://twitter.com/pranav_km)) - Improve Restore command performance by increasing parallelization ## Notable features in the release @@ -112,14 +112,14 @@ With each of the partners above, they would use their own copy of nuget.exe and #### Known Issues -There were two known issues with nuget.exe restore with the initial 2.7 release, but they were fixed on 9/6/2013 with an update to the [NuGet.CommandLine package](http://www.nuget.org/packages/NuGet.CommandLine/). This update is also available on the [NuGet 2.7 download page](https://nuget.codeplex.com/releases/view/107605) on CodePlex. Running `nuget.exe update -self` will update to the latest release. +There were two known issues with nuget.exe restore with the initial 2.7 release, but they were fixed on 9/6/2013 with an update to the [NuGet.CommandLine package](https://www.nuget.org/packages/NuGet.CommandLine/). This update is also available on the ```[NuGet 2.7 download page](https://nuget.codeplex.com/releases/view/107605)``` on CodePlex. Running `nuget.exe update -self` will update to the latest release. The fixed were: -1. [New package restore doesn't work on Mono when using SLN file](https://nuget.codeplex.com/workitem/3596) -1. [New package restore doesn't work with Wix projects](https://nuget.codeplex.com/workitem/3598) +1. ```[New package restore doesn't work on Mono when using SLN file](https://nuget.codeplex.com/workitem/3596)``` +1. ```[New package restore doesn't work with Wix projects](https://nuget.codeplex.com/workitem/3598)``` -There is also a known issue with the new package restore workflow whereby [Automatic Package Restore does not work for projects under a solution folder](https://nuget.codeplex.com/workitem/3625). This issue was fixed in NuGet 2.7.1. +There is also a known issue with the new package restore workflow whereby ```[Automatic Package Restore does not work for projects under a solution folder](https://nuget.codeplex.com/workitem/3625)```. This issue was fixed in NuGet 2.7.1. ### Project Retargeting and Upgrade Build Errors/Warnings @@ -159,23 +159,23 @@ We added some new APIs to our extensibility services to fill the gap of missing #### IVsPackageInstallerServices - ```cs - // Checks if a NuGet package with the specified Id and version is installed in the specified project. - bool IsPackageInstalledEx(Project project, string id, string versionString); +```cs +// Checks if a NuGet package with the specified Id and version is installed in the specified project. +bool IsPackageInstalledEx(Project project, string id, string versionString); - // Get the list of NuGet packages installed in the specified project. - IEnumerable GetInstalledPackages(Project project); - ``` +// Get the list of NuGet packages installed in the specified project. +IEnumerable GetInstalledPackages(Project project); +``` #### IVsPackageInstaller - ```cs - // Installs one or more packages that exist on disk in a folder defined in the registry. - void InstallPackagesFromRegistryRepository(string keyName, bool isPreUnzipped, bool skipAssemblyReferences, Project project, IDictionary packageVersions); +```cs +// Installs one or more packages that exist on disk in a folder defined in the registry. +void InstallPackagesFromRegistryRepository(string keyName, bool isPreUnzipped, bool skipAssemblyReferences, Project project, IDictionary packageVersions); - // Installs one or more packages that are embedded in a Visual Studio Extension Package. - void InstallPackagesFromVSExtensionRepository(string extensionId, bool isPreUnzipped, bool skipAssemblyReferences, Project project, IDictionary packageVersions); - ``` +// Installs one or more packages that are embedded in a Visual Studio Extension Package. +void InstallPackagesFromVSExtensionRepository(string extensionId, bool isPreUnzipped, bool skipAssemblyReferences, Project project, IDictionary packageVersions); +``` ### Development-Only Dependencies @@ -187,8 +187,8 @@ The new package restore model in 2.7 is implemented by a new VSPackage which is Since we are unsure how many developers are still using NuGet in that version/edition of Visual Studio, we are publishing a separate Visual Studio extension specifically for those users and publishing it on CodePlex (rather than the Visual Studio Extension Gallery). We don't plan to continue to maintain that extension, but if this affects you please let us know by filing an issue on CodePlex. -To download the NuGet Package Manager (for Visual Studio 2010 Express for Windows Phone), visit the [NuGet 2.7 Downloads](https://nuget.codeplex.com/releases/view/107605) page. +To download the NuGet Package Manager (for Visual Studio 2010 Express for Windows Phone), visit the ```[NuGet 2.7 Downloads](https://nuget.codeplex.com/releases/view/107605)``` page. ### Bug Fixes -In addition to these features, this release of NuGet also includes many other bug fixes. There were 97 total issues addressed in the release. For a full list of work items fixed in NuGet 2.7, please view the [NuGet Issue Tracker for this release](https://nuget.codeplex.com/workitem/list/advanced?release=NuGet%202.7&status=all). +In addition to these features, this release of NuGet also includes many other bug fixes. There were 97 total issues addressed in the release. For a full list of work items fixed in NuGet 2.7, please view the ```[NuGet Issue Tracker for this release](https://nuget.codeplex.com/workitem/list/advanced?release=NuGet%202.7&status=all)```. diff --git a/docs/release-notes/NuGet-2.8.1.md b/docs/release-notes/NuGet-2.8.1.md index cf6f48ed6..1b9cea406 100644 --- a/docs/release-notes/NuGet-2.8.1.md +++ b/docs/release-notes/NuGet-2.8.1.md @@ -1,10 +1,10 @@ --- title: NuGet 2.8.1 Release Notes description: Release notes for NuGet 2.8.1 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.8.1 Release Notes @@ -27,7 +27,7 @@ This release updates the NuGet client found in WebMatrix to [NuGet.Core](https:/ For more information about the WebMatrix Extension update, see those specific [release notes](../release-notes/nuget-2.6.1-for-WebMatrix.md). ### Bug Fixes -In addition to these features, this release of NuGet includes other bug fixes. There were 16 total issues addressed in the release. For a full list of the work items fixed in NuGet 2.8.1, please view the [NuGet Issue Tracker for this release](https://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%202.8.1&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0&reasonClosed=All). +In addition to these features, this release of NuGet includes other bug fixes. There were 16 total issues addressed in the release. For a full list of the work items fixed in NuGet 2.8.1, please view the ```[NuGet Issue Tracker for this release](https://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%202.8.1&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0&reasonClosed=All)```. ### Reshipping with Visual Studio "14" CTP In Visual Studio "14" CTP released on June 3rd 2014, NuGet 2.8.1 is shipped in the box. The features it support remain in-par with other 2.8.1 VSIXes such as the one for Visual Studio 2013. diff --git a/docs/release-notes/NuGet-2.8.2.md b/docs/release-notes/NuGet-2.8.2.md index 76891517b..30fc16840 100644 --- a/docs/release-notes/NuGet-2.8.2.md +++ b/docs/release-notes/NuGet-2.8.2.md @@ -1,10 +1,10 @@ --- title: NuGet 2.8.2 Release Notes description: Release notes for NuGet 2.8.2 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.8.2 Release Notes @@ -19,13 +19,13 @@ The most notable updates were in the nuget.exe command-line and the NuGet.Server ### Important nuget.exe Bug Fixes -1. [nuget.exe Push fails and keeps retrying](https://nuget.codeplex.com/workitem/4000) -1. [nuget.exe Push does not send Basic Auth credentials correctly](https://nuget.codeplex.com/workitem/4109) -1. [nuget.exe Push won't follow temporary redirect](https://nuget.codeplex.com/workitem/4050) +1. ```[nuget.exe Push fails and keeps retrying](https://nuget.codeplex.com/workitem/4000)``` +1. ```[nuget.exe Push does not send Basic Auth credentials correctly](https://nuget.codeplex.com/workitem/4109)``` +1. ```[nuget.exe Push won't follow temporary redirect](https://nuget.codeplex.com/workitem/4050)``` ### Important NuGet.Server Bug Fix -1. [Wrong value of IsAbsoluteLatestVersion returned by NuGet.Server](https://nuget.codeplex.com/workitem/4147) +1. ```[Wrong value of IsAbsoluteLatestVersion returned by NuGet.Server](https://nuget.codeplex.com/workitem/4147)``` ## Packages Updated @@ -40,4 +40,4 @@ Here's the list of updated packages: 1. [NuGet.VisualStudio](https://www.nuget.org/packages/NuGet.VisualStudio/) (the package, not the extension) ## All Changes -There were 10 issues addressed in the release. For a full list of the work items fixed in NuGet 2.8.2, please view the [NuGet Issue Tracker for this release](https://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%202.8.2&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0&reasonClosed=All). +There were 10 issues addressed in the release. For a full list of the work items fixed in NuGet 2.8.2, please view the ```[NuGet Issue Tracker for this release](https://nuget.codeplex.com/workitem/list/advanced?keyword=&status=All&type=All&priority=All&release=NuGet%202.8.2&assignedTo=All&component=All&sortField=LastUpdatedDate&sortDirection=Descending&page=0&reasonClosed=All)```. diff --git a/docs/release-notes/NuGet-2.8.3.md b/docs/release-notes/NuGet-2.8.3.md index 4a091bc3d..85476d164 100644 --- a/docs/release-notes/NuGet-2.8.3.md +++ b/docs/release-notes/NuGet-2.8.3.md @@ -1,10 +1,10 @@ --- title: NuGet 2.8.3 Release Notes description: Release notes for NuGet 2.8.3 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.8.3 Release Notes @@ -13,4 +13,4 @@ ms.topic: conceptual NuGet 2.8.3 was released October 17, 2014. It is a minor update to our 2.8.1 VSIX with some targeted fixes. -In this release, the support for NuGet Package Manager dialog was added for [ASP.NET vNext](http://www.asp.net/vnext), [DevExtreme](http://js.devexpress.com/) and [BizTalk (.btproj)](/biztalk/core/developing-biztalk-server-applications) project types. It also includes reliability bug fixes related to the scenarios of enabling package restore and saving package manager options. +In this release, the support for NuGet Package Manager dialog was added for [ASP.NET vNext](https://www.asp.net/vnext), [DevExtreme](https://js.devexpress.com/) and [BizTalk (.btproj)](/biztalk/core/developing-biztalk-server-applications) project types. It also includes reliability bug fixes related to the scenarios of enabling package restore and saving package manager options. diff --git a/docs/release-notes/NuGet-2.8.5.md b/docs/release-notes/NuGet-2.8.5.md index 84a9973cc..8952af0db 100644 --- a/docs/release-notes/NuGet-2.8.5.md +++ b/docs/release-notes/NuGet-2.8.5.md @@ -1,10 +1,10 @@ --- title: NuGet 2.8.5 Release Notes description: Release notes for NuGet 2.8.5 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.8.5 Release Notes @@ -22,4 +22,4 @@ In this release, the support for NuGet Package Manager dialog was added for [DNX One bug was fixed that prevented packages from installing into FSharp projects properly: -https://nuget.codeplex.com/workitem/4400 \ No newline at end of file +```https://nuget.codeplex.com/workitem/4400``` diff --git a/docs/release-notes/NuGet-2.8.6.md b/docs/release-notes/NuGet-2.8.6.md index 9ece694a4..2d009fd6d 100644 --- a/docs/release-notes/NuGet-2.8.6.md +++ b/docs/release-notes/NuGet-2.8.6.md @@ -1,10 +1,10 @@ --- title: NuGet 2.8.6 Release Notes description: Release notes for NuGet 2.8.6 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.8.6 Release Notes @@ -20,4 +20,4 @@ In this release, the NuGet Package Manager dialog had support added for: * Introduced the UAP Target Framework Moniker to support Windows 10 Application Development. * NuGet protocol version 3 endpoints * Support for [Nuget.Config](../consume-packages/configuring-nuget-behavior.md) protocolVersion attribute on repository sources. Default value is "2" -* Falling back to remote repository if a required package version is not available in the local cache \ No newline at end of file +* Falling back to remote repository if a required package version is not available in the local cache diff --git a/docs/release-notes/NuGet-2.8.7.md b/docs/release-notes/NuGet-2.8.7.md index c1123da94..7eba6482a 100644 --- a/docs/release-notes/NuGet-2.8.7.md +++ b/docs/release-notes/NuGet-2.8.7.md @@ -1,10 +1,10 @@ --- title: NuGet 2.8.7 Release Notes description: Release notes for NuGet 2.8.7 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.8.7 Release Notes @@ -12,4 +12,4 @@ ms.topic: conceptual [NuGet 2.8.6 Release Notes](../release-notes/nuget-2.8.6.md) | [NuGet 2.9-RC Release Notes](../release-notes/nuget-2.9-RC.md) NuGet 2.8.7 was released July 27, 2015 as a patch update to the 2.8.6 VSIX with fix specific to a bug that effected Powershell policy implementation. -[https://github.com/NuGet/Home/issues/974](https://github.com/NuGet/Home/issues/974) \ No newline at end of file +[https://github.com/NuGet/Home/issues/974](https://github.com/NuGet/Home/issues/974) diff --git a/docs/release-notes/NuGet-2.8.md b/docs/release-notes/NuGet-2.8.md index ca6632837..950ad8ac6 100644 --- a/docs/release-notes/NuGet-2.8.md +++ b/docs/release-notes/NuGet-2.8.md @@ -1,10 +1,10 @@ --- title: NuGet 2.8 Release Notes description: Release notes for NuGet 2.8 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.8 Release Notes @@ -15,23 +15,23 @@ NuGet 2.8 was released on January 29, 2014. ## Acknowledgements -1. [Llewellyn Pritchard](https://www.codeplex.com/site/users/view/leppie) ([@leppie](https://twitter.com/leppie)) - - [#3466](https://nuget.codeplex.com/workitem/3466) - When packing packages, verifying Id of dependency packages. -2. [Maarten Balliauw](https://www.codeplex.com/site/users/view/maartenba) ([@maartenballiauw](https://twitter.com/maartenballiauw)) - - [#2379](https://nuget.codeplex.com/workitem/2379) - Remove the $metadata suffix when persistening feed credentials. -3. [Filip De Vos](https://www.codeplex.com/site/users/view/FilipDeVos) ([@foxtricks](https://twitter.com/foxtricks)) - - [#3538](http://nuget.codeplex.com/workitem/3538) - Support specifying project file for the nuget.exe update command. -4. [Juan Gonzalez](https://www.codeplex.com/site/users/view/jjgonzalez) - - [#3536](http://nuget.codeplex.com/workitem/3536) - Replacement tokens not passed with -IncludeReferencedProjects. -5. [David Poole](https://www.codeplex.com/site/users/view/Sarkie) ([@Sarkie_Dave](https://twitter.com/Sarkie_Dave)) - - [#3677](http://nuget.codeplex.com/workitem/3677) - Fix nuget.push throwing OutOfMemoryException when pushing large package. -6. [Wouter Ouwens](https://www.codeplex.com/site/users/view/Despotes) - - [#3666](http://nuget.codeplex.com/workitem/3666) - Fix incorrect target path when project references another CLI/C++ project. -7. [Adam Ralph](http://www.codeplex.com/site/users/view/adamralph) ([@adamralph](https://twitter.com/adamralph)) - - [#3639](https://nuget.codeplex.com/workitem/3639) - Allow packages to be installed as development dependencies by default -8. [David Fowler](https://www.codeplex.com/site/users/view/dfowler) ([@davidfowl](https://twitter.com/davidfowl)) - - [#3717](https://nuget.codeplex.com/workitem/3717) - Remove implicit upgrades to the latest patch version -9. [Gregory Vandenbrouck](https://www.codeplex.com/site/users/view/vdbg) +1. ```[Llewellyn Pritchard](https://www.codeplex.com/site/users/view/leppie)``` ([@leppie](https://twitter.com/leppie)) + - ```[#3466](https://nuget.codeplex.com/workitem/3466)``` - When packing packages, verifying Id of dependency packages. +2. ```[Maarten Balliauw](https://www.codeplex.com/site/users/view/maartenba)``` ([@maartenballiauw](https://twitter.com/maartenballiauw)) + - ```[#2379](https://nuget.codeplex.com/workitem/2379)``` - Remove the $metadata suffix when persistening feed credentials. +3. ```[Filip De Vos](https://www.codeplex.com/site/users/view/FilipDeVos)``` ([@foxtricks](https://twitter.com/foxtricks)) + - ```[#3538](http://nuget.codeplex.com/workitem/3538)``` - Support specifying project file for the nuget.exe update command. +4. ```[Juan Gonzalez](https://www.codeplex.com/site/users/view/jjgonzalez)``` + - ```[#3536](http://nuget.codeplex.com/workitem/3536)``` - Replacement tokens not passed with -IncludeReferencedProjects. +5. ```[David Poole](https://www.codeplex.com/site/users/view/Sarkie)``` ([@Sarkie_Dave](https://twitter.com/Sarkie_Dave)) + - ```[#3677](http://nuget.codeplex.com/workitem/3677)``` - Fix nuget.push throwing OutOfMemoryException when pushing large package. +6. ```[Wouter Ouwens](https://www.codeplex.com/site/users/view/Despotes)``` + - ```[#3666](http://nuget.codeplex.com/workitem/3666)``` - Fix incorrect target path when project references another CLI/C++ project. +7. ```[Adam Ralph](http://www.codeplex.com/site/users/view/adamralph)``` ([@adamralph](https://twitter.com/adamralph)) + - ```[#3639](https://nuget.codeplex.com/workitem/3639)``` - Allow packages to be installed as development dependencies by default +8. ```[David Fowler](https://www.codeplex.com/site/users/view/dfowler)``` ([@davidfowl](https://twitter.com/davidfowl)) + - ```[#3717](https://nuget.codeplex.com/workitem/3717)``` - Remove implicit upgrades to the latest patch version +9. ```[Gregory Vandenbrouck](https://www.codeplex.com/site/users/view/vdbg)``` - Several bug fixes and improvements for NuGet.Server, the nuget.exe mirror command, and others. - This work was done over several months, with Gregory working with us on the right timing to integrate into master for 2.8. @@ -39,13 +39,15 @@ NuGet 2.8 was released on January 29, 2014. When resolving package dependencies, NuGet has historically implemented a strategy of selecting the lowest major and minor package version which satisfies the dependencies on the package. Unlike the major and minor version, however, the patch version was always resolved to the highest version. Though the behavior was well-intentioned, it created a lack of determinism for installing packages with dependencies. Consider the following example: - PackageA@1.0.0 -[ >=1.0.0 ]-> PackageB@1.0.0 +``` +PackageA@1.0.0 -[ >=1.0.0 ]-> PackageB@1.0.0 - Developer1 installs PackageA@1.0.0: installed PackageA@1.0.0 and PackageB@1.0.0 +Developer1 installs PackageA@1.0.0: installed PackageA@1.0.0 and PackageB@1.0.0 - PackageB@1.0.1 is published +PackageB@1.0.1 is published - Developer2 installs PackageA@1.0.0: installed PackageA@1.0.0 and PackageB@1.0.1 +Developer2 installs PackageA@1.0.0: installed PackageA@1.0.0 and PackageB@1.0.1 +``` In this example, even though Developer1 and Developer2 installed PackageA@1.0.0, each ended up with a different version of PackageB. NuGet 2.8 changes this default behavior such that the dependency resolution behavior for patch versions is consistent with the behavior for major and minor versions. In the above example, then, PackageB@1.0.0 would be installed as a result of installing PackageA@1.0.0, regardless of the newer patch version. @@ -59,24 +61,28 @@ Though NuGet 2.8 changes the _default_ behavior for resolving dependencies, it a In addition to the -DependencyVersion switch detailed above, NuGet has also allowed for the ability to set a new attribute in the Nuget.Config file defining what the default value is, if the -DependencyVersion switch is not specified in an invocation of install-package. This value will also be respected by the NuGet Package Manager Dialog for any install package operations. To set this value, add the attribute below to your Nuget.Config file: - - - +```xml + + + +``` ## Preview NuGet Operations With -whatif Some NuGet packages can have deep dependency graphs, and as such, it can be helpful during an install, uninstall, or update operation to first see what will happen. NuGet 2.8 adds the standard PowerShell -whatif switch to the install-package, uninstall-package, and update-package commands to enable visualizing the entire closure of packages to which the command will be applied. For example, running `install-package Microsoft.AspNet.WebApi -whatif` in an empty ASP.NET Web application yields the following. - PM> install-package Microsoft.AspNet.WebApi -whatif - Attempting to resolve dependency 'Microsoft.AspNet.WebApi.WebHost (≥ 5.0.0)'. - Attempting to resolve dependency 'Microsoft.AspNet.WebApi.Core (≥ 5.0.0)'. - Attempting to resolve dependency 'Microsoft.AspNet.WebApi.Client (≥ 5.0.0)'. - Attempting to resolve dependency 'Newtonsoft.Json (≥ 4.5.11)'. - Install Newtonsoft.Json 4.5.11 - Install Microsoft.AspNet.WebApi.Client 5.0.0 - Install Microsoft.AspNet.WebApi.Core 5.0.0 - Install Microsoft.AspNet.WebApi.WebHost 5.0.0 - Install Microsoft.AspNet.WebApi 5.0.0 +``` +PM> install-package Microsoft.AspNet.WebApi -whatif +Attempting to resolve dependency 'Microsoft.AspNet.WebApi.WebHost (≥ 5.0.0)'. +Attempting to resolve dependency 'Microsoft.AspNet.WebApi.Core (≥ 5.0.0)'. +Attempting to resolve dependency 'Microsoft.AspNet.WebApi.Client (≥ 5.0.0)'. +Attempting to resolve dependency 'Newtonsoft.Json (≥ 4.5.11)'. +Install Newtonsoft.Json 4.5.11 +Install Microsoft.AspNet.WebApi.Client 5.0.0 +Install Microsoft.AspNet.WebApi.Core 5.0.0 +Install Microsoft.AspNet.WebApi.WebHost 5.0.0 +Install Microsoft.AspNet.WebApi 5.0.0 +``` ## Downgrade Package @@ -94,14 +100,16 @@ When developing applications for multiple target platforms, it's common to have ## Fallback to Local Cache -Though NuGet packages are typically consumed from a remote gallery such as [the NuGet gallery](http://www.nuget.org/) using a network connection, there are many scenarios where the client is not connected. Without a network connection, the NuGet client was not able to successfully install packages - even when those packages were already on the client's machine in the local NuGet cache. NuGet 2.8 adds automatic cache fallback to the package manager console. For example, when disconnecting the network adapter and installing jQuery, the console shows the following: +Though NuGet packages are typically consumed from a remote gallery such as [the NuGet gallery](https://www.nuget.org/) using a network connection, there are many scenarios where the client is not connected. Without a network connection, the NuGet client was not able to successfully install packages - even when those packages were already on the client's machine in the local NuGet cache. NuGet 2.8 adds automatic cache fallback to the package manager console. For example, when disconnecting the network adapter and installing jQuery, the console shows the following: - PM> Install-Package jquery - The source at nuget.org [https://www.nuget.org/api/v2/] is unreachable. Falling back to NuGet Local Cache at C:\Users\me\AppData\Local\NuGet\Cache - Installing 'jQuery 2.0.3'. - Successfully installed 'jQuery 2.0.3'. - Adding 'jQuery 2.0.3' to WebApplication18. - Successfully added 'jQuery 2.0.3' to WebApplication18. +``` +PM> Install-Package jquery +The source at nuget.org [https://www.nuget.org/api/v2/] is unreachable. Falling back to NuGet Local Cache at C:\Users\me\AppData\Local\NuGet\Cache +Installing 'jQuery 2.0.3'. +Successfully installed 'jQuery 2.0.3'. +Adding 'jQuery 2.0.3' to WebApplication18. +Successfully added 'jQuery 2.0.3' to WebApplication18. +``` The cache fallback feature does not require any specific command arguments. Additionally, cache fallback currently works only in the package manager console - the behavior does not currently work in the package manager dialog. @@ -123,4 +131,4 @@ This is the NuGet team's first release of the NuGet Package Manager extension fo One of the major bug fixes made was performance improvement in the update-package -reinstall command. -In addition to these features and the aforementioned performance fix, this release of NuGet also includes many other bug fixes. There were 181 total issues addressed in the release. For a full list of the work items fixed in NuGet 2.8, please view the [NuGet Issue Tracker for this release](https://nuget.codeplex.com/workitem/list/advanced?release=NuGet%202.8&status=all). +In addition to these features and the aforementioned performance fix, this release of NuGet also includes many other bug fixes. There were 181 total issues addressed in the release. For a full list of the work items fixed in NuGet 2.8, please view the ```[NuGet Issue Tracker for this release](https://nuget.codeplex.com/workitem/list/advanced?release=NuGet%202.8&status=all)```. diff --git a/docs/release-notes/NuGet-2.9-RC.md b/docs/release-notes/NuGet-2.9-RC.md index 27cf95643..a4c2a3ebb 100644 --- a/docs/release-notes/NuGet-2.9-RC.md +++ b/docs/release-notes/NuGet-2.9-RC.md @@ -1,10 +1,10 @@ --- title: NuGet 2.9-RC Release Notes description: Release notes for NuGet 2.9 RC including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 2.9-RC Release Notes diff --git a/docs/release-notes/NuGet-3.0-Beta.md b/docs/release-notes/NuGet-3.0-Beta.md index 8d6518c4a..0cd6ff14a 100644 --- a/docs/release-notes/NuGet-3.0-Beta.md +++ b/docs/release-notes/NuGet-3.0-Beta.md @@ -1,10 +1,10 @@ --- title: NuGet 3.0 Beta Release Notes description: Release notes for NuGet 3.0 Beta including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.0 Beta Release Notes @@ -13,11 +13,11 @@ ms.topic: conceptual NuGet 3.0 Beta was released on February 23, 2015 for the Visual Studio 2015 CTP 6 release. This release means a lot to our team, as we have a number of architecture and performance improvements to share, and we're excited to start tuning the performance settings on our nuget.org service. -We strongly recommend that you uninstall any prior version of the NuGet Visual Studio 2015 extension before installing this new version. If you have any problems with this version of the extension, we recommend you revert to the [prior version](http://nuget.codeplex.com/downloads/get/909582) for use with Visual Studio 2015 preview. +We strongly recommend that you uninstall any prior version of the NuGet Visual Studio 2015 extension before installing this new version. If you have any problems with this version of the extension, we recommend you revert to the ```[prior version](http://nuget.codeplex.com/downloads/get/909582)``` for use with Visual Studio 2015 preview. ## Visual Studio 2012+ -This NuGet 3.0 Beta is available to install in the Visual Studio 2015 CTP 6 Extension Gallery. We are working to get preview drops out for Visual Studio 2012 and Visual Studio 2013 very soon. We previously shared our intent to [discontinue updates for Visual Studio 2010](http://blog.nuget.org/20141002/visual-studio-2010.html), and we did make that difficult decision. +This NuGet 3.0 Beta is available to install in the Visual Studio 2015 CTP 6 Extension Gallery. We are working to get preview drops out for Visual Studio 2012 and Visual Studio 2013 very soon. We previously shared our intent to [discontinue updates for Visual Studio 2010](https://blog.nuget.org/20141002/visual-studio-2010.html), and we did make that difficult decision. ## New Client/Server API @@ -51,4 +51,4 @@ We have now rearchitected our NuGet clients into several components that are the ## Stay Tuned -Please keep an eye on [our blog](http://blog.nuget.org) for more progress and announcements for NuGet 3.0! +Please keep an eye on [our blog](https://blog.nuget.org) for more progress and announcements for NuGet 3.0! diff --git a/docs/release-notes/NuGet-3.0-Preview.md b/docs/release-notes/NuGet-3.0-Preview.md index d96f59375..00f990e0f 100644 --- a/docs/release-notes/NuGet-3.0-Preview.md +++ b/docs/release-notes/NuGet-3.0-Preview.md @@ -1,10 +1,10 @@ --- title: NuGet 3.0 Preview Release Notes description: Release notes for NuGet 3.0 Preview including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.0 Preview Release Notes @@ -15,7 +15,7 @@ NuGet 3.0 Preview was released on November 12, 2014 as part of the Visual Studio ## Visual Studio 2012+ -This NuGet 3.0 Preview is included in Visual Studio 2015 Preview. We are working to get preview drops out for Visual Studio 2012 and Visual Studio 2013 very soon. We previously shared our intent to [discontinue updates for Visual Studio 2010](http://blog.nuget.org/20141002/visual-studio-2010.html), and we did make that difficult decision. +This NuGet 3.0 Preview is included in Visual Studio 2015 Preview. We are working to get preview drops out for Visual Studio 2012 and Visual Studio 2013 very soon. We previously shared our intent to [discontinue updates for Visual Studio 2010](https://blog.nuget.org/20141002/visual-studio-2010.html), and we did make that difficult decision. ## Brand New UI @@ -113,11 +113,11 @@ Despite the investment we're putting into API v3, we've made all of these new fe Between now and 3.0 RTM, we are also working on some fundamental new NuGet features, beyond what you see in the UI. Here's a short list of salient investment areas: -1. We're partnering with the Visual Studio and MSBuild teams to get [NuGet deeper into the platform](http://blog.nuget.org/20141014/in-the-platform.html). -1. We're working to abandon installation-time package conventions and instead apply those conventions at packaging time by introducing a new "authoritative" [package manifest](http://blog.nuget.org/20141023/package-manifests.html). +1. We're partnering with the Visual Studio and MSBuild teams to get [NuGet deeper into the platform](https://blog.nuget.org/20141014/in-the-platform.html). +1. We're working to abandon installation-time package conventions and instead apply those conventions at packaging time by introducing a new "authoritative" [package manifest](https://blog.nuget.org/20141023/package-manifests.html). 1. We're working to refactor the NuGet codebase to make the client and server components reusable in different domains beyond package management in Visual Studio. 1. We're investigating the notion of "private dependencies" where a package can indicate that it has dependencies on other packages for implementation details only, and those dependencies shouldn't be surfaced as top-level dependencies. ## Stay Tuned -Please keep an eye on [our blog](http://blog.nuget.org) for more progress and announcements for NuGet 3.0! \ No newline at end of file +Please keep an eye on [our blog](https://blog.nuget.org) for more progress and announcements for NuGet 3.0! diff --git a/docs/release-notes/NuGet-3.0-RC.md b/docs/release-notes/NuGet-3.0-RC.md index 676eee3f3..867f4269b 100644 --- a/docs/release-notes/NuGet-3.0-RC.md +++ b/docs/release-notes/NuGet-3.0-RC.md @@ -1,10 +1,10 @@ --- title: NuGet 3.0 RC Release Notes description: Release notes for NuGet 3.0 RC including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.0 RC Release Notes @@ -32,9 +32,9 @@ In order to stabilize the NuGet clients, we resolved many issues as part of this ## GitHub presence overhaul -We've made some changes to our [source code repositories on GitHub](http://github.com/nuget/home). If you have any issues with the NuGet Visual Studio client, the Powershell commands, or the command-line executable you can log those issues and monitor their progress on our [GitHub Home repository issues list](http://github.com/nuget/home/issues). We are tracking issues for the gallery in our [GitHub NuGetGallery repository](http://github.com/nuget/NuGetGallery/issues). +We've made some changes to our [source code repositories on GitHub](https://github.com/nuget/home). If you have any issues with the NuGet Visual Studio client, the Powershell commands, or the command-line executable you can log those issues and monitor their progress on our [GitHub Home repository issues list](https://github.com/nuget/home/issues). We are tracking issues for the gallery in our [GitHub NuGetGallery repository](https://github.com/nuget/NuGetGallery/issues). ## Stay Tuned -Please keep an eye on [our blog](http://blog.nuget.org) for more progress and announcements for NuGet 3.0! \ No newline at end of file +Please keep an eye on [our blog](https://blog.nuget.org) for more progress and announcements for NuGet 3.0! diff --git a/docs/release-notes/NuGet-3.0-RC2.md b/docs/release-notes/NuGet-3.0-RC2.md index 7979ab0f1..193ae5190 100644 --- a/docs/release-notes/NuGet-3.0-RC2.md +++ b/docs/release-notes/NuGet-3.0-RC2.md @@ -1,17 +1,17 @@ --- title: NuGet 3.0 RC2 Release Notes description: Release notes for NuGet 3.0 RC2 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.0 RC2 Release Notes [NuGet 3.0 RC Release Notes](../release-notes/nuget-3.0-RC.md) | [NuGet 3.0 Release Notes](../release-notes/nuget-3.0.0.md) -NuGet 3.0 RC2 was released on June 3, 2015 as an interim release available from the Visual Studio 2015 Extension Gallery and [Codeplex](https://nuget.codeplex.com/releases/view/615507). This release has a number of important bug fixes and performance improvements that we felt were important to release before the completed Visual Studio 2015 release. This NuGet extension version is only available for Visual Studio 2015. +NuGet 3.0 RC2 was released on June 3, 2015 as an interim release available from the Visual Studio 2015 Extension Gallery and ```[Codeplex](https://nuget.codeplex.com/releases/view/615507)```. This release has a number of important bug fixes and performance improvements that we felt were important to release before the completed Visual Studio 2015 release. This NuGet extension version is only available for Visual Studio 2015. In total, we closed 158 issues in this release, and you can review the [complete list of issues on GitHub](https://github.com/NuGet/Home/issues?utf8=%E2%9C%93&q=is%3Aclosed+milestone%3A3.0.0-RTM+sort%3Aupdated-asc+updated%3A%3C%3D2015-06-01). @@ -31,4 +31,4 @@ In total, we closed 158 issues in this release, and you can review the [complete * [Improved error logging](https://github.com/NuGet/Home/issues/407) * [Improved powershell error messages when calling Update-Package](https://github.com/NuGet/Home/issues/5) -Download this [update to the NuGet extension](https://nuget.codeplex.com/releases/view/615507) from Codeplex and please keep an eye on [our blog](http://blog.nuget.org) for more progress and announcements for NuGet 3.0! \ No newline at end of file +Download this ```[update to the NuGet extension](https://nuget.codeplex.com/releases/view/615507)``` from Codeplex and please keep an eye on [our blog](https://blog.nuget.org) for more progress and announcements for NuGet 3.0! diff --git a/docs/release-notes/NuGet-3.0.0.md b/docs/release-notes/NuGet-3.0.0.md index e90e3ceb0..a404510af 100644 --- a/docs/release-notes/NuGet-3.0.0.md +++ b/docs/release-notes/NuGet-3.0.0.md @@ -1,10 +1,10 @@ --- title: NuGet 3.0 Release Notes description: Release notes for NuGet 3.0.0 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.0 Release Notes @@ -49,4 +49,4 @@ There were a number of known issues delivered with this release, and all of thes * [Multiple Packages can be gathered in parallel](https://github.com/NuGet/Home/issues/713) * [Removed install-package -force command](https://github.com/NuGet/Home/issues/697) -Please keep an eye on [our blog](http://blog.nuget.org) for more progress and announcements as we get ready to deliver support for Windows 10 development. \ No newline at end of file +Please keep an eye on [our blog](https://blog.nuget.org) for more progress and announcements as we get ready to deliver support for Windows 10 development. diff --git a/docs/release-notes/NuGet-3.1.1.md b/docs/release-notes/NuGet-3.1.1.md index 03c118a2f..d755e1cd1 100644 --- a/docs/release-notes/NuGet-3.1.1.md +++ b/docs/release-notes/NuGet-3.1.1.md @@ -1,10 +1,10 @@ --- title: NuGet 3.1.1 Release Notes description: Release notes for NuGet 3.1.1 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.1.1 Release Notes @@ -12,4 +12,4 @@ ms.topic: conceptual [NuGet 3.1 Release Notes](../release-notes/nuget-3.1.md) | [NuGet 3.2-RC Release Notes](../release-notes/nuget-3.2-RC.md) NuGet 3.1.1 was released July 27, 2015 as a patch update to the 3.1 VSIX with fix specific to a bug that effected Powershell policy implementation. -[https://github.com/NuGet/Home/issues/974](https://github.com/NuGet/Home/issues/974) \ No newline at end of file +[https://github.com/NuGet/Home/issues/974](https://github.com/NuGet/Home/issues/974) diff --git a/docs/release-notes/NuGet-3.1.md b/docs/release-notes/NuGet-3.1.md index 4b3d25786..db0f53466 100644 --- a/docs/release-notes/NuGet-3.1.md +++ b/docs/release-notes/NuGet-3.1.md @@ -1,10 +1,10 @@ --- title: NuGet 3.1 Release Notes description: Release notes for NuGet 3.1 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.1 Release Notes @@ -48,11 +48,13 @@ There were a number of known issues delivered with this release. ## NuGet Command-line -The NuGet command-line executable was updated and moved to a new distributable location so that historical versions of nuget.exe can continue to be made available. You can download the 3.1 beta version of nuget.exe for Windows at: [http://dist.nuget.org/win-x86-commandline/v3.1.0-beta/nuget.exe](http://dist.nuget.org/win-x86-commandline/v3.1.0-beta/nuget.exe) +The NuGet command-line executable was updated and moved to a new distributable location so that historical versions of nuget.exe can continue to be made available. You can download the 3.1 beta version of nuget.exe for Windows at: [https://dist.nuget.org/win-x86-commandline/v3.1.0-beta/nuget.exe](https://dist.nuget.org/win-x86-commandline/v3.1.0-beta/nuget.exe) The new distributable location resides on the dist.nuget.org host, with a folder structure that follows this template: - {platform supported}/{version}/nuget.exe +``` +{platform supported}/{version}/nuget.exe +``` ### New Features @@ -64,4 +66,4 @@ The new distributable location resides on the dist.nuget.org host, with a folder 1. Cannot execute pack against a `project.json` file - [928](https://github.com/NuGet/Home/issues/928) 2. Is not supported on Mono - [1059](https://github.com/NuGet/Home/issues/1059) 3. Is not localized - [1058](https://github.com/NuGet/Home/issues/1058), [1057](https://github.com/NuGet/Home/issues/1057) -4. Is not signed, just like the existing http://nuget.org/nuget.exe - [1073](https://github.com/NuGet/Home/issues/1073) +4. Is not signed, just like the existing https://nuget.org/nuget.exe - [1073](https://github.com/NuGet/Home/issues/1073) diff --git a/docs/release-notes/NuGet-3.2-RC.md b/docs/release-notes/NuGet-3.2-RC.md index cf774f4f6..28f9dd082 100644 --- a/docs/release-notes/NuGet-3.2-RC.md +++ b/docs/release-notes/NuGet-3.2-RC.md @@ -1,10 +1,10 @@ --- title: NuGet 3.2 RC Release Notes description: Release notes for NuGet 3.2 RC including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.2 RC Release Notes @@ -111,4 +111,4 @@ A complete list of issues addressed for the Visual Studio extension can be found ## Known Issues -We continue to track issues on our GitHub issues list which can be found at: [http://github.com/nuget/home/issues](http://github.com/nuget/home/issues) \ No newline at end of file +We continue to track issues on our GitHub issues list which can be found at: [https://github.com/nuget/home/issues](https://github.com/nuget/home/issues) diff --git a/docs/release-notes/NuGet-3.2.1.md b/docs/release-notes/NuGet-3.2.1.md index ec776d496..543ed8742 100644 --- a/docs/release-notes/NuGet-3.2.1.md +++ b/docs/release-notes/NuGet-3.2.1.md @@ -1,17 +1,17 @@ --- title: NuGet 3.2.1 Release Notes description: Release notes for NuGet 3.2.1 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.2.1 Release Notes [NuGet 3.2 Release Notes](../release-notes/nuget-3.2.md) | [NuGet 3.3 Release Notes](../release-notes/nuget-3.3.md) -NuGet 3.2.1 for the command-line was released October 12, 2015 with a handful of optimizations and fixes for the 3.2 release and is available from [dist.nuget.org](http://dist.nuget.org/index.html). +NuGet 3.2.1 for the command-line was released October 12, 2015 with a handful of optimizations and fixes for the 3.2 release and is available from [dist.nuget.org](https://dist.nuget.org/index.html). ## Improvements @@ -30,4 +30,4 @@ A complete list of issues addressed for the command-line and Visual Studio exten ## Known Issues -We continue to track issues on our GitHub issues list which can be found at: [http://github.com/nuget/home/issues](http://github.com/nuget/home/issues) \ No newline at end of file +We continue to track issues on our GitHub issues list which can be found at: [https://github.com/nuget/home/issues](https://github.com/nuget/home/issues) diff --git a/docs/release-notes/NuGet-3.2.md b/docs/release-notes/NuGet-3.2.md index e26d847fd..48afecf3f 100644 --- a/docs/release-notes/NuGet-3.2.md +++ b/docs/release-notes/NuGet-3.2.md @@ -1,17 +1,17 @@ --- title: NuGet 3.2 Release Notes description: Release notes for NuGet 3.2 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.2 Release Notes [NuGet 3.2-RC Release Notes](../release-notes/nuget-3.2-RC.md) | [NuGet 3.2.1 Release Notes](../release-notes/nuget-3.2.1.md) -NuGet 3.2 was released September 16, 2015 as a collection of improvements and fixes for the 3.1.1 release and is available from both [dist.nuget.org](http://dist.nuget.org/index.html) and the [Visual Studio Gallery](https://marketplace.visualstudio.com/items?itemName=NuGetTeam.NuGetPackageManagerforVisualStudio2015). +NuGet 3.2 was released September 16, 2015 as a collection of improvements and fixes for the 3.1.1 release and is available from both [dist.nuget.org](https://dist.nuget.org/index.html) and the [Visual Studio Gallery](https://marketplace.visualstudio.com/items?itemName=NuGetTeam.NuGetPackageManagerforVisualStudio2015). ## New Features @@ -109,4 +109,4 @@ A complete list of issues addressed for the Visual Studio extension can be found ## Known Issues -We continue to track issues on our GitHub issues list which can be found at: [http://github.com/nuget/home/issues](http://github.com/nuget/home/issues) \ No newline at end of file +We continue to track issues on our GitHub issues list which can be found at: [https://github.com/nuget/home/issues](https://github.com/nuget/home/issues) diff --git a/docs/release-notes/NuGet-3.3.md b/docs/release-notes/NuGet-3.3.md index dd9ca3f96..f9e990a61 100644 --- a/docs/release-notes/NuGet-3.3.md +++ b/docs/release-notes/NuGet-3.3.md @@ -1,10 +1,10 @@ --- title: NuGet 3.3 Release Notes description: Release notes for NuGet 3.3 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.3 Release Notes @@ -15,7 +15,7 @@ NuGet 3.3 was released November 30, 2015 with a significant number of user inter ## New Features -* Credential Providers have been introduced that allow NuGet command-line clients to be able to work seamlessly with an authenticated feed. [Instructions on how to install the Visual Studio Team Services credential provider ](../api/nuget-exe-credential-providers.md) and configure the NuGet clients to use it are available on NuGet Docs. +* Credential Providers have been introduced that allow NuGet command-line clients to be able to work seamlessly with an authenticated feed. [Instructions on how to install the Visual Studio Team Services credential provider ](../reference/extensibility/nuget-exe-credential-providers.md) and configure the NuGet clients to use it are available on NuGet Docs. ## New User Interface Features @@ -32,7 +32,7 @@ NuGet 3.3 was released November 30, 2015 with a significant number of user inter ## New Command-line Features -In this version we introduced the `add` and `init` commands to initialize folder-based repositories as described in the [nuget.exe reference](../reference/nuget-exe-cli-reference.md). Repositories that are constructed and maintained with this folder structure will [deliver significant performance benefits](http://blog.nuget.org/20150922/Accelerate-Package-Source.html) as outlined on our blog. +In this version we introduced the `add` and `init` commands to initialize folder-based repositories as described in the [nuget.exe reference](../reference/nuget-exe-cli-reference.md). Repositories that are constructed and maintained with this folder structure will [deliver significant performance benefits](https://blog.nuget.org/20150922/Accelerate-Package-Source.html) as outlined on our blog. ## ContentFiles @@ -54,4 +54,4 @@ The list of issues fixed in the 3.3 command-line release are recorded in the [3. ## Known Issues -We continue to track issues on our GitHub issues list which can be found at: [http://github.com/nuget/home/issues](http://github.com/nuget/home/issues) \ No newline at end of file +We continue to track issues on our GitHub issues list which can be found at: [https://github.com/nuget/home/issues](https://github.com/nuget/home/issues) diff --git a/docs/release-notes/NuGet-3.4-RC.md b/docs/release-notes/NuGet-3.4-RC.md index ae9b9ac6f..8e7e10089 100644 --- a/docs/release-notes/NuGet-3.4-RC.md +++ b/docs/release-notes/NuGet-3.4-RC.md @@ -1,10 +1,10 @@ --- title: NuGet 3.4-RC Release Notes description: Release notes for NuGet 3.4 RC including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.4-RC Release Notes @@ -43,4 +43,4 @@ The following features are available in this RC, with more planned for the 3.4 f ## Known Issues -We continue to track issues on our GitHub issues list which can be found at: [http://github.com/nuget/home/issues](http://github.com/nuget/home/issues) \ No newline at end of file +We continue to track issues on our GitHub issues list which can be found at: [https://github.com/nuget/home/issues](https://github.com/nuget/home/issues) diff --git a/docs/release-notes/NuGet-3.4.1.md b/docs/release-notes/NuGet-3.4.1.md index 1ba5a4081..2d9ddc85f 100644 --- a/docs/release-notes/NuGet-3.4.1.md +++ b/docs/release-notes/NuGet-3.4.1.md @@ -1,10 +1,10 @@ --- title: NuGet 3.4.1 Release Notes description: Release notes for NuGet 3.4.1 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.4.1 Release Notes @@ -19,4 +19,4 @@ NuGet 3.4.1 was released March 30, 2016 at the same time as the Visual Studio 20 * Corrected an issue with Visual Studio locating `lucene.net.dll` * All sources should not be the default repository source after a NuGet extension install or update. You can opt-in to this feature from the configuration settings. -We continue to track issues on our GitHub issues list which can be found at: [http://github.com/nuget/home/issues](http://github.com/nuget/home/issues) \ No newline at end of file +We continue to track issues on our GitHub issues list which can be found at: [https://github.com/nuget/home/issues](https://github.com/nuget/home/issues) diff --git a/docs/release-notes/NuGet-3.4.2.md b/docs/release-notes/NuGet-3.4.2.md index a87800eb2..ace3e38a3 100644 --- a/docs/release-notes/NuGet-3.4.2.md +++ b/docs/release-notes/NuGet-3.4.2.md @@ -1,10 +1,10 @@ --- title: NuGet 3.4.2 Release Notes description: Release notes for NuGet 3.4.2 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.4.2 Release Notes @@ -40,4 +40,4 @@ These issues will be fixed early next week before we hit RTM. * Running nuget delete command on a package using the V2 feed will fail. Use V3 feed instead. -For the complete list of fixes and improvements in this release, check out the list of issues [here](https://github.com/NuGet/Home/issues?utf8=%E2%9C%93&q=is%3Aissue+milestone%3A3.4.2++is%3Aclosed+). \ No newline at end of file +For the complete list of fixes and improvements in this release, check out the list of issues [here](https://github.com/NuGet/Home/issues?utf8=%E2%9C%93&q=is%3Aissue+milestone%3A3.4.2++is%3Aclosed+). diff --git a/docs/release-notes/NuGet-3.4.3.md b/docs/release-notes/NuGet-3.4.3.md index c7b83344e..0e1471ab6 100644 --- a/docs/release-notes/NuGet-3.4.3.md +++ b/docs/release-notes/NuGet-3.4.3.md @@ -1,10 +1,10 @@ --- title: NuGet 3.4.3 Release Notes description: Release notes for NuGet 3.4.3 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.4.3 Release Notes @@ -27,4 +27,4 @@ You can download both the VSIX and nuget.exe [here](https://dist.nuget.org/index * Fixed an issue that caused restore failures in C++/CLI projects with `project.json`. * Some packages (E.g ModernHttpClient) where not being unzipped correctly when you use nuget in mono. This has now been fixed in this release. -For the complete list of fixes and improvements in this release, check out the list of issues [here](https://github.com/NuGet/Home/issues?q=is%3Aissue+milestone%3A3.4.3+is%3Aclosed). \ No newline at end of file +For the complete list of fixes and improvements in this release, check out the list of issues [here](https://github.com/NuGet/Home/issues?q=is%3Aissue+milestone%3A3.4.3+is%3Aclosed). diff --git a/docs/release-notes/NuGet-3.4.4.md b/docs/release-notes/NuGet-3.4.4.md index 33b5a24f8..ac831086e 100644 --- a/docs/release-notes/NuGet-3.4.4.md +++ b/docs/release-notes/NuGet-3.4.4.md @@ -1,10 +1,10 @@ --- title: NuGet 3.4.4 Release Notes description: Release notes for NuGet 3.4.4 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.4.4 Release Notes @@ -32,4 +32,4 @@ You can download both the VSIX and nuget.exe [here](https://dist.nuget.org/index - Updating `NuGet.Core.dll` version to 2.12.0 to fix XML issue [\#594](https://github.com/NuGet/NuGet.Client/pull/594) - Support ./NuGet.CommandLine.XPlat -v \ \ [\#593](https://github.com/NuGet/NuGet.Client/pull/593) - Display error restoring without `project.json` or `packages.config` [\#590](https://github.com/NuGet/NuGet.Client/pull/590) -- Fixing dependency versions when required versions differ [\#559](https://github.com/NuGet/NuGet.Client/pull/559) \ No newline at end of file +- Fixing dependency versions when required versions differ [\#559](https://github.com/NuGet/NuGet.Client/pull/559) diff --git a/docs/release-notes/NuGet-3.4.md b/docs/release-notes/NuGet-3.4.md index 0a4d49f96..a9e55c5df 100644 --- a/docs/release-notes/NuGet-3.4.md +++ b/docs/release-notes/NuGet-3.4.md @@ -1,10 +1,10 @@ --- title: NuGet 3.4 Release Notes description: Release notes for NuGet 3.4 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.4 Release Notes @@ -54,11 +54,11 @@ The following features were previously added in the RC and have been updated or * Loading projects that have an init.ps1 script (like EntityFramework) * Publishing web content -* **Workaround:** Ensure that your Windows 10 install has the latest patches applied, expecially the January 2016 (KB 3124263) or a later update. More details are available on [GitHub issue #1638](http://github.com/nuget/home/issues/1638) +* **Workaround:** Ensure that your Windows 10 install has the latest patches applied, expecially the January 2016 (KB 3124263) or a later update. More details are available on [GitHub issue #1638](https://github.com/nuget/home/issues/1638) * **Issue:** NuGet v2 protocol redirects are broken. Custom NuGet repositories that redirect requests to an alternative host do not honor the redirect request. * **Workaround:** To work around this issue, configure the package repository URI in settings to point to the redirected server location. For more information, see [GitHub pull request #387](https://github.com/NuGet/NuGet.Client/pull/387). -We continue to track issues on our GitHub issues list which can be found at: [http://github.com/nuget/home/issues](http://github.com/nuget/home/issues) \ No newline at end of file +We continue to track issues on our GitHub issues list which can be found at: [https://github.com/nuget/home/issues](https://github.com/nuget/home/issues) diff --git a/docs/release-notes/NuGet-3.5-Beta.md b/docs/release-notes/NuGet-3.5-Beta.md index bddbcce4e..5d69352d7 100644 --- a/docs/release-notes/NuGet-3.5-Beta.md +++ b/docs/release-notes/NuGet-3.5-Beta.md @@ -1,17 +1,17 @@ --- title: NuGet 3.5 Beta Release Notes description: Release notes for NuGet 3.5 Beta including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.5 Beta Release Notes [NuGet 3.4 Release Notes](../release-notes/nuget-3.4.md) | [NuGet 3.5-Beta2 Release Notes](../release-notes/nuget-3.5-Beta2.md) -NuGet 3.5 Beta was released on May 16, 2016 as part of the ASP.NET Core Preview Tooling wave. This release adds support for .NET Core RC2 and ASP.NET Core RC2. For more information about this release please refer to [http://dot.net](http://dot.net). +NuGet 3.5 Beta was released on May 16, 2016 as part of the ASP.NET Core Preview Tooling wave. This release adds support for .NET Core RC2 and ASP.NET Core RC2. For more information about this release please refer to [http://dot.net](https://dot.net). You can download both the VSIX and nuget.exe [here](https://dist.nuget.org/index.html). @@ -23,4 +23,4 @@ NuGet 3.5 Beta is a superset of the changes introduced in the 3.4.3 release. For ## Fixes -* The list of fixes and improvements in this release, is given [here](https://github.com/NuGet/Home/issues?q=is%3Aissue+milestone%3A%223.5+Beta%22+is%3Aclosed). \ No newline at end of file +* The list of fixes and improvements in this release, is given [here](https://github.com/NuGet/Home/issues?q=is%3Aissue+milestone%3A%223.5+Beta%22+is%3Aclosed). diff --git a/docs/release-notes/NuGet-3.5-Beta2.md b/docs/release-notes/NuGet-3.5-Beta2.md index 431744bb4..7cf76b2cb 100644 --- a/docs/release-notes/NuGet-3.5-Beta2.md +++ b/docs/release-notes/NuGet-3.5-Beta2.md @@ -1,10 +1,10 @@ --- title: 3.5 Beta2 Release Notes description: Release notes for NuGet 3.5 Beta 2 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.5 Beta2 Release Notes @@ -85,4 +85,4 @@ NuGet 3.5 Beta 2 RTM was released June 27, 2016 for Visual Studio 2013 and nuget * Print out nuget.exe version header in detailed output - [#1887](https://github.com/NuGet/Home/issues/1887) -* NuGet should add support for /runtimes/{rid}/nativeassets/{txm}/ - [#2782](https://github.com/NuGet/Home/issues/2782) \ No newline at end of file +* NuGet should add support for /runtimes/{rid}/nativeassets/{txm}/ - [#2782](https://github.com/NuGet/Home/issues/2782) diff --git a/docs/release-notes/NuGet-3.5-RC.md b/docs/release-notes/NuGet-3.5-RC.md index 1ac24a31c..b3bd58ed8 100644 --- a/docs/release-notes/NuGet-3.5-RC.md +++ b/docs/release-notes/NuGet-3.5-RC.md @@ -1,10 +1,10 @@ --- title: 3.5 RC Release Notes description: Release notes for NuGet 3.5 RC including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.5 RC Release Notes diff --git a/docs/release-notes/NuGet-3.5-RTM.md b/docs/release-notes/NuGet-3.5-RTM.md index 2520f3a14..3301d1b2a 100644 --- a/docs/release-notes/NuGet-3.5-RTM.md +++ b/docs/release-notes/NuGet-3.5-RTM.md @@ -1,10 +1,10 @@ --- -title: NuGet 3.5 Beta Release Notes +title: NuGet 3.5 RTM Release Notes description: Release notes for NuGet 3.5 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/11/2016 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 3.5 Release Notes diff --git a/docs/release-notes/NuGet-4.0-RC.md b/docs/release-notes/NuGet-4.0-RC.md index e94b606e7..cfeb207ad 100644 --- a/docs/release-notes/NuGet-4.0-RC.md +++ b/docs/release-notes/NuGet-4.0-RC.md @@ -1,10 +1,10 @@ --- title: NuGet 4.0 RC Release Notes description: Release notes for NuGet 4.0 RC including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 02/03/2017 -ms.topic: conceptual +ms.topic: release-notes ms.reviewer: ananguar --- @@ -12,7 +12,7 @@ ms.reviewer: ananguar [NuGet 3.5 RTM Release Notes](../release-notes/nuget-3.5-RTM.md) -[NuGet 4.0 RC for Visual Studio 2017](http://blog.nuget.org/20161121/introducing-nuget4.0) is focused on adding support for .NET Core scenarios, addressing key customer feedback and improving performance in a variety of scenarios. This release brings several improvements like support for PackageReference, NuGet commands as MSBuild targets, background package restore, and more. +[NuGet 4.0 RC for Visual Studio 2017](https://blog.nuget.org/20161121/introducing-nuget4.0) is focused on adding support for .NET Core scenarios, addressing key customer feedback and improving performance in a variety of scenarios. This release brings several improvements like support for PackageReference, NuGet commands as MSBuild targets, background package restore, and more. ## Bug Fixes @@ -47,7 +47,7 @@ ms.reviewer: ananguar - TFS issue: "[file]not be found in your workspace, or you do not have permission to access it" - [#2805](https://github.com/NuGet/Home/issues/2805) -- Typing "nuget " in vs quicklaunch search box keeps "nuget " prefix - [#2719](https://github.com/NuGet/Home/issues/2719) +- Typing "nuget \" in vs quicklaunch search box keeps "nuget " prefix - [#2719](https://github.com/NuGet/Home/issues/2719) - System.Xml.XmlException: Unrecognized root element in Core Properties part. Line 2, position 2. - [#2718](https://github.com/NuGet/Home/issues/2718) diff --git a/docs/release-notes/NuGet-4.0-RTM.md b/docs/release-notes/NuGet-4.0-RTM.md index eea6e726a..7fd345079 100644 --- a/docs/release-notes/NuGet-4.0-RTM.md +++ b/docs/release-notes/NuGet-4.0-RTM.md @@ -1,10 +1,10 @@ --- -title: NuGet 4.0 RC Release Notes +title: NuGet 4.0 RTM Release Notes description: Release notes for NuGet 4.0 RTM including known issues, bug fixes, added features, and DCRs. author: anangaur ms.author: anangaur ms.date: 03/03/2017 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 4.0 RTM Release Notes @@ -332,7 +332,7 @@ There is no workaround at this time. - dotnetcore pack always seems to set ProjectReference version to 1.0.0 - [#3874](https://github.com/NuGet/Home/issues/3874) - dotnet - - dotnetcore pack fails with project references and - [#3865](https://github.com/NuGet/Home/issues/3865) + - dotnetcore pack fails with project references and \ - [#3865](https://github.com/NuGet/Home/issues/3865) - LockRecursionException in ProjectSystemCache.TryGetProjectNameByShortName - [#3861](https://github.com/NuGet/Home/issues/3861) diff --git a/docs/release-notes/NuGet-4.3-RTM.md b/docs/release-notes/NuGet-4.3-RTM.md index c2e6887b1..9700bea1a 100644 --- a/docs/release-notes/NuGet-4.3-RTM.md +++ b/docs/release-notes/NuGet-4.3-RTM.md @@ -1,10 +1,10 @@ --- title: NuGet 4.3 RTM Release Notes description: Release notes for NuGet 4.3 RTM including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 08/14/2017 -ms.topic: conceptual +ms.topic: release-notes ms.reviewer: anangaur --- diff --git a/docs/release-notes/NuGet-4.4-RTM.md b/docs/release-notes/NuGet-4.4-RTM.md index 5ca141eb5..a06c05f27 100644 --- a/docs/release-notes/NuGet-4.4-RTM.md +++ b/docs/release-notes/NuGet-4.4-RTM.md @@ -1,10 +1,10 @@ --- title: NuGet 4.4 RTM Release Notes -description: Release notes for NuGet 4.3 RTM including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +description: Release notes for NuGet 4.4 RTM including known issues, bug fixes, added features, and DCRs. +author: JonDouglas +ms.author: jodou ms.date: 08/14/2017 -ms.topic: conceptual +ms.topic: release-notes ms.reviewer: anangaur --- diff --git a/docs/release-notes/NuGet-4.5-RTM.md b/docs/release-notes/NuGet-4.5-RTM.md index 507e183f7..7acc5f0b1 100644 --- a/docs/release-notes/NuGet-4.5-RTM.md +++ b/docs/release-notes/NuGet-4.5-RTM.md @@ -4,7 +4,7 @@ description: Release notes for NuGet 4.5 RTM including known issues, bug fixes, author: anangaur ms.author: anangaur ms.date: 12/4/2017 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 4.5 Release Notes diff --git a/docs/release-notes/NuGet-4.6-rtm.md b/docs/release-notes/NuGet-4.6-rtm.md index b1e089539..ce8438c4c 100644 --- a/docs/release-notes/NuGet-4.6-rtm.md +++ b/docs/release-notes/NuGet-4.6-rtm.md @@ -4,7 +4,7 @@ description: Release notes for NuGet 4.6.0 including known issues, bug fixes, ad author: anangaur ms.author: anangaur ms.date: 3/7/2018 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 4.6 Release Notes diff --git a/docs/release-notes/NuGet-4.7-RTM.md b/docs/release-notes/NuGet-4.7-RTM.md index 46500d841..a43b5ab53 100644 --- a/docs/release-notes/NuGet-4.7-RTM.md +++ b/docs/release-notes/NuGet-4.7-RTM.md @@ -1,10 +1,10 @@ --- title: NuGet 4.7 RTM Release Notes description: Release notes for NuGet 4.7.0 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 5/14/2018 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 4.7 Release Notes @@ -15,7 +15,7 @@ ms.topic: conceptual * We have augmented package signing to enable [Repository Signed packages](https://github.com/NuGet/Home/wiki/Repository-Signatures) -* With Visual Studio Version 15.7, we have introduced the capability to [migrate existing projects that use the packages.config format to use PackageReference](https://docs.microsoft.com/en-us/nuget/consume-packages/migrate-packages-config-to-package-reference) instead. +* With Visual Studio Version 15.7, we have introduced the capability to [migrate existing projects that use the packages.config format to use PackageReference](../consume-packages/migrate-packages-config-to-package-reference.md) instead. ## Summary: What's New in 4.7.2 diff --git a/docs/release-notes/NuGet-4.8-RTM.md b/docs/release-notes/NuGet-4.8-RTM.md index 53b2ed285..1fef31ac9 100644 --- a/docs/release-notes/NuGet-4.8-RTM.md +++ b/docs/release-notes/NuGet-4.8-RTM.md @@ -1,10 +1,10 @@ --- title: NuGet 4.8 RTM Release Notes description: Release notes for NuGet 4.8.1 including known issues, bug fixes, added features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 5/14/2018 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 4.8 Release Notes @@ -31,7 +31,7 @@ Command line versions of the same functionality are also available: ### Installing signed packages on a CI machine or in an offline environment takes longer than usual #### Issue -If the machine has restricted internet access (such as a build machine in a CI/CD scenario), installing/restoring a signed nuget package will result a warning ([NU3028](https://docs.microsoft.com/en-us/nuget/reference/errors-and-warnings/nu3028)) since the revocation servers are not reachable. This is expected. However, in some cases, this may have unintended concequences such as the package install/restore taking longer than usual. +If the machine has restricted internet access (such as a build machine in a CI/CD scenario), installing/restoring a signed nuget package will result a warning ([NU3028](../reference/errors-and-warnings/nu3028.md)) since the revocation servers are not reachable. This is expected. However, in some cases, this may have unintended concequences such as the package install/restore taking longer than usual. #### Workaround Update to Visual Studio 15.8.4 and NuGet.exe 4.8.1 where we introduced an environment variable to switch the revocation check mode. diff --git a/docs/release-notes/NuGet-4.9-RTM.md b/docs/release-notes/NuGet-4.9-RTM.md index e098443d0..fd729e748 100644 --- a/docs/release-notes/NuGet-4.9-RTM.md +++ b/docs/release-notes/NuGet-4.9-RTM.md @@ -1,10 +1,10 @@ --- title: NuGet 4.9 RTM Release Notes description: Release notes for NuGet 4.9 including known issues, bug fixes, new features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 11/20/2018 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 4.9 Release Notes @@ -17,7 +17,16 @@ NuGet distribution vehicles: | [**4.9.1**](https://nuget.org/downloads) | n/a | n/a | | [**4.9.2**](https://nuget.org/downloads) |[Visual Studio 2017 version 15.9.4](https://visualstudio.microsoft.com/downloads/) | [2.1.502, 2.2.101](https://www.microsoft.com/net/download/visual-studio-sdks) | | [**4.9.3**](https://nuget.org/downloads) |[Visual Studio 2017 version 15.9.6](https://visualstudio.microsoft.com/downloads/) | [2.1.504, 2.2.104](https://www.microsoft.com/net/download/visual-studio-sdks) | +| [**4.9.5**](https://nuget.org/downloads) |n/a| n/a [.NET Core 2.1 is out of support as of August 21, 2021](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) +| [**4.9.6**](https://nuget.org/downloads) |n/a| n/a [.NET Core 2.1 is out of support as of August 21, 2021](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) +## Summary: What's New in 4.9.6 + +* [Security]: Microsoft Security Advisory CVE-2022-41032 | .NET Elevation of Privilege Vulnerability - [#12149](https://github.com/NuGet/Home/issues/12149) + +## Summary: What's New in 4.9.5 + +* [Security]: Microsoft Security Advisory CVE-2022-30184 | .NET Information Disclosure Vulnerability - [#11883](https://github.com/NuGet/Home/issues/11883) ## Summary: What's New in 4.9.0 diff --git a/docs/release-notes/NuGet-5.0-RTM.md b/docs/release-notes/NuGet-5.0-RTM.md index a39e8e51f..bd75b0597 100644 --- a/docs/release-notes/NuGet-5.0-RTM.md +++ b/docs/release-notes/NuGet-5.0-RTM.md @@ -1,10 +1,10 @@ --- title: NuGet 5.0 RTM Release Notes description: Release notes for NuGet 5.0 including known issues, bug fixes, new features, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 04/02/2019 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 5.0 Release Notes @@ -22,11 +22,11 @@ NuGet distribution vehicles: ## Summary: What's New in 5.0 -* Support for restoring [filtered solutions](https://docs.microsoft.com/en-us/visualstudio/ide/filtered-solutions?view=vs-2019) in Visual Studio 2019 - [#5820](https://github.com/NuGet/Home/issues/5820) +* Support for restoring [filtered solutions](/visualstudio/ide/filtered-solutions) in Visual Studio 2019 - [#5820](https://github.com/NuGet/Home/issues/5820) * `BuildTransitive` folder enables packages to transitively contribute targets/props to the host project - [#6091](https://github.com/NuGet/Home/issues/6091) * Better support for PackageReference scenarios in NuGet IVs APIs - [#7005](https://github.com/NuGet/Home/issues/7005), [#7493](https://github.com/NuGet/Home/issues/7493) * `nuget.exe pack project.json` has been deprecated - [#7928](https://github.com/NuGet/Home/issues/7928) -* Gen 1 Credential Provider plugin has been superseded by [Gen 2](https://aka.ms/nuget-cross-platform-authentication-plugin) and will soon be deprecated - [#7819](https://github.com/NuGet/Home/issues/7819) +* Gen 1 Credential Provider plugin has been superseded by [Gen 2](../reference/extensibility/nuget-cross-platform-authentication-plugin.md) and will soon be deprecated - [#7819](https://github.com/NuGet/Home/issues/7819) ## Issues fixed in this release diff --git a/docs/release-notes/NuGet-5.0-preview.md b/docs/release-notes/NuGet-5.0-preview.md deleted file mode 100644 index 528ab6728..000000000 --- a/docs/release-notes/NuGet-5.0-preview.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: NuGet 5.0-preview Release Notes -description: Release notes for NuGet 5.0 previews including known issues, bug fixes, new features, and DCRs. -author: anangaur -ms.author: anangaur -ms.date: 1/25/2019 -ms.topic: conceptual ---- - -# NuGet 5.0 Preview Release Notes - -## NuGet 5.0 Preview Releases - -* February 27, 2019 - [NuGet 5.0 Preview 4](#whats-new-in-nuget-50-preview-4) -* February 13, 2019 - [NuGet 5.0 Preview 3](#whats-new-in-nuget-50-preview-3) -* January 23, 2019 - [NuGet 5.0 Preview 2](#whats-new-in-nuget-50-preview-2) - -## What's New in NuGet 5.0 Preview 4 - -### Issues fixed in this release - -**Bugs** - -* NuGet.VisualStudio.IVsPackageInstaller - calling on a project with no package references always uses packages.config, even if the default is set to PackageReference - [#7005](https://github.com/NuGet/Home/issues/7005) - -* PMC: Update-Package reinstall fails ("Unable to find package") on delisted packages. - [#7268](https://github.com/NuGet/Home/issues/7268) - -* Add third party notice in our repo and VSIX - [#7409](https://github.com/NuGet/Home/issues/7409) - -* NuGet.VisualStudio.IVsPackageInstaller.InstallPackage should install latest version when no version given - [#7493](https://github.com/NuGet/Home/issues/7493) - -* --interactive support for dotnet nuget push - [#7519](https://github.com/NuGet/Home/issues/7519) - -* When restoring with lock file, NU1603 warning shouldn't be raised. - [#7529](https://github.com/NuGet/Home/issues/7529) - -* NuGet should not print project path during restore with minimal logging - [#7647](https://github.com/NuGet/Home/issues/7647) - -* --interactive support for dotnet remove package - [#7727](https://github.com/NuGet/Home/issues/7727) - -* Add back NuGet.Packaging.Core with TypeForwardedTo attrs - [#7768](https://github.com/NuGet/Home/issues/7768) - -* plugins_cache needs shorter path to work well - [#7770](https://github.com/NuGet/Home/issues/7770) - -* Prefer path for msbuild discovery if user didn't ask for specific msbuild version - [#7786](https://github.com/NuGet/Home/issues/7786) - -**DCRs** - -* limit http request number per source through NuGet.Config - [#4538](https://github.com/NuGet/Home/issues/4538) - -* NuGet should target Net472 (to help Cleanup the 16.0 build of the VSIX) - [#7143](https://github.com/NuGet/Home/issues/7143) - -* PMC: Remove OpenPackagePage command - [#7384](https://github.com/NuGet/Home/issues/7384) - -* Make NetCoreApp 3.0 map to NetStandard 2.1 - [#7762](https://github.com/NuGet/Home/issues/7762) - -* Add netstandard2.0 support to NuGet.* packages - [#6516](https://github.com/NuGet/Home/issues/6516) - - -## What's New in NuGet 5.0 Preview 3 - -### Issues fixed in this release - -**Bugs** - -* nuget.exe /? should list correct msbuild versions - [#7794](https://github.com/NuGet/Home/issues/7794) - -* NuGet.targets(498,5): error : Could not find a part of the path '/tmp/NuGetScratch - on mono - [#7793](https://github.com/NuGet/Home/issues/7793) - -* restore unnecessarily enumerates the contents of all versions of referenced package in the machine cache - [#7639](https://github.com/NuGet/Home/issues/7639) - -* MSBuild auto-detection always selects 16.0 after installing VS 2019 Preview - [#7621](https://github.com/NuGet/Home/issues/7621) - -* dotnet list package on a solution outputs duplicate entries for framework - [#7607](https://github.com/NuGet/Home/issues/7607) - -* Exception "Empty path name is not legal" when calling IVsPackageInstaller.InstallPackage on old projects and packages folder does not exist. - [#5936](https://github.com/NuGet/Home/issues/5936) - -* msbuild /t:restore minimal verbosity should be more minimal - [#4695](https://github.com/NuGet/Home/issues/4695) - -**DCRs** - -* Allow package authors to define build assets transitive behavior - [#6091](https://github.com/NuGet/Home/issues/6091) - -* Enable restore in VS to succeed if a project is not part of solution or is not loaded, but has previously been restored - [#5820](https://github.com/NuGet/Home/issues/5820) - - -## What's New in NuGet 5.0 Preview 2 - -### Issues fixed in this release - -**Bugs** - -* VS 16.0's NuGet UI has unreadable tabs due to color problems - [#7735](https://github.com/NuGet/Home/issues/7735) - -* NuGet.Core & NuGet.Clients License.txt clarification - [#7629](https://github.com/NuGet/Home/issues/7629) - -* Restore unnecessarily enumerates global package folder in attempt to determine type - [#7596](https://github.com/NuGet/Home/issues/7596) - -* Errors from lock file enforcement should show up in Error List Window - [#7429](https://github.com/NuGet/Home/issues/7429) - -* Fix NuGet.Configuration issues - [#7326](https://github.com/NuGet/Home/issues/7326) - -* Adapt to MSBuild updating it's install location. - [#7325](https://github.com/NuGet/Home/issues/7325) - -* NuGet.Build.Tasks.Pack should be a development dependency - [#7249](https://github.com/NuGet/Home/issues/7249) - -* Add pack extension point for including debug symbols - [#7234](https://github.com/NuGet/Home/issues/7234) - -* dotnet pack should preserve dependency version range in the created nupkg. (even if floating version is used) - [#7232](https://github.com/NuGet/Home/issues/7232) - -* dotnet restore fails on authenticated source when user-level config also has source - [#7209](https://github.com/NuGet/Home/issues/7209) - -* Pack should not restrict the set of BuildActions for content files - [#7155](https://github.com/NuGet/Home/issues/7155) - -* Using a projectreference which requires AssetTargetFallback to succeed, should warn. - [#7137](https://github.com/NuGet/Home/issues/7137) - -* Deadlock due to threading issues when calling into CPS (CommonProjectSystem) - [#7103](https://github.com/NuGet/Home/issues/7103) - -* dotnet add package won't use credentials from global config for a source specified in local config - [#6935](https://github.com/NuGet/Home/issues/6935) - -* Threading issues with MEF being called on async codepaths - [#6771](https://github.com/NuGet/Home/issues/6771) - -* Signing: error reported twice and without call stack - [#6455](https://github.com/NuGet/Home/issues/6455) - -* Installing a signed package with untrusted signing certificate should show error - [#6318](https://github.com/NuGet/Home/issues/6318) - -* NuGet restore improperly NoOps when 2 projects are sharing obj directory - [#6114](https://github.com/NuGet/Home/issues/6114) - -* Cannot use PAT with dotnet restore on Linux with packages from authenticated feed - [#5651](https://github.com/NuGet/Home/issues/5651) - -* dotnet restore fails due to disabled machine wide feed - [#5410](https://github.com/NuGet/Home/issues/5410) - -**DCRs** - -* NuGet 5.0 assemblies to require .NET 4.7.2 (via TFM change) - [#7510](https://github.com/NuGet/Home/issues/7510) - -* NuGetLicenseData from NuGet.Packaging should be a public type. Update license metadata ingested from spdx. - [#7471](https://github.com/NuGet/Home/issues/7471) - -* Remove obsolete Settings APIs - [#7294](https://github.com/NuGet/Home/issues/7294) - -* Workaround restore timeouts on systems with 1 cpu - [#6742](https://github.com/NuGet/Home/issues/6742) - -* NuGet prefers NTLM auth even if there are credentials in NuGet.config - add config option to filter auth types for credentials - [#5286](https://github.com/NuGet/Home/issues/5286) - -* Enable EmbedInteropTypes for PackageReference (matching Packages.Config capability) - [#2365](https://github.com/NuGet/Home/issues/2365) - -[List of all issues fixed in this release 5.0.0-preview2](https://github.com/NuGet/Home/issues?q=is%3Aissue+is%3Aclosed+milestone%3A%224.9.2") - -### Known issues - -#### Packages in FallbackFolders installed by .NET Core SDK are custom installed, and fail signature validation. - [#7414](https://github.com/NuGet/Home/issues/7414) -**Issue** -When using dotnet.exe 2.x to restore a project that multi-targets netcoreapp 1.x and netcoreapp 2.x, the fallback folder is treated as a file feed. This means, when restoring, NuGet will pick the package from the fallback folder and try to install it into the global packages folder and do the usual signing validation which fails. -**Workaround** -Disable the usage of the fallback folder by setting the `RestoreAdditionalProjectSources` to nothing. `` Use this with caution as it will cause a lot of packages to be downloaded from NuGet.org which otherwise would be have been restored from the fallback folder. diff --git a/docs/release-notes/NuGet-5.1-RTM.md b/docs/release-notes/NuGet-5.1-RTM.md index 71e5a2393..1f04bff82 100644 --- a/docs/release-notes/NuGet-5.1-RTM.md +++ b/docs/release-notes/NuGet-5.1-RTM.md @@ -1,10 +1,10 @@ --- title: NuGet 5.1 RTM Release Notes description: Release notes for NuGet 5.1 including new features, bug fixes, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 05/21/2019 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 5.1 Release Notes @@ -28,7 +28,7 @@ NuGet distribution vehicles: * Support for new .NET Core 3.0 assets such as [Targeting Packs](https://github.com/dotnet/cli/issues/10006) and [Runtime Packs](https://github.com/dotnet/cli/issues/10007) * NuGet pack and restore support for FrameworkReferences to enable targeting and runtime package references - [#7342](https://github.com/NuGet/Home/issues/7342) * Support "download only" package scenario with PackageDownload - [#7339](https://github.com/NuGet/Home/issues/7339) - * Exlcude runtime and targeting packs from search results & restore graph using PackageType - [#7337](https://github.com/NuGet/Home/issues/7337) + * Exclude runtime and targeting packs from search results & restore graph using PackageType - [#7337](https://github.com/NuGet/Home/issues/7337) ### Issues fixed in this release diff --git a/docs/release-notes/NuGet-5.10.md b/docs/release-notes/NuGet-5.10.md new file mode 100644 index 000000000..e83d28fa6 --- /dev/null +++ b/docs/release-notes/NuGet-5.10.md @@ -0,0 +1,154 @@ +--- +title: NuGet 5.10 Release Notes +description: Release notes for NuGet 5.10 including new features, bug fixes, and DCRs. +author: zkat +ms.author: kmarchan +ms.date: 6/11/2021 +ms.topic: release-notes +--- + +# NuGet 5.10 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**5.10.0**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.10](https://visualstudio.microsoft.com/downloads/) | [5.0.300](https://dotnet.microsoft.com/download/dotnet-core/5.0)1 | + +1 Installed with Visual Studio 2019 with .NET Core workload + +> [!NOTE] +> Visual Studio 16.10, MSBuild 16.10, and .NET 5.0.300+ requires NuGet.exe 5.10 or later. + +## Summary: What's New in 5.10 + +* Signing: implement dotnet trusted-signers command - [#8053](https://github.com/NuGet/Home/issues/8053) + +* Make default validation disabled on Linux, but enabled by default on Windows - [#10713](https://github.com/NuGet/Home/issues/10713) + +* Add an ENV Variable for Package Signing Verification on .NET 5+ Linux/MAC - [#10742](https://github.com/NuGet/Home/issues/10742) + +* Improve install new package performance for large solutions - [#10166](https://github.com/NuGet/Home/issues/10166) + +* Add the project type `nfproj` to the list of supportedProjectExtensions for Nuget CLI. - [#10562](https://github.com/NuGet/Home/issues/10562) + +### Issues fixed in this release + +* Suppress the `` element when packing a project - [#5133](https://github.com/NuGet/Home/issues/5133) + +* [CPVM] preview warning should be shown on dotnet cli - [#10226](https://github.com/NuGet/Home/issues/10226) + +* Update the background and foreground color tokens of the PMUI to CommonDocumentColors - [#10608](https://github.com/NuGet/Home/issues/10608) + +* [Bug Bash] Error “operation canceled by user” show in Error List window when switching between tabs quickly in PM UI - [#10671](https://github.com/NuGet/Home/issues/10671) + +* PM UI: Improve package installation performance on the solution level - [#10210](https://github.com/NuGet/Home/issues/10210) + +* Replace GetService with GetServiceAsync everywhere in NuGet.Clients - [#3784](https://github.com/NuGet/Home/issues/3784) + +* NuGet.exe pack performance problem with `..` relative path - [#5016](https://github.com/NuGet/Home/issues/5016) + +* The performance of "nuget pack" decreases with increasing levels in the source paths - [#5706](https://github.com/NuGet/Home/issues/5706) + +* NuGet doesn't error when packaging nuspec with duplicate files. - [#6941](https://github.com/NuGet/Home/issues/6941) + +* NuGet pack "The DateTimeOffset specified cannot be converted into a Zip file timestamp" - [#7001](https://github.com/NuGet/Home/issues/7001) + +* Timestamps of file of packed package is shifted by the timezone - [#7395](https://github.com/NuGet/Home/issues/7395) + +* NU1004 should contain more actionable information - [#7696](https://github.com/NuGet/Home/issues/7696) + +* [Bug Bash][Test Failure] The empty/malformed lock file should not be updated when running ‘dotnet restore --use-lock-file --locked-mode’ - [#8640](https://github.com/NuGet/Home/issues/8640) + +* NuGetVersionRange allows logically incorrect ranges to be parsed - [#9145](https://github.com/NuGet/Home/issues/9145) + +* PM UI can’t show distinguishable background color between selected and hovered package sources - [#9538](https://github.com/NuGet/Home/issues/9538) + +* Checkbox for selecting projects to install to isn't being read by screen reader - [#9578](https://github.com/NuGet/Home/issues/9578) + +* Details Pane Versions Dropdown default selection should be Installed/LatestStable on Installed/Updates tabs - [#9887](https://github.com/NuGet/Home/issues/9887) + +* Remove workaround account for some .NET 5 SDKs report TargetPlatformMoniker of ` ,Version= ` - [#9913](https://github.com/NuGet/Home/issues/9913) + +* dotnet nuget verify is too quiet - [#10316](https://github.com/NuGet/Home/issues/10316) + +* VersionRange cannot parse single-digit ranges - [#10342](https://github.com/NuGet/Home/issues/10342) + +* VS Solution manager throws null exception for during debugging - [#10352](https://github.com/NuGet/Home/issues/10352) + +* Move CLI exception messages to String Resource files - [#10392](https://github.com/NuGet/Home/issues/10392) + +* Remove dead code (TabItemButtonAutomationPeer) - [#10435](https://github.com/NuGet/Home/issues/10435) + +* Update context menu should scroll to first selected item - [#10498](https://github.com/NuGet/Home/issues/10498) + +* Solution PMUI Details has overlapping horizontal bar - [#10533](https://github.com/NuGet/Home/issues/10533) + +* Signing: primary signature details not displayed when certificate expired and timestamp untrusted - [#10535](https://github.com/NuGet/Home/issues/10535) + +* Having no enabled sources prevents the PM UI from showing - [#10541](https://github.com/NuGet/Home/issues/10541) + +* Package Metadata (details, deprecation) are sometimes not pulled from nuget.org in CodeSpaces - [#10549](https://github.com/NuGet/Home/issues/10549) + +* PMUI initialization fails with exception during debug session - [#10559](https://github.com/NuGet/Home/issues/10559) + +* nuget restore results in a package integrity check failure on big endian system - [#10567](https://github.com/NuGet/Home/issues/10567) + +* FormatException is thrown instead of PackagingException - [#10595](https://github.com/NuGet/Home/issues/10595) + +* CPVM - Concurrency issues in the graph walking algorithm - [#10598](https://github.com/NuGet/Home/issues/10598) + +* Add PMC powershell version telemetry - [#10609](https://github.com/NuGet/Home/issues/10609) + +* Improve NuGetVersion sort performance - [#10611](https://github.com/NuGet/Home/issues/10611) + +* Trusted-signers Add has inconsistent arguments - [#10647](https://github.com/NuGet/Home/issues/10647) + +* Vs2019 v16.9.0: Switching tabs in NuGet Package Manager from "Updates" to "Installed" doesn't update the frame. - [#10654](https://github.com/NuGet/Home/issues/10654) + +* Remove the "v" from the version number in PMUI - [#10677](https://github.com/NuGet/Home/issues/10677) + +* INuGetProjectService.GetInstalledPackagesAsync throws before receiving CPS project system nomination - [#10681](https://github.com/NuGet/Home/issues/10681) + +* Embedded Icons cause Access Denied from source "Microsoft Visual Studio Offline Packages" on Browse tab - [#10687](https://github.com/NuGet/Home/issues/10687) + +* INuGetProjectService.GetInstalledPackagesAsync throws when MSBuildProjectExtensionsPath is not set - [#10739](https://github.com/NuGet/Home/issues/10739) + +* "dotnet nuget remove source nuget.org" doesn't work the first time - [#10745](https://github.com/NuGet/Home/issues/10745) + +* Nuget blocks a threadpool thread in an async method making a synchronous call to the UI thread - [#10775](https://github.com/NuGet/Home/issues/10775) + +* `PackageLoadContext.GetInstalledAndTransitivePackagesAsync` is dead code and hurting performance - [#10790](https://github.com/NuGet/Home/issues/10790) + +* Use embedded icon in NuGet SDK packages - [#10795](https://github.com/NuGet/Home/issues/10795) + +* Update the SPDX license list - [#10806](https://github.com/NuGet/Home/issues/10806) + +**[List of all issues fixed in this release - 5.10](https://app.zenhub.com/workspaces/nuget-client-team-55aec9a240305cf007585881/reports/release?release=Z2lkOi8vcmFwdG9yL1JlbGVhc2UvNTY2MTQ)** + +**[List of commits in this release - 5.10.0](https://github.com/NuGet/NuGet.Client/compare/5.9.0.7134...5.10.0.7240)** + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +|Who|PRs|Issues| +|----|----|----| +[louis-z](https://github.com/louis-z) | [3991](https://github.com/NuGet/NuGet.Client/pull/3991) | VersionRange cannot parse single-digit ranges - [#10342](https://github.com/NuGet/Home/issues/10342) +[omajid](https://github.com/omajid) | [3860](https://github.com/NuGet/NuGet.Client/pull/3860) | NuGet.Client build.sh is broken - [#10139](https://github.com/NuGet/Home/issues/10139) +[Nirmal4G](https://github.com/Nirmal4G) | [3623](https://github.com/NuGet/NuGet.Client/pull/3623) | NuGet.Client build.sh is broken - [#10139](https://github.com/NuGet/Home/issues/10139) +[BlackGad](https://github.com/BlackGad) | [3953](https://github.com/NuGet/NuGet.Client/pull/3953) | The performance of "nuget pack" decreases with increasing levels in the source paths - [#5706](https://github.com/NuGet/Home/issues/5706) +[BlackGad](https://github.com/BlackGad) | [3953](https://github.com/NuGet/NuGet.Client/pull/3953) | NuGet.exe pack performance problem with .. relative path - [#5016](https://github.com/NuGet/Home/issues/5016) +[marcin-krystianc](https://github.com/marcin-krystianc) | [3940](https://github.com/NuGet/NuGet.Client/pull/3940) | CPVM - Concurrency issues in the graph walking algorithm - [#10598](https://github.com/NuGet/Home/issues/10598) +[josesimoes](https://github.com/josesimoes) | [3943](https://github.com/NuGet/NuGet.Client/pull/3943) | Add the project type nfproj to the list of supportedProjectExtensions for Nuget CLI. - [#10562](https://github.com/NuGet/Home/issues/10562) + +## Feedback welcome + +Your feedback is important to us. If there are any problems with this release, check our +[GitHub Issues](https://github.com/NuGet/Home/issues) and +[Visual Studio Developer Community](https://developercommunity.visualstudio.com/) +for existing issues. For new issues within NuGet, please report a +[GitHub Issue](https://github.com/NuGet/Home/issues/new). +For general NuGet experience issues, let us know via the +[Report a Problem](/visualstudio/ide/how-to-report-a-problem-with-visual-studio) +option found in your favorite IDE under **Help > Report a Problem**. diff --git a/docs/release-notes/NuGet-5.11.md b/docs/release-notes/NuGet-5.11.md new file mode 100644 index 000000000..dd8f31249 --- /dev/null +++ b/docs/release-notes/NuGet-5.11.md @@ -0,0 +1,71 @@ +--- +title: NuGet 5.11 Release Notes +description: Release notes for NuGet 5.11 including new features, bug fixes, and DCRs. +author: erdembayar +ms.author: eryondon +ms.date: 8/10/2021 +ms.topic: release-notes +--- + +# NuGet 5.11 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**5.11.0**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.11](https://visualstudio.microsoft.com/downloads/) | [5.0.400](https://dotnet.microsoft.com/download/dotnet-core/5.0)1 | +| [**5.11.2**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.11.16](https://visualstudio.microsoft.com/downloads/) | N/A | +| [**5.11.3**](https://nuget.org/downloads) | N/A | N/A | +| [**5.11.5**](https://nuget.org/downloads) | N/A | N/A | +| [**5.11.6**](https://nuget.org/downloads) | N/A | N/A | + +1 Installed with Visual Studio 2019 with .NET Core workload + +> [!NOTE] +> Visual Studio 16.11, MSBuild 16.11, and .NET 5.0.400+ requires NuGet.exe 5.11 or later. + +## Summary: What's New in 5.11.6 + +* [Security]: Microsoft Security Advisory CVE-2024-0057 | NuGet Client Security Feature bypass Vulnerability - [#12653](https://github.com/NuGet/Home/issues/13241) + +## Summary: What's New in 5.11.5 + +* [Security]: Microsoft Security Advisory CVE-2023-29337 | NuGet Client Remote Code Execution Vulnerability - [#12653](https://github.com/NuGet/Home/issues/12653) + +> [!NOTE] +> There is a behavior breaking change on Linux. The temp folder location, where NuGet stores temporary files during its various operations, has changed from `/tmp/NuGetScratch` to `/tmp/NuGetScratch`. E.g. for user User1, the temp folder will be `/tmp/NuGetScratchUser1`. + +## Summary: What's New in 5.11.3 + +* [Security]: Microsoft Security Advisory CVE-2022-41032 | .NET Elevation of Privilege Vulnerability - [#12149](https://github.com/NuGet/Home/issues/12149) + +## Summary: What's New in 5.11.2 + +* [Security]: Microsoft Security Advisory CVE-2022-30184 | .NET Information Disclosure Vulnerability - [#11883](https://github.com/NuGet/Home/issues/11883) + +## Summary: What's New in 5.11 + +### Issues fixed in this release + +**Bugs:** + +* Tools -> Options -> NuGet Package Manager string is truncated - [#10779](https://github.com/NuGet/Home/issues/10779) + +* Hang when the PackagesMissingStatusChanged event is fired - [#10854](https://github.com/NuGet/Home/issues/10854) + +* The NuGet client ignores the NO_PROXY setting - [#10902](https://github.com/NuGet/Home/issues/10902) + +**[List of all issues fixed in this release - 5.11](https://app.zenhub.com/workspaces/nuget-client-team-55aec9a240305cf007585881/reports/release?release=Z2lkOi8vcmFwdG9yL1JlbGVhc2UvNTk5MDE)** + +**[List of commits in this release - 5.11](https://github.com/NuGet/NuGet.Client/compare/5.10.0.7240...5.11.0.17)** + +## Feedback welcome + +Your feedback is important to us. If there are any problems with this release, check our +[GitHub Issues](https://github.com/NuGet/Home/issues) and +[Visual Studio Developer Community](https://developercommunity.visualstudio.com/) +for existing issues. For new issues within NuGet, please report a +[GitHub Issue](https://github.com/NuGet/Home/issues/new). +For general NuGet experience issues, let us know via the +[Report a Problem](/visualstudio/ide/how-to-report-a-problem-with-visual-studio) +option found in your favorite IDE under **Help > Report a Problem**. diff --git a/docs/release-notes/NuGet-5.2-RTM.md b/docs/release-notes/NuGet-5.2-RTM.md index 74d5dea15..a57435a9c 100644 --- a/docs/release-notes/NuGet-5.2-RTM.md +++ b/docs/release-notes/NuGet-5.2-RTM.md @@ -1,10 +1,10 @@ --- title: NuGet 5.2 RTM Release Notes description: Release notes for NuGet 5.2 including new features, bug fixes, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 07/23/2019 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 5.2 Release Notes @@ -14,11 +14,16 @@ NuGet distribution vehicles: | NuGet version | Available in Visual Studio version| Available in .NET SDK(s)| |:---|:---|:---| | [**5.2.0**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.2](https://visualstudio.microsoft.com/downloads/) | [2.1.80X](https://dotnet.microsoft.com/download/dotnet-core/2.1)1, [2.2.40X](https://dotnet.microsoft.com/download/dotnet-core/2.2)2 | +| [**5.2.1**](https://nuget.org/downloads) | n/a | n/a [.NET Core 2.2 is out of support as of December 23, 2019](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) | 1Installed with Visual Studio 2019 with .NET Core workload 2Available as an optional install with Visual Studio 2019 with .NET Core workload +## Summary: What's New in 5.2.1 + +* [Security]: Microsoft Security Advisory CVE 2022-30184 | .NET Information Disclosure Vulnerability - [#11883](https://github.com/NuGet/Home/issues/11883) + ## Summary: What's New in 5.2 * Fixed a critical bug that caused occasional NuGet operation failures due to path issues on Linux & Mac - [#7341](https://github.com/NuGet/Home/issues/7341) diff --git a/docs/release-notes/NuGet-5.3.md b/docs/release-notes/NuGet-5.3.md index 665ece148..6559e3454 100644 --- a/docs/release-notes/NuGet-5.3.md +++ b/docs/release-notes/NuGet-5.3.md @@ -1,10 +1,10 @@ --- title: NuGet 5.3 Release Notes description: Release notes for NuGet 5.3 including new features, bug fixes, and DCRs. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 09/06/2019 -ms.topic: conceptual +ms.topic: release-notes --- # NuGet 5.3 Release Notes @@ -14,6 +14,7 @@ NuGet distribution vehicles: | NuGet version | Available in Visual Studio version| Available in .NET SDK(s)| |:---|:---|:---| | [**5.3.0**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.3](https://visualstudio.microsoft.com/downloads/) | [3.0.100](https://dotnet.microsoft.com/download/dotnet-core/3.0)1 | +| [**5.3.1**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.3.6](https://visualstudio.microsoft.com/downloads/) | [Future version: 3.0.101](https://dotnet.microsoft.com/download/dotnet-core/3.0) | 1Installed with Visual Studio 2019 with .NET Core workload @@ -23,7 +24,7 @@ NuGet distribution vehicles: * Improved security with SHA tracking and enforcement for Packages.Config - [#7281](https://github.com/NuGet/Home/issues/7281) -* Enable deprecation of obsolete/legacy NuGet Packages [#2867](https://github.com/NuGet/Home/issues/2867) | [Blog post](https://devblogs.microsoft.com/nuget/deprecating-packages-on-nuget-org/) | [Docs](https://docs.microsoft.com/en-us/nuget/nuget-org/deprecate-packages) +* Enable deprecation of obsolete/legacy NuGet Packages [#2867](https://github.com/NuGet/Home/issues/2867) | [Blog post](https://devblogs.microsoft.com/nuget/deprecating-packages-on-nuget-org/) | [Docs](../nuget-org/deprecate-packages.md) ### Issues fixed in this release @@ -88,3 +89,9 @@ NuGet distribution vehicles: * Add -SolutionDirectory and -PackageDirectory options to nuget.exe pack - [#7163](https://github.com/NuGet/Home/issues/7163) **[List of all issues fixed in this release - 5.3](https://github.com/nuget/home/issues?q=is%3Aissue+is%3Aclosed+milestone%3A%225.3")** + +## Summary: What's New in 5.3.1 + +* Plugin: A task was canceled - don't let cancellations affect plugin instantiation - [#8648](https://github.com/NuGet/Home/issues/8648) + +* Restore Task cannot be safely run twice in one process (when Credential providers are used) - [#8688](https://github.com/NuGet/Home/issues/8688) diff --git a/docs/release-notes/NuGet-5.4.md b/docs/release-notes/NuGet-5.4.md new file mode 100644 index 000000000..9c8251328 --- /dev/null +++ b/docs/release-notes/NuGet-5.4.md @@ -0,0 +1,50 @@ +--- +title: NuGet 5.4 Release Notes +description: Release notes for NuGet 5.4 including new features, bug fixes, and DCRs. +author: JonDouglas +ms.author: jodou +ms.date: 09/06/2019 +ms.topic: release-notes +--- + +# NuGet 5.4 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version| Available in .NET SDK(s)| +|:---|:---|:---| +| [**5.4.0**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.4](https://visualstudio.microsoft.com/downloads/) | [3.1.100](https://dotnet.microsoft.com/download/dotnet-core/3.1)1 | + +1Installed with Visual Studio 2019 with .NET Core workload + +## Summary: What's New in 5.4 + +* Faster solution load time - Overhead running NuGet code during first solution load has been reduced via partial-ngen to reduce JIT cost - [#6007](https://github.com/NuGet/Home/issues/6007) + +* New helper function - given a list of package ids and versions, get the likely top level packages. - [#8316](https://github.com/NuGet/Home/issues/8316) + +* New [`nuget/setup-nuget`](https://github.com/marketplace/actions/setup-nuget-exe-for-use-with-actions) action for installing and configuring NuGet.exe on [GitHub Actions](https://github.com/features/actions). - [#8818](https://github.com/NuGet/Home/issues/8818) + +### Issues fixed in this release + +**Bugs** + +* Plugin: Logging time accuracy is off on linux/Mac - [#8747](https://github.com/NuGet/Home/issues/8747) + +* Disposing of a plugin can sometimes throw and fail the whole operation. - [#8732](https://github.com/NuGet/Home/issues/8732) + +* Stop displaying version duplicates in allowed and blocked versions list in PMUI - [#8679](https://github.com/NuGet/Home/issues/8679) + +* Lock File not properly generated - framework ordering should not impact the restore with lockedmode - [#8645](https://github.com/NuGet/Home/issues/8645) + +* LockFile validation fails for projects with \ set in SDK 3.0.100 - [#8639](https://github.com/NuGet/Home/issues/8639) + +* Signing Validation will now properly reject signatures with timestamps which have 2 values under the same OID - [#8629](https://github.com/NuGet/Home/issues/8629) + +* Update the license list - [#8544](https://github.com/NuGet/Home/issues/8544) + +**DCRs** + +* Onboarding diagnostic files to IFeedbackDiagnosticFileProvider - [#8535](https://github.com/NuGet/Home/issues/8535) + +**[List of all issues fixed in this release - 5.4](https://github.com/nuget/home/issues?q=is%3Aissue+is%3Aclosed+milestone%3A%225.4")** diff --git a/docs/release-notes/NuGet-5.5.md b/docs/release-notes/NuGet-5.5.md new file mode 100644 index 000000000..8c51128bc --- /dev/null +++ b/docs/release-notes/NuGet-5.5.md @@ -0,0 +1,100 @@ +--- +title: NuGet 5.5 Release Notes +description: Release notes for NuGet 5.5 including new features, bug fixes, and DCRs. +author: JonDouglas +ms.author: jodou +ms.date: 03/19/2020 +ms.topic: release-notes +--- + +# NuGet 5.5 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version| Available in .NET SDK(s)| +|:---|:---|:---| +| [**5.5.0**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.5](https://visualstudio.microsoft.com/downloads/) | [3.1.200](https://dotnet.microsoft.com/download/dotnet-core/3.1)1 | + +1Installed with Visual Studio 2019 with .NET Core workload + +## Summary: What's New in 5.5 + +* Improved accessibility and screen reader experience for the NuGet package manager UI in Visual Studio + * Accessibility issues in Screen Reader experiences, missing altText and accessible name for Installed textbox, etc., - [#9059](https://github.com/NuGet/Home/issues/9059) + * Accessibility issues in Screen Reader experiences in Packages List - [#9077](https://github.com/NuGet/Home/issues/9077) + * Accessibility issues in Screen Reader experiences related to "browse","install","update" Tabs - [#9078](https://github.com/NuGet/Home/issues/9078) + * Narrator does not announce "Blank","No Dependencies","nuget.org","MIT" link label [#9157](https://github.com/NuGet/Home/issues/9157) + +* Support for surfacing self-contained icons in Visual Studio package manager UI for packages hosted on local feeds - [#8189](https://github.com/NuGet/Home/issues/8189) + +* Significantly improved no-op restore performance using `RestoreUseStaticGraphEvaluation` which speeds up evaluations by calling MSBuild Static Graph APIs - [8791](https://github.com/NuGet/Home/issues/8791) + +* Improved dotnet.exe reliability with cross-platform authentication plugins + * dotnet restore failing with TaskCanceledException - [#7842](https://github.com/NuGet/Home/issues/7842) + * Plugin: "A task was cancelled" - problem with ADO authentication due to this. - [#8528](https://github.com/NuGet/Home/issues/8528) + +* add `dotnet nuget source` command - [#4126](https://github.com/NuGet/Home/issues/4126) + +* Suport for `--skip-duplicate` using dotnet nuget push - [#8778](https://github.com/NuGet/Home/issues/8778) + +* Support `packages.config` with msbuild /restore - [#8506](https://github.com/NuGet/Home/issues/8506) + +### Issues fixed in this release + +**Bugs** + +* Rework Self-Updater with V3 Apis - [#4197](https://github.com/NuGet/Home/issues/4197) + +* Wrong package dependency version If package dependency version is set to '*' - [#6697](https://github.com/NuGet/Home/issues/6697) + +* ErrorUnsafePackageEntry error message is not pointing to source of problem - [#7505](https://github.com/NuGet/Home/issues/7505) + +* Lock file is not honored in "*" scenarios - [#8073](https://github.com/NuGet/Home/issues/8073) + +* NuGet.exe does not resolve to the latest version of a package when using * in PackageReference (MSBuild/Dotnet/VS restore do) - [#8432](https://github.com/NuGet/Home/issues/8432) + +* dotnet list package with multi targeting WPF project - [#8463](https://github.com/NuGet/Home/issues/8463) + +* Improve ConcurrencyUtilities (reduce CPU usage) - [#8653](https://github.com/NuGet/Home/issues/8653) + +* DG Spec for unloaded project scenarios should not be written in preview restores - [#8793](https://github.com/NuGet/Home/issues/8793) + +* The Visual Studio NuGet packages (RestoreManagerPackage) needs to auto load on solution build events - [#8796](https://github.com/NuGet/Home/issues/8796) + +* Deadlock in VSSettings init - [#8842](https://github.com/NuGet/Home/issues/8842) + +* VisualStudio ToolBox is not populated from a NuGet package if a project is placed in a solution folder - [#8868](https://github.com/NuGet/Home/issues/8868) + +* VS: solution restore perpetually fails due to race condition - [#8881](https://github.com/NuGet/Home/issues/8881) + +* Constant "loading.." on installed tab, and "searching \.." on updates tab - [#8890](https://github.com/NuGet/Home/issues/8890) + +* Missing Embedded Icons in VS PM UI after cache expires - [#9069](https://github.com/NuGet/Home/issues/9069) + +* FireAndForget PM UI startup - [#9112](https://github.com/NuGet/Home/issues/9112) + +* Restore: IncludeExcludeFiles.Equals(...) implementation is incorrect - [#9167](https://github.com/NuGet/Home/issues/9167) + +* Restore: PackageSpec.Clone() creates unequal clone - [#9211](https://github.com/NuGet/Home/issues/9211) + +* Error list shown although "Always show Error List if build finishes with errors" is not checked - [#8190](https://github.com/NuGet/Home/issues/8190) + +* Static Graph restore should not pass empty SolutionPath - [#9061](https://github.com/NuGet/Home/issues/9061) + +* Restore: closure computed for each project 4 times - [#9042](https://github.com/NuGet/Home/issues/9042) + +* Restore: DependencyGraphSpec.Load(...) does not need JObject - [#9040](https://github.com/NuGet/Home/issues/9040) + +* Restore: large strings created on large object heap (LOH) - [#9031](https://github.com/NuGet/Home/issues/9031) + +* Custom nuget.exe on newer mono might break due to the MSBuild SDK Resolver - [8848](https://github.com/NuGet/Home/issues/8848) + +* restore fails when nuget.dgspec.json is "used by another process" - [8692](https://github.com/NuGet/Home/issues/8692) + +**DCRs** + +* Logic in _GetRestoreProjectStyle should be in a task - [#8804](https://github.com/NuGet/Home/issues/8804) + +* Add deprecation information by default on the installed tab - [#8541](https://github.com/NuGet/Home/issues/8541) + +**[List of all issues fixed in this release - 5.5](https://app.zenhub.com/workspaces/nuget-client-team-55aec9a240305cf007585881/reports/release?release=5e0e5fbd021f7aa0ec95db18)** diff --git a/docs/release-notes/NuGet-5.6.md b/docs/release-notes/NuGet-5.6.md new file mode 100644 index 000000000..696fb3493 --- /dev/null +++ b/docs/release-notes/NuGet-5.6.md @@ -0,0 +1,76 @@ +--- +title: NuGet 5.6 Release Notes +description: Release notes for NuGet 5.6 including new features, bug fixes, and DCRs. +author: nkolev92 +ms.author: nikolev +ms.date: 05/19/2020 +ms.topic: release-notes +--- + +# NuGet 5.6 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version| Available in .NET SDK(s)| +|:---|:---|:---| +| [**5.6.0**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.6](https://visualstudio.microsoft.com/downloads/) | [3.1.300](https://dotnet.microsoft.com/download/dotnet-core/3.1)1 | + +1Installed with Visual Studio 2019 with .NET Core workload + +## Summary: What's New in 5.6 + +* Support prerelease packages with floating versions. `Version="*-*"`, `Version="1.*-*"`, and similar float to latest versions, including prerelease versions, within specified range - [#912](https://github.com/NuGet/Home/issues/912) + +### Issues fixed in this release + +**Bugs:** + +* `nuget push *.nupkg` fails when snupkg does not exist - [#8148](https://github.com/NuGet/Home/issues/8148) + +* Pack, and several other code paths, fail dependent on locale. Use RegexOptions.CultureInvariant - [#8246](https://github.com/NuGet/Home/issues/8246) + +* Perf: DG Spec for unloaded project scenarios should not be written in preview restores - [#8793](https://github.com/NuGet/Home/issues/8793) + +* Restore: Improve performance by caching solution dependency graph spec - [#9201](https://github.com/NuGet/Home/issues/9201) + +* PM UI doesn't work for SDK style projects after installing a package with PM Console - [#9203](https://github.com/NuGet/Home/issues/9203) + +* Embedded icon can’t be shown in PM UI with local package feed - depending on / vs \ - [#9225](https://github.com/NuGet/Home/issues/9225) + +* NuGetVersion.TryParseStrict() should return false if it fails to parse - [#9255](https://github.com/NuGet/Home/issues/9255) + +* `nuget.exe push` help for `-source`, should suggest usage of source name, not source URL - [#9265](https://github.com/NuGet/Home/issues/9265) + +* `dotnet nuget add package SourceUri` creates bad default package source name - [#9277](https://github.com/NuGet/Home/issues/9277) + +* Screen reader doesn't announce "Searching..." message when switching tabs - [#9307](https://github.com/NuGet/Home/issues/9307) + +* Accessibility: Focus-rectangle color is not accessible PM UI tabs in dark theme - [#9336](https://github.com/NuGet/Home/issues/9336) + +* nuget.exe 5.5 fails to restore with MSBuild 14 or below - [#9458](https://github.com/NuGet/Home/issues/9458) + +* Don't log millisecond times in restore messages - [#8977](https://github.com/NuGet/Home/issues/8977) + +* Make IOutputConsole async - [#9268](https://github.com/NuGet/Home/issues/9268) + +* MSBuild version picking works poorly on some non-english cultures - [#9322](https://github.com/NuGet/Home/issues/9322) + +* Missing format default on `dotnet nuget list source` - [#9337](https://github.com/NuGet/Home/issues/9337) + +* Perf: RestoreOperationLogger has unnecessary thread affinity - [#9288](https://github.com/NuGet/Home/issues/9288) + +* Automated creation of docs for `dotnet nuget` commands - [#9146](https://github.com/NuGet/Home/issues/9146) + +* Default verbosity should not report each project's noop restore - [#8792](https://github.com/NuGet/Home/issues/8792) + +* Support `-DependencyVersion` parameter for `NuGet.exe update`, similar to install command - [#7694](https://github.com/NuGet/Home/issues/7694) + + +**DCRs:** + +* Add initial support for net5.0 target framework - [#9584](https://github.com/NuGet/Home/issues/9584) + +* Sort packages by ID in the Updates tab of the PM UI - [#9278](https://github.com/NuGet/Home/issues/9278) + + +**[List of all issues fixed in this release - 5.6](https://app.zenhub.com/workspaces/nuget-client-team-55aec9a240305cf007585881/reports/release?release=5e3b2080c4b30708e48bf9f3)** diff --git a/docs/release-notes/NuGet-5.7.md b/docs/release-notes/NuGet-5.7.md new file mode 100644 index 000000000..ee702a83b --- /dev/null +++ b/docs/release-notes/NuGet-5.7.md @@ -0,0 +1,127 @@ +--- +title: NuGet 5.7 Release Notes +description: Release notes for NuGet 5.7 including new features, bug fixes, and DCRs. +author: nkolev92 +ms.author: nikolev +ms.date: 8/14/2020 +ms.topic: release-notes +--- + +# NuGet 5.7 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**5.7.0**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.7](https://visualstudio.microsoft.com/downloads/) | [3.1.401](https://dotnet.microsoft.com/download/dotnet-core/3.1)1 | +| [**5.7.1**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.7](https://visualstudio.microsoft.com/downloads/) | [3.1.408](https://dotnet.microsoft.com/download/dotnet-core/3.1)1 | +| [**5.7.2**](https://nuget.org/downloads) | N/A | [3.1.420](https://dotnet.microsoft.com/download/dotnet-core/3.1)1 | +| [**5.7.3**](https://nuget.org/downloads) | N/A | [3.1.424](https://dotnet.microsoft.com/download/dotnet-core/3.1)1 | + +1 Installed with Visual Studio 2019 with .NET Core workload + +## Summary: What's New in 5.7.3 + +* [Security]: Microsoft Security Advisory CVE-2022-41032 | .NET Elevation of Privilege Vulnerability - [#12149](https://github.com/NuGet/Home/issues/12149) + +## Summary: What's New in 5.7.2 + +* [Security]: Microsoft Security Advisory CVE-2022-30184 | .NET Information Disclosure Vulnerability - [#11883](https://github.com/NuGet/Home/issues/11883) + +## Summary: What's New in 5.7 + +### Features added in this release + +* Added extern alias support for NuGet package references - [#4989](https://github.com/NuGet/Home/issues/4989) + +* Made switching between Installed and Updates tabs faster by allowing them to share a data source and reducing resfreshing - [#8294](https://github.com/NuGet/Home/issues/8294) + +* Make restore faster - speed up evaluations by calling MSBuild Static Graph apis (dotnet.exe) - [#9644](https://github.com/NuGet/Home/issues/9644) + +* Added Visual Studio partial restore for PackageReference projects (no-op++) - [#9513](https://github.com/NuGet/Home/issues/9513) + +* Visual Studio Package Manager UI will crash less often when searching misbehaving package sources that return more than the requested number of results per HTTP request. - [#8478](https://github.com/NuGet/Home/issues/8478) + +* Added integration of PackageVersion information for non-SDK style projects in VS restore - [#9236](https://github.com/NuGet/Home/issues/9236) + +* Added support for nuget.exe update `-self -Source` https://feed - [#1783](https://github.com/NuGet/Home/issues/1783) + +* Added support for multiple config files in %APPDATA%\NuGet directory - [#9394](https://github.com/NuGet/Home/issues/9394) + +* DeterministicSourcePaths now takes NuGet source packages into account - [#9431](https://github.com/NuGet/Home/issues/9431) + +* Added INuGetProjectService.GetInstalledPackagesAsync extensibility API - [#9702](https://github.com/NuGet/Home/issues/9702) + +* Added interop API to enumerate fallback folders without requiring a solution/project - [#9395](https://github.com/NuGet/Home/issues/9395) + +* Added `latest` option for `-MSBuildVersion` - [#8808](https://github.com/NuGet/Home/issues/8808) + +### Issues fixed in this release + +**Bugs:** + +* In a dotnet CLI restore, when launching credential plugins, try the dotnet CLI on the system path if the `DOTNET_HOST_PATH` environment variable is not defined. - [#7438](https://github.com/NuGet/Home/issues/7438) + +* nuget.exe spec generates a copyright tag with hard-coded text of Copyright YYYY Instead of `$copyright$` - [#8696](https://github.com/NuGet/Home/issues/8696) + +* NuGet.exe throws exception 'authors required' during pack of a csproj ignoring placeholders and assemblyinfo attributes if the assembly name is changed - [#4234](https://github.com/NuGet/Home/issues/4234) + +* HttpRequestMessage gets reused multiple times which is not supported with the SocketHttpHandler - [#8661](https://github.com/NuGet/Home/issues/8661) + +* NuGet.Indexing 5.6.0 preview 3 and later use a different public key token - [#9481](https://github.com/NuGet/Home/issues/9481) + +* Honor TreatWarningsAsErrors during NuGet Package creation - [#7404](https://github.com/NuGet/Home/issues/7404) + +* [CPVM] Spurious package downgrades for multiple p2p projects - [#9549](https://github.com/NuGet/Home/issues/9549) + +* The “Browse” tab is not aligned left with search box - [#9559](https://github.com/NuGet/Home/issues/9559) + +* The installed version is inconsistent with the embedded icon in the solution level PM UI for one package id with multiple versions installed - [#9321](https://github.com/NuGet/Home/issues/9321) + +* Leak: PartCreationPolicy(CreationPolicy.NonShared) NuGet.SolutionRestoreManager.RestoreOperationLogger - [#9595](https://github.com/NuGet/Home/issues/9595) + +* Avoid reading the assets file in no-op restores - [#9693](https://github.com/NuGet/Home/issues/9693) + +* NuGet.Protocol does not support getting a version's download count from search - [#9086](https://github.com/NuGet/Home/issues/9086) + +* Improve memory performance of PackageMetadataResourceV3 by reducing the JObject dependencies - [#9719](https://github.com/NuGet/Home/issues/9719) + +**Design change requests:** + +* Suppressed the `` element when it is redundant - [#5134](https://github.com/NuGet/Home/issues/5134) + +* Log IntervalTrackers as ETW events - [#9593](https://github.com/NuGet/Home/issues/9593) + +* Added an informational message on restore to inform CPVM users that the feature is in preview - [#9340](https://github.com/NuGet/Home/issues/9340) + +* Populate Solution Explorer package/project transitive dependencies from assets file - [#9580](https://github.com/NuGet/Home/issues/9580) + +* Installed packages tab shouldn't paginate the packages list - [#6995](https://github.com/NuGet/Home/issues/6995) + +**[List of all issues fixed in this release - 5.7](https://app.zenhub.com/workspaces/nuget-client-team-55aec9a240305cf007585881/reports/release?release=5ea77f51ab1a972297db2e92)** + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +|Who|PRs|Issues| +|----|----|----| +|[campersau](https://github.com/campersau)|[3433](https://github.com/NuGet/NuGet.Client/pull/3433), [3120](https://github.com/NuGet/NuGet.Client/pull/3120)|NuGet.Protocol does not support getting a version's download count from search - [#9086](https://github.com/NuGet/Home/issues/9086)
    HttpRequestMessage gets reused multiple times which is not supported with the SocketHttpHandler - [#8661](https://github.com/NuGet/Home/issues/8661)| +|[Joseph Musser (jnm2)](https://github.com/jnm2)|[3241](https://github.com/NuGet/NuGet.Client/pull/3241)|Suppressed the `` element when it is redundant - [#5134](https://github.com/NuGet/Home/issues/5134)| +|[Volodymyr Shkolka (BlackGad)](https://github.com/BlackGad)|[3273](https://github.com/NuGet/NuGet.Client/pull/3273)|NuGet cannot restore from HTTPS sources that require Client Certificates - [#5773](https://github.com/NuGet/Home/issues/5773)| +|[Marius Ungureanu (Therzok)](https://github.com/Therzok)|[3357](https://github.com/NuGet/NuGet.Client/pull/3357)|HttpSourceAuthenticationHandler SemaphoreSlim future proofing - [#9463](https://github.com/NuGet/Home/issues/9463)| +|[Sunner (SuNNjek)](https://github.com/SuNNjek)|[3088](https://github.com/NuGet/NuGet.Client/pull/3088)|nuget.exe spec generates a copyright tag with hard-coded text of Copyright YYYY Instead of `$copyright$` - [#8696](https://github.com/NuGet/Home/issues/8696)| +|[Olivier Spinelli (olivier-spinelli)](https://github.com/olivier-spinelli)|[3335](https://github.com/NuGet/NuGet.Client/pull/3335)|In a dotnet CLI restore, when launching credential plugins, try the dotnet CLI on the system path if the `DOTNET_HOST_PATH` environment variable is not defined. - [#7438](https://github.com/NuGet/Home/issues/7438)| +|[goyzhang](https://github.com/goyzhang)|[3370](https://github.com/NuGet/NuGet.Client/pull/3370)|Added `latest` option for `-MSBuildVersion` - [#8808](https://github.com/NuGet/Home/issues/8808)| + +## Summary: What's New in 5.7.1 + +* Extend the .nupkg.metadata file to include the installation source - [#10354](https://github.com/NuGet/Home/issues/10354) + +* Log package contenthash during restore logging (during extraction) - [#10384](https://github.com/NuGet/Home/issues/10384) + +* When restoring at normal verbosity, log which source a package is being restored from - [#10461](https://github.com/NuGet/Home/issues/10461) + +**[List of all issues fixed in this release - 5.7.1](https://app.zenhub.com/workspaces/nuget-client-team-55aec9a240305cf007585881/reports/release?release=6075f5724f84579cc29a79ee)** + +**[List of commits in this release - 5.7.1](https://github.com/NuGet/NuGet.Client/compare/80512866a2c127e52ce3e86fd803fff77e9b9b52...5.7.1.4)** diff --git a/docs/release-notes/NuGet-5.8.md b/docs/release-notes/NuGet-5.8.md new file mode 100644 index 000000000..837149983 --- /dev/null +++ b/docs/release-notes/NuGet-5.8.md @@ -0,0 +1,159 @@ +--- +title: NuGet 5.8 Release Notes +description: Release notes for NuGet 5.8 including new features, bug fixes, and DCRs. +author: JonDouglas +ms.author: jodou +ms.date: 11/9/2020 +ms.topic: release-notes +--- + +# NuGet 5.8 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**5.8**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.8](https://visualstudio.microsoft.com/downloads/) | [5.0](https://dotnet.microsoft.com/download/dotnet-core/5.0)1 | +| [**5.8.1**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.8.4](https://visualstudio.microsoft.com/downloads/) | | + +1 Installed with Visual Studio 2019 with .NET Core workload + +> [!NOTE] +> Visual Studio 16.8, MSBuild 16.8, and .NET 5.0 require NuGet.exe 5.8 or later. + + +## Summary: What's New in 5.8 +🎉 **This is the first release to offer full authoring and restoring support for NuGet packages targeting .NET 5.0** 🎉 + +* Speed up nupkg extraction using mmap/CreateFileMapping - [#9807](https://github.com/NuGet/Home/issues/9807) + +* Display package vulnerability details in the Package Manager UI package details pane - [#9850](https://github.com/NuGet/Home/issues/9850) + +* Verify signed NuGet packages with the new [`dotnet nuget verify`](/dotnet/core/tools/dotnet-nuget-verify) command - [#8051](https://github.com/NuGet/Home/issues/8051) + +* [`dotnet add package`](/dotnet/core/tools/dotnet-add-package#:~:text=dotnet%20add%20package%201%20Name%202%20Synopsis%203,when%20targeting%20a%20specific%20framework.%20...%206%20Examples) supports `--prerelease` option to add the latest version of a package, including prerelease versions - [#4699](https://github.com/NuGet/Home/issues/4699) + +* Search for packages in the CLI with [`nuget.exe search`](../reference/cli-reference/cli-ref-search.md) command - [#9704](https://github.com/NuGet/Home/issues/9704) + +* [`dotnet list package`](/dotnet/core/tools/dotnet-list-package) command supports `--verbosity` option - [#9600](https://github.com/NuGet/Home/issues/9600) + +* Enable fast No-Op restore optimization for csproj-style, PackageReference-based projects in Visual Studio - [#9565](https://github.com/NuGet/Home/issues/9565) + +* Solution level Package Manager UI operations such as package installs and updates are up to 10x faster - [#6010](https://github.com/NuGet/Home/issues/6010) + +* Several other NuGet performance improvements in Visual Studio - [#9982](https://github.com/NuGet/Home/issues/9982), [#9984](https://github.com/NuGet/Home/issues/9984), [#10052](https://github.com/NuGet/Home/issues/10052), [#9903](https://github.com/NuGet/Home/issues/9903) + + +### Issues fixed in this release + +**DCRs:** + +* .NET 5.0 TFM: Framework Precedence Rules - [#9436](https://github.com/NuGet/Home/issues/9436) + +* NuGet should not infer dots platform version when parsing TargetFramework - [#9842](https://github.com/NuGet/Home/issues/9842) + +* Use TargetFrameworkMoniker & TargetPlatformMoniker to infer the frameworks instead of using individual TFI, TFV, TPI, TPV properties - [#9895](https://github.com/NuGet/Home/issues/9895) + +* Update `GetReferenceNearestTargetFrameworkTask()` to support target frameworks with platforms (such as net5.0-windows) - [#9894](https://github.com/NuGet/Home/issues/9894) + +* .NET 5.0 Visual Studio APIs - [#9650](https://github.com/NuGet/Home/issues/9650) + +* Package Manager UI: Consolidate or Update packages operations should not be blocked due to errors (Package Downgrade, etc.) - [#9224](https://github.com/NuGet/Home/issues/9224) + +* NuGet features should light up for projects that have the capability; "PackageReferences" - [#9957](https://github.com/NuGet/Home/issues/9957) + +* Suppress No-Op Restore messages in Visual Studio - [#6384](https://github.com/NuGet/Home/issues/6384) + +**Bugs:** + +* OutputWindowTextWriter constructor should not be called on background thread - [#9764](https://github.com/NuGet/Home/issues/9764) + +* Restore signed packages on Big Endian CPUs - [#9547](https://github.com/NuGet/Home/issues/9547) + +* OutputConsoleLogger should not call affinitized methods in MEF constructors - [#9591](https://github.com/NuGet/Home/issues/9591) + +* Bug in NuGet.CommandLine.Console `PrintJustified()` method - [#9737](https://github.com/NuGet/Home/issues/9737) + +* Package Manager UI memory leak when package metadata is garbage collected due to a bad binding - [#9757](https://github.com/NuGet/Home/issues/9757) + +* [Signing] No warning is showed in Error List when installing a signed package with packages.config format in Package Manager UI - [#9798](https://github.com/NuGet/Home/issues/9798) + +* NuGet.CommandLine.XPlat should not have public APIs - [#9821](https://github.com/NuGet/Home/issues/9821) + +* Reduce resource contention at Solution Load time caused by blocking a threaded-pool thread with `BlockingCollection.Take()` - [#9822](https://github.com/NuGet/Home/issues/9822) + +* In command line restore, with multi targeted projects, NuGet should read the target framework related information from the inner build - [#9869](https://github.com/NuGet/Home/issues/9869) + +* Read Runtime Identifier graph through TargetFrameworkInformation item - [#9874](https://github.com/NuGet/Home/issues/9874) + +* Static graph restore is inconsistent with regards to CrossTargeting property in compared to Visual Studio and regular MSBuild evaluation restore - [#9881](https://github.com/NuGet/Home/issues/9881) + +* In static graph restore, with multi targeted projects, NuGet should read the target framework related information from the inner build. - [#9870](https://github.com/NuGet/Home/issues/9870) + +* Allow `net5.0-platform` projects to be loaded and restored in Visual Studio - [#9863](https://github.com/NuGet/Home/issues/9863) + +* Display the resolved version in the Package Manager UI - [#9826](https://github.com/NuGet/Home/issues/9826) + +* Package Manager UI: Solution Explorer is not showing all NuGet package dependencies - [#9898](https://github.com/NuGet/Home/issues/9898) + +* Update the SPDX license list - [#9946](https://github.com/NuGet/Home/issues/9946) + +* VS 2019 crashes after opening Manage NuGet Packages: icon causes unhandled exception in image conversio - [#9696](https://github.com/NuGet/Home/issues/9696) + +* NuGet.Packaging.Extraction needs ilmerge to exclude Newtonsoft.Json - [#9966](https://github.com/NuGet/Home/issues/9966) + +* Packing with ContinuePackingAfterGeneratingNuspec=false should not fail when there are no errors - [#9786](https://github.com/NuGet/Home/issues/9786) + +* Package Manager UI: Icons aren't inverting colors properly - [#10017](https://github.com/NuGet/Home/issues/10017) + +* Incorrect project counts for Up-To-Date and No-Op projects at Restore - [#10026](https://github.com/NuGet/Home/issues/10026) + +* Using `/p:RestoreUseStaticGraphEvaluation=true` Results in Value Cannot Be Null - [#9280](https://github.com/NuGet/Home/issues/9280) + +* `dotnet pack` mistakenly uses alias for WPF Library projects - [#10020](https://github.com/NuGet/Home/issues/10020) + +* Package Manager UI: NullReferenceException when signature validation fails - [#10042](https://github.com/NuGet/Home/issues/10042) + +* Codespaces: do not use `object` type for project metadata values - [#10055](https://github.com/NuGet/Home/issues/10055) + +* Codespaces: saving package sources in tools options will overwrite credentials - [#9711](https://github.com/NuGet/Home/issues/9711) + + +**[List of all issues fixed in this release - 5.8](https://app.zenhub.com/workspaces/nuget-client-team-55aec9a240305cf007585881/reports/release?release=5f03519b777e78b4ffb2edeb)** + +**[List of issues in this release - 5.8](https://github.com/NuGet/NuGet.Client/compare/5.7.0.6726...5.8.0.6930)** + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +|Who|PRs|Issues| +|----|----|----| +[omajid](https://github.com/omajid) | [3437](https://github.com/NuGet/NuGet.Client/pull/3437) | Typo in error message. "administator" instead of "administrator" - [#9662](https://github.com/NuGet/Home/issues/9662) +[odalet](https://github.com/odalet) | [3341](https://github.com/NuGet/NuGet.Client/pull/3341) | NuGet Pack with invalid AssemblyInformationalVersion reports "description is required" - [#5548](https://github.com/NuGet/Home/issues/5548) +[campersau](https://github.com/campersau) | [3501](https://github.com/NuGet/NuGet.Client/pull/3501) | `RepositoryMetadata.Equals()` does not account for Branch and Commit properties - [#9613](https://github.com/NuGet/Home/issues/9613) +[Youssef1313](https://github.com/Youssef1313) | [3599](https://github.com/NuGet/NuGet.Client/pull/3599) | Clicking NU code in Visual Studio Error List window should go to [Errors and warnings](/nuget/reference/errors-and-warnings/) - [#9934](https://github.com/NuGet/Home/issues/9934) +[ChrisMaddock](https://github.com/ChrisMaddock) | [3624](https://github.com/NuGet/NuGet.Client/pull/3624) | Use 'https://' when adding new package source through Visual Studio options - [#9974](https://github.com/NuGet/Home/issues/9974) +[Therzok](https://github.com/Therzok) | [3636](https://github.com/NuGet/NuGet.Client/pull/3636) | `RuntimeEnvironmentHelper.IsRunningOnVisualStudio` performance issue on Mono - [#9989](https://github.com/NuGet/Home/issues/9989) +[thomaslevesque](https://github.com/thomaslevesque) | [3442](https://github.com/NuGet/NuGet.Client/pull/3442) | Add a TypeConverter for the SemanticVersion class - [#9125](https://github.com/NuGet/Home/issues/9125) + +## Summary: What's New in 5.8.1 + +* packages.config package.lock.json uses an incorrect target framework in 5.8 - [#10257](https://github.com/NuGet/Home/issues/10257) + +* 5.8 + 16.8 Cannot resolve transitive project dependencies when mixing PackageReference and packages.config - [#10326](https://github.com/NuGet/Home/issues/10326) + +**[List of all issues fixed in this release - 5.8.1](https://app.zenhub.com/workspaces/nuget-client-team-55aec9a240305cf007585881/reports/release?release=5ff7aeae16150e3b19910391)** + +**[List of commits in this release - 5.8.1](https://github.com/NuGet/NuGet.Client/compare/5.8.0.6930...5.8.1.7021)** + +## Feedback welcome + +Your feedback is important to us. If there are any problems with this release, check our +[GitHub Issues](https://github.com/NuGet/Home/issues) and +[Visual Studio Developer Community](https://developercommunity.visualstudio.com/) +for existing issues. For new issues within NuGet, please report a +[GitHub Issue](https://github.com/NuGet/Home/issues/new). +For general NuGet experience issues, let us know via the +[Report a Problem](/visualstudio/ide/how-to-report-a-problem-with-visual-studio) +option found in your favorite IDE under **Help > Report a Problem**. diff --git a/docs/release-notes/NuGet-5.9.md b/docs/release-notes/NuGet-5.9.md new file mode 100644 index 000000000..f10019cf8 --- /dev/null +++ b/docs/release-notes/NuGet-5.9.md @@ -0,0 +1,248 @@ +--- +title: NuGet 5.9 Release Notes +description: Release notes for NuGet 5.9 including new features, bug fixes, and DCRs. +author: erdembayar +ms.author: eryondon +ms.date: 3/11/2021 +ms.topic: release-notes +--- + +# NuGet 5.9 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**5.9.0**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.9](https://visualstudio.microsoft.com/downloads/) | [5.0.200](https://dotnet.microsoft.com/download/dotnet-core/5.0)1 | +| [**5.9.1**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.9](https://visualstudio.microsoft.com/downloads/) | [5.0.202](https://dotnet.microsoft.com/download/dotnet-core/5.0)1 | +| [**5.9.2**](https://nuget.org/downloads) | [Visual Studio 2019 version 16.9.22](https://visualstudio.microsoft.com/downloads/) | N/A | +| [**5.9.3**](https://nuget.org/downloads) | N/A | N/A | + +1 Installed with Visual Studio 2019 with .NET Core workload + +> [!NOTE] +> Visual Studio 16.9, MSBuild 16.9, and .NET 5.0.200+ requires NuGet.exe 5.9 or later. + +## Summary: What's New in 5.9.3 + +* [Security]: Microsoft Security Advisory CVE-2022-41032 | .NET Elevation of Privilege Vulnerability - [#12149](https://github.com/NuGet/Home/issues/12149) + +## Summary: What's New in 5.9.2 + +* [Security]: Microsoft Security Advisory CVE-2022-30184 | .NET Information Disclosure Vulnerability - [#11883](https://github.com/NuGet/Home/issues/11883) + +## Summary: What's New in 5.9 + +* Add "Update" context menu item for package dependencies that launches Package Manager UI with preselected packages to update - [#10378](https://github.com/NuGet/Home/issues/10378) + + ![Right-click package "Update" experience](media/releasenotes-59-update.png) + +* Show the requested version (including floating version or version range request) in the "Version" column of the project list in the solution level Package Manager UI - [#9827](https://github.com/NuGet/Home/issues/9827) + + ![Requested version in solution level Package Manager UI](media/releasenotes-59-requested-version.png) + +* IntelliCode package suggestions in the Package Manager UI Browse tab released as an A/B test - [#10053](https://github.com/NuGet/Home/issues/10053) + +* Extend the `.nupkg.metadata` file to include the installation source - [#10354](https://github.com/NuGet/Home/issues/10354) + +* Introduce a new msbuild property to exclude build output for specific TFMs during pack task - [#10396](https://github.com/NuGet/Home/issues/10396) + +### Issues fixed in this release + +**DCRs(Design Change Request):** + +* The down icon icon when the latest package version is installed is not intuitive. The old green tick was perfect - [#9789](https://github.com/NuGet/Home/issues/9789) + +* Nuget Debug verbosity should say where a package came from - [#3055](https://github.com/NuGet/Home/issues/3055) + +* NuGet pack should catch incorrect omitting of the dot in version numbers - [#9215](https://github.com/NuGet/Home/issues/9215) + +* [CPVM] Disable pinning of the central transitive dependencies - [#10132](https://github.com/NuGet/Home/issues/10132) + +* net5 TFM: produce error when missing TPV - [#9441](https://github.com/NuGet/Home/issues/9441) + +* Log package contenthash during restore logging (during extraction) - [#10384](https://github.com/NuGet/Home/issues/10384) + +* Implement a pre-registration mechanism for legacy PR projects that call restore at solution open - [#9986](https://github.com/NuGet/Home/issues/9986) + +* NuGet package recommender should work when more than one source is selected in package manager - [#10433](https://github.com/NuGet/Home/issues/10433) + +* When restoring at normal verbosity, log which source a package is being restored from - [#10461](https://github.com/NuGet/Home/issues/10461) + +**Bugs:** + +* INuGetPackageFileService - Fetch Images and embedded licenses for Codespaces-connected and standalone - [#10151](https://github.com/NuGet/Home/issues/10151) + +* VS OE: IProjectMetadataContextInfo missing formatter - [#10079](https://github.com/NuGet/Home/issues/10079) + +* [CPVM-Perf] Reduce the information written to centralTransitiveDependencyGroups - [#10002](https://github.com/NuGet/Home/issues/10002) + +* Restore operations that throw due to a project not being loaded are reported as `NoOp` in telemetry - [#9985](https://github.com/NuGet/Home/issues/9985) + +* Icons with certain color pallets causes PM UI to crash VS - [#10037](https://github.com/NuGet/Home/issues/10037) + +* [CPVM-Perf] Reduce the PackageSpec clone when adding the CPVM information - [#10003](https://github.com/NuGet/Home/issues/10003) + +* PM UI - asyncify icon loading - [#10009](https://github.com/NuGet/Home/issues/10009) + +* UI delay when loading icon URLs in PM UI - [#8505](https://github.com/NuGet/Home/issues/8505) + +* Thread affinity in BitmapSource and WPF UI threads - [#9161](https://github.com/NuGet/Home/issues/9161) + +* Warning for warning NU5128 when packastool with targetframework alias - [#10097](https://github.com/NuGet/Home/issues/10097) + +* OutputPath logic in Pack targets in a customized build doesn't work properly - [#9234](https://github.com/NuGet/Home/issues/9234) + +* VS OE: cache IServiceBroker instance on client - [#10141](https://github.com/NuGet/Home/issues/10141) + +* Make creating NuGetProjectActions for uninstall from PM UI a parallel operation - [#9956](https://github.com/NuGet/Home/issues/9956) + +* Performance: Reduce UIDelays in GetPackageSpecsAsync for Legacy projects and non PR projects - [#9953](https://github.com/NuGet/Home/issues/9953) + +* ``dotnet nuget push *.nupkg`` doesn't push more than one file - [#4393](https://github.com/NuGet/Home/issues/4393) + +* Output is wrapped at 80 characters on macOS when redirected - [#10198](https://github.com/NuGet/Home/issues/10198) + +* Restore fails with -Source \ - [#9406](https://github.com/NuGet/Home/issues/9406) + +* netcoreapp5.0-windows does not round trip and does not parse platform information - [#10177](https://github.com/NuGet/Home/issues/10177) + +* Custom CPS projects require AssemblyReferences project capability in order to restore. - [#8071](https://github.com/NuGet/Home/issues/8071) + +* License and icon file existence check should always use a case-sensitive comparison - [#9817](https://github.com/NuGet/Home/issues/9817) + +* DotnetCLiToolReference restores make it difficult to reason about no-op projects count/uptodateprojectscount - [#10038](https://github.com/NuGet/Home/issues/10038) + +* Hard to see the dash-line box of package format when navigating by tab through the “Choose NuGet Package Manager Format” dialog in Dark theme - [#9729](https://github.com/NuGet/Home/issues/9729) + +* Exclude transitive framework references from `CollectFrameworkReferences` - [#10314](https://github.com/NuGet/Home/issues/10314) + +* Comparer static properties should be idempotent - [#10339](https://github.com/NuGet/Home/issues/10339) + +* resolve internal contracts assembly loading (fix RPS or get exception) - [#9919](https://github.com/NuGet/Home/issues/9919) + +* Replace GetService with GetServiceAsync in NuGet.Clients, Part 1 - [#10362](https://github.com/NuGet/Home/issues/10362) + +* CLI installs should not install unlisted packages - [#7466](https://github.com/NuGet/Home/issues/7466) + +* Static msbuild graph restore - unnnecessary logging about MSBuildStartupDirectory - [#10335](https://github.com/NuGet/Home/issues/10335) + +* Project Dependencies of ProjectReferences marked as PrivateAssets should not be included in the lock file up to date check - [#8565](https://github.com/NuGet/Home/issues/8565) + +* SDK projects with bad data not showing restore errors in VS - [#10406](https://github.com/NuGet/Home/issues/10406) + +* NU1004 when restoring a solution that has mixed Legacy and netstandard2 projects from cmd line with LockedMode - [#9623](https://github.com/NuGet/Home/issues/9623) + +* Pack includes content brought in through dependency packages into the current project's package (SDK based projects only) - [#8867](https://github.com/NuGet/Home/issues/8867) + +* Add telemetry for NuGet's VS extensibility API faults - [#10062](https://github.com/NuGet/Home/issues/10062) + +* Add GenerateRestoreGraphFile in static graph restore to improve debugability. - [#10365](https://github.com/NuGet/Home/issues/10365) + +* Cannot open the NuGet Package manager - [#10336](https://github.com/NuGet/Home/issues/10336) + +* NVDA/Narrator is not reading "License" label for "Apache-2.0" link - [#10425](https://github.com/NuGet/Home/issues/10425) + +* The up to date status bar message is not great in VS - [#9402](https://github.com/NuGet/Home/issues/9402) + +* packages.config package.lock.json uses an incorrect target framework - [#10257](https://github.com/NuGet/Home/issues/10257) + +* Codespaces: fix telemetry from https://github.com/NuGet/NuGet.Client/pull/3786 - [#10439](https://github.com/NuGet/Home/issues/10439) + +* Error NU1004 disappears when building solution after enabling “RestoreLockedMode” - [#8973](https://github.com/NuGet/Home/issues/8973) + +* Tabbing through PMUI in the reverse should mirror forward direction - [#10234](https://github.com/NuGet/Home/issues/10234) + +* Debugging PMUI in Experimental Instance sometimes throws InvalidCastException from SolutionView to ProjectView - [#10416](https://github.com/NuGet/Home/issues/10416) + +* The default version is null after clicking a deprecated package in Browse tab - [#10380](https://github.com/NuGet/Home/issues/10380) + +* The NuGet manager in Visual Studio reloads when focus is regained - [#4176](https://github.com/NuGet/Home/issues/4176) + +* Remove IPackageSourceProvider2 and related types - [#10098](https://github.com/NuGet/Home/issues/10098) + +* Package 'NameOfPackage' is incompatible with 'all' frameworks in project - [#5127](https://github.com/NuGet/Home/issues/5127) + +* CreateVersionsAsync does unnecessary NuGetVersion Compares - [#10436](https://github.com/NuGet/Home/issues/10436) + +* NuGet.Client should replace using of ManagedImageMonikers with KnownMonikers - [#9977](https://github.com/NuGet/Home/issues/9977) + +* The deprecated icon overlaps with the version of the deprecated package in Browse tab - [#10452](https://github.com/NuGet/Home/issues/10452) + +* PackageReference NU1604 error handling is different across VS and command line (Restore & Package Manager UI) - [#9289](https://github.com/NuGet/Home/issues/9289) + +* Codespaces: necessary formatters not registered - [#10467](https://github.com/NuGet/Home/issues/10467) + +* Remove net45 as as a target framework from NuGet.Frameworks - [#10470](https://github.com/NuGet/Home/issues/10470) + +* Implementation - Add new telemetries to track events related to PMC and Powershell usage. - [#10142](https://github.com/NuGet/Home/issues/10142) + +* Only one package shows in the Preview Changes window when there are multiple packages available to update in the Package Manager UI - [#10483](https://github.com/NuGet/Home/issues/10483) + +* Empty frameworkReferences groups should be generated when packing multitargeted projects - [#10218](https://github.com/NuGet/Home/issues/10218) + +* Hard to see the check-box of package in ‘Updates’ Tab is focused with a dash-line box when navigating through Tab in Blue/Blue (Extra Contrast)/Light themes - [#8963](https://github.com/NuGet/Home/issues/8963) + +* Updates Tab checkboxes do not work well with screen-readers - [#10449](https://github.com/NuGet/Home/issues/10449) + +* Updating in PMUI causes Object reference not set to an instance of an object - [#9882](https://github.com/NuGet/Home/issues/9882) + +* Implementation - Add new telemetries to track events related to PMC and Powershell usage follow up. - [#10478](https://github.com/NuGet/Home/issues/10478) + +* Copy-paste error in V2FeedPackageInfo - [#10480](https://github.com/NuGet/Home/issues/10480) + +* NuGetPackageFileService fix - use using for disposable memorystream - [#10503](https://github.com/NuGet/Home/issues/10503) + +**[List of all issues fixed in this release - 5.9.0](https://app.zenhub.com/workspaces/nuget-client-team-55aec9a240305cf007585881/reports/release?release=5f6be8c10485c0236b7ef889)** + +**[List of commits in this release - 5.9.0](https://github.com/NuGet/NuGet.Client/compare/5.8.1.7021...5.9.0.7134)** + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +|Who|PRs|Issues| +|----|----|----| +[omajid](https://github.com/omajid) | [3865](https://github.com/NuGet/NuGet.Client/pull/3865) | Copy-paste error in V2FeedPackageInfo - [#10480](https://github.com/NuGet/Home/issues/10480) +[marcin-krystianc](https://github.com/marcin-krystianc) | [3812](https://github.com/NuGet/NuGet.Client/pull/3812) | Missing tests for the case where packages are referenced with PrivateAssets="All" attribute - [#10397](https://github.com/NuGet/Home/issues/10397) +[marcin-krystianc](https://github.com/marcin-krystianc) | [3739](https://github.com/NuGet/NuGet.Client/pull/3739) | Adding support for pushing multiple packages - [#4393](https://github.com/NuGet/Home/issues/4393) +[marcin-krystianc](https://github.com/marcin-krystianc) | [3723](https://github.com/NuGet/NuGet.Client/pull/3723) | Build of NuGet libraries is broken when assembly signing is disabled - [#10173](https://github.com/NuGet/Home/issues/10173) +[kant2002](https://github.com/kant2002) | [3807](https://github.com/NuGet/NuGet.Client/pull/3807) | Clean-up the contributing docs - [#10399](https://github.com/NuGet/Home/issues/10399) +[PathogenDavid](https://github.com/PathogenDavid) | [3754](https://github.com/NuGet/NuGet.Client/pull/3754) | License and icon file existence check should always use a case-sensitive comparison - [#9817](https://github.com/NuGet/Home/issues/9817) +[campersau](https://github.com/campersau) | [3677](https://github.com/NuGet/NuGet.Client/pull/3677) | Use BitmapCreateOptions.IgnoreColorProfile to workaround WPF issue when using DecodePixelWidth - [#10037](https://github.com/NuGet/Home/issues/10037) +[bjorkstromm](https://github.com/bjorkstromm) | [3697](https://github.com/NuGet/NuGet.Client/pull/3697) | Windows SDK 10 link is broken in NuGet.Client Contribution guide - [#10099](https://github.com/NuGet/Home/issues/10099) +[bjorkstromm](https://github.com/bjorkstromm) | [3696](https://github.com/NuGet/NuGet.Client/pull/3696) | Relative links are broken in NuGet.Client debugging guide - [#10100](https://github.com/NuGet/Home/issues/10100) +[Nirmal4G](https://github.com/Nirmal4G) | [3637](https://github.com/NuGet/NuGet.Client/pull/3637) | Improve test fixtures and related code - [#9996](https://github.com/NuGet/Home/issues/9996) +[rolfbjarne](https://github.com/rolfbjarne) | [3743](https://github.com/NuGet/NuGet.Client/pull/3743) | Output is wrapped at 80 characters on macOS when redirected - [#10198](https://github.com/NuGet/Home/issues/10198) +[xen2](https://github.com/xen2) | [2861](https://github.com/NuGet/NuGet.Client/pull/2861) | Make NuGet.PackageManagement available as a .NET Standard package - [#6150](https://github.com/NuGet/Home/issues/6150) +[Anipik](https://github.com/Anipik) | [3810](https://github.com/NuGet/NuGet.Client/pull/3810) | Introduce a new msbuild property to exclude build output for specific tfms during pack task - [#10396](https://github.com/NuGet/Home/issues/10396) + +## Summary: What's New in 5.9.1 + +* "dotnet nuget remove source nuget.org" doesn't work the first time - [#10745](https://github.com/NuGet/Home/issues/10745) +* Make default validation disabled on Linux, but enabled by default on Windows - [#10713](https://github.com/NuGet/Home/issues/10713) + +**[List of all issues fixed in this release - 5.9.1](https://app.zenhub.com/workspaces/nuget-client-team-55aec9a240305cf007585881/reports/release?release=6075f42efd068017639b4036)** + +**[List of commits in this release - 5.9.1](https://github.com/NuGet/NuGet.Client/compare/5.9.0.7134...5.9.1.8)** + +## Known issues + +### nuget 5.9 pack raises `Null Reference` exception. - [#10685](https://github.com/NuGet/Home/issues/10685) + +#### Issue +When tring to `pack` using a `.nuspec` file, `NuGet 5.9` version raises a `null reference` exception if [explicit assembly references](../reference/nuspec.md#explicit-assembly-references) are specified without adding any `reference groups` for projects that target `multiple frameworks`. + +#### Workaround +Use `nuget.exe` [5.8.1](https://dist.nuget.org/win-x86-commandline/v5.8.1/nuget.exe) or latest version other than `5.9.1`. + +## Feedback welcome + +Your feedback is important to us. If there are any problems with this release, check our +[GitHub Issues](https://github.com/NuGet/Home/issues) and +[Visual Studio Developer Community](https://developercommunity.visualstudio.com/) +for existing issues. For new issues within NuGet, please report a +[GitHub Issue](https://github.com/NuGet/Home/issues/new). +For general NuGet experience issues, let us know via the +[Report a Problem](/visualstudio/ide/how-to-report-a-problem-with-visual-studio) +option found in your favorite IDE under **Help > Report a Problem**. diff --git a/docs/release-notes/NuGet-6.0.md b/docs/release-notes/NuGet-6.0.md new file mode 100644 index 000000000..5de5d1544 --- /dev/null +++ b/docs/release-notes/NuGet-6.0.md @@ -0,0 +1,406 @@ +--- +title: NuGet 6.0 Release Notes +description: Release notes for NuGet 6.0 including new features, bug fixes, and DCRs. +author: zkat +ms.author: kmarchan +ms.date: 10/7/2021 +ms.topic: release-notes +--- + +# NuGet 6.0 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.0.0**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.0.0](https://visualstudio.microsoft.com/downloads/) | [6.0.0](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | +| **6.0.1** | [Visual Studio 2022 version 17.0.2](https://visualstudio.microsoft.com/downloads/) | N/A | +| [**6.0.2**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.0.11](https://visualstudio.microsoft.com/downloads/) | [6.0.301](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | +| [**6.0.3**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.0](https://visualstudio.microsoft.com/downloads/) | [6.0.110](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | +| [**6.0.5**](https://nuget.org/downloads) | N/A | [6.0.118](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | +| [**6.0.6**](https://nuget.org/downloads) | N/A | [6.0.127](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | + +1 Installed with Visual Studio 2022 with.NET Core workload + +## Summary: What's New in 6.0.6 + +* [Security]: Microsoft Security Advisory CVE-2024-0057 | NuGet Client Security Feature bypass Vulnerability - [#12653](https://github.com/NuGet/Home/issues/13241) + +## Summary: What's New in 6.0.5 + +* [Security]: Microsoft Security Advisory CVE-2023-29337 | NuGet Client Remote Code Execution Vulnerability - [#12653](https://github.com/NuGet/Home/issues/12653) + +> [!NOTE] +> There is a behavior breaking change on Linux. The temp folder location, where NuGet stores temporary files during its various operations, has changed from `/tmp/NuGetScratch` to `/tmp/NuGetScratch`. E.g. for user User1, the temp folder will be `/tmp/NuGetScratchUser1`. + +## Summary: What's New in 6.0.3 + +* [Security]: Microsoft Security Advisory CVE-2022-41032 | .NET Elevation of Privilege Vulnerability - [#12149](https://github.com/NuGet/Home/issues/12149) + +> [!NOTE] +> Visual Studio 17.0, MSBuild 17.0, and .NET 6.0 require NuGet.exe 6.0 or later. +## Summary: What's New in 6.0.2 + +* [Security]: Microsoft Security Advisory CVE 2022-30184 | .NET Information Disclosure Vulnerability - [#11883](https://github.com/NuGet/Home/issues/11883) + +## Summary: What's New in 6.0.0 + +🎉 **This is the first release to offer full authoring and restoring support for NuGet packages targeting .NET 6.0** 🎉 + +### .NET 6 Support + +NuGet 6.0 is the first release to offer full authoring and restoring support for NuGet packages targeting .NET 6.0. You can now target the following target frameworks: + +* net6.0 +* net6.0-windows +* net6.0-android +* net6.0-ios +* net6.0-macos +* net6.0-maccatalyst +* net6.0-tvos +* net6.0-tizen + + ![.NET 6](media/NuGet-6.0/dotnet.png) + +If you aren’t familiar with the .NET 6.0 targets today or what it will look like in the future, don’t forget to check out the [.NET 6.0 TFM spec](https://github.com/dotnet/designs/blob/main/accepted/2021/net6.0-tfms/net6.0-tfms.md). + +### Source Mapping + +Earlier this year, many package managers became aware of [dependency confusion](https://medium.com/@alex.birsan/dependency-confusion-4a5d60fec610) attacks in which a user to be tricked into installing a malicious dependency instead of the one they intended to. To fortify your software supply chain against these attacks, the NuGet team has developed a new feature that allows you to map your dependencies to specific sources. Below is an example of how you can use source mapping to protect your projects. + +
    <!-- Define a global packages folder for your repository. -->
+<!-- This is where installed packages will be stored locally. -->
+<config>
+  <add key="globalPackagesFolder" value="globalPackagesFolder" />
+</config>
+
+<!-- Define my package sources, nuget.org and contoso.com. -->
+<!-- `clear` ensures no additional sources are inherited from another config file. -->
+<packageSources>
+  <clear />
+  <!-- `key` can be any identifier for your source. -->
+  <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+  <add key="contoso.com" value="https://contoso.com/packages/" />
+</packageSources>
+
+<!-- Define mappings by adding package ID patterns beneath the target source. -->
+<!-- Contoso.* packages will be restored from contoso.com, everything else from nuget.org. -->
+<packageSourceMapping>
+  <!-- key value for <packageSource> should match key values from <packageSources> element -->
+  <packageSource key="nuget.org">
+    <package pattern="*" />
+  </packageSource>
+  <packageSource key="contoso.com">
+    <package pattern="Contoso.*" />
+  </packageSource>
+</packageSourceMapping>
+
    + +You can read more about source mapping in our [blog released earlier this year](https://devblogs.microsoft.com/nuget/introducing-package-source-mapping/). + +### Package Vulnerabilities in Visual Studio + +When using the NuGet Package Manager within Visual Studio, you will now see package vulnerabilities for your packages including details such as the number and severity of vulnerabilities as well as direct links to learn more about the advisories. + + ![Visual Studio Package Vulnerabilities](media/NuGet-6.0/VS-Vulnerability.png) + +### Retry & Backoff Behavior + +There is now a `NUGET_ENABLE_EXPERIMENTAL_HTTP_RETRY` flag to improve the retry & backoff behavior of NuGet clients such as increasing the maximum amount of retries and increasing the delay for a more resilient experience when encountering a weaker internet connection. + +### Exclude Default File Extensions + +You can now use the MSBuild flag `` to edit the file extensions included in the build output of your package. This gives you more control over the extensions being included in your build output folder. + +### Improved Deprecation Information in Visual Studio + +Deprecated packages in Visual Studio now include a link to the suggested alternate package to use. You can use this feature to quickly browse and install packages that are actively maintained. + + ![Visual Studio Package Deprecations](media/NuGet-6.0/VS-Deprecation.png) + +### Add a Package README in Visual Studio + +You can now add a package README.md file directly within Visual Studio. A README helps communicate important information about your package. It is often the first item a visitor will see when visiting your package on NuGet.org. README files typically include information on: + +* What the package does +* Why the package is useful +* How users can get started with the package +* Where users can get help or contribute to your package + +You can read more about [adding a README to your NuGet package on our blog](https://devblogs.microsoft.com/nuget/add-a-readme-to-your-nuget-package/). + +### Faster Solution Load & Branch Switching in Visual Studio + +In Visual Studio 2022, NuGet has redefined the contract between NuGet package restore and common Visual Studio components to improve performance for large solutions by only calling restore once instead of multiple times. This improves the time it takes for background processes to complete significantly. + +Install the [Visual Studio 2022 Preview](https://visualstudio.microsoft.com/downloads/) and let us know if you notice a faster experience when loading your large solutions or switching between branches! + +### NuGet's SolutionRestoreManager Visual Studio APIs moved into NuGet.VisualStudio package + +NuGet.SolutionRestoreManager.Interop is no longer updated, and its APIs have been merged into the NuGet.VisualStudio package. +If you are updating an existing Visual Studio extension to work with Visual Studio 2022 (17.0), and you were previously using NuGet.SolutionRestoreManager.Interop, you should uninstall that package and upgrade/install NuGet.VisualStudio to version 6.0.0. +The namespaces and classes remain the same, so it's compatible from an API perspective. + +Additionally, following [Visual Studio's change in policy](/visualstudio/extensibility/migration/migrated-assemblies?view=vs-2022&preserve-view=true), NuGet.VisualStudio no longer uses `EmbedInteropTypes`. +Therefore, your extension will have a compile time reference to NuGet.VisualStudio.dll. +Nuget instructs Visual Studio to use binding redirects, so your extension will not be affected when NuGet updates to newer versions and your extension is compiled against an older version of our assembly. +For this reason, you can suppress NuGet's assemblies from your vsix to reduce the download size. +NuGet's packages will be updated to do this automatically in NuGet 6.2 (for Visual Studio 17.2). + +To suppress NuGet's assemblies from your vsix, add the following to your project file: + +```xml + + + + +``` + +**Features:** + +* Add hook for excluding certain build output extensions from the nuget package - [#10690](https://github.com/NuGet/Home/issues/10690) + +* Implement new precedence for xamarin TFMs when using net6.0+ - [#10717](https://github.com/NuGet/Home/issues/10717) + +* Implement maccatalyst warning when "falling back" to xamarin.ios for net6.0+ projects - [#10718](https://github.com/NuGet/Home/issues/10718) + +* Add package namespaces support as part of the configuration - add a reading capability only - [#10725](https://github.com/NuGet/Home/issues/10725) + +* Package Namespaces: Account for package namespaces filtering in package downloading in PackageReference restore - [#10732](https://github.com/NuGet/Home/issues/10732) + +* Add namespaces filtering support in packages.config restore in nuget.exe and msbuild /t:restore - [#10737](https://github.com/NuGet/Home/issues/10737) + +* Add a contract for identifying a restore source, to help nuget better batch restores/branch switches. - [#10807](https://github.com/NuGet/Home/issues/10807) + +* Add support for net6.0-tizen and net6.0-android - [#10819](https://github.com/NuGet/Home/issues/10819) + +* Add namespaces filtering support for packages.config restore in Visual Studio - [#10823](https://github.com/NuGet/Home/issues/10823) + +* Add support for TfmSpecificDebugSymbolsFile to provide symbols in the inner build - [#10913](https://github.com/NuGet/Home/issues/10913) + +* Show warning icon in Installed tab if there are vulnerable packages installed - [#10982](https://github.com/NuGet/Home/issues/10982) + +* Show warning icon by package in list of packages if there is a vulnerability - [#10983](https://github.com/NuGet/Home/issues/10983) + +* Show package vulnerability details in the package details pane of the PMUI - [#10985](https://github.com/NuGet/Home/issues/10985) + +* Add Deprecation Links in Details page in PM UI - [#10996](https://github.com/NuGet/Home/issues/10996) + +* [Feature]: Make retry count and backoff behavior configurable for Nuget Clients - [#11027](https://github.com/NuGet/Home/issues/11027) + +* [Feature]: Address all the package installation rules for package namespaces work in PackageReference and PackageDownload scenarios. - [#11035](https://github.com/NuGet/Home/issues/11035) + +* [Feature]: Address all the package installation rules for package namespaces work in Packages Config style projects - [#11036](https://github.com/NuGet/Home/issues/11036) + +### Issues fixed in this release + +**DCRs:** + +* Consider removing the extensibility that allows other package managers to be shown as compatible - [#6623](https://github.com/NuGet/Home/issues/6623) + +* Stop using EmbedInteropTypes for NuGet's VS extenbility packages/assemblies - [#10892](https://github.com/NuGet/Home/issues/10892) + +* Project.nuget.g.targets should not prepend to MSBuildAllProjects in MSBuild 16 or later - [#10895](https://github.com/NuGet/Home/issues/10895) + +* Remove obsolete core APIs - [#10940](https://github.com/NuGet/Home/issues/10940) + +* Merge NuGet.SolutionRestoreManager.Interop into NuGet.VisualStudio - [#10957](https://github.com/NuGet/Home/issues/10957) + +* Remove RuntimeEnvironmentHelper.IsDev14 - [#11000](https://github.com/NuGet/Home/issues/11000) + +* Update Newtonsoft.Json to 13.0.1 - [#11095](https://github.com/NuGet/Home/issues/11095) + +* [DCR]: Rename packageNamespaces feature to packageSourceMapping - [#11205](https://github.com/NuGet/Home/issues/11205) + +**Bugs:** + +* Installing with package save mode "nuspec" always reinstalls - [#2402](https://github.com/NuGet/Home/issues/2402) + +* Update-Package -reinstall -ProjectName `` does not work for PR - [#6088](https://github.com/NuGet/Home/issues/6088) + +* "An item with the same key has already been added" - when project graph has projectName == packageRef name (of same version) - [#6795](https://github.com/NuGet/Home/issues/6795) + +* [Test Failure] Suggest removing the second duplicated string “License Acceptance” in “License Acceptance” dialog - [#8162](https://github.com/NuGet/Home/issues/8162) + +* Can't remove config key using nuget.exe - [#8223](https://github.com/NuGet/Home/issues/8223) + +* msbuild /t:Restore and Visual Studio produce different assets files when assembly name != project name - [#8272](https://github.com/NuGet/Home/issues/8272) + +* PM UI does not humanize the download count when 999,500 <= count <=999,999 - [#8800](https://github.com/NuGet/Home/issues/8800) + +* Roslyn Analyzer suggestion "install with package manager" opens NuGet to wrong tab - [#10124](https://github.com/NuGet/Home/issues/10124) + +* StaticGraph Restore should clearly call out when a project is not `KnownToBeMSBuildFormat` When Called via a Solution File - [#10363](https://github.com/NuGet/Home/issues/10363) + +* The "nuget spec" command generates a .nuspec file with an iconUrl - [#10400](https://github.com/NuGet/Home/issues/10400) + +* Rfc3161TimestampTokenInfo.GetNonce can throw - [#10484](https://github.com/NuGet/Home/issues/10484) + +* Verify command is not disabled on Mono - [#10585](https://github.com/NuGet/Home/issues/10585) + +* The CreateLockFileTargetLibrary method slows down the restore operation - [#10614](https://github.com/NuGet/Home/issues/10614) + +* PackageArchieveReader doesn't override CopyNupkgAsync so package extraction fails - [#10708](https://github.com/NuGet/Home/issues/10708) + +* Propagate package namespaces information to the restore command - [#10736](https://github.com/NuGet/Home/issues/10736) + +* Ensure the namespaces filtering is respected in packages.config package installation/updates in PMUI - [#10738](https://github.com/NuGet/Home/issues/10738) + +* NuGet.Packaging.Extraction: exceptions from resources not found - [#10776](https://github.com/NuGet/Home/issues/10776) + +* Cannot use embeded PackageReadmeFile when using snupkg for symbols - [#10791](https://github.com/NuGet/Home/issues/10791) + +* Remove redundant UI delay switches in NuGet Project initialization - [#10824](https://github.com/NuGet/Home/issues/10824) + +* Remove unnecessary ToList enumerations in restore codepaths - [#10835](https://github.com/NuGet/Home/issues/10835) + +* Mark IVsPackageInstallerServices as deprecated - [#10836](https://github.com/NuGet/Home/issues/10836) + +* NuGet packages downloaded over 1 billion times show the wrong unit - [#10864](https://github.com/NuGet/Home/issues/10864) + +* Hard to see the background color of the number on the right of “Updates” and “Consolidate” tabs in the Dark theme - [#10896](https://github.com/NuGet/Home/issues/10896) + +* IVsProjectRestoreInfoSource improvements - [#10898](https://github.com/NuGet/Home/issues/10898) + +* packages.lock.json broken with Sdk-Style C# project targeting net5.0-windows - [#10901](https://github.com/NuGet/Home/issues/10901) + +* Add a default implementation for IVsSolutionRestoreService4 - [#10908](https://github.com/NuGet/Home/issues/10908) + +* [Responsiveness] Remove implicit RPC from background thread via unneeded GetServiceAsync extensions - [#10916](https://github.com/NuGet/Home/issues/10916) + +* Boxing of bool is to compute hashcode is causing excessive allocations - [#10917](https://github.com/NuGet/Home/issues/10917) + +* Iterating over Library Dependencies is causing over-allocation of Enumerators - [#10918](https://github.com/NuGet/Home/issues/10918) + +* Compatibility cache lookup allocates Func for each lookup - [#10919](https://github.com/NuGet/Home/issues/10919) + +* Overallocations of WhereListIterator in DependencyWalker.CreateGraphNode - [#10920](https://github.com/NuGet/Home/issues/10920) + +* Exception while restoring: "Restore metadata is mising the required target frameworks list" - [#10924](https://github.com/NuGet/Home/issues/10924) + +* Share a framework reducer across managed code conventions - [#10925](https://github.com/NuGet/Home/issues/10925) + +* NuGet VSIX is generated with incorrect binding redirects - [#10946](https://github.com/NuGet/Home/issues/10946) + +* NuGet Package Manager UI delays when running init scripts - [#10947](https://github.com/NuGet/Home/issues/10947) + +* Support sourceUri passed on nuget restore/install and dotnet restore package or other equivalent commands - [#10948](https://github.com/NuGet/Home/issues/10948) + +* Namespaces filtering support for the nuget.exe install command - [#10961](https://github.com/NuGet/Home/issues/10961) + +* Stop generating raw properties for every segment - [#10969](https://github.com/NuGet/Home/issues/10969) + +* Unexpected NU1605 from transitive reference that was never selected (pruned subgraph) - [#10972](https://github.com/NuGet/Home/issues/10972) + +* NuGet.Localization has no package icon - [#10975](https://github.com/NuGet/Home/issues/10975) + +* Avoid unnecessarily resizing dictionary while calculating project closure - [#10976](https://github.com/NuGet/Home/issues/10976) + +* Conflicting documentation on ISettings.AddOrUpdate - [#10980](https://github.com/NuGet/Home/issues/10980) + +* Use a pooled byte array when copying files and validating signatures - [#10988](https://github.com/NuGet/Home/issues/10988) + +* Avoid Task.WhenAny allocations in dependency walker - [#10989](https://github.com/NuGet/Home/issues/10989) + +* Ensure the namespaces filtering is respected in packages.config package installation/updates PMC - [#11001](https://github.com/NuGet/Home/issues/11001) + +* Ensure the namespaces filtering is respected in packages.config package installation/updates IVs installer API - [#11002](https://github.com/NuGet/Home/issues/11002) + +* [Bug]: PM UI shows 0 download count when selected package is already installed - [#11012](https://github.com/NuGet/Home/issues/11012) + +* Reduce allocations in VersionFormatter - [#11014](https://github.com/NuGet/Home/issues/11014) + +* Obsolete unused types: LibraryDependencyType and related - [#11015](https://github.com/NuGet/Home/issues/11015) + +* [Bug]: `nuget.exe install packages.config` does not honor `-PackageSaveMode nuspec` - [#11018](https://github.com/NuGet/Home/issues/11018) + +* [Bug]: `$(IsPackable)` is not quoted - [#11025](https://github.com/NuGet/Home/issues/11025) + +* Create Apex tests with multi source repositories for PMUI Package namespace filtering - [#11026](https://github.com/NuGet/Home/issues/11026) + +* [Bug]: [Accessibility] Hard to read links in PM UI search results using Light or Dark Theme - [#11055](https://github.com/NuGet/Home/issues/11055) + +* IVsSolutionRestoreService4 should extend IVsSolutionRestoreService3 - [#11098](https://github.com/NuGet/Home/issues/11098) + +* [Bug]: Advisory links should be aligned in details pane of PMUI - [#11101](https://github.com/NuGet/Home/issues/11101) + +* Tooltip of the installed vulnerable/deprecation package versions’ warning icon is not clear - [#11103](https://github.com/NuGet/Home/issues/11103) + +* [Responsiveness] RestoreOperationLogger+StatusBarProgress.Dispose blocking a thread pool thread waiting for UI thread - [#11115](https://github.com/NuGet/Home/issues/11115) + +* Add time since last restore metric - [#11124](https://github.com/NuGet/Home/issues/11124) + +* [Bug]: nuget.exe regression in handling of recursive `` entries between 5.9.1 and 5.10.0 - [#11125](https://github.com/NuGet/Home/issues/11125) + +* Await WhenNominated when a project has a pending nomination - [#11132](https://github.com/NuGet/Home/issues/11132) + +* Support sourceUri option passed on dotnet add package - [#11140](https://github.com/NuGet/Home/issues/11140) + +* [Bug]: VS PM UI does not display JPEG icons for packages - [#11144](https://github.com/NuGet/Home/issues/11144) + +* UIDelay: `nuget.packagemanagement.visualstudio.dll!NuGet.PackageManagement.VisualStudio.VsCoreProjectSystemReferenceReader+d__` - CPS projects - [#11162](https://github.com/NuGet/Home/issues/11162) + +* [Bug]: `dotnet list package --outdated --interactive` makes credential provider invalidate cache for every package listed - [#11169](https://github.com/NuGet/Home/issues/11169) + +* [Bug]: Package namespaces for packages.config scenarios is using all the sources as fallback option when no matching namespaces are found for a package - [#11170](https://github.com/NuGet/Home/issues/11170) + +* Avoid MEF lookups on UI thread during NuGet projects initialization - [#11176](https://github.com/NuGet/Home/issues/11176) + +* [Bug]: Tooltip on the warning indicator image in the Installed tab no longer works - [#11183](https://github.com/NuGet/Home/issues/11183) + +* All ServiceLocator calls that retrieve MEF services should avoid the UI thread. - [#11201](https://github.com/NuGet/Home/issues/11201) + +* [Bug]: Telemetry event missing in Visual Studio - [#11206](https://github.com/NuGet/Home/issues/11206) + +* Avoid duplicate EnvDTEProjectUtility.IsSupportedAsync calls - [#11207](https://github.com/NuGet/Home/issues/11207) + +* Add IVsSolutionManager.GetSolutionDirectoryAsync - improve performance and stop blocking the calling thread in async codepaths. - [#11208](https://github.com/NuGet/Home/issues/11208) + +* Rename types/variables in the product/test code to reflect new name for package namespaces feature - [#11216](https://github.com/NuGet/Home/issues/11216) + +* [Bug]: ArPow build doesn't work well when in a subdirectory of an unrelated git repository - [#11227](https://github.com/NuGet/Home/issues/11227) + +* dotnet list package --vulnerable, --deprecated, --outdated does not work for transitive-only positives - [#10767](https://github.com/NuGet/Home/issues/10767) + +**[List of all issues fixed in this release - 6.0](https://app.zenhub.com/workspaces/nuget-client-team-55aec9a240305cf007585881/reports/release?release=Z2lkOi8vcmFwdG9yL1JlbGVhc2UvNDMwMDQ)** + +**[List of commits in this release - 6.0.0](https://github.com/NuGet/NuGet.Client/compare/5.11.0.17...6.0.0.280)** + +## Summary: What's New in 6.0.1 + +Only Visual Studio was updated with this version of NuGet. + +### Issues fixed in this release + +* [Bug]: Cannot get INuGetProjectService from the service broker in Visual Studio 17 - [#11367](https://github.com/NuGet/Home/issues/11367) +* [Bug]: Package Manager Console initialization might cause deadlocks - [#11320](https://github.com/NuGet/Home/issues/11320) + +**[List of commits in this release - 6.0.1](https://github.com/NuGet/NuGet.Client/compare/6.0.0.280...6.0.1.1)** + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +|Who|PRs|Issues| +|----|----|----| +[omajid](https://github.com/omajid) | [3866](https://github.com/NuGet/NuGet.Client/pull/3866) | Handle nonce being null in Rfc3161TimestampTokenInfo - [#10484](https://github.com/NuGet/Home/issues/10484) +[marcin-krystianc](https://github.com/marcin-krystianc) | [3934](https://github.com/NuGet/NuGet.Client/pull/3934) | Adding a cache for LockFileTargetLibrary - [#10614](https://github.com/NuGet/Home/issues/10614) +[krafs](https://github.com/krafs) | [4151](https://github.com/NuGet/NuGet.Client/pull/4151) | Removed return value from docs on ISettings.AddOrUpdate - [#10980](https://github.com/NuGet/Home/issues/10980) +[huangqinjin](https://github.com/huangqinjin) | [4148](https://github.com/NuGet/NuGet.Client/pull/4148) | Fix PackageSaveMode nuspec always reinstalls - [#2402](https://github.com/NuGet/Home/issues/2402) +[Insomniak47](https://github.com/Insomniak47) | [4190](https://github.com/NuGet/NuGet.Client/pull/4190) | fix(docs): Remove link to closed/dead-end link in Contributing guidelines - [#8987](https://github.com/NuGet/Home/issues/8987) +[marcin-krystianc](https://github.com/marcin-krystianc) | [4194](https://github.com/NuGet/NuGet.Client/pull/4194) | Make the performance scripts account for restore operation failures - [#9968](https://github.com/NuGet/Home/issues/9968) +[eriawan](https://github.com/eriawan) | [4159](https://github.com/NuGet/NuGet.Client/pull/4159) | Fixes Surround ($IsPackable) with single quotes - [#11025](https://github.com/NuGet/Home/issues/11025) +[huangqinjin](https://github.com/huangqinjin) | [4193](https://github.com/NuGet/NuGet.Client/pull/4193) | Install packages.config should honor PackageSaveMode - [#11018](https://github.com/NuGet/Home/issues/11018) +[mfkl](https://github.com/mfkl) | [4199](https://github.com/NuGet/NuGet.Client/pull/4199) | test: use new DependencyGraphSpec - [#11168](https://github.com/NuGet/Home/issues/11168) +[omajid](https://github.com/omajid) | [4254](https://github.com/NuGet/NuGet.Client/pull/4254) | Use --work-tree with git apply - [#11227](https://github.com/NuGet/Home/issues/11227) + +## Feedback welcome + +Your feedback is important to us. If there are any problems with this release, check our +[GitHub Issues](https://github.com/NuGet/Home/issues) and +[Visual Studio Developer Community](https://developercommunity.visualstudio.com/) +for existing issues. For new issues within NuGet, please report a +[GitHub Issue](https://github.com/NuGet/Home/issues/new/choose). +For general NuGet experience issues, let us know via the +[Report a Problem](/visualstudio/ide/how-to-report-a-problem-with-visual-studio) +option found in your favorite IDE under **Help > Report a Problem**. diff --git a/docs/release-notes/NuGet-6.1.md b/docs/release-notes/NuGet-6.1.md new file mode 100644 index 000000000..9ae87e416 --- /dev/null +++ b/docs/release-notes/NuGet-6.1.md @@ -0,0 +1,131 @@ +--- +title: NuGet 6.1 Release Notes +description: Release notes for NuGet 6.1 including new features, bug fixes, and DCRs. +author: zivkan +ms.author: zivkan +ms.date: 2/15/2022 +ms.topic: release-notes +--- + +# NuGet 6.1 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.1.0**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.1](https://visualstudio.microsoft.com/downloads/) | [6.0.200](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | + +1 Installed with Visual Studio 2022 with.NET Core workload + +## Summary: What's New in 6.1 + +* Show subcommand help instead of main `dotnet nuget trust` command help for all cases - [#10788](https://github.com/NuGet/Home/issues/10788) + +* Sort the package vulnerabilities in descending order in PMUI details pane - [#11091](https://github.com/NuGet/Home/issues/11091) + +### Issues fixed in this release + +**DCRs:** + +* Disable nuget.exe pack for project.json by default, add a fallback env var to enable it - [#11214](https://github.com/NuGet/Home/issues/11214) + +* [DCR]: Adjust compatibility rules for Apple TFMs in .NET - [#11338](https://github.com/NuGet/Home/issues/11338) + +* [DCR][No Customer Impact]: NuGetPackage (VS extension entry point) should not use DTEEvents - [#11360](https://github.com/NuGet/Home/issues/11360) + +* [DCR]: Mitigate missing nuget.org when non-NuGet tool creates nuget.config without any sources - [#11387](https://github.com/NuGet/Home/issues/11387) + +* [DCR]: NuGet.VisualStudio and NuGet.VisualStudio.Contracts to follow Visual Studio version numbers - [#11394](https://github.com/NuGet/Home/issues/11394) + +* [DCR]: Deprecate VS Extensibility APIs that use System.Version - [#11412](https://github.com/NuGet/Home/issues/11412) + +* [DCR]: Obsolete VS extensibility APIs that use System.Runtime.Versioning.FrameworkName - [#11419](https://github.com/NuGet/Home/issues/11419) + +* Remove Mac Catalyst warning - [#11438](https://github.com/NuGet/Home/issues/11438) + +* dotnet nuget push - Missing value for option - [#4864](https://github.com/NuGet/Home/issues/4864) + +**Bugs:** + +* Confusing restore output: it did some restore on one of the projects, but at the end it still prints "All packages are already installed and there is nothing to restore" - [#4376](https://github.com/NuGet/Home/issues/4376) + +* Restore does not print enough info in the output when fails - [#6047](https://github.com/NuGet/Home/issues/6047) + +* Minimal VS install has broken NuGet UI - [#8414](https://github.com/NuGet/Home/issues/8414) + +* Visual Studio is unresponsive while using `Clear All NuGet cache(s)` feature - [#9831](https://github.com/NuGet/Home/issues/9831) + +* Versions List in Details Pane is not kept in sync when changing Selected Package - [#10557](https://github.com/NuGet/Home/issues/10557) + +* File Conflict dialog does not have access keys - [#10691](https://github.com/NuGet/Home/issues/10691) + +* ContentItemCollection uses yield return which is causing over-allocation of Enumerators - [#10921](https://github.com/NuGet/Home/issues/10921) + +* UIDelay: `nuget.packagemanagement.visualstudio.dll!NuGet.PackageManagement.VisualStudio.VsCoreProjectSystemReferenceReader+d__` - managed projects - [#11163](https://github.com/NuGet/Home/issues/11163) + +* [Bug]: MSBuild restore is logging exception as warning - [#11179](https://github.com/NuGet/Home/issues/11179) + +* [Bug]: String comparison approach used for Source and Namespaces is not consistent - [#11182](https://github.com/NuGet/Home/issues/11182) + +* There is no tooltip for the “install” button on the right of a package in "Browse" tab - [#11189](https://github.com/NuGet/Home/issues/11189) + +* Async Service Provider should be invoked on threadpool threads via the built in TService,TInterface extensions instead of custom casting - [#11200](https://github.com/NuGet/Home/issues/11200) + +* [Bug]: VS crashes when package sources dropdown in PM UI has multiple package sources whose names are equal when compared using Culture Ignore Case - [#11241](https://github.com/NuGet/Home/issues/11241) + +* The strings "ms" and "sec" are not localized on Output - Package Manager window. - [#11297](https://github.com/NuGet/Home/issues/11297) + +* Sort Package Source dropdown list using locale/culture setttings in PM UI - [#11298](https://github.com/NuGet/Home/issues/11298) + +* Update SDPX license list from da7ecca to fafa781 - [#11309](https://github.com/NuGet/Home/issues/11309) + +* [Bug]: NuGet.Localization isn't generated - [#11328](https://github.com/NuGet/Home/issues/11328) + +* [Bug]: assembly-loading MEF composition in NuGet.Tools VS package's synchronous event handlers can cause responsiveness delays - [#11334](https://github.com/NuGet/Home/issues/11334) + +* [Bug]: NuGet SDK resolver should not throw if project path is NULL - [#11376](https://github.com/NuGet/Home/issues/11376) + +* [Bug]: PackageSourceMapping inconsistencies should be reported - [#11385](https://github.com/NuGet/Home/issues/11385) + +* [Bug]: `RegistryKeyUtility.GetValueFromRegistryKey()` has unused parameter, leading to incorrect results - [#11407](https://github.com/NuGet/Home/issues/11407) + +* Reduce heap allocations in ResolverUtility.FindLibraryByVersionAsync - [#11409](https://github.com/NuGet/Home/issues/11409) + +* [Bug]: Package Source Mapping matches found should not be logged for projects - [#11413](https://github.com/NuGet/Home/issues/11413) + +* [Bug]: Avoid explicitly casting the result of GetService/GetServiceAsync, use the extension methods instead - [#11451](https://github.com/NuGet/Home/issues/11451) + +* [Bug]: Package Source options in VS does not announce package sources or checkbox status - [#11482](https://github.com/NuGet/Home/issues/11482) + +* [Bug]: VS package source options clears all checkboxes when adding or removing sources - [#11521](https://github.com/NuGet/Home/issues/11521) + +**[List of all issues fixed in this release - 6.1](https://app.zenhub.com/workspaces/nuget-client-team-55aec9a240305cf007585881/reports/release?release=Z2lkOi8vcmFwdG9yL1JlbGVhc2UvNjY5ODY)** + +## Known issues + +### dotnet nuget push -n|--no-symbols or -d|--disable-buffering raises `error: File does not exist ...` exception. - [#11601](https://github.com/NuGet/Home/issues/11601) + +#### Issue +Previously in order to use `-n|--no-symbols` and `-d|--disable-buffering` options with `dotnet nuget push` command requires passing of unnecessary random value after it. Removal of this unnecessary value can break your script by throwing exception with `error: File does not exist ...` even though actual push operation was successful. + +#### Workaround +Use `-n|--no-symbols` and `-d|--disable-buffering` options standalone without any additional value parameter. + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +|Who|PRs|Issues| +|----|----|----| +[mairaw](https://github.com/mairaw) | [4336](https://github.com/NuGet/NuGet.Client/pull/4336) | Fix broken NuGet logo image - [#11390](https://github.com/NuGet/Home/issues/11390) + +## Feedback welcome + +Your feedback is important to us. If there are any problems with this release, check our +[GitHub Issues](https://github.com/NuGet/Home/issues) and +[Visual Studio Developer Community](https://developercommunity.visualstudio.com/) +for existing issues. For new issues within NuGet, please report a +[GitHub Issue](https://github.com/NuGet/Home/issues/new/choose). +For general NuGet experience issues, let us know via the +[Report a Problem](/visualstudio/ide/how-to-report-a-problem-with-visual-studio) +option found in your favorite IDE under **Help > Report a Problem**. diff --git a/docs/release-notes/NuGet-6.10.md b/docs/release-notes/NuGet-6.10.md new file mode 100644 index 000000000..cdc222c9d --- /dev/null +++ b/docs/release-notes/NuGet-6.10.md @@ -0,0 +1,214 @@ +--- +title: NuGet 6.10 Release Notes +description: Release notes for NuGet 6.10 including new features, bug fixes, and DCRs. +author: kartheekp-ms +ms.date: 5/13/2024 +ms.topic: release-notes +--- + +# NuGet 6.10 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.10.2**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.10](https://visualstudio.microsoft.com/downloads/) | [8.0.3xx](https://dotnet.microsoft.com/download/dotnet/8.0)1 | + +1 Installed with Visual Studio 2022 with any .NET workload + +## Summary: What's New in 6.10.2 + +### Issues fixed in this release + +* Revert Enable central package management implicitly when Directory.Packages.props exists - [#11834](https://github.com/NuGet/Home/issues/11834) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.10.1.5...6.10.2.8) + +1 Installed with Visual Studio 2022 with any .NET workload + +## Summary: What's New in 6.10.1 + +### Issues fixed in this release + +* Visual Studio and PMC restore/update fails when multiple packages.config projects in the solution share the same name (An item with the same key has already been added) - [#13465](https://github.com/NuGet/Home/issues/13465) + +* ##[error]The nuget command failed with exit code(1) and error(An item with the same key has already been added. - [#13456](https://github.com/NuGet/Home/issues/13456) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.10.0.97...6.10.1.5) + +## Summary: What's New in 6.10 + +* [Feature]: add dotnet nuget config command - [#12469](https://github.com/NuGet/Home/issues/12469) + +* Warn when vulnerabilities are detected during packages.config restore - [#12307](https://github.com/NuGet/Home/issues/12307) + +* Display a vulnerability info bar when there's vulnerabilities in packages.config based projects. - [#13271](https://github.com/NuGet/Home/issues/13271) + +* [Bug]: VS Credential Provider Incorrectly Setting Value of `isRetry` - [#11210](https://github.com/NuGet/Home/issues/11210) + +* dotnet list package --vulnerable requires constant login to 3rd party nuget feed - [#12456](https://github.com/NuGet/Home/issues/12456) + +### 6.10.0 Known issues + +NuGet.exe 6.10.0 and Visual Studio 17.10.0 may have failures during NuGet operations for projects using packages.config under the following scenarios: + +* Two or more projects in the solution have the same name +* Two or more projects in the solution use the same packages.config file (the project files exist in the same directory) + +These issues have been fixed in NuGet.exe 6.10.1 and Visual Studio 17.10.2. + +Public tracking issues and discussions can be found in the following locations: + +* [Cannot nuget restore after updating visual studio community to 17.10.0. An item with the same key has already been added.](https://developercommunity.visualstudio.com/t/Cannot-nuget-restore-after-updating-visu/10665602) +* [Visual Studio and PMC restore/update fails when multiple packages.config projects in the solution share the same name (An item with the same key has already been added)](https://github.com/NuGet/Home/issues/13465) +* [##[error]The nuget command failed with exit code(1) and error(An item with the same key has already been added.](https://github.com/NuGet/Home/issues/13456) + +### Breaking changes + +* Add nullable annotations to NuGet.Configuration - [#13250](https://github.com/NuGet/Home/issues/13250) + +* [Dotnet Package Search] The search result of the package should be “version” instead of “latestVersion” when executing command “dotnet package search \ --exact-match --format json” - [#13158](https://github.com/NuGet/Home/issues/13158) + +* ResolvedDependencyKey should be struct to reduce memory allocations - [#13138](https://github.com/NuGet/Home/issues/13138) + +* [DCR]: Central Package Management - Respect .props file as a way to opt-in to the feature. - [#11834](https://github.com/NuGet/Home/issues/11834) + +* Remove NuGet.Packaging.Core - [#12495](https://github.com/NuGet/Home/issues/12495) + +### Issues fixed in this release + +* Warn when vulnerabilities are detected during packages.config restore in CLI scenarios. - [#13253](https://github.com/NuGet/Home/issues/13253) + +* Stop using JObject in assets file reading to reduce allocations. [#12715](https://github.com/NuGet/Home/issues/12715) + +* Add event tracing to restore to make it possible to measure performance - [#13274](https://github.com/NuGet/Home/issues/13274) + +* Read auditSources from nuget.config files - [#13211](https://github.com/NuGet/Home/issues/13211) + +* SourceRepository.GetResourceAsync should be cancellable. - [#13234](https://github.com/NuGet/Home/issues/13234) + +* CreateWalkAsync should not be recursive - [#13222](https://github.com/NuGet/Home/issues/13222) + +* ProjectModel.HashObjectWriter.OnFlush is using a SHA512 hash versus a cheaper hash which seems like overkill - [#13214](https://github.com/NuGet/Home/issues/13214) + +* Owner package metadata is an array in JSON but a string in Protocol types - [#13186](https://github.com/NuGet/Home/issues/13186) + +* dotnet package search --verbosity detailed output table too wide - [#13162](https://github.com/NuGet/Home/issues/13162) + +* Calls in SetWarningProperties() have allocation overhead due to multiple enumeration - [#13151](https://github.com/NuGet/Home/issues/13151) + +* Use of ConcurrentStack in object pool implementation creates large amounts of allocations - [#13147](https://github.com/NuGet/Home/issues/13147) + +* IsBestVersion boxes HashSet\ enumerators resulting in lots of allocation overhead during restore. - [#13146](https://github.com/NuGet/Home/issues/13146) + +* Deprecate NuGet.exe list in favor of NuGet.exe search - [#7912](https://github.com/NuGet/Home/issues/7912) + +* [Dotnet Package Search] An unhandled exception is thrown when searching with “--verbosity detailed” and “--format json” - [#13300](https://github.com/NuGet/Home/issues/13300) + +* `dotnet package search` crashes on .NET 9 preview 2 nightly - [#13286](https://github.com/NuGet/Home/issues/13286) + +* Use the StringBuilderPool rather than allocating a new StringBuilder - [#13285](https://github.com/NuGet/Home/issues/13285) + +* Pass in an appropriate size for List\ - [#13284](https://github.com/NuGet/Home/issues/13284) + +* JsonTextWriter allocates a large number strings - [#13283](https://github.com/NuGet/Home/issues/13283) + +* Usage of StringBuilder.Append() allocates when appending an int - [#13282](https://github.com/NuGet/Home/issues/13282) + +* Unnecessary boxing of struct enumerators - [#13281](https://github.com/NuGet/Home/issues/13281) + +* Process objects should be disposed so that the finalizer doesn't run - [#13280](https://github.com/NuGet/Home/issues/13280) + +* Avoid boxing enumerators for collections - [#13279](https://github.com/NuGet/Home/issues/13279) + +* [.NET 9 Preview 3] no-op restore is no longer a no-op - [#13269](https://github.com/NuGet/Home/issues/13269) + +* Reduce allocations in calling IVsProjectAdpater.IsCapabilityMatchAsync - [#13268](https://github.com/NuGet/Home/issues/13268) + +* Consolidate packages.config restore implementations by minimizing discrepancies - [#13233](https://github.com/NuGet/Home/issues/13233) + +* Unroll LINQ usage to trim some allocations in AddMSBuildAssets - [#13223](https://github.com/NuGet/Home/issues/13223) + +* PackageSpecWriter is calling Any on an ICollection\/IList\ instances instead of .Count - [#13213](https://github.com/NuGet/Home/issues/13213) + +* StringBuilder.Append(int) causes unnecessary allocations - [#13207](https://github.com/NuGet/Home/issues/13207) + +* Caching task results can cause all continuations to occur on the same thread - [#13206](https://github.com/NuGet/Home/issues/13206) + +* LibraryDependency creates a collection that is mostly empty - [#13184](https://github.com/NuGet/Home/issues/13184) + +* PackageSpecWriter should write out original string for versions instead of allocating a new one - [#13183](https://github.com/NuGet/Home/issues/13183) + +* SetCentralDependencies is calling OrderBy without specifying comparison defaulting to cultural-sensitive compare - [#13182](https://github.com/NuGet/Home/issues/13182) + +* Search results in json format from dotnet package search should not include fields for which no values are provided - [#13166](https://github.com/NuGet/Home/issues/13166) + +* The search result of the package should be “totalDownloads” instead of “total downloads” when executing command “dotnet package search \ --format json” - [#13165](https://github.com/NuGet/Home/issues/13165) + +* [dotnet package search] the failure to load a serivce index should be an error and not a warning. - [#13163](https://github.com/NuGet/Home/issues/13163) + +* dotnet package search format shows help output in addition to a json file - [#13161](https://github.com/NuGet/Home/issues/13161) + +* Cancelling static graph-based restore does not end the restore process - [#13140](https://github.com/NuGet/Home/issues/13140) + +* Use string.Contains instead of IEnumerable.Contains in VersionRange parsing - [#13124](https://github.com/NuGet/Home/issues/13124) + +* Static graph restore doesn't restore packages.config only solution - [#13109](https://github.com/NuGet/Home/issues/13109) + +* NuGet restore always touched the project.assets.json file even no content is changed when it needs log error messages. - [#13098](https://github.com/NuGet/Home/issues/13098) + +* Audit at restore time must not throw and fail the operation - [#13085](https://github.com/NuGet/Home/issues/13085) + +* Getting "An item with the same key has already been added" error when restoring. - [#13067](https://github.com/NuGet/Home/issues/13067) + +* PM UI Scrolling no longer loads additional packages. - [#13063](https://github.com/NuGet/Home/issues/13063) + +* NuGet restore cache check is no longer using file existence cache - [#13058](https://github.com/NuGet/Home/issues/13058) + +* Adding a reference to an esproj from an ASP.Net project results in a NU1105 error - [#12986](https://github.com/NuGet/Home/issues/12986) + +* RemoteDependencyWalker allocates a lot due to the fact that it's called recursively - [#12748](https://github.com/NuGet/Home/issues/12748) + +* [Bug]: Canceling msbuild restore is slow when invalid/unreachable source configured - [#11813](https://github.com/NuGet/Home/issues/11813) + +* Restore: excessive deep cloning of ProjectSpec - [#9041](https://github.com/NuGet/Home/issues/9041) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.9.1.3...6.10.0.97) + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +* [Erarndt](https://github.com/NuGet/NuGet.Client/pull/5659) + * [5659](https://github.com/NuGet/NuGet.Client/pull/5659) Reduce boxing when enumerating lists + * [5662](https://github.com/NuGet/NuGet.Client/pull/5662) Use StringBuilder.AppendInt() in more places to reduce allocations when appending integers to a StringBuilder + * [5663](https://github.com/NuGet/NuGet.Client/pull/5663) Remove allocations from TextWriter.NewLine implementation + * [5665](https://github.com/NuGet/NuGet.Client/pull/5665) Use pooled StringBuilder + * [5661](https://github.com/NuGet/NuGet.Client/pull/5661) Avoid enumerator boxing in PackageSpecificWarningProperties.AddRangeOfCodes and TransitiveNoWarnUtils.AddToSeen + * [5660](https://github.com/NuGet/NuGet.Client/pull/5660) Ensure that Process objects are disposed when launching authentication plug-ins + * [5664](https://github.com/NuGet/NuGet.Client/pull/5664) Specify list size in TopologicalSortUtility.CalculateRelationships + * [5624](https://github.com/NuGet/NuGet.Client/pull/5624) Switch CreateNodeAsync to an iterative approach + * [5584](https://github.com/NuGet/NuGet.Client/pull/5584) Unroll LINQ usage to trim some allocations in AddMSBuildAssets + * [5574](https://github.com/NuGet/NuGet.Client/pull/5574) Unroll several LINQ calls + * [5593](https://github.com/NuGet/NuGet.Client/pull/5593) Further reduce allocations in CreateGraphNodeAsync + * [5592](https://github.com/NuGet/NuGet.Client/pull/5592) Avoid multiple enumeration when writing Json objects + * [5600](https://github.com/NuGet/NuGet.Client/pull/5600) Avoid intermediate string allocation caused by StringBuilder Append(i… + * [5555](https://github.com/NuGet/NuGet.Client/pull/5555) Unroll Linq in GetFlags + * [5588](https://github.com/NuGet/NuGet.Client/pull/5588) Avoid boxing HashSet Enumerator in IsBestVerion + * [5589](https://github.com/NuGet/NuGet.Client/pull/5589) Update the pool implementation to use a stack with a lock to avoid al… + * [5568](https://github.com/NuGet/NuGet.Client/pull/5568) Change ResolvedDependencyKey to a struct + * [5553](https://github.com/NuGet/NuGet.Client/pull/5553) Avoid some allocations in GetCompatibilityData + * [5554](https://github.com/NuGet/NuGet.Client/pull/5554) Switch from Tuple to ValueTuple for Dictionary keys + * [5552](https://github.com/NuGet/NuGet.Client/pull/5552) Avoid creating the capture class for calls to WithExtension + * [5556](https://github.com/NuGet/NuGet.Client/pull/5556) Switch from ConcurrentDictionary to Dictionary with lock to avoid rep… + * [5551](https://github.com/NuGet/NuGet.Client/pull/5551) Use string.Contains instead of IEnumerable.Contains + * [5550](https://github.com/NuGet/NuGet.Client/pull/5550) Avoid boxing List\ enumerator +* [GenelleM](https://github.com/NuGet/NuGet.Client/pull/5655) + * [5655](https://github.com/NuGet/NuGet.Client/pull/5655) Add 64-bit non crypto hash algo for dgspec uniqueness computation + * [5629](https://github.com/NuGet/NuGet.Client/pull/5629) Replace calls to Any() on ICollection in PackageSpecWriter with Count > 0 Issue #13213 + * [5619](https://github.com/NuGet/NuGet.Client/pull/5619) Reduces some CPU time usage in SetCentralDependencies +* [NikolaMilosavljevic](https://github.com/NuGet/NuGet.Client/pull/5673) + * [5673](https://github.com/NuGet/NuGet.Client/pull/5673) Enable publishing in VMR + * [5625](https://github.com/NuGet/NuGet.Client/pull/5625) Eliminate System.CommandLine prebuilt package +* [brianrob](https://github.com/NuGet/NuGet.Client/pull/5650) + * [5650](https://github.com/NuGet/NuGet.Client/pull/5650) Add Restore Instrumentation diff --git a/docs/release-notes/NuGet-6.11.md b/docs/release-notes/NuGet-6.11.md new file mode 100644 index 000000000..0e74cce77 --- /dev/null +++ b/docs/release-notes/NuGet-6.11.md @@ -0,0 +1,107 @@ +--- +title: NuGet 6.11 Release Notes +description: Release notes for NuGet 6.11 including new features, bug fixes, and DCRs. +author: martinrrm +ms.date: 8/13/2024 +ms.topic: release-notes +--- +# NuGet 6.11 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.11**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.11](https://visualstudio.microsoft.com/downloads/) | [8.0.4xx](https://dotnet.microsoft.com/download/dotnet/8.0)1 | + +1 Installed with Visual Studio 2022 with any .NET workload + +## Summary: What's New in 6.11.1 + +### Issues fixed in this release + +* Fix "multiple attempts to download the nupkg have failed" - [#13545](https://github.com/NuGet/Home/issues/13545) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.11.0.122...6.11.1.2) + +## Summary: What's New in 6.11 + +* Suppress NuGetAudit warnings for specific advisories for PackageReference projects - [#13679](https://github.com/NuGet/Home/issues/13679) + +* Add `--allow-insecure-connections` option to dotnet SDK - [#13396](https://github.com/NuGet/Home/issues/13396) + +* Swap authors for owners in Visual Studio Package Manager UI - [#12501](https://github.com/NuGet/Home/issues/12501) + +* [Feature]: add dotnet nuget why to dotnet CLI - [#11943](https://github.com/NuGet/Home/issues/11943) + +* NuGet cannot restore from HTTPS sources that have SSL certificate problems - [#4387](https://github.com/NuGet/Home/issues/4387) + +### Breaking changes + +* `MSBuildRestoreUtility.GetRestoreAuditProperties` needs a breaking change to read `NuGetAuditSuppress` items - [#13313](https://github.com/NuGet/Home/issues/13313) + +### Issues fixed in this release + +* IVsNuGetProjectUpdateEvents.ProjectUpdateStarted or ProjectUpdateFinished should only provide a list of files that will get changed. - [#13413](https://github.com/NuGet/Home/issues/13413) + +* `dotnet nuget` commands should not output usage information on all errors - [#13251](https://github.com/NuGet/Home/issues/13251) + +* [DCR]: NuGet causes many ArgumentExceptions to be thrown & caught in VS - [#11535](https://github.com/NuGet/Home/issues/11535) + +* Remove .NET Framework TFM from NuGet.CommandLine.XPlat - [#8452](https://github.com/NuGet/Home/issues/8452) + +* PERF: GetPackageInfo allocates by unnecessarily calling GetNupkgMetadataPath - [#13556](https://github.com/NuGet/Home/issues/13556) + +* 'dotnet nuget why' crashes when using --framework option - [#13547](https://github.com/NuGet/Home/issues/13547) + +* SignatureUtility.GetCertificates in NuGet.Client can skip calling Dispose on error - [#13535](https://github.com/NuGet/Home/issues/13535) + +* 'dotnet nuget why' does not work when a directory is provided for the 'Path' argument - [#13527](https://github.com/NuGet/Home/issues/13527) + +* NuGet IntelliCode Package Suggestions are missing Author in packages list - [#13515](https://github.com/NuGet/Home/issues/13515) + +* Rebuilding in VS causes unnecessary restores - [#13505](https://github.com/NuGet/Home/issues/13505) + +* MSB4181: The "Restore Task" task returned false but did not log an error. - [#13460](https://github.com/NuGet/Home/issues/13460) + +* TaskResultCache incorrectly shares the same lock object for all the keys. - [#13448](https://github.com/NuGet/Home/issues/13448) + +* Calls to CompareTo and Equals should not allocate - [#13442](https://github.com/NuGet/Home/issues/13442) + +* Enable Nullable and throw in KnownOwnerViewModel - [#13425](https://github.com/NuGet/Home/issues/13425) + +* `PackageSourceProvider.UpdatePackageSource` doesn't respect a value from `disableTLSCertificateValidation` attribute - [#13423](https://github.com/NuGet/Home/issues/13423) + +* `PackageSourceProvider.UpdatePackageSource` doesn't respect a value from `AllowInsecureConnection` field - [#13418](https://github.com/NuGet/Home/issues/13418) + +* "nuget install -ExcludeVersion" inaccurate reports "already installed" when trying to install older version - [#13334](https://github.com/NuGet/Home/issues/13334) + +* Vulnerability InfoBar remains visible in the Solution Explorer after closing solution - [#13055](https://github.com/NuGet/Home/issues/13055) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.10.1.5...6.11.0.122) + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +* [seclerp](https://github.com/seclerp) + * [5783](https://github.com/NuGet/NuGet.Client/pull/5783) Fix `PackageSourceProvider.UpdatePackageSource` doesn't respect a value from `DisableTLSCertificateValidation` field + * [5767](https://github.com/NuGet/NuGet.Client/pull/5767) Fix `PackageSourceProvider.UpdatePackageSource` doesn't respect a value from `AllowInsecureConnection` field +* [mmitche](https://github.com/mmitche) + * [5749](https://github.com/NuGet/NuGet.Client/pull/5749) Build NuGet from the VMR + * [5752](https://github.com/NuGet/NuGet.Client/pull/5752) Fixup signing support conditional +* [ToddGrun](https://github.com/ToddGrun) + * [5859](https://github.com/NuGet/NuGet.Client/pull/5859) Reduce allocations in GetPackageInfo by conditionally calling GetNupkgMetadataPath +* [omajid](https://github.com/omajid) + * [5848](https://github.com/NuGet/NuGet.Client/pull/5848) Dispose certificates on failure in SignatureUtility.GetCertificates +* [SimonCropp](https://github.com/SimonCropp) + * [5842](https://github.com/NuGet/NuGet.Client/pull/5842) remove redundant .GetTypeInfo() +* [ryanmolden](https://github.com/ryanmolden) + * [5834](https://github.com/NuGet/NuGet.Client/pull/5834) Eliminate first-chance ArgumentExceptions when querying a legacy project for properties that don't exist via DTE +* [hickford](https://github.com/hickford) + * [5743](https://github.com/NuGet/NuGet.Client/pull/5743) Correct message in the case that a higher version of package is already installed +* [ViktorHofer](https://github.com/ViktorHofer) + * [5764](https://github.com/NuGet/NuGet.Client/pull/5764) Use .NET SDK sourcelink integration +* [NikolaMilosavljevic](https://github.com/NikolaMilosavljevic) + * [5738](https://github.com/NuGet/NuGet.Client/pull/5738) Disable CA2022 errors +* [jv42](https://github.com/jv42) + * [5717](https://github.com/NuGet/NuGet.Client/pull/5717) Fixed NullReferenceException in ResolverComparer diff --git a/docs/release-notes/NuGet-6.12.md b/docs/release-notes/NuGet-6.12.md new file mode 100644 index 000000000..51c3c9702 --- /dev/null +++ b/docs/release-notes/NuGet-6.12.md @@ -0,0 +1,181 @@ +--- +title: NuGet 6.12 Release Notes +description: Release notes for NuGet 6.12 including new features, bug fixes, and DCRs. +author: zivkan +ms.topic: release-notes +--- + +# NuGet 6.12 Release Notes + +> [!NOTE] +> In response to developers' feedback to ensure builds continuity when updating to .NET SDK 9, we have reverted the default value of NuGetAuditMode to `direct` in Visual Studio 17.12.3 and .NET 9.0.101. + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.12**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.12](https://visualstudio.microsoft.com/downloads/) | [9.0.1xx](https://dotnet.microsoft.com/download/dotnet/9.0)1 | +| [**6.12.4**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.12.8](https://visualstudio.microsoft.com/downloads/) | [9.0.106](https://dotnet.microsoft.com/download/dotnet/9.0)1 | + +1 Installed with Visual Studio 2022 with any .NET workload + +## Known Issues + +* Project and package in the same graph with the same name but different dependencies may lead to incorrect versions of the dependencies of that id [#13888](https://github.com/NuGet/Home/issues/13888) +* VS PM UI shows warning icon about package vulnerability even after upgrade [#13866](https://github.com/NuGet/Home/issues/13866) +* dotnet nuget why reports missing argument, even though it ran [#13908](https://github.com/NuGet/Home/issues/13908) + +## Summary: What's New in 6.12.4 + +NuGet 6.12.4 is available in Visual Studio 17.12.8. + +### Issues fixed in this release + +* Restore should fail more quickly when using http sources - [#14210](https://github.com/NuGet/Home/issues/14210) + +## Summary: What's New in 6.12.3 + +NuGet 6.12.3 is available in Visual Studio 17.12.4. + +### Issues fixed in this release + +* Small Solution PM UI size can cause a System.ArgumentException SolutionView.ListView_SizeChanged - [#13928](https://github.com/NuGet/Home/issues/13928) + +## Summary: What's New in 6.12.1 + +NuGet 6.12.1 is available in Visual Studio 17.12.0 and the .NET 9.0.101 SDK. + +### Issues fixed in this release + +* Deserializing an empty version range in a package dependency fails in .NET SDK 9.0.100-rc.2 [#13869](https://github.com/NuGet/Home/issues/13869) + +## Summary: What's New in 6.12 + +NuGet 6.12.0 is available in the .NET 9.0.100 SDK. + +* Add new graph resolution algorithm for better performance with large graphs - [#13692](https://github.com/NuGet/Home/issues/13692) + +* NuGetAudit raises warnings for vulnerable transitive packages by default when the .NET 9 SDK is installed [#13293](https://github.com/NuGet/Home/issues/13293) + +* Change NuGetAuditMode default from direct to all, raising warnings for vulnerable transitive packages for non-SDK style projects - [#13584](https://github.com/NuGet/Home/issues/13584) + +* Audit security vulnerabilities without adding nuget.org as package source - [#12698](https://github.com/NuGet/Home/issues/12698) + +* Owner profile hyperlinks needed in Details Pane of PM UI - [#13686](https://github.com/NuGet/Home/issues/13686) + +* Deprecate SHA-1 fingerprints usage in NuGet Sign commands in favor of SHA-2 family fingerprints [#13891](https://github.com/NuGet/Home/issues/13891) + +* Bubble-up Known Vulnerability Indicators in Solution Explorer for Transitive Packages - [#13636](https://github.com/NuGet/Home/issues/13636) + +* Enable Transitive Dependencies and vulnerabilities for Solution-level in Visual Studio - [#13216](https://github.com/NuGet/Home/issues/13216) + +### Breaking changes + +* Deprecate http usage: Promote from warning to error - [#13289](https://github.com/NuGet/Home/issues/13289) + +### Issues fixed in this release + +* Enable `dotnet nuget why` on non-SDK style projects - [#13576](https://github.com/NuGet/Home/issues/13576) + +* NuGetAuditSuppress for packages.config - [#13575](https://github.com/NuGet/Home/issues/13575) + +* Roll-out new breaking change process for SDK tools, respect SdkAnalysisLevel - [#13309](https://github.com/NuGet/Home/issues/13309) + +* Add property for toggling the to the previous NuGet resolver: RestoreUseLegacyDependencyResolver - [#13700](https://github.com/NuGet/Home/issues/13700) + +* Reduce allocations in TokenSegment.TryMatch - [#12728](https://github.com/NuGet/Home/issues/12728) + +* Use `SDKAnalysisLevel` in restore "https everywhere: promote from warning to error" - [#13546](https://github.com/NuGet/Home/issues/13546) + +* tweak wording of NU1603 - [#13446](https://github.com/NuGet/Home/issues/13446) + +* Default Package icon shown even when embedded icon file exists on disk - [#13766](https://github.com/NuGet/Home/issues/13766) + +* Navigation telemetry for hyperlinks: License, ReportAbuse, Readme, ProjectUrl - [#13749](https://github.com/NuGet/Home/issues/13749) + +* Navigation telemetry for Owner Profile URLs in PM UI - [#13738](https://github.com/NuGet/Home/issues/13738) + +* PM UI should show transitive path - [#13574](https://github.com/NuGet/Home/issues/13574) + +* NuGetVersion should use a factory to intern parsed versions - [#13532](https://github.com/NuGet/Home/issues/13532) + +* Remove NuGet.Packaging.Core code - [#13385](https://github.com/NuGet/Home/issues/13385) + +* PM UI transitive dependencies should display all transitive dependencies, not just ones brought in through packages directly installed in a project - [#13060](https://github.com/NuGet/Home/issues/13060) + +* Remove deprecated field "owners" from VS UI Details Pane - [#10666](https://github.com/NuGet/Home/issues/10666) + +* "Value cannot be null; Parameter name: source" displays in error list when clicking installed tab in PM UI - [#13801](https://github.com/NuGet/Home/issues/13801) + +* New dependency resolver does not properly handle missing package versions when using CPM - [#13788](https://github.com/NuGet/Home/issues/13788) + +* Saving PackageManagementFormat throws Nullable object must have a value. - [#13773](https://github.com/NuGet/Home/issues/13773) + +* ProjectReference causing PM UI to error with "Value cannot be null. Parameter name: frameworkIdentifier" - [#13737](https://github.com/NuGet/Home/issues/13737) + +* LockFileUtils.CreateLockFileTargetProject allocates a lot - [#13712](https://github.com/NuGet/Home/issues/13712) + +* ConvertToProjectPaths causes extra allocations due to yield usage - [#13677](https://github.com/NuGet/Home/issues/13677) + +* dotnet add package with CPM installs a different version than what gets restored - [#13657](https://github.com/NuGet/Home/issues/13657) + +* `dotnet list package` does not work if project is using central package management system, after upgrading to `.NET 8.0` - [#13632](https://github.com/NuGet/Home/issues/13632) + +* Add a log code NuGetAuditSuppress duplicate items - [#13620](https://github.com/NuGet/Home/issues/13620) + +* Solution Explorer search can be broken by skipped dataflow updates - [#13619](https://github.com/NuGet/Home/issues/13619) + +* Add nullability declarations to ResolverUtility and RemoteWalkContext - [#13617](https://github.com/NuGet/Home/issues/13617) + +* Use of Obsolete X509Certificate2 ctor - [#13612](https://github.com/NuGet/Home/issues/13612) + +* nuget restore warnings can't be suppressed with NoWarn in Visual Studio - [#13571](https://github.com/NuGet/Home/issues/13571) + +* Restore may write nulls to project.assets.json - [#13563](https://github.com/NuGet/Home/issues/13563) + +* VS 17.10 - Error building projects with CPM explicitly enabled if ManagePackageVersionsCentrally is set to false in Directory.Build.props - [#13560](https://github.com/NuGet/Home/issues/13560) + +* PERF: Version and VersionRange allocations are very prevalent in profiles of Roslyn solution load - [#13559](https://github.com/NuGet/Home/issues/13559) + +* PERF: LockFileFormat is filled completely when common callers only need some of the data - [#13558](https://github.com/NuGet/Home/issues/13558) + +* PERF: Unnecessary construction of LockFileItem.Properties dictionary - [#13557](https://github.com/NuGet/Home/issues/13557) + +* Narator does not read the value of `allowInsecureConnections` - [#13555](https://github.com/NuGet/Home/issues/13555) + +* NuGet fails because of invalid characters in User-Agent header - [#13531](https://github.com/NuGet/Home/issues/13531) + +* 'why' and 'config' command does not show up in 'dotnet nuget --help' output - [#13517](https://github.com/NuGet/Home/issues/13517) + +* allocation: nuget.protocol.dll!NuGet.Protocol.HttpCacheUtility+<CreateCacheFileAsync>d__.MoveNext|nuget.protocol.dll!NuGet.Protocol.PackageDependencyGroupConverter.ReadJson - [#13445](https://github.com/NuGet/Home/issues/13445) + +* Reduce allocations in ContentItemCollection - [#12657](https://github.com/NuGet/Home/issues/12657) + +* When a source isn't accessible, service index cannot be read issues suppress the internal message making it difficult to understand the root cause - [#12530](https://github.com/NuGet/Home/issues/12530) + +* [Bug]: Extra space at start of package description in tooltip - [#12105](https://github.com/NuGet/Home/issues/12105) + +* Map branch name from sourcelink to RepositoryBranch for NuGet pack - [#13625](https://github.com/NuGet/Home/issues/13625) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.12.1.1...6.11.1.2) + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +* [akoeplinger](https://github.com/NuGet/NuGet.Client/pull/6005) + * [6005](https://github.com/NuGet/NuGet.Client/pull/6005) Improve build.sh and fixes for building on arm64 macOS + * [5956](https://github.com/NuGet/NuGet.Client/pull/5956) Add System.Formats.Asn1 into Version.Details.xml + * [5911](https://github.com/NuGet/NuGet.Client/pull/5911) Don't use obsolete X509Certificate2 constructor on net9.0 +* [ToddGrun](https://github.com/NuGet/NuGet.Client/pull/5862) + * [5862](https://github.com/NuGet/NuGet.Client/pull/5862) Reduce allocations for version / versionranges + * [5857](https://github.com/NuGet/NuGet.Client/pull/5857) Reduce memory allocations during solution load in VS + * [5861](https://github.com/NuGet/NuGet.Client/pull/5861) Defer LockFileItem.Properties dictionary construction until needed +* [KirillOsenkov](https://github.com/NuGet/NuGet.Client/pull/6008) + * [6008](https://github.com/NuGet/NuGet.Client/pull/6008) Always debug RestoreTask and RestoreEx when environment variable is set +* [vernou](https://github.com/NuGet/NuGet.Client/pull/5982) + * [5982](https://github.com/NuGet/NuGet.Client/pull/5982) Fix restore when a package is installed with a version specified in CPM +* [mthalman](https://github.com/NuGet/NuGet.Client/pull/5959) + * [5959](https://github.com/NuGet/NuGet.Client/pull/5959) Allow override of System.Formats.Asn1 package version +* [MattKotsenas](https://github.com/NuGet/NuGet.Client/pull/5923) + * [5923](https://github.com/NuGet/NuGet.Client/pull/5923) Map SourceBranchName from sourcelink to RepositoryBranch for NuGet pack diff --git a/docs/release-notes/NuGet-6.13.md b/docs/release-notes/NuGet-6.13.md new file mode 100644 index 000000000..1c09115b4 --- /dev/null +++ b/docs/release-notes/NuGet-6.13.md @@ -0,0 +1,136 @@ +--- +title: NuGet 6.13 Release Notes +description: Release notes for NuGet 6.13 including new features, bug fixes, and DCRs. +author: Nigusu-Allehu +ms.author: nyenework +ms.date: 2/4/2025 +ms.topic: release-notes +--- + +# NuGet 6.13 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.13.0**](https://nuget.org/downloads) | N/A | [9.0.200](https://dotnet.microsoft.com/download/dotnet/9.0)1 | +| [**6.13.1**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.13.0](https://visualstudio.microsoft.com/downloads/) | [9.0.201](https://dotnet.microsoft.com/download/dotnet/9.0)1 | +| [**6.13.2**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.13.2](https://visualstudio.microsoft.com/downloads/) | [9.0.203](https://dotnet.microsoft.com/download/dotnet/9.0)1 | + +1 Installed with Visual Studio 2022 with any .NET workload + +## Summary: What's New in 6.13.2 + +* New restore dependency resolver fails when resolving identical child dependencies - [#14025](https://github.com/NuGet/Home/issues/14025) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.13.1.3...6.13.2.1) + +## Summary: What's New in 6.13.1 + +NuGet 6.13.1 is available in Visual Studio 17.13 and .NET 9.0.201 SDK. + +* Support for new slnx solution format in dotnet nuget why and dotnet list package - [#14034](https://github.com/NuGet/Home/issues/14034) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.13.0.113...6.13.1.3) + +## Summary: What's New in 6.13.0 + +NuGet 6.13.0 is available in the .NET 9.0.200 SDK. + +* Support for credential providers deployed via .NET tools - [#12567](https://github.com/NuGet/Home/issues/12567) + +* Opt-in feature: "Supplied by Platform", which removes packages that are supplied by the .NET platform from the dependency graph. This results in better performance and eliminates false positives for vulnerabilities in transitive dependencies. + +* dotnet nuget why should check RID specific packages - [#13718](https://github.com/NuGet/Home/issues/13718) + +* Allow specifying the msbuild binlog path when invoking static graph restore to avoid modifying the environment - [#10789](https://github.com/NuGet/Home/issues/10789) + +* New Dependency Resolver Fixes + + * New dependency resolver downloads more packages than before - [#13943](https://github.com/NuGet/Home/issues/13943) + + * New dependency resolver does not handle floating versions correctly in some situations - [#13992](https://github.com/NuGet/Home/issues/13992) + + * New dependency resolver erroneously reports NU1605 (downgrade) when using transitive pinning a direct dependency and a downgrade exists in a package graph - [#13938](https://github.com/NuGet/Home/issues/13938) + + * NuGet Restore restoring old versions of transitive dependencies when direct dependency does not have guidelines for user's targeted .NET Framework - [#13934](https://github.com/NuGet/Home/issues/13934) + + * Project and package in the same graph with the same name but different dependencies may lead to incorrect versions of the dependencies of that id - [#13888](https://github.com/NuGet/Home/issues/13888) + +* Package Manager UI in Visual Studio now shows embedded READMEs for NuGet packages, if available - [#12583](https://github.com/NuGet/Home/issues/12583) + +### Issues fixed in this release + +* Detect if restore used NuGetAudit or not for PackageReference projects - [#13778](https://github.com/NuGet/Home/issues/13778) + +* Add indicator for deprecated and vulnerable packages to Package Details tab header. - [#13974](https://github.com/NuGet/Home/issues/13974) + +* Navigation telemetry for 'Clear All NuGet Storage' Command in VS Settings - [#13968](https://github.com/NuGet/Home/issues/13968) + +* Nuget Package Manager for Solution automatically selects transitive dependencies - [#13893](https://github.com/NuGet/Home/issues/13893) + +* Debugging large repos with static graph-based restore is slow - [#13876](https://github.com/NuGet/Home/issues/13876) + +* NuGet Client SDK packages updating to net8.0 - [#13842](https://github.com/NuGet/Home/issues/13842) + +* Promote NU3043 warning to error in .NET 10 - [#13814](https://github.com/NuGet/Home/issues/13814) + +* Setting "Allow format selection on first package install" meaning is unclear - [#14016](https://github.com/NuGet/Home/issues/14016) + +* `dotnet nuget why` reports missing argument, even though it ran - [#13908](https://github.com/NuGet/Home/issues/13908) + +* Spacing adjustments in Details Pane Tabs - [#13880](https://github.com/NuGet/Home/issues/13880) + +* The focus border on the Details Pane Tab content is being truncated - [#13879](https://github.com/NuGet/Home/issues/13879) + +* JAWS is reading the entire contents of the Package Details Tab when first visiting it - [#13878](https://github.com/NuGet/Home/issues/13878) + +* ContentItemCollection.PopulateItemGroups unnecessarily allocates - [#13851](https://github.com/NuGet/Home/issues/13851) + +* Read and write .nupkg.metadata files with System.Text.Json - [#13835](https://github.com/NuGet/Home/issues/13835) + +* NuGet Fails in Containers When HOME Is Not Set - [#13834](https://github.com/NuGet/Home/issues/13834) + +* Signing: key not disposed - [#13823](https://github.com/NuGet/Home/issues/13823) + +* Walk TFMs in parallel when collecting pack outputs - [#13776](https://github.com/NuGet/Home/issues/13776) + +* PERF: NuGet Cloning operations are showing heavily in allocations during VS solution load - [#13647](https://github.com/NuGet/Home/issues/13647) + +* Fetching Vulnerability Resources doesn't respect cancellation - [#13644](https://github.com/NuGet/Home/issues/13644) + +* Wrong order of arguments in logs for centralized package version (string `Info_AddPkgCPM`) - [#13155](https://github.com/NuGet/Home/issues/13155) + +* Satellite assemblies for three-letter languages are not copied from NuGet package - [#12253](https://github.com/NuGet/Home/issues/12253) + +* Nuget pack doesn't support blank <version> in .nuspec even though version is passed on the command line - [#7987](https://github.com/NuGet/Home/issues/7987) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.12.3.1...6.13.1.3) + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +* [SimonCropp](https://github.com/NuGet/NuGet.Client/pull/6185) + * [6185](https://github.com/NuGet/NuGet.Client/pull/6185) reduce memory in ManifestMetadata + * [6168](https://github.com/NuGet/NuGet.Client/pull/6168) remove duplicate dictionary lookups + * [6166](https://github.com/NuGet/NuGet.Client/pull/6166) remove redundant Count() in GlobalPackageFolderRepositories + * [6165](https://github.com/NuGet/NuGet.Client/pull/6165) avoid Any call in GetCommandAttribute + * [6167](https://github.com/NuGet/NuGet.Client/pull/6167) remove redundant casts +* [baronfel](https://github.com/NuGet/NuGet.Client/pull/6124) + * [6124](https://github.com/NuGet/NuGet.Client/pull/6124) Expand Locale parser to support three-character language codes + * [6018](https://github.com/NuGet/NuGet.Client/pull/6018) Update _WalkEachTargetPerFramework to walk TFMs in parallel +* [ToddGrun](https://github.com/NuGet/NuGet.Client/pull/6098) + * [6098](https://github.com/NuGet/NuGet.Client/pull/6098) Modify ContentItemCollection.PopulateItemGroups to use pooling for highly allocated temporary data structures + * [5930](https://github.com/NuGet/NuGet.Client/pull/5930) Attempt to move several data structures to be immutable +* [mthalman](https://github.com/NuGet/NuGet.Client/pull/6212) + * [6212](https://github.com/NuGet/NuGet.Client/pull/6212) Fix formatting in GraphOperations +* [kasperk81](https://github.com/NuGet/NuGet.Client/pull/6072) + * [6072](https://github.com/NuGet/NuGet.Client/pull/6072) add SpecialFolder.UserProfile fallback +* [MichaelSimons](https://github.com/NuGet/NuGet.Client/pull/6102) + * [6102](https://github.com/NuGet/NuGet.Client/pull/6102) Update source-build team references +* [akoeplinger](https://github.com/NuGet/NuGet.Client/pull/6025) + * [6025](https://github.com/NuGet/NuGet.Client/pull/6025) Fix typo in EnhancedHttpRetryHelper.cs +* [jimmylewis](https://github.com/NuGet/NuGet.Client/pull/6027) + * [6027](https://github.com/NuGet/NuGet.Client/pull/6027) Refactor calls to EnsureVisualStudioHost() to a base [TestInitialize] method + diff --git a/docs/release-notes/NuGet-6.14.md b/docs/release-notes/NuGet-6.14.md new file mode 100644 index 000000000..d14104ce5 --- /dev/null +++ b/docs/release-notes/NuGet-6.14.md @@ -0,0 +1,131 @@ +--- +title: NuGet 6.14 Release Notes +description: Release notes for NuGet 6.14 including new features, bug fixes, and DCRs. +author: zivkan +ms.date: 5/6/2025 +ms.topic: release-notes +--- + +# NuGet 6.14 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.14.0**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.14.0](https://visualstudio.microsoft.com/downloads/) | [9.0.300](https://dotnet.microsoft.com/download/dotnet/9.0)1 | + +1 Installed with Visual Studio 2022 with any .NET workload + +## Summary: What's New in 6.14.0 + +* (preview feature) NuGet onboards to Unified Settings and create General page - [#14040](https://github.com/NuGet/Home/issues/14040) + +* Support for new `slnx` solution format - [#14034](https://github.com/NuGet/Home/issues/14034) + +* dotnet-nuget-push now supports --config-file - [#4879](https://github.com/NuGet/Home/issues/4879) + +* `dotnet list package --vulnerable` should support auditSources - [#13767](https://github.com/NuGet/Home/issues/13767) + +* [DCR]: Focus shifts from Output window to Error List after every package operation, even with no error or warnings - [#11728](https://github.com/NuGet/Home/issues/11728) + +### Issues fixed in this release + +* Event tracing in new dependency resolver - [#14134](https://github.com/NuGet/Home/issues/14134) + +* Support for new slnx format in static graph-based restore - [#14086](https://github.com/NuGet/Home/issues/14086) + +* Add Net90 to FrameworkConstants.CommonFrameworks - [#14067](https://github.com/NuGet/Home/issues/14067) + +* Don't show usage help when dotnet cli command throws unhandled exception - [#14200](https://github.com/NuGet/Home/issues/14200) + +* Multiple callers check for NuGet entries before calling Error List `BringToFrontIfSettingsPermitAsync` - [#14163](https://github.com/NuGet/Home/issues/14163) + +* NuGetAudit should report transitive packages with vulnerabilities when targeting .NET 10 or higher - [#14161](https://github.com/NuGet/Home/issues/14161) + +* Update README preview to render with same font size as Visual Studio - [#14112](https://github.com/NuGet/Home/issues/14112) + +* NU5100 (AssemblyOutsideLibWarning): Why build is allowed but buildTransitive is not? - [#14080](https://github.com/NuGet/Home/issues/14080) + +* Can't copy the text from NuGet package manager gold bar - [#14074](https://github.com/NuGet/Home/issues/14074) + +* NuGet 6.13.2.1 does no longer support prerelease versions - [#14219](https://github.com/NuGet/Home/issues/14219) + +* Badly specified framework leads to an uninformative error - [#14216](https://github.com/NuGet/Home/issues/14216) + +* Restore should fail more quickly when using http sources - [#14210](https://github.com/NuGet/Home/issues/14210) + +* README spins indefinitely if the Readme URI does not result in a readme - [#14201](https://github.com/NuGet/Home/issues/14201) + +* Error in Visual Studio if Path contains directory you do not have permission to view - [#14192](https://github.com/NuGet/Home/issues/14192) + +* list package doesn't work with a solution argument in 9.0.201 - [#14177](https://github.com/NuGet/Home/issues/14177) + +* Focus shifts from Output window to Error List after Clear NuGet Locals command - [#14157](https://github.com/NuGet/Home/issues/14157) + +* NuGet adding a bunch of generally unuseful information to VS activity log - [#14153](https://github.com/NuGet/Home/issues/14153) + +* NuGet authentication plug-in discovery fails when environment variable has trailing semicolon - [#14144](https://github.com/NuGet/Home/issues/14144) + +* nuget.exe fails to find Microsoft.VisualStudio.SolutionPersistence.dll - [#14136](https://github.com/NuGet/Home/issues/14136) + +* NuGet restore writes dgspec too frequently - [#14135](https://github.com/NuGet/Home/issues/14135) + +* dotnet list package does not display resolved versions when AuditSources are used - [#14116](https://github.com/NuGet/Home/issues/14116) + +* The REAMDE tab always shows “Loading README” for the latest version of the package in the detail panel of PM UI - [#14098](https://github.com/NuGet/Home/issues/14098) + +* [Bug Bash] The second time clicking ‘Installed’ tab for a remote source which doesn’t allow for downloading a README shows the README tab - [#14097](https://github.com/NuGet/Home/issues/14097) + +* HttpFileSystemBasedFindPackageByIdResource.ConsumeFlatContainerIndexAsync allocates significantly more than necessary - [#14095](https://github.com/NuGet/Home/issues/14095) + +* UnresolvedMessages.GetMessageAsync is allocating more heavily than necessary - [#14094](https://github.com/NuGet/Home/issues/14094) + +* New dependency resolver does not properly detect a cycle with a transitive dependency with the same name as the root project - [#14052](https://github.com/NuGet/Home/issues/14052) + +* dotnet nuget why does not give an error if only a project path was specified - [#14030](https://github.com/NuGet/Home/issues/14030) + +* Cleanup ServiceProviderExtensions, remove GetFreeThreadedServiceAsync - [#14007](https://github.com/NuGet/Home/issues/14007) + +* Value cannot be null. Parameter name: versionRange when opening the PM UI - [#13933](https://github.com/NuGet/Home/issues/13933) + +* Reenable new algorithm resolution with lock files with .NET 10 SDK - [#13800](https://github.com/NuGet/Home/issues/13800) + +* Report the path when unable to read corrupted .nupkg.metadata - [#13763](https://github.com/NuGet/Home/issues/13763) + +* [Bug Bash] The vulnerability InfoBar disappears in the Solution Explorer window after restoring packages for .NET SDK based project - [#13318](https://github.com/NuGet/Home/issues/13318) + +* Use System.Text.Json to read the cache file in CacheFileFormat - [#13059](https://github.com/NuGet/Home/issues/13059) + +* [Bug]: dotnet nuget push symbols not working as expected - [#11871](https://github.com/NuGet/Home/issues/11871) + +* nuget.exe restore fails when MSBuildPath ends with a slash - [#8634](https://github.com/NuGet/Home/issues/8634) + +* nuget.exe -msbuildpath c:\foo\msbuild.exe gives bad error experience - [#4195](https://github.com/NuGet/Home/issues/4195) + +* Address comments in `Implement Support for NuGet Authentication Plugins as .NET Tools` PR - [#13975](https://github.com/NuGet/Home/issues/13975) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.13.2.1...6.14.0.116) + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +* [ViktorHofer](https://github.com/NuGet/NuGet.Client/pull/6309) + * [6309](https://github.com/NuGet/NuGet.Client/pull/6309) Define MicrosoftVisualStudioSolutionPersistenceVersion property + * [6292](https://github.com/NuGet/NuGet.Client/pull/6292) Upgrade ProtectedData version when building source-only + * [6270](https://github.com/NuGet/NuGet.Client/pull/6270) Update dependencies and remove unused runtime dependencies + * [6261](https://github.com/NuGet/NuGet.Client/pull/6261) React to NuGet package pruning warnings +* [jkoritzinsky](https://github.com/NuGet/NuGet.Client/pull/6306) + * [6306](https://github.com/NuGet/NuGet.Client/pull/6306) Don't publish RID-agnostic nuget packages when we only want RID-specific artifacts + * [6233](https://github.com/NuGet/NuGet.Client/pull/6233) Use the documented Artifact extension point to add artifacts +* [ToddGrun](https://github.com/NuGet/NuGet.Client/pull/6294) + * [6294](https://github.com/NuGet/NuGet.Client/pull/6294) Reduce activity log output from VsSolutionRestoreService.NominateProjectAsync + * [6264](https://github.com/NuGet/NuGet.Client/pull/6264) Reduce allocations under UnresolvedMessages.GetMessageAsync +* [AlexDelepine](https://github.com/NuGet/NuGet.Client/pull/6338) + * [6338](https://github.com/NuGet/NuGet.Client/pull/6338) Update ngen Priorities for VS +* [mmitche](https://github.com/NuGet/NuGet.Client/pull/6305) + * [6305](https://github.com/NuGet/NuGet.Client/pull/6305) Set build number to arcade build revision for VMR builds +* [premun](https://github.com/NuGet/NuGet.Client/pull/6251) + * [6251](https://github.com/NuGet/NuGet.Client/pull/6251) Remove extra spaces in Publishing.props +* [baronfel](https://github.com/NuGet/NuGet.Client/pull/6219) + * [6219](https://github.com/NuGet/NuGet.Client/pull/6219) Use new serializer library to parse solution files diff --git a/docs/release-notes/NuGet-6.2.md b/docs/release-notes/NuGet-6.2.md new file mode 100644 index 000000000..dc09706ea --- /dev/null +++ b/docs/release-notes/NuGet-6.2.md @@ -0,0 +1,147 @@ +--- +title: NuGet 6.2 Release Notes +description: Release notes for NuGet 6.2 including new features, bug fixes, and DCRs. +author: martinrrm +ms.author: mruizmares +ms.date: 5/9/2022 +ms.topic: release-notes +--- + +# NuGet 6.2 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.2.0**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.2](https://visualstudio.microsoft.com/downloads/) | [6.0.300](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | +| [**6.2.1**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.2.4](https://visualstudio.microsoft.com/downloads/) | [6.0.301](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | +| [**6.2.2**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.2](https://visualstudio.microsoft.com/downloads/) | [6.0.305](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | +| [**6.2.4**](https://nuget.org/downloads) | N/A | [6.0.313](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | + +1 Installed with Visual Studio 2022 with .NET Core workload + +## Summary: What's New in 6.2.4 + +* [Security]: Microsoft Security Advisory CVE-2023-29337 | NuGet Client Remote Code Execution Vulnerability - [#12653](https://github.com/NuGet/Home/issues/12653) + +> [!NOTE] +> There is a behavior breaking change on Linux. The temp folder location, where NuGet stores temporary files during its various operations, has changed from `/tmp/NuGetScratch` to `/tmp/NuGetScratch`. E.g. for user User1, the temp folder will be `/tmp/NuGetScratchUser1`. + +## Summary: What's New in 6.2.2 + +* [Security]: Microsoft Security Advisory CVE 2022-41032 | .NET Elevation of Privilege Vulnerability - [#12149](https://github.com/NuGet/Home/issues/12149) + +## Summary: What's New in 6.2.1 + +* [Security]: Microsoft Security Advisory CVE 2022-30184 | .NET Information Disclosure Vulnerability - [#11883](https://github.com/NuGet/Home/issues/11883) + +## Summary: What's New in 6.2 + +* Add TFM for .NET nanoFramework - [#10800](https://github.com/NuGet/Home/issues/10800) + +* [Feature]: Require package source mapping when using CPM - [#11505](https://github.com/NuGet/Home/issues/11505) + +* [Feature]: Allow overriding a centrally defined package version - [#11516](https://github.com/NuGet/Home/issues/11516) + +* [Feature]: Add IVsNuGetProjectUpdateEvents in Visual Studio, reporting of restore changes for PackageReference based projects. - [#9782](https://github.com/NuGet/Home/issues/9782) - [See documentation](../visual-studio-extensibility/nuget-api-in-visual-studio.md#ivsnugetprojectupdateevents-interface) + +* Project A referencing package B via AssetTargetFallback, doesn't use that same AssetTargetFallback to pull B's dependency package C - [#5957](https://github.com/NuGet/Home/issues/5957) - [More information](https://github.com/NuGet/Samples/tree/main/AssetTargetFallbackTransitiveDependencies) + +### Issues fixed in this release + +**DCRs:** + +* Make LocalPackageFileCache methods virtual - [#10325](https://github.com/NuGet/Home/issues/10325) + +* NuGetScratch lock files are not cleaned up - [#10679](https://github.com/NuGet/Home/issues/10679) + +* AutoCompleteResourceV3 does not use the supplied logger - [#11272](https://github.com/NuGet/Home/issues/11272) + +* Add Author to the tooltip for a package in the packages list of PM UI - [#11499](https://github.com/NuGet/Home/issues/11499) + +* Remove unused code NU5049 - [#11598](https://github.com/NuGet/Home/issues/11598) + +**Bugs:** + +* Revert mitigation of missing nuget.org when other tools create nuget.config [#11616](https://github.com/NuGet/Home/issues/11616) + +* Add support for grouping to the InfiniteScrollList, allowing it to be enabled or disabled - [#10748](https://github.com/NuGet/Home/issues/10748) + +* Make the InfiniteScrollList grouping sections expandable and collapsible - [#10749](https://github.com/NuGet/Home/issues/10749) + +* Read and store the transitive origins of a package while reading installed packages from assets file - [#10751](https://github.com/NuGet/Home/issues/10751) + +* Add caching of the transitive dependencies data pulled from the lockfile (assets file) - [#10752](https://github.com/NuGet/Home/issues/10752) + +* Surface the transitive packages and its transitive origins through the search layer - [#11486](https://github.com/NuGet/Home/issues/11486) + +* NuGet.exe list from local packages folder does not work with the AllVersion flag - [#4537](https://github.com/NuGet/Home/issues/4537) + +* Errors due to missing/failing sources are inconsistently shown in solution explorer vs the error list - [#7245](https://github.com/NuGet/Home/issues/7245) + +* Arrow keys in NuGet PM UI Sources editing doesn't change order of persistence - [#8315](https://github.com/NuGet/Home/issues/8315) + +* PackageReference ungracefully handles duplicate Runtime Identifiers in csproj PackageReference - [#9290](https://github.com/NuGet/Home/issues/9290) + +* RestoreIgnoreFailedSources=true still gives warnings - [#9765](https://github.com/NuGet/Home/issues/9765) + +* Introduce a warning for null/empty version range (new or reuse NU1604) - [#9767](https://github.com/NuGet/Home/issues/9767) + +* NuGet again throwing exceptions "authors is required" "description is required", ignoring csproj/nuspec replacement tokens - [#9954](https://github.com/NuGet/Home/issues/9954) + +* [Bug]: Package extraction sometimes fails with "file in use by another process" - [#11373](https://github.com/NuGet/Home/issues/11373) + +* Add progress reporting during package installation - [#11432](https://github.com/NuGet/Home/issues/11432) + +* [Bug]: Reduce string allocations in restore code path - [#11475](https://github.com/NuGet/Home/issues/11475) + +* [Responsiveness] RestoreOperationLogger blocking large number of thread pool threads trying to get access to the output window pane - [#11501](https://github.com/NuGet/Home/issues/11501) + +* [Responsiveness] Package Management UI can consume large number of threads all searching the disk, it needs to run from long running thread - [#11570](https://github.com/NuGet/Home/issues/11570) + +* [Responsiveness] Package Management UI can consume large number of threads all searching the disk (up to 316 threads), use cancellation token at subroutines - [#11599](https://github.com/NuGet/Home/issues/11599) + +* [Bug]: NU1004 in Visual Studio, but not command line (lock files in locked mode) - [#11639](https://github.com/NuGet/Home/issues/11639) + +* [Bug]: new warning for package source mappings doesn't pass a value for the resource string placeholder - [#11709](https://github.com/NuGet/Home/issues/11709) + + +**[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.1.0.80%5E...6.2.0.146)** + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +|Who|PRs|Issues| +|----|----|----| +[MarkKharitonov](https://github.com/MarkKharitonov) | [4511](https://github.com/nuget/nuget.client/pull/4511) | [Feature]: Add support for a dedicated environment variable providing the NuGetScratch path. - [#11671](https://github.com/NuGet/Home/issues/11671) +[mfkl](https://github.com/mfkl) | [4222](https://github.com/nuget/nuget.client/pull/4222) | A better cache clean-up and expiration policy - [#4980](https://github.com/NuGet/Home/issues/4980) +[dfederm](https://github.com/dfederm) | [4504](https://github.com/nuget/nuget.client/pull/4504) | Static Graph restore uses Project.FromFile + Project.CreateInstance instead of ProjectInstance.FromFile directly - [#11675](https://github.com/NuGet/Home/issues/11675) +[crummel](https://github.com/crummel) | [4404](https://github.com/nuget/nuget.client/pull/4404) | [main] Backport source-build patches to repos. [#2708](https://github.com/dotnet/source-build/issues/2708) +[mjolka](https://github.com/mjolka) | [4475](https://github.com/nuget/nuget.client/pull/4475) | Very slow restore when using NoWarn in single project that has lots of dependents - [#11222](https://github.com/NuGet/Home/issues/11222) +[marcin-krystianc](https://github.com/marcin-krystianc) | [4488](https://github.com/nuget/nuget.client/pull/4488) | dotnet integration pack test IL issue - [#11454](https://github.com/NuGet/Home/issues/11454) +[marcin-krystianc](https://github.com/marcin-krystianc) | [4025](https://github.com/nuget/nuget.client/pull/4025) | Restore fails with NU1106 for solution that uses StaticGraph and CPVM - [#10327](https://github.com/NuGet/Home/issues/10327); [Feature]: Add option to allow versions of transitive dependencies to be overridden - [#10389](https://github.com/NuGet/Home/issues/10389) +[davkean](https://github.com/davkean) | [4483](https://github.com/nuget/nuget.client/pull/4483) | Remove unneeded allocations when parsing assets file [#11648](https://github.com/NuGet/Home/issues/11648) +[reynoldsbd](https://github.com/reynoldsbd) | [4458](https://github.com/nuget/nuget.client/pull/4458) | [Bug]: Race Condition Creating Plugin Log Files - [#11517](https://github.com/NuGet/Home/issues/11517) +[tintoy](https://github.com/tintoy) | [4287](https://github.com/nuget/nuget.client/pull/4287) | AutoCompleteResourceV3 does not use the supplied logger - [#11272](https://github.com/NuGet/Home/issues/11272) +[davkean](https://github.com/davkean) | [4440](https://github.com/nuget/nuget.client/pull/4440) | Improve VS and NuGet performance by making some methods non-asynchronous - [#11816](https://github.com/NuGet/Home/issues/11816) +[davkean](https://github.com/davkean) | [4439](https://github.com/nuget/nuget.client/pull/4439) | Redundant calls to get VsHierarchy in NuGet VS code - [#11817](https://github.com/NuGet/Home/issues/11817) +[davkean](https://github.com/davkean) | [4432](https://github.com/nuget/nuget.client/pull/4432) | Avoid double-checking for supported projects - [#11554](https://github.com/NuGet/Home/issues/11554) +[dfederm](https://github.com/dfederm) | [4393](https://github.com/nuget/nuget.client/pull/4393) | [Bug]: Static graph restore binlog doesn't log task inputs - [#11484](https://github.com/NuGet/Home/issues/11484) +[drewnoakes](https://github.com/drewnoakes) | [4390](https://github.com/nuget/nuget.client/pull/4390) | Show package .props and .targets files in Solution Explorer [#7838](https://github.com/dotnet/project-system/issues/7838) +[drewnoakes](https://github.com/drewnoakes) | [4386](https://github.com/nuget/nuget.client/pull/4386) | Solution Explorer search is not showing package contents - [#7834](https://github.com/dotnet/project-system/issues/7834) +[marcin-krystianc](https://github.com/marcin-krystianc) | [4186](https://github.com/nuget/nuget.client/pull/4186) | [Regression]: Performance regression for cold restores in .NET 5.0.x [#11031](https://github.com/NuGet/Home/issues/11031) +[joperator](https://github.com/joperator) | [4389](https://github.com/nuget/nuget.client/pull/4389) | [Bug]: Errors NU3028 and NU3037 when restoring NuGet packages on FreeBSD - [#11481](https://github.com/NuGet/Home/issues/11481) +[AndreiTimisescu](https://github.com/AndreiTimisescu) | [3779](https://github.com/nuget/nuget.client/pull/3779) | Make LocalPackageFileCache methods virtual - [#10325](https://github.com/NuGet/Home/issues/10325) +[tmds](https://github.com/tmds) | [4123](https://github.com/nuget/nuget.client/pull/4123) | NuGetScratch lock files are not cleaned up - [#10679](https://github.com/NuGet/Home/issues/10679) + +## Feedback welcome + +Your feedback is important to us. If there are any problems with this release, check our +[GitHub Issues](https://github.com/NuGet/Home/issues) and +[Visual Studio Developer Community](https://developercommunity.visualstudio.com/) +for existing issues. For new issues within NuGet, please report a +[GitHub Issue](https://github.com/NuGet/Home/issues/new/choose). +For general NuGet experience issues, let us know via the +[Report a Problem](/visualstudio/ide/how-to-report-a-problem-with-visual-studio) +option found in your favorite IDE under **Help > Report a Problem**. diff --git a/docs/release-notes/NuGet-6.3.md b/docs/release-notes/NuGet-6.3.md new file mode 100644 index 000000000..8e9b5fb30 --- /dev/null +++ b/docs/release-notes/NuGet-6.3.md @@ -0,0 +1,130 @@ +--- +title: NuGet 6.3 Release Notes +description: Release notes for NuGet 6.3 including new features, bug fixes, and DCRs. +author: martinrrm +ms.author: mruizmares +ms.date: 8/2/2022 +ms.topic: release-notes +--- + +# NuGet 6.3 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.3**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.3](https://visualstudio.microsoft.com/downloads/) | [6.0.400](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | +| [**6.3.1**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.3](https://visualstudio.microsoft.com/downloads/) | [6.0.402](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | +| [**6.3.3**](https://nuget.org/downloads) | N/A | [6.0.410](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | +| [**6.3.4**](https://nuget.org/downloads) | N/A | [6.0.419](https://dotnet.microsoft.com/download/dotnet-core/6.0)1 | + +1 Installed with Visual Studio 17.3 with.NET Core workload + +## Summary: What's New in 6.3.4 + +* [Security]: Microsoft Security Advisory CVE-2024-0057 | NuGet Client Security Feature bypass Vulnerability - [#12653](https://github.com/NuGet/Home/issues/13241) + +## Summary: What's New in 6.3.3 + +* [Security]: Microsoft Security Advisory CVE-2023-29337 | NuGet Client Remote Code Execution Vulnerability - [#12653](https://github.com/NuGet/Home/issues/12653) + +> [!NOTE] +> There is a behavior breaking change on Linux. The temp folder location, where NuGet stores temporary files during its various operations, has changed from `/tmp/NuGetScratch` to `/tmp/NuGetScratch`. E.g. for user User1, the temp folder will be `/tmp/NuGetScratchUser1`. + +## Summary: What's New in 6.3.1 + +* [Security]: Microsoft Security Advisory CVE-2022-41032 | .NET Elevation of Privilege Vulnerability - [#12149](https://github.com/NuGet/Home/issues/12149) + +## Summary: What's New in 6.3 + +* [Feature] Allow to user to input custom (floating) versions through the PM UI - [#9829](https://github.com/NuGet/Home/issues/9829) [#3788](https://github.com/NuGet/Home/issues/3788) + +* [Feature] NuGet warns when duplicate PackageReference, PackageVersion or PackageDownload items are specified - [#9467](https://github.com/NuGet/Home/issues/9467) [#9864](https://github.com/NuGet/Home/issues/9864) + +* When using Central Package Management, Visual Studio no longer errors when installing packages and instead the project and central package management file are updated - [#11828](https://github.com/NuGet/Home/issues/11828) + +* NuGet.Common, NuGet.Configuration, NuGet.Frameworks, NuGet.Packaging.Extraction and NuGet.Versioning no longer support net45 or net40 - [#11830](https://github.com/NuGet/Home/issues/11830) + +### Issues fixed in this release + +**DCRs:** + +* [DCR]: Print sources in NU1507 - [#11715](https://github.com/NuGet/Home/issues/11715) + +* [DCR]: Only cancel VS cred provider requests if VS is closing - [#11970](https://github.com/NuGet/Home/issues/11970) + +* For C++/CLI PackageReference projects, NuGet should ignore the TargetPlatformMoniker - [#11808](https://github.com/NuGet/Home/issues/11808) + +* [DCR]: Include caught exceptions as inner exceptions when rethrowing (in MsBuildUtility) - [#11766](https://github.com/NuGet/Home/issues/11766) + +* Specifying both -f ... and -r ... to dotnet build fails to restore if multiple frameworks are present in the project file - [#11653](https://github.com/NuGet/Home/issues/11653) + +* PackageSourceMapping public constructor - [#11609](https://github.com/NuGet/Home/issues/11609) + +* Add support for system and fallback certificate bundles - [#11263](https://github.com/NuGet/Home/issues/11263) + +**Bugs:** + +* [Bug]: X.509 trust store isn't initialized in `dotnet add package` and SDK resolver code paths - [#11956](https://github.com/NuGet/Home/issues/11956) + +* Cache DTE service in VS Solution Manager - [#11902](https://github.com/NuGet/Home/issues/11902) + +* Nuget CPS references reader is forcing all vc projects to be fully loaded - [#11877](https://github.com/NuGet/Home/issues/11877) + +* Make dotnet package verification env var value comparison case insensitive - [#11876](https://github.com/NuGet/Home/issues/11876) + +* Using JsonTextWriter manually in LockFileFormat - [#11870](https://github.com/NuGet/Home/issues/11870) + +* Extra allocations in EqualityUtility - [#11867](https://github.com/NuGet/Home/issues/11867) + +* [Bug]: Boxing of structs to compute hashcode is causing excessive allocations - [#11866](https://github.com/NuGet/Home/issues/11866) + +* When restore raises an NU1301, build might fail with a `project.assets.json doesn't have a target for 'net6.0-windows10.0.19041.0` like error that's a red herring - [#11862](https://github.com/NuGet/Home/issues/11862) + +* [Bug]: Package source option "All" appears unsorted in the in the list when using VS in non-English languages - [#11857](https://github.com/NuGet/Home/issues/11857) + +* [Bug]: [Bug Bash] The “Version” dropdown box is blank in “Consolidate” tab of solution-level PM UI - [#11806](https://github.com/NuGet/Home/issues/11806) + +* PackageDownload multiple versions doesn't work in Visual Studio. - [#11798](https://github.com/NuGet/Home/issues/11798) + +* [Bug]: Visual Studio restore sometimes sets originalTargetFrameworks incorrectly in project.assets.json - [#11795](https://github.com/NuGet/Home/issues/11795) + +* [Bug]: NuGet does not retry some HTTP timeouts - [#11779](https://github.com/NuGet/Home/issues/11779) + +* [Bug]: misspelling in RestoreCommandCannotDeterminePackagesFolder_deu - [#11774](https://github.com/NuGet/Home/issues/11774) + +* Update SPDX licenses to bb0099c - [#11765](https://github.com/NuGet/Home/issues/11765) + +* "Illegal characters in path" (Solution Directory) - [#11764](https://github.com/NuGet/Home/issues/11764) + +* NuGet Package Manager window causes persistent WPF frame rate spike due to a runaway animation - [#11746](https://github.com/NuGet/Home/issues/11746) + +* [Bug]: PM UI version list only shows a single latest version - [#11734](https://github.com/NuGet/Home/issues/11734) + +* Large number of allocations while processing package references - [#11733](https://github.com/NuGet/Home/issues/11733) + +* Unnecessary Allocations in SemanticVersion.ParseSections() - [#11732](https://github.com/NuGet/Home/issues/11732) + +* [Bug]: new warning for package source mappings doesn't pass a value for the resource string placeholder - [#11709](https://github.com/NuGet/Home/issues/11709) + +* [Bug]: Central package management breaks no-op restores - [#11696](https://github.com/NuGet/Home/issues/11696) + +* [Bug]: MsBuild version is not parsed correctly when -MsBuildPath option is passed to nuget.exe restore - [#11689](https://github.com/NuGet/Home/issues/11689) + +* [Bug]: Very slow restore or OOM when using NoWarn - [#11669](https://github.com/NuGet/Home/issues/11669) + +* [Bug]: Automatic credential plugin discovery is broken when 64 bit msbuild.exe is used by nuget.exe - [#11623](https://github.com/NuGet/Home/issues/11623) + +* [Bug]: Reduce memory allocation while detecting cycles or potential degrades in package versions during restore - [#11614](https://github.com/NuGet/Home/issues/11614) + +* Avoid JTF.Run wrapped property retrieval, use async methods instead. - [#11199](https://github.com/NuGet/Home/issues/11199) + +* .nupkg.metadata locked and being used by another process - [#10882](https://github.com/NuGet/Home/issues/10882) + +* Unexpected error “Your project file doesn’t list ‘win’ as a “RuntimeIdentifier”” occurs when building the solution after enabling “RestoreLockedMode” - [#10590](https://github.com/NuGet/Home/issues/10590) + +* NuGet.exe pack issues a warning (NU5128) when packing a project file - [#8713](https://github.com/NuGet/Home/issues/8713) + +* Transitive lock files (with wildcard) result in NU1004 - [#8465](https://github.com/NuGet/Home/issues/8465) + +* Enhance the experimentation infrastructure in NuGet code to support transitive dependencies - [#10758](https://github.com/NuGet/Home/issues/10758) diff --git a/docs/release-notes/NuGet-6.4.md b/docs/release-notes/NuGet-6.4.md new file mode 100644 index 000000000..ffbcdc7d9 --- /dev/null +++ b/docs/release-notes/NuGet-6.4.md @@ -0,0 +1,132 @@ +--- +title: NuGet 6.4 Release Notes +description: Release notes for NuGet 6.4 including new features, bug fixes, and DCRs. +author: jebriede +ms.author: jebriede +ms.date: 10/27/2022 +ms.topic: release-notes +--- + +# NuGet 6.4 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.4**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.4](https://visualstudio.microsoft.com/downloads/) | [7.0.100](https://dotnet.microsoft.com/download/dotnet-core/7.0)1 | +| [**6.4.2**](https://nuget.org/downloads) | N/A | [7.0.107](https://dotnet.microsoft.com/download/dotnet-core/7.0)1 | +| [**6.4.3**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.4](https://visualstudio.microsoft.com/downloads/) | [7.0.116](https://dotnet.microsoft.com/download/dotnet-core/7.0)1 | + +1 Installed with Visual Studio 17.4 with .NET Core workload + +## Summary: What's New in 6.4.3 + +* [Security]: Microsoft Security Advisory CVE-2024-0057 | NuGet Client Security Feature bypass Vulnerability - [#12653](https://github.com/NuGet/Home/issues/13241) + +## Summary: What's New in 6.4.2 + +* [Security]: Microsoft Security Advisory CVE-2023-29337 | NuGet Client Remote Code Execution Vulnerability - [#12653](https://github.com/NuGet/Home/issues/12653) + +> [!NOTE] +> There is a behavior breaking change on Linux. The temp folder location, where NuGet stores temporary files during its various operations, has changed from `/tmp/NuGetScratch` to `/tmp/NuGetScratch`. E.g. for user User1, the temp folder will be `/tmp/NuGetScratchUser1`. + +## Summary: What's New in 6.4 + +* Central package management is considered production ready and the preview message has been removed - [#11950](https://github.com/NuGet/Home/issues/11950) + +* Add ability to designate a package reference as used by every project in the repo - GlobalPackageReference [#10159](https://github.com/NuGet/Home/issues/10159) + +* Signed package verification is available for opt-in on Linux and macOS by setting the environment variable `DOTNET_NUGET_SIGNATURE_VERIFICATION` to `true`. - [#12033](https://github.com/NuGet/Home/issues/12033), [#11973](https://github.com/NuGet/Home/issues/11973) + +* Improved performance while loading packages for all tabs in the Package Manager UI and solution restore - [#11923](https://github.com/NuGet/Home/issues/11923) + +* Prompts for authentication with Azure Artifacts package sources in Visual Studio indicate that it is for NuGet purposes and contain specific source information. + +### Issues fixed in this release + +**DCRs:** + +* [DCR]: Static graph-based restore should handle an AggregateException from MSBuild - [#12100](https://github.com/NuGet/Home/issues/12100) + +* Signing: use separate fallback certificate bundles for code signing and timestamping - [#12033](https://github.com/NuGet/Home/issues/12033) + +* [DCR]: Central package management package source mapping should only look at configured feeds - [#11951](https://github.com/NuGet/Home/issues/11951) + +* [DCR]: Package Source Mapping API does not support saving - [#11935](https://github.com/NuGet/Home/issues/11935) + +* [DCR]: Plugin timeout defaults should be increased - [#11793](https://github.com/NuGet/Home/issues/11793) + +* Regenerate dgspec when customer triggers VS Feedback - [#8605](https://github.com/NuGet/Home/issues/8605) + +**Bugs:** + +* Details for Installed MAUI packages are missing NuGet Project PM UI - [#12130](https://github.com/NuGet/Home/issues/12130) + +* Static graph restore supports long paths on Windows - [#12121](https://github.com/NuGet/Home/issues/12121) + +* TelemetryUtility.IsVsOfflineFeed fails to correctly identify the local feed with 64-bit windows - [#12110](https://github.com/NuGet/Home/issues/12110) + +* [Bug]: IVsPackageInstallerServices APIs sometimes throw ProjectNotNominatedException - [#12103](https://github.com/NuGet/Home/issues/12103) + +* [Bug]: The transitive package doesn’t show in “Installed” tab until reopening the solution - [#12102](https://github.com/NuGet/Home/issues/12102) + +* [Bug]: Incorrect check for feed count when logging NU1507 warning about not using package source mapping - [#12095](https://github.com/NuGet/Home/issues/12095) + +* [Bug]: User needs to login multiple times while executing dotnet list package from private feeds - [#12090](https://github.com/NuGet/Home/issues/12090) + +* [Bug]: Rename VS NuGet Options "Clear NuGet Cache(s)" button - [#12076](https://github.com/NuGet/Home/issues/12076) + +* nuget.exe help command has unlocalized strings - [#12067](https://github.com/NuGet/Home/issues/12067) + +* Remove unused localized resources in nuget.exe - [#12066](https://github.com/NuGet/Home/issues/12066) + +* [Bug]: NugetSDKResolver doesn't give detailed error messages when it fails - [#12049](https://github.com/NuGet/Home/issues/12049) + +* [Bug]: Package signature validation fails on Linux due to missing 'thawte_Primary_Root_CA' in codesignctl.pem - [#12027](https://github.com/NuGet/Home/issues/12027) + +* [Bug]: "An item with the same key has already been added" when migrating to CPM with `ProjectDependencies` in solution file - [#12021](https://github.com/NuGet/Home/issues/12021) + +* [Bug]: Build failures in dev branch due to renaming of parameter from cpvmEnabled to centralPackageTransitivePinningEnabled - [#12020](https://github.com/NuGet/Home/issues/12020) + +* [Bug]: [Bug Bash] Other versions will lose after selecting a version in the custom version drop-down box for a while - [#11992](https://github.com/NuGet/Home/issues/11992) + +* Remove extra layers of abstractions from IVsProjectAdapter, move RuntimeGraph specific methods from VSProject to LegacyPackageReferenceProject - [#11980](https://github.com/NuGet/Home/issues/11980) + +* Reduce redundant SolutionDirectory calculation, special-case template wizard solution directory retrieval - [#11936](https://github.com/NuGet/Home/issues/11936) + +* Make VS adapter ProjectDirectory sync, use IVsHierarchy only to generate the guids, avoid double casting VSProject4 - [#11928](https://github.com/NuGet/Home/issues/11928) + +* [Bug]: NuGet.VisualStudio.Implementation.Extensibility.VsPathContextProvider.TryCreateContext fault - [#11918](https://github.com/NuGet/Home/issues/11918) + +* [Bug]: Package version downgrade is not detected due to invalid transitive pinning - [#11760](https://github.com/NuGet/Home/issues/11760) + +* _CleanPackageFiles target fails sporadically when (re)building - [#11710](https://github.com/NuGet/Home/issues/11710) + +* Avoid calling CreateLockFileTargetLibrary twice when AssetTargetFallback is used - [#11654](https://github.com/NuGet/Home/issues/11654) + +* Package source mapping should check for duplicate node keys - [#11573](https://github.com/NuGet/Home/issues/11573) + +* VSSolutionManager.DoesNuGetSupportsAnyProjectAsync can exit at the first supported projec - [#11555](https://github.com/NuGet/Home/issues/11555) + +* Review all sync ServiceLocator calls and move to async where possible - [#11203](https://github.com/NuGet/Home/issues/11203) + +* [Bug Bash]The new designs of hovered-on menu between VS and NuGet are inconsistent - [#10978](https://github.com/NuGet/Home/issues/10978) + +* [Bug]: Metadata like PrivateAssets does not flow from parent to transitively pinned dependency in CPM - [#10311](https://github.com/NuGet/Home/issues/10311) + +**[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.3.1.1...6.4.0.123)** + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +* [kkirkfield](https://github.com/kkirkfield) + * [4738](https://github.com/NuGet/NuGet.Client/pull/4738) Fix issue with _CleanPackageFiles target failing on rebuild +* [MichaelSimons](https://github.com/MichaelSimons) + * [4737](https://github.com/NuGet/NuGet.Client/pull/4737) Tweak ApplySourceBuildPatchFiles target to support virtual mono repo (VMR) +* [marcin-krystianc](https://github.com/marcin-krystianc) + * [4611](https://github.com/NuGet/NuGet.Client/pull/4611) Central transitive dependencies should be considered only for root nodes +* [Forgind](https://github.com/Forgind) + * [4766](https://github.com/NuGet/NuGet.Client/pull/4766) Return warnings to log when NuGet SDK resolver fails +* [lbussell](https://github.com/lbussell) + * [4742](https://github.com/NuGet/NuGet.Client/pull/4742) Update TFM to net7.0 for source-build diff --git a/docs/release-notes/NuGet-6.5.md b/docs/release-notes/NuGet-6.5.md new file mode 100644 index 000000000..8ee257234 --- /dev/null +++ b/docs/release-notes/NuGet-6.5.md @@ -0,0 +1,127 @@ +--- +title: NuGet 6.5 Release Notes +description: Release notes for NuGet 6.5 including new features, bug fixes, and DCRs. +author: martinrrm +ms.author: mruizmares +ms.date: 2/21/2023 +ms.topic: release-notes +--- + +# NuGet 6.5 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.5**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.5](https://visualstudio.microsoft.com/downloads/) | [7.0.200](https://dotnet.microsoft.com/download/dotnet-core/7.0)1 | +| [**6.5.1**](https://nuget.org/downloads) | N/A | N/A 1 | + +1 Installed with Visual Studio 2022 with.NET Core workload + +## Summary: What's New in 6.5.1 + +* [Security]: Microsoft Security Advisory CVE-2023-29337 | NuGet Client Remote Code Execution Vulnerability - [#12653](https://github.com/NuGet/Home/issues/12653) + +> [!NOTE] +> There is a behavior breaking change on Linux. The temp folder location, where NuGet stores temporary files during its various operations, has changed from `/tmp/NuGetScratch` to `/tmp/NuGetScratch`. E.g. for user User1, the temp folder will be `/tmp/NuGetScratchUser1`. + +## Summary: What's New in 6.5 + +* Manage packages in the Directory.Packages.props file for CPM projects - [#11890](https://github.com/NuGet/Home/issues/11890) + +* Package Source Mapping UI - Allow the Creation/Removal of package source mappings in the NuGet Options UI - [#11363](https://github.com/NuGet/Home/issues/11363) + +* Package Source Mapping UI - List Package Source Mappings in the NuGet Options UI - [#11362](https://github.com/NuGet/Home/issues/11362) + +* Observe Retry-After delay on HTTP request retry - [#10558](https://github.com/NuGet/Home/issues/10558) + +* Machine readable output for dotnet list package - [#7752](https://github.com/NuGet/Home/issues/7752) + +* Honor WarningsNotAsErrors - [#5375](https://github.com/NuGet/Home/issues/5375) + +* Reload Visual Studio package sources when nuget.config is modified manually - [#1538](https://github.com/NuGet/Home/issues/1538) + +* Restore dependencies for projects listed in a solution filter (.slnf) file - [#10809](https://github.com/NuGet/Home/issues/10809) + +### Issues fixed in this release + +**DCRs:** + +* During MSBuild project SDK resolution, always log errors in the case of failure - [#12312](https://github.com/NuGet/Home/issues/12312) + +* Environment variable `NUGET_CLI_LANGUAGE` to control language of nuget.exe command output - [#12181](https://github.com/NuGet/Home/issues/12181) + +* Make it obvious when a warning is elevated to an error - [#8803](https://github.com/NuGet/Home/issues/8803) + +* Show error when using nuget.exe to pack SDK csproj - [#7778](https://github.com/NuGet/Home/issues/7778) + +**Bugs:** + +* Output version option only applicable for format json option in dotnet list package - [#12293](https://github.com/NuGet/Home/issues/12293) + +* NuGet transitive pinning changes g.props import order, breaking the build - [#12278](https://github.com/NuGet/Home/issues/12278) + +* PrivateAssets for central transitive dependencies should flow regardless whether the parent is a project or a package - [#12276](https://github.com/NuGet/Home/issues/12276) + +* Include flags flow incorrectly to transitively pinned centrally managed dependencies - [#12274](https://github.com/NuGet/Home/issues/12274) + +* Possible race condition in ConfigurationDefaults.Instance.DefaultPackageSources - [#12246](https://github.com/NuGet/Home/issues/12246) + +* NuGet doesn't retry on HTTP 429 responses - [#12214](https://github.com/NuGet/Home/issues/12214) + +* Simplification of Linq Any method for performance improvement - [#12193](https://github.com/NuGet/Home/issues/12193) + +* StackOverflowException in InstallPackagesFromVSExtensionRepository - [#12192](https://github.com/NuGet/Home/issues/12192) + +* Versions_SelectionChanged throws NullReferenceException when changing selected package - [#12184](https://github.com/NuGet/Home/issues/12184) + +* Static graph-based restore fails with a NullReferenceException during SetPlatform negotiation - [#12177](https://github.com/NuGet/Home/issues/12177) + +* Reduce memory allocation while creating empty InnerNodes and ParentNodes for a new GraphNode during restore - [#12157](https://github.com/NuGet/Home/issues/12157) + +* SettingsLoadingContext throws exceptions when a different settings file causes an exception - [#12154](https://github.com/NuGet/Home/issues/12154) + +* Bad NuGet.config causes NuGet-based MSBuild SDK resolver to throw an unhandled exception - [#12152](https://github.com/NuGet/Home/issues/12152) + +* Watermark TextBox font color is incorrect in Add Dialog of Package Source Mapping Options - [#12141](https://github.com/NuGet/Home/issues/12141) + +* VS2022 17.1.2: Dependency between .NET Standard 2.0 and .NET 4.7.1 throws NuGet error System.Memory, Version=4.0.1.1 not found - [#12137](https://github.com/NuGet/Home/issues/12137) + +* Breaking change in .NET 8 - Environment.GetFolderPath returns incorrect path on Unix - [#12127](https://github.com/NuGet/Home/issues/12127) + +* nuget.exe strings from NuGet.Commands are not localized - [#12097](https://github.com/NuGet/Home/issues/12097) + +* Process argument string is too long when publishing in Visual Studio with static graph enabled - [#11968](https://github.com/NuGet/Home/issues/11968) + +* Provide solution for NuGet Error NU1012 - the pack error does not call out the problem files - [#11905](https://github.com/NuGet/Home/issues/11905) + +* Some CLI commands don't respect DOTNET_CLI_UI_LANGUAGE - [#11326](https://github.com/NuGet/Home/issues/11326) + +* Reduce UI thread switching when determining solution folder and if solution is open - [#11090](https://github.com/NuGet/Home/issues/11090) + +* Issue saving settings in Visual Studio - adding a source throws an exception - [#8407](https://github.com/NuGet/Home/issues/8407) + +* PackageDependencyGroup does not implement Equals correctly - [#6478](https://github.com/NuGet/Home/issues/6478) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.5.0.154...6.4.1.21) + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +* [Forgind](https://github.com/Forgind) + * [4970](https://github.com/NuGet/NuGet.Client/pull/4970) Have SDK resolver always log an error when SDK resolution in unsuccessful +* [marcin-krystianc](https://github.com/marcin-krystianc) + * [4952](https://github.com/NuGet/NuGet.Client/pull/4952) PrivateAssets for central transitive dependencies should flow regardless whether the parent node is a project or a package +* [marcin-krystianc](https://github.com/marcin-krystianc) + * [4950](https://github.com/NuGet/NuGet.Client/pull/4950) Fix include flags calculation for transitively pinned centrally managed dependencies +* [drewnoakes](https://github.com/drewnoakes) + * [4891](https://github.com/NuGet/NuGet.Client/pull/4891) Display documents from packages in the dependencies tree +* [kvpt](https://github.com/kvpt) + * [4790](https://github.com/NuGet/NuGet.Client/pull/4790) Add support for restoring slnf file from command line +* [AtariDreams](https://github.com/AtariDreams) + * [4863](https://github.com/NuGet/NuGet.Client/pull/4863) Simplification of Linq Any method +* [davidegiacometti](https://github.com/davidegiacometti) + * [4840](https://github.com/NuGet/NuGet.Client/pull/4840) Refactor PackageDependencyGroup Equals and GetHashCode +* [danjagnow](https://github.com/danjagnow) + * [4843](https://github.com/NuGet/NuGet.Client/pull/4843) Updated NU1012 error message to display item paths diff --git a/docs/release-notes/NuGet-6.6.md b/docs/release-notes/NuGet-6.6.md new file mode 100644 index 000000000..29eb769cf --- /dev/null +++ b/docs/release-notes/NuGet-6.6.md @@ -0,0 +1,87 @@ +--- +title: NuGet 6.6 Release Notes +description: Release notes for NuGet 6.6 including new features, bug fixes, and DCRs. +author: donnie-msft +ms.author: eagoodso +ms.date: 5/1/2023 +ms.topic: release-notes +--- + +# NuGet 6.6 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.6**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.6](https://visualstudio.microsoft.com/downloads/) | [7.0.300](https://dotnet.microsoft.com/download/dotnet-core/7.0)1 | +| [**6.6.1**](https://nuget.org/downloads) | N/A | [7.0.304](https://dotnet.microsoft.com/download/dotnet-core/7.0)1 | +| [**6.6.2**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.6](https://visualstudio.microsoft.com/downloads/) | [7.0.313](https://dotnet.microsoft.com/download/dotnet-core/7.0)1 | + +1 Installed with Visual Studio 2022 with .NET Core workload + +## Summary: What's New in 6.6.2 + +* [Security]: Microsoft Security Advisory CVE-2024-0057 | NuGet Client Security Feature bypass Vulnerability - [#12653](https://github.com/NuGet/Home/issues/13241) + +## Summary: What's New in 6.6.1 + +* [Security]: Microsoft Security Advisory CVE-2023-29337 | NuGet Client Remote Code Execution Vulnerability - [#12653](https://github.com/NuGet/Home/issues/12653) + +> [!NOTE] +> There is a behavior breaking change on Linux. The temp folder location, where NuGet stores temporary files during its various operations, has changed from `/tmp/NuGetScratch` to `/tmp/NuGetScratch`. E.g. for user User1, the temp folder will be `/tmp/NuGetScratchUser1`. + +## Summary: What's New in 6.6 + +* [Epic]: Central Package Management improvements for 17.6 - [#12413](https://github.com/NuGet/Home/issues/12413) + +### Issues fixed in this release + +**DCRs:** + +* Static graph-based restore should always log an error on failure - [#12372](https://github.com/NuGet/Home/issues/12372) + +**Bugs:** + +* Set CentralPackageVersionOverrideEnabled=false in project with CPM broke project restore - [#12500](https://github.com/NuGet/Home/issues/12500) + +* Static graph-based restore crashes on systems with alternate console encodings - [#12373](https://github.com/NuGet/Home/issues/12373) + +* GlobalPackageReference is not working for legacy-style csproj projects - [#12368](https://github.com/NuGet/Home/issues/12368) + +* WebSite projects opened from IIS fail to install packages - [#12337](https://github.com/NuGet/Home/issues/12337) + +* StackOverflow in SemanticVersion.ToString - [#12330](https://github.com/NuGet/Home/issues/12330) + +* Static graph restore failure when referencing unrestorable project - [#12322](https://github.com/NuGet/Home/issues/12322) + +* CPM opt in detection in VS and commandline is different - [#12285](https://github.com/NuGet/Home/issues/12285) + +* PrivateAssets flow incorrectly to transitively pinned centrally managed dependencies - [#12270](https://github.com/NuGet/Home/issues/12270) + +* Performance regression of NuGet restores in the sdk v7.0.100 due to calculation of "CentralTransitiveDependencyGroups" - [#12269](https://github.com/NuGet/Home/issues/12269) + +* [Bug]: `NuGet.VisualStudio` depends on package not existing on NuGet.org - [#12164](https://github.com/NuGet/Home/issues/12164) + +* [Bug]: Custom kernel breaks nuget - [#11995](https://github.com/NuGet/Home/issues/11995) + +* PackageSource: returns possibly incorrect hash code - [#10276](https://github.com/NuGet/Home/issues/10276) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.6.0.61...6.5.0.160) + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +* [kant2002](https://github.com/kant2002) + * [5103](https://github.com/NuGet/NuGet.Client/pull/5103) Fix project restore when CentralPackageVersionOverrideEnabled=false +* [atamagaii](https://github.com/atamagaii) + * [5078](https://github.com/NuGet/NuGet.Client/pull/5078) Changed english resource MsbuildPathNotExist to correctly describe th… +* [pombredanne](https://github.com/pombredanne) + * [5083](https://github.com/NuGet/NuGet.Client/pull/5083) Fix minor typo +* [NikolaMilosavljevic](https://github.com/NikolaMilosavljevic) + * [5091](https://github.com/NuGet/NuGet.Client/pull/5091) Trim away netframework targets in source-build +* [uweigand](https://github.com/uweigand) + * [5046](https://github.com/NuGet/NuGet.Client/pull/5046) Limit concurrent connections via NUGET_CONCURRENCY_LIMIT +* [marcin-krystianc](https://github.com/marcin-krystianc) + * [4954](https://github.com/NuGet/NuGet.Client/pull/4954) Improved performance of calculation of PrivateAssets for transitively pinned centrally managed dependencies + * [4953](https://github.com/NuGet/NuGet.Client/pull/4953) Effective PrivateAssets of centrally managed transitive dependencies should be an intersection of parent dependencies diff --git a/docs/release-notes/NuGet-6.7.md b/docs/release-notes/NuGet-6.7.md new file mode 100644 index 000000000..ac9bbe4db --- /dev/null +++ b/docs/release-notes/NuGet-6.7.md @@ -0,0 +1,166 @@ +--- +title: NuGet 6.7 Release Notes +description: Release notes for NuGet 6.7 including new features, bug fixes, and DCRs. +author: jeffkl +ms.author: jeffkl +ms.date: 7/31/2023 +ms.topic: release-notes +--- + +# NuGet 6.7 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.7**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.7](https://visualstudio.microsoft.com/downloads/) | [7.0.400](https://dotnet.microsoft.com/download/dotnet-core/7.0)1 | +| [**6.7.1**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.7](https://visualstudio.microsoft.com/downloads/) | [7.0.406](https://dotnet.microsoft.com/download/dotnet-core/7.0)1 | + +1 Installed with Visual Studio 2022 with.NET Core workload + +## Summary: What's New in 6.7.1 + +* [Security]: Microsoft Security Advisory CVE-2024-0057 | NuGet Client Security Feature bypass Vulnerability - [#12653](https://github.com/NuGet/Home/issues/13241) + +## Summary: What's New in 6.7 + +* Package Source Mapping status for selected package in Details Pane - [#12586](https://github.com/NuGet/Home/issues/12586) + +* Add VulnerabilityInfo APIs into NuGet.Protocol - [#12518](https://github.com/NuGet/Home/issues/12518) + +* Signing: raise actionable message on Linux if verification results in untrusted failure - [#12459](https://github.com/NuGet/Home/issues/12459) + +* [Feature]: Show which package versions are vulnerable in the VS PMUI package details pane version dropdown - [#11127](https://github.com/NuGet/Home/issues/11127) + +### Issues fixed in this release + +**DCRs:** + +* There are no visual indicators for the Package Source Mapping status in details pane - [#12609](https://github.com/NuGet/Home/issues/12609) + +* VS Options shortcut from PMUI for PackageSourceMappings doesn't scroll to or select the Package - [#12608](https://github.com/NuGet/Home/issues/12608) + +* Install/Update buttons are enabled in Details Pane when the PackageSourceMapping is not found - [#12607](https://github.com/NuGet/Home/issues/12607) + +* Add nullable annotations to NuGet.Frameworks - [#12570](https://github.com/NuGet/Home/issues/12570) + +* NuGet should use a different property for the platform version for C++/CLI - [#12521](https://github.com/NuGet/Home/issues/12521) + +* NuGet should use HttpClientHandler.PreAuthentication to reduce HTTP 401's - [#12514](https://github.com/NuGet/Home/issues/12514) + +**Bugs:** + +* Create SingleFileProvider and use it for content files - [#12706](https://github.com/NuGet/Home/issues/12706) + +* Restore task dumps stack because TaskCanceledException should be OperationCanceledException - [#12700](https://github.com/NuGet/Home/issues/12700) + +* Improve nuget.exe restore error message when passing file globs - [#12691](https://github.com/NuGet/Home/issues/12691) + +* NuGet: LockFileUtils.GetLockFileItems boxing enumerator - [#12684](https://github.com/NuGet/Home/issues/12684) + +* Preview Window needs some strings reworded and margins adjusted - [#12681](https://github.com/NuGet/Home/issues/12681) + +* PackageSpecificWarningProperties classes do redundant collection lookups - [#12678](https://github.com/NuGet/Home/issues/12678) + +* Specify SelectionCriteria list capacity correctly - [#12667](https://github.com/NuGet/Home/issues/12667) + +* Avoid value lookup in foreach loop over dictionary's keys - [#12666](https://github.com/NuGet/Home/issues/12666) + +* NuGet: VersionRangeFormatter.GetNormalizedString bypassing StringBuilderCache via use of string.format - [#12664](https://github.com/NuGet/Home/issues/12664) + +* NuGet: LockFileFormat.ReadTargetLibrary using string.split on a simple pattern - [#12663](https://github.com/NuGet/Home/issues/12663) + +* Performance: Don't allocate as many Task instances - [#12659](https://github.com/NuGet/Home/issues/12659) + +* Replace unreliable assembly location code with reliable one - [#12650](https://github.com/NuGet/Home/issues/12650) + +* PackageSpec should use an empty RuntimeGraph instead of a new one - [#12649](https://github.com/NuGet/Home/issues/12649) + +* TargetFrameworkInformation.Clone calls ToDictionary on a type that is already a dictionary, TargetFrameworkInformation.Clone resizes a dictionary it already knows the destination size - [#12648](https://github.com/NuGet/Home/issues/12648) + +* PackageSpecReferenceDependencyProvider.GetLibrary unnecessarily resizes a List<T> that it doesn't even need - [#12647](https://github.com/NuGet/Home/issues/12647) + +* ResolverUtility.FindLibraryCachedAsync should use a struct as lookup - [#12646](https://github.com/NuGet/Home/issues/12646) + +* ContentItemCollection.PopulateItemGroups unnecessarily causing resizes of List<T>, ContentItemCollection.PopulateItemGroups boxing List<T>.Enumerator - [#12645](https://github.com/NuGet/Home/issues/12645) + +* PackageSpec.Clone and LibraryDependency.Clone overwrite collections created by their constructors. - [#12642](https://github.com/NuGet/Home/issues/12642) + +* RestoreOperationLogger.ReportProgressAsync repeatedly requests UI thread time - [#12640](https://github.com/NuGet/Home/issues/12640) + +* Avoid repeated Enum.ToString() in PackageSpecWriter.SetDependencies - [#12638](https://github.com/NuGet/Home/issues/12638) + +* ETW events should use default '/' instead of '_' - [#12631](https://github.com/NuGet/Home/issues/12631) + +* Parsing NuGetVersion causes significant GC pressure - [#12630](https://github.com/NuGet/Home/issues/12630) + +* The vulnerable label doesn’t show in the “version” dropdown box of “Browse” tab when searching for vulnerable packages - [#12623](https://github.com/NuGet/Home/issues/12623) + +* nuget restore fails for solution filters not in same directory as the solution it references. - [#12562](https://github.com/NuGet/Home/issues/12562) + +* VersionRangeFormatter should use StringBuilderPool - [#12551](https://github.com/NuGet/Home/issues/12551) + +* Reduce allocations in VirtualFileInfo.Name - [#12550](https://github.com/NuGet/Home/issues/12550) + +* Reduce allocations when getting hash code of LibraryModel.LibraryRange - [#12549](https://github.com/NuGet/Home/issues/12549) + +* NuGet.Build.Tasks.Console should roll forward to newer runtimes - [#12528](https://github.com/NuGet/Home/issues/12528) + +* SourceRepository.GetResource throws if type is not an exact match - [#12455](https://github.com/NuGet/Home/issues/12455) + +* [Bug]: Disable the option to update version when using VersionOverride in CPM - [#12230](https://github.com/NuGet/Home/issues/12230) + +* [Bug]: dotnet nuget push not detecting apikey for 3rd party symbol server - [#11846](https://github.com/NuGet/Home/issues/11846) + +* X-NuGet-Warning doesn't work when using proxy due to missing ServerWarningLogHandler - [#5004](https://github.com/NuGet/Home/issues/5004) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.7.0.127...6.6.1.2) + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +* [danmoseley](https://github.com/danmoseley) + * [5276](https://github.com/NuGet/NuGet.Client/pull/5276) fix crash on cancel in Restore task +* [oleksandr-didyk](https://github.com/oleksandr-didyk) + * [5196](https://github.com/NuGet/NuGet.Client/pull/5196) add review comment to sb files +* [drewnoakes](https://github.com/drewnoakes) + * [5200](https://github.com/NuGet/NuGet.Client/pull/5200) Reduce allocations in ContentItemCollection +* [Erarndt](https://github.com/Erarndt) + * [5202](https://github.com/NuGet/NuGet.Client/pull/5202) Avoid allocations while parsing NuGetVersion from strings +* [jerhon](https://github.com/jerhon) + * [5197](https://github.com/NuGet/NuGet.Client/pull/5197) Fix issue with solution filters not restoring when in different folder than referenced solution +* [NikolaMilosavljevic](https://github.com/NikolaMilosavljevic) + * [5228](https://github.com/NuGet/NuGet.Client/pull/5228) Add System.Security.Cryptography.Xml dependency +* [DevPaulLiu](https://github.com/DevPaulLiu) + * [5206](https://github.com/NuGet/NuGet.Client/pull/5206) Use default '/' split symbol in ETW events. +* [drewnoakes](https://github.com/drewnoakes) + * [5201](https://github.com/NuGet/NuGet.Client/pull/5201) Reduce allocations in PackageSpecReferenceDependencyProvider +* [drewnoakes](https://github.com/drewnoakes) + * [5199](https://github.com/NuGet/NuGet.Client/pull/5199) Reduce allocations in TargetFrameworkInformation.Clone +* [Erarndt](https://github.com/Erarndt) + * [5217](https://github.com/NuGet/NuGet.Client/pull/5217) Ensure only one logging task is active at a time +* [Erarndt](https://github.com/Erarndt) + * [5219](https://github.com/NuGet/NuGet.Client/pull/5219) Update PackageSpec.Clone and LibraryDependency.Clone to avoid allocations +* [Erarndt](https://github.com/Erarndt) + * [5215](https://github.com/NuGet/NuGet.Client/pull/5215) Add AsString() for LibraryDependencyTarget and LibraryIncludeFlags +* [NikolaMilosavljevic](https://github.com/NikolaMilosavljevic) + * [5207](https://github.com/NuGet/NuGet.Client/pull/5207) Add dependencies for PVP flow +* [NikolaMilosavljevic](https://github.com/NikolaMilosavljevic) + * [5193](https://github.com/NuGet/NuGet.Client/pull/5193) Target net8.0 for source-build +* [mthalman](https://github.com/mthalman) + * [5180](https://github.com/NuGet/NuGet.Client/pull/5180) Exclude WPF projects from source-build +* [NikolaMilosavljevic](https://github.com/NikolaMilosavljevic) + * [5190](https://github.com/NuGet/NuGet.Client/pull/5190) Enable source-build pre-built detection +* [drewnoakes](https://github.com/drewnoakes) + * [5146](https://github.com/NuGet/NuGet.Client/pull/5146) Show diagnostic beneath unresolved package/project reference in Solution Explorer +* [0xced](https://github.com/0xced) + * [5021](https://github.com/NuGet/NuGet.Client/pull/5021) Log warnings from server also when using an http proxy (X-NuGet-Warning) +* [jwfx](https://github.com/jwfx) + * [5122](https://github.com/NuGet/NuGet.Client/pull/5122) Fall back to using API key also for pushing symbol packages if nothing else was specified as parameter or config +* [MichaelSimons](https://github.com/MichaelSimons) + * [5132](https://github.com/NuGet/NuGet.Client/pull/5132) Remove MinimalTargetFrameworksExeSigning from MinimalTargetFrameworksExeSigning in source-build +* [dfederm](https://github.com/dfederm) + * [5125](https://github.com/NuGet/NuGet.Client/pull/5125) Add RollForward to NuGet.Build.Tasks.Console +* [atamagaii](https://github.com/atamagaii) + * [5107](https://github.com/NuGet/NuGet.Client/pull/5107) Add missing RegistrationsBaseUrls to prevent exceptions when loading valid Service Indexes. diff --git a/docs/release-notes/NuGet-6.8.md b/docs/release-notes/NuGet-6.8.md new file mode 100644 index 000000000..bd351673e --- /dev/null +++ b/docs/release-notes/NuGet-6.8.md @@ -0,0 +1,179 @@ +--- +title: NuGet 6.8 Release Notes +description: Release notes for NuGet 6.8 including new features, bug fixes, and DCRs. +author: nkolev92 +ms.author: nikolev +ms.date: 10/30/2023 +ms.topic: release-notes +--- + +# NuGet 6.8 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.8**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.8](https://visualstudio.microsoft.com/downloads/) | [8.0.100](https://dotnet.microsoft.com/download/dotnet/8.0)1 | +| [**6.8.1**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.8](https://visualstudio.microsoft.com/downloads/) | [8.0.102](https://dotnet.microsoft.com/download/dotnet/8.0)1 | + + +1 Installed with Visual Studio 2022 with any .NET workload + +## Summary: What's New in 6.8.1 + +* [Security]: Microsoft Security Advisory CVE-2024-0057 | NuGet Client Security Feature bypass Vulnerability - [#12653](https://github.com/NuGet/Home/issues/13241) + +## Summary: What's New in 6.8 + +* [NuGetAudit](../concepts/Auditing-Packages.md) - notifications for package vulnerabilities + * Warn when vulnerabilities are detected during PackageReference restore - [#12289](https://github.com/NuGet/Home/issues/12289) + * Show vulnerabilities in transitive packages for PackageReference type projects in PMUI - [#8756](https://github.com/NuGet/Home/issues/8756) + * Show an infobar in Solution Explorer for any detected security vulnerabilities in a project or solution - [#12398](https://github.com/NuGet/Home/issues/12398) + +* Add [`allowInsecureConnections`](../reference/nuget-config-file.md#packagesources) property for package sources in NuGet.config, allowing opt-out of "HTTPs everywhere" warnings - [#12786](https://github.com/NuGet/Home/issues/12786) + +* Create Package Source Mappings during Installation/update through PM UI - [#11366](https://github.com/NuGet/Home/issues/11366) + +* Conditional package updating is respected in Visual Studio [#5420](https://github.com/NuGet/NuGet.Client/pull/5420) + +* Add [protocolVersion argument](../reference/cli-reference/cli-ref-sources.md#options) to nuget source add - [#9170](https://github.com/NuGet/Home/issues/9170) + +* Signed package verification is [enabled by default on Linux in .NET 8 SDK](/dotnet/core/tools/nuget-signed-package-verification#linux) - [#11262](https://github.com/NuGet/Home/issues/11262) + +### Known issues + +* NuGetAuditMode doesn't work for SDK style projects in VS 17.8 - [#13003](https://github.com/NuGet/Home/issues/13003) + +### NuGet SDK breaking changes + +The following is a list of breaking changes in the NuGet SDK. If you are using NuGet tooling, such as Visual Studio or .NET SDK, you are not affected. + +* Remove the NuGetOperationType from NuGet.PackageManagement, use NuGetProjectActionType instead - [#12866](https://github.com/NuGet/Home/issues/12866) + +* Changing PackageVulnerabilityInfo severity from int to enum - [#12781](https://github.com/NuGet/Home/issues/12781) + +* Add nullable annotations to NuGet.Common - [#12775](https://github.com/NuGet/Home/issues/12775) + +* Obsolete Clone methods on immutable types - [#12669](https://github.com/NuGet/Home/issues/12669) + +### Issues fixed in this release + +* NuGetAudit should not warn when no vulnerability data is available - [#12875](https://github.com/NuGet/Home/issues/12875) + +* NuGetAudit: read vulnerability files with System.Text.Json - [#12855](https://github.com/NuGet/Home/issues/12855) + +* `PackageSourceMapping` API doesn't follow best practices for returning lists - [#12794](https://github.com/NuGet/Home/issues/12794) + +* Signing: enable `X509Chain.Build(...)` retry behavior by default - [#12592](https://github.com/NuGet/Home/issues/12592) + +* NuGetAudit should check direct PackageReferences by default - [#12590](https://github.com/NuGet/Home/issues/12590) + +* NuGetAudit should be on by default with the .NET 8 SDK - [#12568](https://github.com/NuGet/Home/issues/12568) + +* Remove "Checking compatibility..." log messages from RestoreTask - [#10383](https://github.com/NuGet/Home/issues/10383) + +* 16.10: remove package source 1.0 service. remove obsolete APIs (in nuget.configuration that we added in 16.8) - [#10015](https://github.com/NuGet/Home/issues/10015) + +* Add more logging to NuGetSdkResolver - [#11445](https://github.com/NuGet/Home/issues/11445) + +* Upgrade Newtonsoft.Json reference to 13.0.3 - [#12858](https://github.com/NuGet/Home/issues/12858) + +* Add an API for checking vulnerability during packages.config restore - [#12852](https://github.com/NuGet/Home/issues/12852) + +* VS Options add/remove package source icons aren't using VS2022 styling - [#12840](https://github.com/NuGet/Home/issues/12840) + +* Package Source Mapping utility always appends package ID - [#12839](https://github.com/NuGet/Home/issues/12839) + +* NuGetSdkResolver loads global.json multiple times during project load - [#12819](https://github.com/NuGet/Home/issues/12819) + +* dotnet list package doesn't list requested versions when using CPM - [#12765](https://github.com/NuGet/Home/issues/12765) + +* Fix case sensitivity of runtime dependency sets during merge - [#12757](https://github.com/NuGet/Home/issues/12757) + +* dotnet list package errors with Object reference not set to an instance of an object - [#12755](https://github.com/NuGet/Home/issues/12755) + +* Improve hashing and equality allocations/performance - [#12746](https://github.com/NuGet/Home/issues/12746) + +* NuGetAudit severity bugs - [#12743](https://github.com/NuGet/Home/issues/12743) + +* Lock contention thread pool issues caused by LoadSettings not passing settingsLoadingContext to LoadSettingsForSpecificConfigs - [#12737](https://github.com/NuGet/Home/issues/12737) + +* NuGetAuditMode all warns about package versions that were upgraded (rejected) - [#12730](https://github.com/NuGet/Home/issues/12730) + +* An error “unable to find metadata of PackageName.1.0.0” occurs when installing package with “packages.config” format - [#12723](https://github.com/NuGet/Home/issues/12723) + +* WalkTreeRejectNodesOfRejectedNodes constantly triggering resizes of its tracker collection - [#12719](https://github.com/NuGet/Home/issues/12719) + +* Reduce RuntimeGraph allocations as it's immutable - [#12717](https://github.com/NuGet/Home/issues/12717) + +* Heavy allocations in NuGet.Commands.RestoreRunner.ExecuteAndCommitAsync|nuget.packaging.dll!NuGet.RuntimeModel.RuntimeDescription - [#12714](https://github.com/NuGet/Home/issues/12714) + +* Heavy allocations in NuGet.Commands.RestoreRunner.ExecuteAndCommitAsync|nuget.versioning.dll!NuGet.Versioning.VersionFormatter.Format - [#12707](https://github.com/NuGet/Home/issues/12707) + +* Remove allocations from PackageSource.Source setter - [#12692](https://github.com/NuGet/Home/issues/12692) + +* ContentItemCollection.FindBestItemGroup boxing enumerator - [#12689](https://github.com/NuGet/Home/issues/12689) + +* FrameworkNameProvider.GetVersionString boxing enumerator - [#12685](https://github.com/NuGet/Home/issues/12685) + +* NuGet.Client allocates many instances of comparers - [#12680](https://github.com/NuGet/Home/issues/12680) + +* GetContentFileFolderRelativeToFramework allocates too much - [#12668](https://github.com/NuGet/Home/issues/12668) + +* Deprecated info will flash for less than one second in the right penal when clicking package “Microsoft.Net.Http” with a non-deprecated version in the package list - [#12661](https://github.com/NuGet/Home/issues/12661) + +* CreateGraphNode has a high number of allocations - [#12641](https://github.com/NuGet/Home/issues/12641) + +* The vulnerable label doesn’t show in the “version” dropdown box of “Browse” tab when searching for vulnerable packages - [#12623](https://github.com/NuGet/Home/issues/12623) + +* NuGet.Commands.LockFileBuilder KeyNotFoundException Exception - [#12464](https://github.com/NuGet/Home/issues/12464) + +* A PackageDownload without a version causes a NullReferenceException - [#12212](https://github.com/NuGet/Home/issues/12212) + +* [Bug]: View License dialog does not display license content - [#12060](https://github.com/NuGet/Home/issues/12060) + + +* [Bug Bash] Only the embedded license content of the latest version can be loaded correctly in PM UI when there are multiple versions in the same package from local feeds - [#10670](https://github.com/NuGet/Home/issues/10670) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.8.0.131...6.7.0.127) + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +* [drewnoakes](https://github.com/NuGet/NuGet.Client/pull/5311) + * [5311](https://github.com/NuGet/NuGet.Client/pull/5311) Null annotate PackageDependencyInfo + * [5310](https://github.com/NuGet/NuGet.Client/pull/5310) Reduce size of LockFileTargetLibrary + * [5304](https://github.com/NuGet/NuGet.Client/pull/5304) Improve hashing and equality allocations/performance + * [5267](https://github.com/NuGet/NuGet.Client/pull/5267) Reduce allocations in NuGet.DependencyResolver.Tracker + * [5232](https://github.com/NuGet/NuGet.Client/pull/5232) Reduce allocations in RuntimeGraph + * [5279](https://github.com/NuGet/NuGet.Client/pull/5279) Reduce allocations in VersionRangeFormatter + * [5248](https://github.com/NuGet/NuGet.Client/pull/5248) Reduce allocations in RuntimeDescription and RuntimeDependencySet + * [5269](https://github.com/NuGet/NuGet.Client/pull/5269) Don't box enumerators in ContentItemCollection + * [5250](https://github.com/NuGet/NuGet.Client/pull/5250) Don't allocate temporaries in FrameworkNameProvider.GetVersionString + * [5271](https://github.com/NuGet/NuGet.Client/pull/5271) Remove allocations from PackageSource.Source setter +* [MichaelSimons](https://github.com/NuGet/NuGet.Client/pull/5418) + * [5418](https://github.com/NuGet/NuGet.Client/pull/5418) Fix source-build CI regression + * [5414](https://github.com/NuGet/NuGet.Client/pull/5414) Remove unnecessary source-build patch +* [mthalman](https://github.com/NuGet/NuGet.Client/pull/5385) + * [5385](https://github.com/NuGet/NuGet.Client/pull/5385) Update Newtonsoft.Json from 13.0.1 to 13.0.3 +* [timheuer](https://github.com/NuGet/NuGet.Client/pull/5375) + * [5375](https://github.com/NuGet/NuGet.Client/pull/5375) Update VS Options add/remove package source icons to VS2022 styling +* [dotnokato](https://github.com/NuGet/NuGet.Client/pull/5002) + * [5002](https://github.com/NuGet/NuGet.Client/pull/5002) CLI: Add -protocolVersion option to nuget sources add/update commands +* [oleksandr-didyk](https://github.com/NuGet/NuGet.Client/pull/5352) + * [5352](https://github.com/NuGet/NuGet.Client/pull/5352) allow empty sb intermediate +* [drolevar](https://github.com/NuGet/NuGet.Client/pull/5346) + * [5346](https://github.com/NuGet/NuGet.Client/pull/5346) Add .vdproj to the exclusion list +* [Greybird](https://github.com/NuGet/NuGet.Client/pull/5335) + * [5335](https://github.com/NuGet/NuGet.Client/pull/5335) Remove projects from list package output +* [NikolaMilosavljevic](https://github.com/NuGet/NuGet.Client/pull/5322) + * [5322](https://github.com/NuGet/NuGet.Client/pull/5322) Fix incorrect package version property for System.Security.Cryptograp… +* [vishavpandhi](https://github.com/NuGet/NuGet.Client/pull/5283) + * [5283](https://github.com/NuGet/NuGet.Client/pull/5283) [DartLab B2B feature] dropname for base VS should be retrieved using the baseline. +* [v-chayan](https://github.com/NuGet/NuGet.Client/pull/5278) + * [5278](https://github.com/NuGet/NuGet.Client/pull/5278) Remove redundant SourceBuildTrimNetFrameworkTargets property +* [marcin-krystianc](https://github.com/NuGet/NuGet.Client/pull/5293) + * [5293](https://github.com/NuGet/NuGet.Client/pull/5293) DetectAndMarkAmbiguousCentralTransitiveDependencies should be exhaustive and deterministic +* [Erarndt](https://github.com/NuGet/NuGet.Client/pull/5218) + * [5218](https://github.com/NuGet/NuGet.Client/pull/5218) Reduce some allocations in CreateGraphNode. diff --git a/docs/release-notes/NuGet-6.9.md b/docs/release-notes/NuGet-6.9.md new file mode 100644 index 000000000..4870ba3d2 --- /dev/null +++ b/docs/release-notes/NuGet-6.9.md @@ -0,0 +1,112 @@ +--- +title: NuGet 6.9 Release Notes +description: Release notes for NuGet 6.9 including new features, bug fixes, and DCRs. +author: jgonz120 +ms.author: jongonza +ms.date: 2/1/2024 +ms.topic: release-notes +--- + +# NuGet 6.9 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +|:---|:---|:---| +| [**6.9.1**](https://nuget.org/downloads) | [Visual Studio 2022 version 17.9](https://visualstudio.microsoft.com/downloads/) | [8.0.200](https://dotnet.microsoft.com/download/dotnet/8.0)1 | + +1 Installed with Visual Studio 2022 with any .NET workload + +## Summary: What's New in 6.9.1 + +* Support for dotnet search command (equivalent to nuget.exe list, later search) - [#6060](https://github.com/NuGet/Home/issues/6060) [#5138](https://github.com/NuGet/Home/issues/5138) + +* PM UI multi targeting experience is incomplete - support for updating and uninstalling conditional package versions - [#4681](https://github.com/NuGet/Home/issues/4681) + +* [Security]: Microsoft Security Advisory CVE-2024-0057 | NuGet Client Security Feature bypass Vulnerability - [#12653](https://github.com/NuGet/Home/issues/13241) + +### Breaking changes + +* Add nullable annotations to NuGet.LibraryModel - [#12889](https://github.com/NuGet/Home/issues/12889) + +### Issues fixed in this release + +* NuGetAudit should not download vulnerabilities database when project does not use any packages - [#13073](https://github.com/NuGet/Home/issues/13073) + +* Static graph-based restore should not enumerate every item's metadata - [#13049](https://github.com/NuGet/Home/issues/13049) + +* Migrate NuGet.CommandLine.XPlat package search to use System.CommandLine - [#13031](https://github.com/NuGet/Home/issues/13031) + +* Add `--format`, `--verbosity` , `configfile` options to `dotnet package search` - [#12978](https://github.com/NuGet/Home/issues/12978) + +* Set NuGetAudit defaults in MSBuild - [#12960](https://github.com/NuGet/Home/issues/12960) + +* RestoreTask: Control whether to embed files in the binlog - [#12957](https://github.com/NuGet/Home/issues/12957) + +* Create NU Error Code for Package Source Mapping & GPF conflicts - [#12953](https://github.com/NuGet/Home/issues/12953) + +* [DCR]: Allow floating versions with Central Package Management (CPM) - [#10432](https://github.com/NuGet/Home/issues/10432) + +* Static Graph restore won't warn for invalid projects - [#9300](https://github.com/NuGet/Home/issues/9300) + +* Rename no-cache to no-http-cache - [#9180](https://github.com/NuGet/Home/issues/9180) + +* VS Package Manager Console should close Text View - [#13104](https://github.com/NuGet/Home/issues/13104) + +* Vulnerability indicator shows up on dependent project if parent project has transitive vulnerabilities - [#13068](https://github.com/NuGet/Home/issues/13068) + +* Conditional updating when *all* packages are conditioned is broken - [#13034](https://github.com/NuGet/Home/issues/13034) + +* Perf issue in AssetsFileDependenciesDataSource - [#13019](https://github.com/NuGet/Home/issues/13019) + +* The `NuGetPackageSearchService.GetDeprecationMetadataAsync` in `NuGet.PackageManagement.VisualStudio` is dead code - [#13007](https://github.com/NuGet/Home/issues/13007) + +* Vulnerabilities filter shows incorrectly on “Brower” tab when the default tab was “Browse” instead of “Installed” for the previous opening of solution PM UI - [#12974](https://github.com/NuGet/Home/issues/12974) + +* HTTP 401 after some time in VS - [#12961](https://github.com/NuGet/Home/issues/12961) + +* [NuGet.Versioning] SemanticVersion.HasMetadata should indicate that Metadata is not null when true - [#12949](https://github.com/NuGet/Home/issues/12949) + +* TelemetryUtility.ToJsonArrayOfTimingsInSeconds returns incorrect json array on locales having comma as decimal separator - [#12915](https://github.com/NuGet/Home/issues/12915) + +* Static graph-based restore does not respect Interactive option when loading projects - [#12907](https://github.com/NuGet/Home/issues/12907) + +* Vulnerabilities InfoBar link to `Manage NuGet Packages` is truncated - [#12835](https://github.com/NuGet/Home/issues/12835) + +* NuGet.Build.Tasks caches CredentialProvider device flow timeout. - [#12540](https://github.com/NuGet/Home/issues/12540) + +* "error: Sequence contains no matching element" when listing outdated packages - [#12256](https://github.com/NuGet/Home/issues/12256) + +* [Bug]: Process argument string is too long when publishing in Visual Studio with static graph enabled - [#11968](https://github.com/NuGet/Home/issues/11968) + +* [Bug]: PM UI cannot uninstall packages in multitargeting projects - [#11914](https://github.com/NuGet/Home/issues/11914) + +* When a package is installed in the global packages folder, add details about the package location - [#11447](https://github.com/NuGet/Home/issues/11447) + +* NuGet should handle duplicate nomination data better. - [#8749](https://github.com/NuGet/Home/issues/8749) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.9.0.74...6.8.0.131) + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +* [KirillOsenkov](https://github.com/KirillOsenkov) + * Control embedding Restore files in binlog - [5494](https://github.com/NuGet/NuGet.Client/pull/5494) + * Don't log task inputs and outputs when binary logger is enabled - [5498](https://github.com/NuGet/NuGet.Client/pull/5498) +* [Erarndt](https://github.com/Erarndt) + * Unroll Linq usage in FilterDependencyProvidersForLibrary - [5535](https://github.com/NuGet/NuGet.Client/pull/5535) + * Reduce allocations in calls to CreateGraphNode() - [5531](https://github.com/NuGet/NuGet.Client/pull/5531) +* [dotnokato](https://github.com/dotnokato) + * Fix tests failing when run on systems with non-English language/locale settings - [5442](https://github.com/NuGet/NuGet.Client/pull/5442) + * Fix incorrect json array returned for locales with comma as decimal separator in TelemetryUtility.ToJsonArrayOfTimingsInSeconds - [5441](https://github.com/NuGet/NuGet.Client/pull/5441) +* [ellahathaway](https://github.com/ellahathaway) + * Shorten source-build inner clone paths - [5543](https://github.com/NuGet/NuGet.Client/pull/5543) +* [jasonmalinowski](https://github.com/jasonmalinowski) + * Output a more debuggable message if a single value isn't specified - [5533](https://github.com/NuGet/NuGet.Client/pull/5533) +* [mthalman](https://github.com/mthalman) + * Target net9.0 for .NET source build - [5511](https://github.com/NuGet/NuGet.Client/pull/5511) +* [NikolaMilosavljevic](https://github.com/NikolaMilosavljevic) + * Eliminate obsolete API warnings/errors in product source-build - [5496](https://github.com/NuGet/NuGet.Client/pull/5496) +* [amis92](https://github.com/amis92) + * Add MemberNotNullWhen to SemanticVersion.HasMetadata - [5465](https://github.com/NuGet/NuGet.Client/pull/5465) diff --git a/docs/release-notes/NuGet-7.0.md b/docs/release-notes/NuGet-7.0.md new file mode 100644 index 000000000..0de1486cc --- /dev/null +++ b/docs/release-notes/NuGet-7.0.md @@ -0,0 +1,312 @@ +--- +title: NuGet 7.0 Release Notes +description: Release notes for NuGet 7.0 including new features, bug fixes, and DCRs. +author: donnie-msft +ms.author: eagoodso +ms.date: 10/29/2025 +ms.topic: release-notes +--- + +# NuGet 7.0 Release Notes + +NuGet distribution vehicles: + +| NuGet version | Available in Visual Studio version | Available in .NET SDK(s) | +| :---|:---|:---| +| [**7.0.0**](https://nuget.org/downloads) | [Visual Studio 2026 version 18.0.0](https://visualstudio.microsoft.com/downloads/) | [10.0.100](https://dotnet.microsoft.com/download/dotnet/10.0)1 | + +1 Installed with Visual Studio 2026 with any .NET workload + +## Summary: What's New in 7.0.0 + +* Projects that target .NET 10 warn for vulnerabilities in transitive packages by defaulting to NuGetAuditMode=all [#14161](https://github.com/nuget/home/issues/14161) + +* [Package pruning](../consume-packages/Package-References-in-Project-Files.md#prunepackagereference) is enabled for all projects targeting .NET 10 [#14345](https://github.com/NuGet/Home/issues/14345) + +* Created the [NuGet Model Context Protocol (MCP) Server](../concepts/NuGet-MCP-Server.md), supported by .NET 10 SDK or later. +NuGet's MCP is pre-installed in Visual Studio 2026, and installable in VS 17.14 and VS Code. +The server is published on nuget.org as the [NuGet.Mcp.Server](https://www.nuget.org/packages/NuGet.Mcp.Server#readme-body-tab) package. + +* Enable packing legacy PackageReference projects without the need for a package - [#14046](https://github.com/NuGet/Home/issues/14046) + +* Deprecate SHA-1 usage in .NET 10 - [#13814](https://github.com/NuGet/Home/issues/13814) + +* Details pane reflects Vulnerability Data from Audit Sources - [#14554](https://github.com/NuGet/Home/issues/14554) + +* NuGet AuditSources support in the Package Manager UI - [#13954](https://github.com/NuGet/Home/issues/13954) + +* Migrate NuGet's settings to the new Visual Studio Options window + + * Migrate "Package sources" settings in Visual Studio Options - [#14233](https://github.com/NuGet/Home/issues/14233) + + * Migrate "Package Source Mapping" settings in Visual Studio Options - [#14234](https://github.com/NuGet/Home/issues/14234) + +* dotnet update package --vulnerable (Audit fix) - [#13372](https://github.com/NuGet/Home/issues/13372) + +### Breaking changes + +* Add package ID validation during restore - [#14407](https://github.com/NuGet/Home/issues/14407) + +* Project.json is no longer supported in 7.0. Visual Studio 2026 automatically migrated project.json projects to PackageReference + +* Package pruning will lead to a one-time diff in packages lock file - [#14272](https://github.com/NuGet/Home/issues/14272) + +* Pruning privatizes a direct references by apply PrivateAssets=all and IncludeAssets=none - [#14196](https://github.com/NuGet/Home/issues/14196) + +* Raise an error for SHA-1 fingerprints usage in NuGet.exe sign, mssign commands - [#13962](https://github.com/NuGet/Home/issues/13962) + +* Show an error when a non https source is used in a resource in a service index - [#13364](https://github.com/NuGet/Home/issues/13364) + +#### SDK Breaking changes + +* Project.json deprecation + * Remove project.json pack - [#7931](https://github.com/NuGet/Home/issues/7931) + + * Remove project.json support - [#7199](https://github.com/NuGet/Home/issues/7199) + + * Remove PackageSpec.Dependencies - [#14446](https://github.com/NuGet/Home/issues/14446) + + * Clean up Package Spec redudant APIs - [#6231](https://github.com/NuGet/Home/issues/6231) + +* Unused NuGet VS Extensibility APIs removed - [#14403](https://github.com/NuGet/Home/issues/14403) + +* Remove all unused APIs marked as obsolete in NuGet.Frameworks, NuGet.Protocol, NuGet.Commands & NuGet.PackageManagement - [#14395](https://github.com/NuGet/Home/issues/14395) + +* Remove obsolete APIs from NuGet.Common, NuGet.Configuration, NuGet.LibraryModel, NuGet.Packaging and NuGet.ProjectModel - [#14393](https://github.com/NuGet/Home/issues/14393) + +* Block and remove code for unused restore implementations such as `Standalone`. - [#14184](https://github.com/NuGet/Home/issues/14184) + +* Remove `DotnetToolReference` restore - [#14183](https://github.com/NuGet/Home/issues/14183) + +### Issues fixed in this release + +#### NuGet SDK fixes + +* Don't use reflection based deserialization in NuGet.Protocol - [#14470](https://github.com/NuGet/Home/issues/14470) + +* JsonSerializerIsReflectionDisabled on update to Nuget.Protocols 6.13.1 in apps with JsonSerializerIsReflectionEnabledByDefault set to false - [#14111](https://github.com/NuGet/Home/issues/14111) + +#### .NET CLI + +* Enable CanShowDialog for .NET core Authentication Plugins - [#14010](https://github.com/NuGet/Home/issues/14010) + +* "dotnet package update" modifies wrong project file (csproj) - [#14585](https://github.com/NuGet/Home/issues/14585) + +* dotnet nuget verify should output package content hash - [#14384](https://github.com/NuGet/Home/issues/14384) + +* dotnet package update should support --verbosity - [#14319](https://github.com/NuGet/Home/issues/14319) + +* dotnet package update should support CPM and VersionOverride - [#14318](https://github.com/NuGet/Home/issues/14318) + +* dotnet package update should support multiple packages - [#14308](https://github.com/NuGet/Home/issues/14308) + +* dotnet package update should support package source mapping - [#14307](https://github.com/NuGet/Home/issues/14307) + +* dotnet package update to a specific version - [#14306](https://github.com/NuGet/Home/issues/14306) + +* dotnet package update initial version - [#14305](https://github.com/NuGet/Home/issues/14305) + +* [Bug Bash][Unstable] An error “Attempted to divide by zero.” occurs when executing command “dotnet list [ProjectPath] package --vulnerable” - [#14122](https://github.com/NuGet/Home/issues/14122) + +* [Feature]: dotnet list [project | solution] package does not work with solution filters - [#11789](https://github.com/NuGet/Home/issues/11789) + +#### Package Manager UI in Visual Studio + +* Convert Search Control to Fluent UI - [#14469](https://github.com/NuGet/Home/issues/14469) + +* Use Fluent TextBox for Project PM UI Installed Version - [#14466](https://github.com/NuGet/Home/issues/14466) + +* [Bug Bash] There is a tiny gap in the version drop-down list of PM UI - [#11990](https://github.com/NuGet/Home/issues/11990) + +* [Bug Bash] The dropdown list of PM UI doesn’t distinguish the background color between selected-item and hover-on item - [#10977](https://github.com/NuGet/Home/issues/10977) + +* [Bug Bash] Pressing the page-down button on the keyboard when focusing on ‘Version’ drop-down box with Tab key makes the box empty - [#13605](https://github.com/NuGet/Home/issues/13605) + +* Dead Code: ActionsAndVersions View - [#14464](https://github.com/NuGet/Home/issues/14464) + +#### Visual Studio options + +* Decommission Legacy VS Options NuGet Settings - [#14398](https://github.com/NuGet/Home/issues/14398) + +* When adding an http source in the options dialog, have the user click on a checkbox to more explicitly agree to AllowInsecureConnections being added - [#14377](https://github.com/NuGet/Home/issues/14377) + +* Error needed in Package Sources settings for HTTP source without AllowInsecureConnections - [#14367](https://github.com/NuGet/Home/issues/14367) + +* Improve validation of NuGet's settings in Visual Studio Options - [#14359](https://github.com/NuGet/Home/issues/14359) + +* Show validation errors on NuGet options pages while typing - [#14358](https://github.com/NuGet/Home/issues/14358) + +* [Bug Bash] [Unstable] The first removing of a source mapping from the ‘Package Source Mappings’ list in ‘Package Source Mapping’ dialog doesn’t work - [#13520](https://github.com/NuGet/Home/issues/13520) + +* [Localization] The table title ‘Package Source Mapping’ in the ‘Options->NuGet Package Manager->Package Source Mapping’ page was not localized - [#14550](https://github.com/NuGet/Home/issues/14550) + +* [Bug Bash] The offline package source cannot be enabled after disabling it from the ‘Machine-wide package sources’ source list previously in the ‘Options->NuGet Package Manager->Package Sources’ window - [#13434](https://github.com/NuGet/Home/issues/13434) + +* [Bug Bash] The “source” column of the “Add New Package Source Mapping” dialog doesn’t have the minimum width set which makes it can be dragged out of sight - [#13355](https://github.com/NuGet/Home/issues/13355) + +* [Bug Bash] The first reopening of Options dialog should bring back the default package source "Microsoft Visual Studio Offline Packages" in "package sources" list when all the sources were deleted previously - [#13278](https://github.com/NuGet/Home/issues/13278) + +* [Bug Bash] Newly added package source mapping shouldn’t be case-sensitive in “Option->NuGet Package Manager->Package Source Mapping” window - [#13210](https://github.com/NuGet/Home/issues/13210) + +* [Bug Bash] New added package source mapping will lost after switching back to the "Package Source Mapping" tab from other tab in “Option->NuGet Package Manager” window - [#13150](https://github.com/NuGet/Home/issues/13150) + +* [Bug Bash] The “Remove” button should be disable when no package source mapping is selected in the “Package Source Mappings” list - [#13115](https://github.com/NuGet/Home/issues/13115) + +* [CSY] Duplicated hotkeys show in “Options->NuGet Package Manager->Package Sources” dialog - [#7822](https://github.com/NuGet/Home/issues/7822) + +* VS NuGet PMUI - Machine-wide package sources area should be vertically resize-able as well - [#7560](https://github.com/NuGet/Home/issues/7560) + +* [Bug Bash] There will be a duplicated package source when modifying the name of source “Microsoft Visual Studio Offline Packages” - [#13057](https://github.com/NuGet/Home/issues/13057) + +* [Bug Bash] The “Options->NuGet Package Manager->Package Sources” page is disabled after checking or unchecking the checkbox “Enabled” of any one of the package sources having duplicated sources - [#14499](https://github.com/NuGet/Home/issues/14499) + +* Have to manually select pre-populated text on Add Package Source dialog - [#14450](https://github.com/NuGet/Home/issues/14450) + +* VS should not delete Package Source attributes when Name is updated - [#14370](https://github.com/NuGet/Home/issues/14370) + +#### Package Pruning + +* Warning rollout for PrunePackageReference - [#14126](https://github.com/NuGet/Home/issues/14126) + +* Missing audit warnings from "nuget install" when nuget.org is not a package source - [#14096](https://github.com/NuGet/Home/issues/14096) + +* It's not possible to push to HTTP sources specified via command line - [#14047](https://github.com/NuGet/Home/issues/14047) + +* Package pruning is enabled for all projects targeting .NET 10 including multi-targeted ones - [#14345](https://github.com/NuGet/Home/issues/14345) + +* Move pruning enabled frameworks to the NuGet.targets - [#14424](https://github.com/NuGet/Home/issues/14424) + +* Change _RestorePackagePruningDefault to RestorePackagePruningDefault - [#14511](https://github.com/NuGet/Home/issues/14511) + +#### Restore + +* dotnet restore/Visual Studio conflicting with .esproj + Nx project.json - [#13512](https://github.com/NuGet/Home/issues/13512) + +* Improve NU1004 when pruning is used with locked mode - [#14075](https://github.com/NuGet/Home/issues/14075) + +* Consider not writing NuGetToolVersion to generated MSBuild props files on Restore - [#14355](https://github.com/NuGet/Home/issues/14355) + +* NuGet Restore fails if SQL Server Management Studio 21 is installed - [#14349](https://github.com/NuGet/Home/issues/14349) + +* Remove NUGET_EXPERIMENTAL_USE_NJ_FOR_FILE_PARSING - [#14257](https://github.com/NuGet/Home/issues/14257) + +* Remove RestoreTargetGraph.Name as it's redundant with restoreTargetGraph.TargetGraphName being the widely used version - [#14529](https://github.com/NuGet/Home/issues/14529) + +* Remove RestoreArgs.LockFileVersion as it's functionality unused - [#14524](https://github.com/NuGet/Home/issues/14524) + +* Remove NUGET_BULK_RESTORE_COORDINATION and NUGET_SOLUTION_CACHE_INITIALIZATION fallbacks - [#14502](https://github.com/NuGet/Home/issues/14502) + +#### Dependency resolver + +* New dependency resolver does not properly handle floating prerelease versions - [#13833](https://github.com/NuGet/Home/issues/13833) + +* Reenable new algorithm resolution with lock files - [#13800](https://github.com/NuGet/Home/issues/13800) + +#### Other + +* Stop ilmerging pack - [#13079](https://github.com/NuGet/Home/issues/13079) + +* Make NuGet.Client's Build.ps1 more friendly to GitHub Copilot in VSCode - [#14453](https://github.com/NuGet/Home/issues/14453) + +* Generate identical [Content_Types].xml on repeated builds - [#14357](https://github.com/NuGet/Home/issues/14357) + +* pack legacy csproj: include pack targets and tasks in VS build tools - [#14520](https://github.com/NuGet/Home/issues/14520) + +* VS crashes when the only project in the solution is a project.json project - [#14553](https://github.com/NuGet/Home/issues/14553) + +* review exception handling - [#14440](https://github.com/NuGet/Home/issues/14440) + +* Improve perf by avoiding redundant dictionary lookups - [#14432](https://github.com/NuGet/Home/issues/14432) + +* LockFileLibrary does not need to be mutable - [#14385](https://github.com/NuGet/Home/issues/14385) + +[List of commits in this release](https://github.com/NuGet/NuGet.Client/compare/6.14.1.1...7.0.0.289) + +### Community contributions + +Thank you to all the contributors who helped make this NuGet release awesome! + +* [SimonCropp](https://github.com/NuGet/NuGet.Client/pull/6720) + * [6720](https://github.com/NuGet/NuGet.Client/pull/6720) remove redundant default constructors + * [6610](https://github.com/NuGet/NuGet.Client/pull/6610) add "does not have a min version" to messages in GetNupkgInfo + * [6581](https://github.com/NuGet/NuGet.Client/pull/6581) remove redundant dictionary lookups in MarkTransitiveOrigin + * [6596](https://github.com/NuGet/NuGet.Client/pull/6596) enable nullability in PackageItemViewModelTests + * [6634](https://github.com/NuGet/NuGet.Client/pull/6634) remove IFrameworkTargetable + * [6616](https://github.com/NuGet/NuGet.Client/pull/6616) avoid redundant version parsing in PluginFindPackageByIdResource + * [6595](https://github.com/NuGet/NuGet.Client/pull/6595) enable nullability in ReadmePreviewViewModelTests + * [6587](https://github.com/NuGet/NuGet.Client/pull/6587) remove redundant dictionary lookup in ProcessUnrankedEntries + * [6598](https://github.com/NuGet/NuGet.Client/pull/6598) enable nullability in EmbeddedResourcesCapabilityTests + * [6577](https://github.com/NuGet/NuGet.Client/pull/6577) use fields instead of private properties + * [6622](https://github.com/NuGet/NuGet.Client/pull/6622) remove un-used list in GetPackagesToBeReinstalled + * [6589](https://github.com/NuGet/NuGet.Client/pull/6589) redundant null check for projectManagerService.GetMetadataAsync return value + * [6605](https://github.com/NuGet/NuGet.Client/pull/6605) enable nullable in VSRestoreSettingsUtilityTests + * [6575](https://github.com/NuGet/NuGet.Client/pull/6575) remove redundant dictionary lookup in CredentialServiceAdapter.GetCredentials + * [6601](https://github.com/NuGet/NuGet.Client/pull/6601) enable nullabe in NuGetInstallCommandTest + * [6593](https://github.com/NuGet/NuGet.Client/pull/6593) enable nullable in IProjectContextInfoExtensionsTests + * [6614](https://github.com/NuGet/NuGet.Client/pull/6614) remove redundant lists in DependencyGraphFileRequestProvider + * [6625](https://github.com/NuGet/NuGet.Client/pull/6625) remove un-used variables in PackageExtractor + * [6609](https://github.com/NuGet/NuGet.Client/pull/6609) fix nullability in UnresolvedMessages + * [6608](https://github.com/NuGet/NuGet.Client/pull/6608) remove un-used contextForGather + * [6628](https://github.com/NuGet/NuGet.Client/pull/6628) remove redundant enumeration in CredentialsItem + * [6617](https://github.com/NuGet/NuGet.Client/pull/6617) remove toolItems list instance in MSBuildRestoreUtility + * [6599](https://github.com/NuGet/NuGet.Client/pull/6599) fix parameter nullability in Constructor_SetReportAbuseUrl_Initialize… + * [6604](https://github.com/NuGet/NuGet.Client/pull/6604) enable nullable in LegacyPackageReferenceProjectTests + * [6631](https://github.com/NuGet/NuGet.Client/pull/6631) remove DependencyGraphSpecRequestProvider.CollectReferences + * [6635](https://github.com/NuGet/NuGet.Client/pull/6635) remove EnvDteProjectExtensions.PathComparer + * [6623](https://github.com/NuGet/NuGet.Client/pull/6623) remove redundant GetManifestResourceNames in ManifestSchemaUtility + * [6619](https://github.com/NuGet/NuGet.Client/pull/6619) remove unused packageID variable + * [6620](https://github.com/NuGet/NuGet.Client/pull/6620) remove un-used variables in PackageManagerControl + * [6640](https://github.com/NuGet/NuGet.Client/pull/6640) remove redundant exception handling + * [6637](https://github.com/NuGet/NuGet.Client/pull/6637) remove PackageManagerControl.AddMigratorBar + * [6629](https://github.com/NuGet/NuGet.Client/pull/6629) remove un-used HashSet instance in ResolverMetadataClient + * [6602](https://github.com/NuGet/NuGet.Client/pull/6602) enable nullable in MSBuildUtilityTest + * [6641](https://github.com/NuGet/NuGet.Client/pull/6641) remove redundant null condition in UpdateCommand.ExecuteCommandAsync + * [6683](https://github.com/NuGet/NuGet.Client/pull/6683) remove redundant string alloc in GetTempFilePath + * [6626](https://github.com/NuGet/NuGet.Client/pull/6626) remove un-used variables in SignedPackageArchiveIOUtility + * [6574](https://github.com/NuGet/NuGet.Client/pull/6574) remove redundant dictionary lookup in CreatePackageSourceMappingDictionary + * [6594](https://github.com/NuGet/NuGet.Client/pull/6594) enable nullability in InfiniteScrollListTests + * [6682](https://github.com/NuGet/NuGet.Client/pull/6682) Use async delay in SafeReadAsync + * [6600](https://github.com/NuGet/NuGet.Client/pull/6600) enable nullable in NuGetUpdateCommandTests + * [6606](https://github.com/NuGet/NuGet.Client/pull/6606) enable nullable in VSNominationUtilitiesTests + * [6613](https://github.com/NuGet/NuGet.Client/pull/6613) remove redundant type variable in GetExternalProject + * [6611](https://github.com/NuGet/NuGet.Client/pull/6611) remove un-used solutionService instances + * [6643](https://github.com/NuGet/NuGet.Client/pull/6643) remove MsBuildUtility.GetMsBuildPathInPathVar + * [6632](https://github.com/NuGet/NuGet.Client/pull/6632) remove PackageSpecFactory.GetTargetFrameworkStrings + * [6573](https://github.com/NuGet/NuGet.Client/pull/6573) avoid some allocation in ProjectFactory.ProcessDependencies + * [6588](https://github.com/NuGet/NuGet.Client/pull/6588) remove dictionary lookups from GetPreviewResultsAsync + * [6597](https://github.com/NuGet/NuGet.Client/pull/6597) fix nullability in PackageModelCreationTestHelper + * [6612](https://github.com/NuGet/NuGet.Client/pull/6612) remove un-used list instances in NuGetPackageManager + * [6591](https://github.com/NuGet/NuGet.Client/pull/6591) enable nullable in PackageSourceValidatorTests + * [6603](https://github.com/NuGet/NuGet.Client/pull/6603) fix nullability in IVsProjectBuildProperties + * [6636](https://github.com/NuGet/NuGet.Client/pull/6636) remove _project* fields from PackageReferenceProject + * [6630](https://github.com/NuGet/NuGet.Client/pull/6630) remove un-used identity instance in LocalV3FindPackageByIdResource + * [6618](https://github.com/NuGet/NuGet.Client/pull/6618) remove LoggerAdapter instance in NuGetPackageManager + * [6621](https://github.com/NuGet/NuGet.Client/pull/6621) remove un-used projectsByUniqueName in SolutionUpToDateChecker + * [6624](https://github.com/NuGet/NuGet.Client/pull/6624) remove un-used variables in PackageBuilder + * [6633](https://github.com/NuGet/NuGet.Client/pull/6633) remove JsonPackageSpecReader DelimitedStringSeparators and VersionSeparators + * [6642](https://github.com/NuGet/NuGet.Client/pull/6642) use cast instead of as and null check in CommandLineParser.AssignValue + * [6615](https://github.com/NuGet/NuGet.Client/pull/6615) remove redundant list in GetPluginAsync + * [6627](https://github.com/NuGet/NuGet.Client/pull/6627) remove un-used GetDirectoryName in MisplacedAssemblyOutsideLibRule + * [6578](https://github.com/NuGet/NuGet.Client/pull/6578) remove redundant dictionary lookup in PrunePackageTree.PruneDowngrades + * [6576](https://github.com/NuGet/NuGet.Client/pull/6576) remove redundant dictionary lookup in RecommenderPackageFeed +* [baronfel](https://github.com/NuGet/NuGet.Client/pull/6554) + * [6554](https://github.com/NuGet/NuGet.Client/pull/6554) Fix NuGet->SDK Codeflow + * [6514](https://github.com/NuGet/NuGet.Client/pull/6514) Pin and stabilize the `NuGetToolVersion` property in the generated NuGet props files during restore. +* [omajid](https://github.com/NuGet/NuGet.Client/pull/6500) + * [6500](https://github.com/NuGet/NuGet.Client/pull/6500) Ensure stable order of entries in Content_Types.xml + * [6507](https://github.com/NuGet/NuGet.Client/pull/6507) Support building on Linux when full signing is not available +* [AlexDelepine](https://github.com/NuGet/NuGet.Client/pull/6793) + * [6793](https://github.com/NuGet/NuGet.Client/pull/6793) Update Ngen Priorities for VS +* [hickford](https://github.com/NuGet/NuGet.Client/pull/6475) + * [6475](https://github.com/NuGet/NuGet.Client/pull/6475) Populate audit sources consistently +* [nohwnd](https://github.com/NuGet/NuGet.Client/pull/6735) + * [6735](https://github.com/NuGet/NuGet.Client/pull/6735) Disable loading profile in utility powershell.exe calls +* [mmitche](https://github.com/NuGet/NuGet.Client/pull/6539) + * [6539](https://github.com/NuGet/NuGet.Client/pull/6539) Move NuGet to xliff-tasks +* [dkurepa](https://github.com/NuGet/NuGet.Client/pull/6644) + * [6644](https://github.com/NuGet/NuGet.Client/pull/6644) Add Version.Details.props +* [bdukes](https://github.com/NuGet/NuGet.Client/pull/6530) + * [6530](https://github.com/NuGet/NuGet.Client/pull/6530) Fix `nuget.exe` restore finding MSBuild from SSMS instead of Visual Studio +* [ToddGrun](https://github.com/NuGet/NuGet.Client/pull/6519) + * [6519](https://github.com/NuGet/NuGet.Client/pull/6519) Make LockFileLibrary immutable for performance and sanity reasons + \ No newline at end of file diff --git a/docs/release-notes/media/NuGet-6.0/VS-Deprecation.png b/docs/release-notes/media/NuGet-6.0/VS-Deprecation.png new file mode 100644 index 000000000..1685da19c Binary files /dev/null and b/docs/release-notes/media/NuGet-6.0/VS-Deprecation.png differ diff --git a/docs/release-notes/media/NuGet-6.0/VS-Vulnerability.png b/docs/release-notes/media/NuGet-6.0/VS-Vulnerability.png new file mode 100644 index 000000000..32db7425a Binary files /dev/null and b/docs/release-notes/media/NuGet-6.0/VS-Vulnerability.png differ diff --git a/docs/release-notes/media/NuGet-6.0/dotnet.png b/docs/release-notes/media/NuGet-6.0/dotnet.png new file mode 100644 index 000000000..a69d9fe96 Binary files /dev/null and b/docs/release-notes/media/NuGet-6.0/dotnet.png differ diff --git a/docs/release-notes/media/releasenotes-59-context-update.gif b/docs/release-notes/media/releasenotes-59-context-update.gif new file mode 100644 index 000000000..f04d388a7 Binary files /dev/null and b/docs/release-notes/media/releasenotes-59-context-update.gif differ diff --git a/docs/release-notes/media/releasenotes-59-requested-version.png b/docs/release-notes/media/releasenotes-59-requested-version.png new file mode 100644 index 000000000..345dcd076 Binary files /dev/null and b/docs/release-notes/media/releasenotes-59-requested-version.png differ diff --git a/docs/release-notes/media/releasenotes-59-update.png b/docs/release-notes/media/releasenotes-59-update.png new file mode 100644 index 000000000..cefb690f2 Binary files /dev/null and b/docs/release-notes/media/releasenotes-59-update.png differ diff --git a/docs/resources/NuGet-FAQ.md b/docs/resources/NuGet-FAQ.md deleted file mode 100644 index fe380a7e2..000000000 --- a/docs/resources/NuGet-FAQ.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: NuGet Frequently-Asked Questions -description: Common questions and answers for using NuGet on the command line and in Visual Studio -author: shishirx34 -ms.author: shishirh -ms.date: 06/05/2019 -ms.topic: conceptual ---- - -# NuGet frequently-asked questions - -For frequently-asked questions pertaining to NuGet.org, such as NuGet.org account questions, see [NuGet.org frequently-asked questions](../nuget-org/nuget-org-faq.md). - -**What is required to run NuGet?** - -All the information around both UI and command-line tools is available in the [Install guide](../install-nuget-client-tools.md). - -**Does NuGet support Mono?** - -The command-line tool, `nuget.exe`, builds and runs under Mono 3.2+ and can create packages in Mono. - -Although `nuget.exe` works fully on Windows, there are known issues on Linux and OS X. Refer to [Mono issues](https://github.com/NuGet/Home/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+mono) on GitHub. - -A [graphical client](https://github.com/mrward/monodevelop-nuget-addin) is available as an add-in for MonoDevelop. - -**How can I determine what a package contains and whether it's stable and useful for my application?** - -The primary source for learning about a package is its listing page on nuget.org (or another private feed). Each package page on nuget.org includes a description of the package, its version history, and usage statistics. The **Info** section on the package page also contains a link to the project's web site where you typically find many examples and other documentation to help you learn how the package is used. - -For more information, see [Finding and choosing packages](../consume-packages/finding-and-choosing-packages.md). - -## NuGet in Visual Studio - -**How is NuGet supported in different Visual Studio products?** - -- Visual Studio on Windows supports the [Package Manager UI](../consume-packages/install-use-packages-visual-studio.md) and the [Package Manager Console](../consume-packages/install-use-packages-powershell.md). -- Visual Studio for Mac has built-in NuGet capabilities as described on [Including a NuGet package in your project](/visualstudio/mac/nuget-walkthrough). -- Visual Studio Code (all platforms) does not have any direct NuGet integration. Use the [NuGet CLI](../reference/nuget-exe-cli-reference.md) or the [dotnet CLI](../reference/dotnet-commands.md). -- Azure DevOps provides [a build step to restore NuGet packages](/vsts/build-release/tasks/package/nuget). You can also [host private NuGet package feeds on Azure DevOps](https://docs.microsoft.com/azure/devops/artifacts/nuget/publish). - -**How do I check the exact version of the NuGet tools that are installed?** - -In Visual Studio, use the **Help > About Microsoft Visual Studio** command and look at the version displayed next to **NuGet Package Manager**. - -Alternatively, launch the Package Manager Console (**Tools > NuGet Package Manager > Package Manager Console**) and enter `$host` to see information about NuGet including the version. - -**What programming languages are supported by NuGet?** - -NuGet generally works for .NET languages and is designed to bring .NET libraries into a project. Because it also supports MSBuild and Visual Studio automation in some project types, it also supports other projects and languages to various degrees. - -The most recent version of NuGet supports C#, Visual Basic, F#, WiX, and C++. - -**What project templates are supported by NuGet?** - -NuGet has full support for a variety of project templates like Windows, Web, Cloud, SharePoint, Wix, and so on. - -**How do I update packages that are part of Visual Studio templates?** - -Go to the **Updates** tab in the Package Manager UI and select **Update All**, or use the [`Update-Package` command](../reference/ps-reference/ps-ref-update-package.md) from the Package Manager Console. - -To update the template itself, you need to manually update the template repository. See [Xavier Decoster's blog](http://www.xavierdecoster.com/update-project-template-to-latest-nuget-packages) on this subject. Note that this is done at your own risk, because manual updates might corrupt the template if the latest version of all dependencies are not compatible with each other. - -**Can I use NuGet outside of Visual Studio?** - -Yes, NuGet works directly from the command line. See the [Install guide](../install-nuget-client-tools.md) and the [CLI reference](../reference/nuget-exe-cli-reference.md). - -## NuGet command line - -**How do I get the latest version of NuGet command line tool?** - -See the [Install guide](../install-nuget-client-tools.md). To check the current installed version of the tool, use `nuget help`. - -**What is the license for nuget.exe?** - -You are allowed to redistribute nuget.exe under the terms of the MIT license. You are responsible for updating and servicing any copies of nuget.exe that you choose to redistribute. - -**Is it possible to extend the NuGet command line tool?** - -Yes, it's possible to add custom commands to `nuget.exe`, as described in [Rob Reynold's post](http://geekswithblogs.net/robz/archive/2011/07/15/extend-nuget-command-line.aspx). - -## NuGet Package Manager Console (Visual Studio on Windows) - -**How do I get access to the DTE object in the Package Manager console?** - -The top-level object in the Visual Studio automation object model is called the DTE (Development Tools Environment) object. The console provides this through a variable named `$DTE`. For more information, see [Automation Model Overview](/visualstudio/extensibility/internals/automation-model-overview) in the Visual Studio Extensibility documentation. - -**I try to cast the $DTE variable to the type DTE2, but I get an error: Cannot convert the "EnvDTE.DTEClass" value of type "EnvDTE.DTEClass" to type "EnvDTE80.DTE2". What's wrong?** - -This is a known issue with how PowerShell interacts with a COM object. Try the following: - -```ps -`$dte2 = Get-Interface $dte ([EnvDTE80.DTE2])` -``` - -`Get-Interface` is a helper function added by the NuGet PowerShell host. - -## Creating and publishing packages - -**How do I list my package in a feed?** - -See [Creating and publishing a package](../quickstart/create-and-publish-a-package.md). - -**I have multiple versions of my library that target different versions of the .NET Framework. How do I build a single package that supports this?** - -See [Supporting Multiple .NET Framework Versions and Profiles](../create-packages/supporting-multiple-target-frameworks.md). - -**How do I set up my own repository or feed?** - -See the [Hosting packages overview](../hosting-packages/overview.md). - -**How can I upload packages to my NuGet feed in bulk?** - -See [Bulk publishing NuGet packages](http://jeffhandley.com/archive/2012/12/13/Bulk-Publishing-NuGet-Packages.aspx) (jeffhandly.com). - -## Working with packages - -**What is the difference between a project-level package and a solution-level package?** - -A solution-level package (NuGet 3.x+) is installed only once in a solution and is then available for all projects in the solution. A project-level package is installed in each project that uses it. A solution-level package might also install new commands that can be called from within the Package Manager Console. - -**Is it possible to install NuGet packages without Internet connectivity?** - -Yes, see Scott Hanselman's Blog post [How to access NuGet when nuget.org is down (or you're on a plane)](http://www.hanselman.com/blog/HowToAccessNuGetWhenNuGetorgIsDownOrYoureOnAPlane.aspx) (hanselman.com). - -**How do I install packages in a different location from the default packages folder?** - -Set the [`repositoryPath`](../reference/nuget-config-file.md#config-section) setting in `Nuget.Config` using `nuget config -set repositoryPath=`. - -**How do I avoid adding the NuGet packages folder into to source control?** - -Set the [`disableSourceControlIntegration`](../reference/nuget-config-file.md#solution-section) in `Nuget.Config` to `true`. This key works at the solution level and hence need to be added to the `$(Solutiondir)\.nuget\Nuget.Config` file. Enabling package restore from Visual Studio creates this file automatically. - -**How do I turn off package restore?** - -See [Enabling and disabling package restore](../consume-packages/package-restore.md#enable-and-disable-package-restore-in-visual-studio). - -**Why do I get an "Unable to resolve dependency error" when installing a local package with remote dependencies?** - -You need to select the **All** source when installing a local package into the project. This aggregates all the feeds instead of using just one. The reason this error appears is that users of a local repository often want to avoid accidentally installing a remote package due to corporate polices. - -**I have multiple projects in the same folder, how can I use separate packages.config files for each project?** - -In most projects where separate projects live in separate folders, this is not a problem as NuGet identifies the `packages.config` files in each project. With NuGet 3.3+ and multiple projects in the same folder, you can insert the name of the project into the `packages.config` filenames use the pattern `packages.{project-name}.config`, and NuGet uses that file. - -This is not an issue when using PackageReference, as each project file contains its own list of dependencies. - -**I don't see nuget.org in my list of repositories, how do I get it back?** - -- Add `https://api.nuget.org/v3/index.json` to your list of sources, or -- Delete `%appdata%\.nuget\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) and let NuGet re-create it. diff --git a/docs/resources/NuGet-FAQ.yml b/docs/resources/NuGet-FAQ.yml new file mode 100644 index 000000000..07bb046b1 --- /dev/null +++ b/docs/resources/NuGet-FAQ.yml @@ -0,0 +1,190 @@ +### YamlMime:FAQ +metadata: + title: NuGet Frequently-Asked Questions + description: Common questions and answers for using NuGet on the command line and in Visual Studio + author: shishirx34 + ms.author: shishirh + ms.date: 01/31/2022 + ms.topic: faq + +title: NuGet frequently-asked questions +summary: | + For frequently-asked questions pertaining to NuGet.org, such as NuGet.org account questions, see [NuGet.org frequently-asked questions](../nuget-org/nuget-org-faq.yml). + + +sections: + - name: General + questions: + - question: | + What is required to run NuGet? + answer: | + All the information around both UI and command-line tools is available in the [Install guide](../install-nuget-client-tools.md). + + - question: | + Does NuGet support Mono? + answer: | + The command-line tool, `nuget.exe`, builds and runs typically under Windows. NuGet can run on Unix operating systems using `mono`, but it is not officially supported by [NuGet's Support Policy](https://devblogs.microsoft.com/nuget/announcing-nuget-exe-and-nuget-client-sdk-packages-support-policy-keeping-you-informed-and-secure/). + + [Mono has transferred ownership to Wine and is no longer maintained by Microsoft](https://github.com/mono/mono/issues/21796). + + - question: | + How can I determine what a package contains and whether it's stable and useful for my application? + answer: | + The primary source for learning about a package is its listing page on nuget.org (or another private feed). Each package page on nuget.org includes a description of the package, its version history, and usage statistics. The **Info** section on the package page also contains a link to the project's web site where you typically find many examples and other documentation to help you learn how the package is used. + + For more information, see [Finding and choosing packages](../consume-packages/finding-and-choosing-packages.md). + + - name: NuGet in Visual Studio + questions: + - question: | + How is NuGet supported in different Visual Studio products? + answer: | + - Visual Studio on Windows supports the [Package Manager UI](../consume-packages/install-use-packages-visual-studio.md) and the [Package Manager Console](../consume-packages/install-use-packages-powershell.md). + - Visual Studio for Mac has built-in NuGet capabilities as described on [Including a NuGet package in your project](/visualstudio/mac/nuget-walkthrough). + - Visual Studio Code (all platforms) does not have any direct NuGet integration. Use the [NuGet CLI](../reference/nuget-exe-cli-reference.md) or the [dotnet CLI](../reference/dotnet-commands.md). + - Azure DevOps provides [a build step to restore NuGet packages](/vsts/build-release/tasks/package/nuget). You can also [host private NuGet package feeds on Azure DevOps](/azure/devops/artifacts/nuget/publish). + + - question: | + How do I check the exact version of the NuGet tools that are installed? + answer: | + In Visual Studio, use the **Help > About Microsoft Visual Studio** command and look at the version displayed next to **NuGet Package Manager**. + + Alternatively, launch the Package Manager Console (**Tools > NuGet Package Manager > Package Manager Console**) and enter `$host` to see information about NuGet including the version. + + - question: | + What programming languages are supported by NuGet? + answer: | + NuGet generally works for .NET languages and is designed to bring .NET libraries into a project. Because it also supports MSBuild and Visual Studio automation in some project types, it also supports other projects and languages to various degrees. + + The most recent version of NuGet supports C#, Visual Basic, F#, WiX, C++, and Q#. + + - question: | + What project templates are supported by NuGet? + answer: | + NuGet has full support for a variety of project templates like Windows, Web, Cloud, SharePoint, Wix, and so on. + + - question: | + How do I update packages that are part of Visual Studio templates? + answer: | + Go to the **Updates** tab in the Package Manager UI and select **Update All**, or use the [`Update-Package` command](../reference/ps-reference/ps-ref-update-package.md) from the Package Manager Console. + + To update the template itself, you need to manually update the template repository. See [Xavier Decoster's blog](http://www.xavierdecoster.com/update-project-template-to-latest-nuget-packages) on this subject. Note that this is done at your own risk, because manual updates might corrupt the template if the latest version of all dependencies are not compatible with each other. + + - question: | + Can I use NuGet outside of Visual Studio? + answer: | + Yes, NuGet works directly from the command line. See the [Install guide](../install-nuget-client-tools.md) and the [CLI reference](../reference/nuget-exe-cli-reference.md). + + - name: NuGet command line + questions: + - question: | + How do I get the latest version of NuGet command line tool? + answer: | + See the [Install guide](../install-nuget-client-tools.md). To check the current installed version of the tool, use `nuget help`. + + - question: | + What is the license for nuget.exe? + answer: | + You are allowed to redistribute nuget.exe under the terms of the MIT license. You are responsible for updating and servicing any copies of nuget.exe that you choose to redistribute. + + - question: | + Is it possible to extend the NuGet command line tool? + answer: | + Yes, it's possible to add custom commands to `nuget.exe`, as described in [Rob Reynold's post](https://web.archive.org/web/20200814172907/http://geekswithblogs.net/robz/archive/2011/07/15/extend-nuget-command-line.aspx) available via Archive.org. + + - name: NuGet Package Manager Console (Visual Studio on Windows) + questions: + - question: | + How do I get access to the DTE object in the Package Manager console? + answer: | + The top-level object in the Visual Studio automation object model is called the DTE (Development Tools Environment) object. The console provides this through a variable named `$DTE`. For more information, see [Automation Model Overview](/visualstudio/extensibility/internals/automation-model-overview) in the Visual Studio Extensibility documentation. + + - question: | + I try to cast the $DTE variable to the type DTE2, but I get an error: Cannot convert the "EnvDTE.DTEClass" value of type "EnvDTE.DTEClass" to type "EnvDTE80.DTE2". What's wrong? + answer: | + This is a known issue with how PowerShell interacts with a COM object. Try the following: + + ```ps + `$dte2 = Get-Interface $dte ([EnvDTE80.DTE2])` + ``` + + `Get-Interface` is a helper function added by the NuGet PowerShell host. + + - name: Creating and publishing packages + questions: + - question: | + How do I list my package in a feed? + answer: | + See [Creating and publishing a package](../quickstart/create-and-publish-a-package-using-visual-studio.md). + + - question: | + I have multiple versions of my library that target different versions of the .NET Framework. How do I build a single package that supports this? + answer: | + See [Supporting Multiple .NET Framework Versions and Profiles](../create-packages/supporting-multiple-target-frameworks.md). + + - question: | + How do I set up my own repository or feed? + answer: | + See the [Hosting packages overview](../hosting-packages/overview.md). + + - question: | + How can I upload packages to my NuGet feed in bulk? + answer: | + See [Bulk publishing NuGet packages](http://jeffhandley.com/archive/2012/12/13/Bulk-Publishing-NuGet-Packages.aspx) (jeffhandly.com). + + - name: Working with packages + questions: + - question: | + Is it possible to install NuGet packages without Internet connectivity? + answer: | + Yes, see Scott Hanselman's Blog post [How to access NuGet when nuget.org is down (or you're on a plane)](http://www.hanselman.com/blog/HowToAccessNuGetWhenNuGetorgIsDownOrYoureOnAPlane.aspx) (hanselman.com). + + - question: | + How do I install packages in a different location from the default packages folder? + answer: | + Set the [`repositoryPath`](../reference/nuget-config-file.md#config-section) setting in `Nuget.Config` using `nuget config -set repositoryPath=`. + + - question: | + How do I avoid adding the NuGet packages folder into to source control? + answer: | + Set the [`disableSourceControlIntegration`](../reference/nuget-config-file.md#solution-section) in `Nuget.Config` to `true`. This key works at the solution level and hence need to be added to the `$(Solutiondir)\.nuget\Nuget.Config` file. Enabling package restore from Visual Studio creates this file automatically. + + - question: | + How do I turn off package restore? + answer: | + See [Enabling and disabling package restore](../consume-packages/package-restore.md#enable-and-disable-package-restore-in-visual-studio). + + - question: | + Why do I get an "Unable to resolve dependency error" when installing a local package with remote dependencies? + answer: | + You need to select the **All** source when installing a local package into the project. This aggregates all the feeds instead of using just one. The reason this error appears is that users of a local repository often want to avoid accidentally installing a remote package due to corporate polices. + + - question: | + I have multiple projects in the same folder, how can I use separate packages.config files for each project? + answer: | + In most projects where separate projects live in separate folders, this is not a problem as NuGet identifies the `packages.config` files in each project. With NuGet 3.3+ and multiple projects in the same folder, you can insert the name of the project into the `packages.config` filenames use the pattern `packages.{project-name}.config`, and NuGet uses that file. + + This is not an issue when using PackageReference, as each project file contains its own list of dependencies. + + - question: | + I don't see nuget.org in my list of repositories, how do I get it back? + answer: | + - Add `https://api.nuget.org/v3/index.json` to your list of sources, or + - Delete `%appdata%\.nuget\NuGet.Config` (Windows) or `~/.nuget/NuGet/NuGet.Config` (Mac/Linux) and let NuGet re-create it. + + - question: | + I migrated to PackageReference, why is my build failing `This project references NuGet package(s) that are missing on this computer.`? + answer: | + In packages.config projects, when a package with `build` props or targets was installed, NuGet would add an `EnsureNuGetPackageBuildImports` target to verify that the packages msbuild content has been imported before building. + If the `target` has been modified manually, NuGet might not be able to detect that it needs removed when migrating. + + If your project is `PackageReference` and you still have this target in project file, it should be safe to remove. + + - question: | + There is no README in Visual Studio NuGet Package Manager for the selected package. + answer: | + If you see the message "There is no README available for the selected package version" in Visual Studio NuGet Package Manager, that means that the selected version of the NuGet package does not have an embedded README file. + - If this is not the latest version of the package, consider checking the latest version. + - If the latest version doesn't have the README file embedded either, and you are not the maintainer of this package, consider filing an issue or contacting the maintainer to request a README. + - If you are the maintainer of the package, here is the guide on [how to embed the README in your package](https://aka.ms/nuget/readme). Please note that if you have added the README file on NuGet.org but didn't embed it in your package, the README will not be shown in Visual Studio. + diff --git a/docs/resources/check-project-format.md b/docs/resources/check-project-format.md index 03e7ce594..b7ed7d665 100644 --- a/docs/resources/check-project-format.md +++ b/docs/resources/check-project-format.md @@ -4,7 +4,7 @@ description: Describes how to identity your project format author: mikejo5000 ms.author: mikejo ms.date: 07/09/2019 -ms.topic: conceptual +ms.topic: article --- # Identify the project format @@ -15,10 +15,10 @@ Whether your project is SDK-style or not depends on the method used to create th | Project               | Default project format | CLI tool          | Notes | |:------------- |:-------------|:-----|:-----| -| .NET Standard | SDK-style | [dotnet CLI](../install-nuget-client-tools.md#dotnetexe-cli) | Projects created prior to Visual Studio 2017 are non-SDK-style. Use `nuget.exe` CLI. | -| .NET Core | SDK-style | [dotnet CLI](../install-nuget-client-tools.md#dotnetexe-cli) | Projects created prior to Visual Studio 2017 are non-SDK-style. Use `nuget.exe` CLI. | -| .NET Framework | Non-SDK-style | [nuget.exe CLI](../install-nuget-client-tools.md#nugetexe-cli) | .NET Framework projects created using other methods may be SDK-style projects. For these, use [dotnet CLI](../install-nuget-client-tools.md#dotnetexe-cli) instead. | -| [Migrated](../consume-packages/migrate-packages-config-to-package-reference.md) .NET project | Non-SDK-style| To create packages, use [msbuild -t:pack](../consume-packages/migrate-packages-config-to-package-reference.md#create-a-package-after-migration) to create packages. | To create packages, `msbuild -t:pack` is recommended. Otherwise, use the [dotnet CLI](../install-nuget-client-tools.md#dotnetexe-cli). Migrated projects are not SDK-style projects. | +| .NET Standard | SDK-style | [dotnet SDK](../install-nuget-client-tools.md#dotnet-sdk) | Projects created prior to Visual Studio 2017 are non-SDK-style. Use `nuget.exe` CLI. | +| .NET Core | SDK-style | [dotnet SDK](../install-nuget-client-tools.md#dotnet-sdk) | Projects created prior to Visual Studio 2017 are non-SDK-style. Use `nuget.exe` CLI. | +| .NET Framework | Non-SDK-style | [nuget.exe CLI](../install-nuget-client-tools.md#nugetexe-cli) | .NET Framework projects created using other methods may be SDK-style projects. For these, use [dotnet SDK](../install-nuget-client-tools.md#dotnet-sdk) instead. | +| [Migrated](../consume-packages/migrate-packages-config-to-package-reference.md) .NET project | Non-SDK-style| To create packages, use [msbuild -t:pack](../consume-packages/migrate-packages-config-to-package-reference.md#create-a-package-after-migration) to create packages. | To create packages, `msbuild -t:pack` is recommended. Otherwise, use the [dotnet SDK](../install-nuget-client-tools.md#dotnet-sdk). Migrated projects are not SDK-style projects. | ## Check the project format diff --git a/docs/visual-studio-extensibility/Project-System-Support.md b/docs/visual-studio-extensibility/Project-System-Support.md index 10c8cc15e..a2d19776a 100644 --- a/docs/visual-studio-extensibility/Project-System-Support.md +++ b/docs/visual-studio-extensibility/Project-System-Support.md @@ -1,8 +1,8 @@ --- title: NuGet Support for the Visual Studio Project System description: Integration of NuGet into the Visual Studio project system for third-party project types. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/09/2017 ms.topic: reference --- @@ -109,6 +109,6 @@ case __VSHPROPID8.VSHPROPID_ProjectCapabilitiesChecker: ## DTE Support -NuGet drives the project system to add references, content items, and MSBuild imports by calling into [DTE](/dotnet/api/envdte.dte?view=visualstudiosdk-2017), which is the top-level Visual Studio automation interface. DTE is a set of COM interfaces that you may already implement. +NuGet drives the project system to add references, content items, and MSBuild imports by calling into [DTE](/dotnet/api/envdte.dte), which is the top-level Visual Studio automation interface. DTE is a set of COM interfaces that you may already implement. If your project type is based on CPS, DTE is implemented for you. diff --git a/docs/visual-studio-extensibility/Visual-Studio-Templates.md b/docs/visual-studio-extensibility/Visual-Studio-Templates.md index 8184cb33c..aa1cf0484 100644 --- a/docs/visual-studio-extensibility/Visual-Studio-Templates.md +++ b/docs/visual-studio-extensibility/Visual-Studio-Templates.md @@ -1,10 +1,10 @@ --- title: NuGet Packages in Visual Studio templates description: Instructions for including NuGet packages as part of Visual Studio project and item templates. -author: karann-msft -ms.author: karann +author: JonDouglas +ms.author: jodou ms.date: 01/03/2018 -ms.topic: conceptual +ms.topic: article --- # Packages in Visual Studio templates @@ -20,7 +20,9 @@ The remainder of this section describes the specific steps to take when authorin - [Adding packages to a template](#adding-packages-to-a-template) - [Best practices](#best-practices) -For an example, see the [NuGetInVsTemplates sample](https://bitbucket.org/marcind/nugetinvstemplates). +## Samples + +The [Preinstalled-Packages](https://github.com/NuGet/Samples/tree/main/Preinstalled-Packages) sample is available in the NuGet/Samples repository on GitHub. ## Adding packages to a template @@ -88,7 +90,7 @@ If you are distributing only a single project/item template and do not need to p 1. Modify the `` element in the `.vstemplate` file as follows: ```xml - + ``` @@ -131,7 +133,7 @@ SDKs that are installed using an MSI can install NuGet packages directly on the ```xml NuGet Package Manager - http://docs.microsoft.com/nuget/ + http://learn.microsoft.com/nuget/ ``` diff --git a/docs/visual-studio-extensibility/nuget-api-in-visual-studio.md b/docs/visual-studio-extensibility/nuget-api-in-visual-studio.md index b8521399c..e49186605 100644 --- a/docs/visual-studio-extensibility/nuget-api-in-visual-studio.md +++ b/docs/visual-studio-extensibility/nuget-api-in-visual-studio.md @@ -1,41 +1,121 @@ --- title: NuGet API in Visual Studio description: Interface reference for the API that NuGet exports through the Managed Extensibility Framework in Visual Studio -author: karann-msft -ms.author: karann +author: nkolev92 +ms.author: nikolev ms.date: 01/09/2017 ms.topic: reference --- # NuGet API in Visual Studio -In addition to the Package Manager UI and Console in Visual Studio, NuGet also exports some useful services through the [Managed Extensibility Framework (MEF)](/dotnet/framework/mef/index). This interface allows other components in Visual Studio to interact with NuGet, which can be used to install and uninstall packages, and to obtain information about installed packages. +In addition to the Package Manager UI and Console in Visual Studio, NuGet also exports some useful services that other extensions can use. These interfaces allow other components in Visual Studio to interact with NuGet, which can be used to install and uninstall packages, and to obtain information about installed packages. -As of NuGet 3.3+, NuGet exports the following services all of which reside in the `NuGet.VisualStudio` namespace in the `NuGet.VisualStudio.dll` assembly: +NuGet provides services via two different technologies, each of which have their interfaces defined in a different NuGet package. NuGet's older services are available via [the Managed Extensibility Framework (MEF)](/dotnet/framework/mef/), which are available in the package [NuGet.VisualStudio](https://www.nuget.org/packages/NuGet.VisualStudio) ([go to NuGet's MEF services](#mef-services)). There are newer APIs, designed to be usable with `async` code, available in the package `NuGet.VisualStudio.Contracts`, using a Visual Studio's `IServiceBroker` ([go to NuGet's Brokered Services](#brokered-services)). -- [`IRegistryKey`](#iregistrykey-interface): Method to retrieve a value from a registry subkey. -- [`IVsPackageInstaller`](#ivspackageinstaller-interface): Methods to install NuGet packages into projects. -- [`IVsPackageInstallerEvents`](#ivspackageinstallerevents-interface): Events for package install/uninstall. -- [`IVsPackageInstallerProjectEvents`](#ivspackageinstallerprojectevents-interface): Batch events for package install/uninstall. -- [`IVsPackageInstallerServices`](#ivspackageinstallerservices-interface): Methods to retrieve installed packages in the current solution and to check whether a given package is installed in a project. -- [`IVsPackageManagerProvider`](#ivspackagemanagerprovider-interface): Methods to provide alternative Package Manager suggestions for a NuGet package. -- [`IVsPackageMetadata`](#ivspackagemetadata-interface): Methods to retrieve information about an installed package. -- [`IVsPackageProjectMetadata`](#ivspackageprojectmetadata-interface): Methods to retrieve information about a project where NuGet actions are being executed. -- [`IVsPackageRestorer`](#ivspackagerestorer-interface): Methods to restore packages installed in a project. -- [`IVsPackageSourceProvider`](#ivspackagesourceprovider-interface): Methods to retrieve a list of NuGet package sources. -- [`IVsPackageUninstaller`](#ivspackageuninstaller-interface): Methods to uninstall NuGet packages from projects. -- [`IVsTemplateWizard`](#ivstemplatewizard-interface): Designed for project/item templates to include pre-installed packages; this interface is *not* meant to be invoked from code and has no public methods. +## Package Versions -## Using NuGet services +NuGet's product follows Visual Studio's version, but is 11.0 versions behind. For example, NuGet 6.0 corresponds to Visual Studio 2022 17.0, NuGet 5.11 corresponds to Visual Studio 2019 16.11, and so on. -1. Install the [`NuGet.VisualStudio`](https://www.nuget.org/packages/NuGet.VisualStudio) package into your project, which contains the `NuGet.VisualStudio.dll` assembly. +Starting from Visual Studio 17.1, NuGet's Visual Studio extensibility API packages match the version of Visual Studio that the APIs are targeting. For example, NuGet.VisualStudio and NuGet.VisualStudio.Contracts package version 17.1.0 should be used when your extension targets Visual Studio 17.1 and higher. In Visual Studio 17.0 and earlier, NuGet's package versions are the same as NuGet's product version. For example, if your extension targets Visual Studio 2022 version 17.0, you should use version 6.0 of NuGet's Visual Studio extensibility packages. + +## NuGet Client SDK in Visual Studio Extensions + +Only the APIs in `NuGet.VisualStudio` and `NuGet.VisualStudio.Contracts` are supported in Visual Studio extensions. +NuGet provides binding redirects for these assemblies, so these assemblies do not need to be included in your extension. + +Using NuGet Client SDK packages, for example `NuGet.Protocol`, is not supported in Visual Studio extensions. +NuGet does not provide binding redirects for these assemblies. +See [the NuGet Client SDK support policy](../reference/NuGet-Client-SDK.md#support-policy) for more information. + +## Services List + +### Brokered Services + +These services are available in the package [NuGet.VisualStudio.Contracts](https://nuget.org/packages/NuGet.VisualStudio.Contracts/). + +- [`INuGetProjectService`](#inugetprojectservice-interface): Methods to interact with a project. (5.7+) + +### MEF Services + +From NuGet 6.0, all of these APIs are available in the package [NuGet.VisualStudio](https://www.nuget.org/packages/NuGet.VisualStudio/). In NuGet 5.11 and earlier, the APIs in the namespace `NuGet.VisualStudio` are available in the package [NuGet.VisualStudio](https://www.nuget.org/packages/NuGet.VisualStudio/), and APIs in the namespace `NuGet.SolutionRestoreManager` are available in the package [NuGet.SolutionRestoreManager.Interop](https://www.nuget.org/packages/NuGet.SolutionRestoreManager.Interop/). + +#### NuGet.VisualStudio - When installed, the package automatically sets the **Embed Interop Types** property of the assembly reference to **True**. This makes your code resilient against version changes when users update to newer versions of NuGet. +- [`IRegistryKey`](#iregistrykey-interface): Method to retrieve a value from a registry subkey. (3.3+) +- [`IVsCredentialProvider`](#ivscredentialprovider-interface) Contains methods to get credentials for NuGet operations. (4.0+) +- [`IVsFrameworkCompatibility`](#ivsframeworkcompatibility-interface) Contains methods to discover frameworks and compatibility between frameworks. (4.0+) +- [`IVsFrameworkCompatibility2`](#ivsframeworkcompatibility2-interface) Contains methods to discover frameworks and compatibility between frameworks. (4.0+) +- [`IVsFrameworkCompatibility3`](#ivsframeworkcompatibility3-interface) Contains methods to discover frameworks and compatibility between frameworks. (5.8+) +- [`IVsFrameworkParser`](#ivsframeworkparser-interface) An interface for dealing with the conversion between strings and [FrameworkName](/dotnet/api/system.runtime.versioning.frameworkname) (4.0+) +- [`IVsFrameworkParser2`](#ivsframeworkparser2-interface) An interface to parse .NET Framework strings. See [NuGet-IVsFrameworkParser](https://aka.ms/NuGet-IVsFrameworkParser). (5.8+) +- [`IVsPackageInstaller`](#ivspackageinstaller-interface): Methods to install NuGet packages into projects. (3.3+) +- [`IVsPackageInstaller2](#ivspackageinstaller2-interface) Contains method to install latest version of a single package into a project within the current solution. +- [`IVsPackageInstallerEvents`](#ivspackageinstallerevents-interface): Events for package install/uninstall. (3.3+) +- [`IVsPackageInstallerProjectEvents`](#ivspackageinstallerprojectevents-interface): Batch events for package install/uninstall. (3.3+) +- [`IVsPackageInstallerServices`](#ivspackageinstallerservices-interface): Methods to retrieve installed packages in the current solution and to check whether a given package is installed in a project. (3.3+) +- [`IVsPackageRestorer`](#ivspackagerestorer-interface): Methods to restore packages installed in a project. (3.3+) +- [`IVsPackageSourceProvider`](#ivspackagesourceprovider-interface): Methods to retrieve a list of NuGet package sources. (3.3+) +- [`IVsPackageUninstaller`](#ivspackageuninstaller-interface): Methods to uninstall NuGet packages from projects. (3.3+) +- [`IVsPathContext`](#ivspathcontext-interface) NuGet path information specific to the current context (e.g. project context). (4.0+) +- [`IVsPathContext2`](#ivspathcontext2-interface) NuGet path information specific to the current context (e.g. project context). (5.0+) +- [`IVsPathContextProvider`](#ivspathcontextprovider-interface) A factory to initialize [IVsPathContext](#ivspathcontext-interface) instances. (4.0+) +- [`IVsPathContextProvider2`](#ivspathcontextprovider2-interface) A factory to initialize [IVsPathContext2](#ivspathcontext2-interface) instances. (5.0+) +- [`IVsProjectJsonToPackageReferenceMigrator`](#ivsprojectjsontopackagereferencemigrator-interface) Contains methods to migrate a project.json based legacy project to PackageReference based project. (4.3+) +- [`IVsSemanticVersionComparer`](#ivssemanticversioncomparer-interface) An interface for comparing two opaque version strings by treating them as NuGet semantic (4.0+) +- [`IVsNuGetProjectUpdateEvents`](#ivsnugetprojectupdateevents-interface) (6.2+) + +#### NuGet.SolutionRestoreManager + +These interfaces are designed for project systems to interact with NuGet, allowing the project system to notify NuGet of changes to `PackageReference`s, and orchestrate batch updates. Visual Studio extensions that are not project systems probably will not benefit from these APIs. + +- [`IVsSolutionRestoreService`](#ivssolutionrestoreservice-interface) (4.0+) +- [`IVsSolutionRestoreService2`](#ivssolutionrestoreservice2-interface) (4.3+) +- [`IVsSolutionRestoreService3`](#ivssolutionrestoreservice3-interface) (5.1+) +- [`IVsSolutionRestoreService4`](#ivssolutionrestoreservice4-interface) (6.0+) +- [`IVsSolutionRestoreService5`](#ivssolutionrestoreservice5-interface) (6.11+) +- [`IVsSolutionRestoreStatusProvider`](#ivssolutionrestorestatusprovider-interface) (6.0+) + +## Using NuGet Services > [!Warning] -> Do not use any other types besides the public interfaces in your code, and do not reference any other NuGet assemblies, including `NuGet.Core.dll`. +> Do not use any other types besides the public interfaces in your code, and do not reference any other NuGet assemblies, such as `NuGet.Protocol.dll`, `NuGet.Frameworks.dll`, and so on. + +In order to maximize the backwards compatibility promises we make, but also providing ourselves the flexibility to implement new features, performance improvements, and bug fixes in Visual Studio, we do not support the NuGet Client SDK being used in Visual Studio, and we do not provide binding redirects in `devenv.exe.config` to assemblies other than our VS extensibility contracts. + +If you would like a new NuGet related API in Visual Studio, please search [NuGet's Home repo](https://github.com/NuGet/Home/) and upvote any existing issues if you find a similar one. If you can't find an existing feature request to upvote, please create one. + +### Brokered Services + +1. Install the [`NuGet.VisualStudio.Contracts`](https://www.nuget.org/packages/NuGet.VisualStudio.Contracts/) package into your project, as well as [`Microsoft.VisualStudio.SDK`](https://www.nuget.org/packages/Microsoft.VisualStudio.SDK). + +1. Use the `IAsyncServiceProvider` to get Visual Studio's service broker, and use that to get NuGet's service. Note that [`AsyncPackage` extends `IVsAsyncServiceProvider2`](/dotnet/api/microsoft.visualstudio.shell.asyncpackage), so your class that implements `AsyncPackage` can be used as the `IAsyncServiceProvider`. Also see the docs on [`IBrokeredServiceContainer`](/dotnet/api/microsoft.visualstudio.shell.servicebroker.ibrokeredservicecontainer) and [`IServiceBroker`](/dotnet/api/microsoft.servicehub.framework.iservicebroker) + + ```cs + // Your AsyncPackage implements IAsyncServiceProvider + IAsyncServiceProvider asyncServiceProvider = this; + var brokeredServiceContainer = await asyncServiceProvider.GetServiceAsync(); + var serviceBroker = brokeredServiceContainer.GetFullAccessServiceBroker(); + var nugetProjectService = await serviceBroker.GetProxyAsync(NuGetServices.NuGetProjectServiceV1); + ``` -1. To use a service, import it through the [MEF Import attribute](/dotnet/framework/mef/index#imports-and-exports-with-attributes), or through the [IComponentModel service](/dotnet/api/microsoft.visualstudio.componentmodelhost.icomponentmodel?redirectedfrom=MSDN&view=visualstudiosdk-2017). +1. When your code no longer needs NuGet's brokered service, dispose it. For example, if you only need NuGet's brokered service during a single method call, you can wrap it in a C#`using` statement: + + ```cs + InstalledPackagesResult installedPackagesResult; + using (nugetProjectService as IDisposable) + { + installedPackagesResult = await nugetProjectService.GetInstalledPackages(projectGuid, cancellationToken); + } + ``` + +### MEF Services + +1. Install the [`NuGet.VisualStudio`](https://www.nuget.org/packages/NuGet.VisualStudio) package into your project, which contains the `NuGet.VisualStudio.dll` assembly. + + In NuGet 5.11 and earlier, the package automatically sets the [**Embed Interop Types**](/dotnet/framework/interop/type-equivalence-and-embedded-interop-types) property of the assembly reference to **True**. [Visual Studio 2022 policy regarding embed interop types changed](/visualstudio/extensibility/migration/migrated-assemblies?view=vs-2022&preserve-view=true), so NuGet.VisualStudio package version 6.0.0 and above no longer use this. + +1. To use a service, import it through the [MEF Import attribute](/dotnet/framework/mef/index#imports-and-exports-with-attributes), or through the [IComponentModel service](/dotnet/api/microsoft.visualstudio.componentmodelhost.icomponentmodel). ```cs //Using the Import attribute @@ -54,6 +134,33 @@ As of NuGet 3.3+, NuGet exports the following services all of which reside in th For reference, the source code for NuGet.VisualStudio is contained within the [NuGet.Clients repository](https://github.com/NuGet/NuGet.Client/tree/dev/src/NuGet.Clients/NuGet.VisualStudio). +## Understanding the .NET project systems + +When SDK style projects were added for .NET Core 1.0, it was designed to be more asynchronous than previous Visual Studio project systems. This has an impact on how all other Visual Studio components interact with it directly, or though other components such as NuGet. This is most noticeable on solution load and project load, where projects are not fully available some time after Visual Studio's older synchronous API notifications have already fired. + +During solution load, NuGet ignores `IVsSolutionEvents.OnAfterProjectLoad`, in order to avoid delaying the synchronous part of solution load. NuGet will synchronize its internal data structures after the synchronous part of solution load has completed. This is also true for non-SDK style projects. + +Even after all `IVsSolutionEvents.OnAfterSolutionLoad` event handlers finish, this only signals the end of the synchronous part of solution load. The asynchronous part of solution load is still in progress. Therefore, if your extension calls NuGet APIs like `GetInstalledPackagesAsync` or `InstallPackage` soon after project or solution load, NuGet might throw an `InvalidOperationException` with message similar to "The operation failed as details for project {project name} could not be loaded.". + +When a solution contains at least one SDK style project, NuGet will automatically perform a restore after solution load, and you should not call any Nuget APIs until this is complete. You can use `IVsNuGetProjectUpdateEvents` to get a notification when the solution restore, or when specific project restores, complete. If a solution does not contain any SDK style projects, then restore will not be scheduled automatically, and may not happen until a build is scheduled. + +In order to determine whether a project uses NuGet's asynchronous flow (SDK style project), use [`PackageUtilities.IsCapabilityMatch`](/dotnet/api/microsoft.visualstudio.shell.packageutilities.iscapabilitymatch) with the expression `CPS + PackageReference`. + +## INuGetProjectService interface + +```cs + /// Service to interact with projects in a solution + /// This interface should not be implemented. New methods may be added over time. + public interface INuGetProjectService + { + /// Gets the list of packages installed in a project. + /// Project ID (GUID). + /// Cancellation token. + /// The list of packages in the project. + Task GetInstalledPackagesAsync(Guid projectId, CancellationToken cancellationToken); + } +``` + ## IRegistryKey interface ```cs @@ -85,462 +192,1172 @@ public interface IRegistryKey } ``` -## IVsPackageInstaller interface +## IVsCredentialProvider interface ```cs -public interface IVsPackageInstaller -{ - /// - /// Installs a single package from the specified package source. - /// - /// - /// The package source to install the package from. This value can be null - /// to indicate that the user's configured sources should be used. Otherwise, - /// this should be the source path as a string. If the user has credentials - /// configured for a source, this value must exactly match the configured source - /// value. - /// - /// The target project for package installation. - /// The package ID of the package to install. - /// - /// The version of the package to install. null can be provided to - /// install the latest version of the package. - /// - /// - /// A boolean indicating whether or not to ignore the package's dependencies - /// during installation. - /// - void InstallPackage(string source, Project project, string packageId, Version version, bool ignoreDependencies); - - /// - /// Installs a single package from the specified package source. - /// - /// - /// The package source to install the package from. This value can be null - /// to indicate that the user's configured sources should be used. Otherwise, - /// this should be the source path as a string. If the user has credentials - /// configured for a source, this value must exactly match the configured source - /// value. - /// - /// The target project for package installation. - /// The package ID of the package to install. - /// - /// The version of the package to install. null can be provided to - /// install the latest version of the package. - /// - /// - /// A boolean indicating whether or not to ignore the package's dependencies - /// during installation. - /// - void InstallPackage(string source, Project project, string packageId, string version, bool ignoreDependencies); - - /// - /// Installs a single package from the specified package source. - /// - /// The package repository to install the package from. - /// The target project for package installation. - /// The package id of the package to install. - /// - /// The version of the package to install. null can be provided to - /// install the latest version of the package. - /// - /// - /// A boolean indicating whether or not to ignore the package's dependencies - /// during installation. - /// - /// - /// A boolean indicating if assembly references from the package should be - /// skipped. - /// - void InstallPackage(IPackageRepository repository, Project project, string packageId, string version, bool ignoreDependencies, bool skipAssemblyReferences); - - /// - /// Installs one or more packages that exist on disk in a folder defined in the registry. - /// - /// - /// The registry key name (under NuGet's repository key) that defines the folder on disk - /// containing the packages. - /// - /// - /// A boolean indicating whether the folder contains packages that are - /// pre-unzipped. - /// - /// - /// A boolean indicating whether the assembly references from the packages - /// should be skipped. - /// - /// The target project for package installation. - /// - /// A dictionary of packages/versions to install where the key is the package id - /// and the value is the version. - /// - /// - /// If any version of the package is already installed, no action will be taken. - /// - /// Dependencies are always ignored. - /// - /// - void InstallPackagesFromRegistryRepository(string keyName, bool isPreUnzipped, bool skipAssemblyReferences, Project project, IDictionary packageVersions); - - /// - /// Installs one or more packages that exist on disk in a folder defined in the registry. - /// - /// - /// The registry key name (under NuGet's repository key) that defines the folder on disk - /// containing the packages. - /// - /// - /// A boolean indicating whether the folder contains packages that are - /// pre-unzipped. - /// - /// - /// A boolean indicating whether the assembly references from the packages - /// should be skipped. - /// - /// A boolean indicating whether the package's dependencies should be ignored - /// The target project for package installation. - /// - /// A dictionary of packages/versions to install where the key is the package id - /// and the value is the version. - /// - /// - /// If any version of the package is already installed, no action will be taken. - /// - void InstallPackagesFromRegistryRepository(string keyName, bool isPreUnzipped, bool skipAssemblyReferences, bool ignoreDependencies, Project project, IDictionary packageVersions); - - /// - /// Installs one or more packages that are embedded in a Visual Studio Extension Package. - /// - /// The Id of the Visual Studio Extension Package. - /// - /// A boolean indicating whether the folder contains packages that are - /// pre-unzipped. - /// - /// - /// A boolean indicating whether the assembly references from the packages - /// should be skipped. - /// - /// The target project for package installation - /// - /// A dictionary of packages/versions to install where the key is the package id - /// and the value is the version. - /// - /// - /// If any version of the package is already installed, no action will be taken. - /// - /// Dependencies are always ignored. - /// - /// - void InstallPackagesFromVSExtensionRepository(string extensionId, bool isPreUnzipped, bool skipAssemblyReferences, Project project, IDictionary packageVersions); - - /// - /// Installs one or more packages that are embedded in a Visual Studio Extension Package. - /// - /// The Id of the Visual Studio Extension Package. - /// - /// A boolean indicating whether the folder contains packages that are - /// pre-unzipped. - /// - /// - /// A boolean indicating whether the assembly references from the packages - /// should be skipped. - /// - /// A boolean indicating whether the package's dependencies should be ignored - /// The target project for package installation - /// - /// A dictionary of packages/versions to install where the key is the package id - /// and the value is the version. - /// - /// - /// If any version of the package is already installed, no action will be taken. - /// - void InstallPackagesFromVSExtensionRepository(string extensionId, bool isPreUnzipped, bool skipAssemblyReferences, bool ignoreDependencies, Project project, IDictionary packageVersions); -} + /// + /// Contains methods to get credentials for NuGet operations. + /// + public interface IVsCredentialProvider + { + /// + /// Get credentials for the supplied package source Uri. + /// + /// The NuGet package source Uri for which credentials are being requested. Implementors are + /// expected to first determine if this is a package source for which they can supply credentials. + /// If not, then Null should be returned. + /// Web proxy to use when comunicating on the network. Null if there is no proxy + /// authentication configured. + /// True if if this request is to get proxy authentication + /// credentials. If the implementation is not valid for acquiring proxy credentials, then + /// null should be returned. + /// True if credentials were previously acquired for this uri, but + /// the supplied credentials did not allow authorized access. + /// If true, then interactive prompts must not be allowed. + /// This cancellation token should be checked to determine if the + /// operation requesting credentials has been cancelled. + /// Credentials acquired by this provider for the given package source uri. + /// If the provider does not handle requests for the input parameter set, then null should be returned. + /// If the provider does handle the request, but cannot supply credentials, an exception should be thrown. + Task GetCredentialsAsync(Uri uri, + IWebProxy proxy, + bool isProxyRequest, + bool isRetry, + bool nonInteractive, + CancellationToken cancellationToken); + } ``` -## IVsPackageInstallerEvents interface +## IVsFrameworkCompatibility interface ```cs -public interface IVsPackageInstallerEvents -{ /// - /// Raised when a package is about to be installed into the current solution. + /// Contains methods to discover frameworks and compatibility between frameworks. /// - event VsPackageEventHandler PackageInstalling; + public interface IVsFrameworkCompatibility + { + /// + /// Gets all .NETStandard frameworks currently supported, in ascending order by version. + /// + /// This API is free-threaded. + IEnumerable GetNetStandardFrameworks(); + + /// + /// Gets frameworks that support packages of the provided .NETStandard version. + /// + /// + /// The result list is not exhaustive as it is meant to human-readable. For example, + /// equivalent frameworks are not returned. Additionally, a framework name with version X + /// in the result implies that framework names with versions greater than or equal to X + /// but having the same are also supported. + /// + /// This API is free-threaded. + /// + /// The .NETStandard version to get supporting frameworks for. + [Obsolete("This API does not support .NET 5 and higher target frameworks with platforms. Use IVsFrameworkCompatibility3 instead.")] + IEnumerable GetFrameworksSupportingNetStandard(FrameworkName frameworkName); + + /// + /// Selects the framework from that is nearest + /// to the , according to NuGet's framework + /// compatibility rules. null is returned of none of the frameworks + /// are compatible. + /// + /// This API is free-threaded. + /// The target framework. + /// The list of frameworks to choose from. + /// If any of the arguments are null. + /// The nearest framework. + [Obsolete("This API does not support .NET 5 and higher target frameworks with platforms. Use IVsFrameworkCompatibility3 instead.")] + FrameworkName GetNearest(FrameworkName targetFramework, IEnumerable frameworks); + } +``` - /// - /// Raised after a package has been installed into the current solution. - /// - event VsPackageEventHandler PackageInstalled; +## IVsFrameworkCompatibility2 interface +```cs /// - /// Raised when a package is about to be uninstalled from the current solution. + /// Contains methods to discover frameworks and compatibility between frameworks. /// - event VsPackageEventHandler PackageUninstalling; + [Obsolete("This API does not support .NET 5 and higher target frameworks with platforms. Use IVsFrameworkCompatibility3 instead.")] + public interface IVsFrameworkCompatibility2 : IVsFrameworkCompatibility + { + /// + /// Selects the framework from that is nearest + /// to the , according to NuGet's framework + /// compatibility rules. null is returned of none of the frameworks + /// are compatible. + /// + /// This API is free-threaded. + /// The target framework. + /// + /// Target frameworks to use if the provided is not compatible. + /// These fallback frameworks are attempted in sequence after . + /// + /// The list of frameworks to choose from. + /// If any of the arguments are null. + /// The nearest framework. + [Obsolete("This API does not support .NET 5 and higher target frameworks with platforms. Use IVsFrameworkCompatibility3 instead.")] + FrameworkName GetNearest( + FrameworkName targetFramework, + IEnumerable fallbackTargetFrameworks, + IEnumerable frameworks); + } +``` - /// - /// Raised after a package has been uninstalled from the current solution. - /// - event VsPackageEventHandler PackageUninstalled; +## IVsFrameworkCompatibility3 interface +```cs /// - /// Raised after a package has been installed into a project within the current solution. + /// Contains methods to discover frameworks and compatibility between frameworks. /// - event VsPackageEventHandler PackageReferenceAdded; + public interface IVsFrameworkCompatibility3 + { + /// + /// Selects the framework from that is nearest + /// to the , according to NuGet's framework + /// compatibility rules. null is returned of none of the frameworks + /// are compatible. + /// + /// The target framework. + /// The list of frameworks to choose from. + /// If any of the arguments are null. + /// If any of the frameworks cannot be parsed. + /// The nearest framework. + /// This API is free-threaded. + IVsNuGetFramework GetNearest(IVsNuGetFramework targetFramework, IEnumerable frameworks); + + /// + /// Selects the framework from that is nearest + /// to the , according to NuGet's framework + /// compatibility rules. null is returned of none of the frameworks + /// are compatible. + /// + /// The target framework. + /// + /// Target frameworks to use if the provided is not compatible. + /// These fallback frameworks are attempted in sequence after . + /// + /// The list of frameworks to choose from. + /// If any of the arguments are null. + /// If any of the frameworkscannot be parsed. + /// The nearest framework. + /// This API is free-threaded. + IVsNuGetFramework GetNearest( + IVsNuGetFramework targetFramework, + IEnumerable fallbackTargetFrameworks, + IEnumerable frameworks); + } +``` + +## IVsFrameworkParser interface +```cs /// - /// Raised after a package has been uninstalled from a project within the current solution. + /// An interface for dealing with the conversion between strings and + /// instances. /// - event VsPackageEventHandler PackageReferenceRemoved; -} + [Obsolete("This API does not support .NET 5 and higher target frameworks with platforms. Use IVsFrameworkParser2 instead.")] + public interface IVsFrameworkParser + { + /// + /// Parses a short framework name (e.g. "net45") or a full framework name + /// (e.g. ".NETFramework,Version=v4.5") into a + /// instance. + /// + /// This API is free-threaded. + /// The framework string. + /// If the provided string is null. + /// If the provided string cannot be parsed. + /// The parsed framework. + [Obsolete("This API does not support .NET 5 and higher target frameworks with platforms. Use IVsFrameworkParser2 instead.")] + FrameworkName ParseFrameworkName(string shortOrFullName); + + /// + /// Gets the shortened version of the framework name from a + /// instance. + /// + /// + /// For example, ".NETFramework,Version=v4.5" is converted to "net45". This is the value + /// used inside of .nupkg folder structures as well as in project.json files. + /// This API is free-threaded. + /// + /// The framework name. + /// If the input is null. + /// + /// If the provided framework name cannot be converted to a short name. + /// + /// The short framework name. + [Obsolete("This API does not support .NET 5 and higher target frameworks with platforms. Use IVsFrameworkParser2 instead.")] + string GetShortFrameworkName(FrameworkName frameworkName); + } ``` -## IVsPackageInstallerProjectEvents interface +## IVsFrameworkParser2 interface ```cs -public interface IVsPackageInstallerProjectEvents -{ - /// - /// Raised before any IVsPackageInstallerEvents events are raised for a project. - /// - event VsPackageProjectEventHandler BatchStart; + /// An interface to parse .NET Framework strings. See http://aka.ms/NuGet-IVsFrameworkParser. + public interface IVsFrameworkParser2 + { + /// + /// Parses a short framework name (e.g. "net45") or a full Target Framework Moniker + /// (e.g. ".NETFramework,Version=v4.5") into a + /// instance. + /// + /// The framework string + /// The resulting . If the method returns false, this return NuGet's "Unsupported" framework details. + /// A boolean to specify whether the input could be parsed into a valid object. + /// This API is not needed to get framework information about loaded projects, and should not be used to parse the project's TargetFramework property. See http://aka.ms/NuGet-IVsFrameworkParser.
    + /// This API is free-threaded.     + bool TryParse(string input, out IVsNuGetFramework nuGetFramework); + } +``` + +## IVsPackageInstaller interface +```cs /// - /// Raised after all IVsPackageInstallerEvents events are raised for a project. + /// Contains methods to install packages into a project within the current solution. /// - event VsPackageProjectEventHandler BatchEnd; -} + [ComImport] + [Guid("4F3B122B-A53B-432C-8D85-0FAFB8BE4FF4")] + public interface IVsPackageInstaller + { + /// + /// Installs a single package from the specified package source. + /// + /// Can be called from a background thread, if the UI thread is not blocked waiting for this to finish. + /// See https://github.com/nuget/home/issues/11476 + /// + /// The package source to install the package from. This value can be null + /// to indicate that the user's configured sources should be used. Otherwise, + /// this should be the source path as a string. If the user has credentials + /// configured for a source, this value must exactly match the configured source + /// value. + /// + /// The target project for package installation. + /// The package ID of the package to install. + /// + /// The version of the package to install. null can be provided to + /// install the latest version of the package. + /// + /// + /// A boolean indicating whether or not to ignore the package's dependencies + /// during installation. + /// + [Obsolete("System.Version does not support SemVer pre-release versions. Use the overload with string version instead.")] + void InstallPackage(string source, Project project, string packageId, Version version, bool ignoreDependencies); + + /// + /// Installs a single package from the specified package source. + /// + /// Can be called from a background thread, if the UI thread is not blocked waiting for this to finish. + /// See https://github.com/nuget/home/issues/11476 + /// + /// The package source to install the package from. This value can be null + /// to indicate that the user's configured sources should be used. Otherwise, + /// this should be the source path as a string. If the user has credentials + /// configured for a source, this value must exactly match the configured source + /// value. + /// + /// The target project for package installation. + /// The package ID of the package to install. + /// + /// The version of the package to install. null can be provided to + /// install the latest version of the package. + /// + /// + /// A boolean indicating whether or not to ignore the package's dependencies + /// during installation. + /// + void InstallPackage(string source, Project project, string packageId, string version, bool ignoreDependencies); + + /// + /// Installs a single package from the specified package source. + /// + /// The package repository to install the package from. + /// The target project for package installation. + /// The package id of the package to install. + /// + /// The version of the package to install. null can be provided to + /// install the latest version of the package. + /// + /// + /// A boolean indicating whether or not to ignore the package's dependencies + /// during installation. + /// + /// + /// A boolean indicating if assembly references from the package should be + /// skipped. + /// + [Obsolete] + void InstallPackage(IPackageRepository repository, Project project, string packageId, string version, bool ignoreDependencies, bool skipAssemblyReferences); + + /// + /// Installs one or more packages that exist on disk in a folder defined in the registry. + /// + /// + /// The registry key name (under NuGet's repository key) that defines the folder on disk + /// containing the packages. + /// + /// + /// A boolean indicating whether the folder contains packages that are + /// pre-unzipped. + /// + /// + /// A boolean indicating whether the assembly references from the packages + /// should be skipped. + /// + /// The target project for package installation. + /// + /// A dictionary of packages/versions to install where the key is the package id + /// and the value is the version. + /// + /// + /// If any version of the package is already installed, no action will be taken. + /// + /// Dependencies are always ignored. + /// + /// Can be called from a background thread, if the UI thread is not blocked waiting for this to finish. + /// See https://github.com/nuget/home/issues/11476 + /// + void InstallPackagesFromRegistryRepository(string keyName, bool isPreUnzipped, bool skipAssemblyReferences, Project project, IDictionary packageVersions); + + /// + /// Installs one or more packages that exist on disk in a folder defined in the registry. + /// + /// + /// The registry key name (under NuGet's repository key) that defines the folder on disk + /// containing the packages. + /// + /// + /// A boolean indicating whether the folder contains packages that are + /// pre-unzipped. + /// + /// + /// A boolean indicating whether the assembly references from the packages + /// should be skipped. + /// + /// A boolean indicating whether the package's dependencies should be ignored + /// The target project for package installation. + /// + /// A dictionary of packages/versions to install where the key is the package id + /// and the value is the version. + /// + /// + /// If any version of the package is already installed, no action will be taken. + /// Can be called from a background thread, if the UI thread is not blocked waiting for this to finish. + /// See https://github.com/nuget/home/issues/11476 + /// + void InstallPackagesFromRegistryRepository(string keyName, bool isPreUnzipped, bool skipAssemblyReferences, bool ignoreDependencies, Project project, IDictionary packageVersions); + + /// + /// Installs one or more packages that are embedded in a Visual Studio Extension Package. + /// + /// The Id of the Visual Studio Extension Package. + /// + /// A boolean indicating whether the folder contains packages that are + /// pre-unzipped. + /// + /// + /// A boolean indicating whether the assembly references from the packages + /// should be skipped. + /// + /// The target project for package installation + /// + /// A dictionary of packages/versions to install where the key is the package id + /// and the value is the version. + /// + /// + /// If any version of the package is already installed, no action will be taken. + /// + /// Dependencies are always ignored. + /// + /// Can be called from a background thread, if the UI thread is not blocked waiting for this to finish. + /// See https://github.com/nuget/home/issues/11476 + /// + void InstallPackagesFromVSExtensionRepository(string extensionId, bool isPreUnzipped, bool skipAssemblyReferences, Project project, IDictionary packageVersions); + + /// + /// Installs one or more packages that are embedded in a Visual Studio Extension Package. + /// + /// The Id of the Visual Studio Extension Package. + /// + /// A boolean indicating whether the folder contains packages that are + /// pre-unzipped. + /// + /// + /// A boolean indicating whether the assembly references from the packages + /// should be skipped. + /// + /// A boolean indicating whether the package's dependencies should be ignored + /// The target project for package installation + /// + /// A dictionary of packages/versions to install where the key is the package id + /// and the value is the version. + /// + /// + /// If any version of the package is already installed, no action will be taken. + /// Can be called from a background thread, if the UI thread is not blocked waiting for this to finish. + /// See https://github.com/nuget/home/issues/11476 + /// + void InstallPackagesFromVSExtensionRepository(string extensionId, bool isPreUnzipped, bool skipAssemblyReferences, bool ignoreDependencies, Project project, IDictionary packageVersions); + } ``` -## IVsPackageInstallerServices interface +## IVsPackageinstaller2 interface ```cs -public interface IVsPackageInstallerServices -{ - // IMPORTANT: do NOT rearrange the methods here. The order is important to maintain - // backwards compatibility with clients that were compiled against old versions of NuGet. /// - /// Get the list of NuGet packages installed in the current solution. + /// Contains method to install latest version of a single package into a project within the current solution. /// - IEnumerable GetInstalledPackages(); + public interface IVsPackageInstaller2 : IVsPackageInstaller + { + /// + /// Installs the latest version of a single package from the specified package source. + /// + /// Can be called from a background thread, if the UI thread is not blocked waiting for this to finish. + /// See https://github.com/nuget/home/issues/11476 + /// + /// The package source to install the package from. This value can be null + /// to indicate that the user's configured sources should be used. Otherwise, + /// this should be the source path as a string. If the user has credentials + /// configured for a source, this value must exactly match the configured source + /// value. + /// + /// The target project for package installation. + /// The package ID of the package to install. + /// + /// Whether or not to consider prerelease versions when finding the latest version + /// to install. + /// + /// + /// A boolean indicating whether or not to ignore the package's dependencies + /// during installation. + /// + /// + /// Thrown when is false and no stable version + /// of the package exists. + /// + void InstallLatestPackage( + string source, + Project project, + string packageId, + bool includePrerelease, + bool ignoreDependencies); + } +``` - /// - /// Checks if a NuGet package with the specified Id is installed in the specified project. - /// - /// The project to check for NuGet package. - /// The id of the package to check. - /// true if the package is install. false otherwise. - bool IsPackageInstalled(Project project, string id); +## IVsPackageInstallerEvents interface + +> [!Note] +> These events are only raised for packages.config projects. To get updates for both packages.config and PackageReference use [`IVsNuGetProjectUpdateEvents`](#ivsnugetprojectupdateevents-interface) instead. +```cs /// - /// Checks if a NuGet package with the specified Id and version is installed in the specified project. + /// Contains events which are raised when packages are installed or uninstalled from projects and the current + /// solution. /// - /// The project to check for NuGet package. - /// The id of the package to check. - /// The version of the package to check. - /// true if the package is install. false otherwise. - bool IsPackageInstalled(Project project, string id, SemanticVersion version); + public interface IVsPackageInstallerEvents + { + /// + /// Raised when a package is about to be installed into the current solution. + /// + event VsPackageEventHandler PackageInstalling; + + /// + /// Raised after a package has been installed into the current solution. + /// + event VsPackageEventHandler PackageInstalled; + + /// + /// Raised when a package is about to be uninstalled from the current solution. + /// + event VsPackageEventHandler PackageUninstalling; + + /// + /// Raised after a package has been uninstalled from the current solution. + /// + event VsPackageEventHandler PackageUninstalled; + + /// + /// Raised after a package has been installed into a project within the current solution. + /// + event VsPackageEventHandler PackageReferenceAdded; + + /// + /// Raised after a package has been uninstalled from a project within the current solution. + /// + event VsPackageEventHandler PackageReferenceRemoved; + } +``` + +## IVsPackageInstallerProjectEvents interface +> [!Note] +> These events are only raised for packages.config projects. To get updates for both packages.config and PackageReference use [`IVsNuGetProjectUpdateEvents`](#ivsnugetprojectupdateevents-interface) instead. + +```cs /// - /// Checks if a NuGet package with the specified Id and version is installed in the specified project. + /// Contains batch events which are raised when packages are installed or uninstalled from projects with packages.config + /// and the current solution. /// - /// The project to check for NuGet package. - /// The id of the package to check. - /// The version of the package to check. - /// true if the package is install. false otherwise. - /// - /// The reason this method is named IsPackageInstalledEx, instead of IsPackageInstalled, is that - /// when client project compiles against this assembly, the compiler would attempt to bind against - /// the other overload which accepts SemanticVersion and would require client project to reference NuGet.Core. - /// - bool IsPackageInstalledEx(Project project, string id, string versionString); + public interface IVsPackageInstallerProjectEvents + { + /// + /// Raised before any IVsPackageInstallerEvents events are raised for a project. + /// + event VsPackageProjectEventHandler BatchStart; + + /// + /// Raised after all IVsPackageInstallerEvents events are raised for a project. + /// + event VsPackageProjectEventHandler BatchEnd; + + } +``` +## IVsPackageInstallerServices interface + +```cs /// - /// Get the list of NuGet packages installed in the specified project. + /// Contains methods to query for installed packages within the current solution. /// - /// The project to get NuGet packages from. - IEnumerable GetInstalledPackages(Project project); -} + [Obsolete("Use INuGetProjectService in the NuGet.VisualStudio.Contracts package instead.")] + public interface IVsPackageInstallerServices + { + /// + /// Get the list of NuGet packages installed in the current solution. + /// + [Obsolete("This method can cause UI delays if called on the UI thread. Use INuGetProjectService.GetInstalledPackagesAsync in the NuGet.VisualStudio.Contracts package instead, and iterate all projects in the solution")] + IEnumerable GetInstalledPackages(); + + /// + /// Checks if a NuGet package with the specified Id is installed in the specified project. + /// + /// The project to check for NuGet package. + /// The id of the package to check. + /// true if the package is install. false otherwise. + /// A "project not nominated" exception will be thrown if the project system has not yet told NuGet about the project. + /// You can use or Microsoft.VisualStudio.OperationProgress to be notified when the project is ready. + [Obsolete("This method can cause UI delays if called on the UI thread. Use INuGetProjectService.GetInstalledPackagesAsync in the NuGet.VisualStudio.Contracts package instead, and check the specific package you're interested in")] + bool IsPackageInstalled(Project project, string id); + + /// + /// Checks if a NuGet package with the specified Id and version is installed in the specified project. + /// + /// The project to check for NuGet package. + /// The id of the package to check. + /// The version of the package to check. + /// true if the package is install. false otherwise. + /// A "project not nominated" exception will be thrown if the project system has not yet told NuGet about the project. + /// You can use or Microsoft.VisualStudio.OperationProgress to be notified when the project is ready. + [Obsolete("This method can cause UI delays if called on the UI thread. Use INuGetProjectService.GetInstalledPackagesAsync in the NuGet.VisualStudio.Contracts package instead, and check the specific package you're interested in")] + bool IsPackageInstalled(Project project, string id, SemanticVersion version); + + /// + /// Checks if a NuGet package with the specified Id and version is installed in the specified project. + /// + /// The project to check for NuGet package. + /// The id of the package to check. + /// The version of the package to check. + /// true if the package is install. false otherwise. + /// + /// The reason this method is named IsPackageInstalledEx, instead of IsPackageInstalled, is that + /// when client project compiles against this assembly, the compiler would attempt to bind against + /// the other overload which accepts SemanticVersion and would require client project to reference NuGet.Core. + /// + /// A "project not nominated" exception will be thrown if the project system has not yet told NuGet about the project. + /// You can use or Microsoft.VisualStudio.OperationProgress to be notified when the project is ready. + [Obsolete("This method can cause UI delays if called on the UI thread. Use INuGetProjectService.GetInstalledPackagesAsync in the NuGet.VisualStudio.Contracts package instead, and check the specific package you're interested in")] + bool IsPackageInstalledEx(Project project, string id, string versionString); + + /// + /// Get the list of NuGet packages installed in the specified project. + /// + /// The project to get NuGet packages from. + /// A "project not nominated" exception will be thrown if the project system has not yet told NuGet about the project. + /// You can use or Microsoft.VisualStudio.OperationProgress to be notified when the project is ready. + [Obsolete("This method can cause UI delays if called on the UI thread. Use INuGetProjectService.GetInstalledPackagesAsync in the NuGet.VisualStudio.Contracts package instead")] + IEnumerable GetInstalledPackages(Project project); + } ``` -## IVsPackageManagerProvider interface +## IVsPackageRestorer interface ```cs -public interface IVsPackageManagerProvider -{ + /// - /// Localized display package manager name. + /// Contains methods to restore packages installed in a project within the current solution. /// - string PackageManagerName { get; } + public interface IVsPackageRestorer + { + /// + /// Returns a value indicating whether the user consent to download NuGet packages + /// has been granted. + /// + /// Can be called from a background thread. + /// true if the user consent has been granted; otherwise, false. + bool IsUserConsentGranted(); + + /// + /// Restores NuGet packages installed in the given project within the current solution. + /// + /// Can be called from a background thread. + /// The project whose NuGet packages to restore. + void RestorePackages(Project project); + } +``` + +## IVsPackageSourceProvider interface +```cs /// - /// Package manager unique id. + /// A public API for retrieving the list of NuGet package sources. /// - string PackageManagerId { get; } + public interface IVsPackageSourceProvider + { + /// + /// Provides the list of package sources. + /// + /// Can be called from a background thread. + /// Unofficial sources will be included in the results + /// Disabled sources will be included in the results + /// Does not require the UI thread. + /// Thrown if a NuGet configuration file is invalid. + /// Thrown if a NuGet configuration file is invalid. + /// Thrown if a NuGet configuration file is invalid. + /// Thrown if a NuGet configuration file is invalid. + /// Key: source name Value: source URI + IEnumerable> GetSources(bool includeUnOfficial, bool includeDisabled); + + /// + /// Raised when sources are added, removed, disabled, or modified. + /// + event EventHandler SourcesChanged; + } +``` +## IVsPackageUninstaller interface + +```cs /// - /// The tool tip description for the package + /// Contains methods to uninstall packages from a project within the current solution. /// - string Description { get; } + public interface IVsPackageUninstaller + { + /// + /// Uninstall the specified package from a project and specify whether to uninstall its dependency packages + /// too. + /// + /// Can be called from a background thread, if the UI thread is not blocked waiting for this to finish. + /// See https://github.com/nuget/home/issues/11476 + /// The project from which the package is uninstalled. + /// The package to be uninstalled + /// + /// A boolean to indicate whether the dependency packages should be + /// uninstalled too. + /// + void UninstallPackage(Project project, string packageId, bool removeDependencies); + } +``` + +## IVsPathContext interface +```cs /// - /// Check if a recommendation should be surfaced for an alternate package manager. - /// This code should not rely on slow network calls, and should return rapidly. + /// NuGet path information specific to the current context (e.g. project context). + /// Represents captured snapshot associated with current project/solution settings. + /// Should be discarded immediately after all queries are done. /// - /// Current package id - /// Unique project name for finding the project through VS dte - /// Cancellation Token - /// return true if need to direct to integrated package manager for this package - Task CheckForPackageAsync(string packageId, string projectName, CancellationToken token); + public interface IVsPathContext + { + /// + /// User package folder directory. The path returned is an absolute path. + /// + string UserPackageFolder { get; } + + /// + /// Fallback package folder locations. The paths (if any) in the returned list are absolute paths. If no + /// fallback package folders are configured, an empty list is returned. The item type of this sequence is + /// . + /// + /// Can be called from a background thread. + IEnumerable FallbackPackageFolders { get; } + + /// + /// Fetch a package directory containing the provided asset path. + /// + /// Absolute path to package asset file. + /// Full path to a package directory. + /// null if returned falue is false. + /// + /// true when a package containing the given file was found, false - otherwise. + /// + /// + /// Suppose the project is a packages.config project and the following asset paths are provided: + /// + /// - C:\src\MyProject\packages\NuGet.Versioning.3.5.0-rc1-final\lib\net45\NuGet.Versioning.dll + /// - C:\path\to\non\package\assembly\Newtonsoft.Json.dll + /// - C:\src\MyOtherProject\packages\NuGet.Core.2.12.0\lib\net40\NuGet.Core.dll + /// - C:\src\MyProject\packages\Autofac.3.5.2\lib\net40\Autofac.dll + /// - C:\src\MyProject\packages\Autofac.3.5.2\lib\net40\Autofac.Fake.dll + /// + /// The result will be: + /// + /// - C:\src\MyProject\packages\NuGet.Versioning.3.5.0-rc1-final + /// - null + /// - null + /// - C:\src\MyProject\packages\Autofac.3.5.2 + /// - C:\src\MyProject\packages\Autofac.3.5.2 + /// + bool TryResolvePackageAsset(string packageAssetPath, out string packageDirectoryPath); + } +``` +## IVsPathContext2 interface + +```cs /// - /// This Action should take the user to the other package manager. + /// NuGet path information specific to the current context (e.g. project context) or solution context + /// Represents captured snapshot associated with current project/solution settings. + /// Should be discarded immediately after all queries are done. /// - /// Current package id - /// Unique project name for finding the project through VS dte - void GoToPackage(string packageId, string projectName); -} + public interface IVsPathContext2 : IVsPathContext + { + /// + /// Solution packages folder directory. This will always be set irrespective if folder actually exists or not. + /// The path returned is an absolute path. + /// + string SolutionPackageFolder { get; } + } ``` -## IVsPackageMetadata interface +## IVsPathContextProvider interface ```cs -public interface IVsPackageMetadata -{ /// - /// Id of the package. + /// A factory to initialize instances. /// - string Id { get; } + public interface IVsPathContextProvider + { + /// + /// Attempts to create an instance of . + /// + /// Can be called from a background thread. + /// + /// Unique identificator of the project. Should be a full path to project file. + /// + /// The path context associated with given project. + /// + /// True if operation has succeeded and context was created. + /// False, otherwise, e.g. when provided project is not managed by NuGet. + /// + /// + /// ArgumentNullException if projectUniqueName is passed as null. + /// InvalidOperationException when it fails to create a context and return appropriate error message. + /// + bool TryCreateContext(string projectUniqueName, out IVsPathContext context); + } +``` + +## IVsPathContextProvider2 interface +```cs /// - /// Version of the package. + /// A factory to initialize instances. /// - /// - /// Do not use this property because it will require referencing NuGet.Core.dll assembly. Use the VersionString - /// property instead. - /// - [Obsolete("Do not use this property because it will require referencing NuGet.Core.dll assembly. Use the VersionString property instead.")] - NuGet.SemanticVersion Version { get; } + public interface IVsPathContextProvider2 : IVsPathContextProvider + { + /// + /// Attempts to create an instance of for the solution. + /// + /// This API is free-threaded, but APIs on the returned IVsPathContext2 may not be. + /// The path context associated with this solution. + /// + /// True if operation has succeeded and context was created. + /// False otherwise. + /// + /// + /// InvalidOperationException when it fails to create a context and return appropriate error message. + /// + bool TryCreateSolutionContext(out IVsPathContext2 context); + + /// + /// Attempts to create an instance of for the solution. + /// + /// This API is free-threaded, but APIs on the returned IVsPathContext2 may not be. + /// + /// path to the solution directory. Must be an absolute path. + /// It will be performant to pass the solution directory if it's available. + /// + /// The path context associated with this solution. + /// + /// True if operation has succeeded and context was created. + /// False otherwise. + /// + /// + /// ArgumentNullException if solutionDirectory is passed as null. + /// InvalidOperationException when it fails to create a context and return appropriate error message. + /// + bool TryCreateSolutionContext(string solutionDirectory, out IVsPathContext2 context); + + /// + /// Attempts to create an instance of containing only the user wide and machine wide configurations. + /// If a solution is loaded, note that the values in the path context might not be the actual effective values for the solution. + /// If a customer has overriden the `globalPackagesFolder` key or cleared the `fallbackPackageFolders`, these values will be incorrect. + /// It is important to keep this scenario in mind when working with this path. To predict differences you can call this in combination with . + /// + /// + /// True if operation has succeeded and context was created. + /// False otherwise. + /// + /// + /// This method can be safely invoked from a background thread. Do note that this method might switch to the UI thread internally, so be mindful of blocking the UI thread on this. + /// + bool TryCreateNoSolutionContext(out IVsPathContext vsPathContext); + } +``` +## IVsProjectJsonToPackageReferenceMigrator interface + +```cs /// - /// Title of the package. + /// Contains methods to migrate a project.json based legacy project to PackageReference based project. /// - string Title { get; } + public interface IVsProjectJsonToPackageReferenceMigrator + { + /// + /// Migrates a legacy Project.json based project to Package Reference based project. The result + /// should be casted to type + /// The backup of the original project file and project.json file is created in the Backup folder + /// in the root of the project directory. + /// + /// The full path to the project that needs to be migrated + Task MigrateProjectJsonToPackageReferenceAsync(string projectUniqueName); + + } +``` + +## IVsSemanticVersionComparer interface +```cs /// - /// Description of the package. + /// An interface for comparing two opaque version strings by treating them as NuGet semantic + /// versions. /// - string Description { get; } + public interface IVsSemanticVersionComparer + { + /// + /// Compares two version strings as if they were NuGet semantic version + /// strings. Returns a number less than zero if + /// is less than . Returns zero if the two versions + /// are equivalent. Returns a number greater than zero if + /// is greater than . + /// + /// This API is free-threaded. + /// The first version string. + /// The second version string. + /// If either version string is null. + /// If either string cannot be parsed. + /// + /// A standard comparison integer based on the relationship between the + /// two provided versions. + /// + int Compare(string versionA, string versionB); + } +``` + +## IVsNuGetProjectUpdateEvents interface +```cs /// - /// The authors of the package. + /// NuGet project update events. + /// This API provides means of tracking project updates by NuGet. + /// In particular, for PackageReference projects, updates to the assets file and nuget generated props/targets. + /// For packages.config projects, package installations will be tracked. + /// All events are fired from a threadpool thread. /// - IEnumerable Authors { get; } + public interface IVsNuGetProjectUpdateEvents + { + /// + /// Raised when solution restore starts with the list of projects that will be restored. + /// The list will not include all projects. Some projects may have been skipped in earlier up to date check, and other projects may no-op. + /// + /// + /// Just because a project is being restored that doesn't necessarily mean any actual updates will happen. + /// No heavy computation should happen in any of these methods as it'll block the NuGet progress. + /// + event SolutionRestoreEventHandler SolutionRestoreStarted; + + /// + /// Raised when solution restore finishes with the list of projects that were restored. + /// The list will not include all projects. Some projects may have been skipped in earlier up to date check, and other projects may no-op. + /// + /// + /// Just because a project is being restored that doesn't necessarily mean any actual updates will happen. + /// No heavy computation should happen in any of these methods as it'll block the NuGet progress. + /// + event SolutionRestoreEventHandler SolutionRestoreFinished; + + /// + /// Raised when particular project is about to be updated. + /// For PackageReference projects, this means an assets file or a nuget temp msbuild file write (nuget.g.props or nuget.g.targets). The list of updated files will include the aforementioned. + /// If a project was restored, but no file updates happen, this event will not be fired. + /// For packages.config projects, this means that the project file was changed. + /// + /// + /// No heavy computation should happen in any of these methods as it'll block the NuGet progress. + /// + event ProjectUpdateEventHandler ProjectUpdateStarted; + + /// + /// Raised when particular project update has been completed. + /// For PackageReference projects, this means an assets file or a nuget temp msbuild file write (nuget.g.props or nuget.g.targets). The list of updated files will include the aforementioned. + /// If a project was restored, but no file updates happen, this event will not be fired. + /// For packages.config projects, this means that the project file was changed. + /// + /// + /// No heavy computation should happen in any of these methods as it'll block the NuGet progress. + /// + event ProjectUpdateEventHandler ProjectUpdateFinished; + } /// - /// The location where the package is installed on disk. + /// Defines an event handler delegate for solution restore start and end. /// - string InstallPath { get; } + /// List of projects that will run restore. Never . + public delegate void SolutionRestoreEventHandler(IReadOnlyList projects); - // IMPORTANT: This property must come LAST, because it was added in 2.5. Having it declared - // LAST will avoid breaking components that compiled against earlier versions which doesn't - // have this property. /// - /// The version of the package. + /// Defines an event handler delegate for project updates. /// - /// - /// Use this property instead of the Version property becase with the type string, - /// it doesn't require referencing NuGet.Core.dll assembly. - /// - string VersionString { get; } + /// Project full path. Never . + /// NuGet output files that may be updated. Never . + public delegate void ProjectUpdateEventHandler(string projectUniqueName, IReadOnlyList updatedFiles); } ``` -## IVsPackageProjectMetadata interface +## IVsSolutionRestoreService interface ```cs -public interface IVsPackageProjectMetadata -{ - /// - /// Unique batch id for batch start/end events of the project. - /// - string BatchId { get; } - /// - /// Name of the project. + /// Represents a package restore service API for integration with a project system. /// - string ProjectName { get; } -} + public interface IVsSolutionRestoreService + { + /// + /// A task providing last/current restore operation status. + /// Could be null if restore has not started yet. + /// + /// + /// This task is a reflection of the current state of the current-restore-operation or + /// recently-completed-restore. The usage of this property will be to continue, + /// e.g. to build solution or something) on completion of this task. + /// Also, on completion, if the task returns false then it means the restore failed and + /// the build task will be terminated. + /// + Task CurrentRestoreOperation { get; } + + /// + /// An entry point used by CPS to indicate given project needs to be restored. + /// + /// + /// Unique identifier of the project. Should be a full path to project file. + /// + /// Metadata needed for restoring the project. + /// Cancellation token. + /// + /// Returns a restore task corresponding to the nominated project request. + /// NuGet will batch restore requests so it's possible the same restore task will be returned for multiple projects. + /// When the requested restore operation for the given project completes the task will indicate operation success or failure. + /// + /// Thrown if is not the path of a project file. + /// Thrown if is null. + /// Thrown if is cancelled. + [Obsolete("Use IVsSolutionRestoreService5 instead")] + Task NominateProjectAsync(string projectUniqueName, IVsProjectRestoreInfo projectRestoreInfo, CancellationToken token); + } ``` -## IVsPackageRestorer interface +## IVsSolutionRestoreService2 interface ```cs -public interface IVsPackageRestorer -{ /// - /// Returns a value indicating whether the user consent to download NuGet packages - /// has been granted. + /// Represents a package restore service API for integration with a project system. /// - /// true if the user consent has been granted; otherwise, false. - bool IsUserConsentGranted(); + public interface IVsSolutionRestoreService2 + { + /// + /// An entry point which allows non-NETCore SDK based projects to indicate given project needs to be restored. + /// + /// + /// Unique identificator of the project. Should be a full path to project file. + /// + /// Cancellation token. + /// + /// Returns a restore task corresponding to the nominated project request. + /// NuGet will batch restore requests so it's possible the same restore task will be returned for multiple projects. + /// When the requested restore operation for the given project completes the task will indicate operation success or failure. + /// + Task NominateProjectAsync(string projectUniqueName, CancellationToken token); + } +``` + +## IVsSolutionRestoreService3 interface +```cs /// - /// Restores NuGet packages installed in the given project within the current solution. + /// Represents a package restore service API for integration with a project system. /// - /// The project whose NuGet packages to restore. - void RestorePackages(Project project); -} + public interface IVsSolutionRestoreService3 + { + /// + /// A task providing last/current restore operation status. + /// Could be null if restore has not started yet. + /// + /// + /// This task is a reflection of the current state of the current-restore-operation or + /// recently-completed-restore. The usage of this property will be to continue, + /// e.g. to build solution or something) on completion of this task. + /// Also, on completion, if the task returns false then it means the restore failed and + /// the build task will be terminated. + /// + Task CurrentRestoreOperation { get; } + + /// + /// An entry point used by CPS to indicate given project needs to be restored. + /// This entry point also handles PackageDownload items + /// + /// + /// Unique identifier of the project. Should be a full path to project file. + /// + /// Metadata needed for restoring the project. + /// Cancellation token. + /// + /// Returns a restore task corresponding to the nominated project request. + /// NuGet will batch restore requests so it's possible the same restore task will be returned for multiple projects. + /// When the requested restore operation for the given project completes the task will indicate operation success or failure. + /// + /// Thrown if is not the path of a project file. + /// Thrown if is null. + /// Thrown if is cancelled. + [Obsolete("Use IVsSolutionRestoreService5 instead")] + Task NominateProjectAsync(string projectUniqueName, IVsProjectRestoreInfo2 projectRestoreInfo, CancellationToken token); + } ``` -## IVsPackageSourceProvider interface +## IVsSolutionRestoreService4 interface ```cs -public interface IVsPackageSourceProvider -{ /// - /// Provides the list of package sources. + /// Represents a package restore service API for integration with a project system. + /// Implemented by NuGet. /// - /// Unofficial sources will be included in the results - /// Disabled sources will be included in the results - /// Key: source name Value: source URI - IEnumerable> GetSources(bool includeUnOfficial, bool includeDisabled); + public interface IVsSolutionRestoreService4 : IVsSolutionRestoreService3 + { + /// + /// A project system can call this service (optionally) to register itself to coordinate restore.
    + /// Each project can only register once. NuGet will call into the source to wait for nominations for restore.
    + /// NuGet will remove the registered object when a project is unloaded. + ///     + /// Represents a project specific info source + /// Cancellation token. + /// If the project has already been registered. + /// If is null. + /// If 's is . + Task RegisterRestoreInfoSourceAsync(IVsProjectRestoreInfoSource restoreInfoSource, CancellationToken cancellationToken); + } +``` + +## IVsSolutionRestoreService5 interface +```cs /// - /// Raised when sources are added, removed, disabled, or modified. + /// Represents a package restore service API for integration with a project system. + /// Implemented by NuGet. /// - event EventHandler SourcesChanged; -} + public interface IVsSolutionRestoreService5 : IVsSolutionRestoreService4 + { + /// + /// An entry point used by CPS to indicate given project needs to be restored. + /// + /// + /// The full path to the project file. In the VS SDK's IVsSolution, this is also known as the unique name. + /// + /// Metadata needed for restoring the project. + /// Cancellation token. + /// + /// Returns a restore task corresponding to the nominated project request. + /// NuGet will batch restore requests so it's possible the same restore task will be returned for multiple projects. + /// When the requested restore operation for the given project completes the task will indicate operation success or failure. + /// + /// Thrown if is not the path of a project file, + /// or if has some basic validation errors. + /// Thrown if is . + /// Thrown if is cancelled. + Task NominateProjectAsync(string projectUniqueName, IVsProjectRestoreInfo3 projectRestoreInfo, CancellationToken token); + } ``` -## IVsPackageUninstaller interface +## IVsProjectRestoreInfoSource interface ```cs -public interface IVsPackageUninstaller -{ - /// - /// Uninstall the specified package from a project and specify whether to uninstall its dependency packages - /// too. - /// - /// The project from which the package is uninstalled. - /// The package to be uninstalled - /// - /// A boolean to indicate whether the dependency packages should be - /// uninstalled too. - /// - void UninstallPackage(Project project, string packageId, bool removeDependencies); -} + /// + /// Represents a package restore service API for integration with a project system. + /// Implemented by the project-system. + /// + public interface IVsProjectRestoreInfoSource + { + /// + /// Project Unique Name. + /// Must be equivalent to the name provided in the or equivalent. + /// + /// Never . + string Name { get; } + + /// + /// Whether the source needs to do some work that could lead to a nomination.
    + /// Called frequently, so it should be very efficient. + ///     + bool HasPendingNomination { get; } + + /// + /// NuGet calls this method to wait on a potential nomination.
    + /// If the project has no pending restore data, it will return a completed task.
    + /// Otherwise, the task will be completed once the project nominates.
    + /// The task will be cancelled, if the source decide it no longer needs to nominate (for example: the restore state has no change)
    + /// The task will be failed, if the source runs into a problem, and it cannot get the correct data to nominate (for example: DT build failed)
    + ///     + /// Cancellation token. + Task WhenNominated(CancellationToken cancellationToken); + } ``` -## IVsTemplateWizard interface +## IVsSolutionRestoreStatusProvider interface ```cs -/// -/// Defines the logic for a template wizard extension. -/// - -public interface IVsTemplateWizard : IWizard -{ -} + /// + /// Provides the status of IVsSolutionRestore. + /// + public interface IVsSolutionRestoreStatusProvider + { + /// + /// IsRestoreCompleteAsync indicates whether or not automatic package restore has pending work. + /// Automatic package restore applies for both packages.config and PackageReference projects. + /// + /// Returns true if all projects in the solution that require nomination have been nominated for restore and all pending restores have completed. + /// The result does not indicate that restore completed successfully, a failed restore will still return true. + /// + /// + /// Special cases: + /// * An empty solution will return true. + /// * If no solution is open this will true. + /// * An invalid project that does not provide restore details will cause this to return false since restore will not run for that project. + /// + /// Restores running due to Install/Update/Uninstall operations are NOT included in this status. Status here is limited to IVsSolutionRestoreService. + /// + Task IsRestoreCompleteAsync(CancellationToken token); + } ``` diff --git a/docs/what-is-nuget.md b/docs/what-is-nuget.md index 4d8b884da..5c0537b68 100644 --- a/docs/what-is-nuget.md +++ b/docs/what-is-nuget.md @@ -1,9 +1,9 @@ --- title: What is NuGet and what does it do? description: A comprehensive introduction to what NuGet is and does -author: karann-msft -ms.author: karann -ms.date: 05/24/2019 +author: JonDouglas +ms.author: jodou +ms.date: 11/30/2021 ms.topic: overview --- @@ -32,7 +32,7 @@ A "compatible" package means that it contains assemblies built for at least one Package developers who require APIs outside of .NET Standard, on the other hand, create separate assemblies for the different target frameworks they want to support and include all of those assemblies in the same package (which is called "multi-targeting"). When a consumer installs such a package, NuGet extracts only those assemblies that are needed by the project. This minimizes the package's footprint in the final application and/or assemblies produced by that project. A multi-targeting package is, of course, more difficult for its creator to maintain. > [!Note] -> Targeting .NET Standard supersedes the previous approach of using various portable class library (PCL) targets. This documentation therefore focuses on creating packages for .NET Standard. +> For guidance on app components vs. reusable libraries, see the [.NET Standard documentation on the topic](/dotnet/standard/net-standard?branch=main#when-to-target-net50-vs-netstandard). ## NuGet tools @@ -100,10 +100,14 @@ To make these processes work efficiently, NuGet does some behind-the-scenes opti Within an individual project, NuGet manages the overall dependency graph, which again includes resolving multiple references to different versions of the same package. It's quite common that a project takes a dependency on one or more packages that themselves have the same dependencies. Some of the most useful utility packages on nuget.org are employed by many other packages. In the entire dependency graph, then, you could easily have ten different references to different versions of the same package. To avoid bringing multiple versions of that package into the application itself, NuGet sorts out which single version can be used by all consumers. (For more information, see [Dependency Resolution](concepts/dependency-resolution.md).) -Beyond that, NuGet maintains all the specifications related to how packages are structured (including [localization](create-packages/creating-localized-packages.md) and [debug symbols](create-packages/symbol-packages.md)) and how they are [referenced](consume-packages/package-references-in-project-files.md) (including [version ranges](concepts/package-versioning.md#version-ranges-and-wildcards) and [pre-release versions](create-packages/prerelease-packages.md).) NuGet also provides various APIs to work with its services programmatically, and provides support for developers who write Visual Studio extensions and project templates. +Beyond that, NuGet maintains all the specifications related to how packages are structured (including [localization](create-packages/creating-localized-packages.md) and [debug symbols](create-packages/symbol-packages-snupkg.md)) and how they are [referenced](consume-packages/package-references-in-project-files.md) (including [version ranges](concepts/package-versioning.md#version-ranges) and [pre-release versions](create-packages/prerelease-packages.md).) NuGet also provides various APIs to work with its services programmatically, and provides support for developers who write Visual Studio extensions and project templates. Take a moment to browse the table of contents for this documentation, and you see all of these capabilities represented there, along with release notes dating back to NuGet's beginnings. +## Related video + +Find NuGet videos on [Channel 9](/shows/NuGet-101/) and [YouTube](https://www.youtube.com/playlist?list=PLdo4fOcmZ0oVLvfkFk8O9h6v2Dcdh2bh_). + ## Comments, contributions, and issues Finally, we very much welcome comments and contributions to this documentation—just select the **Feedback** and **Edit** commands on the top of any page, or visit the [docs repository](https://github.com/NuGet/docs.microsoft.com-nuget/) and [docs issue list](https://github.com/NuGet/docs.microsoft.com-nuget/issues) on GitHub. diff --git a/global.json b/global.json new file mode 100644 index 000000000..d894f924e --- /dev/null +++ b/global.json @@ -0,0 +1,5 @@ +{ + "msbuild-sdks": { + "Microsoft.Build.NoTargets" : "3.7.134" + } +} \ No newline at end of file