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 b/LICENSE index 324695d03..3de968b27 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2016 NuGet +Copyright (c) .NET Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal 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 e1a77074b..36a0aa314 100644 --- a/README.md +++ b/README.md @@ -1,38 +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. -## Respository structure +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. -- 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. +## Repository structure + +- All markdown files are in the `docs` folder and various subfolders. +- The `docs/index.md` file defines the landing (hub) page as it appears 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](docs.microsoft.com/nuget), then click the **Edit** button on the top right. This brings you to the appropriate markdown page in the repo. +1. Visit the page to edit in [NuGet documentation](https://learn.microsoft.com/nuget/), then click the **Edit** button on the top right. This brings you to the appropriate markdown page in the repo. 1. Edit the markdown: 1. If you're including images (use PNGs, generally), place them in the media folder that's in the topic's folder. Links are then `media/.png`. - 1. Relative links to other pages in this docset should be in the form `..//.md` including the training `.md`. If you're linking to another topic in the same folder, then `..//` can be omitted. When using anchors, always remember to include the `.md` before the `#`. - 1. When using external links, especially to docs.microsoft.com or msdn.microsoft.com, 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 @@ -40,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". @@ -57,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. @@ -77,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. @@ -91,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 @@ -109,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. \ No newline at end of file +- 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 29609051f..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: nuget - -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 e610b11a4..000000000 --- a/docs/Consume-Packages/Configuring-NuGet-Behavior.md +++ /dev/null @@ -1,269 +0,0 @@ ---- -# required metadata - -title: Configuring the behavior of NuGet | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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` will use 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 and later) 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 2.7 and later) The "defaults" file 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. - -> [!Note] -> The `%ProgramData%\NuGet` folder typically requires Administrator permissions to modify. Administrators are expected to set the correct permissions on this folder 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. - -```bash -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 will make 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: - -```bash -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` 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 will be used. This means that those settings that are "closest" to where NuGet was invoked will be 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 and later) - %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 - -### 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: - -1. Global configuration file, `%APPDATA%\NuGet\Nuget.Config`: - - ```xml - - - - - - - ``` - -1. `d:\NuGet.Config`: - - ```xml - - - - - - - - - - ``` - -1. `d:\Project1\NuGet.Config`: - - ```xml - - - - - - - - - - - - ``` - -1. `d:\Project2\NuGet.Config`: - - ```xml - - - - - - - - ``` - -Here's how NuGet will load 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**: (A) is loaded first, then NuGet goes to the root of `d:` and finds (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**: (A) is loaded first, then NuGet loads (B) from the `d:` root, followed by (C). Settings in (C) override those in (B) and (A), so the `repositoryPath` where packages get installed will be `d:\Project1\External\Packages` instead of `d:\tmp`. Also, because (C) clears ``, nuget.org will no longer be available a source leaving only `https://MyPrivateRepo/ES/nuget`. - -- **Invoked from d:\Project2 or d:\Project2\Source**: (A) is loaded first followed by (B) and (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 uses a hardcoded default package source, nuget.org, that the user could not delete. 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 and later, you can use the `%PROGRAMDATA%\NuGet\NuGetDefaults.Config` file to control certain machine-wide defaults described below. This provides administrators a convenient way to deploy (using Group Policy, for example) 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 will not use nuget.org as a default package source. An administrator can thus make sure that everyone using this file will be 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 will never cause 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 68223d810..000000000 --- a/docs/Consume-Packages/Dependency-Resolution.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -# required metadata - -title: NuGet Package Dependency Resolution | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 2/8/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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 will be used. - -The exact process differs between NuGet 2.x (using `packages.config`) and NuGet 3.x (using `project.json`) as described in the sections below. - -In some cases, such as when there's a conflict between a dependency specified in one project and an assembly that's produced by another, it might be necessary to explicitly exclude a reference. The section [Excluding references](#excluding-reference) below. - -## Dependency resolution in NuGet 2.x - -With NuGet 2.x, a project's dependencies are written to the `packages.config` file as a flat list. Any dependencies of those packages are also written in the same list, and NuGet might also modify `.csproj` file and possibly also `app.config`, `web.config`, and other individual files. - -NuGet 2.x will attempt to resolve dependency conflicts during the installation of each individual package, which includes package restore. 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 will compare the versions of Package B being requested and attempt to find a version that will satisfy all version constraints. Specifically, NuGet will select 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](../release-notes/nuget-2.8.md#patch-resolution-for-dependencies) changes this behavior to look for the lowest patch version by default, and allows you to control this setting through the `DependencyVersion` attribute in `Nuget.Config` and the `-DependencyVersion` switch on the command line. - -On the downside, the NuGet 2.x process for resolving dependencies gets complicated for larger dependency graphs. This is especially true during package restore, because each new package installation requires a traversal of the whole graph and raises the chance for version conflicts. When a conflict occurs, package restoration is stopped, leaving the project in a partially-restored state, especially with potential modifications to the project file itself. - -This and other challenges is why dependency resolution was overhauled in NuGet 3.x, as described in the next section. - -## Dependency resolution in NuGet 3.x - -As dependencies are installed into a project, NuGet 3.x adds them to a flat package graph in `project.json` in which conflicts are resolved ahead of time. This is referred to as *transitive restore*. Reinstalling or restoring packages is then simply a process of downloading the packages listed in the graph, resulting in faster and more predictable builds. - -> [!Note] -> `project.json` is mandatory for UWP apps and ASP.NET 5 apps, is optional for PCLs, and currently is not fully supported on other project systems. - - -### Advantages of transitive restore - -1. Developers explicitly declare which package versions they depend on, without worrying about their down-level dependencies. -1. Project files are not modified, avoiding merge conflicts and file churn on commits. This also allows the project system to evolve independent of NuGet. -1. Developers can easily change dependency versions without worrying about side effects on the rest of the project. -1. Hint paths are not being burned into the project files, fixing the ability to move projects around on disk, and re-targeting problems. -1. Direct support for Native or special dependencies can be determined directly by the project system. This is related to a new package format in NuGet 3.x. -1. Developers can specify a floating version range such as *2.8.\**, avoiding expensive and error prone calls to NuGet update on the client machines and build servers. - -### Lock file and MSBuild - -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.lock.json` alongside `project.json`. MSBuild then reads this file and translates it into a set of folders where potential references can be found, and then adds them to the project tree in memory. - -The lock file is temporary and does not need to be added to source control; it's listed by default in both `.gitignore` and `.tfignore`. - - -### Dependency resolution rules - -NuGet 3.x applies four main rules to resolve dependencies: lowest applicable version, floating versions, nearest-wins, cousin dependencies. - - - -#### Lowest applicable version - -NuGet 3.x restores the lowest possible version of a package as defined by its dependencies. This rule also applied to dependencies on the application or the class library unless declared as [floating](#floating-versions). - -For example, in the following figure *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 will pick 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 will fail 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 versions - -A floating dependency version is specified with the * wildcard, as with *6.0.\** in the `project.json` file. This says "use the latest 6.0.x version"; a floating version of *4.\** means "use the latest 4.x version." Using a floating version allows a dependency package to continue evolving without requiring a change to the consuming application (or package). - -When a floating version constraint is specified then NuGet will resolve the highest version of a package that matches the version pattern, for example *6.0.** will get 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) - - - -#### Nearest wins - -When the package graph for an application contains different versions of the same package, the package that's closest to the application in the graph will be used and others will be ignored. This 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] -> Applying the Nearest Wins rule can downgrading the package version, thus potentially breaking other dependencies in the graph. This currently produces an error, although we are considering making it a warning instead. See [issue #897 on GitHub](https://github.com/NuGet/Home/issues/897). - -This rule also results in greater efficiency with large dependency graph (such as those with the BCL packages) because by 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 will be used, NuGet can ignore 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 will satisfy the other *>=1.0* constraint, and will thus be 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 required exactly Package B *1.0* and Package C requires Package B *>=2.0*, then NuGet cannot resolve the dependencies and will give 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. - -# 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. For example, consider a project that contains a custom version of `C.dll`, and references packageC that also contains `C.dll`. At the same time, the project also depends on packageB which also depends on packageC and `C.dll`. As a result, NuGet won't be able to determine which `C.dll` to use, but you can't just remove the project's dependency on packageC because packageB 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 packageC that excludes all its assets. This is done as follows: - -* If you're project is using `packages.config` for tracking NuGet dependencies, simply remove the reference to packageC from the `.csproj` file so that it references only the version of `C.dll` that you want. - -* If your project uses `project.json` for NuGet, add `"exclude" : "all"` in the dependency for packageC: - - ```json - { - "dependencies": { - "packageC": { - "version": "1.0.0", - "exclude": "all" - } - } - } - ''' - -* With [package references in project files](../consume-packages/package-references-in-project-files.md) (NuGet 4.0+ only), add `Exclude="All"` in the dependency: - - ```xml - - ``` 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 7c8af4891..000000000 --- a/docs/Consume-Packages/Finding-and-Choosing-Packages.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -# required metadata - -title: Finding and choosing NuGet Packages | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 2/8/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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" will list 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 will install 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 will issue 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 will show 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). - -### 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 obviously indicates 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 will have recent updates, and will have a rich version history. Neglected packages will 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, click **Package Statistics** on the left side. This will show you the package installs for the last six weeks. A package with more current use is obviously a better choice than one without. -- *Restore vs. new install*: on the same package statistics page, clear the **Version** checkbox and check **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, click **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, click 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 an open-source repository, making it possible for developers depending on it 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*: all this is not to say that new developers are not equally committed to producing great packages for you to use, and it's certainly good to give them a chance to bring something new to the NuGet ecosystem. With this in mind, you can always talk directly to the package developers through the **Contact Owners** option on the listing page. Chances are, they'll be happy to work directly with you to serve your needs! - -> [!Note] -> Always be mindful of a package's license terms, which you can see by clicking **License** on a package's listing page on nuget.org. - -> [!Note] -> Every package that is uploaded to nuget.org is scanned for viruses. All packages listed on nuget.org are also scanned periodically. - -## 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 will look for relevant packages that contain with all of the provided keywords. Example: - - modern UI javascript - -- **Phrases**: Entering terms within quotation marks will look for exact matches to those terms (case-insensitive). 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 634c1da8a..000000000 --- a/docs/Consume-Packages/Managing-the-NuGet-Cache.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -# required metadata - -title: How to manage package caching in NuGet | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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 machine, and to provide offline support. NuGet versions 2.8 and later automatically fall back to the cache when installing or reinstalling packages without a network connection. - -To see the list of cache locations, use the [locals command](../tools/nuget-exe-cli-reference.md#locals): - -```bash -nuget locals all -list -``` - -Typical output is as follows: - - http-cache: C:\Users\user\AppData\Local\NuGet\v3-cache #3.x cache - packages-cache: C:\Users\user\AppData\Local\NuGet\Cache #2.x cache - global-packages: C:\Users\user\.nuget\packages\ #Global cache - 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 the remote gallery, use the `locals -clear` option in one or more of the following ways: - -```bash -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 cache -nuget locals temp -clear #Clear the temporary cache -nuget locals all -clear #Clears 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 5b1f3ae15..000000000 --- a/docs/Consume-Packages/Overview-and-Workflow.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -# required metadata - -title: Overview and workflow of using NuGet 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: nuget -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` or `project.json` in your project root, depending on project type. With NuGet 4.0+ and .NET Core projects, dependencies are instead stored in the project file directly. See [Package References in Project Files](../consume-packages/package-references-in-project-files.md). 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). - -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 `packages.config` or `project.json` to reinstall all dependencies. Note that there are differences in the process between NuGet 2.x and 3.x+, which are 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 21664ffbe..000000000 --- a/docs/Consume-Packages/Package-References-in-Project-Files.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -# required metadata - -title: NuGet PackageReference in Visual Studio Project Files | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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 in .NET Core and .NET Standard project files, without needing a separate `packages.config` or `project.json` file. This approach also 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, it is the same as using `project.json`. - -> [!Note] -> Package references are currently supported for only .NET Core and .NET Standard projects in Visual Studio 2017. - -## Adding a PackageReference - -You can add a dependency in your project file using the following syntax: - -```xml - - - - 3.6.0 - - - -``` - -or, alternately: - -```xml - - - - - -``` - -## Controlling dependency version - -The convention for specifying version remains unchanged: - -```xml - - - - 3.6.0 - - - -``` - -In the example above, 3.6.0 means any version that is >=3.6.0 with preference for the lowest version, as described on [version ranges](../create-packages/dependency-versions.md#version-ranges). - -## Floating Versions - -[Floating versions](../consume-packages/dependency-resolution.md#floating-versions) are supported with `PackageReference`: - -```xml - - - - 3.6.* - - - - 3.6.0-beta* - - - -``` - -## 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 `PrivateAsset`, 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. - -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 - - - - 9.0.1 - - - -``` - -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](media/PackageReference-Condition.png) - -Conditions can also be applied at the `ItemGroup` level and will apply to all children `PackageReference` elements: - -```xml - - - - - 9.0.1 - - - - - - -``` diff --git a/docs/Consume-Packages/Package-Restore.md b/docs/Consume-Packages/Package-Restore.md deleted file mode 100644 index 16a05a56e..000000000 --- a/docs/Consume-Packages/Package-Restore.md +++ /dev/null @@ -1,245 +0,0 @@ ---- -# required metadata - -title: NuGet Package Restore | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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: - -- [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) - -To check your NuGet version, simply run `nuget.exe` on the command line and look at the first line of output. - -It's best to avoid mixing the automatic and MSBuild-integrated restore methods for a single project. We instead recommend [migrating to automatic restore](#migrating-to-automatic-restore). - -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. - -## Enabling and disabling package restore - -Automatic restore and command-line restore is enabled by default with NuGet 2.7 and later. 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**: enables 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**: enables 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 either `packages.config` or `project.json`: - -- `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)" - ``` - -In both cases, use the notation described in [Dependency versions](../create-packages/dependency-versions.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 (using either `packages.config` in NuGet 2.x and later or `project.json` in NuGet 3.x and later). For a given project folder such as `c:\proj\app`, the common variations below each restore the packages: - -```bash -c:\proj\app\> nuget restore -c:\proj\app\> nuget.exe restore app.sln -c:\proj\> nuget restore app -``` - -## 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). -2. When a build begins, Visual Studio instructs NuGet to restore packages. -3. NuGet recursively looks for all `packages.config` files in the solution (NuGet 2.x), or looks for `project.json` (NuGet 3.x). -4. For each packages listed in the configuration files, NuGet checks if it exists in the solution's `packages` folder. -5. 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 downloads the package from the enabled sources as listed in **Tools > Options > [NuGet] Package Manager > Package Sources**, in the order that the sources appear. -6. If the download is successful, NuGet caches it, and then installs the package into the `packages` folder; otherwise NuGet fails and the build fails. - -During this process, developers 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 - - ```bash - 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 - -> [!Note] -> 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, 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 this 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 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](#commandline-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. diff --git a/docs/Consume-Packages/Packages-and-Source-Control.md b/docs/Consume-Packages/Packages-and-Source-Control.md deleted file mode 100644 index 95349976d..000000000 --- a/docs/Consume-Packages/Packages-and-Source-Control.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -# required metadata - -title: NuGet Packages and Source Control | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -ms.assetid: 2c874e6f-99eb-46dd-997f-f67d98d0237e - -# optional metadata - -description: Considerations for how to treat NuGet packages within version control and source control systems, and how to omit packages with git and TFVC. -keywords: NuGet source control, NuGet version control, NuGet and git, NuGet and TFS, NuGet and TFVC, omitting packages, source control repositories, version control repositories -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann -- unnir -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- - -# Omitting NuGet packages in source control systems - -Developers typically omit binaries, such as NuGet packages, from their source control repository and rely instead on [package restore](../consume-packages/package-restore.md) to reinstall a project's dependencies before doing a build. - -The reasons for doing so include the following: - -1. Distributed version control systems, such as Git, include full copies of every version of every file within the repository. Binary files that are frequently updated will lead to significant bloat and lengthens the time it takes to clone the repository. -1. When packages are included in the repository, developers are liable to add references directly to package contents on disk rather than referencing packages through NuGet, which can lead to hard-coded path names in the project. -1. It becomes harder to "clean" your solution of any unused package folders, as you need to ensure you don't delete any package folders still in use. -1. By omitting packages, you maintain clean boundaries of ownership between your code and the packages from others that you depend upon. Many NuGet packages are maintained in their own source control repositories already. - -Note that although package restore is the default behavior with NuGet, some manual work is necessary to omit packages (the `packages` folder in your project) from source control, as described in the following sections. - -## Omitting packages with Git - -Use the [.gitignore file](https://www.kernel.org/pub/software/scm/git/docs/gitignore.html) to have Git ignore the contents of the `packages` folder. For reference, see the [sample `.gitignore` for Visual Studio projects](https://github.com/github/gitignore/blob/master/VisualStudio.gitignore). - -The important parts of the `.gitignore` file are: - - # Ignore NuGet Packages - *.nupkg - - # Ignore the packages folder - **/packages/* - - # except build/, which is used as an MSBuild target. - !**/packages/build/ - - # Uncomment if necessary; generally it will be regenerated when needed - #!**/packages/repositories.config - - # Ignore other intermediate files that NuGet might create - project.lock.json - *.nuget.props - -## Omitting packages with Team Foundation Version Control - -> [!Note] -> Follow these instructions if possible *before* adding your project to source control. Otherwise, manually delete the `packages` folder from your repository and check in that change before continuing. - -To disable source control integration with TFVC for selected files: - -1. Create a folder called `.nuget` in your solution folder (where the `.sln` file is). - * Tip: on Windows, to create this folder in Windows Explorer, use the name `.nuget.` *with* the training dot. -1. In that folder, create a file named `NuGet.Config` and open it for editing. -1. Add the following text as a minimum, where the [disableSourceControlIntegration](../Schema/nuget-config-file.md#solution-section) setting instructs Visual Studio to skip everything in the `packages` folder: - - ```xml - - - - - - - ``` - -1. If you are using TFS 2010 or earlier, cloak the `packages` folder in your workspace mappings. -1. On TFS 2012 or later, or with Visual Studio Team Services, add a [`.tfignore`](https://msdn.microsoft.com/library/ms245454.aspx#tfignore) file with the content below to explicitly ignore modifications to the `\packages` folder on the repository level and a few other intermediate files. (You can create the file in Windows Explorer using the name a `.tfignore.` with the trailing dot, but you might need to disable the "Hide known file extensions" option first.): - - # Ignore the NuGet packages folder in the root of the repository. - # If needed, prefix 'packages' with additional folder names if it's - # not in the same folder as .tfignore. - packages - - # Include package target files which may be required for MSBuild, - # again prefixing the folder name as needed. - !packages/*.targets - -1. Add `NuGet.Config` and `.tfignore` to source control and check in your changes. 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 9445a27ea..000000000 --- a/docs/Consume-Packages/Reinstalling-and-Updating-Packages.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -# required metadata - -title: Reinstalling and Updating NuGet Packages | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 2/8/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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 following command in the Visual Studio Package Manager Console (**Tools** > **NuGet Package Manager** > **Package Manager Console**): - -```ps -Update-Package –reinstall -``` - -Using this command, where `` is replaced with the specific package name you want, is much easier than removing a package and then trying to locate the same package in the NuGet gallery with the same version. - -The same command without `-reinstall` will update a package to a newer version, if applicable: - -```ps -Update-Package -``` - -Any updates are subject to version constraints indicated in `packages.config`, as described below in [Constraining upgrade versions](#constraining-upgrade-versions), but do not apply to projects using `project.json`. - -For complete usage, refer to the [PowerShell reference for Update-Package](../tools/powershell-reference.md#update-package). - -## 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 will raise 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 - -In NuGet 3.x with projects using `project.json` to list dependencies, installing or updating a package will *always* install the latest version available from the package source. - -In projects using `packages.config`, the same behavior applies unless you specifically constrain the version range. For example, if you know that your application will work 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 [Dependency versions](../create-packages/dependency-versions.md). 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 471c1daf1..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 517a15c7e..000000000 --- a/docs/Create-Packages/Creating-a-Package.md +++ /dev/null @@ -1,412 +0,0 @@ ---- -# required metadata - -title: How to create a NuGet package | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 2/8/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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 - -> [!Note] -> This topic is intended to be a reference for the process of creating a package. For a focused walkthrough example, refer to the [Create and Publish a Package Quickstart](../quickstart/create-and-publish-a-package.md). -> -> Additionally, this topic applies to all project types other than .NET Core projects using Visual Studio 2017 and NuGet 4.0+. In these cases, NuGet uses information from a `.csproj` file directly. These details are explained in [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). - -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 process of creating a package always begins with creating a `.nuspec` package manifest file that describes your package contents. This manifest drives the creation of the package as well as its usage when installed into a project. - -This topic covers the most common steps involved in package creation: - -- [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 in the other topics in this documentation. See [Next steps](#next-steps) below for a list of those options. - -## Deciding which assemblies to package - -In general, it's a best practice to have one NuGet package per assembly, 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. - -However, if your package contains assemblies that are used exclusively by your package, then it's fine to include them. For example, if `Utilities.dll` depends on `Utilities.resources.dll`, where the latter is not useful on its own, then you can put both in the same package. - -> [!Note] -> 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](../create-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 - -A `.nuspec` is an XML manifest file that describes a package's contents and drives the process of creating a NuGet package. At a minimum, the manifest includes the package identifier, version number, the title that appears in a gallery, author and owner information, and a long description. It can also include release notes, copyright information, a short description for the Package Manager UI in Visual Studio, a locale ID, home page and license URLs, an icon URL, lists of dependencies and references, tags that assist in gallery searches, and more. See the [.nuspec reference](../schema/nuspec.md) for complete details. - -Here's typical (but fictitious) `.nuspec` file, with annotation comments: - -```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 [Dependencies](../create-packages/dependency-versions.md). - -Because the manifest is always included in a package, 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: - -```bash -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 that when creating a `.nuspec` from a Visual Studio project, the manifest will contain tokens that will be replaced with information from the project when the package is build. See [Creating the .nuspec from a Visual Studio project](#from-a-visual-studio-project) below. - - -## Creating the .nuspec file - -You can create a `.nuspec` file from scratch in any text editor, or by editing a file from another project. You can also have NuGet create a template manifest for your by using the following command: - -```bash -nuget spec MyPackage -``` - -The resulting `MyPackage.nuspec` file (or `Package.nuspec` if you omit a specific name) will contain placeholders for values like the `projectUrl`, so be sure to edit it 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 will contain placeholders that you'll need to edit before creating the package itself. - -### From an assembly DLL - -If you have an assembly DLL, you can easily generate a `.nuspec` file from the metadata in the assembly using the following command: - -```bash -nuget spec MyAssembly.dll -``` - -### 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 will be automatically referenced as dependencies. Simply use the following command in the same folder as the project file: - -```bash -nuget spec -``` - -This creates a template `.nuspec` file as usual (where `` is replaced with your project name), but includes tokens that will be replaced at packaging time with values from the project. This means you do not need to update crucial values like the version number in the `.nuspec` as you update the project (but you can always replace the tokens with literal values, if desired). - -For example, the `` value will typically appear as follows: - -```xml -$id$ -``` - -and will be replaced with the `AssemblyName` value from the project file. For the exact mapping of project values to `.nuspec` tokens, see the [Replacement Tokens reference](../schema/nuspec.md#replacement-tokens). - -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)** -> -> NuGet 2.x supports 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. -> -> A package is considered a solution-level package if it does not contain any files in its lib, content, or build directories. If the package has dependencies, they also must not have files in their lib, content, or build directories. -> -> When a solution-level package is installed, it is tracked in a `packages.config` file in the `.nuget` directory, rather than in a `packages.config` file in a specific project. - - -### From a convention-based working directory - -In addition to assemblies and simple files like a readme, some packages may contain the following: - -- 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 no longer supported in NuGet 3.x and later.) -- Transformations to existing configuration and source code files in a project - -To include all these files in a package, you lay out a folder structure using the following conventions: - -|Folder |Description|Action upon package install| -|-------|-----------|---------------------------| -| 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.| -| lib | Assembly files (`.dll`), documentation (`.xml`) files, and symbol (`.pdb`) files | Assemblies are added as references; `.xml` and `.pdb` copied into project folders. | -| 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).| - - -Think of the **content** folder as the root of the target application, so if you want the package to add an image in the application's */images* folder, place it in the *content/images* folder of the package. - -Next, from the root folder of this layout, run the following command to create the `.nuspec` file: - -```bash -nuget spec -``` - -In this case, the `.nuspec` will not contain any explicit references to the folder structure, but all those files will be automatically included when creating the package later on. - -## Choosing a unique package identifier and setting the version number - -The package identifier in `` and the version number in `` are the two most important values in the manifest because they uniquely identify the exact code that's contained in the package. - -For the `` value, the following best practices apply: - -- **Uniqueness**: The identifier must be unique within nuget.org or whatever gallery will be hosting the package. Before deciding on an identifier, spend a little time searching in the applicable gallery to see if that name is already used. A good pattern to follow is to use your company name as the first part of the identifier, such as `Contoso.`. -- **Namespace-like names**: Identifiers should 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`. It's especially helpful to the consumers of your package to match the identifier to the namespaces of the code in the package, if applicable. -- **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`. - -For the `` value: - -- 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 [Handling Dependencies](../create-packages/dependency-versions.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 - -Beginning with NuGet 3.5, packages can be marked with a specific *package type* to indicate the package's intended use. Packages that are not marked with a type, including all packages created with earlier versions of NuGet, are assumed to be 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 will place 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 - - - - - - - - - - - - - -``` - -When you include a file named `readme.txt` in the package, the contents of that file will be displayed in Visual Studio as plain text immediately after the package is installed directly (but not when when the package is installed as a dependency). 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 will not 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 will add 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: - -```bash -nuget pack .nuspec -``` - -When using a Visual Studio project, run `nuget pack` instead with your project file, which will automatically load the project's `.nuspec` file and replace any tokens within it using values in the project file: - -```bash -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 will indicate if there are any errors in the `.nuspec` file that need correcting, such as forgetting to change values in the manifest from their defaults. - -Once `nuget pack` succeeds, you'll 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: - - ```bash - 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 will be 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 will need to package and publish that project separately. - -- **Build configuration**: By default, NuGet will use 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: - - ```bash - 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: - - ```bash - 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: - -- [Handling dependencies](../create-packages/dependency-versions.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 a3e513bab..000000000 --- a/docs/Create-Packages/Dependency-Versions.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -# required metadata - -title: Dependency Versions in NuGet | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/5/20167 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -ms.assetid: ae6c6212-67e9-4968-9585-e265407fd9c8 - -# optional metadata - -description: Exact details on specifying version numbers and ranges for other packages upon which a NuGet package depends, and how dependencies are installed. -keywords: versioning, NuGet package dependencies, NuGet dependency versions, NuGet version numbers, NuGet package version, version ranges, version specifications, normalized version numbers -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann -- unnir -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: - ---- -# Specifying dependency versions for NuGet Packages - -*For .NET Core projects using NuGet 4.0+, see [Package References in Project Files](../consume-packages/package-references-in-project-files.md) for declaring dependencies.* - -When you [create a NuGet package](../create-packages/creating-a-package.md), you can specify dependencies for your package in the `` node of the `.nuspec` file, where each dependency is listed with a `` tag: - -```xml - - - - - - - - - - - -``` - -Dependencies are installed whenever the dependent package is installed, [reinstalled](../consume-packages/reinstalling-and-updating-packages.md), or included in a [package restore](../consume-packages/package-restore.md). NuGet chooses the exact version of the installed dependency by using the value of the `version` attribute specified for that dependency as described in the following sections. - -- [Version ranges](#version-ranges) -- [Normalized version numbers](#normalized-version-numbers) -- [Dependency updates during package install](#dependency-updates-during-package-install). - -> **Best practice** -> -> Developers most commonly specify a minimum version, which is a version number without adornments as shown above, like 6.1.0. This allows NuGet to install that version or later. - - -For additional details on how dependencies are installed, see [Reinstalling and updating packages](../consume-packages/reinstalling-and-updating-packages.md) and [Dependency resolution](../consume-packages/dependency-resolution.md). - - -## Version ranges - -NuGet supports using interval notation for specifying version ranges, summarized as follows: - -| Notation | Applied rule | Description | -|----------|--------------|-------------| -| 1.0 | 1.0 ≤ x | Minimum version, inclusive | -| (1.0,) | 1.0 < x | Minimum version, exclusive | -| [1.0] | x == 1.0 | Exact version match | -| (,1.0] | x ≤ 1.0 | Maximum version, inclusive | -| (,1.0) | x < 1.0 | Maximum version, exclusive | -| [1.0,2.0] | 1.0 ≤ x ≤ 2.0 | Exact range, inclusive | -| (1.0,2.0) | 1.0 < x < 2.0 | Exact range, exclusive | -| [1.0,2.0) | 1.0 ≤ x < 2.0 | Mixed inclusive minimum and exclusive maximum version | -| (1.0) | invalid | invalid | - - -A few examples: - -```xml - - - - - - - - - - - - - - -``` - - -If no version is specified for a dependency, NuGet behaves as follows: - -- NuGet v2.7.2 and earlier: The **latest** package version will be used -- NuGet v2.8 and later: The **lowest** package version will be used - -For consistent behavior, it's recommended to always specify a version or version range for package dependencies. - -(For the curious, the NuGet version notation is inspired by Maven Version Range Specification, but is not identical to it.) - -## Normalized version numbers - -> [!Note] -> This is a breaking change for NuGet 3.4 and later. - - -When obtaining packages from a repository during install, reinstall, or restore operations, NuGet 3.4 and later will treat version numbers as follows: - -- Leading zeroes are removed from version numbers: - - 1.00 is treated as 1.0 - 1.01.1 is treated as 1.1.1 - 1.00.0.1 is treated as 1.0.0.1 - -- A zero in the fourth part of the version number will be omitted - - 1.0.0.0 is treated as 1.0.0 - 1.0.01.0 is treated as 1.0.1 - -This normalization does not affect the version numbers in the packages themselves; it affects only how NuGet matches versions. - -However, NuGet repositories must treat these values in the same way as NuGet to prevent package version duplication. Thus a repository that contains v1.0 of a package should not also host v1.0.0 as a separate and different package. - -## 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 will not be updated during other package installations. - -In the same example above, installing package A into a project with NuGet 2.5 and later will leave 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. diff --git a/docs/Create-Packages/Overview-and-Workflow.md b/docs/Create-Packages/Overview-and-Workflow.md deleted file mode 100644 index 0d6200054..000000000 --- a/docs/Create-Packages/Overview-and-Workflow.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -# required metadata - -title: Overview and workflow of creating NuGet 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: nuget -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 code 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 only to pull in a number of other dependencies and not contain any code of its own, which is a convenient way to create a single package for 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 will be 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. - -To learn and understand the creation process, start with [Creating a package](../create-packages/creating-a-package.md) which will guide you through the core processes common to all packages. This includes deciding which assemblies to package, creating the `.nuspec` (manifest) file, choosing a package identity and version number, setting a package type, adding a readme, and including MSBuild props and targets. The topic ends with creating the package itself using the `nuget pack` command. - -From there, you can consider a number of other options for your package: - -- [Dependency Versions](../create-packages/dependency-versions.md) discusses how to identify the exact versions that you allow for your dependencies (other packages that you consume from 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. -- [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. -- [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. -- [Native Packages](../create-packages/native-packages.md) describes the process for creating a package for C++ consumers. -- [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. - - -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 a67ca821a..000000000 --- a/docs/Create-Packages/Prerelease-Packages.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -# required metadata - -title: Pre-release versions in NuGet 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: nuget -ms.assetid: df6a366a-22c1-47bb-8017-18231311ce88 - -# optional metadata - -description: How to specify pre-release version numbers for a NuGet package, using the semantic versioning conventions. -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: - ---- - -# Pre-release versions - -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` (as described in [semantic versioning](#semantic-versioning) later in this topic). - -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 will pick up this value instead of the one specified in the `AssemblyVersion` attribute, which does not support SemVer. - -> [!Note] -> A stable package release cannot have a pre-release dependency. This avoids accidentally installing a potentially unstable releases. - -When you’re ready to release a stable version, just remove the suffix and the package will take precedence over any 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 build 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-beta - 1.0.1-alpha2 - 1.0.1-alpha - -As shown, the version without any suffix will always take precedence over pre-release versions. diff --git a/docs/Create-Packages/Publish-a-package.md b/docs/Create-Packages/Publish-a-package.md deleted file mode 100644 index 9eac11729..000000000 --- a/docs/Create-Packages/Publish-a-package.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -# required metadata - -title: How to Publish a NuGet Package | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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). See instructions below. -- 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, or a third-party repository such as myget, ProGet, Nexus Repository, and Artifactory. For additional details, see [Hosting Packages Overview](../hosting-packages/overview.md)) - -## 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: - - ```bash - nuget setApiKey Your-API-Key - ``` - - This will store your API key on the machine so that you will not need to do this step again on the same machine. - - 4. Push your package to NuGet Gallery using the command: - - ```bash - 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 will be 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 will indicate "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 will 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 c176a7e21..000000000 --- a/docs/Create-Packages/Supporting-Multiple-Target-Frameworks.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -# required metadata - -title: Multi-targeting for NuGet 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: nuget -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. - -Fortunately, NuGet supports putting multiple versions of the same library in a single package through the convention-based working directory method described in [Creating a package](../create-packages/creating-a-package.md#from-a-convention-based-working-directory). - -> [!Note] -> Assemblies that have no associated framework name or version should be stored directly in the `lib` folder and not in separate folders. - -In this topic: - -- [Framework version folder structure](#framework-version-folder-structure) -- [Content files and PowerShell scripts](#content-files-and-powershell-scripts) -- [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) - - -## Framework version folder structure - -When NuGet installs an assembly from a package, it checks the target .NET Framework version of the project, then selects the correct version of the assembly from the appropriate subfolder under `lib` in the package, provided those folders use 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). Note that names are case-sensitive - -The following example shows a folder structure that supports four versions of a library: - - \lib - \net46 - \MyAssembly.dll - \net461 - \MyAssembly.dll - \uap - \MyAssembly.dll - \netcore - \MyAssembly.dll - - -## 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 will not 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. If placed under a framework folder, it will be ignored. - - -## 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. - -For example, consider the following folder structure in a package: - - \lib - \net45 - \MyAssembly.dll - \net461 - \MyAssembly.dll - - -Installing this package in a project that targets .NET Framework 4.6, NuGet installs the assembly in the `net45` 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) - - -To easily include all these files, use a wildcard in the `` section of your `.nuspec`: - -```xml - - - -``` - -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. (One reason why NuGet behaves this way is that `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 .NET Framework 3.5, NuGet copies both `MyAssembly.dll` and `MyAssembly.Core.dll` because their location in the package does not restrict them to a specific target. But as was true of the previous example, in projects that target .NET Framework 4.5, only `MyAssembly.dll` from the `net45` folder will be copied. If you want 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} - -For example, to target the Windows Phone profile, place your assembly in a folder named `sl3-wp`. - -Profiles supported by NuGet : - -- `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 sometimes 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. Here are some links to useful external resources to 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 diff --git a/docs/Create-Packages/Symbol-Packages.md b/docs/Create-Packages/Symbol-Packages.md deleted file mode 100644 index 21ceb675e..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: nuget -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: - -```bash -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. - -```bash -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: - -```bash -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: - -```bash -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: - -```bash -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. \ No newline at end of file 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/Create-Packages/project-json-and-UWP.md b/docs/Create-Packages/project-json-and-UWP.md deleted file mode 100644 index 5142daf62..000000000 --- a/docs/Create-Packages/project-json-and-UWP.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -# required metadata - -title: NuGet project.json file with UWP projects | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -ms.assetid: 37caf4d7-dabd-4a78-aad2-7d445f818457 - -# optional metadata - -description: Description of how the project.json file is used to track NuGet dependencies in Universal Windows Platform (UWP) projects. -keywords: NuGet dependencies, NuGet and UWP, UWP and project.json, NuGet project.json file -#ROBOTS: -#audience: -#ms.devlang: -ms.reviewer: -- karann -- unnir -#ms.suite: -#ms.tgt_pltfrm: -#ms.custom: ---- - -# project.json and UWP - -This document describes a the package structure that can be used to take advantage of features in NuGet v3. The `minClientVersion` property of your `.nuspec` can be used to state that you require the features described here by setting it to 3.1. Note that NuGet v3 is available in Visual Studio 2015 and newer. - -## Adding UWP support to an existing package - -If you have an existing package and you want to add support for UWP applications then you don’t need to adopt the new packaging format described here. You only need to adopt this format if you require the features it describes and are willing to only work with clients that have updated to the latest version of the NuGet client. - -## I already target netcore45 - -If you target `netcore45` already, and you don’t need to take advantage of anything new then you don’t need to do anything, `netcore45` will be consumed by UWP applications. - -## I want to take advantage of Windows 10 specific APIs - -In this case you need to add the uap10.0 TxM to your package. Create a new folder in your package and add the assembly that has been compiled to work with Windows 10 to that folder. - -## I don’t need Windows 10 specific APIs, but want new .NET features or don’t have netcore45 already - -In this case you would add the new dotnet TxM to your package. Unlike other TxMs dotnet doesn't imply a surface area or platform. It is stating that your package will work on any platform that your dependencies work on. When building a package with the dotnet TxM you are likely to have many more TxM specific dependencies in your `.nuspec`, as you will need to define the BCL packages you depend on, such System.Text, System.Xml, etc. The locations that those dependencies work on define where your package will work. - -### How do I find out my dependencies - -There are two ways to figure out which dependencies to list: - -1. Use `ILDasm` to look at your `.dll` to see what assemblies are actually needed at runtime. Then determine which NuGet package they each come from. This is the hard way. -2. Use the [NuSpec Dependency Generator](https://github.com/onovotny/ReferenceGenerator) **3rd party** tool. The tool automates the process and updates your `.nuspec` file with the dependant packages on build. It is available via a NuGet package, [NuSpec.ReferenceGenerator](https://www.nuget.org/packages/NuSpec.ReferenceGenerator/). - -See the `project.json` document for details on supports and includes features that both help in the creation of a package that support the dotnet TxM. - -**If your package is intended to work with the new PCL project, we highly recommend to create a dotnet folder, to avoid warnings and potential compatibility issues.** - - - -## Directory structure - -NuGet packages using the new format have the following well-known directories and behaviors: - -* Build - * MSBuild targets and props files in this folder are integrated differently into the project, but otherwise there is no change. - -* Tools - * `install.ps1` and `uninstall.ps1` will no longer run. `init.ps1` works as it always has. - -* Content - * Content will no longer be copied automatically into a user's project. Support for content inclusion in the project is planned for a later release - -* Lib - * For many packages the `lib` will work the same way it does in the 2.0, but with expanded options for what names can be used inside it and better logic for picking the correct sub-folder when consuming packages. However, when used in conjunction with `ref`, the `lib` folder will contain assemblies that implement the surface area defined by the assemblies in the `ref` folder. - -* Ref - * `ref` is a new, optional, folder that contains .NET assemblies defining the public surface (public types and methods) for an application to compile against. The assemblies in this folder may have no implementation, they are purely used to define surface area for the compiler. If the package has no `ref` folder, then the `lib` is both the reference assembly and the implementation assembly. - -* Runtimes - * `runtimes` is a new, optional, folder that will contain OS specific code, such as CPU architecture and OS specific or otherwise platform-dependent binaries. - - -## MSBuild targets and props files in packages - -NuGet packages can contain `.targets` and `.props` files which will be imported into any MSBuild project that the package is installed into. In NuGet 2.x, this was done by injecting `` statements into the `.csproj` file, in NuGet 3.0 there is no specific "installation to project" action. Instead the package restore process writes two files `[projectname].nuget.props` and `[projectname].NuGet.targets`. - -MSBuild knows to look for these two files and automatically imports them near the beginning and near the end of the project build process. This provides very similar behavior to NuGet 2, but with one major difference: **There is no guaranteed order of targets/props files in this case**. However, MSBuild does provide ways to order Targets through the BeforeTargets and AfterTargets attributes of the `` definition (see [https://msdn.microsoft.com/library/t50z2hka.aspx](https://msdn.microsoft.com/library/t50z2hka.aspx)). - - -## Lib and Ref - -The behavior of the `lib` folder hasn't changed significantly in NuGet v3. However, all assemblies must be within sub-folders named after a TxM, and can no longer be placed directly under the `lib` folder. A TxM is the name of a platform that a given asset in a package is supposed to work for. Logically these are an extension of the Target Framework Monikers (TFM) e.g. `net45`, `net46`, `netcore50`, and `dnxcore50` are all examples of TxMs. We use a new term TxM because a TxM can refer to a framework (TFM) as well as other platform specific surface area. For example the UWP TxM (UAP10.0) represents the .NET surface area as well as the Windows surface area for UWP applications. - -An example lib structure: - - lib - ├───net40 - │ MyLibrary.dll - └───wp81 - MyLibrary.dll - -The `lib` folder contains assemblies that will be used at runtime. For most packages a folder under `lib` for each of the target TxMs is all that is required. - -## Ref - -There are sometimes cases where a different assembly should be used during compilation (.NET Reference Assemblies do this today). For those cases, we are introducing a new top-level folder called *ref* (short for "Reference Assemblies"). - -Most package authors will not require the `ref` folder. It is useful for packages that need to provide a consistent surface area for compilation and IntelliSense but then have different implementation for different TxMs. The biggest use case of this will be the `System.*` packages that are being produced as part of shipping .NET Core on NuGet. These packages have various implementations that are being unified by a consistent set of ref assemblies. - -Mechanically, the assemblies included in the `ref` folder are the reference assemblies being passed to the compiler. For those of you who have used csc.exe these are the assemblies we are passing to the /reference ([https://msdn.microsoft.com/library/yabyz3h4.aspx](https://msdn.microsoft.com/library/yabyz3h4.aspx)) switch. - -The structure of the `ref` folder is the same as lib, for example: - - └───MyImageProcessingLib - ├───lib - │ ├───net40 - │ │ MyImageProcessingLibrary.dll - │ │ - │ ├───net451 - │ │ MyImageProcessingLibrary.dll - │ │ - │ └───win81 - │ MyImageProcessingLibrary.dll - │ - └───ref - ├───net40 - │ MyImageProcessingLibrary.dll - │ - └───portable-net451-win81 - MyImageProcessingLibrary.dll - - -In this example the assemblies in the ref directories would all be identical. - - -## Runtimes - -The runtimes folder contains assemblies and native libraries required to run on specific "runtimes", which are generally defined by Operating System and CPU architecture. These runtimes are identified using Runtime Identifiers (RIDs) such as win, win-x86, win7-x86, win8-64, etc. - -## Native light-up - -In the following example we will show a package that has a purely managed implementation for several platforms, but will use native helpers on Windows 8 where it can call into Windows 8 specific native APIs. - - └───MyLibrary - ├───lib - │ └───net40 - │ MyLibrary.dll - │ - └───runtimes - ├───win8-x64 - │ ├───lib - │ │ └───net40 - │ │ MyLibrary.dll - │ │ - │ └───native - │ MyNativeLibrary.dll - │ - └───win8-x86 - ├───lib - │ └───net40 - │ MyLibrary.dll - │ - └───native - MyNativeLibrary.dll - -Given the above package the following things will happen: - -* When not on Windows 8 the `lib/net40/MyLibrary.dll` assembly will be used. - -* When on Windows 8 the `runtimes/win8-/lib/MyLibrary.dll` will be used and the `native/MyNativeHelper.dll` will be copied to the output of your build. - -In the example above the `lib/net40` assembly is purely managed code, whilst the assemblies in the runtimes folder will p/invoke into the native helper assembly to call APIs specific to Windows 8. - -Only a single `lib` folder will ever be picked, so if there is a runtime specific folder it will be chosen over non-runtime specific `lib`. The native folder is additive, if it exists it will be copied to the output of the build. - -## Managed wrapper - -Another way to use runtimes is to ship a package that is purely a managed wrapper over a native assembly. In this scenario you create a package like the following: - - └───MyLibrary - └───runtimes - ├───win8-x64 - │ ├───lib - │ │ └───net451 - │ │ MyLibrary.dll - │ │ - │ └───native - │ MyImplementation.dll - │ - └───win8-x86 - ├───lib - │ └───net451 - │ MyLibrary.dll - │ - └───native - MyImplementation.dll - -In this case there is no top-level `lib` folder as that folder as there is no implementation of this package that doesn't rely on the corresponding native assembly. If the managed assembly, `MyLibrary.dll`, was exactly the same in both of these cases then we could put it in a top level `lib` folder, but because the lack of a native assembly doesn't cause the package to fail installing if it was installed on a platform that wasn't win-x86 or win-x64 then the top level lib would be used but no native assembly would be copied. - - -## Authoring packages for NuGet 2 and NuGet 3 - -If you want to create a package that can be consumed by projects using `packages.config` as well as packages using `project.json` then the following apply: - -* Ref and runtimes only work on NuGet 3. They will both be ignored by NuGet 2. - -* You cannot rely on `install.ps1` or `uninstall.ps1` to function. These files will execute when using `packages.config`, but will be ignored in v3. So your package needs to be usable without them running. `init.ps1` will still run on NuGet 3. - -* Targets and Props installation is different, you will need to make sure that your package works as expected on both clients. - -* Subdirectories of lib must be a TxM in NuGet 3. You cannot place libraries at the root of the `lib` folder. - -* Content will no longer be copied automatically. If you package relies on the files in content being copied into the users project then this will not happen on NuGet 3. Consumers of your package could copy the files themselves or use a tool like a task runner to automate copying the files. - -* You cannot rely on transforms, like web.config transformation. Transforms are not run by the NuGet 3 client. - -If you are supporting NuGet 2 and 3 then your minClientVersion should be the lowest version of NuGet 2 client that your package works on. In the case of an existing package it shouldn't need to change. \ No newline at end of file diff --git a/docs/Guides/Create-Cross-Platform-Packages.md b/docs/Guides/Create-Cross-Platform-Packages.md deleted file mode 100644 index 3b15fccce..000000000 --- a/docs/Guides/Create-Cross-Platform-Packages.md +++ /dev/null @@ -1,289 +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: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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: - -```bash -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 - - - ``` - -### 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: - -```bash -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) -- [Dependency Versions](../create-packages/dependency-versions.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 da3938867..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: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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: - -```bash -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: - -```bash -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 [Dependency Versions](../create-packages/dependency-versions.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) -- [Dependency Versions](../create-packages/dependency-versions.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 3eada0e75..000000000 --- a/docs/Guides/Create-NET-Standard-Packages-VS2017.md +++ /dev/null @@ -1,124 +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: 2/8/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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--net-core-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 Core 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 (Portable)` 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, 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\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 2016 (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 - -This 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) -- [NuGet pack and restore as MSBuild targets](../schema/msbuild-targets.md) -- [.NET Standard Library documentation](https://docs.microsoft.com/dotnet/articles/standard/library) -- [Porting to .NET Core from .NET Framework](https://docs.microsoft.com/dotnet/articles/core/porting/index) diff --git a/docs/Guides/Create-UWP-Controls.md b/docs/Guides/Create-UWP-Controls.md deleted file mode 100644 index f6133508f..000000000 --- a/docs/Guides/Create-UWP-Controls.md +++ /dev/null @@ -1,232 +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: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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`. -- *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. - -```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`. - -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. - -## PackageReference-based UWP projects -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 enforce the appropriate TPMinV check, package your control contents with the following folder names: - -``` -\lib\uap10.0.14393.0\* -\ref\uap10.0.14393.0\* -``` - -Note that `ref` is given here for completeness. It’s required only if you have a reference assembly that’s used to compile the app and there’s a different implementation assembly in `lib` that’s copied into the application output. - -To specify multiple versions of the assembly targeting specific versions of the SDK, creating separate folders for each version of the OS: - -``` -\lib\uap10.0.14393.0\* -\lib\uap10.0.10586.0\* -\ref\uap10.0.14393.0\* -\ref\uap10.0.10586.0\* -``` - -The correct version of the assembly is then selected based on the consuming project's TPV. If the consuming project's TPV is higher than all available assemblies, the highest version of the assembly is selected. - -> [!Note] -> The TPV `\lib\uap10.0` and `\lib\uap` will continue to work, but there’s no TPMinV check and the package can be consumed by a UWP project irrespective of its TPMinV. -> This feature currently works only for PackageReference-based UWP projects. To continue to support `project.json` based UWP projects, include your controls under the `\lib\uap10.0` folder as well. - -## Build-time TPMinV check for project.json/packages.config based UWP projects - -The install-time TPMinV check is not supported for UWP projects using `project.json` or `packages.config`. Instead, you can author a build target that performs this check at project build time. - -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: - -``` -\build - \uap10.0 - MyManagedPackage.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: - -``` -\build -\lib - \uap10.0.14393.0 - \Design - \MyControl.design.dll - \ManagedPackage - \Themes - Generic.xaml -\tools -``` - -> [!Note] -> By default, control properties will show up under the Miscellaneous category in the property inspector. - -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. - -## 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: - -``` -\build -\lib - \uap10.0.14393.0 - \Design - \ManagedPackage -\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 454a891fe..000000000 --- a/docs/Guides/Install-NuGet.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -# required metadata - -title: Installing NuGet | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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 that works on Windows, Mac OS X, and Linux and supports all NuGet capabilities. -1. The [**NuGet Package Manager in Visual Studio**](#nuget-package-manager-in-visual-studio) is a GUI tool for managing packages and includes a console through which you can use certain NuGet commands directly within Visual Studio. It's included with Visual Studio 2012 and later and can be installed manually for earlier versions. - -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] -> You might also be interested in the [NuGet Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer), an open-source, stand-alone tool to visually explore and create NuGet packages. -> Also, the cross-platform [.NET Core CLI](https://docs.microsoft.com/dotnet/articles/core/tools/index#installation) toolchain for developing .NET Core applications also supports a [dotnet restore](https://docs.microsoft.com/dotnet/articles/core/tools/dotnet-restore) command that performs a nuget restore. No other nuget commands are available in the .NET Core CLI at present, however. - - -## NuGet CLI - -The NuGet CLI can be installed using any of the following methods: - -1. **nuget.org**: Download the latest version of the nuget.exe file from [nuget.org/downloads](https://nuget.org/downloads) and save it to an appropriate location on your machine. If desired, add that location to your PATH environment variable so you can NuGet from anywhere. (Note that the download is a single .exe file, so save it rather than running it from the browser.) - -> [!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. - - ```bash - 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. - -> **NuGet 2.x users** -> -> Because there are a few 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 CI systems from potentially breaking at this time. - -### Compatibility with Mono - -Though not fully-supported as yet, the NuGet command-line executable (version 3.2 and above) will run on Mac OS X and Linux systems when the Mono runtime is installed with a few 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 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. Use the NuGet CLI outside of that environment. - - -### Package Manager installation for Visual Studio 2010 and earlier - -1. In Visual Studio, click **Tools > Extension and Updates**. -1. Navigate to **Online**, 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 beta channel - -The NuGet Beta Channel for the NuGet Package Manager in Visual Studio 2015 gives you access to high-quality builds that are close to completion. We use this channel to gather feedback on our near-final builds, and it's recommended for developers who want to try out new features and those who are experiencing blocking issues and need early access to updated builds before RTM. - -Accessing the beta channel is simple: - -1. In Visual Studio, navigate to **Tools > Options > Environment > Extensions and Updates**, then add the feed `https://dotnet.myget.org/F/nuget-beta/vsix/` to the **Additional Extension Galleries** list: - - ![Adding the NuGet beta channel feed to Visual Studio](media/BetaChannel-ToolsSettings.png) - -1. Navigate to **Tools > Extensions and Updates** and select **Online**, which should show the NuGet-Beta Feed from which you can install a beta NuGet Package Manager: - - ![Checking NuGet beta channel updates](media/BetaChannel-ExtensionUpdate.png) - -To report problems with the Beta builds 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 1c88175a3..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: 1/9/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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 in which you place packages (or even just a folder on your own machine). Local feeds can be either 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 these cases, you enable the source by simply adding the pathname, such as `\\myserver\packages` through the [Package Manager UI](../tools/package-manager-ui.md#package-sources) or the command line using [`nuget sources`](../tools/nuget-exe-cli-reference.md#sources). - -## Initializing and maintaining hierarchical folders - -With NuGet 3.3 and above, you'll realize much better performance by structuring the feed using a hierarchical versioned folder tree: - - \\myserver\packages - └─ - └─ - ├─..nupkg - └─ - -NuGet will create this structure automatically when you use the [`nuget add`](../tools/nuget-exe-cli-reference.md#add) command to copy packages to the feed: - -```bash -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`: - -```bash -nuget init c:\packages \\myserver\packages -``` - -Again, this will create a folder for each package identifier, each of which will contain a version number folder, within which will be the appropriate package. diff --git a/docs/Hosting-Packages/NuGet-Server.md b/docs/Hosting-Packages/NuGet-Server.md deleted file mode 100644 index 752cadba2..000000000 --- a/docs/Hosting-Packages/NuGet-Server.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -# required metadata - -title: NuGet.Server to Host NuGet Feeds | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 3/8/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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 basically makes a folder on the server available through HTTP(S) (specifically OData). As such it's best for simple scenarios and is easy to set up. - -The process is as follows: - -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, click OK, and in the next dialog select the **ASP.NET 4.6 - Empty** template and click 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. By running the application the first time, the `Packages` folder gets restructured 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, you can 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` will contain 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 8f1f195b0..000000000 --- a/docs/Hosting-Packages/Overview.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -# required metadata - -title: Overview of Hosting Your Own NuGet Feeds | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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 for 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 a private package source 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 server through HTTP. 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) on GitHub. NuGet Gallery provides user management and additional 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: - -- [Package Management](https://www.visualstudio.com/docs/package/overview) from [VS Team Services](https://www.visualstudio.com/team-services/) and [TFS](https://www.visualstudio.com/tfs/) -- [MyGet](http://myget.org) -- [ProGet](http://inedo.com/proget) from Inedo -- [NuGet Server](http://nugetserver.net/), a community project from Inedo -- [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 anything from a local folder to a network name to an Internet 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 cb87be73f..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: nuget -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 no longer 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 64d4bc1a2..000000000 --- a/docs/Policies/NuGet-FAQ.md +++ /dev/null @@ -1,243 +0,0 @@ ---- -# required metadata - -title: NuGet Frequently-Asked Questions | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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` work fully on Windows, there are known issues on Linux and OS X. Refer [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 from Package Manager Console. - -To update the template itself, you'll 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). - -## NuGet command line - -**How do I get the latest version of NuGet commandline?** - -See the [Install guide](../guides/install-nuget.md). - -**Is it possible to extend the NuGet commandline?** - -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 console provides a variable named `$DTE` that returns the `DTE` object. See the [`Get-Project` command](../tools/powershell-reference.md#get-project). - -**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. Typically, a solution-level package installs new commands that can be called from within the Package Manager Console. - -**Is it possible to install NuGet package 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 will identify 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 will use that file: - - `packages.config`: use the pattern `packages.{project-name}.config` - `project.json`: use the pattern `{project-name}.project.json` - -**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 (click 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's 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 have 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 will perform some static analysis and indicate if there are issues. If the package is accepted, you'll then 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, click on your username, then on **Manage my packages**, then on 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/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 406ef7353..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 | Microsoft Docs -author: kraigb -ms.author: kraigb -manager: ghogen -ms.date: 1/9/2017 -ms.topic: article -ms.prod: nuget -#ms.service: -ms.technology: nuget -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, of course. -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 add 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 will create 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`: - - ```bash - 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). You must also 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: - -```bash -nuget pack AppLogger.csproj -``` - -This will create a NuGet package file like `AppLogger.1.0.0.0.nupkg` using, of course, 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 will be 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: - - ```bash - 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 which time you'll see the following message on your package page: - - ![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**: 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. - -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) -- [Dependency versions](../create-packages/dependency-versions.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 202068288..000000000 --- a/docs/Quickstart/Use-a-Package.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -# required metadata - -title: Introductory Guide to Using NuGet 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: nuget -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: - -- [Install pre-requisites](#install-pre-requisites) -- [Create a new UWP project](#create-a-new-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) - -You'll use a similar same workflow for virtually every NuGet package you use in a project. - -> **Start with nuget.org**: Installing packages from nuget.org is a very 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 we'll do here. - -## Install pre-requisites - -This tutorial requires Visual Studio 2015 Update 3 with Tools for Universal Windows Apps. - -You can install the Community edition for free from [visualstudio.com](https://www.visualstudio.com/) or use the Professional or Enterprise editions. The UWP tools option can be selected through the Custom install option during setup, checking the box under **Windows and Web Development > Universal Windows App Development Tools**. If you already have Visual Studio installed, you can run the installer again and click **Modify** to add the UWP tools. - -## Create a new 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 - - -