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 bde732511..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 are 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 ccb98efe1..000000000 --- a/docs/API/NuGet-API-V3.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -# required metadata  - -title: NuGet v3 Client and NuGetGallery APIs | 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: d1a393b7-51b1-4840-b1a8-fdd76455077d - -# optional metadata - -description: The NuGet and NuGetGallery APIs are evolving and not yet documented, but examples are available on Dave Glick's blog. -keywords: NuGet API, NuGetGallery API, NuGet v3 libraries -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann -- unnir -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: ---- - -# NuGet API v3 - -The NuGet v3 Client and NuGetGallery APIs are constantly evolving and we are working on having a stable surface area that we can document soon. - -In the meantime, you can find examples and documentation for some of the API in the following blog series by Dave Glick: - -- [Exploring the NuGet v3 Libraries, Part 1: Introduction and concepts](http://daveaglick.com/posts/exploring-the-nuget-v3-libraries-part-1) -- [Exploring the NuGet v3 Libraries, Part 2: Searching for packages](http://daveaglick.com/posts/exploring-the-nuget-v3-libraries-part-2) -- [Exploring the NuGet v3 Libraries, Part 3: Installing packages](http://daveaglick.com/posts/exploring-the-nuget-v3-libraries-part-3) diff --git a/docs/Consume-Packages/Configuring-NuGet-Behavior.md b/docs/Consume-Packages/Configuring-NuGet-Behavior.md deleted file mode 100644 index 1eb989af8..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: 7/25/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 -- unnir -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Configuring NuGet behavior - -NuGet's `NuGet.Config` files (in XML) store configuration settings 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/nuget-exe-cli-reference.md#config) 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 eb136c26d..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 -- unnir -#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 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 251ac7ff4..000000000 --- a/docs/Consume-Packages/Finding-and-Choosing-Packages.md +++ /dev/null @@ -1,143 +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 -- unnir -#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 **Package Statistics** on the left side. This shows you the package installs for the last six weeks. A package that other developers are actively using is typically a better choice than one that's not. -- *Restore vs. new install*: on the same package statistics page, clear the **Version** checkbox and select **Operation** to see a chart of package restores vs. new installs (below). - - ![Chart of operations for a NuGet package on nuget.org package statistics](media/Finding-05-OperationChart.png) - -- *Dependency installs*: the same **Operation** chart above has an "Install-Dependency" bar that indicates how many other NuGet packages have taken a dependency on this one. This is an even stronger indication that other developers find the package reliable. -- *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 6e2ae243e..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 -- unnir -#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/nuget-exe-cli-reference.md#locals): - -``` -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 722fae77f..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 -- unnir -#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/nuget-exe-cli-reference.md#install)._ - -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 c5f03bd27..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 -- unnir -#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 1c64f6353..000000000 --- a/docs/Consume-Packages/Package-Restore.md +++ /dev/null @@ -1,297 +0,0 @@ ---- -# required metadata - -title: NuGet Package Restore | 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: 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 -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann -- unnir -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Installing and reinstalling packages with 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: - -- [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. - -## 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).| -| `Update-Package -reinstall -ProjectName ` | Restores a project's packages from the Package Manager Console. See [Update-Package reference](../tools/ps-ref-update-package.md). | - -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. | - -See [Automatic restore in Visual Studio](#automatic-restore-in-visual-studio) below for more details. - -## Enabling and disabling package restore - -Automatic restore and command-line restore is enabled by default with NuGet 2.7+. MSBuild-integrated restore and command-line restore is **not** enabled by default for NuGet 2.6 and earlier and must be enabled manually. - -Package restore is primarily enabled through **Tools > Options > [NuGet] Package Manager > General** 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. (For NuGet 2.6 or earlier, this setting can also be used in a project-specific `.nuget\Nuget.Config` file.) - - ```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). - -MSBuild-integrated restore with NuGet 2.6 and earlier is typically enabled by right-clicking a solution in Visual Studio and selecting **Enable NuGet Package Restore**. This sets up the necessary files and folders for this option to work, as explained under [MSBuild-integrated restore in Visual Studio](#msbuild-integrated-restore). - -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.6 and earlier, you use the [Install](../tools/nuget-exe-cli-reference.md#install) command and point to the `packages.config` file that lists all the dependencies. - -For NuGet 2.7 and above, use the [Restore](../tools/nuget-exe-cli-reference.md#restore) 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). - -In the [Package Manager Console](../tools/Package-Manager-Console.md) you can use the [`Update-Package`](../tools/ps-ref-update-package.md) command: - -```ps -# Restore packages for a project -Update-Package -reinstall -ProjectName - -# Restore packages for all projects in the solution -Update-Package -reinstall -``` - -Note that the `-reinstall` argument is what specifically instructs `Update-Package` to restore packages to their currently installed versions rather than updating any of those versions. - -## Automatic restore in Visual Studio - -With NuGet 2.7 and later, 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**. - -Automatic restore is also ignored if a `.nuget\NuGet.targets` file exists in a project, indicating that the project is configured for MSBuild-integrated restore. This can cause some errors as described below in [Automatic restore errors](#automatic-restore-errors). To update a project, see [Migrating to automatic restore](#migrating-to-automatic-restore). - -When enabled, automatic restore works as follows: - -1. A `.nuget` folder is created in the solution containing a `Nuget.Config` file that contains only a single setting for `disableSourceControlIntegration` (as described in [Packages and source control](../consume-packages/packages-and-source-control.md) for Team Foundation Version Control). -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. - -### Automatic restore errors - -If you're using NuGet 2.7 or later and have a solution that is still configured for MSBuild-integrated restore, you may have an older version of `nuget.exe` in the solution's `.nuget` folder. This will cause builds to fail with an error stating that you have not given consent to restore packages. - -To correct these errors, do one of the following: - -1. [Migrate the project to automatic restore](#migrating-to-automatic-restore). -1. Update `nuget.exe` in the `.nuget` folder** as follows - - ``` - cd .nuget - nuget update -self - ``` - -1. Reset consent in your `%AppData%\NuGet\NuGet.Config` file by going to **Tools > Options > NuGet Package Manager > General** in Visual Studio, clear and re-select both **Package Restore** options, and click OK. This re-saves `NuGet.Config` with the proper consent settings for NuGet 2.6 and earlier. - - -## MSBuild-integrated restore - -> [!Important] -> Although MS-Build integrated restore still works with NuGet 2.7 and later, we recommended that you [migrate to automatic restore](#migrating-to-automatic-restore) instead because it's simpler and more robust. - -As noted before, MSBuild-integrated restore with NuGet 2.6 and earlier is typically enabled by right-clicking a solution in Visual Studio and selecting **Enable NuGet Package Restore**. This has the following effects: - -- NuGet creates a `.nuget` folder in the solution containing `nuget.exe`, `Nuget.Config`, and `NuGet.targets` files. -- NuGet updates all projects in the solution to include a `true` flag and to import `NuGet.targets`. These cause MSBuild to invoke `nuget.exe` to restore packages before a build provided that the **Tools > Options > NuGet Package Manager > General > Allow NuGet to download missing packages** option is checked. - -Again, this option is **not** checked by default for NuGet 2.6 and earlier and must be manually set for package restore to work. For a custom build `.proj`, a pre build `` action must also be added manually to restore packages. - -With MSBuild-integrated restore, packages that are downloaded by Visual Studio will be automatically added to Team Foundation Version Control by default when the project is connected to a repository. To change this behavior, see [Omitting packages with Team Foundation Version Control](../consume-packages/packages-and-source-control.md#omitting-packages-with-team-foundation-version-control). - - -### Migrating to automatic restore - -Although the MSBuild-integrated restore approach works with NuGet 2.7 and later, it has several drawbacks: - -- It requires additional files within the solution folder. -- It requires importing a `.targets` file into all projects in the solution, which can introduce issues when projects are shared among multiple solutions. -- Projects will fail to load if `NuGet.targets` cannot be found. -- Projects won't build successfully if any of the restored NuGet packages extend MSBuild through a targets/props file import. -- Packages are automatically added to Team Foundation Version Control, when in use, unless specifically disabled. -- It is not compatible with ASP.NET web site projects created in Visual Studio. - -To avoid all these issues, it's recommended to migrate any project using MSBuild-integrated restore to use the automatic restore capabilities of NuGet 2.7 and above. - -The process is as follows: - -1. Close Visual Studio to avoid file potential file locks and conflicts. -1. If using Team Foundation Server (TFS): - 1. Remove `nuget.exe` and `NuGet.targets` from the solution's `.nuget` folder and remove those files from the solution workspace. - 1. Retain `Nuget.Config` with the `disableSourceControlIntegration` setting as explained in [Omitting packages with Team Foundation Version Control](../consume-packages/packages-and-source-control.md#omitting-packages-with-team-foundation-version-control). -1. If not using TFS: - 1. Remove the `.nuget` folder from the solution and the solution workspace. -1. Edit each project file in the solution, remove the `` element, and remove any references to the `NuGet.targets` file. Those settings generally appear as follows: - - ```xml - true - ... - - ... - - - This project references NuGet package(s) that are missing on this computer. Enable NuGet Package Restore to download them. For more information, see http://go.microsoft.com/fwlink/?LinkID=322105. The missing file is {0}. - - - - ``` - -> [!Tip] -> Owen Johnson has created a [PowerShell migration script](https://github.com/owen2/AutomaticPackageRestoreMigrationScript) that can work in many cases, but is used at your own risk. Be sure to commit your project to source control or make a backup before using it. - -To test the migration, do the following: - -1. Remove the `packages` folder from the solution. -1. Open the solution in Visual Studio and start a build. -1. Automatic restore should download and install each dependency package, without adding them to source control. - - -## 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). - -### Command-line restore wrapped in MSBuild - -With existing build servers and MSBuild-based projects, you can also choose to wrap the command line in a regular MSBuild project. This minimizes changes on the server and also provides built-in support for aggregated logging and error reporting. This differs from the usual MSBuild-integrated restore as it runs before any other build process happens, instead of as part of those other processes. - -Note that 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). 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 9591a9588..000000000 --- a/docs/Consume-Packages/Reinstalling-and-Updating-Packages.md +++ /dev/null @@ -1,118 +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 -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann -- unnir -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# 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 reference to working order. - -Being mindful of the [Considerations](#considerations) described later, 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 `-Project` 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. - -## 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. - -### 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 add 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. - -## Constraining upgrade versions - -By default, reinstalling or updating a package *always* installs the latest version available from the package source. - -In projects using `packages.config`, 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). 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/Creating-a-Package.md b/docs/Create-Packages/Creating-a-Package.md deleted file mode 100644 index 8c4690b18..000000000 --- a/docs/Create-Packages/Creating-a-Package.md +++ /dev/null @@ -1,462 +0,0 @@ ---- -# required metadata - -title: How to create a NuGet package | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 7/24/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 456797cb-e3e4-4b88-9b01-8b5153cee802 - -# optional metadata - -description: A detailed guide to the process of designing and creating a NuGet package, including key decision points like files and versioning. -keywords: NuGet package creation, creating a package, nuspec manifest, NuGet package conventions, NuGet package version -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann -- unnir -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- -# Creating NuGet packages - -No matter what your package does or what code it contains, NuGet is how you package that functionality into a component that can be shared with and used by any number of other developers. - -The packaging process begins with the compiled code (assemblies), symbols, and/or other files that you want to deliver as a package (see [Overview and workflow](Overview-and-Workflow.md). That is, creating a package is an independent process from compiling or otherwise generating the files that go into the package. That said, the packaging process can use information in a project file, helping you keep compiled assemblies and packages containing those assemblies in sync. - -This topic describes the detailed process of creating a package and serves as a reference for different aspects of that process. For a focused walkthrough, refer to [Create and Publish a Package Quickstart](../quickstart/create-and-publish-a-package.md). - -In this topic: - -- [Deciding which assemblies to package](#deciding-which-assemblies-to-package) -- [The role and structure of the `.nuspec` file](#the-role-and-structure-of-the-nuspec-file) -- [Creating the `.nuspec` file](#creating-the-nuspec-file) from: - - [An assembly DLL](#from-an-assembly-dll) - - [A Visual Studio project](#from-a-visual-studio-project) - - [A convention-based working directory](#from-a-convention-based-working-directory) -- [Choosing a unique package identifier and setting the version number](#choosing-a-unique-package-identifier-and-setting-the-version-number) -- [Setting a package type](#setting-a-package-type) (NuGet 3.5 and later) -- [Adding a readme and other files](#adding-a-readme-and-other-files) -- [Including MSBuild props and targets in a package](#including-msbuild-props-and-targets-in-a-package) -- [Creating the package](#creating-the-package) - -After these core steps, you can incorporate a variety of other features as described elsewhere in this documentation. See [Next steps](#next-steps) below. - -> [!Note] -> This topic applies to project types other than .NET Core projects using Visual Studio 2017 and NuGet 4.0+. In those .NET Core projects, NuGet uses information in the `.csproj` file directly. For details, see [Create .NET Standard Packages with Visual Studio 2017](../guides/create-net-standard-packages-vs2017.md) and [NuGet pack and restore as MSBuild targets](../schema/msbuild-targets.md). - -## Deciding which assemblies to package - -Most general-purpose packages contain one or more assemblies that other developers can use in their own projects. - -In general, it's best to have one assembly per NuGet package, provided that each assembly is independently useful. For example, if you have a `Utilities.dll` that depends on `Parser.dll`, and `Parser.dll` is useful on its own, then create one package for each. Doing so allows developers to use `Parser.dll` independently of `Utilities.dll`. - -However, if your library is composed of multiple assemblies that aren't independently useful, then it's fine to combine them into one package. Using the previous example, if `Parser.dll` contains code that's used only by `Utilities.dll`, then it's fine to keep `Parser.dll` in the same package. - -Similarly, if `Utilities.dll` depends on `Utilities.resources.dll`, where again the latter is not useful on its own, then put both in the same package. - -Resources are, in fact, a special case. When a package is installed into a project, NuGet automatically adds assembly references to the package's DLLs, *excluding* those that are named `.resources.dll` because they are assumed to be localized satellite assemblies (see [Creating localized packages](creating-localized-packages.md)). For this reason, avoid using `.resources.dll` for files that otherwise contain essential package code. - -## The role and structure of the .nuspec file - -Once you know what files you want to package, the next step is creating a `.nuspec` package manifest. The manifest is an XML file that describes the package's contents and is itself included in the package. The manifest both drives the creation of the package and instructs NuGet on how to install the package into a project. The manifest, for example, identifies other package dependencies such that NuGet can also install those dependencies when the main package is installed. - -The manifest contains both required and optional properties as described below. For exact details, including other properties not mentioned here, see the [.nuspec reference](../schema/nuspec.md). - -Required properties: -- The package identifier, which must be unique across the gallery that hosts the package. -- A specific version number in the form *Major.Minor.Patch.Build[-Suffix]* where *-Suffix* identifies [pre-release versions](Prerelease-Packages.md)- - The package title as it should appears on the host (like nuget.org) -- Author and owner information. -- A long description of the package. - -Common optional properties: -- Release notes -- Copyright information -- A short description for the [Package Manager UI in Visual Studio](../Tools/Package-Manager-UI.md) -- A locale ID -- Home page and license URLs -- An icon URL -- Lists of dependencies and references -- Tags that assist in gallery searches - -The following is a typical (but fictitious) `.nuspec` file, with comments describing the properties: - -```xml - - - - - Contoso.Utility.UsefulStuff - - - 1.8.3.331 - - - Dejana Tesic, Rajeev Dey - - - dejanatc, rjdey - - - http://opensource.org/licenses/MS-PL - http://github.com/contoso/UsefulStuff - - - http://github.com/contoso/UsefulStuff/nuget_icon.png - - - false - - - Bug fixes and performance improvements - - - Core utility functions for web applications - - - Copyright ©2016 Contoso Corporation - - - web utility http json url parsing - - - - - - - - - - - - -``` - -For details on declaring dependencies and specifying version numbers, see [Package versioning](../reference/package-versioning.md). - -Because the manifest is included in the package created from it, you can find any number of additional examples by examining existing packages. A good source is the global package cache on your machine, the location of which is returned by the following command: - -``` -nuget locals -list global-packages -``` - -Go into any *package\version* folder, copy the `.nupkg` file to a `.zip` file, then open that `.zip` file and examine the `.nuspec` within it. - -> [!Note] -> When creating a `.nuspec` from a Visual Studio project, the manifest contains tokens that are be replaced with information from the project when the package is built. See [Creating the .nuspec from a Visual Studio project](#from-a-visual-studio-project). - -## Creating the .nuspec file - -Creating a complete manifest typically begins with a basic `.nuspec` file, which you then edit by hand into its final form so that it describes the exact content you want in the final package. - -The best way to create an initial `.nuspec` file is by using the [nuget spec](../Tools/nuget-exe-CLI-Reference.md#spec) command to create a template manifest. This ensures that you start with the proper file structure. You can also start with a manifest from another package and modify it to suit your needs. - -With `nuget spec`, you can create a new file with default values, or you can create a file using information in an existing assembly DLL, a project file, or a convention-based working directory as explained in the following sections. - -> [!Important] -> Generated `.nuspec` files contain placeholders that must be modified before creating the package with the `nuget pack` command. That command fails if the `.nuspec` contains any placeholders. - -### New file with default values - -The following command creates a default manifest with placeholders: - -``` -nuget spec [] -``` - -If you omit ``, the resulting file is `Package.nuspec`. If you provide a name such as `Contoso.Utility.UsefulStuff`, the file is `Contoso.Utility.UsefulStuff.nuspec`. - -The resulting `.nuspec` contains placeholders for values like the `projectUrl`. Be sure to edit the file before using it to creating the package. - -You can also use `nuget spec` with an existing assembly, a Visual Studio project, or a convention-based working directory as described in the following sections. Note that in all cases, the resulting `.nuspec` file contains placeholders that you'll need to edit before creating the package itself. - -### From an assembly DLL - -If you have an assembly DLL, generate a `.nuspec` file from the metadata in the assembly using the following command: - -``` -nuget spec .dll -``` - -Using this form of the command replaces a few placeholders in the manifest with specific values from the assembly. For example, the `` property is set to the assembly name, and `` is set to the assembly version. Other properties in the manifest, however, don't have matching values in the assembly and thus still contain placeholders. - -### From a Visual Studio project - -Creating a `.nuspec` from a `.csproj` or `.vbproj` file is convenient because other packages that have been installed into those project are automatically referenced as dependencies. Simply use the following command in the same folder as the project file: - -``` -# Use in a folder containing a project file .csproj or .vbproj -nuget spec -``` - -The resulting `.nuspec` file contains *tokens* that are replaced at packaging time with values from the project, including references to any other packages that have already been installed. - -A token is delimited by `$` symbols on both sides of the project property. For example, the `` value in a manifest generated in this way typically appears as follows: - -```xml -$id$ -``` - -This token is replaced with the `AssemblyName` value from the project file at packing time. For the exact mapping of project values to `.nuspec` tokens, see the [Replacement Tokens reference](../schema/nuspec.md#replacement-tokens). - -Tokens relieve you from needing to update crucial values like the version number in the `.nuspec` as you update the project. (You can always replace the tokens with literal values, if desired). - -Note that there are several additional packaging options available when working from a Visual Studio project, as described in the [Creating the package](#creating-the-package) section later on. - -#### Solution-level packages - -*NuGet 2.x only. This capability is not present in NuGet 3.0+.* - -NuGet 2.x supported the notion of a solution-level package that installs tools or additional commands for the Package Manager Console, but does not add references, content, or build customizations to any projects in the solution. Such packages contain no files in its direct `lib`, `content`, or `build` folders, and none of its dependencies have files in their respective `lib`, `content`, or `build` folders. - -NuGet tracks installed solution-level packages in a `packages.config` file in the `.nuget` folder, rather than the project's `packages.config` file. - -### From a convention-based working directory - -Technically speaking, a NuGet package is just a ZIP file that's been renamed with the `.nupkg` extension and whose contents match certain conventions. The package's assembly DLLs, for instance, are always placed in a `lib` folder. - -The practical upshot of this is that you can simply create a folder structure that follows the expected conventions and contains all the files you want to include in the package *excluding any folders that begin with `.`*. You then generate a manifest directly from that folder tree. When you create the package using that manifest, NuGet automatically adds all the files in the folder structure. - -An advantage to this approach is that you don't need to edit the manifest to specifically identify which files you want to include in the package (as explained later in this topic). That is, when creating a manifest and package from the contents of a project tree, NuGet includes only the files that you specify in the manifest. Otherwise you'd risk including temporary build files, project files, `.gitignore` files, and so forth. - -When using a convention-based working directory, on the other hand, NuGet assumes that everything in the folder structure is exactly what you want in the final package (again excluding folders starting with `.`). You don't need to specifically reference any files in the manifest. - -Such a folder structure also allows you to easily include files that might not be part of a project at all, including: - -- Content and source code that should be injected into the target project. -- PowerShell scripts (packages used in NuGet 2.x can include installation scripts as well, which is not supported in NuGet 3.x and later). -- Transformations to existing configuration and source code files in a project. - -The folder conventions are as follows: - -| Folder | Description | Action upon package install | -| --- | --- | --- | -| (root) | Location for readme.txt | Visual Studio displays a readme.txt file in the package root when the package is installed. | -| lib | Assembly (`.dll`), documentation (`.xml`), and symbol (`.pdb`) files | Assemblies are added as references; `.xml` and `.pdb` copied into project folders. See [Supporting multiple target frameworks](Supporting-Multiple-Target-Frameworks.md) for creating framework target-specific sub-folders. | -| runtimes | Architecture-specific assembly (`.dll`), symbol (`.pdb`), and native resource (`.pri`) files | Assemblies are added as references; other files are copied into project folders. See [Supporting multiple target frameworks](Supporting-Multiple-Target-Frameworks.md). | -| content | Arbitrary files | Contents are copied to the project root | -| build | MSBuild `.targets` and `.props` files | Automatically inserted into the project file (NuGet 2.x) or `project.lock.json` (NuGet 3.x+). | -| tools | Powershell scripts and programs accessible from the Package Manager Console | Contents are copied to the project folder, and the `tools` folder is added to the PATH environment variable.| - -Think of the **content** folder as the root of the target application. To have the package add an image in the application's */images* folder, place it in the package's *content/images* folder. - -Next, from the root folder of this layout, run the following command to create the `.nuspec` file: - -``` -nuget spec -``` - -In this case, the `.nuspec` contains no explicit references to files in the folder structure. Again, NuGet automatically includes all files when the package is created. - -## Choosing a unique package identifier and setting the version number - -The package identifier (`` element) and the version number (`` element) are the two most important values in the manifest because they uniquely identify the exact code that's contained in the package. - -**Best practices for the package identifier:** - -- **Uniqueness**: The identifier must be unique across nuget.org or whatever gallery hosts the package. Before deciding on an identifier, search the applicable gallery to check if the name is already in use. To avoid conflicts, a good pattern is to use your company name as the first part of the identifier, such as `Contoso.`. -- **Namespace-like names**: Follow a pattern similar to namespaces in .NET, using dot notation instead of hyphens. For example, use `Contoso.Utility.UsefulStuff` rather than `Contoso-Utility-UsefulStuff` or `Contoso_Utility_UsefulStuff`. Consumers also find it helpful when the package identifier matches the namespaces used in the code. -- **Sample Packages**: If you produce a package of sample code that demonstrates how to use another package, attach `.Sample` as a suffix to the identifier, as in `Contoso.Utility.UsefulStuff.Sample`. (The sample package would of course have a dependency on the other package.) When creating a sample package, use the convention-based working directory method described earlier. In the `content` folder, arrange the sample code in a folder called `\Samples\` as in `\Samples\Contoso.Utility.UsefulStuff.Sample`. - -**Best practices for the package version:** - -- In general, set the version of the package to match the library, though this is not strictly required. This is a simple matter when you limit a package to a single assembly, as described earlier in [Deciding which assemblies to package](#deciding-which-assemblies-to-package). Overall, remember that NuGet itself deals with package versions when resolving dependencies, not assembly versions. -- When using a non-standard version scheme, be sure to consider the NuGet versioning rules as explained in [Package versioning](../reference/package-versioning.md). - -> The following series of brief blog posts are also helpful to understand versioning: -> -> - [Part 1: Taking on DLL Hell](http://blog.davidebbo.com/2011/01/nuget-versioning-part-1-taking-on-dll.html) -> - [Part 2: The core algorithm](http://blog.davidebbo.com/2011/01/nuget-versioning-part-2-core-algorithm.html) -> - [Part 3: Unification via Binding Redirects](http://blog.davidebbo.com/2011/01/nuget-versioning-part-3-unification-via.html) - - -## Setting a package type - -With NuGet 3.5+, packages can be marked with a specific *package type* to indicate its intended use. Packages not marked with a type, including all packages created with earlier versions of NuGet, default to the `Dependency` type. - -- `Dependency` type packages add build- or run-time assets to libraries and applications, and can be installed in any project type (assuming they are compatible). - -- `DotnetCliTool` type packages are extensions to the [.NET CLI](https://docs.microsoft.com/dotnet/articles/core/tools/index) and are invoked from the command line. Such packages can be installed only in .NET Core projects and have no effect on restore operations. More details about these per-project extensions are available in the [.NET Core extensibility](https://docs.microsoft.com/dotnet/articles/core/tools/extensibility#per-project-based-extensibility) documentation. - - When a DotnetCliTool package is installed, Visual Studio places the package in the `project.json` `tools` node instead of the `dependencies` node. - -- Custom type packages use an arbitrary type identifier that conforms to the same format rules as package IDs. Any type other than `Dependency` and `DotnetCliTool`, however, are not recognized by the NuGet Package Manager in Visual Studio. - -Package types are set either in the `.nuspec` file or in `project.json`. In both cases, it's best for backwards compatibility to *not* explicitly set the `Dependency` type and to instead rely on NuGet assuming this type when no type is specified. - -- `.nuspec`: Indicate the package type within a `packageTypes\packageType` node under the `` element: - - ```xml - - - - - - - - - - ``` - -- `project.json`: Indicate the package type within a `packOptions.packageType` property json: - - ```json - { - // ... - "packOptions": { - "packageType": "DotnetCliTool" - } - } - ``` - -## Adding a readme and other files - -To directly specify files to include in the package, use the `` node in the `.nuspec` file, which *follows* the `` tag: - -```xml - - - - - - - - - - - - - -``` - -> [!Tip] -> When using the convention-based working directory approach, you can place the readme.txt in the package root and other content in the `content` folder. No `` elements are necessary in the manifest. - -When you include a file named `readme.txt` in the package root, Visual Studio displays the contents of that file as plain text immediately after installing the package directly. (Readme files are not displayed for packages installed as dependencies). For example, here's how the readme for the HtmlAgilityPack package appears: - -![The display of a readme file for a NuGet package upon installation](media/Create_01-ShowReadme.png) - -> [!Note] -> If you include an empty `` node in the `.nuspec` file, NuGet doesn't include any other content in the package other than what's in the `lib` folder. - -## Including MSBuild props and targets in a package - -In some cases, you might want to add custom build targets or properties in projects that consume your package, such as running a custom tool or process during build. You do this by placing files in the form `.targets` or `.props` (such as `Contoso.Utility.UsefulStuff.targets`) within the `\build` folder of the project. - -Files in the root `\build` folder are considered suitable for all target frameworks. To provide framework-specific files, first place those within appropriate subfolders, such as the following: - - \build - \netstandard1.4 - \Contoso.Utility.UsefulStuff.props - \Contoso.Utility.UsefulStuff.targets - \net462 - \Contoso.Utility.UsefulStuff.props - \Contoso.Utility.UsefulStuff.targets - -Then in the `.nuspec` file, be sure to refer to these files in the `` node: - -```xml - - - - - - - - - - - - - -``` - -When NuGet 2.x installs a package with `\build` files, it adds an MSBuild `` elements in the project file pointing to the `.targets` and `.props` files. (`.props` is added at the top of the project file; `.targets` is added at the bottom.) - -With NuGet 3.x, targets are not added to the project but are instead made available through the `project.lock.json`. - - -## Creating the package - -When using an assembly or the convention-based working directory, create a package by running `nuget pack` with your `.nuspec` file, replacing `` with your specific filename: - -``` -nuget pack .nuspec -``` - -When using a Visual Studio project, run `nuget pack` with your project file, which automatically loads the project's `.nuspec` file and replaces any tokens within it using values in the project file: - -``` -nuget pack .csproj -``` - -> [!Note] -> Using the project file directly is necessary for token replacement because the project is the source of the token values. Token replacement does not happen if you use `nuget pack` with a `.nuspec` file. - - -In all cases, `nuget pack` excludes folders that start with a period, such as `.git` or `.hg`. - -NuGet indicates if there are any errors in the `.nuspec` file that need correcting, such as forgetting to change placeholder values in the manifest. - -Once `nuget pack` succeeds, you have a `.nupkg` file that you can publish to a suitable gallery as described in [Publishing a Package](../create-packages/publish-a-package.md). - -> [!Tip] -> A helpful way to examine a package after creating it is to open it in the [Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer) tool. This gives you a graphical view of the package contents and its manifest. You can also rename the resulting `.nupkg` file to a `.zip` file and explore its contents directly. - - -### Additional options - -You can use various command-line switches with `nuget pack` to exclude files, override the version number in the manifest, and change the output folder, among other features. For a complete list, refer to the [pack command reference](../tools/nuget-exe-cli-reference.md#pack). - -The following options are a few that are common with Visual Studio projects: - -- **Referenced projects**: If the project references other projects, you can add the referenced projects as part of the package, or as dependencies, by using the `-IncludeReferencedProjects` option: - - ``` - nuget pack MyProject.csproj -IncludeReferencedProjects - ``` - - This inclusion process is recursive, so if `MyProject.csproj` references projects B and C, and those projects reference D, E, and F, then files from B, C, D, E, and F are included in the package. - - If a referenced project includes a `.nuspec` file of its own, then NuGet adds that referenced project as a dependency instead. You need to package and publish that project separately. - -- **Build configuration**: By default, NuGet uses the default build configuration set in the project file, typically *Debug*. To pack files from a different build configuration, such as *Release*, use the `-properties` option with the configuration: - - ``` - nuget pack MyProject.csproj -properties Configuration=Release - ``` - -- **Symbols**: to include symbols that allow consumers to step through your package code in the debugger, use the `-Symbols` option: - - ``` - nuget pack MyProject.csproj -symbols - ``` - -## Next Steps - -Once you've created a package, which is a `.nupkg` file, you can publish it to the gallery of your choice as described on [Publishing a Package](../create-packages/publish-a-package.md). - -You might also want to extend the capabilities of your package or otherwise support other scenarios as described in the following topics: - -- [Package versioning](../reference/package-versioning.md) -- [Supporting multiple target frameworks](../create-packages/supporting-multiple-target-frameworks.md) -- [Transformations of source and configuration files](../create-packages/source-and-config-file-transformations.md) -- [Localization](../create-packages/creating-localized-packages.md) -- [Pre-release versions](../create-packages/prerelease-packages.md) - -Finally, there are additional package types to be aware of: - -- [Native Packages](../create-packages/native-packages.md) -- [Symbol Packages](../create-packages/symbol-packages.md) 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 d3e00c7fb..000000000 --- a/docs/Create-Packages/Overview-and-Workflow.md +++ /dev/null @@ -1,60 +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.service: -ms.technology: null -ms.assetid: 3c60f920-457d-4f43-9efe-210c514e5242 - -# 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. -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann -- unnir -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- -# 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 dfb92170c..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 -- unnir -#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 67eff2be7..000000000 --- a/docs/Create-Packages/Publish-a-package.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -# required metadata - -title: How to Publish a NuGet Package | 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: 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 -- unnir -#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, or push to nuget.org from the command line: - -- Web portal: use the Upload Package tab on nuget.org: - - ![Upload a package with the NuGet Package Manager](media/publish_UploadYourPackage.PNG) - -- Command line: - 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) - - -## 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 c878b0b0e..000000000 --- a/docs/Create-Packages/Supporting-Multiple-Target-Frameworks.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -# required metadata - -title: Multi-targeting for 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: 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 -- unnir -#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, you place its files in the `lib` folder of your project. - -When specifically targeting multiple frameworks, you instead 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). - -If you also have a version of the library that is not specific to a framework, place it in the root `lib` folder. - -For example, the following folder structure supports five versions of an assembly, four that are framework-specific and one that is not: - - \lib - MyAssembly.dll - \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, using an assembly in the root `lib` folder, if present, as the fallback. - -For example, consider the following folder structure in a package: - - \lib - \MyAssembly.dll - \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 installs the assembly in the root `lib` folder. - -## 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. - -The rule about copying assemblies from only one folder also applies to the root `lib` folder. Suppose a package has the following folder structure: - - \lib - \MyAssembly.dll (v1.0) - \MyAssembly.Core.dll (v1.0) - \Net45 - \MyAssembly.dll (v2.0) - -In projects that target .NET Framework 4.0 and earlier, NuGet copies both `MyAssembly.dll` (v1.0) and `MyAssembly.Core.dll` (v1.0) because their location in the package does not restrict them to a specific target. In projects that target .NET Framework 4.5, however, only `MyAssembly.dll` (v2.0) from the `net45` folder is copied. Again, to include `MyAssembly.Core.dll` for .NET Framework 4.5, place a copy of it 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 file support and script execution is available in NuGet 2.x, but deprecated in NuGet 3.x and later. - -With NuGet 2.x, 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 4552ca0af..000000000 --- a/docs/Create-Packages/Symbol-Packages.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -# required metadata - -title: How to create NuGet symbol packages | 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: 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 -- unnir -#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 https://nuget.smbsrc.net/ to their symbol sources in Visual Studio. This allows consumers to step into your package code in the Visual Studio debugger. - -## 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 - -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 symbolsource.org (https://nuget.smbsrc.net/), after it publishes the primary package to nuget.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 1846773a4..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 -- unnir -#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 c9f9a8f88..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 -- unnir -#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) \ No newline at end of file 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 4876e890f..000000000 --- a/docs/Guides/Create-NET-Standard-Packages-VS2017.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -# required metadata - -title: Create .NET Standard 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 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 -- unnir -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Create .NET standard packages with Visual Studio 2017 - -*Applies to NuGet 4.x+ and MSBuild 15.1+ as provided with Visual Studio 2017. 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 1.4 with Visual Studio 2017 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 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\netstandard1.4` 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 - - netstandard1.4 - 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+ 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 c61161bf3..000000000 --- a/docs/Guides/Create-UWP-Controls.md +++ /dev/null @@ -1,201 +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 -- unnir -#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) - ManagedPackage - - - - -``` - -## 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 2dc37eeec..000000000 --- a/docs/Guides/Install-NuGet.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -# required metadata - -title: Installing NuGet | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 7/17/2017 -ms.topic: get-started-article -ms.prod: nuget -#ms.service: -ms.technology: null -ms.assetid: 683b8b34-a6f4-4d56-b9cd-2483bfbad1ad - -# optional metadata - -description: Guidance on installing the NuGet command-line interface (CLI) and the NuGet Package Manager for Visual Studio. -keywords: nuget.exe CLI, NuGet package manager, NuGet package manager console, NuGet for Visual Studio, NuGet beta channel -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann -- unnir -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Installing NuGet - -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 -- Replication 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 - -On Windows, install the NuGet CLI using any of the following methods: - -1. **nuget.org**: Various versions of `nuget.exe` are available on [nuget.org/downloads](https://nuget.org/downloads). Each download link points directly to an `.exe` file, so be sure to right-click and save the file to your computer rather than running it from the browser. If desired, add the save location to your PATH environment variable so you can use NuGet from anywhere. - - > [!Note] - > With NuGet 1.4+, you can use `nuget update -self` to update your existing nuget.exe to the latest version. - -1. **Chocolatey**: Install the [NuGet.CommandLine](http://chocolatey.org/packages/NuGet.CommandLine) Chocolatey package using the [Chocolatey](http://chocolatey.org) client. - - ``` - choco install nuget.commandline - ``` - -1. **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: - -1. 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. - -1. 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)). - -> [!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, 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 earlier versions of Visual Studio, 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 d8c7d2b0f..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 -- unnir -#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/nuget-exe-cli-reference.md#sources) 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/nuget-exe-cli-reference.md#add) 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/nuget-exe-cli-reference.md#init) 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 2dcb08072..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 -- unnir -#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 39187ec87..000000000 --- a/docs/Hosting-Packages/Overview.md +++ /dev/null @@ -1,51 +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 -- unnir -- 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. - -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/nuget-exe-cli-reference.md#sources). 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 b91f03d5e..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 -- unnir -#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 dd87d784e..000000000 --- a/docs/Policies/NuGet-FAQ.md +++ /dev/null @@ -1,245 +0,0 @@ ---- -# required metadata - -title: NuGet Frequently-Asked Questions | 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: 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 -- unnir -#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) - -## 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 - -**Is it possible to reserve names for packages that will be published in future?** - -No. If you feel that an existing package has taken the name which suits your package better, try contacting the owner of the package (select on the owner name on the package page on nuget.org). If you don't get a response within a reasonable time, [contact support](https://www.nuget.org/policies/Contact) and we'll look into it. - -**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. - -**Can I edit package information after it's been uploaded?** - -Yes, in fact, you first get an opportunity to edit package metadata during the upload process. When you upload a package, the NuGet gallery performs some static analysis and indicates issues. If the package is accepted, you see a page that allows you to edit any of the metadata before the package is added to the gallery. - -For a package already in the gallery, sign into nuget.org, select on your username, select **Manage my packages**, then select the package you want to manage. From that page, select **Edit Package** on the left-hand side and make the desired changes to the metadata. - -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 check your package and test the editing process without making a package available in the public gallery. - -**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 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 52bfada50..000000000 --- a/docs/Quickstart/Create-and-Publish-a-Package.md +++ /dev/null @@ -1,178 +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: 1/9/2017 -ms.topic: get-started-article -ms.prod: nuget -#ms.service: -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 -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann -- unnir -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# 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: - -- [Install pre-requisites](#install-pre-requisites) -- [Create a class library project](#create-a-class-library-project) -- [Create the .nuspec package manifest file](#create-the-nuspec-package-manifest-file) -- [Create the package](#create-the-package) -- [Publish the package](#publish-the-package) - -## Install 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. -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 a class library project - -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. - -![Create new class library project](media/QS_Create-01-NewProject.png) - -Right-click on the resulting project file and select **Build** to make sure the project was created properly. - -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 CLI creates this file for you, which you then customize. - -1. Open a command prompt and navigate to the folder containing the AppLogger project file (`.csproj`). -1. Run the NuGet CLI `spec` command to generate `AppLogg.nuspec`: - - ``` - nuget spec - ``` - -1. Open the file in your favorite text editor. It will look something like the code below, where tokens in the form *$``$* will 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 will 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. - -## Create the package - -Creating a NuGet package from a project is simple: just run the `pack` command: - -``` -nuget pack AppLogger.csproj -``` - -This creates a NuGet package file like `AppLogger.1.0.0.0.nupkg` using the package name and version number from the `.nuspec` file. - -Note that you'll get warnings if you haven't updated various fields in the `.nuspec` file from their default values. - - -## Publish the package - -You're now ready to publish the package to nuget.org using the NuGet CLI. (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. When creating a new account, you'll receive a confirmation email . You must confirm the account before you can upload a package. -1. Once logged in, click your user name (on the upper right) to navigate to your account settings. -1. Under **API Key**, click **copy to clipboard** 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] -> Always keep your API key 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, replacing the key with the value copied in step 3: - - ``` - nuget push AppLogger.1.0.0.0.nupkg 47be3377-c434-4c29-8576-af7f6993a54b -Source https://www.nuget.org/api/v2/package - ``` - -1. You should then see something like the following: - - ``` - 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. 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 that time your package page will show 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 created and 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 13065bd19..000000000 --- a/docs/Quickstart/Use-a-Package.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -# required metadata - -title: Introductory Guide to Using NuGet Packages | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 8/25/2017 -ms.topic: get-started-article -ms.prod: nuget -#ms.service: -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: NuGet package consumption, installing NuGet packages, NuGet package references, using NuGet packages -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann -- unnir -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - - -# Use a package - -This tutorial walks you through installing and using the popular [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json/) package in a Universal Windows Platform (UWP) project. You use a similar same workflow for virtually every NuGet package you use in a project. - -- [Install pre-requisites](#install-pre-requisites) -- [Create a UWP project](#create-a-uwp-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 UWP project - -In Visual Studio, choose **File > New > Project**, expand **Visual C# > Windows > Universal**, select the **Blank App (Universal Windows)**, and click OK. Accept the default values for Target Version and Minimum Version when prompted. - -![Creating a new UWP project](media/QS_Use-01-NewProject.png) - -## Add the Newtonsoft.Json NuGet package - -1. In Solution Explorer, right click on **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**, click the **Browse** tab, search for **Newtonsoft.Json**, select that package in the list, and click **Install**: - - ![Locating Newtonsoft.Json package](media/QS_Use-03-NewtonsoftJson.png) - -1. If prompted to review changes, click OK. - -1. Right-click the solution in Solution Explorer and click **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 MainPage.xaml and replace the existing `Grid` element with the following: - - ```xaml - - -