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 0c3061414..36a0aa314 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,182 @@ -# docs.microsoft.com-nuget -New repo for our docs.microsoft.com move +# NuGet Docs + +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 *main* branch. The main branch is used for staging changes which is periodically merged into the *live* branch which is what's published to the live Microsoft Learn site. + +NuGet follows the [.NET Foundation Contributors Code of Conduct](https://github.com/dotnet/home/blob/master/guidance/be-nice.md). Please take a few minutes to review it. + +## 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. + +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 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. Review requests are automatic and we review PRs on a regular basis. +1. Thank you! + +If you're creating a new topic, keep the following in mind as well: + +1. Always place the new topic in an appropriate subfolder, and follow the conventions for filenames as you see them used here. + +1. You must include a metadata block as you see on other topics. Typical defaults (such as for `ms.workload` and `ms.reviewer`) are set within `docs/docjx.json`, so you need only change the following: + + - title: The title that appears in search results. For SEO, this ideally isn't the same as the top-level # (H1) of the article. + - description: The abstract of the article that appears in search results. + - author: the author's GitHub ID, to which issues files for this article are assigned. + - ms.author: if the author is a Microsoft employee, this is the Microsoft alias. Used for reporting and forwarding feedback from other channels. + - manager: Microsoft alias of the author's manager, if applicable. + - ms.date: the date of the last revision or review of the article in mm/dd/yyyy format (use leading zeros). This is a communication to the reader about freshness, so it's not updated for minor changes, only for more significant revisions OR when the article has reverified even if there are no changes. + - ms.topic: used to categorize the article in reports. See table below. Most articles are "conceptual". + +1. In addition to adding your page, edit `docs/TOC.md` to add a link to that page. + +1. If you're adding a top-level node to the TOC, also make an entry for it in `docs/index.md`. + +| 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 + +In general, if you don't see something described here, look in editing markdown files for examples, with the exception of files in the Release Notes which are legacy content and haven't been as thoroughly edited. + +## Language level and terms + +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. + +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". + +Don't worry too much, though. We'll thoroughly review your contributions and edit for these things. + +## Naming + +Follow these naming conventions and capitalizations when referring to NuGet and related components. + +- 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 (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. + +For items not listed here, search in the repository for the term and see how it's used. + +### Heading capitalizations + +All headings need only capitalize the first word and proper names. Refer to most topics for examples. + +### UI terms, boldface, and italics + +Use **boldface** for any string that a reader will see in UI, such as "Select the **File** menu," except when referring to common window titles like Solution Explorer. + +Use ">" to indicate UI hierarchies, as in the **File > New Project...** menu, or **Tools > Options > NuGet > NuGet Package Manager > Package Sources**. Notice how in this example you can use ">" to traverse a hierarchy from a menu, into a dialog box, into tabs, sub-tabs, and fields. In other words, readers can work with the chain of items to follow and don't need every click spelled out for them. In general, think of how to get the reader to where they need to go in the most efficient way. + +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 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 out for themselves. + +If an image has white bleed areas on the edges, draw a 1-pixel gray outline around the entire graphic. + +Always include a meaningful description of the image in the markdown alt-text between the []'s. These descriptions are also a great place to put SEO terms that you don't otherwise want to appear in the text. + +### Inline code + +Delineate inline code with grave accents (backticks), as in \`nuget pack\`. This inline formatting is used for the following: + +- Code +- Identifiers +- File names, folder names, and extensions +- Command line strings and arguments + +Except for the following cases: + +- When part of a surrounding code block. +- When appearing in the left-hand column of a table, because these are automatically bolded. +- When appearing in quoted strings +- When appearing in links (although when the term appears by itself, it's OK) + +Markdown and HTML are ignored within inline code. + +### Code blocks + +Code blocks on Microsoft Learn are delineated by with three grave accents (backticks), ```, at the beginning and the end. You do not need to indent code blocks unless they are contained within a list. + +The opening ``` should be followed by a language code for proper syntax coloring, such as "xml", "json", "csharp", etc. Use "cli" for command-line examples and "output" for command-line results. + +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 + +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://learn.microsoft.com/nuget/create-packages/creating-a-package) for examples. + +You can also use one of the following callout tags on the first line that will create a shaded callout in the indicated color: + +| Tag | Callout use | Topic with examples | +| --- | --- | --- | +| `> [!Note]` | Callouts without any special emphasis. | [Creating NuGet packages](https://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 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 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. + +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. 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/Credential-Providers.md b/docs/API/Credential-Providers.md deleted file mode 100644 index 960835932..000000000 --- a/docs/API/Credential-Providers.md +++ /dev/null @@ -1,103 +0,0 @@ -# Credential Providers and NuGet - -*NuGet 3.3+* - -When `nuget.exe` needs credentials to authenticate with a feed, it looks for them in the following manner: - -1. NuGet first looks for credentials in `nuget.config` files. -2. NuGet then uses plug-in credential providers, subject to the order given below. (And example is the [Visual Studio Team Services Credential Provider](https://www.visualstudio.com/en-us/docs/package/get-started/nuget/auth#vsts-credential-provider).) -3. NuGet then prompts the user for credentials on the command line. - -
- Note
- Credential providers do not apply to dotnet restore, or the Package Manager UI or Console in Visual Studio. NuGet in Visual Studio uses a single single built-in credential provider that supports Visual Studio Team Services. -
- -Plug-in credential providers thus provide a way to hook into custom authentication process for different feeds. They can be used in three ways: - -- **Globally**: to make a credential provider available to all instances of `nuget.exe` run under the current user's profile, add it to `%LocalAppData%\NuGet\CredentialProviders`. You may need to create the `CredentialProviders` folder. Credential providers can be installed at the root of the `CredentialProviders` folder or within a subfolder. If a credential provider has multiple files/assemblies, you can use subfolders to keep the providers organized. -- **From an environment variable**: Credential providers can be stored anywhere and made accessible to `nuget.exe` by setting the `%NUGET_CREDENTIALPROVIDERS_PATH%` environment variable to the provider location. This variable can be a semicolon-separated list if you have multiple locations. -- **Alongside nuget.exe**: Credential providers can be placed in the same folder as `nuget.exe`. - -The loading plug-in credential providers, `nuget.exe` searches the above locations, in order, for any file named `credentialprovider*.exe`, then loads those files in the order they're found. If multiple credential providers exist in the same folder, they're loaded in alphabetical order. - - -## Creating a credential provider - -A credential provider is a command-line executable, named in the form `CredentialProvider*.exe`, that gathers inputs, acquires credentials as appropriate, and then returns the appropriate exit status code and standard output. - -A provider must also do the following: - -- Determine whether it can provide credentials for the targeted URI before initiating credential acquisition. If not, it should return status code 1 with no credentials. -- Not modify `nuget.config` (such as setting credentials there). -- Handle HTTP proxy configuration on its own, as NuGet does not provide proxy information to the plugin. -- Encode `stdout` responses using UTF-8 encoding. - -### Input parameters - - - - - - - - - - - - - - - - -
Parameter/SwitchDescription
Uri {value}The package source URI requiring credentials.
NonInteractiveIf present, provider does not issue interactive prompts.
IsRetryIf present, indicates that this attempt is a retry of a previously failed attempt. Providers typically use this flag to ensure that they bypass any existing cache and prompt for new credentials if possible.
- -### Exit codes - - - - - - - - - - - - - - - - - - - - -
CodeResultDescription
0SuccessCredentials were successfully acquired and have been written to stdout.
1ProviderNotApplicableThe current provider does not provide credentials for the given URI.
2FailureThe provider is the correct provider for the given URI, but cannot provide credentials. In this case, nuget.exe will not retry authentication and will fail. A typical example is when a user cancels an interactive login.
- -### Standard output - - - - - - - - - - - - - - - - -
PropertyNotes
UsernameUsername for authenticated requests. -
PasswordPassword for authenticated requests.
MessageOptional details about the response, used only to show additional details in failure cases.
- -Example stdout: - - { "Username" : "freddy@example.com", - "Password" : "bwm3bcx6txhprzmxhl2x63mdsul6grctazoomtdb6kfbof7m3a3z", - "Message" : "" } - diff --git a/docs/API/NuGet-API-V3.md b/docs/API/NuGet-API-V3.md deleted file mode 100644 index 7489eff24..000000000 --- a/docs/API/NuGet-API-V3.md +++ /dev/null @@ -1,9 +0,0 @@ -# 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/API/_metadata b/docs/API/_metadata deleted file mode 100644 index 839833919..000000000 --- a/docs/API/_metadata +++ /dev/null @@ -1,2 +0,0 @@ -Credential Providers -NuGet API v3 \ No newline at end of file diff --git a/docs/Consume-Packages/Configuring-NuGet-Behavior.md b/docs/Consume-Packages/Configuring-NuGet-Behavior.md deleted file mode 100644 index 7bc7b233b..000000000 --- a/docs/Consume-Packages/Configuring-NuGet-Behavior.md +++ /dev/null @@ -1,241 +0,0 @@ -# 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](/ndocs/schema/nuget.config-file.md) topic. - -The preferred method for changing the configuration is using the NuGet [config command](/ndocs/tools/nuget.exe-cli-reference#config) to set a key and value. - -
- Note:
- Keys are always case sensitive. -
- -To **set a value** in any existing configuration file, use the `-configFile` switch as shown in the examples below. - - nuget config -set repositoryPath=c:\packages -configfile c:\my.config - nuget config -set repositoryPath=c:\packages -configfile .\myApp\NuGet.Config - nuget config -set repositoryPath=c:\packages -configfile %ProgramData%\NuGet\Config\VisualStudio\14.0\NuGet.Config - nuget config -set repositoryPath=c:\packages -configfile %ProgramData%\NuGet\NuGetDefaults.Config - -Without the `-configFile` switch, NuGet 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: - - 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: - - - - - -
- Note:
- 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. -2. The global config file, except in NuGet 3.4 and later if `-configFile` is used on the command line. -3. The file specified with `-configFile`. -4. 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. - -2. For collection elements (such as ``), values from all configuration files are added to the collection. - -3. 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: - -(A) Global configuration file, `%APPDATA%\NuGet\Nuget.config`: - - - - - - - - -(B) `d:\NuGet.config`: - - - - - - - - - - - -(C) `d:\Project1\NuGet.config`: - - - - - - - - - - - - - -(D) `d:\Project2\NuGet.config`: - - - - - - - - - - - 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: - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/Consume-Packages/Dependency-Resolution.md b/docs/Consume-Packages/Dependency-Resolution.md deleted file mode 100644 index 2e53c3ed4..000000000 --- a/docs/Consume-Packages/Dependency-Resolution.md +++ /dev/null @@ -1,107 +0,0 @@ -# Dependency Resolution - -Any time a package is installed or reinstalled, which includes being installed as part of a [restore](/ndocs/consume-packages/package-restore) 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. - - -## 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](https://docs.nuget.org/release-notes/nuget-2.8#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. -2. Project files are not modified, avoiding merge conflicts and file churn on commits. This also allows the project system to evolve independent of NuGet. -3. Developers can easily change dependency versions without worrying about side effects on the rest of the project. -4. Hint paths are not being burned into the project files, fixing the ability to move projects around on disk, and re-targeting problems. -5. 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. -6. 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](/images/consume/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](/images/consume/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](/images/consume/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](/images/consume/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](/images/consume/projectJson-dependency-5.png) - -
- Note
- 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. -
- -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](/images/consume/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](/images/consume/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](/images/consume/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. diff --git a/docs/Consume-Packages/Enabling-Symbol-Packages.md b/docs/Consume-Packages/Enabling-Symbol-Packages.md deleted file mode 100644 index 115994c3c..000000000 --- a/docs/Consume-Packages/Enabling-Symbol-Packages.md +++ /dev/null @@ -1,20 +0,0 @@ -# Enabling Symbol Packages - -Package authors have the option to create [Symbol packages](/ndocs/create-packages/symbol-packages) for their libraries and upload them to the [SymbolSource repository](http://www.symbolsource.org/Public). - -When you configure Visual Studio to use symbol packages in the debugger, it will automatically download an available symbol package when you install an associated package from nuget.org. - -To enable this behavior, do the following: - -1. Select **Tools > Options** on the menu and expand **Debugger > Symbols**. -2. In the right hand pane, select the folder icon on the upper right, and enter `https://nuget.smbsrc.net` (if you start typing `nuget` you'll be given an auto-complete option for this). Click OK when you're done. - - ![Adding the NuGet symbol source to Visual Studio](/images/Consume/Symbols_01-AddingSource.png) - -When a symbol package is available, you'll be able to step directly into package code within the Visual Studio debugger. - -
- Note
- This same feature allows you to step into the .NET Framework code. See http://referencesource.microsoft.com/. -
- 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 4785ccd05..000000000 --- a/docs/Consume-Packages/Finding-and-Choosing-Packages.md +++ /dev/null @@ -1,93 +0,0 @@ -# Finding and Choosing Packages - -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](/images/Consume/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](/images/Consume/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. - - -### 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](/ndocs/create-packages/native-packages). - - -## 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](/images/Consume/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](/images/Consume/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, uncheck 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](/images/Consume/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 opions 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 licence 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 160b5836c..000000000 --- a/docs/Consume-Packages/Managing-the-NuGet-Cache.md +++ /dev/null @@ -1,31 +0,0 @@ -#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](/ndocs/tools/nuget.exe-cli-reference#locals): - - nuget locals all -list - -Typical output is as follows: - - http-cache: C:\Users\kraigb\AppData\Local\NuGet\v3-cache #3.x cache - packages-cache: C:\Users\kraigb\AppData\Local\NuGet\Cache #2.x cache - global-packages: C:\Users\kraigb\.nuget\packages\ #Global cache - temp: C:\Users\kraigb\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: - - 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. \ No newline at end of file diff --git a/docs/Consume-Packages/Overview-and-Workflow.md b/docs/Consume-Packages/Overview-and-Workflow.md deleted file mode 100644 index e61b8b48a..000000000 --- a/docs/Consume-Packages/Overview-and-Workflow.md +++ /dev/null @@ -1,24 +0,0 @@ -# Package Consumption Overview and 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 (including packages that support native C++ projects; see [Native C++ Packages](/ndocs/consume-packages/finding-and-choosing-packages#native-c++-packages)). But regardless of the source, consuming a package follows the same general workflow: - -![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](/images/Consume/Overview-01-GeneralFlow.png) - -For details, see [Finding and Choosing Packages](/ndocs/consume-packages/finding-and-choosing-packages) and the [Use a Package quickstart](/ndocs/quickstart/use-a-package). - -NuGet remembers the identity and version number of each installed package, recording it in either `packages.config` (NuGet 2.x) or `project.json` (NuGet 3.x) in your project root. You can look in the appropriate file at any time to see the full list of dependencies for your project. - -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](/ndocs/consume-packages/managing-the-nuget-cache). - -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](/images/Consume/Overview-02-RestoreFlow.png) - -[Package Restore](/ndocs/consume-packages/package-restore) 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](/ndocs/consume-packages/dependency-resolution). - -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](/ndocs/consume-packages/reinstalling-and-updating-packages). - -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](/ndocs/consume-packages/configuring-nuget-behavior). - -Enjoy your productive coding with NuGet packages! - \ No newline at end of file diff --git a/docs/Consume-Packages/Package-Restore.md b/docs/Consume-Packages/Package-Restore.md deleted file mode 100644 index 62d452f34..000000000 --- a/docs/Consume-Packages/Package-Restore.md +++ /dev/null @@ -1,212 +0,0 @@ -# NuGet 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](/ndocs/consume-packages/packages-and-source-control) 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](/ndocs/consume-packages/team-foundation-build). - -
- 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](/images/consume/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.) - - ... - - - - - - - - -
- 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. - - ... - - - - - - - -For reference, see the [NuGet config file overview](/ndocs/consume-packages/nuget-config-file-overview). - -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](/ndocs/consume-packages/configuring-nuget-behavior#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](/ndocs/consume-packages/reinstalling-and-updating-packages#constraining-upgrade-versions). For example: - - - -- `project.json`: Specify a version range directly with the dependency's version number. For example: - - "newtonsoft.json": "[6, 7)" - -In both cases, use the notation described in [Dependency versions](/ndocs/create-packages/dependency-versions). - - -## Command-line restore - -For NuGet 2.6 and earlier, you use the [Install](/ndocs/tools/nuget.exe-cli-reference#install) command and point to the `packages.config` file that lists all the dependencies. - -For NuGet 2.7 and above, use the [Restore](/ndocs/tools/nuget.exe-cli-reference#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: - - 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 unchecking **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](/ndocs/consume-packages/packages-and-source-control) 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](/ndocs/consume-packages/managing-the-nuget-cache). 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). -2. Update `nuget.exe` in the `.nuget` folder** as follows - - cd .nuget - nuget update -self - -3. Reset consent in your `%AppData%\NuGet\NuGet.config` file by going to **Tools > Options > NuGet Package Manager > General** in Visual Studio, uncheck and re-check 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 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](/ndocs/consume-packages/packages-and-source-control#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. -2. If using TFS: - a. Remove `nuget.exe` and `nuget.targets` from the solution's `.nuget` folder and remove those files from the solution workspace. - b. Retain `nuget.config` with the `disableSourceControlIntegration` setting as explained in [Omitting packages with Team Foundation Version Control](/ndocs/consume-packages/packages-and-source-control#omitting-packages-with-team-foundation-version-control). -3. If not using TFS: - a. Remove the `.nuget` folder from the solution and the solution workspace. -4. Edit each project file in the solution, remove the `<RestorePackages>` element, and remove any references to the `nuget.targets` file. Those settings generally appear as follows: - - 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 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. -2. 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](/images/consume/Restore-02-VSTSBuild.png) - - -### Team Foundation Server - -With TFS 2013 and later, packages are automatically restored by default during build, provided that you're using a Team Build Template for Team Foundation Server 2013 or later. - -If you're using a previous version of build templates (such as in a project that's been migrated from earlier versions of TFS), you'll need to also migrate those build templates to TFS 2013. This essentially means recreating the custom parts of the Build Templates using the appropriate template for your source control (TFVC or Git). - -For earlier version of TFS, you can simply include a build step to invoke [command-line restore](#command--line-restore) as described earlier. - -For more details see then [Walkthrough of Package Restore with Team Foundation Build](/ndocs/consume-packages/team-foundation-build). - - -### Command-line restore wrapped in MSBuild - -With existing build servers and MSBuild-based projects, you can also choose to 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 40d79df83..000000000 --- a/docs/Consume-Packages/Packages-and-Source-Control.md +++ /dev/null @@ -1,62 +0,0 @@ -# Packages and source control - -Developers typically omit binaries, such as NuGet packages, from their source control repository and rely instead on [package restore](/ndocs/consume-packages/package-restore) 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. -2. 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. -3. 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. -4. 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 - - -## 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. -2. In that folder, create a file named `NuGet.config` and open it for editing. -3. Add the following text as a minimum, where the [disableSourceControlIntegration](/ndocs/schema/nuget.config-file#solution-section) setting instructs Visual Studio to skip everything in the `packages` folder: - - - - - - - - -4. If you are using TFS 2010 or earlier, cloak the `packages` folder in your workspace mappings. -5. On TFS 2012 or later, or with Visual Studio Team Services, add a [`.tfignore`](https://msdn.microsoft.com/en-us/library/ms245454.aspx#tfignore) file with the content below to explicitly ignore modifications to the `\packages` folder on the repository level. (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 - -5. 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 290feb8ef..000000000 --- a/docs/Consume-Packages/Reinstalling-and-Updating-Packages.md +++ /dev/null @@ -1,67 +0,0 @@ -# Reinstalling and Updating 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**): - - - Update-Package –reinstall <package_name> - - -Using this command is much easier than removing a package and then trying to locate the same package in the NuGet gallery with the same version. - -The same command without `-reinstall` will update a package to a newer version, if applicable: - - - Update-Package <package_name> - - -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](/ndocs/tools/powershell-reference#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. -2. **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. -3. **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. -4. **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. -5. **Improved NuGet package development cycle**: 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 ` work. 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. - -2. **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 - -3. **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]`: - - - - - - - - -In all cases, use the notation described in [Dependency versions](/ndocs/create-packages/dependency-versions). - - \ No newline at end of file diff --git a/docs/Consume-Packages/Team-Foundation-Build.md b/docs/Consume-Packages/Team-Foundation-Build.md deleted file mode 100644 index 70c5cd8df..000000000 --- a/docs/Consume-Packages/Team-Foundation-Build.md +++ /dev/null @@ -1,177 +0,0 @@ -# Walkthrough of Package Restore with Team Foundation Build - -> Applies To: -> - Custom MSBuild projects running on any version of TFS -> - Team Foundation Server 2012 or earlier -> - Custom Team Foundation Build Process Templates migrated to TFS 2013 or later -> - Build Process Templates With Nuget Restore functionality removed - -> If you're using Visual Studio Team Services or on-premises Team Foundation Server 2013 with its build process templates, Automatic Package Restore happens as part of the build process. - -This section will provide a detailed walkthrough on how to restore packages as part of the [Team Foundation Build](http://msdn.microsoft.com/en-us/library/ms181710(v=VS.90).aspx) both, for [git](http://en.wikipedia.org/wiki/Git_(software)) as well as [TF Version Control](http://msdn.microsoft.com/en-us/library/ms181237(v=vs.120).aspx). - -Although this walkthrough is specific for the scenario of using [Team Foundation Service](http://tfs.visualstudio.com/), the concepts also apply to other version control- and build systems. - -## The General Approach - -An advantage of using NuGet is that you can use it to avoid checking in binaries to your version control system. - -This is especially interesting if you are using a [distributed version control](http://en.wikipedia.org/wiki/Distributed_revision_control) system like git because developers need to clone the entire repository, including the full history, before they can start working locally. Checking in binaries can cause significant repository bloat as binary files are typically stored without delta compression. - -NuGet has supported [restoring packages](/ndocs/consume-packages/package-restore) as part of the build for a long time now. The previous implementation had a chicken-and-egg problem for packages that want to extend the build process because NuGet restored packages while building the project. However, MSBuild doesn't allow extending the build during the build; one could argue that this an issue in MSBuild but I would argue that this is an inherent problem. Depending on which aspect you need to extend it might be too late to register by the time your package is restored. - -The cure to this problem is making sure that packages are restored as the first step in the build process. NuGet 2.7+ makes this easy via a simplified command line: - - nuget.exe restore path\to\solution.sln - -When your build process restores packages before building the code, you don't need to check-in **.targets** files - -

-Note
Packages must be authored to allow loading in Visual Studio. Otherwise, you may still want to check in .targets files so that other developers can simply open the solution without having to restore packages first. -

- -The following demo project shows how to set up the build in such a way that the `packages` folders and **.targets** files don't need to be checked-in. Finally, I'll show how you can setup an automated build on the [Team Foundation Service] for this sample project. - -## Repository Structure - -Our demo project is a simple command line tool that uses the command line argument to query Bing. It targets the .NET Framework 4 and uses many of the [BCL packages](http://www.nuget.org/profiles/dotnetframework/) ([Microsoft.Net.Http](http://www.nuget.org/packages/Microsoft.Net.Http), [Microsoft.Bcl](http://www.nuget.org/packages/Microsoft.Bcl), [Microsoft.Bcl.Async](http://www.nuget.org/packages/Microsoft.Bcl.Async), and [Microsoft.Bcl.Build](http://www.nuget.org/packages/Microsoft.Bcl.Build)). - -The structure of the repository looks as follows: - - - │ .gitignore - │ .tfignore - │ build.proj - │ - ├───src - │ │ BingSearcher.sln - │ │ - │ └───BingSearcher - │ │ App.config - │ │ BingSearcher.csproj - │ │ packages.config - │ │ Program.cs - │ │ - │ └───Properties - │ AssemblyInfo.cs - │ - └───tools - └───NuGet - NuGet.exe - -You can see that we haven't checked-in the `packages` folder nor any **.targets** files. - -We have, however, checked-in the `nuget.exe` as it's needed during the build. Following widely used conventions we've checked it in under a shared `tools` folder. - -The source code is under the `src` folder. Although our demo only uses a single solution, you can easily imagine that this folder contains more than one solution. - -### Ignore Files - -

-Note
There is currently a known bug in the NuGet Client that causes the client to still add the packages folder to version control. A workaround is to disable the source control integration. In order to do that, you'll need a nuget.config file in the .nuget folder that is parallel to your solution. If this folder doesn't exist yet, you'll need to create it. In nuget.config, add the following content:
- -

<configuration>
-    <solution>
-        <add key="disableSourceControlIntegration" value="true" />
-    </solution>
-</configuration>
-
- -For more details have a look at the NuGet Config Settings. -

- -In order to communicate to the version control that we don’t intent to check-in the **packages** folders, we've also added ignore files for both git (`.gitignore`) as well as TF version control (`.tfignore`). These files describes patterns of files you don't want to check-in. - -The `.gitignore` file looks as follows: - - syntax: glob - *.user - *.suo - bin - obj - packages - -The `.gitignore` file is [quite powerful](https://www.kernel.org/pub/software/scm/git/docs/gitignore.html). For example, if you want to generally not check-in the contents of the `packages` folder but want to go with previous guidance of checking in the **.targets** files you could have the following rule instead: - - packages - !packages/**/*.targets - -This will exclude all `packages` folders but will re-include all contained **.targets** files. By the way, you can find a template for `.gitignore` files that is specifically tailored for the needs of Visual Studio developers [here](https://github.com/github/gitignore/blob/master/VisualStudio.gitignore). - -TF version control supports a very similar mechanism via the [.tfignore](http://msdn.microsoft.com/en-us/library/ms245454.aspx) file. The syntax is virtually the same: - - *.user - *.suo - bin - obj - packages - -## build.proj - -For our demo, we keep the build process fairly simple. We'll create an MSBuild project that builds all solutions while making sure that packages are restored before building the solutions. - -This project will have the three conventional targets `Clean`, `Build` and `Rebuild` as well as a new target `RestorePackages`. - -- The `Build` and `Rebuild` targets both depend on `RestorePackages`. This makes sure that you can both run `Build` and `Rebuild` and rely on packages being restored. -- `Clean`, `Build` and `Rebuild` invoke the corresponding MSBuild target on all solution files. -- The `RestorePackages` target invokes `nuget.exe` for each solution file. This is accomplished by using [MSBuild's batching functionality](http://msdn.microsoft.com/en-us/library/ms171473.aspx). - -The result looks as follows: - - - - - - $(MSBuildThisFileDirectory)bin\ - Release - $(MSBuildThisFileDirectory)src\ - $(MSBuildThisFileDirectory)tools\ - - - - - OutDir=$(OutDir);Configuration=$(Configuration) - - - - - - - - - - - - - - - - - - - - - -## Configuring Team Build - -Team Build offers various process templates. For this demonstration, we're using the [Team Foundation Service]. On-premises installations of TFS will be very similar though. - -Git and TF Version Control have different Team Build templates, so the following steps will vary depending on which version control system you are using. In both cases, all you need is selecting the build.proj as the project you want to build. - -First, let's look at the process template for git. In the git based template the build is selected via the property `1. Solution to build`: - -![Build Process for git](/images/consume/PackageRestoreTeamBuildGit.png) - -Please note that this property is a location in your repository. Since our `build.proj` is in the root, we simply used `build.proj`. If you place the build file under a folder called `tools`, the value would be `tools\build.proj`. - -In the TF version control template the project is selected via the property `1. Projects`: - -![Build Process for TFVC](/images/consume/PackageRestoreTeamBuildTFVC.png) - -In contrast to the git based template the TF version control supports pickers (the button on the right hand side with the three dots). So in order to avoid any typing errors we suggest you use them to select the project. - diff --git a/docs/Consume-Packages/_metadata b/docs/Consume-Packages/_metadata deleted file mode 100644 index 6cd7468c3..000000000 --- a/docs/Consume-Packages/_metadata +++ /dev/null @@ -1,10 +0,0 @@ -Overview-and-Workflow -Finding-and-Choosing-Packages -Reinstalling-and-Updating-Packages -Packages-and-Source-Control -Package-Restore -Managing-the-NuGet-Cache -Configuring-NuGet-Behavior -Enabling-Symbol-Packages -Dependency-Resolution -Team-Foundation-Build \ No newline at end of file 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 e2c6a6ce8..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 57ef85693..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 5ca41d2e1..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 7828a8957..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 82f420d1d..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 cf1efb314..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 49f961b9c..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 60b80fbcb..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 82f59fb83..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 c9cdc4926..000000000 --- a/docs/Create-Packages/Creating-a-Package.md +++ /dev/null @@ -1,408 +0,0 @@ -#Creating a Package - -
- 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. -
- -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). 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](/ndocs/schema/nuspec) for complete details. - -Here's typical (but fictitious) `.nuspec` file, with annotation comments: - - - - - - 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](/ndocs/create-packages/dependency-versions). - -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: - - - 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 starting with an editing file from another project. You can also have NuGet create a template manifest for your by using the following command: - - - nuget spec - - -The resulting `.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 metatdata in the assembly using the following command: - - - 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: - - - nuget spec - - -This creates a template `.nuspec` file as usual, 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 <id> value will typically appear as follows: - - $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](/ndocs/schema/nuspec#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: - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FolderDescriptionAction upon package install
toolsPowerShell scripts and programs accessible from the Package Manager ConsoleContents are copied to the project folder, and the tools folder is added to the PATH environment variable.
libAssemblies (.dll files)Added as assembly references
contentArbitrary filesContents are copied to the project root
buildMSBuild .targets and .props filesAutomatically inserted into the project file (NuGet 2.x) or project.json.lock (NuGet 3.x)
- -Think of the **content** folder as the 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: - - - 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 **<id>** and the version number in **<version>** are the two most important values in the manifest because they uniquely identify the exact code that's contained in the package. - -For the **<id>** 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 **<version>** 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](/ndocs/create-packages/dependency-versions). - -
- Note
- The following series of brief blog posts are also helpful to understand versioning: - -
- -## 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/en-us/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/en-us/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: - - - - - - - - - - - -- `project.json`: Indicate the package type within a `packOptions.packageType` property json: - - { - // ... - "packOptions": { - "packageType": "DotnetCliTool" - } - } - -## Adding a readme and other files - -To directly specify files to include in the package, use the **<files>** node in the `.nuspec` file, which *follows* the <metadata> tag: - - - - - - - - - - - - - - - -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](/images/Create/Create_01-ShowReadme.png) - -
- Note
- If you include an empty <files> 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 <files> node: - - - - - - - - - - - - - - - - -When NuGet 2.x installs a package with `\build` files, it will add an MSBuild <Import> 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: - - - nuget pack <your_project>.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: - - - nuget pack <your_project>.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](/ndocs/create-packages/publish-a-package). - -
- Package Explorer
- A helpful way to examine a package after creating it is to open it in the Package Explorer 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 directory, among other features. For a complete list, refer to the [pack command reference](/ndocs/tools/nuget.exe-cli-reference#pack). - -The following options are a few that are common with Visual Studio projects: - -- **Referenced projects**: If the project references other projects, you can add the referenced projects as part of the package, or as dependencies, by using the `-IncludeReferencedProjects` option: - - - nuget pack MyProject.csproj -IncludeReferencedProjects - - - This inclusion process is recursive, so if MyProject.csproj references projects B and C, and those projects reference D, E, and F, then files from B, C, D, E, and F 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: - - - nuget pack MyProject.csproj -properties Configuration=Release - - - -- **Symbols**: to include symbols that allow consumers to step through your package code in the debugger, use the `-Symbols` option: - - - nuget pack MyProject.csproj -symbols - - - -##Next Steps - -Once you've created a package, which is a `.nupkg` file, you can publish it to the gallery of your choice as described on [Publishing a Package](/ndocs/create-packages/publish-a-package). - -You might also want to extend the capabilities of your package or otherwise support other scenarios as described in the following topics: - -- [Handling dependencies](/ndocs/create-packages/dependency-versions) -- [Supporting multiple target frameworks](/ndocs/create-packages/supporting-multiple-target-frameworks) -- [Transformations of source and configuration files](/ndocs/create-packages/source-and-config-file-transformations) -- [Localization](/ndocs/create-packages/creating-localized-packages) -- [Pre-release versions](/ndocs/create-packages/prerelease-packages) - -Finally, there are additional package types to be aware of: - -- [Native Packages](/ndocs/create-packages/native-packages) -- [Symbol Packages](/ndocs/create-packages/symbol-packages) - diff --git a/docs/Create-Packages/Dependency-Versions.md b/docs/Create-Packages/Dependency-Versions.md deleted file mode 100644 index 4c44ccaa6..000000000 --- a/docs/Create-Packages/Dependency-Versions.md +++ /dev/null @@ -1,144 +0,0 @@ -# Dependency Versions - -When you [create a NuGet package](/ndocs/create-packages/creating-a-package), you can specify dependencies for your package in the **<dependencies>** node of the `.nuspec` file, where each dependency is listed with a **<dependency>** tag: - - - - - - - - - - - - - -Dependencies are installed whenever the dependent package is installed, [reinstalled](/ndocs/consume-packages/reinstalling-and-updating-packages), or included in a [package restore](/ndocs/consume-packages/package-restore). 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 adornmants 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](/ndocs/consume-packages/reinstalling-and-updating-packages) and [Dependency resolution](/ndocs/consume-packages/dependency-resolution). - - -## Version ranges - -NuGet supports using interval notation for specifying version ranges, summarized as follows: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NotationApplied ruleDescription
1.01.0 ≤ xMinimum version, inclusive
(1.0,)1.0 < xMininum version, exclusive
[1.0]x == 1.0Exact version match
(,1.0]x ≤ 1.0Maximum version, inclusive
(,1.0)x < 1.0Maximum version, exclusive
[1.0,2.0]1.0 ≤ x ≤ 2.0Exact range, inclusive
(1.0,2.0)1.0 < x < 2.0Exact range, exclusive
(1.0)invalidinvalid
- - -A few examples: - - - - - - - - - - - - - - - - - -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 - -
- 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 0187b2e65..000000000 --- a/docs/Create-Packages/Overview-and-Workflow.md +++ /dev/null @@ -1,22 +0,0 @@ -#Overview and 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. - -To learn and understand the creation process, start with [Creating a package](/ndocs/create-packages/creating-a-package) 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](/ndocs/create-packages/dependency-versions) 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](/ndocs/create-packages/supporting-multiple-target-frameworks) describes how to create a package with multiple variants for different .NET Frameworks. -- [Source and Config File Transformations](/ndocs/create-packages/source-and-config-file-transformations) 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](/ndocs/create-packages/creating-localized-packages) describes how to structure a package with multiple language resources and how to use separate localized satellite packages. -- [Pre-release Packages](/ndocs/create-packages/prerelease-packages) demonstrates how to release alpha, beta, and rc packages to those customers who are interested. -- [Native Packages](/ndocs/create-packages/native-packages) describes the process for creating a package for C++ consumers. -- [Symbol Packages](/ndocs/create-packages/symbol-packages) 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](/ndocs/create-packages/publish-a-package). - -If you want to use a private feed instead of nuget.org, see the [Hosting Packages Overview](/ndocs/hosting-packages/overview) \ No newline at end of file diff --git a/docs/Create-Packages/Prerelease-Packages.md b/docs/Create-Packages/Prerelease-Packages.md deleted file mode 100644 index dfa6bc76b..000000000 --- a/docs/Create-Packages/Prerelease-Packages.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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](/images/Create/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](/ndocs/consume-packages/reinstalling-and-updating-packages)). - -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: - - 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: - - [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 prerelese checkbox in Visual Studio](/images/Create/Prerelease_02-CheckPrerelease.png) - - Checking or unchecking 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](/ndocs/tools/powershell-reference). - -- **NuGet CLI**: Use the `-prerelease` switch with the `install`, `update`, `delete`, and `mirror` commands. Refer to the [NuGet CLI reference](/ndocs/tools/nuget.exe-cli-reference) - - -## 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 4127b71e0..000000000 --- a/docs/Create-Packages/Publish-a-package.md +++ /dev/null @@ -1,70 +0,0 @@ -#Publish a Package - -Once you have [created a package](/ndocs/create-packages/creating-a-package) 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](/ndocs/hosting-packages/overview)) - -##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](/images/Create/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](/images/Create/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](/images/Create/publish_APIKey.png) - - 3. At a command prompt, run the following command: - - 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: - - nuget push YourPackage.nupkg - - 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](/images/Create/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'p 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/Source-and-Config-File-Transformations.md b/docs/Create-Packages/Source-and-Config-File-Transformations.md deleted file mode 100644 index bbe44ca55..000000000 --- a/docs/Create-Packages/Source-and-Config-File-Transformations.md +++ /dev/null @@ -1,155 +0,0 @@ -# Source Code and Configuration File Transformations - -NuGet supports the ability to make transformations to source code and configuration files at package install and uninstall times. - -A **source code transformation** applies one-way token replacement to files in the package's `content` folder when the package is installed, where tokens refer to Visual Studio [project properties](https://msdn.microsoft.com/library/vslangproj.projectproperties_properties.aspx). This allows you to insert a file into the project's namespace, or to customize code that would typically go into `global.asax` in an ASP.NET project. - -A **config file transformation** allows you to modify files that already exist in a target project, such as `web.config` and `app.config`. For example, your package might need to add an item to the `modules` section in the config file. This transformation is done by including special files in the package that describe the sections to add to the configuration files. When a package is uninstalled, those same changes are then reversed, making this a two-way transformation. - - -## Specifying source code transformations - -1. Files that you want to insert from the package into the project must be located within the package's `content` folder. For example, if you want a file called `ContosoData.cs` to be installed in a `Models` folder of the target project, it must be inside the `content\Models` folder in the package. - -2. To instruct NuGet to apply token replacement at install time, append `.pp` to the source code file name. After installation, the file will not have the `.pp` extension. - - For example, to make transformations in `ContosoData.cs`, name the file in the package `ContosoData.cs.pp`. After installation it will appear as `ContosoData.cs`. - -3. In the source code file, use case-insensitive tokens of the form `$token$` to indicate values that NuGet should replace with project properties: - - namespace $rootnamespace$.Models { - public struct CategoryInfo { - public string categoryid; - public string description; - public string htmlUrl; - public string rssUrl; - public string title; - } - } - - Upon installation, NuGet replaces `$rootnamespace$` with `Fabrikam` assuming the target project's whose root namespace is `Fabrikam`. - -The `$rootnamespace$` token is the most commonly used project property; all others are listed in the [Project Properties](https://msdn.microsoft.com/library/vslangproj.projectproperties_properties.aspx) documentation on MSDN. Be mindful, of course, that some properties might be specific to the project type. - - -## Specifying config file transformations - -As described in the sections that follow, config file transformations can be done in two ways: - -- Include `app.config.transform` and `web.config.transform` files in your package's `content` folder, where the `.transform` extension tells NuGet that these files contain the XML to merge with existing config files when the package is installed. When a package is uninstalled, that same XML is removed. -- (NuGet 2.6 and later) Include `app.config.install.xdt` and `web.config.install.xdt` files in your package's `content` folder, using [XDT syntax](https://msdn.microsoft.com/library/dd465326.aspx) to describe the desired changes. With this option you can also include a `.uninstall.xdt` file to reverse changes when the package is removed from a project. - -
- Note
- Transformations are not applied to .config files referenced as a link in Visual Studio. -
- -The advantage of using XDT is that instead of simply merging two static files, it provides a syntax for manipulating the structure of an XML DOM using element and attribute matching using full XPath support. XDT can then add, update, or remove elements, place new elements at a specific location, or replace/remove elements (including child nodes). This makes it straightforward to create uninstall transforms that back out all transformations done during package installation. - -### XML transforms - -The `app.config.transform` and `web.config.transform` in a package's `content` folder contain only those elements to merge into the project's existing `app.config` and `web.config` files. - -As an example, suppose the project initially contains the following content in `web.config`: - - - - - - - - - -To add a `MyNuModule` element to the `modules` section during package install, create a `web.config.transform` file in the package's `content` folder that looks like this: - - - - - - - - - -After NuGet installs the package, `web.config` will appear as follows: - - - - - - - - - - -Notice that NuGet didn't replace the `modules` section, it just merged the new entry into it by adding only new elements and attributes. NuGet will not change any existing elements or attributes. - -When the package is uninstalled, NuGet will examine the `.transform` files again and remove the elements it contains from the appropriate `.config` files. Note that this process will not affect any lines in the `.config` file that you modify after package installation. - -As a more extensive example, the [Error Logging Modules and Handlers for ASP.NET (ELMAH)](https://www.nuget.org/packages/elmah/) package adds many entries into `web.config`, which are again removed when a package is uninstalled. - -To examine its `web.config.transform` file, download the ELMAH package from the link above, change the package extension from `.nupkg` to `.zip`, and then open `content\web.config.transform` in that ZIP file. - -To see the effect of installing and uninstalling the package, create a new ASP.NET project in Visual Studio (the template is under **Visual C# > Web** in the New Project dialog), and select an empty ASP.NET application. Open `web.config` to see its initial state. Then right-click the project, select **Manage NuGet Packages**, browse for ELMAH on nuget.org, and install the latest version. Notice all the changes to `web.config`. Now uninstall the package and you'll see `web.config` revert to its prior state. - - -### XDT transforms - -With NuGet 2.6 and later, you can modify config files using [XDT syntax](https://msdn.microsoft.com/library/dd465326.aspx). You can also have NuGet replace tokens with [Project Properties](https://msdn.microsoft.com/library/vslangproj.projectproperties_properties.aspx) by including the property name within `$` delimeters (case-insensitive). - -For example, the following `app.config.install.xdt` file will insert an `appSettings` element into `app.config` containing the `FullPath`, `FileName`, and `ActiveConfigurationSettings` values from the project: - - - - - - - - - - -For another example, suppose the project initially contains the following content in `web.config`: - - - - - - - - - -To add a `MyNuModule` element to the `modules` section during package install, the package's `web.config.install.xdt` would contain the following: - - - - - - - - - - -After installing the package, `web.config` will look like this: - - - - - - - - - - -To remove only the `MyNuModule` element during package uninstall, the `web.config.uninstall.xdt` file should contain the following: - - - - - - - - - - - - - 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 917adb795..000000000 --- a/docs/Create-Packages/Supporting-Multiple-Target-Frameworks.md +++ /dev/null @@ -1,147 +0,0 @@ -#Supporting Multiple .NET Framework Versions - -Many libraries target a specific version of the .NET Framework. For example, you might have one version of your library that's specific to UWP, and another version that takes advantage of features in .NET Framework 4.6. - -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](/ndocs/create-package/creating-a-package#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](/ndocs/schema/target-frameworks#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 - -
- Note
- 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 <files> section of your `.nuspec`: - - - - - -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 to 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 4738367be..000000000 --- a/docs/Create-Packages/Symbol-Packages.md +++ /dev/null @@ -1,108 +0,0 @@ -# Symbol Packages - -In addition to building packages for nuget.org or other sources, NuGet also supports creating associated symbol packages and publishing them to the [SymbolSource repository](http://www.symbolsource.org/Public). - -Package consumers can then add https://nuget.smbsrc.net/ to their symbol sources in Visual Studio. This allows consumers to step into your package code in the Visual Studio debugger. - -## Creating a symbol package - -To create a symbol package, follow these conventions: -- Name the primary package (with your code) `{identifier}.nupkg` and include all your files except `.pdb` files. -- Name the symbol package `{identifier}.symbols.nupkg` and include your assembly DLL, `.pdb` files, XMLDOC files, source files (see the sections that follow). - -You can create both packages with the `-Symbols` option, either from a nuspec file or a project file: - - - nuget pack MyPackage.nuspec -Symbols - - - - nuget pack MyProject.csproj -Symbols - - -## 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: - - - - - - - - - -## Publishing a symbol package - -1. For convenience, first save your API key with NuGet (see [publish a package](/ndocs/create-packages/publish-a-package), which will apply to both nuget.org and symbolsource.org, because symbolsource.org will check with nuget.org to verify that you are the package owner. - - - nuget push MyPackage.symbols.nupkg - - - -3. To publish to a different symbol repository, or to push a symbol package that doesn't follow the naming convention, use the `-Source` option: - - - nuget push MyPackage.nupkg - - - In this case, NuGet will publish `MyPackage.symbols.nupkg`, if present, to symbolsource.org (https://nuget.smbsrc.net/), after it publishes the primary package to nuget.org. - - diff --git a/docs/Create-Packages/_metadata b/docs/Create-Packages/_metadata deleted file mode 100644 index 69960d24b..000000000 --- a/docs/Create-Packages/_metadata +++ /dev/null @@ -1,12 +0,0 @@ -Overview-and-Workflow -Creating-a-Package -Dependency-Versions -Supporting-Multiple-Target-Frameworks -Source-and-Config-File-Transformations -Creating-Localized-Packages -Prerelease-Packages -Native-Packages -Symbol-Packages -Publish-a-package -project.json-and-UWP -project.json-Impact \ 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-Impact.md b/docs/Create-Packages/project.json-Impact.md deleted file mode 100644 index cb08d056a..000000000 --- a/docs/Create-Packages/project.json-Impact.md +++ /dev/null @@ -1,62 +0,0 @@ -# project.json Impact on Package Authors - -The project.json system used in NuGet 3.x affects package authors in several ways as described in the following sections. - -- [Install and uninstall scripts are ignored](#install-and-uninstall-scripts-are-ignored) - - -## Changes affecting existing packages usage - -Traditional NuGet packages support a set of features that are not carried over to the transitive world. - -### Install and uninstall scripts are ignored - -The transitive restore model, described in [Dependency resolution](/ndocs/consume-packages/dependency-resolution#dependency-resolution-in-nuget-3-x), does not have a concept of "package install time". A package is either present or not present, but there is no consistent process that occurs when a package is installed. - -Also, install scripts were supported only in Visual Studio. Other IDEs had to mock the Visual Studio extensibility API to attempt to support such scripts, and no support was available in common editors and command-line tools. - -### Content transforms are not supported. - -Similar to install scripts, transforms run on package install and are typically not idempotent. Since there is no install time anymore, XDT Transform and similar features are not supported, and will be ignored if such a package is used in a transitive scenario. - - -### Content - -Traditional NuGet packages are shipping content files such as source code and configuration files. There are used typically in two scenarios - -1. Initial files dropped into the project so the user can edit them at a later time. The common example is default configuration files. - -2. Content files used as companions to the assemblies installed in the project. The example here would be a logo image used by an assembly. - -Support for content is currently disabled for similar reasons for scripts and transforms, but we are in the process of designing support for content. - -Content files can still be carried inside the packages, and will be ignored currently, however the end user can still copy them into the right spot. - -You can see one of the proposals for bringing back content files, and follow its progress, here: [https://github.com/NuGet/Home/issues/627](https://github.com/NuGet/Home/issues/627) - -## Impact for Package Authors - -Packages using the above features would have to use a different mechanism. The most commonly useful mechanism for this would be the MSBUILD targets/props that continues to get fully supported. The build system can choose to pick up other conventions in the package. This is how msbuild targets are supported as well as Roslyn analyzers. It is possible to build packages that supports targets and analyzers for packages.config and project.json scenarios. - -Packages that attempt to modify the project to ease startup, typically work in a very limited set of scenarios, and will instead provide a readme, or guidance on how to use the package. - -Most existing packages should not need to use the new package format described below. - -The new format enables native content as a first class scenario. This means that managed assemblies depending on close to hardware implementations to ship binary implementations alongside the managed assemblies based on the target platform. For example System.IO.Compression package is utilizing this technology. [https://www.nuget.org/packages/System.IO.Compression](https://www.nuget.org/packages/System.IO.Compression) - -In summary if the functionality above is not absolutely necessary, we recommend sticking with the existing package format. The new format will be supported only by NuGet 3.0. - -It would be possible to build packages to work for both packages.config and project.json scenarios through shimming, however it is often simpler to just structure the packages the traditional way, without the deprecated features mentioned above. - - -## 3.x Package Format ## - -The 3.x package format allows for several new features: - -1. Defining a reference assembly used for compilation and a set of implementation assemblies used for runtime on different platforms/devices. Which allows you to take advantage of platform specific APIs while providing a common surface area for your consumers. Specifically this makes writing intermediate portable libraries easier. - -2. Allows packages to pivot on platforms e.g. operating systems or CPU architecture. - -3. Allows for separation of platform specific implementations to companion packages. - -4. Support Native dependencies as a first class citizen. \ No newline at end of file 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 b563a531d..000000000 --- a/docs/Create-Packages/project.json-and-UWP.md +++ /dev/null @@ -1,196 +0,0 @@ -#Project.json and UWP - -This document describes a new package structure that can be used to take advantage of new features in NuGet v3. The *minClientVersion* property of your NuSpec can be used to state that you require the new 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 directory in your package and add the assembly that has been compiled to work with Windows 10 to that directory. - -## 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-directory 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, directory 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 directory, then the lib is both the reference assembly and the implementation assembly. - -* Runtimes - * runtimes is a new, optional, directory 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 .props and .targets 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 - -* [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/en-us/library/t50z2hka.aspx](https://msdn.microsoft.com/en-us/library/t50z2hka.aspx)). - - -## Lib and Ref ## - -The behavior of the Lib directory 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 directory 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 directory. 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/en-us/library/yabyz3h4.aspx](https://msdn.microsoft.com/en-us/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 directory will ever be picked, so if there is a runtime specific directory it will be chosen over non-runtime specific lib. The native directory 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 20e1a6b94..000000000 --- a/docs/Guides/Create-Cross-Platform-Packages.md +++ /dev/null @@ -1,244 +0,0 @@ -#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) -2. [Create the project structure and abstraction code](#create-the-project-structure-and-abstraction-code) -3. [Write your platform-specific code](#write-your-platform--specific-code) -4. [Create and update the .nuspec file](#create-and-update-the--nuspec-file) -5. [Package the component](#package-the-component) -6. [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. -2. 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. -2. 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](/images/BuildForXplat/01-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: - - 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): - - 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"); - } - } - } - -2. Repeat this implementation in the projects for each platform you want to support. -3. 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. -3. Right-click the solution, select **Configuration Manager...**, and check the **Build** boxes for the PCLs and each platform you're supporting. -4. 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. If you don't have a Mac available, uncheck the iOS project in the configuration manager (step 3 above). -
- -##Create and update the .nuspec file -1. Open a command prompt, navigate to the `LoggingLibrary` folder that's one level below where the .sln file is, and run the NuGet `spec` command to create the initial `Package.nuspec` file: - - - nuget spec - - -2. Rename this file to `LoggingLibrary.nuspec` and open it in an editor. -3. Update the file to match the following, replacing YOUR_NAME with an appropriate value. The <id> value, specifically, must be unique across nuget.org (see the naming conventions described in [Creating a package](/ndocs/create-packages/creating-a-package(#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. - - - - - 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 <files> element of `LoggingLibrary.nuspec` as appropriate for your supported platforms: - - - - - - - - - - - - - - - - - - - - - - -
- 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 <dependencies> element with <group> elements to specify them, for example: - - - - - - - - - - - - - - -For example, the following would set iTextSharp as a dependency for the UAP target: - - - - - - - -###Final nuspec - -Your final .nuspec file should now look like the following, where again YOUR_NAME should be replaced with an appropriate value: - - - - - LoggingLibrary.YOUR_NAME - 1.0.0 - LoggingLibrary - YOUR_NAME - YOUR_NAME - false - Awesome application logging utility - First release - Copyright 2016 - logger logging logs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -##Package the component -With the completed .nuspec referencing all the files you need to include in the package, you're ready to run the `pack` command: - - - nuget pack LoggingLibrary.nuspec - - -This will generate `LoggingLibrary.YOUR_NAME.1.0.0.nupkg`. Opening this file in a tool like the [NuGet Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer) and expanding all the nodes, you'll see the following contents: - -![NuGet Package Explorer showing the LoggingLibrary package](/images/BuildForXplat/04.PNG) - -
- Note
- A .nupkg file is just a ZIP file with a different extension. You can also examine package contents, then, by change .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](/ndocs/create-packages/publish-a-package). - -##Related topics - -* [Nuspec Reference](/ndocs/schema/nuspec) -* [Symbol packages](/ndocs/create-packages/symbol-packages) -* [Dependency Versions](/ndocs/create-packages/dependency-versions) -* [Supporting Multiple .NET Framework Versions](/ndocs/create-packages/supporting-multiple-target-frameworks) -* [Including MSBuild props and targets in a package](/ndocs/create-packages/creating-a-package#including-msbuild-props-and-targets-in-a-package) -* [Creating Localized Packages](/ndocs/create-packages/creating-localized-packages) \ No newline at end of file diff --git a/docs/Guides/Create-NET-Standard-Packages.md b/docs/Guides/Create-NET-Standard-Packages.md deleted file mode 100644 index a06deec74..000000000 --- a/docs/Guides/Create-NET-Standard-Packages.md +++ /dev/null @@ -1,381 +0,0 @@ -#Create .NET Standard Packages - -The [.NET Standard Library](https://docs.microsoft.com/en-us/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](#table) later in this topic. - -1. [Pre-requisites](#pre-requisites) -2. [Create the class library project](#create-the-class-library-project) -3. [Create and update the .nuspec file](#create-and-update-the--nuspec-file) -4. [Package the component](#package-the-component) -5. [Additional options](#additional-options) -5. [.NET Standard mapping table](#-net-standard-mapping-table) -6. [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. -2. .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). -3. 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](/images/BuildForNetStandard/01.PNG) - -2. In the **Add Portable Class Library** dialog that appears, select the `.NET Framework 4.6` and `ASP.NET Core 1.0` options. -3. 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](/images/BuildForNetStandard/02-ChangeTarget.png) - -5. Click on the **Build** tab, change the **Configuration** to `Release`, and check the box for **XML documentation file**. -6. Add your code to the component, for example: - - namespace AppLogger - { - public class Logger - { - public void Log(string text) - { - throw new NotImplementedException("Called Log"); - } - } - } - -6. Build the project (with the Release configuration) and check that DLL and XML files are produced within the bin\Release folder. - -##Create and update the .nuspec file - -1. Open a command prompt, navigate to the folder containing `AppLogg.csproj` folder (one level below where the .sln file is), and run the NuGet `spec` command to create the initial `AppLogger.nuspec` file: - - - nuget spec - - -2. Open `AppLogger.nuspec` in an editor and update it to match the following, replacing YOUR_NAME with an appropriate value. The <id> value, specifically, must be unique across nuget.org (see the naming conventions described in [Creating a package](/ndocs/create-packages/creating-a-package(#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. - - - - - 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 - - - -3. Add reference assemblies to the nuspec file, namely the library's DLL and the IntelliSense XML file: - - - - - - - -3. Right-click the solution and select **Build Solution** to generate all the files for the package. - - -##Package the component -With the completed .nuspec referencing all the files you need to include in the package, you're ready to run the `pack` command: - - - nuget pack AppLogger.nuspec - - -This will generate `AppLogger.YOUR_NAME.1.0.0.nupkg`. Opening this file in a tool like the [NuGet Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer) and expanding all the nodes, you'll see the following contents: - -![NuGet Package Explorer showing the AppLogger package](/images/BuildForNetStandard/03-PackageExplorer.PNG) - -
- Note
- A .nupkg file is just a ZIP file with a different extension. You can also examine package contents, then, by change .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](/ndocs/create-packages/publish-a-package). - - -##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 <dependencies> element with <group> elements. For example, to declare a dependency on NewtonSoft.Json 8.0.3 or above, add the following: - - - - - - - - -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](/ndocs/create-packages/dependency-versions). - -###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 mutliple 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`. -2. Inside `lib`, create folders for each platform you want to support: - - \lib - \netstandard1.4 - \AppLogger.dll - \net462 - \AppLogger.dll - -3. 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: - - - - - AppLogger.YOUR_NAME - 1.0.0.0 - AppLogger - YOUR_NAME - YOUR_NAME - false - Awesome application logging utility - First release. - Copyright 2016 - logger logging logs - - - - - - -4. Create the package again using `nuget pack AppLogger.spec`. - -For more details on using this technique, see [Supporting Multiple .NET Framework Versions](/ndocs/create-packages/supporting-multiple-target-frameworks) - -###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`. -2. 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 - -3. In the .nuspec file, add a `files` node under the `package` node and refer to the files in `build` using wildcards. - - - - ... - - - - - - -4. Create the package again using `nuget pack AppLogger.nuspec`. - -For additional details, refer to [Include MSBuild props and targets in a package](/ndocs/create-packages/creating-a-package#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 - -2. In the .nuspec file, reference these files in the <files> node: - - - - ... - - - - - - -3. 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: - - - - ... - - - - - - - -## .NET Standard mapping table - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Platform NameAlias
.NET Standardnetstandard1.01.11.21.31.41.51.6
.NET Corenetcoreapp→→→→→→1.0
.NET Frameworknet→4.54.5.14.64.6.14.6.24.6.3
Mono/Xamarin Platforms→→→→→→*
Universal Windows Platformuap→→→→10.0
Windowswin→8.08.1
Windows Phonewpa→→8.1
Windows Phone Silverlightwp8.0
- - -##Related topics - -* [Nuspec Reference](/ndocs/schema/nuspec) -* [Symbol packages](/ndocs/create-packages/symbol-packages) -* [Dependency Versions](/ndocs/create-packages/dependency-versions) -* [Supporting Multiple .NET Framework Versions](/ndocs/create-packages/supporting-multiple-target-frameworks) -* [Include MSBuild props and targets in a package](/ndocs/create-packages/creating-a-package#including-msbuild-props-and-targets-in-a-package) -* [Creating Localized Packages](/ndocs/create-packages/creating-localized-packages) -* [.NET Standard Library documentation](https://docs.microsoft.com/en-us/dotnet/articles/standard/library) -* [Porting to .NET Core from .NET Framework](https://docs.microsoft.com/en-us/dotnet/articles/core/porting/index) - diff --git a/docs/Guides/Create-UWP-Packages.md b/docs/Guides/Create-UWP-Packages.md deleted file mode 100644 index 41f2ccdc8..000000000 --- a/docs/Guides/Create-UWP-Packages.md +++ /dev/null @@ -1,249 +0,0 @@ -#Create UWP Packages - -The [Universal Windows Platform (UWP)](https://developer.microsoft.com/en-us/windows) provides a common app platform for every device that runs Windows 10. Within this model, UWP apps can call both the WinRT APIs that are common to all devices, and also APIs (including Win32 and .NET) that are specific to the device family on which the app is running. - -In this walkthrough you'll create a NuGet package with a native UWP component (including a XAML control) that can be used in both Managed and Native projects. - -1. [Pre-requisites](#pre-requisites) -2. [Create a UWP Windows Runtime Component](#create-a-uwp-windows-runtime-component) -3. [Create and update the .nuspec file](#create-and-update-the--nuspec-file) -4. [Package the component](#package-the-component) -5. [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. -2. 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 UWP Windows Runtime Component - -1. In Visual Studio, choose **File > New > Project**, expand the **Visual C++ > Windows > Universal** node, select the **Windows Runtime Component (Universal Windows)** template, change the name to ImageEnhancer, and click OK. Accept the default values for Target Version and Minimum Version when prompted. - - ![Creating a new UWP Windows Runtime Component project](/images/BuildForUWP/01.PNG) - -2. Right click the project in Solution Explorer, select **Add > New Item**, click the **Visual C++ > XAML** node, select **Templated Control**, change the name to AwesomeImageControl.cpp, and click **Add**: - - ![Adding a new XAML Templated Control item to the project](/images/BuildForUWP/02.PNG) - -3. Right-click the project in Solution Explorer and select **Properties.** In the Properties page, expand **Configuration Properties > C/C++** and click **Output Files**. In the pane on the right, change the value for **Generate XML Documentation Files** to Yes: - - ![Setting Generate XML Documentation Files to Yes](/images/BuildForUWP/03.PNG) - -4. Right click the *solution* now, select **Batch Build**, check the three Debug boxes in the dialog as shown below. This makes sure that when you do a build, you'll generate a full set of artifacts for each of the target systems that Windows supports. - - ![Batch Build](/images/BuildForUWP/04.PNG) - -5. In the Batch Build dialog, and click **Build** to verify the project and create the output files that you'll need for the NuGet package. - -
- Note
- In this walkthrough you'll use the Debug artifacts for the package. For non-debug package, check the Release options in the Batch Build dialog instead, and refer to the resulting Release folders in the steps that follow. -
- -##Create and update the .nuspec file - -To create the initial .nuspec file, do the three steps below. The sections that follow then guide you through other necessary updates. - -1. Open a command prompt and navigate to the folder containing ImageEnhancer.vcxproj (this will be a subfolder below where the solution file is). -2. Run the NuGet `spec` command to generate `ImageEnhancer.nuspec` (the name of the file is taken from the name of the .vcxproj file): - - - nuget spec - - -3. Open `ImageEnhancer.nuspec` in an editor and update it to match the following, replacing YOUR_NAME with an appropriate value. The <id> value, specifically, must be unique across nuget.org (see the naming conventions described in [Creating a package](/ndocs/create-packages/creating-a-package(#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. - - - - - ImageEnhancer.YOUR_NAME - 1.0.0 - ImageEnhancer - YOUR_NAME - YOUR_NAME - false - Awesome Image Enhancer - First release - Copyright 2016 - image enhancer imageenhancer - - - -
- Note
- For packages built for public consumption, pay special attention to the <tags> element, as these tags help others find your package and understand what it does. -
- - -###Adding Windows metadata to the package - -A Windows Runtime Component requires metadata that describes all of its publicly available types, which makes it possible for other apps and libraries to consume the component. This metadata is contained in a .winmd file, which is created when you compile the project and must be included in your NuGet package. An XML file with IntelliSense data is also built at the same time, and should be included as well. - -Add the following <files> node to the .nuspec file: - - - - ... - - - - - - - - - - -###Adding XAML content - -To include a XAML control with your component, you need to add the XAML file that has the default template for the control (as generated by the project template). This also goes in the <files> section: - - - - - ... - - - ... - - - - - - - -###Adding the native implementation libraries - -Within your component, the core logic of the ImageEnhancer type is in native code, which is contained in the various `ImageEnhancer.dll` assemblies that are generated for each target runtime (ARM, x86, and x64). To include these in the package, reference them in the <files> section along with their associated .pri resource files: - - - - - ... - - - ... - - - - - - - - - - - - - - -###Adding .targets - -Next, C++ and JavaScript projects that might consume your NuGet package need a .targets file to identify the necessary assembly and winmd files. (C# and Visual Basic projects do this automatically.) Create this file by copying the text below into `ImageEnhancer.targets` and save it in the same folder as the .nuspec file: - - - - - x86 - $(Platform) - - - - ImageEnhancer.dll - - - - - -Then refer to `ImageEnhancer.targets` in your .nuspec file: - - - - - ... - - - ... - - - - - - - - - -###Final nuspec - -Your final .nuspec file should now look like the following, where again YOUR_NAME should be replaced with an appropriate value: - - - - - ImageEnhancer.YOUR_NAME - 1.0.0 - ImageEnhancer - YOUR_NAME - YOUR_NAME - false - Awesome Image Enhancer - First Release - Copyright 2016 - image enhancer imageenhancer - - - - - - - - - - - - - - - - - - - - - - - - -##Package the component - -With the completed .nuspec referencing all the files you need to include in the package, you're ready to run the `pack` command: - - - nuget pack ImageEnhancer.nuspec - - -This will generate `ImageEnhancer.YOUR_NAME.1.0.0.nupkg`. Opening this file in a tool like the [NuGet Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer) and expanding all the nodes, you'll see the following contents: - -![NuGet Package Explorer showing the ImageEnhancer package](/images/BuildForUWP/05.PNG) - -
- Note
- A .nupkg file is just a ZIP file with a different extension. You can also examine package contents, then, by change .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](/ndocs/create-packages/publish-a-package). - - -##Related topics - -* [Nuspec Reference](/ndocs/schema/nuspec) -* [Symbol packages](/ndocs/create-packages/symbol-packages) -* [Dependency Versions](/ndocs/create-packages/dependency-versions) -* [Supporting Multiple .NET Framework Versions](/ndocs/create-packages/supporting-multiple-target-frameworks) -* [Include MSBuild props and targets in a package](/ndocs/create-packages/creating-a-package#including-msbuild-props-and-targets-in-a-package) -* [Creating Localized Packages](/ndocs/create-packages/creating-localized-packages) \ No newline at end of file diff --git a/docs/Guides/Install-NuGet.md b/docs/Guides/Install-NuGet.md deleted file mode 100644 index 08b6477ea..000000000 --- a/docs/Guides/Install-NuGet.md +++ /dev/null @@ -1,127 +0,0 @@ -#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. -2. 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, an open-source, stand-alone tool to visually explore and create NuGet packages..

- Also, the cross-platform .NET Core CLI toolchain for developing .NET Core applications also supports a 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.) - -
- With NuGet 1.4+, you can use `nuget update -self` to update your existing nuget.exe to the latest version. -
- -2. **Chocolatey**: Install the [NuGet.CommandLine](http://chocolatey.org/packages/NuGet.CommandLine) Chocolatey package using the [Chocolatey](http://chocolatey.org) client. - - - choco install nuget.commandline - - -3. **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 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 ](/ndocs/tools/nuget.exe-cli-reference) -- [Creating a package](/ndocs/create-packages/creating-a-package) -- [Publishing a Package](/ndocs/create-packages/publish-a-package) - - -## 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](/ndocs/tools/package-manager-ui)) and the Package Manager Console, through which you can access tools that come with certain packages ([reference](/ndocs/tools/package-manager-console)). - -
- Note
- The console requires PowerShell 2.0, 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 envronment. -
- -### Package Manager installation for Visual Studio 2010 and earlier - -1. In Visual Studio, click **Tools > Extension and Updates**. -2. Navigate to **Online**, search for "NuGet Package Manager for Visual Studio," and click **Download**. -3. In the Installer dialog box, click **Install**. -4. When installation is complete, restart Visual Studio. - -### 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](/images/BetaChannel/01_ToolsSettings.png) - -2. 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](/images/BetaChannel/02_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](/ndocs/tools/package-manager-ui) -- [Package Manager Console reference](/ndocs/tools/package-manager-console) -- [Package Manager Console PowerShell reference](/ndocs/tools/powershell-reference) - diff --git a/docs/Guides/_metadata b/docs/Guides/_metadata deleted file mode 100644 index 4b3556fee..000000000 --- a/docs/Guides/_metadata +++ /dev/null @@ -1,4 +0,0 @@ -Install NuGet -Create .NET Standard Packages -Create UWP Packages -Create Cross Platform Packages \ 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/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 7d82a081d..000000000 --- a/docs/Hosting-Packages/Local-Feeds.md +++ /dev/null @@ -1,26 +0,0 @@ -# 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](/ndocs/tools/package-manager-ui#package-sources) or the command line using [`nuget sources`](/ndocs/tools/nuget.exe-cli-reference#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`](/ndocs/tools/nuget.exe-cli-reference#add) command to copy packages to the feed: - - nuget add new_package.1.0.0.nupkg -source \\myserver\packages - -You can also use the [`nuget init`](/ndocs/tools/nuget.exe-cli-reference#init) command to copy multiple packages from a single folder to the feed. For example, the following command copues all packages from `c:\packages` to a hierarchical tree on `\\myserver\packages`: - - 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 ba31a9043..000000000 --- a/docs/Hosting-Packages/NuGet.Server.md +++ /dev/null @@ -1,83 +0,0 @@ -# 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. -2. Configure the `Packages` folder in the application and add packages. -3. 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** template for C#. - - ![Setting .NET Framework target to 4.6](/images/hosting/Hosting_01-NuGet.Server-Set4.6.png) - -
- Note
- The web application must target .NET Framework 4.6 or above to use the latest version of NuGet.Server (2.11.2 as of this writing). If you target .NET Framework 4.5.2, be sure to install NuGet Server 2.10.3 instead below in step 3. -
- -2. Give the application a suitable name, click OK, and in the next dialog select the **ASP.NET 4.6 - Empty** template (or a higher version) and click OK. - -3. 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. (You can also install it from the Package Manager Console with `Install-Package NuGet.Server`.) - - ![Installing the NuGet.Server package](/images/hosting/Hosting_02-NuGet.Server-Package.png) - -4. 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). -5. 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](/images/hosting/Hosting_03-NuGet.Server-Package-Folder.png) - -6. 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](/images/hosting/Hosting_04-NuGet.Server-FeedHomePage.png) - -7. Click on **here** in the area outlined above to see the OData feed of packages. - -8. 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. - -9. Once you've tested your local deployment, you can deploy the application to any other internal or external site as needed. -10. 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`: - - - - - - -`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: - - - - - -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`: - - - - - - - - - -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. - diff --git a/docs/Hosting-Packages/Overview.md b/docs/Hosting-Packages/Overview.md deleted file mode 100644 index 01f8e205e..000000000 --- a/docs/Hosting-Packages/Overview.md +++ /dev/null @@ -1,21 +0,0 @@ -# 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](/ndocs/hosting-packages/local-feeds). -- NuGet.Server: Packages are made available through a local server through HTTP. For details, see [NuGet.Server](/ndocs/hosting-packages/nuget.server). -- NuGet Gallery: Packages are hosted on an Internet server using the [NuGet Gallery Project](https://github.com/NuGet/NuGetGallery/wiki/Hosting-the-NuGet-Gallery-Locally-in-IIS) 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. - -If you're using Visual Studio Team Services, you can also use the [Package Management extension](https://marketplace.visualstudio.com/items?itemName=ms.feed) to make NuGet packages available to your team. This extension works in conjunction with any other solution. - -There are also several third-party NuGet hosting products that support remote private feeds, including the following: - -- [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](/ndocs/tools/package-manager-ui#package-sources), or from the command line using [`nuget sources`](/ndocs/tools/nuget.exe-cli-reference#sources). The path to a source can be anything from a local directory to a network name to an Internet URL. \ No newline at end of file diff --git a/docs/Hosting-Packages/_metadata b/docs/Hosting-Packages/_metadata deleted file mode 100644 index dadc3f5c5..000000000 --- a/docs/Hosting-Packages/_metadata +++ /dev/null @@ -1,3 +0,0 @@ -Overview -Local-Feeds -NuGet-Server \ No newline at end of file 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 6eab4e789..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 1e7fa9d5d..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 ec3950a10..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 1784f23f3..000000000 --- a/docs/Policies/Deleting-Packages.md +++ /dev/null @@ -1,24 +0,0 @@ -# Deleting packages - -NuGet.org does not support permanent deletion of packages. Doing so would break every project depending on the availabiliyy 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. - -## 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. \ No newline at end of file diff --git a/docs/Policies/NuGet-FAQ.md b/docs/Policies/NuGet-FAQ.md deleted file mode 100644 index f345055a0..000000000 --- a/docs/Policies/NuGet-FAQ.md +++ /dev/null @@ -1,203 +0,0 @@ -# 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-nuget-org) - -## Getting started - -**What is required to run NuGet?** - -All the information around both UI and command-line tools is available in the [Install guide](/ndocs/guides/install-nuget). - -**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 tnere `$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](/ndocs/guides/install-nuget). - - -## NuGet CommandLine - -**How do I get the latest version of NuGet commandline?** - -See the [Install guide](/ndocs/guides/install-nuget). - -**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](/ndocs/tools/powershell-reference#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: - - `$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](/ndocs/quickstart/create-and-publish-a-package). - -**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](/ndocs/create-packages/supporting-multiple-target-frameworks). - -**How do I set up my own repository or feed?** - -See the [Hosting packages overview](/ndocs/hosting-packages/overview). - -**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`](/ndocs/schema/nuget.config#config-section) setting in `nuget.config` using `nuget config -set repositoryPath=<path>`. - -**How do I avoid checking in packages folder to source control?** - -Set the [`disableSourceControlIntegration`](/ndocs/schema/nuget.config#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 automaticatlly. - -**How do I turn off package restore?** - -See [Enabling and disabling package restore](/ndocs/consume-packages/package-restore#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](/ndocs/create-packages/publish-a-package#managing-package-owners-on-nuget-org). - -**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](/ndocs/policies/dispute-resolution) 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. - -**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 faile, [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](/images/consume/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). \ No newline at end of file diff --git a/docs/Policies/_metadata b/docs/Policies/_metadata deleted file mode 100644 index 7840965f4..000000000 --- a/docs/Policies/_metadata +++ /dev/null @@ -1,5 +0,0 @@ -NuGet-FAQ -Governance -Ecosystem -Dispute-Resolution -Deleting-Packages \ No newline at end of file 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 034f2feae..000000000 --- a/docs/Quickstart/Create-and-Publish-a-Package.md +++ /dev/null @@ -1,155 +0,0 @@ -#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. -2. 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](/images/CreatePublishNugetSample/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). -2. Run the NuGet CLI spec command to generate `AppLogg.nuspec`: - - - nuget spec - - -3. Open the file in your favorite text editor. It will look something like the code below, where tokens in the form *$<token>$* 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](/ndocs/create-packages/creating-a-package#creating-the--nuspec-file). - - - - - $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 - - - -4. Select a package ID that is unique across nuget.org. We recommend using the naming conventions described in [Creating a package](/ndocs/create-packages/creating-a-package#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: - - - - - 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 <tags> element, as these tags help others find your package and understand what it does. -
- - -##Create the package - -Creating a NuGet package from a project is simple: just run the pack command: - - - nuget pack AppLogger.csproj - - -This 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 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](/ndocs/create-packages/publish-a-package#publish-through-nuget-org). - -
- Note
- The packages you publish to nuget.org will be publicly visible to other developers. To host packages privately, see Hosting packages. -
- -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. -2. Once logged in, click your user name (on the upper right) to navigate to your account settings. -3. 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](/images/CreatePublishNugetSample/QS_Create-02-APIKey.png) - -
- Note
- 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. -
- -4. At a command prompt, run the following command, replacing the key with the value copied in step 3: - - - nuget push AppLogger.1.0.0.0.nupkg 47be3377-c434-4c29-8576-af7f6993a54b -Source https://www.nuget.org/api/v2/package - - -5. 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. - - -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: - - ![This package has not been indexed yet. It will appear in search results and will be available for install/restore after indexing is complete.](/images/CreatePublishNugetSample/04.PNG) - - -
- 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](/ndocs/create-packages/creating-a-package) -* [Publish a Package](/ndocs/create-packages/publish-a-package) -* [Support multiple target frameworks](/ndocs/create-packages/supporting-multiple-target-frameworks) -* [Dependency versions](/ndocs/create-packages/dependency-versions) -* [Creating localized packages](/ndocs/create-packages/creating-localized-packages) - - - - diff --git a/docs/Quickstart/Use-a-Package.md b/docs/Quickstart/Use-a-Package.md deleted file mode 100644 index 086286186..000000000 --- a/docs/Quickstart/Use-a-Package.md +++ /dev/null @@ -1,102 +0,0 @@ -#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-newtonsoft-json-nuget-package) -- [Use the Newtonsoft.Json API in the app](#use-the-newtonsoft-json-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](/images/ConsumeNugetSample/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](/images/ConsumeNugetSample/QS_Use-02-ManageNuGetPackages.png) - -2. 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](/images/ConsumeNugetSample/QS_Use-03-NewtonsoftJson.png) - -3. If prompted to review changes, click OK. - -4. Right-click the solution in Solution Explorer and click **Build Solution**. This restore anys NuGet packages listed under **References**. For more details, see [Package Restore](/ndocs/consume-packages/package-restore). - - - -##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: - - - -