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/.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 49ddd1d3f..39be778c5 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -1,14 +1,11 @@ { "build_entry_point": "docs", - "need_generate_pdf": false, - "need_generate_intellisense": false, "docsets_to_publish": [ { "docset_name": "Nuget_concept", "build_source_folder": "docs", "build_output_subfolder": "nuget", "locale": "en-us", - "version": 0, "open_to_public_contributors": true, "type_mapping": { "Conceptual": "Content", @@ -16,18 +13,56 @@ "RestApi": "Content" }, "build_entry_point": "docs", - "template_folder": "_themes" + "template_folder": "_themes", + "version": 0 } ], "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": "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": "main", + "branch_mapping": {} + }, + { + "path_to_root": "nuget-samples", + "url": "https://github.com/NuGet/Samples", + "branch": "main", "branch_mapping": {} } - ] + ], + "branch_target_mapping": { + "live": [ + "Publish", + "Pdf" + ], + "main": [ + "Publish", + "PDF" + ] + }, + "need_generate_pdf_url_template": true, + "Targets": { + "Pdf": { + "template_folder": "_themes.pdf" + } + }, + "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 new file mode 100644 index 000000000..be80d09e9 --- /dev/null +++ b/.openpublishing.redirection.json @@ -0,0 +1,394 @@ +{ + "redirections": [ + { + "source_path": "docs/api/introduction.md", + "redirect_url": "/nuget/api/overview", + "redirect_document_id": false + }, + { + "source_path": "docs/api/NuGet-API-V3.md", + "redirect_url": "/nuget/reference/nuget-client-sdk", + "redirect_document_id": false + }, + { + "source_path": "docs/api/NuGet-Credential-Providers-for-Visual-Studio.md", + "redirect_url": "/nuget/reference/extensibility/nuget-credential-providers-for-visual-studio", + "redirect_document_id": false + }, + { + "source_path": "docs/api/nuget-exe-credential-providers.md", + "redirect_url": "/nuget/reference/extensibility/nuget-exe-credential-providers", + "redirect_document_id": false + }, + { + "source_path": "docs/consume-packages/managing-the-nuget-cache.md", + "redirect_url": "/nuget/consume-packages/managing-the-global-packages-and-cache-folders", + "redirect_document_id": false + }, + { + "source_path": "docs/create-packages/Dependency-Versions.md", + "redirect_url": "/nuget/concepts/package-versioning", + "redirect_document_id": false + }, + { + "source_path": "docs/create-packages/project-json-impact.md", + "redirect_url": "/nuget/archive/project-json-impact", + "redirect_document_id": false + }, + { + "source_path": "docs/create-packages/project-json-and-uwp.md", + "redirect_url": "/nuget/archive/project-json-and-uwp", + "redirect_document_id": false + }, + { + "source_path": "docs/guides/create-cross-platform-packages.md", + "redirect_url": "/nuget/guides/create-packages-for-xamarin", + "redirect_document_id": false + }, + { + "source_path": "docs/guides/install-nuget.md", + "redirect_url": "/nuget/install-nuget-client-tools", + "redirect_document_id": false + }, + { + "source_path": "docs/guides/create-net-standard-packages-vs2017.md", + "redirect_url": "/nuget/quickstart/create-and-publish-a-package-using-visual-studio", + "redirect_document_id": false + }, + { + "source_path": "docs/Schema/project-json.md", + "redirect_url": "/nuget/archive/project-json", + "redirect_document_id": false + }, + { + "source_path": "docs/Schema/analyzers-conventions.md", + "redirect_url": "/nuget/guides/analyzers-conventions", + "redirect_document_id": false + }, + { + "source_path": "docs/Schema/msbuild-targets.md", + "redirect_url": "/nuget/reference/msbuild-targets", + "redirect_document_id": false + }, + { + "source_path": "docs/Schema/nuget-config-file.md", + "redirect_url": "/nuget/reference/nuget-config-file", + "redirect_document_id": false + }, + { + "source_path": "docs/Schema/nuspec.md", + "redirect_url": "/nuget/reference/nuspec", + "redirect_document_id": false + }, + { + "source_path": "docs/Schema/packages-config.md", + "redirect_url": "/nuget/reference/packages-config", + "redirect_document_id": false + }, + { + "source_path": "docs/Schema/target-frameworks.md", + "redirect_url": "/nuget/reference/target-frameworks", + "redirect_document_id": false + }, + { + "source_path": "docs/Quickstart/restore.md", + "redirect_url": "/nuget/consume-packages/package-restore-troubleshooting", + "redirect_document_id": false + }, + { + "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", + "redirect_document_id": false + }, + { + "source_path": "docs/policies/command-line-reference.md", + "redirect_url": "/nuget/reference/nuget-exe-cli-reference", + "redirect_document_id": false + }, + { + "source_path": "docs/policies/nuget-faq.md", + "redirect_url": "/nuget/resources/nuget-faq", + "redirect_document_id": false + }, + { + "source_path": "docs/faqs/nuget-faq.md", + "redirect_url": "/nuget/resources/nuget-faq", + "redirect_document_id": false + }, + { + "source_path": "docs/reference/migrate-packages-config-to-package-reference.md", + "redirect_url": "/nuget/consume-packages/migrate-packages-config-to-package-reference", + "redirect_document_id": false + }, + { + "source_path": "docs/reference/analyzers-conventions.md", + "redirect_url": "/nuget/guides/analyzers-conventions", + "redirect_document_id": false + }, + { + "source_path": "docs/create-packages/native-packages.md", + "redirect_url": "/nuget/guides/native-packages", + "redirect_document_id": false + }, + { + "source_path": "docs/consume-packages/dependency-resolution.md", + "redirect_url": "/nuget/concepts/dependency-resolution", + "redirect_document_id": false + }, + { + "source_path": "docs/reference/package-versioning.md", + "redirect_url": "/nuget/concepts/package-versioning", + "redirect_document_id": false + }, + { + "source_path": "docs/reference/ID-Prefix-Reservation.md", + "redirect_url": "/nuget/nuget-org/id-prefix-reservation", + "redirect_document_id": false + }, + { + "source_path": "docs/reference/licenses.nuget.org.md", + "redirect_url": "/nuget/nuget-org/licenses.nuget.org", + "redirect_document_id": false + }, + { + "source_path": "docs/reference/organizations-on-nuget-org.md", + "redirect_url": "/nuget/nuget-org/organizations-on-nuget-org", + "redirect_document_id": false + }, + { + "source_path": "docs/policies/data-requests.md", + "redirect_url": "/nuget/nuget-org/policies/data-requests", + "redirect_document_id": false + }, + { + "source_path": "docs/policies/deleting-packages.md", + "redirect_url": "/nuget/nuget-org/policies/deleting-packages", + "redirect_document_id": false + }, + { + "source_path": "docs/policies/dispute-resolution.md", + "redirect_url": "/nuget/nuget-org/policies/dispute-resolution", + "redirect_document_id": false + }, + { + "source_path": "docs/consume-packages/ways-to-install-a-package.md", + "redirect_url": "/nuget/consume-packages/overview-and-workflow", + "redirect_document_id": false + }, + { + "source_path": "docs/create-packages/publish-a-package.md", + "redirect_url": "/nuget/nuget-org/publish-a-package", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/package-manager-ui.md", + "redirect_url": "/nuget/consume-packages/install-use-packages-visual-studio", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/package-manager-console.md", + "redirect_url": "/nuget/consume-packages/install-use-packages-powershell", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/dotnet-commands.md", + "redirect_url": "/nuget/reference/dotnet-commands", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/nuget-exe-cli-reference.md", + "redirect_url": "/nuget/reference/nuget-exe-cli-reference", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-add.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-add", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-config.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-config", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-delete.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-delete", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-environment-variables.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-environment-variables", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-help.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-help", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-init.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-init", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-install.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-install", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-list.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-list", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-locals.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-locals", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-long-path.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-long-path", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-mirror.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-mirror", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-pack.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-pack", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-push.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-push", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-restore.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-restore", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-setapikey.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-setapikey", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-sign.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-sign", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-sources.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-sources", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-spec.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-spec", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-trusted-signers.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-trusted-signers", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-update.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-update", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/cli-ref-verify.md", + "redirect_url": "/nuget/reference/cli-reference/cli-ref-verify", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/powershell-reference.md", + "redirect_url": "/nuget/reference/powershell-reference", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/ps-ref-add-bindingredirect.md", + "redirect_url": "/nuget/reference/ps-reference/ps-ref-add-bindingredirect", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/ps-ref-find-package.md", + "redirect_url": "/nuget/reference/ps-reference/ps-ref-find-package", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/ps-ref-get-package.md", + "redirect_url": "/nuget/reference/ps-reference/ps-ref-get-package", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/ps-ref-get-project.md", + "redirect_url": "/nuget/reference/ps-reference/ps-ref-get-project", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/ps-ref-install-package.md", + "redirect_url": "/nuget/reference/ps-reference/ps-ref-install-package", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/ps-ref-open-packagepage.md", + "redirect_url": "/nuget/reference/ps-reference/ps-ref-open-packagepage", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/ps-ref-register-tab-expansion.md", + "redirect_url": "/nuget/reference/ps-reference/ps-ref-register-tabexpansion", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/ps-ref-sync-package.md", + "redirect_url": "/nuget/reference/ps-reference/ps-ref-sync-package", + "redirect_document_id": false + }, + { + "source_path": "docs/tools/ps-ref-uninstall-package.md", + "redirect_url": "/nuget/reference/ps-reference/ps-ref-uninstall-package", + "redirect_document_id": false + }, + { + "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/LICENSE-CODE b/LICENSE-CODE new file mode 100644 index 000000000..b17b032a4 --- /dev/null +++ b/LICENSE-CODE @@ -0,0 +1,17 @@ +The MIT License (MIT) +Copyright (c) Microsoft Corporation + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and +associated documentation files (the "Software"), to deal in the Software without restriction, +including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, +and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial +portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT +NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index b4eecd722..36a0aa314 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,67 @@ -# 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 *live* branch, which is what's published to the live docs site. (The master branch is used for staging larger series of changes.) +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. ## 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/en-us/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, 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'll see on other topics. The fields you should change are the following: title, ms.date, ms.assetid, description, and keywords. - 1. For ms.assetid, always create a new GUID for a new topic. - 1. Leave the ms.author and manager fields set as they are, because these are used to manage ownership internally. - 1. Ideally for SEO, the title field and the top-level # heading of the topic are different; see various topics for examples. -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 | +| --- | --- | +| 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. | + +## 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 @@ -42,11 +69,11 @@ 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". -Also avoid any cultural references or idioms that do not translate easily. +Also, avoid any cultural references or idioms that do not translate easily. When describing UI actions, use terms like "select" instead of "click" or "check" because "select" translates better. Use "clear" instead of "uncheck", and prefer "run" over "execute". @@ -59,7 +86,7 @@ Follow these naming conventions and capitalizations when referring to NuGet and - NuGet: refers to the technology. - NuGet Package Manager UI, NuGet Package Manager Console, etc.: refers to other components build on NuGet. - nuget.exe: refers to the command-line executable; you can use "nuget" by itself when followed by other arguments. When referring to the command by itself, as in "when you run nuget", include the .exe as in "when you run nuget.exe" so your meaning is clear. -- packages.config, project.json: refer to NuGet files in a project. +- packages.config (or the deprecated project.json): refer to NuGet files in a project. - NuGet.Config and NuGetDefaults.Config: these files appear with this capitalization so be sure to follow them. - .nuspec: refers to a NuGet specification for creating a package; generally, we speak of a .nuspec file with the period, because it's always used as a file extension. @@ -79,13 +106,13 @@ 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. ### Screenshots and images -Make all images purposeful and easy to consume; avoid graphics for the sake of graphics. When using a screenshot, include a red rounded-rectangle outline of where the reader's eyes should go. That is, do the work to help the reader look at what you want them to look at, rather than burdening them with having to figure that our for themselves. +Make all images purposeful and easy to consume; avoid graphics for the sake of graphics. When using a screenshot, include a red rounded-rectangle outline of where the reader's eyes should go. That is, do the work to help the reader look at what you want them to look at, rather than burdening them with having to figure that out for themselves. If an image has white bleed areas on the edges, draw a 1-pixel gray outline around the entire graphic. @@ -93,7 +120,7 @@ Always include a meaningful description of the image in the markdown alt-text be ### Inline code -Delineate inline code with grave accents (backticks), as in `nuget pack`. This inline formatting is used for the following: +Delineate inline code with grave accents (backticks), as in \`nuget pack\`. This inline formatting is used for the following: - Code - Identifiers @@ -111,45 +138,45 @@ 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 "bash" for command-line examples and "output" for command-line results. +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. -The only case when you should use ``` without a language tag is when creating a block of fixed-point text that isn't related to any kind of code. In these cases you can also just indent the code block, which can be preferable because it visually separates the code in an editor. See [docs/create-packages/project-json-and-uwp.md](./docs/Create-Packages/project-json-and-UWP.md) for an example. +The only case when you should use ``` without a language tag is when creating a block of fixed-point text that isn't related to any kind of code. In these cases you can also just indent the code block, which can be preferable because it visually separates the code in an editor. ### 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/en-us/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 | Shading color | Topic with examples | +| Tag | Callout use | Topic with examples | | --- | --- | --- | -| `> [!Note]` | Light blue, use for callouts without any special emphasis. | [Creating NuGet packages](https://docs.microsoft.com/nuget/create-packages/creating-a-package) | -| `> [!Tip]` | Green, use for 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]` | Yellow, use for callouts that describe cautions. | [NuGet.Server](https://docs.microsoft.com/nuget/hosting-packages/nuget-server) | -| `> [!Warning]` | Red, use for 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, 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 -If you need to do something that markdown can't handle, use inline HTML. An example is creating a bullet list inside a table. +If you need to do something that Markdown can't handle, use inline HTML. An example is creating a bullet list inside a table. Use `<` and `>` for < and > characters outside a code block or inline code (delimited by backticks `). Block-level HTML elements have a few restrictions: -* They must be separated from surrounding text by blank lines. -* The begin and end tags of the outermost block element must not be indented. -* Markdown can't be used within HTML blocks. +- They must be separated from surrounding text by blank lines. +- The begin and end tags of the outermost block element must not be indented. +- Markdown can't be used within HTML blocks. diff --git a/ThirdPartyNotices b/ThirdPartyNotices new file mode 100644 index 000000000..a0bd09d68 --- /dev/null +++ b/ThirdPartyNotices @@ -0,0 +1,15 @@ +##Legal Notices +Microsoft and any contributors grant you a license to the Microsoft documentation and other content +in this repository under the [Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/legalcode), +see the [LICENSE](LICENSE) file, and grant you a license to any code in the repository under the [MIT License](https://opensource.org/licenses/MIT), see the +[LICENSE-CODE](LICENSE-CODE) file. + +Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation +may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. +The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. +Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653. + +Privacy information can be found at https://privacy.microsoft.com/en-us/ + +Microsoft and any contributors reserve all others rights, whether under their respective copyrights, patents, +or trademarks, whether by implication, estoppel or otherwise. \ No newline at end of file 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/API/NuGet-API-V3.md b/docs/API/NuGet-API-V3.md deleted file mode 100644 index 3fbc136db..000000000 --- a/docs/API/NuGet-API-V3.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_url: /nuget/reference/nuget-client-sdk ---- \ No newline at end of file diff --git a/docs/API/NuGet-Credential-Providers-for-Visual-Studio.md b/docs/API/NuGet-Credential-Providers-for-Visual-Studio.md deleted file mode 100644 index f179a7585..000000000 --- a/docs/API/NuGet-Credential-Providers-for-Visual-Studio.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_url: /nuget/reference/extensibility/nuget-credential-providers-for-visual-studio ---- \ No newline at end of file diff --git a/docs/API/_data/package-registration-page.json b/docs/API/_data/package-registration-page.json deleted file mode 100644 index 3eb52c99c..000000000 --- a/docs/API/_data/package-registration-page.json +++ /dev/null @@ -1,55 +0,0 @@ -{ - "count": 2, - "lower": "1.0.531", - "parent": "https://api.nuget.org/v3/registration3/ravendb.client/index.json", - "upper": "1.0.729-unstable", - "items": [ - { - "@id": "https://api.nuget.org/v3/registration3/ravendb.client/1.0.531.json", - "@type": "Package", - "commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1", - "commitTimeStamp": "2017-10-26T14:12:19.3439088Z", - "catalogEntry": { - "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.38.37/ravendb.client.1.0.531.json", - "@type": "PackageDetails", - "authors": "Hibernating Rhinos", - "iconUrl": "http://static.ravendb.net/logo-for-nuget.png", - "id": "RavenDB.Client", - "licenseUrl": "http://www.ravendb.net/licensing", - "listed": false, - "packageContent": "https://api.nuget.org/v3-flatcontainer/ravendb.client/1.0.531/ravendb.client.1.0.531.nupkg", - "projectUrl": "http://www.ravendb.net/", - "published": "1900-01-01T00:00:00+00:00", - "requireLicenseAcceptance": true, - "title": "RavenDB (Client Only)", - "version": "1.0.531" - }, - "packageContent": "https://api.nuget.org/v3-flatcontainer/ravendb.client/1.0.531/ravendb.client.1.0.531.nupkg", - "registration": "https://api.nuget.org/v3/registration3/ravendb.client/index.json" - }, - { - "@id": "https://api.nuget.org/v3/registration3/ravendb.client/1.0.729-unstable.json", - "@type": "Package", - "commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1", - "commitTimeStamp": "2017-10-26T14:12:19.3439088Z", - "catalogEntry": { - "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.18.22.05/ravendb.client.1.0.729-unstable.json", - "@type": "PackageDetails", - "authors": "Hibernating Rhinos", - "iconUrl": "http://static.ravendb.net/logo-for-nuget.png", - "id": "RavenDB.Client", - "licenseUrl": "http://www.ravendb.net/licensing", - "listed": false, - "packageContent": "https://api.nuget.org/v3-flatcontainer/ravendb.client/1.0.729-unstable/ravendb.client.1.0.729-unstable.nupkg", - "projectUrl": "http://www.ravendb.net/", - "published": "1900-01-01T00:00:00+00:00", - "requireLicenseAcceptance": true, - "summary": "This package includes the clinet API of RavenDB.", - "title": "RavenDB Client", - "version": "1.0.729-Unstable" - }, - "packageContent": "https://api.nuget.org/v3-flatcontainer/ravendb.client/1.0.729-unstable/ravendb.client.1.0.729-unstable.nupkg", - "registration": "https://api.nuget.org/v3/registration3/ravendb.client/index.json" - } - ] -} \ No newline at end of file diff --git a/docs/API/introduction.md b/docs/API/introduction.md deleted file mode 100644 index 8f2090398..000000000 --- a/docs/API/introduction.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_url: /nuget/api/overview ---- \ No newline at end of file diff --git a/docs/API/nuget-exe-Credential-Providers.md b/docs/API/nuget-exe-Credential-Providers.md deleted file mode 100644 index b1a9b277c..000000000 --- a/docs/API/nuget-exe-Credential-Providers.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_url: /nuget/reference/extensibility/nuget-exe-credential-providers ---- \ No newline at end of file diff --git a/docs/API/overview.md b/docs/API/overview.md deleted file mode 100644 index 97285fc06..000000000 --- a/docs/API/overview.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -# required metadata  - -title: Overview, NuGet API | Microsoft Docs -author: -- joelverhagen -- kraigb -ms.author: -- joelverhagen -- kraigb -manager: skofman -ms.date: 10/26/2017 -ms.topic: reference -ms.prod: nuget -ms.technology: null -ms.assetid: 8c81f1ac-18c7-44d1-b2e3-584fe85dee6f - -# optional metadata - -description: The NuGet API is a set of HTTP endpoints that can be used to download packages, fetch metadata, publish new packages, etc. -keywords: NuGet V3 API, NuGet V2 API, NuGet JSON, NuGet registration API, NuGet API flat container, NuGet nupkg API, NuGet metadata API, NuGet search API, NuGet push API, NuGe publish API, NuGet delete API, NuGet unlist API, NuGet protocol -ms.reviewer: -- karann -- unniravindranathan - ---- - -# NuGet API - -The NuGet API is a set of HTTP endpoints that can be used to download packages, fetch metadata, publish new packages, -and perform most other operations available in the official NuGet clients. - -This API is used by the NuGet client in Visual Studio, nuget.exe, and the .NET CLI to perform NuGet operations such as -[`dotnet restore`](https://docs.microsoft.com/dotnet/articles/core/preview3/tools/dotnet-restore), search in the Visual -Studio UI, and [`nuget.exe push`](../tools/cli-ref-push.md). - -Note in some cases, nuget.org has additional requirements that are not enforced by other package sources. These -differences are documented by the [nuget.org Protocols](nuget-protocols.md). - -## 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`. - -This JSON document contains a list of *resources* which provide different functionality and fulfill different -use cases. - -Clients that support the API should accept one or more of these service index URL as the means of connecting to the -respective package sources. - -For more information about the service index, see [its API reference](service-index.md). - -## Versioning - -The API is version 3 of NuGet's HTTP protocol. This protocol is sometimes referred to as "the V3 API." These reference -documents will refer to this version of the protocol simply as "the API." - -The service index schema version is indicated by the `version` property in the service index. The API mandates that -the version string has a major version number of `3`. As non-breaking changes are made to the service index schema, the -version string's minor version will be increased. - -Older clients (such as nuget.exe 2.x) do not support the V3 API and only support the older V2 API, which is not -documented here. - -The NuGet V3 API is named as such because it is the successor of the V2 API, which was the OData-based protocol -implemented by the 2.x version of the official NuGet client. The V3 API was first supported by the 3.0 version of the -official NuGet client and is still the latest major protocol version supported by the NuGet client, 4.0 and on. - -Non-breaking protocol changes have been made to the API since it was first release. - -## Resources and schema - -The **service index** describes a variety of resources. The current set of supported resources are as follows: - -Resource name | Required | Description ----------------------------------------------------------------------- | -------- | ----------- -[`PackagePublish`](package-publish-resource.md) | yes | Push and delete (or unlist) packages. -[`SearchQueryService`](search-query-service-resource.md) | yes | Filter and search for packages by keyword. -[`RegistrationsBaseUrl`](registration-base-url-resource.md) | yes | Get package metadata. -[`PackageBaseAddress`](package-base-address-resource.md) | yes | Get package content (.nupkg). -[`SearchAutocompleteService`](search-autocomplete-service-resource.md) | no | Discover package IDs and versions by substring. -[`ReportAbuseUriTemplate`](report-abuse-resource.md) | no | Construct a URL to access a "report abuse" web page. -[`Catalog`](catalog-resource.md) | no | Full record of all package events. - -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 -each resource, see the topics listed above. - -> [!Note] -> When a source does not implement `SearchAutocompleteService` any autocomplete behavior should be disabled -> gracefully. When `ReportAbuseUriTemplate` is not implemented, the official NuGet client falls back to nuget.org's -> report abuse URL (tracked by [NuGet/Home#4924](https://github.com/NuGet/Home/issues/4924)). Other clients may opt -> to simply not show a report abuse URL to the user. - -## Timestamps - -All timestamps returned by the API are UTC or are otherwise specified using -[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) representation. - -## HTTP methods - -Verb | Use ------- | ----------- -GET | Performs a read-only operation, typically retrieving data. -HEAD | Fetches the response headers for the corresponding `GET` request. -PUT | Creates a resource that doesn't exist or, if it does exist, updates it. Some resources may not support update. -DELETE | Deletes or unlists a resource. - -## HTTP status codes - -Code | Description ----- | ----- -200 | Success, and there is a response body. -201 | Success, and the resource was created. -202 | Success, the request has been accepted but some work may still be incomplete and completed asynchronously. -204 | Success, but there is no response body. -301 | A permanent redirect. -302 | A temporary redirect. -400 | The parameters in the URL or in the request body aren't valid. -401 | The provided credentials are invalid. -403 | The action is not allowed given the provided credentials. -404 | The requested resource doesn't exist. -409 | The request conflicts with an existing resource. -500 | The service has encountered an unexpected error. -503 | The service is temporarily unavailable. - -Any `GET` request made to a API endpoint may return an HTTP redirect (301 or 302). Clients should gracefully handle -such redirects by observing the `Location` header and issueing a subsequent `GET`. Documentation concerning specific -endpoints will not explicitly call out where redirects may be used. - -In the case of a 500-level status code, the client can implement a reasonable retry mechanism. The official NuGet -client retries three times when encountering any 500-level status code or TCP/DNS error. - -## HTTP request headers - -Name | Description ------------------------- | ----------- -X-NuGet-ApiKey | Required for push and delete, see [`PackagePublish` resource](package-publish-resource.md) -X-NuGet-Client-Version | **Deprecated** and replaced by `X-NuGet-Protocol-Version` -X-NuGet-Protocol-Version | Required in certain cases only on nuget.org, see [nuget.org protocols](NuGet-Protocols.md) - -## Authentication - -Authentication is left up to the package source implementation to define. For nuget.org, only the `PackagePublish` -resource requires authentication via a special API key header. See -[`PackagePublish` resource](package-publish-resource.md) for details. diff --git a/docs/Consume-Packages/Configuring-NuGet-Behavior.md b/docs/Consume-Packages/Configuring-NuGet-Behavior.md deleted file mode 100644 index 1838873c4..000000000 --- a/docs/Consume-Packages/Configuring-NuGet-Behavior.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -# required metadata - -title: Configuring the behavior of NuGet | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 10/24/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: c1e34826-d07d-4609-a0fd-123459ae89c5 - -# optional metadata - -description: NuGet.Config files control NuGet's behavior both globally and on a per-project basis, and are modified with nuget config command. -keywords: NuGet config files, NuGet configuration, NuGet behavior settings, NuGet settings, Nuget.Config, NuGetDefaults.Config, defaults -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Configuring NuGet behavior - -NuGet's `NuGet.Config` files store configuration settings in XML and allow for changing default configuration values. NuGet uses several global configuration files and any number of configuration files within and near to a project to determine its exact behavior. In addition, in NuGet 2.7 and later you can use the `NuGetDefaults.Config` file to also specifically control package sources. - -In this topic: - -- [File locations and uses](#config-file-locations-and-uses) -- [Changing settings](#changing-config-settings) -- [How settings are applied](#how-settings-are-applied) -- [NuGet defaults file](#nuget-defaults-file) - -## Config file locations and uses - -The behavior of every NuGet command, whether issued from the command line, the Package Manager UI, or the Package Manager Console, is driven by the accumulated settings from any number of `NuGet.Config` files: - -- Project-specific `NuGet.Config` files located in any folder from the solution folder up to the drive root. These allow control over settings as they apply to a project or a group of projects. -- A solution-specific `NuGet.Config` file located within a `.nuget` folder in the solution. Settings in this file apply only to solution-wide packages and is supported only in NuGet 3.3 and earlier. It is ignored for NuGet 3.4 and later. -- The global config file located in `%APPDATA%\NuGet\NuGet.Config`, which is always used unless you specify a different config file using the `-configFile` switch on any NuGet command. For example, `nuget restore -configfile c:\my.config` uses settings from `c:\my.config` for the command and ignores any settings in the global config file. -- Additional machine-wide config files: - - NuGet 2.6 to NuGet 3.5: located in `%ProgramData%\NuGet\Config[\{IDE}[\{Version}[\{SKU}\]]]NuGet.Config`, where `{IDE}` can be `VisualStudio`, `{Version}` can be the Visual Studio version such as `14.0`, and `{SKU}` is either `Community`, `Pro`, or `Enterprise`. These variants allow you to create configurations that are specific to different versions and editions of Visual Studio if needs be. - - NuGet 4.0+: located under `%ProgramFiles(x86)%\NuGet\Config` rather than `%ProgramData%`. To migrate configuration files from `%ProgramData%`, simply copy them to the location under `%ProgramFiles(x86)%`. -- The "default" file: - - NuGet 2.7 to NuGet 3.5: located at `%PROGRAMDATA%\NuGet\NuGetDefaults.Config`, which is described later under [NuGet defaults file](#nuget-defaults-file) as a way to specifically enable and disable package sources. No other settings are supported in this file. - - NuGet 4.0+: located under `%ProgramFiles(x86)%\NuGet\Config` rather than `%ProgramData%`. - -> [!Note] -> The `%ProgramData%\NuGet` and `%ProgramFiles(x86)%\NuGet` folders typically requires Administrator permissions to modify. Administrators are expected to set the correct permissions on these folders based on the user and/or machine information. - -## Changing config settings - -A configuration file is a simple XML text file containing settings as described in the [NuGet Configuration Settings](../Schema/nuget-config-file.md) topic. - -The preferred method for changing the configuration is using the NuGet [config command](../tools/cli-ref-config.md) to set a key and value. - -> [!Note] -> Keys are always case sensitive. - -To **set a value** in any existing configuration file, use the `-configFile` switch as shown in the examples below. - -``` -nuget config -set repositoryPath=c:\packages -configfile c:\my.config -nuget config -set repositoryPath=c:\packages -configfile .\myApp\NuGet.Config -nuget config -set repositoryPath=c:\packages -configfile %ProgramData%\NuGet\Config\VisualStudio\14.0\NuGet.Config -nuget config -set repositoryPath=c:\packages -configfile %ProgramData%\NuGet\NuGetDefaults.Config -``` - -Without the `-configFile` switch, NuGet makes the change in the global config file. - -> [!Note] -> In NuGet 3.4 and later you can use environment variables in any value, as in `repositoryPath=%PACKAGEHOME%`. - -To **remove a value**, use the same commands but with an empty value, such as: - -``` -nuget config -set repositoryPath= -configfile c:\my.config -``` - -To create a new configuration file, copy the template below into that file and then use the `nuget config --configFile ` command to set values: - -```xml - - - -``` -
- -> [!Warning] -> Although you can modify the file in any text editor, NuGet (v3.4.3 and later) silently ignores the entire configuration file if it contains malformed XML (mismatched tags, invalid quotation marks, etc.). - -## How settings are applied - -As described above in [Config file locations and uses](#config-file-locations-and-uses), any number of `NuGet.Config` files can exist on a machine, both in global locations and within a project's folder structure. This allows you to control settings in different places as they apply to a project, a group of projects, or all projects. - -> [!Note] -> This process is sometimes referred to as "chaining" of config file, and the ability to insert a specific setting anywhere along the chain may be referred to as a "NuGet extensibility point." - -When `nuget.exe` is run from the command line or run implicitly within Visual Studio, it loads settings from config files in the following order: - -1. Files in `%ProgramData%\NuGet\Config` (NuGet 3.5 and earlier) or `%ProgramFiles(x86)%\NuGet\Config` (NuGet 4.0+) starting at this top folder and iterating down through the `{IDE}\{Version}\{SKU}\` subfolders if they exist. -1. The global config file, except in NuGet 3.4 and later if `-configFile` is used on the command line. -1. The file specified with `-configFile`. -1. Files found in the path to the current folder (where nuget.exe is invoked or the folder containing the Visual Studio solution), starting from the root and ending in the current folder. - -As settings are found in these files, they are processed as follows: - -1. For single-item elements, the last value found for any given key is used. This means that those settings that are "closest" to where NuGet was invoked is applied. - -1. For collection elements (such as ``), values from all configuration files are added to the collection. - -1. When `` is present for a given node, previously defined configuration values for that node are ignored. - -See [the example](#settings-walkthrough) below for a walkthrough of this process. - -Note also that the [NuGetDefaults.Config file](#nuget-defaults-file) can affect a few specific settings related to package sources, but does not have an effect on any other NuGet behavior. - -### 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 - -### Settings walkthrough - -Let's say you have the following folder structure: - - c:\ - Users - d:\ - Project1 - Source - Project2 - Source - tmp - -You then have four `NuGet.Config` files in the following locations with the given content: - -File A. Global configuration file, `%APPDATA%\NuGet\Nuget.Config`: - -```xml - - - - - - -``` - -File B. `d:\NuGet.Config`: - -```xml - - - - - - - - - -``` - -File C. `d:\Project1\NuGet.Config`: - -```xml - - - - - - - - - - - -``` - -File D. `d:\Project2\NuGet.Config`: - -```xml - - - - - - - -``` - -Here's how NuGet loads and apply the settings, depending on where it's invoked: - -- **Invoked from c:\users**: Only the default repository listed in the global configuration file (A) is used, because that's the only file found on the `c:` drive. - -- **Invoked from d:\ or d:\tmp**: File (A) is loaded first, then NuGet goes to the root of `d:` and finds file (B). NuGet also looks for a configuration file in `d:\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 `d:\tmp`. - -- **Invoked from d:\Project1 or d:\Project1\Source**: File (A) is loaded first, then NuGet loads file (B) from the `d:` root, followed by file (C). Settings in (C) override those in (B) and (A), so the `repositoryPath` where packages get installed is `d:\Project1\External\Packages` instead of `d:\tmp`. Also, because (C) clears ``, nuget.org is no longer available a source leaving only `https://MyPrivateRepo/ES/nuget`. - -- **Invoked from d:\Project2 or d:\Project2\Source**: 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 `d:\tmp` as specified in (B). - -## NuGet defaults file - -NuGet 3.3 and earlier is hardcoded to use nuget.org as the default package source, which cannot be changed. However, when using NuGet with internal package sources, it's often desirable to make sure that developers and build servers use packages from those sources instead of nuget.org. With NuGet 2.7 to 3.5, you can use the `%ProgramData%\NuGet\NuGetDefaults.Config` file (or `%ProgramFiles(x86)%\NuGet\NuGetDefaults.Config` with NuGet 4.0+) to control certain machine-wide defaults described below. This provides administrators a convenient way (using Group Policy, for example) to deploy consistent `NuGetDefaults.Config` files to developer and build machines, thus ensuring correct use of package sources. - -Note that NuGet 3.4 and later does not use a hardcoded default source. When nuget.exe is run for the first time, `NuGet.Config` is generated and nuget.org is added as the default package source in the config file. In the absence of the `NuGet.Config` file, the default package source is undefined. - -The defaults file works with the following settings: - -- `packageSources`: this collection has the same meaning as `packageSources` in regular config files and specifies the default sources in their preferred order. If this setting exists in `NuGetDefaults.Config`, then NuGet doesn't use nuget.org as a default package source. An administrator can thus make sure that everyone using this file is working with the same sources and avoids using nuget.org if desired. - -- `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 it being 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`: when publishing a package, nuget.org is used as the destination or "push source" unless another is specified, which risks developers accidentally pushing internal packages to a public site. By changing the default push source, administrators can ensure that packages stay internal unless published to nuget.org explicitly. - -> [!Note] -> 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` or any other mechanism in NuGet can prevent access to package sources like nuget.org. If an organization wishes to block such access, it much use other means such as firewalls to do so. - -## Example NuGetDefaults.Config and application - -The following is an example `NuGetDefaults.Config` file containing each of its allowable sections: - -```xml - - - - - - - - - - - - - - - - - - - - - - - - -``` diff --git a/docs/Consume-Packages/Dependency-Resolution.md b/docs/Consume-Packages/Dependency-Resolution.md deleted file mode 100644 index fd4e36228..000000000 --- a/docs/Consume-Packages/Dependency-Resolution.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -# required metadata - -title: NuGet Package Dependency Resolution | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 8/14/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 1d530a72-3486-4a0d-b6fb-017524616f91 - -# optional metadata - -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+. -keywords: NuGet package dependencies, NuGet versioning, dependency versions, version graph, version resolution, transitive restore -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# How NuGet resolves package dependencies - -Any time a package is installed or reinstalled, which includes being installed as part of a [restore](../consume-packages/package-restore.md) process, NuGet also installs any additional packages on which that first package depends. - -Those immediate dependencies might then also have dependencies on their own, which can continue to an arbitrary depth. This produces what's called a *dependency graph* that describes the relationships between packages are all levels. - -When multiple packages have the same dependency, then the same package ID can appear in the graph multiple times, potentially with different version constraints. However, only one version of a given package can be used in a project, so NuGet must choose which version is be used. The exact process depends on the package reference format being used. - -In this topic: -- [Dependency resolution with PackageReference and project.json](#dependency-resolution-with-packagereference-and-projectjson) -- [Dependency resolution with packages.config](#dependency-resolution-with-packagesconfig) -- [Excluding references](#excluding-references), which is necessary when there's a conflict between a dependency specified in one project and an assembly that's produced by another. -- [Dependency updates during package install](#dependency-updates-during-package-install) -- [Resolving incompatible package errors](#resolving-incompatible-package-errors) - -## Dependency resolution with PackageReference and project.json - -When installing packages into projects using the PackageReference or `project.json` formats, 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 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` in the `obj` folder of a project using PackageReference, or in a file named `project.lock.json` alongside `project.json`. 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 lock 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](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. - - - -#### Lowest applicable version - -The lowest applicable version rule restores the lowest possible version of a package as defined by its dependencies. It also applies to dependencies on the application or the class library unless declared as [floating](#floating-versions). - -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) - -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) - -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) - - - -#### Floating (wildcard) versions - -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 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/projectJson-dependency-4.png) - -> [!Note] -> For information on the behavior of wildcards and pre-release versions, see [Package versioning](../reference/package-versioning.md#version-ranges-and-wildcards). - - - - -#### Nearest wins - -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. - -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: - -![Application using the Nearest Wins rule](media/projectJson-dependency-5.png) - ->[!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. - -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: - -![When NuGet ignores a package in the graph, it ignores that entire branch](media/projectJson-dependency-6.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: - -![Resolving cousin dependencies using the lower version that satisfies all constraints](media/projectJson-dependency-7.png) - -In some cases, it is 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. - -![Unresolvable dependencies due to an exact version requirement](media/projectJson-dependency-8.png) - -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. - -## Dependency resolution with packages.config - -With `packages.config`, a project's dependencies are written to `packages.config` as a flat list. Any dependencies of those packages are also written in the same list. When packages are installed, NuGet might also modify the `.csproj` file, `app.config`, `web.config`, and other individual files. - -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.7 and earlier resolves the highest *patch* version (using the *major.minor.patch.build* convention). [NuGet 2.8 and higher](../release-notes/nuget-2.8.md#patch-resolution-for-dependencies) changes this behavior to look for the lowest patch version by default. 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 reference formats. - - -## Excluding references - -There are scenarios in which assemblies with the same name might be referenced more than once in a project, producing design-time and build-time errors. Consider a project that contains a custom version of `C.dll`, and references Package C that also contains `C.dll`. At the same time, the project also depends on Package B which also depends on Package C and `C.dll`. As a result, NuGet can't determine which `C.dll` to use, but you can't just remove the project's dependency on Package C because Package B also depends on it. - -To resolve this, you must directly reference the `C.dll` you want (or use another package that references the right one), and then add a dependency on Package C that excludes all its assets. This is done as follows depending on the package reference format in use: - -- [PackageReference](../consume-packages/package-references-in-project-files.md): add `Exclude="All"` in the dependency: - - ```xml - - ``` - -- `packages.config`: remove the reference to PackageC from the `.csproj` file so that it references only the version of `C.dll` that you want. - -- `project.json`: add `"exclude" : "all"` in the dependency for PackageC: - - ```json - { - "dependencies": { - "PackageC": { - "version": "1.0.0", - "exclude": "all" - } - } - } - ``` - -## Dependency updates during package install - -With NuGet 2.4.x and earlier, when a package is installed whose dependency already exists in the project, the dependency is updated to the latest version that satisfies the version constraints, even if the existing version also satisfies those constraints. - -For example, consider package A that depends on package B and specifies 1.0 for the version number. The source repository contains both versions 1.0, 1.1, and 1.2 of package B. If A is installed in a project that already contains B version 1.0, then B is updated to version 1.2. - -With NuGet 2.5 and later, if a dependency version is already satisfied, the dependency isn't updated during other package installations. - -In the same example above, installing package A into a project with NuGet 2.5 and later leaves package B 1.0 in the project, as it already satisfies the version constraint. However, if package A had requests version 1.1 or higher of B, then B 1.2 would be installed. - -## Resolving incompatible package errors - -During a package restore operation, you may see the error "One or more packages are not compatible..." or that a package "is not compatible" with the project's target framework. - -This error occurs when one or more of the packages referenced in your project do not indicate that they support the project's target framework; that is, the package does not contain a suitable DLL in its `lib` folder for a target framework that is compatible with the project. (See [Target frameworks](../Schema/Target-Frameworks.md) for a list.) - -For example, if a project targets `netstandard1.6` and you attempt to install a package that contains DLLs in only the `lib\net20` and `\lib\net45` folders, then you'll see messages like the following for the package and possibly its dependents: - -```output -Restoring packages for myproject.csproj... -Package ContosoUtilities 2.1.2.3 is not compatible with netstandard1.6 (.NETStandard,Version=v1.6). Package ContosoUtilities 2.1.2.3 supports: - - net20 (.NETFramework,Version=v2.0) - - net45 (.NETFramework,Version=v4.5) -Package ContosoCore 0.86.0 is not compatible with netstandard1.6 (.NETStandard,Version=v1.6). Package ContosoCore 0.86.0 supports: - - 11 (11,Version=v0.0) - - net20 (.NETFramework,Version=v2.0) - - sl3 (Silverlight,Version=v3.0) - - sl4 (Silverlight,Version=v4.0) -One or more packages are incompatible with .NETStandard,Version=v1.6. -Package restore failed. Rolling back package changes for 'MyProject'. -``` - -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. -- **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](../Schema/project-json.md#imports) and [MSBuild restore target PackageTargetFallback](../Schema/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. diff --git a/docs/Consume-Packages/Finding-and-Choosing-Packages.md b/docs/Consume-Packages/Finding-and-Choosing-Packages.md deleted file mode 100644 index d77032628..000000000 --- a/docs/Consume-Packages/Finding-and-Choosing-Packages.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -# required metadata - -title: Finding and choosing NuGet Packages | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 8/25/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 8886f899-797b-4704-9d16-820b55b71186 - -# optional metadata - -description: An overview of how to find and choose the best NuGet packages for a project including details on the NuGet search syntax. -keywords: NuGet package consumption, NuGet package discovery, best NuGet packages, deciding on packages, consuming packages, evaluating package, NuGet search syntax -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Finding and evaluating 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. - -On this page: - -- [Finding packages](#finding-packages) -- [Evaluating packages](#evaluating-packages) -- [Search syntax](#search-syntax) - -## Finding packages - -When you visit nuget.org or open the Package Manager UI in Visual Studio, you'll 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. - -![Default view of nuget.org/packages showing the most popular packages](media/Finding-01-Popularity.png) - -For specific needs, searching by tags (within Visual Studio's 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. - -![Search results for 'json' on nuget.org](media/Finding-02-SearchResults.png) - -You can also search using the package ID, if you know it. See [Search Syntax](#search-syntax) below. - -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. - -### Does the package support my project's target framework? - -NuGet installs a package into a project only if that package's supported frameworks include the project's target framework. (See [Supporting multiple target frameworks](../create-packages/supporting-multiple-target-frameworks.md) for how this is done when creating a package.) If the package is not compatible, NuGet issues an error. - -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. Therefore the primary way to check whether a target framework is supported is to attempt to install the package into a project. Using `Install-Package` in the NuGet Package Manager Console is the best method for this, as it shows you the most information if the package is incompatible, including its list of supported frameworks. - -At present there is no means to search nuget.org for packages that support a specific target framework, but the feature is under consideration; see [NuGet Issue 2936](https://github.com/NuGet/NuGetGallery/issues/2936). - -## Pre-release packages - -By default, NuGet does not include pre-release versions when working with packages, but you can change this behavior as follows: - -- **Package Manager UI in Visual Studio**: In the **Manage NuGet Packages** UI, check the **Include prerelease** box: - - ![The Include prerelease checkbox in Visual Studio](media/Prerelease_02-CheckPrerelease.png) - - Setting or clearing this box refreshes the Package Manager UI and the list of available versions you can install. - -- **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](../tools/powershell-reference.md). - -- **NuGet CLI**: Use the `-prerelease` switch with the `install`, `update`, `delete`, and `mirror` commands. Refer to the [NuGet CLI reference](../tools/nuget-exe-cli-reference.md) - - - - -### Native C++ packages - -NuGet 2.5+ 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. - -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. - -For information on creating native packages, see [Native packages](../create-packages/native-packages.md). - - -## Evaluating packages - -The best way to evaluate the usefulness of a package is, of course, to download it and try it out. After all, every highly popular package got started with only a few developers using it, and you might be one of the early adopters! - -At the same time, using a NuGet package means taking a dependency on it, so you'll want to make sure it's robust and reliable. Because installing and directly testing a package is very time-consuming, you can also learn a lot about a package's quality by using the information on a package's listing page: - -- *Downloads statistics*: a the package page you'll see 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. - - ![Download statistics on a package's listing page](media/Finding-03-Downloads.png) - -- *Version history*: on the package page, look at the date of the most recent update, and scroll down to see 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. - - ![Version history on a package's listing page](media/Finding-04-VersionHistory.png) - -- *Recent installs*: on the package page, select **View full stats** on the right side. This shows you the package installs over the last six weeks. A package that other developers are actively using is typically a better choice than one that's not. -- *Support*: on the package page, select **Project Site** (if available) to see what support options are available. A project with a dedicated site is generally better supported. -- *Developer history*: on the package page, select the listed **Owners** to see what other packages they've published. Those with multiple packages are more likely to continue supporting their work in the future. -- *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. -- *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 on the listing page. Chances are, they'll be happy to work with you to serve your needs! - -> [!Note] -> Always be mindful of a package's license terms, which you can see by selecting **License** on a package's listing page on nuget.org. - -> [!Note] -> Every package that's uploaded to nuget.org is scanned for viruses, and nuget.org periodically re-scans all packages. - -## Search Syntax - -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. - -- **Keywords**: Search looks for relevant packages that contain all the provided keywords. Example: - - modern UI javascript - -- **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: - - 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 diff --git a/docs/Consume-Packages/Managing-the-NuGet-Cache.md b/docs/Consume-Packages/Managing-the-NuGet-Cache.md deleted file mode 100644 index 2b5437b07..000000000 --- a/docs/Consume-Packages/Managing-the-NuGet-Cache.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -# required metadata - -title: How to manage package caching in NuGet | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 7/26/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 3932217d-780d-4bd1-ad15-767acd3e8870 - -# optional metadata - -description: How to manage the different NuGet package caches that exist on a machine, which are used when installing or restoring packages. -keywords: NuGet package cache, package caching, NuGet caches, managing caches, local NuGet cache, global NuGet cache, NuGet locals command, clearing a cache -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Managing the NuGet cache - -NuGet manages several local caches to avoid downloading packages that are already on the computer, and to provide offline support. NuGet 2.8+ automatically falls back to the cache when installing or reinstalling packages without a network connection. - -Cache locations are available using the [locals command](../tools/cli-ref-locals.md): - -``` -nuget locals all -list -``` - -Typical output is as follows: - - http-cache: C:\Users\user\AppData\Local\NuGet\v3-cache #NuGet 3.x+ cache - packages-cache: C:\Users\user\AppData\Local\NuGet\Cache #NuGet 2.x cache - global-packages: C:\Users\user\.nuget\packages\ #Global packages folder - temp: C:\Users\user\AppData\Local\Temp\NuGetScratch #Temp folder - -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: - -``` -nuget locals http-cache -clear #Clear the 3.x+ cache -nuget locals packages-cache -clear #Clear the 2.x cache -nuget locals global-packages -clear #Clear the global packages folder -nuget locals temp -clear #Clear the temporary cache -nuget locals all -clear #Clear all caches -``` - -Note that managing the cache is presently supported only from the NuGet command line, and not within Visual Studio or through the Package Manager Console. Also, managing the 2.x cache is not supported in NuGet 3.6 and later. - -The following errors can occur when using `nuget locals`: - -* **Clearing local resources failed: Unable to delete one or more files** -* **The directory is not empty** - -These indicate that you either do not have permission to delete files in the cache, or that one or more files in the cache are in use by another process, which must be closed before the those files can be removed. diff --git a/docs/Consume-Packages/Overview-and-Workflow.md b/docs/Consume-Packages/Overview-and-Workflow.md deleted file mode 100644 index e0026dbc4..000000000 --- a/docs/Consume-Packages/Overview-and-Workflow.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -# required metadata - -title: Overview and workflow of using NuGet packages | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 6/6/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 3c60f920-457d-4f43-9efe-210c514e5242 - -# optional metadata - -description: An overview of the process of consuming NuGet packages in a project, with links to other specific parts of the process. -keywords: NuGet package consumption, NuGet consumption overview, NuGet consumption workflow, package consumption workflow, package consumption overview -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Package consumption workflow - -Between nuget.org and private package galleries that your organization might establish, you can find tens of thousands of highly useful packages to use in your apps and services. But regardless of the source, consuming a package follows the same general workflow as shown below. For details, see [Finding and Choosing Packages](../consume-packages/finding-and-choosing-packages.md) and the [Use a Package quickstart](../quickstart/use-a-package.md). - -![Flow of going to a package source, finding a package, installing it in a project, then adding a using statement and calls to the package API](media/Overview-01-GeneralFlow.png) - -\* _Except with `nuget install` from the command-line, in which case it's necessary to edit the configuration files by hand. See the [install command reference](../tools/cli-ref-install.md)._ - -NuGet remembers the identity and version number of each installed package, recording it in either `packages.config`, the project file, or a `project.json` file in your project root, depending on project type and your version of NuGet. With NuGet 4.0+, [storing dependencies in the project file](../consume-packages/package-references-in-project-files.md) is the default (except for UWP projects targeting Windows 10 RS1). In any case, you can look in the appropriate file at any time to see the full list of dependencies for your project. - -> [!Tip] -> It's prudent to always check the license for each package you intend to use in your software. On nuget.org, you'll find a **License** link on the left side of each package's description page. - -When installing packages, NuGet typically checks if the package is already available from its cache. You can manually clear this cache from the command line, as described on [Managing the NuGet cache](../consume-packages/managing-the-nuget-cache.md). - -NuGet also makes sure that the target frameworks supported by the package are compatible with your project. If the package does not contain compatible assemblies, NuGet will give you an error message. See [Resolving incompatible package errors](dependency-resolution.md#resolving-incompatible-package-errors). - -When adding project code to a source repository, you typically don't include NuGet packages. Those who later clone the repository, which includes build agents on systems like Visual Studio Team Services, must restore the necessary packages prior to running a build: - -![Flow of restoring NuGet packages by cloning a repository and using either a restore command](media/Overview-02-RestoreFlow.png) - -[Package Restore](../consume-packages/package-restore.md) uses the information in the project file, `packages.config`, `project.json` to reinstall all dependencies. Note that there are differences in the process involved, as described in [Dependency Resolution](../consume-packages/dependency-resolution.md). - -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 `reinstall` command via the NuGet command line 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` configuration 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). - -Enjoy your productive coding with NuGet packages! diff --git a/docs/Consume-Packages/Package-References-in-Project-Files.md b/docs/Consume-Packages/Package-References-in-Project-Files.md deleted file mode 100644 index 7d21d775b..000000000 --- a/docs/Consume-Packages/Package-References-in-Project-Files.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -# required metadata - -title: NuGet PackageReference in Visual Studio Project Files | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 7/17/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 5a554e9d-1266-48c2-92e8-6dd00b1d6810 - -# optional metadata - -description: Details on NuGet PackageReference in project files as supported by NuGet 4.0+ and VS2017 -keywords: NuGet package dependencies, package references, project files, PackageReference, packages.config, project.json, VS2017, Visual Studio 2017, NuGet 4 -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- -# Package references (PackageReference) in project files - -Package references, using the `PackageReference` node, allow you to manage NuGet dependencies directly within project files, rather than needing a separate `packages.config` or `project.json` file. This method doesn't affect other aspects of NuGet; for example, settings in `NuGet.Config` files (including package sources) are still applied as explained in [Configuring NuGet Behavior](Configuring-NuGet-Behavior.md). - -> [!Important] -> At present, package references are supported in Visual Studio 2017 only, for .NET Core projects, .NET Standard projects, and UWP projects targeting Windows 10 Build 15063 (Creators Update). - -The `PackageReference` approach allows you to 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. In terms of behavior and [dependency resolution](Dependency-Resolution.md), it is the same as using `project.json`. - -For more details on the integration of MSBuild with package references in project files, see [NuGet pack and restore as MSBuild targets](../schema/msbuild-targets.md). - -## Adding a PackageReference - -Add a dependency in your project file using the following syntax: - -```xml - - - - - -``` - -## Controlling dependency version - -The convention for specifying the version of a package is the same as when using `packages.config` or `project.json`: - -```xml - - - - - -``` - -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](../reference/package-versioning.md#version-ranges-and-wildcards). - -## Floating Versions - -[Floating versions](../consume-packages/dependency-resolution.md#floating-versions) are supported with `PackageReference`: - -```xml - - - - - - -``` - -## Controlling dependency assets - -You might be using a dependency purely as a development harness and might not want to expose that to projects that will consume your package. In this scenario, you can use the `PrivateAssets` metadata to control this behavior. - -```xml - - - - - all - - - - -``` - -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 | -| 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: - -| Value | Description | -| --- | --- -| compile | Contents of the `lib` folder | -| runtime | Contents of the `runtime` folder | -| contentFiles | Contents of the `contentfiles` folder | -| build | Props and targets in the `build` folder | -| analyzers | .NET analyzers | -| native | Contents of the `native` folder | -| 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 - contentFiles - contentFiles;analyzers - - - - -``` - -Note that because `build` is not included with `PrivateAssets`, targets and props *will* flow to the parent project. Consider, for example, that the reference above is used in a project that builds a NuGet package called AppLogger. AppLogger can consume the targets and props from `Contoso.Utility.UsefulStuff`, as can projects that consume AppLogger. - -## 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. - -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: - -```xml - - - - - -``` - -A package built using this project will show that Newtonsoft.json is included as a dependency only for a `net452` target: - -![The result of applying a Condition on PackageReference with VS2017](media/PackageReference-Condition.png) - -Conditions can also be applied at the `ItemGroup` level and will apply to all children `PackageReference` elements: - -```xml - - - - - - -``` diff --git a/docs/Consume-Packages/Package-Restore.md b/docs/Consume-Packages/Package-Restore.md deleted file mode 100644 index c60fe2c2c..000000000 --- a/docs/Consume-Packages/Package-Restore.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -# required metadata - -title: NuGet Package Restore | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 10/24/2017 -ms.topic: article -ms.prod: nuget -ms.technology: null -ms.assetid: a7bf21da-86ae-4c2d-8750-04ff53f41967 - -# optional metadata - -description: A description of how NuGet restores packages upon which a project depends, including how to disable restore and constrain versions. -keywords: NuGet package restore, NuGet package installation, installing package, restoring packages, dependency versions, disabling automatic restore, constraining package versions -ms.reviewer: -- karann-msft -- unniravindranathan - ---- - -# Package Restore - -To promote a cleaner development environment and to reduce repository size, NuGet **Package Restore** installs all referenced packages before a project is built. This widely-used feature ensures that all dependencies are available in a project without requiring those packages to be stored in source control (see [Packages and Source Control](../consume-packages/packages-and-source-control.md) on how to configure your repository to exclude package binaries). - -In this topic: -- [Quick guide to package restore](#quick-guide-to-package-restore) -- [Package restore overview](#package-restore-overview) -- [Enabling and disabling package restore](#enabling-and-disabling-package-restore) -- [Constraining package versions with restore](#constraining-package-versions-with-restore) -- [Command-line restore](#command-line-restore), for all versions of NuGet -- [Automatic restore in Visual Studio](#automatic-restore-in-visual-studio), for NuGet 2.7 and later. -- [MSBuild-integrated restore in Visual Studio](#msbuild-integrated-restore), for NuGet 2.6 and earlier. -- [Package restore with Team Foundation Build](#package-restore-with-team-foundation-build) - -Restore behavior does vary by version; to check your NuGet version, simply run `nuget.exe` on the command line and look at the first line of output. - -For additional details on package restore on build servers, see [Package restore with TFBuild](../consume-packages/team-foundation-build.md). - -> [!Note] -> Projects configured for package restore also work with xbuild on Mono. - -## Quick guide to package restore - -[!INCLUDE[package-restore](../includes/package-restore.md)] - -> [!Note] -> 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," turn on automatic restore by following the instructions under [Enabling and disabling package restore](#enabling-and-disabling-package-restore). - -## Package restore overview - -First, package references are maintained in one of the following package management formats, depending on project type and NuGet version. (Note that NuGet 4 and MSBuild 15.1 are installed with Visual Studio 2017.) - -| Method | NuGet Version | Description | -| --- | --- | --- | -| `packages.config` | 2.x+ | Lists the complete deep set of dependencies. Packages added to `packages.config` must also be added to the project file, and Targets and Props must also be added to the project file. This is the baseline method for all versions of NuGet, but has slower performance compared with the other options. (See [packages.config schema](../schema/packages-config.md).) | -| `project.json` | 3.x+ | Used only by default with UWP projects, but projects can be converted from `packages.config`. `project.json` lists only top-level dependencies. References, Targets, and Props are added dynamically to the project during build, resulting in better performance compared with `packages.config`. (See [project.json schema](../schema/project-json.md).)| -| PackageReference | 4.x+ | Lists dependencies directly in the project file in the `` node, alongside `` and ``. Works similarly to `project.json`; see [Package references in project files](../Consume-Packages/Package-References-in-Project-Files.md). | - -Second, you start a restore using the reference list in a variety of ways: - -From the command line or [Package Manager Console](../tools/Package-Manager-Console.md): - -| Command | Applicable scenarios | -| --- | --- | -| `nuget restore` | All versions of NuGet and all reference types. See [Command-line restore](#command-line-restore) below. | -| `dotnet restore` | Same as `nuget restore` for .NET Core projects. See [dotnet restore](https://docs.microsoft.com/dotnet/articles/core/tools/dotnet-restore). | -| `msbuild /t:restore` | Nuget 4.x+ and MSBuild 15.1+ with [package references in project files](../Consume-Packages/Package-References-in-Project-Files.md) only. `nuget restore` and `dotnet restore` both use this command for applicable projects. See [NuGet pack and restore as MSBuild targets- restore target](../schema/msbuild-targets.md#restore-target).| - -Visual Studio itself also restores packages at different times: - -| Type | When restore happens | -| --- | --- | -| Template restore | During creation of a new project, as some templates depend on external packages. | -| Build restore | As the first step of a build. | -| Solution restore | When user right-clicks a solution and selects **Restore NuGet Packages**. | -| Restore on project change | *(NuGet 4.x only)* When a .NET Core SDK-based project is used, including when project state changes. | - -## Enabling and disabling package restore - -Package restore is primarily enabled through **Tools > Options > NuGet Package Manager** in Visual Studio: - -![Controlling package restore behaviors through NuGet Package Manager options](media/Restore-01-AutoRestoreOptions.png) - -- **Allow NuGet to download missing packages**: controls all forms of package restore by changing the `packageRestore/enabled` setting in the `%AppData%\NuGet\NuGet.Config` file as shown below. - - ```xml - - - - - - - ``` -
- > [!Note] - > The `packageRestore/enabled` setting can be overridden globally by setting an environment variable called **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 for NuGet 2.7 and later by changing the `packageRestore/automatic` setting in the `%AppData%\NuGet\NuGet.Config` file as shown below. - - ```xml - ... - - - - - - - ``` - -For reference, see the [NuGet config file - packageRestore section](../Schema/nuget-config-file.md#packagerestore-section). - -In some cases, a developer or company might want to enable or disable package restore on a machine by default for all users. This can be done by adding the same settings above to the global NuGet configuration file located in `%ProgramData%\NuGet\Config[\{IDE}[\{Version}[\{SKU}]]]`. Individual users can then selectively enable restore as needed on a project level. See [Configuring NuGet Behavior](../consume-packages/configuring-nuget-behavior.md#how-settings-are-applied) for exact details on how NuGet prioritizes multiple config files. - -## Constraining package versions with restore - -When NuGet restores packages through any method, it will honor any constraints specified in `packages.config`, `project.json`, or the project file: - -- `packages.config`: Specify a version range in the `allowedVersion` property of the dependency. See [Reinstalling and Updating Packages](../consume-packages/reinstalling-and-updating-packages.md#constraining-upgrade-versions). For example: - - ```xml - - ``` - -- `project.json`: Specify a version range directly with the dependency's version number. For example: - - ```json - "Newtonsoft.json": "[6, 7)" - ``` - -- Package references in project files: Specify a version range directly with the dependency's version number. For example: - - ```xml - - ``` - -In all cases, use the notation described in [Package versioning](../reference/package-versioning.md). - -## Command-line restore - -For NuGet 2.7 and above, use the [Restore](../tools/cli-ref-restore.md) command to restore all packages in a solution (whether it uses `packages.config`, `project.json`, or package references in project files). For a given project folder such as `c:\proj\app`, the common variations below each restore the packages: - -``` -c:\proj\app\> nuget restore -c:\proj\app\> nuget.exe restore app.sln -c:\proj\> nuget restore app -``` - -For NuGet 4.0+ and MSBuild 15.1+, you can also use `MSBuild /t:restore` as described on [NuGet pack and restore as MSBuild targets](../schema/msbuild-targets.md). - -## Build-time restore in Visual Studio - -Visual Studio automatically restores missing packages by default at the beginning of a build. This behavior can be changed by clearing **Tools > Options > NuGet Package Manager > General > Automatically check for missing packages during build in Visual Studio**. - -When enabled, automatic restore works as follows: - -1. When a build begins, Visual Studio instructs NuGet to restore packages. -1. NuGet recursively looks for all `packages.config` files in the solution, looks for `project.json`, or looks in the project file. -1. For each packages listed in the reference files, NuGet checks if it already exists in the solution (the `packages` folder, `project.lock.json`, or `project.assets.json` depending on whether the project is using `packages.config`, `project.json`, or package references in project files). -1. If the package is not found, NuGet attempts to retrieve the package from its cache first (see [Managing the NuGet cache](../consume-packages/managing-the-nuget-cache.md). If the package is not in the cache, NuGet attempts to download the package from the enabled sources as listed in **Tools > Options > NuGet Package Manager > Package Sources**, in the order that the sources appear. In this case, NuGet does not indicate a failure to find the package until all the sources have been checked, at which time it reports the failure only for the last source in the list. By implication such an error also means that the package wasn't present on any of the other sources either, even though errors were not shown for those sources individually. -1. If the download is successful, NuGet caches the package and installs it into the solution (again, into either the `packages` folder, `project.lock.json`, or `project.assets.json`); otherwise NuGet fails and the build fails. - -During this process, you see a progress dialog with the option to cancel package restore. - -## Package Restore with Team Foundation Build - -Package restore is commonly used when building projects on build servers, as with Team Foundation Server (TFS) and Visual Studio Team Services (as well as other build systems, which are not covered here). - -### Visual Studio Team Services - -When creating a build definition on Team Services, simply include the Restore NuGet Packages task in the definition before any build task. This task is included by default in a number of build templates. - -![NuGet package restore task in a Visual Studio Team Service build definition](media/Restore-02-VSTSBuild.png) - -### Team Foundation Server - -With TFS 2013 and later, packages are automatically restored by default during build, provided that you're using a Team Build Template for Team Foundation Server 2013 or later. - -If you're using a previous version of build templates (such as in a project that's been migrated from earlier versions of TFS), you'll need to also migrate those build templates to TFS 2013. This essentially means recreating the custom parts of the Build Templates using the appropriate template for your source control (TFVC or Git). - -For earlier version of TFS, you can simply include a build step to invoke [command-line restore](#command-line-restore) as described earlier. - -For more details see then [Walkthrough of Package Restore with Team Foundation Build](../consume-packages/team-foundation-build.md). diff --git a/docs/Consume-Packages/Package-restore-troubleshooting.md b/docs/Consume-Packages/Package-restore-troubleshooting.md deleted file mode 100644 index afd9fd34a..000000000 --- a/docs/Consume-Packages/Package-restore-troubleshooting.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -# required metadata - -title: Troubleshooting NuGet Package Restore in Visual STudio | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 10/24/2017 -ms.topic: article -ms.prod: nuget -ms.technology: null -ms.assetid: b70326a0-5bfc-4b7c-881d-7a7d5ebeeed5 - -# optional metadata - -description: A description of common NuGet restore errors in Visual Studio and how to troubleshoot them. -keywords: NuGet package restore, restoring packages, troubleshooting, troubleshoot -ms.reviewer: -- karann-msft -- unniravindranathan - ---- - -# Troubleshooting package restore errors in Visual Studio - -> [!Note] -> This page focuses on common errors when restoring packages in Visual Studio and steps to resolve them. For how-to restore packages, see [Package restore](../Consume-Packages/Package-Restore.md#enabling-and-disabling-package-restore). - -By default, building a project in Visual Studio automatically restores NuGet packages referenced in the project. However, builds will fail if package restore is disabled in the **Tools > Options > NuGet Package Manager > Package Restore** settings and the necessary packages are not available on your computer. In these cases you may see the following errors: - -``` -This project references NuGet package(s) that are missing on this computer. -Use NuGet Package Restore to download them. The missing file is {name}. -``` - -``` -One or more NuGet packages need to be restored but couldn't be because consent has -not been granted. To give consent, open the Visual Studio Options dialog, click on -the NuGet Package Manager node and check 'Allow NuGet to download missing packages -during build.' You can also give consent by setting the environment variable -'EnableNuGetPackageRestore' to 'true'. Missing packages: {name} -``` - -To enable package restore, open **Tools > Options > NuGet Package Manager** and select the options for **Allow NuGet to download missing packages** and **Automatically check for missing packages during build in Visual Studio**: - -![enable NuGet package restore in Tool/Options](../Consume-Packages/media/restore-01-autorestoreoptions.png) - diff --git a/docs/Consume-Packages/Reinstalling-and-Updating-Packages.md b/docs/Consume-Packages/Reinstalling-and-Updating-Packages.md deleted file mode 100644 index 56abac99a..000000000 --- a/docs/Consume-Packages/Reinstalling-and-Updating-Packages.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -# required metadata - -title: Reinstalling and Updating NuGet Packages | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 7/17/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 2785879b-97f0-4a85-b3cc-bf4eaa5c39bf - -# optional metadata - -description: Details on when it's necessary to reinstall and update packages, as with broken package references in Visual Studio. -keywords: NuGet package installation, NuGet package reinstallation, NuGet package restore, updating package, restoring packages, fixing broken references -ms.reviewer: -- karann-msft -- unniravindranathan - ---- - -# How to reinstall and update packages - -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. - -Updating and reinstalling packages is accomplished as follows: - -| 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. | - -In this topic: -- [When to Reinstall a Package](#when-to-reinstall-a-package) -- [Constraining upgrade versions](#constraining-upgrade-versions) - -## When to Reinstall a Package - -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. 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 2.7 and later 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. - -## Constraining upgrade versions - -By default, reinstalling or updating a package *always* installs the latest version available from the package source. - -In projects using the `packages.config` reference 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 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)`: - -```xml - - - - - - -``` - -In all cases, use the notation described in [Package versioning](../reference/package-versioning.md#version-ranges-and-wildcards). - -## Using Update-Package - -Being mindful of the [Considerations](#considerations) described below, you can easily reinstall any package using the [Update-Package command](../Tools/ps-ref-update-package.md) in the Visual Studio Package Manager Console (**Tools** > **NuGet Package Manager** > **Package Manager Console**): - -```ps -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. - -The same command without `-reinstall` updates a package to a newer version, if applicable: - -```ps -Update-Package -``` - -By default, `Update-Package` affects all packages 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: - -```ps -# Reinstall the package in just MyProject -Update-Package -ProjectName MyProject -reinstall -``` -To *update* all packages in a project (or reinstall using `-reinstall`), use `-ProjectName` without specifying any particular package: - -```ps -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: - -```ps -# Updates all packages in all projects in the solution -Update-Package -``` - -Updating packages in a project or solution using `project.json` or [package references in project files](../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). - -For full details on the command, see the [Update-Package](../Tools/ps-ref-update-package.md) reference. - -### Considerations - -The following may be affected when reinstalling a package: - -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. - -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. - -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 - -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. - diff --git a/docs/Consume-Packages/media/Finding-01-Popularity.png b/docs/Consume-Packages/media/Finding-01-Popularity.png deleted file mode 100644 index a065b7308..000000000 Binary files a/docs/Consume-Packages/media/Finding-01-Popularity.png and /dev/null differ diff --git a/docs/Consume-Packages/media/Finding-02-SearchResults.png b/docs/Consume-Packages/media/Finding-02-SearchResults.png deleted file mode 100644 index 49cd15f59..000000000 Binary files a/docs/Consume-Packages/media/Finding-02-SearchResults.png and /dev/null differ diff --git a/docs/Consume-Packages/media/Finding-03-Downloads.png b/docs/Consume-Packages/media/Finding-03-Downloads.png deleted file mode 100644 index bcf60cb9e..000000000 Binary files a/docs/Consume-Packages/media/Finding-03-Downloads.png and /dev/null differ diff --git a/docs/Consume-Packages/media/Finding-04-VersionHistory.png b/docs/Consume-Packages/media/Finding-04-VersionHistory.png deleted file mode 100644 index e221ef340..000000000 Binary files a/docs/Consume-Packages/media/Finding-04-VersionHistory.png and /dev/null 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/Overview-01-GeneralFlow.png b/docs/Consume-Packages/media/Overview-01-GeneralFlow.png deleted file mode 100644 index 1b69a9f48..000000000 Binary files a/docs/Consume-Packages/media/Overview-01-GeneralFlow.png and /dev/null differ diff --git a/docs/Consume-Packages/media/Overview-02-RestoreFlow.png b/docs/Consume-Packages/media/Overview-02-RestoreFlow.png deleted file mode 100644 index 379c2c6c5..000000000 Binary files a/docs/Consume-Packages/media/Overview-02-RestoreFlow.png and /dev/null 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 d542242a1..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/projectJson-dependency-1.png b/docs/Consume-Packages/media/projectJson-dependency-1.png deleted file mode 100644 index 50f1c7b77..000000000 Binary files a/docs/Consume-Packages/media/projectJson-dependency-1.png and /dev/null differ diff --git a/docs/Consume-Packages/media/projectJson-dependency-2.png b/docs/Consume-Packages/media/projectJson-dependency-2.png deleted file mode 100644 index badc8fef0..000000000 Binary files a/docs/Consume-Packages/media/projectJson-dependency-2.png and /dev/null differ diff --git a/docs/Consume-Packages/media/projectJson-dependency-3.png b/docs/Consume-Packages/media/projectJson-dependency-3.png deleted file mode 100644 index 8f5c85f67..000000000 Binary files a/docs/Consume-Packages/media/projectJson-dependency-3.png and /dev/null differ diff --git a/docs/Consume-Packages/media/projectJson-dependency-4.png b/docs/Consume-Packages/media/projectJson-dependency-4.png deleted file mode 100644 index d17973c52..000000000 Binary files a/docs/Consume-Packages/media/projectJson-dependency-4.png and /dev/null differ diff --git a/docs/Consume-Packages/media/projectJson-dependency-5.png b/docs/Consume-Packages/media/projectJson-dependency-5.png deleted file mode 100644 index 5e0df0b07..000000000 Binary files a/docs/Consume-Packages/media/projectJson-dependency-5.png and /dev/null differ diff --git a/docs/Consume-Packages/media/projectJson-dependency-6.png b/docs/Consume-Packages/media/projectJson-dependency-6.png deleted file mode 100644 index 5925eebd0..000000000 Binary files a/docs/Consume-Packages/media/projectJson-dependency-6.png and /dev/null differ diff --git a/docs/Consume-Packages/media/projectJson-dependency-7.png b/docs/Consume-Packages/media/projectJson-dependency-7.png deleted file mode 100644 index 7158cd1a6..000000000 Binary files a/docs/Consume-Packages/media/projectJson-dependency-7.png and /dev/null differ diff --git a/docs/Consume-Packages/media/projectJson-dependency-8.png b/docs/Consume-Packages/media/projectJson-dependency-8.png deleted file mode 100644 index 980604f43..000000000 Binary files a/docs/Consume-Packages/media/projectJson-dependency-8.png and /dev/null differ diff --git a/docs/Create-Packages/Dependency-Versions.md b/docs/Create-Packages/Dependency-Versions.md deleted file mode 100644 index 8817ed7c9..000000000 --- a/docs/Create-Packages/Dependency-Versions.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_url: /nuget/reference/package-versioning ---- \ No newline at end of file diff --git a/docs/Create-Packages/Overview-and-Workflow.md b/docs/Create-Packages/Overview-and-Workflow.md deleted file mode 100644 index d26cb9421..000000000 --- a/docs/Create-Packages/Overview-and-Workflow.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -# required metadata - -title: Overview and workflow of creating NuGet packages | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 7/26/2017 -ms.topic: article -ms.prod: nuget -ms.technology: null -ms.assetid: feb7918c-4709-48a4-a106-8d65c41014dc - -# optional metadata - -description: An overview of the process of creating and publishing a NuGet package, with links to other specific parts of the process. -keywords: NuGet package creation, NuGet creation overview, NuGet creation workflow, package creation workflow, package creation overview. -ms.reviewer: -- karann-msft -- unniravindranathan - ---- -# Package creation workflow - -Creating a package starts with the compiled code (typically .NET assemblies) that you want to package and share with others, either through the public nuget.org gallery or a private gallery within your organization. The package can also include additional files such as a readme that is displayed when the package is installed, and can include transformations to certain project files. - -A package can also serve to only pull in any number of other dependencies, without containing any code of its own. Such a package is a convenient way to deliver an SDK that's composed of multiple independent packages. In other cases, a package may contain only symbol (`.pdb`) files to aid debugging. - -> [!Note] -> When you create a package for use by other developers, it's important to understand that they are taking a dependency on your work. As such, creating and publishing a package also implies a commitment to fixing bugs and making other updates, or at the very least making the package available as open source so others can help to maintain it. - -Whatever the case, creating a package begins with deciding which assemblies and other files to package. You then create a manifest file, referred to as a `.nuspec` file, to describe the package's contents along with its identifer, version number, copyright information, MSBuild props and targets, and much more. - -When you've prepared all the necessary files in the appropriate folders and have created the appropriate `.nuspec` file, you then use the `nuget pack` command (or the[MSBuild pack target](../Schema/msbuild-targets.md)) to put everything together into a `.nupkg` file. You're then ready to deploy the package to whatever host makes it available to other developers. - -> [!Tip] -> A NuGet package with the `.nupkg` extension is simple a ZIP file. To easily examine any package's contents, change the extension to `.zip` and expand its contents as usual. Just be sure to change the extension back to `.nupkg` before attempting to upload it to a host. - -To learn and understand the creation process, start with [Creating a package](../create-packages/creating-a-package.md) which guides you through the core processes common to all packages. - -From there, you can consider a number of other options for your package: - -- [Supporting Multiple Target Frameworks](../create-packages/supporting-multiple-target-frameworks.md) describes how to create a package with multiple variants for different .NET Frameworks. -- [Creating Localized Packages](../create-packages/creating-localized-packages.md) describes how to structure a package with multiple language resources and how to use separate localized satellite packages. -- [Pre-release Packages](../create-packages/prerelease-packages.md) demonstrates how to release alpha, beta, and rc packages to those customers who are interested. -- [Source and Config File Transformations](../create-packages/source-and-config-file-transformations.md) describes how you can do both one-way token replacements in files that are added to a project, and modify `web.config` and `app.config` with settings that are also backed out when the package is uninstalled. -- [Symbol Packages](../create-packages/symbol-packages.md) offers guidance for supplying symbols for your library that allow consumers to step into your code while debugging. -- [Package versioning](../reference/package-versioning.md) discusses how to identify the exact versions that you allow for your dependencies (other packages that you consume from your package). -- [Native Packages](../create-packages/native-packages.md) describes the process for creating a package for C++ consumers. - -When you're then ready to publish a package to nuget.org, follow the simple process in [Publish a package](../create-packages/publish-a-package.md). - -If you want to use a private feed instead of nuget.org, see the [Hosting Packages Overview](../hosting-packages/overview.md) diff --git a/docs/Create-Packages/Prerelease-Packages.md b/docs/Create-Packages/Prerelease-Packages.md deleted file mode 100644 index 89044f221..000000000 --- a/docs/Create-Packages/Prerelease-Packages.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -# required metadata - -title: Pre-release versions in NuGet packages | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 8/14/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: df6a366a-22c1-47bb-8017-18231311ce88 - -# optional metadata - -description: Guidance for building pre-release packages -keywords: versioning, NuGet package versioning, NuGet prerelease versions, NuGet prerelease packages, preview package versions, RC package versions, Beta package versions, NuGet semantic versioning -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Building pre-release packages - -Whenever you release an updated package with a new version number, NuGet considers that one as the "latest stable release" as shown, for example in the Package Manager UI within Visual Studio: - -![Package Manager UI showing the latest stable release](media/Prerelease_01-LatestStable.png) - -A stable release is one that's considered reliable enough to be used in production. The latest stable release is also the one that will be installed as a package update or during package restore (subject to constraints as described in [Reinstalling and updating packages](../consume-packages/reinstalling-and-updating-packages.md)). - -To support the software release lifecycle, NuGet 1.6 and later allows for the distribution of pre-release packages, where the version number includes a semantic versioning suffix such as `-alpha`, `-beta`, or `-rc`. For more information, see [Package versioning](../reference/package-versioning.md#pre-release-versions). - -You can specify such versions in two ways: - -- `.nuspec` file: include the semantic version suffix in the `version` element: - - ```xml - 1.0.1-alpha - ``` - -- Assembly attributes: when building a package from a Visual Studio project (`.csproj` or `.vbproj`), use the `AssemblyInformationalVersionAttribute` to specify the version: - - ```cs - [assembly: AssemblyInformationalVersion("1.0.1-beta")] - ``` - - NuGet picks up this value instead of the one specified in the `AssemblyVersion` attribute, which does not support semantic versioning. - -> [!Note] -> A stable package release cannot have a pre-release dependency. This avoids accidentally installing potentially unstable releases. - -When you’re ready to release a stable version, just remove the suffix and the package takes precedence over any pre-release versions. Again, see [Package versioning](../reference/package-versioning.md#pre-release-versions). - - -## Installing and updating pre-release packages - -By default, NuGet does not include pre-release versions when working with packages, but you can change this behavior as follows: - -- **Package Manager UI in Visual Studio**: In the **Manage NuGet Packages** UI, check the **Include prerelease** box: - - ![The Include prerelease checkbox in Visual Studio](media/Prerelease_02-CheckPrerelease.png) - - Setting or clearing this box will refresh the Package Manager UI and the list of available versions you can install. - -- **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](../tools/powershell-reference.md). - -- **NuGet CLI**: Use the `-prerelease` switch with the `install`, `update`, `delete`, and `mirror` commands. Refer to the [NuGet CLI reference](../tools/nuget-exe-cli-reference.md) - - -## 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 they 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 does not support [SemVer-compatible (v2.0.0)](http://semver.org/spec/v2.0.0.html) prerelease numbers with dot notation, as in `1.0.1-build.23`. You can use a form like `1.0.1-build23` but this is 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-beta12 -1.0.1-beta05 -1.0.1-beta -1.0.1-alpha2 -1.0.1-alpha -``` - -As shown, the version without any suffix will always take precedence over pre-release versions. Note also that 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. diff --git a/docs/Create-Packages/Publish-a-package.md b/docs/Create-Packages/Publish-a-package.md deleted file mode 100644 index c9c589d1a..000000000 --- a/docs/Create-Packages/Publish-a-package.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -# required metadata - -title: How to Publish a NuGet Package | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 10/5/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 2342aabd-983e-4db1-9230-57c84fa36969 - -# optional metadata - -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. -keywords: NuGet package publishing, publish NuGet package, NuGet package ownership, publish to nuget.org, private NuGet feeds -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- -# Publishing packages - -Once you have [created a package](../create-packages/creating-a-package.md) with `nuget pack`, it's a simple process to make it available to other developers, either publicly or privately: - -- Public packages are made available to all developers globally through [nuget.org](https://www.nuget.org/packages/manage/upload) as described in this topic. -- Private packages are available to only a team or organization, by hosting them either a file share, a private NuGet server, [Visual Studio Team Services Package Management](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 topic covers publishing to nuget.org; for publishing to Visual Studio Team Services, see [Package Management](https://www.visualstudio.com/docs/package/nuget/publish). - -## Publish to nuget.org - -For nuget.org, you must first [register for a free account](https://www.nuget.org/users/account/LogOn?returnUrl=%2F) or sign in if already registered: - -![NuGet registration and sign in location](media/publish_NuGetSignIn.png) - -Next, you can either upload the package through the nuget.org web portal, push to nuget.org from the command line, or publish as part of a CI/CD process through Visual Studio Team Services, as described in the following sections. - -### Web portal: use the Upload Package tab on nuget.org: - -![Upload a package with the NuGet Package Manager](media/publish_UploadYourPackage.PNG) - -### Command line: -> [!Important] -> 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). - -1. Click on your user name to navigate to your account settings. -2. Under **API Key**, click **copy to clipboard** to retrieve the access key you'll need in the CLI: - - ![Copying an API Key from account settings](media/publish_APIKey.png) - -3. At a command prompt, run the following command: - - ``` - nuget setApiKey Your-API-Key - ``` - - This stores your API key on the machine so that you need not do this step again on the same machine. - -4. Push your package to NuGet Gallery using the command: - - ``` - nuget push YourPackage.nupkg -Source https://www.nuget.org/api/v2/package - ``` - -5. Before being made public, 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. - -6. In your account on nuget.org, click **Manage my packages** to see the one that you just published; you'll 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 which time you'll see the following message on your package page: - - ![Message indicating a package is not yet indexed](media/publish_NotYetIndexed.png) - -### Visual Studio Team Services (CI/CD) - -If you push packages to nuget.org using Visual Studio Team 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). - -## Managing package owners on nuget.org - -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`. - -All package owners have full permissions for the package, including adding and removing other owners, and publishing updates. - -To change ownership of a package, do the following: - -1. Sign in to nuget.org with the account that is the current owner of the package. -1. Click on your username, then on **Manage my packages**, then on the package you want to manage. -1. Click the **Manage owners** link on the left side. - -From here you have several options: - -1. To add an owner, enter their NuGet account name and click **Add**. This 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 **Manage owners** page indicates "pending approval" for that person). -1. To remove an owner, select their name on the **Manage owners** and click **Remove**. -1. To transfer ownership (as when ownership changes or a package was published under the wrong account), simply add the new owner, and once they've confirmed ownership they can remove you 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. - -### Recovering package ownership - -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. - -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. diff --git a/docs/Create-Packages/Supporting-Multiple-Target-Frameworks.md b/docs/Create-Packages/Supporting-Multiple-Target-Frameworks.md deleted file mode 100644 index 720c04949..000000000 --- a/docs/Create-Packages/Supporting-Multiple-Target-Frameworks.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -# required metadata - -title: Multi-targeting for NuGet Packages | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 9/27/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 2646ffcd-83ae-4086-8915-a7fba3f53e45 - -# optional metadata - -description: Description of the various methods to target multiple .NET Framework versions from within a single NuGet package. -keywords: NuGet package targeting, .NET Framework versions, NuGet and .NET, targeting multiple frameworks, NuGet package creation -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- -# Supporting multiple .NET framework versions - -*For .NET Core projects using NuGet 4.0+, see [NuGet pack and restore as MSBuild targets](../schema/msbuild-targets.md) for details on cross-targeting.* - -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 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). - -In this topic: - -- [Framework version folder structure](#framework-version-folder-structure) -- [Matching assembly versions and the target framework in a project](#matching-assembly-versions-and-the-target-framework-in-a-project) -- [Grouping assemblies by framework version](#grouping-assemblies-by-framework-version) -- [Determining which NuGet target to use](#determining-which-nuget-target-to-use) -- [Content files and PowerShell scripts](#content-files-and-powershell-scripts) - - -## Framework version folder structure - -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}] - -For a complete list of supported names, see the [Target Frameworks reference](../schema/target-frameworks.md#supported-frameworks). - -You should never have a version of the library that is not specific to a framework and placed directly in the root `lib` folder. (This capability was supported only with `packages.config`). Doing so would make the compatible with any target framework and allow it to be installed anywhere, likely resulting in unexpected runtime errors. Adding assemblies in the root folder (such as `lib\abc.dll`) or subfolders (such as `lib\abc\abc.dll`) has been deprecated and is ignored when using the PackagesReference format. - -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 - -To easily include all these files when building the package, use a recursive `**` wildcard in the `` section of your `.nuspec`: - -```xml - - - -``` - -### Architecture-specific folders - -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 - -See [Create UWP Packages](../Guides/Create-UWP-Packages.md) for an example of referencing these files in the `.nuspec` manifest. - - -## Matching assembly versions and the target framework in a project - -When NuGet installs a package that has multiple assembly versions, it tries to match the framework name of the assembly with the target framework of the project. - -If a match is not found, NuGet copies the assembly for the highest version that is less than or equal to the project's target framework, if available. If no compatible assembly is found, NuGet returns an appropriate error message. - -For example, consider the following folder structure in a package: - - \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. - -If the project targets .NET Framework 4.6.1, on the other hand, NuGet installs the assembly in the `net461` folder. - -If the project targets .NET framework 4.0 and earlier, NuGet throws an appropriate error message for not finding the compatible assembly. - -## Grouping assemblies by framework version - -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) - -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`. - -If you want `MyAssembly.Core.dll` to be installed for .NET Framework 4.5, place a copy in the `net45` folder. - -## Grouping assemblies by framework profile - -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} - -The supported profiles are as follows: - -- `client`: Client Profile -- `full`: Full Profile -- `wp`: Windows Phone -- `cf`: Compact Framework - -## Determining which NuGet target to use - -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) (stephenclearly.com) -- [Portable Class Library profiles](http://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 - -> [!Warning] -> Mutable content files and script execution are available with the `packages.config` format only; they are deprecated when using `project.json` and PackagesReference formats and should should not be used for any new packages. - -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 - -If a framework folder is left empty, NuGet doesn't add assembly references or content files or run the PowerShell scripts for that framework. - -> [!Note] -> Because `init.ps1` is executed at the solution level and not dependent on project, it must be placed directly under the `tools` folder. It's ignored if placed under a framework folder. diff --git a/docs/Create-Packages/Symbol-Packages.md b/docs/Create-Packages/Symbol-Packages.md deleted file mode 100644 index a467e4e9c..000000000 --- a/docs/Create-Packages/Symbol-Packages.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -# required metadata - -title: How to create NuGet symbol packages | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 9/12/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 4667a70d-5a17-4f1e-b2f2-b8d0c6af3882 - -# optional metadata - -description: How to create NuGet packages that contain only symbols to support debugging of other NuGet packages in Visual Studio. -keywords: NuGet symbol packages, NuGet package debugging, supporting NuGet debugging, package symbols, symbol package conventions -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Creating symbol packages - -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](http://www.symbolsource.org/Public). - -Package consumers can then add `http://srv.symbolsource.org/pdb/Public` 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](https://docs.microsoft.com/visualstudio/debugger/specify-symbol-dot-pdb-and-source-files-in-the-visual-studio-debugger) for details on that process. - - -## Creating a symbol package - -To create a 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). - -You can create both packages with the `-Symbols` option, either from a `.nuspec` file or a project file: - -``` -nuget pack MyPackage.nuspec -Symbols - -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 - -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. - -For example, a 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 - -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 - \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: - -```xml - - - - - - - -``` - -## Publishing a symbol package - -> [!Important] -> 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). - -1. For convenience, first save your API key with NuGet (see [publish a package](../create-packages/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. - - ``` - nuget SetApiKey Your-API-Key - ``` - -1. 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: - - ``` - nuget push MyPackage.symbols.nupkg - ``` - -1. To publish to a different symbol repository, or to push a symbol package that doesn't follow the naming convention, use the `-Source` option: - - ``` - nuget push MyPackage.symbols.nupkg -source https://nuget.smbsrc.net/ - ``` - -1. You can also push both primary and symbol packages to both repositories at the same time using the following: - - ``` - nuget push MyPackage.nupkg - ``` - -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 - - - Using SymbolSource (symbolsource.org) 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/media/publish_NotYetIndexed.png b/docs/Create-Packages/media/publish_NotYetIndexed.png deleted file mode 100644 index 9996cfefb..000000000 Binary files a/docs/Create-Packages/media/publish_NotYetIndexed.png and /dev/null differ diff --git a/docs/Create-Packages/media/publish_NuGetSignIn.PNG b/docs/Create-Packages/media/publish_NuGetSignIn.PNG deleted file mode 100644 index 59e3a7beb..000000000 Binary files a/docs/Create-Packages/media/publish_NuGetSignIn.PNG and /dev/null differ diff --git a/docs/Create-Packages/media/publish_UploadYourPackage.PNG b/docs/Create-Packages/media/publish_UploadYourPackage.PNG deleted file mode 100644 index 0a396dfca..000000000 Binary files a/docs/Create-Packages/media/publish_UploadYourPackage.PNG and /dev/null differ diff --git a/docs/Guides/Create-Cross-Platform-Packages.md b/docs/Guides/Create-Cross-Platform-Packages.md deleted file mode 100644 index 6c6d111e0..000000000 --- a/docs/Guides/Create-Cross-Platform-Packages.md +++ /dev/null @@ -1,292 +0,0 @@ ---- -# required metadata - -title: Create Cross-Platform NuGet Packages (for iOS, Android, and Windows) | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: get-started-article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: ae24824b-a138-4d12-a810-1f653ddffd32 - -# optional metadata - -description: An end-to-end walkthrough of creating NuGet packages for Xamarin that use native APIs on iOS, Android, and Windows. -keywords: create a package, packages for Xamarin, cross-platform packages -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Create cross-platform packages - -A cross-platform package 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'll create a cross-platform NuGet package that can be used in mobile projects on iOS, Android, and Windows. - -1. [Pre-requisites](#pre-requisites) -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) - -## Pre-requisites - -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://visualstudiogallery.msdn.microsoft.com/afead421-3fbf-489a-a4e8-4a244ecdbb1e) 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'll 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'll 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'll 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: - -``` -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#choosing-a-unique-package-identifier-and-setting-the-version-number)). Also note that you must also update the author and description tags or you'll 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: - -``` -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'll 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](../create-packages/publish-a-package.md). - -## Related topics - -- [Nuspec Reference](../schema/nuspec.md) -- [Symbol packages](../create-packages/symbol-packages.md) -- [Package versioning](../reference/package-versioning.md) -- [Supporting Multiple .NET Framework Versions](../create-packages/supporting-multiple-target-frameworks.md) -- [Including MSBuild props and targets in a package](../create-packages/creating-a-package.md#including-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-NET-Standard-Packages-VS2015.md b/docs/Guides/Create-NET-Standard-Packages-VS2015.md deleted file mode 100644 index c5527ceda..000000000 --- a/docs/Guides/Create-NET-Standard-Packages-VS2015.md +++ /dev/null @@ -1,342 +0,0 @@ ---- -# required metadata - -title: Create .NET Standard NuGet Packages with Visual Studio 2015 | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: get-started-article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 29b3bceb-0f35-4cdd-bbc3-a04eb823164c - -# optional metadata - -description: An end-to-end walkthrough of creating .NET Standard NuGet packages using NuGet 3.x and Visual Studio 2015. -keywords: create a package, .NET Standard packages, .NET Standard mapping table -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Create .NET Standard packages with Visual Studio 2015 - -*Applies to NuGet 3.x. See [Create .NET Standard Packages with Visual Studio 2017](../guides/create-net-standard-packages-vs2017.md) for working with NuGet 4.x+.* - -The [.NET Standard Library](https://docs.microsoft.com/dotnet/articles/standard/library) is a formal specification of .NET APIs intended to be available on all .NET runtimes, thus establishing greater uniformity in the .NET ecosystem. The .NET Standard Library defines a uniform set of BCL (Base Class Library) APIs for all .NET platforms to implement, independent of workload. It enables developers to produce PCLs that are usable across all .NET runtimes, and reduces if not eliminates platform-specific conditional compilation directives in shared code. - -This guide will walk you through creating a nuget package targeting .NET Standard Library 1.4. This will work across .NET Framework 4.6.1, Universal Windows Platform 10, .NET Core, and Mono/Xamarin. For details, see the [.NET Standard mapping table](#net-standard-mapping-table) later in this topic. - -1. [Pre-requisites](#pre-requisites) -1. [Create the class library project](#create-the-class-library-project) -1. [Create and update the .nuspec file](#create-and-update-the-nuspec-file) -1. [Package the component](#package-the-component) -1. [Additional options](#additional-options) -1. [.NET Standard mapping table](#net-standard-mapping-table) -1. [Related topics](#related-topics) - - -## Pre-requisites - -1. Visual Studio 2015. 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. -1. .NET Core: Install .NET Core along with templates and other tools for Visual Studio 2015 from [https://go.microsoft.com/fwlink/?LinkId=824849](https://go.microsoft.com/fwlink/?LinkId=824849). -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 class library project - -1. In Visual Studio, **File > New > Project**, expand the **Visual C# > Windows** node, select **Class Library (Portable)**, change the name to AppLogger, and click OK. - - ![Create new class library project](media/NetStandard-NewProject.png) - -1. In the **Add Portable Class Library** dialog that appears, select the `.NET Framework 4.6` and `ASP.NET Core 1.0` options. -1. Right-click the `AppLogger (Portable)` in Solution Explorer, select **Properties**, select the **Library** tab, then click **Target .NET Platform Standard** in the **Targeting** section. This will prompt for confirmation, after which you can select `.NET Standard 1.4` from the drop down: - - ![Setting the target to .NET Standard 1.4](media/NetStandard-ChangeTarget.png) - -1. Click on the **Build** tab, change the **Configuration** to `Release`, and check the box for **XML documentation file**. -1. Add your code to the component, for example: - - ```cs - namespace AppLogger - { - public class Logger - { - public void Log(string text) - { - throw new NotImplementedException("Called Log"); - } - } - } - ``` - -1. Build the project (with the Release configuration) and check that DLL and XML files are produced within the bin\Release folder. - -## Create and update the .nuspec file - -1. Open a command prompt, navigate to the folder containing `AppLogg.csproj` folder (one level below where the `.sln` file is), and run the NuGet `spec` command to create the initial `AppLogger.nuspec` file: - -``` -nuget spec -``` - -1. Open `AppLogger.nuspec` in an editor and update it 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#choosing-a-unique-package-identifier-and-setting-the-version-number). Also note that you must also update the author and description tags or you'll get an error during the packing step. - -```xml - - - - AppLogger.YOUR_NAME - 1.0.0 - AppLogger - YOUR_NAME - YOUR_NAME - false - Awesome application logging utility - First release - Copyright 2016 (c) Contoso Corporation. All rights reserved. - logger logging logs - - -``` - -1. Add reference assemblies to the `.nuspec` file, namely the library's DLL and the IntelliSense XML file: - - ```xml - - - - - - ``` - -1. Right-click the solution and select **Build Solution** to generate all the files for the package. - - -## 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: - -``` -nuget pack AppLogger.nuspec -``` - -This will generate `AppLogger.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'll see the following contents: - -![NuGet Package Explorer showing the AppLogger package](media/NetStandard-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](../create-packages/publish-a-package.md). - -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. - -## Additional options - -The following sections go into additional options for NuGet package creation: - -- [Declaring dependencies](#declaring-dependencies) -- [Supporting multiple target frameworks](#supporting-multiple-target-frameworks) -- [Adding targets and props for MSBuild](#adding-targets-and-props-for-msbuild) -- [Creating localized packages](#creating-localized-packages) -- [Adding a readme](#adding-a-readme) - -### Declaring dependencies - -If you have any dependencies on other NuGet packages, list those in the `` element with `` elements. For example, to declare a dependency on NewtonSoft.Json 8.0.3 or above, add the following: - -```xml - - - - - - -``` - -The syntax of the *version* attribute here indicates that version 8.0.3 or above is acceptable. To specify different version ranges, refer to [Package versioning](../reference/package-versioning.md). - -### Supporting multiple target frameworks - -Suppose you'd like to take advantage of an API in .NET Framework 4.6.2 that is not available in .NET Standard 1.4. To do this, you'll first need to make sure the library compiles for .NET 4.6.2 by using conditional compilation or shared projects. (In Visual Studio, you can create a NetCore project, add the framework of choice to the multiple framework section, and then build.) Then you create the package using the simple convention-based working directory technique as follows: - -1. In the project's root folder containing your `.nuspec` file, create a folder named `lib`. -1. Inside `lib`, create folders for each platform you want to support: - - \lib - \netstandard1.4 - \AppLogger.dll - \net462 - \AppLogger.dll - -1. In the `.nuspec` file, add a `files` node under the `package` node and refer to the files in `lib` using wildcards. **Note:** Token replacements are not supported with the convention-based working directory approach, so replace them with literal values: - - ```xml - - - - AppLogger.YOUR_NAME - 1.0.0.0 - AppLogger - YOUR_NAME - YOUR_NAME - false - Awesome application logging utility - First release. - Copyright 2016 - logger logging logs - - - - - - ``` - -1. Create the package again using `nuget pack AppLogger.spec`. - -For more details on using this technique, see [Supporting Multiple .NET Framework Versions](../create-packages/supporting-multiple-target-frameworks.md) - -### Adding targets and props for MSBuild - -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 adding files in a `\build` folder as described in the steps below. When NuGet installs a package with \build files, it adds an MSBuild element in the project file pointing to the .targets and .props files. - -> [!Note] -> When using `project.json`, targets are not added to the project but are made available through the `project.lock.json`. - - -1. In the project folder containing the your `.nuspec` file, create a folder named `build`. -1. Inside `build`, create folders for each supported, and within those place your `.targets` and `.props` files: - - \build - \netstandard1.4 - \AppLogger.props - \AppLogger.targets - \net462 - \AppLogger.props - \AppLogger.targets - -1. In the `.nuspec` file, add a `files` node under the `package` node and refer to the files in `build` using wildcards. - - ```xml - - - ... - - - - - - ``` - -1. Create the package again using `nuget pack AppLogger.nuspec`. - -For additional details, refer to [Include MSBuild props and targets in a package](../create-packages/creating-a-package.md#including-msbuild-props-and-targets-in-a-package). - - -### Creating localized packages - -To create localized versions of your library, you can either create separate packages for different locales, or include localized resource assemblies within a single package. Here's how to do the latter approach for German and Italian: - -1. Within each target framework folder under `lib`, create folders for each supported language other than the English default. In these folders you can place resource assemblies and localized IntelliSense XML files. For example: - - lib - ├───netstandard1.4 - │ │ AppLogger.dll - │ │ AppLogger.xml - │ │ - │ ├───de - │ │ AppLogger.resources.dll - │ │ AppLogger.xml - │ │ - │ └───it - │ AppLogger.resources.dll - │ AppLogger.xml - └───net462 - │ AppLogger.dll - │ AppLogger.xml - │ - ├───de - │ AppLogger.resources.dll - │ AppLogger.xml - │ - └───it - AppLogger.resources.dll - AppLogger.xml - -1. In the `.nuspec` file, reference these files in the `` node: - - ```xml - - - ... - - - - - - ``` - -1. Create the package again using `nuget pack AppLogger.nuspec`. - - -### Adding a readme - -When you include a `readme.txt` file in the root of the package, Visual Studio will display it when the package is installed directly. - -> [!Note] -> Readme files are not shown for packages that are installed as a dependency, or for .NET Core projects. - - -To do this, create your `readme.txt` file, place it in the project root folder, and refer to it in the `.nuspec` file: - -```xml - - - ... - - - - - -``` - - -## .NET Standard mapping table - -|Platform Name |Alias| -|--------------|-----| -|.NET Standard | netstandard| 1.0| 1.1| 1.2| 1.3| 1.4| 1.5| 1.6| -|.NET Core | netcoreapp| →| →| →| →| →| →| 1.0| -|.NET Framework| net| 4.5| 4.5.1| 4.6| 4.6.1| 4.6.2| 4.6.3| -|Mono/Xamarin Platforms| →| →| →| →| →| →| -|Universal Windows Platform| uap| →| →| →| →|10.0| -|Windows| win| →| 8.0| 8.1| -|Windows Phone| wpa| →| →|8.1| -|Windows Phone Silverlight| wp| 8.0| - - - -## Related topics - -- [Nuspec Reference](../schema/nuspec.md) -- [Symbol packages](../create-packages/symbol-packages.md) -- [Package versioning](../reference/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#including-msbuild-props-and-targets-in-a-package) -- [Creating Localized Packages](../create-packages/creating-localized-packages.md) -- [.NET Standard Library documentation](https://docs.microsoft.com/dotnet/articles/standard/library) -- [Porting to .NET Core from .NET Framework](https://docs.microsoft.com/dotnet/articles/core/porting/index) diff --git a/docs/Guides/Create-NET-Standard-Packages-VS2017.md b/docs/Guides/Create-NET-Standard-Packages-VS2017.md deleted file mode 100644 index 9f9e7cbe3..000000000 --- a/docs/Guides/Create-NET-Standard-Packages-VS2017.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -# required metadata - -title: Create .NET Standard 2.0 NuGet Packages with Visual Studio 2017 | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 5/23/2017 -ms.topic: get-started-article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 2c1de334-fdc9-4e1e-8ef6-a90b3e77ff0f - -# optional metadata - -description: An end-to-end walkthrough of creating .NET Standard 2.0 NuGet packages using NuGet 4.x and Visual Studio 2017. -keywords: create a package, .NET Standard packages, .NET Core -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Create .NET Standard 2.0 packages with Visual Studio 2017 - -*Applies to NuGet 4.x+ and MSBuild 15.3+ as provided with Visual Studio 2017 Update 3. For earlier versions of Visual Studio 2017, these instructions apply to .NET Standard 1.4 to 1.6 by changing the \ property. Also see [Create .NET Standard Packages with Visual Studio 2015](../guides/create-net-standard-packages-vs2015.md) for working with NuGet 3.x+.* - -The [.NET Standard Library](https://docs.microsoft.com/dotnet/articles/standard/library) is a formal specification of .NET APIs intended to be available on all .NET runtimes, thus establishing greater uniformity in the .NET ecosystem. The .NET Standard Library defines a uniform set of BCL (Base Class Library) APIs for all .NET platforms to implement, independent of workload. It enables developers to produce PCLs that are usable across all .NET runtimes, and reduces if not eliminates platform-specific conditional compilation directives in shared code. - -This guide will walk you through creating a nuget package targeting .NET Standard Library 2.0 with Visual Studio 2017 Update 3 and NuGet 4.0. - -1. [Pre-requisites](#pre-requisites) -1. [Create the class library project](#create-the-netstandard-class-library-project) -1. [Edit metadata in the .csproj file](#edit-metadata-in-the-csproj-file) -1. [Package the component](#package-the-component) -1. [Related topics](#related-topics) - -## Pre-requisites - -This walkthrough requires Visual Studio 2017 Update 3 with the **.NET Core cross-platform development** workload. You can install the Community edition for free from [visualstudio.com](https://www.visualstudio.com/), or use the Professional and Enterprise editions. - -The require workload appears as follows in the Visual Studio installer: - -![.NET Core cross-platform development workload in the Visual Studio Installer](media/NuGet4-01-Workload.png) - -## Create the .NET Standard class library project - -1. In Visual Studio, **File > New > Project**, expand the **Visual C# > .NET Standard** node, select **Class Library (Net Standard)**, change the name to AppLogger, and click OK. - - ![Create new class library project](media/NuGet4-02-NewProject.png) - -1. Change the build configuration to **Release**. -1. Right-click the `AppLogger` project in Solution Explorer, select **Properties**, select the **Build** tab, check the box for **XML documentation file**, and set the filename to just `AppLogger.xml`. Then save the project. - -1. Add your code to the component, such as the following (which clearly just outputs messages to the console): - - ```cs - namespace AppLogger - { - public class Logger - { - public void Log(string text) - { - Console.WriteLine(text); - } - } - } - ``` - -1. Build the project (with the Release configuration) and check that DLL and XML files are produced within the `bin\Release\netstandard2.0` folder. - -## Edit metadata in the .csproj file - -With NuGet 4.0 and .NET Core projects, package metadata is contained directly in the `.csproj` file instead of external files such as a `.nuspec`. A full description of that metadata is found in [NuGet pack and restore as MSBuild targets](../schema/msbuild-targets.md#pack-target). - -1. Right-click the project in Solution Explorer, select **Edit AppLogger.csproj**, and then edit the first property group to include package information such as the following: - - ```xml - - netstandard2.0 - AppLogger.YOUR_NAME - 1.0.0 - YOUR_NAME - Awesome application logging utility - false - First release - Copyright 2017 (c) Contoso Corporation. All rights reserved. - logger logging logs - - ``` - -1. Save the project, then right-click the solution and select **Build Solution** to again generate all the files for the package, this time with the correct metadata. - - -## Package the component - -NuGet 4.0 supports a pack target using MSBuild version 15.1+ (including MSBuild 15.3 as part of Visual Studio 2017 Update 3) when the project contains the necessary package metadata, as was added in the previous section. To invoke MSBuild in this way, simply specify the pack target on the command line in the same folder as the `.csproj` file: - - msbuild /t:pack /p:Configuration=Release - -For additional options with `msbuild /t:pack`, such as including content files, symbols, and source code, see [NuGet pack and restore as MSBuild targets](../schema/msbuild-targets.md#pack-target). - -In any case, the command above generates `AppLogger.YOUR_NAME.1.0.0.nupkg` in the `bin\Release` folder by default, as it builds that configuration. If you omit the `/p` switch, the default configuration will be `Debug`. - -Opening this file in a tool like the [NuGet Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer) and expanding all the nodes, you'll see the following contents: - -![NuGet Package Explorer showing the AppLogger package](media/NuGet4-03-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](../create-packages/publish-a-package.md). - -## Related topics - -- [Package References in Project Files](../consume-packages/package-references-in-project-files.md) describes all the details of describing your package directly in the project file. -- [NuGet pack and restore as MSBuild targets](../schema/msbuild-targets.md) describes all the options for using `msbuild /t:pack` to create the package. -- [.NET Standard Library documentation](https://docs.microsoft.com/dotnet/articles/standard/library) -- [Porting to .NET Core from .NET Framework](https://docs.microsoft.com/dotnet/articles/core/porting/index) diff --git a/docs/Guides/Create-UWP-Controls.md b/docs/Guides/Create-UWP-Controls.md deleted file mode 100644 index 352dc152e..000000000 --- a/docs/Guides/Create-UWP-Controls.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -# required metadata - -title: How to package UWP controls with NuGet | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 3/21/2017 -ms.topic: get-started-article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 1f9de20a-f394-4cf2-8e40-ba0f4239cd5e - -# optional metadata - -description: How to create NuGet packages that contain UWP controls, including the necessary metadata and supporting files for the Visual Studio and Blend designers. -keywords: NuGet UWP controls, Visual Studio XAML designer, Blend designer, custom controls -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Creating UWP controls as NuGet packages - -With Visual Studio 2017, you can take advantage of added capabilities for UWP controls that you deliver in NuGet packages. This guide walks you through these capabilities using the [ExtensionSDKasNuGetPackage sample](https://github.com/NuGet/Samples/tree/master/ExtensionSDKasNuGetPackage). - -## Pre-requisites: - -1. Visual Studio 2017 -1. Understanding of how to [Create UWP Packages](create-uwp-packages.md) - -## Add toolbox/assets pane support for XAML controls - -To have a XAML control appear in the XAML designer’s toolbox in Visual Studio and the Assets pane of Blend, create a `VisualStudioToolsManifest.xml` file in the root of the `tools` folder of your package project. This file is not required if you don’t need the control to appear in the toolbox or Assets pane. - -``` -\build -\lib -\tools - \VisualStudioToolsManifest.xml -``` - -The structure of the file is as follows: - -```xml - - - - - - - - - - - -``` - -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. -- *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. - -In more advanced scenarios, you can also include multiple `` elements within `` when a single package contains multiple control assemblies. You can also have multiple `` nodes within a single `` if you want to organize your controls into separate categories. - -In the following example, the control implemented in `ManagedPackage.winmd` will appear in Visual Studio and Blend in a group named “Managed Package”, and “MyCustomControl” will appear in that group. All these names are arbitrary. - -```xml - - - - - - - -``` - -![An example control as it appear in Visual Studio](media/UWP-control-vs-toolbox.png) - -![An example control as it appear in Blend](media/UWP-control-blend-assets.png) - -> [!Note] -> You must explicitly specify every control that you would like to see in the toolbox/assets pane. Ensure you specify them in the format `Namespace.ControlName`. - -## 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”. Supported formats are `.png`, `.jpg`, `.jpeg`, `.gif`, and `.bmp`. The recommended image size is 64 pixels by 64 pixels. - -In the example below, the project contains an image file named “ManagedPackage.MyCustomControl.png”. - -![Setting a custom icon in a project](media/UWP-control-custom-icon.png) - -> [!Note] -> For native controls, you must put the icon as a resource in the `design.dll` project. - -## Support specific Windows platform versions - -UWP packages have a TargetPlatformVersion (TPV) and TargetPlatformMinVersion (TPMinV) that define the upper and lower bounds of the OS version where the app can be installed. TPV further specifies the version of the SDK against which the app is built. Be mindful of these properties when authoring a UWP package: using APIs outside the bounds of the platform versions defined in the app will cause either the build to fail or the app to fail at runtime. - -For example, let’s say you’ve set the TPMinV for you 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 `project.json` based UWP projects, you must package your controls with the following folder names: - -``` -\lib\uap10.0\* -\ref\uap10.0\* -``` - -To enforce the appropriate TPMinV check, create an [MSBuild targets file](https://docs.microsoft.com/visualstudio/msbuild/msbuild-targets) and package it under the build folder (replacing "your_assembly_name" with the name of your specific assembly): - -``` -\build - \uap10.0 - your_assembly_name.targets -\lib -\tools -``` - -Here is an example of what the targets file should look like: - -```xml - - - - - - 10.0.14393 - $(TargetPlatformMinVersion) - - - - -``` - -## 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\\Design` folder as appropriate to the target platform. Also, to ensure that the **[Edit Template > Edit a Copy](https://docs.microsoft.com/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. (This file has no impact on the runtime behavior of a control.) - - -``` -\build -\lib - \uap10.0.14393.0 - \Design - \MyControl.design.dll - \your_assembly_name - \Themes - Generic.xaml -\tools -``` - -> [!Note] -> By default, control properties will show up under the Miscellaneous category in the property inspector. - - -## Use strings and resources - -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. - -## Package content such as images - -To package content such as images that can be used by your control or the consuming UWP project. add those files `lib\uap10.0.14393.0` folder as follows ("your_assembly_name" should again match your particular control): - -``` -\build -\lib - \uap10.0.14393.0 - \Design - \your_assembly_name -\contosoSampleImage.jpg -\tools -``` - -You may also author an[MSBuild targets file](https://docs.microsoft.com/visualstudio/msbuild/msbuild-targets) to ensure the asset is copied to the consuming project’s output folder: - -```xml - - - - - Always - - - -``` - -## See also - -- [Create UWP Packages](create-uwp-packages.md) -- [ExtensionSDKasNuGetPackage sample](https://github.com/NuGet/Samples/tree/master/ExtensionSDKasNuGetPackage) diff --git a/docs/Guides/Install-NuGet.md b/docs/Guides/Install-NuGet.md deleted file mode 100644 index 0800b5096..000000000 --- a/docs/Guides/Install-NuGet.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -# required metadata - -title: Installing NuGet client tools | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 10/2/2017 -ms.topic: get-started-article -ms.prod: nuget -ms.technology: null -ms.assetid: 683b8b34-a6f4-4d56-b9cd-2483bfbad1ad - -# optional metadata - -description: Guidance on installing client tools, the command-line interface (CLI), and the Package Manager for Visual Studio. -keywords: nuget.exe CLI, NuGet client tools, NuGet package manager, NuGet package manager console, NuGet for Visual Studio, NuGet beta channel -ms.reviewer: -- karann-msft -- unniravindranathan - ---- - -# Installing NuGet client tools - -> [!Tip] -> **Looking to install a package? See [Quickstart - Use a package](../Quickstart/Use-a-Package.md).** - -There are two primary tools available to help you build, publish and consume NuGet packages: - -1. The [**NuGet CLI**](#nuget-cli) is the command-line utility for Windows that provides all NuGet capabilities; it can also be run on Mac OSX and Linux using Mono, or through the .NET Core CLI (`dotnet`). -1. The [**NuGet Package Manager in Visual Studio**](#nuget-package-manager-in-visual-studio) (Windows only) is a GUI tool for managing packages and includes a PowerShell console through which you can use certain NuGet commands directly within Visual Studio. The Package Manager UI and Console are both included with Visual Studio (on Windows) 2012 and later and can be installed manually for earlier versions. - - With Visual Studio for Mac, NuGet capabilities are built in directly. See [Including a NuGet package in your project](https://docs.microsoft.com/visualstudio/mac/nuget-walkthrough) for a walkthrough. - -The NuGet CLI and Package Manager both support the following operations: - -- Search packages -- Install packages -- Update packages -- Uninstall packages -- Restore packages (UI only in the Package Manager) -- Manage NuGet sources - -The following capabilities are supported only in the NuGet CLI: - -- Manage packages (nuget.org or private feed) -- Create packages -- Publish packages -- Manage Nuget.Config -- Manage the NuGet cache -- Replicating a package - -> [!Note] -> Another good tool is 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 having to rebuild the package each time. -> The cross-platform [.NET Core CLI](https://docs.microsoft.com/dotnet/articles/core/tools/index#installation) toolchain, used for developing .NET Core applications, supports several NuGet commands, such as delete, locals, push, pack, and restore. - - -## NuGet CLI - -The NuGet command-line interface provides access to all NuGet capabilities, and can be run on Windows, Mac OSX, and Linux as described in the following sections. - -### Windows - -**Direct download:** - -[!INCLUDE[install-cli](../includes/install-cli.md)] - -> [!Note] -> With NuGet 1.4+, you can use `nuget update -self` to update your existing nuget.exe to the latest version. - -**Other methods:** - -- **Chocolatey**: Install the [NuGet.CommandLine](http://chocolatey.org/packages/NuGet.CommandLine) Chocolatey package using the [Chocolatey](http://chocolatey.org) client. - - ``` - choco install nuget.commandline - ``` - -- **Visual Studio**: Install the [NuGet.CommandLine](http://www.nuget.org/packages/NuGet.CommandLine/) package from the Package Manager Console in Visual Studio. - - > [!Note] - > **For NuGet 2.x users**: Because of breaking changes introduced in NuGet 3.2, [https://nuget.org/nuget.exe](https://nuget.org/nuget.exe) points to the latest stable NuGet 2.x release to prevent continuous integration systems from potentially breaking. - - - -## Mac OSX and Linux - -On Mac OSX and Linux, there are two ways to run the NuGet CLI: - -- Install the [.NET Core SDK](https://www.microsoft.com/net/download/core), which includes the core NuGet capabilities. Downloads are also listed on [github.com/dotnet/cli](https://github.com/dotnet/cli). If you need fuller capabilities, then use the second option below to use `nuget.exe` with Mono. - -- Install [Mono](http://www.mono-project.com/docs/getting-started/install/) and then use the `nuget.exe` command-line executable for Windows (version 3.2 and later) from [nuget.org/downloads](https://nuget.org/downloads). Running NuGet on Mono is subject to the following limitations: - - - Commands tested to work: - - config - - delete - - help - - install - - list - - push - - setApiKey - - sources - - spec - - - Partially-working commands: - - pack: works with `.nuspec` files but not with project files. - - restore: works with `packages.config` and `project.json` files but not with solution (`.sln`) files. - - - Commands that do not work: - - update - - -### Related topics - -- [NuGet CLI reference](../tools/nuget-exe-cli-reference.md) -- [Creating a package](../create-packages/creating-a-package.md) -- [Publishing a Package](../create-packages/publish-a-package.md) - - -## NuGet Package Manager in Visual Studio - -The NuGet Package Manager is included in every edition of Visual Studio on Windows, 2012 and later. It includes the Package Manager UI ([reference](../tools/package-manager-ui.md)), and the Package Manager Console through which you can access tools that come with certain packages ([reference](../tools/package-manager-console.md)). - -The Visual Studio 2017 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 2017 installer and check the option under **Individual Components > Code tools > NuGet package manager**. - -> [!Note] -> The console requires [PowerShell 2.0](http://support.microsoft.com/kb/968929), which will already be installed on Windows 7 or higher and Windows Server 2008 R2 or higher. -> -> Package Manager Console commands also work only within Visual Studio on Windows. Use the NuGet CLI outside of that environment, including with Visual Studio for Mac. - - -### Package Manager installation for Visual Studio 2010 and earlier - -*These steps are not necessary for Visual Studio 2012 and later, which already include the Package Manager.* - -1. In Visual Studio 2010 and earlier, click **Tools > Extension and Updates**. -1. Navigate to **Online**, then search for "NuGet Package Manager for Visual Studio" and click **Download**. -1. In the Installer dialog box, click **Install**. -1. When installation is complete, restart Visual Studio. - -> [!Tip] -> If you're unable to use the **Extensions and Updates** dialog in Visual Studio (for example, its blocked by a proxy), you can download extensions for Visual Studio 2013 and 2015 directly at [https://dist.nuget.org/index.html](https://dist.nuget.org/index.html). - -### Updating the Package Manager - -For Visual Studio 2015 Update 2 and later, the Package Manager is automatically updated to the latest stable release. - -For Visual Studio 2015 Update 1 and earlier, select the **Tools > Extensions and Updates** command and click on the **Updates** tab to see if a new version of the Package Manager is available. - -### NuGet previews - -If you'd like to preview upcoming NuGet features, install the [Visual Studio 2017 Preview](https://www.visualstudio.com/vs/preview/), which works side-by-side with stable releases of Visual Studio. - -Note that the previous NuGet Beta Channel (`https://dotnet.myget.org/F/nuget-beta/vsix/`) for Visual Studio 2015 is no longer used. - -To report problems with any release of NuGet or to share ideas, open an issue on the [NuGet GitHub repository](https://github.com/Nuget/Home). - -### Related topics - -- [Package Manager UI reference](../tools/package-manager-ui.md) -- [Package Manager Console reference](../tools/package-manager-console.md) -- [Package Manager Console PowerShell reference](../tools/powershell-reference.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.png b/docs/Guides/media/UWP-BatchBuild.png deleted file mode 100644 index a0301bfb7..000000000 Binary files a/docs/Guides/media/UWP-BatchBuild.png and /dev/null differ diff --git a/docs/Guides/media/UWP-PackageExplorer.png b/docs/Guides/media/UWP-PackageExplorer.png deleted file mode 100644 index 559a80dff..000000000 Binary files a/docs/Guides/media/UWP-PackageExplorer.png and /dev/null differ diff --git a/docs/Hosting-Packages/Local-Feeds.md b/docs/Hosting-Packages/Local-Feeds.md deleted file mode 100644 index 1622dbd5f..000000000 --- a/docs/Hosting-Packages/Local-Feeds.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -# required metadata - -title: Setting up Local NuGet Feeds | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 8/25/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 1354a527-d988-43d1-8dcf-6ce46ec5d3d4 - -# optional metadata - -description: How to create a local feed for NuGet packages using folders on your local network -keywords: NuGet feed, NuGet gallery, local package feed -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- -# Local feeds - -Local NuGet package feeds are simply folders on your local network (or even just your own computer) in which you place packages. Local feeds can be a simple folder of packages, or a hierarchical folder structure that include version numbers. With NuGet 3.3 and above, using the hierarchical structure gives much better performance. - -In all cases, enable the source by adding its pathname, such as `\\myserver\packages`, using the [Package Manager UI](../tools/package-manager-ui.md#package-sources) or the [`nuget sources`](../tools/cli-ref-sources.md) command. - -## Initializing and maintaining hierarchical folders - -With NuGet 3.3+, you realize much better performance by structuring the feed using a hierarchical versioned folder tree: - - \\myserver\packages - └─ - └─ - ├─..nupkg - └─ - -NuGet creates this structure automatically when you use the [`nuget add`](../tools/cli-ref-add.md) command to copy packages to the feed: - -``` -nuget add new_package.1.0.0.nupkg -source \\myserver\packages -``` - -You can also use the [`nuget init`](../tools/cli-ref-init.md) command to copy multiple packages from a single folder to the feed. For example, the following command copies all packages from `c:\packages` to a hierarchical tree on `\\myserver\packages`: - -``` -nuget init c:\packages \\myserver\packages -``` - -Again, this creates a folder for each package identifier, each of which contains a version number folder, within which is the appropriate package. diff --git a/docs/Hosting-Packages/NuGet-Server.md b/docs/Hosting-Packages/NuGet-Server.md deleted file mode 100644 index 41d7e469e..000000000 --- a/docs/Hosting-Packages/NuGet-Server.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -# required metadata - -title: NuGet.Server to Host NuGet Feeds | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 8/25/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 45138f80-9717-42c2-8b34-9a1bc1fb3eab - -# optional metadata - -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. -keywords: NuGet feed, NuGet gallery, remote package feed, NuGet.Server -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# NuGet.Server - -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. -1. Configure the `Packages` folder in the application and add packages. -1. Deploy the application to a suitable server. - -The following sections walk through this process in detail, using C#. - -## Create and deploy an ASP.NET Web application with NuGet.Server - -1. In Visual Studio, select **File > New > Project**, set the target framework for .NET Framework 4.6 (see below), search for "ASP.NET", and select the **ASP.NET Web Application (.NET Framework)** template for C#. - - ![Setting .NET Framework target to 4.6](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 and select OK. - -1. Right-click the project, select **Manage NuGet Packages**, and in the Package Manager UI 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`.) - - ![Installing the NuGet.Server package](media/Hosting_02-NuGet.Server-Package.png) - - > [!Important] - > If your web application targets .NET Framework 4.5.2, you must install NuGet Server **2.10.3** instead. - -1. Installing NuGet.Server converts the empty Web application into a package source. It creates a `Packages` folder in the application and overwrites `web.config` to include additional settings (see the comments in that file for details). - -1. To make packages available in the feed when you publish the application to a server, add their `.nupkg` files to the `Packages` folder in Visual Studio, then set their **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 (without debugging, that is Ctrl+F5). The home page provides the package feed URLs: - - ![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. 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 or delete packages using nuget.exe provided that you set an API key value in `web.config`. - -After installing the NuGet.Server package, `web.config` contains an empty `appSetting/apiKey` value: - -```xml - - - -``` - -When `apiKey` is omitted or blank, pushing packages to the feed is disabled. - -To enable this capability, set the `apiKey` to a value (ideally a strong password) and add a key called `appSettings/requireApiKey` with the value of `true`: - -```xml - - - - - - - -``` - -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 or delete packages. \ No newline at end of file diff --git a/docs/Hosting-Packages/Overview.md b/docs/Hosting-Packages/Overview.md deleted file mode 100644 index 5f9087406..000000000 --- a/docs/Hosting-Packages/Overview.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -# required metadata - -title: Overview of Hosting Your Own NuGet Feeds | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 8/25/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 97577ddd-c294-432d-81a7-b4aebe88bd1c - -# optional metadata - -description: An overview of opens for hosting your own NuGet package feeds or galleries either locally or remotely. -keywords: NuGet feed, NuGet gallery, custom package feed, NuGet.Server -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -- anangaur -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- -# Hosting your own NuGet feeds - -Instead of making packages publicly available, you might want to release packages to only a limited audience, such as your organization or workgroup. In addition, some companies may want to restrict which third-party libraries their developers may use, and thus direct those developers to draw from a limited package source rather than nuget.org. - -For all such purposes, NuGet supports setting up private package sources in the following ways: - -- Local feed: Packages are simply placed on a suitable network file share, ideally using `nuget init` and `nuget add` to create a hierarchical folder structure (NuGet 3.3+). For details, see [Local Feeds](../hosting-packages/local-feeds.md). -- NuGet.Server: Packages are made available through a local HTTP server. For details, see [NuGet.Server](../hosting-packages/NuGet-Server.md). -- NuGet Gallery: Packages are hosted on an Internet server using the [NuGet Gallery Project](https://github.com/NuGet/NuGetGallery#build-and-run-the-gallery-in-arbitrary-number-easy-steps) (github.com). NuGet Gallery provides user management and features such as an extensive web UI that allows searching and exploring packages from within the browser, similar to nuget.org. - -There are also several other NuGet hosting products that support remote private feeds, including the following: - -- [Visual Studio Team Services Package Management](https://www.visualstudio.com/docs/package/nuget/publish), which is also available on Team Foundation Server 2017 and later. -- [MyGet](http://myget.org) -- [ProGet](http://inedo.com/proget) from Inedo -- [NuGet Server](http://nugetserver.net/), a community project from Inedo -- [NuGet Server (Open Source)](http://nuget-server.net), an open-source implementation similar to Inedo's NuGet Server -- [Artifactory](https://www.jfrog.com/artifactory/) from JFrog. -- [Nexus](http://www.sonatype.org/nexus/) from Sonatype. -- [TeamCity](https://www.jetbrains.com/teamcity/) from JetBrains. - -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](../tools/package-manager-ui.md#package-sources), or from the command line using [`nuget sources`](../tools/cli-ref-sources.md). The path to a source can be a local folder pathname, a network name, or a URL. 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 deleted file mode 100644 index 68dcde4c2..000000000 Binary files a/docs/Hosting-Packages/media/Hosting_01-NuGet.Server-Set4.6.png and /dev/null 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 8d1a08c9c..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_04-NuGet.Server-FeedHomePage.png b/docs/Hosting-Packages/media/Hosting_04-NuGet.Server-FeedHomePage.png deleted file mode 100644 index b5eafb057..000000000 Binary files a/docs/Hosting-Packages/media/Hosting_04-NuGet.Server-FeedHomePage.png and /dev/null differ diff --git a/docs/Policies/Deleting-Packages.md b/docs/Policies/Deleting-Packages.md deleted file mode 100644 index 1c78c1e92..000000000 --- a/docs/Policies/Deleting-Packages.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -# required metadata - -title: Deleting NuGet Packages from nuget.org | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: a348ca2e-0a5d-40ad-ba33-9bb37e1d980b - -# optional metadata - -description: Policies for unlisting packages from nuget.org; permanent deletion is not supported except when packages violate other policies. -keywords: NuGet package deletion, NuGet package unlisting, prohibited uses of packages -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- -# 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: - -- 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). - -## Exceptions - -In exceptional situations such as copyright infringement and potentially harmful content, packages can be deleted manually by the NuGet team. Submit a support request through [NuGet Gallery](http://www.nuget.org) to start the process. - -## Prohibited use - -Packages that meet any of the following criteria are not allowed on the public NuGet gallery and will be immediately removed without discussion. Package owners will, however, be notified of the removal. - -- Contains malware, adware, or any kind of spyware. -- Are designed to harm a developer's workstation or their organization. -- Infringes copyrights or violates licenses. -- 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 is not explicitly designed to do. - -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. diff --git a/docs/Policies/NuGet-FAQ.md b/docs/Policies/NuGet-FAQ.md deleted file mode 100644 index d71f75081..000000000 --- a/docs/Policies/NuGet-FAQ.md +++ /dev/null @@ -1,246 +0,0 @@ ---- -# required metadata - -title: NuGet Frequently-Asked Questions | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 10/30/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 199a915d-9595-4ae2-a1fb-b15da6d7735a - -# optional metadata - -description: Common questions and answers for using NuGet on the command line and in Visual Studio, and working with the NuGet gallery. -keywords: NuGet Q&A, questions and answers, common problems, NuGet versions, package versions -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann-msft -- unniravindranathan -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: ---- -# NuGet frequently-asked questions - -In this topic: - -- [Getting started](#getting-started) -- [NuGet in Visual Studio](#nuget-in-visual-studio) -- [NuGet command line](#nuget-command-line) -- [NuGet Package Manager Console](#nuget-package-manager-console) -- [Creating and publishing packages](#creating-and-publishing-packages) -- [Working with packages](#working-with-packages) -- [Managing packages on nuget.org](#managing-packages-on-nugetorg) -- [nuget.org not accessible](#nugetorg-not-accessible) - -## Getting started - -**What is required to run NuGet?** - -All the information around both UI and command-line tools is available in the [Install guide](../guides/install-nuget.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. - -## NuGet in Visual Studio - -**How do I check the exact version of NuGet 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 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](../Tools/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](../guides/install-nuget.md) and the [CLI reference](../tools/nuget-exe-CLI-Reference.md). - -## NuGet command line - -**How do I get the latest version of NuGet command line tool?** - -See the [Install guide](../guides/install-nuget.md). - -**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 - -**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](https://docs.microsoft.com/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 and later) 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`](../Schema/nuget-config-file.md#config-section) setting in `Nuget.Config` using `nuget config -set repositoryPath=`. - -**How do I avoid checking in packages folder to source control?** - -Set the [`disableSourceControlIntegration`](../Schema/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#enabling-and-disabling-package-restore). - -**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 or project.json 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` and `project.json` 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` or `project.json` filenames as below and NuGet uses that file: - - `packages.config`: use the pattern `packages.{project-name}.config` - `project.json`: use the pattern `{project-name}.project.json` - -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 the `%appdata%\.nuget\NuGet.Config` and let NuGet re-create it. - -## Managing packages on nuget.org - -**Can I edit package metadata after it's been uploaded? Why do you recommend editing the nuspec and uploading a new package for making changes to package metadata?** - -NuGet will be implementing package signing. 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 [staging.nuget.org](http://staging.nuget.org) is a great way to test and validate your package without making a package available in the public gallery. - -**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, send mail to account (at) nuget.org with the package owner display name, and the requested package ID prefix. - -**How do I claim ownership for packages ?** - -See [Managing package owners on nuget.org](../create-packages/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 [staging.nuget.org](http://staging.nuget.org), or alternative public NuGet servers like [myget.org](https://myget.org) or [Visual Studio Team Services](https://blogs.msdn.microsoft.com/visualstudioalm/2015/08/27/announcing-package-management-support-for-vsotfs/). - -Note that packages uploaded to staging.nuget.org may not be preserved. See [Goodbye preview](http://blog.nuget.org/20130419/goodbye-preview.html). - -**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 -- Your operating system version -- Machine configuration (CPU, Network, hard drive) -- Whether is your machine behind a proxy or firewall -- The versions of .NET that are installed on the machine -- Versions of cross-platform tools such as .NET CLI, or DNU that you're using - -*To capture MTR:* - -- Download WinMTR from [http://winmtr.net/download/](http://winmtr.net/) -- 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). diff --git a/docs/Quickstart/Create-and-Publish-a-Package.md b/docs/Quickstart/Create-and-Publish-a-Package.md deleted file mode 100644 index b0e1df9a1..000000000 --- a/docs/Quickstart/Create-and-Publish-a-Package.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -# required metadata - -title: Introductory Guide to Creating and Publishing a NuGet Package | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 10/3/2017 -ms.topic: get-started-article -ms.prod: nuget -ms.technology: null -ms.assetid: 91781ed6-da5c-49f0-b973-16dd8ad84229 - -# optional metadata - -description: A walkthrough tutorial on creating and publishing a NuGet package using both the nuget.exe command-line interface and Visual Studio. -keywords: NuGet package creation, NuGet package publishing, NuGet tutorial -ms.reviewer: -- karann-msft -- unniravindranathan - ---- - -# Create and publish a package - -It's a simple process to create a NuGet package from a .NET Class Library and publish it to nuget.org. The following steps walk you through the process using the NuGet command-line interface (CLI) and Visual Studio: - -- [Pre-requisites](#install-pre-requisites) -- [Create the .nuspec package manifest file](#create-the-nuspec-package-manifest-file) -- [Run the pack command](#run-the-pack-command) -- [Publish the package](#publish-the-package) - -## Pre-requisites - -1. Install any edition of Visual Studio 2017 from [visualstudio.com](https://www.visualstudio.com/). - -1. Install the NuGet CLI tool, `nuget.exe`, by downloading the latest version of `nuget.exe` from [nuget.org/downloads](https://nuget.org/downloads), and saving the `.exe` to a location in your PATH. Note that the download *is* the tool itself, not an installer. - -1. Create a suitable .NET Class Library project for the code you want to package. If you don't already have a project, you can create a simple one as follows: - 1. In Visual Studio, choose **File > New > Project**, expand the **Visual C# > Windows** node, select the "Class Library" template, name the project AppLogger, and click **OK**. - 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). - - Within a real NuGet package, of course, you'll implement many useful features upon 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. - -## Create the .nuspec package manifest file - -Every NuGet package needs a manifest—a `.nuspec` file—to describe its contents and its dependencies. The `nuget spec` command creates this file for you, which you then customize. In this example you create the `.nuspec` from a project file; you can also create the manifest through other means as described on [Create a Package](../create-packages/creating-a-package.md). - -1. Open a command prompt and navigate to the folder containing your project file (`.csproj`). - -1. Run the NuGet CLI `spec` command to generate the manifest, which is named after your project, such as `AppLogger.nuspec`: - - ``` - nuget spec - ``` - -1. Open the file in a text editor. The manifest looks something like the code below, where tokens in the form *$``$* are be replaced during the packaging process with values from the project's Properties/AssemblyInfo.cs file. For more details on tokens, see [Creating a .nuspec file](../create-packages/creating-a-package.md#creating-the-nuspec-file). - - ```xml - - - - $id$ - $version$ - $title$ - $author$ - $author$ - http://LICENSE_URL_HERE_OR_DELETE_THIS_LINE - http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE - http://ICON_URL_HERE_OR_DELETE_THIS_LINE - false - $description$ - Summary of changes made in this release of the package. - Copyright 2016 - Tag1 Tag2 - - - ``` - -1. Select a package ID that is unique across nuget.org. We recommend using the naming conventions described in [Creating a package](../create-packages/creating-a-package.md#choosing-a-unique-package-identifier-and-setting-the-version-number). Be sure to update the author and description tags or you get an error in the next step. Here's an updated `.nuspec` file as an example: - - ```xml - - - - MyCompanyName.MyProductName.MyPackageName - $version$ - $title$ - kraigb - kraigb - false - Awesome application logging utility - First release - Copyright 2016 - application app logger logging logs - - - ``` - -> [!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. - -## Run the pack command - -To build a NuGet package (a `.nupkg` file) from a project, run the `pack` command: - -``` -nuget pack AppLogger.csproj -``` - -This command creates `AppLogger.1.0.0.0.nupkg` using the package name and version number from the `.nuspec` file. The command issues warnings if you haven't updated various fields in the `.nuspec` file from their default values. - -## Publish the package - -Once you have a `.nupkg` file, you publish it to nuget.org using the `push` command. (Alternately, you can use the [nuget.org publishing workflow](../create-packages/publish-a-package.md#publish-to-nugetorg). - -> [!Warning] -> The packages you publish to nuget.org are publicly visible to other developers. To host packages privately, see [Hosting packages](../hosting-packages/overview.md). - - -1. Create a free account on [nuget.org](https://www.nuget.org/users/account/LogOn?returnUrl=%2F), or log in if you already have one. Creating a new account sends a confirmation email. You must confirm the account before you can upload a package. - -1. Once logged in, select your user name (on the upper right), then select **API Keys**. - -1. Select **Create**, provide a name for your key, select **Select Scopes > Push**Under **API Key**, enter * for **Glob pattern**, then select **Create**. - -1. Once the key is created, select **Copy** to retrieve the access key you'll need in the CLI: - - ![Copying the API key to the clipboard](media/QS_Create-02-APIKey.png) - - > [!Warning] - > Save your key in a secure location and keep is a secret. If your key is accidentally revealed, you can always regenerate it at any time. You can also remove the API key if you no longer want to push packages via the CLI. - -1. At a command prompt, run the following command, specifying your package name and replacing the key with the value copied in step 4: - - ``` - nuget push AppLogger.1.0.0.0.nupkg 47be3377-c434-4c29-8576-af7f6993a54b -Source https://www.nuget.org/api/v2/package - ``` - -1. nuget.exe displays the results of the publishing process: - - ``` - Pushing AppLogger.1.0.0.0.nupkg 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. - ``` - -1. 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: - - ![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] -> **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. - -And that's it! You've just published your first NuGet package to [nuget.org](https://www.nuget.org/), that other developers can use in their own projects. - -## Related topics - -- [Create a Package](../create-packages/creating-a-package.md) -- [Publish a Package](../create-packages/publish-a-package.md) -- [Support multiple target frameworks](../create-packages/supporting-multiple-target-frameworks.md) -- [Package versioning](../reference/package-versioning.md) -- [Creating localized packages](../create-packages/creating-localized-packages.md) diff --git a/docs/Quickstart/Use-a-Package.md b/docs/Quickstart/Use-a-Package.md deleted file mode 100644 index 3e52fba35..000000000 --- a/docs/Quickstart/Use-a-Package.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -# required metadata - -title: Introductory Guide to Using NuGet Packages | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 10/4/2017 -ms.topic: get-started-article -ms.prod: nuget -ms.technology: null -ms.assetid: f31f8259-20a8-4617-880e-5819299372d2 - -# optional metadata - -description: A walkthrough tutorial on the process of installing and using a NuGet package in a project. -keywords: install NuGet, NuGet package consumption, installing NuGet packages, NuGet package references, using NuGet packages -ms.reviewer: -- karann-msft -- unniravindranathan - ---- - -# Install and use a package - -Installing a package happens in three ways: - -| Method | Description | Reference | -| --- | --- | --- | -| nuget.exe CLI: `nuget install ` | Downloads the package identified by \ and expands its contents into a folder in the current directory. No changes are made to any project files. Dependencies are also downloaded and expanded. | [CLI reference](../tools/nuget-exe-CLI-Reference.md) | -| Package Manager Console (Visual Studio): `Install-Package ` | Downloads and installs the package into the current project, then update the project file to list the package as a dependency. | [Package Manager Console Guide](../tools/Package-Manager-Console.md) | -| Package Manager UI (Visual Studio) | Provides a UI through which you can browse, select, and install packages into a project. Updates the project file to list the package as a dependency. | [Package Manager UI Reference](../tools/Package-Manager-UI.md) | - -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. - -The remainder of this topic walks through the process of using the Package Manager UI to install the popular [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json/) package in a Universal Windows Platform (UWP) project. It then shows an example of using the package. You use a similar same workflow for virtually every NuGet package you use in a project. - -- [Install pre-requisites](#install-pre-requisites) -- [Create a project](#create-a-project) -- [Add the Newtonsoft.Json NuGet package](#add-the-newtonsoftjson-nuget-package) -- [Use the Newtonsoft.Json API in the app](#use-the-newtonsoftjson-api-in-the-app) - -> [!Tip] -> **Start with nuget.org**: Installing packages from nuget.org is a common workflow that .NET developers use to find components they can reuse in their own applications. You can always search nuget.org directly or find and install packages within Visual Studio as shown in this topic. - -## Install pre-requisites - -This tutorial requires Visual Studio 2015 Update 3 with Tools for Universal Windows Apps, or Visual Studio 2017 with the Universal Windows Platform development workload. If you already have Visual Studio installed, you can run the installer again to add the UWP tools. - -You can install the Community edition for free from [visualstudio.com](https://www.visualstudio.com/) or use the Professional or Enterprise editions. - -## Create a project - -To install a NuGet package, you need some kind of .NET-based project in Visual Studio. For this walkthrough, you can use use a simple Windows Presentation Foundation (WPF) or Universal Windows (UWP) app: - -- For WPF (Windows 7+), choose **File > New > Project**, expand **Visual C#**, select **Windows Classic Desktop > WPF App (.NET Framework)**, and select **OK**. -- For UWP (Windows 10), use the **Windows Universal > Blank App (Universal Windows)** instead. Accept the default values for Target Version and Minimum Version when prompted. - -## Add the Newtonsoft.Json NuGet package - -1. In Solution Explorer, right-click **References** and choose **Manage NuGet Packages**. - - ![Manage NuGet Packages command for project References](media/QS_Use-02-ManageNuGetPackages.png) - -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**: - - ![Locating Newtonsoft.Json package](media/QS_Use-03-NewtonsoftJson.png) - -1. If prompted to select a package management format, choose between PackageReference (recommended) and `packages.config`: - - ![Selecting a package reference format](media/QS_Use-03b-SelectFormat.png) - -1. If prompted to review changes, select **OK**. - -1. Right-click the solution in Solution Explorer and select **Build Solution**. This restores any NuGet packages listed under **References**. For more details, see [Package Restore](../consume-packages/package-restore.md). - -## 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. - -1. Open `MainWindwos.xaml` (WPF) or `MainPage.xaml` (UWP) and replace the existing `Grid` element with the following: - - ```xaml - - -