diff --git a/.ghal.rules.json b/.ghal.rules.json index 4f7841b7067e7..d3639f79bc510 100644 --- a/.ghal.rules.json +++ b/.ghal.rules.json @@ -1,10 +1,10 @@ { "version": 3, - "configRevision": 3, + "configRevision": 4, "issue": { "labeled": { - "processor-conditional": { + "processor-conditional-techprodlabels": { "type": "query", "value": "length(Issue.labels[?contains(name, '/prod') || contains(name, '/tech')]) != `0`", "processors": { @@ -19,6 +19,13 @@ } } } + }, + "processor-conditional-release6": { + "type": "query", + "value": "length(Issue.labels[?name == ':checkered_flag: Release .NET 6']) != `0`", + "actions": { + "projects-add": [ "132" ] + } } }, "opened": { @@ -28,7 +35,8 @@ "processor-meta-custom": { "issuetype": { "(?i)breaking-change$": { - "labels-add": [ "breaking-change", "doc-idea" ] + "labels-add": [ "breaking-change", "doc-idea" ], + "projects-add": [ "135" ] } } } @@ -258,15 +266,6 @@ "(?i).*docs\/framework\/windows-workflow-foundation.*": { "labels-add": [ "dotnet-framework/prod", "dotnet-wf/tech" ] }, - "(?i).*docs\/framework\/winforms.*": { - "labels-add": [ "dotnet-framework/prod", "dotnet-winforms/tech" ] - }, - "(?i).*docs\/framework\/wpf.*": { - "labels-add": [ "dotnet-framework/prod", "dotnet-wpf/tech" ] - }, - "(?i).*docs\/framework\/xaml-services.*": { - "labels-add": [ "dotnet-framework/prod", "dotnet-wpf/tech" ] - }, "(?i).*docs\/fsharp.*": { "labels-add": "dotnet-fsharp/prod" @@ -320,6 +319,15 @@ } } } + }, + "labeled": { + "processor-conditional-release6": { + "type": "query", + "value": "length(PullRequest.labels[?name == ':checkered_flag: Release .NET 6']) != `0`", + "actions": { + "projects-add": [ "132" ] + } + } } }, "comment": { diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a977e6be56a1c..968aa0f9ebb3c 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -72,7 +72,7 @@ # Deployment /docs/core/deploying/ @adegeo # Diagnostics -/docs/core/diagnostics/ @sywhang @sdmaclea @dotnet/docs +/docs/core/diagnostics/ @tommcdon @sdmaclea @dotnet/docs # Docker /docs/core/docker/ @IEvangelist # Install diff --git a/.github/ISSUE_TEMPLATE/dotnet-breaking-change.md b/.github/ISSUE_TEMPLATE/dotnet-breaking-change.md index daa188443a561..c9b5bdcb67859 100644 --- a/.github/ISSUE_TEMPLATE/dotnet-breaking-change.md +++ b/.github/ISSUE_TEMPLATE/dotnet-breaking-change.md @@ -1,7 +1,7 @@ --- name: ".NET breaking change" -about: Report a change in .NET that breaks something that worked in a previous - version (intended mostly for product-team use) +about: Report a change in .NET that breaks something that worked in a previous version + (intended mostly for product-team use) title: '' labels: '' assignees: '' @@ -62,6 +62,7 @@ assignees: '' - [ ] MSBuild - [ ] Networking - [ ] Printing +- [ ] SDK - [ ] Security - [ ] Serialization - [ ] Visual Basic diff --git a/.github/ISSUE_TEMPLATE/okr-internal-use-only-template.md b/.github/ISSUE_TEMPLATE/okr-internal-use-only-template.md new file mode 100644 index 0000000000000..f8ef63590224e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/okr-internal-use-only-template.md @@ -0,0 +1,37 @@ +--- +name: OKR internal use only template +about: This is the object key result (OKR) template, for internal use only. +title: 'OKR: address x, y, and z' +labels: OKR +assignees: '' + +--- + +<-- + +GOAL: +Each team has a commitment around content performance + +OBJECTIVES: + +- Content developers continue to get familiar with the Content Perf report by identifying and updating articles +- Create a sustainable and repeatable process. Each M1 has a project for content performance and tracks +- Continue to use data and feedback from past quarters to influence updates to formulas and ranking + +RESULTS: + +- Continue with 1 article per writer, per quarter +- % of page views to higher performing articles increases (targeted at 80% all up) + +TRACKING: + +- Use the [Azure DevOps template](https://dev.azure.com/mseng/TechnicalContent/_workitems/create/User%20Story) to create a tracking item + - Required: + - [ ] Includes tag "content-perf" and "FY21Q3" + - [ ] Set M1 and M2 fields + - [ ] Area path. Set to your team's path as you see fit +- Writers add "ms.custom: contperfq3" to their updated articles to help with data reporting. + +NOTE: For those teams that aren't currently using the [mseng TechnicalContent project](https://dev.azure.com/mseng/TechnicalContent), you'll still need to set up your items in it so we have an accurate inventory and ability to track. + +--> diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 4257fd77336e2..5800d9808a455 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -776,18 +776,6 @@ updates: interval: "weekly" day: "wednesday" open-pull-requests-limit: 5 - - package-ecosystem: "nuget" - directory: "/samples/snippets/csharp/roslyn-sdk/Tutorials/MakeConst/MakeConst.Test" #MakeConst.Test.csproj - schedule: - interval: "weekly" - day: "wednesday" - open-pull-requests-limit: 5 - - package-ecosystem: "nuget" - directory: "/samples/snippets/csharp/roslyn-sdk/Tutorials/MakeConst/MakeConst" #MakeConst.csproj - schedule: - interval: "weekly" - day: "wednesday" - open-pull-requests-limit: 5 - package-ecosystem: "nuget" directory: "/samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_cancellationwinforms/vb/cancellationwinforms" #cancellationwinforms.vbproj schedule: diff --git a/.github/workflows/build-validation.yml b/.github/workflows/build-validation.yml index c8c4bd411a9e4..de5b15f8d615a 100644 --- a/.github/workflows/build-validation.yml +++ b/.github/workflows/build-validation.yml @@ -2,13 +2,15 @@ name: Snippets 5000 # Controls when the action will run. Triggers the workflow on push or pull request -# events but only for the master branch +# events on the main branch only. on: pull_request: paths: - "**.cs" - "**.vb" - "**.fs" + - "**.cpp" + - "**.h" - "**.xaml" - "**.razor" - "**.cshtml" @@ -16,10 +18,11 @@ on: - "**.csproj" - "**.vbproj" - "**.fsproj" + - "**.vcxproj" - "**.sln" - "**global.json" - "**snippets.5000.json" - branches: [ master ] + branches: [ main ] env: DOTNET_INSTALLER_CHANNEL: 'release/5.0.1xx' @@ -61,7 +64,7 @@ jobs: - name: Locate projects for PR env: GitHubKey: ${{ secrets.GITHUB_TOKEN }} - LocateExts: ".cs;.vb;.fs;.cpp;.h;.xaml;.razor;.cshtml;.vbhtml;.csproj;.fsproj;.vbproj;.sln" + LocateExts: ".cs;.vb;.fs;.cpp;.h;.xaml;.razor;.cshtml;.vbhtml;.csproj;.fsproj;.vbproj;.vcxproj;.sln" run: | ./.github/workflows/dependencies/Get-MSBuildResults.ps1 "${{ github.workspace }}" -PullRequest ${{ github.event.number }} -RepoOwner ${{ github.repository_owner }} -RepoName ${{ github.event.repository.name }} @@ -76,6 +79,3 @@ jobs: - name: Report status run: | ./.github/workflows/dependencies/Out-GithubActionStatus.ps1 - - - diff --git a/.github/workflows/check-for-build-warnings.yml b/.github/workflows/check-for-build-warnings.yml new file mode 100644 index 0000000000000..25f66767ce6bd --- /dev/null +++ b/.github/workflows/check-for-build-warnings.yml @@ -0,0 +1,14 @@ +name: 'Status checker' + +on: + pull_request_target: + types: [opened, synchronize, reopened] + +jobs: + status_checker_job: + name: Look for build warnings + runs-on: ubuntu-latest + steps: + - uses: dotnet/samples/.github/actions/status-checker@main + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/dependencies/DotnetDocsTools.LocateProjects.1.0.10.nupkg b/.github/workflows/dependencies/DotnetDocsTools.LocateProjects.1.0.10.nupkg new file mode 100644 index 0000000000000..3cc8f81c0becd Binary files /dev/null and b/.github/workflows/dependencies/DotnetDocsTools.LocateProjects.1.0.10.nupkg differ diff --git a/.github/workflows/dependencies/DotnetDocsTools.LocateProjects.1.0.9.nupkg b/.github/workflows/dependencies/DotnetDocsTools.LocateProjects.1.0.9.nupkg deleted file mode 100644 index dd2da8d39de16..0000000000000 Binary files a/.github/workflows/dependencies/DotnetDocsTools.LocateProjects.1.0.9.nupkg and /dev/null differ diff --git a/.github/workflows/dependencies/Get-MSBuildResults.ps1 b/.github/workflows/dependencies/Get-MSBuildResults.ps1 index 1ad66c55a53eb..9ae0b0711b715 100644 --- a/.github/workflows/dependencies/Get-MSBuildResults.ps1 +++ b/.github/workflows/dependencies/Get-MSBuildResults.ps1 @@ -31,10 +31,10 @@ None .NOTES - Version: 1.4 + Version: 1.5 Author: adegeo@microsoft.com - Creation Date: 12/11/2020 - Purpose/Change: Add support for config file. Select distinct on project files. + Creation Date: 04/02/2021 + Purpose/Change: Add extra logging info. #> [CmdletBinding()] @@ -166,7 +166,11 @@ foreach ($item in $workingSet) { } } - $result = Invoke-Expression ".\run.bat" | Out-String + Write-Host "run.bat contents: " + Get-Content .\run.bat | Write-Host + Write-Host + + Invoke-Expression ".\run.bat" | Tee-Object -Variable "result" $thisExitCode = 0 if ($LASTEXITCODE -ne 0) { diff --git a/.github/workflows/markdown-links-verifier.yml b/.github/workflows/markdown-links-verifier.yml new file mode 100644 index 0000000000000..9412cff262572 --- /dev/null +++ b/.github/workflows/markdown-links-verifier.yml @@ -0,0 +1,14 @@ +name: Markdown links verifier +on: pull_request + +jobs: + validate_links: + name: Markdown links verifier + runs-on: ubuntu-latest + + steps: + - name: Checkout the repository + uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675 #@v2 + + - name: Validate links + uses: Youssef1313/markdown-links-verifier@2afb5acdf77edc7d6c7fecbe3387aca169bd3eec #@v0.0.9.1 diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml index 4dc5c1878acab..456001792115b 100644 --- a/.github/workflows/markdownlint.yml +++ b/.github/workflows/markdownlint.yml @@ -2,6 +2,8 @@ name: Markdownlint on: push: + branches: + - main paths: - "**/*.md" - ".markdownlint.json" diff --git a/.github/workflows/version-sweep.yml b/.github/workflows/version-sweep.yml index 0a79ca45403f3..39507a46c6fa2 100644 --- a/.github/workflows/version-sweep.yml +++ b/.github/workflows/version-sweep.yml @@ -4,7 +4,7 @@ name: 'target supported version' # Controls when the action will run. on: - # Triggers the workflow on push or pull request events but only for the master branch + # Triggers the workflow on push or pull request events but only for the default branch schedule: - cron: '0 0 1 * *' workflow_dispatch: @@ -35,7 +35,7 @@ jobs: # Start the .NET version sweeper, scan projects/slns for non-LTS (or currrent) versions - name: .NET version sweeper id: dotnet-version-sweeper - uses: dotnet/versionsweeper@v1.2 + uses: dotnet/versionsweeper@main env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index b4e557a745f4a..b2d6d86e13330 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -1,34 +1,14 @@ { - "need_generate_intellisense": false, - "need_preview_pull_request": true, - "need_pr_comments": false, - "need_generate_pdf_url_template": true, - "git_repository_branch_open_to_public_contributors": "master", - "branch_target_mapping": { - "live": [ - "Publish", - "Pdf" - ], - "master": [ - "Publish", - "Pdf" - ] - }, - "Targets": { - "Pdf": { - "template_folder": "_themes.pdf" - } - }, "docsets_to_publish": [ { "docset_name": "core-docs", "build_source_folder": ".", "build_output_subfolder": ".", "locale": "en-us", + "monikers": [], "xref_query_tags": [ "/uwp/api" ], - "monikers": [], "filemap_share_depots": [ "VS.dotnet-api-docs" ], @@ -45,43 +25,71 @@ } ], "notification_subscribers": [], + "sync_notification_subscribers": [], "branches_to_filter": [], + "git_repository_branch_open_to_public_contributors": "main", "skip_source_output_uploading": false, + "need_preview_pull_request": true, + "need_pr_comments": false, + "contribution_branch_mappings": {}, "dependent_repositories": [ { "path_to_root": "_themes", "url": "https://github.com/Microsoft/templates.docs.msft", - "branch": "master" + "branch": "master", + "branch_mapping": {} }, { "path_to_root": "_themes.pdf", "url": "https://github.com/Microsoft/templates.docs.msft.pdf", - "branch": "master" + "branch": "master", + "branch_mapping": {} }, { "path_to_root": "_csharplang", "url": "https://github.com/dotnet/csharplang", - "branch": "master", + "branch": "main", "include_in_build": true }, { "path_to_root": "_vblang", "url": "https://github.com/dotnet/vblang", - "branch": "master", + "branch": "main", "include_in_build": true }, { "path_to_root": "machinelearning-samples", "url": "https://github.com/dotnet/machinelearning-samples", - "branch": "master" + "branch": "main", + "branch_mapping": {} }, { "path_to_root": "iot-samples", "url": "https://github.com/MicrosoftDocs/dotnet-iot-assets", - "branch": "master" + "branch": "master", + "branch_mapping": { + "main": "master" + } } ], + "branch_target_mapping": { + "live": [ + "Publish", + "Pdf" + ], + "main": [ + "Publish", + "Pdf" + ] + }, + "need_generate_pdf_url_template": true, + "targets": { + "Pdf": { + "template_folder": "_themes.pdf" + } + }, "docs_build_engine": { "name": "docfx_v3" - } + }, + "need_generate_intellisense": false } diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index c700f5b273577..df4e5d995e731 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -150,16 +150,24 @@ "redirect_url": "/dotnet/azure/" }, { - "source_path": "docs/azure/sdk/authentication.md", - "redirect_url": "/dotnet/azure/authentication" + "source_path": "docs/azure/authentication.md", + "redirect_url": "/dotnet/azure/sdk/authentication" }, { "source_path": "docs/azure/sdk/index.yml", "redirect_url": "/dotnet/azure/" }, { - "source_path": "docs/azure/sdk/logging.md", - "redirect_url": "/dotnet/azure/logging" + "source_path": "docs/azure/logging.md", + "redirect_url": "/dotnet/azure/sdk/logging" + }, + { + "source_path": "docs/azure/packages.md", + "redirect_url": "/dotnet/azure/sdk/packages" + }, + { + "source_path": "docs/azure/dependency-injection.md", + "redirect_url": "/dotnet/azure/sdk/dependency-injection" }, { "source_path": "docs/azure/sdk/tools.md", @@ -248,62 +256,165 @@ }, { "source_path": "docs/core/compatibility/syslib0001.md", - "redirect_url": "/dotnet/core/compatibility/syslib-warnings/syslib0001", - "redirect_document_id": true + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0001" }, { "source_path": "docs/core/compatibility/syslib0002.md", - "redirect_url": "/dotnet/core/compatibility/syslib-warnings/syslib0002", - "redirect_document_id": true + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0002" }, { "source_path": "docs/core/compatibility/syslib0003.md", - "redirect_url": "/dotnet/core/compatibility/syslib-warnings/syslib0003", - "redirect_document_id": true + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0003" }, { "source_path": "docs/core/compatibility/syslib0004.md", - "redirect_url": "/dotnet/core/compatibility/syslib-warnings/syslib0004", - "redirect_document_id": true + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0004" }, { "source_path": "docs/core/compatibility/syslib0005.md", - "redirect_url": "/dotnet/core/compatibility/syslib-warnings/syslib0005", - "redirect_document_id": true + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0005" }, { "source_path": "docs/core/compatibility/syslib0006.md", - "redirect_url": "/dotnet/core/compatibility/syslib-warnings/syslib0006", - "redirect_document_id": true + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0006" }, { "source_path": "docs/core/compatibility/syslib0007.md", - "redirect_url": "/dotnet/core/compatibility/syslib-warnings/syslib0007", - "redirect_document_id": true + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0007" }, { "source_path": "docs/core/compatibility/syslib0008.md", - "redirect_url": "/dotnet/core/compatibility/syslib-warnings/syslib0008", - "redirect_document_id": true + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0008" }, { "source_path": "docs/core/compatibility/syslib0009.md", - "redirect_url": "/dotnet/core/compatibility/syslib-warnings/syslib0009", - "redirect_document_id": true + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0009" }, { "source_path": "docs/core/compatibility/syslib0010.md", - "redirect_url": "/dotnet/core/compatibility/syslib-warnings/syslib0010", - "redirect_document_id": true + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0010" }, { "source_path": "docs/core/compatibility/syslib0011.md", - "redirect_url": "/dotnet/core/compatibility/syslib-warnings/syslib0011", - "redirect_document_id": true + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0011" }, { "source_path": "docs/core/compatibility/syslib0012.md", - "redirect_url": "/dotnet/core/compatibility/syslib-warnings/syslib0012", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0012" + }, + { + "source_path": "docs/core/compatibility/syslib-obsoletions.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/obsoletions-overview", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0001.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0001", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0002.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0002", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0003.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0003", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0004.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0004", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0005.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0005", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0006.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0006", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0007.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0007", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0008.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0008", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0009.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0009", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0010.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0010", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0011.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0011", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0012.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0012", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0013.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0013", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0014.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0014", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0015.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0015", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0016.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0016", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0017.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0017", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0018.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0018", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0019.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0019", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/syslib-warnings/syslib0020.md", + "redirect_url": "/dotnet/fundamentals/syslib-diagnostics/syslib0020", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/windows-forms/5.0/automatically-infer-winexe-output-type.md", + "redirect_url": "/dotnet/core/compatibility/sdk/5.0/automatically-infer-winexe-output-type", + "redirect_document_id": true + }, + { + "source_path": "docs/core/compatibility/windows-forms/5.0/sdk-and-target-framework-change.md", + "redirect_url": "/dotnet/core/compatibility/sdk/5.0/sdk-and-target-framework-change", "redirect_document_id": true }, { @@ -455,6 +566,10 @@ "source_path": "docs/core/migrating-from-dnx.md", "redirect_url": "/dotnet/core/tools" }, + { + "source_path": "docs/core/migration/20-21.md", + "redirect_url": "/dotnet/core/compatibility/2.1" + }, { "source_path": "docs/core/migration/from-dnx.md", "redirect_url": "/dotnet/core/tools" @@ -463,6 +578,10 @@ "source_path": "docs/core/migration/index.md", "redirect_url": "/dotnet/core/tools/dotnet-migrate" }, + { + "source_path": "docs/core/migration/assembly-info.md", + "redirect_url": "/dotnet/core/project-sdk/msbuild-props#assembly-info-generation-properties" + }, { "source_path": "docs/core/packages.md", "redirect_url": "/dotnet/core/deploying" @@ -471,6 +590,10 @@ "source_path": "docs/core/porting/nuget-packages.md", "redirect_url": "/dotnet/core/deploying" }, + { + "source_path": "docs/core/porting/tools.md", + "redirect_url": "/dotnet/core/porting/#tools-to-assist-porting" + }, { "source_path": "docs/core/porting/winforms.md", "redirect_url": "/dotnet/desktop/winforms/migration/?view=netdesktop-5.0" @@ -770,6 +893,10 @@ "source_path": "docs/core/windows-prerequisites.md", "redirect_url": "/dotnet/core/install/windows#dependencies" }, + { + "source_path": "docs/csharp/basic-types.md", + "redirect_url": "/dotnet/csharp/fundamentals/types" + }, { "source_path": "docs/csharp/classes.md", "redirect_url": "/dotnet/csharp/programming-guide/classes-and-structs/classes" @@ -787,10 +914,18 @@ "source_path": "docs/csharp/csharp.md", "redirect_url": "/dotnet/csharp" }, + { + "source_path": "docs/csharp/deconstruct.md", + "redirect_url": "/dotnet/csharp/fundamentals/functional/deconstruct" + }, { "source_path": "docs/csharp/delegates-events.md", "redirect_url": "/dotnet/csharp/delegates-overview" }, + { + "source_path": "docs/csharp/discards.md", + "redirect_url": "/dotnet/csharp/fundamentals/functional/discards" + }, { "source_path": "docs/csharp/features.md", "redirect_url": "/dotnet/csharp/programming-guide/concepts" @@ -870,6 +1005,11 @@ "source_path": "docs/csharp/getting-started/with-visual-studio.md", "redirect_url": "/dotnet/core/tutorials/with-visual-studio" }, + { + "source_path": "docs/csharp/how-to/safely-cast-using-pattern-matching-is-and-as-operators.md", + "redirect_url": "/dotnet/csharp/fundamentals/tutorials/safely-cast-using-pattern-matching-is-and-as-operators" + }, + { "source_path": "docs/csharp/implicitly-typed-lambda-expressions.md", "redirect_url": "/dotnet/csharp/language-reference/operators/lambda-expressions" @@ -902,10 +1042,258 @@ "source_path": "docs/csharp/lambda-expressions.md", "redirect_url": "/dotnet/csharp/language-reference/operators/lambda-expressions" }, + { + "source_path": "docs/csharp/language-reference/compiler-options/addmodule-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/inputs" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/appconfig-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, { "source_path": "docs/csharp/language-reference/compiler-options/app-deployment.md", "redirect_url": "/dotnet/framework/deployment/deployment-guide-for-developers" }, + { + "source_path": "docs/csharp/language-reference/compiler-options/baseaddress-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/bugreport-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/checked-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/language" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/codepage-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/command-line-building-with-csc-exe.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/debug-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/code-generation" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/deterministic-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/code-generation" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/define-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/language" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/delaysign-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/security" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/doc-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/output" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/errorreport-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/filealign-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/fullpaths-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/help-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/miscellaneous" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/highentropyva-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/security" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/how-to-set-environment-variables-for-the-visual-studio-command-line.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/keycontainer-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/security" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/keyfile-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/security" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/langversion-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/language" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/lib-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/link-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/inputs" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/linkresource-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/resources" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/listed-alphabetically.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/listed-by-category.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/main-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/moduleassemblyname-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/noconfig-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/miscellaneous" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/nologo-file-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/miscellaneous" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/nowarn-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/errors-warnings" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/nowin32manifest-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/resources" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/nullable-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/language" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/optimize-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/code-generation" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/nostdlib-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/out-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/output" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/pathmap-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/pdb-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/platform-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/output" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/preferreduilang-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/publicsign-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/security" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/recurse-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/reference-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/inputs" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/refout-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/output" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/refonly-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/code-generation" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/resource-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/resources" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/response-file-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/miscellaneous" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/subsystemversion-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/target-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/output" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/target-appcontainerexe-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/output" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/target-exe-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/output" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/target-library-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/output" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/target-module-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/output" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/target-winexe-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/output" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/target-winmdobj-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/output" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/unsafe-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/language" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/utf8output-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/advanced" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/warn-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/errors-warnings" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/warnaserror-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/errors-warnings" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/win32icon-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/resources" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/win32manifest-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/resources" + }, + { + "source_path": "docs/csharp/language-reference/compiler-options/win32res-compiler-option.md", + "redirect_url": "/dotnet/csharp/language-reference/compiler-options/resources" + }, { "source_path": "docs/csharp/language-reference/keywords/access-keywords.md", "redirect_url": "/dotnet/csharp/language-reference/keywords/base" @@ -950,6 +1338,10 @@ "source_path": "docs/csharp/language-reference/keywords/delegate.md", "redirect_url": "/dotnet/csharp/language-reference/builtin-types/reference-types" }, + { + "source_path": "docs/csharp/language-reference/keywords/do.md", + "redirect_url": "/dotnet/csharp/language-reference/statements/iteration-statements" + }, { "source_path": "docs/csharp/language-reference/keywords/double.md", "redirect_url": "/dotnet/csharp/language-reference/builtin-types/floating-point-numeric-types" @@ -994,6 +1386,14 @@ "source_path": "docs/csharp/language-reference/keywords/floating-point-types-table.md", "redirect_url": "/dotnet/csharp/language-reference/builtin-types/floating-point-numeric-types" }, + { + "source_path": "docs/csharp/language-reference/keywords/for.md", + "redirect_url": "/dotnet/csharp/language-reference/statements/iteration-statements" + }, + { + "source_path": "docs/csharp/language-reference/keywords/foreach-in.md", + "redirect_url": "/dotnet/csharp/language-reference/statements/iteration-statements" + }, { "source_path": "docs/csharp/language-reference/keywords/formatting-numeric-results-table.md", "redirect_url": "/dotnet/standard/base-types/standard-numeric-format-strings" @@ -1022,9 +1422,13 @@ "source_path": "docs/csharp/language-reference/keywords/interpolated-strings.md", "redirect_url": "/dotnet/csharp/language-reference/tokens/interpolated" }, + { + "source_path": "docs/csharp/language-reference/keywords/is.md", + "redirect_url": "/dotnet/csharp/language-reference/operators/is" + }, { "source_path": "docs/csharp/language-reference/keywords/iteration-statements.md", - "redirect_url": "/dotnet/csharp/language-reference/keywords/statement-keywords" + "redirect_url": "/dotnet/csharp/language-reference/statements/iteration-statements" }, { "source_path": "docs/csharp/language-reference/keywords/jump-statements.md", @@ -1150,6 +1554,10 @@ "source_path": "docs/csharp/language-reference/keywords/void.md", "redirect_url": "/dotnet/csharp/language-reference/builtin-types/void" }, + { + "source_path": "docs/csharp/language-reference/keywords/while.md", + "redirect_url": "/dotnet/csharp/language-reference/statements/iteration-statements" + }, { "source_path": "docs/csharp/language-reference/language-specification/index.md", "redirect_url": "/dotnet/csharp/language-reference/language-specification/introduction" @@ -1314,6 +1722,71 @@ "source_path": "docs/csharp/language-reference/operators/xor-operator.md", "redirect_url": "/dotnet/csharp/language-reference/operators/boolean-logical-operators#logical-exclusive-or-operator-" }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/index.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives", + "redirect_document_id":true + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-define.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-else.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-elif.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-endif.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-endregion.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-error.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-if.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-line.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-nullable.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-pragma.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-pragma-checksum.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-pragma-warning.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-region.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-undef.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, + { + "source_path": "docs/csharp/language-reference/preprocessor-directives/preprocessor-warning.md", + "redirect_url": "/dotnet/csharp/language-reference/preprocessor-directives" + }, { "source_path": "docs/csharp/language-reference/proposals/csharp-7.0/index.md", "redirect_url": "/dotnet/csharp/language-reference/proposals/csharp-7.0/pattern-matching" @@ -1358,6 +1831,10 @@ "source_path": "docs/csharp/parallel.md", "redirect_url": "/dotnet/standard/parallel-programming/index" }, + { + "source_path": "docs/csharp/pattern-matching.md", + "redirect_url": "/dotnet/csharp/fundamentals/functional/pattern-matching" + }, { "source_path": "docs/csharp/programming-guide/arrays/arrays-as-objects.md", "redirect_url": "/dotnet/csharp/programming-guide/arrays" @@ -1366,10 +1843,38 @@ "source_path": "docs/csharp/programming-guide/arrays/passing-arrays-using-ref-and-out.md", "redirect_url": "/dotnet/csharp/programming-guide/arrays" }, + { + "source_path": "docs/csharp/programming-guide/classes-and-structs/anonymous-types.md", + "redirect_url": "/dotnet/csharp/fundamentals/types/anonymous-types" + }, + { + "source_path": "docs/csharp/programming-guide/classes-and-structs/classes.md", + "redirect_url": "/dotnet/csharp/fundamentals/types/classes" + }, { "source_path": "docs/csharp/programming-guide/classes-and-structs/how-to-access-a-collection-class-with-foreach.md", "redirect_url": "/dotnet/csharp/language-reference/keywords/foreach-in" }, + { + "source_path": "docs/csharp/programming-guide/classes-and-structs/index.md", + "redirect_url": "/dotnet/csharp/fundamentals/object-oriented" + }, + { + "source_path": "docs/csharp/programming-guide/classes-and-structs/inheritance.md", + "redirect_url": "/dotnet/csharp/fundamentals/object-oriented/inheritance" + }, + { + "source_path": "docs/csharp/programming-guide/classes-and-structs/objects.md", + "redirect_url": "/dotnet/csharp/fundamentals/object-oriented/objects" + }, + { + "source_path": "docs/csharp/programming-guide/classes-and-structs/polymorphism.md", + "redirect_url": "/dotnet/csharp/fundamentals/object-oriented/polymorphism" + }, + { + "source_path": "docs/csharp/programming-guide/classes-and-structs/records.md", + "redirect_url": "/dotnet/csharp/fundamentals/types/records" + }, { "source_path": "docs/csharp/programming-guide/classes-and-structs/structs.md", "redirect_url": "/dotnet/csharp/language-reference/builtin-types/struct" @@ -2346,9 +2851,44 @@ "source_path": "docs/csharp/programming-guide/events/how-to-use-a-dictionary-to-store-event-instances.md", "redirect_url": "/dotnet/standard/events/how-to-handle-multiple-events-using-event-properties" }, + { + "source_path": "docs/csharp/programming-guide/exceptions/compiler-generated-exceptions.md", + "redirect_url": "/dotnet/csharp/fundamentals/exceptions/compiler-generated-exceptions" + }, + { + "source_path": "docs/csharp/programming-guide/exceptions/creating-and-throwing-exceptions.md", + "redirect_url": "/dotnet/csharp/fundamentals/exceptions/creating-and-throwing-exceptions" + }, + { + "source_path": "docs/csharp/programming-guide/exceptions/exception-handling.md", + "redirect_url": "/dotnet/csharp/fundamentals/exceptions/exception-handling" + }, + { + "source_path": "docs/csharp/programming-guide/exceptions/how-to-handle-an-exception-using-try-catch.md", + "redirect_url": "/dotnet/csharp/fundamentals/exceptions/how-to-handle-an-exception-using-try-catch" + }, + { + "source_path": "docs/csharp/programming-guide/exceptions/how-to-execute-cleanup-code-using-finally.md", + "redirect_url": "/dotnet/csharp/fundamentals/exceptions/how-to-execute-cleanup-code-using-finally" + }, + { + "source_path": "docs/csharp/programming-guide/exceptions/how-to-catch-a-non-cls-exception.md", + "redirect_url": "/dotnet/csharp/how-to/how-to-catch-a-non-cls-exception" + }, + { + "source_path": "docs/csharp/programming-guide/exceptions/index.md", + "redirect_url": "/dotnet/csharp/fundamentals/exceptions" + }, { "source_path": "docs/csharp/programming-guide/exceptions/exceptions-and-exception-handling.md", "redirect_url": "/dotnet/csharp/programming-guide/exceptions/index" + }, { + "source_path": "docs/csharp/programming-guide/exceptions/using-exceptions.md", + "redirect_url": "/dotnet/csharp/fundamentals/exceptions/using-exceptions" + }, + { + "source_path": "docs/csharp/programming-guide/inside-a-program/general-structure-of-a-csharp-program.md", + "redirect_url": "/dotnet/csharp/fundamentals/program-structure" }, { "source_path": "docs/csharp/programming-guide/generics/benefits-of-generics.md", @@ -2363,14 +2903,30 @@ "source_path": "docs/csharp/programming-guide/generics/generics-in-the-net-framework-class-library.md", "redirect_url": "/dotnet/standard/generics/index" }, + { + "source_path": "docs/csharp/programming-guide/generics/index.md", + "redirect_url": "/dotnet/csharp/fundamentals/types/generics" + }, { "source_path": "docs/csharp/programming-guide/generics/introduction-to-generics.md", "redirect_url": "/dotnet/standard/generics/index" }, + { + "source_path": "docs/csharp/programming-guide/inside-a-program/coding-conventions.md", + "redirect_url": "/dotnet/csharp/fundamentals/coding-style/coding-conventions" + }, { "source_path": "docs/csharp/programming-guide/inside-a-program/hello-world-your-first-program.md", "redirect_url": "/dotnet/csharp/tutorials/intro-to-csharp/hello-world" }, + { + "source_path": "docs/csharp/programming-guide/inside-a-program/identifier-names.md", + "redirect_url": "/dotnet/csharp/fundamentals/coding-style/identifier-names" + }, + { + "source_path": "docs/csharp/programming-guide/inside-a-program/index.md", + "redirect_url": "/dotnet/csharp/fundamentals/program-structure" + }, { "source_path": "docs/csharp/programming-guide/interop/interoperability.md", "redirect_url": "/dotnet/csharp/programming-guide/interop/index" @@ -2451,14 +3007,34 @@ "source_path": "docs/csharp/programming-guide/linq-query-expressions/query-expression-basics.md", "redirect_url": "/dotnet/csharp/linq/query-expression-basics" }, + { + "source_path": "docs/csharp/programming-guide/main-and-command-args/command-line-arguments.md", + "redirect_url": "/dotnet/csharp/fundamentals/program-structure/main-command-line" + }, { "source_path": "docs/csharp/programming-guide/main-and-command-args/how-to-access-command-line-arguments-using-foreach.md", "redirect_url": "/dotnet/csharp/programming-guide/arrays/using-foreach-with-arrays" }, + { + "source_path": "docs/csharp/programming-guide/main-and-command-args/how-to-display-command-line-arguments.md", + "redirect_url": "/dotnet/csharp/fundamentals/tutorials/how-to-display-command-line-arguments" + }, + { + "source_path": "docs/csharp/programming-guide/main-and-command-args/index.md", + "redirect_url": "/dotnet/csharp/fundamentals/program-structure/main-command-line" + }, { "source_path": "docs/csharp/programming-guide/main-and-command-args/main-and-command-line-arguments.md", "redirect_url": "/dotnet/csharp/programming-guide/main-and-command-args/index" }, + { + "source_path": "docs/csharp/programming-guide/main-and-command-args/main-return-values.md", + "redirect_url": "/dotnet/csharp/fundamentals/program-structure/main-command-line" + }, + { + "source_path": "docs/csharp/programming-guide/main-and-command-args/top-level-statements.md", + "redirect_url": "/dotnet/csharp/fundamentals/program-structure/top-level-statements" + }, { "source_path": "docs/csharp/programming-guide/namespaces/how-to-use-the-global-namespace-alias.md", "redirect_url": "/dotnet/csharp/language-reference/operators/namespace-alias-qualifier" @@ -2567,10 +3143,26 @@ "source_path": "docs/csharp/programming-guide/types/how-to-safely-cast-using-as-and-is-operators.md", "redirect_url": "/dotnet/csharp/how-to/safely-cast-using-pattern-matching-is-and-as-operators" }, + { + "source_path": "docs/csharp/programming-guide/interfaces/index.md", + "redirect_url": "/dotnet/csharp/fundamentals/types/interfaces" + }, + { + "source_path": "docs/csharp/programming-guide/namespaces/index.md", + "redirect_url": "/dotnet/csharp/fundamentals/types/namespaces" + }, + { + "source_path": "docs/csharp/programming-guide/types/index.md", + "redirect_url": "/dotnet/csharp/fundamentals/types" + }, { "source_path": "docs/csharp/programming-guide/unsafe-code-pointers/arithmetic-operations-on-pointers.md", "redirect_url": "/dotnet/csharp/language-reference/operators/pointer-related-operators#pointer-arithmetic-operators" }, + { + "source_path": "docs/csharp/programming-guide/unsafe-code-pointers/fixed-size-buffers.md", + "redirect_url": "/dotnet/csharp/language-reference/unsafe-code#fixed-size-buffers" + }, { "source_path": "docs/csharp/programming-guide/unsafe-code-pointers/how-to-access-a-member-with-a-pointer.md", "redirect_url": "/dotnet/csharp/language-reference/operators/pointer-related-operators#pointer-member-access-operator--" @@ -2591,6 +3183,14 @@ "source_path": "docs/csharp/programming-guide/unsafe-code-pointers/how-to-obtain-the-value-of-a-pointer-variable.md", "redirect_url": "/dotnet/csharp/language-reference/operators/pointer-related-operators#pointer-indirection-operator-" }, + { + "source_path": "docs/csharp/programming-guide/unsafe-code-pointers/how-to-use-pointers-to-copy-an-array-of-bytes.md", + "redirect_url": "/dotnet/csharp/language-reference/unsafe-code#how-to-use-pointers-to-copy-an-array-of-bytes" + }, + { + "source_path": "docs/csharp/programming-guide/unsafe-code-pointers/index.md", + "redirect_url": "/dotnet/csharp/language-reference/unsafe-code" + }, { "source_path": "docs/csharp/programming-guide/unsafe-code-pointers/manipulating-pointers.md", "redirect_url": "/dotnet/csharp/language-reference/operators/pointer-related-operators" @@ -2599,10 +3199,18 @@ "source_path": "docs/csharp/programming-guide/unsafe-code-pointers/pointer-comparison.md", "redirect_url": "/dotnet/csharp/language-reference/operators/pointer-related-operators#pointer-comparison-operators" }, + { + "source_path": "docs/csharp/programming-guide/unsafe-code-pointers/pointer-conversions.md", + "redirect_url": "/dotnet/csharp/language-reference/unsafe-code#pointer-types" + }, { "source_path": "docs/csharp/programming-guide/unsafe-code-pointers/pointer-expressions.md", "redirect_url": "/dotnet/csharp/language-reference/operators/pointer-related-operators" }, + { + "source_path": "docs/csharp/programming-guide/unsafe-code-pointers/pointer-types.md", + "redirect_url": "/dotnet/csharp/language-reference/unsafe-code#pointer-types" + }, { "source_path": "docs/csharp/programming-guide/xmldoc/xml-documentation-comments.md", "redirect_url": "/dotnet/csharp/programming-guide/xmldoc" @@ -2724,7 +3332,27 @@ }, { "source_path": "docs/csharp/tutorials/default-interface-members-versions.md", - "redirect_url": "/dotnet/csharp/tutorials/default-interface-methods-versions" + "redirect_url": "/dotnet/csharp/whats-new/tutorials/default-interface-methods-versions" + }, + { + "source_path": "docs/csharp/tutorials/generate-consume-asynchronous-stream.md", + "redirect_url": "/dotnet/csharp/whats-new/tutorials/generate-consume-asynchronous-stream" + }, + { + "source_path": "docs/csharp/tutorials/mixins-with-default-interface-methods.md", + "redirect_url": "/dotnet/csharp/whats-new/tutorials/mixins-with-default-interface-methods" + }, + { + "source_path": "docs/csharp/tutorials/nullable-reference-types.md", + "redirect_url": "/dotnet/csharp/whats-new/tutorials/nullable-reference-types" + }, + { + "source_path": "docs/csharp/tutorials/ranges-indexes.md", + "redirect_url": "/dotnet/csharp/whats-new/tutorials/ranges-indexes" + }, + { + "source_path": "docs/csharp/tutorials/upgrade-to-nullable-references.md", + "redirect_url": "/dotnet/csharp/whats-new/tutorials/upgrade-to-nullable-references" }, { "source_path": "docs/csharp/tutorials/exploration/csharp-6.yml", @@ -2734,6 +3362,18 @@ "source_path": "docs/csharp/tutorials/exploration/csharp-7.yml", "redirect_url": "/dotnet/csharp/whats-new/csharp-7" }, + { + "source_path": "docs/csharp/tutorials/exploration/patterns-objects.md", + "redirect_url": "/dotnet/csharp/whats-new/tutorials/patterns-objects" + }, + { + "source_path": "docs/csharp/tutorials/exploration/records.md", + "redirect_url": "/dotnet/csharp/whats-new/tutorials/records" + }, + { + "source_path": "docs/csharp/tutorials/exploration/top-level-statements.md", + "redirect_url": "/dotnet/csharp/whats-new/tutorials/top-level-statements" + }, { "source_path": "docs/csharp/tutorials/intro-to-csharp/index.md", "redirect_url": "/dotnet/csharp/tour-of-csharp/tutorials/" @@ -2770,7 +3410,14 @@ "source_path": "docs/csharp/tutorials/intro-to-csharp/arrays-and-collections.md", "redirect_url": "/dotnet/csharp/tour-of-csharp/tutorials/arrays-and-collections" }, - + { + "source_path": "docs/csharp/tutorials/index.md", + "redirect_url": "/dotnet/csharp/tutorials/intro-to-csharp/introduction-to-classes" + }, + { + "source_path": "docs/csharp/tutorials/inheritance.md", + "redirect_url": "/dotnet/csharp/fundamentals/object-oriented/inheritance" + }, { "source_path": "docs/csharp/tutorials/intro-to-csharp/interpolated-strings-local.md", "redirect_url": "/dotnet/csharp/tutorials/exploration/interpolated-strings-local" @@ -2779,14 +3426,30 @@ "source_path": "docs/csharp/tutorials/intro-to-csharp/interpolated-strings.yml", "redirect_url": "/dotnet/csharp/tutorials/exploration/interpolated-strings" }, + { + "source_path": "docs/csharp/tutorials/intro-to-csharp/introduction-to-classes.md", + "redirect_url": "/dotnet/csharp/fundamentals/tutorials/classes" + }, + { + "source_path": "docs/csharp/tutorials/intro-to-csharp/object-oriented-programming.md", + "redirect_url": "/dotnet/csharp/fundamentals/tutorials/oop" + }, { "source_path": "docs/csharp/tutorials/microservices.md", "redirect_url": "/dotnet/core/docker/" }, + { + "source_path": "docs/csharp/tutorials/pattern-matching.md", + "redirect_url": "/dotnet/csharp/fundamentals/tutorials/pattern-matching" + }, { "source_path": "docs/csharp/type-system.md", "redirect_url": "/dotnet/csharp/programming-guide/types/index" }, + { + "source_path": "docs/csharp/walkthroughs.md", + "redirect_url": "/dotnet/csharp" + }, { "source_path": "docs/csharp/whats-new/csharp-6.md", "redirect_url": "/dotnet/csharp/whats-new/csharp-9" @@ -3053,6 +3716,10 @@ "source_path": "docs/fundamentals/code-analysis/quality-rules/ca1071.md", "redirect_url": "/dotnet/fundamentals/code-analysis/quality-rules/index" }, + { + "source_path": "docs/fundamentals/code-analysis/quality-rules/publish-warnings.md", + "redirect_url": "/dotnet/fundamentals/code-analysis/quality-rules/singlefile-warnings" + }, { "source_path": "docs/fundamentals/code-analysis/style-rules/ide0003.md", "redirect_url": "/dotnet/fundamentals/code-analysis/style-rules/ide0003-ide0009" @@ -3595,6 +4262,154 @@ "source_path": "docs/framework/network-programming/httplistener.md", "redirect_url": "/dotnet/api/system.net.httplistener" }, + { + "source_path": "docs/framework/net-native/apis-that-rely-on-reflection.md", + "redirect_url": "/windows/uwp/dotnet-native/apis-that-rely-on-reflection" + }, + { + "source_path": "docs/framework/net-native/application-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/application-element-net-native" + }, + { + "source_path": "docs/framework/net-native/assembly-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/assembly-element-net-native" + }, + { + "source_path": "docs/framework/net-native/attributeimplies-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/attributeimplies-element-net-native" + }, + { + "source_path": "docs/framework/net-native/directives-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/directives-element-net-native" + }, + { + "source_path": "docs/framework/net-native/event-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/event-element-net-native" + }, + { + "source_path": "docs/framework/net-native/example-handling-exceptions-when-binding-data.md", + "redirect_url": "/windows/uwp/dotnet-native/example-handling-exceptions-when-binding-data" + }, + { + "source_path": "docs/framework/net-native/example-troubleshooting-dynamic-programming.md", + "redirect_url": "/windows/uwp/dotnet-native/example-troubleshooting-dynamic-programming" + }, + { + "source_path": "docs/framework/net-native/field-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/field-element-net-native" + }, + { + "source_path": "docs/framework/net-native/genericparameter-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/genericparameter-element-net-native" + }, + { + "source_path": "docs/framework/net-native/getting-started-with-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/getting-started-with-net-native" + }, + { + "source_path": "docs/framework/net-native/impliestype-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/impliestype-element-net-native" + }, + { + "source_path": "docs/framework/net-native/index.md", + "redirect_url": "/windows/uwp/dotnet-native/index" + }, + { + "source_path": "docs/framework/net-native/library-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/library-element-net-native" + }, + { + "source_path": "docs/framework/net-native/measuring-startup-improvement-with-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/measuring-startup-improvement-with-net-native" + }, + { + "source_path": "docs/framework/net-native/method-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/method-element-net-native" + }, + { + "source_path": "docs/framework/net-native/methodinstantiation-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/methodinstantiation-element-net-native" + }, + { + "source_path": "docs/framework/net-native/migrating-your-windows-store-app-to-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/migrating-your-windows-store-app-to-net-native" + }, + { + "source_path": "docs/framework/net-native/missinginteropdataexception-class-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/missinginteropdataexception-class-net-native" + }, + { + "source_path": "docs/framework/net-native/missingmetadataexception-class-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/missingmetadataexception-class-net-native" + }, + { + "source_path": "docs/framework/net-native/missingruntimeartifactexception-class-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/missingruntimeartifactexception-class-net-native" + }, + { + "source_path": "docs/framework/net-native/namespace-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/namespace-element-net-native" + }, + { + "source_path": "docs/framework/net-native/net-native-and-compilation.md", + "redirect_url": "/windows/uwp/dotnet-native/net-native-and-compilation" + }, + { + "source_path": "docs/framework/net-native/net-native-general-troubleshooting.md", + "redirect_url": "/windows/uwp/dotnet-native/net-native-general-troubleshooting" + }, + { + "source_path": "docs/framework/net-native/net-native-reflection-api-reference.md", + "redirect_url": "/windows/uwp/dotnet-native/net-native-reflection-api-reference" + }, + { + "source_path": "docs/framework/net-native/parameter-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/parameter-element-net-native" + }, + { + "source_path": "docs/framework/net-native/property-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/property-element-net-native" + }, + { + "source_path": "docs/framework/net-native/reflection-and-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/reflection-and-net-native" + }, + { + "source_path": "docs/framework/net-native/runtime-directive-elements.md", + "redirect_url": "/windows/uwp/dotnet-native/runtime-directive-elements" + }, + { + "source_path": "docs/framework/net-native/runtime-directive-policy-settings.md", + "redirect_url": "/windows/uwp/dotnet-native/runtime-directive-policy-settings" + }, + { + "source_path": "docs/framework/net-native/runtime-directives-rd-xml-configuration-file-reference.md", + "redirect_url": "/windows/uwp/dotnet-native/runtime-directives-rd-xml-configuration-file-reference" + }, + { + "source_path": "docs/framework/net-native/runtime-exceptions-in-net-native-apps.md", + "redirect_url": "/windows/uwp/dotnet-native/runtime-exceptions-in-net-native-apps" + }, + { + "source_path": "docs/framework/net-native/serialization-and-metadata.md", + "redirect_url": "/windows/uwp/dotnet-native/serialization-and-metadata" + }, + { + "source_path": "docs/framework/net-native/subtypes-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/subtypes-element-net-native" + }, + { + "source_path": "docs/framework/net-native/type-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/type-element-net-native" + }, + { + "source_path": "docs/framework/net-native/typeinstantiation-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/typeinstantiation-element-net-native" + }, + { + "source_path": "docs/framework/net-native/typeparameter-element-net-native.md", + "redirect_url": "/windows/uwp/dotnet-native/typeparameter-element-net-native" + }, { "source_path": "docs/framework/security/building-my-first-claims-aware-aspnet-web-app.md", "redirect_url": "/previous-versions/dotnet/framework/security/building-my-first-claims-aware-aspnet-web-app" @@ -3769,8 +4584,7 @@ }, { "source_path": "docs/framework/tools/developer-command-prompt-for-vs.md", - "redirect_url": "/visualstudio/ide/reference/command-prompt-powershell", - "redirect_document_id": true + "redirect_url": "/visualstudio/ide/reference/command-prompt-powershell" }, { "source_path": "docs/framework/ui-automation/ui-automation-specification-and-community-promise.md", @@ -11766,6 +12580,11 @@ "source_path": "docs/standard/index.yml", "redirect_url": "/dotnet/fundamentals/" }, + { + "source_path": "docs/standard/language-independence-and-language-independent-components.md", + "redirect_url": "/dotnet/standard/language-independence", + "redirect_document_id": true + }, { "source_path": "docs/standard/library.md", "redirect_url": "/dotnet/standard/net-standard", @@ -11871,6 +12690,10 @@ "source_path": "docs/standard/serialization/web-services-ixmlserializable-technology-sample.md", "redirect_url": "/previous-versions/dotnet/netframework-4.0/h2byscsb(v=vs.100)" }, + { + "source_path": "docs/standard/serialization/write-custom-serializer-deserializer.md", + "redirect_url": "/dotnet/standard/serialization/system-text-json-use-dom-utf8jsonreader-utf8jsonwriter" + }, { "source_path": "docs/standard/threading/autoresetevent.md", "redirect_url": "/dotnet/api/system.threading.autoresetevent" @@ -13206,6 +14029,10 @@ { "source_path": "docs/azure/tools.md", "redirect_url": "/dotnet/azure/dotnet-dev-env-checklist" + }, + { + "source_path": "docs/standard/analyzers/api-analyzer.md", + "redirect_url": "/dotnet/standard/analyzers/platform-compat-analyzer" } ] } diff --git a/.whatsnew.json b/.whatsnew.json index 85a0c4aee32d8..e9f78784cee8a 100644 --- a/.whatsnew.json +++ b/.whatsnew.json @@ -17,7 +17,7 @@ }, { "names": ["azure"], - "heading": "Azure .NET SDK" + "heading": "Azure SDK for .NET" }, { "names": ["csharp"], diff --git a/README.md b/README.md index d92f2ccc97cdf..56afc542c74ae 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # .NET Docs -![Markdownlint](https://github.com/dotnet/docs/workflows/Markdownlint/badge.svg) +![Markdownlint](https://github.com/dotnet/docs/workflows/Markdownlint/badge.svg) [![target supported version](https://github.com/dotnet/docs/actions/workflows/version-sweep.yml/badge.svg)](https://github.com/dotnet/docs/actions/workflows/version-sweep.yml) This repository contains the conceptual documentation for .NET. The [.NET documentation site](https://docs.microsoft.com/dotnet) is built from multiple repositories in addition to this one: diff --git a/docfx.json b/docfx.json index f58a48a41c5ae..85a074d9bee98 100644 --- a/docfx.json +++ b/docfx.json @@ -16,6 +16,7 @@ "dest": ".", "exclude": [ "samples/**/*.*", + "**/snippets/**", "**/includes/**", "**/util/**", "***/contributing.md" @@ -108,17 +109,23 @@ ], "externalReference": [], "globalMetadata": { - "breadcrumb_path": "/dotnet/breadcrumb/toc.json", - "_displayLangs": ["csharp"], - "dev_langs": ["csharp"], - "ms.devlang": "dotnet", + "apiPlatform": "dotnet", "author": "dotnet-bot", + "breadcrumb_path": "/dotnet/breadcrumb/toc.json", + "dev_langs": [ "csharp" ], + "featureFlags": [ "enable_uhf_ppe" ], + "feedback_system": "GitHub", + "feedback_github_repo": "dotnet/docs", + "feedback_product_url": "https://aka.ms/feedback/report?space=61", "ms.author": "dotnetcontent", - "searchScope": [".NET"], - "uhfHeaderId": "MSDocsHeader-DotNet", - "apiPlatform": "dotnet", + "ms.devlang": "dotnet", "ms.prod":"dotnet", "ms.topic": "conceptual", + "recommendations": true, + "searchScope": [ ".NET" ], + "show_latex": true, + "uhfHeaderId": "MSDocsHeader-DotNet", + "_displayLangs": [ "csharp" ], "_op_documentIdPathDepotMapping": { "docs/architecture/containerized-lifecycle/": { "folder_relative_path_in_docset": "docs/standard/containerized-lifecycle-architecture/" @@ -130,19 +137,12 @@ "folder_relative_path_in_docset": "docs/standard/modern-web-apps-azure-architecture/" }, "docs/architecture/modernize-with-azure-containers/": { - "folder_relative_path_in_docset": "docs/standard/modernize-with-azure-and-containers/" - }, - "docs/architecture/serverless/": { - "folder_relative_path_in_docset": "docs/standard/serverless-architecture/" - } - }, - "feedback_system": "GitHub", - "feedback_github_repo": "dotnet/docs", - "feedback_product_url": "https://aka.ms/feedback/report?space=61", - "featureFlags": [ - "enable_uhf_ppe" - ], - "show_latex": true + "folder_relative_path_in_docset": "docs/standard/modernize-with-azure-and-containers/" + }, + "docs/architecture/serverless/": { + "folder_relative_path_in_docset": "docs/standard/serverless-architecture/" + } + } }, "fileMetadata": { "feedback_system": { @@ -150,10 +150,7 @@ "docs/framework/data/adonet/**/**.md": "None", "docs/framework/data/wcf/**/**.md": "None", "docs/framework/ui-automation/**/**.md": "None", - "docs/framework/wcf/**/**.md": "None", - "docs/framework/winforms/**/**.md": "None", - "docs/framework/wpf/**/**.md": "None", - "docs/framework/xaml-services/**/**.md": "None" + "docs/framework/wcf/**/**.md": "None" }, "feedback_product_url": { "docs/azure/sdk/**/*.*": "https://github.com/azure/azure-sdk-for-net", @@ -188,30 +185,56 @@ "_csharplang/**/*.md": "language-reference", "_vblang/spec/*.md": "language-reference", "docs/azure/**/**.md": "conceptual", + "docs/core/compatibility/**.md": "reference", "docs/core/tools/dotnet*.md": "reference", + "docs/core/tools/sdk-errors/*.md": "error-reference", "docs/core/tutorials/**.md": "tutorial", "docs/csharp/getting-started/**/*.md": "overview", "docs/csharp/how-to/**/*.md": "how-to", - "docs/csharp/language-reference/compiler-messages/*.md": "error-reference", "docs/csharp/language-reference/**/*.md": "reference", + "docs/csharp/language-reference/compiler-messages/*.md": "error-reference", "docs/csharp/linq/*.md" : "how-to", - "docs/csharp/misc/**/*.md": "error-reference", + "docs/csharp/misc/*.md": "error-reference", "docs/csharp/programming-guide/**" : "conceptual", + "docs/csharp/programming-guide/xmldoc/**" : "reference", "docs/csharp/roslyn-sdk/get-started/*.md" : "tutorial", "docs/csharp/roslyn-sdk/tutorials/*.md" : "tutorial", - "docs/csharp/tour-of-csharp/**" : "overview", + "docs/csharp/tour-of-csharp/tutorials/**" : "tutorial", "docs/csharp/tutorials/**" : "tutorial", - "docs/framework/**/*how-to*.md": "how-to", "docs/framework/additional-apis/**/**.md": "managed-reference", + "docs/framework/configure-apps/file-schema/**/**.md": "reference", + "docs/framework/data/adonet/ef/language-reference/*-entity-sql.md": "language-reference", + "docs/framework/debug-trace-profile/*-mda.md": "reference", + "docs/framework/performance/*-etw-events.md": "reference", + "docs/framework/tools/**/**.md": "reference", "docs/framework/unmanaged-api/**/**.md": "reference", "docs/framework/wcf/diagnostics/etw/**.md": "reference", "docs/framework/wcf/diagnostics/event-logging/**.md": "reference", "docs/framework/wcf/diagnostics/performance-counters/**.md": "reference", "docs/framework/wcf/diagnostics/tracing/**.md": "reference", "docs/framework/wcf/diagnostics/wmi/**.md": "reference", + "docs/framework/wcf/whats-new/**.md": "reference", + "docs/framework/**/how-to*.md": "how-to", + "docs/framework/**/troubleshooting*.md": "troubleshooting", "docs/fsharp/language-reference/**/**.md": "language-reference", + "docs/fundamentals/code-analysis/**.md": "reference", + "docs/fundamentals/code-analysis/quality-rules/**.md": "reference", + "docs/fundamentals/code-analysis/style-rules/**.md": "reference", + "docs/fundamentals/diagnostics/**.md": "reference", + "docs/fundamentals/syslib-diagnostics/**/*.md": "reference", "docs/standard/**/*how-to*.md": "how-to", - "docs/standard/base-types/*.md": "how-to" + "docs/standard/base-types/*.md": "how-to", + "docs/standard/data/sqlite/*.md": "reference", + "docs/visual-basic/language-reference/**/*.md": "reference", + "docs/visual-basic/reference/**/*.md": "reference", + "docs/visual-basic/misc/bc*.md": "error-reference", + "docs/visual-basic/**/troubleshooting*.md": "troubleshooting", + "docs/whats-new/**/**.md": "reference", + "docs/windows-workflow-foundation/1*.md": "error-reference", + "docs/windows-workflow-foundation/2*.md": "error-reference", + "docs/windows-workflow-foundation/3*.md": "error-reference", + "docs/windows-workflow-foundation/4*.md": "error-reference", + "docs/windows-workflow-foundation/5*.md": "error-reference" }, "dev_langs": { "docs/fsharp/**/**.md": ["fsharp"], @@ -230,7 +253,7 @@ "docs/core/**/**.md": "tdykstra", "docs/core/compatibility/**/**.md": "gewarren", "docs/core/deploying/**/**.md": "adegeo", - "docs/core/diagnostics/**/**.md": "sywhang", + "docs/core/diagnostics/**/**.md": "tommcdon", "docs/core/docker/**/**.md": "IEvangelist", "docs/core/native-interop/**/**.md": "jkoritzinsky", "docs/core/porting/**/**.md": "cartermp", @@ -247,13 +270,12 @@ "docs/framework/configure-apps/file-schema/network/**/**.md": "karelz", "docs/framework/configure-apps/file-schema/wcf/**/**.md": "HongGit", "docs/framework/configure-apps/file-schema/winforms/**/**.md": "adegeo", - "docs/framework/data/**/**.md": "stevestein", + "docs/framework/data/**/**.md": "mcleblanc", "docs/framework/deployment/**/**.md": "adegeo", "docs/framework/get-started/**/**.md": "gewarren", "docs/framework/install/**/**.md": "adegeo", "docs/framework/migration-guide/**/**.md": "gewarren", "docs/framework/misc/**/**.md": "gewarren", - "docs/framework/net-native/**/**.md": "gewarren", "docs/framework/network-programming/**/**.md": "karelz", "docs/framework/performance/**/**.md": "billwagner", "docs/framework/reflection-and-codedom/**/**.md": "adegeo", @@ -261,20 +283,18 @@ "docs/framework/tools/**/**.md": "tdykstra", "docs/framework/ui-automation/**/**.md": "adegeo", "docs/framework/unmanaged-api/alink/**/**.md": "jeffschwMSFT", - "docs/framework/unmanaged-api/debugging/**/**.md": "sywhang", - "docs/framework/unmanaged-api/diagnostics/**/**.md": "sywhang", + "docs/framework/unmanaged-api/debugging/**/**.md": "tommcdon", + "docs/framework/unmanaged-api/diagnostics/**/**.md": "tommcdon", "docs/framework/unmanaged-api/fusion/**/**.md": "jeffschwMSFT", "docs/framework/unmanaged-api/hosting/**/**.md": "jeffschwMSFT", - "docs/framework/unmanaged-api/profiling/**/**.md": "sywhang", + "docs/framework/unmanaged-api/profiling/**/**.md": "tommcdon", "docs/framework/unmanaged-api/strong-naming/**/**.md": "jeffschwMSFT", "docs/framework/unmanaged-api/tlbexp/**/**.md": "jeffschwMSFT", "docs/framework/whats-new/**/**.md": "gewarren", "docs/framework/wcf/**/**.md": "HongGit", - "docs/framework/winforms/**/**.md": "adegeo", - "docs/framework/wpf/**/**.md": "adegeo", - "docs/framework/xaml-services/**/**.md": "adegeo", "docs/fsharp/**/**.md": "cartermp", "docs/fundamentals/code-analysis/**/**.md": "gewarren", + "docs/fundamentals/syslib-diagnostics/**/**.md": "gewarren", "docs/machine-learning/**/**.md": "luisquintanilla", "docs/spark/**/**.md": "luisquintanilla", "docs/standard/**/**.md": "gewarren", @@ -316,7 +336,7 @@ "docs/core/**/**.md": "dotnetcontent", "docs/core/compatibility/**/**.md": "gewarren", "docs/core/deploying/**/**.md": "adegeo", - "docs/core/diagnostics/**/**.md": "suwhang", + "docs/core/diagnostics/**/**.md": "tommcdon", "docs/core/docker/**/**.md": "dapine", "docs/core/native-interop/**/**.md": "jekoritz", "docs/core/porting/**/**.md": "phcart", @@ -333,14 +353,13 @@ "docs/framework/configure-apps/file-schema/network/**/**.md": "ncldev", "docs/framework/configure-apps/file-schema/wcf/**/**.md": "wcfsrvt", "docs/framework/configure-apps/file-schema/winforms/**/**.md": "adegeo", - "docs/framework/data/adonet/**/**.md": "sstein", + "docs/framework/data/adonet/**/**.md": "dotnetcontent", "docs/framework/data/wcf/**/**.md": "wcfsrvt", "docs/framework/deployment/**/**.md": "adegeo", "docs/framework/get-started/**/**.md": "gewarren", "docs/framework/install/**/**.md": "adegeo", "docs/framework/migration-guide/**/**.md": "gewarren", "docs/framework/misc/**/**.md": "gewarren", - "docs/framework/net-native/**/**.md": "gewarren", "docs/framework/network-programming/**/**.md": "ncldev", "docs/framework/performance/**/**.md": "wiwagn", "docs/framework/reflection-and-codedom/**/**.md": "adegeo", @@ -348,20 +367,18 @@ "docs/framework/tools/**/**.md": "tdykstra", "docs/framework/ui-automation/**/**.md": "adegeo", "docs/framework/unmanaged-api/alink/**/**.md": "jeffschw", - "docs/framework/unmanaged-api/debugging/**/**.md": "suwhang", - "docs/framework/unmanaged-api/diagnostics/**/**.md": "suwhang", + "docs/framework/unmanaged-api/debugging/**/**.md": "tommcdon", + "docs/framework/unmanaged-api/diagnostics/**/**.md": "tommcdon", "docs/framework/unmanaged-api/fusion/**/**.md": "jeffschw", "docs/framework/unmanaged-api/hosting/**/**.md": "jeffschw", - "docs/framework/unmanaged-api/profiling/**/**.md": "suwhang", + "docs/framework/unmanaged-api/profiling/**/**.md": "tommcdon", "docs/framework/unmanaged-api/strong-naming/**/**.md": "jeffschw", "docs/framework/unmanaged-api/tlbexp/**/**.md": "jeffschw", "docs/framework/whats-new/**/**.md": "gewarren", "docs/framework/wcf/**/**.md": "wcfsrvt", - "docs/framework/winforms/**/**.md": "adegeo", - "docs/framework/wpf/**/**.md": "adegeo", - "docs/framework/xaml-services/**/**.md": "adegeo", "docs/fsharp/**/**.md": "phcart", "docs/fundamentals/code-analysis/**/*.md": "gewarren", + "docs/fundamentals/syslib-diagnostics/**/**.md": "gewarren", "docs/machine-learning/**/**.md": "luquinta", "docs/spark/**/**.md": "luquinta", "docs/standard/**/**.md": "gewarren", @@ -417,6 +434,7 @@ "docs/csharp/whats-new/**/**.md": "csharp-whats-new", "docs/csharp/how-to/**/**.md": "csharp-fundamentals", "docs/csharp/linq/**/**.md": "csharp-linq", + "docs/csharp/fundamentals/**/**.md": "csharp-fundamentals", "docs/csharp/programming-guide/main-and-command-args/**/**.md": "csharp-fundamentals", "docs/csharp/programming-guide/indexers/**/**.md": "csharp-fundamentals", "docs/csharp/programming-guide/generics/**/**.md": "csharp-fundamentals", @@ -442,7 +460,6 @@ "docs/csharp/programming-guide/events/**/**.md": "csharp-fundamentals", "docs/csharp/programming-guide/inside-a-program/**/**.md": "csharp-get-started", "docs/csharp/programming-guide/interfaces/**/**.md": "csharp-fundamentals", - "docs/csharp/getting-started/**/**.md": "csharp-get-started", "docs/csharp/tutorials/**/**.md": "csharp-fundamentals", "docs/csharp/tutorials/exploration/**/**.md": "csharp-get-started", "docs/csharp/tutorials/intro-to-csharp/**/**.md": "csharp-get-started", @@ -463,15 +480,49 @@ "docs/framework/network-programming/**/**.md": "dotnet-networking", "docs/framework/wcf/**/**.md": "dotnet-wcf", "docs/framework/windows-workflow-foundation/**/**.md": "dotnet-wf", - "docs/framework/winforms/**/**.md": "dotnet-winforms", - "docs/framework/wpf/**/**.md": "dotnet-wpf", - "docs/framework/xaml-services/**/**.md": "dotnet-wpf", "docs/standard/analyzers/**.md": "dotnet-analyzers", "docs/standard/design-guidelines/*.md": "dotnet-standard", "docs/standard/security/**.md": "dotnet-security", "docs/visual-basic/language-reference/error-messages/**/**.md": "vb-diagnostics", "docs/visual-basic/misc/**/**.md": "vb-diagnostics" }, + "recommendations": { + "_csharplang/**/*.md": false, + "_vblang/spec/*.md": false, + "docs/architecture/**/**.md": false, + "docs/standard/design-guidelines/**/**.md": false, + "docs/core/compatibility/**/**.md": false, + "docs/core/tools/dotnet*.md": false, + "docs/core/tools/sdk-errors/**/**.md": false, + "docs/csharp/language-reference/**/**.md": false, + "docs/csharp/misc/**/**.md": false, + "docs/csharp/programming-guide/xmldoc/**/**.md": false, + "docs/csharp/tour-of-csharp/**/*.md": false, + "docs/csharp/tour-of-csharp/tutorials/*.yml": false, + "docs/framework/additional-apis/**/**.md": false, + "docs/framework/configure-apps/file-schema/**/**.md": false, + "docs/framework/data/adonet/ef/language-reference/*-entity-sql.md": false, + "docs/framework/debug-trace-profile/**/**.md": false, + "docs/framework/performance/*-etw-events.md": false, + "docs/framework/tools/**/**.md": false, + "docs/framework/unmanaged-api/**/**.md": false, + "docs/framework/wcf/diagnostics/event-logging/**/**.md": false, + "docs/framework/wcf/diagnostics/performance-counters/**/**.md": false, + "docs/framework/wcf/diagnostics/tracing/**/**.md": false, + "docs/framework/wcf/diagnostics/wmi/**/**.md": false, + "docs/framework/wcf/whats-new/**.md": false, + "docs/fsharp/language-reference/**/**.md": false, + "docs/fundamentals/code-analysis/quality-rules/**/**.md": false, + "docs/fundamentals/code-analysis/style-rules/**/**.md": false, + "docs/fundamentals/diagnostics/**/**.md": false, + "docs/fundamentals/syslib-diagnostics/**/**.md": false, + "docs/standard/data/sqlite/**/**.md": false, + "docs/standard/library-guidance/**/**.md": false, + "docs/visual-basic/language-reference/**/**.md": false, + "docs/visual-basic/reference/**/**.md": false, + "docs/visual-basic/misc/**/**.md": false, + "docs/whats-new/**/**.md": false + }, "title": { "_csharplang/spec/introduction.md": "Introduction", "_csharplang/spec/lexical-structure.md": "Lexical structure", @@ -545,7 +596,7 @@ "_csharplang/proposals/csharp-9.0/nullable-reference-types-specification.md": "Nullable reference types - specification", "_csharplang/proposals/csharp-9.0/patterns3.md" : "Pattern matching changes", "_csharplang/proposals/csharp-9.0/records.md" : "Records", - "_csharplang/proposals/csharp-9.0/skip-localsinit.md" : "Surpress emitting localsinit flag", + "_csharplang/proposals/csharp-9.0/skip-localsinit.md" : "Suppress emitting localsinit flag", "_csharplang/proposals/csharp-9.0/static-anonymous-functions.md" : "Static anonymous functions", "_csharplang/proposals/csharp-9.0/target-typed-conditional-expression.md" : "Target-typed conditional expression", "_csharplang/proposals/csharp-9.0/target-typed-new.md" : "Target-typed new expressions", diff --git a/docs/architecture/cloud-native/deploy-containers-azure.md b/docs/architecture/cloud-native/deploy-containers-azure.md index f990dcff31c52..8ad406beb5a90 100644 --- a/docs/architecture/cloud-native/deploy-containers-azure.md +++ b/docs/architecture/cloud-native/deploy-containers-azure.md @@ -14,7 +14,7 @@ We've discussed containers in this chapter and in chapter 1. We've seen that con ## Azure Container Registry -When containerizing a microservice, you first a build container "image." The image is a binary representation of the service code, dependencies, and runtime. While you can manually create an image using the `Docker Build` command from the Docker API, a better approach is to create it as part of an automated build process. +When containerizing a microservice, you first build a container "image." The image is a binary representation of the service code, dependencies, and runtime. While you can manually create an image using the `Docker Build` command from the Docker API, a better approach is to create it as part of an automated build process. Once created, container images are stored in container registries. They enable you to build, store, and manage container images. There are many registries available, both public and private. Azure Container Registry (ACR) is a fully managed container registry service in the Azure cloud. It persists your images inside the Azure network, reducing the time to deploy them to Azure container hosts. You can also secure them using the same security and identity procedures that you use for other Azure resources. diff --git a/docs/architecture/cloud-native/deploy-eshoponcontainers-azure.md b/docs/architecture/cloud-native/deploy-eshoponcontainers-azure.md index 16ef0408254db..5eeceb46a1e18 100644 --- a/docs/architecture/cloud-native/deploy-eshoponcontainers-azure.md +++ b/docs/architecture/cloud-native/deploy-eshoponcontainers-azure.md @@ -50,7 +50,7 @@ Note how the template describes a dynamic set of key/value pairs. When the templ You'll find the eShopOnContainers helm charts in the /k8s/helm folder. Figure 2-6 shows how the different components of the application are organized into a folder structure used by helm to define and managed deployments. -![eShopOnContainers Architecture](./media/eshoponcontainers-helm-folder.png) +![The eShopOnContainers helm folder](./media/eshoponcontainers-helm-folder.png) **Figure 2-6**. The eShopOnContainers helm folder. Each individual component is installed using a `helm install` command. eShop includes a "deploy all" script that loops through and installs the components using their respective helm charts. The result is a repeatable process, versioned with the application in source control, that anyone on the team can deploy to an AKS cluster with a one-line script command. @@ -65,12 +65,12 @@ Developers share a running (development) instance in an AKS cluster that contain In Figure 2-7, you can see that Developer Susie has deployed an updated version of the Bikes microservice into her dev space. She's then able to test her changes using a custom URL starting with the name of her space (susie.s.dev.myapp.eus.azds.io). -![eShopOnContainers Architecture](./media/azure-devspaces-one.png) +![eShopOnContainers Architecture showing Bikes microservice](./media/azure-devspaces-one.png) **Figure 2-7**. Developer Susie deploys her own version of the Bikes microservice and tests it. At the same time, developer John is customizing the Reservations microservice and needs to test his changes. He deploys his changes to his own dev space without conflicting with Susie's changes as shown in Figure 2-8. John then tests his changes using his own URL that is prefixed with the name of his space (john.s.dev.myapp.eus.azds.io). -![eShopOnContainers Architecture](./media/azure-devspaces-two.png) +![eShopOnContainers Architecture showing John's version of Reservations microservice](./media/azure-devspaces-two.png) **Figure 2-8**. Developer John deploys his own version of the Reservations microservice and tests it without conflicting with other developers. Using Azure Dev Spaces, teams can work directly with AKS while independently changing, deploying, and testing their changes. This approach reduces the need for separate dedicated hosted environments since every developer effectively has their own AKS environment. Developers can work with Azure Dev Spaces using its CLI or launch their application to Azure Dev Spaces directly from Visual Studio. [Learn more about how Azure Dev Spaces works and is configured.](/azure/dev-spaces/how-dev-spaces-works) diff --git a/docs/architecture/cloud-native/devops.md b/docs/architecture/cloud-native/devops.md index fb2bcd9001e0f..e681aa397762f 100644 --- a/docs/architecture/cloud-native/devops.md +++ b/docs/architecture/cloud-native/devops.md @@ -251,7 +251,7 @@ This build definition uses a number of built-in tasks that make creating builds Builds can be triggered manually, by a check-in, on a schedule, or by the completion of another build. In most cases, building on every check-in is desirable. Builds can be filtered so that different builds run against different parts of the repository or against different branches. This allows for scenarios like running fast builds with reduced testing on pull requests and running a full regression suite against the trunk on a nightly basis. -The end result of a build is a collection of files known as build artifacts. These artifacts can be passed along to the next step in the build process or added to an Azure Artifact feed, so they can be consumed by other builds. +The end result of a build is a collection of files known as build artifacts. These artifacts can be passed along to the next step in the build process or added to an Azure Artifacts feed, so they can be consumed by other builds. ### Azure DevOps releases diff --git a/docs/architecture/cloud-native/front-end-communication.md b/docs/architecture/cloud-native/front-end-communication.md index ed7a0aed3c81b..56f52937e3f35 100644 --- a/docs/architecture/cloud-native/front-end-communication.md +++ b/docs/architecture/cloud-native/front-end-communication.md @@ -38,7 +38,7 @@ The gateway insulates the client from internal service partitioning and refactor Care must be taken to keep the API Gateway simple and fast. Typically, business logic is kept out of the gateway. A complex gateway risks becoming a bottleneck and eventually a monolith itself. Larger systems often expose multiple API Gateways segmented by client type (mobile, web, desktop) or back-end functionality. The [Backend for Frontends](/azure/architecture/patterns/backends-for-frontends) pattern provides direction for implementing multiple gateways. The pattern is shown in Figure 4-4. -![API Gateway Pattern](./media/backend-for-frontend-pattern.png) +![Backend for Frontend Pattern](./media/backend-for-frontend-pattern.png) **Figure 4-4.** Backend for frontend pattern diff --git a/docs/architecture/cloud-native/identity-server.md b/docs/architecture/cloud-native/identity-server.md index 9b60f79a93a11..c83593b3dba60 100644 --- a/docs/architecture/cloud-native/identity-server.md +++ b/docs/architecture/cloud-native/identity-server.md @@ -6,7 +6,7 @@ ms.date: 05/13/2020 # IdentityServer for cloud-native applications -IdentityServer is an open-source authentication server that implements OpenID Connect (OIDC) and OAuth 2.0 standards for ASP.NET Core. It's designed to provide a common way to authenticate requests to all of your applications, whether they're web, native, mobile, or API endpoints. IdentityServer can be used to implement Single Sign-On (SSO) for multiple applications and application types. It can be used to authenticate actual users via sign-in forms and similar user interfaces as well as service-based authentication that typically involves token issuance, verification, and renewal without any user interface. IdentityServer is designed to be a customizable solution. Each instance is typically customized to suit an individual organization and/or set of applications' needs. +IdentityServer is an authentication server that implements OpenID Connect (OIDC) and OAuth 2.0 standards for ASP.NET Core. It's designed to provide a common way to authenticate requests to all of your applications, whether they're web, native, mobile, or API endpoints. IdentityServer can be used to implement Single Sign-On (SSO) for multiple applications and application types. It can be used to authenticate actual users via sign-in forms and similar user interfaces as well as service-based authentication that typically involves token issuance, verification, and renewal without any user interface. IdentityServer is designed to be a customizable solution. Each instance is typically customized to suit an individual organization and/or set of applications' needs. ## Common web app scenarios @@ -37,7 +37,14 @@ IdentityServer provides middleware that runs within an ASP.NET Core application ## Getting started -IdentityServer4 is open-source and free to use. You can add it to your applications using its NuGet packages. The main package is [IdentityServer4](https://www.nuget.org/packages/IdentityServer4/) that has been downloaded over four million times. The base package doesn't include any user interface code and only supports in memory configuration. To use it with a database, you'll also want a data provider like [IdentityServer4.EntityFramework](https://www.nuget.org/packages/IdentityServer4.EntityFramework) that uses Entity Framework Core to store configuration and operational data for IdentityServer. For user interface, you can copy files from the [Quickstart UI repository](https://github.com/IdentityServer/IdentityServer4.Quickstart.UI) into your ASP.NET Core MVC application to add support for sign in and sign out using IdentityServer middleware. +IdentityServer4 is available under dual license: + +* RPL - let's you use the IdentityServer4 free if used in open source work +* Paid - let's you use the IdentityServer4 in a commercial scenario + +Please reach out to official [Product's pricing](https://duendesoftware.com/products/identityserver) page. + +You can add it to your applications using its NuGet packages. The main package is [IdentityServer4](https://www.nuget.org/packages/IdentityServer4/) that has been downloaded over four million times. The base package doesn't include any user interface code and only supports in memory configuration. To use it with a database, you'll also want a data provider like [IdentityServer4.EntityFramework](https://www.nuget.org/packages/IdentityServer4.EntityFramework) that uses Entity Framework Core to store configuration and operational data for IdentityServer. For user interface, you can copy files from the [Quickstart UI repository](https://github.com/IdentityServer/IdentityServer4.Quickstart.UI) into your ASP.NET Core MVC application to add support for sign in and sign out using IdentityServer middleware. ## Configuration diff --git a/docs/architecture/cloud-native/infrastructure-as-code.md b/docs/architecture/cloud-native/infrastructure-as-code.md index f47d85bbe3287..b5acdb53816d2 100644 --- a/docs/architecture/cloud-native/infrastructure-as-code.md +++ b/docs/architecture/cloud-native/infrastructure-as-code.md @@ -63,7 +63,7 @@ Resource Manager templates can be run in many of ways. Perhaps the simplest way Cloud-native applications are often constructed to be `cloud agnostic`. Being so means the application isn't tightly coupled to a particular cloud vendor and can be deployed to any public cloud. -[Terraform](https://www.terraform.io/) is commercial templating tool that can provision cloud-native applications across all the major cloud players: Azure, Google Cloud Platform, AWS, and AliCloud. Instead of using JSON as the template definition language, it uses the slightly more terse YAML. +[Terraform](https://www.terraform.io/) is a commercial templating tool that can provision cloud-native applications across all the major cloud players: Azure, Google Cloud Platform, AWS, and AliCloud. Instead of using JSON as the template definition language, it uses the slightly more terse HCL (Hashicorp Configuration Language). An example Terraform file that does the same as the previous Resource Manager template (Figure 10-15) is shown in Figure 10-16: diff --git a/docs/architecture/containerized-lifecycle/Microsoft-platform-tools-containerized-apps/index.md b/docs/architecture/containerized-lifecycle/Microsoft-platform-tools-containerized-apps/index.md index 2be03b5d2e66c..8534d9f9e810e 100644 --- a/docs/architecture/containerized-lifecycle/Microsoft-platform-tools-containerized-apps/index.md +++ b/docs/architecture/containerized-lifecycle/Microsoft-platform-tools-containerized-apps/index.md @@ -17,21 +17,21 @@ A containerized Docker life-cycle workflow can be initially prescriptive based o Table 3-1 demonstrates that the intention of the Azure DevOps for containerized Docker applications is to provide an open DevOps workflow so that you can choose what products to use for each phase (Microsoft or third-party) while providing a simplified workflow that provides "by-default-products" already connected; thus, you can quickly get started with your enterprise-level DevOps workflow for Docker apps. -**Table 3-1.** Azure DevOps workflows, open to any technology +**Table 3-1.** DevOps workflows, open to any technology | Host | Microsoft technologies | Third-party (Azure pluggable) | | ---------------------------| ----------------------------------------------------| --------------------------------------------------------------------------------| | Platform for Docker apps | • Microsoft Visual Studio and Visual Studio Code
• .NET
• Microsoft Azure Kubernetes Service (AKS)
• Azure Container Registry
| • Any code editor (for example, Sublime)
• Any language (Node.js, Java, Go, etc.)
• Any orchestrator and scheduler
• Any Docker registry
| -| DevOps for Docker apps | • Azure DevOps Services
• Microsoft Team Foundation Server
• Azure Kubernetes Service (AKS)
| • GitHub, Git, Subversion, etc.
• Jenkins, Chef, Puppet, Velocity, CircleCI, TravisCI, etc.
• On-premises Docker Datacenter, Kubernetes, Mesos DC/OS, etc.
| +| DevOps for Docker apps | • Azure DevOps Services
• Microsoft Team Foundation Server
• GitHub
• Azure Kubernetes Service (AKS)
| • GitHub, Git, Subversion, etc.
• Jenkins, Chef, Puppet, Velocity, CircleCI, TravisCI, etc.
• On-premises Docker Datacenter, Kubernetes, Mesos DC/OS, etc.
| | Management and monitoring | • Azure Monitor | • Marathon, Chronos, etc.
| The Microsoft platform and tools for containerized Docker apps, as defined in Table 3-1, comprise the following components: - **Platform for Docker Apps development** The development of a service, or collection of services that make up an "app." The development platform provides all the work developers requires prior to pushing their code to a shared code repository. Developing services, deployed as containers, are similar to the development of the same apps or services without Docker. You continue to use your preferred language (.NET, Node.js, Go, etc.) and preferred editor or IDE like Visual Studio or Visual Studio Code. However, rather than consider Docker a deployment destination, you develop your services in the Docker environment. You build, run, test, and debug your code in containers locally, providing the destination environment at development time. By providing the destination environment locally, Docker containers set up what will drastically help you improve your DevOps life cycle. Visual Studio and Visual Studio Code have extensions to integrate Docker containers within your development process. -- **DevOps for Docker Apps** Developers creating Docker applications can use [Azure DevOps](https://azure.microsoft.com/services/devops/) or any other third-party product, like Jenkins, to build out a comprehensive automated application life-cycle management (ALM). +- **DevOps for Docker Apps** Developers creating Docker applications can use [Azure DevOps](https://azure.microsoft.com/services/devops/), GitHub or any other third-party product, like Jenkins, to build out a comprehensive automated application life-cycle management (ALM). - With Azure DevOps, developers can create container-focused DevOps for a fast, iterative process that covers source-code control from anywhere (Azure DevOps-Git, GitHub, any remote Git repository, or Subversion), Continuous Integration (CI), internal unit tests, inter-container/service integration tests, Continuous Delivery (CD), and release management (RM). Developers also can automate their Docker application releases into Azure Kubernetes Service (AKS), from development to staging and production environments. + With Azure DevOps and/or GitHub, developers can create container-focused DevOps for a fast, iterative process that covers source-code control from anywhere (Azure DevOps-Git, GitHub, any remote Git repository, or Subversion), Continuous Integration (CI), internal unit tests, inter-container/service integration tests, Continuous Delivery (CD), and release management (RM). Developers also can automate their Docker application releases into Azure Kubernetes Service (AKS), from development to staging and production environments. - **Management and Monitoring** IT can manage and monitor production applications and services in several ways, integrating both perspectives in a consolidated experience. @@ -42,11 +42,13 @@ The Microsoft platform and tools for containerized Docker apps, as defined in Ta Even if you're familiar with Linux commands, you can manage your container applications using Microsoft Windows and PowerShell with a Linux Subsystem command line and the products (Docker, Kubernetes…) clients running on this Linux Subsystem capability. You'll learn more about using these tools under Linux Subsystem using your favorite Microsoft Windows OS later in this book. - **Open-source tools** Because AKS exposes the standard API endpoints for the orchestration engine, the most popular tools are compatible with AKS and, in most cases, will work out of the box—including visualizers, monitoring, command-line tools, and even future tools as they become available. + + - **GitHub Advanced Security** [GitHub Advanced Security](https://docs.github.com/github/getting-started-with-github/about-github-advanced-security) offers a suite of tools for securing the software supply chain that can seamlessly integrate security into the daily workflow of teams developing containerized applications. - **Azure Monitor** Is Azure's solution to monitor every angle of your production environment. You can monitor production Docker applications by just setting up its SDK into your services so that you can get system-generated log data from the applications. Thus, Microsoft offers a complete foundation for an end-to-end containerized Docker application life cycle. However, it's *a collection of products and technologies that allow you to optionally select and integrate with existing tools and processes*. The flexibility in a broad approach along with the strength in the depth of capabilities place Microsoft in a strong position for containerized Docker application development. >[!div class="step-by-step"] ->[Previous](../Docker-application-lifecycle/containers-foundation-for-devops-collaboration.md) +>[Previous](../docker-application-lifecycle/containers-foundation-for-devops-collaboration.md) >[Next](../design-develop-containerized-apps/index.md) diff --git a/docs/architecture/containerized-lifecycle/design-develop-containerized-apps/visual-studio-tools-for-docker.md b/docs/architecture/containerized-lifecycle/design-develop-containerized-apps/visual-studio-tools-for-docker.md index f8cf77e6fee47..fc443b8d2e62e 100644 --- a/docs/architecture/containerized-lifecycle/design-develop-containerized-apps/visual-studio-tools-for-docker.md +++ b/docs/architecture/containerized-lifecycle/design-develop-containerized-apps/visual-studio-tools-for-docker.md @@ -40,7 +40,7 @@ When you add or enable Docker support, Visual Studio adds a _Dockerfile_ file to When you want to compose a multi-container solution, add container orchestration support to your projects. This lets you run and debug a group of containers (a whole solution) at the same time if they're defined in the same _docker-compose.yml_ file. -To add container orchestration support, right-click on the solution or project node in **Solution Explorer**, and choose **Add > Container Orchestration Support**. Then choose **Kubernetes/Helm** or **Docker Compose** to manage the containers. +To add container orchestration support, right-click on the project node in **Solution Explorer**, and choose **Add > Container Orchestration Support**. Then choose **Kubernetes/Helm** or **Docker Compose** to manage the containers. After you add container orchestration support to your project, you see a Dockerfile added to the project and a **docker-compose** folder added to the solution in **Solution Explorer**, as shown in Figure 4-33: diff --git a/docs/architecture/containerized-lifecycle/Docker-application-lifecycle/containers-foundation-for-devops-collaboration.md b/docs/architecture/containerized-lifecycle/docker-application-lifecycle/containers-foundation-for-devops-collaboration.md similarity index 100% rename from docs/architecture/containerized-lifecycle/Docker-application-lifecycle/containers-foundation-for-devops-collaboration.md rename to docs/architecture/containerized-lifecycle/docker-application-lifecycle/containers-foundation-for-devops-collaboration.md diff --git a/docs/architecture/containerized-lifecycle/Docker-application-lifecycle/index.md b/docs/architecture/containerized-lifecycle/docker-application-lifecycle/index.md similarity index 100% rename from docs/architecture/containerized-lifecycle/Docker-application-lifecycle/index.md rename to docs/architecture/containerized-lifecycle/docker-application-lifecycle/index.md diff --git a/docs/architecture/containerized-lifecycle/Docker-application-lifecycle/media/containers-foundation-for-devops-collaboration/generic-end-to-enddpcker-app-life-cycle.png b/docs/architecture/containerized-lifecycle/docker-application-lifecycle/media/containers-foundation-for-devops-collaboration/generic-end-to-enddpcker-app-life-cycle.png similarity index 100% rename from docs/architecture/containerized-lifecycle/Docker-application-lifecycle/media/containers-foundation-for-devops-collaboration/generic-end-to-enddpcker-app-life-cycle.png rename to docs/architecture/containerized-lifecycle/docker-application-lifecycle/media/containers-foundation-for-devops-collaboration/generic-end-to-enddpcker-app-life-cycle.png diff --git a/docs/architecture/containerized-lifecycle/Docker-application-lifecycle/media/containers-foundation-for-devops-collaboration/persona-workloads-docker-container-lifecycle.png b/docs/architecture/containerized-lifecycle/docker-application-lifecycle/media/containers-foundation-for-devops-collaboration/persona-workloads-docker-container-lifecycle.png similarity index 100% rename from docs/architecture/containerized-lifecycle/Docker-application-lifecycle/media/containers-foundation-for-devops-collaboration/persona-workloads-docker-container-lifecycle.png rename to docs/architecture/containerized-lifecycle/docker-application-lifecycle/media/containers-foundation-for-devops-collaboration/persona-workloads-docker-container-lifecycle.png diff --git a/docs/architecture/containerized-lifecycle/docker-devops-workflow/docker-application-outer-loop-devops-workflow.md b/docs/architecture/containerized-lifecycle/docker-devops-workflow/docker-application-outer-loop-devops-workflow.md index 65bdf3ba7becd..9403afa07ce9a 100644 --- a/docs/architecture/containerized-lifecycle/docker-devops-workflow/docker-application-outer-loop-devops-workflow.md +++ b/docs/architecture/containerized-lifecycle/docker-devops-workflow/docker-application-outer-loop-devops-workflow.md @@ -25,21 +25,21 @@ Even though source-code control (SCC) and source-code management might seem seco The local images, generated by developers, should just be used by them when testing within their own machines. That's why it's critical to have the DevOps pipeline activated from the SCC code. -Azure DevOps Services and Team Foundation Server support Git and Team Foundation Version Control. You can choose between them and use it for an end-to-end Microsoft experience. However, you can also manage your code in external repositories (like GitHub, on-premises Git repositories, or Subversion) and still be able to connect to it and get the code as the starting point for your DevOps CI pipeline. +Azure DevOps Services and Team Foundation Server support Git and Team Foundation Version Control. You can choose between them and use it for an end-to-end Microsoft experience. However, you can also manage your code in external repositories (like GitHub, on-premises Git repositories, or Subversion) and still be able to connect to it and get the code as the starting point for your DevOps CI pipeline. You can also use GitHub Actions for CI/CD pipelines. -## Step 3: Build, CI, Integrate, and Test with Azure DevOps Services and Docker +## Step 3: Build, CI, Integrate, and Test with Azure DevOps Services/GitHub and Docker CI has emerged as a standard for modern software testing and delivery. The Docker solution maintains a clear separation of concerns between the development and operations teams. The immutability of Docker images ensures a repeatable deployment between what's developed, tested through CI, and run in production. Docker Engine deployed across the developer laptops and test infrastructure makes the containers portable across environments. At this point, after you have a version-control system with the correct code submitted, you need a *build service* to pick up the code and run the global build and tests. -The internal workflow for this step (CI, build, test) is about the construction of a CI pipeline consisting of your code repository (Git, etc.), your build server (Azure DevOps Services), Docker Engine, and a Docker Registry. +The internal workflow for this step (CI, build, test) is about the construction of a CI pipeline consisting of your code repository (Git, etc.), your build server (Azure DevOps Services/GitHub), Docker Engine, and a Docker Registry. -You can use Azure DevOps Services as the foundation for building your applications and setting your CI pipeline, and for publishing the built "artifacts" to an "artifacts repository," which is explained in the next step. +You can use Azure DevOps Services as the foundation for building your applications and setting your CI pipeline, and for publishing the built "artifacts" to an "artifacts repository," which is explained in the next step. Alternatively, you can use GitHub to implement the same workflow. -When using Docker for the deployment, the "final artifacts" to be deployed are Docker images with your application or services embedded within them. Those images are pushed or published to a *Docker Registry* (a private repository like the ones you can have in Azure Container Registry, or a public one like Docker Hub Registry, which is commonly used for official base images). +When using Docker for the deployment, the "final artifacts" to be deployed are Docker images with your application or services embedded within them. Those images are pushed or published to a *Docker Registry* (a private repository like the ones you can have in Azure Container Registry, or a public one like Docker Hub Registry or GitHub Container Registry, which is commonly used for official base images). -Here is the basic concept: The CI pipeline will be kicked-off by a commit to an SCC repository like Git. The commit will cause Azure DevOps Services to run a build job within a Docker container and, upon successful completion of that job, push a Docker image to the Docker Registry, as illustrated in Figure 5-2. The first part of the outer loop involves steps 1 to 3, from code, run, debug and validate, then the code repo up to the build and test CI step. +Here is the basic concept: The CI pipeline will be kicked-off by a commit to an SCC repository like Git. The commit will cause Azure DevOps Services/GitHub to run a build job within a Docker container and, upon successful completion of that job, push a Docker image to the Docker Registry, as illustrated in Figure 5-2. The first part of the outer loop involves steps 1 to 3, from code, run, debug and validate, then the code repo up to the build and test CI step. ![Diagram showing the three steps involved in the CI workflow.](./media/docker-application-outer-loop-devops-workflow/continuous-integration-steps.png) @@ -59,7 +59,16 @@ Here are the basic CI workflow steps with Docker and Azure DevOps Services: 6. If the tests are successful, the image is first relabeled to a meaningful name so that you know it's a "blessed build" (like "/1.0.0" or any other label), and then pushed up to your Docker Registry (Docker Hub, Azure Container Registry, DTR, etc.) -### Implementing the CI pipeline with Azure DevOps Services and the Docker extension for Azure DevOps Services +Here are the basic CI workflow steps with Docker and GitHub: + +1. The developer pushes a commit to a GitHub repo. +1. CI is built in, so Actions will trigger base on the event filters. +1. GitHub pulls the SCC repository, including the _Dockerfile_ describing the image, as well as the application and test code. +1. GitHub builds a Docker image and labels it with a build number. +1. GitHub instantiates the Docker container within the provisioned Docker Host, and runs the appropriate tests. +1. If the tests are successful, the image is first relabeled to a meaningful name so that you know it's a "blessed build" (like "/1.0.0" or any other label), and then pushed up to your Docker Registry (Docker Hub, Azure Container Registry, DTR, etc.) + +### Implement a CI pipeline with Azure DevOps Services and the Docker extension for Azure DevOps Services Visual Studio Azure DevOps Services contains Build & Release Templates that you can use in your CI/CD pipeline with which you can build Docker images, push Docker images to an authenticated Docker registry, run Docker images, or run other operations offered by the Docker CLI. It also adds a Docker Compose task that you can use to build, push, and run multi-container Docker applications, or run other operations offered by the Docker Compose CLI, as shown in Figure 5-3. @@ -79,7 +88,7 @@ With these Visual Studio Team Services tasks, a build Linux-Docker Host/VM provi An easy way to create one of these agents is to use Docker to run a container based on the Azure DevOps Services agent Docker image. -> [!INFORMATION] +> [!TIP] > To read more about assembling an Azure DevOps Services Docker CI pipeline and view the walkthroughs, visit these sites: > > - Running a Visual Studio Team Services (Now Azure DevOps Services) agent as a Docker container: \ @@ -91,6 +100,14 @@ With these Visual Studio Team Services tasks, a build Linux-Docker Host/VM provi > - Building a Linux-based Visual Studio Team Service build machine with Docker support: \ > +### Implement a CI pipeline with GitHub Actions + +GitHub Actions allow you to create automation scripts that can build Docker images, push Docker images to an authenticated Docker registry, run Docker images, or run other operations offered by the Docker CLI. + +You can use public Actions (such as [Azure Login](https://github.com/marketplace/actions/azure-login)) and `run` (shell) commands to construct your CI/CD artifacts to Build / Test and Deploy in Azure Service Fabric, Azure Kubernetes Service, and similar offerings. + +With these Actions, a build Linux-Docker Host/VM provisioned in Azure and your preferred Docker registry (Azure Container Registry, Docker Hub, private Docker DTR, or any other Docker registry) you can assemble your Docker CI pipeline in a very consistent way. + ### Integrate, test, and validate multi-container Docker applications Typically, most Docker applications are composed of multiple containers rather than a single container. A good example is a microservices-oriented application for which you would have one container per microservice. But, even without strictly following the microservices approach patterns, it's probable that your Docker application would be composed of multiple containers or services. @@ -123,7 +140,7 @@ Typically, you might want to have your private repositories for your custom imag **Figure 5-4**. Publishing custom images to Docker Registry -In step 3, for building integration and testing (CI) you might publish the resulting docker images to a private or public registry. There are multiple offerings of Docker registries from cloud vendors like Azure Container Registry, Amazon Web Services Container Registry, Google Container Registry, Quay Registry, and so on. +In step 3, for building integration and testing (CI) you might publish the resulting docker images to a private or public registry. There are multiple offerings of Docker registries from cloud vendors like Azure Container Registry, Amazon Web Services Container Registry, Google Container Registry, GitHub Container Registry, Quay Registry, and so on. Using the Docker tasks, you can push a set of service images defined by a `docker-compose.yml` file, with multiple tags, to an authenticated Docker registry (like Azure Container Registry), as shown in Figure 5-5. @@ -131,12 +148,12 @@ Using the Docker tasks, you can push a set of service images defined by a `docke **Figure 5-5**. Using Azure DevOps Services to publishing custom images to a Docker Registry -> [!INFORMATION] +> [!TIP] > For more information about Azure Container Registry, see . ## Step 4: CD, Deploy -The immutability of Docker images ensures a repeatable deployment with what's developed, tested through CI, and run in production. After you have the application Docker images published in your Docker registry (either private or public), you can deploy them to the several environments that you might have (production, QA, staging, etc.) from your CD pipeline by using Azure DevOps Services pipeline tasks or Azure DevOps Services Release Management. +The immutability of Docker images ensures a repeatable deployment with what's developed, tested through CI, and run in production. After you have the application Docker images published in your Docker registry (either private or public), you can deploy them to the several environments that you might have (production, QA, staging, etc.) from your CD pipeline by using Azure DevOps Services pipeline tasks, Azure DevOps Services Release Management or GitHub Actions. However, at this point it depends on what kind of Docker application you're deploying. Deploying a simple application (from a composition and deployment point of view) like a monolithic application comprising a few containers or services and deployed to a few servers or VMs is different from deploying a more complex application like a microservices-oriented application with hyperscale capabilities. These two scenarios are explained in the following sections. @@ -148,17 +165,17 @@ Let's look first at the less-complex scenario: deploying to simple Docker hosts **Figure 5-6**. Deploying application containers to simple Docker host environments registry -Figure 5-7 highlights how you can connect your build CI to QA/test environments via Azure DevOps Services by clicking Docker Compose in the Add Task dialog box. However, when deploying to staging or production environments, you would usually use Release Management features handling multiple environments (like QA, staging, and production). If you're deploying to single Docker hosts, it is using the Azure DevOps Services "Docker Compose" task (which is invoking the `docker-compose up` command under the hood). If you're deploying to Azure Kubernetes Service (AKS), it uses the Docker Deployment task, as explained in the section that follows. +Figure 5-7 highlights how you can connect your build CI to QA/test environments via Azure DevOps Services by clicking Docker Compose in the Add Task dialog box. However, when deploying to staging or production environments, you would usually use Release Management features handling multiple environments (like QA, staging, and production). If you're deploying to single Docker hosts, it is using the Azure DevOps Services "Docker Compose" task (which is invoking the `docker-compose up` command under the hood). If you're deploying to Azure Kubernetes Service (AKS), it uses the Docker Deployment task, as explained in the section that follows. Similar steps can be built for deployment using GitHub Actions. ![Screenshot showing Add tasks dialog of the Docker Compose task.](./media/docker-application-outer-loop-devops-workflow/add-tasks-docker-compose.png) -**Figure 5-7**. Adding a Docker Compose task in an Azure DevOps Services pipeline +**Figure 5-7**. Adding a Docker Compose task in an Azure DevOps Services pipeline or GitHub workflow When you create a release in Azure DevOps Services, it takes a set of input artifacts. These artifacts are intended to be immutable for the lifetime of the release, across all environments. When you introduce containers, the input artifacts identify images in a registry to deploy. Depending on how these images are identified, they are not guaranteed to remain the same throughout the duration of the release, the most obvious case being when you reference `myimage:latest` from a `docker-compose` file. -The Azure DevOps Services templates give you the ability to generate build artifacts that contain specific registry image digests that are guaranteed to uniquely identify the same image binary. These are what you really want to use as input to a release. +The Azure DevOps Services templates give you the ability to generate build artifacts that contain specific registry image digests that are guaranteed to uniquely identify the same image binary. These are what you really want to use as input to a release. You can invoke `docker-compose` in a `run` step inside GitHub Actions to accomplish the same goal. -### Managing releases to Docker environments by using Azure DevOps Services Release Management +### Managing releases to Docker environments by using Azure DevOps Services Release Management or GitHub Actions Through the Azure DevOps Services templates, you can build a new image, publish it to a Docker registry, run it on Linux or Windows hosts, and use commands such as `docker-compose` to deploy multiple containers as an entire application, all through the Azure DevOps Services Release Management capabilities intended for multiple environments, as shown in Figure 5-8. @@ -168,13 +185,15 @@ Through the Azure DevOps Services templates, you can build a new image, publish However, keep in mind that the scenario shown in Figure 5-6 and implemented in Figure 5-8 is a simple one (it's deploying to single Docker hosts and VMs, and there will be a single container or instance per image) and probably should be used only for development or test scenarios. In most enterprise production scenarios, you would want to have High Availability (HA) and easy-to-manage scalability by load balancing across multiple nodes, servers, and VMs, plus "intelligent failovers" so if a server or node fails, its services and containers will be moved to another host server or VM. In that case, you need more advanced technologies such as container clusters, orchestrators, and schedulers. Thus, the way to deploy to those clusters is by handling the advanced scenarios explained in the next section. +GitHub Actions can be used in the same manner, including the use of [environments](https://docs.github.com/actions/reference/environments) for approvals. + ### Deploying Docker applications to Docker clusters The nature of distributed applications requires compute resources that are also distributed. To have production-scale capabilities, you need to have clustering capabilities that provide high scalability and high availability based on pooled resources. You could deploy containers manually to those clusters from a CLI tool or a web UI, but you should reserve that kind of manual work to spot deployment testing or management purposes like scaling-out or monitoring. -From a CD point of view, and Azure DevOps Services specifically, you can run specially made deployment tasks from your Azure DevOps Services Release Management environments that will deploy your containerized applications to distributed clusters in Container Service, as illustrated in Figure 5-9. +From a CD point of view, you can use Azure DevOps Services or GitHub Actions to run specially made deployment tasks from your environments that will deploy your containerized applications to distributed clusters in Container Service, as illustrated in Figure 5-9. ![Diagram showing the CD deploy step deploying to orchestrators.](./media/docker-application-outer-loop-devops-workflow/cd-deploy-to-orchestrators.png) @@ -192,9 +211,12 @@ Figure 5-11 demonstrates how you can edit the Deploy to Kubernetes task with the **Figure 5-11**. Docker Deploy task definition deploying to ACS DC/OS -> [!INFORMATION] +> [!TIP] > To read more about the CD pipeline with Azure DevOps Services and Docker, visit +> [!TIP] +> To see GitHub Actions workflows for CI, visit . For a walkthrough of GitHub Actions performing deployment to an Azure Kubernetes environment, visit . + ## Step 5: Run and manage Because running and managing applications at enterprise-production level is a major subject in and of itself, and due to the type of operations and people working at that level (IT operations) as well as the large scope of this area, the entire next chapter is devoted to explaining it. diff --git a/docs/architecture/containerized-lifecycle/docker-devops-workflow/index.md b/docs/architecture/containerized-lifecycle/docker-devops-workflow/index.md index c678c2db4f06c..1305c1fd5425a 100644 --- a/docs/architecture/containerized-lifecycle/docker-devops-workflow/index.md +++ b/docs/architecture/containerized-lifecycle/docker-devops-workflow/index.md @@ -6,23 +6,25 @@ ms.date: 01/06/2021 # Docker application DevOps workflow with Microsoft tools -*Microsoft Visual Studio, Azure DevOps Services, Team Foundation Server, and Azure Monitor provide a comprehensive ecosystem for development and IT operations that give your team the tools to manage projects and rapidly build, test, and deploy containerized applications.* +*Microsoft Visual Studio, Azure DevOps Services and/or GitHub, Team Foundation Server, and Azure Monitor provide a comprehensive ecosystem for development and IT operations that give your team the tools to manage projects and rapidly build, test, and deploy containerized applications.* -With Visual Studio and Azure DevOps Services in the cloud, along with Team Foundation Server on-premises, development teams can productively build, test, and release containerized applications that target either Windows or Linux. +Teams can choose which tools and platforms they want to use for end to end DevOps. With Visual Studio and Azure DevOps Services in the cloud, along with Team Foundation Server on-premises, development teams can productively build, test, and release containerized applications that target either Windows or Linux. Alternatively, teams can also use Visual Studio Code and GitHub. Teams can even use combinations: for example, storing source code in GitHub and using Azure Boards for work item tracking and Azure Pipelines for CI/CD. -Microsoft tools can automate the pipeline for specific implementations of containerized applications—Docker, .NET, or any combination with other platforms—from global builds and Continuous Integration (CI) and tests with Azure DevOps Services or Team Foundation Server, to Continuous Deployment (CD) to Docker environments (Development, Staging, Production), and to transmit analytics information about the services to the development team through Azure Monitor. Every code commit can initiate a build (CI) and automatically deploy the services to specific containerized environments (CD). +Microsoft tools can automate the pipeline for specific implementations of containerized applications—Docker, .NET, or any combination with other platforms—from global builds and Continuous Integration (CI) and tests with Azure DevOps Services, Team Foundation Server or GitHub, to Continuous Deployment (CD) to Docker environments (Development, Staging, Production), and to transmit analytics information about the services to the development team through Azure Monitor. Every code commit can initiate a build (CI) and automatically deploy the services to specific containerized environments (CD). Developers and testers can easily and quickly provision production-like development and test environments based on Docker by using templates in Microsoft Azure. -The complexity of containerized application development increases steadily depending on the business complexity and scalability needs. A good example of this complexity are applications based on microservices architectures. To succeed in such an environment, your project must automate the entire life cycle—not only the build and deployment, but it also must manage versions along with the collection of telemetry. Azure DevOps Services and Azure offer the following capabilities: +The complexity of containerized application development increases steadily depending on the business complexity and scalability needs. A good example of this complexity are applications based on microservices architectures. To succeed in such an environment, your project must automate the entire life cycle—not only the build and deployment, but it also must manage versions along with the collection of telemetry. Azure DevOps Services, GitHub and Azure offer the following capabilities: - Azure DevOps Services/Team Foundation Server source code management (based on Git or Team Foundation Version Control), Agile planning (Agile, Scrum, and CMMI are supported), CI, release management, and other tools for Agile teams. - Azure DevOps Services and Team Foundation Server include a powerful and growing ecosystem of first and third-party extensions with which you easily can construct a CI, build, test, delivery, and release management pipeline for microservices. -- Run automated tests as part of your build pipeline in Azure DevOps Services. +- GitHub or GitHub Enterprise Server offer similar capabilities, with source control based on Git, Projects and Issues for project tracking, GitHub Actions for automating workflows including CI/CD, and GitHub Advanced Security for dependency, secret and vulnerability scanning. -- Azure DevOps Services can tighten the DevOps life cycle with delivery to multiple environments, not just for production environments, but also for testing, including A/B experimentation, [canary releases](https://martinfowler.com/bliki/CanaryRelease.html), and so on. +- Run automated tests as part of your build pipeline in Azure DevOps Services or through GitHub Actions + +- Azure DevOps Services/GitHub can tighten the DevOps life cycle with delivery to multiple environments, not just for production environments, but also for testing, including A/B experimentation, [canary releases](https://martinfowler.com/bliki/CanaryRelease.html), and so on. - Organizations easily can provision Docker containers from private images stored in Azure Container Registry along with any dependency on Azure components (Data, PaaS, etc.) using Azure Resource Manager templates with tools they're already comfortable with. diff --git a/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/cd-deploy-to-orchestrators.png b/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/cd-deploy-to-orchestrators.png index ced28ef62447f..96f7c13e70c9c 100644 Binary files a/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/cd-deploy-to-orchestrators.png and b/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/cd-deploy-to-orchestrators.png differ diff --git a/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/continuous-integration-steps.png b/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/continuous-integration-steps.png index afe0450060b06..d576c9fed054c 100644 Binary files a/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/continuous-integration-steps.png and b/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/continuous-integration-steps.png differ diff --git a/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/deploy-app-containers-to-docker-host-environments.png b/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/deploy-app-containers-to-docker-host-environments.png index c27d237a5d1fe..9e6d6e0b57185 100644 Binary files a/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/deploy-app-containers-to-docker-host-environments.png and b/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/deploy-app-containers-to-docker-host-environments.png differ diff --git a/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/docker-push-custom-images.png b/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/docker-push-custom-images.png index 0bb48f670eb68..7f743090cfac7 100644 Binary files a/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/docker-push-custom-images.png and b/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/docker-push-custom-images.png differ diff --git a/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/overview-dev-ops-outter-loop-workflow.png b/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/overview-dev-ops-outter-loop-workflow.png index e9d63cba79d9b..9d5714b3c87ff 100644 Binary files a/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/overview-dev-ops-outter-loop-workflow.png and b/docs/architecture/containerized-lifecycle/docker-devops-workflow/media/docker-application-outer-loop-devops-workflow/overview-dev-ops-outter-loop-workflow.png differ diff --git a/docs/architecture/containerized-lifecycle/index.md b/docs/architecture/containerized-lifecycle/index.md index bdf60813abd04..f3e95dc29caae 100644 --- a/docs/architecture/containerized-lifecycle/index.md +++ b/docs/architecture/containerized-lifecycle/index.md @@ -7,7 +7,7 @@ ms.date: 01/06/2021 ![Book cover](./media/devops-book-cover-large-we.png) -**EDITION v5.0** - Updated to ASP.NET Core 5.0 +**EDITION v5.0.1** - Updated to ASP.NET Core 5.0 Refer [changelog](https://aka.ms/DockerLifecycleEbookChangelog) for the book updates and community contributions. @@ -52,6 +52,8 @@ Participants and reviewers: > **Miguel Veloso**, Software Development Engineer at Plain Concepts > > **Sumit Ghosh**, Principal Consultant at Neudesic +> +> **Colin Dembovsky**, DevOps Practice Lead, Cognizant Microsoft Business Group ## Copyright diff --git a/docs/architecture/containerized-lifecycle/media/devops-book-cover-large-we.png b/docs/architecture/containerized-lifecycle/media/devops-book-cover-large-we.png index 10c30876b1d56..8181150fbb236 100644 Binary files a/docs/architecture/containerized-lifecycle/media/devops-book-cover-large-we.png and b/docs/architecture/containerized-lifecycle/media/devops-book-cover-large-we.png differ diff --git a/docs/architecture/dapr-for-net-developers/bindings.md b/docs/architecture/dapr-for-net-developers/bindings.md index 8a2b99e91c2ad..cc3241e14f48c 100644 --- a/docs/architecture/dapr-for-net-developers/bindings.md +++ b/docs/architecture/dapr-for-net-developers/bindings.md @@ -2,7 +2,7 @@ title: The Dapr bindings building block description: A description of the bindings building block, its features, benefits, and how to apply it author: edwinvw -ms.date: 02/07/2021 +ms.date: 02/17/2021 --- # The Dapr bindings building block diff --git a/docs/architecture/dapr-for-net-developers/dapr-at-20000-feet.md b/docs/architecture/dapr-for-net-developers/dapr-at-20000-feet.md index ac38efebff671..a963356f22a50 100644 --- a/docs/architecture/dapr-for-net-developers/dapr-at-20000-feet.md +++ b/docs/architecture/dapr-for-net-developers/dapr-at-20000-feet.md @@ -2,7 +2,7 @@ title: Dapr at 20,000 feet description: A high-level overview of what dapr is, what it does, and how it works. author: robvet -ms.date: 02/07/2021 +ms.date: 02/17/2021 --- # Dapr at 20,000 feet @@ -21,14 +21,16 @@ Imagine flying in a jet at 20,000 feet. You look out the window and see the land Dapr addresses a large challenge inherent in modern distributed applications: **Complexity**. -Through an architecture of pluggable components, Dapr greatly simplifies the plumbing behind distributed applications. It provides a **dynamic glue** that binds your application with infrastructure capabilities from the Dapr runtime. For example, your application may require a state store. You could write custom code to target Redis Cache and inject it into your service at runtime. However, Dapr simplifies your experience by providing a distributed cache capability out-of-the-box. Your service invokes a Dapr **building block** that dynamically binds to Redis Cache **component** via a Dapr **configuration**. With this model, your service delegates the call to Dapr, which calls Redis on your behalf. Your service has no SDK, library, or direct reference to Redis. You code against the common Dapr state management API, not the Redis Cache API. +Through an architecture of pluggable components, Dapr greatly simplifies the plumbing behind distributed applications. It provides a **dynamic glue** that binds your application with infrastructure capabilities from the Dapr runtime. + +Consider a requirement to make one of your services stateful? What would be your design. You could write custom code that targets a state store such as Redis Cache. However, Dapr provides state management capabilities out-of-the-box. Your service invokes the Dapr state management **building block** that dynamically binds to a state store **component** via a Dapr **component configuration** yaml file. Dapr ships with several pre-built state store components, including Redis. With this model, your service delegates state management to the Dapr runtime. Your service has no SDK, library, or direct reference to the underlying component. You can even change state stores, say, from Redis to MySQL or Cassandra, with no code changes. Figure 2-1 shows Dapr from 20,000 feet. ![Dapr at 20,000 feet](./media/dapr-at-20000-feet/dapr-high-level.png) **Figure 2-1**. Dapr at 20,000 feet. -In the top row of the figure, note how Dapr provides language-specific SDKs for popular development platforms. Dapr v 1.0 includes supports Go, Node.js, Python, .NET, Java, and JavaScript. This book focuses on the Dapr .NET SDK, which also provides direct support for ASP.NET Core integration. +In the top row of the figure, note how Dapr provides language-specific SDKs for popular development platforms. Dapr v1.0 includes support for Go, Node.js, Python, .NET, Java, and JavaScript. This book focuses on the Dapr .NET SDK, which also provides direct support for ASP.NET Core integration. While language-specific SDKs enhance the developer experience, Dapr is platform agnostic. Under the hood, Dapr's programming model exposes capabilities through standard HTTP/gRPC communication protocols. Any programming platform can call Dapr via its native HTTP and gRPC APIs. @@ -150,7 +152,6 @@ At the time of this writing, the following component types are provided by Dapr: | [Bindings](https://github.com/dapr/components-contrib/tree/master/bindings) | Provides a uniform interface to trigger application events from external systems and invoke external systems with optional data payloads. | | [Middleware](https://github.com/dapr/components-contrib/tree/master/middleware) | Allows custom middleware to plug into the request processing pipeline and invoke additional actions on a request or response. | | [Secret stores](https://github.com/dapr/components-contrib/tree/master/secretstores) | Provides a uniform interface to interact with external secret stores, including cloud, edge, commercial, open-source services. | -| [Tracing exporters](https://github.com/dapr/components-contrib/tree/master/exporters) | Provides a uniform interface to open telemetry wrappers. | As the jet completes its fly over of Dapr, you look back once more and can see how it connects together. @@ -204,6 +205,8 @@ gRPC is a modern, high-performance framework that evolves the age-old [remote pr - Bidirectional full-duplex communication for sending both client requests and server responses simultaneously. - Built-in streaming enabling requests and responses to asynchronously stream large data sets. +To learn more, check out the [gRPC overview](../cloud-native/grpc.md#what-is-grpc) from the [Architecting Cloud-Native .NET Apps for Azure](../cloud-native/index.md) eBook. + ## Dapr and service meshes Service mesh is another rapidly evolving technology for distributed applications. @@ -216,7 +219,7 @@ Figure 2-8 shows an application that implements service mesh technology. **Figure 2-8**. Service mesh with a side car. -The previous figure shows how messages are intercepted by a proxy that runs alongside each service. Each proxy can be configured with traffic rules specific to the service. It understands messages and can route them across your services and the outside world. +The previous figure shows how messages are intercepted by a sidecar proxy that runs alongside each service. Each proxy can be configured with traffic rules specific to the service. It understands messages and can route them across your services and the outside world. So the question becomes, "Is Dapr a service mesh?". @@ -230,7 +233,7 @@ Figure 2-9 shows an application that implements both Dapr and service mesh techn **Figure 2-9**. Dapr and service mesh together. -In the book, [Learning Dapr](https://www.amazon.com/Learning-Dapr-Building-Distributed-Applications/dp/1492072427/ref=sr_1_1?dchild=1&keywords=dapr&qid=1604794794&sr=8-1), authors Haishi Bai and Yaron Schneider, cover the integration of Dapr and service mesh. +The [Dapr online documentation](https://docs.dapr.io/concepts/faq/#networking-and-service-meshes) cover Dapr and service mesh integration. ## Summary diff --git a/docs/architecture/dapr-for-net-developers/foreword.md b/docs/architecture/dapr-for-net-developers/foreword.md index df0fdb4e6d3ee..635ba4dcf458f 100644 --- a/docs/architecture/dapr-for-net-developers/foreword.md +++ b/docs/architecture/dapr-for-net-developers/foreword.md @@ -2,7 +2,7 @@ title: Foreword description: A foreword to Dapr for .NET Developers by Mark Russinovich author: markrussinovich -ms.date: 02/14/2021 +ms.date: 02/17/2021 --- # Foreword diff --git a/docs/architecture/dapr-for-net-developers/getting-started.md b/docs/architecture/dapr-for-net-developers/getting-started.md index 2b00e6b36c91c..2bf91c5f6d06f 100644 --- a/docs/architecture/dapr-for-net-developers/getting-started.md +++ b/docs/architecture/dapr-for-net-developers/getting-started.md @@ -1,7 +1,7 @@ --- title: Get started with Dapr description: A guide for preparing your local development environment and building your first .NET applications with Dapr. -author: amolenk +author: amolenk ms.date: 02/25/2021 --- @@ -250,7 +250,7 @@ Now, you'll configure communication between the services using Dapr [service inv } ``` - The call to `AddDapr` registers the `DaprClient` class with the ASP.NET Core dependency injection system. You'll use the `DaprClient` class later on to communicate with the Dapr sidecar. + The call to `AddDapr` registers the `DaprClient` class with the ASP.NET Core dependency injection system. With the client registered, you can now inject an instance of `DaprClient` into your service code to communicate with the Dapr sidecar, building blocks, and components. 1. Add a new C# class file named *WeatherForecast* to the `DaprFrontEnd` project: @@ -416,6 +416,7 @@ In the final part of this example, you'll add container support and run the solu FROM mcr.microsoft.com/dotnet/aspnet:3.1 AS base WORKDIR /app EXPOSE 80 + EXPOSE 443 FROM mcr.microsoft.com/dotnet/sdk:3.1 AS build WORKDIR /src @@ -457,7 +458,7 @@ In the final part of this example, you'll add container support and run the solu ```yaml version: '3.4' - + services: daprfrontend: image: ${DOCKER_REGISTRY-}daprfrontend @@ -469,7 +470,7 @@ In the final part of this example, you'll add container support and run the solu daprfrontend-dapr: image: "daprio/daprd:latest" - command: [ "./daprd", "-app-id", "daprfrontend", "-app-port", "80" ] + command: [ "./daprd", "-app-id", "daprfrontend", "-app-port", "443", "-app-ssl" ] depends_on: - daprfrontend network_mode: "service:daprfrontend" @@ -484,9 +485,9 @@ In the final part of this example, you'll add container support and run the solu daprbackend-dapr: image: "daprio/daprd:latest" - command: [ "./daprd", "-app-id", "daprbackend", "-app-port", "80" ] + command: [ "./daprd", "-app-id", "daprbackend", "-app-port", "443", "-app-ssl" ] depends_on: - - daprfrontend + - daprbackend network_mode: "service:daprbackend" ``` diff --git a/docs/architecture/dapr-for-net-developers/index.md b/docs/architecture/dapr-for-net-developers/index.md index ed1576cf85175..a75401771e69a 100644 --- a/docs/architecture/dapr-for-net-developers/index.md +++ b/docs/architecture/dapr-for-net-developers/index.md @@ -2,7 +2,7 @@ title: Dapr for .NET Developers description: A guide for .NET developers to understand and leverage the full power of Microsoft's open source Distributed Application Runtime. author: robvet -ms.date: 02/07/2021 +ms.date: 02/17/2021 --- # Dapr for .NET Developers diff --git a/docs/architecture/dapr-for-net-developers/media/dapr-at-20000-feet/building-blocks.png b/docs/architecture/dapr-for-net-developers/media/dapr-at-20000-feet/building-blocks.png index 556b2720e0e88..65692c84e7e3d 100644 Binary files a/docs/architecture/dapr-for-net-developers/media/dapr-at-20000-feet/building-blocks.png and b/docs/architecture/dapr-for-net-developers/media/dapr-at-20000-feet/building-blocks.png differ diff --git a/docs/architecture/dapr-for-net-developers/observability.md b/docs/architecture/dapr-for-net-developers/observability.md index 2552e43397681..f724ba7ac91f2 100644 --- a/docs/architecture/dapr-for-net-developers/observability.md +++ b/docs/architecture/dapr-for-net-developers/observability.md @@ -2,7 +2,7 @@ title: The Dapr observability building block description: A description of the observability building block, its features, benefits, and how to apply it author: edwinvw -ms.date: 02/07/2021 +ms.date: 02/17/2021 ms.reviewer: robvet --- @@ -35,7 +35,7 @@ As Dapr abstracts away the plumbing, the application is unaware of how observabi Dapr's [sidecar architecture](dapr-at-20000-feet.md#sidecar-architecture) enables built-in observability features. As services communicate, Dapr sidecars intercept the traffic and extract tracing, metrics, and logging information. Telemetry is published in an open standards format. By default, Dapr supports [OpenTelemetry](https://opentelemetry.io/) and [Zipkin](https://zipkin.io/). -Dapr provides [collectors](https://docs.dapr.io/operations/monitoring/open-telemetry-collector/) that can publish telemetry to different back-end monitoring tools. These tools present Dapr telemetry for analysis and querying. Figure 9-1 shows the Dapr observability architecture: +Dapr provides [collectors](https://docs.dapr.io/operations/monitoring/tracing/open-telemetry-collector/) that can publish telemetry to different back-end monitoring tools. These tools present Dapr telemetry for analysis and querying. Figure 9-1 shows the Dapr observability architecture: ![Dapr observability architecture](media/observability/observability-architecture.png) @@ -195,7 +195,7 @@ spec: ##### Inspect the telemetry in Zipkin -Once the application is started, the Dapr sidecars will emit telemetry to the Zipkin server. To inspect this telemetry, point a web-browser to . You'll see the Zipkin web front end: +Once the application is started, the Dapr sidecars will emit telemetry to the Zipkin server. To inspect this telemetry, point a web-browser to `http://localhost:32411`. You'll see the Zipkin web front end: ![The Zipkin start page](media/observability/zipkin.png) @@ -280,7 +280,7 @@ Dapr generates a large set of metrics for Dapr system services and its runtime. | dapr_http_server_request_count | Runtime | Number of HTTP requests started in an HTTP server. | | dapr_http/client/sent_bytes | Runtime | Total bytes sent in request body (not including headers) by an HTTP client. | -For more information on available metrics, see the [Dapr metrics documentation](https://docs.dapr.io/developing-applications/building-blocks/observability/metrics). +For more information on available metrics, see the [Dapr metrics documentation](https://docs.dapr.io/operations/monitoring/metrics/). #### Configure Dapr metrics @@ -307,7 +307,7 @@ With the Prometheus scraper collecting and publishing metrics into the monitorin ![Grafana dashboard displaying Dapr system services metrics](media/observability/grafana-sample.png) -The Dapr documentation includes a [tutorial for installing Prometheus and Grafana](https://docs.dapr.io/operations/monitoring/grafana/). +The Dapr documentation includes a [tutorial for installing Prometheus and Grafana](https://docs.dapr.io/operations/monitoring/metrics/grafana/). ### Logging @@ -376,7 +376,7 @@ helm install dapr dapr/dapr --namespace dapr-system --set global.logAsJson=true #### Collect logs -The logs emitted by Dapr can be fed into a monitoring back end for analysis. A log collector is a component that collects logs from a system and sends them to a monitoring back end. A popular log collector is [Fluentd](https://www.fluentd.org/). Check out the [How-To: Set up Fluentd, Elastic search and Kibana in Kubernetes](https://docs.dapr.io/operations/monitoring/fluentd/) in the Dapr documentation. This article contains instructions for setting up Fluentd as log collector and the [ELK Stack](https://www.elastic.co/elastic-stack) (Elastic Search and Kibana) as a monitoring back end. +The logs emitted by Dapr can be fed into a monitoring back end for analysis. A log collector is a component that collects logs from a system and sends them to a monitoring back end. A popular log collector is [Fluentd](https://www.fluentd.org/). Check out the [How-To: Set up Fluentd, Elastic search and Kibana in Kubernetes](https://docs.dapr.io/operations/monitoring/logging/fluentd/) in the Dapr documentation. This article contains instructions for setting up Fluentd as log collector and the [ELK Stack](https://www.elastic.co/elastic-stack) (Elastic Search and Kibana) as a monitoring back end. ### Health status diff --git a/docs/architecture/dapr-for-net-developers/publish-subscribe.md b/docs/architecture/dapr-for-net-developers/publish-subscribe.md index 6ad0af17e0b6c..4748a8e27ee22 100644 --- a/docs/architecture/dapr-for-net-developers/publish-subscribe.md +++ b/docs/architecture/dapr-for-net-developers/publish-subscribe.md @@ -2,7 +2,7 @@ title: The Dapr publish & subscribe building block description: A description of the Dapr publish & subscribe building-block and how to apply it author: edwinvw -ms.date: 02/07/2021 +ms.date: 02/17/2021 --- # The Dapr publish & subscribe building block @@ -288,7 +288,7 @@ You have to specify several elements with every subscription: ## Reference application: eShopOnDapr -The accompanying [eShopOnDapr](https://github.com/dotnet-architecture/eShopOnDapr) app provides an end-to-end reference architecture for constructing a microservices application implementing Dapr. eShopOnDapr is an evolution of the widely popular [eShopOnContainers](https://github.com/dotnet-architecture/eShopOnContainer) app, created several years ago. Both versions use the pub/sub pattern for communicating [integration events](https://devblogs.microsoft.com/cesardelatorre/domain-events-vs-integration-events-in-domain-driven-design-and-microservices-architectures/#integration-events) across microservices. Integration events include: +The accompanying [eShopOnDapr](https://github.com/dotnet-architecture/eShopOnDapr) app provides an end-to-end reference architecture for constructing a microservices application implementing Dapr. eShopOnDapr is an evolution of the widely popular [eShopOnContainers](https://github.com/dotnet-architecture/eShopOnContainers) app, created several years ago. Both versions use the pub/sub pattern for communicating [integration events](https://devblogs.microsoft.com/cesardelatorre/domain-events-vs-integration-events-in-domain-driven-design-and-microservices-architectures/#integration-events) across microservices. Integration events include: - When a user checks-out a shopping basket. - When a payment for an order has succeeded. diff --git a/docs/architecture/dapr-for-net-developers/reference-application.md b/docs/architecture/dapr-for-net-developers/reference-application.md index 2c8bd58def81c..6c3c6e3fad83a 100644 --- a/docs/architecture/dapr-for-net-developers/reference-application.md +++ b/docs/architecture/dapr-for-net-developers/reference-application.md @@ -2,7 +2,7 @@ title: Introduction to the eShopOnDapr reference application description: An overview of the eShopOnDapr reference application and its history. author: amolenk -ms.date: 02/07/2021 +ms.date: 02/17/2021 --- # Dapr reference application @@ -114,9 +114,9 @@ In this chapter, you're introduced to the eShopOnDapr reference application. It' ### References -- [eShopOnDapr](https://github.com/dotnet-architecture/eShopOnDapr) +- [eShopOnDapr on GitHub](https://github.com/dotnet-architecture/eShopOnDapr) -- [eShopOnContainers](https://github.com/dotnet-architecture/eShopOnContainers) +- [eShopOnContainers on GitHub](https://github.com/dotnet-architecture/eShopOnContainers) - [.NET Microservices for Containerized .NET Applications](https://dotnet.microsoft.com/download/e-book/microservices-architecture/pdf) diff --git a/docs/architecture/dapr-for-net-developers/secrets.md b/docs/architecture/dapr-for-net-developers/secrets.md index e1d02bca6d234..b2f4521d2527a 100644 --- a/docs/architecture/dapr-for-net-developers/secrets.md +++ b/docs/architecture/dapr-for-net-developers/secrets.md @@ -2,7 +2,7 @@ title: The Dapr secrets building block description: A description of the secrets building block, its features, benefits, and how to apply it author: edwinvw -ms.date: 02/07/2021 +ms.date: 02/17/2021 --- # The Dapr secrets building block diff --git a/docs/architecture/dapr-for-net-developers/service-invocation.md b/docs/architecture/dapr-for-net-developers/service-invocation.md index d806c4a6e447a..3a6376ae8eb5c 100644 --- a/docs/architecture/dapr-for-net-developers/service-invocation.md +++ b/docs/architecture/dapr-for-net-developers/service-invocation.md @@ -2,7 +2,7 @@ title: The Dapr service invocation building block description: A description of the service invocation building block, its features, benefits, and how to apply it author: amolenk -ms.date: 02/07/2021 +ms.date: 02/17/2021 --- # The Dapr service invocation building block diff --git a/docs/architecture/dapr-for-net-developers/state-management.md b/docs/architecture/dapr-for-net-developers/state-management.md index e756b32bf7a75..ba6b423ea6dd1 100644 --- a/docs/architecture/dapr-for-net-developers/state-management.md +++ b/docs/architecture/dapr-for-net-developers/state-management.md @@ -2,7 +2,7 @@ title: The Dapr state management building block description: A description of the state management building block, its features, benefits, and how to apply it. author: amolenk -ms.date: 02/07/2021 +ms.date: 02/17/2021 ms.reviewer: robvet --- diff --git a/docs/architecture/dapr-for-net-developers/summary.md b/docs/architecture/dapr-for-net-developers/summary.md index 68874f9611448..a2ec5f4c803f8 100644 --- a/docs/architecture/dapr-for-net-developers/summary.md +++ b/docs/architecture/dapr-for-net-developers/summary.md @@ -1,7 +1,7 @@ --- title: Summary and the road ahead description: A summary of key Dapr conclusions and a look at the road ahead. -ms.date: 02/04/2021 +ms.date: 02/17/2021 author: robvet --- diff --git a/docs/architecture/dapr-for-net-developers/the-world-is-distributed.md b/docs/architecture/dapr-for-net-developers/the-world-is-distributed.md index a065b99ca1c15..61cbce2c09172 100644 --- a/docs/architecture/dapr-for-net-developers/the-world-is-distributed.md +++ b/docs/architecture/dapr-for-net-developers/the-world-is-distributed.md @@ -2,7 +2,7 @@ title: The world is distributed description: The benefits and challenges of distributed applications with a look at monolithic and SOA approaches. author: robvet -ms.date: 02/07/2021 +ms.date: 02/17/2021 --- # The world is distributed diff --git a/docs/architecture/devops-for-aspnet-developers/actions-build.md b/docs/architecture/devops-for-aspnet-developers/actions-build.md new file mode 100644 index 0000000000000..cd6eb2b82124d --- /dev/null +++ b/docs/architecture/devops-for-aspnet-developers/actions-build.md @@ -0,0 +1,205 @@ +--- +title: DevOps with .NET and GitHub Actions - Build a .NET Web App +description: Start your journey of DevOps with .NET and GitHub Actions by building a .NET web app +author: colindembovsky +ms.date: 03/04/2021 +--- +# Build a .NET web app using GitHub Actions + +[GitHub Actions](https://github.com/features/actions) allow you to automate workflows in response to events that are triggered in GitHub. A common workflow is Continuous Integration (CI), but Actions can automate other processes. For example, sending welcome emails when people join a repository. + +To explore moving code to the cloud, you'll build a GitHub Actions workflow file. The workflow file will be used for the Simple Feed Reader app you've already deployed to Azure App Service. + +In this article, you will: +> [!div class="checklist"] +> +> * Learn the basic structure of a GitHub Action workflow YAML file. +> * Use a template to create a basic build workflow that builds the .NET app and executes unit tests. +> * Publish the compiled app so that it's ready for deployment. + +## Workflow structure + +Workflows are defined in YAML files, and contain several common nodes: + +- a `name` +- a trigger, defined by an `on` section +- one or more `job` sections composed of one or more `steps` +- optional attributes such as `environment` variables + +Jobs are run on *runners*. You can use *hosted runners*, which are spun up by GitHub during the workflow and then thrown away. Hosted runners are great because you don't have to maintain your own build infrastructure. For workflows that require a specific build environment, or for running workflows on a private network, you can also use *private* runners. To create a private runner, install the runner on any machine that supports .NET. + +Each `job` will specify what runner GitHub should use to execute the `steps`. You can also specify dependencies between jobs using the `needs` attribute. Deployment jobs can also specify an `environment` to target. + +The `steps` node can be as easy as inline commands, or they can be actions. Most CI workflows will have a combination of `run` steps (for executing scripts) and actions. Individual actions are pulled into the workflow by referencing the GitHub Action repository (and optionally a tag or commit hash for specific versions) and specifying any parameters using the `with` keyword. + +> [!TIP] +> For more information, see [GitHub Actions YAML syntax](https://docs.github.com/actions/reference/workflow-syntax-for-github-actions). + +## Create a basic build workflow + +A primary principle of effective DevOps is to "build once, and deploy many times". You'll start by creating a workflow to build a basic .NET app. In the next step, you'll publish the output to prepare for deployment. + +1. Navigate to your GitHub repository and select the **Actions** tab. +1. GitHub detects that there's .NET code in the repository and suggests a .NET workflow template. Select **Set up this workflow** to create a new YAML workflow file: + + ![Creating a new workflow](./media/actions/build/new-action.jpg) + + **Figure 1**: Creating a new workflow. + +1. Commit the file onto the `main` branch. Since you've defined a trigger condition for *commits to main*, this commit should trigger the workflow to run. + + ![Commit the YAML file](./media/actions/build/commit-workflow.jpg) + + **Figure 2**: Commit the YAML file. + +1. Select the **Actions** tab again. You should see a running workflow. Once the workflow has completed, you should see a successful run. + + ![Successful build view](./media/actions/build/build-action-success.jpg) + + **Figure 3**: Successful build view. + +1. Opening the logs, you can see that the .NET build succeeded and the tests ran and passed. + + ![Checking the logs](./media/actions/build/build-action-success-logs.jpg) + + **Figure 4**: Checking the logs. + +> [!NOTE] +> If any of the tests fail, the workflow will fail. + +## Dissect the workflow file + +Let's examine the workflow YAML file you have so far: + +```yml +name: .NET + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + - name: Setup .NET + uses: actions/setup-dotnet@v1 + with: + dotnet-version: 5.0.x + - name: Restore dependencies + run: dotnet restore + - name: Build + run: dotnet build --no-restore + - name: Test + run: dotnet test --no-build --verbosity normal +``` + +Notice the following things: + +1. There's a `name` that names the workflow. +1. The `on` object specifies when this workflow should run. This workflow has two events that trigger it: `push` to `main` and `pull_request` to `main`. Each time someone commits to `main` or creates a pull request (PR) to `main`, this workflow will execute. +1. There's a single `job` called `build`. This build should run on a hosted agent. `ubuntu_latest` specifies the most recent Ubuntu hosted agent. +1. There are five steps: + 1. `actions/checkout@v2` is an action that checks out the code in the repository onto the runner. + 1. `actions/setup-dotnet@v1` is an action that sets up the .NET CLI. This step also specifies a `name` attribute for the logs and the `dotnet-version` parameter within the `with` object. + 1. Three `run` steps that execute `dotnet restore`, `dotnet build`, and `dotnet test`. `name` attributes are also specified for these `run` steps to make the logs look pretty. + +## Publish the output + +Now that you've successfully built and tested the code, add steps that publish the output so you can deploy the web app. + +1. Navigate to the *.github/workflows/dotnet.yml* file and select the pencil icon to edit it. + + ![Edit the YAML file](./media/actions/build/click-edit.jpg) + + **Figure 5**: Edit the YAML file. + +1. Add the following `Publish` step below the `Test` step. The step runs the `dotnet publish` command to publish the web app: + + ```yml + - name: Test + run: dotnet test --no-build --verbosity normal # <-- this is the current bottom line + + - name: Publish + run: dotnet publish SimpleFeedReader/SimpleFeedReader.csproj -c Release -o website + ``` + +1. This publishes the web app to a folder on the hosted agent. Now you'll want to *upload* the site as a build artifact that can be deployed to Azure. To complete this activity, you'll use an existing action. +1. On the list of actions in the **Actions Helper** pane on the right, search for `artifact`. Select on the `Upload a Build Artifact (By actions)` action. + + ![Accessing the Actions helper](./media/actions/build/search-upload-artifact.jpg) + + **Figure 6**: Accessing the snippet helper. + +1. Edit the version to `v2.2.2` to display a sample snippet. Select the clipboard icon to copy the snippet and paste it into the workflow below the publish step. + + ![Copying a snippet](./media/actions/build/copy-snippet.jpg) + + **Figure 7**: Copying a snippet. + +1. Edit the YAML for this step to look as follows: + + ```yml + - name: Upload a Build Artifact + uses: actions/upload-artifact@v2.2.2 + with: + name: website + path: SimpleFeedReader/website/** + if-no-files-found: error + ``` + +1. Commit the file. +1. Once the workflow completes, you'll see the artifact from the **Home** tab: + + ![Viewing artifacts in the summary page](./media/actions/build/view-uploaded-artifact.jpg) + + **Figure 8**: Viewing artifacts in the summary page. + +### Final workflow file + +The final workflow file should look something like this: + +```yml +name: .NET + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + - name: Setup .NET + uses: actions/setup-dotnet@v1 + with: + dotnet-version: 5.0.x + - name: Restore dependencies + run: dotnet restore + - name: Build + run: dotnet build --no-restore + - name: Test + run: dotnet test --no-build --verbosity normal + - name: Publish + run: dotnet publish SimpleFeedReader/SimpleFeedReader.csproj -c Release -o website + - name: Upload a Build Artifact + uses: actions/upload-artifact@v2.2.2 + with: + name: website + path: SimpleFeedReader/website/** + if-no-files-found: error +``` + +>[!div class="step-by-step"] +>[Previous](actions-vs-pipelines.md) +>[Next](actions-deploy.md) diff --git a/docs/architecture/devops-for-aspnet-developers/actions-codeql.md b/docs/architecture/devops-for-aspnet-developers/actions-codeql.md new file mode 100644 index 0000000000000..afe84c3b5b340 --- /dev/null +++ b/docs/architecture/devops-for-aspnet-developers/actions-codeql.md @@ -0,0 +1,192 @@ +--- +title: DevOps with .NET and GitHub Actions - Secure code with CodeQL +description: Add security scanning to your .NET code with GitHub Actions and CodeQL +author: colindembovsky +ms.date: 03/04/2021 +--- + +# Secure .NET Code with CodeQL and GitHub Actions + +[CodeQL](https://codeql.github.com/docs/codeql-overview/about-codeql/) is a static code analysis engine that can automate security and quality checks. With CodeQL, you can perform *variant analysis*, which uses known vulnerabilities as seeds to find similar issues. CodeQL is part of [GitHub Advanced Security](https://docs.github.com/github/getting-started-with-github/about-github-advanced-security) that includes: + +> [!div class="checklist"] +> +> * Code scanning—find potential security vulnerabilities in your code. +> * Secret scanning—detect secrets and tokens that are committed. +> * Dependency scanning—detect vulnerabilities in packages that you consume. + +CodeQL [supports some of the most popular programming languages and compilers](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/): + +- C/C++ +- Java +- C# +- Python +- Go +- JavaScript +- TypeScript + +CodeQL is a powerful language and security professionals can create custom queries using CodeQL. However, teams can benefit immensely from the large open-source collection of queries that the security community has created without having to write any custom CodeQL. + +In this article, you'll set up a GitHub workflow that will scan code in your repository using CodeQL. You will: + +> [!div class="checklist"] +> +> * Create a code scanning action. +> * Edit the workflow file to include custom scan settings. +> * See scanning results. + +> [!NOTE] +> To see security alerts for your repository, you must be a repository owner. + +## Create the code scanning workflow + +You can use a starter workflow for code scanning by navigating to the **Security** tab of your repository. + +1. Navigate to your GitHub repository and select the **Security** > **Code Scanning Alerts**. The top recommended workflow should be CodeQL Analysis. Select **Set up this workflow**. + + ![Create a new code scanning workflow](./media/actions/codeql/setup-workflow.jpg) + + **Figure 1:** Create a new code scanning workflow. + +1. A new workflow file is created in your *.github/workflows* folder. +1. Select **Start Commit** on the upper right to save the default workflow. You can commit to the `main` branch. + + ![Commit the file](./media/actions/codeql/start-commit.jpg) + + **Figure 2:** Commit the file. + +1. Select the **Actions** tab. In the left-hand tree, you'll see a **CodeQL** node. Select this node to filter for CodeQL workflow runs. + + ![View the CodeQL workflow runs](./media/actions/codeql/codeql-run.jpg) + + **Figure 3:** View the CodeQL workflow runs. + +Take a look at the workflow file while it runs. If you remove the comments from the file, you'll see the following YAML: + +```yml +name: "CodeQL" + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + schedule: + - cron: '40 14 * * 6' + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + + strategy: + fail-fast: false + matrix: + language: [ 'csharp' ] + + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v1 + with: + languages: ${{ matrix.language }} + + - name: Autobuild + uses: github/codeql-action/autobuild@v1 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v1 +``` + +Notice the following things: + +1. The workflow `name` is `CodeQL`. +1. This workflow triggers on `push` and `pull_request` events to the `main` branch. There's also a `cron` trigger. The `cron` trigger lets you define a schedule for triggering this workflow and is randomly generated for you. In this case, this workflow will run at 14:40 UTC every Saturday. + + > [!TIP] + > If you edit the workflow file and hover over the cron expression, a tooltip will show you the English text for the cron expression. + +1. There's a single job called `analyze` that runs on the `ubuntu-latest` hosted agent. +1. This workflow defines a `strategy` with a `matrix` on the array of `language`. In this case, there's only `csharp`. If the repository contained other languages, you could add them to this array. This causes the job to "fan out" and create an instance per value of the matrix. +1. There are four steps, starting with `checkout`. +1. The second step initializes the CodeQL scanner for the `language` this job is going to scan. CodeQL intercepts calls to the compiler to build a database of the code while the code is being built. +1. The `Autobuild` step will attempt to automatically build the source code using common conventions. If this step fails, you can replace it with your own custom build steps. +1. After building, the CodeQL analysis is performed, where suites of queries are run against the code database. +1. The run should complete successfully. However, there appear to be no issues. + + ![No results to the initial scan](./media/actions/codeql/no-results.jpg) + + **Figure 4:** No results to the initial scan. + +## Customize CodeQL settings + +The CodeQL scan isn't reporting any security issues. That's expected with this basic sample. CodeQL can also scan for *quality* issues. The current workflow is using the default `security-extended` suite. You can add quality scanning in by adding a configuration file to customize the scanning suites. In this step, you'll configure CodeQL to use the `security-and-quality` suites. + +> [!INFORMATION] +> For other CodeQL configuration options, see [Configuring CodeQL code scanning in your CI system](https://docs.github.com/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-codeql-code-scanning-in-your-ci-system). + +1. Navigate to the *.github* folder in the **Code** tab and select **Add File**: + + ![Create a new file](./media/actions/codeql/create-new-file.jpg) + + **Figure 5:** Create a new file. + +1. Enter *codeql/codeql-config.yml* as the name. This creates the file in a folder. Paste in the following code: + + ```yml + name: "Security and Quality" + + queries: + - uses: security-and-quality + ``` + + ![Create the CodeQL config file](./media/actions/codeql/codeql-config.jpg) + + **Figure 6:** Create the CodeQL configuration file. + +1. Select **Commit to main** at bottom of the editor to commit the file. +1. Edit the CodeQL workflow to use the new configuration file. Navigate to *.github/workflows/codeql-analysis.yml* and select the pencil icon. Add a new property to the `with` section as shown below: + + ```yml + - name: Initialize CodeQL + uses: github/codeql-action/init@v1 + with: + languages: ${{ matrix.language }} + config-file: ./.github/codeql/codeql-config.yml # <-- add this line + ``` + +1. Select **Start Commit** and commit to the `main` branch. + +## Review the security alerts + +> [!IMPORTANT] +> You must be a repository owner to view security alerts. +> +> This sample repository is small. As such, it doesn't contain any major security or quality issues. However, "real world" repositories will likely have some issues. + +When the last CodeQL workflow run completes, you should see two issues in the **Security** tab: + +![View security alerts](./media/actions/codeql/security-alerts.jpg) + +**Figure 7:** View security alerts. + +1. Select the first alert to open it. +1. In this case, the alert is for a generated file that isn't committed to the repository. For that reason, the preview is unavailable. +1. Notice the tags that are applied. These tags can be used for filtering issues. +1. Select **Show more** under the rule information to show help and recommendations. + + ![Open an alert](./media/actions/codeql/alert.jpg) + + **Figure 8:** Open an alert. + +1. Selecting **Dismiss** will open options for dismissing this issue: + + ![Dismiss an alert](./media/actions/codeql/dismiss.jpg) + + **Figure 9:** Dismiss an alert. + +>[!div class="step-by-step"] +>[Previous](actions-deploy.md) +>[Next](monitoring.md) diff --git a/docs/architecture/devops-for-aspnet-developers/actions-deploy.md b/docs/architecture/devops-for-aspnet-developers/actions-deploy.md new file mode 100644 index 0000000000000..e352e0b081c62 --- /dev/null +++ b/docs/architecture/devops-for-aspnet-developers/actions-deploy.md @@ -0,0 +1,513 @@ +--- +title: DevOps with .NET and GitHub Actions - Deploy a .NET Web App to Azure Web Apps +description: Deploy a .NET app to Azure App Service, the first step for DevOps with .NET and GitHub Actions. +author: colindembovsky +ms.date: 03/04/2021 +--- +# Deploy a .NET web app using GitHub Actions + +> [!WARNING] +> Please complete the [Build](actions-build.md) tutorial before starting this lab. + +In this article, you'll: +> [!div class="checklist"] +> +> * Learn about Environments in GitHub Actions. +> * Create two environments and specify environment protection rules. +> * Create environment secrets for managing environment-specific configuration. +> * Extend the workflow YAML file to add deployment steps. +> * Add a manual dispatch trigger. + +## Environments + +Now that you've published an artifact that's *potentially deployable*, you'll add *deployment* jobs to the workflow. There's nothing special about a deployment job, other than the fact that it references an *environment*. Environments are *logical* constructs that allow you to specify environment protection rules, such as approvals, on any group of resources that you're targeting. + +In this walkthrough, you'll be deploying to two environments: `PRE-PROD` and `PROD`. In a typical development lifecycle, you'll want to deploy the latest code to a *soft* environment (typically `DEV`) that is expected to be a bit unstable. You'll use `PRE-PROD` as this *soft* environment. The "higher" environments (like `UAT` and `PROD`) are *harder* environments that are expected to be more stable. To enforce this, you can build protection rules into higher environments. You'll configure an approval protection rule on the `PROD` environment: whenever a deployment job targets an environment with an approval rule, it will pause until approval is granted before executing. + +GitHub environments are *logical*. They represent the physical (or virtual) resources that you're deploying to. In this case, the `PRE-PROD` is just a deployment slot on the Azure Web App. `PROD` is the production slot. The `PRE-PROD` deployment job will deploy the published .NET app to the staging slot. The `PROD` deployment job will swap the slots. + +Once you have these steps in place, you'll update the workflow to handle environment-specific configuration using environment secrets. + +> [!NOTE] +> For more information, see [GitHub Actions - Environments](https://docs.github.com/actions/reference/environments). + +## Azure authentication + +To perform actions such as deploying code to an Azure resource, you need the correct permissions. For deployment to Azure Web Apps, you can use a publishing profile. If you want to deploy to a staging slot, then you'll need the publishing profile for the slot too. Instead, you can use a service principal (SPN) and assign permission to this service principal. You can then authenticate using credentials for the SPN before using any commands that the SPN has permissions to perform. + +Once you have an SPN, you'll create a [repository secret](https://docs.github.com/actions/reference/encrypted-secrets) to securely store the credentials. You can then refer to the secret whenever you need to authenticate. The secret is encrypted and once it has been saved, can never be viewed or edited (only deleted or re-created). + +### Create an SPN + +1. In your terminal or Cloud Shell, run the following command to create a service principal with contributor permissions to the web app you created earlier: + + ```azurecli + az ad sp create-for-rbac --name "{sp-name}" --sdk-auth --role contributor \ + --scopes /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Web/sites/{webappname} + ``` + +1. The command should output JSON that has credentials embedded: + + ```json + { + "clientId": "", + "clientSecret": "", + "subscriptionId": "", + "tenantId": "", + ... + } + ``` + +1. Make sure to record the `clientId`, `clientSecret`, `subscription`, and `tenantId`. You can also leave the terminal open for copy/paste later. + +### Create a repository secret + +1. Now you're going to create an encrypted secret to store the credentials. You'll create this secret at the repository level. +1. Navigate to GitHub and select your repository **Settings** tab. Then select **Secrets**. Select **New repository secret**: + + ![Create a secret](./media/actions/deploy/add-repo-secret.jpg) + + **Figure 1**: Create a secret. + +1. Copy and paste the JSON from the `az ad sp create-for-rbac` command into the body of the secret. You can create this JSON by hand too if you have the relevant fields for your SPN. The secret should be named `AZURE_CREDENTIALS`. Select **Add secret** to save the new secret: + + ![Add Azure credentials](./media/actions/deploy/azure-credentials.jpg) + + **Figure 2**: Add Azure credentials. + +1. You'll consume this secret in a workflow in later steps. To access it, use the variable notation `${{}}`. In this case, `${{ AZURE_CREDENTIAL }}` will be populated with the JSON you saved. + +## Add environments + +[Environments](https://docs.github.com/actions/reference/environments) are used as a *logical boundary*. You can add approvals to environments to ensure quality. You can also track deployments to environments and specify environment-specific values (secrets) for configuration. + +For this example, you're going to split the actual Azure environment into two *logical* environments called `PRE-PROD` and `PROD`. When you deploy the web app, you'll deploy to the staging slot of the Azure web app, represented by the `PRE-PROD` environment. When you're ready to deploy to `PROD`, you'll just perform a slot swap. + +In this case, the only difference between the environments is the slot that you're deploying to. In real life, there would typically be different web apps (and separate web app plans), separate resource groups, and even separate subscriptions. Typically, there's an SPN per environment. You may want to override the `AZURE_CREDENTIAL` value that you saved as a repository secret by creating it as an *environment secret*. + +> [!NOTE] +> Precedence works from Environment to repository. If a targeted environment has a secret called `MY_SECRET`, then that value is used. If not, the repository value of `MY_SECRET` (if any) is used. + +1. Select **Settings** and then **Environments** in your repository. Select **New Environment**: + + ![Create an environment](./media/actions/deploy/new-env.jpg) + + **Figure 3**: Create an environment. + +1. Enter `PRE-PROD` and select **Configure environment**: + + ![Name the environment](./media/actions/deploy/pre-prod-env.jpg) + + **Figure 4**: Name the environment. + +1. Since deploying to a staging slot doesn't affect the web app, you can safely deploy to the slot without requiring an approval first. A reviewer could be added if desired. For this example, leave the Environment protection rules empty. + + > [!NOTE] + > If you target an environment in a workflow and it does not exist, an "empty" environment is created automatically. The environment would look exactly the same as the `PRE-PROD` environment - it would exist, but would not have any protection rules enabled. + +1. Select **Environments** again and again select **New Environment**. Now enter `PROD` as the name and select **Configure environment**. + +1. Check the **Required reviewers** rule and add yourself as a reviewer. Don't forget to select **Save protection rules**: + + ![Add protection rules](./media/actions/deploy/env-protection-rule.jpg) + + **Figure 5**: Add protection rules. + +## Deploy to staging + +You can now add additional jobs to the workflow to deploy to the environments! You'll start by adding a deployment to the `PRE-PROD` environment, which in this case is the web app staging slot. + +1. Navigate to the *.github/workflows/dotnet.yml* file and select the pencil icon to edit the file. +1. You're going to use the web app name a few times in this workflow, and will need the name of the resource group too. You'll define the app and resource group names as variables. With the variables, you can maintain the values in one place in the workflow file. +1. Add this snippet below the `on` block and above the `jobs` block: + + ```yml + env: + app-name: "" + rg-name: "" + + jobs: # <-- this is the existing jobs line + ``` + + > [!WARNING] + > You'll need to replace `` with the actual name of your web app, and `` with the actual name of your resource group. + +1. Add a new job below the `build` job as follows: + + ```yml + if-no-files-found: error # <-- last line of build job: insert below this line + + deploy_staging: + needs: build + runs-on: ubuntu-latest + + environment: + name: PRE-PROD + url: ${{ steps.deploywebapp.outputs.webapp-url }} + + steps: + - name: Download a Build Artifact + uses: actions/download-artifact@v2.0.8 + with: + name: website + path: website + + - name: Login via Azure CLI + uses: azure/login@v1 + with: + creds: ${{ secrets.AZURE_CREDENTIALS }} + + - name: Deploy web app + id: deploywebapp + uses: azure/webapps-deploy@v2 + with: + app-name: ${{ env.app-name }} + slot-name: staging + package: website + + - name: az cli logout + run: az logout + ``` + + The preceding workflow defines several steps: + + 1. You're creating a new job called `deploy_staging`. + 1. You specify a dependency using `needs`. This job needs the `build` job to complete successfully before it starts. + 1. This job also runs on the latest Ubuntu hosted agent, as specified with the `runs-on` attribute. + 1. You specify that this job is targeting the `PRE-PROD` environment using the `environment` object. You also specify the `url` property. This URL will be displayed in the workflow diagram, giving users an easy way to navigate to the environment. The value of this property is set as the `output` of the `step` with `id` `deploywebapp`, which is defined below. + 1. You're executing a `download-artifact` step to download the artifact (compiled web app) from the `build` job. + 1. You then `login` to Azure using the `AZURE_CREDENTIALS` secret you saved earlier. Note the `${{ }}` notation for dereferencing variables. + 1. You then perform a `webapp-deploy`, specifying the `app-name`, `slot-name`, and path to the downloaded artifact (`package`). This action also defines an `output` parameter that you use to set the `url` of the environment above. + 1. Finally, you execute a `logout` to log out of the Azure context. + +1. Commit the file. +1. When the run completes, you should see two successful jobs. The URL for the `PRE-PROD` stage has been set and selecting it will navigate you to your web app staging slot: + + ![Deployment to PRE-PROD is successful](./media/actions/deploy/deploy-to-staging-completed.jpg) + + **Figure 6**: Deployment to PRE-PROD is successful. + +1. Notice how the staging slot's direct URL contains `-staging`: + + ![The staging slot running](./media/actions/deploy/deployed-to-staging.jpg) + + **Figure 7**: The staging slot running. + +1. You can also now see deployments. Navigate to `https://{your repository url}/deployments` to view your deployments: + + ![View deployments](./media/actions/deploy/deployments.jpg) + + **Figure 8**: View deployments. + +## Deploy to production + +Now that you've deployed successfully to `PRE-PROD`, you'll want to deploy to `PROD`. Deployment to `PROD` will be slightly different since you don't need to copy the website again - you just need to swap the `staging` slot with the production slot. You'll do this using an Azure CLI (`az`) command. + +1. Navigate to the *.github/workflows/dotnet.yml* file and select the pencil icon to edit the file. +1. Add a new job below the `deploy_staging` job as follows: + + ```yml + run: az logout # <-- last line of previous job: insert below this line + + deploy_prod: + needs: deploy_staging + runs-on: ubuntu-latest + + environment: + name: PROD + url: ${{ steps.slot_swap.outputs.url }} + + steps: + - name: Login via Azure CLI + uses: azure/login@v1 + with: + creds: ${{ secrets.AZURE_CREDENTIALS }} + + - name: Swap staging slot into production + id: slot_swap + run: | + az webapp deployment slot swap -g ${{ env.rg-name }} -n ${{ env.app-name }} -s staging + url=$(az webapp show -g ${{ env.rg-name }} -n ${{ env.app-name }} --query "defaultHostName" -o tsv) + echo "::set-output name=url::http://$url" + + - name: az cli logout + run: az logout + ``` + + The deployment to the `PROD` environment workflow specifies several steps: + + 1. Once again, you specify a new job `deploy_prod` that `needs` `deploy_staging` to complete before starting. + 1. You're targeting the `PROD` environment this time. Also, the `url` value is different from before. + 1. For the steps, you don't need to download the artifact since you're just going to perform a slot swap. You start by executing a `login` to the Azure context. + 1. The `Swap staging slot into production` step is a multi-line `run` command (note the use of the pipe symbol `|`). You also specify an `id` for this step so that you can refer to it (you refer to it in the `url` property of the `environment`). The first line executes the slot swap using the variables you defined above in the workflow. The second line uses an `az webapp show` command to extract the URL of the target web app. This final line uses `::set-output` in an echo to create an output variable for this task, setting the value to the web app URL. + + > [!NOTE] + > The URL *must* start with `http://` or `https://` or it won't render. + +1. Commit the file. +1. Let the workflow run for a couple minutes until it has deployed to `PRE-PROD`. At this point, the workflow will pause and wait for the required approval since you're targeting the `PROD` environment, which requires an approval as defined earlier: + + ![Waiting for an approval](./media/actions/deploy/waiting-for-approval.jpg) + + **Figure 9**: Waiting for an approval. + +1. Select **Review deployments**, select the **PROD** checkbox, optionally add a comment, and then select **Approve and deploy** to start the `PROD` job. + + ![Approve the PROD deployment](./media/actions/deploy/approval.jpg) + + **Figure 10**: Approve the PROD deployment. + +1. The deployment should only take a few seconds. Once it has completed, the URL for the `PROD` environment will update. + + ![PROD deployment completed](./media/actions/deploy/prod-deploy-complete.jpg) + + **Figure 11**: PROD deployment completed. + +1. Selecting the `PROD` URL will navigate you to the `PROD` site. + + ![The PROD site](./media/actions/deploy/deployed-to-prod.jpg) + + **Figure 12**: The PROD site. + +## Add a manual queue option + +You now have an end-to-end build and deploy workflow, including approvals. One more change you can make is to add a manual trigger to the workflow so that the workflow can be triggered from within the **Actions** tab of the repository. + +1. Navigate to the *.github/workflows/dotnet.yml* file and select the pencil icon to edit the file. +1. Add a new trigger between `on` and `push` on lines 3 and 4: + + ```yml + on: + workflow_dispatch: # <-- this is the new line + push: + ``` + +1. The `workflow_dispatch` trigger displays a `Run workflow` button in the **Actions** tab of the repository—*but only if the trigger is defined in the default branch*. However, once this trigger is defined in the workflow, you can select the branch for the run. +1. Commit the file. +1. To see the **Run workflow** button, select the **Actions** tab. Select the `.NET` workflow in the list of workflows. At the top of the list of runs, you'll see the **Run workflow** button. If you select it, you can choose the branch to run the workflow against and queue it: + + ![Manual dispatch](./media/actions/deploy/manual-dispatch.jpg) + + **Figure 13**: Manual dispatch. + +## Handle environment configuration + +Your workflow is deploying the same binary to each environment. This concept is important to ensure that the binaries you test in one environment are the same that you deploy to the next. However, environments typically have different settings like database connection strings. You want to ensure that the `DEV` app is using `DEV` settings and the `PROD` app is using `PROD` settings. + +For this simple app, there's no database connection string. However, there's an example configuration setting that you can modify for each environment. If you open the *simple-feed-reader/SimpleFeedReader/appsettings.json* file, you'll see that the configuration includes a setting for the Header text on the Index page: + +```json + "UI": { + "Index": { + "Header": "Simple News Reader" + } + }, +``` + +To show how environment configuration can be handled, you're going to add a secret to each environment and then substitute that value into the settings as you deploy. + +### Add environment secrets + +1. On your repository, select **Settings** > **Environments** > **PRE-PROD**. +1. Select **Add secret** and add a secret called `index_header` with the value `PRE PROD News Reader`. Select **Add secret**. + + ![Add an environment secret](./media/actions/deploy/add-env-secret.jpg) + + **Figure 14**: Add an environment secret. + +1. Repeat these steps to add a secret called `index_header` with the value `PROD News Reader` for the `PROD` environment. +1. If you select **Settings** > **Secrets** in the repository, you'll see the changes. They should look something like this: + + ![View secrets](./media/actions/deploy/env-secrets.jpg) + + **Figure 15**: View secrets. + +### Update the workflow to handle configuration + +1. Navigate to the *.github/workflows/dotnet.yml* file and select the pencil icon to edit the file. +1. Add the following step before the `az cli logout` step in the `deploy_staging` job: + + ```yml + - name: Update config + uses: Azure/appservice-settings@v1 + with: + app-name: ${{ env.app-name }} + slot-name: staging + app-settings-json: | + [ + { + "name": "UI:Index:Header", + "value": "${{ secrets.INDEX_HEADER }}", + "slotSetting": true + } + ] + + - name: az cli logout # <-- this exists already + ``` + +1. Add almost the same code to the `deploy_prod` job above its `az cli logout` step. The only difference is that you don't specify a `slot-name`, since you're targeting the production slot: + + ```yml + - name: Update config + uses: Azure/appservice-settings@v1 + with: + app-name: ${{ env.app-name }} + app-settings-json: | + [ + { + "name": "UI:Index:Header", + "value": "${{ secrets.INDEX_HEADER }}", + "slotSetting": true + } + ] + + - name: az cli logout # <-- this exists already + ``` + +1. Commit the file. +1. Let the workflow run and approve the deployment to `PROD` once the approval is reached. +1. You should see the following headers on the index page for both sites: + + ![Settings changed in the environments](./media/actions/deploy/settings-in-both-envs.jpg) + + **Figure 16**: Settings changed in the environments. + +## Final workflow file + +The final workflow file should look like this: + +```yml +name: .NET + +on: + workflow_dispatch: + inputs: + reason: + description: 'The reason for running the workflow' + required: true + default: 'Manual build from GitHub UI' + push: + branches: [ main ] + pull_request: + branches: [ main ] + +env: + app-name: "cd-simplefeedreader" + rg-name: "cd-dotnetactions" + +jobs: + build: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + - name: 'Print manual run reason' + if: ${{ github.event_name == 'workflow_dispatch' }} + run: | + echo 'Reason: ${{ github.event.inputs.reason }}' + - name: Setup .NET + uses: actions/setup-dotnet@v1 + with: + dotnet-version: 2.1.x + - name: Restore dependencies + run: dotnet restore + - name: Build + run: dotnet build --no-restore + - name: Test + run: dotnet test --no-build --verbosity normal + - name: Publish + run: dotnet publish SimpleFeedReader/SimpleFeedReader.csproj -c Release -o website + - name: Upload a Build Artifact + uses: actions/upload-artifact@v2.2.2 + with: + name: website + path: SimpleFeedReader/website/** + if-no-files-found: error + + deploy_staging: + needs: build + runs-on: ubuntu-latest + + environment: + name: STAGING + url: ${{ steps.deploywebapp.outputs.webapp-url }} + + steps: + - name: Download a Build Artifact + uses: actions/download-artifact@v2.0.8 + with: + name: website + path: website + + - name: Login via Azure CLI + uses: azure/login@v1 + with: + creds: ${{ secrets.AZURE_CREDENTIALS }} + + - name: Deploy web app + id: deploywebapp + uses: azure/webapps-deploy@v2 + with: + app-name: ${{ env.app-name }} + slot-name: staging + package: website + + - name: Update config + uses: Azure/appservice-settings@v1 + with: + app-name: ${{ env.app-name }} + slot-name: staging + app-settings-json: | + [ + { + "name": "UI:Index:Header", + "value": "${{ secrets.INDEX_HEADER }}", + "slotSetting": true + } + ] + + - name: az cli logout + run: az logout + + deploy_prod: + needs: deploy_staging + runs-on: ubuntu-latest + + environment: + name: PROD + url: ${{ steps.slot_swap.outputs.url }} + + steps: + - name: Login via Azure CLI + uses: azure/login@v1 + with: + creds: ${{ secrets.AZURE_CREDENTIALS }} + + - name: Swap staging slot into production + id: slot_swap + run: | + az webapp deployment slot swap -g ${{ env.rg-name }} -n ${{ env.app-name }} -s staging + url=$(az webapp show -g ${{ env.rg-name }} -n ${{ env.app-name }} --query "defaultHostName" -o tsv) + echo "::set-output name=url::http://$url" + + - name: Update config + uses: Azure/appservice-settings@v1 + with: + app-name: ${{ env.app-name }} + app-settings-json: | + [ + { + "name": "UI:Index:Header", + "value": "${{ secrets.INDEX_HEADER }}", + "slotSetting": true + } + ] + + - name: az cli logout + run: az logout +``` + +>[!div class="step-by-step"] +>[Previous](actions-build.md) +>[Next](actions-codeql.md) diff --git a/docs/architecture/devops-for-aspnet-developers/actions-index.md b/docs/architecture/devops-for-aspnet-developers/actions-index.md new file mode 100644 index 0000000000000..c507d6a763c62 --- /dev/null +++ b/docs/architecture/devops-for-aspnet-developers/actions-index.md @@ -0,0 +1,57 @@ +--- +title: Continuous integration and deployment with GitHub Actions overview +description: Learn how to create a continuous deployment pipeline with GitHub Actions and .NET DevOps +author: colindembovsky +ms.date: 03/30/2021 +uid: azure/devops/github-actions +--- +# Continuous integration and deployment with GitHub Actions + +GitHub has long been the home for millions of open-source developers around the globe. Most developers associate source control with GitHub. However, GitHub is an evolving platform that can be used for more than just synchronizing Git repositories. + +## GitHub Actions + +GitHub Actions is a workflow engine that can automate workflows for nearly all events that occur on GitHub. Actions is a great solution for Continuous Integration/Continuous Deployment (CI/CD) pipelines. + +In this section of articles, you'll learn how to create an Actions workflow. The workflow will build, test, and deploy a .NET web app to Azure Web Apps. + +> [!NOTE] +> Before you begin, complete the **Publish the app's code to GitHub** and **Disconnect local Git deployment** sections of the [Continuous integration and deployment with Azure DevOps](cicd.md) section to publish your code to GitHub. Then proceed to the [Build](actions-build.md) article. + +In the [Build](actions-build.md) article, you'll create the initial workflow to build and test the .NET app. You'll: + +> [!div class="checklist"] +> +> * Learn the basic structure of a GitHub Action workflow YAML file. +> * Use a template to create a basic build workflow that builds a .NET app and executes unit tests. +> * Publish the compiled app so that it's ready for deployment. + +In the [Deploy](actions-build.md) article, you'll: + +> [!div class="checklist"] +> +> * Learn about environments in GitHub Actions. +> * Create two environments and specify environment protection rules. +> * Create environment secrets for managing environment-specific configuration. +> * Extend the workflow YAML file to add deployment steps. +> * Add a manual dispatch trigger. + +## Secure code with CodeQL + +In addition to building and deploying code, [GitHub Advanced Security](https://docs.github.com/github/getting-started-with-github/about-github-advanced-security) offers tools for "shifting left" with security. That is, integrating security early on in the software delivery lifecycle. [CodeQL](https://codeql.github.com/docs/codeql-overview/about-codeql/) is a code scanning language that runs queries to find potential vulnerabilities or quality issues in your code. CodeQL is run using an Actions workflow. + +In the [CodeQL](actions-codeql.md) article, you'll: + +> [!div class="checklist"] +> +> * Create a Code Scanning Action. +> * Edit the workflow file to include custom scan settings. +> * See scanning results. + +## Compare and contrast GitHub Actions and Azure Pipelines + +GitHub Actions and Azure Pipelines have a common lineage and are similar in many respects. However, you should understand the differences before selecting a platform for building, testing, and deploying apps. In the [Comparison](actions-vs-pipelines.md) article, you'll deep dive into these platforms and compare and contrast them. You'll also learn how to select the correct platform for your CI/CD needs. + +>[!div class="step-by-step"] +>[Previous](cicd.md) +>[Next](actions-vs-pipelines.md) diff --git a/docs/architecture/devops-for-aspnet-developers/actions-vs-pipelines.md b/docs/architecture/devops-for-aspnet-developers/actions-vs-pipelines.md new file mode 100644 index 0000000000000..6bbb89b022a8e --- /dev/null +++ b/docs/architecture/devops-for-aspnet-developers/actions-vs-pipelines.md @@ -0,0 +1,134 @@ +--- +title: DevOps with .NET and GitHub Actions - Compare GitHub Actions with Azure Pipelines +description: GitHub Actions and Azure Pipelines compared and contrasted for decision makers +author: colindembovsky +ms.date: 03/04/2021 +--- + +# Compare and contrast GitHub Actions and Azure Pipelines + +[GitHub Actions](https://docs.github.com/actions) and [Azure Pipelines](/azure/devops/pipelines/get-started/what-is-azure-pipelines) have a common history. In fact, the Actions agent is a fork of the Pipelines agent. There are many similarities between GitHub Actions and Azure Pipelines and it's worth comparing and contrasting them. + +## Pipelines as code + +Before you compare GitHub Actions and Azure Pipelines, you should consider the benefits of *pipelines as code*. Pipelines as code: + +> [!div class="checklist"] +> +> * Benefit from standard source control practices (such as code reviews via pull request and versioning). +> * Can be audited for changes just like any other files in the repository. +> * Don’t require accessing a separate system or UI to edit. +> * Can fully codify the build, test, and deploy process for code. +> * Can usually be templatized to empower teams to create standard processes across multiple repositories. + +> [!NOTE] +> The term "pipelines" can also be referred to by several different interchangeable words: *pipeline*, *workflow*, and *build* are common terms. In this article, references to *Azure Pipelines* are referring to [YAML Pipelines](/azure/devops/pipelines/get-started/pipelines-get-started?view=azure-devops&preserve-view=true#define-pipelines-using-yaml-syntax), and not the older UI-based [Classic Pipelines](/azure/devops/pipelines/get-started/pipelines-get-started?view=azure-devops&preserve-view=true#define-pipelines-using-the-classic-interface). + +## Agents and runners + +Before you examine pipelines themselves, you should consider how these pipelines *execute*. Both GitHub Actions and Azure Pipelines are really *orchestration engines*. When a pipeline is triggered, the system finds an "agent" and tells the agent to execute the jobs defined in the pipeline file. + +Azure Pipelines run on *agents*. The agent is written in .NET, so it will run wherever .NET can run: Windows, macOS, and Linux. Agents can even run in containers. Agents are registered to a [pool](/azure/devops/pipelines/agents/pools-queues) in Azure Pipelines or to a repository or organization in GitHub. Agents can be *hosted* or *private*. + +GitHub Workflows execute on *runners*. The runner code is essentially a fork of the Azure Pipelines code, so it's very similar. It's also cross-platform and you can also use *hosted* or *self-hosted* runners. + +### Hosted agents and runners + +Hosted agents (Azure Pipelines) and hosted runners (GitHub) are agents that are spun up and managed by Azure DevOps or GitHub respectively. You don't need to maintain any build infrastructure. When a pipeline triggers that targets a hosted agent, an instance of the specified agent image is created. The job is run by the agent on the instance, and once the job completes, the instance is destroyed. The same applies for hosted runners running GitHub workflows. + +> [!NOTE] +> The list of software installed on Azure Pipeline images is listed in [this repository](https://github.com/actions/virtual-environments/tree/main/images). You can select the platform folder and examine the *README.md* files. You can find information on [GitHub hosted runners](https://docs.github.com/actions/reference/specifications-for-github-hosted-runners). + +### Private agents and self-hosted runners + +There are times when you can't use hosted images. For example, when you: + +- Require SDKs or other software that isn't installed on the images. +- Need to access resources that aren't public (such as an internal SonarQube server or an internal Artifactory instance). +- Need to deploy to private networks. +- Need to install licenses for third-party software required for building your code. +- Need more storage or memory than is provided to the hosted agent images. +- Need more time than the maximum build time limit for hosted agents. + +> [!IMPORTANT] +> It's possible to install tools and SDKs when running pipelines on hosted agents. If the install steps don't take long, this is viable. However, if the tools/software take a long time to install, then you may be better off with a private agent or self-hosted runner, since the install steps will need to execute for every run of the workflow. + +### Azure DevOps agents + +Every Azure DevOps account has a hosted pool with a single agent that can run one job at a time. Also included is a set number of free build minutes. You may purchase additional "hosted pipelines" in Azure DevOps. When you purchase an additional hosted pipeline, you're really removing the build minutes limit and adding *concurrency*. One pipeline can run one job at a time. Two pipelines can run two jobs simultaneously, and so on. + +### Comparison of agents + +|Feature|GitHub|Azure Pipelines|Links| +|-------|------|---------------|-----| +|Hosted agents for public repos/projects|Free|[No free minutes](https://devblogs.microsoft.com/devops/change-in-azure-pipelines-grant-for-public-projects/) for public projects|[Azure Pipelines](/azure/devops/pipelines/agents/hosted?view=azure-devops&tabs=yaml&preserve-view=true#capabilities-and-limitations) [GitHub](https://github.com/features/actions)| +|Hosted agents for private repos/projects|2,000 minutes free per month, 3,000 minutes for Pro and Team licenses, 50,000 minutes for Enterprise license. Additional minutes may be purchased.|One free parallel job that can run for up to 60 minutes each time, until you've used 1,800 minutes (30 hours) per month. You can pay for additional capacity per parallel job. Paid parallel jobs remove the monthly time limit and allow you to run each job for up to 360 minutes (6 hours).|| +|Cross-platform|Yes|Yes|| +|Scale set agents|No|Yes| [Azure virtual machine scale set agents](/azure/devops/pipelines/agents/scale-set-agents?view=azure-devops&preserve-view=true)| + +## Comparison of GitHub Actions and Azure Pipelines + +Azure Pipelines (YAML pipelines) provide a mature set of features. Some of the features include: + +* Approvals +* Artifact storage +* Deployment jobs +* Environments +* Gates +* Stages +* Templates +* Triggers +* Variable groups + +For a full list of Azure Pipelines features, refer to the [Feature availability](/azure/devops/pipelines/get-started/pipelines-get-started?view=azure-devops&preserve-view=true#feature-availability) table. + +GitHub Actions are evolving rapidly and provide features such as triggers for almost all GitHub events, artifact storage, environments and environment rules, starter templates, and matrices. Read more about the entire feature set refer [GitHub Actions](https://docs.github.com/actions). + +### Feature comparison + +The following table is current as of March 2021. + +|Feature|Description|GitHub Actions|Azure Pipelines| +|-------|-----------|--------------|---------------| +|Approvals|Define approval conditions before moving further in the pipeline|Yes|Yes| +|Artifacts|Upload, store, and download artifacts from jobs|Yes|Yes| +|Caching|Cache folders or files for subsequent runs|Yes|Yes| +|Conditions|Specify conditions for steps or jobs|Yes|Yes| +|Container Jobs|Run jobs inside a container|Yes|Yes| +|Demands|Specify demands that must be met to match jobs to agents|No|Yes| +|Dependencies|Specify dependencies between jobs or stages|Yes|Yes| +|Deployment Groups|A logical set of target machines for deployments|No|Yes| +|Deployment Jobs|Job that targets a deployment group|No|Yes| +|Environments|A collection of resources to target or a logical environment|Yes|Yes| +|Gates|Automatic collection and evaluation of signals to control continuation|No|Yes| +|Jobs|Sequence of steps that are executed on an agent|Yes|Yes| +|Service Containers|Manage the lifecycle of a containerized service instance available during a job|Yes|Yes| +|Service Connections|Abstract credentials to external systems|No|Yes| +|Stages|Organize jobs in a pipeline|No|Yes| +|Templates|Define reusable, parameterized building blocks for steps, jobs, or variables|No|Yes| +|Starter Templates|Defines a starter workflow based on the type of code detected in a repository|Yes|No| +|Triggers|Set of events that cause the pipeline to trigger|Yes|Yes| +|Variables|Variables that can be passed in, statically or dynamically defined|Yes|Yes| +|Variable Groups|Store values for use across multiple pipelines|No|Yes| + +## Recommendation table for common scenarios + +The following table shows some common scenarios and platform recommendations for each. As always, there will be exceptions. Consider your exact scenario carefully. + +|Requirement|Platform| +|-----------|--------| +|I need to create reusable templates to standardize how jobs are executed across multiple teams|Azure Pipelines| +|I need to have automated gates control pipeline progress|Azure Pipelines| +|I need to define multiple stages|Azure Pipelines| +|I need multiple jobs to target the same environment|Azure Pipelines| +|I need to model multiple, complex environments|Azure Pipelines| +|I need to use the same environments across multiple projects/repos|Azure Pipelines| +|I have repos that aren't in GitHub|Azure Pipelines| +|I need to create custom tasks that aren't open-source|Azure Pipelines| +|I need a simple workflow for building and deploying open-source repositories to a small set of environments|GitHub Actions| +|I need to model workflows for scenarios other than CI/CD. For example, custom alerts on pull requests|GitHub Actions| +|I need to create custom tasks that are open-source|Both| + +>[!div class="step-by-step"] +>[Previous](actions-index.md) +>[Next](actions-build.md) diff --git a/docs/architecture/devops-for-aspnet-developers/cicd.md b/docs/architecture/devops-for-aspnet-developers/cicd.md new file mode 100644 index 0000000000000..0934b16888aff --- /dev/null +++ b/docs/architecture/devops-for-aspnet-developers/cicd.md @@ -0,0 +1,328 @@ +--- +title: Continuous integration and deployment - DevOps for ASP.NET Core Developers +author: CamSoper +description: Continuous integration and deployment in DevOps for ASP.NET Core Developers +ms.author: scaddie +ms.date: 10/24/2018 +ms.custom: "devx-track-csharp, mvc, seodec18" +no-loc: [appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR] +uid: azure/devops/cicd +--- +# Continuous integration and deployment with Azure DevOps + +> [!NOTE] +> This section details continuous integration and deployment with Azure DevOps. You can achieve that with GitHub Actions as well. GitHub Actions is a workflow engine built into GitHub that can also be used for continuous integration and deployment. To follow the guide for building and deploying to Azure using GitHub, complete the **Publish the app's code to GitHub** and **Disconnect local Git deployment** sections below and then proceed to the [GitHub Actions section](actions-index.md). + +In the previous chapter, you created a local Git repository for the Simple Feed Reader app. In this chapter, you'll publish that code to a GitHub repository and construct an Azure DevOps Services pipeline using Azure Pipelines. The pipeline enables continuous builds and deployments of the app. Any commit to the GitHub repository triggers a build and a deployment to the Azure Web App's staging slot. + +In this section, you'll complete the following tasks: + +> [!div class="checklist"] +> +> * Publish the app's code to GitHub +> * Disconnect local Git deployment +> * Create an Azure DevOps organization +> * Create a team project in Azure DevOps organization +> * Configure a self-hosted agent if necessary +> * Create a build definition +> * Create a release pipeline +> * Commit changes to GitHub and automatically deploy to Azure +> * Examine the Azure Pipelines pipeline + +## Publish the app's code to GitHub + +1. Open a browser window, and navigate to `https://github.com`. +1. Click the **+** drop-down in the header, and select **New repository**: + + ![GitHub New Repository option](media/cicd/github-new-repo.png) + +1. Select your account in the **Owner** drop-down, and enter *simple-feed-reader* in the **Repository name** textbox. +1. Click the **Create repository** button. +1. Open your local machine's command shell. Navigate to the directory in which the *simple-feed-reader* Git repository is stored. +1. Rename the existing *origin* remote to *upstream*. Execute the following command: + + ```console + git remote rename origin upstream + ``` + +1. Add a new *origin* remote pointing to your copy of the repository on GitHub. Execute the following command: + + ```console + git remote add origin https://github.com//simple-feed-reader/ + ``` + +1. Publish your local Git repository to the newly created GitHub repository. Execute the following command: + + ```console + git push -u origin main + ``` + +1. Open a browser window, and navigate to `https://github.com//simple-feed-reader/`. Validate that your code appears in the GitHub repository. + +## Disconnect local Git deployment + +Remove the local Git deployment with the following steps. Azure Pipelines (an Azure DevOps service) both replaces and augments that functionality. + +1. Open the [Azure portal](https://portal.azure.com/), and navigate to the *staging (mywebapp\/staging)* Web App. The Web App can be quickly located by entering *staging* in the portal's search box: + + ![staging Web App search term](media/cicd/portal-search-box.png) + +1. Click **Deployment Center**. A new panel appears. Click **Disconnect** to remove the local Git source control configuration that was added in the previous chapter. Confirm the removal operation by clicking the **Yes** button. +1. Navigate to the *mywebapp* App Service. As a reminder, the portal's search box can be used to quickly locate the App Service. +1. Click **Deployment Center**. A new panel appears. Click **Disconnect** to remove the local Git source control configuration that was added in the previous chapter. Confirm the removal operation by clicking the **Yes** button. + +## Create an Azure DevOps organization + +1. Open a browser, and navigate to the [Azure DevOps organization creation page](https://go.microsoft.com/fwlink/?LinkId=307137). +1. Select **New organization** +1. Confirm the information, and then select **Continue**. +1. Sign in to your organization at any time, `https://dev.azure.com/{yourorganization}` + +## Create a team project in Azure DevOps organization + +1. Choose the organization, and then select **New project**. +1. Enter the project name as *MyFirstProject* and select the **Visibility** as *Private* +1. Select **Create project**. + +For more information, see [Create a project](/azure/devops/organizations/projects/create-project?view=azure-devops&tabs=preview-page&preserve-view=true#create-a-project) + +## Configure a self-hosted agent if necessary + +To build your code or deploy your software using Azure Pipelines, you need at least one agent. In Azure Pipelines, you can run parallel jobs on either **Microsoft-hosted** or **self-hosted** agent. But with the recent change in Azure Pipelines free grant of parallel jobs is temporarily disable for the public projects.For more details, refer [Configure and pay for parallel jobs](/azure/devops/pipelines/licensing/concurrent-jobs?view=azure-devops&tabs=ms-hosted&preserve-view=true). + +Go to **Organization Settings** and then **Pipelines** > **Parallel jobs**. If you see value **0** under **Microsoft-hosted** that means you need a **Self-hosted** agent to run your pipeline. + +![MS-hosted agent](media/cicd/azure-devops-ms-hosted-agent.png) + +You can create that by following details mentioned in [Self-hosted agents](/azure/devops/pipelines/agents/agents?view=azure-devops&tabs=browser&preserve-view=true#install). After successful configuration, you'll be able to see available agent under **Organization Settings** > **Agent pools** > **{youragentname}** + +![Self-hosted agent](media/cicd/azure-devops-self-hosted-agent.png) + +## Configure the Azure Pipelines pipeline + +There are three distinct steps to complete. Completing the steps in the following three sections results in an operational DevOps pipeline. + +### Grant Azure DevOps access to the GitHub repository + +1. In your project, navigate to the **Pipelines** page. Then choose the action to create a new pipeline: + + ![Setup Build button](media/cicd/azure-devops-create-pipeline.png) + +1. Use `Use the classic editor` to create the pipeline. + + ![Use classic editor](media/cicd/azure-devops-classic-editor.png) + +1. Select the **GitHub** option from the **Select a source** section:: + + ![Select a source - GitHub](media/cicd/azure-devops-select-source.png) + +1. Authorization is required before Azure DevOps can access your GitHub repository. Enter * GitHub connection* in the **Connection name** textbox. For example: + + ![GitHub connection name](media/cicd/azure-devops-authz.png) + +1. If two-factor authentication is enabled on your GitHub account, a personal access token is required. In that case, click the **Authorize with a GitHub personal access token** link. See the [official GitHub personal access token creation instructions](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) for help. Only the *repo* scope of permissions is needed. Otherwise, click the **Authorize using OAuth** button. +1. When prompted, sign in to your GitHub account. Then select Authorize to grant access to your Azure DevOps organization. If successful, a new service endpoint is created. +1. Click the ellipsis button next to the **Repository** button. Select the */simple-feed-reader* repository from the list. Click the **Select** button. +1. Select the default branch (*main*) from the **Default branch for manual and scheduled builds** drop-down. Click the **Continue** button. The template selection page appears. + +### Create the build definition + +1. From the template selection page, enter *ASP.NET Core* in the search box: + + ![ASP.NET Core search on template page](media/cicd/azure-devops-template-selection.png) + +1. The template search results appear. Hover over the **ASP.NET Core** template, and click the **Apply** button. +1. The **Tasks** tab of the build definition appears. Select the self-hosted **Agent pool** if you have created that in the earlier step. + + ![Select Self-hosted agent pool](media/cicd/azure-devops-build-agent-pool.png) + + > [!NOTE] + > If you are using MS-hosted agent then select the *Hosted > Azure Pipelines* from drop down. + +1. Click the **Triggers** tab. +1. Check the **Enable continuous integration** box. Under the **Branch filters** section, confirm that the **Type** drop-down is set to *Include*. Set the **Branch specification** drop-down to *main*. + + ![Enable continuous integration settings](media/cicd/azure-devops-enable-ci.png) + + These settings cause a build to trigger when any change is pushed to the default branch (*main*) of the GitHub repository. Continuous integration is tested in the [Commit changes to GitHub and automatically deploy to Azure](#commit-changes-to-github-and-automatically-deploy-to-azure) section. + +1. Click the **Save & queue** button, and select the **Save** option: + + ![Save button](media/cicd/azure-devops-save-build.png) + +1. The following modal dialog appears: + + ![Save build definition - modal dialog](media/cicd/azure-devops-save-modal.png) + + Use the default folder of *\\*, and click the **Save** button. + +### Create the release pipeline + +1. Click the **Releases** tab of your team project. Click the **New pipeline** button. + + ![Releases tab - New definition button](media/cicd/azure-devops-create-release.png) + + The template selection pane appears. + +1. From the template selection page, enter *App Service Deployment* in the search box: + + ![Release pipeline template search box](media/cicd/azure-devops-select-template.png) + +1. The template search results appear. Hover over the **Azure App Service Deployment with Slot** template, and click the **Apply** button. The **Pipeline** tab of the release pipeline appears. + + ![Release pipeline Pipeline tab](media/cicd/azure-devops-new-release-pipeline.png) + +1. Click the **Add** button in the **Artifacts** box. The **Add artifact** panel appears: + + ![Release pipeline - Add artifact panel](media/cicd/azure-devops-release-add-artifacts.png) + +1. Select the **Build** tile from the **Source type** section. This type allows for the linking of the release pipeline to the build definition. +1. Select *MyFirstProject* from the **Project** drop-down. +1. Select the build definition name, *MyFirstProject-ASP.NET Core-CI*, from the **Source (Build definition)** drop-down. +1. Select *Latest* from the **Default version** drop-down. This option builds the artifacts produced by the latest run of the build definition. +1. Replace the text in the **Source alias** textbox with *Drop*. +1. Click the **Add** button. The **Artifacts** section updates to display the changes. +1. Click the lightning bolt icon to enable continuous deployments: + + ![Release pipeline Artifacts - lightning bolt icon](media/cicd/azure-devops-artifacts-lightning-bolt.png) + + With this option enabled, a deployment occurs each time a new build is available. +1. A **Continuous deployment trigger** panel appears to the right. Click the toggle button to enable the feature. It isn't necessary to enable the **Pull request trigger**. +1. Click the **Add** drop-down in the **Build branch filters** section. Choose the **Build Definition's default branch** option. This filter causes the release to trigger only for a build from the GitHub repository's default branch (*main*). +1. Click the **Save** button. Click the **OK** button in the resulting **Save** modal dialog. +1. Click the **Stage 1** box. An **Stage** panel appears to the right. Change the *Stage 1* text in the **Stage name** textbox to *Production*. + + ![Release pipeline - Stage name textbox](media/cicd/azure-devops-environment-name-textbox.png) + +1. Click the **1 phase, 2 tasks** link in the **Production** box: + + ![Release pipeline - Production environment link.png](media/cicd/azure-devops-production-link.png) + + The **Tasks** tab of the environment appears. +1. Click the **Deploy Azure App Service to Slot** task. Its settings appear in a panel to the right. +1. Select the Azure subscription associated with the App Service from the **Azure subscription** drop-down. Once selected, click the **Authorize** button. +1. Select *Web App* from the **App type** drop-down. +1. Select *mywebapp/* from the **App service name** drop-down. +1. Select *AzureTutorial* from the **Resource group** drop-down. +1. Select *staging* from the **Slot** drop-down. +1. Select **Run on agent*** under **Tasks**. On the right pane, you'll see **Agent Job**. +1. Select the self-hosted **Agent pool** if you have created that in the earlier step. + + ![Select Self-hosted agent](media/cicd/azure-devops-release-select-agent-pool.png) + + > [!NOTE] + > If you are using MS-hosted agent then select the *Hosted > Azure Pipelines* from drop down. + +1. Click the **Save** button. +1. Hover over the default release pipeline name. Click the pencil icon to edit it. Use *MyFirstProject-ASP.NET Core-CD* as the name. + + ![Release pipeline name](media/cicd/azure-devops-release-definition-name.png) + +1. Click the **Save** button. + +## Commit changes to GitHub and automatically deploy to Azure + +1. Open *SimpleFeedReader.sln* in Visual Studio. +1. In Solution Explorer, open *Pages\Index.cshtml*. Change `

Simple Feed Reader - V3

` to `

Simple Feed Reader - V4

`. +1. Press **Ctrl**+**Shift**+**B** to build the app. +1. Commit the file to the GitHub repository. Use either the **Changes** page in Visual Studio's *Team Explorer* tab, or execute the following using the local machine's command shell: + + ```console + git commit -a -m "upgraded to V4" + ``` + +1. Push the change in the default branch (*main*) to the *origin* remote of your GitHub repository. In the following command, replace the placeholder `{BRANCH}` with the default branch (use `main`): + + ```console + git push origin {BRANCH} + ``` + + The commit appears in the GitHub repository's default branch (*main*). You'll be able to see the commit history in `https://github.com//simple-feed-reader/commits/main`. + + The build is triggered, since continuous integration is enabled in the build definition's **Triggers** tab: + + ![enable continuous integration](media/cicd/enable-ci.png) + +1. Navigate to the **Pipelines**. You'll see the CI pipeline details and monitor each steps if you drill down **Jobs** details. + + ![Trigger build pipeline](media/cicd/azure-devops-pipepine-build.png) + +1. Similarly, go to the **Releases** tab to see the details of CD pipeline. You can always drill down further to see more details of each step. + + ![Release pipeline](media/cicd/azure-devops-release-pipeline-run.png) + +1. Once the build succeeds, a deployment to Azure occurs. Navigate to the app in the browser. Notice that the "V4" text appears in the heading: + + ![updated app](media/cicd/updated-app-v4.png) + +## Examine the Azure Pipelines pipeline + +### Build definition + +A build definition was created with the name *MyFirstProject-ASP.NET Core-CI*. Upon completion, the build produces a *.zip* file including the assets to be published. The release pipeline deploys those assets to Azure. + +The build definition's **Tasks** tab lists the individual steps being used. There are five build tasks. + +![build definition tasks](media/cicd/azure-devops-build-definition-tasks.png) + +1. **Restore** — Executes the `dotnet restore` command to restore the app's NuGet packages. The default package feed used is nuget.org. +1. **Build** — Executes the `dotnet build --configuration release` command to compile the app's code. This `--configuration` option is used to produce an optimized version of the code, which is suitable for deployment to a production environment. Modify the *BuildConfiguration* variable on the build definition's **Variables** tab if, for example, a debug configuration is needed. +1. **Test** — Executes the `dotnet test --configuration release --logger trx --results-directory ` command to run the app's unit tests. Unit tests are executed within any C# project matching the ***/*Tests/*.csproj* glob pattern. Test results are saved in a *.trx* file at the location specified by the `--results-directory` option. If any tests fail, the build fails and isn't deployed. + + > [!NOTE] + > To verify the unit tests work, modify *SimpleFeedReader.Tests\Services\NewsServiceTests.cs* to purposefully break one of the tests. For example, change `Assert.True(result.Count > 0);` to `Assert.False(result.Count > 0);` in the `Returns_News_Stories_Given_Valid_Uri` method. Commit and push the change to GitHub. The build is triggered and fails. The build pipeline status changes to **failed**. Revert the change, commit, and push again. The build succeeds. + +1. **Publish** — Executes the `dotnet publish --configuration release --output ` command to produce a *.zip* file with the artifacts to be deployed. The `--output` option specifies the publish location of the *.zip* file. That location is specified by passing a [predefined variable](/azure/devops/pipelines/build/variables) named `$(build.artifactstagingdirectory)`. That variable expands to a local path, such as *c:\agent\_work\1\a*, on the build agent. +1. **Publish Artifact** — Publishes the *.zip* file produced by the **Publish** task. The task accepts the *.zip* file location as a parameter, which is the predefined variable `$(build.artifactstagingdirectory)`. The *.zip* file is published as a folder named *drop*. + +Click the build definition's **Summary** link to view a history of builds with the definition: + +![Screenshot showing build definition history](media/cicd/build-definition-summary.png) + +On the resulting page, click the individual build for more details. + +![Screenshot showing build definition summary page](media/cicd/azure-devops-build-definition-summary.png) + +A summary of this specific build is displayed. Click the **published** link, and notice the *drop* folder produced by the build is listed: + +![Screenshot showing build definition artifacts - drop folder](media/cicd/azure-devops-build-artifacts.png) + +![Build Artifacts](media/cicd/azure-devops-artifacts.png) + +Use the ellipsis and click on **Downloads artifacts** links to inspect the published artifacts. + +### Release pipeline + +A release pipeline was created with the name *MyFirstProject-ASP.NET Core-CD*: + +![Screenshot showing release pipeline overview](media/cicd/azure-devops-release-pipeline.png) + +The two major components of the release pipeline are the **Artifacts** and the **Stages**. Clicking the box in the **Artifacts** section reveals the following panel: + +![Screenshot showing release pipeline artifacts](media/cicd/azure-devops-release-definition-tasks.png) + +The **Source (Build definition)** value represents the build definition to which this release pipeline is linked. The *.zip* file produced by a successful run of the build definition is provided to the *Production* environment for deployment to Azure. Click the *1 phase, 2 tasks* link in the *Production* environment box to view the release pipeline tasks: + +![Screenshot showing release pipeline tasks](media/cicd/release-definition-tasks.png) + +The release pipeline consists of two tasks: *Deploy Azure App Service to Slot* and *Manage Azure App Service - Slot Swap*. Clicking the first task reveals the following task configuration: + +![Screenshot showing release pipeline tasks](media/cicd/release-definition-tasks.png) + +The Azure subscription, service type, web app name, resource group, and deployment slot are defined in the deployment task. The **Package or folder** textbox holds the *.zip* file path to be extracted and deployed to the *staging* slot of the *mywebapp\* web app. + +Clicking the slot swap task reveals the following task configuration: + +![Screenshot showing release pipeline slot swap task](media/cicd/release-definition-task2.png) + +The subscription, resource group, service type, web app name, and deployment slot details are provided. The **Swap with Production** check box is checked. Consequently, the bits deployed to the *staging* slot are swapped into the production environment. + +## Additional reading + +* [Create your first pipeline with Azure Pipelines](/azure/devops/pipelines/get-started-yaml) +* [Build and .NET Core project](/azure/devops/pipelines/languages/dotnet-core) +* [Deploy a web app with Azure Pipelines](/azure/devops/pipelines/targets/webapp) + +>[!div class="step-by-step"] +>[Previous](deploying-to-app-service.md) +>[Next](actions-index.md) diff --git a/docs/architecture/devops-for-aspnet-developers/deploying-to-app-service.md b/docs/architecture/devops-for-aspnet-developers/deploying-to-app-service.md new file mode 100644 index 0000000000000..1c9293dab3371 --- /dev/null +++ b/docs/architecture/devops-for-aspnet-developers/deploying-to-app-service.md @@ -0,0 +1,261 @@ +--- +title: Deploy an app to App Service - DevOps for ASP.NET Core Developers +author: CamSoper +description: Deploy an ASP.NET Core app to Azure App Service, the first step for DevOps for ASP.NET Core Developers. +ms.author: casoper +ms.custom: "devx-track-csharp, mvc, seodec18, devx-track-azurecli" +ms.date: 10/24/2018 +no-loc: [appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR] +uid: azure/devops/deploy-to-app-service +--- +# Deploy an app to App Service + +[Azure App Service](/azure/app-service/) is Azure's web hosting platform. Deploying a web app to Azure App Service can be done manually or by an automated process. This section of the guide discusses deployment methods that can be triggered manually or by script using the command line, or triggered manually using Visual Studio. + +In this section, you'll accomplish the following tasks: + +> [!div class="checklist"] +> +> * Download and build the sample app. +> * Create an Azure App Service Web App using the Azure Cloud Shell. +> * Deploy the sample app to Azure using Git. +> * Deploy a change to the app using Visual Studio. +> * Add a staging slot to the web app. +> * Deploy an update to the staging slot. +> * Swap the staging and production slots. + +## Download and test the app + +The app used in this guide is a pre-built ASP.NET Core app, [Simple Feed Reader](https://github.com/dotnet-architecture/simple-feed-reader/). It's an ASP.NET Core Razor Pages app that uses the `Microsoft.SyndicationFeed.ReaderWriter` API to retrieve an RSS/Atom feed and display the news items in a list. + +Feel free to review the code, but it's important to understand that there's nothing special about this app. It's just a simple ASP.NET Core app for illustrative purposes. + +From a command shell, download the code, build the project, and run it as follows. + +> [!Note] +> Linux/macOS users should make appropriate changes for paths, e.g., using forward slash (`/`) rather than back slash (`\`).* + +1. Clone the code to a folder on your local machine. + + ```console + git clone https://github.com/dotnet-architecture/simple-feed-reader/ + ``` + +2. Change your working folder to the *simple-feed-reader* folder that was created. + + ```console + cd .\simple-feed-reader\SimpleFeedReader + ``` + +3. Restore the packages, and build the solution. + + ```dotnetcli + dotnet build + ``` + +4. Run the app. + + ```dotnetcli + dotnet run + ``` + + ![The dotnet run command is successful](./media/deploying-to-app-service/dotnet-run.png) + +5. Open a browser and navigate to `http://localhost:5000`. The app allows you to type or paste a syndication feed URL and view a list of news items. + + ![The app displaying the contents of an RSS feed](./media/deploying-to-app-service/app-in-browser.png) + +6. Once you're satisfied the app is working correctly, shut it down by pressing **Ctrl**+**C** in the command shell. + +## Create the Azure App Service Web App + +To deploy the app, you'll need to create an App Service [Web App](/azure/app-service/app-service-web-overview). After creation of the Web App, you'll deploy to it from your local machine using Git. + +1. Sign in to the [Azure Cloud Shell](https://shell.azure.com/bash). Note: When you sign in for the first time, Cloud Shell prompts to create a storage account for configuration files. Accept the defaults or provide a unique name. + +2. Use the Cloud Shell for the following steps. + + a. Declare a variable to store your web app's name. The name must be unique to be used in the default URL. Using the `$RANDOM` Bash function to construct the name guarantees uniqueness and results in the format `webappname99999`. + + ```console + webappname=mywebapp$RANDOM + ``` + + b. Create a resource group. Resource groups provide a means to aggregate Azure resources to be managed as a group. + + ```azurecli + az group create --location centralus --name AzureTutorial + ``` + + The `az` command invokes the [Azure CLI](/cli/azure/). The CLI can be run locally, but using it in the Cloud Shell saves time and configuration. + + c. Create an App Service plan in the S1 tier. An App Service plan is a grouping of web apps that share the same pricing tier. The S1 tier isn't free, but it's required for the staging slots feature. + + ```azurecli + az appservice plan create --name $webappname --resource-group AzureTutorial --sku S1 + ``` + + d. Create the web app resource using the App Service plan in the same resource group. + + ```azurecli + az webapp create --name $webappname --resource-group AzureTutorial --plan $webappname + ``` + + e. Set the deployment branch to `main` in the `appsettings` configuration. + + ```azurecli + az webapp config appsettings set --name $webappname --resource-group AzureTutorial --settings DEPLOYMENT_BRANCH=main + ``` + + f. Set the deployment credentials. These deployment credentials apply to all the web apps in your subscription. Don't use special characters in the user name. + + ```azurecli + az webapp deployment user set --user-name REPLACE_WITH_USER_NAME --password REPLACE_WITH_PASSWORD + ``` + + g. Configure the web app to accept deployments from local Git and display the *Git deployment URL*. **Note this URL for reference later**. + + ```azurecli + echo Git deployment URL: $(az webapp deployment source config-local-git --name $webappname --resource-group AzureTutorial --query url --output tsv) + ``` + + h. Display the *web app URL*. Browse to this URL to see the blank web app. **Note this URL for reference later**. + + ```console + echo Web app URL: http://$webappname.azurewebsites.net + ``` + +3. Using a command shell on your local machine, navigate to the web app's project folder (for example, *.\simple-feed-reader\SimpleFeedReader*). Execute the following commands to set up Git to push to the deployment URL: + + a. Add the remote URL to the local repository. + + ```console + git remote add azure-prod GIT_DEPLOYMENT_URL + ``` + + b. Push the local default branch (*main*) to the *azure-prod* remote's deployment branch (*main*). + + ```console + git push azure-prod main + ``` + + You'll be prompted for the deployment credentials you created earlier. Observe the output in the command shell. Azure builds the ASP.NET Core app remotely. + +4. In a browser, navigate to the *Web app URL* and note the app has been built and deployed. Additional changes can be committed to the local Git repository with `git commit`. These changes are pushed to Azure with the preceding `git push` command. + +## Deployment with Visual Studio + +> [!Note] +> This section applies to Windows only. Linux and macOS users should make the change described in step 2 below. Save the file, and commit the change to the local repository with `git commit`. Finally, push the change with `git push`, as in the first section.* + +The app has already been deployed from the command shell. Let's use Visual Studio's integrated tools to deploy an update to the app. Behind the scenes, Visual Studio accomplishes the same thing as the command line tooling, but within Visual Studio's familiar UI. + +1. Open *SimpleFeedReader.sln* in Visual Studio. +2. In Solution Explorer, open *Pages\Index.cshtml*. Change `

Simple Feed Reader

` to `

Simple Feed Reader - V2

`. +3. Press **Ctrl**+**Shift**+**B** to build the app. +4. In Solution Explorer, right-click on the project and click **Publish**. + + ![Screenshot showing Right-click, Publish](./media/deploying-to-app-service/publish.png) +5. Visual Studio can create a new App Service resource, but this update will be published over the existing deployment. In the **Pick a publish target** dialog, select **App Service** from the list on the left, and then select **Select Existing**. Click **Publish**. +6. In the **App Service** dialog, confirm that the Microsoft or Organizational account used to create your Azure subscription is displayed in the upper right. If it's not, click the drop-down and add it. +7. Confirm that the correct Azure **Subscription** is selected. For **View**, select **Resource Group**. Expand the **AzureTutorial** resource group and then select the existing web app. Click **OK**. + + ![Screenshot showing Publish App Service dialog](./media/deploying-to-app-service/publish-dialog.png) + +Visual Studio builds and deploys the app to Azure. Browse to the web app URL. Validate that the `

` element modification is live. + +![The app with the changed title](./media/deploying-to-app-service/app-v2.png) + +## Deployment slots + +Deployment slots support the staging of changes without impacting the app running in production. Once the staged version of the app is validated by a quality assurance team, the production and staging slots can be swapped. The app in staging is promoted to production in this manner. The following steps create a staging slot, deploy some changes to it, and swap the staging slot with production after verification. + +1. Sign in to the [Azure Cloud Shell](https://shell.azure.com/bash), if not already signed in. +2. Create the staging slot. + + a. Create a deployment slot with the name *staging*. + + ```azurecli + az webapp deployment slot create --name $webappname --resource-group AzureTutorial --slot staging + ``` + + b. Set the deployment branch to `main` in the `appsettings` configuration. + + ```azurecli + az webapp config appsettings set --name $webappname --resource-group AzureTutorial --slot staging --settings DEPLOYMENT_BRANCH=main + ``` + + c. Configure the staging slot to use deployment from local Git and get the **staging** deployment URL. **Note this URL for reference later**. + + ```azurecli + echo Git deployment URL for staging: $(az webapp deployment source config-local-git --name $webappname --resource-group AzureTutorial --slot staging --query url --output tsv) + ``` + + d. Display the staging slot's URL. Browse to the URL to see the empty staging slot. **Note this URL for reference later**. + + ```console + echo Staging web app URL: http://$webappname-staging.azurewebsites.net + ``` + +3. In a text editor or Visual Studio, modify *Pages/Index.cshtml* again so that the `

` element reads `

Simple Feed Reader - V3

` and save the file. + +4. Commit the file to the local Git repository, using either the **Changes** page in Visual Studio's *Team Explorer* tab, or by entering the following using the local machine's command shell: + + ```console + git commit -a -m "upgraded to V3" + ``` + +5. Using the local machine's command shell, add the staging deployment URL as a Git remote and push the committed changes: + + a. Add the remote URL for staging to the local Git repository. + + ```console + git remote add azure-staging + ``` + + b. Push the local default branch (*main*) to the *azure-staging* remote's deployment branch (*main*). + + ```console + git push azure-staging main + ``` + + Wait while Azure builds and deploys the app. + +6. To verify that V3 has been deployed to the staging slot, open two browser windows. In one window, navigate to the original web app URL. In the other window, navigate to the staging web app URL. The production URL serves V2 of the app. The staging URL serves V3 of the app. + + ![Screenshot comparing the browser windows](./media/deploying-to-app-service/ready-to-swap.png) + +7. In the Cloud Shell, swap the verified/warmed-up staging slot into production. + + ```azurecli + az webapp deployment slot swap --name $webappname --resource-group AzureTutorial --slot staging + ``` + +8. Verify that the swap occurred by refreshing the two browser windows. + + ![Comparing the browser windows after the swap](./media/deploying-to-app-service/swapped.png) + +## Summary + +In this section, the following tasks were completed: + +* Downloaded and built the sample app. +* Created an Azure App Service Web App using the Azure Cloud Shell. +* Deployed the sample app to Azure using Git. +* Deployed a change to the app using Visual Studio. +* Added a staging slot to the web app. +* Deployed an update to the staging slot. +* Swapped the staging and production slots. + +In the next section, you'll learn how to build a DevOps pipeline with Azure Pipelines. + +## Additional reading + +* [Web Apps overview](/azure/app-service/app-service-web-overview) +* [Build a .NET Core and SQL Database web app in Azure App Service](/azure/app-service/tutorial-dotnetcore-sqldb-app) +* [Configure deployment credentials for Azure App Service](/azure/app-service/app-service-deployment-credentials) +* [Set up staging environments in Azure App Service](/azure/app-service/web-sites-staged-publishing) + +>[!div class="step-by-step"] +>[Previous](tools-and-downloads.md) +>[Next](cicd.md) diff --git a/docs/architecture/devops-for-aspnet-developers/index.md b/docs/architecture/devops-for-aspnet-developers/index.md new file mode 100644 index 0000000000000..67a790dc60631 --- /dev/null +++ b/docs/architecture/devops-for-aspnet-developers/index.md @@ -0,0 +1,107 @@ +--- +title: DevOps for ASP.NET Core Developers +author: CamSoper +description: A guide that provides end-to-end guidance on building a DevOps pipeline for an ASP.NET Core app hosted in Azure. +ms.author: casoper +ms.date: 04/13/2021 +ms.custom: "devx-track-csharp, mvc, seodec18" +no-loc: [appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR] +uid: azure/devops/index +--- +# DevOps for ASP.NET Core Developers + +[![Cover Image](./media/cover-large.png)](https://aka.ms/devopsbook) + +**EDITION v1.1.0** + +Refer [changelog](https://aka.ms/devops-ebook-changelog) for the book updates and community contributions. + +This guide is available as a [downloadable PDF e-book](https://aka.ms/devopsbook). + +PUBLISHED BY + +Microsoft Developer Division, .NET, and Visual Studio product teams + +A division of Microsoft Corporation + +One Microsoft Way + +Redmond, Washington 98052-6399 + +Copyright © 2021 by Microsoft Corporation + +All rights reserved. No part of the contents of this book may be reproduced or transmitted in any form or by any means without the written permission of the publisher. + +This book is provided "as-is" and expresses the author's views and opinions. The views, opinions, and information expressed in this book, including URL and other Internet website references, may change without notice. + +Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred. + +Microsoft and the trademarks listed at on the "Trademarks" webpage are trademarks of the Microsoft group of companies. + +Mac and macOS are trademarks of Apple Inc. + +The Docker whale logo is a registered trademark of Docker, Inc. Used by permission. + +All other marks and logos are property of their respective owners. + +## Credits + +Authors: + +> [Cam Soper](https://twitter.com/camsoper) +> +> [Scott Addie](https://twitter.com/scottaddie) +> +> [Colin Dembovsky](https://twitter.com/colindembovsky) + +## Welcome + +Welcome to the Azure Development Lifecycle guide for .NET! This guide introduces the basic concepts of building a development lifecycle around Azure using .NET tools and processes. After finishing this guide, you'll reap the benefits of a mature DevOps toolchain. + +## Who this guide is for + +You should be an experienced ASP.NET Core developer (200-300 level). You don't need to know anything about Azure, as we'll cover that in this introduction. This guide may also be useful for DevOps engineers who are more focused on operations than development. + +This guide targets Windows developers. However, Linux and macOS are fully supported by .NET Core. To adapt this guide for Linux/macOS, watch for callouts for Linux/macOS differences. + +## What this guide doesn't cover + +This guide is focused on an end-to-end continuous deployment experience for .NET developers. It's not an exhaustive guide to all things Azure, and it doesn't focus extensively on .NET APIs for Azure services. The emphasis is all around continuous integration, deployment, monitoring, and debugging. Near the end of the guide, recommendations for next steps are offered. Included in the suggestions are Azure platform services that are useful to ASP.NET Core developers. + +## What's in this guide + +### [Tools and downloads](xref:azure/devops/tools-and-downloads) + +Learn where to acquire the tools used in this guide. + +### [Deploy to App Service](xref:azure/devops/deploy-to-app-service) + +Learn the various methods for deploying an ASP.NET Core app to Azure App Service. + +### [Continuous integration and deployment with Azure DevOps](xref:azure/devops/cicd) + +Build an end-to-end continuous integration and deployment solution for your ASP.NET Core app with GitHub, Azure DevOps Services, and Azure. + +### [Continuous integration and deployment with GitHub Actions](xref:azure/devops/github-actions) + +Build an end-to-end continuous integration and deployment solution for your ASP.NET Core app with GitHub, GitHub Actions, and Azure, including code scanning for security and quality using CodeQL. + +### [Monitor and debug](xref:azure/devops/monitor) + +Use Azure's tools to monitor, troubleshoot, and tune your application. + +### [Next steps](xref:azure/devops/next-steps) + +Other learning paths for the ASP.NET Core developer learning Azure. + +## Additional introductory reading + +If this is your first exposure to cloud computing, these articles explain the basics. + +* [What is Cloud Computing?](https://azure.microsoft.com/overview/what-is-cloud-computing/) +* [Examples of Cloud Computing](https://azure.microsoft.com/overview/examples-of-cloud-computing/) +* [What is IaaS?](https://azure.microsoft.com/overview/what-is-iaas/) +* [What is PaaS?](https://azure.microsoft.com/overview/what-is-paas/) + +>[!div class="step-by-step"] +>[Next](tools-and-downloads.md) diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/build/build-action-success-logs.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/build/build-action-success-logs.jpg new file mode 100644 index 0000000000000..9a9bf69c406cb Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/build/build-action-success-logs.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/build/build-action-success.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/build/build-action-success.jpg new file mode 100644 index 0000000000000..ce2c63da72ecc Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/build/build-action-success.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/build/click-edit.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/build/click-edit.jpg new file mode 100644 index 0000000000000..679807e767738 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/build/click-edit.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/build/commit-workflow.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/build/commit-workflow.jpg new file mode 100644 index 0000000000000..0f333eff5fab4 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/build/commit-workflow.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/build/copy-snippet.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/build/copy-snippet.jpg new file mode 100644 index 0000000000000..243aae76e328e Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/build/copy-snippet.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/build/new-action.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/build/new-action.jpg new file mode 100644 index 0000000000000..a3a5fce20afc3 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/build/new-action.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/build/search-upload-artifact.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/build/search-upload-artifact.jpg new file mode 100644 index 0000000000000..de7618cc2dfec Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/build/search-upload-artifact.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/build/view-uploaded-artifact.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/build/view-uploaded-artifact.jpg new file mode 100644 index 0000000000000..3ef8255a9e49c Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/build/view-uploaded-artifact.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/alert.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/alert.jpg new file mode 100644 index 0000000000000..9ebbec9af3429 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/alert.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/codeql-config.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/codeql-config.jpg new file mode 100644 index 0000000000000..49966cd27958a Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/codeql-config.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/codeql-run.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/codeql-run.jpg new file mode 100644 index 0000000000000..2ca7f8d5e9ab3 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/codeql-run.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/create-new-file.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/create-new-file.jpg new file mode 100644 index 0000000000000..4c82696349566 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/create-new-file.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/dismiss.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/dismiss.jpg new file mode 100644 index 0000000000000..020201158b5cd Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/dismiss.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/no-results.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/no-results.jpg new file mode 100644 index 0000000000000..d3d70984d3b5a Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/no-results.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/security-alerts.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/security-alerts.jpg new file mode 100644 index 0000000000000..b6fe346171311 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/security-alerts.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/setup-workflow.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/setup-workflow.jpg new file mode 100644 index 0000000000000..5cb1d432e4f6d Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/setup-workflow.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/start-commit.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/start-commit.jpg new file mode 100644 index 0000000000000..e21082cd0c3e3 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/codeql/start-commit.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/add-env-secret.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/add-env-secret.jpg new file mode 100644 index 0000000000000..759a4bb7e1957 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/add-env-secret.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/add-repo-secret.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/add-repo-secret.jpg new file mode 100644 index 0000000000000..62ae491540b4d Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/add-repo-secret.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/approval.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/approval.jpg new file mode 100644 index 0000000000000..26a4fde4942e9 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/approval.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/azure-credentials.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/azure-credentials.jpg new file mode 100644 index 0000000000000..e70d012bbc265 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/azure-credentials.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/deploy-to-staging-completed.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/deploy-to-staging-completed.jpg new file mode 100644 index 0000000000000..555c977a2a1b1 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/deploy-to-staging-completed.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/deployed-to-prod.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/deployed-to-prod.jpg new file mode 100644 index 0000000000000..7de4c9a8421ae Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/deployed-to-prod.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/deployed-to-staging.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/deployed-to-staging.jpg new file mode 100644 index 0000000000000..6acf67cc3b51d Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/deployed-to-staging.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/deployments.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/deployments.jpg new file mode 100644 index 0000000000000..fc5bd96002a26 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/deployments.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/env-protection-rule.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/env-protection-rule.jpg new file mode 100644 index 0000000000000..746ccaae3a7d7 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/env-protection-rule.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/env-secrets.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/env-secrets.jpg new file mode 100644 index 0000000000000..a8a4e308280ce Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/env-secrets.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/manual-dispatch.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/manual-dispatch.jpg new file mode 100644 index 0000000000000..57c622a844a0c Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/manual-dispatch.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/new-env.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/new-env.jpg new file mode 100644 index 0000000000000..1cfdf9f3c281d Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/new-env.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/pre-prod-env.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/pre-prod-env.jpg new file mode 100644 index 0000000000000..7a7ae63825ffc Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/pre-prod-env.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/prod-deploy-complete.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/prod-deploy-complete.jpg new file mode 100644 index 0000000000000..5db34cafb6885 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/prod-deploy-complete.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/settings-in-both-envs.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/settings-in-both-envs.jpg new file mode 100644 index 0000000000000..e2cb6b489a843 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/settings-in-both-envs.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/waiting-for-approval.jpg b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/waiting-for-approval.jpg new file mode 100644 index 0000000000000..f501a357eef56 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/actions/deploy/waiting-for-approval.jpg differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-artifacts-lightning-bolt.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-artifacts-lightning-bolt.png new file mode 100644 index 0000000000000..97392e4765493 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-artifacts-lightning-bolt.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-artifacts.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-artifacts.png new file mode 100644 index 0000000000000..a4db47d2c042a Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-artifacts.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-authz.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-authz.png new file mode 100644 index 0000000000000..564ea8d1a989e Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-authz.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-build-agent-pool.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-build-agent-pool.png new file mode 100644 index 0000000000000..ad8712bdc13d6 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-build-agent-pool.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-build-artifacts.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-build-artifacts.png new file mode 100644 index 0000000000000..6e5871a48de8b Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-build-artifacts.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-build-definition-summary.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-build-definition-summary.png new file mode 100644 index 0000000000000..e047018202f5b Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-build-definition-summary.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-build-definition-tasks.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-build-definition-tasks.png new file mode 100644 index 0000000000000..2e133717f040f Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-build-definition-tasks.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-classic-editor.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-classic-editor.png new file mode 100644 index 0000000000000..a78f7538cf010 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-classic-editor.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-create-pipeline.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-create-pipeline.png new file mode 100644 index 0000000000000..c41904a3e4c97 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-create-pipeline.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-create-release.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-create-release.png new file mode 100644 index 0000000000000..18853e97fb3e5 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-create-release.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-enable-ci.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-enable-ci.png new file mode 100644 index 0000000000000..e1868eeb68155 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-enable-ci.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-environment-name-textbox.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-environment-name-textbox.png new file mode 100644 index 0000000000000..f14ece36fb47a Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-environment-name-textbox.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-ms-hosted-agent.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-ms-hosted-agent.png new file mode 100644 index 0000000000000..a6e9d185621a1 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-ms-hosted-agent.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-new-release-pipeline.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-new-release-pipeline.png new file mode 100644 index 0000000000000..d0451f845173e Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-new-release-pipeline.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-pipepine-build.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-pipepine-build.png new file mode 100644 index 0000000000000..9fa38586a29ee Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-pipepine-build.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-production-link.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-production-link.png new file mode 100644 index 0000000000000..94a8c8344d239 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-production-link.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-add-artifacts.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-add-artifacts.png new file mode 100644 index 0000000000000..509a391b97739 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-add-artifacts.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-definition-name.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-definition-name.png new file mode 100644 index 0000000000000..953e501f198b6 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-definition-name.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-definition-tasks.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-definition-tasks.png new file mode 100644 index 0000000000000..4d4ebbda82ce0 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-definition-tasks.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-pipeline-run.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-pipeline-run.png new file mode 100644 index 0000000000000..d5b5e7f7a7f8b Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-pipeline-run.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-pipeline.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-pipeline.png new file mode 100644 index 0000000000000..47de90f08bf4c Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-pipeline.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-select-agent-pool.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-select-agent-pool.png new file mode 100644 index 0000000000000..1cd57a670b3fa Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-release-select-agent-pool.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-save-build.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-save-build.png new file mode 100644 index 0000000000000..3ab7389d58305 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-save-build.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-save-modal.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-save-modal.png new file mode 100644 index 0000000000000..a9a1ef012b67e Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-save-modal.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-select-source.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-select-source.png new file mode 100644 index 0000000000000..4954c126022ee Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-select-source.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-select-template.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-select-template.png new file mode 100644 index 0000000000000..82de216e3cc84 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-select-template.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-self-hosted-agent.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-self-hosted-agent.png new file mode 100644 index 0000000000000..63623efb6c52f Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-self-hosted-agent.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-template-selection.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-template-selection.png new file mode 100644 index 0000000000000..3113a3ac32f34 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/azure-devops-template-selection.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/build-definition-summary.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/build-definition-summary.png new file mode 100644 index 0000000000000..2aa572e6cc695 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/build-definition-summary.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/enable-ci.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/enable-ci.png new file mode 100644 index 0000000000000..158a3a0545cd4 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/enable-ci.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/github-new-repo.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/github-new-repo.png new file mode 100644 index 0000000000000..b2fcaf5624221 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/github-new-repo.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/portal-search-box.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/portal-search-box.png new file mode 100644 index 0000000000000..028d7ec92fba2 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/portal-search-box.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/release-definition-task2.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/release-definition-task2.png new file mode 100644 index 0000000000000..e2372d7a569ff Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/release-definition-task2.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/release-definition-tasks.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/release-definition-tasks.png new file mode 100644 index 0000000000000..491be934bc277 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/release-definition-tasks.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cicd/updated-app-v4.png b/docs/architecture/devops-for-aspnet-developers/media/cicd/updated-app-v4.png new file mode 100644 index 0000000000000..365c31a0c3d3d Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cicd/updated-app-v4.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/cover-large.png b/docs/architecture/devops-for-aspnet-developers/media/cover-large.png new file mode 100644 index 0000000000000..7929e7a272537 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/cover-large.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/app-in-browser.png b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/app-in-browser.png new file mode 100644 index 0000000000000..1dc62dffbdcc8 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/app-in-browser.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/app-v2.png b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/app-v2.png new file mode 100644 index 0000000000000..db070ad92ba3a Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/app-v2.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/dotnet-run.png b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/dotnet-run.png new file mode 100644 index 0000000000000..36655be17901d Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/dotnet-run.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/publish-dialog.png b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/publish-dialog.png new file mode 100644 index 0000000000000..9783ebbdfd837 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/publish-dialog.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/publish.png b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/publish.png new file mode 100644 index 0000000000000..8b301f1a8fda2 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/publish.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/ready-to-swap.png b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/ready-to-swap.png new file mode 100644 index 0000000000000..779597416302b Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/ready-to-swap.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/swapped.png b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/swapped.png new file mode 100644 index 0000000000000..37f8b86915a39 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/deploying-to-app-service/swapped.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/monitoring/alerts.png b/docs/architecture/devops-for-aspnet-developers/media/monitoring/alerts.png new file mode 100644 index 0000000000000..4f1038605acd0 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/monitoring/alerts.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/monitoring/app-insights-overview.png b/docs/architecture/devops-for-aspnet-developers/media/monitoring/app-insights-overview.png new file mode 100644 index 0000000000000..7b22035bf5007 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/monitoring/app-insights-overview.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/monitoring/app-insights.png b/docs/architecture/devops-for-aspnet-developers/media/monitoring/app-insights.png new file mode 100644 index 0000000000000..12434a0964ee9 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/monitoring/app-insights.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/monitoring/log-stream.png b/docs/architecture/devops-for-aspnet-developers/media/monitoring/log-stream.png new file mode 100644 index 0000000000000..b65ab37053233 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/monitoring/log-stream.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/monitoring/logging.png b/docs/architecture/devops-for-aspnet-developers/media/monitoring/logging.png new file mode 100644 index 0000000000000..cec2f4b2ad68f Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/monitoring/logging.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/monitoring/new-app-insights-done.png b/docs/architecture/devops-for-aspnet-developers/media/monitoring/new-app-insights-done.png new file mode 100644 index 0000000000000..d208be06bcf8f Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/monitoring/new-app-insights-done.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/monitoring/new-app-insights.png b/docs/architecture/devops-for-aspnet-developers/media/monitoring/new-app-insights.png new file mode 100644 index 0000000000000..9cf9222902318 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/monitoring/new-app-insights.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/monitoring/overview.png b/docs/architecture/devops-for-aspnet-developers/media/monitoring/overview.png new file mode 100644 index 0000000000000..2589c1dc57cc1 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/monitoring/overview.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/media/monitoring/wizards.png b/docs/architecture/devops-for-aspnet-developers/media/monitoring/wizards.png new file mode 100644 index 0000000000000..6bc4e4c92b956 Binary files /dev/null and b/docs/architecture/devops-for-aspnet-developers/media/monitoring/wizards.png differ diff --git a/docs/architecture/devops-for-aspnet-developers/monitoring.md b/docs/architecture/devops-for-aspnet-developers/monitoring.md new file mode 100644 index 0000000000000..b37512f591803 --- /dev/null +++ b/docs/architecture/devops-for-aspnet-developers/monitoring.md @@ -0,0 +1,147 @@ +--- +title: Monitor and debug - DevOps for ASP.NET Core Developers +author: CamSoper +description: Monitoring and debugging your code as part of a DevOps solution with ASP.NET Core and Azure +ms.author: casoper +ms.custom: "devx-track-csharp, mvc, seodec18" +ms.date: 07/10/2019 +no-loc: [appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR] +uid: azure/devops/monitor +--- +# Monitor and debug + +Having deployed the app and built a DevOps pipeline, it's important to understand how to monitor and troubleshoot the app. + +In this section, you'll complete the following tasks: + +> [!div class="checklist"] +> +> * Find basic monitoring and troubleshooting data in the Azure portal +> * Learn how Azure Monitor provides a deeper look at metrics across all Azure services +> * Connect the web app with Application Insights for app profiling +> * Turn on logging and learn where to download logs +> * Stream logs in real time +> * Learn where to set up alerts +> * Learn about remote debugging Azure App Service web apps. + +## Basic monitoring and troubleshooting + +App Service web apps are easily monitored in real time. The Azure portal renders metrics in easy-to-understand charts and graphs. + +1. Open the [Azure portal](https://portal.azure.com), and then navigate to the *mywebapp\* App Service. + +1. The **Overview** tab displays useful "at-a-glance" information, including graphs displaying recent metrics. + + ![Screenshot showing overview panel](./media/monitoring/overview.png) + + * **Http 5xx**: Count of server-side errors, usually exceptions in ASP.NET Core code. + * **Data In**: Data ingress coming into your web app. + * **Data Out**: Data egress from your web app to clients. + * **Requests**: Count of HTTP requests. + * **Average Response Time**: Average time for the web app to respond to HTTP requests. + + Several self-service tools for troubleshooting and optimization are also found on this page. + + ![Screenshot showing self-service tools](./media/monitoring/wizards.png) + + * **Diagnose and solve problems** is a self-service troubleshooter. + * **Application Insights** is for profiling performance and app behavior, and is discussed later in this section. + * **App Service Advisor** makes recommendations to tune your app experience. + +## Advanced monitoring + +[Azure Monitor](/azure/monitoring-and-diagnostics/) is the centralized service for monitoring all metrics and setting alerts across Azure services. Within Azure Monitor, administrators can granularly track performance and identify trends. Each Azure service offers its own [set of metrics](/azure/monitoring-and-diagnostics/monitoring-supported-metrics#microsoftwebsites-excluding-functions) to Azure Monitor. + +## Profile with Application Insights + +[Application Insights](/azure/application-insights/app-insights-overview) is an Azure service for analyzing the performance and stability of web apps and how users use them. The data from Application Insights is broader and deeper than that of Azure Monitor. The data can provide developers and administrators with key information for improving apps. Application Insights can be added to an Azure App Service resource without code changes. + +1. Open the [Azure portal](https://portal.azure.com), and then navigate to the *mywebapp\* App Service. +1. From the **Overview** tab, click the **Application Insights** tile. + + ![Application Insights tile](./media/monitoring/app-insights.png) + +1. Select the **Create new resource** radio button. Use the default resource name, and select the location for the Application Insights resource. The location doesn't need to match that of your web app. + + ![Application Insights setup](./media/monitoring/new-app-insights.png) + +1. For **Runtime/Framework**, select **ASP.NET Core**. Accept the default settings. +1. Select **OK**. If prompted to confirm, select **Continue**. +1. After the resource has been created, click the name of Application Insights resource to navigate directly to the Application Insights page. + + ![New Application Insights resource is ready](./media/monitoring/new-app-insights-done.png) + +As the app is used, data accumulates. Select **Refresh** to reload the blade with new data. + +![Application Insights overview tab](./media/monitoring/app-insights-overview.png) + +Application Insights provides useful server-side information with no additional configuration. To get the most value from Application Insights, [instrument your app with the Application Insights SDK](/azure/application-insights/app-insights-asp-net-core). When properly configured, the service provides end-to-end monitoring across the web server and browser, including client-side performance. For more information, see the [Application Insights documentation](/azure/application-insights/app-insights-overview). + +## Logging + +Web server and app logs are disabled by default in Azure App Service. Enable the logs with the following steps: + +1. Open the [Azure portal](https://portal.azure.com), and navigate to the *mywebapp\* App Service. +1. In the menu to the left, scroll down to the **Monitoring** section. Select **Diagnostics logs**. + + ![Diagnostic logs link](./media/monitoring/logging.png) + +1. Turn on **Application Logging (Filesystem)**. If prompted, click the box to install the extensions to enable app logging in the web app. +1. Set **Web server logging** to **File System**. +1. Enter the **Retention Period** in days. For example, 30. +1. Click **Save**. + +ASP.NET Core and web server (App Service) logs are generated for the web app. They can be downloaded using the FTP/FTPS information displayed. The password is the same as the deployment credentials created earlier in this guide. The logs can be [streamed directly to your local machine with PowerShell or Azure CLI](/azure/app-service/web-sites-enable-diagnostic-log#download). Logs can also be [viewed in Application Insights](/azure/app-service/web-sites-enable-diagnostic-log#how-to-view-logs-in-application-insights). + +## Log streaming + +App and web server logs can be streamed in real time through the portal. + +1. Open the [Azure portal](https://portal.azure.com), and navigate to the *mywebapp\* App Service. +1. In the menu to the left, scroll down to the **Monitoring** section and select **Log stream**. + + ![Screenshot showing log stream link](./media/monitoring/log-stream.png) + +Logs can also be [streamed via Azure CLI or Azure PowerShell](/azure/app-service/web-sites-enable-diagnostic-log#streamlogs), including through the Cloud Shell. + +## Alerts + +Azure Monitor also provides [real time alerts](/azure/monitoring-and-diagnostics/insights-alerts-portal) based on metrics, administrative events, and other criteria. + +> [!NOTE] +> Currently alerting on web app metrics is only available in the Alerts (classic) service. + +The [Alerts (classic) service](/azure/monitoring-and-diagnostics/monitor-quick-resource-metric-alert-portal) can be found in Azure Monitor or under the **Monitoring** section of the App Service settings. + +![Alerts (classic) link](./media/monitoring/alerts.png) + +## Live debugging + +Azure App Service can be [debugged remotely with Visual Studio](/azure/app-service/web-sites-dotnet-troubleshoot-visual-studio#remotedebug) when logs don't provide enough information. However, remote debugging requires the app to be compiled with debug symbols. Debugging shouldn't be done in production, except as a last resort. + +## Conclusion + +In this section, you completed the following tasks: + +> [!div class="checklist"] +> +> * Find basic monitoring and troubleshooting data in the Azure portal +> * Learn how Azure Monitor provides a deeper look at metrics across all Azure services +> * Connect the web app with Application Insights for app profiling +> * Turn on logging and learn where to download logs +> * Stream logs in real time +> * Learn where to set up alerts +> * Learn about remote debugging Azure App Service web apps. + +## Additional reading + +* [Troubleshooting ASP.NET Core on Azure App Service and IIS](/aspnet/core/test/troubleshoot-azure-iis) +* [Common errors reference for Azure App Service and IIS with ASP.NET Core](/aspnet/core/host-and-deploy/azure-iis-errors-reference) +* [Monitor Azure web app performance with Application Insights](/azure/application-insights/app-insights-azure-web-apps) +* [Enable diagnostics logging for web apps in Azure App Service](/azure/app-service/web-sites-enable-diagnostic-log) +* [Troubleshoot a web app in Azure App Service using Visual Studio](/azure/app-service/web-sites-dotnet-troubleshoot-visual-studio) +* [Create classic metric alerts in Azure Monitor for Azure services - Azure portal](/azure/monitoring-and-diagnostics/insights-alerts-portal) + +>[!div class="step-by-step"] +>[Previous](actions-codeql.md) +>[Next](next-steps.md) diff --git a/docs/architecture/devops-for-aspnet-developers/next-steps.md b/docs/architecture/devops-for-aspnet-developers/next-steps.md new file mode 100644 index 0000000000000..88dd2866bf160 --- /dev/null +++ b/docs/architecture/devops-for-aspnet-developers/next-steps.md @@ -0,0 +1,44 @@ +--- +title: Next steps - DevOps for ASP.NET Core Developers +author: CamSoper +description: Additional learning paths for DevOps for ASP.NET Core Developers. +ms.author: casoper +ms.custom: "devx-track-csharp, mvc, seodec18" +ms.date: 10/24/2018 +no-loc: [appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR] +uid: azure/devops/next-steps +--- +# Next steps + +In this guide, you created a DevOps pipeline for an ASP.NET Core sample app. Congratulations! We hope you enjoyed learning to publish ASP.NET Core web apps to Azure App Service and automate the continuous integration of changes. + +Beyond web hosting and DevOps, Azure has a wide array of Platform-as-a-Service (PaaS) services useful to ASP.NET Core developers. This section gives a brief overview of some of the most commonly used services. + +## Storage and databases + +[Redis Cache](/azure/redis-cache/) is high-throughput, low-latency data caching available as a service. It can be used for caching page output, reducing database requests, and providing ASP.NET Core session state across multiple instances of an app. + +[Azure Storage](/azure/storage/) is Azure's massively scalable cloud storage. Developers can take advantage of [Queue Storage](/azure/storage/queues/storage-queues-introduction) for reliable message queuing, and [Table Storage](/azure/storage/tables/table-storage-overview) is a NoSQL key-value store designed for rapid development using massive, semi-structured data sets. + +[Azure SQL Database](/azure/sql-database/) provides familiar relational database functionality as a service using the Microsoft SQL Server Engine. + +[Cosmos DB](/azure/cosmos-db/) globally distributed, multi-model NoSQL database service. Multiple APIs are available, including SQL API (formerly called DocumentDB), Cassandra, and MongoDB. + +## Identity + +[Azure Active Directory](/azure/active-directory/) and [Azure Active Directory B2C](/azure/active-directory-b2c/) are both identity services. Azure Active Directory is designed for enterprise scenarios and enables Azure AD B2B (business-to-business) collaboration, while Azure Active Directory B2C is intended business-to-customer scenarios, including social network sign-in. + +## Mobile + +[Notification Hubs](/azure/notification-hubs/) is a multi-platform, scalable push-notification engine to quickly send millions of messages to apps running on various types of devices. + +## Web infrastructure + +[Azure Container Service](/azure/aks/) manages your hosted Kubernetes environment, making it quick and easy to deploy and manage containerized apps without container orchestration expertise. + +[Azure Search](/azure/search/) is used to create an enterprise search solution over private, heterogenous content. + +[Service Fabric](/azure/service-fabric/) is a distributed systems platform that makes it easy to package, deploy, and manage scalable and reliable microservices and containers. + +>[!div class="step-by-step"] +>[Previous](monitoring.md) diff --git a/docs/architecture/devops-for-aspnet-developers/toc.yml b/docs/architecture/devops-for-aspnet-developers/toc.yml new file mode 100644 index 0000000000000..d62938126d973 --- /dev/null +++ b/docs/architecture/devops-for-aspnet-developers/toc.yml @@ -0,0 +1,27 @@ +- name: "DevOps for ASP.NET Core Developers" + href: index.md + items: + - name: Tools and downloads + href: tools-and-downloads.md + - name: Deploy an app to App Service + href: deploying-to-app-service.md + - name: Continuous integration and deployment (CI/CD) + items: + - name: Azure DevOps + href: cicd.md + - name: GitHub Actions + items: + - name: Overview + href: actions-index.md + - name: Comparison of GitHub Actions and Azure Pipelines + href: actions-vs-pipelines.md + - name: Basic build workflow + href: actions-build.md + - name: Deployment workflow + href: actions-deploy.md + - name: Secure .NET code with CodeQL + href: actions-codeql.md + - name: Monitor and debug + href: monitoring.md + - name: Next steps + href: next-steps.md diff --git a/docs/architecture/devops-for-aspnet-developers/tools-and-downloads.md b/docs/architecture/devops-for-aspnet-developers/tools-and-downloads.md new file mode 100644 index 0000000000000..c1ff040548821 --- /dev/null +++ b/docs/architecture/devops-for-aspnet-developers/tools-and-downloads.md @@ -0,0 +1,46 @@ +--- +title: Tools and downloads - DevOps for ASP.NET Core Developers +author: CamSoper +description: Tools and downloads required for DevOps for ASP.NET Core Developers. +ms.author: casoper +ms.custom: "devx-track-csharp, mvc, seodec18" +ms.date: 10/24/2018 +no-loc: [appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR] +uid: azure/devops/tools-and-downloads +--- +# Tools and downloads + +Azure has several interfaces for provisioning and managing resources, such as the [Azure portal](https://portal.azure.com), [Azure CLI](/cli/azure/), [Azure PowerShell](/powershell/azure/overview), [Azure Cloud Shell](https://shell.azure.com/bash), and Visual Studio. This guide takes a minimalist approach and uses the Azure Cloud Shell whenever possible to reduce the steps required. However, the Azure portal must be used for some portions. + +## Prerequisites + +The following subscriptions are required: + +* Azure — If you don't have an account, [get a free trial](https://azure.microsoft.com/free/dotnet/). +* Azure DevOps Services — your Azure DevOps subscription and organization is created in Chapter 4. +* GitHub — If you don't have an account, [sign up for free](https://github.com/join). + +The following tools are required: + +* [Git](https://git-scm.com/downloads) — A fundamental understanding of Git is recommended for this guide. Review the [Git documentation](https://git-scm.com/doc), specifically [git remote](https://git-scm.com/docs/git-remote) and [git push](https://git-scm.com/docs/git-push). +* [.NET Core SDK](https://dotnet.microsoft.com/download/) — Version 2.1.300 or later is required to build and run the sample app. If Visual Studio is installed with the **.NET Core cross-platform development** workload, the .NET Core SDK is already installed. + + Verify your .NET Core SDK installation. Open a command shell, and run the following command: + + ```dotnetcli + dotnet --version + ``` + +## Recommended tools (Windows only) + +* [Visual Studio](https://visualstudio.microsoft.com)'s robust Azure tools provide a GUI for most of the functionality described in this guide. Any edition of Visual Studio will work, including the free Visual Studio Community Edition. The tutorials are written to demonstrate development, deployment, and DevOps both with and without Visual Studio. + + Confirm that Visual Studio has the following [workloads](/visualstudio/install/modify-visual-studio) installed: + + * ASP.NET and web development + * Azure development + * .NET Core cross-platform development + +>[!div class="step-by-step"] +>[Previous](index.md) +>[Next](deploying-to-app-service.md) diff --git a/docs/architecture/grpc-for-wcf-developers/application-performance-management.md b/docs/architecture/grpc-for-wcf-developers/application-performance-management.md index ff59b8fb0a777..1dcbb8a5e1300 100644 --- a/docs/architecture/grpc-for-wcf-developers/application-performance-management.md +++ b/docs/architecture/grpc-for-wcf-developers/application-performance-management.md @@ -46,7 +46,7 @@ For more information about writing log messages and available logging sinks and ## Metrics in ASP.NET Core gRPC -The .NET Core runtime provides a set of components for emitting and observing metrics. These include APIs such as the and classes. These APIs can emit basic numeric data that can be consumed by external processes, like the [dotnet-counters global tool](../../core/diagnostics/dotnet-counters.md), or Event Tracing for Windows. For more information about using `EventCounter` in your own code, see [EventCounter introduction](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md). +The .NET Core runtime provides a set of components for emitting and observing metrics. These include APIs such as the and classes. These APIs can emit basic numeric data that can be consumed by external processes, like the [dotnet-counters global tool](../../core/diagnostics/dotnet-counters.md), or Event Tracing for Windows. For more information about using `EventCounter` in your own code, see [EventCounter introduction](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Diagnostics.Tracing/documentation/EventCounterTutorial.md). For more advanced metrics and for writing metric data to a wider range of data stores, you might try an open-source project called [App Metrics](https://www.app-metrics.io). This suite of libraries provides an extensive set of types to instrument your code. It also offers packages to write metrics to different kinds of targets that include time-series databases, such as Prometheus and InfluxDB, and [Application Insights](/azure/azure-monitor/app/app-insights-overview). The [App.Metrics.AspNetCore.Mvc](https://www.nuget.org/packages/App.Metrics.AspNetCore.Mvc/) NuGet package even adds a comprehensive set of basic metrics that are automatically generated via integration with the ASP.NET Core framework. The project website provides [templates](https://www.app-metrics.io/samples/grafana/) for displaying those metrics with the [Grafana](https://grafana.com/) visualization platform. @@ -115,7 +115,7 @@ Distributed tracing is based on the concept of *spans*: named, timed operations ### Distributed tracing with `DiagnosticSource` -.NET has an internal module that maps well to distributed traces and spans: [DiagnosticSource](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md#diagnosticsource-users-guide). As well as providing a simple way to produce and consume diagnostics within a process, the `DiagnosticSource` module has the concept of an *activity*. An activity is effectively an implementation of a distributed trace, or a span within a trace. The internals of the module take care of parent/child activities, including allocating identifiers. For more information about using the `Activity` type, see the [Activity User Guide on GitHub](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md#activity-user-guide). +.NET has an internal module that maps well to distributed traces and spans: [DiagnosticSource](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md#diagnosticsource-users-guide). As well as providing a simple way to produce and consume diagnostics within a process, the `DiagnosticSource` module has the concept of an *activity*. An activity is effectively an implementation of a distributed trace, or a span within a trace. The internals of the module take care of parent/child activities, including allocating identifiers. For more information about using the `Activity` type, see the [Activity User Guide on GitHub](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md#activity-user-guide). Because `DiagnosticSource` is a part of the core framework and later, it's supported by several core components. These include , Entity Framework Core, and ASP.NET Core, including explicit support in the gRPC framework. When ASP.NET Core receives a request, it checks for a pair of HTTP headers matching the [W3C Trace Context](https://www.w3.org/TR/trace-context) standard. If the headers are found, an activity is started by using the identity values and context from the headers. If no headers are found, an activity is started with generated identity values that match the standard format. Any diagnostics generated by the framework or by application code during the lifetime of this activity can be tagged with the trace and span identifiers. The `HttpClient` support extends this functionality further by checking for a current activity on every request, and automatically adding the trace headers to the outgoing request. @@ -126,7 +126,7 @@ The ASP.NET Core gRPC client and server libraries include explicit support for ` ### Add your own `DiagnosticSource` and `Activity` -To add your own diagnostics or create explicit spans within your application code, see the [DiagnosticSource User Guide](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md#instrumenting-with-diagnosticsourcediagnosticlistener) and [Activity User Guide](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md#activity-usage). +To add your own diagnostics or create explicit spans within your application code, see the [DiagnosticSource User Guide](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md#instrumenting-with-diagnosticsourcediagnosticlistener) and [Activity User Guide](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md#activity-usage). ### Store distributed trace data diff --git a/docs/architecture/index.yml b/docs/architecture/index.yml index 8e6563871cb04..4830ad077487c 100644 --- a/docs/architecture/index.yml +++ b/docs/architecture/index.yml @@ -66,9 +66,9 @@ landingContent: - linkListType: concept links: - text: Containerized Docker application lifecycle with Microsoft platform and tools - url: containerized-lifecycle/index.md - - text: ASP.NET Core DevOps with Azure - url: /aspnet/core/azure/devops/ + url: containerized-lifecycle/index.md + - text: DevOps for ASP.NET Core Developers + url: devops-for-aspnet-developers/index.md # Card - title: Modernize desktop apps diff --git a/docs/architecture/microservices/architect-microservice-container-applications/direct-client-to-microservice-communication-versus-the-API-Gateway-pattern.md b/docs/architecture/microservices/architect-microservice-container-applications/direct-client-to-microservice-communication-versus-the-api-gateway-pattern.md similarity index 100% rename from docs/architecture/microservices/architect-microservice-container-applications/direct-client-to-microservice-communication-versus-the-API-Gateway-pattern.md rename to docs/architecture/microservices/architect-microservice-container-applications/direct-client-to-microservice-communication-versus-the-api-gateway-pattern.md diff --git a/docs/architecture/microservices/architect-microservice-container-applications/index.md b/docs/architecture/microservices/architect-microservice-container-applications/index.md index 0eecca6189e59..d7009bb326718 100644 --- a/docs/architecture/microservices/architect-microservice-container-applications/index.md +++ b/docs/architecture/microservices/architect-microservice-container-applications/index.md @@ -7,13 +7,13 @@ ms.date: 01/13/2021 *Microservices offer great benefits but also raise huge new challenges. Microservice architecture patterns are fundamental pillars when creating a microservice-based application.* -Earlier in this guide, you learned basic concepts about containers and Docker. That information was the minimum you needed to get started with containers. Even though when containers are enablers and a great fit for microservices, they aren't mandatory for a microservice architecture and many architectural concepts in this architecture section could be applied without containers, too. However, this guidance focuses on the intersection of both due to the already introduced importance of containers. +Earlier in this guide, you learned basic concepts about containers and Docker. That information was the minimum you needed to get started with containers. Even though containers are enablers of, and a great fit for microservices, they aren't mandatory for a microservice architecture. Many architectural concepts in this architecture section could be applied without containers. However, this guide focuses on the intersection of both due to the already introduced importance of containers. Enterprise applications can be complex and are often composed of multiple services instead of a single service-based application. For those cases, you need to understand other architectural approaches, such as the microservices and certain Domain-Driven Design (DDD) patterns plus container orchestration concepts. Note that this chapter describes not just microservices on containers, but any containerized application, as well. ## Container design principles -In the container model, a container image instance represents a single process. By defining a container image as a process boundary, you can create primitives that can be used to scale the process or to batch it. +In the container model, a container image instance represents a single process. By defining a container image as a process boundary, you can create primitives that can be used to scale or batch the process. When you design a container image, you'll see an [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) definition in the Dockerfile. This definition defines the process whose lifetime controls the lifetime of the container. When the process completes, the container lifecycle ends. Containers might represent long-running processes like web servers, but can also represent short-lived processes like batch jobs, which formerly might have been implemented as Azure [WebJobs](https://github.com/Azure/azure-webjobs-sdk/wiki). diff --git a/docs/architecture/microservices/docker-application-development-process/media/docker-app-development-workflow/docker-compose-tree-node.PNG b/docs/architecture/microservices/docker-application-development-process/media/docker-app-development-workflow/docker-compose-tree-node.png similarity index 100% rename from docs/architecture/microservices/docker-application-development-process/media/docker-app-development-workflow/docker-compose-tree-node.PNG rename to docs/architecture/microservices/docker-application-development-process/media/docker-app-development-workflow/docker-compose-tree-node.png diff --git a/docs/architecture/microservices/implement-resilient-applications/implement-http-call-retries-exponential-backoff-polly.md b/docs/architecture/microservices/implement-resilient-applications/implement-http-call-retries-exponential-backoff-polly.md index f0082f8834200..610ea1155a1f8 100644 --- a/docs/architecture/microservices/implement-resilient-applications/implement-http-call-retries-exponential-backoff-polly.md +++ b/docs/architecture/microservices/implement-resilient-applications/implement-http-call-retries-exponential-backoff-polly.md @@ -12,9 +12,9 @@ Polly is a .NET library that provides resilience and transient-fault handling ca The following steps show how you can use Http retries with Polly integrated into `IHttpClientFactory`, which is explained in the previous section. -**Reference the ASP.NET Core 3.1 packages** +**Reference the .NET 5 packages** -`IHttpClientFactory` is available since .NET Core 2.1 however we recommend you to use the latest ASP.NET Core 3.1 packages from NuGet in your project. You typically also need to reference the extension package `Microsoft.Extensions.Http.Polly`. +`IHttpClientFactory` is available since .NET Core 2.1 however we recommend you to use the latest .NET 5 packages from NuGet in your project. You typically also need to reference the extension package `Microsoft.Extensions.Http.Polly`. **Configure a client with Polly's Retry policy, in Startup** @@ -46,20 +46,16 @@ With Polly, you can define a Retry policy with the number of retries, the expone ## Add a jitter strategy to the retry policy -A regular Retry policy can impact your system in cases of high concurrency and scalability and under high contention. To overcome peaks of similar retries coming from many clients in case of partial outages, a good workaround is to add a jitter strategy to the retry algorithm/policy. This can improve the overall performance of the end-to-end system by adding randomness to the exponential backoff. This spreads out the spikes when issues arise. The principle is illustrated by the following example: +A regular Retry policy can affect your system in cases of high concurrency and scalability and under high contention. To overcome peaks of similar retries coming from many clients in partial outages, a good workaround is to add a jitter strategy to the retry algorithm/policy. This strategy can improve the overall performance of the end-to-end system. As recommended in [Polly: Retry with Jitter](https://github.com/App-vNext/Polly/wiki/Retry-with-jitter), a good jitter strategy can be implemented by smooth and evenly distributed retry intervals applied with a well-controlled median initial retry delay on an exponential backoff. This approach helps to spread out the spikes when the issue arises. The principle is illustrated by the following example: ```csharp -Random jitterer = new Random(); -var retryWithJitterPolicy = HttpPolicyExtensions - .HandleTransientHttpError() - .OrResult(msg => msg.StatusCode == System.Net.HttpStatusCode.NotFound) - .WaitAndRetryAsync(6, // exponential back-off plus some jitter - retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)) - + TimeSpan.FromMilliseconds(jitterer.Next(0, 100)) - ); -``` -Polly provides production-ready jitter algorithms via the project website. +var delay = Backoff.DecorrelatedJitterBackoffV2(medianFirstRetryDelay: TimeSpan.FromSeconds(1), retryCount: 5); + +var retryPolicy = Policy + .Handle() + .WaitAndRetryAsync(delay); +``` ## Additional resources diff --git a/docs/architecture/microservices/microservice-ddd-cqrs-patterns/enumeration-classes-over-enum-types.md b/docs/architecture/microservices/microservice-ddd-cqrs-patterns/enumeration-classes-over-enum-types.md index 89c849852d305..725e13e15e4b8 100644 --- a/docs/architecture/microservices/microservice-ddd-cqrs-patterns/enumeration-classes-over-enum-types.md +++ b/docs/architecture/microservices/microservice-ddd-cqrs-patterns/enumeration-classes-over-enum-types.md @@ -58,9 +58,9 @@ You can use this class as a type in any entity or value object, as for the follo public class CardType : Enumeration { - public static CardType Amex = new CardType(1, nameof(Amex)); - public static CardType Visa = new CardType(2, nameof(Visa)); - public static CardType MasterCard = new CardType(3, nameof(MasterCard)); + public static CardType Amex = new(1, nameof(Amex)); + public static CardType Visa = new(2, nameof(Visa)); + public static CardType MasterCard = new(3, nameof(MasterCard)); public CardType(int id, string name) : base(id, name) diff --git a/docs/architecture/microservices/multi-container-microservice-net-applications/implement-api-gateways-with-ocelot.md b/docs/architecture/microservices/multi-container-microservice-net-applications/implement-api-gateways-with-ocelot.md index 148bde48ca6d3..4e1ec1ff04470 100644 --- a/docs/architecture/microservices/multi-container-microservice-net-applications/implement-api-gateways-with-ocelot.md +++ b/docs/architecture/microservices/multi-container-microservice-net-applications/implement-api-gateways-with-ocelot.md @@ -134,7 +134,7 @@ However, direct-access communication to the microservice, in this case through t ## Implementing your API Gateways with Ocelot -Ocelot is basically a set of middlewares that you can apply in a specific order. +Ocelot is basically a set of middleware that you can apply in a specific order. Ocelot is designed to work with ASP.NET Core only. The latest version of the package targets `.NETCoreApp 3.1` and hence it is not suitable for .NET Framework applications. @@ -394,7 +394,7 @@ In the case of the "Marketing" business area and microservices, it is a simple u ### Authentication and authorization in Ocelot API Gateways -In an Ocelot API Gateway you can sit the authentication service, such as an ASP.NET Core Web API service using [IdentityServer](https://identityserver.io/) providing the auth token, either out or inside the API Gateway. +In an Ocelot API Gateway, you can sit the authentication service, such as an ASP.NET Core Web API service using [IdentityServer](../../cloud-native/identity-server.md) providing the auth token, either out or inside the API Gateway. Since eShopOnContainers is using multiple API Gateways with boundaries based on BFF and business areas, the Identity/Auth service is left out of the API Gateways, as highlighted in yellow in the following diagram. diff --git a/docs/architecture/microservices/multi-container-microservice-net-applications/subscribe-events.md b/docs/architecture/microservices/multi-container-microservice-net-applications/subscribe-events.md index b6da4616ed827..de7f8b298355c 100644 --- a/docs/architecture/microservices/multi-container-microservice-net-applications/subscribe-events.md +++ b/docs/architecture/microservices/multi-container-microservice-net-applications/subscribe-events.md @@ -196,9 +196,7 @@ public async Task UpdateProduct([FromBody]CatalogItem productToUp _catalogContext.CatalogItems.Update(catalogItem); await _catalogContext.SaveChangesAsync(); - // Save to EventLog only if product price changed - if(raiseProductPriceChangedEvent) - await _integrationEventLogService.SaveEventAsync(priceChangedEvent); + await _integrationEventLogService.SaveEventAsync(priceChangedEvent); transaction.Commit(); } diff --git a/docs/architecture/microservices/net-core-net-framework-containers/net-framework-container-scenarios.md b/docs/architecture/microservices/net-core-net-framework-containers/net-framework-container-scenarios.md index 447e666035dcf..112e80c22d8fd 100644 --- a/docs/architecture/microservices/net-core-net-framework-containers/net-framework-container-scenarios.md +++ b/docs/architecture/microservices/net-core-net-framework-containers/net-framework-container-scenarios.md @@ -33,7 +33,7 @@ The following list shows most of the technologies that aren't available in .NET - Workflow-related services. Windows Workflow Foundation (WF), Workflow Services (WCF + WF in a single service), and WCF Data Services (formerly known as ADO.NET Data Services) are only available on .NET Framework. There are currently no plans to bring them to .NET 5. -In addition to the technologies listed in the official [.NET roadmap](https://github.com/dotnet/core/blob/master/roadmap.md), other features might be ported to the new [unified .NET platform](https://devblogs.microsoft.com/dotnet/introducing-net-5/). You might consider participating in the discussions on GitHub so that your voice can be heard. And if you think something is missing, file a new issue in the [dotnet/runtime](https://github.com/dotnet/runtime/issues/new) GitHub repository. +In addition to the technologies listed in the official [.NET roadmap](https://github.com/dotnet/core/blob/main/roadmap.md), other features might be ported to the new [unified .NET platform](https://devblogs.microsoft.com/dotnet/introducing-net-5/). You might consider participating in the discussions on GitHub so that your voice can be heard. And if you think something is missing, file a new issue in the [dotnet/runtime](https://github.com/dotnet/runtime/issues/new) GitHub repository. ## Using a platform or API that doesn't support .NET 5 diff --git a/docs/architecture/microservices/secure-net-microservices-web-applications/azure-key-vault-protects-secrets.md b/docs/architecture/microservices/secure-net-microservices-web-applications/azure-key-vault-protects-secrets.md index e881fa2b54020..7685dd020edaf 100644 --- a/docs/architecture/microservices/secure-net-microservices-web-applications/azure-key-vault-protects-secrets.md +++ b/docs/architecture/microservices/secure-net-microservices-web-applications/azure-key-vault-protects-secrets.md @@ -42,9 +42,6 @@ Note that calling `AddAzureKeyVault` requires the application ID that was regist - **Data Protection key management and lifetime in ASP.NET Core** \ [https://docs.microsoft.com/aspnet/core/security/data-protection/configuration/default-settings](/aspnet/core/security/data-protection/configuration/default-settings) -- **Microsoft.Extensions.Configuration** GitHub repository. \ - - >[!div class="step-by-step"] >[Previous](developer-app-secrets-storage.md) >[Next](../key-takeaways.md) diff --git a/docs/architecture/microservices/secure-net-microservices-web-applications/index.md b/docs/architecture/microservices/secure-net-microservices-web-applications/index.md index 86b3582df4d45..39c2ca25e3815 100644 --- a/docs/architecture/microservices/secure-net-microservices-web-applications/index.md +++ b/docs/architecture/microservices/secure-net-microservices-web-applications/index.md @@ -124,13 +124,13 @@ In all cases, you must complete an application registration procedure that is ve 1. Getting a Client Application ID. 2. Getting a Client Application Secret. -3. Configuring an redirection URL, that's handled by the authorization middleware and the registered provider +3. Configuring a redirection URL, that's handled by the authorization middleware and the registered provider 4. Optionally, configuring a sign-out URL to properly handle sign out in a Single Sign On (SSO) scenario. For details on configuring your app for an external provider, see the [External provider authentication in the ASP.NET Core documentation](/aspnet/core/security/authentication/social/)). ->[!TIP] ->All details are handled by the authorization middleware and services previously mentioned. So, you just have to choose the **Individual User Account** authentication option when you create the ASP.NET Code web application project in Visual Studio, as shown in Figure 9-3, besides registering the authentication providers previously mentioned. +> [!TIP] +> All details are handled by the authorization middleware and services previously mentioned. So, you just have to choose the **Individual User Account** authentication option when you create the ASP.NET Core web application project in Visual Studio, as shown in Figure 9-3, besides registering the authentication providers previously mentioned. ![Screenshot of the New ASP.NET Core Web Application dialog.](./media/index/select-individual-user-account-authentication-option.png) @@ -201,7 +201,7 @@ public void ConfigureServices(IServiceCollection services) } ``` -Note that when you use this workflow, the ASP.NET Core Identity middleware is not needed, because all user information storage and authentication is handled by the Identity service. +When you use this workflow, the ASP.NET Core Identity middleware is not needed, because all user information storage and authentication is handled by the Identity service. ### Issue security tokens from an ASP.NET Core service diff --git a/docs/architecture/modern-web-apps-azure/architectural-principles.md b/docs/architecture/modern-web-apps-azure/architectural-principles.md index 4a643ba25097b..03451e041f783 100644 --- a/docs/architecture/modern-web-apps-azure/architectural-principles.md +++ b/docs/architecture/modern-web-apps-azure/architectural-principles.md @@ -28,7 +28,7 @@ In classes, encapsulation is achieved by limiting outside access to the class's ### Dependency inversion -The direction of dependency within the application should be in the direction of abstraction, not implementation details. Most applications are written such that compile-time dependency flows in the direction of runtime execution, producing a direct dependency graph. That is, if module A calls a function in module B, which calls a function in module C, then at compile time A will depend on B, which will depend on C, as shown in Figure 4-1. +The direction of dependency within the application should be in the direction of abstraction, not implementation details. Most applications are written such that compile-time dependency flows in the direction of runtime execution, producing a direct dependency graph. That is, if class A calls a method of class B and class B calls a method of class C, then at compile time class A will depend on class B, and class B will depend on class C, as shown in Figure 4-1. ![Direct dependency graph](./media/image4-1.png) diff --git a/docs/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps.md b/docs/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps.md index 4018cb3d8e521..e68cc120796bb 100644 --- a/docs/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps.md +++ b/docs/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps.md @@ -646,7 +646,7 @@ Consider ways in which your applications communicate directly with client applic > ### References – Client Communication > > - **ASP.NET Core SignalR**\ -> +> > - **WebSocket Manager**\ > diff --git a/docs/architecture/modernize-desktop/example-migration.md b/docs/architecture/modernize-desktop/example-migration.md index 42f9d4cb2fe27..b034e1923c452 100644 --- a/docs/architecture/modernize-desktop/example-migration.md +++ b/docs/architecture/modernize-desktop/example-migration.md @@ -185,7 +185,7 @@ Save and reload the project. You're now done updating the project file and the p If you compile the project at this point, you'll find some errors related to the WCF client reference. Since this code is autogenerated, you must regenerate it to target .NET. -![Screenshot of compilation errors on Visual Studio](./media/example-migration-core/winforms-compilation-errors.png) +![Error List in Visual Studio showing errors](./media/example-migration-core/winforms-compilation-errors.png) Delete the *Reference.cs* file and generate a new Service Client. @@ -256,7 +256,7 @@ In this case, delete all the content of the *.csproj* file and replace it with t If you reload the project and compile it, you'll get the following error: -![Screenshot of compilation errors on Visual Studio](./media/example-migration-core/wpf-compilation-error.png) +![Error List in Visual Studio showing single error CS0234](./media/example-migration-core/wpf-compilation-error.png) Since you've deleted all the *.csproj* contents, you've lost a project reference specification present in the old project. You just need to add this line to the *.csproj* file to include the project reference back: diff --git a/docs/architecture/modernize-desktop/migrate-modern-applications.md b/docs/architecture/modernize-desktop/migrate-modern-applications.md index be63f30e7b9ef..49791e8d27bdd 100644 --- a/docs/architecture/modernize-desktop/migrate-modern-applications.md +++ b/docs/architecture/modernize-desktop/migrate-modern-applications.md @@ -40,7 +40,7 @@ The configuration API supports the concept of configuration provider, which defi Or you can build your own. -The new configuration allows a list of name-value pairs that can be grouped into a multi-level hierarchy. Any stored value maps to a string, and there's built-in binding support that allows you to deserialize settings into a custom plain old CLR object (POCO) object. +The new configuration allows a list of name-value pairs that can be grouped into a multi-level hierarchy. Any stored value maps to a string, and there's built-in binding support that allows you to deserialize settings into a custom plain old CLR object (POCO). The object lets you add as many configuration providers you may need for your application, using a precedence rule to resolve preference. So, the last provider you add in your code will override the others. This is a great feature for managing different environments for execution since you can define different configurations for development, testing and production environments, and manage them on a single function inside your code. @@ -151,7 +151,7 @@ to Microsoft Access using the library. ## Consuming services -With the raise of service-oriented architectures, desktop applications began to evolve from a client-server model to the three-layer approach. In the client-server approach, a direct database connection is established from the client holding the business logic usually inside a single EXE file. On the other hand, the three-layer approach establishes an intermediate service layer implementing business logic and database access allowing for better security, scalability, and reusability. Instead of working directly with datasets of data, the layer approach relies in a set of services implementing contracts and types objects as a way to implement data transfer. +With the rise of service-oriented architectures, desktop applications began to evolve from a client-server model to the three-layer approach. In the client-server approach, a direct database connection is established from the client holding the business logic, usually inside a single EXE file. On the other hand, the three-layer approach establishes an intermediate service layer implementing business logic and database access, allowing for better security, scalability, and reusability. Instead of working directly with underlying data, the layered approach relies on a set of services implementing contracts and typed objects for data transfer. If you have a desktop application using a WCF service and you want to migrate it to .NET, there are some things to consider. diff --git a/docs/architecture/modernize-with-azure-containers/lift-and-shift-existing-apps-azure-iaas.md b/docs/architecture/modernize-with-azure-containers/lift-and-shift-existing-apps-azure-iaas.md index 4bde3b851e713..8c0b975422d30 100644 --- a/docs/architecture/modernize-with-azure-containers/lift-and-shift-existing-apps-azure-iaas.md +++ b/docs/architecture/modernize-with-azure-containers/lift-and-shift-existing-apps-azure-iaas.md @@ -57,7 +57,7 @@ Azure Migrate gives you confidence that your workloads can migrate with minimal Figure 2-2 shows you the built-in dependency mapping for all server and application connections performed by Azure Migrate. -![Positioning Cloud Infrastructure-Ready applications](./media/image2-2.png) +![Dependencies of server and application connections](./media/image2-2.png) **Figure 2-2.** Positioning Cloud Infrastructure-Ready applications @@ -69,7 +69,7 @@ Site Recovery is also made specifically for hybrid environments that are partly Figure 2-3 shows the execution of multiple VM migrations by using Azure Site Recovery. -![Positioning Cloud Infrastructure-Ready applications](./media/image2-3.png) +![VM migrations using Azure Site Recovery](./media/image2-3.png) **Figure 2-3.** Positioning Cloud Infrastructure-Ready applications diff --git a/docs/architecture/modernize-with-azure-containers/modernize-existing-apps-to-cloud-optimized/choosing-azure-compute-options-for-container-based-applications.md b/docs/architecture/modernize-with-azure-containers/modernize-existing-apps-to-cloud-optimized/choosing-azure-compute-options-for-container-based-applications.md index e7d2c6aac6999..f772bfc6066e4 100644 --- a/docs/architecture/modernize-with-azure-containers/modernize-existing-apps-to-cloud-optimized/choosing-azure-compute-options-for-container-based-applications.md +++ b/docs/architecture/modernize-with-azure-containers/modernize-existing-apps-to-cloud-optimized/choosing-azure-compute-options-for-container-based-applications.md @@ -33,6 +33,12 @@ In the following table, you can see a breakdown of different kinds of apps and t ![Recommended icon](media/choosing-azure-compute-options-for-container-based-applications/recommended.png) Recommended \ ![Possible icon](media/choosing-azure-compute-options-for-container-based-applications/possible.png) Possible +### Additional resources + +- **Choose an Azure compute service for your application** + + + > [!div class="step-by-step"] > [Previous](when-to-deploy-windows-containers-to-azure-container-service-kubernetes.md) > [Next](build-resilient-services-ready-for-the-cloud-embrace-transient-failures-in-the-cloud.md) diff --git a/docs/architecture/porting-existing-aspnet-apps/configuration-differences.md b/docs/architecture/porting-existing-aspnet-apps/configuration-differences.md index ab758327fe16a..63e88a685336f 100644 --- a/docs/architecture/porting-existing-aspnet-apps/configuration-differences.md +++ b/docs/architecture/porting-existing-aspnet-apps/configuration-differences.md @@ -54,7 +54,7 @@ public class TestModel : PageModel **Figure 2-2.** Accessing configuration values with `IConfiguration`. -Using the options pattern, settings access is similar but is strongly typed and more specific to the setting(s) needed by the consuming class, as Figure 2-3 demonstrates. +Using the [options pattern](../../core/extensions/options.md), settings access is similar but is strongly typed and more specific to the setting(s) needed by the consuming class, as Figure 2-3 demonstrates. ```csharp public class PositionOptions @@ -92,7 +92,7 @@ services.Configure(Configuration.GetSection(PositionOptions.Pos ## Migrate configuration -When considering how to port an app's configuration settings from .NET Framework to .NET Core, the first step is to identify all of the configuration settings that are being used. Most of these will be in the *web.config* file in the app's root folder, but some apps expect settings to be found in the shared *machine.config* file as well. +When considering how to port an app's configuration settings from .NET Framework to .NET Core, the first step is to identify all of the configuration settings that are being used. Most of these will be in the *web.config* file in the app's root folder, but some apps expect settings to be found in the shared *machine.config* file as well. These settings will include elements of the `appSettings` element, the `connectionStrings` element, and any custom configuration elements as well. In .NET Core, all of these settings are typically stored in the *appsettings.json* file. Once all settings in the config files have been cataloged, the next step should be to identify where and how the settings are used in the app itself. If some settings aren't being used, these can probably be omitted from the migration. For each setting, note all of the places it's being used so you can be sure you don't miss any when you migrate the code. diff --git a/docs/architecture/porting-existing-aspnet-apps/deployment-strategies.md b/docs/architecture/porting-existing-aspnet-apps/deployment-strategies.md index 9e92e31b0ad0c..6770b9a2cdee4 100644 --- a/docs/architecture/porting-existing-aspnet-apps/deployment-strategies.md +++ b/docs/architecture/porting-existing-aspnet-apps/deployment-strategies.md @@ -16,7 +16,7 @@ Because .NET Core runs on Linux, you'll find some hosting options available that * Your organization has infrastructure or expertise. * Hosting providers offer attractive features or pricing for Linux-based hosting. -.NET Core opens to door to these options. +.NET Core opens the door to these options. ## Cloud native development diff --git a/docs/architecture/porting-existing-aspnet-apps/example-migration-eshop.md b/docs/architecture/porting-existing-aspnet-apps/example-migration-eshop.md index da9b72c254250..1dc443dbdbc99 100644 --- a/docs/architecture/porting-existing-aspnet-apps/example-migration-eshop.md +++ b/docs/architecture/porting-existing-aspnet-apps/example-migration-eshop.md @@ -21,7 +21,7 @@ This chapter demonstrates how to perform many of the upgrade steps by hand. Alte ## Run *ApiPort* to identify problematic APIs -The first step in preparing to migrate is to run the *ApiPort* tool. The tool identifies how many .NET Framework APIs the app calls and how many of these have .NET Standard or .NET Core equivalents. Focus primarily on your own app's logic, not third-party dependencies, and pay attention to `System.Web` dependencies that will need to be ported. The ApiPort tool was introduced in the last chapter on [understanding and updating dependencies](/understand-update-dependencies.md). +The first step in preparing to migrate is to run the *ApiPort* tool. The tool identifies how many .NET Framework APIs the app calls and how many of these have .NET Standard or .NET Core equivalents. Focus primarily on your own app's logic, not third-party dependencies, and pay attention to `System.Web` dependencies that will need to be ported. The ApiPort tool was introduced in the last chapter on [understanding and updating dependencies](understand-update-dependencies.md). After [installing and configuring the *ApiPort* tool](../../standard/analyzers/portability-analyzer.md), run the analysis from within Visual Studio, as shown in Figure 4-2. @@ -53,7 +53,7 @@ Most of the incompatible types refer to `Controller` and various related attribu ## Update project files and NuGet reference syntax -Next, migrate from the older *.csproj* file structure to the newer, simpler structure introduced with .NET Core. In doing so, you'll also migrate from using a *packages.config* file for NuGet references to using `` elements in the project file. +Next, migrate from the older *.csproj* file structure to the newer, simpler structure introduced with .NET Core. In doing so, you'll also migrate from using a *packages.config* file for NuGet references to using `` elements in the project file. Old-style project files may also use `` elements, so it usually makes sense to migrate all NuGet package references to this format first, before upgrading to the new project file format. The original project's *eShopLegacyMVC.csproj* file is 418 lines long. A sample of the project file is shown in Figure 4-6. To offer a sense of its overall size and complexity, the right side of the image contains a miniature view of the entire file. @@ -69,7 +69,7 @@ In addition to the C# project file, NuGet dependencies are stored in a separate **Figure 4-7.** The *packages.config* file. -After upgrading to the new *.csproj* file format, you can migrate *packages.config* in class library projects using Visual Studio. This functionality doesn't work with ASP.NET projects, however. [Learn more about migrating *packages.config* to `` in Visual Studio](/nuget/consume-packages/migrate-packages-config-to-package-reference). If you have a large number of projects to migrate, [this community tool may help](https://github.com/MarkKharitonov/NuGetPCToPRMigrator). +You can migrate *packages.config* in class library projects using Visual Studio. This functionality doesn't work with ASP.NET projects, however. [Learn more about migrating *packages.config* to `` in Visual Studio](/nuget/consume-packages/migrate-packages-config-to-package-reference). If you have a large number of projects to migrate, [this community tool may help](https://github.com/MarkKharitonov/NuGetPCToPRMigrator). If you're using a tool to migrate the project file to the new format, you should do that after you've finished migrating all NuGet references to use ``. ## Create new ASP.NET Core project @@ -307,20 +307,13 @@ Building again reveals one more error loading jQuery Validation on the *Create* ``` -The last thing to fix in the views is the reference to `Session` to display how long the app has been running, and on which machine. We can collect this data in `Startup` as static variables and display the variables on the layout page. Add the following properties to *Startup.cs*: - -```csharp -public static DateTime StartTime { get; } = DateTime.UtcNow; -public static string MachineName { get; } = Environment.MachineName; -``` - -Then replace the content of the footer in the layout with the following code: +The last thing to fix in the views is the reference to `Session` to display how long the app has been running, and on which machine. We can display this data directly in the site's *_Layout.cshtml* by using `System.Environment.MachineName` and `System.Diagnostics.Process.GetCurrentProcess().StartTime`: ```razor

-@eShopPorted.Startup.MachineName - @eShopPorted.Startup.StartTime.ToString() UTC +@Environment.MachineName - @System.Diagnostics.Process.GetCurrentProcess().StartTime.ToString() UTC
``` @@ -442,7 +435,7 @@ public void ConfigureServices(IServiceCollection services) } ``` -The preceding code is the minimal configuration required to get MVC features working. There are many additional features that can be configured from this call, but for now this will suffice to build the app. Running it now routes the default request properly, but since we've not yet configured DI, an error occurs while activating `CatalogController`, because no implementation of type `ICatalogService` has been provided yet. We'll return to configure MVC further in a moment. For now, let's migrate the app's dependency injection. +The preceding code is the minimal configuration required to get MVC features working. There are many additional features that can be configured from this call (some of which are detailed later in this chapter), but for now this will suffice to build the app. Running it now routes the default request properly, but since we've not yet configured DI, an error occurs while activating `CatalogController`, because no implementation of type `ICatalogService` has been provided yet. We'll return to configure MVC further in a moment. For now, let's migrate the app's dependency injection. #### Migrate dependency injection configuration diff --git a/docs/architecture/porting-existing-aspnet-apps/hosting-differences.md b/docs/architecture/porting-existing-aspnet-apps/hosting-differences.md index c7a995bb9356c..8fcaeeba09b52 100644 --- a/docs/architecture/porting-existing-aspnet-apps/hosting-differences.md +++ b/docs/architecture/porting-existing-aspnet-apps/hosting-differences.md @@ -11,11 +11,12 @@ ASP.NET MVC apps are hosted in IIS, and may rely on IIS configuration for their [ASP.NET Core apps can run on a number of different servers](/aspnet/core/fundamentals/servers/). The default cross platform server, Kestrel, is a good default choice. Apps running in Kestrel can be hosted by IIS, running in a separate process. On Windows, apps can also run in process on IIS or using HTTP.sys. Kestrel is generally recommended for best performance. HTTP.sys can be used in scenarios where the app is exposed to the Internet and required capabilities are supported by HTTP.sys but not Kestrel. -Kestrel does not have an equivalent to IIS modules (though apps hosted in IIS can still take advantage of IIS modules). To achieve equivalent behavior, middleware configured in the ASP.NET Core app itself is typically used. +Kestrel does not have an equivalent to IIS modules (though apps hosted in IIS can still take advantage of IIS modules). To achieve equivalent behavior, [middleware](/aspnet/core/fundamentals/middleware/) configured in the ASP.NET Core app itself is typically used. ## References - [IIS Modules](/iis/get-started/introduction-to-iis/iis-modules-overview) +- [ASP.NET Core Middleware](/aspnet/core/fundamentals/middleware/) - [ASP.NET Core Servers](/aspnet/core/fundamentals/servers/) >[!div class="step-by-step"] diff --git a/docs/architecture/porting-existing-aspnet-apps/identify-migration-sequence.md b/docs/architecture/porting-existing-aspnet-apps/identify-migration-sequence.md index 776a7872af6db..49a483faf9108 100644 --- a/docs/architecture/porting-existing-aspnet-apps/identify-migration-sequence.md +++ b/docs/architecture/porting-existing-aspnet-apps/identify-migration-sequence.md @@ -56,8 +56,8 @@ Watch an overview of how to employ this approach in this [dotNetConf presentatio - Migrate third-party NuGet dependencies - Migrate apps to use new *.csproj* file format -- Migrate apps to ASP.NET Core (targeting .NET Framework) - Update internal NuGet dependencies to .NET Standard +- Migrate apps to ASP.NET Core (targeting .NET Framework) - Update all apps to target .NET Core 3.1 When automating a large suite of apps, it helps significantly if they follow consistent coding guidelines and project organization. Automation efforts rely on this consistency to be effective. In addition to parsing and migrating project files, common code patterns can be migrated automatically. Some code pattern examples include differences in how controller actions are declared or how they return results. diff --git a/docs/architecture/porting-existing-aspnet-apps/incremental-migration-strategies.md b/docs/architecture/porting-existing-aspnet-apps/incremental-migration-strategies.md index 36ebf7cd18a54..fdede4087f604 100644 --- a/docs/architecture/porting-existing-aspnet-apps/incremental-migration-strategies.md +++ b/docs/architecture/porting-existing-aspnet-apps/incremental-migration-strategies.md @@ -7,12 +7,20 @@ ms.date: 11/13/2020 # Strategies for migrating incrementally -The biggest challenge with migrating any large app is determining how to break the process into smaller tasks. There are several strategies that can be applied for this purpose, including breaking the app into horizontal layers such as UI, data access, business logic, or breaking up the app into separate, smaller apps. Another strategy is to upgrade some or all of the app to different framework versions on the way to a recent .NET Core release. One approach you could use, is to migrate [vertical slices](https://deviq.com/practices/vertical-slices) of the app, rather than attempting to migrate one horizontal layer at a time. Let's consider each of these different approaches. +The biggest challenge with migrating any large app is determining how to break the process into smaller tasks. There are several strategies that can be applied for this purpose, including breaking the app into horizontal layers such as UI, data access, business logic, or breaking up the app into separate, smaller apps. Another strategy is to upgrade some or all of the app to different framework versions on the way to a recent .NET Core release. One approach you could use is to migrate [vertical slices](https://deviq.com/practices/vertical-slices) of the app, rather than attempting to migrate one horizontal layer at a time. Let's consider each of these different approaches. -Consider the challenge of migrating a large ASP.NET 4.5 app. One approach is to migrate the entire app directly from .NET Framework 4.5 to .NET Core 3.1. However, this approach needs to account for every breaking change between the two frameworks and versions, which are substantial. +## Migrating slice by slice + +One successful approach to migrating is to identify vertical slices of functionality and migrate them to the target platform one by one. The first step is to create a new ASP.NET Core 3.1 or 5 app. Next, identify the individual page or API endpoint that will be migrated first. Build out just the necessary functionality to support this one route in the ASP.NET Core app. Then use HTTP rewriting and/or a reverse proxy to start sending requests for these pages or endpoints to the new app rather than the ASP.NET app. This approach is well-suited to API projects, but can also work for many MVC apps. + +When migrating slice by slice, the entire stack of the individual API endpoint or requested route is recreated in the new project or solution. The very first such slice typically requires the most effort, since it will typically need several projects to be created and decisions to be made about data access and solution organization. Once the first slice's functionality mirrors the existing app's, it can be deployed and the existing app can redirect to it or simply be removed. This approach is then repeated until the entire app has been ported to the new structure. + +Some specific guidance on how to follow this strategy using IIS is covered in [Chapter 5, Deployment Scenarios](deployment-scenarios.md). ## Migrating layer by layer +Consider the challenge of migrating a large ASP.NET 4.5 app. One approach is to migrate the entire app directly from .NET Framework 4.5 to .NET Core 3.1. However, this approach needs to account for every breaking change between the two frameworks and versions, which are substantial. Performing this work on one project at a time provides a set of stepping stones so that the entire solution doesn't need to be moved at once. + One recent addition to the .NET ecosystem that helps with interoperability between different .NET frameworks is [.NET Standard](https://dotnet.microsoft.com/platform/dotnet-standard). .NET Standard allows libraries to build against the agreed upon set of common APIs, ensuring they can be used in any .NET app. .NET Standard 2.0 is notable because it covers most base class library functionality used by most .NET Framework and .NET Core apps. Unfortunately, the earliest version of .NET with support for .NET Standard 2.0 is .NET Framework 4.6.1, and there are a number of updates in .NET Framework 4.8 that make it a compelling choice for initial upgrades. One approach to incrementally upgrade a .NET Framework 4.5 system layer-by-layer is to first update its class library dependencies to .NET Framework 4.8. Then, modify these libraries to be .NET Standard class libraries. Use multi-targeting and conditional compilation, if necessary. This step can be helpful in scenarios where app dependencies require .NET Framework and cannot easily be ported directly to use .NET Standard and .NET Core. Since .NET Framework libraries can be consumed by ASP.NET Core 2.1 apps, the next step is to migrate some or all of the web functionality of the app to ASP.NET Core 2.1 (as described in the [previous chapter](choose-net-core-version.md)). This is a "bottom up" approach, starting with low level class library dependencies and working up to the web app entry point. @@ -25,12 +33,6 @@ Instead of a "bottom up" approach, another alternative is to start with the web Instead of a "bottom up" approach, another alternative is to start with the web app (or even the entire solution) and use an automated tool to assist with the upgrade. The [.NET Upgrade Assistant tool](https://aka.ms/dotnet-upgrade-assistant) can be used to help upgrade .NET Framework apps to .NET Core / .NET 5. It automates many of the common tasks related to upgrading apps, such as modifying project file format, setting appropriate target frameworks, updating NuGet dependencies, and more. -## Migrating slice by slice - -Another approach to the migration would be to identify vertical slices of functionality, and migrate them to the target platform one by one. The first step would be to create a new ASP.NET Core 3.1 or 5 app. Next, identify the individual page or API endpoint that will be migrated first. Build out just the necessary functionality to support this one route in the ASP.NET Core app. Then use HTTP rewriting and/or a reverse proxy to start sending requests for these pages or endpoints to the new app rather than the ASP.NET app. - -Some specific guidance on how to follow this strategy using IIS is covered in [Chapter 5, Deployment Scenarios](deployment-scenarios.md). - ## References - [What is .NET Standard?](https://dotnet.microsoft.com/platform/dotnet-standard) diff --git a/docs/architecture/porting-existing-aspnet-apps/middleware-modules-handlers.md b/docs/architecture/porting-existing-aspnet-apps/middleware-modules-handlers.md index 05bee2430645b..48192d5b846b6 100644 --- a/docs/architecture/porting-existing-aspnet-apps/middleware-modules-handlers.md +++ b/docs/architecture/porting-existing-aspnet-apps/middleware-modules-handlers.md @@ -21,6 +21,63 @@ ASP.NET Core defines a request pipeline in each app's `Configure` method. This r Behavior in an ASP.NET MVC app that uses HTTP modules is probably best suited to [custom middleware](/aspnet/core/fundamentals/middleware/?preserve-view=true&view=aspnetcore-3.1). Custom HTTP handlers can be replaced with custom routes or endpoints that respond to the same path. +## Accessing HttpContext + +Many .NET apps reference the current request's context through `HttpContext.Current`. This static access can be a common source of problems with testing and other code usage outside of individual requests. When building ASP.NET Core apps, access to the current HttpContext should be provided as a method parameter on middleware, as this sample demonstrates: + +```csharp +public class Middleware +{ + private readonly RequestDelegate _next; + + public Middleware(RequestDelegate next) + { + _next = next; + } + + public Task Invoke(HttpContext httpContext) + { + return _next(httpContext); + } +} +``` + +Similarly, ASP.NET Core filters pass a context argument to their methods, from which the current HttpContext can be accessed: + +```csharp +public class MyActionFilterAttribute : ActionFilterAttribute +{ + public override void OnResultExecuting(ResultExecutingContext context) + { + var headers = context.HttpContext.Request.Headers; + // do something based on a header + + base.OnResultExecuting(context); + } +} +``` + +If you have components or services that require access to HttpContext, rather than using a static call like `HttpContext.Current` you should instead use constructor dependency injection and the interface: + +```csharp +public class MyService +{ + private readonly IHttpContextAccessor _httpContextAccessor; + + public MyService(IHttpContextAccessor httpContextAccessor) + { + _httpContextAccessor = httpContextAccessor; + } + + public void DoSomething() + { + var currentContext = _httpContextAccessor.HttpContext; + } +} +``` + +This approach eliminates the static coupling of the method to the current context while providing access in a testable fashion. + ## References - [ASP.NET HTTP modules and HTTP handlers](/troubleshoot/aspnet/http-modules-handlers) diff --git a/docs/architecture/porting-existing-aspnet-apps/migrate-aspnet-core-2-1.md b/docs/architecture/porting-existing-aspnet-apps/migrate-aspnet-core-2-1.md index 394ae47becc3b..f0ceaad87288a 100644 --- a/docs/architecture/porting-existing-aspnet-apps/migrate-aspnet-core-2-1.md +++ b/docs/architecture/porting-existing-aspnet-apps/migrate-aspnet-core-2-1.md @@ -7,7 +7,7 @@ ms.date: 11/13/2020 # Migrate to ASP.NET Core 2.1 -ASP.NET Core 2.1 is an interesting release because it's the only currently supported .NET Core release to support both .NET Core and .NET Framework runtimes. As such, it may offer an easier upgrade path for some apps when compared to upgrading all parts of the app to .NET Core at once. As an LTS release, support for .NET Core 2.1 will continue through August 2021. Support for ASP.NET Core 2.1 running on .NET Framework will continue for as long as its underlying .NET Framework is supported. +ASP.NET Core 2.1 is an interesting release because it's the only currently supported ASP.NET Core release to support both .NET Core and .NET Framework runtimes. As such, it may offer an easier upgrade path for some apps when compared to upgrading all parts of the app to .NET Core at once. As an LTS release, support for .NET Core 2.1 will continue through August 2021. Support for ASP.NET Core 2.1 running on .NET Framework will continue for as long as its underlying .NET Framework is supported. ## Should apps run on .NET Framework with ASP.NET Core 2.1 diff --git a/docs/architecture/porting-existing-aspnet-apps/migration-considerations.md b/docs/architecture/porting-existing-aspnet-apps/migration-considerations.md index b4e80b3902648..c25e1056f9f2c 100644 --- a/docs/architecture/porting-existing-aspnet-apps/migration-considerations.md +++ b/docs/architecture/porting-existing-aspnet-apps/migration-considerations.md @@ -45,7 +45,7 @@ The biggest reason to stay on .NET Framework is when an app isn't under active d ### Application domains -Application domains (AppDomains) isolate apps from one another. AppDomains require runtime support and can be expensive. Creating additional app domains isn't supported, and there are no plans to add this capability to .NET Core in the future. For code isolation, use separate processes or containers as an alternative. +Application domains (AppDomains) isolate apps from one another. AppDomains require runtime support and can be expensive. Creating additional app domains isn't supported, and there are no plans to add this capability to .NET Core in the future. For code isolation, use separate processes or containers as an alternative. Some customers use AppDomains as a way of unloading assemblies. In .NET Core [AssemblyLoadContext](../../standard/assembly/unloadability.md) provides an alternative way to unload assemblies. ### WCF @@ -53,6 +53,8 @@ Server-side WCF isn't supported in .NET Core. .NET Core supports WCF clients but There is a [WCF client port available from the .NET Foundation](../../core/dotnet-five.md#windows-communication-foundation). It is entirely open source, cross platform, and supported by Microsoft. There is also a community-supported [CoreWCF project](https://github.com/CoreWCF/CoreWCF) that is *not* officially supported by Microsoft. +To learn more about migrating from WCF to gRPC, consult the [gRPC for WCF Developers](../grpc-for-wcf-developers/index.md) ebook. + ### Remoting .NET Remoting was identified as a problematic architecture. It's used for cross-AppDomain communication, which is no longer supported. Also, Remoting requires runtime support, which is expensive to maintain. For these reasons, .NET Remoting isn't supported on .NET Core, and the product team doesn't plan on adding support for it in the future. There are several alternative messaging strategies and implementations you can use to replace remoting in your .NET Core apps. diff --git a/docs/architecture/porting-existing-aspnet-apps/more-migration-scenarios.md b/docs/architecture/porting-existing-aspnet-apps/more-migration-scenarios.md index 2136e8a69e828..e7ff4b67001c2 100644 --- a/docs/architecture/porting-existing-aspnet-apps/more-migration-scenarios.md +++ b/docs/architecture/porting-existing-aspnet-apps/more-migration-scenarios.md @@ -112,10 +112,415 @@ public IActionResult Index() This will default to returning the data in JSON format. XML and other formats will be used [if the app has been configured with the appropriate formatter](/aspnet/core/web-api/advanced/formatting). +## Custom model binding + +Most ASP.NET MVC and Web API apps make use of model binding. The default model binding syntax migrates fairly seamlessly between these apps and ASP.NET Core MVC. However, in some cases customers have written [custom model binders](/aspnet/web-api/overview/formats-and-model-binding/parameter-binding-in-aspnet-web-api#model-binders) to support specific model types or usage scenarios. Custom model binders in ASP.NET MVC and Web API projects use separate `IModelBinder` interfaces defined in `System.Web.Mvc` and `System.Web.Http` namespaces, respectively. In both cases, the custom binder exposes a `Bind` method that accepts a controller or action context and a model binding context as arguments. + +Once the custom binder is created, it must be registered with the app. This step requires creating another type, a `ModelBinderProvider`, which acts as a factory and creates the model binder during a request. Binders can be added during `ApplicationStart` in MVC apps as shown: + +```csharp +ModelBinderProviders.BinderProviders.Insert(0, new MyCustomBinderProvider()); // MVC +``` + +In Web API apps, custom binders can be referenced using attributes. The `ModelBinder` attribute can be added to action method parameters or to the parameter's type definition, as shown: + +```csharp +// attribute on action method parameter +public HttpResponseMessage([ModelBinder(typeof(MyCustomBinder))] CustomDTO custom) +{ +} + +// attribute on type +[ModelBinder(typeof(MyCustomBinder))] +public class CustomDTO +{ +} +``` + +To register a model binder globally in ASP.NET Web API, its provider must be added during app startup: + +```csharp +public static class WebApiConfig +{ + public static void Register(HttpConfiguration config) + { + var provider = new CustomModelBinderProvider( + typeof(CustomDTO), new CustomModelBinder()); + config.Services.Insert(typeof(ModelBinderProvider), 0, provider); + + // ... + } +} +``` + +When migrating [custom model providers to ASP.NET Core](/aspnet/core/mvc/advanced/custom-model-binding#custom-model-binder-sample), the Web API pattern is closer to the ASP.NET Core approach than the ASP.NET MVC 5. The main differences between ASP.NET Core's `IModelBinder` interface and Web API's is that the ASP.NET Core method is async (`BindModelAsync`) and it only requires a single `BindingModelContext` parameter instead of two parameters like Web API's version required. In ASP.NET Core, you can use a `[ModelBinder]` attribute on individual action method parameters or their associated types. You can also create a `ModelBinderProvider` that will be used globally within the app where appropriate. To configure such a provider, you would add code to `Startup` in `ConfigureServices`: + +```csharp +public void ConfigureServices(IServiceCollection services) +{ + services.AddControllers(options => + { + options.ModelBinderProviders.Insert(0, new CustomModelBinderProvider()); + }); +} +``` + +## Media formatters + +ASP.NET Web API supports multiple media formats and can be extended by using custom media formatters. The docs describe an [example CSV Media Formatter](/aspnet/web-api/overview/formats-and-model-binding/media-formatters#example-creating-a-csv-media-formatter) that can be used to send data in a comma-separated value format. If your Web API app uses custom media formatters, you'll need to convert them to [ASP.NET Core custom formatters](/aspnet/core/web-api/advanced/custom-formatters). + +To create a custom formatter in Web API 2, you inherited from an appropriate base class and then added the formatter to the Web API pipeline using the `HttpConfiguration` object: + +```csharp +public static void ConfigureApis(HttpConfiguration config) +{ + config.Formatters.Add(new ProductCsvFormatter()); +} +``` + +In ASP.NET Core, the process is similar. ASP.NET Core supports both input formatters (used by model binding) and output formatters (used to format responses). Adding a custom formatter to output responses in a specific way involves inheriting from an appropriate base class and adding the formatter to MVC in `Startup`: + +```csharp +public void ConfigureServices(IServiceCollection services) +{ + services.AddControllers(options => + { + options.InputFormatters.Insert(0, new CustomInputFormatter()); + options.OutputFormatters.Insert(0, new CustomOutputFormatter()); + }); +} +``` + +You'll find a complete list of base classes in the namespace. + +The steps to migrate from a Web API formatter to an ASP.NET Core MVC formatter are: + +1. Identify an appropriate base class for the new formatter. +1. Create a new instance of the base class and implement its required methods. +1. Copy over the functionality from the Web API formatter to the new implementation. +1. Configure MVC in the ASP.NET Core App's `ConfigureServices` method to use the new formatter. + +## Custom filters + +Filters are used in ASP.NET Core apps to execute code before and/or after certain stages in the request processing pipeline. ASP.NET MVC and Web API also use filters in much the same way, but the details vary. For instance, [ASP.NET MVC supports four kinds of filters](/aspnet/mvc/overview/older-versions-1/controllers-and-routing/understanding-action-filters-cs#the-different-types-of-filters). ASP.NET Web API 2 supports similar filters, and both MVC and Web API included attributes to [override filters](/dotnet/api/system.web.mvc.filters.ioverridefilter). + +The most common filter used in ASP.NET MVC and Web API apps is the action filter, which is defined by an [IActionFilter interface](/dotnet/api/system.web.mvc.iactionfilter). This interface provides methods for before (`OnActionExecuting`) and after (`OnActionExecuted`) which can be used to execute code before and/or after an action executes, as noted for each method. + +ASP.NET Core continues to support filters, and its unification of MVC and Web API means there is only one approach to their implementation. The [docs include detailed coverage of the five (5) kinds of filters built into ASP.NET Core MVC](/aspnet/core/mvc/controllers/filters#filter-types). All of the filter variants supported in ASP.NET MVC and ASP.NET Web API have associated versions in ASP.NET Core, so migration is generally just a matter of identifying the appropriate interface and/or base class and migrating the code over. + +In addition to the synchronous interfaces, ASP.NET Core also provides async interfaces like `IAsyncActionFilter` which provide a single async method that can be used to incorporate code to run both before and after the action, as shown: + +```csharp +public class SampleAsyncActionFilter : IAsyncActionFilter +{ + public async Task OnActionExecutionAsync( + ActionExecutingContext context, + ActionExecutionDelegate next) + { + // Do something before the action executes. + + // next() calls the action method. + var resultContext = await next(); + // resultContext.Result is set. + // Do something after the action executes. + } +} +``` + +When migrating async code (or code that should be async), teams should consider leveraging the built in async types that are provided for this purpose. + +Most ASP.NET MVC and Web API apps do not use a large number of custom filters. Since the approach to filters in ASP.NET Core MVC is closely aligned with filters in ASP.NET MVC and Web API, the migration of custom filters is generally fairly straightforward. Be sure to read the detailed documentation on filters in ASP.NET Core's docs, and once you're sure you have a good understanding of them, port the logic from the old system to the new system's filters. + +## Route constraints + +ASP.NET Core uses route constraints to help ensure requests are routed properly to route a request. [ASP.NET Core supports a large number of different route constraints for this purpose]/aspnet/core/fundamentals/routing#route-constraint-reference). Route constraints can be applied in the route table, but most apps built with ASP.NET MVC 5 and/or [ASP.NET Web API 2](/aspnet/web-api/overview/web-api-routing-and-actions/attribute-routing-in-web-api-2#route-constraints) use inline route constraints applied to attribute routes. Inline route constraints use a format like this one: + +```csharp +[Route("/customer/{id:int}")] +``` + +The `:int` after the `id` route parameter constrains the value to match the the `int` type. One benefit of using route constraints is that they allow for two otherwise-identical routes to exist where the parameters differ only by their type. This allows for the equivalent of [method overloading](../../standard/design-guidelines/member-overloading.md) of routes based solely on parameter type. + +The set of route constraints, their syntax, and usage is very similar between all three approaches. Custom route constraints are fairly rare in customer applications. If your app uses a custom route constraint and needs to port to ASP.NET Core, the docs include examples showing [how to create custom route constraints in ASP.NET Core](/aspnet/core/fundamentals/routing#custom-route-constraints). Essentially all that's required is to implement `IRouteConstraint` and its `Match` method, and then add the custom constraint when configuring routing for the app: + +```csharp +public void ConfigureServices(IServiceCollection services) +{ + services.AddControllers(); + + services.AddRouting(options => + { + options.ConstraintMap.Add("customName", typeof(MyCustomConstraint)); + }); +} +``` + +This is very similar to how custom constraints are used in ASP.NET Web API, which uses `IHttpRouteConstraint` and configures it using a resolver and a call to `HttpConfiguration.MapHttpAttributeRoutes`: + +```csharp +public static class WebApiConfig +{ + public static void Register(HttpConfiguration config) + { + var constraintResolver = new DefaultInlineConstraintResolver(); + constraintResolver.ConstraintMap.Add("nonzero", typeof(CustomConstraint)); + + config.MapHttpAttributeRoutes(constraintResolver); + } +} +``` + +ASP.NET MVC 5 follows a very similar approach, using `IRouteConstraint` for its interface name and configuring the constraint as part of route configuration: + +```csharp +public class RouteConfig +{ + public static void RegisterRoutes(RouteCollection routes) + { + routes.IgnoreRoute("{resource}.axd/{*pathInfo}"); + + var constraintsResolver = new DefaultInlineConstraintResolver(); + constraintsResolver.ConstraintMap.Add("values", typeof(ValuesConstraint)); + routes.MapMvcAttributeRoutes(constraintsResolver); + } +} +``` + +Migrating route constraint usage as well as custom route constraints to ASP.NET Core is typically very straightforward. + +## Custom route handlers + +Another fairly advanced feature of ASP.NET MVC 5 is route handlers. Custom route handlers implement `IRouteHandler`, which includes a single method that returns an `IHttpHandler` for a give request. The `IHttpHandler`, in turn, exposes an `IsReusable` property and a single `ProcessRequest` method. In ASP.NET MVC 5, you can configure a particular route in the route table to use your custom handler: + +```csharp +public static void RegisterRoutes(RouteCollection routes) +{ + routes.IgnoreRoute("{resource}.axd/{*pathInfo}"); + + routes.Add(new Route("custom", new CustomRouteHandler())); +} +``` + +To migrate custom route handlers from ASP.NET MVC 5 to ASP.NET Core, you can either use a filter (such as an action filter) or a custom [`IRouter`](/dotnet/api/microsoft.aspnetcore.routing.irouter). The filter approach is relatively straightforward, and can be added as a global filter when MVC is added to `ConfigureServices` in *Startup.cs*. + +```csharp +public void ConfigureServices(IServiceCollection services) +{ + services.AddMvc(options => + { + options.Filters.Add(typeof(CustomActionFilter)); + }); +} +``` + +The `IRouter` option requires implementing the interface's `RouteAsync` and `GetVirtualPath` methods. The custom router is added to the request pipeline in the `Configure` method in *Startup.cs*. + +```csharp +public void Configure(IApplicationBuilder app) +{ + // ... + app.UseMvc(routes => + { + routes.Routes.Add(new CustomRouter(routes.DefaultHandler)); + }); +} +``` + +In ASP.NET Web API, these handlers are referred to as [custom message handlers](/aspnet/web-api/overview/advanced/http-message-handlers#custom-message-handlers), rather than *route handlers*. Message handlers must derive from `DelegatingHandler` and override its `SendAsync` method. Message handlers can be chained together to form a pipeline in a fashion that is very similar to ASP.NET Core middleware and its request pipeline. + +ASP.NET Core has no `DelegatingHandler` type or separate message handler pipeline. Instead, such handlers should be migrated using global filters, custom `IRouter` instances (see above), or custom middleware. ASP.NET Core MVC filters and `IRouter` types have the advantage of having built-in access to MVC constructs like controllers and actions, while middleware is a lower level approach that has no ties to MVC. This makes it more flexible but also requires more effort if you need to access MVC components. + +## CORS support + +CORS, or Cross-Origin Resource Sharing, is a W3C standard that allows servers to accept requests that don't originate from responses they've served. ASP.NET MVC 5 and ASP.NET Web API 2 support CORS in different ways. The simplest way to enable CORS support in ASP.NET MVC 5 is with an action filter like this one: + +```csharp +public class AllowCrossSiteAttribute : ActionFilterAttribute +{ + public override void OnActionExecuting(ActionExecutingContext filterContext) + { + filterContext.RequestContext.HttpContext.Response.AddHeader( + "Access-Control-Allow-Origin", "example.com"); + base.OnActionExecuting(filterContext); + } +} +``` + +ASP.NET Web API can also use such a filter, but it has [built-in support for enabling CORS](/aspnet/web-api/overview/security/enabling-cross-origin-requests-in-web-api#enable-cors) as well: + +```csharp +public static class WebApiConfig +{ + public static void Register(HttpConfiguration config) + { + config.EnableCors(); + // ... + } +} +``` + +Once this is added, you can configure allowed origins, headers, and methods using the `EnableCors` attribute, like so: + +```csharp +[EnableCors(origins: "https://dot.net", headers: "*", methods: "*")] +public class TestController : ApiController +{ + // Controller methods not shown... +} +``` + +Before migrating your CORS implementation from ASP.NET MVC 5 or ASP.NET Web API 2, be sure to review [how CORS works](/aspnet/web-api/overview/security/enabling-cross-origin-requests-in-web-api#how-cors-works) and create some automated tests that demonstrate CORS is working as expected in your current system. + +In ASP.NET Core, there are three built-in ways to enable CORS: + +- [Configured via policy](/aspnet/core/security/cors?#cors-with-named-policy-and-middleware) in `ConfigureServices` +- Enabled with [endpoint routing](/aspnet/core/security/cors?#enable-cors-with-endpoint-routing) +- Enabled with the [`EnableCors` attribute](/aspnet/core/security/cors?view=aspnetcore-5.0#enable-cors-with-attributes) + +Each of these approaches is covered in detail in the docs, which are linked from the above options. Which one you choose will largely depend on how your existing app supports CORS. If the app uses attributes, you can probably migrate to use the `EnableCors` attribute most easily. If your app uses filters, you could continue using that approach (though it's not the typical approach used in ASP.NET Core), or migrate to use attributes or policies. Endpoint routing is a relatively new feature introduced with ASP.NET Core 3 and as such it doesn't have a close analog in ASP.NET MVC 5 or ASP.NET Web API 2 apps. + +## Custom areas + +Many ASP.NET MVC apps use Areas to organize the project. Areas typically reside in the root of the project in an *Areas* folder, and must be registered when the application starts, typically in `Application_Start()`: + +```csharp +AreaRegistration.RegisterAllAreas(); +``` + +An alternative to registering all areas in startup is to use the `RouteArea` attribute on individual controllers: + +```csharp +[RouteArea("Admin")] +public class SomeController : Controller +``` + +When using Areas, additional arguments are passed into HTML helper methods to generate links to actions in different areas: + +```cshtml +@Html.ActionLink("News", "Index", "News", new { area = "News" }, null) +``` + +ASP.NET Web API apps don't typically use areas explicitly, since their controllers can be placed in any folder in the project. Teams can use any folder structure they like to organize their API controllers. + +[Areas](/aspnet/core/mvc/controllers/areas) are supported in ASP.NET Core MVC. The approach used is nearly identical to the use of areas in ASP.NET MVC 5. Developers migrating code using areas should keep in mind the following differences: + +- `AreaRegistration.RegisterAllAreas` is not used in ASP.NET Core MVC +- Areas are applied using the `[Area("name")]` attribute (not `RouteArea` as in ASP.NET MVC 5) +- Areas can be added to the route table templates, if desired (or they can use attribute routing) + +To add area support to the route table in ASP.NET Core MVC, you would add the following in `Configure` in *Startup.cs*: + +```csharp +app.UseEndpoints(endpoints => +{ + endpoints.MapControllerRoute( + name: "MyArea", + pattern: "{area:exists}/{controller=Home}/{action=Index}/{id?}"); + + endpoints.MapControllerRoute( + name: "default", + pattern: "{controller=Home}/{action=Index}/{id?}"); +}); +``` + +Areas can also be used with attribute routing, using the `{area}` keyword in the route definition (it's one of several [reserved routing names](/aspnet/core/mvc/controllers/routing#reserved-routing-names) that can be used with route templates). + +Tag helpers support areas with the `asp-area` attribute, which can be used to generate links in Razor views and pages: + +```razor + +``` + +If you're migrating to Razor Pages you will need to use an *Areas* folder in your *Pages* folder. For more information, see [Areas with Razor Pages](/aspnet/core/mvc/controllers/areas#areas-with-razor-pages). + +In addition to the above guidance, teams should review [how routing in ASP.NET Core works with areas](/aspnet/core/mvc/controllers/routing#areas) as part of their migration planning process. + +## Integration tests for ASP.NET MVC and ASP.NET Web API + +Integration tests are automated tests that verify several different parts of an app work together correctly. Writing integration tests for ASP.NET MVC and ASP.NET Web API usually involved deploying the app to a real web server, such as a local instance of IIS or IIS Express, and then making requests to this hosted application using an HTTP client. Some of these tests may interact with the client-side user interface using browser automation tools like [Selenium](https://www.selenium.dev/), though often these are referred to as *UI tests* rather than integration tests. + +If your migrated app shares the same behavior as its original version, whatever existing technology the team is using to perform integration tests (and UI tests) should continue to work just as it did before. These tests are usually indifferent to the underlying technology used to host the app they're testing, and interact with it only through HTTP requests. Where things may get more challenging is with how the tests interact with the app to get it into a known good state prior to each test. This may require some migration effort, since configuration and startup are significantly different in ASP.NET Core compared to ASP.NET MVC or ASP.NET Web API. + +Teams should strongly consider migrating their integration tests to use [ASP.NET Core's built-in integration testing](/aspnet/core/test/integration-tests) support. In ASP.NET Core, apps can be tested by deploying them to a `TestHost`, which is configured using a `WebApplicationFactory`. There's a little bit of setup required to host the app for testing, but once this is in place, creating individual integration tests is very straightforward. + +One of the best features of ASP.NET Core's integration testing support is that the app is hosted in memory. There's no need to configure a real webserver to host the app. There's no need to use a browser automation tool (if you're only testing ASP.NET Core and not client-side behavior). Many of the problems that can be encountered when trying to use a real web server for automated integration tests, such as firewall issues or process start/stop issues, are eliminated with this approach. Since the requests are all made in memory with no network requirement, the tests also tend to run much faster than tests that must set up a separate webserver and communicate with it over the network (even if it's running on the same machine). + +Below you can see an example ASP.NET Core integration test (sometimes referred to as *functional tests* to distinguish them from lower-level integration tests) from the [eShopOnWeb reference application](https://github.com/dotnet-architecture/eShopOnWeb): + +```csharp +public class GetByIdEndpoint : IClassFixture +{ + JsonSerializerOptions _jsonOptions = new JsonSerializerOptions { PropertyNameCaseInsensitive = true }; + + public GetByIdEndpoint(ApiTestFixture factory) + { + Client = factory.CreateClient(); + } + + public HttpClient Client { get; } + + [Fact] + public async Task ReturnsItemGivenValidId() + { + var response = await Client.GetAsync("api/catalog-items/5"); + response.EnsureSuccessStatusCode(); + var stringResponse = await response.Content.ReadAsStringAsync(); + var model = stringResponse.FromJson(); + + Assert.Equal(5, model.CatalogItem.Id); + Assert.Equal("Roslyn Red Sheet", model.CatalogItem.Name); + } +} +``` + +If the app being migrated has no integration tests, the migration process can be a great opportunity to add some. These tests can verify that the migrated app behaves as the team expects. When such tests are in place early in a migration, they can ensure that later migration efforts do not break previously migrated portions of the app. Given how easy it is to set up and run integration tests in ASP.NET Core, the return on the investment spent setting up such tests is usually pretty high. + +## WCF client configuration + +If your app currently relies on WCF services as a client, this scenario is supported. However, you will need to [migrate your configuration](/aspnet/core/migration/configuration) from *web.config* to use the new *appsettings.json* file. Another option is to add any necessary configuration to your clients programmatically when you create them. For example: + +```csharp +var wcfClient = new OrderServiceClient( + new BasicHttpBinding(BasicHttpSecurityMode.None), + new EndpointAddress("http://localhost:5050/OrderService.svc")); +``` + +If your organization has extensive services built using WCF that your app relies on, consider migrating them to use gRPC instead. For more details on gRPC, why you may wish to migrate, and a detailed migration guide, consult the [gRPC for WCF Developers](../grpc-for-wcf-developers/index.md) eBook. + ## References - [ASP.NET Web API Content Negotiation](/aspnet/web-api/overview/formats-and-model-binding/content-negotiation) - [Format response data in ASP.NET Core Web API](/aspnet/core/web-api/advanced/formatting) +- [Custom Model Binders in ASP.NET Web API](/aspnet/web-api/overview/formats-and-model-binding/parameter-binding-in-aspnet-web-api#model-binders) +- [Custom Model Binders in ASP.NET Core](/aspnet/core/mvc/advanced/custom-model-binding#custom-model-binder-sample) +- [Media Formatters in ASP.NET Web API 2](/aspnet/web-api/overview/formats-and-model-binding/media-formatters)\ +- [Custom formatters in ASP.NET Core Web API](/aspnet/core/web-api/advanced/custom-formatters) +- [Filters in ASP.NET Core](/aspnet/core/mvc/controllers/filters) +- [Route constraints in ASP.NET Web API 2](/aspnet/web-api/overview/web-api-routing-and-actions/attribute-routing-in-web-api-2#route-constraints) +- [Route constraints in ASP.NET MVC 5](https://devblogs.microsoft.com/aspnet/attribute-routing-in-asp-net-mvc-5/#route-constraints) +- [ASP.NET Core Route Constraint Reference](/aspnet/core/fundamentals/routing#route-constraint-reference) +- [Custom message handlers in ASP.NET Web API 2](/aspnet/web-api/overview/advanced/http-message-handlers#custom-message-handlers) +- [Simple CORS control in MVC 5 and Web API 2](https://stackoverflow.com/questions/6290053/setting-access-control-allow-origin-in-asp-net-mvc-simplest-possible-method) +- [Enabling Cross-Origin Requests in Web API](/aspnet/web-api/overview/security/enabling-cross-origin-requests-in-web-api#enable-cors) +- [Enable Cross-Origin Requests (CORS) in ASP.NET Core](/aspnet/core/security/cors) +- [Areas in ASP.NET Core](/aspnet/core/mvc/controllers/areas) +- [Integration tests in ASP.NET Core](/aspnet/core/test/integration-tests) >[!div class="step-by-step"] >[Previous](example-migration-eshop.md) diff --git a/docs/architecture/porting-existing-aspnet-apps/signalr-differences.md b/docs/architecture/porting-existing-aspnet-apps/signalr-differences.md index 2227795199c04..ebef833df63a4 100644 --- a/docs/architecture/porting-existing-aspnet-apps/signalr-differences.md +++ b/docs/architecture/porting-existing-aspnet-apps/signalr-differences.md @@ -18,7 +18,7 @@ ASP.NET Core SignalR is incompatible with clients or servers using ASP.NET Signa - ASP.NET Core SignalR requires sticky sessions; ASP.NET SignalR doesn't. - ASP.NET Core simplifies the connection model; connections are only made to a single hub. - ASP.NET Core SignalR supports streaming data from the hub to the client. -- ASP.NET Core SignalR doesn't support passing state between clients and the hub. +- ASP.NET Core SignalR doesn't support passing state between clients and the hub (but method calls still allow passing information between hubs and clients). - The `PersistentConnection` class doesn't exist in ASP.NET Core SignalR. - ASP.NET SignalR supports SQL Server and Redis. ASP.NET Core SignalR supports [Azure SignalR](/azure/azure-signalr/) and Redis. diff --git a/docs/architecture/porting-existing-aspnet-apps/strategies-migrating-in-production.md b/docs/architecture/porting-existing-aspnet-apps/strategies-migrating-in-production.md index d01638e3a0297..97cfaf3f3ac2b 100644 --- a/docs/architecture/porting-existing-aspnet-apps/strategies-migrating-in-production.md +++ b/docs/architecture/porting-existing-aspnet-apps/strategies-migrating-in-production.md @@ -11,7 +11,7 @@ Many teams have .NET Framework apps they plan to migrate to .NET Core, but the a ## Refactor the .NET Framework solution -A good place to start if you plan to port a .NET Framework app to .NET Core is to refactor it to work better with .NET Core. This means updating individual class libraries to target .NET Standard and moving as much logic out of your ASP.NET MVC projects and into these class libraries. Any code you have in .NET Standard libraries should move relatively easily from .NET Framework to .NET Core. +A good place to start if you plan to port a .NET Framework app to .NET Core is to refactor it to work better with .NET Core. This means updating individual class libraries to target .NET Standard and moving as much logic out of your ASP.NET MVC projects and into these class libraries. Any code you have in .NET Standard libraries is immediately usable from both .NET Framework to .NET Core apps, which is why this step is so valuable as part of a migration. When refactoring, make sure you're following good refactoring fundamentals. For example, create tests that verify what the system does before you start refactoring. Run these tests when you're done to confirm you didn't change the system's behavior. You may need to add characterization tests to the system if you don't already have a good suite of automated tests you can rely on. @@ -35,18 +35,18 @@ Large ASP.NET MVC apps can be gradually replaced with a new ASP.NET Core app by Once the facade is in place, you can route part of it to a new ASP.NET Core app. As you port more of the original .NET Framework app to .NET Core, you continue to update the facade layer accordingly, sending more of the facade's total functionality to the new system. Figure 3-5 shows the strangler pattern progression over time. -## Multi-targeting approaches - -Large apps that target .NET Framework may be migrated to ASP.NET Core over time by using multi-targeting and separate code paths for each framework. For example, code that must run in both environments could be modified with [preprocessor `#if`](../../csharp/language-reference/preprocessor-directives/preprocessor-if.md) directives to implement different functionality or use different dependencies when run in .NET Framework versus .NET Core. Another option is to modify project files to include different sets of files based on which framework is being targeted. Project files can use different globbing patterns, such as `*.core.cs`, to include different sets of source files depending on the framework being targeted. - -These techniques allow a single common codebase to be maintained while new functionality is added and (parts of) the app are ported to use .NET Core. - ![Figure 3-5](media/Figure3-5.png) **Figure 3-5.** The Strangler pattern over time. Eventually, the entire facade layer corresponds to the new, modern implementation. At this point, both the legacy system and the face layer can be retired. +## Multi-targeting approaches + +Large apps that target .NET Framework may be migrated to ASP.NET Core over time by using multi-targeting and separate code paths for each framework. For example, code that must run in both environments could be modified with [preprocessor `#if`](../../csharp/language-reference/preprocessor-directives.md#conditional-compilation) directives to implement different functionality or use different dependencies when run in .NET Framework versus .NET Core. Another option is to modify project files to include different sets of files based on which framework is being targeted. Project files can use different globbing patterns, such as `*.core.cs`, to include different sets of source files depending on the framework being targeted. Typically you only follow this approach for libraries that will be consumed by multiple web apps. For the web apps themselves, it's generally better to have two separate projects. + +These techniques allow a single common codebase to be maintained while new functionality is added and (parts of) the app are ported to use .NET Core. + ## Summary Frequently, large ASP.NET MVC and Web API apps won't be ported to ASP.NET Core all at once, but will migrate incrementally over time. This section offers several strategies for performing this incremental migration. Choose the one(s) that will work best for your organization and app. diff --git a/docs/architecture/porting-existing-aspnet-apps/understand-update-dependencies.md b/docs/architecture/porting-existing-aspnet-apps/understand-update-dependencies.md index 02b9622191161..9e6b299c4dd14 100644 --- a/docs/architecture/porting-existing-aspnet-apps/understand-update-dependencies.md +++ b/docs/architecture/porting-existing-aspnet-apps/understand-update-dependencies.md @@ -41,7 +41,7 @@ Analyze your use of third-party NuGet packages and determine if any of them don' If support exists using the version of the package the app currently uses, great! If not, see if a more recent version of the package has the support and research what would be involved in upgrading. There may be breaking changes in the package, especially if the major version of the package changes between your currently used version and the one to which you're upgrading. -In some cases, no version of a given package works with .NET Core. In that case, teams have a couple options. They can continue depending on the .NET Framework version, but this has limitations. The app will only run on Windows, and the team may want to run Portability Analyzer on the package's binaries to see if there are any issues likely to be encountered. Certainly the team will want to test thoroughly. The other option is to find a different package or, if the required package is open source, upgrade it to .NET Standard or .NET Core themselves. +In some cases, no version of a given package works with .NET Core. In that case, teams have a couple options. They can continue depending on the .NET Framework version, but this has limitations. The app may only run on Windows, and the team may want to run Portability Analyzer on the package's binaries to see if there are any issues likely to be encountered. Certainly the team will want to test thoroughly, since if .NET Framework packages are used that reference APIs not available in .NET Core, a runtime exception will occur. The other option is to find a different package or, if the required package is open source, upgrade it to .NET Standard or .NET Core themselves. ## Migrate ASP.NET MVC projects diff --git a/docs/architecture/toc.yml b/docs/architecture/toc.yml index c61454141752e..42e1787e66f78 100644 --- a/docs/architecture/toc.yml +++ b/docs/architecture/toc.yml @@ -13,6 +13,8 @@ href: blazor-for-web-forms-developers/ - name: Containerized Docker application lifecycle with Microsoft platform and tools href: containerized-lifecycle/ + - name: DevOps for ASP.NET Core Developers + href: devops-for-aspnet-developers/ - name: Modernize existing .NET applications with Azure cloud and Windows Containers href: modernize-with-azure-containers/ - name: "Modernizing desktop apps on Windows 10 with .NET 5" diff --git a/docs/azure/TOC.yml b/docs/azure/TOC.yml index 6060aa3ac29c4..d55c92fbaef03 100644 --- a/docs/azure/TOC.yml +++ b/docs/azure/TOC.yml @@ -8,7 +8,7 @@ - name: Key Azure services for .NET developers href: key-azure-services.md - name: Configure your development environment - items: + items: - name: Create an Azure account href: create-azure-account.md - name: Configure Visual Studio for Azure development (Windows) @@ -20,7 +20,7 @@ - name: Install additional tools href: azure-tools.md - name: Development setup checklist - href: dotnet-dev-env-checklist.md + href: dotnet-dev-env-checklist.md - name: Migrate to Azure items: - name: Choose the right Azure hosting option @@ -36,13 +36,17 @@ - name: What is the Azure SDK for .NET? href: ./sdk/azure-sdk-for-dotnet.md - name: Authentication - href: authentication.md + href: ./sdk/authentication.md + - name: Dependency injection + href: ./sdk/dependency-injection.md + - name: Thread safety + href: ./sdk/thread-safety.md - name: Logging - href: logging.md + href: ./sdk/logging.md - name: Configuring a proxy server href: ./sdk/azure-sdk-configure-proxy.md - name: Package List - href: packages.md + href: ./sdk/packages.md - name: SDK example href: /samples/dotnet/samples/azure-identity-resource-management-storage/ - name: Sample code diff --git a/docs/azure/azure-tools.md b/docs/azure/azure-tools.md index f4514402e8613..a0d57aa9ea407 100644 --- a/docs/azure/azure-tools.md +++ b/docs/azure/azure-tools.md @@ -6,6 +6,7 @@ ms.topic: conceptual ms.custom: devx-track-dotnet ms.author: daberry author: daberry +recommendations: false --- # Additional Tools for Azure Developers diff --git a/docs/azure/configure-visual-studio.md b/docs/azure/configure-visual-studio.md index bbca6cbad2904..8b2780c6fa554 100644 --- a/docs/azure/configure-visual-studio.md +++ b/docs/azure/configure-visual-studio.md @@ -6,6 +6,7 @@ ms.topic: conceptual ms.custom: devx-track-dotnet ms.author: daberry author: daberry +recommendations: false --- # Configure Visual Studio for Azure development with .NET diff --git a/docs/azure/configure-vs-code.md b/docs/azure/configure-vs-code.md index 8046867d76a72..4ef08b781c851 100644 --- a/docs/azure/configure-vs-code.md +++ b/docs/azure/configure-vs-code.md @@ -6,6 +6,7 @@ ms.topic: conceptual ms.custom: devx-track-dotnet ms.author: daberry author: daberry +recommendations: false --- # Configure Visual Studio Code for Azure development diff --git a/docs/azure/create-azure-account.md b/docs/azure/create-azure-account.md index fbf00d6d09211..b87b6ce1ca2b0 100644 --- a/docs/azure/create-azure-account.md +++ b/docs/azure/create-azure-account.md @@ -6,6 +6,7 @@ ms.topic: conceptual ms.custom: devx-track-dotnet ms.author: daberry author: daberry +recommendations: false --- # Create an Azure account diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index 947ff061915d8..0e3d44b2fed96 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -1,86 +1,134 @@ | Name | Package | Docs | Source | | ---- | ------- | ---- | ------ | -| Anomaly Detector | NuGet [3.0.0-preview.2](https://www.nuget.org/packages/Azure.AI.AnomalyDetector/3.0.0-preview.2) | [docs](/dotnet/api/overview/azure/AI.AnomalyDetector-readme-pre/) | GitHub [3.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AnomalyDetector_3.0.0-preview.2/sdk/anomalydetector/Azure.AI.AnomalyDetector/) | -| App Configuration | NuGet [1.0.2](https://www.nuget.org/packages/Azure.Data.AppConfiguration/1.0.2) | [docs](/dotnet/api/overview/azure/Data.AppConfiguration-readme/) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.AppConfiguration_1.0.2/sdk/appconfiguration/Azure.Data.AppConfiguration/) | -| ASP.NET Extension - Configuration Secrets | NuGet [1.0.2](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.Configuration.Secrets/1.0.2) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.Configuration.Secrets-readme/) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.Configuration.Secrets_1.0.2/sdk/extensions/Azure.Extensions.AspNetCore.Configuration.Secrets/) | -| ASP.NET Extension - DataProtection Blobs | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Blobs/1.2.0) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Blobs-readme/) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Blobs_1.2.0/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Blobs/) | -| ASP.NET Extension - DataProtection Keys | NuGet [1.0.2](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Keys/1.0.2) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Keys-readme/) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Keys_1.0.2/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Keys/) | -| Azure Mixed Reality Authentication | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.MixedReality.Authentication/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.Authentication_1.0.0-beta.1/sdk/mixedreality/Azure.MixedReality.Authentication/) | -| Azure Remote Rendering | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.MixedReality.RemoteRendering/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.RemoteRendering_1.0.0-beta.1/sdk/mixedreality/Azure.MixedReality.RemoteRendering/) | -| Azure Security Attestation | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Security.Attestation/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Security.Attestation-readme-pre/) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.Attestation_1.0.0-beta.1/sdk/attestation/Azure.Security.Attestation/) | -| Cognitive Search | NuGet [11.2.0](https://www.nuget.org/packages/Azure.Search.Documents/11.2.0) | [docs](/dotnet/api/overview/azure/Search.Documents-readme/) | GitHub [11.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Search.Documents_11.2.0/sdk/search/Azure.Search.Documents/) | -| Communication Administration | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.Administration/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Communication.Administration-readme-pre/) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Administration_1.0.0-beta.3/sdk/communication/Azure.Communication.Administration/) | -| Communication Chat | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Communication.Chat/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme-pre/) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.0.0-beta.4/sdk/communication/Azure.Communication.Chat/) | -| Communication Common | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Communication.Common/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Communication.Common-readme-pre/) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_1.0.0-beta.4/sdk/communication/Azure.Communication.Common/) | -| Communication Identity | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Communication.Identity/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Communication.Identity-readme-pre/) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Identity_1.0.0-beta.4/sdk/communication/Azure.Communication.Identity/) | -| Communication SMS | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.Sms/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Communication.Sms-readme-pre/) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Sms_1.0.0-beta.3/sdk/communication/Azure.Communication.Sms/) | -| Core | NuGet [1.9.0](https://www.nuget.org/packages/Azure.Core/1.9.0) | [docs](/dotnet/api/overview/azure/Core-readme/) | GitHub [1.9.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core_1.9.0/sdk/core/Azure.Core/) | -| Core - AMQP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Core.Amqp/1.0.0) | [docs](/dotnet/api/overview/azure/Core.Amqp-readme/) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Amqp_1.0.0/sdk/core/Azure.Core.Amqp/) | +| Anomaly Detector | NuGet [3.0.0-preview.3](https://www.nuget.org/packages/Azure.AI.AnomalyDetector/3.0.0-preview.3) | [docs](/dotnet/api/overview/azure/AI.AnomalyDetector-readme-pre) | GitHub [3.0.0-preview.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AnomalyDetector_3.0.0-preview.3/sdk/anomalydetector/Azure.AI.AnomalyDetector/) | +| App Configuration | NuGet [1.0.3](https://www.nuget.org/packages/Azure.Data.AppConfiguration/1.0.3)
NuGet [1.1.0-beta.2](https://www.nuget.org/packages/Azure.Data.AppConfiguration/1.1.0-beta.2) | [docs](/dotnet/api/overview/azure/Data.AppConfiguration-readme) | GitHub [1.0.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.AppConfiguration_1.0.3/sdk/appconfiguration/Azure.Data.AppConfiguration/)
GitHub [1.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.AppConfiguration_1.1.0-beta.2/sdk/appconfiguration/Azure.Data.AppConfiguration/) | +| ASP.NET Extension - Configuration Secrets | NuGet [1.2.1](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.Configuration.Secrets/1.2.1) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.Configuration.Secrets-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.Configuration.Secrets_1.2.1/sdk/extensions/Azure.Extensions.AspNetCore.Configuration.Secrets/) | +| ASP.NET Extension - DataProtection Blobs | NuGet [1.2.1](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Blobs/1.2.1) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Blobs-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Blobs_1.2.1/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Blobs/) | +| ASP.NET Extension - DataProtection Keys | NuGet [1.0.3](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Keys/1.0.3) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Keys-readme) | GitHub [1.0.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Keys_1.0.3/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Keys/) | +| Attestation | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Security.Attestation/1.0.0) | [docs](/dotnet/api/overview/azure/Security.Attestation-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.Attestation_1.0.0/sdk/attestation/Azure.Security.Attestation/) | +| Azure Mixed Reality Authentication | NuGet [1.0.1](https://www.nuget.org/packages/Azure.MixedReality.Authentication/1.0.1) | [docs](/dotnet/api/overview/azure/MixedReality.Authentication-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.Authentication_1.0.1/sdk/mixedreality/Azure.MixedReality.Authentication/) | +| Azure Object Anchors Conversion | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.MixedReality.ObjectAnchors.Conversion/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/MixedReality.ObjectAnchors.Conversion-readme-pre) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.ObjectAnchors.Conversion_0.2.0-beta.1/sdk/objectanchors/Azure.MixedReality.ObjectAnchors.Conversion/) | +| Azure Remote Rendering | NuGet [1.0.1](https://www.nuget.org/packages/Azure.MixedReality.RemoteRendering/1.0.1) | [docs](/dotnet/api/overview/azure/MixedReality.RemoteRendering-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.RemoteRendering_1.0.1/sdk/remoterendering/Azure.MixedReality.RemoteRendering/) | +| Azure Video Analyzer Edge | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Media.VideoAnalyzer.Edge/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Media.VideoAnalyzer.Edge-readme-pre) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Media.VideoAnalyzer.Edge_1.0.0-beta.4/sdk/videoanalyzer/Azure.Media.VideoAnalyzer.Edge/) | +| Cognitive Search | NuGet [11.2.1](https://www.nuget.org/packages/Azure.Search.Documents/11.2.1)
NuGet [11.3.0-beta.2](https://www.nuget.org/packages/Azure.Search.Documents/11.3.0-beta.2) | [docs](/dotnet/api/overview/azure/Search.Documents-readme) | GitHub [11.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Search.Documents_11.2.1/sdk/search/Azure.Search.Documents/)
GitHub [11.3.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Search.Documents_11.3.0-beta.2/sdk/search/Azure.Search.Documents/) | +| Communication Chat | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Chat/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.0.1/sdk/communication/Azure.Communication.Chat/) | +| Communication Common | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Common/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Common-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_1.0.1/sdk/communication/Azure.Communication.Common/) | +| Communication Identity | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Identity/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Identity-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Identity_1.0.1/sdk/communication/Azure.Communication.Identity/) | +| Communication Phone Numbers | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.PhoneNumbers/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.PhoneNumbers-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.PhoneNumbers_1.0.1/sdk/communication/Azure.Communication.PhoneNumbers/) | +| Communication SMS | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Sms/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Sms-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Sms_1.0.1/sdk/communication/Azure.Communication.Sms/) | +| ConfidentialLedger | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Storage.ConfidentialLedger/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.ConfidentialLedger-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.ConfidentialLedger_1.0.0-beta.1/sdk/confidentialledger/Azure.Storage.ConfidentialLedger/) | +| Container Registry | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Containers.ContainerRegistry/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Containers.ContainerRegistry-readme-pre) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Containers.ContainerRegistry_1.0.0-beta.2/sdk/containerregistry/Azure.Containers.ContainerRegistry/) | +| Core | NuGet [1.14.0](https://www.nuget.org/packages/Azure.Core/1.14.0) | [docs](/dotnet/api/overview/azure/Core-readme) | GitHub [1.14.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core_1.14.0/sdk/core/Azure.Core/) | +| Core - AMQP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Core.Amqp/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Core.Amqp/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Core.Amqp-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Amqp_1.0.0/sdk/core/Azure.Core.Amqp/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Amqp_1.1.0-beta.1/sdk/core/Azure.Core.Amqp/) | | Cosmos DB | NuGet [4.0.0-preview3](https://www.nuget.org/packages/Azure.Cosmos/4.0.0-preview3) | [docs](/dotnet/api/azure.cosmos) | GitHub [4.0.0-preview3](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/releases/4.0.0-preview3) | -| Digital Twins - Core | NuGet [1.2.1](https://www.nuget.org/packages/Azure.DigitalTwins.Core/1.2.1) | [docs](/dotnet/api/overview/azure/DigitalTwins.Core-readme/) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.DigitalTwins.Core_1.2.1/sdk/digitaltwins/Azure.DigitalTwins.Core/) | -| Event Grid | NuGet [4.0.0-beta.5](https://www.nuget.org/packages/Azure.Messaging.EventGrid/4.0.0-beta.5) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid-readme-pre/) | GitHub [4.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid_4.0.0-beta.5/sdk/eventgrid/Azure.Messaging.EventGrid/) | -| Event Hubs | NuGet [5.3.0](https://www.nuget.org/packages/Azure.Messaging.EventHubs/5.3.0) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs-readme/) | GitHub [5.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs_5.3.0/sdk/eventhub/Azure.Messaging.EventHubs/) | -| Event Hubs - Event Processor | NuGet [5.3.0](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/5.3.0) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs.Processor-readme/) | GitHub [5.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs.Processor_5.3.0/sdk/eventhub/Azure.Messaging.EventHubs.Processor/) | -| Event Hubs - Schema Registry | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Data.SchemaRegistry/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Data.SchemaRegistry-readme-pre/) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.SchemaRegistry_1.0.0-beta.2/sdk/schemaregistry/Azure.Data.SchemaRegistry/) | -| Form Recognizer | NuGet [3.0.0](https://www.nuget.org/packages/Azure.AI.FormRecognizer/3.0.0)
NuGet [3.1.0-beta.2](https://www.nuget.org/packages/Azure.AI.FormRecognizer/3.1.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.FormRecognizer-readme/) | GitHub [3.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.FormRecognizer_3.0.0/sdk/formrecognizer/Azure.AI.FormRecognizer/)
GitHub [3.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.FormRecognizer_3.1.0-beta.2/sdk/formrecognizer/Azure.AI.FormRecognizer/) | -| Identity | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Identity/1.3.0)
NuGet [1.4.0-beta.3](https://www.nuget.org/packages/Azure.Identity/1.4.0-beta.3) | [docs](/dotnet/api/overview/azure/Identity-readme/) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.3.0/sdk/identity/Azure.Identity/)
GitHub [1.4.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.4.0-beta.3/sdk/identity/Azure.Identity/) | -| Key Vault - Administration | NuGet [4.0.0-beta.4](https://www.nuget.org/packages/Azure.Security.KeyVault.Administration/4.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Administration-readme-pre/) | GitHub [4.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Administration_4.0.0-beta.4/sdk/keyvault/Azure.Security.KeyVault.Administration/) | -| Key Vault - Certificates | NuGet [4.1.0](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates/4.1.0)
NuGet [4.2.0-beta.4](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates/4.2.0-beta.4) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Certificates-readme/) | GitHub [4.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Certificates_4.1.0/sdk/keyvault/Azure.Security.KeyVault.Certificates/)
GitHub [4.2.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Certificates_4.2.0-beta.4/sdk/keyvault/Azure.Security.KeyVault.Certificates/) | -| Key Vault - Keys | NuGet [4.1.0](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys/4.1.0)
NuGet [4.2.0-beta.4](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys/4.2.0-beta.4) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Keys-readme/) | GitHub [4.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Keys_4.1.0/sdk/keyvault/Azure.Security.KeyVault.Keys/)
GitHub [4.2.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Keys_4.2.0-beta.4/sdk/keyvault/Azure.Security.KeyVault.Keys/) | -| Key Vault - Secrets | NuGet [4.1.0](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets/4.1.0)
NuGet [4.2.0-beta.4](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets/4.2.0-beta.4) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Secrets-readme/) | GitHub [4.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Secrets_4.1.0/sdk/keyvault/Azure.Security.KeyVault.Secrets/)
GitHub [4.2.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Secrets_4.2.0-beta.4/sdk/keyvault/Azure.Security.KeyVault.Secrets/) | -| Media Analytics Edge | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Media.Analytics.Edge/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Media.Analytics.Edge-readme-pre/) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Media.Analytics.Edge_1.0.0-beta.1/sdk/mediaservices/Azure.Media.Analytics.Edge/) | -| Metrics Advisor | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.AI.MetricsAdvisor/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/AI.MetricsAdvisor-readme-pre/) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.MetricsAdvisor_1.0.0-beta.3/sdk/metricsadvisor/Azure.AI.MetricsAdvisor/) | -| Service Bus | NuGet [7.1.0](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/7.1.0) | [docs](/dotnet/api/overview/azure/Messaging.ServiceBus-readme/) | GitHub [7.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.ServiceBus_7.1.0/sdk/servicebus/Azure.Messaging.ServiceBus/) | -| Storage - Blobs | NuGet [12.8.0](https://www.nuget.org/packages/Azure.Storage.Blobs/12.8.0)
NuGet [12.9.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs/12.9.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme/) | GitHub [12.8.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.8.0/sdk/storage/Azure.Storage.Blobs/)
GitHub [12.9.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.9.0-beta.1/sdk/storage/Azure.Storage.Blobs/) | -| Storage - Blobs Batch | NuGet [12.5.0](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.5.0)
NuGet [12.6.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.6.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme/) | GitHub [12.5.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.5.0/sdk/storage/Azure.Storage.Blobs.Batch/)
GitHub [12.6.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.6.0-beta.1/sdk/storage/Azure.Storage.Blobs.Batch/) | -| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.9](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.9) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme-pre/) | GitHub [12.0.0-preview.9](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.9/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | -| Storage - Common | NuGet [12.7.0](https://www.nuget.org/packages/Azure.Storage.Common/12.7.0)
NuGet [12.8.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Common/12.8.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Common-readme/) | GitHub [12.7.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.7.0/sdk/storage/Azure.Storage.Common/)
GitHub [12.8.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.8.0-beta.1/sdk/storage/Azure.Storage.Common/) | -| Storage - Files Data Lake | NuGet [12.6.0](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.6.0)
NuGet [12.7.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.7.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme/) | GitHub [12.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.6.0/sdk/storage/Azure.Storage.Files.DataLake/)
GitHub [12.7.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.7.0-beta.1/sdk/storage/Azure.Storage.Files.DataLake/) | -| Storage - Files Shares | NuGet [12.6.0](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.6.0)
NuGet [12.7.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.7.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme/) | GitHub [12.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.6.0/sdk/storage/Azure.Storage.Files.Shares/)
GitHub [12.7.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.7.0-beta.1/sdk/storage/Azure.Storage.Files.Shares/) | -| Storage - Queues | NuGet [12.6.0](https://www.nuget.org/packages/Azure.Storage.Queues/12.6.0)
NuGet [12.7.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Queues/12.7.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme/) | GitHub [12.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.6.0/sdk/storage/Azure.Storage.Queues/)
GitHub [12.7.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.7.0-beta.1/sdk/storage/Azure.Storage.Queues/) | -| Synapse - AccessControl | NuGet [1.0.0-preview.3](https://www.nuget.org/packages/Azure.Analytics.Synapse.AccessControl/1.0.0-preview.3) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.AccessControl-readme-pre/) | GitHub [1.0.0-preview.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.AccessControl_1.0.0-preview.3/sdk/synapse/Azure.Analytics.Synapse.AccessControl/) | -| Synapse - Artifacts | NuGet [1.0.0-preview.6](https://www.nuget.org/packages/Azure.Analytics.Synapse.Artifacts/1.0.0-preview.6) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Artifacts-readme-pre/) | GitHub [1.0.0-preview.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Artifacts_1.0.0-preview.6/sdk/synapse/Azure.Analytics.Synapse.Artifacts/) | -| Synapse - Managed Private Endpoints | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Analytics.Synapse.ManagedPrivateEndpoints/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.ManagedPrivateEndpoints-readme-pre/) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.ManagedPrivateEndpoints_1.0.0-beta.2/sdk/synapse/Azure.Analytics.Synapse.ManagedPrivateEndpoints/) | -| Synapse - Monitoring | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Analytics.Synapse.Monitoring/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Monitoring-readme-pre/) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Monitoring_1.0.0-beta.2/sdk/synapse/Azure.Analytics.Synapse.Monitoring/) | -| Synapse - Spark | NuGet [1.0.0-preview.4](https://www.nuget.org/packages/Azure.Analytics.Synapse.Spark/1.0.0-preview.4) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Spark-readme-pre/) | GitHub [1.0.0-preview.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Spark_1.0.0-preview.4/sdk/synapse/Azure.Analytics.Synapse.Spark/) | -| System Memory Data | NuGet [1.0.1](https://www.nuget.org/packages/System.Memory.Data/1.0.1) | [docs](/dotnet/api/overview/azure/System.Memory.Data-readme/) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/System.Memory.Data_1.0.1/sdk/core/System.Memory.Data/) | -| Tables | NuGet [3.0.0-beta.5](https://www.nuget.org/packages/Azure.Data.Tables/3.0.0-beta.5) | [docs](/dotnet/api/overview/azure/Data.Tables-readme-pre/) | GitHub [3.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.Tables_3.0.0-beta.5/sdk/tables/Azure.Data.Tables/) | -| Text Analytics | NuGet [5.0.0](https://www.nuget.org/packages/Azure.AI.TextAnalytics/5.0.0)
NuGet [5.1.0-beta.4](https://www.nuget.org/packages/Azure.AI.TextAnalytics/5.1.0-beta.4) | [docs](/dotnet/api/overview/azure/AI.TextAnalytics-readme/) | GitHub [5.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.TextAnalytics_5.0.0/sdk/textanalytics/Azure.AI.TextAnalytics/)
GitHub [5.1.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.TextAnalytics_5.1.0-beta.4/sdk/textanalytics/Azure.AI.TextAnalytics/) | -| Resource Management - App Configuration | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.AppConfiguration/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.AppConfiguration-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppConfiguration_1.0.0-preview.1/sdk/appconfiguration/Azure.ResourceManager.AppConfiguration/) | -| Resource Management - Communication | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.ResourceManager.Communication/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/ResourceManager.Communication-readme-pre/) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Communication_1.0.0-beta.3/sdk/communication/Azure.ResourceManager.Communication/) | -| Resource Management - Compute | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Compute/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Compute-readme-pre/) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute_1.0.0-preview.2/sdk/compute/Azure.ResourceManager.Compute/) | -| Resource Management - Cosmos DB | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.CosmosDB/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.CosmosDB-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.CosmosDB_1.0.0-preview.1/sdk/cosmosdb/Azure.ResourceManager.CosmosDB/) | -| Resource Management - DNS | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.Dns/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Dns-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Dns_1.0.0-preview.1/sdk/dns/Azure.ResourceManager.Dns/) | -| Resource Management - Event Hubs | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.EventHubs/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.EventHubs-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.EventHubs_1.0.0-preview.1/sdk/eventhub/Azure.ResourceManager.EventHubs/) | -| Resource Management - Insights | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.Insights/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Insights-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Insights_1.0.0-preview.1/sdk/insights/Azure.ResourceManager.Insights/) | -| Resource Management - KeyVault | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.KeyVault/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.KeyVault-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.KeyVault_1.0.0-preview.1/sdk/keyvault/Azure.ResourceManager.KeyVault/) | -| Resource Management - Network | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Network/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Network-readme-pre/) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Network_1.0.0-preview.2/sdk/network/Azure.ResourceManager.Network/) | -| Resource Management - Resources | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Resources/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Resources-readme-pre/) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Resources_1.0.0-preview.2/sdk/resources/Azure.ResourceManager.Resources/) | -| Resource Management - Storage | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Storage/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Storage-readme-pre/) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Storage_1.0.0-preview.2/sdk/storage/Azure.ResourceManager.Storage/) | -| Azure.Quantum.Jobs | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Quantum.Jobs/1.0.0-beta.1) | | | +| Digital Twins - Core | NuGet [1.2.2](https://www.nuget.org/packages/Azure.DigitalTwins.Core/1.2.2) | [docs](/dotnet/api/overview/azure/DigitalTwins.Core-readme) | GitHub [1.2.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.DigitalTwins.Core_1.2.2/sdk/digitaltwins/Azure.DigitalTwins.Core/) | +| Document Translation | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.AI.Translation.Document/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/AI.Translation.Document-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Translation.Document_1.0.0-beta.1/sdk/translation/Azure.AI.Translation.Document/) | +| Event Grid | NuGet [4.2.0](https://www.nuget.org/packages/Azure.Messaging.EventGrid/4.2.0) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid-readme) | GitHub [4.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid_4.2.0/sdk/eventgrid/Azure.Messaging.EventGrid/) | +| Event Hubs | NuGet [5.4.1](https://www.nuget.org/packages/Azure.Messaging.EventHubs/5.4.1) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs-readme) | GitHub [5.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs_5.4.1/sdk/eventhub/Azure.Messaging.EventHubs/) | +| Event Hubs - Event Processor | NuGet [5.4.1](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/5.4.1) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs.Processor-readme) | GitHub [5.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs.Processor_5.4.1/sdk/eventhub/Azure.Messaging.EventHubs.Processor/) | +| Event Hubs - Schema Registry | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Data.SchemaRegistry/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Data.SchemaRegistry-readme-pre) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.SchemaRegistry_1.0.0-beta.2/sdk/schemaregistry/Azure.Data.SchemaRegistry/) | +| FarmBeats | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Verticals.AgriFood.Farming/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Verticals.AgriFood.Farming-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Verticals.AgriFood.Farming_1.0.0-beta.1/sdk/farmbeats/Azure.Verticals.AgriFood.Farming/) | +| Form Recognizer | NuGet [3.1.0](https://www.nuget.org/packages/Azure.AI.FormRecognizer/3.1.0) | [docs](/dotnet/api/overview/azure/AI.FormRecognizer-readme) | GitHub [3.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.FormRecognizer_3.1.0/sdk/formrecognizer/Azure.AI.FormRecognizer/) | +| Identity | NuGet [1.4.0](https://www.nuget.org/packages/Azure.Identity/1.4.0) | [docs](/dotnet/api/overview/azure/Identity-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.4.0/sdk/identity/Azure.Identity/) | +| IoT Device Update | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.IoT.DeviceUpdate/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/IoT.DeviceUpdate-readme-pre) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.IoT.DeviceUpdate_1.0.0-beta.2/sdk/deviceupdate/Azure.Iot.DeviceUpdate/) | +| Key Vault - Administration | NuGet [4.0.0-beta.5](https://www.nuget.org/packages/Azure.Security.KeyVault.Administration/4.0.0-beta.5) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Administration-readme-pre) | GitHub [4.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Administration_4.0.0-beta.5/sdk/keyvault/Azure.Security.KeyVault.Administration/) | +| Key Vault - Certificates | NuGet [4.1.1](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates/4.1.1)
NuGet [4.2.0-beta.6](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates/4.2.0-beta.6) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Certificates-readme) | GitHub [4.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Certificates_4.1.1/sdk/keyvault/Azure.Security.KeyVault.Certificates/)
GitHub [4.2.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Certificates_4.2.0-beta.6/sdk/keyvault/Azure.Security.KeyVault.Certificates/) | +| Key Vault - Keys | NuGet [4.1.1](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys/4.1.1)
NuGet [4.2.0-beta.6](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys/4.2.0-beta.6) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Keys-readme) | GitHub [4.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Keys_4.1.1/sdk/keyvault/Azure.Security.KeyVault.Keys/)
GitHub [4.2.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Keys_4.2.0-beta.6/sdk/keyvault/Azure.Security.KeyVault.Keys/) | +| Key Vault - Secrets | NuGet [4.1.1](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets/4.1.1)
NuGet [4.2.0-beta.5](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets/4.2.0-beta.5) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Secrets-readme) | GitHub [4.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Secrets_4.1.1/sdk/keyvault/Azure.Security.KeyVault.Secrets/)
GitHub [4.2.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Secrets_4.2.0-beta.5/sdk/keyvault/Azure.Security.KeyVault.Secrets/) | +| Media Analytics Edge | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Media.Analytics.Edge/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Media.Analytics.Edge-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Media.Analytics.Edge_1.0.0-beta.1/sdk/mediaservices/Azure.Media.Analytics.Edge) | +| Metrics Advisor | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.AI.MetricsAdvisor/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/AI.MetricsAdvisor-readme-pre) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.MetricsAdvisor_1.0.0-beta.3/sdk/metricsadvisor/Azure.AI.MetricsAdvisor/) | +| Monitor OpenTelemetry Exporter | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.Exporter-readme-pre) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.0.0-beta.2/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/) | +| Purview Catalog | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Catalog/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Catalog-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Catalog_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Catalog/) | +| Purview Scanning | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Scanning/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Scanning-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Scanning_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Scanning/) | +| Service Bus | NuGet [7.1.2](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/7.1.2)
NuGet [7.2.0-beta.3](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/7.2.0-beta.3) | [docs](/dotnet/api/overview/azure/Messaging.ServiceBus-readme) | GitHub [7.1.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.ServiceBus_7.1.2/sdk/servicebus/Azure.Messaging.ServiceBus/)
GitHub [7.2.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.ServiceBus_7.2.0-beta.3/sdk/servicebus/Azure.Messaging.ServiceBus/) | +| Storage - Blobs | NuGet [12.8.4](https://www.nuget.org/packages/Azure.Storage.Blobs/12.8.4)
NuGet [12.9.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Blobs/12.9.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme) | GitHub [12.8.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.8.4/sdk/storage/Azure.Storage.Blobs/)
GitHub [12.9.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.9.0-beta.4/sdk/storage/Azure.Storage.Blobs/) | +| Storage - Blobs Batch | NuGet [12.5.2](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.5.2)
NuGet [12.6.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.6.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme) | GitHub [12.5.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.5.2/sdk/storage/Azure.Storage.Blobs.Batch/)
GitHub [12.6.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.6.0-beta.4/sdk/storage/Azure.Storage.Blobs.Batch/) | +| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.12](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.12) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme-pre) | GitHub [12.0.0-preview.12](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.12/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | +| Storage - Common | NuGet [12.7.3](https://www.nuget.org/packages/Azure.Storage.Common/12.7.3)
NuGet [12.8.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Common/12.8.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Common-readme) | GitHub [12.7.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.7.3/sdk/storage/Azure.Storage.Common/)
GitHub [12.8.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.8.0-beta.4/sdk/storage/Azure.Storage.Common/) | +| Storage - Files Data Lake | NuGet [12.6.2](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.6.2)
NuGet [12.7.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.7.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme) | GitHub [12.6.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.6.2/sdk/storage/Azure.Storage.Files.DataLake/)
GitHub [12.7.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.7.0-beta.4/sdk/storage/Azure.Storage.Files.DataLake/) | +| Storage - Files Shares | NuGet [12.6.2](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.6.2)
NuGet [12.7.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.7.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme) | GitHub [12.6.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.6.2/sdk/storage/Azure.Storage.Files.Shares/)
GitHub [12.7.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.7.0-beta.4/sdk/storage/Azure.Storage.Files.Shares/) | +| Storage - Queues | NuGet [12.6.2](https://www.nuget.org/packages/Azure.Storage.Queues/12.6.2)
NuGet [12.7.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Queues/12.7.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme) | GitHub [12.6.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.6.2/sdk/storage/Azure.Storage.Queues/)
GitHub [12.7.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.7.0-beta.4/sdk/storage/Azure.Storage.Queues/) | +| Synapse - AccessControl | NuGet [1.0.0-preview.4](https://www.nuget.org/packages/Azure.Analytics.Synapse.AccessControl/1.0.0-preview.4) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.AccessControl-readme-pre) | GitHub [1.0.0-preview.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.AccessControl_1.0.0-preview.4/sdk/synapse/Azure.Analytics.Synapse.AccessControl/) | +| Synapse - Artifacts | NuGet [1.0.0-preview.10](https://www.nuget.org/packages/Azure.Analytics.Synapse.Artifacts/1.0.0-preview.10) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Artifacts-readme-pre) | GitHub [1.0.0-preview.10](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Artifacts_1.0.0-preview.10/sdk/synapse/Azure.Analytics.Synapse.Artifacts/) | +| Synapse - Managed Private Endpoints | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Analytics.Synapse.ManagedPrivateEndpoints/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.ManagedPrivateEndpoints-readme-pre) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.ManagedPrivateEndpoints_1.0.0-beta.3/sdk/synapse/Azure.Analytics.Synapse.ManagedPrivateEndpoints/) | +| Synapse - Monitoring | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Analytics.Synapse.Monitoring/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Monitoring-readme-pre) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Monitoring_1.0.0-beta.3/sdk/synapse/Azure.Analytics.Synapse.Monitoring/) | +| Synapse - Spark | NuGet [1.0.0-preview.6](https://www.nuget.org/packages/Azure.Analytics.Synapse.Spark/1.0.0-preview.6) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Spark-readme-pre) | GitHub [1.0.0-preview.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Spark_1.0.0-preview.6/sdk/synapse/Azure.Analytics.Synapse.Spark/) | +| System Memory Data | NuGet [1.0.2](https://www.nuget.org/packages/System.Memory.Data/1.0.2) | [docs](/dotnet/api/overview/azure/System.Memory.Data-readme) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/System.Memory.Data_1.0.2/sdk/core/System.Memory.Data/) | +| Tables | NuGet [12.0.0-beta.8](https://www.nuget.org/packages/Azure.Data.Tables/12.0.0-beta.8) | [docs](/dotnet/api/overview/azure/Data.Tables-readme-pre) | GitHub [12.0.0-beta.8](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.Tables_12.0.0-beta.8/sdk/tables/Azure.Data.Tables/) | +| Text Analytics | NuGet [5.0.0](https://www.nuget.org/packages/Azure.AI.TextAnalytics/5.0.0)
NuGet [5.1.0-beta.7](https://www.nuget.org/packages/Azure.AI.TextAnalytics/5.1.0-beta.7) | [docs](/dotnet/api/overview/azure/AI.TextAnalytics-readme) | GitHub [5.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.TextAnalytics_5.0.0/sdk/textanalytics/Azure.AI.TextAnalytics/)
GitHub [5.1.0-beta.7](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.TextAnalytics_5.1.0-beta.7/sdk/textanalytics/Azure.AI.TextAnalytics/) | +| Resource Management - App Configuration | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.AppConfiguration/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.AppConfiguration-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppConfiguration_1.0.0-preview.1/sdk/appconfiguration/Azure.ResourceManager.AppConfiguration/) | +| Resource Management - Communication | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.Communication/1.0.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Communication-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Communication_1.0.0/sdk/communication/Azure.ResourceManager.Communication/) | +| Resource Management - Compute | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Compute/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Compute-readme-pre) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute_1.0.0-preview.2/sdk/compute/Azure.ResourceManager.Compute/) | +| Resource Management - Cosmos DB | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.CosmosDB/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.CosmosDB-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.CosmosDB_1.0.0-preview.1/sdk/cosmosdb/Azure.ResourceManager.CosmosDB/) | +| Resource Management - DNS | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.Dns/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Dns-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Dns_1.0.0-preview.1/sdk/dns/Azure.ResourceManager.Dns/) | +| Resource Management - Event Hubs | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.EventHubs/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.EventHubs-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.EventHubs_1.0.0-preview.1/sdk/eventhub/Azure.ResourceManager.EventHubs/) | +| Resource Management - Insights | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.Insights/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Insights-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Insights_1.0.0-preview.1/sdk/insights/Azure.ResourceManager.Insights/) | +| Resource Management - KeyVault | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.KeyVault/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.KeyVault-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.KeyVault_1.0.0-preview.1/sdk/keyvault/Azure.ResourceManager.KeyVault/) | +| Resource Management - Network | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Network/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Network-readme-pre) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Network_1.0.0-preview.2/sdk/network/Azure.ResourceManager.Network/) | +| Resource Management - Resources | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Resources/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Resources-readme-pre) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Resources_1.0.0-preview.2/sdk/resources/Azure.ResourceManager.Resources/) | +| Resource Management - Storage | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Storage/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Storage-readme-pre) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Storage_1.0.0-preview.2/sdk/storage/Azure.ResourceManager.Storage/) | +| Azure.Communication.Administration | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.Administration/1.0.0-beta.3) | | | +| Azure.Communication.Calling | NuGet [1.0.0-beta.28](https://www.nuget.org/packages/Azure.Communication.Calling/1.0.0-beta.28) | | | +| Azure.Communication.NetworkTraversal | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Communication.NetworkTraversal/1.0.0-beta.1) | | | +| Azure.Messaging.WebPubSub | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Messaging.WebPubSub/1.0.0-beta.1) | | | +| Azure.Quantum.Jobs | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Quantum.Jobs/1.0.0-beta.2) | | | +| IoT Models Repository | NuGet [1.0.0-preview.3](https://www.nuget.org/packages/Azure.IoT.ModelsRepository/1.0.0-preview.3) | | | +| Microsoft.Azure.Functions.Analyzers | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Analyzers/1.0.0) | | | +| Microsoft.Azure.Functions.Authentication.WebAssembly | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Authentication.WebAssembly/1.0.0)
NuGet [1.0.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Functions.Authentication.WebAssembly/1.0.1-preview) | | | +| Microsoft.Azure.Functions.Worker.Core | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Core/1.1.0) | | | +| Microsoft.Azure.Functions.Worker.Extensions.Abstractions | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Abstractions/1.0.0)
NuGet [1.0.0-preview5](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Abstractions/1.0.0-preview5) | | | +| Microsoft.Azure.Functions.Worker.Extensions.CosmosDB | NuGet [3.0.9](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.CosmosDB/3.0.9)
NuGet [3.0.9-preview1](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.CosmosDB/3.0.9-preview1) | | | +| Microsoft.Azure.Functions.Worker.Extensions.EventGrid | NuGet [2.1.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.EventGrid/2.1.0)
NuGet [2.1.0-preview1](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.EventGrid/2.1.0-preview1) | | | +| Microsoft.Azure.Functions.Worker.Extensions.EventHubs | NuGet [4.2.1](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.EventHubs/4.2.1) | | | +| Microsoft.Azure.Functions.Worker.Extensions.Http | NuGet [3.0.13](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Http/3.0.13) | | | +| Microsoft.Azure.Functions.Worker.Extensions.Kafka | NuGet [3.2.1](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Kafka/3.2.1)
NuGet [3.2.1-preview1](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Kafka/3.2.1-preview1) | | | +| Microsoft.Azure.Functions.Worker.Extensions.RabbitMQ | NuGet [1.0.0-beta](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.RabbitMQ/1.0.0-beta) | | | +| Microsoft.Azure.Functions.Worker.Extensions.ServiceBus | NuGet [4.2.1](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.ServiceBus/4.2.1)
NuGet [4.2.1-preview1](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.ServiceBus/4.2.1-preview1) | | | +| Microsoft.Azure.Functions.Worker.Extensions.SignalRService | NuGet [1.2.2](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.SignalRService/1.2.2)
NuGet [1.2.2-preview1](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.SignalRService/1.2.2-preview1) | | | +| Microsoft.Azure.Functions.Worker.Extensions.Storage | NuGet [4.0.4](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Storage/4.0.4)
NuGet [4.0.4-preview1](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Storage/4.0.4-preview1) | | | +| Microsoft.Azure.Functions.Worker.Extensions.Timer | NuGet [4.1.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Timer/4.1.0) | | | +| Microsoft.Azure.Functions.Worker.Extensions.Warmup | NuGet [4.0.2](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Warmup/4.0.2) | | | +| Microsoft.Azure.Functions.Worker.Grpc | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Grpc/1.1.0) | | | +| Microsoft.Azure.Functions.Worker.ItemTemplates | NuGet [3.1.1796](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.ItemTemplates/3.1.1796) | | | +| Microsoft.Azure.Functions.Worker.ProjectTemplates | NuGet [3.1.1796](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.ProjectTemplates/3.1.1796) | | | +| Microsoft.Azure.Functions.Worker.Sdk.Analyzers | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Sdk.Analyzers/1.0.0) | | | +| Microsoft.Azure.Management.ChangeAnalysis | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ChangeAnalysis/1.0.0)
NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Management.ChangeAnalysis/1.0.0-beta.1) | | | +| Microsoft.Azure.Management.DeviceUpdate | NuGet [1.0.1-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Management.DeviceUpdate/1.0.1-beta.1) | | | +| Microsoft.Azure.Management.Elastic | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Elastic/1.0.0-beta.1) | | | +| Microsoft.Azure.Management.Healthbot | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Healthbot/1.0.0) | | | +| Microsoft.Azure.Management.Kubernetes | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Kubernetes/1.0.0-beta.1) | | | +| Microsoft.Azure.Management.KubernetesConfiguration | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.KubernetesConfiguration/1.0.0) | | | +| Microsoft.Azure.Management.ProviderHub | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Management.ProviderHub/1.0.0-beta.1) | | | | Microsoft.Azure.Management.Purview | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Purview/1.0.0-beta.1) | | | | Microsoft.Azure.Management.Quantum | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Quantum/1.0.0-beta.1) | | | -| Microsoft.Azure.SignalR.Emulator | NuGet [1.0.0-preview1-10723](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Emulator/1.0.0-preview1-10723) | | | -| Anomaly Detector | NuGet [3.0.0-preview.2](https://www.nuget.org/packages/Azure.AI.AnomalyDetector/3.0.0-preview.2) | [docs](/dotnet/api/overview/azure/AI.AnomalyDetector-readme-pre/) | GitHub [3.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AnomalyDetector_3.0.0-preview.2/sdk/anomalydetector/Azure.AI.AnomalyDetector/) | +| Microsoft.Azure.Management.ServiceFabricManagedClusters | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ServiceFabricManagedClusters/1.0.0)
NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Management.ServiceFabricManagedClusters/1.0.0-beta.1) | | | +| Microsoft.Azure.Management.StoragePool | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.StoragePool/1.0.0) | | | +| Microsoft.Azure.Management.VideoAnalyzer | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Management.VideoAnalyzer/1.0.0-beta.1) | | | +| Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents/1.0.0-beta.1) | | | +| Microsoft.Azure.SignalR.Emulator | NuGet [1.0.0-preview1-10756](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Emulator/1.0.0-preview1-10756) | | | +| Microsoft.Azure.WebJobs.Extensions.WebPubSub | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.WebPubSub/1.0.0-beta.1) | | | +| Anomaly Detector | NuGet [3.0.0-preview.3](https://www.nuget.org/packages/Azure.AI.AnomalyDetector/3.0.0-preview.3) | [docs](/dotnet/api/overview/azure/AI.AnomalyDetector-readme-pre) | GitHub [3.0.0-preview.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AnomalyDetector_3.0.0-preview.3/sdk/anomalydetector/Azure.AI.AnomalyDetector/) | | Anomaly Detector | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.AnomalyDetector/1.0.0)
NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.AnomalyDetector/1.0.0-preview.1) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.AnomalyDetector_1.0.0-preview.1/sdk/cognitiveservices/AnomalyDetector) | -| App Configuration | NuGet [1.0.2](https://www.nuget.org/packages/Azure.Data.AppConfiguration/1.0.2) | [docs](/dotnet/api/overview/azure/Data.AppConfiguration-readme/) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.AppConfiguration_1.0.2/sdk/appconfiguration/Azure.Data.AppConfiguration/) | +| App Configuration | NuGet [1.0.3](https://www.nuget.org/packages/Azure.Data.AppConfiguration/1.0.3)
NuGet [1.1.0-beta.2](https://www.nuget.org/packages/Azure.Data.AppConfiguration/1.1.0-beta.2) | [docs](/dotnet/api/overview/azure/Data.AppConfiguration-readme) | GitHub [1.0.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.AppConfiguration_1.0.3/sdk/appconfiguration/Azure.Data.AppConfiguration/)
GitHub [1.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.AppConfiguration_1.1.0-beta.2/sdk/appconfiguration/Azure.Data.AppConfiguration/) | | App Service | NuGet [0.2.2-alpha](https://www.nuget.org/packages/Microsoft.Azure.AppService/0.2.2-alpha) | | | | App Service - API Apps Common | NuGet [0.9.36](https://www.nuget.org/packages/Microsoft.Azure.AppService.ApiApps.Common/0.9.36) | | | | App Service - API Apps Service | NuGet [0.9.64](https://www.nuget.org/packages/Microsoft.Azure.AppService.ApiApps.Service/0.9.64) | | | | Application Insights | NuGet [0.9.0-preview](https://www.nuget.org/packages/Microsoft.Azure.ApplicationInsights/0.9.0-preview) | | | | Application Insights - Query | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.ApplicationInsights.Query/1.0.0) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/applicationinsights/Microsoft.Azure.ApplicationInsights.Query) | -| ASP.NET Extension - Configuration Secrets | NuGet [1.0.2](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.Configuration.Secrets/1.0.2) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.Configuration.Secrets-readme/) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.Configuration.Secrets_1.0.2/sdk/extensions/Azure.Extensions.AspNetCore.Configuration.Secrets/) | -| ASP.NET Extension - DataProtection Blobs | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Blobs/1.2.0) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Blobs-readme/) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Blobs_1.2.0/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Blobs/) | -| ASP.NET Extension - DataProtection Keys | NuGet [1.0.2](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Keys/1.0.2) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Keys-readme/) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Keys_1.0.2/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Keys/) | +| ASP.NET Extension - Configuration Secrets | NuGet [1.2.1](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.Configuration.Secrets/1.2.1) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.Configuration.Secrets-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.Configuration.Secrets_1.2.1/sdk/extensions/Azure.Extensions.AspNetCore.Configuration.Secrets/) | +| ASP.NET Extension - DataProtection Blobs | NuGet [1.2.1](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Blobs/1.2.1) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Blobs-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Blobs_1.2.1/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Blobs/) | +| ASP.NET Extension - DataProtection Keys | NuGet [1.0.3](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Keys/1.0.3) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Keys-readme) | GitHub [1.0.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Keys_1.0.3/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Keys/) | +| Attestation | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Security.Attestation/1.0.0) | [docs](/dotnet/api/overview/azure/Security.Attestation-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.Attestation_1.0.0/sdk/attestation/Azure.Security.Attestation/) | | Attestation | NuGet [0.10.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Attestation/0.10.0-preview) | | GitHub [0.10.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Attestation_0.10.0-preview/sdk/attestation/Microsoft.Azure.Attestation/) | | AutoRest Common | NuGet [2.4.48](https://www.nuget.org/packages/Microsoft.AutoRest.Common/2.4.48) | | GitHub [2.4.48](https://github.com/Azure/autorest.common) | | Autosuggest | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.AutoSuggest/2.0.0) | | | | Azure Active Directory - App Authentication | NuGet [1.6.1](https://www.nuget.org/packages/Microsoft.Azure.Services.AppAuthentication/1.6.1) | | | -| Azure Mixed Reality Authentication | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.MixedReality.Authentication/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.Authentication_1.0.0-beta.1/sdk/mixedreality/Azure.MixedReality.Authentication/) | -| Azure Monitor Exporter for OpenTelemetry | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.OpenTelemetry.Exporter.AzureMonitor/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Microsoft.OpenTelemetry.Exporter.AzureMonitor-readme-pre/) | | -| Azure Remote Rendering | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.MixedReality.RemoteRendering/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.RemoteRendering_1.0.0-beta.1/sdk/mixedreality/Azure.MixedReality.RemoteRendering/) | -| Azure Security Attestation | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Security.Attestation/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Security.Attestation-readme-pre/) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.Attestation_1.0.0-beta.1/sdk/attestation/Azure.Security.Attestation/) | +| Azure Mixed Reality Authentication | NuGet [1.0.1](https://www.nuget.org/packages/Azure.MixedReality.Authentication/1.0.1) | [docs](/dotnet/api/overview/azure/MixedReality.Authentication-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.Authentication_1.0.1/sdk/mixedreality/Azure.MixedReality.Authentication/) | +| Azure Monitor Exporter for OpenTelemetry | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.OpenTelemetry.Exporter.AzureMonitor/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Microsoft.OpenTelemetry.Exporter.AzureMonitor-readme-pre) | | +| Azure Object Anchors Conversion | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.MixedReality.ObjectAnchors.Conversion/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/MixedReality.ObjectAnchors.Conversion-readme-pre) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.ObjectAnchors.Conversion_0.2.0-beta.1/sdk/objectanchors/Azure.MixedReality.ObjectAnchors.Conversion/) | +| Azure Remote Rendering | NuGet [1.0.1](https://www.nuget.org/packages/Azure.MixedReality.RemoteRendering/1.0.1) | [docs](/dotnet/api/overview/azure/MixedReality.RemoteRendering-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.RemoteRendering_1.0.1/sdk/remoterendering/Azure.MixedReality.RemoteRendering/) | | Azure Stack - Azure Consistent Storage | NuGet [0.10.8-preview](https://www.nuget.org/packages/Microsoft.AzureStack.AzureConsistentStorage/0.10.8-preview) | | | +| Azure Video Analyzer Edge | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Media.VideoAnalyzer.Edge/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Media.VideoAnalyzer.Edge-readme-pre) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Media.VideoAnalyzer.Edge_1.0.0-beta.4/sdk/videoanalyzer/Azure.Media.VideoAnalyzer.Edge/) | | Batch | NuGet [14.0.0](https://www.nuget.org/packages/Microsoft.Azure.Batch/14.0.0) | | GitHub [14.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Batch_14.0.0/sdk/batch/Microsoft.Azure.Batch/) | | Batch - Apps Cryptography | NuGet [1.1.1.4](https://www.nuget.org/packages/Microsoft.Azure.Batch.Apps.Cryptography/1.1.1.4) | | | | Batch - Conventions Files | NuGet [3.5.1](https://www.nuget.org/packages/Microsoft.Azure.Batch.Conventions.Files/3.5.1) | | GitHub [3.5.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Batch.Conventions.Files_3.5.1/sdk/batch/Microsoft.Azure.Batch.Conventions.Files/) | @@ -95,61 +143,65 @@ | Bing Video Search | NuGet [2.1.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.BingVideoSearch/2.1.0-preview.1) | | GitHub [2.1.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Search.BingVideoSearch_2.1.0-preview.1/sdk/cognitiveservices/Search.BingVideoSearch) | | Bing Visual Search | NuGet [2.1.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.BingVisualSearch/2.1.0-preview.1) | | GitHub [2.1.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Search.BingVisualSearch_2.1.0-preview.1/sdk/cognitiveservices/Search.BingVisualSearch) | | Bing Web Search | NuGet [2.1.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.BingWebSearch/2.1.0-preview.1) | | GitHub [2.1.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Search.BingWebSearch_2.1.0-preview.1/sdk/cognitiveservices/Search.BingWebSearch) | -| Client Runtime | NuGet [2.3.22](https://www.nuget.org/packages/Microsoft.Rest.ClientRuntime/2.3.22) | | GitHub [2.3.22](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Rest.ClientRuntime_2.3.21/sdk/mgmtcommon/ClientRuntime) | +| Client Runtime | NuGet [2.3.23](https://www.nuget.org/packages/Microsoft.Rest.ClientRuntime/2.3.23) | | GitHub [2.3.23](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Rest.ClientRuntime_2.3.21/sdk/mgmtcommon/ClientRuntime) | | Client Runtime - Azure | NuGet [3.3.19](https://www.nuget.org/packages/Microsoft.Rest.ClientRuntime.Azure/3.3.19) | | GitHub [3.3.19](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/mgmtcommon/ClientRuntime.Azure) | | Client Runtime - Azure Authentication | NuGet [2.4.1](https://www.nuget.org/packages/Microsoft.Rest.ClientRuntime.Azure.Authentication/2.4.1) | | GitHub [2.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Rest.ClientRuntime.Azure.Authentication_2.4.1/sdk/mgmtcommon/Auth/Az.Auth/Az.Authentication) | | Client Runtime - Azure Test Framework | NuGet [1.7.7](https://www.nuget.org/packages/Microsoft.Rest.ClientRuntime.Azure.TestFramework/1.7.7) | | GitHub [1.7.7](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Rest.ClientRuntime.Azure.TestFramework_1.7.7/sdk/mgmtcommon/TestFramework/ClientRuntime.Azure.TestFramework) | | Client Runtime - ETW | NuGet [2.1.3](https://www.nuget.org/packages/Microsoft.Rest.ClientRuntime.Etw/2.1.3) | | GitHub [2.1.3](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/mgmtcommon/ClientRuntime.Etw) | | Client Runtime - Log4Net | NuGet [2.1.4](https://www.nuget.org/packages/Microsoft.Rest.ClientRuntime.Log4Net/2.1.4) | | GitHub [2.1.4](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/mgmtcommon/ClientRuntime.Log4Net) | -| Cognitive Search | NuGet [11.2.0](https://www.nuget.org/packages/Azure.Search.Documents/11.2.0) | [docs](/dotnet/api/overview/azure/Search.Documents-readme/) | GitHub [11.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Search.Documents_11.2.0/sdk/search/Azure.Search.Documents/) | +| Cognitive Search | NuGet [11.2.1](https://www.nuget.org/packages/Azure.Search.Documents/11.2.1)
NuGet [11.3.0-beta.2](https://www.nuget.org/packages/Azure.Search.Documents/11.3.0-beta.2) | [docs](/dotnet/api/overview/azure/Search.Documents-readme) | GitHub [11.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Search.Documents_11.2.1/sdk/search/Azure.Search.Documents/)
GitHub [11.3.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Search.Documents_11.3.0-beta.2/sdk/search/Azure.Search.Documents/) | | Commerce Usage Aggregates | NuGet [1.5.3](https://www.nuget.org/packages/Microsoft.Azure.Commerce.UsageAggregates/1.5.3) | | | | Common | NuGet [2.2.1](https://www.nuget.org/packages/Microsoft.Azure.Common/2.2.1) | | | | Common - Authentication | NuGet [1.7.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Common.Authentication/1.7.0-preview) | | | | Common - Dependencies | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Common.Dependencies/1.0.0) | | | -| Communication Administration | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.Administration/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Communication.Administration-readme-pre/) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Administration_1.0.0-beta.3/sdk/communication/Azure.Communication.Administration/) | -| Communication Chat | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Communication.Chat/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme-pre/) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.0.0-beta.4/sdk/communication/Azure.Communication.Chat/) | -| Communication Common | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Communication.Common/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Communication.Common-readme-pre/) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_1.0.0-beta.4/sdk/communication/Azure.Communication.Common/) | -| Communication Identity | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Communication.Identity/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Communication.Identity-readme-pre/) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Identity_1.0.0-beta.4/sdk/communication/Azure.Communication.Identity/) | -| Communication SMS | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.Sms/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Communication.Sms-readme-pre/) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Sms_1.0.0-beta.3/sdk/communication/Azure.Communication.Sms/) | -| Computer Vision | NuGet [6.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.ComputerVision/6.0.0)
NuGet [6.0.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.ComputerVision/6.0.0-preview.1) | | GitHub [6.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.ComputerVision_6.0.0-preview.1/sdk/cognitiveservices/Vision.ComputerVision) | +| Communication Chat | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Chat/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.0.1/sdk/communication/Azure.Communication.Chat/) | +| Communication Common | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Common/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Common-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_1.0.1/sdk/communication/Azure.Communication.Common/) | +| Communication Identity | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Identity/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Identity-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Identity_1.0.1/sdk/communication/Azure.Communication.Identity/) | +| Communication Phone Numbers | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.PhoneNumbers/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.PhoneNumbers-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.PhoneNumbers_1.0.1/sdk/communication/Azure.Communication.PhoneNumbers/) | +| Communication SMS | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Sms/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Sms-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Sms_1.0.1/sdk/communication/Azure.Communication.Sms/) | +| Computer Vision | NuGet [7.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.ComputerVision/7.0.0) | | GitHub [7.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.ComputerVision_6.0.0-preview.1/sdk/cognitiveservices/Vision.ComputerVision) | +| ConfidentialLedger | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Storage.ConfidentialLedger/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.ConfidentialLedger-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.ConfidentialLedger_1.0.0-beta.1/sdk/confidentialledger/Azure.Storage.ConfidentialLedger/) | | Configuration Manager | NuGet [4.0.0](https://www.nuget.org/packages/Microsoft.Azure.ConfigurationManager/4.0.0) | | | +| Container Registry | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Containers.ContainerRegistry/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Containers.ContainerRegistry-readme-pre) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Containers.ContainerRegistry_1.0.0-beta.2/sdk/containerregistry/Azure.Containers.ContainerRegistry/) | | Container Registry | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Microsoft.Azure.ContainerRegistry/1.0.0-preview.2) | | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.ContainerRegistry_1.0.0-preview.2/sdk/containerregistry/Microsoft.Azure.ContainerRegistry/) | | Content Moderator | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.ContentModerator/2.0.0) | | | -| Core | NuGet [1.9.0](https://www.nuget.org/packages/Azure.Core/1.9.0) | [docs](/dotnet/api/overview/azure/Core-readme/) | GitHub [1.9.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core_1.9.0/sdk/core/Azure.Core/) | -| Core - AMQP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Core.Amqp/1.0.0) | [docs](/dotnet/api/overview/azure/Core.Amqp-readme/) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Amqp_1.0.0/sdk/core/Azure.Core.Amqp/) | +| Core | NuGet [1.14.0](https://www.nuget.org/packages/Azure.Core/1.14.0) | [docs](/dotnet/api/overview/azure/Core-readme) | GitHub [1.14.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core_1.14.0/sdk/core/Azure.Core/) | +| Core - AMQP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Core.Amqp/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Core.Amqp/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Core.Amqp-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Amqp_1.0.0/sdk/core/Azure.Core.Amqp/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Amqp_1.1.0-beta.1/sdk/core/Azure.Core.Amqp/) | | Core Newtonsoft Json | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Core.NewtonsoftJson/1.0.0)
NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.Core.NewtonsoftJson/1.0.0-preview.1) | | | | Core Spatial | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial/1.0.0)
NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial/1.0.0-beta.1) | | | | Core Spatial Newtonsoft Json | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial.NewtonsoftJson/1.0.0)
NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial.NewtonsoftJson/1.0.0-beta.1) | | | | Cosmos DB | NuGet [4.0.0-preview3](https://www.nuget.org/packages/Azure.Cosmos/4.0.0-preview3) | [docs](/dotnet/api/azure.cosmos) | GitHub [4.0.0-preview3](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/releases/4.0.0-preview3) | -| Cosmos DB | NuGet [3.16.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.16.0) | [docs](/dotnet/api/overview/azure/cosmosdb) | GitHub [3.16.0](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/3.12.0/Microsoft.Azure.Cosmos) | +| Cosmos DB | NuGet [3.19.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.19.0)
NuGet [3.19.0-preview1](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.19.0-preview1) | [docs](/dotnet/api/overview/azure/cosmosdb) | GitHub [3.19.0](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/3.12.0/Microsoft.Azure.Cosmos) | | Cosmos DB - BulkExecutor | NuGet [2.5.1-preview](https://www.nuget.org/packages/Microsoft.Azure.CosmosDB.BulkExecutor/2.5.1-preview) | | GitHub [2.5.1-preview](https://github.com/Azure/azure-cosmosdb-bulkexecutor-dotnet-getting-started) | -| Cosmos DB - Direct | NuGet [3.17.1](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Direct/3.17.1) | | GitHub [3.17.1](https://github.com/Azure/azure-cosmos-dotnet-v3) | -| Cosmos DB - Encryption | NuGet [1.0.0-previewV10](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Encryption/1.0.0-previewV10) | | GitHub [1.0.0-previewV10](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/releases/encryption/1.0.0-preview4/Microsoft.Azure.Cosmos.Encryption) | +| Cosmos DB - Direct | NuGet [3.20.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Direct/3.20.0) | | GitHub [3.20.0](https://github.com/Azure/azure-cosmos-dotnet-v3) | +| Cosmos DB - Encryption | NuGet [1.0.0-previewV15](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Encryption/1.0.0-previewV15) | | GitHub [1.0.0-previewV15](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/releases/encryption/1.0.0-preview4/Microsoft.Azure.Cosmos.Encryption) | | Custom Image Search | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.CustomImageSearch/2.0.0) | | | | Custom Search | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.CustomSearch/2.0.0) | | | | Custom Vision Prediction | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Prediction/2.0.0) | | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Prediction_2.0.0/sdk/cognitiveservices/Vision.CustomVision.Prediction) | | Custom Vision Training | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training/2.0.0)
NuGet [2.1.0-preview](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training/2.1.0-preview) | | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training_2.0.0/sdk/cognitiveservices/Vision.CustomVision.Training) | | Data Lake Analytics | NuGet [1.4.200831](https://www.nuget.org/packages/Microsoft.Azure.DataLake.USQL.SDK/1.4.200831) | | | | Data Lake Storage | NuGet [1.2.5-alpha](https://www.nuget.org/packages/Microsoft.Azure.DataLake.Store/1.2.5-alpha) | [docs](/dotnet/api/overview/azure/data-lake-store) | GitHub [1.2.5-alpha](https://github.com/Azure/azure-data-lake-store-net/tree/1.2.3-alpha) | -| DCAP | NuGet [1.6.0](https://www.nuget.org/packages/Microsoft.Azure.DCAP/1.6.0) | | GitHub [1.6.0](https://github.com/microsoft/Azure-DCAP-Client/tree/1.6) | -| Devices Client | NuGet [1.35.0](https://www.nuget.org/packages/Microsoft.Azure.Devices.Client/1.35.0) | | | -| Digital Twins - Core | NuGet [1.2.1](https://www.nuget.org/packages/Azure.DigitalTwins.Core/1.2.1) | [docs](/dotnet/api/overview/azure/DigitalTwins.Core-readme/) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.DigitalTwins.Core_1.2.1/sdk/digitaltwins/Azure.DigitalTwins.Core/) | -| Document DB | NuGet [2.13.1](https://www.nuget.org/packages/Microsoft.Azure.DocumentDB/2.13.1) | | GitHub [2.13.1](https://github.com/Azure/azure-cosmos-dotnet-v2) | -| Document DB - Change Feed Processor | NuGet [2.3.2](https://www.nuget.org/packages/Microsoft.Azure.DocumentDB.ChangeFeedProcessor/2.3.2) | | GitHub [2.3.2](https://github.com/Azure/azure-documentdb-changefeedprocessor-dotnet/tree/master) | -| Document DB - Core | NuGet [2.13.1](https://www.nuget.org/packages/Microsoft.Azure.DocumentDB.Core/2.13.1) | | GitHub [2.13.1](https://github.com/Azure/azure-cosmos-dotnet-v2) | +| DCAP | NuGet [1.10.0](https://www.nuget.org/packages/Microsoft.Azure.DCAP/1.10.0) | | GitHub [1.10.0](https://github.com/microsoft/Azure-DCAP-Client/tree/1.6) | +| Devices Client | NuGet [1.37.2](https://www.nuget.org/packages/Microsoft.Azure.Devices.Client/1.37.2) | | | +| Digital Twins - Core | NuGet [1.2.2](https://www.nuget.org/packages/Azure.DigitalTwins.Core/1.2.2) | [docs](/dotnet/api/overview/azure/DigitalTwins.Core-readme) | GitHub [1.2.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.DigitalTwins.Core_1.2.2/sdk/digitaltwins/Azure.DigitalTwins.Core/) | +| Document DB | NuGet [2.14.1](https://www.nuget.org/packages/Microsoft.Azure.DocumentDB/2.14.1) | | GitHub [2.14.1](https://github.com/Azure/azure-cosmos-dotnet-v2) | +| Document DB - Change Feed Processor | NuGet [2.4.0](https://www.nuget.org/packages/Microsoft.Azure.DocumentDB.ChangeFeedProcessor/2.4.0) | | GitHub [2.4.0](https://github.com/Azure/azure-documentdb-changefeedprocessor-dotnet/tree/master) | +| Document DB - Core | NuGet [2.14.1](https://www.nuget.org/packages/Microsoft.Azure.DocumentDB.Core/2.14.1) | | GitHub [2.14.1](https://github.com/Azure/azure-cosmos-dotnet-v2) | +| Document Translation | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.AI.Translation.Document/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/AI.Translation.Document-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Translation.Document_1.0.0-beta.1/sdk/translation/Azure.AI.Translation.Document/) | | Entity Search | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.EntitySearch/2.0.0) | | | -| Event Grid | NuGet [4.0.0-beta.5](https://www.nuget.org/packages/Azure.Messaging.EventGrid/4.0.0-beta.5) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid-readme-pre/) | GitHub [4.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid_4.0.0-beta.5/sdk/eventgrid/Azure.Messaging.EventGrid/) | +| Event Grid | NuGet [4.2.0](https://www.nuget.org/packages/Azure.Messaging.EventGrid/4.2.0) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid-readme) | GitHub [4.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid_4.2.0/sdk/eventgrid/Azure.Messaging.EventGrid/) | | Event Grid | NuGet [3.2.0](https://www.nuget.org/packages/Microsoft.Azure.EventGrid/3.2.0) | [docs](/dotnet/api/overview/azure/eventgrid) | GitHub [3.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.EventGrid_3.2.0/sdk/eventgrid/Microsoft.Azure.EventGrid/) | -| Event Hubs | NuGet [5.3.0](https://www.nuget.org/packages/Azure.Messaging.EventHubs/5.3.0) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs-readme/) | GitHub [5.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs_5.3.0/sdk/eventhub/Azure.Messaging.EventHubs/) | -| Event Hubs | NuGet [4.3.1](https://www.nuget.org/packages/Microsoft.Azure.EventHubs/4.3.1) | | GitHub [4.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.EventHubs_4.3.1/sdk/eventhub/Microsoft.Azure.EventHubs/) | -| Event Hubs - Event Processor | NuGet [5.3.0](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/5.3.0) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs.Processor-readme/) | GitHub [5.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs.Processor_5.3.0/sdk/eventhub/Azure.Messaging.EventHubs.Processor/) | -| Event Hubs - Processor | NuGet [4.3.1](https://www.nuget.org/packages/Microsoft.Azure.EventHubs.Processor/4.3.1) | | GitHub [4.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.EventHubs.Processor_4.3.1/sdk/eventhub/Microsoft.Azure.EventHubs.Processor/) | -| Event Hubs - Schema Registry | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Data.SchemaRegistry/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Data.SchemaRegistry-readme-pre/) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.SchemaRegistry_1.0.0-beta.2/sdk/schemaregistry/Azure.Data.SchemaRegistry/) | +| Event Hubs | NuGet [5.4.1](https://www.nuget.org/packages/Azure.Messaging.EventHubs/5.4.1) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs-readme) | GitHub [5.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs_5.4.1/sdk/eventhub/Azure.Messaging.EventHubs/) | +| Event Hubs | NuGet [4.3.2](https://www.nuget.org/packages/Microsoft.Azure.EventHubs/4.3.2) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.EventHubs-readme) | GitHub [4.3.2](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.EventHubs_4.3.2/sdk/eventhub/Microsoft.Azure.EventHubs/) | +| Event Hubs - Event Processor | NuGet [5.4.1](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/5.4.1) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs.Processor-readme) | GitHub [5.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs.Processor_5.4.1/sdk/eventhub/Azure.Messaging.EventHubs.Processor/) | +| Event Hubs - Processor | NuGet [4.3.2](https://www.nuget.org/packages/Microsoft.Azure.EventHubs.Processor/4.3.2) | | GitHub [4.3.2](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.EventHubs.Processor_4.3.2/sdk/eventhub/Microsoft.Azure.EventHubs.Processor/) | +| Event Hubs - Schema Registry | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Data.SchemaRegistry/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Data.SchemaRegistry-readme-pre) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.SchemaRegistry_1.0.0-beta.2/sdk/schemaregistry/Azure.Data.SchemaRegistry/) | | Event Hubs - Schema Registry Apache Avro | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro/1.0.0-beta.1) | | | | Event Hubs - Service Fabric Processor | NuGet [0.5.4](https://www.nuget.org/packages/Microsoft.Azure.EventHubs.ServiceFabricProcessor/0.5.4) | | GitHub [0.5.4](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.EventHubs.ServiceFabricProcessor_0.5.4/sdk/eventhub/Microsoft.Azure.EventHubs.ServiceFabricProcessor/) | -| Extensions - Caching Cosmos | NuGet [1.0.0-preview5](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Cosmos/1.0.0-preview5) | | GitHub [1.0.0-preview5](https://github.com/Azure/Microsoft.Extensions.Caching.Cosmos/tree/v1.0.0-preview4) | -| Face | NuGet [2.6.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.Face/2.6.0-preview.1) | | GitHub [2.6.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.Face_2.6.0-preview.1/sdk/cognitiveservices/Vision.Face) | -| Form Recognizer | NuGet [3.0.0](https://www.nuget.org/packages/Azure.AI.FormRecognizer/3.0.0)
NuGet [3.1.0-beta.2](https://www.nuget.org/packages/Azure.AI.FormRecognizer/3.1.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.FormRecognizer-readme/) | GitHub [3.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.FormRecognizer_3.0.0/sdk/formrecognizer/Azure.AI.FormRecognizer/)
GitHub [3.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.FormRecognizer_3.1.0-beta.2/sdk/formrecognizer/Azure.AI.FormRecognizer/) | +| Extensions - Caching Cosmos | NuGet [1.0.0-preview6](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Cosmos/1.0.0-preview6) | | GitHub [1.0.0-preview6](https://github.com/Azure/Microsoft.Extensions.Caching.Cosmos/tree/v1.0.0-preview4) | +| Face | NuGet [2.7.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.Face/2.7.0-preview.1) | | GitHub [2.7.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.Face_2.6.0-preview.1/sdk/cognitiveservices/Vision.Face) | +| FarmBeats | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Verticals.AgriFood.Farming/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Verticals.AgriFood.Farming-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Verticals.AgriFood.Farming_1.0.0-beta.1/sdk/farmbeats/Azure.Verticals.AgriFood.Farming/) | +| Form Recognizer | NuGet [3.1.0](https://www.nuget.org/packages/Azure.AI.FormRecognizer/3.1.0) | [docs](/dotnet/api/overview/azure/AI.FormRecognizer-readme) | GitHub [3.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.FormRecognizer_3.1.0/sdk/formrecognizer/Azure.AI.FormRecognizer/) | | Form Recognizer | NuGet [0.8.0-preview](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.FormRecognizer/0.8.0-preview) | | GitHub [0.8.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/cognitiveservices/FormRecognizer) | | Functions - Extensions | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Extensions/1.1.0)
NuGet [1.1.0-preview1](https://www.nuget.org/packages/Microsoft.Azure.Functions.Extensions/1.1.0-preview1) | | GitHub [1.1.0](https://github.com/Azure/azure-functions-dotnet-extensions) | | Gallery | NuGet [2.6.2-preview](https://www.nuget.org/packages/Microsoft.Azure.Gallery/2.6.2-preview) | | | @@ -159,161 +211,160 @@ | Hyak Common | NuGet [1.2.2](https://www.nuget.org/packages/Hyak.Common/1.2.2) | | | | Hyak Common - Tracing Etw | NuGet [1.0.2](https://www.nuget.org/packages/Hyak.Common.Tracing.Etw/1.0.2) | | | | Hyak Common - Tracing Log4Net | NuGet [1.0.2](https://www.nuget.org/packages/Hyak.Common.Tracing.Log4Net/1.0.2) | | | -| Identity | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Identity/1.3.0)
NuGet [1.4.0-beta.3](https://www.nuget.org/packages/Azure.Identity/1.4.0-beta.3) | [docs](/dotnet/api/overview/azure/Identity-readme/) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.3.0/sdk/identity/Azure.Identity/)
GitHub [1.4.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.4.0-beta.3/sdk/identity/Azure.Identity/) | +| Identity | NuGet [1.4.0](https://www.nuget.org/packages/Azure.Identity/1.4.0) | [docs](/dotnet/api/overview/azure/Identity-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.4.0/sdk/identity/Azure.Identity/) | | Image Search | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.ImageSearch/2.0.0) | | | | Information Protection | NuGet [1.7.147](https://www.nuget.org/packages/Microsoft.InformationProtection.File/1.7.147) | | | | Insights | NuGet [0.16.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Insights/0.16.0-preview) | | | +| IoT Device Update | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.IoT.DeviceUpdate/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/IoT.DeviceUpdate-readme-pre) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.IoT.DeviceUpdate_1.0.0-beta.2/sdk/deviceupdate/Azure.Iot.DeviceUpdate/) | | Jobs | NuGet [0.3.2-beta](https://www.nuget.org/packages/Microsoft.Azure.Jobs/0.3.2-beta) | | GitHub [0.3.2-beta](https://github.com/Azure/azure-webjobs-sdk) | | Jobs - Core | NuGet [0.3.2-beta](https://www.nuget.org/packages/Microsoft.Azure.Jobs.Core/0.3.2-beta) | | GitHub [0.3.2-beta](https://github.com/Azure/azure-webjobs-sdk) | | Jobs - Service Bus | NuGet [0.3.2-beta](https://www.nuget.org/packages/Microsoft.Azure.Jobs.ServiceBus/0.3.2-beta) | | GitHub [0.3.2-beta](https://github.com/Azure/azure-webjobs-sdk) | | Key Vault | NuGet [3.0.5](https://www.nuget.org/packages/Microsoft.Azure.KeyVault/3.0.5) | | GitHub [3.0.5](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.KeyVault_3.0.5/sdk/keyvault/Microsoft.Azure.KeyVault/) | -| Key Vault - Administration | NuGet [4.0.0-beta.4](https://www.nuget.org/packages/Azure.Security.KeyVault.Administration/4.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Administration-readme-pre/) | GitHub [4.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Administration_4.0.0-beta.4/sdk/keyvault/Azure.Security.KeyVault.Administration/) | -| Key Vault - Certificates | NuGet [4.1.0](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates/4.1.0)
NuGet [4.2.0-beta.4](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates/4.2.0-beta.4) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Certificates-readme/) | GitHub [4.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Certificates_4.1.0/sdk/keyvault/Azure.Security.KeyVault.Certificates/)
GitHub [4.2.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Certificates_4.2.0-beta.4/sdk/keyvault/Azure.Security.KeyVault.Certificates/) | +| Key Vault - Administration | NuGet [4.0.0-beta.5](https://www.nuget.org/packages/Azure.Security.KeyVault.Administration/4.0.0-beta.5) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Administration-readme-pre) | GitHub [4.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Administration_4.0.0-beta.5/sdk/keyvault/Azure.Security.KeyVault.Administration/) | +| Key Vault - Certificates | NuGet [4.1.1](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates/4.1.1)
NuGet [4.2.0-beta.6](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates/4.2.0-beta.6) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Certificates-readme) | GitHub [4.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Certificates_4.1.1/sdk/keyvault/Azure.Security.KeyVault.Certificates/)
GitHub [4.2.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Certificates_4.2.0-beta.6/sdk/keyvault/Azure.Security.KeyVault.Certificates/) | | Key Vault - Core | NuGet [3.0.5](https://www.nuget.org/packages/Microsoft.Azure.KeyVault.Core/3.0.5) | | GitHub [3.0.5](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.KeyVault.Core_3.0.5/sdk/keyvault/Microsoft.Azure.KeyVault.Core/) | | Key Vault - Cryptography | NuGet [3.0.5](https://www.nuget.org/packages/Microsoft.Azure.KeyVault.Cryptography/3.0.5) | | GitHub [3.0.5](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.KeyVault.Cryptography_3.0.5/sdk/keyvault/Microsoft.Azure.KeyVault.Cryptography/) | | Key Vault - Extensions | NuGet [3.0.5](https://www.nuget.org/packages/Microsoft.Azure.KeyVault.Extensions/3.0.5) | | GitHub [3.0.5](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.KeyVault.Extensions_3.0.5/sdk/keyvault/Microsoft.Azure.KeyVault.Extensions/) | -| Key Vault - Keys | NuGet [4.1.0](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys/4.1.0)
NuGet [4.2.0-beta.4](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys/4.2.0-beta.4) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Keys-readme/) | GitHub [4.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Keys_4.1.0/sdk/keyvault/Azure.Security.KeyVault.Keys/)
GitHub [4.2.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Keys_4.2.0-beta.4/sdk/keyvault/Azure.Security.KeyVault.Keys/) | -| Key Vault - Secrets | NuGet [4.1.0](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets/4.1.0)
NuGet [4.2.0-beta.4](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets/4.2.0-beta.4) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Secrets-readme/) | GitHub [4.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Secrets_4.1.0/sdk/keyvault/Azure.Security.KeyVault.Secrets/)
GitHub [4.2.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Secrets_4.2.0-beta.4/sdk/keyvault/Azure.Security.KeyVault.Secrets/) | +| Key Vault - Keys | NuGet [4.1.1](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys/4.1.1)
NuGet [4.2.0-beta.6](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys/4.2.0-beta.6) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Keys-readme) | GitHub [4.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Keys_4.1.1/sdk/keyvault/Azure.Security.KeyVault.Keys/)
GitHub [4.2.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Keys_4.2.0-beta.6/sdk/keyvault/Azure.Security.KeyVault.Keys/) | +| Key Vault - Secrets | NuGet [4.1.1](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets/4.1.1)
NuGet [4.2.0-beta.5](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets/4.2.0-beta.5) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Secrets-readme) | GitHub [4.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Secrets_4.1.1/sdk/keyvault/Azure.Security.KeyVault.Secrets/)
GitHub [4.2.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Secrets_4.2.0-beta.5/sdk/keyvault/Azure.Security.KeyVault.Secrets/) | | Key Vault - WebKey | NuGet [3.0.5](https://www.nuget.org/packages/Microsoft.Azure.KeyVault.WebKey/3.0.5) | | GitHub [3.0.5](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.KeyVault.WebKey_3.0.5/sdk/keyvault/Microsoft.Azure.KeyVault.WebKey/) | | Kinect Developer Kit | NuGet [1.0.1](https://www.nuget.org/packages/Microsoft.Azure.Kinect.BodyTracking/1.0.1) | | | | Kinect Developer Kit | NuGet [1.4.1](https://www.nuget.org/packages/Microsoft.Azure.Kinect.Sensor/1.4.1) | | GitHub [1.4.1](https://github.com/Microsoft/Azure-Kinect-Sensor-SDK) | | Kusto | NuGet [9.0.6](https://www.nuget.org/packages/Microsoft.Azure.Kusto.Data/9.0.6) | | | | Local Search | NuGet [0.9.0-preview](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.LocalSearch/0.9.0-preview) | | | -| LUIS Authoring | NuGet [3.2.0-preview.3](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Language.LUIS.Authoring/3.2.0-preview.3) | | GitHub [3.2.0-preview.3](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Language.LUIS.Authoring_3.2.0-preview.3/sdk/cognitiveservices/Language.LUIS.Authoring) | +| LUIS - Authoring | NuGet [3.1.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Language.LUIS.Authoring/3.1.0)
NuGet [3.2.0-preview.4](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Language.LUIS.Authoring/3.2.0-preview.4) | | GitHub [3.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Language.LUIS.Authoring_3.2.0-preview.3/sdk/cognitiveservices/Language.LUIS.Authoring) | | LUIS Runtime | NuGet [3.1.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Language.LUIS.Runtime/3.1.0-preview.1) | | GitHub [3.1.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Language.LUIS.Runtime_3.1.0-preview.1/sdk/cognitiveservices/Language.LUIS.Runtime) | -| Media Analytics Edge | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Media.Analytics.Edge/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Media.Analytics.Edge-readme-pre/) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Media.Analytics.Edge_1.0.0-beta.1/sdk/mediaservices/Azure.Media.Analytics.Edge/) | -| Media Live Video Analytics Edge | NuGet [1.0.4-preview.1](https://www.nuget.org/packages/Microsoft.Azure.Media.LiveVideoAnalytics.Edge/1.0.4-preview.1) | | GitHub [1.0.4-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/mediaservices/Microsoft.Azure.Media.LiveVideoAnalytics.Edge) | -| Metrics Advisor | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.AI.MetricsAdvisor/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/AI.MetricsAdvisor-readme-pre/) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.MetricsAdvisor_1.0.0-beta.3/sdk/metricsadvisor/Azure.AI.MetricsAdvisor/) | -| Microsoft.Azure.Amqp | NuGet [2.4.9](https://www.nuget.org/packages/Microsoft.Azure.Amqp/2.4.9) | | | -| Microsoft.Azure.Devices | NuGet [1.30.0](https://www.nuget.org/packages/Microsoft.Azure.Devices/1.30.0) | | | +| Media Analytics Edge | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Media.Analytics.Edge/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Media.Analytics.Edge-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Media.Analytics.Edge_1.0.0-beta.1/sdk/mediaservices/Azure.Media.Analytics.Edge) | +| Media Live Video Analytics Edge | NuGet [1.0.4-preview.1](https://www.nuget.org/packages/Microsoft.Azure.Media.LiveVideoAnalytics.Edge/1.0.4-preview.1) | | GitHub [1.0.4-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Media.LiveVideoAnalytics.Edge_1.0.4-preview.1/sdk/mediaservices/Microsoft.Azure.Media.LiveVideoAnalytics.Edge) | +| Metrics Advisor | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.AI.MetricsAdvisor/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/AI.MetricsAdvisor-readme-pre) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.MetricsAdvisor_1.0.0-beta.3/sdk/metricsadvisor/Azure.AI.MetricsAdvisor/) | +| Microsoft.Azure.Amqp | NuGet [2.4.13](https://www.nuget.org/packages/Microsoft.Azure.Amqp/2.4.13) | | | +| Microsoft.Azure.Devices | NuGet [1.34.0](https://www.nuget.org/packages/Microsoft.Azure.Devices/1.34.0) | | | | Microsoft.Azure.Devices.Client.PCL | NuGet [1.0.16](https://www.nuget.org/packages/Microsoft.Azure.Devices.Client.PCL/1.0.16) | | | | Microsoft.Azure.Devices.DigitalTwin.Client | NuGet [1.0.0-preview-001](https://www.nuget.org/packages/Microsoft.Azure.Devices.DigitalTwin.Client/1.0.0-preview-001) | | | | Microsoft.Azure.Devices.DigitalTwin.Service | NuGet [1.0.0-preview-001](https://www.nuget.org/packages/Microsoft.Azure.Devices.DigitalTwin.Service/1.0.0-preview-001) | | | | Microsoft.Azure.Devices.ProtocolGateway.Core | NuGet [2.0.1](https://www.nuget.org/packages/Microsoft.Azure.Devices.ProtocolGateway.Core/2.0.1) | | | | Microsoft.Azure.Devices.ProtocolGateway.IotHubClient | NuGet [2.0.1](https://www.nuget.org/packages/Microsoft.Azure.Devices.ProtocolGateway.IotHubClient/2.0.1) | | | | Microsoft.Azure.Devices.ProtocolGateway.Providers.CloudStorage | NuGet [2.0.1](https://www.nuget.org/packages/Microsoft.Azure.Devices.ProtocolGateway.Providers.CloudStorage/2.0.1) | | | -| Microsoft.Azure.Devices.Provisioning.Client | NuGet [1.17.0-preview-001](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Client/1.17.0-preview-001) | | | -| Microsoft.Azure.Devices.Provisioning.Security.Tpm | NuGet [1.13.0-preview-001](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Security.Tpm/1.13.0-preview-001) | | | -| Microsoft.Azure.Devices.Provisioning.Service | NuGet [1.17.0-preview-001](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Service/1.17.0-preview-001) | | | -| Microsoft.Azure.Devices.Provisioning.Transport.Amqp | NuGet [1.14.0-preview-001](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Transport.Amqp/1.14.0-preview-001) | | | -| Microsoft.Azure.Devices.Provisioning.Transport.Http | NuGet [1.13.0-preview-001](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Transport.Http/1.13.0-preview-001) | | | -| Microsoft.Azure.Devices.Provisioning.Transport.Mqtt | NuGet [1.14.0](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Transport.Mqtt/1.14.0)
NuGet [1.14.0-preview-001](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Transport.Mqtt/1.14.0-preview-001) | | | -| Microsoft.Azure.Devices.Shared | NuGet [1.27.0](https://www.nuget.org/packages/Microsoft.Azure.Devices.Shared/1.27.0) | | | -| Microsoft.Azure.Functions.Worker | NuGet [1.0.0-preview3](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker/1.0.0-preview3) | | | -| Microsoft.Azure.Functions.Worker.Sdk | NuGet [1.0.0-preview3](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Sdk/1.0.0-preview3) | | | +| Microsoft.Azure.Devices.Provisioning.Client | NuGet [1.17.1](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Client/1.17.1) | | | +| Microsoft.Azure.Devices.Provisioning.Security.Tpm | NuGet [1.13.1](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Security.Tpm/1.13.1) | | | +| Microsoft.Azure.Devices.Provisioning.Service | NuGet [1.17.1](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Service/1.17.1) | | | +| Microsoft.Azure.Devices.Provisioning.Transport.Amqp | NuGet [1.14.1](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Transport.Amqp/1.14.1) | | | +| Microsoft.Azure.Devices.Provisioning.Transport.Http | NuGet [1.13.1](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Transport.Http/1.13.1) | | | +| Microsoft.Azure.Devices.Provisioning.Transport.Mqtt | NuGet [1.15.1](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Transport.Mqtt/1.15.1) | | | +| Microsoft.Azure.Devices.Shared | NuGet [1.28.1](https://www.nuget.org/packages/Microsoft.Azure.Devices.Shared/1.28.1) | | | +| Microsoft.Azure.Functions.Worker | NuGet [1.2.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker/1.2.0) | | | +| Microsoft.Azure.Functions.Worker.Sdk | NuGet [1.0.3](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Sdk/1.0.3) | | | | Microsoft.Azure.uamqp | NuGet [1.2.11](https://www.nuget.org/packages/Microsoft.Azure.uamqp/1.2.11) | | | | Microsoft.Azure.umqtt | NuGet [1.1.11](https://www.nuget.org/packages/Microsoft.Azure.umqtt/1.1.11) | | | | Mobile Apps | NuGet [2.0.3](https://www.nuget.org/packages/Microsoft.Azure.Mobile.Server/2.0.3) | | | | Mobile Server - Cross Domain | NuGet [2.0.3](https://www.nuget.org/packages/Microsoft.Azure.Mobile.Server.CrossDomain/2.0.3) | | | | Mobile Service - Resource Broker | NuGet [1.0.2.1](https://www.nuget.org/packages/Microsoft.WindowsAzure.Mobile.Service.ResourceBroker/1.0.2.1) | | | +| Monitor OpenTelemetry Exporter | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.Exporter-readme-pre) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.0.0-beta.2/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/) | | News Search | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.NewsSearch/2.0.0) | | | | Notification Hubs | NuGet [4.1.0](https://www.nuget.org/packages/Microsoft.Azure.NotificationHubs/4.1.0) | | GitHub [4.1.0](https://github.com/Azure/azure-notificationhubs-dotnet) | | Operational Insights | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.OperationalInsights/1.0.0) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/operationalinsights/Microsoft.Azure.OperationalInsights) | | Personalizer | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Personalizer/1.0.0) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Personalizer_1.0.0/sdk/cognitiveservices/Personalizer) | | Power BI | NuGet [3.20.1](https://www.nuget.org/packages/Microsoft.PowerBI.Api/3.20.1) | | GitHub [3.20.1](https://github.com/Microsoft/PowerBI-CSharp) | +| Purview Catalog | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Catalog/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Catalog-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Catalog_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Catalog/) | +| Purview Scanning | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Scanning/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Scanning-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Scanning_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Scanning/) | | QnA Maker | NuGet [2.0.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker/2.0.1)
NuGet [3.0.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker/3.0.0-preview.1) | | GitHub [2.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker_2.0.1/sdk/cognitiveservices/Knowledge.QnAMaker) | -| Relay | NuGet [2.0.1](https://www.nuget.org/packages/Microsoft.Azure.Relay/2.0.1) | [docs](/dotnet/api/overview/azure/service-bus-relay) | GitHub [2.0.1](https://github.com/Azure/azure-relay-dotnet/tree/2.0.1) | +| Relay | NuGet [2.0.15596](https://www.nuget.org/packages/Microsoft.Azure.Relay/2.0.15596) | [docs](/dotnet/api/overview/azure/service-bus-relay) | GitHub [2.0.15596](https://github.com/Azure/azure-relay-dotnet/tree/2.0.1) | | Search | NuGet [10.1.0](https://www.nuget.org/packages/Microsoft.Azure.Search/10.1.0) | | GitHub [10.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Search_10.1.0/sdk/search/Microsoft.Azure.Search/) | | Search - Common | NuGet [10.1.0](https://www.nuget.org/packages/Microsoft.Azure.Search.Common/10.1.0) | | GitHub [10.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Search.Common_10.1.0/sdk/search/Microsoft.Azure.Search.Common/) | | Search - Data | NuGet [10.1.0](https://www.nuget.org/packages/Microsoft.Azure.Search.Data/10.1.0) | | GitHub [10.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Search.Data_10.1.0/sdk/search/Microsoft.Azure.Search.Data/) | | Search - Service | NuGet [10.1.0](https://www.nuget.org/packages/Microsoft.Azure.Search.Service/10.1.0) | | GitHub [10.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Search.Service_10.1.0/sdk/search/Microsoft.Azure.Search.Service/) | -| Service Bus | NuGet [7.1.0](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/7.1.0) | [docs](/dotnet/api/overview/azure/Messaging.ServiceBus-readme/) | GitHub [7.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.ServiceBus_7.1.0/sdk/servicebus/Azure.Messaging.ServiceBus/) | -| Service Bus | NuGet [5.1.1](https://www.nuget.org/packages/Microsoft.Azure.ServiceBus/5.1.1) | | GitHub [5.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.ServiceBus_5.1.1/sdk/servicebus/Microsoft.Azure.ServiceBus/) | +| Service Bus | NuGet [7.1.2](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/7.1.2)
NuGet [7.2.0-beta.3](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/7.2.0-beta.3) | [docs](/dotnet/api/overview/azure/Messaging.ServiceBus-readme) | GitHub [7.1.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.ServiceBus_7.1.2/sdk/servicebus/Azure.Messaging.ServiceBus/)
GitHub [7.2.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.ServiceBus_7.2.0-beta.3/sdk/servicebus/Azure.Messaging.ServiceBus/) | +| Service Bus | NuGet [5.1.3](https://www.nuget.org/packages/Microsoft.Azure.ServiceBus/5.1.3) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.ServiceBus-readme) | GitHub [5.1.3](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.ServiceBus_5.1.3/sdk/servicebus/Microsoft.Azure.ServiceBus/) | | Service Bus - Message ID plugin | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.ServiceBus.MessageIdPlugin/2.0.0) | | | -| SignalR | NuGet [1.7.1](https://www.nuget.org/packages/Microsoft.Azure.SignalR/1.7.1) | | GitHub [1.7.1](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR) | -| SignalR - ASP.NET | NuGet [1.7.1](https://www.nuget.org/packages/Microsoft.Azure.SignalR.AspNet/1.7.1) | | GitHub [1.7.1](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR.AspNet) | +| SignalR | NuGet [1.8.1](https://www.nuget.org/packages/Microsoft.Azure.SignalR/1.8.1) | | GitHub [1.8.1](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR) | +| SignalR - ASP.NET | NuGet [1.8.1](https://www.nuget.org/packages/Microsoft.Azure.SignalR.AspNet/1.8.1) | | GitHub [1.8.1](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR.AspNet) | | SignalR - Benchmark | NuGet [1.0.0-preview1-10415](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Benchmark/1.0.0-preview1-10415) | | GitHub [1.0.0-preview1-10415](https://github.com/azure/azure-signalr-bench) | -| SignalR - Protocols | NuGet [1.7.1](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Protocols/1.7.1) | | GitHub [1.7.1](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR.Protocols) | -| SignalR - Serverless Protocols | NuGet [1.2.2](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Serverless.Protocols/1.2.2) | | GitHub [1.2.2](https://github.com/Azure/azure-functions-signalrservice-extension/tree/v1.2.0/src/Microsoft.Azure.SignalR.Serverless.Protocols) | -| Speech | NuGet [1.15.0](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech/1.15.0) | | | -| Speech Remoteconversation | NuGet [1.15.0](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech.Remoteconversation/1.15.0) | | | -| Speech Xamarin iOS | NuGet [1.15.0](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech.Xamarin.iOS/1.15.0) | | | +| SignalR - Protocols | NuGet [1.8.1](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Protocols/1.8.1) | | GitHub [1.8.1](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR.Protocols) | +| SignalR - Serverless Protocols | NuGet [1.4.1](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Serverless.Protocols/1.4.1) | | GitHub [1.4.1](https://github.com/Azure/azure-functions-signalrservice-extension/tree/v1.2.0/src/Microsoft.Azure.SignalR.Serverless.Protocols) | +| Speech | NuGet [1.17.0](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech/1.17.0) | | | +| Speech Remoteconversation | NuGet [1.17.0](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech.Remoteconversation/1.17.0) | | | +| Speech Xamarin iOS | NuGet [1.17.0](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech.Xamarin.iOS/1.17.0) | | | | Spell Check | NuGet [4.1.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Language.SpellCheck/4.1.0-preview.1) | | GitHub [4.1.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Language.SpellCheck_4.1.0-preview.1/sdk/cognitiveservices/Language.SpellCheck) | | Spring Cloud Client | NuGet [2.0.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.SpringCloud.Client/2.0.0-preview.1) | | | | SQL Database Elastic Scale Client | NuGet [2.3.0](https://www.nuget.org/packages/Microsoft.Azure.SqlDatabase.ElasticScale.Client/2.3.0) | | GitHub [2.3.0](https://github.com/Azure/elastic-db-tools/tree/v2.3.0/Src/ElasticScale.Client) | | SQL Database Elastic Scale Service SplitMerge | NuGet [1.2.0](https://www.nuget.org/packages/Microsoft.Azure.SqlDatabase.ElasticScale.Service.SplitMerge/1.2.0) | | | | SQL Database Jobs | NuGet [0.8.3362.1](https://www.nuget.org/packages/Microsoft.Azure.SqlDatabase.Jobs/0.8.3362.1) | | | -| Storage - Blobs | NuGet [12.8.0](https://www.nuget.org/packages/Azure.Storage.Blobs/12.8.0)
NuGet [12.9.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs/12.9.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme/) | GitHub [12.8.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.8.0/sdk/storage/Azure.Storage.Blobs/)
GitHub [12.9.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.9.0-beta.1/sdk/storage/Azure.Storage.Blobs/) | -| Storage - Blobs | NuGet [11.2.2](https://www.nuget.org/packages/Microsoft.Azure.Storage.Blob/11.2.2) | | GitHub [11.2.2](https://github.com/Azure/azure-storage-net/tree/master/Blob) | -| Storage - Blobs Batch | NuGet [12.5.0](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.5.0)
NuGet [12.6.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.6.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme/) | GitHub [12.5.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.5.0/sdk/storage/Azure.Storage.Blobs.Batch/)
GitHub [12.6.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.6.0-beta.1/sdk/storage/Azure.Storage.Blobs.Batch/) | -| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.9](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.9) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme-pre/) | GitHub [12.0.0-preview.9](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.9/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | -| Storage - Common | NuGet [12.7.0](https://www.nuget.org/packages/Azure.Storage.Common/12.7.0)
NuGet [12.8.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Common/12.8.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Common-readme/) | GitHub [12.7.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.7.0/sdk/storage/Azure.Storage.Common/)
GitHub [12.8.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.8.0-beta.1/sdk/storage/Azure.Storage.Common/) | -| Storage - Data Movement | NuGet [2.0.1](https://www.nuget.org/packages/Microsoft.Azure.Storage.DataMovement/2.0.1) | | GitHub [2.0.1](https://github.com/Azure/azure-storage-net-data-movement/tree/v1.3.0) | -| Storage - Files Data Lake | NuGet [12.6.0](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.6.0)
NuGet [12.7.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.7.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme/) | GitHub [12.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.6.0/sdk/storage/Azure.Storage.Files.DataLake/)
GitHub [12.7.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.7.0-beta.1/sdk/storage/Azure.Storage.Files.DataLake/) | -| Storage - Files Shares | NuGet [12.6.0](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.6.0)
NuGet [12.7.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.7.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme/) | GitHub [12.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.6.0/sdk/storage/Azure.Storage.Files.Shares/)
GitHub [12.7.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.7.0-beta.1/sdk/storage/Azure.Storage.Files.Shares/) | -| Storage - Files Shares | NuGet [11.2.2](https://www.nuget.org/packages/Microsoft.Azure.Storage.File/11.2.2) | | GitHub [11.2.2](https://github.com/Azure/azure-storage-net/tree/master/File) | -| Storage - Queues | NuGet [12.6.0](https://www.nuget.org/packages/Azure.Storage.Queues/12.6.0)
NuGet [12.7.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Queues/12.7.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme/) | GitHub [12.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.6.0/sdk/storage/Azure.Storage.Queues/)
GitHub [12.7.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.7.0-beta.1/sdk/storage/Azure.Storage.Queues/) | -| Storage - Queues | NuGet [11.2.2](https://www.nuget.org/packages/Microsoft.Azure.Storage.Queue/11.2.2) | | GitHub [11.2.2](https://github.com/Azure/azure-storage-net/tree/master/Queue) | +| Storage - Blobs | NuGet [12.8.4](https://www.nuget.org/packages/Azure.Storage.Blobs/12.8.4)
NuGet [12.9.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Blobs/12.9.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme) | GitHub [12.8.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.8.4/sdk/storage/Azure.Storage.Blobs/)
GitHub [12.9.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.9.0-beta.4/sdk/storage/Azure.Storage.Blobs/) | +| Storage - Blobs | NuGet [11.2.3](https://www.nuget.org/packages/Microsoft.Azure.Storage.Blob/11.2.3) | | GitHub [11.2.3](https://github.com/Azure/azure-storage-net/tree/master/Blob) | +| Storage - Blobs Batch | NuGet [12.5.2](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.5.2)
NuGet [12.6.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.6.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme) | GitHub [12.5.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.5.2/sdk/storage/Azure.Storage.Blobs.Batch/)
GitHub [12.6.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.6.0-beta.4/sdk/storage/Azure.Storage.Blobs.Batch/) | +| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.12](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.12) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme-pre) | GitHub [12.0.0-preview.12](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.12/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | +| Storage - Common | NuGet [12.7.3](https://www.nuget.org/packages/Azure.Storage.Common/12.7.3)
NuGet [12.8.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Common/12.8.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Common-readme) | GitHub [12.7.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.7.3/sdk/storage/Azure.Storage.Common/)
GitHub [12.8.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.8.0-beta.4/sdk/storage/Azure.Storage.Common/) | +| Storage - Data Movement | NuGet [2.0.4](https://www.nuget.org/packages/Microsoft.Azure.Storage.DataMovement/2.0.4) | | GitHub [2.0.4](https://github.com/Azure/azure-storage-net-data-movement/tree/v1.3.0) | +| Storage - Files Data Lake | NuGet [12.6.2](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.6.2)
NuGet [12.7.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.7.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme) | GitHub [12.6.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.6.2/sdk/storage/Azure.Storage.Files.DataLake/)
GitHub [12.7.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.7.0-beta.4/sdk/storage/Azure.Storage.Files.DataLake/) | +| Storage - Files Shares | NuGet [12.6.2](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.6.2)
NuGet [12.7.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.7.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme) | GitHub [12.6.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.6.2/sdk/storage/Azure.Storage.Files.Shares/)
GitHub [12.7.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.7.0-beta.4/sdk/storage/Azure.Storage.Files.Shares/) | +| Storage - Files Shares | NuGet [11.2.3](https://www.nuget.org/packages/Microsoft.Azure.Storage.File/11.2.3) | | GitHub [11.2.3](https://github.com/Azure/azure-storage-net/tree/master/File) | +| Storage - Queues | NuGet [12.6.2](https://www.nuget.org/packages/Azure.Storage.Queues/12.6.2)
NuGet [12.7.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Queues/12.7.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme) | GitHub [12.6.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.6.2/sdk/storage/Azure.Storage.Queues/)
GitHub [12.7.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.7.0-beta.4/sdk/storage/Azure.Storage.Queues/) | +| Storage - Queues | NuGet [11.2.3](https://www.nuget.org/packages/Microsoft.Azure.Storage.Queue/11.2.3) | | GitHub [11.2.3](https://github.com/Azure/azure-storage-net/tree/master/Queue) | | Synapse | NuGet [0.1.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Synapse/0.1.0-preview) | | GitHub [0.1.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Synapse_0.1.0-preview/sdk/synapse/Microsoft.Azure.Synapse/) | -| Synapse - AccessControl | NuGet [1.0.0-preview.3](https://www.nuget.org/packages/Azure.Analytics.Synapse.AccessControl/1.0.0-preview.3) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.AccessControl-readme-pre/) | GitHub [1.0.0-preview.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.AccessControl_1.0.0-preview.3/sdk/synapse/Azure.Analytics.Synapse.AccessControl/) | -| Synapse - Artifacts | NuGet [1.0.0-preview.6](https://www.nuget.org/packages/Azure.Analytics.Synapse.Artifacts/1.0.0-preview.6) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Artifacts-readme-pre/) | GitHub [1.0.0-preview.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Artifacts_1.0.0-preview.6/sdk/synapse/Azure.Analytics.Synapse.Artifacts/) | -| Synapse - Managed Private Endpoints | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Analytics.Synapse.ManagedPrivateEndpoints/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.ManagedPrivateEndpoints-readme-pre/) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.ManagedPrivateEndpoints_1.0.0-beta.2/sdk/synapse/Azure.Analytics.Synapse.ManagedPrivateEndpoints/) | -| Synapse - Monitoring | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Analytics.Synapse.Monitoring/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Monitoring-readme-pre/) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Monitoring_1.0.0-beta.2/sdk/synapse/Azure.Analytics.Synapse.Monitoring/) | -| Synapse - Spark | NuGet [1.0.0-preview.4](https://www.nuget.org/packages/Azure.Analytics.Synapse.Spark/1.0.0-preview.4) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Spark-readme-pre/) | GitHub [1.0.0-preview.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Spark_1.0.0-preview.4/sdk/synapse/Azure.Analytics.Synapse.Spark/) | -| System Memory Data | NuGet [1.0.1](https://www.nuget.org/packages/System.Memory.Data/1.0.1) | [docs](/dotnet/api/overview/azure/System.Memory.Data-readme/) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/System.Memory.Data_1.0.1/sdk/core/System.Memory.Data/) | -| Tables | NuGet [3.0.0-beta.5](https://www.nuget.org/packages/Azure.Data.Tables/3.0.0-beta.5) | [docs](/dotnet/api/overview/azure/Data.Tables-readme-pre/) | GitHub [3.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.Tables_3.0.0-beta.5/sdk/tables/Azure.Data.Tables/) | +| Synapse - AccessControl | NuGet [1.0.0-preview.4](https://www.nuget.org/packages/Azure.Analytics.Synapse.AccessControl/1.0.0-preview.4) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.AccessControl-readme-pre) | GitHub [1.0.0-preview.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.AccessControl_1.0.0-preview.4/sdk/synapse/Azure.Analytics.Synapse.AccessControl/) | +| Synapse - Artifacts | NuGet [1.0.0-preview.10](https://www.nuget.org/packages/Azure.Analytics.Synapse.Artifacts/1.0.0-preview.10) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Artifacts-readme-pre) | GitHub [1.0.0-preview.10](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Artifacts_1.0.0-preview.10/sdk/synapse/Azure.Analytics.Synapse.Artifacts/) | +| Synapse - Managed Private Endpoints | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Analytics.Synapse.ManagedPrivateEndpoints/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.ManagedPrivateEndpoints-readme-pre) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.ManagedPrivateEndpoints_1.0.0-beta.3/sdk/synapse/Azure.Analytics.Synapse.ManagedPrivateEndpoints/) | +| Synapse - Monitoring | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Analytics.Synapse.Monitoring/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Monitoring-readme-pre) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Monitoring_1.0.0-beta.3/sdk/synapse/Azure.Analytics.Synapse.Monitoring/) | +| Synapse - Spark | NuGet [1.0.0-preview.6](https://www.nuget.org/packages/Azure.Analytics.Synapse.Spark/1.0.0-preview.6) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Spark-readme-pre) | GitHub [1.0.0-preview.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Spark_1.0.0-preview.6/sdk/synapse/Azure.Analytics.Synapse.Spark/) | +| System Memory Data | NuGet [1.0.2](https://www.nuget.org/packages/System.Memory.Data/1.0.2) | [docs](/dotnet/api/overview/azure/System.Memory.Data-readme) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/System.Memory.Data_1.0.2/sdk/core/System.Memory.Data/) | +| Tables | NuGet [12.0.0-beta.8](https://www.nuget.org/packages/Azure.Data.Tables/12.0.0-beta.8) | [docs](/dotnet/api/overview/azure/Data.Tables-readme-pre) | GitHub [12.0.0-beta.8](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.Tables_12.0.0-beta.8/sdk/tables/Azure.Data.Tables/) | | Tables | NuGet [2.0.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Table/2.0.0-preview) | | | | Tables | NuGet [2.1.2](https://www.nuget.org/packages/Microsoft.Azure.CosmosDB.Table/2.1.2) | | | | Template | NuGet [1.0.2-preview1](https://www.nuget.org/packages/Microsoft.Azure.Template/1.0.2-preview1) | | | | Test HttpRecorder | NuGet [1.13.3](https://www.nuget.org/packages/Microsoft.Azure.Test.HttpRecorder/1.13.3) | | GitHub [1.13.3](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/mgmtcommon/TestFramework/Microsoft.Azure.Test.HttpRecorder) | -| Text Analytics | NuGet [5.0.0](https://www.nuget.org/packages/Azure.AI.TextAnalytics/5.0.0)
NuGet [5.1.0-beta.4](https://www.nuget.org/packages/Azure.AI.TextAnalytics/5.1.0-beta.4) | [docs](/dotnet/api/overview/azure/AI.TextAnalytics-readme/) | GitHub [5.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.TextAnalytics_5.0.0/sdk/textanalytics/Azure.AI.TextAnalytics/)
GitHub [5.1.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.TextAnalytics_5.1.0-beta.4/sdk/textanalytics/Azure.AI.TextAnalytics/) | +| Text Analytics | NuGet [5.0.0](https://www.nuget.org/packages/Azure.AI.TextAnalytics/5.0.0)
NuGet [5.1.0-beta.7](https://www.nuget.org/packages/Azure.AI.TextAnalytics/5.1.0-beta.7) | [docs](/dotnet/api/overview/azure/AI.TextAnalytics-readme) | GitHub [5.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.TextAnalytics_5.0.0/sdk/textanalytics/Azure.AI.TextAnalytics/)
GitHub [5.1.0-beta.7](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.TextAnalytics_5.1.0-beta.7/sdk/textanalytics/Azure.AI.TextAnalytics/) | | Text Analytics | NuGet [4.1.0-preview.2](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Language.TextAnalytics/4.1.0-preview.2) | | GitHub [4.1.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Language.TextAnalytics_4.1.0-preview.2/sdk/cognitiveservices/Language.TextAnalytics) | | Video Search | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.VideoSearch/2.0.0) | | | | Vision Content Moderator | NuGet [2.1.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.ContentModerator/2.1.0-preview.1) | | GitHub [2.1.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.ContentModerator_2.1.0-preview.1/sdk/cognitiveservices/Vision.ContentModerator) | | Visual Search | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.VisualSearch/2.0.0) | | | | Wastorage | NuGet [4.0.0](https://www.nuget.org/packages/wastorage/4.0.0) | | | | Wastorage - Redist | NuGet [2.0.0](https://www.nuget.org/packages/wastorage.redist/2.0.0) | | | -| Wastorage - Symbols | NuGet [2.0.0](https://www.nuget.org/packages/wastorage.symbols/2.0.0) | | | -| Wastorage V120 | NuGet [4.0.0](https://www.nuget.org/packages/wastorage.v120/4.0.0) | | | -| Wastorage V140 | NuGet [4.0.0](https://www.nuget.org/packages/wastorage.v140/4.0.0) | | | | Web - Redis Output Cache Provider | NuGet [3.0.1](https://www.nuget.org/packages/Microsoft.Web.RedisOutputCacheProvider/3.0.1) | | GitHub [3.0.1](https://github.com/Azure/aspnet-redis-providers/tree/NuGet-Release/RedisOutputCacheProvider-3.0.1/src/OutputCacheProvider) | | Web - Redis Session State Provider | NuGet [4.0.1](https://www.nuget.org/packages/Microsoft.Web.RedisSessionStateProvider/4.0.1) | | GitHub [4.0.1](https://github.com/Azure/aspnet-redis-providers/tree/NuGet-Release/RedisSessionStateProvider-4.0.1/src/RedisSessionStateProvider) | | Web Search | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.WebSearch/2.0.0) | | | -| WebJobs | NuGet [3.0.25](https://www.nuget.org/packages/Microsoft.Azure.WebJobs/3.0.25) | | GitHub [3.0.25](https://github.com/Azure/azure-webjobs-sdk/tree/v3.0.18/src/Microsoft.Azure.WebJobs) | -| WebJobs - Core | NuGet [3.0.25](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Core/3.0.25) | | GitHub [3.0.25](https://github.com/Azure/azure-webjobs-sdk/tree/v3.0.18) | +| WebJobs | NuGet [3.0.27](https://www.nuget.org/packages/Microsoft.Azure.WebJobs/3.0.27) | | GitHub [3.0.27](https://github.com/Azure/azure-webjobs-sdk/tree/v3.0.18/src/Microsoft.Azure.WebJobs) | +| WebJobs - Core | NuGet [3.0.27](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Core/3.0.27) | | GitHub [3.0.27](https://github.com/Azure/azure-webjobs-sdk/tree/v3.0.18) | | WebJobs - Host Storage | NuGet [4.0.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Host.Storage/4.0.1) | | GitHub [4.0.1](https://github.com/Azure/azure-webjobs-sdk/tree/storage-v4.0.1/src/Microsoft.Azure.WebJobs.Host.Storage) | -| WebJobs - Host Test Common | NuGet [3.0.25](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Host.TestCommon/3.0.25) | | GitHub [3.0.25](https://github.com/Azure/azure-webjobs-sdk) | -| WebJobs - Item Templates | NuGet [3.1.1648](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.ItemTemplates/3.1.1648) | | GitHub [3.1.1648](https://github.com/Azure/azure-functions-templates/tree/3.1.1582) | -| WebJobs - Logging | NuGet [4.0.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Logging/4.0.1) | | GitHub [4.0.1](https://github.com/Azure/azure-webjobs-sdk/tree/dev/src/Microsoft.Azure.WebJobs.Logging) | -| WebJobs - Logging Application Insights | NuGet [3.0.25](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Logging.ApplicationInsights/3.0.25) | | GitHub [3.0.25](https://github.com/Azure/azure-webjobs-sdk/tree/v3.0.18/src/Microsoft.Azure.WebJobs.Logging.ApplicationInsights) | -| WebJobs - Project Templates | NuGet [3.1.1648](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.ProjectTemplates/3.1.1648) | | GitHub [3.1.1648](https://github.com/Azure/azure-functions-templates/tree/3.1.1582) | +| WebJobs - Host Test Common | NuGet [3.0.27](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Host.TestCommon/3.0.27) | | GitHub [3.0.27](https://github.com/Azure/azure-webjobs-sdk) | +| WebJobs - Item Templates | NuGet [3.1.1809](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.ItemTemplates/3.1.1809) | | GitHub [3.1.1809](https://github.com/Azure/azure-functions-templates/tree/3.1.1582) | +| WebJobs - Logging | NuGet [4.0.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Logging/4.0.2) | | GitHub [4.0.2](https://github.com/Azure/azure-webjobs-sdk/tree/dev/src/Microsoft.Azure.WebJobs.Logging) | +| WebJobs - Logging Application Insights | NuGet [3.0.27](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Logging.ApplicationInsights/3.0.27) | | GitHub [3.0.27](https://github.com/Azure/azure-webjobs-sdk/tree/v3.0.18/src/Microsoft.Azure.WebJobs.Logging.ApplicationInsights) | +| WebJobs - Project Templates | NuGet [3.1.1809](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.ProjectTemplates/3.1.1809) | | GitHub [3.1.1809](https://github.com/Azure/azure-functions-templates/tree/3.1.1582) | | WebJobs - Scrip Web Host | NuGet [1.0.0-beta3](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Script.WebHost/1.0.0-beta3) | | GitHub [1.0.0-beta3](https://github.com/Azure/azure-functions-host/tree/dev/src/WebJobs.Script.WebHost) | | WebJobs - Script | NuGet [1.0.0-beta3](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Script/1.0.0-beta3) | | GitHub [1.0.0-beta3](https://github.com/Azure/azure-functions-host/tree/dev/src/WebJobs.Script) | | WebJobs - Script Abstractions | NuGet [1.0.0-preview](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Script.Abstractions/1.0.0-preview) | | | | WebJobs - Script Extensibility | NuGet [1.0.0-beta3](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Script.Extensibility/1.0.0-beta3) | | GitHub [1.0.0-beta3](https://github.com/Azure/azure-functions-host) | -| WebJobs - Script Extensions Metadata Generator | NuGet [1.2.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Script.ExtensionsMetadataGenerator/1.2.1) | | GitHub [1.2.1](https://github.com/Azure/azure-functions-host) | +| WebJobs - Script Extensions Metadata Generator | NuGet [1.2.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Script.ExtensionsMetadataGenerator/1.2.2) | | GitHub [1.2.2](https://github.com/Azure/azure-functions-host) | | WebJobs - Service Bus | NuGet [3.0.0-beta8](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.ServiceBus/3.0.0-beta8) | | GitHub [3.0.0-beta8](https://github.com/Azure/azure-webjobs-sdk/tree/v3.0.0-beta8/src/Microsoft.Azure.WebJobs.ServiceBus) | -| WebJobs - Sources | NuGet [3.0.25](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Sources/3.0.25) | | GitHub [3.0.25](https://github.com/Azure/azure-webjobs-sdk) | +| WebJobs - Sources | NuGet [3.0.27](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Sources/3.0.27) | | GitHub [3.0.27](https://github.com/Azure/azure-webjobs-sdk) | | WebJobs Extensions | NuGet [4.0.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions/4.0.1) | | GitHub [4.0.1](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/dev/src/WebJobs.Extensions) | | WebJobs Extensions - API Hub | NuGet [1.0.0-beta9](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.ApiHub/1.0.0-beta9) | | GitHub [1.0.0-beta9](https://github.com/Azure/azure-webjobs-sdk-extensions) | | WebJobs Extensions - Auth Tokens | NuGet [1.0.0-beta6](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthTokens/1.0.0-beta6) | | GitHub [1.0.0-beta6](https://github.com/Azure/azure-webjobs-sdk-extensions) | -| WebJobs Extensions - Cosmos DB | NuGet [3.0.9](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.CosmosDB/3.0.9) | | GitHub [3.0.9](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/cosmos-v3.0.7/src/WebJobs.Extensions.CosmosDB) | +| WebJobs Extensions - Cosmos DB | NuGet [3.0.10](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.CosmosDB/3.0.10) | | GitHub [3.0.10](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/cosmos-v3.0.7/src/WebJobs.Extensions.CosmosDB) | | WebJobs Extensions - Document DB | NuGet [1.3.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.DocumentDB/1.3.0) | | GitHub [1.3.0](https://github.com/Azure/azure-webjobs-sdk-extensions) | -| WebJobs Extensions - Durable Task | NuGet [2.4.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.DurableTask/2.4.1) | [docs](/dotnet/api/overview/azure/functions) | GitHub [2.4.1](https://github.com/Azure/azure-functions-durable-extension/tree/v2.2.2/src/WebJobs.Extensions.DurableTask) | +| WebJobs Extensions - Durable Task | NuGet [2.4.3](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.DurableTask/2.4.3) | [docs](/dotnet/api/overview/azure/functions) | GitHub [2.4.3](https://github.com/Azure/azure-functions-durable-extension/tree/v2.2.2/src/WebJobs.Extensions.DurableTask) | | WebJobs Extensions - Durable Task Analyzers | NuGet [0.4.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.DurableTask.Analyzers/0.4.0) | | GitHub [0.4.0](https://github.com/Azure/azure-functions-durable-extension/tree/Analyzer-v0.3.0/src/WebJobs.Extensions.DurableTask.Analyzers) | | WebJobs Extensions - Edge Hub | NuGet [1.0.7](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EdgeHub/1.0.7) | | GitHub [1.0.7](https://github.com/Azure/iotedge/tree/1.0.7/edge-hub) | -| WebJobs Extensions - Event Grid | NuGet [2.1.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventGrid/2.1.0) | | GitHub [2.1.0](https://github.com/Azure/azure-functions-eventgrid-extension/tree/v2.1.0/src/EventGridExtension) | -| WebJobs Extensions - Event Hubs | NuGet [4.2.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventHubs/4.2.0)
NuGet [5.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventHubs/5.0.0-beta.1) | | GitHub [4.2.0](https://github.com/Azure/azure-webjobs-sdk-extensions) | +| WebJobs Extensions - Event Grid | NuGet [2.1.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventGrid/2.1.0)
NuGet [3.0.0-beta.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventGrid/3.0.0-beta.2) | | GitHub [2.1.0](https://github.com/Azure/azure-functions-eventgrid-extension/tree/v2.1.0/src/EventGridExtension) | +| WebJobs Extensions - Event Hubs | NuGet [4.2.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventHubs/4.2.0)
NuGet [5.0.0-beta.5](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventHubs/5.0.0-beta.5) | | GitHub [4.2.0](https://github.com/Azure/azure-webjobs-sdk-extensions) | | WebJobs Extensions - Http | NuGet [3.0.12](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Http/3.0.12) | | GitHub [3.0.12](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/v3.0.2/src/WebJobs.Extensions.Http) | -| WebJobs Extensions - Kafka | NuGet [3.2.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Kafka/3.2.1)
NuGet [3.3.1-PRE2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Kafka/3.3.1-PRE2) | | GitHub [3.2.1](https://github.com/Azure/azure-functions-kafka-extension/tree/3.0.0/src/Microsoft.Azure.WebJobs.Extensions.Kafka) | +| WebJobs Extensions - Kafka | NuGet [3.3.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Kafka/3.3.2) | | GitHub [3.3.2](https://github.com/Azure/azure-functions-kafka-extension/tree/3.0.0/src/Microsoft.Azure.WebJobs.Extensions.Kafka) | | WebJobs Extensions - Microsoft Graph | NuGet [1.0.0-beta6](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.MicrosoftGraph/1.0.0-beta6) | | GitHub [1.0.0-beta6](https://github.com/Azure/azure-functions-microsoftgraph-extension) | | WebJobs Extensions - Mobile Apps | NuGet [3.0.0-beta8](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.MobileApps/3.0.0-beta8) | | GitHub [3.0.0-beta8](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/v3.0.0-beta8/src/WebJobs.Extensions.MobileApps) | | WebJobs Extensions - Notification Hubs | NuGet [1.3.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.NotificationHubs/1.3.0) | | GitHub [1.3.0](https://github.com/Azure/azure-webjobs-sdk-extensions) | -| WebJobs Extensions - OpenAPI | NuGet [0.4.0-preview](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi/0.4.0-preview) | | | -| WebJobs Extensions - OpenAPI Configuration AppSettings | NuGet [0.4.0-preview](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi.Configuration.AppSettings/0.4.0-preview) | | | -| WebJobs Extensions - OpenAPI Core | NuGet [0.4.0-preview](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi.Core/0.4.0-preview) | | | -| WebJobs Extensions - RabbitMQ | NuGet [1.0.0-beta](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.RabbitMQ/1.0.0-beta) | | GitHub [1.0.0-beta](https://github.com/Azure/azure-functions-rabbitmq-extension/tree/v0.2.2029-beta) | +| WebJobs Extensions - OpenAPI | NuGet [0.7.2-preview](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi/0.7.2-preview) | | | +| WebJobs Extensions - OpenAPI Configuration AppSettings | NuGet [0.7.2-preview](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi.Configuration.AppSettings/0.7.2-preview) | | | +| WebJobs Extensions - OpenAPI Core | NuGet [0.7.2-preview](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.OpenApi.Core/0.7.2-preview) | | | +| WebJobs Extensions - RabbitMQ | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.RabbitMQ/1.0.0)
NuGet [1.0.0-beta](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.RabbitMQ/1.0.0-beta) | | GitHub [1.0.0](https://github.com/Azure/azure-functions-rabbitmq-extension/tree/v0.2.2029-beta) | | WebJobs Extensions - SendGrid | NuGet [3.0.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.SendGrid/3.0.2) | | GitHub [3.0.2](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/v3.0.0/src/WebJobs.Extensions.SendGrid) | -| WebJobs Extensions - Service Bus | NuGet [4.2.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.ServiceBus/4.2.1) | | GitHub [4.2.1](https://github.com/Azure/azure-functions-servicebus-extension/tree/v4.1.2) | -| WebJobs Extensions - SignalR Service | NuGet [1.2.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.SignalRService/1.2.2) | | GitHub [1.2.2](https://github.com/Azure/azure-functions-signalrservice-extension/tree/v1.2.0/src/SignalRServiceExtension) | -| WebJobs Extensions - Storage | NuGet [4.0.3](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage/4.0.3)
NuGet [5.0.0-beta.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage/5.0.0-beta.2) | | GitHub [4.0.3](https://github.com/Azure/azure-webjobs-sdk/tree/master/src/Microsoft.Azure.WebJobs.Extensions.Storage) | -| WebJobs Extensions - Storage Blobs | NuGet [5.0.0-beta.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs/5.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Microsoft.WebJobs.Extensions.Storage.Blobs-readme-pre/) | | -| WebJobs Extensions - Storage Queues | NuGet [5.0.0-beta.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage.Queues/5.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Microsoft.WebJobs.Extensions.Storage.Queues-readme-pre/) | | +| WebJobs Extensions - Service Bus | NuGet [4.2.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.ServiceBus/4.2.1)
NuGet [5.0.0-beta.3](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.ServiceBus/5.0.0-beta.3) | | GitHub [4.2.1](https://github.com/Azure/azure-functions-servicebus-extension/tree/v4.1.2) | +| WebJobs Extensions - SignalR Service | NuGet [1.4.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.SignalRService/1.4.1) | | GitHub [1.4.1](https://github.com/Azure/azure-functions-signalrservice-extension/tree/v1.2.0/src/SignalRServiceExtension) | +| WebJobs Extensions - Storage | NuGet [4.0.3](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage/4.0.3)
NuGet [5.0.0-beta.4](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage/5.0.0-beta.4) | | GitHub [4.0.3](https://github.com/Azure/azure-webjobs-sdk/tree/master/src/Microsoft.Azure.WebJobs.Extensions.Storage) | +| WebJobs Extensions - Storage Blobs | NuGet [5.0.0-beta.4](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs/5.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs-readme-pre) | | +| WebJobs Extensions - Storage Queues | NuGet [5.0.0-beta.4](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage.Queues/5.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage.Queues-readme-pre) | | | WebJobs Extensions - Twilio | NuGet [3.0.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Twilio/3.0.2) | | GitHub [3.0.2](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/v3.0.0/src/WebJobs.Extensions.Twilio) | | WebJobs Extensions - WebHooks | NuGet [1.0.0-beta4](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.WebHooks/1.0.0-beta4) | | GitHub [1.0.0-beta4](https://github.com/Azure/azure-webjobs-sdk-extensions) | | WebSites - DataProtection | NuGet [0.1.78-alpha](https://www.nuget.org/packages/Microsoft.Azure.WebSites.DataProtection/0.1.78-alpha) | | | -| WindowsAzure Caching | NuGet [2.9.5](https://www.nuget.org/packages/Microsoft.WindowsAzure.Caching/2.9.5) | | | -| WindowsAzure Caching - Memcache Shim | NuGet [2.9.5](https://www.nuget.org/packages/Microsoft.WindowsAzure.Caching.MemcacheShim/2.9.5) | | | | WindowsAzure Common | NuGet [1.4.1](https://www.nuget.org/packages/Microsoft.WindowsAzure.Common/1.4.1) | | | | WindowsAzure Common - Dependencies | NuGet [1.1.1](https://www.nuget.org/packages/Microsoft.WindowsAzure.Common.Dependencies/1.1.1) | | | | WindowsAzure Common - Tracing ETW | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.WindowsAzure.Common.Tracing.Etw/1.0.0) | | | @@ -330,7 +381,7 @@ | WindowsAzure Mobile Services - Backend Tables | NuGet [1.0.478](https://www.nuget.org/packages/WindowsAzure.MobileServices.Backend.Tables/1.0.478) | | | | WindowsAzure Mobile Services - SQLiteStore | NuGet [1.0.4](https://www.nuget.org/packages/WindowsAzure.MobileServices.SQLiteStore/1.0.4) | | | | WindowsAzure Mobile Services - WinJS | NuGet [2.0.0-beta](https://www.nuget.org/packages/WindowsAzure.MobileServices.WinJS/2.0.0-beta) | | | -| WindowsAzure Service Bus | NuGet [6.0.3](https://www.nuget.org/packages/WindowsAzure.ServiceBus/6.0.3) | | | +| WindowsAzure Service Bus | NuGet [6.1.1](https://www.nuget.org/packages/WindowsAzure.ServiceBus/6.1.1) | | | | WindowsAzure Storage | NuGet [9.3.3](https://www.nuget.org/packages/WindowsAzure.Storage/9.3.3) | | GitHub [9.3.3](https://github.com/Azure/azure-storage-net) | | WindowsAzure Storage - Premium Table | NuGet [0.1.0-preview](https://www.nuget.org/packages/WindowsAzure.Storage-PremiumTable/0.1.0-preview) | | GitHub [0.1.0-preview](https://github.com/Azure/azure-storage-net) | | WindowsAzure Storage - Preview | NuGet [3.2.0-preview](https://www.nuget.org/packages/WindowsAzure.Storage-Preview/3.2.0-preview) | | GitHub [3.2.0-preview](https://github.com/Azure/azure-storage-net) | @@ -356,65 +407,67 @@ | Management - Analysis Services Fluent | NuGet [1.9.1-beta](https://www.nuget.org/packages/Microsoft.Azure.Management.AnalysisServices.Fluent/1.9.1-beta) | | | | Management - API Management | NuGet [6.0.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.ApiManagement/6.0.0-preview) | | GitHub [6.0.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ApiManagement_6.0.0-preview/sdk/apimanagement/Microsoft.Azure.Management.ApiManagement/) | | Management - App Platform | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.AppPlatform/1.0.0) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.AppPlatform_1.0.0/sdk/appplatform/Microsoft.Azure.Management.AppPlatform/) | -| Management - App Service Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.AppService.Fluent/1.37.0) | [docs](/dotnet/api/overview/azure/appservice) | | +| Management - App Service Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.AppService.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/appservice) | | | Management - Application Insights | NuGet [0.3.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.ApplicationInsights/0.3.0-preview) | | GitHub [0.3.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ApplicationInsights_0.3.0-preview/sdk/applicationinsights/Microsoft.Azure.Management.ApplicationInsights/) | | Management - Attestation | NuGet [0.12.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Attestation/0.12.0-preview) | | GitHub [0.12.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Attestation_0.12.0-preview/sdk/attestation/Microsoft.Azure.Management.Attestation/) | | Management - Authorization | NuGet [2.12.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Authorization/2.12.0-preview) | | GitHub [2.12.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Authorization_2.12.0-preview/sdk/authorization/Microsoft.Azure.Management.Authorization/) | | Management - Automanage | NuGet [0.1.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Automanage/0.1.0-preview) | | | -| Management - Automation | NuGet [3.8.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Automation/3.8.1-preview) | [docs](/dotnet/api/overview/azure/automation) | GitHub [3.8.1-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/automation/Microsoft.Azure.Management.Automation) | +| Management - Automation | NuGet [3.8.3-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Automation/3.8.3-preview) | [docs](/dotnet/api/overview/azure/automation) | GitHub [3.8.3-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/automation/Microsoft.Azure.Management.Automation) | | Management - Azure Stack HCI | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.AzureStackHCI/1.0.0)
NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.Management.AzureStackHCI/1.0.0-preview.1) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.AzureStackHCI_1.0.0/sdk/azurestackhci/Microsoft.Azure.Management.AzureStackHCI/)
GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.AzureStackHCI_1.0.0-preview.1/sdk/azurestackhci/Microsoft.Azure.Management.AzureStackHCI/) | | Management - Azure VMware Solution | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Avs/1.0.0)
NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Avs/1.0.0-preview.1) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Avs_1.0.0/sdk/avs/Microsoft.Azure.Management.Avs/)
GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Avs_1.0.0-preview.1/sdk/avs/Microsoft.Azure.Management.Avs/) | | Management - Backup Services | NuGet [1.0.5-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.BackupServices/1.0.5-preview) | | | | Management - Batch | NuGet [13.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Batch/13.0.0) | [docs](/dotnet/api/overview/azure/batch) | GitHub [13.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Batch_13.0.0/sdk/batch/Microsoft.Azure.Management.Batch/) | | Management - Batch AI | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.BatchAI/2.0.0) | [docs](/dotnet/api/overview/azure/batchai) | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/batchai/Microsoft.Azure.Management.BatchAI) | -| Management - Batch AI Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.BatchAI.Fluent/1.37.0) | | | +| Management - Batch AI Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.BatchAI.Fluent/1.37.1) | | | | Management - Batch Fluent | NuGet [1.26.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Batch.Fluent/1.26.1) | | | | Management - Billing | NuGet [4.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Billing/4.1.0) | [docs](/dotnet/api/overview/azure/billing) | GitHub [4.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Billing_4.1.0/sdk/billing/Microsoft.Azure.Management.Billing/) | | Management - Billing Fluent | NuGet [1.9.1-beta](https://www.nuget.org/packages/Microsoft.Azure.Management.Billing.Fluent/1.9.1-beta) | | | | Management - Blueprint | NuGet [0.20.7-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Blueprint/0.20.7-preview) | | GitHub [0.20.7-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Blueprint_0.20.7-preview/sdk/blueprint/Microsoft.Azure.Management.Blueprint/) | | Management - Bot Service | NuGet [0.9.3-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.BotService/0.9.3-preview) | | GitHub [0.9.3-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/botservice/Microsoft.Azure.Management.BotService) | -| Management - Cognitive Services | NuGet [7.4.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.CognitiveServices/7.4.0-preview) | | GitHub [7.4.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.CognitiveServices_7.4.0-preview/sdk/cognitiveservices/Microsoft.Azure.Management.CognitiveServices/) | +| Management - Cognitive Services | NuGet [8.0.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.CognitiveServices/8.0.0-preview) | | GitHub [8.0.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.CognitiveServices_8.0.0-preview/sdk/cognitiveservices/Microsoft.Azure.Management.CognitiveServices/) | | Management - Cognitive Services Fluent | NuGet [1.9.1-beta](https://www.nuget.org/packages/Microsoft.Azure.Management.CognitiveServices.Fluent/1.9.1-beta) | | | +| Management - Compute | NuGet [46.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Compute/46.0.0) | | GitHub [46.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Compute_46.0.0/sdk/compute/Microsoft.Azure.Management.Compute/) | +| Management - Compute Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Compute.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/virtualmachines) | | | Management - Confluent | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Confluent/1.0.0) | | | | Management - Consumption | NuGet [3.0.2](https://www.nuget.org/packages/Microsoft.Azure.Management.Consumption/3.0.2) | | GitHub [3.0.2](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/consumption/Microsoft.Azure.Management.Consumption) | | Management - Consumption Fluent | NuGet [1.9.1-beta](https://www.nuget.org/packages/Microsoft.Azure.Management.Consumption.Fluent/1.9.1-beta) | | | | Management - Container Instances | NuGet [3.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerInstance/3.0.0) | | GitHub [3.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ContainerInstance_3.0.0/sdk/containerinstance/Microsoft.Azure.Management.ContainerInstance/) | -| Management - Container Instances Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerInstance.Fluent/1.37.0) | [docs](/dotnet/api/overview/azure/containerinstance) | | +| Management - Container Instances Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerInstance.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/containerinstance) | | | Management - Container Registry | NuGet [5.0.0-preview.5](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerRegistry/5.0.0-preview.5) | | GitHub [5.0.0-preview.5](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ContainerRegistry_5.0.0-preview.5/sdk/containerregistry/Microsoft.Azure.Management.ContainerRegistry/) | -| Management - Container Registry Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerRegistry.Fluent/1.37.0) | | | +| Management - Container Registry Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerRegistry.Fluent/1.37.1) | | | | Management - Container Service | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerService/1.1.0) | | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ContainerService_1.1.0/sdk/containerservice/Microsoft.Azure.Management.ContainerService/) | -| Management - Container Service Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerService.Fluent/1.37.0) | | | +| Management - Container Service Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerService.Fluent/1.37.1) | | | | Management - Content Delivery Network | NuGet [6.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Cdn/6.1.0) | | GitHub [6.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Cdn_6.1.0/sdk/cdn/Microsoft.Azure.Management.Cdn/) | -| Management - Content Delivery Network Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Cdn.Fluent/1.37.0) | [docs](/dotnet/api/overview/azure/cdn) | | -| Management - Cosmos DB | NuGet [1.2.0](https://www.nuget.org/packages/Microsoft.Azure.Management.CosmosDB/1.2.0)
NuGet [1.4.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.CosmosDB/1.4.1-preview) | | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.CosmosDB_1.2.0/sdk/cosmosdb/Microsoft.Azure.Management.CosmosDB/)
GitHub [1.4.1-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.CosmosDB_1.4.1-preview/sdk/cosmosdb/Microsoft.Azure.Management.CosmosDB/) | -| Management - Cosmos DB Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.CosmosDB.Fluent/1.37.0) | | | +| Management - Content Delivery Network Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Cdn.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/cdn) | | +| Management - Cosmos DB | NuGet [3.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.CosmosDB/3.0.0) | | GitHub [3.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.CosmosDB_3.0.0/sdk/cosmosdb/Microsoft.Azure.Management.CosmosDB/) | +| Management - Cosmos DB Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.CosmosDB.Fluent/1.37.1) | | | | Management - Customer Insights | NuGet [0.9.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.CustomerInsights/0.9.1-preview) | | GitHub [0.9.1-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/customer-insights/Microsoft.Azure.Management.CustomerInsights) | | Management - Customer Insights Fluent | NuGet [1.9.1-beta](https://www.nuget.org/packages/Microsoft.Azure.Management.CustomerInsights.Fluent/1.9.1-beta) | | | | Management - Data Box | NuGet [1.3.1](https://www.nuget.org/packages/Microsoft.Azure.Management.DataBox/1.3.1) | | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.DataBox_1.3.1/sdk/databox/Microsoft.Azure.Management.DataBox/) | | Management - Data Box Edge | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.DataBoxEdge/1.0.0) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.DataBoxEdge_1.0.0/sdk/databoxedge/Microsoft.Azure.Management.DataBoxEdge/) | | Management - Data Factories | NuGet [4.13.3](https://www.nuget.org/packages/Microsoft.Azure.Management.DataFactories/4.13.3) | [docs](/dotnet/api/overview/azure/data-factory) | | -| Management - Data Factory | NuGet [4.14.0](https://www.nuget.org/packages/Microsoft.Azure.Management.DataFactory/4.14.0) | [docs](/dotnet/api/overview/azure/data-factory) | GitHub [4.14.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.DataFactory_4.14.0/sdk/datafactory/Microsoft.Azure.Management.DataFactory/) | +| Management - Data Factory | NuGet [4.19.0](https://www.nuget.org/packages/Microsoft.Azure.Management.DataFactory/4.19.0) | [docs](/dotnet/api/overview/azure/data-factory) | GitHub [4.19.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.DataFactory_4.19.0/sdk/datafactory/Microsoft.Azure.Management.DataFactory/) | | Management - Data Lake Analytics | NuGet [3.5.3-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.DataLake.Analytics/3.5.3-preview) | [docs](/dotnet/api/overview/azure/data-lake-analytics) | GitHub [3.5.3-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/datalake-analytics/Microsoft.Azure.Management.DataLake.Analytics) | | Management - Data Lake Storage | NuGet [2.4.2-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.DataLake.Store/2.4.2-preview) | [docs](/dotnet/api/overview/azure/data-lake-store) | GitHub [2.4.2-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/datalake-store/Microsoft.Azure.Management.DataLake.Store) | | Management - Data Lake Storage Uploader | NuGet [1.0.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.DataLake.StoreUploader/1.0.1-preview) | | | -| Management - Data Migration | NuGet [0.10.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.DataMigration/0.10.0-preview) | | GitHub [0.10.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.DataMigration_0.10.0-preview/sdk/datamigration/Microsoft.Azure.Management.DataMigration/) | -| Management - Data Share | NuGet [1.0.1](https://www.nuget.org/packages/Microsoft.Azure.Management.DataShare/1.0.1) | [docs](/dotnet/api/overview/azure/datashare) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.DataShare_1.0.1/sdk/datashare/Microsoft.Azure.Management.DataShare/) | +| Management - Data Migration | NuGet [0.11.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.DataMigration/0.11.0-preview) | | GitHub [0.11.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.DataMigration_0.11.0-preview/sdk/datamigration/Microsoft.Azure.Management.DataMigration/) | +| Management - Data Share | NuGet [1.2.0](https://www.nuget.org/packages/Microsoft.Azure.Management.DataShare/1.2.0) | [docs](/dotnet/api/overview/azure/datashare) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.DataShare_1.2.0/sdk/datashare/Microsoft.Azure.Management.DataShare/) | | Management - Datadog | NuGet [0.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Datadog/0.1.0) | | | | Management - Deployment Manager | NuGet [0.9.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.DeploymentManager/0.9.1-preview) | | GitHub [0.9.1-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.DeploymentManager_0.9.1-preview/sdk/deploymentmanager/Microsoft.Azure.Management.DeploymentManager/) | | Management - Dev Spaces | NuGet [0.10.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.DevSpaces/0.10.0-preview) | | GitHub [0.10.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/devspaces/Microsoft.Azure.Management.DevSpaces) | -| Management - Device Provisioning Services | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.DeviceProvisioningServices/1.0.0) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/deviceprovisioningservices/Microsoft.Azure.Management.DeviceProvisioningServices) | +| Management - Device Provisioning Services | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.DeviceProvisioningServices/2.0.0) | | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/deviceprovisioningservices/Microsoft.Azure.Management.DeviceProvisioningServices) | | Management - Devices Fluent | NuGet [1.9.1-beta](https://www.nuget.org/packages/Microsoft.Azure.Management.Devices.Fluent/1.9.1-beta) | | | | Management - DevTest Labs | NuGet [3.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.DevTestLabs/3.0.0) | | GitHub [3.0.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/devtestlabs/Microsoft.Azure.Management.DevTestLabs) | | Management - Digital Twins | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.DigitalTwins/1.1.0) | | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.DigitalTwins_1.1.0/sdk/digitaltwins/Microsoft.Azure.Management.DigitalTwins/) | | Management - DNS | NuGet [3.0.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Dns/3.0.1) | [docs](/dotnet/api/overview/azure/dns) | GitHub [3.0.1](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/dns/Microsoft.Azure.Management.Dns) | -| Management - DNS Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Dns.Fluent/1.37.0) | | | +| Management - DNS Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Dns.Fluent/1.37.1) | | | | Management - Edge Gateway | NuGet [0.8.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.EdgeGateway/0.8.1-preview) | | GitHub [0.8.1-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/edgegateway/Microsoft.Azure.Management.EdgeGateway) | -| Management - Event Grid | NuGet [6.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.EventGrid/6.0.0) | [docs](/dotnet/api/overview/azure/eventgrid) | GitHub [6.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.EventGrid_6.0.0/sdk/eventgrid/Microsoft.Azure.Management.EventGrid/) | +| Management - Event Grid | NuGet [6.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.EventGrid/6.0.0)
NuGet [6.1.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.EventGrid/6.1.0-preview) | [docs](/dotnet/api/overview/azure/eventgrid) | GitHub [6.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.EventGrid_6.0.0/sdk/eventgrid/Microsoft.Azure.Management.EventGrid/)
GitHub [6.1.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.EventGrid_6.1.0-preview/sdk/eventgrid/Microsoft.Azure.Management.EventGrid/) | | Management - Event Hubs | NuGet [2.8.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.EventHub/2.8.0-preview) | [docs](/dotnet/api/overview/azure/event-hubs) | GitHub [2.8.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/eventhub/Microsoft.Azure.Management.EventHub) | -| Management - Event Hubs Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.EventHub.Fluent/1.37.0) | | | -| Management - Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Fluent/1.37.0) | | | +| Management - Event Hubs Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.EventHub.Fluent/1.37.1) | | | +| Management - Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Fluent/1.37.1) | | | | Management - Front Door | NuGet [4.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.FrontDoor/4.0.0) | | GitHub [4.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.FrontDoor_4.0.0/sdk/frontdoor/Microsoft.Azure.Management.FrontDoor/) | -| Management - Graph RBAC Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Graph.RBAC.Fluent/1.37.0) | | | +| Management - Graph RBAC Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Graph.RBAC.Fluent/1.37.1) | | | | Management - Guest Configuration | NuGet [1.4.0](https://www.nuget.org/packages/Microsoft.Azure.Management.GuestConfiguration/1.4.0) | | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.GuestConfiguration_1.4.0/sdk/guestconfiguration/Microsoft.Azure.Management.GuestConfiguration/) | | Management - HD Insight | NuGet [6.2.0](https://www.nuget.org/packages/Microsoft.Azure.Management.HDInsight/6.2.0) | [docs](/dotnet/api/overview/azure/hdinsight) | GitHub [6.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.HDInsight_6.2.0/sdk/hdinsight/Microsoft.Azure.Management.HDInsight/) | | Management - HD Insight Job | NuGet [2.0.7](https://www.nuget.org/packages/Microsoft.Azure.Management.HDInsight.Job/2.0.7) | [docs](/dotnet/api/overview/azure/hdinsight) | | @@ -423,94 +476,92 @@ | Management - Hybrid Data | NuGet [1.0.1](https://www.nuget.org/packages/Microsoft.Azure.Management.HybridData/1.0.1) | | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.HybridData_1.0.1/sdk/hybriddatamanager/Microsoft.Azure.Management.HybridDataManager) | | Management - Intune | NuGet [0.2.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Intune/0.2.0-preview) | | | | Management - IoT Central | NuGet [3.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.IotCentral/3.1.0) | | GitHub [3.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.IotCentral_3.1.0/sdk/iotcentral/Microsoft.Azure.Management.IotCentral/) | -| Management - IoT Hub | NuGet [2.10.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.IotHub/2.10.0-preview) | | GitHub [2.10.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.IotHub_2.10.0-preview/sdk/iothub/Microsoft.Azure.Management.IotHub/) | +| Management - IoT Hub | NuGet [4.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.IotHub/4.0.0) | | GitHub [4.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.IotHub_4.0.0/sdk/iothub/Microsoft.Azure.Management.IotHub/) | | Management - Key Vault | NuGet [3.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.KeyVault/3.1.0)
NuGet [3.1.0-preview.2](https://www.nuget.org/packages/Microsoft.Azure.Management.KeyVault/3.1.0-preview.2) | | GitHub [3.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.KeyVault_3.1.0/sdk/keyvault/Microsoft.Azure.Management.KeyVault/)
GitHub [3.1.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.KeyVault_3.1.0-preview.2/sdk/keyvault/Microsoft.Azure.Management.KeyVault/) | -| Management - Key Vault Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.KeyVault.Fluent/1.37.0) | | | -| Management - Kusto | NuGet [7.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Kusto/7.0.0) | | GitHub [7.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Kusto_7.0.0/sdk/kusto/Microsoft.Azure.Management.Kusto/) | +| Management - Key Vault Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.KeyVault.Fluent/1.37.1) | | | +| Management - Kusto | NuGet [8.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Kusto/8.0.0) | | GitHub [8.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Kusto_8.0.0/sdk/kusto/Microsoft.Azure.Management.Kusto/) | | Management - Lab Services | NuGet [3.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.LabServices/3.0.0) | | GitHub [3.0.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/labservices/Microsoft.Azure.Management.LabServices) | | Management - Location Based Services | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.LocationBasedServices/2.0.0) | | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/locationbasedservices/Microsoft.Azure.Management.LocationBasedServices) | -| Management - Locks Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Locks.Fluent/1.37.0) | | | +| Management - Locks Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Locks.Fluent/1.37.1) | | | | Management - Logic Apps | NuGet [4.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Logic/4.1.0) | | GitHub [4.1.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/logic/Microsoft.Azure.Management.Logic) | | Management - Logic Apps Fluent | NuGet [1.9.1-beta](https://www.nuget.org/packages/Microsoft.Azure.Management.Logic.Fluent/1.9.1-beta) | | | | Management - Machine Learning | NuGet [1.0.1](https://www.nuget.org/packages/Microsoft.Azure.Management.MachineLearning/1.0.1) | | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/machinelearning/Microsoft.Azure.Management.MachineLearning) | | Management - Machine Learning Compute | NuGet [0.4.0](https://www.nuget.org/packages/Microsoft.Azure.Management.MachineLearningCompute/0.4.0) | | GitHub [0.4.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/machinelearningcompute/Microsoft.Azure.Management.MachineLearningCompute) | | Management - Machine Learning Fluent | NuGet [1.9.1-beta](https://www.nuget.org/packages/Microsoft.Azure.Management.MachineLearning.Fluent/1.9.1-beta) | | | -| Management - Maintenance | NuGet [1.2.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Maintenance/1.2.0) | | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Maintenance_1.2.0/sdk/maintenance/Microsoft.Azure.Management.Maintenance/) | +| Management - Maintenance | NuGet [1.3.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Maintenance/1.3.0) | | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Maintenance_1.3.0/sdk/maintenance/Microsoft.Azure.Management.Maintenance/) | | Management - Managed Network | NuGet [1.0.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.ManagedNetwork/1.0.1-preview) | | GitHub [1.0.1-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ManagedNetwork_1.0.1-preview/sdk/managednetwork/Microsoft.Azure.Management.ManagedNetwork/) | | Management - Managed Service Identity | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ManagedServiceIdentity/1.0.0) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ManagedServiceIdentity_1.0.0/sdk/managedserviceidentity/Microsoft.Azure.Management.ManagedServiceIdentity/) | -| Management - Managed Service Identity Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Msi.Fluent/1.37.0) | | | +| Management - Managed Service Identity Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Msi.Fluent/1.37.1) | | | | Management - Managed Services | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ManagedServices/1.1.0) | | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ManagedServices_1.1.0/sdk/managedservices/Microsoft.Azure.Management.ManagedServices/) | | Management - Management Groups | NuGet [1.1.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.ManagementGroups/1.1.1-preview) | | GitHub [1.1.1-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/managementgroups/Microsoft.Azure.Management.ManagementGroups) | | Management - Management Partner | NuGet [1.1.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.ManagementPartner/1.1.1-preview) | | GitHub [1.1.1-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/managementpartner/Microsoft.Azure.Management.ManagementPartner) | | Management - Maps | NuGet [1.0.2](https://www.nuget.org/packages/Microsoft.Azure.Management.Maps/1.0.2) | | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/maps/Microsoft.Azure.Management.Maps) | | Management - Marketplace | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Marketplace/1.1.0)
NuGet [2.0.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Marketplace/2.0.0-preview) | | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Marketplace_1.1.0/sdk/marketplace/Microsoft.Azure.Management.Marketplace/)
GitHub [2.0.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Marketplace_2.0.0-preview/sdk/marketplace/Microsoft.Azure.Management.Marketplace/) | | Management - Marketplace Ordering | NuGet [1.0.1](https://www.nuget.org/packages/Microsoft.Azure.Management.MarketplaceOrdering/1.0.1) | | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/marketplaceordering/Microsoft.Azure.Management.MarketplaceOrdering) | -| Management - Media Services | NuGet [3.0.3](https://www.nuget.org/packages/Microsoft.Azure.Management.Media/3.0.3) | | GitHub [3.0.3](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Media_3.0.3/sdk/mediaservices/Microsoft.Azure.Management.Media/) | +| Management - Media Services | NuGet [3.0.4](https://www.nuget.org/packages/Microsoft.Azure.Management.Media/3.0.4) | | GitHub [3.0.4](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Media_3.0.4/sdk/mediaservices/Microsoft.Azure.Management.Media/) | | Management - Migrate Resource Mover | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Migrate.ResourceMover/2.0.0) | | | -| Management - Mixed Reality | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.MixedReality/1.0.0) | [docs](/dotnet/api/overview/azure/mixed-reality) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.MixedReality_1.0.0/sdk/mixedreality/Microsoft.Azure.Management.MixedReality/) | +| Management - Mixed Reality | NuGet [3.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.MixedReality/3.0.0) | [docs](/dotnet/api/overview/azure/mixed-reality) | GitHub [3.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.MixedReality_3.0.0/sdk/mixedreality/Microsoft.Azure.Management.MixedReality/) | | Management - Monitor | NuGet [0.25.3-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Monitor/0.25.3-preview) | | GitHub [0.25.3-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Monitor_0.25.3-preview/sdk/monitor/Microsoft.Azure.Management.Monitor/) | -| Management - Monitor Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Monitor.Fluent/1.37.0) | [docs](/dotnet/api/overview/azure/monitor) | | +| Management - Monitor Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Monitor.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/monitor) | | | Management - MySQL | NuGet [0.1.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.MySQL/0.1.0-preview) | | | -| Management - NetApp | NuGet [1.9.0](https://www.nuget.org/packages/Microsoft.Azure.Management.NetApp/1.9.0) | | GitHub [1.9.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.NetApp_1.9.0/sdk/netapp/Microsoft.Azure.Management.NetApp/) | -| Management - Network | NuGet [20.3.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Network/20.3.0) | | GitHub [20.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Network_20.3.0/sdk/network/Microsoft.Azure.Management.Network/) | -| Management - Network Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Network.Fluent/1.37.0) | [docs](/dotnet/api/overview/azure/virtual-network) | | +| Management - NetApp | NuGet [1.12.0](https://www.nuget.org/packages/Microsoft.Azure.Management.NetApp/1.12.0) | | GitHub [1.12.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.NetApp_1.12.0/sdk/netapp/Microsoft.Azure.Management.NetApp/) | +| Management - Network | NuGet [20.5.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Network/20.5.0) | | GitHub [20.5.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Network_20.5.0/sdk/network/Microsoft.Azure.Management.Network/) | +| Management - Network Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Network.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/virtual-network) | | | Management - Notification Hubs | NuGet [2.3.3-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.NotificationHubs/2.3.3-preview) | [docs](/dotnet/api/overview/azure/notification-hubs) | GitHub [2.3.3-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.NotificationHubs_2.3.3-preview/sdk/notificationhubs/Microsoft.Azure.Management.NotificationHubs/) | | Management - Notification Hubs Fluent | NuGet [1.9.1-beta](https://www.nuget.org/packages/Microsoft.Azure.Management.NotificationHubs.Fluent/1.9.1-beta) | | | -| Management - Operational Insights | NuGet [0.21.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.OperationalInsights/0.21.0-preview) | | GitHub [0.21.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.OperationalInsights_0.21.0-preview/sdk/operationalinsights/Microsoft.Azure.Management.OperationalInsights/) | +| Management - Operational Insights | NuGet [0.23.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.OperationalInsights/0.23.0-preview) | | GitHub [0.23.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.OperationalInsights_0.23.0-preview/sdk/operationalinsights/Microsoft.Azure.Management.OperationalInsights/) | | Management - Peering | NuGet [2.1.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Peering/2.1.1) | | GitHub [2.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Peering_2.1.1/sdk/peering/Microsoft.Azure.Management.Peering/) | | Management - Policy Insights | NuGet [4.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.PolicyInsights/4.0.0) | | GitHub [4.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.PolicyInsights_4.0.0/sdk/policyinsights/Microsoft.Azure.Management.PolicyInsights/) | | Management - PostgreSQL | NuGet [0.9.5-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.PostgreSQL/0.9.5-preview) | | GitHub [0.9.5-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/postgresql/Microsoft.Azure.Management.PostgreSQL) | | Management - Power BI Dedicated | NuGet [0.11.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.PowerBIDedicated/0.11.0-preview) | | GitHub [0.11.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/powerbidedicated/Microsoft.Azure.Management.PowerBIDedicated) | | Management - Power BI Embedded | NuGet [1.1.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.PowerBIEmbedded/1.1.1-preview) | | GitHub [1.1.1-preview](https://github.com/Azure/azure-sdk-for-net/tree/master/tools/legacy/SdkBackup/PowerBIEmbedded) | | Management - Private DNS | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.PrivateDns/1.0.0) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.PrivateDns_1.0.0/sdk/privatedns/Microsoft.Azure.Management.PrivateDns/) | -| Management - Private DNS Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.PrivateDns.Fluent/1.37.0) | | | +| Management - Private DNS Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.PrivateDns.Fluent/1.37.1) | | | | Management - Recovery Services | NuGet [4.3.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.RecoveryServices/4.3.1-preview) | [docs](/dotnet/api/overview/azure/recovery-services) | GitHub [4.3.1-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.RecoveryServices_4.3.1-preview/sdk/recoveryservices/Microsoft.Azure.Management.RecoveryServices/) | -| Management - Recovery Services Backup | NuGet [4.1.5-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.RecoveryServices.Backup/4.1.5-preview) | [docs](/dotnet/api/overview/azure/recovery-services) | GitHub [4.1.5-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.RecoveryServices.Backup_4.1.5-preview/sdk/recoveryservices-backup/Microsoft.Azure.Management.RecoveryServices.Backup/) | -| Management - Recovery Services Site Recovery | NuGet [2.1.2-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.RecoveryServices.SiteRecovery/2.1.2-preview) | | GitHub [2.1.2-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.RecoveryServices.SiteRecovery_2.1.2-preview/sdk/recoveryservices-siterecovery/Microsoft.Azure.Management.RecoveryServices.SiteRecovery/) | +| Management - Recovery Services Backup | NuGet [4.1.7-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.RecoveryServices.Backup/4.1.7-preview) | [docs](/dotnet/api/overview/azure/recovery-services) | GitHub [4.1.7-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.RecoveryServices.Backup_4.1.7-preview/sdk/recoveryservices-backup/Microsoft.Azure.Management.RecoveryServices.Backup/) | +| Management - Recovery Services Site Recovery | NuGet [2.1.4-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.RecoveryServices.SiteRecovery/2.1.4-preview) | | GitHub [2.1.4-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.RecoveryServices.SiteRecovery_2.1.4-preview/sdk/recoveryservices-siterecovery/Microsoft.Azure.Management.RecoveryServices.SiteRecovery/) | | Management - Recovery Services Vault Upgrade | NuGet [1.0.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.RecoveryServicesVaultUpgrade/1.0.0-preview) | | | | Management - Redis | NuGet [6.0.0-preview.2](https://www.nuget.org/packages/Microsoft.Azure.Management.Redis/6.0.0-preview.2) | | | -| Management - Redis Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Redis.Fluent/1.37.0) | [docs](/dotnet/api/overview/azure/redis-cache) | | +| Management - Redis Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Redis.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/redis-cache) | | | Management - Relay | NuGet [2.0.2](https://www.nuget.org/packages/Microsoft.Azure.Management.Relay/2.0.2) | | GitHub [2.0.2](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/relay/Microsoft.Azure.Management.Relay) | | Management - Relay Fluent | NuGet [1.9.1-beta](https://www.nuget.org/packages/Microsoft.Azure.Management.Relay.Fluent/1.9.1-beta) | | | | Management - Remote App | NuGet [1.0.9](https://www.nuget.org/packages/Microsoft.Azure.Management.RemoteApp/1.0.9) | | | | Management - Reservations | NuGet [1.15.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Reservations/1.15.0-preview) | | GitHub [1.15.0-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Reservations_1.15.0-preview/sdk/reservations/Microsoft.Azure.Management.Reservations/) | -| Management - Resource Graph | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ResourceGraph/2.0.0) | | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ResourceGraph_2.0.0/sdk/resourcegraph/Microsoft.Azure.Management.ResourceGraph/) | -| Management - Resource Manager | NuGet [3.11.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.ResourceManager/3.11.1-preview) | | | -| Management - Resource Manager Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ResourceManager.Fluent/1.37.0) | [docs](/dotnet/api/overview/azure/resource-manager) | | +| Management - Resource Graph | NuGet [2.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ResourceGraph/2.1.0) | | GitHub [2.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ResourceGraph_2.1.0/sdk/resourcegraph/Microsoft.Azure.Management.ResourceGraph/) | +| Management - Resource Manager | NuGet [3.13.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.ResourceManager/3.13.1-preview) | | | +| Management - Resource Manager Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.ResourceManager.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/resource-manager) | | | Management - Resources | NuGet [2.20.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Resources/2.20.1-preview) | | | | Management - Sample Project Publish | NuGet [0.9.0-Preview](https://www.nuget.org/packages/Microsoft.Azure.Management.SampleProjectPublish/0.9.0-Preview) | | | | Management - Scheduler | NuGet [2.2.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Scheduler/2.2.0) | | GitHub [2.2.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/scheduler/Microsoft.Azure.Management.Scheduler) | | Management - Scheduler Fluent | NuGet [1.9.1-beta](https://www.nuget.org/packages/Microsoft.Azure.Management.Scheduler.Fluent/1.9.1-beta) | | | | Management - Search | NuGet [4.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Search/4.0.0) | | GitHub [4.0.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/search/Microsoft.Azure.Management.Search) | -| Management - Search Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Search.Fluent/1.37.0) | | | +| Management - Search Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Search.Fluent/1.37.1) | | | | Management - Security Center | NuGet [2.2.0](https://www.nuget.org/packages/Microsoft.Azure.Management.SecurityCenter/2.2.0) | | GitHub [2.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.SecurityCenter_2.2.0/sdk/securitycenter/Microsoft.Azure.Management.SecurityCenter/) | | Management - Server Management | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ServerManagement/1.1.0) | | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/servermanagement/Microsoft.Azure.Management.ServerManagement) | | Management - Service Bus | NuGet [2.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ServiceBus/2.1.0) | | GitHub [2.1.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/servicebus/Microsoft.Azure.Management.ServiceBus) | -| Management - Service Bus Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ServiceBus.Fluent/1.37.0) | [docs](/dotnet/api/overview/azure/service-bus) | | +| Management - Service Bus Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.ServiceBus.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/service-bus) | | | Management - Service Fabric | NuGet [1.3.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ServiceFabric/1.3.0) | [docs](/dotnet/api/overview/azure/service-fabric) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ServiceFabric_1.3.0/sdk/servicefabric/Microsoft.Azure.Management.ServiceFabric/) | | Management - Service Fabric Fluent | NuGet [1.9.1-beta](https://www.nuget.org/packages/Microsoft.Azure.Management.ServiceFabric.Fluent/1.9.1-beta) | | | -| Management - SignalR | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.SignalR/1.1.0)
NuGet [1.1.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.SignalR/1.1.1-preview) | | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.SignalR_1.1.0/sdk/signalr/Microsoft.Azure.Management.SignalR/)
GitHub [1.1.1-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.SignalR_1.1.1-preview/sdk/signalr/Microsoft.Azure.Management.SignalR/) | +| Management - SignalR | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.SignalR/1.1.0)
NuGet [1.1.2-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.SignalR/1.1.2-preview) | | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.SignalR_1.1.0/sdk/signalr/Microsoft.Azure.Management.SignalR/)
GitHub [1.1.2-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.SignalR_1.1.2-preview/sdk/signalr/Microsoft.Azure.Management.SignalR/) | | Management - Site Recovery | NuGet [2.0.2-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.SiteRecovery/2.0.2-preview) | | | -| Management - SQL | NuGet [1.48.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Sql/1.48.0-preview) | | | -| Management - SQL Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Sql.Fluent/1.37.0) | [docs](/dotnet/api/overview/azure/sql) | | +| Management - SQL | NuGet [1.53.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Sql/1.53.0-preview) | | | +| Management - SQL Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Sql.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/sql) | | | Management - SQL Virtual Machine | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.SqlVirtualMachine/1.0.0) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.SqlVirtualMachine_1.0.0/sdk/sqlvirtualmachine/Microsoft.Azure.Management.SqlVirtualMachine/) | -| Management - Storage | NuGet [17.2.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Storage/17.2.0)
NuGet [18.0.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Storage/18.0.0-beta.1) | | GitHub [17.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Storage_17.2.0/sdk/storage/Microsoft.Azure.Management.Storage/)
GitHub [18.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Storage_18.0.0-beta.1/sdk/storage/Microsoft.Azure.Management.Storage/) | -| Management - Storage Cache | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.StorageCache/1.1.0) | | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.StorageCache_1.1.0/sdk/storagecache/Microsoft.Azure.Management.StorageCache/) | -| Management - Storage Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Storage.Fluent/1.37.0) | | | +| Management - Storage | NuGet [22.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Storage/22.0.0) | | GitHub [22.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Storage_22.0.0/sdk/storage/Microsoft.Azure.Management.Storage/) | +| Management - Storage Cache | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.StorageCache/2.0.0) | | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.StorageCache_2.0.0/sdk/storagecache/Microsoft.Azure.Management.StorageCache/) | +| Management - Storage Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Storage.Fluent/1.37.1) | | | | Management - Storage Sync | NuGet [5.0.1](https://www.nuget.org/packages/Microsoft.Azure.Management.StorageSync/5.0.1) | | GitHub [5.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.StorageSync_5.0.1/sdk/storagesync/Microsoft.Azure.Management.StorageSync/) | | Management - Storsimple 8000 series | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Storsimple8000series/1.0.0) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/storsimple8000series/Microsoft.Azure.Management.StorSimple8000Series) | | Management - StorSimple Fluent | NuGet [1.9.1-beta](https://www.nuget.org/packages/Microsoft.Azure.Management.StorSimple.Fluent/1.9.1-beta) | [docs](/dotnet/api/overview/azure/storsimple) | | | Management - Stream Analytics | NuGet [2.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.StreamAnalytics/2.1.0)
NuGet [3.0.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.StreamAnalytics/3.0.0-preview) | [docs](/dotnet/api/overview/azure/stream-analytics) | GitHub [2.1.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/streamanalytics/Microsoft.Azure.Management.StreamAnalytics) | | Management - Subscription | NuGet [1.1.5](https://www.nuget.org/packages/Microsoft.Azure.Management.Subscription/1.1.5) | | GitHub [1.1.5](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Subscription_1.1.5/sdk/subscription/Microsoft.Azure.Management.Subscription/) | | Management - Support | NuGet [1.0.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Support/1.0.1) | | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Support_1.0.1/sdk/support/Microsoft.Azure.Management.Support/) | -| Management - Synapse | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Synapse/1.0.0)
NuGet [1.0.0-preview.5](https://www.nuget.org/packages/Microsoft.Azure.Management.Synapse/1.0.0-preview.5) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Synapse_1.0.0/sdk/synapse/Microsoft.Azure.Management.Synapse/)
GitHub [1.0.0-preview.5](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Synapse_1.0.0-preview.5/sdk/synapse/Microsoft.Azure.Management.Synapse/) | +| Management - Synapse | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Synapse/2.0.0) | | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Synapse_2.0.0/sdk/synapse/Microsoft.Azure.Management.Synapse/) | | Management - Traffic Manager | NuGet [2.5.3](https://www.nuget.org/packages/Microsoft.Azure.Management.TrafficManager/2.5.3) | | GitHub [2.5.3](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/trafficmanager/Microsoft.Azure.Management.TrafficManager) | -| Management - Traffic Manager Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.TrafficManager.Fluent/1.37.0) | [docs](/dotnet/api/overview/azure/traffic-manager) | | -| Management - Virtual Machines | NuGet [42.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Compute/42.0.0)
NuGet [43.0.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Compute/43.0.0-preview.1) | | GitHub [42.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Compute_42.0.0/sdk/compute/Microsoft.Azure.Management.Compute/)
GitHub [43.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Compute_43.0.0-preview.1/sdk/compute/Microsoft.Azure.Management.Compute/) | -| Management - Virtual Machines Fluent | NuGet [1.37.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Compute.Fluent/1.37.0) | [docs](/dotnet/api/overview/azure/virtualmachines) | | -| Management - WebSites | NuGet [3.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.WebSites/3.1.0) | | GitHub [3.1.0](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/websites/Microsoft.Azure.Management.WebSites) | +| Management - Traffic Manager Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.TrafficManager.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/traffic-manager) | | +| Management - WebSites | NuGet [3.1.1](https://www.nuget.org/packages/Microsoft.Azure.Management.WebSites/3.1.1) | | GitHub [3.1.1](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/websites/Microsoft.Azure.Management.WebSites) | | Management - Workload Monitor | NuGet [1.0.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.WorkloadMonitor/1.0.0-preview) | | | -| Microsoft.Azure.Management.RedisEnterprise | NuGet [1.0.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.RedisEnterprise/1.0.0-preview) | | | +| Microsoft.Azure.Management.RedisEnterprise | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.RedisEnterprise/2.0.0) | | | | Profiles hybrid_2018_03_01 Management - Authorization | NuGet [0.9.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Profiles.hybrid_2018_03_01.Authorization/0.9.0-preview) | | | | Profiles hybrid_2018_03_01 Management - Compute | NuGet [0.9.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Profiles.hybrid_2018_03_01.Compute/0.9.0-preview) | | | | Profiles hybrid_2018_03_01 Management - DNS | NuGet [0.9.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Profiles.hybrid_2018_03_01.Dns/0.9.0-preview) | | | @@ -530,19 +581,19 @@ | Profiles hybrid_2019_03_01 Management - Storage | NuGet [0.9.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Profiles.hybrid_2019_03_01.Storage/0.9.0-preview) | | | | Profiles hybrid_2019_03_01 Management - Subscription | NuGet [0.9.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Profiles.hybrid_2019_03_01.Subscription/0.9.0-preview) | | | | Profiles hybrid_2019_03_01 Management - WebSites | NuGet [0.9.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Profiles.hybrid_2019_03_01.Websites/0.9.0-preview) | | | -| Resource Management - App Configuration | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.AppConfiguration/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.AppConfiguration-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppConfiguration_1.0.0-preview.1/sdk/appconfiguration/Azure.ResourceManager.AppConfiguration/) | -| Resource Management - Communication | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.ResourceManager.Communication/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/ResourceManager.Communication-readme-pre/) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Communication_1.0.0-beta.3/sdk/communication/Azure.ResourceManager.Communication/) | -| Resource Management - Compute | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Compute/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Compute-readme-pre/) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute_1.0.0-preview.2/sdk/compute/Azure.ResourceManager.Compute/) | -| Resource Management - Cosmos DB | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.CosmosDB/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.CosmosDB-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.CosmosDB_1.0.0-preview.1/sdk/cosmosdb/Azure.ResourceManager.CosmosDB/) | -| Resource Management - DNS | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.Dns/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Dns-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Dns_1.0.0-preview.1/sdk/dns/Azure.ResourceManager.Dns/) | -| Resource Management - Event Hubs | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.EventHubs/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.EventHubs-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.EventHubs_1.0.0-preview.1/sdk/eventhub/Azure.ResourceManager.EventHubs/) | -| Resource Management - Insights | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.Insights/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Insights-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Insights_1.0.0-preview.1/sdk/insights/Azure.ResourceManager.Insights/) | -| Resource Management - KeyVault | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.KeyVault/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.KeyVault-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.KeyVault_1.0.0-preview.1/sdk/keyvault/Azure.ResourceManager.KeyVault/) | -| Resource Management - Network | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Network/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Network-readme-pre/) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Network_1.0.0-preview.2/sdk/network/Azure.ResourceManager.Network/) | -| Resource Management - Resources | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Resources/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Resources-readme-pre/) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Resources_1.0.0-preview.2/sdk/resources/Azure.ResourceManager.Resources/) | -| Resource Management - Storage | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Storage/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Storage-readme-pre/) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Storage_1.0.0-preview.2/sdk/storage/Azure.ResourceManager.Storage/) | -| Security Insights | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Microsoft.Azure.Management.SecurityInsights/1.0.0-preview.2) | | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.SecurityInsights_1.0.0-preview.2/sdk/securityinsights/Microsoft.Azure.Management.SecurityInsights/) | -| SignalR Management | NuGet [1.7.1](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Management/1.7.1) | | GitHub [1.7.1](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR.Management) | +| Resource Management - App Configuration | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.AppConfiguration/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.AppConfiguration-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppConfiguration_1.0.0-preview.1/sdk/appconfiguration/Azure.ResourceManager.AppConfiguration/) | +| Resource Management - Communication | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.Communication/1.0.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Communication-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Communication_1.0.0/sdk/communication/Azure.ResourceManager.Communication/) | +| Resource Management - Compute | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Compute/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Compute-readme-pre) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute_1.0.0-preview.2/sdk/compute/Azure.ResourceManager.Compute/) | +| Resource Management - Cosmos DB | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.CosmosDB/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.CosmosDB-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.CosmosDB_1.0.0-preview.1/sdk/cosmosdb/Azure.ResourceManager.CosmosDB/) | +| Resource Management - DNS | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.Dns/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Dns-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Dns_1.0.0-preview.1/sdk/dns/Azure.ResourceManager.Dns/) | +| Resource Management - Event Hubs | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.EventHubs/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.EventHubs-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.EventHubs_1.0.0-preview.1/sdk/eventhub/Azure.ResourceManager.EventHubs/) | +| Resource Management - Insights | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.Insights/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Insights-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Insights_1.0.0-preview.1/sdk/insights/Azure.ResourceManager.Insights/) | +| Resource Management - KeyVault | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.KeyVault/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.KeyVault-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.KeyVault_1.0.0-preview.1/sdk/keyvault/Azure.ResourceManager.KeyVault/) | +| Resource Management - Network | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Network/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Network-readme-pre) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Network_1.0.0-preview.2/sdk/network/Azure.ResourceManager.Network/) | +| Resource Management - Resources | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Resources/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Resources-readme-pre) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Resources_1.0.0-preview.2/sdk/resources/Azure.ResourceManager.Resources/) | +| Resource Management - Storage | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Storage/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Storage-readme-pre) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Storage_1.0.0-preview.2/sdk/storage/Azure.ResourceManager.Storage/) | +| Security Insights | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.SecurityInsights/1.0.0)
NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Microsoft.Azure.Management.SecurityInsights/1.0.0-preview.2) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.SecurityInsights_1.0.0/sdk/securityinsights/Microsoft.Azure.Management.SecurityInsights/)
GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.SecurityInsights_1.0.0-preview.2/sdk/securityinsights/Microsoft.Azure.Management.SecurityInsights/) | +| SignalR Management | NuGet [1.8.1](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Management/1.8.1) | | GitHub [1.8.1](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR.Management) | | SQL Server Mangement - Key Vault Provider | NuGet [2.4.0](https://www.nuget.org/packages/Microsoft.SqlServer.Management.AlwaysEncrypted.AzureKeyVaultProvider/2.4.0) | | | | WindowsAzure Management | NuGet [4.1.3](https://www.nuget.org/packages/Microsoft.WindowsAzure.Management/4.1.3) | | | | WindowsAzure Management - Automation | NuGet [1.0.3](https://www.nuget.org/packages/Microsoft.WindowsAzure.Management.Automation/1.0.3) | | | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index d44038384a0fc..ae59e5101f9c0 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -1,59 +1,69 @@ | Name | Package | Docs | Source | | ---- | ------- | ---- | ------ | -| Anomaly Detector | NuGet [3.0.0-preview.2](https://www.nuget.org/packages/Azure.AI.AnomalyDetector/3.0.0-preview.2) | [docs](/dotnet/api/overview/azure/AI.AnomalyDetector-readme-pre/) | GitHub [3.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AnomalyDetector_3.0.0-preview.2/sdk/anomalydetector/Azure.AI.AnomalyDetector/) | -| App Configuration | NuGet [1.0.2](https://www.nuget.org/packages/Azure.Data.AppConfiguration/1.0.2) | [docs](/dotnet/api/overview/azure/Data.AppConfiguration-readme/) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.AppConfiguration_1.0.2/sdk/appconfiguration/Azure.Data.AppConfiguration/) | -| ASP.NET Extension - Configuration Secrets | NuGet [1.0.2](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.Configuration.Secrets/1.0.2) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.Configuration.Secrets-readme/) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.Configuration.Secrets_1.0.2/sdk/extensions/Azure.Extensions.AspNetCore.Configuration.Secrets/) | -| ASP.NET Extension - DataProtection Blobs | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Blobs/1.2.0) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Blobs-readme/) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Blobs_1.2.0/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Blobs/) | -| ASP.NET Extension - DataProtection Keys | NuGet [1.0.2](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Keys/1.0.2) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Keys-readme/) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Keys_1.0.2/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Keys/) | -| Azure Mixed Reality Authentication | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.MixedReality.Authentication/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.Authentication_1.0.0-beta.1/sdk/mixedreality/Azure.MixedReality.Authentication/) | -| Azure Remote Rendering | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.MixedReality.RemoteRendering/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.RemoteRendering_1.0.0-beta.1/sdk/mixedreality/Azure.MixedReality.RemoteRendering/) | -| Azure Security Attestation | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Security.Attestation/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Security.Attestation-readme-pre/) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.Attestation_1.0.0-beta.1/sdk/attestation/Azure.Security.Attestation/) | -| Cognitive Search | NuGet [11.2.0](https://www.nuget.org/packages/Azure.Search.Documents/11.2.0) | [docs](/dotnet/api/overview/azure/Search.Documents-readme/) | GitHub [11.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Search.Documents_11.2.0/sdk/search/Azure.Search.Documents/) | -| Communication Administration | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.Administration/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Communication.Administration-readme-pre/) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Administration_1.0.0-beta.3/sdk/communication/Azure.Communication.Administration/) | -| Communication Chat | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Communication.Chat/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme-pre/) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.0.0-beta.4/sdk/communication/Azure.Communication.Chat/) | -| Communication Common | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Communication.Common/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Communication.Common-readme-pre/) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_1.0.0-beta.4/sdk/communication/Azure.Communication.Common/) | -| Communication Identity | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Communication.Identity/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Communication.Identity-readme-pre/) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Identity_1.0.0-beta.4/sdk/communication/Azure.Communication.Identity/) | -| Communication SMS | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.Sms/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Communication.Sms-readme-pre/) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Sms_1.0.0-beta.3/sdk/communication/Azure.Communication.Sms/) | -| Core | NuGet [1.9.0](https://www.nuget.org/packages/Azure.Core/1.9.0) | [docs](/dotnet/api/overview/azure/Core-readme/) | GitHub [1.9.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core_1.9.0/sdk/core/Azure.Core/) | -| Core - AMQP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Core.Amqp/1.0.0) | [docs](/dotnet/api/overview/azure/Core.Amqp-readme/) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Amqp_1.0.0/sdk/core/Azure.Core.Amqp/) | +| Anomaly Detector | NuGet [3.0.0-preview.3](https://www.nuget.org/packages/Azure.AI.AnomalyDetector/3.0.0-preview.3) | [docs](/dotnet/api/overview/azure/AI.AnomalyDetector-readme-pre) | GitHub [3.0.0-preview.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AnomalyDetector_3.0.0-preview.3/sdk/anomalydetector/Azure.AI.AnomalyDetector/) | +| App Configuration | NuGet [1.0.3](https://www.nuget.org/packages/Azure.Data.AppConfiguration/1.0.3)
NuGet [1.1.0-beta.2](https://www.nuget.org/packages/Azure.Data.AppConfiguration/1.1.0-beta.2) | [docs](/dotnet/api/overview/azure/Data.AppConfiguration-readme) | GitHub [1.0.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.AppConfiguration_1.0.3/sdk/appconfiguration/Azure.Data.AppConfiguration/)
GitHub [1.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.AppConfiguration_1.1.0-beta.2/sdk/appconfiguration/Azure.Data.AppConfiguration/) | +| ASP.NET Extension - Configuration Secrets | NuGet [1.2.1](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.Configuration.Secrets/1.2.1) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.Configuration.Secrets-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.Configuration.Secrets_1.2.1/sdk/extensions/Azure.Extensions.AspNetCore.Configuration.Secrets/) | +| ASP.NET Extension - DataProtection Blobs | NuGet [1.2.1](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Blobs/1.2.1) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Blobs-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Blobs_1.2.1/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Blobs/) | +| ASP.NET Extension - DataProtection Keys | NuGet [1.0.3](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Keys/1.0.3) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Keys-readme) | GitHub [1.0.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Keys_1.0.3/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Keys/) | +| Attestation | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Security.Attestation/1.0.0) | [docs](/dotnet/api/overview/azure/Security.Attestation-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.Attestation_1.0.0/sdk/attestation/Azure.Security.Attestation/) | +| Azure Mixed Reality Authentication | NuGet [1.0.1](https://www.nuget.org/packages/Azure.MixedReality.Authentication/1.0.1) | [docs](/dotnet/api/overview/azure/MixedReality.Authentication-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.Authentication_1.0.1/sdk/mixedreality/Azure.MixedReality.Authentication/) | +| Azure Object Anchors Conversion | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.MixedReality.ObjectAnchors.Conversion/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/MixedReality.ObjectAnchors.Conversion-readme-pre) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.ObjectAnchors.Conversion_0.2.0-beta.1/sdk/objectanchors/Azure.MixedReality.ObjectAnchors.Conversion/) | +| Azure Remote Rendering | NuGet [1.0.1](https://www.nuget.org/packages/Azure.MixedReality.RemoteRendering/1.0.1) | [docs](/dotnet/api/overview/azure/MixedReality.RemoteRendering-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.RemoteRendering_1.0.1/sdk/remoterendering/Azure.MixedReality.RemoteRendering/) | +| Azure Video Analyzer Edge | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Media.VideoAnalyzer.Edge/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Media.VideoAnalyzer.Edge-readme-pre) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Media.VideoAnalyzer.Edge_1.0.0-beta.4/sdk/videoanalyzer/Azure.Media.VideoAnalyzer.Edge/) | +| Cognitive Search | NuGet [11.2.1](https://www.nuget.org/packages/Azure.Search.Documents/11.2.1)
NuGet [11.3.0-beta.2](https://www.nuget.org/packages/Azure.Search.Documents/11.3.0-beta.2) | [docs](/dotnet/api/overview/azure/Search.Documents-readme) | GitHub [11.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Search.Documents_11.2.1/sdk/search/Azure.Search.Documents/)
GitHub [11.3.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Search.Documents_11.3.0-beta.2/sdk/search/Azure.Search.Documents/) | +| Communication Chat | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Chat/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.0.1/sdk/communication/Azure.Communication.Chat/) | +| Communication Common | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Common/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Common-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_1.0.1/sdk/communication/Azure.Communication.Common/) | +| Communication Identity | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Identity/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Identity-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Identity_1.0.1/sdk/communication/Azure.Communication.Identity/) | +| Communication Phone Numbers | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.PhoneNumbers/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.PhoneNumbers-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.PhoneNumbers_1.0.1/sdk/communication/Azure.Communication.PhoneNumbers/) | +| Communication SMS | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Sms/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Sms-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Sms_1.0.1/sdk/communication/Azure.Communication.Sms/) | +| ConfidentialLedger | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Storage.ConfidentialLedger/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.ConfidentialLedger-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.ConfidentialLedger_1.0.0-beta.1/sdk/confidentialledger/Azure.Storage.ConfidentialLedger/) | +| Container Registry | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Containers.ContainerRegistry/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Containers.ContainerRegistry-readme-pre) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Containers.ContainerRegistry_1.0.0-beta.2/sdk/containerregistry/Azure.Containers.ContainerRegistry/) | +| Core | NuGet [1.14.0](https://www.nuget.org/packages/Azure.Core/1.14.0) | [docs](/dotnet/api/overview/azure/Core-readme) | GitHub [1.14.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core_1.14.0/sdk/core/Azure.Core/) | +| Core - AMQP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Core.Amqp/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Core.Amqp/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Core.Amqp-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Amqp_1.0.0/sdk/core/Azure.Core.Amqp/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Amqp_1.1.0-beta.1/sdk/core/Azure.Core.Amqp/) | | Cosmos DB | NuGet [4.0.0-preview3](https://www.nuget.org/packages/Azure.Cosmos/4.0.0-preview3) | [docs](/dotnet/api/azure.cosmos) | GitHub [4.0.0-preview3](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/releases/4.0.0-preview3) | -| Digital Twins - Core | NuGet [1.2.1](https://www.nuget.org/packages/Azure.DigitalTwins.Core/1.2.1) | [docs](/dotnet/api/overview/azure/DigitalTwins.Core-readme/) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.DigitalTwins.Core_1.2.1/sdk/digitaltwins/Azure.DigitalTwins.Core/) | -| Event Grid | NuGet [4.0.0-beta.5](https://www.nuget.org/packages/Azure.Messaging.EventGrid/4.0.0-beta.5) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid-readme-pre/) | GitHub [4.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid_4.0.0-beta.5/sdk/eventgrid/Azure.Messaging.EventGrid/) | -| Event Hubs | NuGet [5.3.0](https://www.nuget.org/packages/Azure.Messaging.EventHubs/5.3.0) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs-readme/) | GitHub [5.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs_5.3.0/sdk/eventhub/Azure.Messaging.EventHubs/) | -| Event Hubs - Event Processor | NuGet [5.3.0](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/5.3.0) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs.Processor-readme/) | GitHub [5.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs.Processor_5.3.0/sdk/eventhub/Azure.Messaging.EventHubs.Processor/) | -| Event Hubs - Schema Registry | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Data.SchemaRegistry/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Data.SchemaRegistry-readme-pre/) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.SchemaRegistry_1.0.0-beta.2/sdk/schemaregistry/Azure.Data.SchemaRegistry/) | -| Form Recognizer | NuGet [3.0.0](https://www.nuget.org/packages/Azure.AI.FormRecognizer/3.0.0)
NuGet [3.1.0-beta.2](https://www.nuget.org/packages/Azure.AI.FormRecognizer/3.1.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.FormRecognizer-readme/) | GitHub [3.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.FormRecognizer_3.0.0/sdk/formrecognizer/Azure.AI.FormRecognizer/)
GitHub [3.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.FormRecognizer_3.1.0-beta.2/sdk/formrecognizer/Azure.AI.FormRecognizer/) | -| Identity | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Identity/1.3.0)
NuGet [1.4.0-beta.3](https://www.nuget.org/packages/Azure.Identity/1.4.0-beta.3) | [docs](/dotnet/api/overview/azure/Identity-readme/) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.3.0/sdk/identity/Azure.Identity/)
GitHub [1.4.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.4.0-beta.3/sdk/identity/Azure.Identity/) | -| Key Vault - Administration | NuGet [4.0.0-beta.4](https://www.nuget.org/packages/Azure.Security.KeyVault.Administration/4.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Administration-readme-pre/) | GitHub [4.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Administration_4.0.0-beta.4/sdk/keyvault/Azure.Security.KeyVault.Administration/) | -| Key Vault - Certificates | NuGet [4.1.0](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates/4.1.0)
NuGet [4.2.0-beta.4](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates/4.2.0-beta.4) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Certificates-readme/) | GitHub [4.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Certificates_4.1.0/sdk/keyvault/Azure.Security.KeyVault.Certificates/)
GitHub [4.2.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Certificates_4.2.0-beta.4/sdk/keyvault/Azure.Security.KeyVault.Certificates/) | -| Key Vault - Keys | NuGet [4.1.0](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys/4.1.0)
NuGet [4.2.0-beta.4](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys/4.2.0-beta.4) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Keys-readme/) | GitHub [4.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Keys_4.1.0/sdk/keyvault/Azure.Security.KeyVault.Keys/)
GitHub [4.2.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Keys_4.2.0-beta.4/sdk/keyvault/Azure.Security.KeyVault.Keys/) | -| Key Vault - Secrets | NuGet [4.1.0](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets/4.1.0)
NuGet [4.2.0-beta.4](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets/4.2.0-beta.4) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Secrets-readme/) | GitHub [4.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Secrets_4.1.0/sdk/keyvault/Azure.Security.KeyVault.Secrets/)
GitHub [4.2.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Secrets_4.2.0-beta.4/sdk/keyvault/Azure.Security.KeyVault.Secrets/) | -| Media Analytics Edge | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Media.Analytics.Edge/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Media.Analytics.Edge-readme-pre/) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Media.Analytics.Edge_1.0.0-beta.1/sdk/mediaservices/Azure.Media.Analytics.Edge/) | -| Metrics Advisor | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.AI.MetricsAdvisor/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/AI.MetricsAdvisor-readme-pre/) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.MetricsAdvisor_1.0.0-beta.3/sdk/metricsadvisor/Azure.AI.MetricsAdvisor/) | -| Service Bus | NuGet [7.1.0](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/7.1.0) | [docs](/dotnet/api/overview/azure/Messaging.ServiceBus-readme/) | GitHub [7.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.ServiceBus_7.1.0/sdk/servicebus/Azure.Messaging.ServiceBus/) | -| Storage - Blobs | NuGet [12.8.0](https://www.nuget.org/packages/Azure.Storage.Blobs/12.8.0)
NuGet [12.9.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs/12.9.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme/) | GitHub [12.8.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.8.0/sdk/storage/Azure.Storage.Blobs/)
GitHub [12.9.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.9.0-beta.1/sdk/storage/Azure.Storage.Blobs/) | -| Storage - Blobs Batch | NuGet [12.5.0](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.5.0)
NuGet [12.6.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.6.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme/) | GitHub [12.5.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.5.0/sdk/storage/Azure.Storage.Blobs.Batch/)
GitHub [12.6.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.6.0-beta.1/sdk/storage/Azure.Storage.Blobs.Batch/) | -| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.9](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.9) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme-pre/) | GitHub [12.0.0-preview.9](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.9/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | -| Storage - Common | NuGet [12.7.0](https://www.nuget.org/packages/Azure.Storage.Common/12.7.0)
NuGet [12.8.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Common/12.8.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Common-readme/) | GitHub [12.7.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.7.0/sdk/storage/Azure.Storage.Common/)
GitHub [12.8.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.8.0-beta.1/sdk/storage/Azure.Storage.Common/) | -| Storage - Files Data Lake | NuGet [12.6.0](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.6.0)
NuGet [12.7.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.7.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme/) | GitHub [12.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.6.0/sdk/storage/Azure.Storage.Files.DataLake/)
GitHub [12.7.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.7.0-beta.1/sdk/storage/Azure.Storage.Files.DataLake/) | -| Storage - Files Shares | NuGet [12.6.0](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.6.0)
NuGet [12.7.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.7.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme/) | GitHub [12.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.6.0/sdk/storage/Azure.Storage.Files.Shares/)
GitHub [12.7.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.7.0-beta.1/sdk/storage/Azure.Storage.Files.Shares/) | -| Storage - Queues | NuGet [12.6.0](https://www.nuget.org/packages/Azure.Storage.Queues/12.6.0)
NuGet [12.7.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Queues/12.7.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme/) | GitHub [12.6.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.6.0/sdk/storage/Azure.Storage.Queues/)
GitHub [12.7.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.7.0-beta.1/sdk/storage/Azure.Storage.Queues/) | -| Synapse - AccessControl | NuGet [1.0.0-preview.3](https://www.nuget.org/packages/Azure.Analytics.Synapse.AccessControl/1.0.0-preview.3) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.AccessControl-readme-pre/) | GitHub [1.0.0-preview.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.AccessControl_1.0.0-preview.3/sdk/synapse/Azure.Analytics.Synapse.AccessControl/) | -| Synapse - Artifacts | NuGet [1.0.0-preview.6](https://www.nuget.org/packages/Azure.Analytics.Synapse.Artifacts/1.0.0-preview.6) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Artifacts-readme-pre/) | GitHub [1.0.0-preview.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Artifacts_1.0.0-preview.6/sdk/synapse/Azure.Analytics.Synapse.Artifacts/) | -| Synapse - Managed Private Endpoints | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Analytics.Synapse.ManagedPrivateEndpoints/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.ManagedPrivateEndpoints-readme-pre/) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.ManagedPrivateEndpoints_1.0.0-beta.2/sdk/synapse/Azure.Analytics.Synapse.ManagedPrivateEndpoints/) | -| Synapse - Monitoring | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Analytics.Synapse.Monitoring/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Monitoring-readme-pre/) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Monitoring_1.0.0-beta.2/sdk/synapse/Azure.Analytics.Synapse.Monitoring/) | -| Synapse - Spark | NuGet [1.0.0-preview.4](https://www.nuget.org/packages/Azure.Analytics.Synapse.Spark/1.0.0-preview.4) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Spark-readme-pre/) | GitHub [1.0.0-preview.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Spark_1.0.0-preview.4/sdk/synapse/Azure.Analytics.Synapse.Spark/) | -| System Memory Data | NuGet [1.0.1](https://www.nuget.org/packages/System.Memory.Data/1.0.1) | [docs](/dotnet/api/overview/azure/System.Memory.Data-readme/) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/System.Memory.Data_1.0.1/sdk/core/System.Memory.Data/) | -| Tables | NuGet [3.0.0-beta.5](https://www.nuget.org/packages/Azure.Data.Tables/3.0.0-beta.5) | [docs](/dotnet/api/overview/azure/Data.Tables-readme-pre/) | GitHub [3.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.Tables_3.0.0-beta.5/sdk/tables/Azure.Data.Tables/) | -| Text Analytics | NuGet [5.0.0](https://www.nuget.org/packages/Azure.AI.TextAnalytics/5.0.0)
NuGet [5.1.0-beta.4](https://www.nuget.org/packages/Azure.AI.TextAnalytics/5.1.0-beta.4) | [docs](/dotnet/api/overview/azure/AI.TextAnalytics-readme/) | GitHub [5.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.TextAnalytics_5.0.0/sdk/textanalytics/Azure.AI.TextAnalytics/)
GitHub [5.1.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.TextAnalytics_5.1.0-beta.4/sdk/textanalytics/Azure.AI.TextAnalytics/) | -| Resource Management - App Configuration | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.AppConfiguration/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.AppConfiguration-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppConfiguration_1.0.0-preview.1/sdk/appconfiguration/Azure.ResourceManager.AppConfiguration/) | -| Resource Management - Communication | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.ResourceManager.Communication/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/ResourceManager.Communication-readme-pre/) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Communication_1.0.0-beta.3/sdk/communication/Azure.ResourceManager.Communication/) | -| Resource Management - Compute | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Compute/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Compute-readme-pre/) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute_1.0.0-preview.2/sdk/compute/Azure.ResourceManager.Compute/) | -| Resource Management - Cosmos DB | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.CosmosDB/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.CosmosDB-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.CosmosDB_1.0.0-preview.1/sdk/cosmosdb/Azure.ResourceManager.CosmosDB/) | -| Resource Management - DNS | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.Dns/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Dns-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Dns_1.0.0-preview.1/sdk/dns/Azure.ResourceManager.Dns/) | -| Resource Management - Event Hubs | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.EventHubs/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.EventHubs-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.EventHubs_1.0.0-preview.1/sdk/eventhub/Azure.ResourceManager.EventHubs/) | -| Resource Management - Insights | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.Insights/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Insights-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Insights_1.0.0-preview.1/sdk/insights/Azure.ResourceManager.Insights/) | -| Resource Management - KeyVault | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.KeyVault/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.KeyVault-readme-pre/) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.KeyVault_1.0.0-preview.1/sdk/keyvault/Azure.ResourceManager.KeyVault/) | -| Resource Management - Network | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Network/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Network-readme-pre/) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Network_1.0.0-preview.2/sdk/network/Azure.ResourceManager.Network/) | -| Resource Management - Resources | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Resources/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Resources-readme-pre/) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Resources_1.0.0-preview.2/sdk/resources/Azure.ResourceManager.Resources/) | -| Resource Management - Storage | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Storage/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Storage-readme-pre/) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Storage_1.0.0-preview.2/sdk/storage/Azure.ResourceManager.Storage/) | +| Digital Twins - Core | NuGet [1.2.2](https://www.nuget.org/packages/Azure.DigitalTwins.Core/1.2.2) | [docs](/dotnet/api/overview/azure/DigitalTwins.Core-readme) | GitHub [1.2.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.DigitalTwins.Core_1.2.2/sdk/digitaltwins/Azure.DigitalTwins.Core/) | +| Document Translation | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.AI.Translation.Document/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/AI.Translation.Document-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Translation.Document_1.0.0-beta.1/sdk/translation/Azure.AI.Translation.Document/) | +| Event Grid | NuGet [4.2.0](https://www.nuget.org/packages/Azure.Messaging.EventGrid/4.2.0) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid-readme) | GitHub [4.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid_4.2.0/sdk/eventgrid/Azure.Messaging.EventGrid/) | +| Event Hubs | NuGet [5.4.1](https://www.nuget.org/packages/Azure.Messaging.EventHubs/5.4.1) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs-readme) | GitHub [5.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs_5.4.1/sdk/eventhub/Azure.Messaging.EventHubs/) | +| Event Hubs - Event Processor | NuGet [5.4.1](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/5.4.1) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs.Processor-readme) | GitHub [5.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs.Processor_5.4.1/sdk/eventhub/Azure.Messaging.EventHubs.Processor/) | +| Event Hubs - Schema Registry | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Data.SchemaRegistry/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Data.SchemaRegistry-readme-pre) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.SchemaRegistry_1.0.0-beta.2/sdk/schemaregistry/Azure.Data.SchemaRegistry/) | +| FarmBeats | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Verticals.AgriFood.Farming/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Verticals.AgriFood.Farming-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Verticals.AgriFood.Farming_1.0.0-beta.1/sdk/farmbeats/Azure.Verticals.AgriFood.Farming/) | +| Form Recognizer | NuGet [3.1.0](https://www.nuget.org/packages/Azure.AI.FormRecognizer/3.1.0) | [docs](/dotnet/api/overview/azure/AI.FormRecognizer-readme) | GitHub [3.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.FormRecognizer_3.1.0/sdk/formrecognizer/Azure.AI.FormRecognizer/) | +| Identity | NuGet [1.4.0](https://www.nuget.org/packages/Azure.Identity/1.4.0) | [docs](/dotnet/api/overview/azure/Identity-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.4.0/sdk/identity/Azure.Identity/) | +| IoT Device Update | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.IoT.DeviceUpdate/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/IoT.DeviceUpdate-readme-pre) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.IoT.DeviceUpdate_1.0.0-beta.2/sdk/deviceupdate/Azure.Iot.DeviceUpdate/) | +| Key Vault - Administration | NuGet [4.0.0-beta.5](https://www.nuget.org/packages/Azure.Security.KeyVault.Administration/4.0.0-beta.5) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Administration-readme-pre) | GitHub [4.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Administration_4.0.0-beta.5/sdk/keyvault/Azure.Security.KeyVault.Administration/) | +| Key Vault - Certificates | NuGet [4.1.1](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates/4.1.1)
NuGet [4.2.0-beta.6](https://www.nuget.org/packages/Azure.Security.KeyVault.Certificates/4.2.0-beta.6) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Certificates-readme) | GitHub [4.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Certificates_4.1.1/sdk/keyvault/Azure.Security.KeyVault.Certificates/)
GitHub [4.2.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Certificates_4.2.0-beta.6/sdk/keyvault/Azure.Security.KeyVault.Certificates/) | +| Key Vault - Keys | NuGet [4.1.1](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys/4.1.1)
NuGet [4.2.0-beta.6](https://www.nuget.org/packages/Azure.Security.KeyVault.Keys/4.2.0-beta.6) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Keys-readme) | GitHub [4.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Keys_4.1.1/sdk/keyvault/Azure.Security.KeyVault.Keys/)
GitHub [4.2.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Keys_4.2.0-beta.6/sdk/keyvault/Azure.Security.KeyVault.Keys/) | +| Key Vault - Secrets | NuGet [4.1.1](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets/4.1.1)
NuGet [4.2.0-beta.5](https://www.nuget.org/packages/Azure.Security.KeyVault.Secrets/4.2.0-beta.5) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Secrets-readme) | GitHub [4.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Secrets_4.1.1/sdk/keyvault/Azure.Security.KeyVault.Secrets/)
GitHub [4.2.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Secrets_4.2.0-beta.5/sdk/keyvault/Azure.Security.KeyVault.Secrets/) | +| Media Analytics Edge | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Media.Analytics.Edge/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Media.Analytics.Edge-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Media.Analytics.Edge_1.0.0-beta.1/sdk/mediaservices/Azure.Media.Analytics.Edge) | +| Metrics Advisor | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.AI.MetricsAdvisor/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/AI.MetricsAdvisor-readme-pre) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.MetricsAdvisor_1.0.0-beta.3/sdk/metricsadvisor/Azure.AI.MetricsAdvisor/) | +| Monitor OpenTelemetry Exporter | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.Exporter-readme-pre) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.0.0-beta.2/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/) | +| Purview Catalog | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Catalog/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Catalog-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Catalog_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Catalog/) | +| Purview Scanning | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Scanning/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Scanning-readme-pre) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Scanning_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Scanning/) | +| Service Bus | NuGet [7.1.2](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/7.1.2)
NuGet [7.2.0-beta.3](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/7.2.0-beta.3) | [docs](/dotnet/api/overview/azure/Messaging.ServiceBus-readme) | GitHub [7.1.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.ServiceBus_7.1.2/sdk/servicebus/Azure.Messaging.ServiceBus/)
GitHub [7.2.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.ServiceBus_7.2.0-beta.3/sdk/servicebus/Azure.Messaging.ServiceBus/) | +| Storage - Blobs | NuGet [12.8.4](https://www.nuget.org/packages/Azure.Storage.Blobs/12.8.4)
NuGet [12.9.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Blobs/12.9.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme) | GitHub [12.8.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.8.4/sdk/storage/Azure.Storage.Blobs/)
GitHub [12.9.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.9.0-beta.4/sdk/storage/Azure.Storage.Blobs/) | +| Storage - Blobs Batch | NuGet [12.5.2](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.5.2)
NuGet [12.6.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.6.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme) | GitHub [12.5.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.5.2/sdk/storage/Azure.Storage.Blobs.Batch/)
GitHub [12.6.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.6.0-beta.4/sdk/storage/Azure.Storage.Blobs.Batch/) | +| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.12](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.12) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme-pre) | GitHub [12.0.0-preview.12](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.12/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | +| Storage - Common | NuGet [12.7.3](https://www.nuget.org/packages/Azure.Storage.Common/12.7.3)
NuGet [12.8.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Common/12.8.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Common-readme) | GitHub [12.7.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.7.3/sdk/storage/Azure.Storage.Common/)
GitHub [12.8.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.8.0-beta.4/sdk/storage/Azure.Storage.Common/) | +| Storage - Files Data Lake | NuGet [12.6.2](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.6.2)
NuGet [12.7.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.7.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme) | GitHub [12.6.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.6.2/sdk/storage/Azure.Storage.Files.DataLake/)
GitHub [12.7.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.7.0-beta.4/sdk/storage/Azure.Storage.Files.DataLake/) | +| Storage - Files Shares | NuGet [12.6.2](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.6.2)
NuGet [12.7.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.7.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme) | GitHub [12.6.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.6.2/sdk/storage/Azure.Storage.Files.Shares/)
GitHub [12.7.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.7.0-beta.4/sdk/storage/Azure.Storage.Files.Shares/) | +| Storage - Queues | NuGet [12.6.2](https://www.nuget.org/packages/Azure.Storage.Queues/12.6.2)
NuGet [12.7.0-beta.4](https://www.nuget.org/packages/Azure.Storage.Queues/12.7.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme) | GitHub [12.6.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.6.2/sdk/storage/Azure.Storage.Queues/)
GitHub [12.7.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.7.0-beta.4/sdk/storage/Azure.Storage.Queues/) | +| Synapse - AccessControl | NuGet [1.0.0-preview.4](https://www.nuget.org/packages/Azure.Analytics.Synapse.AccessControl/1.0.0-preview.4) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.AccessControl-readme-pre) | GitHub [1.0.0-preview.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.AccessControl_1.0.0-preview.4/sdk/synapse/Azure.Analytics.Synapse.AccessControl/) | +| Synapse - Artifacts | NuGet [1.0.0-preview.10](https://www.nuget.org/packages/Azure.Analytics.Synapse.Artifacts/1.0.0-preview.10) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Artifacts-readme-pre) | GitHub [1.0.0-preview.10](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Artifacts_1.0.0-preview.10/sdk/synapse/Azure.Analytics.Synapse.Artifacts/) | +| Synapse - Managed Private Endpoints | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Analytics.Synapse.ManagedPrivateEndpoints/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.ManagedPrivateEndpoints-readme-pre) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.ManagedPrivateEndpoints_1.0.0-beta.3/sdk/synapse/Azure.Analytics.Synapse.ManagedPrivateEndpoints/) | +| Synapse - Monitoring | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Analytics.Synapse.Monitoring/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Monitoring-readme-pre) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Monitoring_1.0.0-beta.3/sdk/synapse/Azure.Analytics.Synapse.Monitoring/) | +| Synapse - Spark | NuGet [1.0.0-preview.6](https://www.nuget.org/packages/Azure.Analytics.Synapse.Spark/1.0.0-preview.6) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Spark-readme-pre) | GitHub [1.0.0-preview.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Spark_1.0.0-preview.6/sdk/synapse/Azure.Analytics.Synapse.Spark/) | +| System Memory Data | NuGet [1.0.2](https://www.nuget.org/packages/System.Memory.Data/1.0.2) | [docs](/dotnet/api/overview/azure/System.Memory.Data-readme) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/System.Memory.Data_1.0.2/sdk/core/System.Memory.Data/) | +| Tables | NuGet [12.0.0-beta.8](https://www.nuget.org/packages/Azure.Data.Tables/12.0.0-beta.8) | [docs](/dotnet/api/overview/azure/Data.Tables-readme-pre) | GitHub [12.0.0-beta.8](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.Tables_12.0.0-beta.8/sdk/tables/Azure.Data.Tables/) | +| Text Analytics | NuGet [5.0.0](https://www.nuget.org/packages/Azure.AI.TextAnalytics/5.0.0)
NuGet [5.1.0-beta.7](https://www.nuget.org/packages/Azure.AI.TextAnalytics/5.1.0-beta.7) | [docs](/dotnet/api/overview/azure/AI.TextAnalytics-readme) | GitHub [5.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.TextAnalytics_5.0.0/sdk/textanalytics/Azure.AI.TextAnalytics/)
GitHub [5.1.0-beta.7](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.TextAnalytics_5.1.0-beta.7/sdk/textanalytics/Azure.AI.TextAnalytics/) | +| Resource Management - App Configuration | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.AppConfiguration/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.AppConfiguration-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppConfiguration_1.0.0-preview.1/sdk/appconfiguration/Azure.ResourceManager.AppConfiguration/) | +| Resource Management - Communication | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.Communication/1.0.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Communication-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Communication_1.0.0/sdk/communication/Azure.ResourceManager.Communication/) | +| Resource Management - Compute | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Compute/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Compute-readme-pre) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute_1.0.0-preview.2/sdk/compute/Azure.ResourceManager.Compute/) | +| Resource Management - Cosmos DB | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.CosmosDB/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.CosmosDB-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.CosmosDB_1.0.0-preview.1/sdk/cosmosdb/Azure.ResourceManager.CosmosDB/) | +| Resource Management - DNS | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.Dns/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Dns-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Dns_1.0.0-preview.1/sdk/dns/Azure.ResourceManager.Dns/) | +| Resource Management - Event Hubs | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.EventHubs/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.EventHubs-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.EventHubs_1.0.0-preview.1/sdk/eventhub/Azure.ResourceManager.EventHubs/) | +| Resource Management - Insights | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.Insights/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Insights-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Insights_1.0.0-preview.1/sdk/insights/Azure.ResourceManager.Insights/) | +| Resource Management - KeyVault | NuGet [1.0.0-preview.1](https://www.nuget.org/packages/Azure.ResourceManager.KeyVault/1.0.0-preview.1) | [docs](/dotnet/api/overview/azure/ResourceManager.KeyVault-readme-pre) | GitHub [1.0.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.KeyVault_1.0.0-preview.1/sdk/keyvault/Azure.ResourceManager.KeyVault/) | +| Resource Management - Network | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Network/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Network-readme-pre) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Network_1.0.0-preview.2/sdk/network/Azure.ResourceManager.Network/) | +| Resource Management - Resources | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Resources/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Resources-readme-pre) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Resources_1.0.0-preview.2/sdk/resources/Azure.ResourceManager.Resources/) | +| Resource Management - Storage | NuGet [1.0.0-preview.2](https://www.nuget.org/packages/Azure.ResourceManager.Storage/1.0.0-preview.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Storage-readme-pre) | GitHub [1.0.0-preview.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Storage_1.0.0-preview.2/sdk/storage/Azure.ResourceManager.Storage/) | diff --git a/docs/azure/index.yml b/docs/azure/index.yml index 4f017f0eaa645..3d35f18b81db2 100644 --- a/docs/azure/index.yml +++ b/docs/azure/index.yml @@ -1,7 +1,7 @@ ### YamlMime:Hub title: Azure for .NET developers -summary: .NET 💜 Azure +summary: Learn to use the Azure SDK for .NET. Browse API reference, sample code, tutorials, quickstarts, conceptual articles and more. Know that .NET 💜 Azure. brand: dotnet metadata: @@ -9,7 +9,7 @@ metadata: description: Samples, tutorials, and education for .NET on Azure ms.topic: hub-page ms.prod: azure-dotnet - ms.date: 08/12/2020 + ms.date: 05/13/2021 highlightedContent: # itemType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | whats-new @@ -272,4 +272,4 @@ additionalContent: url: https://github.com/dotnet/ # footer (optional) - footer: "Contribute to .NET docs. Read our [contributor guide](/contribute/dotnet/dotnet-contribute)." + footer: "Are you interested in contributing to the .NET docs? For more information, see our [contributor guide](/contribute/dotnet/dotnet-contribute)." diff --git a/docs/azure/install-azure-cli.md b/docs/azure/install-azure-cli.md index a03bed954cf23..be49daf3468f2 100644 --- a/docs/azure/install-azure-cli.md +++ b/docs/azure/install-azure-cli.md @@ -6,6 +6,7 @@ ms.topic: conceptual ms.custom: devx-track-dotnet ms.author: daberry author: daberry +recommendations: false --- # Install the Azure CLI diff --git a/docs/azure/intro.md b/docs/azure/intro.md index cb1f5678a8138..3604c4ea0d16a 100644 --- a/docs/azure/intro.md +++ b/docs/azure/intro.md @@ -1,7 +1,7 @@ --- title: Get started with Azure and .NET description: Learn the basics you need to know about Azure and .NET. -ms.date: 06/20/2020 +ms.date: 05/05/2021 ms.topic: conceptual ms.custom: devx-track-dotnet ms.author: daberry @@ -10,8 +10,6 @@ author: daberry # Introduction to Azure and .NET -## What is Azure? - Azure is a cloud platform designed to simplify the process of building modern applications. Whether you choose to host your applications entirely in Azure or extend your on-premises applications with Azure services, Azure helps you create applications that are scalable, reliable, and maintainable. With extensive support in tools you already use like Visual Studio and Visual Studio Code and a comprehensive SDK library, Azure is designed to make you, the .NET developer productive right from the start. ## Application development scenarios on Azure diff --git a/docs/azure/media/azure-sdk-for-dotnet-overview.png b/docs/azure/media/azure-sdk-for-dotnet-overview.png index 159f179ae3b96..7803a66222e30 100644 Binary files a/docs/azure/media/azure-sdk-for-dotnet-overview.png and b/docs/azure/media/azure-sdk-for-dotnet-overview.png differ diff --git a/docs/azure/migration/choose.md b/docs/azure/migration/choose.md index 04e920280537c..ef7ec94ae9253 100644 --- a/docs/azure/migration/choose.md +++ b/docs/azure/migration/choose.md @@ -4,6 +4,7 @@ description: Learn which Azure migration path is right for your ASP.NET web appl author: CESARDELATORRE ms.author: cesardl ms.date: 03/01/2020 +recommendations: false --- # Choose the right Azure hosting option diff --git a/docs/azure/migration/sql.md b/docs/azure/migration/sql.md index 53d69ace012ca..1e928bb4bea9c 100644 --- a/docs/azure/migration/sql.md +++ b/docs/azure/migration/sql.md @@ -3,6 +3,7 @@ title: Migrate a SQL Server database to Azure description: Learn how to migrate a SQL Server database from on-premises SQL Server to Azure. ms.topic: how-to ms.date: 05/27/2020 +recommendations: false --- # Migrate a SQL Server database to Azure diff --git a/docs/azure/migration/vm.md b/docs/azure/migration/vm.md index 06ba6f231614f..fb7702e324495 100644 --- a/docs/azure/migration/vm.md +++ b/docs/azure/migration/vm.md @@ -3,6 +3,7 @@ title: Migrate an ASP.NET Web app to an Azure VM description: Learn how to migrate an ASP.NET Web application from on-premises to an Azure Virtual Machine. ms.topic: how-to ms.date: 06/20/2020 +recommendations: false --- # Migrate an ASP.NET Web application to an Azure Virtual Machine diff --git a/docs/azure/authentication.md b/docs/azure/sdk/authentication.md similarity index 96% rename from docs/azure/authentication.md rename to docs/azure/sdk/authentication.md index 3e977de47430e..9faa54bae5bde 100644 --- a/docs/azure/authentication.md +++ b/docs/azure/sdk/authentication.md @@ -26,7 +26,7 @@ The methods for using a connection string vary by product. [Refer to the documen ## Manage Azure resources -[!include[Create service principal](includes/create-sp.md)] +[!include[Create service principal](../includes/create-sp.md)] Now that the service principal is created, two options are available to authenticate to the service principal to create and manage resources. @@ -73,7 +73,7 @@ var azure = Microsoft.Azure.Management.Fluent.Azure File-based authentication allows you to put the service principal credentials in a plain text file and secure it within the file system. -[!include[File-based authentication](includes/file-based-auth.md)] +[!include[File-based authentication](../includes/file-based-auth.md)] Read the contents of the file and create the entry point `Azure` object to start working with the API: diff --git a/docs/azure/sdk/azure-sdk-for-dotnet.md b/docs/azure/sdk/azure-sdk-for-dotnet.md index fe63736694f87..a51ffd58f4d4f 100644 --- a/docs/azure/sdk/azure-sdk-for-dotnet.md +++ b/docs/azure/sdk/azure-sdk-for-dotnet.md @@ -21,10 +21,10 @@ The Azure SDK for .NET is available as series of NuGet packages that can be used To use an Azure SDK package in one of your .NET applications, you want to follow these steps. -1. **Locate the appropriate SDK package -** Use the [package list](../packages.md) to find the appropriate package for the Azure service you are working with. Be advised that most services have a client package for working with the service and a management package for creating and managing instances of the service. In most cases, you will want the client package. Install this package in your application using NuGet. +1. **Locate the appropriate SDK package -** Use the [package list](/dotnet/azure/sdk/packages) to find the appropriate package for the Azure service you are working with. Be advised that most services have a client package for working with the service and a management package for creating and managing instances of the service. In most cases, you will want the client package. Install this package in your application using NuGet. -2. **Set up authentication for your application -** To access Azure resources, your application will need to have the appropriate credentials and access rights assigned in Azure. Learn how to configure authentication in [Authenticating .NET applications to Azure](../authentication.md). +2. **Set up authentication for your application -** To access Azure resources, your application will need to have the appropriate credentials and access rights assigned in Azure. Learn how to configure authentication in [Authenticating .NET applications to Azure](/dotnet/azure/sdk/authentication). 3. **Write code using the SDK in your application -** When working with Azure services, your code will first create a client object to work with the service and then call methods on that client object to interact with the service. Both synchronous and asynchronous methods are provided. Examples of using each individual SDK package are provided throughout the Azure documentation. -4. **Configure logging for the SDK (optional) -** If you need to diagnose issues between your application and Azure, you can [enable logging in the Azure SDK for .NET](../logging.md). +4. **Configure logging for the SDK (optional) -** If you need to diagnose issues between your application and Azure, you can [enable logging in the Azure SDK for .NET](/dotnet/azure/sdk/logging). diff --git a/docs/azure/sdk/dependency-injection.md b/docs/azure/sdk/dependency-injection.md new file mode 100644 index 0000000000000..373992d28abc1 --- /dev/null +++ b/docs/azure/sdk/dependency-injection.md @@ -0,0 +1,245 @@ +--- +title: Dependency injection with the Azure SDK for .NET +description: Learn how to use dependency injection with the Azure SDK for .NET client libraries. +ms.date: 05/20/2021 +ms.author: pakrym +author: pakrym +--- + +# Dependency injection with the Azure SDK for .NET + +This article demonstrates how to register Azure service clients from the [latest Azure SDKs for .NET](https://azure.github.io/azure-sdk/releases/latest/index.html#net) in an ASP.NET Core app. Every ASP.NET Core app starts up by using the instructions provided in the `Startup` class. The `Startup` class includes a `ConfigureServices` method, which is an ideal place to configure clients. + +To configure the service clients, first add the following NuGet packages to your project: + +- [Microsoft.Extensions.Azure](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/extensions/Microsoft.Extensions.Azure/README.md) +- [Azure.Identity](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md) +- The `Azure.*` package you'd like to use. + +The sample code in this article uses Key Vault secrets and Blob Storage for demonstration purposes. + +```dotnetcli +dotnet add package Microsoft.Extensions.Azure +dotnet add package Azure.Identity +dotnet add package Azure.Security.KeyVault.Secrets +dotnet add package Azure.Storage.Blobs +``` + +## Register client + +In the `Startup.ConfigureServices` method, register a client for each service: + +```csharp +public void ConfigureServices(IServiceCollection services) +{ + services.AddAzureClients(builder => + { + // Add a KeyVault client + builder.AddSecretClient(keyVaultUrl); + + // Add a Storage account client + builder.AddBlobServiceClient(storageUrl); + + // Use DefaultAzureCredential by default + builder.UseCredential(new DefaultAzureCredential()); + }); + + services.AddControllers(); +} +``` + +In the preceding code: + +* You specify the `Uri`-typed `keyVaultUrl` and `storageUrl` variables. The [Store configuration separately from code](#store-configuration-separately-from-code) section shows how you can avoid specifying the URLs explicitly. +* is used for authentication. `DefaultAzureCredential` chooses the best authentication mechanism based on your environment, allowing you to move your app seamlessly from development to production with no code changes. + +## Use the registered clients + +With the clients registered in `Startup.ConfigureServices`, you can now use them: + +```csharp +[ApiController] +[Route("[controller]")] +public class MyApiController : ControllerBase +{ + private readonly BlobServiceClient _blobServiceClient; + + public MyApiController(BlobServiceClient blobServiceClient) + { + _blobServiceClient = blobServiceClient; + } + + // Get a list of all the blobs in the demo container + [HttpGet] + public async Task> Get() + { + var containerClient = _blobServiceClient.GetBlobContainerClient("demo"); + var results = new List(); + await foreach (BlobItem blob in containerClient.GetBlobsAsync()) + { + results.Add(blob.Name); + } + return results.ToArray(); + } +} +``` + +## Store configuration separately from code + +In the [Register client](#register-client) section, you explicitly specify the `keyVaultUrl` and `storageUrl` variables. This approach could cause problems when you run code against different environments during development and production. The .NET team suggests [storing such configurations in environment-dependent JSON files](/dotnet/core/extensions/configuration-providers#json-configuration-provider). For example, you can have an _appsettings.Development.json_ file containing development environment settings. Another _appsettings.Production.json_ file would contain production environment settings, and so on. The file format is: + +```json +{ + "AzureDefaults": { + "Diagnostics": { + "IsTelemetryDisabled": false, + "IsLoggingContentEnabled": true + }, + "Retry": { + "MaxRetries": 3, + "Mode": "Exponential" + } + }, + "KeyVault": { + "VaultUri": "https://mykeyvault.vault.azure.net" + }, + "Storage": { + "ServiceUri": "https://mydemoaccount.storage.windows.net" + } +} +``` + +You can add any options from into the JSON file's `AzureDefaults` section. One of the options is the retry policy. For more information, see [Configure a new retry policy](#configure-a-new-retry-policy). + +Since the `Configuration` object is injected from the host and stored inside the `Startup` constructor, you can use the following code in `Startup.ConfigureServices`: + +```csharp +public void ConfigureServices(IServiceCollection services) +{ + services.AddAzureClients(builder => + { + // Add a KeyVault client + builder.AddSecretClient(Configuration.GetSection("KeyVault")); + + // Add a storage account client + builder.AddBlobServiceClient(Configuration.GetSection("Storage")); + + // Use DefaultAzureCredential by default + builder.UseCredential(new DefaultAzureCredential()); + + // Set up any default settings + builder.ConfigureDefaults(Configuration.GetSection("AzureDefaults")); + }); + + services.AddControllers(); +} +``` + +## Configure multiple service clients with different names + +Assume you have two storage accounts: one for private information and one for public information. Your app transfers data from the public to private storage account after some operation. You need to have two storage service clients. To set up these clients in `Startup.ConfigureServices`: + +```csharp +public void ConfigureServices(IServiceCollection services) +{ + services.AddAzureClients(builder => + { + builder.AddBlobServiceClient(Configuration.GetSection("PublicStorage")); + builder.AddBlobServiceClient(Configuration.GetSection("PrivateStorage")) + .WithName("PrivateStorage"); + }); +} +``` + +In your controller, you can access the named service clients using : + +```csharp +public class HomeController : Controller +{ + private readonly BlobServiceClient _publicStorage; + private readonly BlobServiceClient _privateStorage; + + public HomeController( + BlobServiceClient defaultClient, + IAzureClientFactory clientFactory) + { + _publicStorage = defaultClient; + _privateStorage = clientFactory.GetClient("PrivateStorage"); + } +} +``` + +The unnamed service client is still available in the same way as before. Named clients are additive. + +## Configure a new retry policy + +At some point, you might want to change the default settings for a service client. You may want different retry settings or to use a different service API version, for example. You can set the retry settings globally or on a per-service basis. Assume you have the following _appsettings.json_ file: + +```json +{ + "AzureDefaults": { + "Retry": { + "maxTries": 3 + } + }, + "KeyVault": { + "VaultUri": "https://mykeyvault.vault.azure.net" + }, + "Storage": { + "ServiceUri": "https://store1.storage.windows.net" + }, + "CustomStorage": { + "ServiceUri": "https://store2.storage.windows.net" + } +} +``` + +You could change the retry policy depending on your needs like so: + +```csharp +public void ConfigureServices(IServiceCollection services) +{ + services.AddAzureClients(builder => + { + // Establish the global defaults + builder.ConfigureDefaults(Configuration.GetSection("AzureDefaults")); + builder.UseCredential(new DefaultAzureCredential()); + + // A Key Vault Secrets client using the global defaults + builder.AddSecretClient(Configuration.GetSection("KeyVault")); + + // A Storage client with a custom retry policy + builder.AddBlobServiceClient(Configuration.GetSection("Storage")) + .ConfigureOptions(options => options.Retry.MaxRetries = 10); + + // A named storage client with a different custom retry policy + builder.AddBlobServiceClient(Configuration.GetSection("CustomStorage")) + .WithName("CustomStorage") + .ConfigureOptions(options => + { + options.Retry.Mode = Azure.Core.RetryMode.Exponential; + options.Retry.MaxRetries = 5; + options.Retry.MaxDelay = TimeSpan.FromSections(120); + }); + }); +} +``` + +You can also place policy overrides in the _appsettings.json_ file: + +```json +{ + "KeyVault": { + "VaultUri": "https://mykeyvault.vault.azure.net", + "Retry": { + "maxRetries": 10 + } + } +} +``` + +## See also + +- [Dependency injection in .NET](/dotnet/core/extensions/dependency-injection) +- [Configuration in .NET](/dotnet/core/extensions/configuration) +- [Configuration in ASP.NET Core](/aspnet/core/fundamentals/configuration) diff --git a/docs/azure/logging.md b/docs/azure/sdk/logging.md similarity index 95% rename from docs/azure/logging.md rename to docs/azure/sdk/logging.md index 89176c7853e09..fc72e1b0072aa 100644 --- a/docs/azure/logging.md +++ b/docs/azure/sdk/logging.md @@ -41,7 +41,7 @@ HTTP response log entry: For request and response content: - Content stream as text or bytes depending on the Content-Type header. - > [!NOTE} + > [!NOTE] > Content logging is disabled by default. To enable it, set `Diagnostics.IsLoggingContentEnabled` to `true` in `ClientOptions`. Event logs are output usually at one of these three levels: @@ -66,7 +66,7 @@ using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsole ### Log to diagnostic traces -If you implement trace listeners, you can use the `CreateTraceLogger` method to log to the standard .NET event tracing mechanism ([`System.Diagnostics.Tracing`](/dotnet/api/system.diagnostics.tracing)). For more information on event tracing in .NET, see [Trace Listeners](../framework/debug-trace-profile/trace-listeners.md). This example specifies a log level of verbose: +If you implement trace listeners, you can use the `CreateTraceLogger` method to log to the standard .NET event tracing mechanism ([`System.Diagnostics.Tracing`](/dotnet/api/system.diagnostics.tracing)). For more information on event tracing in .NET, see [Trace Listeners](/dotnet/framework/debug-trace-profile/trace-listeners). This example specifies a log level of verbose: ```csharp using AzureEventSourceListener listener = AzureEventSourceListener.CreateTraceLogger(EventLevel.Verbose); @@ -95,4 +95,4 @@ using AzureEventSourceListener listener = new AzureEventSourceListener((e, messa - [Enable diagnostics logging for apps in Azure App Service](/azure/app-service/troubleshoot-diagnostic-logs) - Review [Azure security logging and auditing](/azure/security/fundamentals/log-audit) options - Learn how to work with [Azure platform logs](/azure/azure-monitor/platform/platform-logs-overview) -- Read more about [.NET Core logging and tracing](../core/diagnostics/logging-tracing.md) +- Read more about [.NET Core logging and tracing](/dotnet/core/diagnostics/logging-tracing) diff --git a/docs/azure/packages.md b/docs/azure/sdk/packages.md similarity index 76% rename from docs/azure/packages.md rename to docs/azure/sdk/packages.md index e8ca0b4fe29c0..aa2f8e86e9cb2 100644 --- a/docs/azure/packages.md +++ b/docs/azure/sdk/packages.md @@ -5,6 +5,7 @@ ms.custom: azure-sdk-dotnet author: camsoper ms.author: casoper ms.date: 07/29/2020 +ms.topic: reference --- # Azure SDK for .NET package index @@ -15,8 +16,8 @@ ms.date: 07/29/2020 ## Libraries using Azure.Core -[!INCLUDE [dotnet-new-releases](./includes/dotnet-new.md)] +[!INCLUDE [dotnet-new-releases](../includes/dotnet-new.md)] ## All libraries -[!INCLUDE [dotnet-all-libraries](./includes/dotnet-all.md)] +[!INCLUDE [dotnet-all-libraries](../includes/dotnet-all.md)] diff --git a/docs/azure/sdk/thread-safety.md b/docs/azure/sdk/thread-safety.md new file mode 100644 index 0000000000000..aa317e993b243 --- /dev/null +++ b/docs/azure/sdk/thread-safety.md @@ -0,0 +1,124 @@ +--- +title: Thread safety with the Azure SDK for .NET +description: Learn about thread safety in Azure SDK client objects and how this design impacts client lifetime management. +ms.date: 05/24/2021 +ms.author: pakrym +author: pakrym +--- + +# Thread safety and client lifetime management for Azure SDK objects + +This article helps you understand thread safety issues when using the Azure SDK. It also discusses how the design of the SDK impacts client lifetime management. You'll learn why it's unnecessary to dispose of Azure SDK client objects. + +## Thread safety + +All Azure SDK client objects are thread-safe and independent of each other. This design ensures that reusing client instances is always safe, even across threads. For example, the following code launches multiple tasks but is thread safe: + +```csharp +var client = new SecretClient( + new Uri(""), new DefaultAzureCredential()); + +foreach (var secretName in secretNames) +{ + // Using clients from parallel threads + Task.Run(() => Console.WriteLine(client.GetSecret(secretName).Value)); +} +``` + +Model objects used by SDK clients, whether input or output models, aren't thread-safe by default. Most use cases involving model objects only use a single thread. Therefore, the cost of implementing synchronization as a default behavior is too high for these objects. The following code illustrates a bug in which accessing a model from multiple threads could cause an undefined behavior: + +```csharp +KeyVaultSecret newSecret = client.SetSecret("secret", "value"); + +foreach (var tag in tags) +{ + // Don't use model type from parallel threads + Task.Run(() => newSecret.Properties.Tags[tag] = CalculateTagValue(tag)); +} + +client.UpdateSecretProperties(newSecret.Properties); +``` + +To access the model from different threads, you must implement your own synchronization code. For example: + +```csharp +KeyVaultSecret newSecret = client.SetSecret("secret", "value"); + +// Code omitted for brevity + +foreach (var tag in tags) +{ + Task.Run(() => + { + lock (newSecret) + { + newSecret.Properties.Tags[tag] = CalculateTagValue(tag); + } + ); +} + +client.UpdateSecretProperties(newSecret.Properties); +``` + +## Client lifetime + +Because Azure SDK clients are thread-safe, there's no reason to construct multiple SDK client objects for a given set of constructor parameters. Treat Azure SDK client objects as singletons once constructed. This recommendation is commonly implemented by registering Azure SDK client objects as singletons in the app's Inversion of Control (IoC) container. Dependency injection (DI) is used to obtain references to the SDK client object. The following example shows a singleton client object registration in an ASP.NET Core app's `Startup.ConfigureServices` method: + +```csharp +public void ConfigureServices(IServiceCollection services) +{ + services.AddControllersWithViews(); + + var blobServiceClient = new BlobServiceClient( + new Uri(""), new DefaultAzureCredential()); + services.AddSingleton(blobServiceClient); + + // Code omitted for brevity +} +``` + +For more information about implementing DI with the Azure SDK, see [Dependency injection with the Azure SDK for .NET](./dependency-injection.md). + +Alternatively, you may create an SDK client instance and provide it to methods that require a client. The point is to avoid unnecessary instantiations of the same SDK client object with the same parameters. It's both unnecessary and wasteful. + +## Clients aren't disposable + +Two final questions that often come up are: + +* Do I need to dispose of Azure SDK client objects when I'm finished using them? +* Why aren't HTTP-based Azure SDK client objects disposable? + +Internally, all Azure SDK clients use a single shared `HttpClient` instance. The clients don't create any other resources that need to be actively freed. The shared `HttpClient` instance persists throughout the entire application lifetime. + +```csharp +// Both clients reuse the shared HttpClient and don't need to be disposed +var blobClient = new BlobClient(new Uri(sasUri)); +var blobClient2 = new BlobClient(new Uri(sasUri2)); +``` + +It's possible to provide a custom instance of `HttpClient` to an Azure SDK client object. In this case, you become responsible for managing the `HttpClient` lifetime and properly disposing of it at the right time. + +```csharp +var httpClient = new HttpClient(); + +var clientOptions = new BlobClientOptions() +{ + Transport = new HttpClientTransport(httpClient) +}; + +// Both clients would use the HttpClient instance provided in clientOptions +var blobClient = new BlobClient(new Uri(sasUri), clientOptions); +var blobClient2 = new BlobClient(new Uri(sasUri2), clientOptions); + +// Code omitted for brevity + +// You're responsible for properly disposing httpClient some time later +httpClient.Dispose(); +``` + +Further guidance for properly managing and disposing of `HttpClient` instances can be found in the documentation. + +## See also + +- [Dependency injection with the Azure SDK for .NET](./dependency-injection.md) +- [Dependency injection in .NET](/dotnet/core/extensions/dependency-injection) diff --git a/docs/breadcrumb/toc.yml b/docs/breadcrumb/toc.yml index 3eccbac34fa06..3d863a83fa7fb 100644 --- a/docs/breadcrumb/toc.yml +++ b/docs/breadcrumb/toc.yml @@ -318,12 +318,19 @@ items: - name: Tutorials tocHref: /dotnet/csharp/tour-of-csharp/tutorials/ topicHref: /dotnet/csharp/tour-of-csharp/tutorials/index - - name: Tutorials - tocHref: /dotnet/csharp/tutorials/ - topicHref: /dotnet/csharp/tutorials/index + - name: Fundamentals + tocHref: /dotnet/csharp/fundamentals/ + topicHref: /dotnet/csharp/fundamentals/type-system/index - name: What's new tocHref: /dotnet/csharp/whats-new/ topicHref: /dotnet/csharp/whats-new/index + items: + - name: Tutorials + tocHref: /dotnet/csharp/whats-new/tutorials/ + topicHref: /dotnet/csharp/whats-new/tutorials/records + - name: Tutorials + tocHref: /dotnet/csharp/tutorials/ + topicHref: /dotnet/csharp/tutorials/index - name: .NET Compiler Platform SDK tocHref: /dotnet/csharp/roslyn-sdk/ topicHref: /dotnet/csharp/roslyn-sdk/index @@ -429,7 +436,7 @@ items: - name: Compiler options tocHref: /dotnet/csharp/language-reference/compiler-options/ topicHref: /dotnet/csharp/language-reference/compiler-options/index - - name: Compiler errors + - name: Compiler messages tocHref: /dotnet/csharp/language-reference/compiler-messages/ topicHref: /dotnet/csharp/language-reference/compiler-messages/index - name: C# 6.0 draft specification @@ -450,6 +457,9 @@ items: - name: C# 8.0 language proposals tocHref: /dotnet/csharp/language-reference/proposals/csharp-8.0/ topicHref: /dotnet/csharp/language-reference/proposals/csharp-8.0/index + - name: Compiler messages + tocHref: /dotnet/csharp/misc + topicHref: /dotnet/csharp/language-reference/compiler-messages/index - name: F# guide tocHref: /dotnet/fsharp/ topicHref: /dotnet/fsharp/index diff --git a/docs/core/additional-tools/dotnet-svcutil-guide.md b/docs/core/additional-tools/dotnet-svcutil-guide.md index 25334cb0e9391..f03f9d5d610e4 100644 --- a/docs/core/additional-tools/dotnet-svcutil-guide.md +++ b/docs/core/additional-tools/dotnet-svcutil-guide.md @@ -174,7 +174,7 @@ If you have any questions or feedback, [open an issue on GitHub](https://github. ## Release notes -- Refer to the [Release notes](https://github.com/dotnet/wcf/blob/master/release-notes/dotnet-svcutil-notes.md) for updated release information, including known issues. +- Refer to the [Release notes](https://github.com/dotnet/wcf/blob/main/release-notes/dotnet-svcutil-notes.md) for updated release information, including known issues. ## Information diff --git a/docs/core/additional-tools/self-signed-certificates-guide.md b/docs/core/additional-tools/self-signed-certificates-guide.md index bab6be65048a3..ea7392e48b8ed 100644 --- a/docs/core/additional-tools/self-signed-certificates-guide.md +++ b/docs/core/additional-tools/self-signed-certificates-guide.md @@ -9,7 +9,7 @@ ms.date: 11/19/2020 When using self-signed certificates, there are different ways to create and use them for development and testing scenarios. In this guide, you'll cover using self-signed certificates with `dotnet dev-certs`, and other options like `PowerShell` and `OpenSSL`. -You can then validate that the certificate will load using an example such as an [ASP.NET Core app](https://github.com/dotnet/dotnet-docker/blob/master/samples/run-aspnetcore-https-development.md) hosted in a container. +You can then validate that the certificate will load using an example such as an [ASP.NET Core app](https://github.com/dotnet/dotnet-docker/blob/main/samples/run-aspnetcore-https-development.md) hosted in a container. ## Prerequisites @@ -41,7 +41,7 @@ Navigate to the repository locally and open up the workspace in an editor. > [!NOTE] > If you're looking to use dotnet publish parameters to *trim* the deployment, you should make sure that the appropriate dependencies are included for supporting SSL certificates. -Update the [dotnet-docker\samples\aspnetapp\aspnetapp.csproj](https://github.com/dotnet/dotnet-docker/blob/master/samples/aspnetapp/aspnetapp/aspnetapp.csproj) to ensure that the appropriate assemblies are included in the container. For reference, check how to update the .csproj file to [support ssl certificates](../deploying/trim-self-contained.md#support-for-ssl-certificates) when using trimming for self-contained deployments. +Update the [dotnet-docker\samples\aspnetapp\aspnetapp.csproj](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/aspnetapp/aspnetapp.csproj) to ensure that the appropriate assemblies are included in the container. For reference, check how to update the .csproj file to [support ssl certificates](../deploying/trim-self-contained.md#support-for-ssl-certificates) when using trimming for self-contained deployments. Make sure the `aspnetapp.csproj` includes the appropriate target framework: @@ -96,7 +96,7 @@ docker build -t aspnetapp:my-sample -f Dockerfile . For this guide, the [sample aspnetapp](https://hub.docker.com/_/microsoft-dotnet-samples) should be checked for .NET 5. -Check sample app [Dockerfile](https://github.com/dotnet/dotnet-docker/blob/master/samples/aspnetapp/Dockerfile) is using .NET 5. +Check sample app [Dockerfile](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/Dockerfile) is using .NET 5. Depending on the host OS, the ASP.NET runtime may need to be updated. For example, changing from `mcr.microsoft.com/dotnet/aspnet:5.0-nanoservercore-2009 AS runtime` to `mcr.microsoft.com/dotnet/aspnet:5.0-windowsservercore-ltsc2019 AS runtime` in the Dockerfile will help with targeting the appropriate Windows runtime. @@ -143,7 +143,7 @@ Make sure the `aspnetapp.csproj` includes the appropriate target framework: > [!NOTE] > If you want to use `dotnet publish` parameters to *trim* the deployment, make sure that the appropriate dependencies are included for supporting SSL certificates. -Update the [dotnet-docker\samples\aspnetapp\aspnetapp.csproj](https://github.com/dotnet/dotnet-docker/blob/master/samples/aspnetapp/aspnetapp/aspnetapp.csproj) to ensure that the appropriate assemblies are included in the container. For reference, check how to update the .csproj file to [support ssl certificates](../deploying/trim-self-contained.md#support-for-ssl-certificates) when using trimming for self-contained deployments. +Update the [dotnet-docker\samples\aspnetapp\aspnetapp.csproj](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/aspnetapp/aspnetapp.csproj) to ensure that the appropriate assemblies are included in the container. For reference, check how to update the .csproj file to [support ssl certificates](../deploying/trim-self-contained.md#support-for-ssl-certificates) when using trimming for self-contained deployments. Make sure you're pointing to the sample app. @@ -205,7 +205,7 @@ dotnet dev-certs https --clean ### With PowerShell -You can use PowerShell to generate self-signed certificates. The [PKI Client](/powershell/module/pkiclient/new-selfsignedcertificate?preserve-view=true&view=win10-ps) can be used to generate a self-signed certificate. +You can use PowerShell to generate self-signed certificates. The [PKI Client](/powershell/module/pki/new-selfsignedcertificate) can be used to generate a self-signed certificate. ```powershell $cert = New-SelfSignedCertificate -DnsName @("contoso.com", "www.contoso.com") -CertStoreLocation "cert:\LocalMachine\My" diff --git a/docs/core/additional-tools/vscode-dotnet-runtime.md b/docs/core/additional-tools/vscode-dotnet-runtime.md index 7ff73c812138d..f072f24475166 100644 --- a/docs/core/additional-tools/vscode-dotnet-runtime.md +++ b/docs/core/additional-tools/vscode-dotnet-runtime.md @@ -15,9 +15,9 @@ To ensure that the .NET install tool for extension authors is the right fit for > [!NOTE] > This tool can be used to install the .NET runtime only, it currently does not have the capability to install the .NET SDK. -Once you have verified that the .NET install tool for extension authors fits your needs, you can take a dependency on it in your [extension manifest](https://code.visualstudio.com/api/references/extension-manifest) and begin using the commands we expose with the [VS Code API](https://code.visualstudio.com/api/extension-guides/command#programmatically-executing-a-command). You can find the list of commands this extension exposes on our [GitHub](https://github.com/dotnet/vscode-dotnet-runtime/blob/master/Documentation/commands.md). +Once you have verified that the .NET install tool for extension authors fits your needs, you can take a dependency on it in your [extension manifest](https://code.visualstudio.com/api/references/extension-manifest) and begin using the commands we expose with the [VS Code API](https://code.visualstudio.com/api/extension-guides/command#programmatically-executing-a-command). You can find the list of commands this extension exposes on our [GitHub](https://github.com/dotnet/vscode-dotnet-runtime/blob/main/Documentation/commands.md). -Check out this [sample extension](https://github.com/dotnet/vscode-dotnet-runtime/tree/master/sample) to see these steps in action. +Check out this [sample extension](https://github.com/dotnet/vscode-dotnet-runtime/tree/main/sample) to see these steps in action. For more examples, check out these open source extensions that currently leverage this tool: @@ -27,4 +27,4 @@ For more examples, check out these open source extensions that currently leverag ## Getting started: end users -In general, the end user should not need to interact with the .NET install tool for extension authors at all. If you are having problems with the extension, check out our [troubleshooting page](https://github.com/dotnet/vscode-dotnet-runtime/blob/master/Documentation/troubleshooting.md) or file an issue on our [GitHub](https://github.com/dotnet/vscode-dotnet-runtime/issues). +In general, the end user should not need to interact with the .NET install tool for extension authors at all. If you are having problems with the extension, check out our [troubleshooting page](https://github.com/dotnet/vscode-dotnet-runtime/blob/main/Documentation/troubleshooting-runtime.md) or file an issue on our [GitHub](https://github.com/dotnet/vscode-dotnet-runtime/issues). diff --git a/docs/core/additional-tools/wcf-web-service-reference-guide.md b/docs/core/additional-tools/wcf-web-service-reference-guide.md index e0cadf27f99b1..d22a7bab54b5d 100644 --- a/docs/core/additional-tools/wcf-web-service-reference-guide.md +++ b/docs/core/additional-tools/wcf-web-service-reference-guide.md @@ -32,11 +32,11 @@ Using the **ASP.NET Core Web Application** project template as an example, this The **Connected Services** page appears as shown in the following image: - ![Visual Studio Connected Services tab for .NET Core](./media/wcf-web-service-reference-guide/wcfcs-ConnectedServicesPage.png) + ![Visual Studio Connected Services tab for .NET Core](./media/wcf-web-service-reference-guide/wcfcs-connectedservicespage.png) 2. On the **Connected Services** page, click **Microsoft WCF Web Service Reference Provider**. This brings up the **Configure WCF Web Service Reference** wizard: - ![Visual Studio Service Endpoint tab for .NET Core](./media/wcf-web-service-reference-guide/wcfcs-ServiceEndpointPage.png) + ![Visual Studio Service Endpoint tab for .NET Core](./media/wcf-web-service-reference-guide/wcfcs-serviceendpointpage.png) 3. Select a service. @@ -52,7 +52,7 @@ Using the **ASP.NET Core Web Application** project template as an example, this 4. The **Data Type Options** form enables you to refine the generated service reference configuration settings: - ![Visual Studio Data type options tab for .NET Core](./media/wcf-web-service-reference-guide/wcfcs-DataTypesPage.png) + ![Visual Studio Data type options tab for .NET Core](./media/wcf-web-service-reference-guide/wcfcs-datatypespage.png) > [!NOTE] > The **Reuse types in referenced assemblies** check box option is useful when data types needed for service reference code generation are defined in one of your project's referenced assemblies. It's important to reuse those existing data types to avoid compile-time type clash or runtime issues. @@ -67,7 +67,7 @@ While displaying progress, the tool: - Generates the service reference code in a file named *reference.cs*, and adds it to your project under the **Connected Services** node. - Updates the project file (.csproj) with NuGet package references required to compile and run on the target platform. -![Visual Studio Progress window](./media/wcf-web-service-reference-guide/wcfcs-ProgressWindow.png) +![Visual Studio Progress window](./media/wcf-web-service-reference-guide/wcfcs-progresswindow.png) When these processes complete, you can create an instance of the generated WCF client type and invoke the service operations. @@ -75,7 +75,7 @@ When these processes complete, you can create an instance of the generated WCF c - [Get started with Windows Communication Foundation applications](../../framework/wcf/getting-started-tutorial.md) - [Windows Communication Foundation services and WCF data services in Visual Studio](/visualstudio/data-tools/windows-communication-foundation-services-and-wcf-data-services-in-visual-studio) -- [WCF supported features on .NET Core](https://github.com/dotnet/wcf/blob/master/release-notes/SupportedFeatures-v2.1.0.md) +- [WCF supported features on .NET Core](https://github.com/dotnet/wcf/blob/main/release-notes/SupportedFeatures-v2.1.0.md) ## Feedback & questions @@ -83,4 +83,4 @@ If you have any product feedback, report it at [Developer Community](https://aka ## Release notes -- Refer to the [Release notes](https://github.com/dotnet/wcf/blob/master/release-notes/WCF-Web-Service-Reference-notes.md) for updated release information, including known issues. +- Refer to the [Release notes](https://github.com/dotnet/wcf/blob/main/release-notes/WCF-Web-Service-Reference-notes.md) for updated release information, including known issues. diff --git a/docs/core/compatibility/2.1.md b/docs/core/compatibility/2.1.md index 7ffb92fddceab..9e166e63cd418 100644 --- a/docs/core/compatibility/2.1.md +++ b/docs/core/compatibility/2.1.md @@ -9,9 +9,14 @@ If you're migrating to version 2.1 of .NET Core, the breaking changes listed in ## Core .NET libraries +- [Path APIs don't throw an exception for invalid characters](#path-apis-dont-throw-an-exception-for-invalid-characters) - [Private fields added to built-in struct types](#private-fields-added-to-built-in-struct-types) - [OpenSSL versions on macOS](#openssl-versions-on-macos) +[!INCLUDE [path-apis-dont-throw-exception-for-invalid-paths](../../../includes/core-changes/corefx/2.1/path-apis-dont-throw-exception-for-invalid-paths.md)] + +*** + [!INCLUDE[Private fields added to built-in struct types](../../../includes/core-changes/corefx/2.1/instantiate-struct.md)] *** diff --git a/docs/core/compatibility/5.0.md b/docs/core/compatibility/5.0.md index 93f329052a922..93121bd71c4b2 100644 --- a/docs/core/compatibility/5.0.md +++ b/docs/core/compatibility/5.0.md @@ -128,6 +128,12 @@ If you're migrating an app to .NET 5, the breaking changes listed here might aff - [Streams allow successive Begin operations](networking/5.0/negotiatestream-sslstream-dont-fail-on-successive-begin-calls.md) - [WinHttpHandler removed from .NET runtime](networking/5.0/winhttphandler-removed-from-runtime.md) +## SDK + +- [Error generated when executable project references mismatched executable](sdk/5.0/referencing-executable-generates-error.md) +- [OutputType set to WinExe](sdk/5.0/automatically-infer-winexe-output-type.md) +- [WinForms and WPF apps use Microsoft.NET.Sdk](sdk/5.0/sdk-and-target-framework-change.md) + ## Security - [Code access security APIs are obsolete](core-libraries/5.0/code-access-security-apis-obsolete.md) @@ -146,17 +152,17 @@ If you're migrating an app to .NET 5, the breaking changes listed here might aff ## Windows Forms - [Native code can't access Windows Forms objects](windows-forms/5.0/winforms-objects-not-accessible-from-native-code.md) -- [OutputType set to WinExe](windows-forms/5.0/automatically-infer-winexe-output-type.md) +- [OutputType set to WinExe](sdk/5.0/automatically-infer-winexe-output-type.md) - [DataGridView doesn't reset custom fonts](windows-forms/5.0/datagridview-doesnt-reset-custom-font-settings.md) - [Methods throw ArgumentException](windows-forms/5.0/invalid-args-cause-argumentexception.md) - [Methods throw ArgumentNullException](windows-forms/5.0/null-args-cause-argumentnullexception.md) - [Properties throw ArgumentOutOfRangeException](windows-forms/5.0/invalid-args-cause-argumentoutofrangeexception.md) - [TextFormatFlags.ModifyString is obsolete](windows-forms/5.0/modifystring-field-of-textformatflags-obsolete.md) - [DataGridView APIs throw InvalidOperationException](windows-forms/5.0/null-owner-causes-invalidoperationexception.md) -- [WinForms apps use Microsoft.NET.Sdk](windows-forms/5.0/sdk-and-target-framework-change.md) +- [WinForms apps use Microsoft.NET.Sdk](sdk/5.0/sdk-and-target-framework-change.md) - [Removed status bar controls](windows-forms/5.0/winforms-deprecated-controls.md) ## WPF -- [OutputType set to WinExe](windows-forms/5.0/automatically-infer-winexe-output-type.md) -- [WPF apps use Microsoft.NET.Sdk](windows-forms/5.0/sdk-and-target-framework-change.md) +- [OutputType set to WinExe](sdk/5.0/automatically-infer-winexe-output-type.md) +- [WPF apps use Microsoft.NET.Sdk](sdk/5.0/sdk-and-target-framework-change.md) diff --git a/docs/core/compatibility/6.0.md b/docs/core/compatibility/6.0.md index 2c0e8a17c14a3..8381f34b2ce22 100644 --- a/docs/core/compatibility/6.0.md +++ b/docs/core/compatibility/6.0.md @@ -1,8 +1,8 @@ --- title: Breaking changes in .NET 6 description: Navigate to the breaking changes in .NET 6. -ms.date: 02/24/2021 -no-loc: [Blazor] +ms.date: 05/06/2021 +no-loc: [Blazor, Razor, Kestrel] --- # Breaking changes in .NET 6 @@ -13,23 +13,41 @@ If you're migrating an app to .NET 6, the breaking changes listed here might aff ## ASP.NET Core -- [Nullable reference type annotations changed](aspnet-core/6.0/nullable-reference-type-annotations-changed.md) -- [Obsoleted and removed APIs](aspnet-core/6.0/obsolete-removed-apis.md) +- [AddDataAnnotationsValidation method made obsolete](aspnet-core/6.0/adddataannotationsvalidation-obsolete.md) +- [Assemblies removed from Microsoft.AspNetCore.App shared framework](aspnet-core/6.0/assemblies-removed-from-shared-framework.md) - [Blazor: Parameter name changed in RequestImageFileAsync method](aspnet-core/6.0/blazor-parameter-name-changed-in-method.md) - [Blazor: WebEventDescriptor.EventArgsType property replaced](aspnet-core/6.0/blazor-eventargstype-property-replaced.md) +- [Changed MessagePack library in @microsoft/signalr-protocol-msgpack](aspnet-core/6.0/messagepack-library-change.md) - [Kestrel: Log message attributes changed](aspnet-core/6.0/kestrel-log-message-attributes-changed.md) +- [Microsoft.AspNetCore.Http.Features split](aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md) - [Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports](aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md) +- [Middleware: New Use overload](aspnet-core/6.0/middleware-new-use-overload.md) +- [MVC doesn't buffer IAsyncEnumerable types when using System.Text.Json](aspnet-core/6.0/iasyncenumerable-not-buffered-by-mvc.md) +- [Nullable reference type annotations changed](aspnet-core/6.0/nullable-reference-type-annotations-changed.md) +- [Obsoleted and removed APIs](aspnet-core/6.0/obsolete-removed-apis.md) +- [PreserveCompilationContext not configured by default](aspnet-core/6.0/preservecompilationcontext-not-set-by-default.md) +- [Razor: Compiler no longer produces a Views assembly](aspnet-core/6.0/razor-compiler-doesnt-produce-views-assembly.md) - [Razor: RazorEngine APIs marked obsolete](aspnet-core/6.0/razor-engine-apis-obsolete.md) +- [SignalR: Java Client updated to RxJava3](aspnet-core/6.0/signalr-java-client-updated.md) ## Core .NET libraries - [Changes to nullable reference type annotations](core-libraries/6.0/nullable-ref-type-annotation-changes.md) +- [Environment.ProcessorCount behavior on Windows](core-libraries/6.0/environment-processorcount-on-windows.md) +- [New System.Linq.Queryable method overloads](core-libraries/6.0/additional-linq-queryable-method-overloads.md) +- [API obsoletions with non-default diagnostic IDs](core-libraries/6.0/obsolete-apis-with-custom-diagnostics.md) - [Some parameters in Stream-derived types are renamed](core-libraries/6.0/parameters-renamed-on-stream-derived-types.md) - [Standard numeric format parsing precision](core-libraries/6.0/numeric-format-parsing-handles-higher-precision.md) +- [Unhandled exceptions from a BackgroundService](core-libraries/6.0/hosting-exception-handling.md) + +## Networking + +- [WebRequest, WebClient, and ServicePoint are obsolete](networking/6.0/webrequest-deprecated.md) ## Windows Forms - [Selected TableLayoutSettings properties throw InvalidEnumArgumentException](windows-forms/6.0/tablelayoutsettings-apis-throw-invalidenumargumentexception.md) +- [DataGridView-related APIs now throw InvalidOperationException](windows-forms/6.0/null-owner-causes-invalidoperationexception.md) - [NotifyIcon.Text maximum text length increased](windows-forms/6.0/notifyicon-text-max-text-length-increased.md) - [Some APIs throw ArgumentNullException](windows-forms/6.0/apis-throw-argumentnullexception.md) - [TreeNodeCollection.Item throws exception if node is assigned elsewhere](windows-forms/6.0/treenodecollection-item-throws-argumentexception.md) diff --git a/docs/core/compatibility/aspnet-core/5.0/authentication-aad-packages-obsolete.md b/docs/core/compatibility/aspnet-core/5.0/authentication-aad-packages-obsolete.md index 78ac7b34e76d6..aaa6d9d35e877 100644 --- a/docs/core/compatibility/aspnet-core/5.0/authentication-aad-packages-obsolete.md +++ b/docs/core/compatibility/aspnet-core/5.0/authentication-aad-packages-obsolete.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Authentication: AzureAD.UI and AzureADB2C.UI APIs and packages marked obsolete" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Authentication: AzureAD.UI and AzureADB2C.UI APIs and packages marked obsolete" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/authorization-resource-in-endpoint-routing.md b/docs/core/compatibility/aspnet-core/5.0/authorization-resource-in-endpoint-routing.md index 43f5c2c9ad63f..84d01d60c7bed 100644 --- a/docs/core/compatibility/aspnet-core/5.0/authorization-resource-in-endpoint-routing.md +++ b/docs/core/compatibility/aspnet-core/5.0/authorization-resource-in-endpoint-routing.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Authorization: Resource in endpoint routing is HttpContext" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Authorization: Resource in endpoint routing is HttpContext" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/azure-integration-packages-removed.md b/docs/core/compatibility/aspnet-core/5.0/azure-integration-packages-removed.md index 1f441ccbfa726..9c4d9fd1b766b 100644 --- a/docs/core/compatibility/aspnet-core/5.0/azure-integration-packages-removed.md +++ b/docs/core/compatibility/aspnet-core/5.0/azure-integration-packages-removed.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Azure: Microsoft-prefixed Azure integration packages removed" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Azure: Microsoft-prefixed Azure integration packages removed" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/blazor-browser-support-updated.md b/docs/core/compatibility/aspnet-core/5.0/blazor-browser-support-updated.md index 3385a9a9066bf..78a7e8407cebc 100644 --- a/docs/core/compatibility/aspnet-core/5.0/blazor-browser-support-updated.md +++ b/docs/core/compatibility/aspnet-core/5.0/blazor-browser-support-updated.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Blazor: Updated browser support" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Blazor: Updated browser support" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 no-loc: [Blazor, "Blazor WebAssembly", "Blazor Server"] diff --git a/docs/core/compatibility/aspnet-core/5.0/blazor-components-trim-insignificant-whitespace.md b/docs/core/compatibility/aspnet-core/5.0/blazor-components-trim-insignificant-whitespace.md index fbcd65930758c..0aa6dba824b56 100644 --- a/docs/core/compatibility/aspnet-core/5.0/blazor-components-trim-insignificant-whitespace.md +++ b/docs/core/compatibility/aspnet-core/5.0/blazor-components-trim-insignificant-whitespace.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Blazor: Insignificant whitespace trimmed from components at compile time" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Blazor: Insignificant whitespace trimmed from components at compile time" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/blazor-jsobjectreference-to-internal.md b/docs/core/compatibility/aspnet-core/5.0/blazor-jsobjectreference-to-internal.md index 6e61804fd1714..4a885b1dce80e 100644 --- a/docs/core/compatibility/aspnet-core/5.0/blazor-jsobjectreference-to-internal.md +++ b/docs/core/compatibility/aspnet-core/5.0/blazor-jsobjectreference-to-internal.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Blazor: JSObjectReference and JSInProcessObjectReference types changed to internal" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Blazor: JSObjectReference and JSInProcessObjectReference types changed to internal" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/blazor-packages-target-framework-changed.md b/docs/core/compatibility/aspnet-core/5.0/blazor-packages-target-framework-changed.md index 7cb7cdabb9049..5bed46f598c2a 100644 --- a/docs/core/compatibility/aspnet-core/5.0/blazor-packages-target-framework-changed.md +++ b/docs/core/compatibility/aspnet-core/5.0/blazor-packages-target-framework-changed.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Blazor: Target framework of NuGet packages changed" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Blazor: Target framework of NuGet packages changed" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/blazor-protectedbrowserstorage-moved.md b/docs/core/compatibility/aspnet-core/5.0/blazor-protectedbrowserstorage-moved.md index 977caeca60aed..4773eac4e0695 100644 --- a/docs/core/compatibility/aspnet-core/5.0/blazor-protectedbrowserstorage-moved.md +++ b/docs/core/compatibility/aspnet-core/5.0/blazor-protectedbrowserstorage-moved.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Blazor: ProtectedBrowserStorage feature moved to shared framework" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Blazor: ProtectedBrowserStorage feature moved to shared framework" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/blazor-rendertreeframe-fields-become-properties.md b/docs/core/compatibility/aspnet-core/5.0/blazor-rendertreeframe-fields-become-properties.md index bc84ebcd13e7f..83880b2e6dffb 100644 --- a/docs/core/compatibility/aspnet-core/5.0/blazor-rendertreeframe-fields-become-properties.md +++ b/docs/core/compatibility/aspnet-core/5.0/blazor-rendertreeframe-fields-become-properties.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Blazor: RenderTreeFrame readonly public fields have become properties" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Blazor: RenderTreeFrame readonly public fields have become properties" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/blazor-routing-logic-changed.md b/docs/core/compatibility/aspnet-core/5.0/blazor-routing-logic-changed.md index 49660cce0893f..03abb2cc2a49a 100644 --- a/docs/core/compatibility/aspnet-core/5.0/blazor-routing-logic-changed.md +++ b/docs/core/compatibility/aspnet-core/5.0/blazor-routing-logic-changed.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Blazor: Changes to routing logic in Blazor apps" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Blazor: Changes to routing logic in Blazor apps" -author: scottaddie ms.author: scaddie ms.date: 12/14/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/blazor-static-web-assets-validation-logic-updated.md b/docs/core/compatibility/aspnet-core/5.0/blazor-static-web-assets-validation-logic-updated.md index b5494a1381641..e29e1f6439e30 100644 --- a/docs/core/compatibility/aspnet-core/5.0/blazor-static-web-assets-validation-logic-updated.md +++ b/docs/core/compatibility/aspnet-core/5.0/blazor-static-web-assets-validation-logic-updated.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Blazor: Updated validation logic for static web assets" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Blazor: Updated validation logic for static web assets" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/extensions-package-reference-changes.md b/docs/core/compatibility/aspnet-core/5.0/extensions-package-reference-changes.md index 8f7e9672095b7..eec143e4f2399 100644 --- a/docs/core/compatibility/aspnet-core/5.0/extensions-package-reference-changes.md +++ b/docs/core/compatibility/aspnet-core/5.0/extensions-package-reference-changes.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Extensions: Package reference changes affecting some NuGet packages" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Extensions: Package reference changes affecting some NuGet packages" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/http-badhttprequestexception-obsolete.md b/docs/core/compatibility/aspnet-core/5.0/http-badhttprequestexception-obsolete.md index bdeee0d7b10d4..a4d7fd272fbdd 100644 --- a/docs/core/compatibility/aspnet-core/5.0/http-badhttprequestexception-obsolete.md +++ b/docs/core/compatibility/aspnet-core/5.0/http-badhttprequestexception-obsolete.md @@ -1,7 +1,6 @@ --- title: "Breaking change: HTTP: Kestrel and IIS BadHttpRequestException types marked obsolete and replaced" description: "Learn about the breaking change in ASP.NET Core 5.0 titled HTTP: Kestrel and IIS BadHttpRequestException types marked obsolete and replaced" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/http-httpclient-instances-log-integer-status-codes.md b/docs/core/compatibility/aspnet-core/5.0/http-httpclient-instances-log-integer-status-codes.md index 1ec09b6f2315a..3ee6ac1df9783 100644 --- a/docs/core/compatibility/aspnet-core/5.0/http-httpclient-instances-log-integer-status-codes.md +++ b/docs/core/compatibility/aspnet-core/5.0/http-httpclient-instances-log-integer-status-codes.md @@ -1,7 +1,6 @@ --- title: "Breaking change: HTTP: HttpClient instances created by IHttpClientFactory log integer status codes" description: "Learn about the breaking change in ASP.NET Core 5.0 titled HTTP: HttpClient instances created by IHttpClientFactory log integer status codes" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/httpsys-client-certificate-renegotiation-disabled-by-default.md b/docs/core/compatibility/aspnet-core/5.0/httpsys-client-certificate-renegotiation-disabled-by-default.md index 4eb886f97dbe8..43f09b87232d5 100644 --- a/docs/core/compatibility/aspnet-core/5.0/httpsys-client-certificate-renegotiation-disabled-by-default.md +++ b/docs/core/compatibility/aspnet-core/5.0/httpsys-client-certificate-renegotiation-disabled-by-default.md @@ -1,7 +1,6 @@ --- title: "Breaking change: HttpSys: Client certificate renegotiation disabled by default" description: "Learn about the breaking change in ASP.NET Core 5.0 titled HttpSys: Client certificate renegotiation disabled by default" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/iis-urlrewrite-middleware-query-strings-are-preserved.md b/docs/core/compatibility/aspnet-core/5.0/iis-urlrewrite-middleware-query-strings-are-preserved.md index 900a45812cd0c..6f32900ab4098 100644 --- a/docs/core/compatibility/aspnet-core/5.0/iis-urlrewrite-middleware-query-strings-are-preserved.md +++ b/docs/core/compatibility/aspnet-core/5.0/iis-urlrewrite-middleware-query-strings-are-preserved.md @@ -1,7 +1,6 @@ --- title: "Breaking change: IIS: UrlRewrite middleware query strings are preserved" description: "Learn about the breaking change in ASP.NET Core 5.0 titled IIS: UrlRewrite middleware query strings are preserved" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/kestrel-configuration-changes-at-run-time-detected-by-default.md b/docs/core/compatibility/aspnet-core/5.0/kestrel-configuration-changes-at-run-time-detected-by-default.md index 4717e11475a09..6ba9b27c84689 100644 --- a/docs/core/compatibility/aspnet-core/5.0/kestrel-configuration-changes-at-run-time-detected-by-default.md +++ b/docs/core/compatibility/aspnet-core/5.0/kestrel-configuration-changes-at-run-time-detected-by-default.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Kestrel: Configuration changes at run time detected by default" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Kestrel: Configuration changes at run time detected by default" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/kestrel-default-supported-tls-protocol-versions-changed.md b/docs/core/compatibility/aspnet-core/5.0/kestrel-default-supported-tls-protocol-versions-changed.md index 16ede8d6916ee..61320fbda3d34 100644 --- a/docs/core/compatibility/aspnet-core/5.0/kestrel-default-supported-tls-protocol-versions-changed.md +++ b/docs/core/compatibility/aspnet-core/5.0/kestrel-default-supported-tls-protocol-versions-changed.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Kestrel: Default supported TLS protocol versions changed" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Kestrel: Default supported TLS protocol versions changed" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/kestrel-disables-http2-over-tls.md b/docs/core/compatibility/aspnet-core/5.0/kestrel-disables-http2-over-tls.md index 70cebbbb956e4..4a7b51ace3e5c 100644 --- a/docs/core/compatibility/aspnet-core/5.0/kestrel-disables-http2-over-tls.md +++ b/docs/core/compatibility/aspnet-core/5.0/kestrel-disables-http2-over-tls.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Kestrel: HTTP/2 disabled over TLS on incompatible Windows versions" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Kestrel: HTTP/2 disabled over TLS on incompatible Windows versions" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/kestrel-libuv-transport-obsolete.md b/docs/core/compatibility/aspnet-core/5.0/kestrel-libuv-transport-obsolete.md index bcf83709af83e..f7a823e8611bc 100644 --- a/docs/core/compatibility/aspnet-core/5.0/kestrel-libuv-transport-obsolete.md +++ b/docs/core/compatibility/aspnet-core/5.0/kestrel-libuv-transport-obsolete.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Kestrel: Libuv transport marked as obsolete" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Kestrel: Libuv transport marked as obsolete" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/localization-members-removed.md b/docs/core/compatibility/aspnet-core/5.0/localization-members-removed.md index 3ae95b1cc750e..b4dd9e40a05c9 100644 --- a/docs/core/compatibility/aspnet-core/5.0/localization-members-removed.md +++ b/docs/core/compatibility/aspnet-core/5.0/localization-members-removed.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Localization: ResourceManagerWithCultureStringLocalizer class and WithCulture interface member removed" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Localization: ResourceManagerWithCultureStringLocalizer class and WithCulture interface member removed" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/localization-pubternal-apis-removed.md b/docs/core/compatibility/aspnet-core/5.0/localization-pubternal-apis-removed.md index 52e28f2717bf9..667f354a47a45 100644 --- a/docs/core/compatibility/aspnet-core/5.0/localization-pubternal-apis-removed.md +++ b/docs/core/compatibility/aspnet-core/5.0/localization-pubternal-apis-removed.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Pubternal APIs removed" description: "Learn about the breaking change in ASP.NET Core 5.0 where some pubternal localization APIs were removed" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/localization-requestlocalizationmiddleware-constructor-removed.md b/docs/core/compatibility/aspnet-core/5.0/localization-requestlocalizationmiddleware-constructor-removed.md index 59ec0c96e44b7..ca2e177fb3ae7 100644 --- a/docs/core/compatibility/aspnet-core/5.0/localization-requestlocalizationmiddleware-constructor-removed.md +++ b/docs/core/compatibility/aspnet-core/5.0/localization-requestlocalizationmiddleware-constructor-removed.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Localization: Obsolete constructor removed in request localization middleware" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Localization: Obsolete constructor removed in request localization middleware" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/middleware-database-error-page-obsolete.md b/docs/core/compatibility/aspnet-core/5.0/middleware-database-error-page-obsolete.md index 5404cd55677f8..936c00786f3fd 100644 --- a/docs/core/compatibility/aspnet-core/5.0/middleware-database-error-page-obsolete.md +++ b/docs/core/compatibility/aspnet-core/5.0/middleware-database-error-page-obsolete.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Middleware: Database error page marked as obsolete" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Middleware: Database error page marked as obsolete" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/middleware-exception-handler-throws-original-exception.md b/docs/core/compatibility/aspnet-core/5.0/middleware-exception-handler-throws-original-exception.md index b861fd50e6f9c..9d848ff41d552 100644 --- a/docs/core/compatibility/aspnet-core/5.0/middleware-exception-handler-throws-original-exception.md +++ b/docs/core/compatibility/aspnet-core/5.0/middleware-exception-handler-throws-original-exception.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Middleware: Exception Handler Middleware throws original exception if handler not found" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Middleware: Exception Handler Middleware throws original exception if handler not found" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/mvc-objectmodelvalidator-calls-new-overload.md b/docs/core/compatibility/aspnet-core/5.0/mvc-objectmodelvalidator-calls-new-overload.md index 9f124c85ddf29..118af0c24253e 100644 --- a/docs/core/compatibility/aspnet-core/5.0/mvc-objectmodelvalidator-calls-new-overload.md +++ b/docs/core/compatibility/aspnet-core/5.0/mvc-objectmodelvalidator-calls-new-overload.md @@ -1,7 +1,6 @@ --- title: "Breaking change: MVC: ObjectModelValidator calls a new overload of ValidationVisitor.Validate" description: "Learn about the breaking change in ASP.NET Core 5.0 titled MVC: ObjectModelValidator calls a new overload of ValidationVisitor.Validate" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- diff --git a/docs/core/compatibility/aspnet-core/5.0/security-cookie-name-encoding-removed.md b/docs/core/compatibility/aspnet-core/5.0/security-cookie-name-encoding-removed.md index 9bba16c26eb9a..48a4caea50e68 100644 --- a/docs/core/compatibility/aspnet-core/5.0/security-cookie-name-encoding-removed.md +++ b/docs/core/compatibility/aspnet-core/5.0/security-cookie-name-encoding-removed.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Security: Cookie name encoding removed" description: "Learn about the breaking change in ASP.NET Core 5.0 titled Security: Cookie name encoding removed" -author: scottaddie ms.author: scaddie ms.date: 10/01/2020 --- @@ -40,8 +39,8 @@ If you're moving projects to ASP.NET Core 5.0 or later, ensure that their cookie - - -- -- +- `Microsoft.Owin.IOwinRequest.Cookies` +- `Microsoft.Owin.IOwinResponse.Cookies` diff --git a/docs/core/compatibility/aspnet-core/6.0/assemblies-removed-from-shared-framework.md b/docs/core/compatibility/aspnet-core/6.0/assemblies-removed-from-shared-framework.md new file mode 100644 index 0000000000000..b21b0e3f53024 --- /dev/null +++ b/docs/core/compatibility/aspnet-core/6.0/assemblies-removed-from-shared-framework.md @@ -0,0 +1,66 @@ +--- +title: "Breaking change: Assemblies removed from Microsoft.AspNetCore.App shared framework" +description: "Learn about the breaking change in ASP.NET Core 6.0 where some assemblies where removed from the Microsoft.AspNetCore.App shared framework." +ms.date: 04/02/2021 +--- +# Assemblies removed from Microsoft.AspNetCore.App shared framework + +The following two assemblies were removed from the ASP.NET Core targeting pack: + +- System.Security.Permissions +- System.Windows.Extensions + +In addition, the following assemblies were removed from the ASP.NET Core runtime pack: + +- Microsoft.Win32.SystemEvents +- System.Drawing.Common +- System.Security.Permissions +- System.Windows.Extensions + +## Version introduced + +ASP.NET Core 6.0 + +## Old behavior + +Applications could use APIs provided by these libraries by referencing the [Microsoft.AspNetCore.App](/aspnet/core/fundamentals/metapackage-app) shared framework. + +## New behavior + +If you use APIs from the affected assemblies without having a [PackageReference](../../../project-sdk/msbuild-props.md#packagereference) in your project file, you might see run-time errors. For example, an application that uses reflection to access APIs from one of these assemblies without adding an explicit reference to the package will have run-time errors. The `PackageReference` ensures that the assemblies are present as part of the application output. + +For discussion, see . + +## Reason for change + +This change was introduced to reduce the size of the ASP.NET Core shared framework. + +## Recommended action + +To continue using these APIs in your project, add a [PackageReference](../../../project-sdk/msbuild-props.md#packagereference). For example: + +```xml + +``` + +## Affected APIs + +- +- +- +- + + diff --git a/docs/core/compatibility/aspnet-core/6.0/blazor-eventargstype-property-replaced.md b/docs/core/compatibility/aspnet-core/6.0/blazor-eventargstype-property-replaced.md index d3d13e6f3c8e4..5773c904efb39 100644 --- a/docs/core/compatibility/aspnet-core/6.0/blazor-eventargstype-property-replaced.md +++ b/docs/core/compatibility/aspnet-core/6.0/blazor-eventargstype-property-replaced.md @@ -1,10 +1,9 @@ --- title: "Breaking change: Blazor: WebEventDescriptor.EventArgsType property replaced" description: "Learn about the breaking change in ASP.NET Core 6.0 where the WebEventDescriptor.EventArgsType property is replaced by the EventName property." -author: scottaddie ms.author: scaddie ms.date: 02/24/2021 -no-loc: [Blazor] +no-loc: [ Blazor ] --- # Blazor: :::no-loc text="WebEventDescriptor.EventArgsType"::: property replaced @@ -14,7 +13,7 @@ Starting in ASP.NET Core 6.0, the types by buffering the sequence in memory and formatting the buffered collection. In ASP.NET Core 6, when formatting using , MVC no longer buffers instances. Instead, MVC relies on the support that added for these types. + +In most cases, the absence of buffering would not be observable by the application. However, some scenarios may have inadvertently relied on the buffering semantics to correctly serialize. For example, returning an that's backed by an Entity Framework query on a type with lazy-loaded properties can result in concurrent query execution, which might not be supported by the provider. + +This change does not affect output formatting using Newtonsoft.Json or with XML-based formatters. + +## Version introduced + +ASP.NET Core 6.0 Preview 4 + +## Old behavior + + instances returned from an MVC action as a value to be formatted using or a are buffered before being serialized as a synchronous collection. + +## New behavior + +When formatting using , MVC no longer buffers instances. + +## Reason for change + + added support for streaming types. This allows for a smaller memory footprint during serialization. + +## Recommended action + +If your application requires buffering, consider manually buffering the object: + +```csharp +// Before +public IActionResult Get() +{ + return Ok(dbContext.Blogs); +} + +// After +public async Task Get() +{ + return Ok(await dbContext.Blogs.ToListAsync()); +} +``` + + diff --git a/docs/core/compatibility/aspnet-core/6.0/kestrel-log-message-attributes-changed.md b/docs/core/compatibility/aspnet-core/6.0/kestrel-log-message-attributes-changed.md index 586e43a28e8de..89f1e5c1d7e3e 100644 --- a/docs/core/compatibility/aspnet-core/6.0/kestrel-log-message-attributes-changed.md +++ b/docs/core/compatibility/aspnet-core/6.0/kestrel-log-message-attributes-changed.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Kestrel: Log message attributes changed" description: "Learn about the breaking change in ASP.NET Core 6.0 titled Kestrel: Log message attributes changed" -author: scottaddie ms.author: scaddie ms.date: 02/01/2021 --- @@ -11,7 +10,7 @@ Kestrel log messages have associated IDs and names. These attributes uniquely id ## Version introduced -6.0 +ASP.NET Core 6.0 ## Old behavior diff --git a/docs/core/compatibility/aspnet-core/6.0/messagepack-library-change.md b/docs/core/compatibility/aspnet-core/6.0/messagepack-library-change.md new file mode 100644 index 0000000000000..65fba2546d18d --- /dev/null +++ b/docs/core/compatibility/aspnet-core/6.0/messagepack-library-change.md @@ -0,0 +1,64 @@ +--- +title: "Breaking change: Changed MessagePack library in signalr-protocol-msgpack package" +description: "Learn about the breaking change in ASP.NET Core 6.0 where the MessagePack library was changed and two options were removed in the @microsoft/signalr-protocol-msgpack package." +ms.date: 04/07/2021 +--- +# Changed MessagePack library in @microsoft/signalr-protocol-msgpack + +The [@microsoft/signalr-protocol-msgpack](https://www.npmjs.com/package/@microsoft/signalr-protocol-msgpack) npm package now references `@msgpack/msgpack` instead of `msgpack5`. Additionally, the available options that can optionally be passed into the `MessagePackHubProtocol` have changed. The `MessagePackOptions.disableTimestampEncoding` and `MessagePackOptions.forceFloat64` properties were removed, and some new options were added. + +For discussion, see . + +## Version introduced + +ASP.NET Core 6.0 + +## Old behavior + +In previous versions, you must include three script references to use the [MessagePack Hub Protocol](/aspnet/core/signalr/messagepackhubprotocol) in the browser: + +```html + + + +``` + +## New behavior + +Starting in ASP.NET Core 6, you only need two script references to use the [MessagePack Hub Protocol](/aspnet/core/signalr/messagepackhubprotocol) in the browser: + +```html + + +``` + +Instead of the `msgpack5` package, the `@msgpack/msgpack` package is downloaded to your *node_modules* directory if you want to use it directly in your app. + +Finally, `MessagePackOptions` has new, additional properties, and the `disableTimestampEncoding` and `forceFloat64` properties are removed. + +## Reason for change + +This change was made to reduce asset size, make it simpler to consume the package, and add more customizability. + +## Recommended action + +If you were previously using `msgpack5` in your app, you'll need to add a direct reference to the library in your *package.json* file. + +## Affected APIs + +The following APIs were removed: + +- `MessagePackOptions.disableTimestampEncoding` +- `MessagePackOptions.forceFloat64` + + diff --git a/docs/core/compatibility/aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md b/docs/core/compatibility/aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md new file mode 100644 index 0000000000000..586edeaf94e46 --- /dev/null +++ b/docs/core/compatibility/aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md @@ -0,0 +1,87 @@ +--- +title: "Breaking change: Microsoft.AspNetCore.Http.Features split up" +description: "Learn about the breaking change in ASP.NET Core 6.0 where the Microsoft.AspNetCore.Http.Features package has been split, and no longer ships as a package." +ms.date: 05/06/2021 +--- +# Microsoft.AspNetCore.Http.Features split + +Microsoft.AspNetCore.Http.Features has been split into the following two assemblies: + +- Microsoft.AspNetCore.Http.Features +- Microsoft.Extensions.Features + +For discussion, see GitHub issue [dotnet/aspnetcore#32307](https://github.com/dotnet/aspnetcore/issues/32307). + +## Version introduced + +ASP.NET Core 6.0 + +## Old behavior + +Microsoft.AspNetCore.Http.Features 5.0 shipped both in the ASP.NET shared framework and as a NuGet package. Microsoft.AspNetCore.Http.Features 5.0 targeted .NET 4.6.1, .NET Standard 2.0, and .NET 5. + +## New behavior + +Microsoft.AspNetCore.Http.Features 6.0 ships only in the ASP.NET shared framework, not as a NuGet package. It targets .NET 6 only. + +Microsoft.Extensions.Features 6.0 ships in both the ASP.NET shared framework and as a NuGet package. It targets .NET 4.6.1, .NET Standard 2.0, and .NET 6.0. + +The following types have been moved to the new Microsoft.Extensions.Features assembly: + +- +- +- +- + +These types are still in the `Microsoft.AspNetCore.Http.Features` namespace, and type forwards have been added for compatibility. + +## Reason for change + +This change was introduced for two reasons: + +- Allows the core types to be shared more broadly across components. +- Allows the remaining Http-specific components in Microsoft.AspNetCore.Http.Features to take advantage of new runtime and language features. + +## Recommended action + +When upgrading to ASP.NET 6.0, remove any packages references for Microsoft.AspNetCore.Http.Features. Add a package reference for Microsoft.Extensions.Features only if required. + +For class libraries that need to consume the types from Microsoft.AspNetCore.Http.Features, add a `FrameworkReference` instead: + +```xml + + + +``` + +For more information about adding the framework reference, see [Use the ASP.NET Core shared framework](/aspnet/core/fundamentals/target-aspnetcore?#use-the-aspnet-core-shared-framework). + +Libraries with out of date references may encounter a or the following error: + +**Error CS0433 The type 'IFeatureCollection' exists in both 'Microsoft.AspNetCore.Http.Features, Version=5.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60' and 'Microsoft.Extensions.Features, Version=6.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'** + +To resolve the error, add a `FrameworkReference` to Microsoft.AspNetCore.App to any of the affected projects. + +For questions, see [dotnet/aspnetcore#32307](https://github.com/dotnet/aspnetcore/issues/32307). + +## Affected APIs + +- +- +- +- + + diff --git a/docs/core/compatibility/aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md b/docs/core/compatibility/aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md index 956669eef762c..c5d84b367d2d8 100644 --- a/docs/core/compatibility/aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md +++ b/docs/core/compatibility/aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports" description: "Learn about the breaking change in ASP.NET Core 6.0 titled Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports" -author: scottaddie ms.author: scaddie ms.date: 02/04/2021 --- @@ -13,7 +12,7 @@ For discussion, see GitHub issue [dotnet/aspnetcore#29222](https://github.com/do ## Version introduced -6.0 +ASP.NET Core 6.0 ## Old behavior diff --git a/docs/core/compatibility/aspnet-core/6.0/middleware-new-use-overload.md b/docs/core/compatibility/aspnet-core/6.0/middleware-new-use-overload.md new file mode 100644 index 0000000000000..2dac25cb8697a --- /dev/null +++ b/docs/core/compatibility/aspnet-core/6.0/middleware-new-use-overload.md @@ -0,0 +1,82 @@ +--- +title: "Breaking change: Middleware: New Use overload" +description: "Learn about the breaking change in ASP.NET Core 6.0 where a new overload of Use middleware was introduced." +ms.date: 05/06/2021 +--- +# Middleware: New Use overload + +A new overload of `app.Use` has been introduced. If you call `app.Use` but never call the `next` middleware, you'll now get compiler error CS0121: + +**The call is ambiguous between the following methods or properties: 'UseExtensions.Use(IApplicationBuilder, Func)' and 'UseExtensions.Use(IApplicationBuilder, Func)'** + +To resolve the error, use `app.Run` instead of `app.Use`. + +For discussion, see GitHub issue [dotnet/aspnetcore#32020](https://github.com/dotnet/aspnetcore/issues/32020). + +## Version introduced + +ASP.NET Core 6.0 Preview 4 + +## Old behavior + +```csharp +app.Use(async (context, next) => +{ + await next(); +}); +``` + +or + +```csharp +app.Use(async (context, next) => +{ + await SomeAsyncWork(); + // next not called... +}); +``` + +## New behavior + +You can now pass `context` to the `next` delegate: + +```csharp +app.Use(async (context, next) => +{ + await next(context); +}); +``` + +Use `app.Run` when your middleware never calls `next`: + +```csharp +app.Run(async (context) => +{ + await SomeAsyncWork(); + // next never called +}); +``` + +## Reason for change + +The previous `Use` method allocates two objects per request. The new overload avoids these allocations with a small change to how you invoke the `next` middleware. + +## Recommended action + +If you get a compile error, it means you are calling `app.Use` without using the `next` delegate. Switch to `app.Run` to fix the error. + +## Affected APIs + +None. + + diff --git a/docs/core/compatibility/aspnet-core/6.0/nullable-reference-type-annotations-changed.md b/docs/core/compatibility/aspnet-core/6.0/nullable-reference-type-annotations-changed.md index 433d3812a5865..0b8db93c420df 100644 --- a/docs/core/compatibility/aspnet-core/6.0/nullable-reference-type-annotations-changed.md +++ b/docs/core/compatibility/aspnet-core/6.0/nullable-reference-type-annotations-changed.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Nullable reference type annotations changed" description: "Learn about the breaking change in ASP.NET Core 6.0 titled Nullable reference type annotations changed" -author: scottaddie ms.author: scaddie ms.date: 02/24/2021 --- @@ -9,13 +8,13 @@ ms.date: 02/24/2021 _**This issue represents a work-in-progress. All breaking changes to nullability annotations will be aggregated into this issue throughout the course of ASP.NET Core 6.0.**_ -Starting in ASP.NET Core 5.0, nullability annotations have been applied to parts of the code. From the outset of this effort, [mistakes were expected](https://github.com/dotnet/runtime/blob/master/docs/coding-guidelines/api-guidelines/nullability.md#breaking-change-guidance) in these annotations and fixes would need to be made. In ASP.NET Core 6.0, some previously applied annotations are being updated. Some of these changes are considered source breaking changes. The changes lead to the APIs being incompatible or more restrictive. The updated APIs may result in build-time warnings when used in projects that have nullable reference types enabled. +Starting in ASP.NET Core 5.0, nullability annotations have been applied to parts of the code. From the outset of this effort, [mistakes were expected](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/api-guidelines/nullability.md#breaking-change-guidance) in these annotations and fixes would need to be made. In ASP.NET Core 6.0, some previously applied annotations are being updated. Some of these changes are considered source breaking changes. The changes lead to the APIs being incompatible or more restrictive. The updated APIs may result in build-time warnings when used in projects that have nullable reference types enabled. For discussion, see GitHub issue [dotnet/aspnetcore#27564](https://github.com/dotnet/aspnetcore/issues/27564). ## Version introduced -6.0 +ASP.NET Core 6.0 ## Old behavior diff --git a/docs/core/compatibility/aspnet-core/6.0/obsolete-removed-apis.md b/docs/core/compatibility/aspnet-core/6.0/obsolete-removed-apis.md index b0738841e20c8..76edb71be1ca4 100644 --- a/docs/core/compatibility/aspnet-core/6.0/obsolete-removed-apis.md +++ b/docs/core/compatibility/aspnet-core/6.0/obsolete-removed-apis.md @@ -1,7 +1,6 @@ --- title: "Breaking change: Obsoleted and removed APIs" description: "Learn about the breaking change in ASP.NET Core 6.0 titled Obsoleted and removed APIs" -author: scottaddie ms.author: scaddie ms.date: 02/16/2021 --- @@ -11,7 +10,7 @@ In ASP.NET Core 6.0 Preview 1, several APIs were either removed or marked as obs ## Version introduced -6.0 Preview 1 +ASP.NET Core 6.0 Preview 1 ## Old behavior diff --git a/docs/core/compatibility/aspnet-core/6.0/preservecompilationcontext-not-set-by-default.md b/docs/core/compatibility/aspnet-core/6.0/preservecompilationcontext-not-set-by-default.md new file mode 100644 index 0000000000000..c9412da6a68b7 --- /dev/null +++ b/docs/core/compatibility/aspnet-core/6.0/preservecompilationcontext-not-set-by-default.md @@ -0,0 +1,53 @@ +--- +title: "Breaking change: PreserveCompilationContext not configured by default" +description: "Learn about the breaking change in ASP.NET Core 6.0 where the PreserveCompilationContext property is no longer configured by default." +no-loc: [ Razor ] +ms.date: 04/22/2021 +--- +# PreserveCompilationContext not configured by default + +[`PreserveCompilationContext`](../../../project-sdk/msbuild-props.md#preservecompilationcontext) is an MSBuild property that causes .NET Core projects to emit additional content to the application's dependency (.deps) file about how the app was compiled. This is primarily used to support run-time compilation scenarios. + +Prior to .NET 6, `PreserveCompilationContext` was set to `true` for all apps that target the Razor (Microsoft.NET.Sdk.Razor) and Web (Microsoft.NET.Sdk.Web) SDKs. Starting in .NET 6, this property is no longer configured by default. However, packages such as Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation configure this property as required. + +## Version introduced + +ASP.NET Core 6.0 + +## Old behavior + +The dependency file contains compilation context. + +## New behavior + +The dependency file no longer contains compilation context. + +## Reason for change + +This change improves build performance and startup time, and reduces the size of ASP.NET Core's build output. + +## Recommended action + +If your app requires this feature and does not reference a package that configures the property, add the `PreserveCompilationContext` property to your project file. + +```xml + + true + +``` + +## Affected APIs + +None. + + diff --git a/docs/core/compatibility/aspnet-core/6.0/razor-compiler-doesnt-produce-views-assembly.md b/docs/core/compatibility/aspnet-core/6.0/razor-compiler-doesnt-produce-views-assembly.md new file mode 100644 index 0000000000000..22528c1ec4626 --- /dev/null +++ b/docs/core/compatibility/aspnet-core/6.0/razor-compiler-doesnt-produce-views-assembly.md @@ -0,0 +1,51 @@ +--- +title: "Breaking change: Razor: Compiler now produces a single assembly" +description: "Learn about the breaking change in ASP.NET Core 6.0 where the Razor compiler no longer uses a two-step compilation process to produce two separate assemblies." +no-loc: [ Razor ] +ms.date: 04/08/2021 +--- +# Razor: Compiler no longer produces a Views assembly + +The Razor compiler no longer produces a separate *Views.dll* file that contains the CSHTML views defined in an application. + +## Version introduced + +ASP.NET Core 6.0 Preview 3 + +## Old behavior + +In previous versions, the Razor compiler utilizes a two-step compilation process that produces two files: + +- A main *AppName.dll* assembly that contains application types. +- An *AppName.Views.dll* assembly that contains the generated views that are defined in the app. Generated view types are `public` and under the `AspNetCore` namespace. + +## New behavior + +Both views and application types are included in a single *AppName.dll* assembly. View types have the accessibility modifiers `internal` and `sealed`, by default, and are included under the `AspNetCoreGeneratedDocument` namespace. + +## Reason for change + +Removing the two-step compilation process: + +* Improves build performance for applications that use Razor views. +* Allows Razor views to participate in the "hot reload" experience for Visual Studio. + +## Recommended action + +None. + +## Affected APIs + +None. + + diff --git a/docs/core/compatibility/aspnet-core/6.0/razor-engine-apis-obsolete.md b/docs/core/compatibility/aspnet-core/6.0/razor-engine-apis-obsolete.md index 444c126aab908..2fbdcd1cb9ba9 100644 --- a/docs/core/compatibility/aspnet-core/6.0/razor-engine-apis-obsolete.md +++ b/docs/core/compatibility/aspnet-core/6.0/razor-engine-apis-obsolete.md @@ -1,7 +1,7 @@ --- title: "Breaking change: Razor: RazorEngine APIs marked obsolete" description: "Learn about the breaking change in ASP.NET Core 6.0 titled Razor: RazorEngine APIs marked obsolete" -author: scottaddie +no-loc: [ Razor ] ms.author: scaddie ms.date: 02/09/2021 --- @@ -11,7 +11,7 @@ Types related to the type ## Version introduced -6.0 Preview 1 +ASP.NET Core 6.0 Preview 1 ## Old behavior @@ -31,9 +31,9 @@ Migrate source code from the `RazorEngine` type to the `RazorProjectEngine` type ## Affected APIs -- [Microsoft.AspNetCore.Mvc.Razor.Extensions.InjectDirective.Register](/dotnet/api/microsoft.aspnetcore.mvc.razor.extensions.injectdirective.register?view=aspnetcore-3.1&preserve-view=true) -- [Microsoft.AspNetCore.Mvc.Razor.Extensions.ModelDirective.Register](/dotnet/api/microsoft.aspnetcore.mvc.razor.extensions.namespacedirective.register?view=aspnetcore-2.2&preserve-view=true) -- [Microsoft.AspNetCore.Mvc.Razor.Extensions.PageDirective.Register](/dotnet/api/microsoft.aspnetcore.mvc.razor.extensions.namespacedirective.register?view=aspnetcore-2.2&preserve-view=true) +- `Microsoft.AspNetCore.Mvc.Razor.Extensions.InjectDirective.Register` +- `Microsoft.AspNetCore.Mvc.Razor.Extensions.ModelDirective.Register` +- `Microsoft.AspNetCore.Mvc.Razor.Extensions.PageDirective.Register` - [Microsoft.AspNetCore.Razor.Language.Extensions.FunctionsDirective.Register](/dotnet/api/microsoft.aspnetcore.razor.language.extensions.functionsdirective.register?view=aspnetcore-3.0&preserve-view=true) - [Microsoft.AspNetCore.Razor.Language.Extensions.InheritsDirective.Register](/dotnet/api/microsoft.aspnetcore.razor.language.extensions.inheritsdirective.register?view=aspnetcore-3.0&preserve-view=true) - [Microsoft.AspNetCore.Razor.Language.Extensions.SectionDirective.Register](/dotnet/api/microsoft.aspnetcore.razor.language.extensions.sectiondirective.register?view=aspnetcore-3.0&preserve-view=true) diff --git a/docs/core/compatibility/aspnet-core/6.0/signalr-java-client-updated.md b/docs/core/compatibility/aspnet-core/6.0/signalr-java-client-updated.md new file mode 100644 index 0000000000000..6870514ce9337 --- /dev/null +++ b/docs/core/compatibility/aspnet-core/6.0/signalr-java-client-updated.md @@ -0,0 +1,44 @@ +--- +title: "Breaking change: SignalR Java Client updated to RxJava3" +description: "Learn about the breaking change in ASP.NET Core 6.0 where the SignalR Java Client was updated to RxJava3." +ms.date: 04/21/2021 +--- +# SignalR: Java Client updated to RxJava3 + +The SignalR Java Client is now RxJava3. + +## Version introduced + +ASP.NET Core 6.0 Preview 4 + +## Old behavior + +The RxJava package reference in the library was RxJava2. + +## New behavior + +The RxJava package reference in the library is now RxJava3. For information about what changed in RxJava, see [What's different in 3.0](https://github.com/ReactiveX/RxJava/wiki/What's-different-in-3.0). + +## Reason for change + +The previous dependency (RxJava2) is no longer maintained. Support for RxJava2 ended in February 2021. + +## Recommended action + +If you were using RxJava2 in your app or library, you might need to update to RxJava3. For more information, see [What's different in 3.0](https://github.com/ReactiveX/RxJava/wiki/What's-different-in-3.0). + +## Affected APIs + +None. + + diff --git a/docs/core/compatibility/aspnetcore.md b/docs/core/compatibility/aspnetcore.md index 1c22b1286e707..713fd8e0c5f4b 100644 --- a/docs/core/compatibility/aspnetcore.md +++ b/docs/core/compatibility/aspnetcore.md @@ -3,7 +3,6 @@ title: ASP.NET Core breaking changes titleSuffix: "" description: Lists the breaking changes in ASP.NET Core 3.0 and 3.1. ms.date: 11/03/2020 -author: scottaddie ms.author: scaddie --- # ASP.NET Core breaking changes for versions 3.0 and 3.1 diff --git a/docs/core/compatibility/breaking-changes.md b/docs/core/compatibility/breaking-changes.md index 1e36b80b3f156..0f458a540aa52 100644 --- a/docs/core/compatibility/breaking-changes.md +++ b/docs/core/compatibility/breaking-changes.md @@ -2,6 +2,7 @@ title: Breaking changes reference overview description: Learn how to navigate the .NET breaking changes reference. ms.date: 11/16/2020 +ms.topic: conceptual --- # Breaking changes reference overview diff --git a/docs/core/compatibility/categories.md b/docs/core/compatibility/categories.md index 60ba6f95e5082..c54652b1771a7 100644 --- a/docs/core/compatibility/categories.md +++ b/docs/core/compatibility/categories.md @@ -2,6 +2,7 @@ title: Compatibility description: Learn about the ways in which code changes can affect compatibility in .NET. ms.date: 06/10/2019 +ms.topic: conceptual --- # How code changes can affect compatibility diff --git a/docs/core/compatibility/code-analysis/5.0/ca1416-platform-compatibility-analyzer.md b/docs/core/compatibility/code-analysis/5.0/ca1416-platform-compatibility-analyzer.md index a430dae54bc00..086f332ab80c8 100644 --- a/docs/core/compatibility/code-analysis/5.0/ca1416-platform-compatibility-analyzer.md +++ b/docs/core/compatibility/code-analysis/5.0/ca1416-platform-compatibility-analyzer.md @@ -1,7 +1,7 @@ --- title: "Breaking change: CA1416: Platform compatibility" description: Learn about the breaking change in .NET 5 caused by the enablement of code analysis rule CA1416. -ms.date: 09/29/2020 +ms.date: 05/04/2021 --- # Warning CA1416: Platform compatibility @@ -88,7 +88,7 @@ public void PlayCMajor() If you don't want to fix all your call sites, you can choose one of the following options to suppress the warning: -- To suppress rule CA1416, you can do so using `#pragma` or the [-nowarn](../../../../csharp/language-reference/compiler-options/nowarn-compiler-option.md) compiler flag, or by [setting the rule's severity](../../../../fundamentals/code-analysis/configuration-options.md#severity-level) to `none` in an .editorconfig file. +- To suppress rule CA1416, you can do so using `#pragma` or the [**DisabledWarnings**](../../../../csharp/language-reference/compiler-options/errors-warnings.md#disabledwarnings) compiler flag, or by [setting the rule's severity](../../../../fundamentals/code-analysis/configuration-options.md#severity-level) to `none` in an .editorconfig file. ```csharp public void PlayCMajor() @@ -105,7 +105,7 @@ If you don't want to fix all your call sites, you can choose one of the followin For Windows platform: -- All APIs listed at . +- All APIs listed at . - - - @@ -131,4 +131,4 @@ For Blazor WebAssembly platform: ## See also - [CA1416: Validate platform compatibility](/visualstudio/code-quality/ca1416) -- [.NET API analyzer](../../../../standard/analyzers/api-analyzer.md) +- [Platform compatibility analyzer](../../../../standard/analyzers/platform-compat-analyzer.md) diff --git a/docs/core/compatibility/core-libraries/5.0/obsolete-apis-with-custom-diagnostics.md b/docs/core/compatibility/core-libraries/5.0/obsolete-apis-with-custom-diagnostics.md index 4b96a0725ef01..acbf4b814beaa 100644 --- a/docs/core/compatibility/core-libraries/5.0/obsolete-apis-with-custom-diagnostics.md +++ b/docs/core/compatibility/core-libraries/5.0/obsolete-apis-with-custom-diagnostics.md @@ -1,5 +1,6 @@ --- -title: "Breaking change: API obsoletions with non-default diagnostic IDs" +title: "Breaking change: .NET 5 API obsoletions with non-default diagnostic IDs" +titleSuffix: "" description: Learn about the .NET 5 breaking change in core .NET libraries where some APIs have been marked as obsolete with a custom diagnostic ID. ms.date: 11/01/2020 --- @@ -15,18 +16,18 @@ The following table lists the custom diagnostic IDs and their corresponding warn | Diagnostic ID | Description | Severity | | - | - | -| `SYSLIB0001` | The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead. | Warning | -| `SYSLIB0002` | is not honored by the runtime and must not be used. | Error | -| `SYSLIB0003` | Code access security (CAS) is not supported or honored by the runtime. | Warning | -| `SYSLIB0004` | The constrained execution region (CER) feature is not supported. | Warning | -| `SYSLIB0005` | The global assembly cache (GAC) is not supported. | Warning | -| `SYSLIB0006` | is not supported and throws . | Warning | -| `SYSLIB0007` | The default implementation of this cryptography algorithm is not supported. | Warning | -| `SYSLIB0008` | The API is not supported and throws . | Warning | -| `SYSLIB0009` | The and methods are not supported and throw . | Warning | -| `SYSLIB0010`| Some remoting APIs are not supported and throw . | Warning | -| `SYSLIB0011` | serialization is obsolete and should not be used. | Warning | -| `SYSLIB0012` | and are only included for .NET Framework compatibility. Use instead. | Warning | +| [SYSLIB0001](../../../../fundamentals/syslib-diagnostics/syslib0001.md) | The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead. | Warning | +| [SYSLIB0002](../../../../fundamentals/syslib-diagnostics/syslib0002.md) | is not honored by the runtime and must not be used. | Error | +| [SYSLIB0003](../../../../fundamentals/syslib-diagnostics/syslib0003.md) | Code access security (CAS) is not supported or honored by the runtime. | Warning | +| [SYSLIB0004](../../../../fundamentals/syslib-diagnostics/syslib0004.md) | The constrained execution region (CER) feature is not supported. | Warning | +| [SYSLIB0005](../../../../fundamentals/syslib-diagnostics/syslib0005.md) | The global assembly cache (GAC) is not supported. | Warning | +| [SYSLIB0006](../../../../fundamentals/syslib-diagnostics/syslib0006.md) | is not supported and throws . | Warning | +| [SYSLIB0007](../../../../fundamentals/syslib-diagnostics/syslib0007.md) | The default implementation of this cryptography algorithm is not supported. | Warning | +| [SYSLIB0008](../../../../fundamentals/syslib-diagnostics/syslib0008.md) | The API is not supported and throws . | Warning | +| [SYSLIB0009](../../../../fundamentals/syslib-diagnostics/syslib0009.md) | The and methods are not supported and throw . | Warning | +| [SYSLIB0010](../../../../fundamentals/syslib-diagnostics/syslib0010.md) | Some remoting APIs are not supported and throw . | Warning | +| [SYSLIB0011](../../../../fundamentals/syslib-diagnostics/syslib0011.md) | serialization is obsolete and should not be used. | Warning | +| [SYSLIB0012](../../../../fundamentals/syslib-diagnostics/syslib0012.md) | and are only included for .NET Framework compatibility. Use instead. | Warning | ## Version introduced @@ -199,6 +200,7 @@ Enums in the `System.Security.Permissions` namespace: Classes and members that depend on code access security types: +- - - - @@ -266,6 +268,7 @@ Classes and members that depend on code access security types: ### SYSLIB0011 +- - - - @@ -277,3 +280,8 @@ Classes and members that depend on code access security types: - - + +## See also + +- [API obsoletions with non-default diagnostic IDs (.NET 6)](../6.0/obsolete-apis-with-custom-diagnostics.md) +- [Obsolete features in .NET 5+](../../../../fundamentals/syslib-diagnostics/obsoletions-overview.md) diff --git a/docs/core/compatibility/core-libraries/6.0/additional-linq-queryable-method-overloads.md b/docs/core/compatibility/core-libraries/6.0/additional-linq-queryable-method-overloads.md new file mode 100644 index 0000000000000..e104cf5693cf4 --- /dev/null +++ b/docs/core/compatibility/core-libraries/6.0/additional-linq-queryable-method-overloads.md @@ -0,0 +1,68 @@ +--- +title: ".NET 6 breaking change: Additional overloads of LINQ Queryable methods" +description: Learn about the .NET 6 breaking change in core .NET libraries where additional method overloads were added to the System.Linq.Queryable type. +ms.date: 03/31/2021 +--- +# New System.Linq.Queryable method overloads + +Additional public method overloads have been added to as part of the new features implemented in . If your reflection code isn't sufficiently robust when looking up methods, these additions can break your query provider implementations. + +## Change description + +In .NET 6, new overloads were added to the methods listed in the [Affected APIs](#affected-apis) section. Reflection code, such as that shown in the following example, may break as a result of these additions: + +```csharp +typeof(System.Linq.Queryable) + .GetMethods(BindingFlags.Public | BindingFlags.Static) + .Where(m => m.Name == "ElementAt") + .Single(); +``` + +This reflection code will now throw an with a message similar to: **Sequence contains more than one element**. + +## Version introduced + +6.0 Preview 3 and Preview 4 + +## Reason for change + +The new overloads were added to extend the LINQ `Queryable` API. + +## Recommended action + +If you're a query-provider library author, ensure that your reflection code is tolerant of method overload additions. For example, use a overload that explicitly accepts the method's parameter types. + +## Affected APIs + +New overloads were added for the following extension methods: + +- +- +- +- +- +- +- +- +- + + diff --git a/docs/core/compatibility/core-libraries/6.0/environment-processorcount-on-windows.md b/docs/core/compatibility/core-libraries/6.0/environment-processorcount-on-windows.md new file mode 100644 index 0000000000000..4d984af5cf926 --- /dev/null +++ b/docs/core/compatibility/core-libraries/6.0/environment-processorcount-on-windows.md @@ -0,0 +1,59 @@ +--- +title: ".NET 6 breaking change: Environment.ProcessorCount behavior on Windows" +description: Learn about the .NET 6 breaking change in core .NET libraries where Environment.ProcessorCount may return a different value on Windows compared to previous .NET versions. +ms.date: 05/19/2021 +--- +# Environment.ProcessorCount behavior on Windows + +On Windows, the property now respects process affinity and the job object's hard limit on CPU utilization. + +## Change description + +In previous .NET versions, the property on Windows returns the number of logical processors on the machine. The property ignores process affinity and the job object's hard limit on CPU utilization. That Windows behavior is inconsistent with the behavior on Unix-based operating systems, where those limits are respected. + +Starting with .NET 6, the behavior of on Windows is consistent with the behavior on Unix-based operating system. In general, returns the minimum of: + +- The number of logical processors on the machine. +- If the process is running with CPU affinity, the number of processors that the process is affinitized to. +- If the process is running with a CPU utilization limit, the CPU utilization limit rounded up to the next whole number. + +The following table shows how the value of changes from .NET 5 to .NET 6 on a machine with eight logical processors: + +| Environment | .NET 5 | .NET 6 | +|-|-|-| +| Process affinitized to two logical processors (Windows) | 8 | 2 | +| Process affinitized to two logical processors (Unix) | 2 | 2 | +| CPU utilization limited to the equivalent of two logical processors (Windows) | 8 | 2 | +| CPU utilization limited to the equivalent of two logical processors (Unix) | 2 | 2 | + +## Version introduced + +6.0 + +## Reason for change + +This property is frequently used to determine the parallelism factor for a process. We've observed that not limiting the property's value based on affinitization and CPU utilization limit can lead to worse performance. + +## Recommended action + +Review code that uses to scale down the parallelism factor based on application or system configuration. Even if the code takes the process's affinity mask or the job object's CPU utilization limit into account, it may end up using lower parallelism than intended. + +Review code that expects to return the total number of logical processors on the machine, for example, to display it to a user. Instead, you can use a PInvoke call to the `GetSystemInfo` or `GetNativeSystemInfo` Win32 APIs. + +If code performs worse as a result of this change, you can use the `DOTNET_PROCESSOR_COUNT` environment variable to override the number of processors thought to be available by the .NET runtime and reported by the property. For example, if you set `DOTNET_PROCESSOR_COUNT` to 4, will disregard any process affinity and CPU utilization limit and return 4. To mimic .NET 5 behavior, set the environment variable to `%NUMBER_OF_PROCESSORS%`. + +## Affected APIs + +- + + diff --git a/docs/core/compatibility/core-libraries/6.0/hosting-exception-handling.md b/docs/core/compatibility/core-libraries/6.0/hosting-exception-handling.md new file mode 100644 index 0000000000000..efcef2cca10ad --- /dev/null +++ b/docs/core/compatibility/core-libraries/6.0/hosting-exception-handling.md @@ -0,0 +1,55 @@ +--- +title: ".NET 6 breaking change: Exception handling in hosting" +description: Learn about the .NET 6 breaking change in core .NET libraries where unhandled exceptions from a BackgroundService are logged instead of lost. +ms.date: 04/23/2021 +--- +# Unhandled exceptions from a BackgroundService + +In previous versions, when a throws an unhandled exception, the exception is lost and the service appears to hang. .NET 6 fixes this behavior by logging the exception and stopping the host. + +## Change description + +In previous .NET versions, when an exception is thrown from a override, the host continues to run, and no message is logged. + +Starting in .NET 6, when an exception is thrown from a override, the exception is logged to the current . By default, the host is stopped when an unhandled exception is encountered. + +## Version introduced + +6.0 Preview 4 + +## Reason for change + +The new behavior is consistent with the way other app models behave when unhandled exceptions are encountered. It's also confusing to developers when their encounters an error, but nothing is logged. The best default behavior is to stop the host, because unhandled exceptions shouldn't be ignored. They indicate a problem that needs attention. + +## Recommended action + +If you prefer to keep the previous behavior of allowing an unhandled exception in a to not stop the Host, you can set `HostOptions.BackgroundServiceExceptionBehavior` to `BackgroundServiceExceptionBehavior.Ignore`. + +```csharp +Host.CreateBuilder(args) + .ConfigureServices(services => + { + services.Configure(hostOptions => + { + hostOptions.BackgroundServiceExceptionBehavior = BackgroundServiceExceptionBehavior.Ignore; + }); + }); +``` + +## Affected APIs + +- +- + + diff --git a/docs/core/compatibility/core-libraries/6.0/obsolete-apis-with-custom-diagnostics.md b/docs/core/compatibility/core-libraries/6.0/obsolete-apis-with-custom-diagnostics.md new file mode 100644 index 0000000000000..1a71839c4866f --- /dev/null +++ b/docs/core/compatibility/core-libraries/6.0/obsolete-apis-with-custom-diagnostics.md @@ -0,0 +1,118 @@ +--- +title: "Breaking change: .NET 6 obsoletions with non-default diagnostic IDs" +titleSuffix: "" +description: Learn about the .NET 6 breaking change in core .NET libraries where some APIs have been marked as obsolete with a custom diagnostic ID. +ms.date: 05/18/2021 +--- +# API obsoletions with non-default diagnostic IDs (.NET 6) + +Some APIs have been marked as obsolete, starting in .NET 6. This breaking change is specific to APIs that have been marked as obsolete *with a custom diagnostic ID*. Suppressing the default obsoletion diagnostic ID, which is [CS0618](../../../../csharp/language-reference/compiler-messages/cs0618.md) for the C# compiler, does not suppress the warnings that the compiler generates when these APIs are used. + +## Change description + +In previous .NET versions, these APIs can be used without any build warning. In .NET 6 and later versions, use of these APIS produces a compile-time warning or error with a custom diagnostic ID. The use of custom diagnostic IDs allows you to suppress the obsoletion warnings individually instead of blanket-suppressing all obsoletion warnings. + +The following table lists the custom diagnostic IDs and their corresponding warning messages for obsoleted APIs. + +| Diagnostic ID | Description | Severity | +| - | - | +| [SYSLIB0013](../../../../fundamentals/syslib-diagnostics/syslib0013.md) | can corrupt the Uri string in some cases. Consider using for query string components instead. | Warning | +| [SYSLIB0014](../../../../fundamentals/syslib-diagnostics/syslib0014.md) | , , , and are obsolete. Use instead. | Error | +| [SYSLIB0015](../../../../fundamentals/syslib-diagnostics/syslib0015.md) | has no effect in .NET 6+. | Warning | +| [SYSLIB0016](../../../../fundamentals/syslib-diagnostics/syslib0016.md) | Use the overloads that accept arguments for better performance and fewer allocations. | Warning | +| [SYSLIB0017](../../../../fundamentals/syslib-diagnostics/syslib0017.md) | Strong-name signing is not supported and throws . | Warning | +| [SYSLIB0018](../../../../fundamentals/syslib-diagnostics/syslib0018.md) | Reflection-only loading is not supported and throws . | Warning | +| [SYSLIB0019](../../../../fundamentals/syslib-diagnostics/syslib0019.md) | The members , , and are no longer supported and throw . | Warning | +| [SYSLIB0020](../../../../fundamentals/syslib-diagnostics/syslib0020.md) | is obsolete. To ignore null values when serializing, set to . | Warning | +| [SYSLIB0021](../../../../fundamentals/syslib-diagnostics/syslib0021.md) | Derived cryptographic types are obsolete. Use the `Create` method on the base type instead. | Warning | +| [SYSLIB0022](../../../../fundamentals/syslib-diagnostics/syslib0022.md) | The and types are obsolete. Use instead. | Warning | +| [SYSLIB0023](../../../../fundamentals/syslib-diagnostics/syslib0023.md) | is obsolete. To generate a random number, use one of the static methods instead. | Warning | +| [SYSLIB0024](../../../../fundamentals/syslib-diagnostics/syslib0024.md) | Creating and unloading [AppDomains](xref:System.AppDomain) is not supported and throws an exception. | Warning | + +## Version introduced + +.NET 6.0 + +## Recommended action + +- Follow the specific guidance provided for the each diagnostic ID using the URL link provided on the warning. + +- Warnings or errors for these obsoletions can't be suppressed using the standard diagnostic ID for obsolete types or members; use the custom `SYSLIBxxxx` diagnostic ID value instead. + +## Affected APIs + +### SYSLIB0013 + +- + +### SYSLIB0014 + +- +- +- +- + +### SYSLIB0015 + +- + +### SYSLIB0016 + +- + +### SYSLIB0017 + +- +- + +### SYSLIB0018 + +- +- +- + +### SYSLIB0019 + +- +- +- + +### SYSLIB0020 + +- + +### SYSLIB0021 + +- +- +- +- +- +- +- +- +- +- +- +- +- +- + +### SYSLIB0022 + +- +- + +### SYSLIB0023 + +- + +### SYSLIB0024 + +- +- + +## See also + +- [API obsoletions with non-default diagnostic IDs (.NET 5)](../5.0/obsolete-apis-with-custom-diagnostics.md) +- [Obsolete features in .NET 5+](../../../../fundamentals/syslib-diagnostics/obsoletions-overview.md) diff --git a/docs/core/compatibility/corefx.md b/docs/core/compatibility/corefx.md index bd8783f8445e2..4e21fb5378195 100644 --- a/docs/core/compatibility/corefx.md +++ b/docs/core/compatibility/corefx.md @@ -11,23 +11,24 @@ The following breaking changes are documented on this page: | Breaking change | Version introduced | | - | :-: | -| [Passing GroupCollection to extension methods taking IEnumerable\ requires disambiguation](#passing-groupcollection-to-extension-methods-taking-ienumerablet-requires-disambiguation) | 3.0 | -| [APIs that report version now report product and not file version](#apis-that-report-version-now-report-product-and-not-file-version) | 3.0 | -| [Custom EncoderFallbackBuffer instances cannot fall back recursively](#custom-encoderfallbackbuffer-instances-cannot-fall-back-recursively) | 3.0 | -| [Floating point formatting and parsing behavior changes](#floating-point-formatting-and-parsing-behavior-changed) | 3.0 | -| [Floating-point parsing operations no longer fail or throw an OverflowException](#floating-point-parsing-operations-no-longer-fail-or-throw-an-overflowexception) | 3.0 | -| [InvalidAsynchronousStateException moved to another assembly](#invalidasynchronousstateexception-moved-to-another-assembly) | 3.0 | -| [Replacing ill-formed UTF-8 byte sequences follows Unicode guidelines](#replacing-ill-formed-utf-8-byte-sequences-follows-unicode-guidelines) | 3.0 | -| [TypeDescriptionProviderAttribute moved to another assembly](#typedescriptionproviderattribute-moved-to-another-assembly) | 3.0 | -| [ZipArchiveEntry no longer handles archives with inconsistent entry sizes](#ziparchiveentry-no-longer-handles-archives-with-inconsistent-entry-sizes) | 3.0 | -| [FieldInfo.SetValue throws exception for static, init-only fields](#fieldinfosetvalue-throws-exception-for-static-init-only-fields) | 3.0 | -| [Private fields added to built-in struct types](#private-fields-added-to-built-in-struct-types) | 2.1 | -| [Change in default value of UseShellExecute](#change-in-default-value-of-useshellexecute) | 2.1 | -| [OpenSSL versions on macOS](#openssl-versions-on-macos) | 2.1 | -| [UnauthorizedAccessException thrown by FileSystemInfo.Attributes](#unauthorizedaccessexception-thrown-by-filesysteminfoattributes) | 1.0 | -| [Handling corrupted-process-state exceptions is not supported](#handling-corrupted-state-exceptions-is-not-supported) | 1.0 | -| [UriBuilder properties no longer prepend leading characters](#uribuilder-properties-no-longer-prepend-leading-characters) | 1.0 | -| [Process.StartInfo throws InvalidOperationException for processes you didn't start](#processstartinfo-throws-invalidoperationexception-for-processes-you-didnt-start) | 1.0 | +| [Passing GroupCollection to extension methods taking IEnumerable\ requires disambiguation](#passing-groupcollection-to-extension-methods-taking-ienumerablet-requires-disambiguation) | .NET Core 3.0 | +| [APIs that report version now report product and not file version](#apis-that-report-version-now-report-product-and-not-file-version) | .NET Core 3.0 | +| [Custom EncoderFallbackBuffer instances cannot fall back recursively](#custom-encoderfallbackbuffer-instances-cannot-fall-back-recursively) | .NET Core 3.0 | +| [Floating point formatting and parsing behavior changes](#floating-point-formatting-and-parsing-behavior-changed) | .NET Core 3.0 | +| [Floating-point parsing operations no longer fail or throw an OverflowException](#floating-point-parsing-operations-no-longer-fail-or-throw-an-overflowexception) | .NET Core 3.0 | +| [InvalidAsynchronousStateException moved to another assembly](#invalidasynchronousstateexception-moved-to-another-assembly) | .NET Core 3.0 | +| [Replacing ill-formed UTF-8 byte sequences follows Unicode guidelines](#replacing-ill-formed-utf-8-byte-sequences-follows-unicode-guidelines) | .NET Core 3.0 | +| [TypeDescriptionProviderAttribute moved to another assembly](#typedescriptionproviderattribute-moved-to-another-assembly) | .NET Core 3.0 | +| [ZipArchiveEntry no longer handles archives with inconsistent entry sizes](#ziparchiveentry-no-longer-handles-archives-with-inconsistent-entry-sizes) | .NET Core 3.0 | +| [FieldInfo.SetValue throws exception for static, init-only fields](#fieldinfosetvalue-throws-exception-for-static-init-only-fields) | .NET Core 3.0 | +| [Path APIs don't throw an exception for invalid characters](#path-apis-dont-throw-an-exception-for-invalid-characters) | .NET Core 2.1 | +| [Private fields added to built-in struct types](#private-fields-added-to-built-in-struct-types) | .NET Core 2.1 | +| [Change in default value of UseShellExecute](#change-in-default-value-of-useshellexecute) | .NET Core 2.1 | +| [OpenSSL versions on macOS](#openssl-versions-on-macos) | .NET Core 2.1 | +| [UnauthorizedAccessException thrown by FileSystemInfo.Attributes](#unauthorizedaccessexception-thrown-by-filesysteminfoattributes) | .NET Core 1.0 | +| [Handling corrupted-process-state exceptions is not supported](#handling-corrupted-state-exceptions-is-not-supported) | .NET Core 1.0 | +| [UriBuilder properties no longer prepend leading characters](#uribuilder-properties-no-longer-prepend-leading-characters) | .NET Core 1.0 | +| [Process.StartInfo throws InvalidOperationException for processes you didn't start](#processstartinfo-throws-invalidoperationexception-for-processes-you-didnt-start) | .NET Core 1.0 | ## .NET Core 3.0 @@ -73,6 +74,10 @@ The following breaking changes are documented on this page: ## .NET Core 2.1 +[!INCLUDE [path-apis-dont-throw-exception-for-invalid-paths](../../../includes/core-changes/corefx/2.1/path-apis-dont-throw-exception-for-invalid-paths.md)] + +*** + [!INCLUDE[Private fields added to built-in struct types](~/includes/core-changes/corefx/2.1/instantiate-struct.md)] *** diff --git a/docs/core/compatibility/fx-core.md b/docs/core/compatibility/fx-core.md index b154ccae3da48..89f5e884c030b 100644 --- a/docs/core/compatibility/fx-core.md +++ b/docs/core/compatibility/fx-core.md @@ -90,6 +90,11 @@ Windows Forms support was added to .NET Core in version 3.0. If you're migrating - [EnableVisualStyleValidation compatibility switch not supported](#enablevisualstylevalidation-compatibility-switch-not-supported) - [UseLegacyContextMenuStripSourceControlValue compatibility switch not supported](#uselegacycontextmenustripsourcecontrolvalue-compatibility-switch-not-supported) - [UseLegacyImages compatibility switch not supported](#uselegacyimages-compatibility-switch-not-supported) +- [About and SplashScreen templates are broken for Visual Basic](#about-and-splashscreen-templates-are-broken) +- [Types in Microsoft.VisualBasic.ApplicationServices namespace not available](#types-in-microsoftvisualbasicapplicationservices-namespace-not-available) +- [Types in Microsoft.VisualBasic.Devices namespace not available](#types-in-microsoftvisualbasicdevices-namespace-not-available) +- [Types in Microsoft.VisualBasic.MyServices namespace not available](#types-in-microsoftvisualbasicmyservices-namespace-not-available) +- [Microsoft.VisualBasic.Constants.vbNewLine is obsolete](#microsoftvisualbasicconstantsvbnewline-is-obsolete) ### .NET Core 3.1 @@ -147,6 +152,25 @@ Windows Forms support was added to .NET Core in version 3.0. If you're migrating *** +[!INCLUDE[About and SplashScreen templates are broken for Visual Basic](~/includes/core-changes/visualbasic/3.0/vb-winforms-splash-about-broken.md)] + +*** + +[!INCLUDE[Types in Microsoft.VisualBasic.ApplicationServices namespace not available](~/includes/core-changes/visualbasic/3.0/microsoft.visualbasic.applicationservices-unavailable.md)] + +*** +[!INCLUDE[Types in Microsoft.VisualBasic.Devices namespace not available](~/includes/core-changes/visualbasic/3.0/microsoft.visualbasic.devices-unavailable.md)] + +*** + +[!INCLUDE[Types in Microsoft.VisualBasic.MyServices namespace not available](~/includes/core-changes/visualbasic/3.0/microsoft.visualbasic.myservices-unavailable.md)] + +*** + +[!INCLUDE[vbNewLine is obsolete](~/includes/core-changes/visualbasic/3.0/vbnewline-is-obsolete.md)] + +*** + ## See also - [APIs that always throw exceptions on .NET Core](unsupported-apis.md) diff --git a/docs/core/compatibility/index.md b/docs/core/compatibility/index.md index e3a562d85ae9d..edc8603419818 100644 --- a/docs/core/compatibility/index.md +++ b/docs/core/compatibility/index.md @@ -1,7 +1,8 @@ --- title: Types of breaking changes description: Learn how .NET attempts to maintain compatibility for developers across .NET versions, and what kind of change is considered a breaking change. -ms.date: 01/28/2021 +ms.date: 05/12/2021 +ms.topic: conceptual --- # Changes that affect compatibility @@ -120,6 +121,8 @@ Changes in this category modify the public surface area of a type. Most of the c - ❌ **DISALLOWED: Adding a member to an interface** + If you [provide an implementation](../../csharp/whats-new/tutorials/default-interface-methods-versions.md), adding a new member to an existing interface won't necessarily result in compile failures in downstream assemblies. However, not all languages support default interface members (DIMs). Also, in some scenarios, the runtime can't decide which default interface member to invoke. For these reasons, adding a member to an existing interface is considered a breaking change. + - ❌ **DISALLOWED: Changing the value of a public constant or enumeration member** - ❌ **DISALLOWED: Changing the type of a property, field, parameter, or return value** @@ -144,15 +147,16 @@ Changes in this category modify the public surface area of a type. Most of the c - ❌ **DISALLOWED: Removing the [virtual](../../csharp/language-reference/keywords/virtual.md) keyword from a member** +- ❌ **DISALLOWED: Adding the [virtual](../../csharp/language-reference/keywords/virtual.md) keyword to a member** + While this often is not a breaking change because the C# compiler tends to emit [callvirt]() Intermediate Language (IL) instructions to call non-virtual methods (`callvirt` performs a null check, while a normal call doesn't), this behavior is not invariable for several reasons: + - C# is not the only language that .NET targets. - The C# compiler increasingly tries to optimize `callvirt` to a normal call whenever the target method is non-virtual and is probably not null (such as a method accessed through the [?. null propagation operator](../../csharp/language-reference/operators/member-access-operators.md#null-conditional-operators--and-)). Making a method virtual means that the consumer code would often end up calling it non-virtually. -- ❌ **DISALLOWED: Adding the [virtual](../../csharp/language-reference/keywords/virtual.md) keyword to a member** - - ❌ **DISALLOWED: Making a virtual member abstract** A [virtual member](../../csharp/language-reference/keywords/virtual.md) provides a method implementation that *can be* overridden by a derived class. An [abstract member](../../csharp/language-reference/keywords/abstract.md) provides no implementation and *must be* overridden. @@ -310,3 +314,7 @@ Changes in this category modify the public surface area of a type. Most of the c - ❌ **DISALLOWED: Changing the number of times given events are called** - ❌ **DISALLOWED: Adding the to an enumeration type** + +## See also + +- [Library design guidelines - breaking changes](../../standard/library-guidance/breaking-changes.md) diff --git a/docs/core/compatibility/msbuild/5.0/publishdepsfilepath-behavior-change.md b/docs/core/compatibility/msbuild/5.0/publishdepsfilepath-behavior-change.md index 262ac3cd8aeeb..6b6066c7ae528 100644 --- a/docs/core/compatibility/msbuild/5.0/publishdepsfilepath-behavior-change.md +++ b/docs/core/compatibility/msbuild/5.0/publishdepsfilepath-behavior-change.md @@ -21,7 +21,7 @@ Starting in .NET 5, `PublishDepsFilePath` is empty for single-file applications This change was made for a couple of reasons: -- Due to a refactoring of the publish logic in order to support [improved single-file apps](https://github.com/dotnet/designs/blob/master/accepted/2020/single-file/design.md) in .NET 5. +- Due to a refactoring of the publish logic in order to support [improved single-file apps](https://github.com/dotnet/designs/blob/main/accepted/2020/single-file/design.md) in .NET 5. - In single-file apps, to help guard against targets that try to rewrite the *deps.json* file after *deps.json* has already been bundled, thus silently not affecting the app. For this reason, `PublishDepsFilePath` is empty for single-file applications. diff --git a/docs/core/compatibility/networking/6.0/webrequest-deprecated.md b/docs/core/compatibility/networking/6.0/webrequest-deprecated.md new file mode 100644 index 0000000000000..826e81f5ccc10 --- /dev/null +++ b/docs/core/compatibility/networking/6.0/webrequest-deprecated.md @@ -0,0 +1,46 @@ +--- +title: "Breaking change: WebRequest, WebClient, and ServicePoint are obsolete" +description: Learn about the breaking change in .NET 6.0 where WebRequest, WebClient, and ServicePoint are deprecated in favor of HttpClient. +ms.date: 04/26/2021 +--- +# WebRequest, WebClient, and ServicePoint are obsolete + +, , and classes are marked as obsolete and generate a `SYSLIB0014` warning at compile time. + +## Version introduced + +6.0 + +## Change description + +, , and classes were added to .NET Core in version 2.0 for backward compatibility. However, they introduced several runtime breaking changes, for example, `WebRequest.GetRequestStream` allocates memory for the whole response, and `WebClient.CancelAsync` doesn't always cancel immediately. + +Starting in .NET 6, the , , and classes are deprecated. The classes are still available, but they're not recommended for new development. To reduce the number of analyzer warnings, only construction methods are decorated with the attribute. + +## Recommended action + +Use the class instead. + +## Affected APIs + +- +- +- +- +- + + diff --git a/docs/core/compatibility/windows-forms/5.0/automatically-infer-winexe-output-type.md b/docs/core/compatibility/sdk/5.0/automatically-infer-winexe-output-type.md similarity index 93% rename from docs/core/compatibility/windows-forms/5.0/automatically-infer-winexe-output-type.md rename to docs/core/compatibility/sdk/5.0/automatically-infer-winexe-output-type.md index 06f8ab600fab6..0a7ad04759fc8 100644 --- a/docs/core/compatibility/windows-forms/5.0/automatically-infer-winexe-output-type.md +++ b/docs/core/compatibility/sdk/5.0/automatically-infer-winexe-output-type.md @@ -25,7 +25,7 @@ Starting in the 5.0.100 version of the .NET SDK, when `OutputType` is set to `Ex ``` - If `OutputType` is not specified in the project file, it defaults to `Library` and that value doesn't change. +If `OutputType` is not specified in the project file, it defaults to `Library` and that value doesn't change. ## Reason for change @@ -33,7 +33,7 @@ It's assumed that most users don't want a console window to open when a WPF or W ## Version introduced -.NET 5.0.100 +.NET SDK 5.0.100 ## Recommended action @@ -55,6 +55,7 @@ Not detectable via API analysis. ### Category +- SDK - Windows Forms - Windows Presentation Framework (WPF) diff --git a/docs/core/compatibility/sdk/5.0/referencing-executable-generates-error.md b/docs/core/compatibility/sdk/5.0/referencing-executable-generates-error.md new file mode 100644 index 0000000000000..bb4f044ac60ff --- /dev/null +++ b/docs/core/compatibility/sdk/5.0/referencing-executable-generates-error.md @@ -0,0 +1,46 @@ +--- +title: "Breaking change: Error generated when executable references executable" +description: Learn about the breaking change in .NET 5 where compile-time errors are generated when an executable references an executable whose SelfContained value is different. +ms.date: 05/26/2021 +--- +# Error generated when executable project references mismatched executable + +Generally, an executable project references library projects, not other executable projects. An executable project can also reference another executable project to use APIs that are defined in it. Some developers want to reference an executable project from another executable project so that both apps are placed in and are runnable from the same output folder. However, this scenario does not work if a self-contained executable references a non-self-contained executable, or vice versa. Because of how the application host works, neither app can be launched. To prevent situations where apps aren't runnable, .NET SDK 5+ produces compile-time errors NETSDK1150 and NETSDK1151 when it detects mismatched executable references. + +## Change description + +In previous .NET SDK versions, you could reference a self-contained executable project from a non-self-contained executable project without a build error. However, both apps would not be runnable. Starting in .NET SDK 5, an error is generated if an executable project references another executable project and the `SelfContained` values don't match. + +## Version introduced + +.NET SDK 5.0.300 + +## Reason for change + +The errors were introduced to prevent situations where you expect to be able to launch both applications but cannot. + +## Recommended action + +If the referenced project doesn't need to be runnable from the output folder, you can set a property to avoid this error check: + +```xml +false +``` + +For more information, see [ValidateExecutableReferencesMatchSelfContained](../../../project-sdk/msbuild-props.md#validateexecutablereferencesmatchselfcontained). + +## Affected APIs + +None. + + diff --git a/docs/core/compatibility/windows-forms/5.0/sdk-and-target-framework-change.md b/docs/core/compatibility/sdk/5.0/sdk-and-target-framework-change.md similarity index 98% rename from docs/core/compatibility/windows-forms/5.0/sdk-and-target-framework-change.md rename to docs/core/compatibility/sdk/5.0/sdk-and-target-framework-change.md index ca90df50ae121..23c9f368a7106 100644 --- a/docs/core/compatibility/windows-forms/5.0/sdk-and-target-framework-change.md +++ b/docs/core/compatibility/sdk/5.0/sdk-and-target-framework-change.md @@ -52,7 +52,7 @@ In your WPF or Windows Forms project file: ## Affected APIs -Not detectable via API analysis. +None. - $(NoWarn);SYSLIB0001 - - $(NoWarn);SYSLIB0002 - $(NoWarn);SYSLIB0003 - - $(NoWarn);SYSLIB0001;SYSLIB0002;SYSLIB0003 - - -``` - -> [!NOTE] -> Suppressing warnings in this way only disables the obsoletion warnings you specify. It doesn't disable any other warnings, including obsoletion warnings with different diagnostic IDs. diff --git a/docs/core/compatibility/syslib-warnings/syslib0006.md b/docs/core/compatibility/syslib-warnings/syslib0006.md deleted file mode 100644 index 530e1df5cd0af..0000000000000 --- a/docs/core/compatibility/syslib-warnings/syslib0006.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: SYSLIB0006 warning -description: Learn about the obsoletions that generate compile-time warning SYSLIB0006. -ms.topic: reference -ms.date: 10/20/2020 ---- -# SYSLIB0006: Thread.Abort is not supported - -The following APIs are marked obsolete, starting in .NET 5.0. Use of these APIs generates warning `SYSLIB0006` at compile time. - -- -- - -## Workarounds - -Use a to abort processing of a unit of work instead of calling . The following example illustrates the use of . - -```csharp -void ProcessPendingWorkItemsNew(CancellationToken cancellationToken) -{ - if (QueryIsMoreWorkPending()) - { - // If the CancellationToken is marked as "needs to cancel", - // this will throw the appropriate exception. - cancellationToken.ThrowIfCancellationRequested(); - - WorkItem work = DequeueWorkItem(); - ProcessWorkItem(work); - } -} -``` - -[!INCLUDE [suppress-syslib-warning](../../../../includes/suppress-syslib-warning.md)] - -## See also - -- [Thread.Abort is obsolete](../core-libraries/5.0/thread-abort-obsolete.md) -- [Cancellation in managed threads](../../../standard/threading/cancellation-in-managed-threads.md) diff --git a/docs/core/compatibility/syslib-warnings/syslib0008.md b/docs/core/compatibility/syslib-warnings/syslib0008.md deleted file mode 100644 index b2120fd4f8fad..0000000000000 --- a/docs/core/compatibility/syslib-warnings/syslib0008.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: SYSLIB0008 warning -description: Learn about the obsoletion that generates compile-time warning SYSLIB0008. -ms.topic: reference -ms.date: 10/20/2020 ---- -# SYSLIB0008: CreatePdbGenerator is not supported - -The API is marked obsolete, starting in .NET 5.0. Using this API generates warning `SYSLIB0008` at compile time. - -## Suppress the warning - -If you cannot change your code, you can suppress the warning through a `#pragma` directive or a `` project setting. For examples, see [Suppress warnings](../syslib-obsoletions.md#suppress-warnings). diff --git a/docs/core/compatibility/syslib-warnings/syslib0009.md b/docs/core/compatibility/syslib-warnings/syslib0009.md deleted file mode 100644 index 0b962f616c21e..0000000000000 --- a/docs/core/compatibility/syslib-warnings/syslib0009.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: SYSLIB0009 warning -description: Learn about the obsoletions that generate compile-time warning SYSLIB0009. -ms.topic: reference -ms.date: 10/20/2020 ---- -# SYSLIB0009: The AuthenticationManager Authenticate and PreAuthenticate methods are not supported - -The following APIs are marked obsolete, starting in .NET 5.0. Use of these APIs generates warning `SYSLIB0009` at compile time. - -- -- - -## Suppress the warning - -If you cannot change your code, you can suppress the warning through a `#pragma` directive or a `` project setting. For examples, see [Suppress warnings](../syslib-obsoletions.md#suppress-warnings). diff --git a/docs/core/compatibility/syslib-warnings/syslib0010.md b/docs/core/compatibility/syslib-warnings/syslib0010.md deleted file mode 100644 index 4edec657fa795..0000000000000 --- a/docs/core/compatibility/syslib-warnings/syslib0010.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: SYSLIB0010 warning -description: Learn about the obsoletions that generate compile-time warning SYSLIB0010. -ms.topic: reference -ms.date: 10/20/2020 ---- -# SYSLIB0010: Unsupported remoting APIs - -[.NET remoting](/previous-versions/dotnet/netframework-1.1/kwdt6w2k(v=vs.71)) is a legacy technology, and the infrastructure exists only in .NET Framework. The following remoting-related APIs are marked as obsolete, starting in .NET 5.0. Using them in code generates warning `SYSLIB0010` at compile time. - -- -- - -## Workarounds - -Consider using WCF or HTTP-based REST services to communicate with objects in other applications or across machines. For more information, see [.NET Framework technologies unavailable on .NET Core](../../porting/net-framework-tech-unavailable.md). - -[!INCLUDE [suppress-syslib-warning](../../../../includes/suppress-syslib-warning.md)] - -## See also - -- [.NET remoting](/previous-versions/dotnet/netframework-1.1/kwdt6w2k(v=vs.71)) diff --git a/docs/core/compatibility/syslib-warnings/syslib0011.md b/docs/core/compatibility/syslib-warnings/syslib0011.md deleted file mode 100644 index 8c25983e3e248..0000000000000 --- a/docs/core/compatibility/syslib-warnings/syslib0011.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: SYSLIB0011 warning -description: Learn about the obsoletions that generate compile-time warning SYSLIB0011. -ms.topic: reference -ms.date: 10/20/2020 ---- -# SYSLIB0011: BinaryFormatter serialization is obsolete - -Due to [security vulnerabilities](../../../standard/serialization/binaryformatter-security-guide.md#binaryformatter-security-vulnerabilities) in , the following APIs are marked as obsolete, starting in .NET 5.0. Using them in code generates warning `SYSLIB0011` at compile time. - -- -- -- -- -- -- - -## Workarounds - -Consider using or instead of . - -For more information about recommended actions, see [Resolving BinaryFormatter obsoletion and disablement errors](../../../standard/serialization/binaryformatter-security-guide.md). - -[!INCLUDE [suppress-syslib-warning](../../../../includes/suppress-syslib-warning.md)] - -## See also - -- [Resolving BinaryFormatter obsoletion and disablement errors](../../../standard/serialization/binaryformatter-security-guide.md) -- [BinaryFormatter serialization methods are obsolete and prohibited in ASP.NET apps](../core-libraries/5.0/binaryformatter-serialization-obsolete.md) diff --git a/docs/core/compatibility/syslib-warnings/syslib0012.md b/docs/core/compatibility/syslib-warnings/syslib0012.md deleted file mode 100644 index 4af88b8f1a603..0000000000000 --- a/docs/core/compatibility/syslib-warnings/syslib0012.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: SYSLIB0012 warning -description: Learn about the obsoletions that generate compile-time warning SYSLIB0012. -ms.topic: reference -ms.date: 10/20/2020 ---- -# SYSLIB0012: Assembly.CodeBase and Assembly.EscapedCodeBase are obsolete - -The following APIs are marked as obsolete, starting in .NET 5.0. Using them in code generates warning `SYSLIB0012` at compile time. - -- -- - -## Workarounds - -Use instead. - -[!INCLUDE [suppress-syslib-warning](../../../../includes/suppress-syslib-warning.md)] diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index f7cdc2f9a5f7c..8f9a4b43443a2 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -25,32 +25,62 @@ items: href: 6.0.md - name: ASP.NET Core items: - - name: Nullable reference type annotations changed - href: aspnet-core/6.0/nullable-reference-type-annotations-changed.md - - name: Obsoleted and removed APIs - href: aspnet-core/6.0/obsolete-removed-apis.md + - name: Assemblies removed from shared framework + href: aspnet-core/6.0/assemblies-removed-from-shared-framework.md - name: "Blazor: Parameter name changed in RequestImageFileAsync method" href: aspnet-core/6.0/blazor-parameter-name-changed-in-method.md - name: "Blazor: WebEventDescriptor.EventArgsType property replaced" - href: aspnet-core/6.0/blazor-eventargstype-property-replaced.md + href: aspnet-core/6.0/blazor-eventargstype-property-replaced.md - name: "Kestrel: Log message attributes changed" href: aspnet-core/6.0/kestrel-log-message-attributes-changed.md + - name: "MessagePack: Library changed in @microsoft/signalr-protocol-msgpack" + href: aspnet-core/6.0/messagepack-library-change.md + - name: Microsoft.AspNetCore.Http.Features split + href: aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md - name: "Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports" href: aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md + - name: "Middleware: New Use overload" + href: aspnet-core/6.0/middleware-new-use-overload.md + - name: MVC doesn't buffer IAsyncEnumerable types + href: aspnet-core/6.0/iasyncenumerable-not-buffered-by-mvc.md + - name: Nullable reference type annotations changed + href: aspnet-core/6.0/nullable-reference-type-annotations-changed.md + - name: Obsoleted and removed APIs + href: aspnet-core/6.0/obsolete-removed-apis.md + - name: PreserveCompilationContext not configured by default + href: aspnet-core/6.0/preservecompilationcontext-not-set-by-default.md + - name: "Razor: Compiler generates single assembly" + href: aspnet-core/6.0/razor-compiler-doesnt-produce-views-assembly.md - name: "Razor: RazorEngine APIs marked obsolete" href: aspnet-core/6.0/razor-engine-apis-obsolete.md + - name: "SignalR: Java Client updated to RxJava3" + href: aspnet-core/6.0/signalr-java-client-updated.md - name: Core .NET libraries items: + - name: API obsoletions with non-default diagnostic IDs + href: core-libraries/6.0/obsolete-apis-with-custom-diagnostics.md + - name: Environment.ProcessorCount behavior on Windows + href: core-libraries/6.0/environment-processorcount-on-windows.md + - name: New Queryable method overloads + href: core-libraries/6.0/additional-linq-queryable-method-overloads.md - name: Nullability annotation changes href: core-libraries/6.0/nullable-ref-type-annotation-changes.md - name: Parameters renamed in Stream-derived types href: core-libraries/6.0/parameters-renamed-on-stream-derived-types.md - name: Standard numeric format parsing precision href: core-libraries/6.0/numeric-format-parsing-handles-higher-precision.md + - name: Unhandled exceptions from a BackgroundService + href: core-libraries/6.0/hosting-exception-handling.md + - name: Networking + items: + - name: WebRequest, WebClient, and ServicePoint are obsolete + href: networking/6.0/webrequest-deprecated.md - name: Windows Forms items: - name: APIs throw ArgumentNullException href: windows-forms/6.0/apis-throw-argumentnullexception.md + - name: DataGridView APIs throw InvalidOperationException + href: windows-forms/6.0/null-owner-causes-invalidoperationexception.md - name: NotifyIcon.Text maximum text length increased href: windows-forms/6.0/notifyicon-text-max-text-length-increased.md - name: TableLayoutSettings properties throw InvalidEnumArgumentException @@ -63,6 +93,8 @@ items: href: 5.0.md - name: ASP.NET Core items: + - name: AddDataAnnotationsValidation method made obsolete + href: aspnet-core/6.0/adddataannotationsvalidation-obsolete.md - name: ASP.NET Core apps deserialize quoted numbers href: serialization/5.0/jsonserializer-allows-reading-numbers-as-strings.md - name: AzureAD.UI and AzureADB2C.UI APIs obsolete @@ -265,6 +297,14 @@ items: href: networking/5.0/negotiatestream-sslstream-dont-fail-on-successive-begin-calls.md - name: WinHttpHandler removed from .NET runtime href: networking/5.0/winhttphandler-removed-from-runtime.md + - name: SDK + items: + - name: Error when referencing mismatched executable + href: sdk/5.0/referencing-executable-generates-error.md + - name: OutputType set to WinExe + href: sdk/5.0/automatically-infer-winexe-output-type.md + - name: WinForms and WPF apps use Microsoft.NET.Sdk + href: sdk/5.0/sdk-and-target-framework-change.md - name: Security items: - name: Code access security APIs are obsolete @@ -327,20 +367,38 @@ items: items: - name: .NET 6 items: - - name: "Nullable reference type annotations changed" - href: aspnet-core/6.0/nullable-reference-type-annotations-changed.md - - name: "Obsoleted and removed APIs" - href: aspnet-core/6.0/obsolete-removed-apis.md + - name: AddDataAnnotationsValidation method made obsolete + href: aspnet-core/6.0/adddataannotationsvalidation-obsolete.md + - name: Assemblies removed from shared framework + href: aspnet-core/6.0/assemblies-removed-from-shared-framework.md - name: "Blazor: Parameter name changed in RequestImageFileAsync method" href: aspnet-core/6.0/blazor-parameter-name-changed-in-method.md - name: "Blazor: WebEventDescriptor.EventArgsType property replaced" href: aspnet-core/6.0/blazor-eventargstype-property-replaced.md - name: "Kestrel: Log message attributes changed" href: aspnet-core/6.0/kestrel-log-message-attributes-changed.md + - name: "MessagePack: Library changed in @microsoft/signalr-protocol-msgpack" + href: aspnet-core/6.0/messagepack-library-change.md + - name: Microsoft.AspNetCore.Http.Features split + href: aspnet-core/6.0/microsoft-aspnetcore-http-features-package-split.md - name: "Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports" href: aspnet-core/6.0/middleware-ambiguous-https-ports-exception.md + - name: "Middleware: New Use overload" + href: aspnet-core/6.0/middleware-new-use-overload.md + - name: MVC doesn't buffer IAsyncEnumerable types + href: aspnet-core/6.0/iasyncenumerable-not-buffered-by-mvc.md + - name: Nullable reference type annotations changed + href: aspnet-core/6.0/nullable-reference-type-annotations-changed.md + - name: Obsoleted and removed APIs + href: aspnet-core/6.0/obsolete-removed-apis.md + - name: PreserveCompilationContext not configured by default + href: aspnet-core/6.0/preservecompilationcontext-not-set-by-default.md + - name: "Razor: Compiler generates single assembly" + href: aspnet-core/6.0/razor-compiler-doesnt-produce-views-assembly.md - name: "Razor: RazorEngine APIs marked obsolete" href: aspnet-core/6.0/razor-engine-apis-obsolete.md + - name: "SignalR: Java Client updated to RxJava3" + href: aspnet-core/6.0/signalr-java-client-updated.md - name: .NET 5 items: - name: ASP.NET Core apps deserialize quoted numbers @@ -441,12 +499,20 @@ items: items: - name: .NET 6 items: + - name: API obsoletions with non-default diagnostic IDs + href: core-libraries/6.0/obsolete-apis-with-custom-diagnostics.md + - name: Environment.ProcessorCount behavior on Windows + href: core-libraries/6.0/environment-processorcount-on-windows.md + - name: New Queryable method overloads + href: core-libraries/6.0/additional-linq-queryable-method-overloads.md - name: Nullability annotation changes href: core-libraries/6.0/nullable-ref-type-annotation-changes.md - name: Parameters renamed in Stream-derived types href: core-libraries/6.0/parameters-renamed-on-stream-derived-types.md - name: Standard numeric format parsing precision href: core-libraries/6.0/numeric-format-parsing-handles-higher-precision.md + - name: Unhandled exceptions from a BackgroundService + href: core-libraries/6.0/hosting-exception-handling.md - name: .NET 5 items: - name: Assembly-related API changes for single-file publishing @@ -505,7 +571,7 @@ items: href: core-libraries/5.0/vector-lerp-behavior-change.md - name: Vector throws NotSupportedException href: core-libraries/5.0/vectort-throws-notsupportedexception.md - - name: .NET 1.0-3.1 + - name: .NET Core 1.0-3.1 href: corefx.md - name: Cryptography items: @@ -541,7 +607,7 @@ items: href: globalization/5.0/unicode-categories-for-latin1-chars.md - name: ListSeparator values changed href: globalization/5.0/listseparator-value-change.md - - name: .NET 3.0 + - name: .NET Core 3.0 href: globalization.md - name: Interop items: @@ -569,6 +635,10 @@ items: href: msbuild.md - name: Networking items: + - name: .NET 6 + items: + - name: WebRequest, WebClient, and ServicePoint are obsolete + href: networking/6.0/webrequest-deprecated.md - name: .NET 5 items: - name: Cookie path handling conforms to RFC 6265 @@ -581,8 +651,18 @@ items: href: networking/5.0/negotiatestream-sslstream-dont-fail-on-successive-begin-calls.md - name: WinHttpHandler removed from .NET runtime href: networking/5.0/winhttphandler-removed-from-runtime.md - - name: .NET 2.0-3.0 + - name: .NET Core 2.0-3.0 href: networking.md + - name: SDK + items: + - name: .NET 5 + items: + - name: Error when referencing mismatched executable + href: sdk/5.0/referencing-executable-generates-error.md + - name: OutputType set to WinExe + href: sdk/5.0/automatically-infer-winexe-output-type.md + - name: WinForms and WPF apps use Microsoft.NET.Sdk + href: sdk/5.0/sdk-and-target-framework-change.md - name: Security items: - name: .NET 5 @@ -619,6 +699,8 @@ items: items: - name: APIs throw ArgumentNullException href: windows-forms/6.0/apis-throw-argumentnullexception.md + - name: DataGridView APIs throw InvalidOperationException + href: windows-forms/6.0/null-owner-causes-invalidoperationexception.md - name: NotifyIcon.Text maximum text length increased href: windows-forms/6.0/notifyicon-text-max-text-length-increased.md - name: TableLayoutSettings properties throw InvalidEnumArgumentException @@ -657,32 +739,3 @@ items: href: windows-forms/5.0/automatically-infer-winexe-output-type.md - name: WPF apps use Microsoft.NET.Sdk href: windows-forms/5.0/sdk-and-target-framework-change.md - - name: SYSLIB warnings - items: - - name: Overview - displayName: syslib, obsolete, obsoletion - href: syslib-obsoletions.md - - name: SYSLIB0001 - href: syslib-warnings/syslib0001.md - - name: SYSLIB0002 - href: syslib-warnings/syslib0002.md - - name: SYSLIB0003 - href: syslib-warnings/syslib0003.md - - name: SYSLIB0004 - href: syslib-warnings/syslib0004.md - - name: SYSLIB0005 - href: syslib-warnings/syslib0005.md - - name: SYSLIB0006 - href: syslib-warnings/syslib0006.md - - name: SYSLIB0007 - href: syslib-warnings/syslib0007.md - - name: SYSLIB0008 - href: syslib-warnings/syslib0008.md - - name: SYSLIB0009 - href: syslib-warnings/syslib0009.md - - name: SYSLIB0010 - href: syslib-warnings/syslib0010.md - - name: SYSLIB0011 - href: syslib-warnings/syslib0011.md - - name: SYSLIB0012 - href: syslib-warnings/syslib0012.md diff --git a/docs/core/compatibility/unsupported-apis.md b/docs/core/compatibility/unsupported-apis.md index 620e0642e5506..408a8ed722ef2 100644 --- a/docs/core/compatibility/unsupported-apis.md +++ b/docs/core/compatibility/unsupported-apis.md @@ -6,7 +6,7 @@ ms.date: 10/13/2020 --- # APIs that always throw exceptions on .NET Core and .NET 5+ -The following APIs will always throw a on .NET 5 and later versions (including all versions of .NET Core) on all or a subset of platforms. +The following APIs will always throw an exception on .NET 5 and later versions (including all versions of .NET Core) on all or a subset of platforms. In most cases, the exception that's thrown is . This article organizes the affected APIs by namespace. @@ -21,6 +21,7 @@ This article organizes the affected APIs by namespace. | - | - | | | All | | | All | +| | All | | | Linux and macOS | | | Linux and macOS | | | All | @@ -163,12 +164,14 @@ This article organizes the affected APIs by namespace. | Member | Platforms that throw | | - | - | +| | All | +| | All | | | All | | | All | | | All | +| | All | | | All | -| | All | -| | All | +| | All | | | All | ## System.Runtime.CompilerServices diff --git a/docs/core/compatibility/visualbasic.md b/docs/core/compatibility/visualbasic.md index 67467db4adbad..760247bdc72f5 100644 --- a/docs/core/compatibility/visualbasic.md +++ b/docs/core/compatibility/visualbasic.md @@ -1,14 +1,33 @@ --- title: Visual Basic breaking changes description: Lists the breaking changes in Visual Basic used with .NET Core 3.0. -ms.date: "09/20/2019" +ms.date: "05/25/2021" --- # Visual Basic breaking changes in .NET Core 3.0 The following is a list of breaking changes in Visual Basic: +- [Types in Microsoft.VisualBasic.ApplicationServices namespace not available](#types-in-microsoftvisualbasicapplicationservices-namespace-not-available) +- [Types in Microsoft.VisualBasic.Devices namespace not available](#types-in-microsoftvisualbasicdevices-namespace-not-available) +- [Types in Microsoft.VisualBasic.MyServices namespace not available](#types-in-microsoftvisualbasicmyservices-namespace-not-available) - [Microsoft.VisualBasic.Constants.vbNewLine is obsolete](#microsoftvisualbasicconstantsvbnewline-is-obsolete) +- [About and SplashScreen templates are broken](#about-and-splashscreen-templates-are-broken) ## .NET Core 3.0 +[!INCLUDE[Types in Microsoft.VisualBasic.ApplicationServices namespace not available](~/includes/core-changes/visualbasic/3.0/microsoft.visualbasic.applicationservices-unavailable.md)] + +*** +[!INCLUDE[Types in Microsoft.VisualBasic.Devices namespace not available](~/includes/core-changes/visualbasic/3.0/microsoft.visualbasic.devices-unavailable.md)] + +*** + +[!INCLUDE[Types in Microsoft.VisualBasic.MyServices namespace not available](~/includes/core-changes/visualbasic/3.0/microsoft.visualbasic.myservices-unavailable.md)] + +*** + [!INCLUDE[vbNewLine is obsolete](~/includes/core-changes/visualbasic/3.0/vbnewline-is-obsolete.md)] + +*** + +[!INCLUDE[About and SplashScreen templates are broken for Visual Basic](~/includes/core-changes/visualbasic/3.0/vb-winforms-splash-about-broken.md)] diff --git a/docs/core/compatibility/windows-forms/5.0/null-owner-causes-invalidoperationexception.md b/docs/core/compatibility/windows-forms/5.0/null-owner-causes-invalidoperationexception.md index 2f1d55f4ec1e1..5df9aea970ce0 100644 --- a/docs/core/compatibility/windows-forms/5.0/null-owner-causes-invalidoperationexception.md +++ b/docs/core/compatibility/windows-forms/5.0/null-owner-causes-invalidoperationexception.md @@ -1,15 +1,17 @@ --- -title: "Breaking change: DataGridView-related APIs throw InvalidOperationException" +title: ".NET 5 breaking change: DataGridView-related APIs throw InvalidOperationException" description: Learn about the breaking change in .NET 5 where some APIs related to DataGridView throw an exception if the object's DataGridViewCellAccessibleObject.Owner value is null. ms.date: 09/18/2020 --- -# DataGridView-related APIs now throw InvalidOperationException +# DataGridView-related APIs throw InvalidOperationException Some APIs related to now throw an if the object's value is `null`. ## Change description -In previous .NET versions, the affected APIs throw a when they are invoked and the value is `null`. Starting in .NET 5, these APIs throw an instead of a if the value is `null` when they are invoked. +In previous .NET versions, the affected APIs throw a when they are invoked and the property value is `null`. Starting in .NET 5, these APIs throw an instead of a if the property value is `null` when they're invoked. + +## Reason for change Throwing an conforms to the behavior of the .NET runtime. It also improves the debugging experience by clearly communicating the invalid property. @@ -23,7 +25,7 @@ Review your code and, if necessary, update it to prevent constructing the affect ## Affected APIs -The following table lists the affected properties and parameters: +The following table lists the affected APIs: > [!div class="mx-tdBreakAll"] > | Affected method or property | Validated property | Version added | @@ -41,6 +43,10 @@ The following table lists the affected properties and parameters: > | | | 5.0 | > | | | 5.0 | +## See also + +- [DataGridView-related APIs throw InvalidOperationException (.NET 6)](../6.0/null-owner-causes-invalidoperationexception.md) + diff --git a/docs/core/compatibility/winforms.md b/docs/core/compatibility/winforms.md index 81375d8dea260..fba4717edf82b 100644 --- a/docs/core/compatibility/winforms.md +++ b/docs/core/compatibility/winforms.md @@ -24,6 +24,7 @@ The following breaking changes are documented on this page: | [EnableVisualStyleValidation compatibility switch not supported](#enablevisualstylevalidation-compatibility-switch-not-supported) | 3.0 | | [UseLegacyContextMenuStripSourceControlValue compatibility switch not supported](#uselegacycontextmenustripsourcecontrolvalue-compatibility-switch-not-supported) | 3.0 | | [UseLegacyImages compatibility switch not supported](#uselegacyimages-compatibility-switch-not-supported) | 3.0 | +| [About and SplashScreen templates are broken for Visual Basic](#about-and-splashscreen-templates-are-broken) | 3.0 | ## .NET Core 3.1 @@ -81,6 +82,10 @@ The following breaking changes are documented on this page: *** +[!INCLUDE[About and SplashScreen templates are broken for Visual Basic](~/includes/core-changes/visualbasic/3.0/vb-winforms-splash-about-broken.md)] + +*** + ## See also - [Port a Windows Forms app to .NET Core](/dotnet/desktop/winforms/migration/?view=netdesktop-5.0&preserve-view=true) diff --git a/docs/core/dependency-loading/collect-details.md b/docs/core/dependency-loading/collect-details.md index 2c6d8a64f32c3..5b1e5d120018f 100644 --- a/docs/core/dependency-loading/collect-details.md +++ b/docs/core/dependency-loading/collect-details.md @@ -30,7 +30,7 @@ The collected trace file can be viewed on Windows using the Events view in [Perf ## Example (on Windows) -This example uses the [assembly loading extension points sample](https://github.com/dotnet/samples/tree/master/core/extensions/AssemblyLoading). The application attempts to load an assembly `MyLibrary` - an assembly that is not referenced by the application and thus requires handling in an assembly loading extension point to be successfully loaded. +This example uses the [assembly loading extension points sample](/samples/dotnet/samples/assembly-loading-extension-points/). The application attempts to load an assembly `MyLibrary` - an assembly that is not referenced by the application and thus requires handling in an assembly loading extension point to be successfully loaded. ### Collect the trace diff --git a/docs/core/dependency-loading/understanding-assemblyloadcontext.md b/docs/core/dependency-loading/understanding-assemblyloadcontext.md index 68ff1eccbb468..7dea73d00a6ae 100644 --- a/docs/core/dependency-loading/understanding-assemblyloadcontext.md +++ b/docs/core/dependency-loading/understanding-assemblyloadcontext.md @@ -50,7 +50,7 @@ The articles This section covers the general principles for the relevant events and functions. - **Be repeatable**. A query for a specific dependency must always result in the same response. The same loaded dependency instance must be returned. This requirement is fundamental for cache consistency. For managed assemblies in particular, we're creating an cache. The cache key is a simple assembly name, . -- **Typically don't throw**. It's expected that these functions return `null` rather than throw when unable to find the requested dependency. Throwing will prematurely end the search and be propagate an exception to the caller. Throwing should be restricted to unexpected errors like a corrupted assembly or an out of memory condition. +- **Typically don't throw**. It's expected that these functions return `null` rather than throw when unable to find the requested dependency. Throwing will prematurely end the search and propagate an exception to the caller. Throwing should be restricted to unexpected errors like a corrupted assembly or an out of memory condition. - **Avoid recursion**. Be aware that these functions and handlers implement the loading rules for locating dependencies. Your implementation shouldn't call APIs that trigger recursion. Your code should typically call **AssemblyLoadContext** load functions that require a specific path or memory reference argument. - **Load into the correct AssemblyLoadContext**. The choice of where to load dependencies is application-specific. The choice is implemented by these events and functions. When your code calls **AssemblyLoadContext** load-by-path functions call them on the instance where you want the code loaded. Sometime returning `null` and letting the handle the load may be the simplest option. - **Be aware of thread races**. Loading can be triggered by multiple threads. The AssemblyLoadContext handles thread races by atomically adding assemblies to its cache. The race loser's instance is discarded. In your implementation logic, don't add extra logic that doesn't handle multiple threads properly. diff --git a/docs/core/deploying/deploy-with-cli.md b/docs/core/deploying/deploy-with-cli.md index 1e45c64e8e3b4..6abda7f4c53af 100644 --- a/docs/core/deploying/deploy-with-cli.md +++ b/docs/core/deploying/deploy-with-cli.md @@ -146,11 +146,11 @@ Whenever you use the `-r` switch, the output folder path changes to: `./bin/ [!NOTE] -> You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that are not globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/master/docs/design/features/globalization-invariant-mode.md). +> You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that are not globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). ## Self-contained deployment -When you publish a self-contained deployment (SCD), the .NET SDK creates a platform-specific executable. Publishing an SCD includes all required .NET files to run your app but it doesn't include the [native dependencies of .NET](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md). These dependencies must be present on the system before the app runs. +When you publish a self-contained deployment (SCD), the .NET SDK creates a platform-specific executable. Publishing an SCD includes all required .NET files to run your app but it doesn't include the [native dependencies of .NET](https://github.com/dotnet/core/blob/main/Documentation/prereqs.md). These dependencies must be present on the system before the app runs. Publishing an SCD creates an app that doesn't roll forward to the latest available .NET security patch. For more information on version binding at compile time, see [Select the .NET version to use](../versions/selection.md#self-contained-deployments-include-the-selected-runtime). @@ -169,7 +169,7 @@ You must use the following switches with the `dotnet publish` command to publish | | 5.0 | `dotnet publish -c Release -r --self-contained true` | > [!NOTE] -> You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that are not globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Core Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/master/docs/design/features/globalization-invariant-mode.md). +> You can reduce the total size of your deployment by enabling **globalization invariant mode**. This mode is useful for applications that are not globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). For more information about **globalization invariant mode** and how to enable it, see [.NET Core Globalization Invariant Mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). ## See also diff --git a/docs/core/deploying/deploy-with-vs.md b/docs/core/deploying/deploy-with-vs.md index c78f81ca78d9d..36e448fa8c2e5 100644 --- a/docs/core/deploying/deploy-with-vs.md +++ b/docs/core/deploying/deploy-with-vs.md @@ -88,7 +88,7 @@ Deploying a self-contained deployment with no third-party dependencies involves 1. Determine whether you want to use globalization invariant mode. - Particularly if your app targets Linux, you can reduce the total size of your deployment by taking advantage of [globalization invariant mode](https://github.com/dotnet/runtime/blob/master/docs/design/features/globalization-invariant-mode.md). Globalization invariant mode is useful for applications that are not globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). + Particularly if your app targets Linux, you can reduce the total size of your deployment by taking advantage of [globalization invariant mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). Globalization invariant mode is useful for applications that are not globally aware and that can use the formatting conventions, casing conventions, and string comparison and sort order of the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture). To enable invariant mode, right-click on your project (not the solution) in **Solution Explorer**, and select **Edit SCD.csproj** or **Edit SCD.vbproj**. Then add the following highlighted lines to the file: diff --git a/docs/core/deploying/index.md b/docs/core/deploying/index.md index e763cce9db417..6bf4a99273735 100644 --- a/docs/core/deploying/index.md +++ b/docs/core/deploying/index.md @@ -123,7 +123,7 @@ Because you have to publish your app for each platform, you know where your app Because your app includes the .NET runtime and all of your app dependencies, the download size and hard drive space required is greater than a [framework-dependent](#publish-framework-dependent) version. > [!TIP] - > You can reduce the size of your deployment on Linux systems by approximately 28 MB by using .NET [*globalization invariant mode*](https://github.com/dotnet/runtime/blob/master/docs/design/features/globalization-invariant-mode.md). This forces your app to treat all cultures like the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture?displayProperty=nameWithType). + > You can reduce the size of your deployment on Linux systems by approximately 28 MB by using .NET [*globalization invariant mode*](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). This forces your app to treat all cultures like the [invariant culture](xref:System.Globalization.CultureInfo.InvariantCulture?displayProperty=nameWithType). > [!TIP] > There is a [preview Trim feature](trim-self-contained.md) that can further reduce the size of your deployment. diff --git a/docs/core/deploying/prepare-libraries-for-trimming.md b/docs/core/deploying/prepare-libraries-for-trimming.md new file mode 100644 index 0000000000000..3af98f264724d --- /dev/null +++ b/docs/core/deploying/prepare-libraries-for-trimming.md @@ -0,0 +1,246 @@ +--- +title: Prepare .NET libraries for trimming +description: Learn how to prepare .NET libraries for trimming. +author: sbomer +ms.author: svbomer +ms.date: 04/16/2021 +--- + +# Prepare .NET libraries for trimming + +The .NET SDK makes it possible to reduce the size of self-contained apps by [trimming](trim-self-contained.md), removing unused code from the app and its dependencies. Not all code is compatible with trimming, so .NET 6 provides trim analysis [warnings](trimming-options.md#analysis-warnings) to detect patterns that may break trimmed apps. This document describes how to prepare libraries for trimming with the aid of these warnings, including recommendations for fixing some common cases. + +## Trim warnings in apps + +In .NET 6+, when publishing an app, the `PublishTrimmed` project file element will produce trim analysis warnings for patterns that are not statically understood to be compatible with trimming, including patterns in your code and in dependencies. + +You will encounter detailed warnings originating from your own code and `ProjectReference` dependencies. You may also see warnings like `warning IL2104: Assembly 'SomeAssembly' produced trim warnings` for `PackageReference` libraries. This warning means that the library contained patterns which are not guaranteed to work in the context of the trimmed app, and may result in a broken app. Consider contacting the author to see if the library can be annotated for trimming. + +To resolve warnings originating from the app code, see [resolving trim warnings](#resolve-trim-warnings). If you are interested in making your own `ProjectReference` libraries trim friendly, follow the instructions to [enable library trim warnings](#enable-library-trim-warnings). + +If your app only uses parts of a library that are compatible with trimming, consider [enabling trimming](trimming-options.md#trim-additional-assemblies) of this library if it is not already being trimmed. This will only produce warnings if your app uses problematic parts of the library. (You can also [show detailed warnings](trimming-options.md#show-detailed-warnings) for the library to see which parts of it are problematic.) + +## Enable library trim warnings + +These instructions show how to enable and resolve static analysis warnings to prepare a library for trimming. Follow these steps if you are authoring a library and either want to proactively make your library trimmable, or have been contacted by app authors who encountered trim warnings from your library. + +Ensure you are using the .NET 6 SDK for these steps. They will not work correctly in previous versions. + +## Enable Roslyn analyzer + +Set `true` (in .NET 6+) in your library project. This will not have any effect on the output, but it will enable trim analysis during build via a Roslyn analyzer. + +The Roslyn analyzer is useful for a fast feedback cycle with IDE integration, but is currently incomplete. It doesn't cover all trim analysis warnings, but the set of patterns it understands will improve over time to give more complete coverage. The Roslyn analyzer also isn't able to analyze the implementations of reference assemblies that you depend on. It is important to follow the next steps to ensure that your library is fully compatible with trimming. + +### Show all warnings + +To show all analysis warnings for your library, including warnings about dependencies, create a separate app project like the following that references your library, and publish it with `PublishTrimmed`. + +The extra step of creating an app project just to get complete warnings for a library is necessary because the implementations of dependencies are not generally available during `dotnet build`, and reference assemblies don't contain enough information to determine whether they are compatible with trimming. Publishing a self-contained app ensures that the library is analyzed in a context where its dependencies are available, so that you are alerted if your library uses any code from dependencies that could break a trimmed app. + +```xml + + + + Exe + net6.0 + + linux-x64 + true + + link + + + + + + + + + +``` + +```dotnetcli +dotnet publish -c Release +``` + +- `TrimmerRootAssembly` ensures that every part of the library is analyzed. This is necessary in case the library has `[AssemblyMetadata("IsTrimmable", "True")]`, which would otherwise let trimming remove the unused library without analyzing it. + +- `link` ensures that only used parts of dependencies are analyzed. Without this option, you would see warnings originating from _any_ part of a dependency that doesn't set `[AssemblyMetadata("IsTrimmable", "True")]`, including parts that are unused by your library. + +You can also follow the same pattern for multiple libraries, adding them all to the same project as `ProjectReference` and `TrimmerRootAssembly` item to see trim analysis warnings for more than one library at a time, but note that this will warn about dependencies if _any_ of the root libraries use a trim-unfriendly API in a dependency. To see warnings that have to do with only a particular library, reference that library only. + +> [!NOTE] +> The analysis results depend on the implementation details of your dependencies. If you update to a new version of a dependency, this may introduce analysis warnings if the new version added non-understood reflection patterns, even if there were no API changes. In other words, introducing trim analysis warnings to a library is a breaking change when the library is used with `PublishTrimmed`. + +## Resolve trim warnings + +The above steps will produce warnings about code that may cause problems when used in a trimmed app. Here are a few examples of the most common kinds of warnings you may encounter, with recommendations for fixing them. + +### RequiresUnreferencedCode + +```csharp +using System.Diagnostics.CodeAnalysis; + +public class MyLibrary +{ + public static void Method() + { + // warning IL2026 : MyLibrary.Method: Using method 'MyLibrary.DynamicBehavior' which has + // 'RequiresUnreferencedCodeAttribute' can break functionality + // when trimming application code. + DynamicBehavior(); + } + + [RequiresUnreferencedCode("DynamicBehavior is incompatible with trimming.")] + static void DynamicBehavior() + { + } +} +``` + +This means the library calls a method which has explicitly been annotated as incompatible with trimming, using [`RequiresUnreferencedCodeAttribute`]( +https://docs.microsoft.com/dotnet/api/system.diagnostics.codeanalysis.requiresunreferencedcodeattribute?view=net-5.0&preserve-view=true). To get rid of the warning, consider whether `Method` needs to call `DynamicBehavior` to do its job. If so, annotate the caller `Method` with `RequiresUnreferencedCode` as well; this will "bubble up" the warning so that callers of `Method` get a warning instead: + +```csharp +// Warn for calls to Method, but not for Method's call to DynamicBehavior. +[RequiresUnreferencedCode("Calls DynamicBehavior.")] +public static void Method() +{ + DynamicBehavior(); // OK. Doesn't warn now. +} +``` + +Once you have "bubbled up" the attribute all the way to public APIs (so that these warnings are produced only for public methods, if at all), you are done. Apps which call your library will now get warnings if they call those public APIs, but these will no longer produce warnings like `IL2104: Assembly 'MyLibrary' produced trim warnings`. + +### DynamicallyAccessedMembers + +```csharp +using System.Diagnostics.CodeAnalysis; + +public class MyLibrary +{ + static void UseMethods(Type type) + { + // warning IL2070: MyLibrary.UseMethods(Type): 'this' argument does not satisfy + // 'DynamicallyAccessedMemberTypes.PublicMethods' in call to 'System.Type.GetMethods()'. + // The parameter 't' of method 'MyLibrary.UseMethods(Type)' does not have matching annotations. + foreach (var method in type.GetMethods()) + { + // ... + } + } +} +``` + +Here, `UseMethods` is calling a reflection method that has a requirement. The requirement states that the type's public methods are available. In this case, you can satisfy the requirement by adding the same requirement to the parameter of `UseMethods`. + +```csharp +static void UseMethods( + // State the requirement in the UseMethods parameter. + [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicMethods)] + Type type) +{ + // ... +} +``` + +Now any calls to `UseMethods` will produce warnings if they pass in values which don't satisfy the `PublicMethods` requirement. Like with `RequiresUnreferencedCode`, once you have bubbled up such warnings to public APIs, you are done. + +Here is another example where an unknown `Type` flows into the annotated method parameter, this time from a field: + +```csharp +static Type type; + +static void UseMethodsHelper() +{ + // warning IL2077: MyLibrary.UseMethodsHelper(Type): 'type' argument does not satisfy + // 'DynamicallyAccessedMemberTypes.PublicMethods' in call to 'MyLibrary.UseMethods(Type)'. + // The field 'System.Type MyLibrary::type' does not have matching annotations. + UseMethods(type); +} +``` + +Similarly, here the problem is that the field `type` is passed into a parameter with these requinements. You can fix it by adding `DynamicallyAccessedMembers` to the field. This will warn about code that assigns incompatible values to the field instead. Sometimes this process will continue until a public API is annotated, and other times it will end when a concrete type flows into a location with these requirements. For example: + +```csharp +[DynamicallyAccessedMembers(DynamicallyAccessedMembers.PublicMethods)] +static Type type; + +static void InitializeTypeField() +{ + MyLibrary.type = typeof(System.Tuple); +} +``` + +In this case the trim analysis will simply keep public methods of `System.Tuple`, and will not produce further warnings. + +## Recommendations + +In general, try to avoid reflection if possible. When using reflection, limit it in scope so that it is reachable only from a small part of the library. + +- Avoid using non-understood patterns in places like static constructors that will result in the warning propagating to all members of the class. +- Avoid annotating virtual methods or interface methods, which will require all overrides to have matching annotations. +- In some cases, you will be able to mechanically propagate warnings through your code without issues. Sometimes this will result in much of your public API being annotated with `RequiresUnreferencedCode`, which is the right thing to do if the library indeed behaves in ways that can't be understood statically by the trim analysis. +- In other cases, you might discover that your code uses patterns which can't be expressed in terms of the `DynamicallyAccessedMembers` attributes, even if it only uses reflection to operate on statically-known types. In these cases, you may need to reorganize some of your code to make it follow an analyzable pattern. +- Sometimes the existing design of an API will render it mostly trim-incompatible, and you may need to find other ways to accomplish what it is doing. A common example is reflection-based serializers. In these cases, consider adopting other technology like source generators to produce code that is more easily statically analyzed. + +## Resolve warnings for non-analyzable patterns + +You should prefer resolving warnings by expressing the intent of your code using `RequiresUnreferencedCode` and `DynamicallyAccessedMembers` when possible. However, in some cases you may be interested in enabling trimming of a library that uses patterns which can't be expressed with those attributes, or without refactoring existing code. This section describes additional advanced ways to resolve trim analysis warnings. + +> [!WARNING] +> These techniques might break your code if used incorrectly. + +When suppressing warnings, you are responsible for guaranteeing the trim compatibility of your code based on invariants that you know to be true by inspection. Be very careful with these annotations, because if they are incorrect, or if invariants of your code change, they might end up hiding real issues. + +### UnconditionalSuppressMessage + +If the intent of your code can't be expressed with the annotations, but you know that the warning doesn't represent a real issue at run time, you can suppress the warnings using . This is similar to `SuppressMessageAttribute`, but it's persisted in IL and respected during trim analysis. For example: + +```csharp +class TypeCollection +{ + Type[] types;u + + // Ensure that only types with ctors are stored in the array + [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicParameterlessConstructor)] + public Type this[int i] + { + // warning IL2063: TypeCollection.Item.get: Value returned from method 'TypeCollection.Item.get' + // can not be statically determined and may not meet 'DynamicallyAccessedMembersAttribute' requirements. + get => types[i]; + set => types[i] = value; + } +} + +class TypeCreator +{ + TypeCollection types; + + public void CreateType(int i) + { + types[i] = typeof(TypeWithConstructor); + Activator.CreateInstance(types[i]); // No warning! + } +} + +class TypeWithConstructor +{ +} +``` + +Here, the indexer property has been annotated so that the returned `Type` meets the requirements of `CreateInstance`. This already ensures that the `TypeWithConstructor` constructor is kept, and that the call to `CreateInstance` doesn't warn. Furthermore, the indexer setter annotation ensures that any types stored in the `Type[]` have a constructor. However, the analysis isn't able to see this, and still produces a warning for the getter, because it doesn't know that the returned type has its constructor preserved. + +If you are sure that the requirements are met, you can silence this warning by adding `UnconditionalSuppressMessage` to the getter: + +```csharp +[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicParameterlessConstructor)] +public Type this[int i] +{ + [UnconditionalSuppressMessage("ReflectionAnalysis", "IL2063", + Justification = "The list only contains types stored through the annotated setter.")] + get => types[i]; + set => types[i] = value; +} +``` diff --git a/docs/core/deploying/single-file.md b/docs/core/deploying/single-file.md index a049a27903668..3cf987e5da2a0 100644 --- a/docs/core/deploying/single-file.md +++ b/docs/core/deploying/single-file.md @@ -11,6 +11,10 @@ Bundling all application-dependent files into a single binary provides an applic Single File deployment is available for both the [framework-dependent deployment model](index.md#publish-framework-dependent) and [self-contained applications](index.md#publish-self-contained). The size of the single file in a self-contained application will be large since it will include the runtime and the framework libraries. The single file deployment option can be combined with [ReadyToRun](ready-to-run.md) and [Trim (an experimental feature in .NET 5.0)](trim-self-contained.md) publish options. +## Output differences from .NET 3.x + +In .NET Core 3.x, publishing as a single file produced exactly one file, consisting of the app itself, dependencies, and any other files in the folder during publish. When the app starts, the single file app was extracted to a temporary folder and run from there. Starting with .NET 5, only managed DLLs are bundled with the app into a single executable. When the app starts, the managed DLLs are extracted and loaded in memory, avoiding the extraction to a temporary folder. On Windows, this means that the managed binaries are embedded in the single-file bundle, but the native binaries of the core runtime itself are separate files. To embed those files for extraction and get exactly one output file, like in .NET Core 3.x, set the property `IncludeNativeLibrariesForSelfExtract` to `true`. For more information about extraction, see [Other considerations](#other-considerations). + ## API incompatibility Some APIs are not compatible with single-file deployment and applications may require modification if they use these APIs. If you use a third-party framework or package, it's possible that they may also use one of these APIs and need modification. The most common cause of problems is dependence on file paths for files or DLLs shipped with the application. diff --git a/docs/core/deploying/trim-self-contained.md b/docs/core/deploying/trim-self-contained.md index 6d3d1b11ae857..80ef67d064905 100644 --- a/docs/core/deploying/trim-self-contained.md +++ b/docs/core/deploying/trim-self-contained.md @@ -7,19 +7,23 @@ ms.date: 04/03/2020 --- # Trim self-contained deployments and executables -The [framework-dependent deployment model](index.md#publish-framework-dependent) has been the most successful deployment model since the inception of .NET. In this scenario, the application developer bundles only the application and third-party assemblies with the expectation that the .NET runtime and framework libraries will be available in the client machine. This deployment model continues to be the dominant one in .NET Core as well but there are some scenarios where the framework-dependent model is not optimal. The alternative is to publish a [self-contained application](index.md#publish-self-contained), where the .NET Core runtime and framework are bundled together with the application and third-party assemblies. +The [framework-dependent deployment model](index.md#publish-framework-dependent) has been the most successful deployment model since the inception of .NET. In this scenario, the application developer bundles only the application and third-party assemblies with the expectation that the .NET runtime and runtime libraries will be available in the client machine. This deployment model continues to be the dominant one in the latest .NET release, however, there are some scenarios where the framework-dependent model is not the best choice. The alternative is to publish a [self-contained application](index.md#publish-self-contained), where the .NET runtime and runtime libraries are bundled together with the application and third-party assemblies. The trim-self-contained deployment model is a specialized version of the self-contained deployment model that is optimized to reduce deployment size. Minimizing deployment size is a critical requirement for some client-side scenarios like Blazor applications. Depending on the complexity of the application, only a subset of the framework assemblies are referenced, and a subset of the code within each assembly is required to run the application. The unused parts of the libraries are unnecessary and can be trimmed from the packaged application. However, there is a risk that the build time analysis of the application can cause failures at runtime, due to not being able to reliably analyze various problematic code patterns (largely centered on reflection use). Because reliability can't be guaranteed, this deployment model is offered as a preview feature. -The build time analysis engine provides warnings to the developer of code patterns that are problematic to detect which other code is required. Code can be annotated with attributes to tell the trimmer what else to include. Many reflection patterns can be replaced with build-time code generation using [Source Generators](https://github.com/dotnet/roslyn/blob/master/docs/features/source-generators.md). +The build time analysis engine provides warnings to the developer of code patterns that are problematic to detect which other code is required. Code can be annotated with attributes to tell the trimmer what else to include. Many reflection patterns can be replaced with build-time code generation using [Source Generators](https://github.com/dotnet/roslyn/blob/main/docs/features/source-generators.md). The trim mode for the applications is configured with the `TrimMode` setting. The default value is `copyused` and bundles referenced assemblies with the application. The `link` value is used with Blazor WebAssembly applications and trims unused code within assemblies. Trim analysis warnings give information on code patterns where a full dependency analysis was not possible. These warnings are suppressed by default and can be turned on by setting the flag `SuppressTrimAnalysisWarnings` to `false`. For more information about the trim options available, see [Trimming options](trimming-options.md). > [!NOTE] > Trimming is an experimental feature in .NET Core 3.1 and .NET 5.0. Trimming is _only_ available to applications that are published self-contained. +## Components that cause trimming problems + +Any code that causes build time analysis challenges, isn't suitable for trimming. Some common coding patterns that are problematic when used by an application, originate from unbounded reflection usage and external dependencies that aren't visible at build time. An example of unbounded reflection is a legacy serializer, such as [XML serialization](../../standard/serialization/introducing-xml-serialization.md) and example of invisible external dependencies is [built-in COM](../../standard/native-interop/cominterop.md). Any Windows desktop applications that depend on built-in COM support might have challenges with trimming. This includes Windows Forms and Windows Presentation Foundation (WPF) applications. The trimming engine generates warnings during build time when it detects code in an application that uses problematic coding patterns. For more information, see [Prepare .NET libraries for trimming](prepare-libraries-for-trimming.md). + ## Prevent assemblies from being trimmed There are scenarios in which the trimming functionality will fail to detect references. For example, when reflection is used on a runtime assembly, either by your application or a library that is referenced by your application, the assembly isn't directly referenced. Trimming is unaware of these indirect references and would exclude the library from the published folder. diff --git a/docs/core/deploying/trimming-options.md b/docs/core/deploying/trimming-options.md index 438ea0d450684..60fe4ead76fa5 100644 --- a/docs/core/deploying/trimming-options.md +++ b/docs/core/deploying/trimming-options.md @@ -4,32 +4,53 @@ description: Learn how to control trimming of self-contained apps. author: sbomer ms.author: svbomer ms.date: 08/25/2020 +ms.topic: reference --- # Trimming options The following MSBuild properties and items influence the behavior of [trimmed self-contained deployments](trim-self-contained.md). Some of the options mention `ILLink`, which is the name of the underlying tool that implements trimming. More information about the underlying tool can be found at the [Linker documentation](https://github.com/mono/linker/tree/master/docs). +Trimming with `PublishTrimmed` was introduced in .NET Core 3.0. The other options are available only in .NET 5 and above. + ## Enable trimming - `true` Enable trimming during publish, with the default settings defined by the SDK. -When using `Microsoft.NET.Sdk`, this will perform assembly-level trimming of the framework assemblies from the netcoreapp runtime pack. Application code and non-framework libraries are not trimmed. Other SDKs may define different defaults. +This will trim any assemblies which have been configured for trimming. With `Microsoft.NET.Sdk` in .NET 6, this includes the any assemblies with `[AssemblyMetadata("IsTrimmable", "True")]`, which is the case for framework assemblies. In .NET 5, framework assemblies from the netcoreapp runtime pack are configured for trimming via `` MSBuild metadata. Other SDKs may define different defaults. ## Trimming granularity -The following granularity settings control how aggressively unused IL is discarded. This can be set as a property, or as metadata on an [individual assembly](#trimmed-assemblies). +The following granularity settings control how aggressively unused IL is discarded. This can be set as a property affecting all trimmer input assemblies, or as metadata on an [individual assembly](#trimmed-assemblies) which overrides the property setting. + +- `link` + + Enable member-level trimming, which removes unused members from types. This is the default in .NET 6+. - `copyused` Enable assembly-level trimming, which will keep an entire assembly if any part of it is used (in a statically understood way). -- `link` +Assemblies with `true` metadata but no explicit `TrimMode` will use the global `TrimMode`. The default `TrimMode` for `Microsoft.NET.Sdk` is `link` in .NET 6+, and `copyused` in previous versions. + +## Trim additional assemblies + +In .NET 6+, `PublishTrimmed` trims assemblies with the assembly-level attribute - Enable member-level trimming, which removes unused members from types. +```csharp +[AssemblyMetadata("IsTrimmable", "True")] +``` + +which includes the framework libraries. In .NET 6+, you can also opt in to trimming for a library without this attribute, specifying the assembly by name (without the `.dll` extension). + +```xml + + + +``` -Assemblies with `true` metadata but no explicit `TrimMode` will use the global `TrimMode`. The default `TrimMode` for `Microsoft.NET.Sdk` is `copyused`. +This is equivalent to setting MSBuild metadata `true` for the assembly in `ManagedAssemblyToLink` (see below). ## Trimmed assemblies @@ -46,6 +67,8 @@ When publishing a trimmed app, the SDK computes an `ItemGroup` called `ManagedAs ``` +You can also use this to override the trimming behavior specified by the library author, by setting `false` for an assembly with `[AssemblyMetadata("IsTrimmable", "True"])`. + Do not add or remove items to/from `ManagedAssemblyToLink`, because the SDK computes this set during publish and expects it not to change. The supported metadata is: - `true` @@ -56,6 +79,10 @@ Do not add or remove items to/from `ManagedAssemblyToLink`, because the SDK comp Control the [trimming granularity](#trimming-granularity) of this assembly. This takes precedence over the global `TrimMode`. Setting `TrimMode` on an assembly implies `true`. +- `True` or `False` + + Control whether to show [single warnings](#show-detailed-warnings) for this assembly. + ## Root assemblies All assemblies that do not have `true` are considered roots for the analysis, which means that they and all of their statically understood dependencies will be kept. Additional assemblies may be "rooted" by name (without the `.dll` extension): @@ -98,6 +125,14 @@ Trimming will remove IL that is not statically reachable. Apps that use reflecti This will include warnings about the entire app, including your own code, library code, and framework code. +## Roslyn analyzer + +Setting `PublishTrimmed` in .NET 6+ will also enable a Roslyn analyzer that shows a _limited_ set of analysis warnings. The analyzer may also be enabled or disabled independently of `PublishTrimmed`. + +- `true` + + Enable a Roslyn analyzer for a subset of trim analysis warnings. + ## Warning versions Trim analysis respects the [`AnalysisLevel`](../project-sdk/msbuild-props.md#analysislevel) property that controls the version of analysis warnings across the SDK. There is another property that controls the version of trim analysis warnings independently (similar to `WarningLevel` for the compiler): @@ -114,7 +149,17 @@ Individual [warning codes](https://github.com/mono/linker/blob/master/docs/error Don't treat ILLink warnings as errors. This may be useful to avoid turning trim analysis warnings into errors when treating compiler warnings as errors globally. -## Removing symbols +## Show detailed warnings + +In .NET 6+, trim analysis will produce at most one warning for each assembly that comes from a `PackageReference`, indicating that the assembly's internals are not compatible with trimming. You can also show individual warnings for all assemblies: + +- `false` + + Show all detailed warnings, instead of collapsing them to a single warning per assembly. + +The defaults show detailed warnings for the project assembly and `ProjectReference`s. `` can also be set as metadata on an [individual assembly](#trimmed-assemblies) to control the warning behavior for that assembly only. + +## Remove symbols Symbols will normally be trimmed to match the trimmed assemblies. You can also remove all symbols: @@ -130,7 +175,7 @@ Several feature areas of the framework libraries come with linker directives tha - `false` - Remove code that enables better debugging experiences. This will also [remove symbols](#removing-symbols). + Remove code that enables better debugging experiences. This will also [remove symbols](#remove-symbols). - `false` @@ -156,4 +201,4 @@ Several feature areas of the framework libraries come with linker directives tha Strip exception messages for `System.*` assemblies. When an exception is thrown from a `System.*` assembly, the message will be a simplified resource ID instead of the full message. - These properties will cause the related code to be trimmed and will also disable features via the [runtimeconfig](../run-time-config/index.md) file. For more information about these properties, including the corresponding runtimeconfig options, see [feature switches](https://github.com/dotnet/runtime/blob/master/docs/workflow/trimming/feature-switches.md). Some SDKs may have default values for these properties. + These properties will cause the related code to be trimmed and will also disable features via the [runtimeconfig](../run-time-config/index.md) file. For more information about these properties, including the corresponding runtimeconfig options, see [feature switches](https://github.com/dotnet/runtime/blob/main/docs/workflow/trimming/feature-switches.md). Some SDKs may have default values for these properties. diff --git a/docs/core/diagnostics/available-counters.md b/docs/core/diagnostics/available-counters.md index a25f25a231d0b..c5113fe00136c 100644 --- a/docs/core/diagnostics/available-counters.md +++ b/docs/core/diagnostics/available-counters.md @@ -11,7 +11,7 @@ The .NET runtime and libraries implement and publish several [`EventCounter`](./ ## System.Runtime counters -The following counters are published as part of .NET runtime (CoreCLR) and are maintained in the [`RuntimeEventSource.cs`](https://github.com/dotnet/coreclr/blob/master/src/System.Private.CoreLib/src/System/Diagnostics/Eventing/RuntimeEventSource.cs). +The following counters are published as part of .NET runtime (CoreCLR) and are maintained in the [`RuntimeEventSource.cs`](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Private.CoreLib/src/System/Diagnostics/Tracing/RuntimeEventSource.cs). | Counter | Description | |--|--| @@ -38,10 +38,11 @@ The following counters are published as part of .NET runtime (CoreCLR) and are m | :::no-loc text="Working Set"::: (`working-set`) | The amount of physical memory mapped to the process context at a point in time base on | | :::no-loc text="IL Bytes Jitted"::: (`il-bytes-jitted`) | The total size of ILs that are JIT-compiled, in bytes (available on .NET 5 and later versions) | | :::no-loc text="Method Jitted Count"::: (`method-jitted-count`) | The number of methods that are JIT-compiled (available on .NET 5 and later versions) | +| :::no-loc text="GC Committed Bytes"::: (`gc-committed-bytes`) | The number of bytes committed by the GC (available on .NET 6 and later versions) | ## "Microsoft.AspNetCore.Hosting" counters -The following counters are published as part of [ASP.NET Core](/aspnet/core) and are maintained in [`HostingEventSource.cs`](https://github.com/dotnet/aspnetcore/blob/master/src/Hosting/Hosting/src/Internal/HostingEventSource.cs). +The following counters are published as part of [ASP.NET Core](/aspnet/core) and are maintained in [`HostingEventSource.cs`](https://github.com/dotnet/aspnetcore/blob/main/src/Hosting/Hosting/src/Internal/HostingEventSource.cs). | Counter | Description | |--|--| @@ -52,7 +53,7 @@ The following counters are published as part of [ASP.NET Core](/aspnet/core) and ## "Microsoft.AspNetCore.Http.Connections" counters -The following counters are published as part of [ASP.NET Core SignalR](/aspnet/core/signalr/introduction) and are maintained in [`HttpConnectionsEventSource.cs`](https://github.com/dotnet/aspnetcore/blob/master/src/SignalR/common/Http.Connections/src/Internal/HttpConnectionsEventSource.cs). +The following counters are published as part of [ASP.NET Core SignalR](/aspnet/core/signalr/introduction) and are maintained in [`HttpConnectionsEventSource.cs`](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/common/Http.Connections/src/Internal/HttpConnectionsEventSource.cs). | Counter | Description | |--|--| @@ -64,7 +65,7 @@ The following counters are published as part of [ASP.NET Core SignalR](/aspnet/c ## "Microsoft-AspNetCore-Server-Kestrel" counters -The following counters are published as part of the [ASP.NET Core Kestrel web server](/aspnet/core/fundamentals/servers/kestrel) and are maintained in [`KestrelEventSource.cs`](https://github.com/dotnet/aspnetcore/blob/master/src/Servers/Kestrel/Core/src/Internal/Infrastructure/KestrelEventSource.cs). +The following counters are published as part of the [ASP.NET Core Kestrel web server](/aspnet/core/fundamentals/servers/kestrel) and are maintained in [`KestrelEventSource.cs`](https://github.com/dotnet/aspnetcore/blob/main/src/Servers/Kestrel/Core/src/Internal/Infrastructure/KestrelEventSource.cs). | Counter | Description | |--|--| diff --git a/docs/core/diagnostics/debug-deadlock.md b/docs/core/diagnostics/debug-deadlock.md index fe69aac577c25..ed363ea844f5e 100644 --- a/docs/core/diagnostics/debug-deadlock.md +++ b/docs/core/diagnostics/debug-deadlock.md @@ -3,6 +3,7 @@ title: Debugging deadlock - .NET Core description: A tutorial that walks you through debugging a locking issue in .NET Core. ms.topic: tutorial ms.date: 07/20/2020 +recommendations: false --- # Debug a deadlock in .NET Core @@ -262,7 +263,7 @@ The second thread is similar. It's also trying to acquire a lock that it already - [dotnet-trace](dotnet-trace.md) to list processes - [dotnet-counters](dotnet-counters.md) to check managed memory usage - [dotnet-dump](dotnet-dump.md) to collect and analyze a dump file -- [dotnet/diagnostics](https://github.com/dotnet/diagnostics/tree/master/documentation/tutorial) +- [dotnet/diagnostics](https://github.com/dotnet/diagnostics/tree/main/documentation/tutorial) ## Next steps diff --git a/docs/core/diagnostics/debug-highcpu.md b/docs/core/diagnostics/debug-highcpu.md index 3ec619451635b..eff51305e92ad 100644 --- a/docs/core/diagnostics/debug-highcpu.md +++ b/docs/core/diagnostics/debug-highcpu.md @@ -3,6 +3,7 @@ title: Debug high CPU usage - .NET Core description: A tutorial that walks you through debugging high CPU usage in .NET Core. ms.topic: tutorial ms.date: 07/20/2020 +recommendations: false --- # Debug high CPU usage in .NET Core @@ -113,12 +114,14 @@ When analyzing a slow request, you need a diagnostics tool that can provide insi The `perf` tool can be used to generate .NET Core app profiles. Exit the previous instance of the [sample debug target](/samples/dotnet/samples/diagnostic-scenarios). -Set the `COMPlus_PerfMapEnabled` environment variable to cause the .NET Core app to create a `map` file in the `/tmp` directory. This `map` file is used by `perf` to map CPU address to JIT-generated functions by name. For more information, see [Write perf map](../run-time-config/debugging-profiling.md#write-perf-map). +Set the `DOTNET_PerfMapEnabled` environment variable to cause the .NET Core app to create a `map` file in the `/tmp` directory. This `map` file is used by `perf` to map CPU address to JIT-generated functions by name. For more information, see [Write perf map](../run-time-config/debugging-profiling.md#write-perf-map). + +[!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)] Run the [sample debug target](/samples/dotnet/samples/diagnostic-scenarios) in the same terminal session. ```dotnetcli -export COMPlus_PerfMapEnabled=1 +export DOTNET_PerfMapEnabled=1 dotnet run ``` @@ -166,7 +169,7 @@ Open the `nettrace` with [`PerfView`](https://github.com/microsoft/perfview/blob - [dotnet-trace](dotnet-trace.md) to list processes - [dotnet-counters](dotnet-counters.md) to check managed memory usage - [dotnet-dump](dotnet-dump.md) to collect and analyze a dump file -- [dotnet/diagnostics](https://github.com/dotnet/diagnostics/tree/master/documentation/tutorial) +- [dotnet/diagnostics](https://github.com/dotnet/diagnostics/tree/main/documentation/tutorial) ## Next steps diff --git a/docs/core/diagnostics/debug-linux-dumps.md b/docs/core/diagnostics/debug-linux-dumps.md index 9af591f4b68b7..527aee8b54e86 100644 --- a/docs/core/diagnostics/debug-linux-dumps.md +++ b/docs/core/diagnostics/debug-linux-dumps.md @@ -13,7 +13,7 @@ ms.date: 08/27/2020 The two recommended ways of collecting dumps on Linux are: * [`dotnet-dump`](dotnet-dump.md) CLI tool -* [Environment variables](dumps.md#collecting-dumps-on-crash) that collect dumps on crashes +* [Environment variables](dumps.md#collect-dumps-on-crash) that collect dumps on crashes ### Managed dumps with `dotnet-dump` @@ -21,7 +21,7 @@ The [`dotnet-dump`](dotnet-dump.md) tool is simple to use, and does not have a d ### Core dumps with `createdump` -As an alternative to `dotnet-dump`, which creates managed-only dumps, [`createdump`](https://github.com/dotnet/runtime/blob/master/docs/design/coreclr/botr/xplat-minidump-generation.md) is the recommended tool for creating core dumps on Linux containing both native and managed information. Other tools like gdb or gcore can also be used to create core dumps but may miss state needed for managed debugging, resulting in "UNKNOWN" type or function names during analysis. +As an alternative to `dotnet-dump`, which creates managed-only dumps, [`createdump`](https://github.com/dotnet/runtime/blob/main/docs/design/coreclr/botr/xplat-minidump-generation.md) is the recommended tool for creating core dumps on Linux containing both native and managed information. Other tools like gdb or gcore can also be used to create core dumps but may miss state needed for managed debugging, resulting in "UNKNOWN" type or function names during analysis. The `createdump` tool is installed with the .NET Core runtime and can be found next to libcoreclr.so (typically in "/usr/share/dotnet/shared/Microsoft.NETCore.App/[version]"). The tool takes a process ID to collect a dump from as its primary argument and can also take optional parameters specifying what kind of dump to collect (a minidump with heap is the default). Options include: @@ -61,7 +61,7 @@ Collecting core dumps requires either the `SYS_PTRACE` capability or that `creat Both managed dumps collected with `dotnet-dump` and core dumps collected with `createdump` can be analyzed with the `dotnet-dump` tool using the `dotnet-dump analyze` command. The `dotnet dump` requires that the environment analyzing the dump has the same OS and architecture as the environment the dump was captured in. -Alternatively, [LLDB](https://lldb.llvm.org/) can be used to analyze core dumps on Linux, which allows analysis of both managed and native frames. LLDB uses the SOS extension to debug managed code. The [`dotnet-sos`](dotnet-sos.md) CLI tool can be used to install SOS, which has [many useful commands](https://github.com/dotnet/diagnostics/blob/master/documentation/sos-debugging-extension.md) for debugging managed code. In order to analyze .NET Core dumps, LLDB and SOS require the following .NET Core binaries from the environment the dump was created in: +Alternatively, [LLDB](https://lldb.llvm.org/) can be used to analyze core dumps on Linux, which allows analysis of both managed and native frames. LLDB uses the SOS extension to debug managed code. The [`dotnet-sos`](dotnet-sos.md) CLI tool can be used to install SOS, which has [many useful commands](https://github.com/dotnet/diagnostics/blob/main/documentation/sos-debugging-extension.md) for debugging managed code. In order to analyze .NET Core dumps, LLDB and SOS require the following .NET Core binaries from the environment the dump was created in: 1. libmscordaccore.so 2. libcoreclr.so @@ -77,11 +77,11 @@ lldb --core In the above command line, `` is the path of the dump to analyze and `` is the native program that started the .NET Core application. This is typically the `dotnet` binary unless the app is self-contained, in which case it is the name of the application without the dll extension. -Once LLDB starts, it may be necessary to use the `setsymbolserver` command to point at the correct symbol location (`setsymbolserver -ms` to use Microsoft's symbol server or `setsymbolserver -directory ` to specify a local path). Native symbols can be loaded by running `loadsymbols`. At this point, [SOS commands](https://github.com/dotnet/diagnostics/blob/master/documentation/sos-debugging-extension.md) can be used to analyze the dump. +Once LLDB starts, it may be necessary to use the `setsymbolserver` command to point at the correct symbol location (`setsymbolserver -ms` to use Microsoft's symbol server or `setsymbolserver -directory ` to specify a local path). Native symbols can be loaded by running `loadsymbols`. At this point, [SOS commands](https://github.com/dotnet/diagnostics/blob/main/documentation/sos-debugging-extension.md) can be used to analyze the dump. ## See also - [dotnet-sos](dotnet-sos.md) for more details on installing the SOS extension. - [dotnet-symbol](dotnet-symbol.md) for more details on installing and using the symbol download tool. -- [.NET Core diagnostics repo](https://github.com/dotnet/diagnostics/blob/master/documentation/) for more details on debugging, including a useful FAQ. -- [Installing LLDB](https://github.com/dotnet/diagnostics/blob/master/documentation/sos.md#getting-lldb) for instructions on installing LLDB on Linux or Mac. +- [.NET Core diagnostics repo](https://github.com/dotnet/diagnostics/blob/main/documentation/) for more details on debugging, including a useful FAQ. +- [Installing LLDB](https://github.com/dotnet/diagnostics/blob/main/documentation/sos.md#getting-lldb) for instructions on installing LLDB on Linux or Mac. diff --git a/docs/core/diagnostics/debug-memory-leak.md b/docs/core/diagnostics/debug-memory-leak.md index 15099323e39b0..0235cf1c80abc 100644 --- a/docs/core/diagnostics/debug-memory-leak.md +++ b/docs/core/diagnostics/debug-memory-leak.md @@ -3,6 +3,7 @@ title: Debug a memory leak tutorial description: Learn how to debug a memory leak in .NET Core. ms.topic: tutorial ms.date: 04/20/2020 +recommendations: false --- # Debug a memory leak in .NET Core @@ -233,7 +234,7 @@ You can also delete the dump file that was created. - [dotnet-trace](dotnet-trace.md) to list processes - [dotnet-counters](dotnet-counters.md) to check managed memory usage - [dotnet-dump](dotnet-dump.md) to collect and analyze a dump file -- [dotnet/diagnostics](https://github.com/dotnet/diagnostics/tree/master/documentation/tutorial) +- [dotnet/diagnostics](https://github.com/dotnet/diagnostics/tree/main/documentation/tutorial) - [Use Visual Studio to debug memory leaks](/visualstudio/profiling/memory-usage) ## Next steps diff --git a/docs/core/diagnostics/debug-stackoverflow.md b/docs/core/diagnostics/debug-stackoverflow.md index 8040739a1c049..a7aa51444b6e7 100644 --- a/docs/core/diagnostics/debug-stackoverflow.md +++ b/docs/core/diagnostics/debug-stackoverflow.md @@ -4,14 +4,13 @@ description: Learn how to diagnose StackOverflow exceptions ms.topic: tutorial ms.date: 12/22/2020 --- +# Debug StackOverflow errors -# Debugging StackOverflow errors - -A is thrown when when the execution stack overflows because it contains too many nested method calls. +A is thrown when when the execution stack overflows because it contains too many nested method calls. For example, suppose you have an app as follows: -```` +````csharp using System; namespace temp @@ -20,13 +19,13 @@ namespace temp { static void Main(string[] args) { - Main(args); // oops this recursion won't stop + Main(args); // Oops, this recursion won't stop. } } } ```` -The Main method will continuously call itself until there is no more stack space. Once there is no more stack space, execution cannot continue and so it will throw a . +The `Main` method will continuously call itself until there is no more stack space. Once there is no more stack space, execution cannot continue and so it will throw a . ```` > dotnet run @@ -37,20 +36,22 @@ Stack overflow. > On .NET 5 and later, the callstack is output to the console. > [!NOTE] -> This article describes how to debug a stack overflow with lldb. If you are running on Windows, we suggest debugging the app with [Visual Studio](/visualstudio/debugger/what-is-debugging) or [Visual Studio Code](https://code.visualstudio.com/Docs/editor/debugging). +> This article describes how to debug a stack overflow with lldb. If you are running on Windows, we suggest debugging the app with [Visual Studio](/visualstudio/debugger/what-is-debugging) or [Visual Studio Code](https://code.visualstudio.com/Docs/editor/debugging). ## Example 1. Run the app with it configured to collect a dump on crash ```` - > export COMPlus_DbgEnableMiniDump=1 + > export DOTNET_DbgEnableMiniDump=1 > dotnet run Stack overflow. Writing minidump with heap to file /tmp/coredump.6412 Written 58191872 bytes (14207 pages) to core file ```` + [!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)] + 2. Install the SOS extension using [dotnet-sos](dotnet-sos.md) ```` diff --git a/docs/core/diagnostics/diagnostics-in-containers.md b/docs/core/diagnostics/diagnostics-in-containers.md index 5f0e1c48abd7a..9e695ac992eea 100644 --- a/docs/core/diagnostics/diagnostics-in-containers.md +++ b/docs/core/diagnostics/diagnostics-in-containers.md @@ -18,7 +18,7 @@ The only complicating factor of using these tools in a container is that they ar ```dockerfile # In build stage -# Install desired .NET CLI diagnostics tools +# Install desired .NET CLI diagnostics tools RUN dotnet tool install --tool-path /tools dotnet-trace RUN dotnet tool install --tool-path /tools dotnet-counters RUN dotnet tool install --tool-path /tools dotnet-dump @@ -46,28 +46,32 @@ If you would like to use .NET Core global CLI diagnostic tools to diagnose proce The [`PerfCollect`](./trace-perfcollect-lttng.md) script is useful for collecting performance traces and is the recommended tool for collecting traces prior to .NET Core 3.0. If using `PerfCollect` in a container, keep the following requirements in mind: -1. `PerfCollect` requires the [`SYS_ADMIN` capability](https://man7.org/linux/man-pages/man7/capabilities.7.html) (in order to run the `perf` tool), so be sure the container is [started with that capability](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). -2. `PerfCollect` requires some environment variables be set prior to the app it is profiling starting. These can be set either in a [Dockerfile](https://docs.docker.com/engine/reference/builder/#env) or when [starting the container](https://docs.docker.com/engine/reference/run/#env-environment-variables). Because these variables shouldn't be set in normal production environments, it's common to just add them when starting a container that will be profiled. The two variables which PerfCollect requires are: - 1. COMPlus_PerfMapEnabled=1 - 1. COMPlus_EnableEventLog=1 +- `PerfCollect` requires the [`SYS_ADMIN` capability](https://man7.org/linux/man-pages/man7/capabilities.7.html) (in order to run the `perf` tool), so be sure the container is [started with that capability](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). + +- `PerfCollect` requires some environment variables be set prior to the app it is profiling starting. These can be set either in a [Dockerfile](https://docs.docker.com/engine/reference/builder/#env) or when [starting the container](https://docs.docker.com/engine/reference/run/#env-environment-variables). Because these variables shouldn't be set in normal production environments, it's common to just add them when starting a container that will be profiled. The two variables that PerfCollect requires are: + + - `DOTNET_PerfMapEnabled=1` + - `DOTNET_EnableEventLog=1` + + [!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)] ### Using `PerfCollect` in a sidecar container If you would like to run `PerfCollect` in one container to profile a .NET Core process in a different container, the experience is almost the same except for these differences: -1. The environment variables mentioned previously (COMPlus_PerfMapEnabled and COMPlus_EnableEventLog) must be set for the target container (not the one running `PerfCollect`). -2. The container running `PerfCollect` must have the `SYS_ADMIN` capability (not the target container). -3. The two containers must [share a process namespace](https://docs.docker.com/engine/reference/run/#pid-settings---pid). +- The environment variables mentioned previously (`DOTNET_PerfMapEnabled` and `DOTNET_EnableEventLog`) must be set for the target container (not the one running `PerfCollect`). +- The container running `PerfCollect` must have the `SYS_ADMIN` capability (not the target container). +- The two containers must [share a process namespace](https://docs.docker.com/engine/reference/run/#pid-settings---pid). ## Using `createdump` in a container **This tool applies to: ✔️** .NET Core 2.1 and later versions -An alternative to `dotnet-dump`, [`createdump`](https://github.com/dotnet/runtime/blob/master/docs/design/coreclr/botr/xplat-minidump-generation.md) can be used for creating core dumps on Linux containing both native and managed information. The `createdump` tool is installed with the .NET Core runtime and can be found next to libcoreclr.so (typically in "/usr/share/dotnet/shared/Microsoft.NETCore.App/[version]"). The tool works the same in a container as it does in non-containerized Linux environments with the single exception that the tool requires the [`SYS_PTRACE` capability](https://man7.org/linux/man-pages/man7/capabilities.7.html), so the Docker container must be [started with that capability](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). +An alternative to `dotnet-dump`, [`createdump`](https://github.com/dotnet/runtime/blob/main/docs/design/coreclr/botr/xplat-minidump-generation.md) can be used for creating core dumps on Linux containing both native and managed information. The `createdump` tool is installed with the .NET Core runtime and can be found next to libcoreclr.so (typically in "/usr/share/dotnet/shared/Microsoft.NETCore.App/[version]"). The tool works the same in a container as it does in non-containerized Linux environments with the single exception that the tool requires the [`SYS_PTRACE` capability](https://man7.org/linux/man-pages/man7/capabilities.7.html), so the Docker container must be [started with that capability](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities). ### Using `createdump` in a sidecar container If you would like to use `createdump` to create a dump from a process in a different container, the experience is almost the same except for these differences: -1. The container running `createdump` must have the `SYS_PTRACE` capability (not the target container). -2. The two containers must [share a process namespace](https://docs.docker.com/engine/reference/run/#pid-settings---pid). +- The container running `createdump` must have the `SYS_PTRACE` capability (not the target container). +- The two containers must [share a process namespace](https://docs.docker.com/engine/reference/run/#pid-settings---pid). diff --git a/docs/core/diagnostics/distributed-tracing-collection-walkthroughs.md b/docs/core/diagnostics/distributed-tracing-collection-walkthroughs.md new file mode 100644 index 0000000000000..d66ce47b5cb98 --- /dev/null +++ b/docs/core/diagnostics/distributed-tracing-collection-walkthroughs.md @@ -0,0 +1,363 @@ +--- +title: Collect a distributed trace - .NET +description: Tutorials to collect distributed traces in .NET applications using OpenTelemetry, Application Insights, or ActivityListener +ms.topic: tutorial +ms.date: 03/14/2021 +--- + +# Collect a distributed trace + +**This article applies to: ✔️** .NET Core 2.1 and later versions **✔️** .NET Framework 4.5 and later versions + +Instrumented code can create objects as part of a distributed trace, but the information +in these objects needs to be collected into centralized storage so that the entire trace can be +reviewed later. In this tutorial, you will collect the distributed trace telemetry in different ways so that it's +available to diagnose application issues when needed. See +[the instrumentation tutorial](distributed-tracing-instrumentation-walkthroughs.md) if you need to add new instrumentation. + +## Collect traces using OpenTelemetry + +### Prerequisites + +- [.NET Core 2.1 SDK](https://dotnet.microsoft.com/download/dotnet) or a later version + +### Create an example application + +Before any distributed trace telemetry can be collected, we need to produce it. Often this instrumentation might be +in libraries, but for simplicity, you'll create a small app that has some example instrumentation using +. At this point, no collection has happened, and +StartActivity() has no side-effect and returns null. See +[the instrumentation tutorial](distributed-tracing-instrumentation-walkthroughs.md) for more details. + +```dotnetcli +dotnet new console +``` + +Applications that target .NET 5 and later already have the necessary distributed tracing APIs included. For apps targeting older +.NET versions, add the [System.Diagnostics.DiagnosticSource NuGet package](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource/) +version 5 or greater. + +```dotnetcli +dotnet add package System.Diagnostics.DiagnosticSource +``` + +Replace the contents of the generated Program.cs with this example source: + +```C# +using System; +using System.Diagnostics; +using System.Threading.Tasks; + +namespace Sample.DistributedTracing +{ + class Program + { + static ActivitySource s_source = new ActivitySource("Sample.DistributedTracing"); + + static async Task Main(string[] args) + { + await DoSomeWork(); + Console.WriteLine("Example work done"); + } + + static async Task DoSomeWork() + { + using (Activity a = s_source.StartActivity("SomeWork")) + { + await StepOne(); + await StepTwo(); + } + } + + static async Task StepOne() + { + using (Activity a = s_source.StartActivity("StepOne")) + { + await Task.Delay(500); + } + } + + static async Task StepTwo() + { + using (Activity a = s_source.StartActivity("StepTwo")) + { + await Task.Delay(1000); + } + } + } +} +``` + +Running the app does not collect any trace data yet: + +```dotnetcli +> dotnet run +Example work done +``` + +### Collect using OpenTelemetry + +[OpenTelemetry](https://opentelemetry.io/) is a vendor-neutral open-source project supported by the +[Cloud Native Computing Foundation](https://www.cncf.io/) that aims to standardize generating and collecting telemetry for +cloud-native software. In this example, you will collect and display distributed trace information on the console though +OpenTelemetry can be reconfigured to send it elsewhere. For more information, see the +[OpenTelemetry getting started guide](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/docs/trace/getting-started/README.md). + +Add the [OpenTelemetry.Exporter.Console](https://www.nuget.org/packages/OpenTelemetry.Exporter.Console/) NuGet package. + +```dotnetcli +dotnet add package OpenTelemetry.Exporter.Console +``` + +Update Program.cs with additional OpenTelemetry `using` directives: + +```C# +using OpenTelemetry; +using OpenTelemetry.Resources; +using OpenTelemetry.Trace; +using System; +using System.Diagnostics; +using System.Threading.Tasks; +``` + +Update `Main()` to create the OpenTelemetry TracerProvider: + +```C# + public static async Task Main() + { + using var tracerProvider = Sdk.CreateTracerProviderBuilder() + .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("MySample")) + .AddSource("Sample.DistributedTracing") + .AddConsoleExporter() + .Build(); + + await DoSomeWork(); + Console.WriteLine("Example work done"); + } +``` + +Now the app collects distributed trace information and displays it to the console: + +```dotnetcli +> dotnet run +Activity.Id: 00-7759221f2c5599489d455b84fa0f90f4-6081a9b8041cd840-01 +Activity.ParentId: 00-7759221f2c5599489d455b84fa0f90f4-9a52f72c08a9d447-01 +Activity.DisplayName: StepOne +Activity.Kind: Internal +Activity.StartTime: 2021-03-18T10:46:46.8649754Z +Activity.Duration: 00:00:00.5069226 +Resource associated with Activity: + service.name: MySample + service.instance.id: 909a4624-3b2e-40e4-a86b-4a2c8003219e + +Activity.Id: 00-7759221f2c5599489d455b84fa0f90f4-d2b283db91cf774c-01 +Activity.ParentId: 00-7759221f2c5599489d455b84fa0f90f4-9a52f72c08a9d447-01 +Activity.DisplayName: StepTwo +Activity.Kind: Internal +Activity.StartTime: 2021-03-18T10:46:47.3838737Z +Activity.Duration: 00:00:01.0142278 +Resource associated with Activity: + service.name: MySample + service.instance.id: 909a4624-3b2e-40e4-a86b-4a2c8003219e + +Activity.Id: 00-7759221f2c5599489d455b84fa0f90f4-9a52f72c08a9d447-01 +Activity.DisplayName: SomeWork +Activity.Kind: Internal +Activity.StartTime: 2021-03-18T10:46:46.8634510Z +Activity.Duration: 00:00:01.5402045 +Resource associated with Activity: + service.name: MySample + service.instance.id: 909a4624-3b2e-40e4-a86b-4a2c8003219e + +Example work done +``` + +#### Sources + +In the example code, you invoked `AddSource("Sample.DistributedTracing")` so that OpenTelemetry would +capture the Activities produced by the ActivitySource that was already present in the code: + +```csharp +static ActivitySource s_source = new ActivitySource("Sample.DistributedTracing"); +``` + +Telemetry from any ActivitySource can be captured by calling `AddSource()` with the source's name. + +#### Exporters + +The console exporter is helpful for quick examples or local development but in a production deployment +you will probably want to send traces to a centralized store. OpenTelemetry supports various destinations using different +[exporters](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#exporter-library). +For more information about configuring OpenTelemetry, see the [OpenTelemetry getting started guide](https://github.com/open-telemetry/opentelemetry-dotnet#getting-started). + +## Collect traces using Application Insights + +Distributed tracing telemetry is automatically captured after configuring the Application Insights SDK for +[ASP.NET](/azure/azure-monitor/app/asp-net) or [ASP.NET Core](/azure/azure-monitor/app/asp-net-core) apps, +or by enabling [code-less instrumentation](/azure/azure-monitor/app/codeless-overview). + +For more +information, see the [Application Insights distributed tracing documentation](/azure/azure-monitor/app/distributed-tracing). + +> [!NOTE] +> Currently, Application Insights only supports collecting specific well-known Activity instrumentation and ignores new user-added Activities. Application Insights offers [TrackDependency](/azure/azure-monitor/app/api-custom-events-metrics#trackdependency) as a vendor-specific API for adding custom distributed tracing information. + +## Collect traces using custom logic + +Developers are free to create their own customized collection logic for Activity trace data. This example collects the +telemetry using the API provided by .NET and prints +it to the console. + +### Prerequisites + +- [.NET Core 2.1 SDK](https://dotnet.microsoft.com/download/dotnet) or a later version + +### Create an example application + +First you will create an example application that has some distributed trace instrumentation but no trace data is being collected. + +```dotnetcli +dotnet new console +``` + +Applications that target .NET 5 and later already have the necessary distributed tracing APIs included. For apps targeting older +.NET versions, add the [System.Diagnostics.DiagnosticSource NuGet package](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource/) +version 5 or greater. + +```dotnetcli +dotnet add package System.Diagnostics.DiagnosticSource +``` + +Replace the contents of the generated Program.cs with this example source: + +```C# +using System; +using System.Diagnostics; +using System.Threading.Tasks; + +namespace Sample.DistributedTracing +{ + class Program + { + static ActivitySource s_source = new ActivitySource("Sample.DistributedTracing"); + + static async Task Main(string[] args) + { + await DoSomeWork(); + Console.WriteLine("Example work done"); + } + + static async Task DoSomeWork() + { + using (Activity a = s_source.StartActivity("SomeWork")) + { + await StepOne(); + await StepTwo(); + } + } + + static async Task StepOne() + { + using (Activity a = s_source.StartActivity("StepOne")) + { + await Task.Delay(500); + } + } + + static async Task StepTwo() + { + using (Activity a = s_source.StartActivity("StepTwo")) + { + await Task.Delay(1000); + } + } + } +} +``` + +Running the app does not collect any trace data yet: + +```dotnetcli +> dotnet run +Example work done +``` + +### Add code to collect the traces + +Update Main() with this code: + +```C# + static async Task Main(string[] args) + { + Activity.DefaultIdFormat = ActivityIdFormat.W3C; + Activity.ForceDefaultIdFormat = true; + + Console.WriteLine(" {0,-15} {1,-60} {2,-15}", "OperationName", "Id", "Duration"); + ActivitySource.AddActivityListener(new ActivityListener() + { + ShouldListenTo = (source) => true, + Sample = (ref ActivityCreationOptions options) => ActivitySamplingResult.AllDataAndRecorded, + ActivityStarted = activity => Console.WriteLine("Started: {0,-15} {1,-60}", activity.OperationName, activity.Id), + ActivityStopped = activity => Console.WriteLine("Stopped: {0,-15} {1,-60} {2,-15}", activity.OperationName, activity.Id, activity.Duration) + }); + + await DoSomeWork(); + Console.WriteLine("Example work done"); + } +``` + +The output now includes logging: + +```dotnetcli +> dotnet run + OperationName Id Duration +Started: SomeWork 00-bdb5faffc2fc1548b6ba49a31c4a0ae0-c447fb302059784f-01 +Started: StepOne 00-bdb5faffc2fc1548b6ba49a31c4a0ae0-a7c77a4e9a02dc4a-01 +Stopped: StepOne 00-bdb5faffc2fc1548b6ba49a31c4a0ae0-a7c77a4e9a02dc4a-01 00:00:00.5093849 +Started: StepTwo 00-bdb5faffc2fc1548b6ba49a31c4a0ae0-9210ad536cae9e4e-01 +Stopped: StepTwo 00-bdb5faffc2fc1548b6ba49a31c4a0ae0-9210ad536cae9e4e-01 00:00:01.0111847 +Stopped: SomeWork 00-bdb5faffc2fc1548b6ba49a31c4a0ae0-c447fb302059784f-01 00:00:01.5236391 +Example work done +``` + +Setting and + is optional +but helps ensure the sample produces similar output on different .NET runtime versions. .NET 5 uses +the W3C TraceContext ID format by default but earlier .NET versions default to using + ID format. For more information, see +[Activity IDs](distributed-tracing-concepts.md#activity-ids). + + is used to receive callbacks +during the lifetime of an Activity. + +- - Each +Activity is associated with an ActivitySource, which acts as its namespace and producer. +This callback is invoked once for each ActivitySource in the process. Return true +if you are interested in performing sampling or being notified about start/stop events +for Activities produced by this source. +- - By default + does not +create an Activity object unless some ActivityListener indicates it should be sampled. Returning + +indicates that the Activity should be created, + should be set +to true, and +will have the +flag set. IsAllDataRequested can be observed by the instrumented code as a hint that a listener +wants to ensure that auxiliary Activity information such as Tags and Events are populated. +The Recorded flag is encoded in the W3C TraceContext ID and is a hint to other processes +involved in the distributed trace that this trace should be sampled. +- and + are +called when an Activity is started and stopped respectively. These callbacks provide an +opportunity to record relevant information about the Activity or potentially to modify it. +When an Activity has just started, much of the data may still be incomplete and it will +be populated before the Activity stops. + +Once an ActivityListener has been created and the callbacks are populated, calling + +initiates invoking the callbacks. Call + to +stop the flow of callbacks. Be aware that in multi-threaded code, callback notifications in +progress could be received while `Dispose()` is running or even shortly after it has +returned. diff --git a/docs/core/diagnostics/distributed-tracing-concepts.md b/docs/core/diagnostics/distributed-tracing-concepts.md new file mode 100644 index 0000000000000..5cd98ce4f1f4a --- /dev/null +++ b/docs/core/diagnostics/distributed-tracing-concepts.md @@ -0,0 +1,137 @@ +--- +title: Distributed tracing concepts - .NET +description: .NET distributed tracing concepts +ms.date: 03/14/2021 +--- + +# .NET distributed tracing concepts + +Distributed tracing is a diagnostic technique that helps engineers localize failures and +performance issues within applications, especially those that may be distributed across +multiple machines or processes. See the [Distributed Tracing Overview](distributed-tracing.md) +for general information about where distributed tracing is useful and example code to get +started. + +## Traces and Activities + +Each time a new request is received by an application, it can be associated with a trace. In +application components written in .NET, units of work in a trace are represented by instances of + and the trace as a whole forms +a tree of these Activities, potentially spanning across many distinct processes. The first +Activity created for a new request forms the root of the trace tree and it tracks the overall +duration and success/failure handling the request. Child activities can be optionally created +to subdivide the work into different steps that can be tracked individually. +For example given an Activity that tracked a specific inbound HTTP request in a web server, +child activities could be created to track each of the database queries that were necessary to +complete the request. This allows the duration and success for each query to be recorded independently. +Activities can record other information for each unit of work such as +, name-value pairs +called , and . The +name identifies the type of work being performed, tags can record descriptive parameters of the work, +and events are a simple logging mechanism to record timestamped diagnostic messages. + +> [!NOTE] +> Another common industry name for units of work in a distributed trace are 'Spans'. +> .NET adopted the term 'Activity' many years ago, before the name 'Span' was well +> established for this concept. + +## Activity IDs + +Parent-Child relationships between Activities in the distributed trace tree are established +using unique IDs. .NET's implementation of distributed tracing supports two ID schemes: the W3C +standard [TraceContext](https://www.w3.org/TR/trace-context/), which is the default in .NET 5+, and +an older .NET convention called 'Hierarchical' that's available for backwards compatibility. + controls which +ID scheme is used. In the W3C TraceContext standard, every trace is assigned a globally unique 16-byte trace-id (), and +every Activity within the trace is assigned a unique 8-byte span-id +(). Each Activity +records the trace-id, its own span-id, and the span-id of its parent +(). Because +distributed traces can track work across process boundaries, parent and child Activities may +not be in the same process. The combination of a trace-id and parent span-id can uniquely +identify the parent Activity globally, regardless of what process it resides in. + + controls which +ID format is used for starting new traces, but by default adding a new Activity to an existing +trace uses whatever format the parent Activity is using. +Setting +to true overrides this behavior and creates all new Activities with the DefaultIdFormat, even +when the parent uses a different ID format. + +## Start and stop Activities + +Each thread in a process may have a corresponding Activity object that is tracking the work +occurring on that thread, accessible via +. The current activity +automatically flows along all synchronous calls on a thread as well as following async calls +that are processed on different threads. If Activity A is the current activity on a thread and +code starts a new Activity B, then B becomes the new current activity on that thread. By default, +activity B will also treat Activity A as its parent. When Activity B is later stopped, activity +A will be restored as the current Activity on the thread. When an Activity is started, it +captures the current time as the +. When it +stops, is calculated +as the difference between the current time and the start time. + +## Coordinate across process boundaries + +To track work across process boundaries, Activity parent IDs need to be transmitted across +the network so that the receiving process can create Activities that refer to them. When using +W3C TraceContext ID format, .NET also uses the HTTP headers recommended by +[the standard](https://www.w3.org/TR/trace-context/) to transmit this information. When using the + ID format, +.NET uses a custom request-id HTTP header to transmit the ID. Unlike many other language runtimes, +.NET in-box libraries such as the ASP.NET web server and System.Net.Http natively understand how to +decode and encode Activity IDs on HTTP messages. The runtime also understands how to flow the ID +through synchronous and asynchronous calls. This means that .NET applications that receive and +emit HTTP messages participate in flowing distributed trace IDs automatically, with no special +coding by the app developer or third-party library dependencies. Third-party libraries may add +support for transmitting IDs over non-HTTP message protocols or supporting custom encoding +conventions for HTTP. + +## Collect traces + +Instrumented code can create objects +as part of a distributed trace, but the information in these objects needs to be transmitted +and serialized in a centralized persistant store so that the entire trace can be usefully reviewed +later. There are several telemetry collection libraries that can do this task such as +[Application Insights](/azure/azure-monitor/app/distributed-tracing), +[OpenTelemetry](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/docs/trace/getting-started/README.md), +or a library provided by a third-party telemetry or APM vendor. Alternately developers can author +their own custom Activity telemetry collection by using + or +. ActivityListener +supports observing any Activity regardless whether the developer has any a priori knowledge about it. +This makes ActivityListener a simple and flexible general purpose solution. By contrast using +DiagnosticListener is a more complex scenario that requires the instrumented code to opt in by +invoking and +the collection library needs to know the exact naming information that the instrumented code +used when starting it. Using DiagnosticSource and DiagnosticListener allows the creator +and listener to exchange arbitrary .NET objects and establish customized information passing +conventions. + +## Sampling + +For improved performance in high throughput applications, distributed tracing on .NET supports +sampling only a subset of traces rather than recording all of them. For activities created with +the recommended +API, telemetry collection libraries can control sampling with the + callback. +The logging library can elect not to create the Activity at all, to create it with minimal +information necessary to propagate distributing tracing IDs, or to populate it with complete +diagnostic information. These choices trade-off increasing performance overhead for +increasing diagnostic utility. Activities that are started using the older pattern of invoking + and + may +also support DiagnosticListener sampling by first calling +. +Even when capturing full diagnostic information the .NET +implementation is designed to be fast - coupled with an efficient collector an Activity can be +created, populated, and transmitted in about a microsecond on modern hardware. Sampling +can reduce the instrumentation cost to less than 100 nanoseconds for each Activity that isn't +recorded. + +## Next steps + +For example code to get started +using distributed tracing in .NET applications, see the [Distributed Tracing Instrumentation](distributed-tracing-instrumentation-walkthroughs.md). diff --git a/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md b/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md new file mode 100644 index 0000000000000..4a85aa63fbfcb --- /dev/null +++ b/docs/core/diagnostics/distributed-tracing-instrumentation-walkthroughs.md @@ -0,0 +1,457 @@ +--- +title: Add distributed tracing instrumentation - .NET +description: A tutorial to instrument distributed traces in .NET applications +ms.topic: tutorial +ms.date: 03/14/2021 +--- + +# Adding distributed tracing instrumentation + +**This article applies to: ✔️** .NET Core 2.1 and later versions **✔️** .NET Framework 4.5 and later versions + +.NET applications can be instrumented using the API to produce +distributed tracing telemetry. Some instrumentation is built into standard .NET libraries, but you may want to add more to make +your code more easily diagnosable. In this tutorial, you will add new custom distributed tracing instrumentation. See +[the collection tutorial](distributed-tracing-instrumentation-walkthroughs.md) to learn more about recording the telemetry +produced by this instrumentation. + +## Prerequisites + +- [.NET Core 2.1 SDK](https://dotnet.microsoft.com/download/dotnet) or a later version + +## Create initial app + +First you will create a sample app that collects telemetry using OpenTelemetry, but doesn't yet have any instrumentation. + +```dotnetcli +dotnet new console +``` + +Applications that target .NET 5 and later already have the necessary distributed tracing APIs included. For apps targeting older +.NET versions, add the [System.Diagnostics.DiagnosticSource NuGet package](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource/) +version 5 or greater. + +```dotnetcli +dotnet add package System.Diagnostics.DiagnosticSource +``` + +Add the [OpenTelemetry](https://www.nuget.org/packages/OpenTelemetry/) and +[OpenTelemetry.Exporter.Console](https://www.nuget.org/packages/OpenTelemetry.Exporter.Console/) NuGet packages, which will be used to collect the telemetry. + +```dotnetcli +dotnet add package OpenTelemetry +dotnet add package OpenTelemetry.Exporter.Console +``` + +Replace the contents of the generated Program.cs with this example source: + +```C# +using OpenTelemetry; +using OpenTelemetry.Resources; +using OpenTelemetry.Trace; +using System; +using System.Threading.Tasks; + +namespace Sample.DistributedTracing +{ + class Program + { + static async Task Main(string[] args) + { + using var tracerProvider = Sdk.CreateTracerProviderBuilder() + .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("MySample")) + .AddSource("Sample.DistributedTracing") + .AddConsoleExporter() + .Build(); + + await DoSomeWork("banana", 8); + Console.WriteLine("Example work done"); + } + + // All the functions below simulate doing some arbitrary work + static async Task DoSomeWork(string foo, int bar) + { + await StepOne(); + await StepTwo(); + } + + static async Task StepOne() + { + await Task.Delay(500); + } + + static async Task StepTwo() + { + await Task.Delay(1000); + } + } +} +``` + +The app has no instrumentation yet so there is no trace information to display: + +```dotnetcli +> dotnet run +Example work done +``` + +### Best practices + +Only app developers need to reference an optional third-party library for collecting the +distributed trace telemetry, such as OpenTelemetry in this example. .NET library +authors can exclusively rely on APIs in System.Diagnostics.DiagnosticSource, which is part +of .NET runtime. This ensures that libraries will run in a wide range of .NET apps, regardless +of the app developer's preferences about which library or vendor to use for collecting +telemetry. + +## Add basic instrumentation + +Applications and libraries add distributed tracing instrumentation using the + and + classes. + +### ActivitySource + +First create an instance of ActivitySource. ActivitySource provides APIs to create and +start Activity objects. Add the static ActivitySource variable above Main() and +`using System.Diagnostics;` to the using statements. + +```csharp +using OpenTelemetry; +using OpenTelemetry.Resources; +using OpenTelemetry.Trace; +using System; +using System.Diagnostics; +using System.Threading.Tasks; + +namespace Sample.DistributedTracing +{ + class Program + { + private static ActivitySource source = new ActivitySource("Sample.DistributedTracing", "1.0.0"); + + static async Task Main(string[] args) + { + ... +``` + +#### Best practices + +- Create the ActivitySource once, store it in a static variable and use that instance as long as needed. +Each library or library subcomponent can (and often should) create its own source. Consider creating a new +source rather than reusing an existing one if you anticipate app developers would appreciate being able to +enable and disable the Activity telemetry in the sources independently. + +- The source name passed to the constructor has to be unique to avoid the conflicts with any other sources. +If +there are multiple sources within the same assembly, use a hierarchical name that contains the assembly name and optionally a component name, for example, `Microsoft.AspNetCore.Hosting`. If an assembly +is adding instrumentation for code in a second, independent assembly, the name should be based on the +assembly that defines the ActivitySource, not the assembly whose code is being instrumented. + +- The version parameter is optional. We recommend that you provide the version in case you release multiple +versions of the library and make changes to the instrumented telemetry. + +> [!NOTE] +> OpenTelemetry uses alternate terms 'Tracer' and 'Span'. In .NET 'ActivitySource' is the implementation +> of Tracer and Activity is the implementation of 'Span'. .NET's Activity type long pre-dates +> the OpenTelemetry specification and the original .NET naming has been preserved for +> consistency within the .NET ecosystem and .NET application compatibility. + +### Activity + +Use the ActivitySource object to Start and Stop Activity objects around meaningful units of work. Update +DoSomeWork() with the code shown here: + +```csharp + static async Task DoSomeWork(string foo, int bar) + { + using (Activity activity = source.StartActivity("SomeWork")) + { + await StepOne(); + await StepTwo(); + } + } +``` + +Running the app now shows the new Activity being logged: + +```dotnetcli +> dotnet run +Activity.Id: 00-f443e487a4998c41a6fd6fe88bae644e-5b7253de08ed474f-01 +Activity.DisplayName: SomeWork +Activity.Kind: Internal +Activity.StartTime: 2021-03-18T10:36:51.4720202Z +Activity.Duration: 00:00:01.5025842 +Resource associated with Activity: + service.name: MySample + service.instance.id: 067f4bb5-a5a8-4898-a288-dec569d6dbef +``` + +#### Notes + +- creates and starts +the activity at the same time. The listed code pattern is using the `using` block, which automatically disposes +the created Activity object after executing the block. Disposing the Activity object will stop it so the code +doesn't need to explicitly call . +That simplifies the coding pattern. + +- internally determines if +there are any listeners recording the Activity. If there are no registered listeners or there are listeners that +are not interested, `StartActivity()` will return `null` and avoid creating the Activity object. This +is a performance optimization so that the code pattern can still be used in functions that are called frequently. + +## Optional: Populate tags + +Activities support key-value data called Tags, commonly used to store any parameters of the work that +may be useful for diagnostics. Update DoSomeWork() to include them: + +```csharp + static async Task DoSomeWork(string foo, int bar) + { + using (Activity activity = source.StartActivity("SomeWork")) + { + activity?.SetTag("foo", foo); + activity?.SetTag("bar", bar); + await StepOne(); + await StepTwo(); + } + } +``` + +```dotnetcli +> dotnet run +Activity.Id: 00-2b56072db8cb5a4496a4bfb69f46aa06-7bc4acda3b9cce4d-01 +Activity.DisplayName: SomeWork +Activity.Kind: Internal +Activity.StartTime: 2021-03-18T10:37:31.4949570Z +Activity.Duration: 00:00:01.5417719 +Activity.TagObjects: + foo: banana + bar: 8 +Resource associated with Activity: + service.name: MySample + service.instance.id: 25bbc1c3-2de5-48d9-9333-062377fea49c + +Example work done +``` + +### Best practices + +- As mentioned above, `activity` returned by +may be null. The null-coalescing operator `?.` in C# is a convenient short-hand to only invoke + if `activity` is not null. The behavior is identical to +writing: + +```csharp +if(activity != null) +{ + activity.SetTag("foo", foo); +} +``` + +- OpenTelemetry provides a set of recommended +[conventions](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/trace/semantic_conventions) +for setting Tags on Activities that represent common types of application work. + +- If you are instrumenting functions with high-performance requirements, + is a hint that indicates whether any +of the code listening to Activities intends to read auxiliary information such as Tags. If no listener will read it, then there +is no need for the instrumented code to spend CPU cycles populating it. For simplicity, this sample doesn't apply that +optimization. + +## Optional: Add events + +Events are timestamped messages that can attach an arbitrary stream of additional diagnostic data to Activities. Add +some events to the Activity: + +```csharp + static async Task DoSomeWork(string foo, int bar) + { + using (Activity activity = source.StartActivity("SomeWork")) + { + activity?.SetTag("foo", foo); + activity?.SetTag("bar", bar); + await StepOne(); + activity?.AddEvent(new ActivityEvent("Part way there")); + await StepTwo(); + activity?.AddEvent(new ActivityEvent("Done now")); + } + } +``` + +```dotnetcli +> dotnet run +Activity.Id: 00-82cf6ea92661b84d9fd881731741d04e-33fff2835a03c041-01 +Activity.DisplayName: SomeWork +Activity.Kind: Internal +Activity.StartTime: 2021-03-18T10:39:10.6902609Z +Activity.Duration: 00:00:01.5147582 +Activity.TagObjects: + foo: banana + bar: 8 +Activity.Events: + Part way there [3/18/2021 10:39:11 AM +00:00] + Done now [3/18/2021 10:39:12 AM +00:00] +Resource associated with Activity: + service.name: MySample + service.instance.id: ea7f0fcb-3673-48e0-b6ce-e4af5a86ce4f + +Example work done +``` + +### Best practices + +- Events are stored in an in-memory list until they can be transmitted which makes this mechanism only suitable for +recording a modest number of events. For a large or unbounded volume of events, it's better to use a logging API focused on this task, +such as [ILogger](/aspnet/core/fundamentals/logging/). ILogger also ensures +that the logging information will be available regardless whether the app developer opts to use distributed tracing. +ILogger supports automatically capturing the active Activity IDs so messages logged via that API can still be correlated +with the distributed trace. + +## Optional: Add status + +OpenTelemetry allows each Activity to report a +[Status](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-status) +that represents the pass/fail result of the work. .NET does not currently have a strongly typed API for this purpose but +there is an established convention using Tags: + +- `otel.status_code` is the Tag name used to store `StatusCode`. Values for the StatusCode tag must be one of the +strings "UNSET", "OK", or "ERROR", which correspond respectively to the enums `Unset`, `Ok`, and `Error` from StatusCode. +- `otel.status_description` is the Tag name used to store the optional `Description` + +Update DoSomeWork() to set status: + +```csharp + static async Task DoSomeWork(string foo, int bar) + { + using (Activity activity = source.StartActivity("SomeWork")) + { + activity?.SetTag("foo", foo); + activity?.SetTag("bar", bar); + await StepOne(); + activity?.AddEvent(new ActivityEvent("Part way there")); + await StepTwo(); + activity?.AddEvent(new ActivityEvent("Done now")); + + // Pretend something went wrong + activity?.SetTag("otel.status_code", "ERROR"); + activity?.SetTag("otel.status_description", "Use this text give more information about the error"); + } + } +``` + +## Optional: Add additional Activities + +Activities can be nested to describe portions of a larger unit of work. This can be valuable around +portions of code that might not execute quickly or to better localize failures that come from specific external +dependencies. Although this sample uses an Activity in every method, that is solely because extra code has been +minimized. In a larger and more realistic project, using an Activity in every method would produce extremely +verbose traces, so it's not recommended. + +Update StepOne and StepTwo to add more tracing around these separate steps: + +```csharp + static async Task StepOne() + { + using (Activity activity = source.StartActivity("StepOne")) + { + await Task.Delay(500); + } + } + + static async Task StepTwo() + { + using (Activity activity = source.StartActivity("StepTwo")) + { + await Task.Delay(1000); + } + } +``` + +```dotnetcli +> dotnet run +Activity.Id: 00-9d5aa439e0df7e49b4abff8d2d5329a9-39cac574e8fda44b-01 +Activity.ParentId: 00-9d5aa439e0df7e49b4abff8d2d5329a9-f16529d0b7c49e44-01 +Activity.DisplayName: StepOne +Activity.Kind: Internal +Activity.StartTime: 2021-03-18T10:40:51.4278822Z +Activity.Duration: 00:00:00.5051364 +Resource associated with Activity: + service.name: MySample + service.instance.id: e0a8c12c-249d-4bdd-8180-8931b9b6e8d0 + +Activity.Id: 00-9d5aa439e0df7e49b4abff8d2d5329a9-4ccccb6efdc59546-01 +Activity.ParentId: 00-9d5aa439e0df7e49b4abff8d2d5329a9-f16529d0b7c49e44-01 +Activity.DisplayName: StepTwo +Activity.Kind: Internal +Activity.StartTime: 2021-03-18T10:40:51.9441095Z +Activity.Duration: 00:00:01.0052729 +Resource associated with Activity: + service.name: MySample + service.instance.id: e0a8c12c-249d-4bdd-8180-8931b9b6e8d0 + +Activity.Id: 00-9d5aa439e0df7e49b4abff8d2d5329a9-f16529d0b7c49e44-01 +Activity.DisplayName: SomeWork +Activity.Kind: Internal +Activity.StartTime: 2021-03-18T10:40:51.4256627Z +Activity.Duration: 00:00:01.5286408 +Activity.TagObjects: + foo: banana + bar: 8 + otel.status_code: ERROR + otel.status_description: Use this text give more information about the error +Activity.Events: + Part way there [3/18/2021 10:40:51 AM +00:00] + Done now [3/18/2021 10:40:52 AM +00:00] +Resource associated with Activity: + service.name: MySample + service.instance.id: e0a8c12c-249d-4bdd-8180-8931b9b6e8d0 + +Example work done +``` + +Notice that both StepOne and StepTwo include a ParentId that refers to SomeWork. The console is +not a great visualization of nested trees of work, but many GUI viewers such as +[Zipkin](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Exporter.Zipkin/README.md) +can show this as a Gantt chart: + +[![Zipkin Gantt chart](media/zipkin-nested-activities.jpg)](media/zipkin-nested-activities.jpg) + +## Optional: ActivityKind + +Activities have an property, which +describes the relationship between the Activity, its parent, and its children. By default, all new Activities are +set to , which is appropriate for Activities that are an +internal operation within an application with no remote parent or children. Other kinds can be set using the +kind parameter on +. For other options, see +. + +## Optional: Links + +When work occurs in batch processing systems, a single Activity might represent work on behalf of many +different requests simultaneously, each of which has its own trace-id. Although Activity is restricted +to have a single parent, it can link to additional trace-ids using +. Each ActivityLink is +populated with an that +stores ID information about the Activity being linked to. ActivityContext can be retrieved from in-process +Activity objects using or +it can be parsed from serialized ID information using +. + +```csharp +void DoBatchWork(ActivityContext[] requestContexts) +{ + // Assume each context in requestContexts encodes the trace-id that was sent with a request + using(Activity activity = s_source.StartActivity(name: "BigBatchOfWork", + kind: ActivityKind.Internal, + parentContext: null, + links: requestContexts.Select(ctx => new ActivityLink(ctx)) + { + // do the batch of work here + } +} +``` + +Unlike events and Tags that can be added on-demand, links must be added during StartActivity() and +are immutable afterwards. diff --git a/docs/core/diagnostics/distributed-tracing.md b/docs/core/diagnostics/distributed-tracing.md index 13590c6680d3a..d8c78b2813de0 100644 --- a/docs/core/diagnostics/distributed-tracing.md +++ b/docs/core/diagnostics/distributed-tracing.md @@ -1,229 +1,43 @@ --- title: Distributed tracing - .NET description: An introduction to .NET distributed tracing. -ms.date: 02/02/2021 +ms.date: 03/15/2021 --- -# .NET Distributed Tracing +# .NET distributed tracing -Distributed tracing is the way to publish and observe tracing data in a distributed system. -.NET Framework and .NET Core has been supporting tracing through the APIs. +Distributed tracing is a diagnostic technique that helps engineers localize failures and +performance issues within applications, especially those that may be distributed across +multiple machines or processes. This technique tracks requests through an application +correlating together work done by different application components and separating it from +other work the application may be doing for concurrent requests. For example, a request to a +typical web service might be first received by a load balancer, then forwarded to a web server +process, which then makes several queries to a database. Using distributed tracing allows +engineers to distinguish if any of those steps failed, how long each step took, and potentially +logging messages produced by each step as it ran. -- class which allows storing and accessing diagnostics context and consuming it with logging system. -- that allows code to be instrumented for production-time logging of rich data payloads for consumption within the process that was instrumented. +## Getting started for .NET app developers -Here is an example that shows how to publish tracing data from the HTTP incoming requests: +Key .NET libraries are instrumented to produce distributed tracing information automatically. However, this information needs to be collected and stored so that it will be available for review later. +Typically, app developers select a telemetry service that stores this trace information for them and +then use a corresponding library to transmit the distributed tracing telemetry to their chosen +service: -```csharp - public void OnIncomingRequest(DiagnosticListener httpListener, HttpContext context) - { - if (httpListener.IsEnabled("Http_In")) - { - var activity = new Activity("Http_In"); +- [OpenTelemetry](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/docs/trace/getting-started/README.md) +is a vendor-neutral library that supports several services. For more information, see [Collect distributed traces with OpenTelemetry](distributed-tracing-collection-walkthroughs.md#collect-traces-using-opentelemetry). +- [Application Insights](/azure/azure-monitor/app/distributed-tracing) +is a full-featured service provided by Microsoft. For more information, see [Collect distributed traces with Application Insights](distributed-tracing-collection-walkthroughs.md#collect-traces-using-application-insights). +- There are many high-quality third-party application performance monitoring (APM) vendors that offer integrated .NET solutions. - //add tags, baggage, etc. - activity.SetParentId(context.Request.headers["Request-id"]) - foreach (var pair in context.Request.Headers["Correlation-Context"]) - { - var baggageItem = NameValueHeaderValue.Parse(pair); - activity.AddBaggage(baggageItem.Key, baggageItem.Value); - } - httpListener.StartActivity(activity, new { context }); - try - { - //process request ... - } - finally - { - //stop activity - httpListener.StopActivity(activity, new {context} ); - } - } - } -``` +For more information, see [Understand distributed tracing concepts](distributed-tracing-concepts.md) and the following guides: -Here is example for how to listen to the Activity events: +- [Collect distributed traces with custom logic](distributed-tracing-collection-walkthroughs.md#collect-traces-using-custom-logic) +- [Adding custom distributed trace instrumentation](distributed-tracing-instrumentation-walkthroughs.md) -```csharp - DiagnosticListener.AllListeners.Subscribe(delegate (DiagnosticListener listener) - { - if (listener.Name == "MyActivitySource") - { - listener.Subscribe(delegate (KeyValuePair value) - { - if (value.Key.EndsWith("Start", StringComparison.Ordinal)) - LogActivityStart(); - else if (value.Key.EndsWith("Stop", StringComparison.Ordinal)) - LogActivityStop(); - }); - } - } -``` +For third-party telemetry collection services, follow the setup instructions provided by the vendor. -.NET 5.0 has extended the capability of the distributed tracing to allow the [OpenTelemetry](https://opentelemetry.io/) tracing scenarios, added Sampling capabilities, simplified the tracing coding pattern, and made listening to the Activity events easier and flexible. +## Getting started for .NET library developers -> [!NOTE] -> To access all added .NET 5.0 capabilities, ensure your project references the [System.Diagnostics.DiagnosticSource](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource/) NuGet package version 5.0 or later. This package can be used in libraries and apps targeting any supported version of the .NET Framework, .NET Core, and .NET Standard. If targeting .NET 5.0 or later, there is no need to manually reference the package as it is included in the shared library installed with the .NET Runtime. +.NET libraries don't need to be concerned with how telemetry is ultimately collected, only +with how it is produced. If you want consumers of your library to be able to see the work that it does detailed in a distributed trace, add distributed tracing instrumentation to support it. -## Getting Started With Tracing - -Applications and libraries can easily publish tracing data by simply using the and the classes. - -### ActivitySource - -The first step to publish tracing data is to create an instance of the ActivitySource class. The ActivitySource is the class that provides APIs to create and start Activity objects and to register ActivityListener objects to listen to the Activity events. - -```csharp - private static ActivitySource source = new ActivitySource("MyCompany.MyComponent.SourceName", "v1"); -``` - -#### Best Practices - -- Create the ActivitySource once and store it in a static variable and use that instance as long as needed. - -- The source name passed to the constructor has to be unique to avoid the conflicts with any other sources. It is recommended to use a hierarchical name contains the company name, the component name, and the source name. For example, `Microsoft.System.HttpClient.HttpInOutRequests`. - -- The version parameter is optional. It is recommended to provide the version in case you plan to release multiple versions of the library or the application and want to distinguish between the sources of different versions. - -### Activity Creation - -Now the created ActivitySource object can be used to create and start Activity objects which are used to log any tracing data in any desired places in the code. - -```csharp - using (Activity activity = source.StartActivity("OperationName")) - { - // Do something - - activity?.AddTag("key", "value"); // log the tracing - } -``` - -This sample code tries to create the Activity object and then logs some tracing tag `key` and `value`. - -#### Notes - -- `ActivitySource.StartActivity` tries to create and start the activity at the same time. The listed code pattern is using the `using` block which automatically disposes the created Activity object after executing the block. Disposing the Activity object will stop this started activity and the code doesn't have to explicitly stop the activity. That simplifies the coding pattern. - -- `ActivitySource.StartActivity` internally figures out if there are any listeners to such events. If there are no registered listeners or there are listeners which are not interested in such an event, `ActivitySource.StartActivity` simply will return `null` and avoid creating the Activity object. That is why the code used the nullable operator `?` in the statement `activity?.AddTag`. In general, inside the `using` block, always use the nullable operator `?` after the activity object name. - -## Listening to the Activity Events - -.NET provides the class which can be used to listen to the Activity events triggered from one or more ActivitySources. -The listener can be used to collect tracing data, sample, or force creating the Activity object. - -The `ActivityListener` class provides a different callbacks to handle different events. - -```csharp -var listener = new ActivityListener -{ - ShouldListenTo = (activitySource) => object.ReferenceEquals(source, activitySource), - ActivityStarted = activity => /* Handle the Activity start event here */ DoSomething(), - ActivityStopped = activity => /* Handle the Activity stop event here */ DoSomething(), - SampleUsingParentId = (ref ActivityCreationOptions activityOptions) => ActivitySamplingResult.AllData, - Sample = (ref ActivityCreationOptions activityOptions) => ActivitySamplingResult.AllData -}; - -// Enable the listener -ActivitySource.AddActivityListener(listener); -``` - -- `ShouldListenTo` enables listening to specific `ActivitySource` objects. In the example, it enables listening to the `ActivitySource` object we have previously created. There is more flexibility to listen to any other `ActivitySource` objects by checking the `Name` and `Version` of the input `ActivitySource`. - -- `ActivityStarted` and `ActivityStopped` enable getting the `Activity` Start and Stop events for all `Activity` objects created by the `ActivitySource` objects which were enabled by the `ShouldListenTo` callback. - -- `Sample` and `SampleUsingParentId` are the main callbacks which intended for sampling. These two callbacks return the `ActivitySamplingResult` enum value which can tell either to sample in or out the current `Activity` creation request. If the callback returns `ActivitySamplingResult.None` and no other enabled listeners return different value, then the Activity will not get created and `ActivitySource.StartActivity` will return `null`. Otherwise, the `Activity` object will get created. - -## .NET 5.0 New Features - -For awhile the `Activity` class has been supporting tracing scenarios. It allowed adding tags which are key-value pairs of tracing data. It has been supporting Baggage which is are key-value pairs intended to be propagated across the wire. - -.NET 5.0 supports more features mainly to enable OpenTelemetry scenarios. - -### ActivityContext - - is the struct carrying the context of the tracing operations (e.g. the trace Id, Span Id, trace flags, and trace state). Now it is possible to create a new `Activity` providing the parent tracing context. Also, it is easy to extract the tracing context from any `Activity` object by calling `Activity.Context` property. - -### ActivityLink - - is the struct containing the tracing context instance which can be linked to casually related `Activity` objects. Links can be added to the `Activity` object by passing the links list to `ActivitySource.StartActivity` method when creating the `Activity`. The `Activity` object attached links can be retrieved using the property `Activity.Links`. - -### ActivityEvent - - represents an event containing a name and a timestamp, as well as an optional list of tags. Events can be added to the `Activity` object by calling `Activity.AddEvent` method. The whole list of the `Activity` object Events can be retrieved using the property `Activity.Events`. - -### ActivityKind - - describes the relationship between the activity, its parents and its children in a trace. Kind can be set to the `Activity` object by passing the kind value to `ActivitySource.StartActivity` method when creating the `Activity`. The `Activity` object kind can be retrieved using the property `Activity.Kind`. - -### IsAllDataRequested - - indicates whether this activity should be populated with all the propagation information, as well as all the other properties, such as links, tags, and events. The value of `IsAllDataRequested` is determined from the result returned from all listeners `Sample` and `SampleUsingParentId` callbacks. The value can be retrieved using `Activity.IsAllDataRequested` property. - -### Activity.Source - - gets the activity source associated with this activity. - -### Activity.DisplayName - - allows getting or setting a display name for the activity. - -### Activity.TagObjects - -`Activity` class has the property `Activity.Tags` which return the a key-value pair list of the tags of type string for the key and value. Such Tags can be added to the `Activity` using the method `AddTag(string, string)`. `Activity` has extended the support of tags by providing the overloaded method `AddTag(string, object)` allowing values of any type. The complete list of such tags can be retrieved using . - -## Sampling - -Sampling is a mechanism to control the noise and overhead by reducing the number of samples of traces collected and sent to the backend. Sampling is an important OpenTelemetry scenario. In .NET 5.0 it is easy to allow sampling. A good practice is to create the new `Activity` objects using `ActivitySource.StartActivity` and try to provide all possible available data (e.g. tags, kind, links, ...etc.) when calling this method. Providing the data will allow the samplers implemented using the `ActivityListener` to have a proper sampling decision. If the performance is critical to avoid creating the data before creating the `Activity` object, the property `ActivitySource.HasListeners` comes in handy to check if there are any listeners before creating the needed data. - -## OpenTelemetry - -OpenTelemetry SDK comes with many features that support end-to-end distributed tracing scenarios. It provides multiple samplers and exporters which you can choose from. It allows creating a custom samplers and exporters too. - -OpenTelemetry supports exporting the collected tracing data to different backends (e.g. Jaeger, Zipkin, New Relic,...etc.). Refer to [OpenTelemetry-dotnet](https://github.com/open-telemetry/opentelemetry-dotnet/) for more details and search Nuget.org for packages starting with `OpenTelemetry.Exporter.` to get the exporter packages list. - -Here is sample code ported from [OpenTelemetry-dotnet getting started](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/trace/getting-started) showing how easy it is to sample and export tracing data to the console. - -```csharp -// -// Copyright The OpenTelemetry Authors -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. -// - -using System.Diagnostics; -using OpenTelemetry; -using OpenTelemetry.Trace; - -public class Program -{ - private static readonly ActivitySource MyActivitySource = new ActivitySource( - "MyCompany.MyProduct.MyLibrary"); - - public static void Main() - { - using var tracerProvider = Sdk.CreateTracerProviderBuilder() - .SetSampler(new AlwaysOnSampler()) - .AddSource("MyCompany.MyProduct.MyLibrary") - .AddConsoleExporter() - .Build(); - - using (var activity = MyActivitySource.StartActivity("SayHello")) - { - activity?.SetTag("foo", 1); - activity?.SetTag("bar", "Hello, World!"); - activity?.SetTag("baz", new int[] { 1, 2, 3 }); - } - } -} -``` - -The sample needs to reference the package [OpenTelemetry.Exporter.Console](https://www.nuget.org/packages/OpenTelemetry.Exporter.Console/1.0.0-rc2). +For more information, see [Understand distributed tracing concepts](distributed-tracing-concepts.md) and the [Adding custom distributed trace instrumentation](distributed-tracing-instrumentation-walkthroughs.md) guide. diff --git a/docs/core/diagnostics/dotnet-counters.md b/docs/core/diagnostics/dotnet-counters.md index 7485e9e6239fd..b71c9089508b5 100644 --- a/docs/core/diagnostics/dotnet-counters.md +++ b/docs/core/diagnostics/dotnet-counters.md @@ -2,6 +2,7 @@ title: dotnet-counters diagnostic tool - .NET CLI description: Learn how to install and use the dotnet-counter CLI tool for ad-hoc health monitoring and first-level performance investigation. ms.date: 11/17/2020 +ms.topic: reference --- # Investigate performance counters (dotnet-counters) diff --git a/docs/core/diagnostics/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md index fbf2da0f866da..7b2931b0ea2b2 100644 --- a/docs/core/diagnostics/dotnet-dump.md +++ b/docs/core/diagnostics/dotnet-dump.md @@ -2,6 +2,7 @@ title: dotnet-dump diagnostic tool - .NET CLI description: Learn how to install and use the dotnet-dump CLI tool to collect and analyze Windows and Linux dumps without any native debugger. ms.date: 11/17/2020 +ms.topic: reference --- # Dump collection and analysis utility (dotnet-dump) @@ -183,7 +184,7 @@ dotnet-dump analyze [-h|--help] [-c|--command] ## Using `dotnet-dump` -The first step is to collect a dump. This step can be skipped if a core dump has already been generated. The operating system or the .NET Core runtime's built-in [dump generation feature](https://github.com/dotnet/runtime/blob/master/docs/design/coreclr/botr/xplat-minidump-generation.md) can each create core dumps. +The first step is to collect a dump. This step can be skipped if a core dump has already been generated. The operating system or the .NET Core runtime's built-in [dump generation feature](https://github.com/dotnet/runtime/blob/main/docs/design/coreclr/botr/xplat-minidump-generation.md) can each create core dumps. ```console $ dotnet-dump collect --process-id 1902 diff --git a/docs/core/diagnostics/dotnet-gcdump.md b/docs/core/diagnostics/dotnet-gcdump.md index 994795cff0c3d..907d27d560d9b 100644 --- a/docs/core/diagnostics/dotnet-gcdump.md +++ b/docs/core/diagnostics/dotnet-gcdump.md @@ -2,6 +2,7 @@ title: dotnet-gcdump diagnostic tool - .NET CLI description: Learn how to install and use dotnet-gcdump CLI tool to collect GC (Garbage Collector) dumps of live .NET processes using the .NET EventPipe. ms.date: 11/17/2020 +ms.topic: reference --- # Heap analysis tool (dotnet-gcdump) diff --git a/docs/core/diagnostics/dotnet-sos.md b/docs/core/diagnostics/dotnet-sos.md index a1e11f74c7437..b34844a4a9541 100644 --- a/docs/core/diagnostics/dotnet-sos.md +++ b/docs/core/diagnostics/dotnet-sos.md @@ -2,6 +2,7 @@ title: dotnet-sos diagnostic tool - .NET CLI description: Learn how to install and use the dotnet-sos CLI tool to manage the SOS debugger extension, which is used with native debuggers on Windows and Linux. ms.date: 11/17/2020 +ms.topic: reference --- # SOS installer (dotnet-sos) diff --git a/docs/core/diagnostics/dotnet-stack.md b/docs/core/diagnostics/dotnet-stack.md new file mode 100644 index 0000000000000..52fafed446383 --- /dev/null +++ b/docs/core/diagnostics/dotnet-stack.md @@ -0,0 +1,145 @@ +--- +title: dotnet-stack diagnostic tool - .NET CLI +description: Learn how to install and use the dotnet-stack CLI tool which captures and prints the managed stacks for all threads in the target .NET process. +ms.date: 04/21/2021 +--- +# Inspect managed stack traces (dotnet-stack) + +**This article applies to:** ✔️ .NET Core 3.0 and later versions + +## Install + +There are two ways to download and install `dotnet-stack`: + +- **dotnet global tool:** + + To install the latest release version of the `dotnet-stack` [NuGet package](https://www.nuget.org/packages/dotnet-stack), use the [dotnet tool install](../tools/dotnet-tool-install.md) command: + + ```dotnetcli + dotnet tool install --global dotnet-stack + ``` + +- **Direct download:** + + Download the tool executable that matches your platform: + + | OS | Platform | + | --- | -------- | + | Windows | [x86](https://aka.ms/dotnet-stack/win-x86) \| [x64](https://aka.ms/dotnet-stack/win-x64) \| [arm](https://aka.ms/dotnet-stack/win-arm) \| [arm-x64](https://aka.ms/dotnet-stack/win-arm64) | + | macOS | [x64](https://aka.ms/dotnet-stack/osx-x64) | + | Linux | [x64](https://aka.ms/dotnet-stack/linux-x64) \| [arm](https://aka.ms/dotnet-stack/linux-arm) \| [arm64](https://aka.ms/dotnet-stack/linux-arm64) \| [musl-x64](https://aka.ms/dotnet-stack/linux-musl-x64) \| [musl-arm64](https://aka.ms/dotnet-stack/linux-musl-arm64) | + +## Synopsis + +```console +dotnet-stack [-h, --help] [--version] +``` + +## Description + +The `dotnet-stack` tool: + +* Is a cross-platform .NET Core tool. +* Captures and prints the managed stacks for all threads in the target .NET process. +* Utilizes [`EventPipe`](./eventpipe.md) tracing provided by the .NET Core runtime. + +## Options + +- **`-h|--help`** + + Shows command-line help. + +- **`--version`** + + Displays the version of the dotnet-stack utility. + +## Commands + +| Command | Description | +|---------------------------------------------|---------------------------------------------------------------| +| [dotnet-stack report](#dotnet-stack-report) | Prints the stack trace for each thread in the target process. | +| [dotnet-stack ps](#dotnet-stack-ps) | Lists the dotnet processes that traces can be collected from. | + +## dotnet-stack report + +Prints the stack trace for each thread in the target process. + +### Synopsis + +```console +dotnet-stack report -p|--process-id + -n|--name + [-h|--help] +``` + +### Options + +- **`-n, --name `** + + The name of the process to collect the trace from. + +- **`-p|--process-id `** + + The process ID to collect the trace from. + +## dotnet-stack ps + + Lists the dotnet processes that traces can be collected from. + +### Synopsis + +```console +dotnet-stack ps [-h|--help] +``` + +## Report managed stacks with dotnet-stack + +To report managed stacks using `dotnet-stack`: + +- Get the process identifier (PID) of the .NET Core application to report stacks from. + + - On Windows, you can use Task Manager or the `tasklist` command, for example. + - On Linux, for example, the `ps` command. + - [dotnet-stack ps](#dotnet-stack-ps) + +- Run the following command: + + ```console + dotnet-stack report --process-id + ``` + + The preceding command generates output similar to the following: + + ```console + Thread (0x48839B): + [Native Frames] + System.Console!System.IO.StdInReader.ReadKey(bool&) + System.Console!System.IO.SyncTextReader.ReadKey(bool&) + System.Console!System.ConsolePal.ReadKey(bool) + System.Console!System.Console.ReadKey() + StackTracee!Tracee.Program.Main(class System.String[]) + ``` + + The output of `dotnet-stack` follows the following form: + + - Comments in the output are prefixed with `#`. + - Each thread has a header that includes the native thread ID: `Thread ():`. + - Stack frames follow the form `Module!Method`. + - Transitions to unmanaged code are represented as `[Native Frames]` in the output. + + ```console + # comment + Thread (0x1234): + module!Method + module!Method + + Thread (0x5678): + [Native Frames] + Module!Method + Module!Method + ``` + +## Next steps + +- [Use dotnet-trace to collect CPU samples of a .NET application](dotnet-trace.md) +- [Use dotnet-dump to collect a dump of a .NET application](dotnet-dump.md) diff --git a/docs/core/diagnostics/dotnet-symbol.md b/docs/core/diagnostics/dotnet-symbol.md index 45000748ace0d..ef0c64a6ce0ed 100644 --- a/docs/core/diagnostics/dotnet-symbol.md +++ b/docs/core/diagnostics/dotnet-symbol.md @@ -2,6 +2,7 @@ title: dotnet-symbol diagnostic tool - .NET CLI description: Learn how to install and use the dotnet-symbol CLI tool to download files required for debugging .NET dumps and minidumps. ms.date: 11/17/2020 +ms.topic: reference --- # Symbol downloader (dotnet-symbol) @@ -96,4 +97,4 @@ dotnet-symbol --host-only --debugging ## See also * [Debugging with symbols](/windows/win32/dxtecharts/debugging-with-symbols) -* [Portable PDBs](https://github.com/dotnet/core/blob/master/Documentation/diagnostics/portable_pdb.md) +* [Symbols and Portable PDBs](./symbols.md) diff --git a/docs/core/diagnostics/dotnet-trace.md b/docs/core/diagnostics/dotnet-trace.md index 0776ca9811510..3e733525025b2 100644 --- a/docs/core/diagnostics/dotnet-trace.md +++ b/docs/core/diagnostics/dotnet-trace.md @@ -2,6 +2,7 @@ title: dotnet-trace diagnostic tool - .NET CLI description: Learn how to install and use the dotnet-trace CLI tool to collect .NET traces of a running process without the native profiler, by using the .NET EventPipe. ms.date: 11/17/2020 +ms.topic: reference --- # dotnet-trace performance analysis utility @@ -68,7 +69,7 @@ The `dotnet-trace` tool: ## dotnet-trace collect -Collects a diagnostic trace from a running process. +Collects a diagnostic trace from a running process or launches a child process and traces it (.NET 5+ only). To have the tool run a child process and trace it from its startup, append `--` to the collect command. ### Synopsis @@ -77,6 +78,7 @@ dotnet-trace collect [--buffersize ] [--clreventlevel ] [-- [--format ] [-h|--help] [-n, --name ] [--diagnostic-port] [-o|--output ] [-p|--process-id ] [--profile ] [--providers ] + [--show-child-io] [-- ] (for target applications running .NET 5.0 or later) ``` @@ -86,6 +88,9 @@ dotnet-trace collect [--buffersize ] [--clreventlevel ] [-- Sets the size of the in-memory circular buffer, in megabytes. Default 256 MB. + > [!NOTE] + > If the target process writes events too frequently, it can overflow this buffer and some events might be dropped. If too many events are getting dropped, increase the buffer size to see if the number of dropped events reduces. If the number of dropped events does not decrease with a larger buffer size, it may be due to a slow reader preventing the target process' buffers from being flushed. + - **`--clreventlevel `** Verbosity of CLR events to be emitted. @@ -183,6 +188,10 @@ dotnet-trace collect [--buffersize ] [--clreventlevel ] [-- > [!NOTE] > Using this option monitors the first .NET 5.0 process that communicates back to the tool, which means if your command launches multiple .NET applications, it will only collect the first app. Therefore, it is recommended you use this option on self-contained applications, or using the `dotnet exec ` option. +- **`--show-child-io`** + + Shows the input and output streams of a launched child process in the current console. + > [!NOTE] > Stopping the trace may take a long time (up to minutes) for large applications. The runtime needs to send over the type cache for all managed code that was captured in the trace. @@ -305,7 +314,7 @@ Press or to exit... You can stop collecting the trace by pressing `` or `` key. Doing this will also exit `hello.exe`. > [!NOTE] -> Launching `hello.exe` via dotnet-trace will make its input/output to be redirected and you won't be able to interact with its stdin/stdout. +> Launching `hello.exe` via dotnet-trace will redirect its input/output and you won't be able to interact with it on the console by default. Use the `--show-child-io` switch to interact with its stdin/stdout. > Exiting the tool via CTRL+C or SIGTERM will safely end both the tool and the child process. > If the child process exits before the tool, the tool will exit as well and the trace should be safely viewable. diff --git a/docs/core/diagnostics/dumps.md b/docs/core/diagnostics/dumps.md index de4bf090ea8fe..3450b763e4915 100644 --- a/docs/core/diagnostics/dumps.md +++ b/docs/core/diagnostics/dumps.md @@ -17,7 +17,7 @@ Dumps can be collected in a variety of ways depending on which platform you are > [!NOTE] > Dumps may contain sensitive information because they can contain the full memory of the running process. Handle them with any security restrictions and guidances in mind. -### Collecting dumps on crash +### Collect dumps on crash You can use environment variables to configure your application to collect a dump upon a crash. This is helpful when you want to get an understanding of why a crash happened. For example, capturing a dump when an exception is thrown helps you identify an issue by examining the state of the app when it crashed. @@ -25,12 +25,14 @@ The following table shows the environment variables you can configure for collec |Environment variable|Description|Default value| |-------|---------|---| -|`COMPlus_DbgEnableMiniDump`|If set to 1, enable core dump generation.|0| -|`COMPlus_DbgMiniDumpType`|Type of dump to be collected. For more information, see the table below|2 (`MiniDumpWithPrivateReadWriteMemory`)| -|`COMPlus_DbgMiniDumpName`|Path to a file to write the dump to.|`/tmp/coredump.`| -|`COMPlus_CreateDumpDiagnostics`|If set to 1, enable diagnostic logging of dump process.|0| +|`DOTNET_DbgEnableMiniDump`|If set to 1, enable core dump generation.|0| +|`DOTNET_DbgMiniDumpType`|Type of dump to be collected. For more information, see the table below|2 (`MiniDumpWithPrivateReadWriteMemory`)| +|`DOTNET_DbgMiniDumpName`|Path to a file to write the dump to.|`/tmp/coredump.`| +|`DOTNET_CreateDumpDiagnostics`|If set to 1, enable diagnostic logging of dump process.|0| -The table below shows all the options you may use for `COMPlus_DbgMiniDumpType` which can be specified as a value. For example, setting `COMPlus_DbgMiniDumpType` to 1 means `MiniDumpNormal` type dump will be collected on a crash. +[!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)] + +The following table shows all the values you can use for `DOTNET_DbgMiniDumpType`. For example, setting `DOTNET_DbgMiniDumpType` to 1 means `MiniDumpNormal` type dump will be collected on a crash. |Value|Name|Description| |-----|----|-----------| @@ -39,7 +41,7 @@ The table below shows all the options you may use for `COMPlus_DbgMiniDumpType` |3|`MiniDumpFilterTriage`|Include just the information necessary to capture stack traces for all existing threads in a process. Limited GC heap memory and information.| |4|`MiniDumpWithFullMemory`|Include all accessible memory in the process. The raw memory data is included at the end, so that the initial structures can be mapped directly without the raw memory information. This option can result in a very large file.| -### Collecting dumps at specific point in time +### Collect dumps at a specific point in time You may want to collect a dump when the app hasn't crashed yet. For example, if you want to examine the state of an application that seems to be in a deadlock, configuring the environment variables to collect dumps on crash will not be helpful because the app is still running. @@ -50,7 +52,7 @@ To collect dump at your own request, you can use `dotnet-dump`, which is a CLI t You can anlayze dumps using the [`dotnet-dump`](dotnet-dump.md) CLI tool or with [Visual Studio](/visualstudio/debugger/using-dump-files). > [!NOTE] -> Visual Studio version 16.8 and later allows you to [open Linux dumps](https://devblogs.microsoft.com/visualstudio/linux-managed-memory-dump-debugging/) generated on .NET Core 3.1.7 or later. +> Visual Studio version 16.8 and later allows you to [open Linux dumps](https://devblogs.microsoft.com/visualstudio/linux-managed-memory-dump-debugging/) generated on .NET Core 3.1.7 or later. > [!NOTE] > If native debugging is necessary, the [SOS debugger extension](sos-debugging-extension.md) can be used with [LLDB on Linux and macOS](debug-linux-dumps.md#analyze-dumps-on-linux). SOS is also supported with [Windbg/cdb](/windows-hardware/drivers/debugger/debugger-download-tools) on Windows, although Visual Studio is recommended. diff --git a/docs/core/diagnostics/event-counter-perf.md b/docs/core/diagnostics/event-counter-perf.md index 813998aca13e9..6e653ede06953 100644 --- a/docs/core/diagnostics/event-counter-perf.md +++ b/docs/core/diagnostics/event-counter-perf.md @@ -3,6 +3,7 @@ title: Measure performance using EventCounters in .NET Core description: In this tutorial, you'll learn how to measure performance using EventCounters. ms.date: 08/07/2020 ms.topic: tutorial +recommendations: false --- # Tutorial: Measure performance using EventCounters in .NET Core diff --git a/docs/core/diagnostics/event-counters.md b/docs/core/diagnostics/event-counters.md index c84cbbda870e4..18a6e7e75908b 100644 --- a/docs/core/diagnostics/event-counters.md +++ b/docs/core/diagnostics/event-counters.md @@ -122,7 +122,7 @@ The uses the [!NOTE] > The is _not_ used by [dotnet-counters](dotnet-counters.md), and event listeners are not required to use it. -There are more counter implementations to use as a reference in the [.NET runtime](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Private.CoreLib/src/System/Diagnostics/Tracing/RuntimeEventSource.cs) repo. +There are more counter implementations to use as a reference in the [.NET runtime](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Private.CoreLib/src/System/Diagnostics/Tracing/RuntimeEventSource.cs) repo. ## Concurrency @@ -154,7 +154,7 @@ _requestRateCounter = new IncrementingPollingCounter("request-rate", this, () => There are two primary ways of consuming EventCounters, either in-proc, or out-of-proc. The consumption of EventCounters can be distinguished into three layers of various consuming technologies. - Transporting events in a raw stream via ETW or EventPipe: - - ETW APIs come with the Windows OS, and EventPipe is accessible as a [.NET API](https://github.com/dotnet/diagnostics/blob/master/documentation/design-docs/diagnostics-client-library.md#1-attaching-to-a-process-and-dumping-out-all-the-runtime-gc-events-in-real-time-to-the-console), or the diagnostic [IPC protocol](https://github.com/dotnet/diagnostics/blob/master/documentation/design-docs/ipc-protocol.md). + - ETW APIs come with the Windows OS, and EventPipe is accessible as a [.NET API](https://github.com/dotnet/diagnostics/blob/main/documentation/design-docs/diagnostics-client-library.md#1-attaching-to-a-process-and-dumping-out-all-the-runtime-gc-events-in-real-time-to-the-console), or the diagnostic [IPC protocol](https://github.com/dotnet/diagnostics/blob/main/documentation/design-docs/ipc-protocol.md). - Decoding the binary event stream into events: - The [TraceEvent library](https://www.nuget.org/packages/Microsoft.Diagnostics.Tracing.TraceEvent) handles both ETW and EventPipe stream formats. - Command-line and GUI tools: diff --git a/docs/core/diagnostics/eventpipe.md b/docs/core/diagnostics/eventpipe.md index d2975ad27b2a1..898c8762eee34 100644 --- a/docs/core/diagnostics/eventpipe.md +++ b/docs/core/diagnostics/eventpipe.md @@ -11,13 +11,13 @@ EventPipe is a runtime component that can be used to collect tracing data, simil EventPipe is the mechanism behind many of the diagnostic tools and can be used for consuming events emitted by the runtime as well as custom events written with [EventSource](xref:System.Diagnostics.Tracing.EventSource). -This article is a high-level overview of EventPipe describing when and how to use EventPipe, and how to configure it to best suit your needs. +This article is a high-level overview of EventPipe. It describes when and how to use EventPipe, and how to configure it to best suit your needs. ## EventPipe basics EventPipe aggregates events emitted by runtime components - for example, the Just-In-Time compiler or the garbage collector - and events written from [EventSource](xref:System.Diagnostics.Tracing.EventSource) instances in the libraries and user code. -The events are then serialized and can be written directly to a file or consumed through a Diagnostics Port from out-of-proces. On Windows, Diagnostic Ports are implemented as `NamedPipe`s. On non-Windows platforms, such as Linux or macOS, it is implemented using Unix Domain Sockets. For more information about the Diagnostics Port and how to interact with it via its custom inter-process communication protocol, see the [diagnostics IPC protocol documentation](https://github.com/dotnet/diagnostics/blob/master/documentation/design-docs/ipc-protocol.md). +The events are then serialized and can be written directly to a file or consumed through a Diagnostics Port from out-of-proces. On Windows, Diagnostic Ports are implemented as `NamedPipe`s. On non-Windows platforms, such as Linux or macOS, it is implemented using Unix Domain Sockets. For more information about the Diagnostics Port and how to interact with it via its custom inter-process communication protocol, see the [diagnostics IPC protocol documentation](https://github.com/dotnet/diagnostics/blob/main/documentation/design-docs/ipc-protocol.md). EventPipe then writes the serialized events in the `.nettrace` file format, either as a stream via Diagnostic Ports or directly to a file. To learn more about the EventPipe serialization format, refer to the [EventPipe format documentation](https://github.com/microsoft/perfview/blob/master/src/TraceEvent/EventPipe/EventPipeFormat.md). @@ -44,7 +44,7 @@ You can use EventPipe to trace your .NET application in many ways: * Use one of the [diagnostics tools](#tools-that-use-eventpipe) that are built on top of EventPipe. -* Use [Microsoft.Diagnostics.NETCore.Client](https://github.com/dotnet/diagnostics/blob/master/documentation/diagnostics-client-library-instructions.md) library to write your own tool to configure and start EventPipe sessions yourself. +* Use [Microsoft.Diagnostics.NETCore.Client](https://github.com/dotnet/diagnostics/blob/main/documentation/diagnostics-client-library-instructions.md) library to write your own tool to configure and start EventPipe sessions yourself. * Use [environment variables](#trace-using-environment-variables) to start EventPipe. @@ -68,15 +68,18 @@ The preferred mechanism for using EventPipe is to use `dotnet-trace` or the `Mic However, you can use the following environment variables to set up an EventPipe session on an app and have it write the trace directly to a file. To stop tracing, exit the application. -* `COMPlus_EnableEventPipe`: Set this to `1` to start an EventPipe session that writes directly to a file. The default value is `0`. +* `DOTNET_EnableEventPipe`: Set this to `1` to start an EventPipe session that writes directly to a file. The default value is `0`. -* `COMPlus_EventPipeOutputPath`: The path to the output EventPipe trace file when it's configured to run via `COMPlus_EnableEventPipe`. The default value is `trace.nettrace`, which will be created in the same directory that the app is running from. +* `DOTNET_EventPipeOutputPath`: The path to the output EventPipe trace file when it's configured to run via `DOTNET_EnableEventPipe`. The default value is `trace.nettrace`, which will be created in the same directory that the app is running from. -* `COMPlus_EventPipeCircularMB`: A hexadecimal value that represents the size of EventPipe's internal buffer in megabytes. This configuration value is only used when EventPipe is configured to run via `COMPlus_EnableEventPipe`. The default buffer size is 1024MB which translates to this environment variable being set to `400`, since `0x400` == `1024`. +* `DOTNET_EventPipeCircularMB`: A hexadecimal value that represents the size of EventPipe's internal buffer in megabytes. This configuration value is only used when EventPipe is configured to run via `DOTNET_EnableEventPipe`. The default buffer size is 1024MB which translates to this environment variable being set to `400`, since `0x400` == `1024`. -* `COMPlus_EventPipeProcNumbers`: Set this to `1` to enable capturing processor numbers in EventPipe event headers. The default value is `0`. + > [!NOTE] + > If the target process writes events too frequently, it can overflow this buffer and some events might be dropped. If too many events are getting dropped, increase the buffer size to see if the number of dropped events reduces. If the number of dropped events does not decrease with a larger buffer size, it may be due to a slow reader preventing the target process' buffers from being flushed. -* `COMPlus_EventPipeConfig`: Sets up the EventPipe session configuration when starting an EventPipe session with `COMPlus_EnableEventPipe`. +* `DOTNET_EventPipeProcNumbers`: Set this to `1` to enable capturing processor numbers in EventPipe event headers. The default value is `0`. + +* `DOTNET_EventPipeConfig`: Sets up the EventPipe session configuration when starting an EventPipe session with `DOTNET_EnableEventPipe`. The syntax is as follows: `::` @@ -85,10 +88,12 @@ However, you can use the following environment variables to set up an EventPipe `::,::` - If this environment variable is not set but EventPipe is enabled by `COMPlus_EnableEventPipe`, it will start tracing by enabling the following providers with the following keywords and levels: + If this environment variable is not set but EventPipe is enabled by `DOTNET_EnableEventPipe`, it will start tracing by enabling the following providers with the following keywords and levels: - `Microsoft-Windows-DotNETRuntime:4c14fccbd:5` - `Microsoft-Windows-DotNETRuntimePrivate:4002000b:5` - `Microsoft-DotNETCore-SampleProfiler:0:5` To learn more about some of the well-known providers in .NET, refer to [Well-known Event Providers](./well-known-event-providers.md). + +[!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)] diff --git a/docs/core/diagnostics/index.md b/docs/core/diagnostics/index.md index 9e03f0b7a7bf7..4e8c492ee0da5 100644 --- a/docs/core/diagnostics/index.md +++ b/docs/core/diagnostics/index.md @@ -57,6 +57,10 @@ The [dotnet-gcdump](dotnet-gcdump.md) tool is a way to collect GC (Garbage Colle .NET Core includes what is called the `EventPipe` through which diagnostics data is exposed. The [dotnet-trace](dotnet-trace.md) tool allows you to consume interesting profiling data from your app that can help in scenarios where you need to root cause apps running slow. +### dotnet-stack + +The [dotnet-stack](dotnet-stack.md) tool allows you quickly print the managed stacks for all threads in a running .NET process. + ### dotnet-symbol [dotnet-symbol](dotnet-symbol.md) downloads files (symbols, DAC/DBI, host files, etc.) needed to open a core dump or minidump. Use this tool if you need symbols and modules to debug a dump file captured on a different machine. diff --git a/docs/core/diagnostics/logging-tracing.md b/docs/core/diagnostics/logging-tracing.md index bb4ed7494ef2b..bdda4e4c67b3f 100644 --- a/docs/core/diagnostics/logging-tracing.md +++ b/docs/core/diagnostics/logging-tracing.md @@ -19,11 +19,11 @@ This simple technique is surprisingly powerful. It can be used in situations whe ## .NET Core APIs -### Print style APIs +### Print-style APIs -The , , and classes each provide similar print style APIs convenient for logging. +The , , and classes each provide similar print-style APIs that are convenient for logging. -The choice of which print style API to use is up to you. The key differences are: +The choice of which print-style API to use is up to you. The key differences are: - - Always enabled and always writes to the console. @@ -36,7 +36,7 @@ The choice of which print style API to use is up to you. The key differences are - - Only enabled when `DEBUG` is defined by adding `#define DEBUG` to your source or specifying the option `/d:DEBUG` when compiling. - Writes to an attached debugger. - - On `*nix` writes to stderr if `COMPlus_DebugWriteToStdErr` is set. + - On `*nix` writes to stderr if `DOTNET_DebugWriteToStdErr` or `COMPlus_DebugWriteToStdErr` is set. - Use this API when creating logs that will be enabled only in debug builds. ### Logging events @@ -66,7 +66,11 @@ The following APIs are more event oriented. Rather than logging simple strings t ## Distributed Tracing -[Distributed Tracing](./distributed-tracing.md) is the way to publish and observe the tracing data in a distributed system. +[Distributed Tracing](./distributed-tracing.md) is a diagnostic technique that helps engineers +localize failures and performance issues within applications, especially those that may be +distributed across multiple machines or processes. This technique tracks requests through an +application correlating together work done by different application components and separating +it from other work the application may be doing for concurrent requests. ## ILogger and logging frameworks @@ -79,7 +83,7 @@ For instance, to allow you to make the best choice for your application .NET off - [.NET Built-in logging providers](../extensions/logging-providers.md#built-in-logging-providers) - [.NET Third-party logging providers](../extensions/logging-providers.md#third-party-logging-providers) -## Logging related references +## Logging-related references - [How to: Compile Conditionally with Trace and Debug](../../framework/debug-trace-profile/how-to-compile-conditionally-with-trace-and-debug.md) @@ -101,7 +105,7 @@ For instance, to allow you to make the best choice for your application .NET off String formatting can take noticeable CPU processing time. -In performance critical applications, it's recommended that you: +In performance-critical applications, it's recommended that you: - Avoid lots of logging when no one is listening. Avoid constructing costly logging messages by checking if logging is enabled first. - Only log what's useful. diff --git a/docs/core/diagnostics/media/zipkin-nested-activities.jpg b/docs/core/diagnostics/media/zipkin-nested-activities.jpg new file mode 100644 index 0000000000000..a51180242db44 Binary files /dev/null and b/docs/core/diagnostics/media/zipkin-nested-activities.jpg differ diff --git a/docs/core/diagnostics/sos-debugging-extension.md b/docs/core/diagnostics/sos-debugging-extension.md index 1252119934506..e955986743065 100644 --- a/docs/core/diagnostics/sos-debugging-extension.md +++ b/docs/core/diagnostics/sos-debugging-extension.md @@ -2,6 +2,7 @@ title: "SOS Debugging Extension for .NET" description: Learn about the SOS debugging extension for .NET, which provides information about the internal CLR environment. ms.date: "12/21/2020" +ms.topic: reference helpviewer_keywords: - "debugging extensions" - "SOS debugging extensions" diff --git a/docs/core/diagnostics/symbols.md b/docs/core/diagnostics/symbols.md index 66a71a9191a6e..cb17d472254a8 100644 --- a/docs/core/diagnostics/symbols.md +++ b/docs/core/diagnostics/symbols.md @@ -34,7 +34,7 @@ Portable PDBs can be read on any operating systems and is the recommended symbol * There may be older versions of profilers that do not support portable PDBs. -To use portable PDBs on tools that do not support them, you can try using Pdb2Pdb[https://github.com/dotnet/symreader-converter#pdb2pdb] which converts between Portable PDBs and Windows PDBs. +To use portable PDBs on tools that do not support them, you can try using [Pdb2Pdb](https://github.com/dotnet/symreader-converter#pdb2pdb) which converts between Portable PDBs and Windows PDBs. ### Support for Windows PDBs diff --git a/docs/core/diagnostics/trace-perfcollect-lttng.md b/docs/core/diagnostics/trace-perfcollect-lttng.md index dde8caff568f1..2593491be3f16 100644 --- a/docs/core/diagnostics/trace-perfcollect-lttng.md +++ b/docs/core/diagnostics/trace-perfcollect-lttng.md @@ -67,10 +67,12 @@ For resolving method names of native runtime DLLs (such as libcoreclr.so), `perf 3. **[App]** Set up the application shell with the following environment variables - this enables tracing configuration of CoreCLR. > ```bash - > export COMPlus_PerfMapEnabled=1 - > export COMPlus_EnableEventLog=1 + > export DOTNET_PerfMapEnabled=1 + > export DOTNET_EnableEventLog=1 > ``` + [!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)] + 4. **[App]** Run the app - let it run as long as you need to in order to capture the performance problem. The exact length can be as short as you need as long as it sufficiently captures the window of time where the performance problem you want to investigate occurs. > ```bash @@ -154,6 +156,9 @@ PerfView will display the list of views that are supported based on the data con For more information on how to interpret views in PerfView, see help links in the view itself, or from the main window in PerfView, choose **Help->Users Guide**. +> [!NOTE] +> Events written via API (including the events from Framework) won't show up under their provider name. Instead, they are written as `EventSourceEvent` events under `Microsoft-Windows-DotNETRuntime` provider and their payloads are JSON serialized. + ### Use TraceCompass to open the trace file [Eclipse TraceCompass](https://www.eclipse.org/tracecompass/) is another option you can use to view the traces. `TraceCompass` works on Linux machines as well, so you don't need to move your trace over to a Windows machine. To use `TraceCompass` to open your trace file, you will need to unzip the file. @@ -208,16 +213,18 @@ If you don't have the ability to update the .NET Runtime (to add `crossgen`), or To do this, you can add the following environment variable: ```bash -export COMPlus_ZapDisable=1 +export DOTNET_ZapDisable=1 ``` +[!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)] + With this change, you should get the symbols for all .NET code. ## Get symbols for the native runtime Most of the time you are interested in your own code, which `perfcollect` resolves by default. Sometimes it is useful to see what is going on inside the .NET DLLs (which is what the last section was about), but sometimes what is going on in the native runtime dlls (typically libcoreclr.so), is interesting. `perfcollect` will resolve the symbols for these when it converts its data, but only if the symbols for these native DLLs are present (and are beside the library they are for). -There is a global command called [dotnet-symbol](https://github.com/dotnet/symstore/blob/master/src/dotnet-symbol/README.md#symbol-downloader-dotnet-cli-extension) that does this. To use dotnet-symbol to get native runtime symbols: +There is a global command called [dotnet-symbol](https://github.com/dotnet/symstore/blob/main/src/dotnet-symbol/README.md#symbol-downloader-dotnet-cli-extension) that does this. To use dotnet-symbol to get native runtime symbols: 1. Install `dotnet-symbol`: diff --git a/docs/core/docker/build-container.md b/docs/core/docker/build-container.md index 51017c9a3f419..49ab0ce18fca7 100644 --- a/docs/core/docker/build-container.md +++ b/docs/core/docker/build-container.md @@ -1,7 +1,7 @@ --- title: Containerize an app with Docker tutorial description: In this tutorial, you'll learn how to containerize a .NET Core application with Docker. -ms.date: 04/27/2020 +ms.date: 03/22/2021 ms.topic: tutorial ms.custom: "mvc" #Customer intent: As a developer, I want to containerize my .NET Core app so that I can deploy it to the cloud. @@ -184,7 +184,7 @@ FROM mcr.microsoft.com/dotnet/aspnet:5.0 > [!NOTE] > The ASP.NET Core runtime image is used intentionally here, although the `mcr.microsoft.com/dotnet/runtime:5.0` image could have been used. -The `FROM` keyword requires a fully qualified Docker container image name. The Microsoft Container Registry (MCR, mcr.microsoft.com) is a syndicate of Docker Hub - which hosts publicly accessible containers. The `dotnet/core` segment is the container repository, where as the `aspnet` segment is the container image name. The image is tagged with `5.0`, which is used for versioning. Thus, `mcr.microsoft.com/dotnet/aspnet:5.0` is the .NET Core 5.0 runtime. Make sure that you pull the runtime version that matches the runtime targeted by your SDK. For example, the app created in the previous section used the .NET Core 5.0 SDK and the base image referred to in the *Dockerfile* is tagged with **5.0**. +The `FROM` keyword requires a fully qualified Docker container image name. The Microsoft Container Registry (MCR, mcr.microsoft.com) is a syndicate of Docker Hub - which hosts publicly accessible containers. The `dotnet` segment is the container repository, where as the `aspnet` segment is the container image name. The image is tagged with `5.0`, which is used for versioning. Thus, `mcr.microsoft.com/dotnet/aspnet:5.0` is the .NET Core 5.0 runtime. Make sure that you pull the runtime version that matches the runtime targeted by your SDK. For example, the app created in the previous section used the .NET Core 5.0 SDK and the base image referred to in the *Dockerfile* is tagged with **5.0**. Save the *Dockerfile* file. The directory structure of the working folder should look like the following. Some of the deeper-level files and folders have been omitted to save space in the article: @@ -236,6 +236,15 @@ The `WORKDIR` command changes the **current directory** inside of the container The next command, `ENTRYPOINT`, tells Docker to configure the container to run as an executable. When the container starts, the `ENTRYPOINT` command runs. When this command ends, the container will automatically stop. +> [!TIP] +> For added security, you can opt-out of the diagnostic pipeline. When you opt-out this allows the container to run as readonly. In order to do this, specify a `DOTNET_EnableDiagnostics` environment variable as `0` (just before the `ENTRYPOINT` step): +> +> ```dockerfile +> ENV DOTNET_EnableDiagnostics=0 +> ``` + +[!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)] + From your terminal, run `docker build -t counter-image -f Dockerfile .` and when that command finishes, run `docker images`. ```console diff --git a/docs/core/extensions/access-by-line.txt b/docs/core/extensions/access-by-line.txt index c852391157730..e19697855efb6 100644 --- a/docs/core/extensions/access-by-line.txt +++ b/docs/core/extensions/access-by-line.txt @@ -23,6 +23,7 @@ snippets/configuration/options-configparam/ServiceCollectionExtensions.cs: ~/doc snippets/configuration/options-noparams/ServiceCollectionExtensions.cs: ~/docs/core/extensions/options-library-authors.md snippets/configuration/options-object/ServiceCollectionExtensions.cs: ~/docs/core/extensions/options-library-authors.md snippets/configuration/options-postconfig/ServiceCollectionExtensions.cs: ~/docs/core/extensions/options-library-authors.md +snippets/configuration/worker-scope/Worker.cs: ~/docs/core/extensions/dependency-injection.md snippets/configuration/worker-service-options/Worker.cs: ~/docs/core/extensions/high-performance-logging.md snippets/configuration/worker-service/appsettings.IncludeScopes.json: ~/docs/core/extensions/logging.md snippets/configuration/worker-service/Worker.cs: ~/docs/core/extensions/logging.md diff --git a/docs/core/extensions/configuration-providers.md b/docs/core/extensions/configuration-providers.md index 9123938904b8e..70d2d2ef582d7 100644 --- a/docs/core/extensions/configuration-providers.md +++ b/docs/core/extensions/configuration-providers.md @@ -3,7 +3,8 @@ title: Configuration providers in .NET description: Learn how the Configuration provider API is used to configure .NET applications. author: IEvangelist ms.author: dapine -ms.date: 12/04/2020 +ms.date: 05/21/2021 +ms.topic: reference --- # Configuration providers in .NET @@ -52,13 +53,11 @@ An example *appsettings.json* file with various configuration settings follows: From the instance, after configuration providers have been added you can call to get the object. The configuration root represents the root of a configuration hierarchy. Sections from the configuration can be bound to instances of .NET objects, and later provided as through dependency injection. -Consider the `TransientFaultHandlingOptions` record type defined as follows: +Consider the `TransientFaultHandlingOptions` class defined as follows: :::code language="csharp" source="snippets/configuration/console-json/TransientFaultHandlingOptions.cs"::: -For information on record types, see [Record types in C# 9](../../csharp/whats-new/csharp-9.md#record-types). - -The following code builds the configuration root, binds a section to the `TransientFaultHandlingOptions` record type, and prints the bound values to the console window: +The following code builds the configuration root, binds a section to the `TransientFaultHandlingOptions` class type, and prints the bound values to the console window: :::code language="csharp" source="snippets/configuration/console-json/Program.cs" range="31-38"::: @@ -162,6 +161,10 @@ The preceding environment settings: - Are only set in processes launched from the command window they were set in. - Won't be read by web apps launched with Visual Studio. +With Visual Studio 2019 version 16.10 preview 4 and later, you can specify environment variables using the **Launch Profiles** dialog. + +:::image type="content" source="media/launch-profiles-env-vars.png" alt-text="Launch Profiles dialog showing environment variables" lightbox="media/launch-profiles-env-vars.png"::: + The following [setx](/windows-server/administration/windows-commands/setx) commands can be used to set the environment keys and values on Windows. Unlike `set`, `setx` settings are persisted. `/M` sets the variable in the system environment. If the `/M` switch isn't used, a user environment variable is set. ```dotnetcli @@ -244,6 +247,10 @@ Using the default configuration, the ` API dictates what text gets wrappe For inspiration on further customizing formatting, see the existing implementations in the `Microsoft.Extensions.Logging.Console` namespace: -- [SimpleConsoleFormatter](https://github.com/dotnet/runtime/blob/master/src/libraries/Microsoft.Extensions.Logging.Console/src/SimpleConsoleFormatter.cs). -- [SystemdConsoleFormatter](https://github.com/dotnet/runtime/blob/master/src/libraries/Microsoft.Extensions.Logging.Console/src/SystemdConsoleFormatter.cs) -- [JsonConsoleFormatter](https://github.com/dotnet/runtime/blob/master/src/libraries/Microsoft.Extensions.Logging.Console/src/JsonConsoleFormatter.cs) +- [SimpleConsoleFormatter](https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.Extensions.Logging.Console/src/SimpleConsoleFormatter.cs). +- [SystemdConsoleFormatter](https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.Extensions.Logging.Console/src/SystemdConsoleFormatter.cs) +- [JsonConsoleFormatter](https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.Extensions.Logging.Console/src/JsonConsoleFormatter.cs) ## Implement custom color formatting diff --git a/docs/core/extensions/custom-configuration-provider.md b/docs/core/extensions/custom-configuration-provider.md index 1b9e6e9d206f0..977197d3bff9c 100644 --- a/docs/core/extensions/custom-configuration-provider.md +++ b/docs/core/extensions/custom-configuration-provider.md @@ -3,7 +3,7 @@ title: Implement a custom configuration provider in .NET description: Learn how to implement a custom configuration provider in .NET applications. author: IEvangelist ms.author: dapine -ms.date: 12/04/2020 +ms.date: 04/19/2021 ms.topic: how-to --- @@ -17,7 +17,8 @@ The sample app demonstrates how to create a basic configuration provider that re The provider has the following characteristics: -- The EF in-memory database is used for demonstration purposes. To use a database that requires a connection string, implement a secondary `ConfigurationBuilder` to supply the connection string from another configuration provider. +- The EF in-memory database is used for demonstration purposes. + - To use a database that requires a connection string, get a connection string from an interim configuration. - The provider reads a database table into configuration at startup. The provider doesn't query the database on a per-key basis. - Reload-on-change isn't implemented, so updating the database after the app starts has no effect on the app's configuration. @@ -33,6 +34,8 @@ Add an `EntityConfigurationContext` to store and access the configured values. :::code language="csharp" source="snippets/configuration/custom-provider/Providers/EntityConfigurationContext.cs"::: +By overriding you can use the appropriate database connection. For example, if a connection string was provided you could connect to SQL Server, otherwise you could rely on an in-memory database. + Create a class that implements . *Providers/EntityConfigurationSource.cs*: @@ -51,11 +54,28 @@ An `AddEntityConfiguration` extension method permits adding the configuration so :::code language="csharp" source="snippets/configuration/custom-provider/Extensions/ConfigurationBuilderExtensions.cs"::: +> [!IMPORTANT] +> The use of a temporary configuration source to acquire the connection string is important. The current `builder` has its configuration constructed temporarily by calling , and . After obtaining the connection string, the `builder` adds the `EntityConfigurationSource` given the `connectionString`. + The following code shows how to use the custom `EntityConfigurationProvider` in *Program.cs*: -:::code language="csharp" source="snippets/configuration/custom-provider/Program.cs" highlight="27-28"::: +:::code language="csharp" source="snippets/configuration/custom-provider/Program.cs" highlight="33"::: + +## Consume provider + +To consume the custom configuration provider, you can use the [options pattern](options.md). With the sample app in place, define an options object to represent the widget settings. + +:::code language="csharp" source="snippets/configuration/custom-provider/WidgetOptions.cs"::: + +A call to configures the mapping of the options. + +:::code language="csharp" source="snippets/configuration/custom-provider/Program.cs" highlight="16-19,35-37"::: + +The preceding code configures the `WidgetOptions` object from the `"WidgetOptions"` section of the configuration. This enables the options pattern, exposing a dependency injection-ready `IOptions` representation of the EF settings. The options are ultimately provided from the custom configuration provider. ## See also - [Configuration in .NET](configuration.md) - [Configuration providers in .NET](configuration-providers.md) +- [Options pattern in .NET](options.md) +- [Dependency injection in .NET](dependency-injection.md) diff --git a/docs/core/extensions/custom-logging-provider.md b/docs/core/extensions/custom-logging-provider.md index b960bd2863841..e1ee7e5bd8ee8 100644 --- a/docs/core/extensions/custom-logging-provider.md +++ b/docs/core/extensions/custom-logging-provider.md @@ -3,7 +3,7 @@ title: Implement a custom logging provider in .NET description: Learn how to implement a custom logging provider in your .NET applications. author: IEvangelist ms.author: dapine -ms.date: 09/25/2020 +ms.date: 05/06/2021 ms.topic: how-to --- @@ -28,7 +28,7 @@ The `ILogger` implementation category name is typically the logging source. For The preceding code: - Creates a logger instance per category name. -- Checks `logLevel == _config.LogLevel` in `IsEnabled`, so each `logLevel` has a unique logger. Loggers should also be enabled for all higher log levels: +- Checks `_config.LogLevels.ContainsKey(logLevel)` in `IsEnabled`, so each `logLevel` has a unique logger. Loggers should also be enabled for all higher log levels: :::code language="csharp" source="snippets/configuration/console-custom-logging/ColorConsoleLogger.cs" range="16-17"::: @@ -38,26 +38,29 @@ The `ILoggerProvider` object is responsible for creating logger instances. Maybe :::code language="csharp" source="snippets/configuration/console-custom-logging/ColorConsoleLoggerProvider.cs"::: -In the preceding code, creates a single instance of the `ColorConsoleLogger` per category name and stores it in the [`ConcurrentDictionary`](/dotnet/api/system.collections.concurrent.concurrentdictionary-2). +In the preceding code, creates a single instance of the `ColorConsoleLogger` per category name and stores it in the [`ConcurrentDictionary`](/dotnet/api/system.collections.concurrent.concurrentdictionary-2). Additionally, the interface is required to update changes to the underlying `ColorConsoleLoggerConfiguration` object. ## Usage and registration of the custom logger +By convention, registering services for dependency injection happens as part of the startup routine of an application. The registration occurs in the `Program` class, or could be delegated to a `Startup` class. In this example, you'll register directly from the _Program.cs_. + To add the custom logging provider and corresponding logger, add an with from the : -:::code language="csharp" source="snippets/configuration/console-custom-logging/Program.cs" range="23-39"::: +:::code language="csharp" source="snippets/configuration/console-custom-logging/Program.cs" highlight="23-33"::: The `ILoggingBuilder` creates one or more `ILogger` instances. The `ILogger` instances are used by the framework to log the information. -For the preceding code, provide at least one extension method for the `ILoggerFactory`: +By convention, extension methods on `ILoggingBuilder` are used to register the custom provider: :::code language="csharp" source="snippets/configuration/console-custom-logging/Extensions/ColorConsoleLoggerExtensions.cs"::: -Running this simple application will render similar to the following console window: +Running this simple application will render color output to the console window similar to the following image: :::image type="content" source="media/color-console-logger.png" alt-text="Color console logger sample output"::: ## See also -- [Logging in .NET](logging.md). -- [Logging providers in .NET](logging-providers.md). -- [High-performance logging in .NET](high-performance-logging.md). +- [Logging in .NET](logging.md) +- [Logging providers in .NET](logging-providers.md) +- [Dependency injection in .NET](dependency-injection.md) +- [High-performance logging in .NET](high-performance-logging.md) diff --git a/docs/core/extensions/dependency-injection-usage.md b/docs/core/extensions/dependency-injection-usage.md index f203cf3a5a5d2..54bcf053bdf47 100644 --- a/docs/core/extensions/dependency-injection-usage.md +++ b/docs/core/extensions/dependency-injection-usage.md @@ -3,7 +3,7 @@ title: Use dependency injection in .NET description: Learn how to use dependency injection in your .NET applications. author: IEvangelist ms.author: dapine -ms.date: 11/13/2020 +ms.date: 04/12/2021 ms.topic: tutorial no-loc: [Transient, Scoped, Singleton, Example] --- @@ -80,10 +80,10 @@ Update *Program.cs* with the following code: :::code language="csharp" source="snippets/configuration/console-di/Program.cs" range="1-18,35-60" highlight="22-26"::: -> Each `services.Add{SERVICE_NAME}` extension method adds, and potentially configures, services. We recommended that apps follow this convention. Place extension methods in the namespace to encapsulate groups of service registrations. Including the namespace portion `Microsoft.Extensions.DependencyInjection` for DI extension methods also: -> -> - Allows them to be displayed in [IntelliSense](/visualstudio/ide/using-intellisense) without adding additional `using` blocks. -> - Prevents excessive `using` statements in the `Program` or `Startup` classes where these extension methods are typically called. +Each `services.Add{SERVICE_NAME}` extension method adds (and potentially configures) services. We recommended that apps follow this convention. Place extension methods in the namespace to encapsulate groups of service registrations. Including the namespace portion `Microsoft.Extensions.DependencyInjection` for DI extension methods also: + +- Allows them to be displayed in [IntelliSense](/visualstudio/ide/using-intellisense) without adding additional `using` blocks. +- Prevents excessive `using` statements in the `Program` or `Startup` classes where these extension methods are typically called. The app: diff --git a/docs/core/extensions/dependency-injection.md b/docs/core/extensions/dependency-injection.md index 9dffd5b13c446..7782dcf521f7f 100644 --- a/docs/core/extensions/dependency-injection.md +++ b/docs/core/extensions/dependency-injection.md @@ -3,7 +3,7 @@ title: Dependency injection in .NET description: Learn how .NET implements dependency injection and how to use it. author: IEvangelist ms.author: dapine -ms.date: 10/28/2020 +ms.date: 04/12/2021 ms.topic: overview --- @@ -132,16 +132,17 @@ The `ConfigureServices` method registers services that the app uses, including p The following table lists a small sample of these framework-registered services: -| Service Type | Lifetime | -|------------------------------------------------------------------------------------|-----------| -| | Singleton | -| | Singleton | -| | Singleton | -| | Singleton | -| | Transient | -| | Singleton | -| | Singleton | -| | Singleton | +| Service Type | Lifetime | +|-----------------------------------------------------------------------------------------------|-----------| +| | Singleton | +| | Singleton | +| | Singleton | +| | Singleton | +| | Singleton | +| | Transient | +| | Singleton | +| | Singleton | +| | Singleton | ## Service lifetimes @@ -188,9 +189,6 @@ Register singleton services with is disposed on application shutdown. Because memory is not released until the app is shut down, consider memory use with a singleton service. -> [!WARNING] -> Do ***not*** resolve a scoped service from a singleton. It may cause the service to have incorrect state when processing subsequent requests. It's fine to resolve a singleton service from a scoped or transient service. - ## Service registration methods The framework provides service registration extension methods that are useful in specific scenarios: @@ -307,6 +305,23 @@ The root service provider is created when is always registered as a singleton, but the can vary based on the lifetime of the containing class. For example, if you resolve services from a scope, and any of those services take an , it'll be a scoped instance. + +To achieve scoping services within implementations of , such as the , do *not* inject the service dependencies via constructor injection. Instead, inject , create a scope, then resolve dependencies from the scope to use the appropriate service lifetime. + +:::code language="csharp" source="snippets/configuration/worker-scope/Worker.cs" highlight="13,15-16,22"::: + +In the preceding code, while the app is running, the background service: + +- Depends on the . +- Creates an for resolving additional services. +- Resolves scoped services for consumption. +- Works on processing objects and then relaying them, and finally marks them as processed. + +From the sample source code, you can see how implementations of can benefit from scoped service lifetimes. + ## See also - [Use dependency injection in .NET](dependency-injection-usage.md) diff --git a/docs/core/extensions/includes/file-new-worker.md b/docs/core/extensions/includes/file-new-worker.md new file mode 100644 index 0000000000000..63d9cd3f42092 --- /dev/null +++ b/docs/core/extensions/includes/file-new-worker.md @@ -0,0 +1,19 @@ +--- +author: IEvangelist +ms.author: dapine +ms.date: 05/25/2021 +ms.topic: include +--- + +## Create a new project + +To create a new Worker Service project with Visual Studio, you'd select **File** > **New** > **Project...**. From the **Create a new project** dialog search for "Worker Service", and select Worker Service template. If you'd rather use the .NET CLI, open your favorite .NET CLI tool in a working directory. Run the `dotnet new` command, and replace the `` with your desired project name. + +```dotnetcli +dotnet new worker --name +``` + +For more information on the .NET CLI new worker service project command, see [dotnet new worker](../../tools/dotnet-new-sdk-templates.md#web-others). + +> [!TIP] +> If you're using Visual Studio Code, you can run .NET CLI commands from the integrated terminal. For more information, see [Visual Studio Code: Integrated Terminal](https://code.visualstudio.com/docs/editor/integrated-terminal). diff --git a/docs/core/extensions/includes/run-app.md b/docs/core/extensions/includes/run-app.md new file mode 100644 index 0000000000000..b596c9c570761 --- /dev/null +++ b/docs/core/extensions/includes/run-app.md @@ -0,0 +1,14 @@ +--- +author: IEvangelist +ms.author: dapine +ms.date: 05/25/2021 +ms.topic: include +--- + +To run the application from Visual Studio, select F5 or select the **Debug** > **Start Debugging** menu option. If you're using the .NET CLI, run the `dotnet run` command from the working directory: + +```dotnetcli +dotnet run +``` + +For more information on the .NET CLI run command, see [dotnet run](../../tools/dotnet-run.md). diff --git a/docs/core/extensions/includes/stop-app.md b/docs/core/extensions/includes/stop-app.md new file mode 100644 index 0000000000000..49cd2b9079e76 --- /dev/null +++ b/docs/core/extensions/includes/stop-app.md @@ -0,0 +1,8 @@ +--- +author: IEvangelist +ms.author: dapine +ms.date: 05/25/2021 +ms.topic: include +--- + +If running the application from within Visual Studio, select **Debug** > **Stop Debugging...**. Alternatively, select Ctrl + C from the console window to signal cancellation. diff --git a/docs/core/extensions/logger-message-generator.md b/docs/core/extensions/logger-message-generator.md new file mode 100644 index 0000000000000..c8d53aba97897 --- /dev/null +++ b/docs/core/extensions/logger-message-generator.md @@ -0,0 +1,393 @@ +--- +title: Compile-time logging source generation +description: Learn how to use the LoggerMessageAttribute and compile-time source generation for logging in .NET. +author: maryamariyan +ms.author: maariyan +ms.date: 05/18/2021 +--- + +# Compile-time logging source generation + +> [!NOTE] +> The APIs in this article are new. They'll be generally available as part of .NET 6, but are subject to change. +> +> - When using .NET 6 Preview 4, the APIs are part of the [Microsoft.Extensions.Logging](https://www.nuget.org/packages/microsoft.extensions.logging) package. +> - When using [.NET nightly builds](https://github.com/dotnet/runtime/blob/main/docs/project/dogfooding.md), the APIs are part of the [Microsoft.Extensions.Logging.Abstractions](https://www.nuget.org/packages/microsoft.extensions.logging.abstractions) package. + +.NET 6 introduces the `LoggerMessageAttribute` type. This attribute is part of the `Microsoft.Extensions.Logging` namespace, and when used, it source-generates performant logging APIs. The source-generation logging support is designed to deliver a highly usable and highly performant logging solution for modern .NET applications. The auto-generated source code relies on the interface in conjunction with functionality. + +The source generator is triggered when `LoggerMessageAttribute` is used on `partial` logging methods. When triggered, it is either able to autogenerate the implementation of the `partial` methods it's decorating, or produce compile-time diagnostics with hints about proper usage. The compile-time logging solution is typically considerably faster at run time than existing logging approaches. It achieves this by eliminating boxing, temporary allocations, and copies to the maximum extent possible. + +## Basic usage + +To use the `LoggerMessageAttribute`, the consuming class and method need to be `partial`. The code generator is triggered at compile time, and generates an implementation of the `partial` method. + +```csharp +public static partial class Log +{ + [LoggerMessage( + EventId = 0, + Level = LogLevel.Critical, + Message = "Could not open socket to `{hostName}`")] + public static partial void CouldNotOpenSocket( + ILogger logger, string hostName); +} +``` + +In the preceding example, the logging method is `static` and the log level is specified in the attribute definition. When using the attribute in a static context, the `ILogger` instance is required as a parameter. You may choose to use the attribute in a non-static context as well. Consider the following example where the logging method is declared as an instance method. In this context, the logging method gets the logger by accessing an `ILogger` field in the containing class. + +```csharp +public partial class InstanceLoggingExample +{ + private readonly ILogger _logger; + + public InstanceLoggingExample(ILogger logger) + { + _logger = logger; + } + + [LoggerMessage( + EventId = 0, + Level = LogLevel.Critical, + Message = "Could not open socket to `{hostName}`")] + public partial void CouldNotOpenSocket(string hostName); +} +``` + +Sometimes, the log level needs to be dynamic rather than statically built into the code. You can do this by omitting the log level from the attribute and instead requiring it as a parameter to the logging method. + +```csharp +public static partial class Log +{ + [LoggerMessage( + EventId = 0, + Message = "Could not open socket to `{hostName}`")] + public static partial void CouldNotOpenSocket( + ILogger logger, + LogLevel level, /* Dynamic log level as parameter, rather than defined in attribute. */ + string hostName); +} +``` + +You can omit the logging message and will be provided for the message. The state will contain the arguments, formatted as key-value pairs. + +```csharp +using System.Text.Json; +using Microsoft.Extensions.Logging; + +ILogger logger = LoggerFactory.Create( + builder => + builder.AddJsonConsole( + options => + options.JsonWriterOptions = new JsonWriterOptions() + { + Indented = true + })) + .CreateLogger(); + +logger.CustomLogEvent(LogLevel.Information, "Liana", "California"); + +public static partial class SampleObject +{ + [LoggerMessage(EventId = 23)] + public static partial void CustomLogEvent( + this ILogger logger, LogLevel logLevel, + string name, string state); +} +``` + +Consider the example logging output when using the `JsonConsole` formatter. + +```json +{ + "EventId": 23, + "LogLevel": "Information", + "Category": "ConsoleApp.SampleObject", + "Message": "", + "State": { + "Message": "", + "name": "Liana", + "state": "California", + "{OriginalFormat}": "" + } +} +``` + +## Log method constraints + +When using the `LoggerMessageAttribute` on logging methods, there are some constraints that must be followed: + +- Logging methods must be `static`, `partial`, and return `void`. +- Logging method names must *not* start with an underscore. +- Parameter names of logging methods must *not* start with an underscore. +- Logging methods may *not* be defined in a nested type. +- Logging methods *cannot* be generic. + +The code-generation model depends on code being compiled with a modern C# compiler, version 9 or later. The C# 9.0 compiler became available with .NET 5. To upgrade to a modern C# compiler, edit your project file to target C# 9.0. + +```xml + + 9.0 + +``` + +For more information, see [C# language versioning](../../csharp/language-reference/configure-language-version.md). + +## Log method anatomy + +The signature accepts the and optionally an , as shown below. + +```csharp +public interface ILogger +{ + void Log( + Microsoft.Extensions.Logging.LogLevel logLevel, + Microsoft.Extensions.Logging.EventId eventId, + TState state, + System.Exception? exception, + Func formatter); +} +``` + +As a general rule, the first instance of `ILogger`, `LogLevel`, and `Exception` are treated specially in the log method signature of the source generator. Subsequent instances are treated like normal parameters to the message template: + +```csharp +// This is a valid attribute usage +[LoggerMessage( + EventId = 110, Level = LogLevel.Debug, Message = "M1 {ex3} {ex2}")] +public static partial void ValidLogMethod( + ILogger logger, + Exception ex, + Exception ex2, + Exception ex3); + +// This causes a warning +[LoggerMessage( + EventId = 0, Level = LogLevel.Debug, Message = "M1 {ex} {ex2}")] +public static partial void WarningLogMethod( + ILogger logger, + Exception ex, + Exception ex2); +``` + +> [!IMPORTANT] +> The warnings emitted provide details as to the correct usage of the `LoggerMessageAttribute`. In the preceding example, the `WarningLogMethod` will report a `DiagnosticSeverity.Warning` of `SYSLIB0025`. +> +> ```console +> Don't include a template for ex in the logging message since it is implicitly taken care of. +> ``` + +### Case-insensitive template name support + +The generator does case-insensitive comparison between items in message template and argument names in the log message. This means that when the `ILogger` enumerates the state, the argument is picked up by message template, which can make the logs nicer to consume: + +```csharp +public partial class LoggingExample +{ + private readonly ILogger _logger; + + public LoggingExample(ILogger logger) + { + _logger = logger; + } + + [LoggerMessage( + EventId = 10, + Level = LogLevel.Information, + Message = "Welcome to {City} {Province}!")] + public partial void LogMethodSupportsPascalCasingOfNames( + string city, string province); + + public void TestLogging() + { + LogMethodSupportsPascalCasingOfNames("Vancouver", "BC"); + } +} +``` + +Consider the example logging output when using the `JsonConsole` formatter. + +```json +{ + "EventId": 13, + "LogLevel": "Information", + "Category": "LoggingExample", + "Message": "Welcome to Vancouver BC!", + "State": { + "Message": "Welcome to Vancouver BC!", + "City": "Vancouver", + "Province": "BC", + "{OriginalFormat}": "Welcome to {City} {Province}!" + } +} +``` + +### Indeterminate parameter order + +There are no constraints on the ordering of log method parameters. A developer could define the `ILogger` as the last parameter, although it may a appear a bit awkward. + +```csharp +[LoggerMessage( + EventId = 110, + Level = LogLevel.Debug, + Message = "M1 {ex3} {ex2}")] +static partial void LogMethod( + Exception ex, + Exception ex2, + Exception ex3, + ILogger logger); +``` + +> [!TIP] +> The order of the parameters on a log method is *not* required to correspond to the order of the template placeholders. Instead, the placeholder names in the template are expected to match the parameters. Consider the following `JsonConsole` output and the order of the errors. +> +> ```json +> { +> "EventId": 110, +> "LogLevel": "Debug", +> "Category": "ConsoleApp.Program", +> "Message": "M1 System.Exception: Third time's the charm. System.Exception: This is the second error.", +> "State": { +> "Message": "M1 System.Exception: Third time's the charm. System.Exception: This is the second error.", +> "ex2": "System.Exception: This is the second error.", +> "ex3": "System.Exception: Third time's the charm.", +> "{OriginalFormat}": "M1 {ex3} {ex2}" +> } +> } +> ``` + +## Additional logging examples + +The samples below show how to: + +- `LogWithCustomEventName`: Retrieve event name via `LoggerMessage` attribute. +- `LogWithDynamicLogLevel`: Set log level dynamically, to allow log level to be set based on configuration input. +- `UsingFormatSpecifier`: Use format specifiers to format logging parameters. + +```csharp +public partial class LoggingSample +{ + private readonly ILogger _logger; + + public LoggingSample(ILogger logger) + { + _logger = logger; + } + + [LoggerMessage( + EventId = 20, + Level = LogLevel.Critical, + Message = "Value is {value:E}")] + public static partial void UsingFormatSpecifier( + ILogger logger, double value); + + [LoggerMessage( + EventId = 9, + Level = LogLevel.Trace, + Message = "Fixed message", + EventName = "CustomEventName")] + public partial void LogWithCustomEventName(); + + [LoggerMessage( + EventId = 10, + Message = "Welcome to {city} {province}!")] + public partial void LogWithDynamicLogLevel( + string city, LogLevel level, string province); + + public void TestLogging() + { + LogWithCustomEventName(); + + LogWithDynamicLogLevel("Vancouver", LogLevel.Warning, "BC"); + LogWithDynamicLogLevel("Vancouver", LogLevel.Information, "BC"); + + UsingFormatSpecifier(logger, 12345.6789); + } +} +``` + +Consider the example logging output when using the `SimpleConsole` formatter. + +```console +trce: LoggingExample[9] + Fixed message +warn: LoggingExample[10] + Welcome to Vancouver BC! +info: LoggingExample[10] + Welcome to Vancouver BC! +crit: LoggingExample[20] + Value is 1.234568E+004 +``` + +Consider the example logging output when using the `JsonConsole` formatter. + +```json +{ + "EventId": 9, + "LogLevel": "Trace", + "Category": "LoggingExample", + "Message": "Fixed message", + "State": { + "Message": "Fixed message", + "{OriginalFormat}": "Fixed message" + } +} +{ + "EventId": 10, + "LogLevel": "Warning", + "Category": "LoggingExample", + "Message": "Welcome to Vancouver BC!", + "State": { + "Message": "Welcome to Vancouver BC!", + "city": "Vancouver", + "province": "BC", + "{OriginalFormat}": "Welcome to {city} {province}!" + } +} +{ + "EventId": 10, + "LogLevel": "Information", + "Category": "LoggingExample", + "Message": "Welcome to Vancouver BC!", + "State": { + "Message": "Welcome to Vancouver BC!", + "city": "Vancouver", + "province": "BC", + "{OriginalFormat}": "Welcome to {city} {province}!" + } +} +{ + "EventId": 20, + "LogLevel": "Critical", + "Category": "LoggingExample", + "Message": "Value is 1.234568E+004", + "State": { + "Message": "Value is 1.234568E+004", + "value": 12345.6789, + "{OriginalFormat}": "Value is {value:E}" + } +} +``` + +## Summary + +With the advent of C# source generators, writing highly performant logging APIs is much easier. Using the source generator approach has several key benefits: + +- Allows the logging structure to be preserved and enables the exact format syntax required by [Message Templates](https://messagetemplates.org). +- Allows supplying alternative names for the template placeholders and using format specifiers. +- Allows the passing of all original data as-is, without any complication around how it's stored prior to something being done with it (other than creating a `string`). +- Provides logging-specific diagnostics, emits warnings for duplicate event IDs. + +Additionally, there are benefits over manually using : + +- Shorter and simpler syntax: Declarative attribute usage rather than coding boilerplate. +- Guided developer experience: The generator gives warnings to help developers do the right thing. +- Support for an arbitrary number of logging parameters. `LoggerMessage.Define` supports a maximum of six. +- Support for dynamic log level. This is not possible with `LoggerMessage.Define` alone. + +## See also + +- [Logging in .NET](logging.md) +- [High-performance logging in .NET](high-performance-logging.md) +- [Console log formatting](console-log-formatter.md) +- [NuGet: Microsoft.Extensions.Logging.Abstractions](https://www.nuget.org/packages/microsoft.extensions.logging.abstractions) diff --git a/docs/core/extensions/media/event-properties.png b/docs/core/extensions/media/event-properties.png new file mode 100644 index 0000000000000..5059b659c9d38 Binary files /dev/null and b/docs/core/extensions/media/event-properties.png differ diff --git a/docs/core/extensions/media/launch-profiles-cmd-line-args.png b/docs/core/extensions/media/launch-profiles-cmd-line-args.png new file mode 100644 index 0000000000000..ff899111f9249 Binary files /dev/null and b/docs/core/extensions/media/launch-profiles-cmd-line-args.png differ diff --git a/docs/core/extensions/media/launch-profiles-env-vars.png b/docs/core/extensions/media/launch-profiles-env-vars.png new file mode 100644 index 0000000000000..c87c7b0f98f7d Binary files /dev/null and b/docs/core/extensions/media/launch-profiles-env-vars.png differ diff --git a/docs/core/extensions/media/profile-settings.png b/docs/core/extensions/media/profile-settings.png new file mode 100644 index 0000000000000..c83cf729836eb Binary files /dev/null and b/docs/core/extensions/media/profile-settings.png differ diff --git a/docs/core/extensions/media/publish-dialog.png b/docs/core/extensions/media/publish-dialog.png new file mode 100644 index 0000000000000..1fed495993b28 Binary files /dev/null and b/docs/core/extensions/media/publish-dialog.png differ diff --git a/docs/core/extensions/media/windows-service.png b/docs/core/extensions/media/windows-service.png new file mode 100644 index 0000000000000..cdd809a115fb7 Binary files /dev/null and b/docs/core/extensions/media/windows-service.png differ diff --git a/docs/core/extensions/options-library-authors.md b/docs/core/extensions/options-library-authors.md index 53d3d925cdcbc..4121824aa5250 100644 --- a/docs/core/extensions/options-library-authors.md +++ b/docs/core/extensions/options-library-authors.md @@ -3,7 +3,7 @@ title: Options pattern guidance for .NET library authors author: IEvangelist description: Learn how to expose the options pattern as a library author in .NET. ms.author: dapine -ms.date: 01/28/2021 +ms.date: 04/12/2021 --- # Options pattern guidance for .NET library authors @@ -46,13 +46,13 @@ In the preceding code, the `AddMyLibraryService`: When you author a library that exposes many options to consumers, you may want to consider requiring an `IConfiguration` parameter extension method. The expected `IConfiguration` instance should be scoped to a named section of the configuration by using the function. -:::code language="csharp" source="snippets/configuration/options-configparam/ServiceCollectionExtensions.cs" highlight="10,12-16"::: +:::code language="csharp" source="snippets/configuration/options-configparam/ServiceCollectionExtensions.cs" highlight="10,12-14"::: In the preceding code, the `AddMyLibraryService`: - Extends an instance of - Defines an parameter `namedConfigurationSection` -- Calls passing an options instance that the configuration binds to +- Calls passing the generic type parameter of `LibraryOptions` and the `namedConfigurationSection` instance to configure Consumers in this pattern provide the scoped `IConfiguration` instance of the named section: diff --git a/docs/core/extensions/options.md b/docs/core/extensions/options.md index 6aa2d26cc1bf9..4d3395b338d9d 100644 --- a/docs/core/extensions/options.md +++ b/docs/core/extensions/options.md @@ -3,7 +3,7 @@ title: Options pattern in .NET author: IEvangelist description: Learn how to use the options pattern to represent groups of related settings in .NET apps. ms.author: dapine -ms.date: 02/18/2021 +ms.date: 05/04/2021 --- # Options pattern in .NET @@ -153,6 +153,11 @@ The following example uses [!TIP] +> Some file systems, such as Docker containers and network shares, may not reliably send change notifications. When using the interface in these environments, set the `DOTNET_USE_POLLING_FILE_WATCHER` environment variable to `1` or `true` to poll the file system for changes. The interval at which changes are polled is every four seconds and is not configurable. +> +> For more information on Docker containers, see [Containerize a .NET app](../docker/build-container.md). + ## Named options support using IConfigureNamedOptions Named options: diff --git a/docs/core/extensions/queue-service.md b/docs/core/extensions/queue-service.md new file mode 100644 index 0000000000000..39951458c3047 --- /dev/null +++ b/docs/core/extensions/queue-service.md @@ -0,0 +1,118 @@ +--- +title: Create a Queue Service +description: Learn how to create a queue service subclass of BackgroundService in .NET. +author: IEvangelist +ms.author: dapine +ms.date: 05/26/2021 +ms.topic: tutorial +--- + +# Create a Queue Service + +A queue service is a great example of a long-running service, where work items can be queued and worked on sequentially as previous work items are completed. Relying on the Worker Service template, you'll build out new functionality on top of the . + +In this tutorial, you learn how to: + +> [!div class="checklist"] +> +> - Create a queue service. +> - Delegate work to a task queue. +> - Register a console key-listener from events. + +## Prerequisites + +- The [.NET 5.0 SDK or later](https://dotnet.microsoft.com/download/dotnet) +- A .NET integrated development environment (IDE) + - Feel free to use [Visual Studio](https://visualstudio.microsoft.com) + + +[!INCLUDE [file-new-worker](includes/file-new-worker.md)] + +## Create queuing services + +You may be familiar with the functionality from the `System.Web.Hosting` namespace. To model a service that is inspired by this functionality, start by adding an `IBackgroundTaskQueue` interface to the project: + +:::code source="snippets/workers/queue-service/IBackgroundTaskQueue.cs"::: + +There are two methods, one which exposes queuing functionality and the other that dequeues previously queued work items. A *work item* is a `Func`. Next, add the default implementation to the project. + +:::code source="snippets/workers/queue-service/DefaultBackgroundTaskQueue.cs"::: + +The preceding implementation relies on a as a queue. The is called with an explicit capacity. Capacity should be set based on the expected application load and number of concurrent threads accessing the queue. will cause calls to to return a task, which completes only when space becomes available. This leads to backpressure, in case too many publishers/calls start accumulating. + +## Rewrite the Worker class + +In the following `QueueHostedService` example: + +- The `ProcessTaskQueueAsync` method returns a in `ExecuteAsync`. +- Background tasks in the queue are dequeued and executed in `ProcessTaskQueueAsync`. +- Work items are awaited before the service stops in `StopAsync`. + +Replace the existing `Worker` class with the following C# code, and rename the file to *QueueHostedService.cs*. + +:::code source="snippets/workers/queue-service/QueuedHostedService.cs" highlight="35-36,38"::: + +A `MonitorLoop` service handles enqueuing tasks for the hosted service whenever the `w` key is selected on an input device: + +- The `IBackgroundTaskQueue` is injected into the `MonitorLoop` service. +- `IBackgroundTaskQueue.QueueBackgroundWorkItemAsync` is called to enqueue a work item. +- The work item simulates a long-running background task: + - Three 5-second delays are executed . + - A `try-catch` statement traps if the task is cancelled. + +:::code source="snippets/workers/queue-service/MonitorLoop.cs" highlight="11,16,41"::: + +Replace the existing `Program` contents with the following C# code: + +:::code source="snippets/workers/queue-service/Program.cs" highlight="8-18"::: + +The services are registered in `IHostBuilder.ConfigureServices` (*Program.cs*). The hosted service is registered with the `AddHostedService` extension method. `MonitorLoop` is started in *Program.cs* top-level statement: + +:::code source="snippets/workers/queue-service/Program.cs" range="22-23"::: + +For more information on registering services, see [Dependency injection in .NET](dependency-injection.md). + +## Verify service functionality + +[!INCLUDE [run-app](includes/run-app.md)] + +When prompted enter the `w` (or `W`) at least once to queue an emulated work item. You will see output similar to the following: + +```Output +info: App.QueueService.MonitorLoop[0] + MonitorAsync loop is starting. +info: App.QueueService.QueuedHostedService[0] + QueuedHostedService is running. + + Tap W to add a work item to the background queue. + +info: Microsoft.Hosting.Lifetime[0] + Application started. Press Ctrl+C to shut down. +info: Microsoft.Hosting.Lifetime[0] + Hosting environment: Development +info: Microsoft.Hosting.Lifetime[0] + Content root path: .\queue-service +winfo: App.QueueService.MonitorLoop[0] + Queued work item 8453f845-ea4a-4bcb-b26e-c76c0d89303e is starting. +info: App.QueueService.MonitorLoop[0] + Queued work item 8453f845-ea4a-4bcb-b26e-c76c0d89303e is running. 1/3 +info: App.QueueService.MonitorLoop[0] + Queued work item 8453f845-ea4a-4bcb-b26e-c76c0d89303e is running. 2/3 +info: App.QueueService.MonitorLoop[0] + Queued work item 8453f845-ea4a-4bcb-b26e-c76c0d89303e is running. 3/3 +info: App.QueueService.MonitorLoop[0] + Queued Background Task 8453f845-ea4a-4bcb-b26e-c76c0d89303e is complete. +info: Microsoft.Hosting.Lifetime[0] + Application is shutting down... +info: App.QueueService.QueuedHostedService[0] + QueuedHostedService is stopping. +``` + +[!INCLUDE [stop-app](includes/stop-app.md)] + +## See also + +- [Worker Services in .NET](workers.md) +- [Use scoped services within a `BackgroundService`](scoped-service.md) +- [Create a Windows Service using `BackgroundService`](windows-service.md) +- [Implement the `IHostedService` interface](timer-service.md) diff --git a/docs/core/extensions/scoped-service.md b/docs/core/extensions/scoped-service.md new file mode 100644 index 0000000000000..3903ff6514c8e --- /dev/null +++ b/docs/core/extensions/scoped-service.md @@ -0,0 +1,100 @@ +--- +title: Use scoped services within a BackgroundService +description: Learn how to use scoped services within a BackgroundService in .NET. +author: IEvangelist +ms.author: dapine +ms.date: 05/26/2021 +ms.topic: tutorial +--- + +# Use scoped services within a `BackgroundService` + +When you register implementations of using any of the extension methods - the service is registered as a singleton. There may be scenarios where you'd like to rely on a scoped service. For more information, see [Dependency injection in .NET: Service lifetimes](dependency-injection.md#service-lifetimes). + +In this tutorial, you learn how to: + +> [!div class="checklist"] +> +> - Resolve scoped dependencies in a singleton . +> - Delegate work to a scoped service. +> - Implement an `override` of . + +## Prerequisites + +- The [.NET 5.0 SDK or later](https://dotnet.microsoft.com/download/dotnet) +- A .NET integrated development environment (IDE) + - Feel free to use [Visual Studio](https://visualstudio.microsoft.com) + + +[!INCLUDE [file-new-worker](includes/file-new-worker.md)] + +## Create scoped services + +To use [scoped services](dependency-injection.md#scoped) within a `BackgroundService`, create a scope. No scope is created for a hosted service by default. The scoped background service contains the background task's logic. + +:::code source="snippets/workers/scoped-service/IScopedProcessingService.cs"::: + +The preceding interface defines a single `DoWorkAsync` method. To define the default implementation: + +- The service is asynchronous. The `DoWorkAsync` method returns a `Task`. For demonstration purposes, a delay of ten seconds is awaited in the `DoWorkAsync` method. +- An is injected into the service.: + +:::code source="snippets/workers/scoped-service/DefaultScopedProcessingService.cs"::: + +The hosted service creates a scope to resolve the scoped background service to call its `DoWorkAsync` method. `DoWorkAsync` returns a `Task`, which is awaited in `ExecuteAsync`: + +## Rewrite the Worker class + +Replace the existing `Worker` class with the following C# code, and rename the file to *ScopedBackgroundService.cs*: + +:::code source="snippets/workers/scoped-service/ScopedBackgroundService.cs" highlight="33-39"::: + +In the preceding code, an explicit scope is created and the `IScopedProcessingService` implementation is resolved from the dependency injection service provider. The resolved service instance is scoped, and it's `DoWorkAsync` method is awaited. + +Replace the template *Program.cs* file contents with the following C# code: + +:::code source="snippets/workers/scoped-service/Program.cs" highlight="8-9"::: + +The services are registered in `IHostBuilder.ConfigureServices` (*Program.cs*). The hosted service is registered with the `AddHostedService` extension method. + +For more information on registering services, see [Dependency injection in .NET](dependency-injection.md). + +## Verify service functionality + +[!INCLUDE [run-app](includes/run-app.md)] + +Let the application run for a bit to generate several execution count increments. You will see output similar to the following: + +```Output +info: App.ScopedService.ScopedBackgroundService[0] + ScopedBackgroundService is running. +info: App.ScopedService.ScopedBackgroundService[0] + ScopedBackgroundService is working. +info: App.ScopedService.DefaultScopedProcessingService[0] + DefaultScopedProcessingService working, execution count: 1 +info: Microsoft.Hosting.Lifetime[0] + Application started. Press Ctrl+C to shut down. +info: Microsoft.Hosting.Lifetime[0] + Hosting environment: Development +info: Microsoft.Hosting.Lifetime[0] + Content root path: .\scoped-service +info: App.ScopedService.DefaultScopedProcessingService[0] + DefaultScopedProcessingService working, execution count: 2 +info: App.ScopedService.DefaultScopedProcessingService[0] + DefaultScopedProcessingService working, execution count: 3 +info: App.ScopedService.DefaultScopedProcessingService[0] + DefaultScopedProcessingService working, execution count: 4 +info: Microsoft.Hosting.Lifetime[0] + Application is shutting down... +info: App.ScopedService.ScopedBackgroundService[0] + ScopedBackgroundService is stopping. +``` + +[!INCLUDE [stop-app](includes/stop-app.md)] + +## See also + +- [Worker Services in .NET](workers.md) +- [Create a Queue Service](queue-service.md) +- [Create a Windows Service using `BackgroundService`](windows-service.md) +- [Implement the `IHostedService` interface](timer-service.md) diff --git a/docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLogger.cs b/docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLogger.cs index 332674f7c9cd2..4f9566b769681 100644 --- a/docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLogger.cs +++ b/docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLogger.cs @@ -14,7 +14,7 @@ public ColorConsoleLogger( public IDisposable BeginScope(TState state) => default; public bool IsEnabled(LogLevel logLevel) => - logLevel == _config.LogLevel; + _config.LogLevels.ContainsKey(logLevel); public void Log( LogLevel logLevel, @@ -32,7 +32,7 @@ public void Log( { ConsoleColor originalColor = Console.ForegroundColor; - Console.ForegroundColor = _config.Color; + Console.ForegroundColor = _config.LogLevels[logLevel]; Console.WriteLine($"[{eventId.Id,2}: {logLevel,-12}]"); Console.ForegroundColor = originalColor; diff --git a/docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLoggerConfiguration.cs b/docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLoggerConfiguration.cs index ee572ee880e2c..5e4175666f961 100644 --- a/docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLoggerConfiguration.cs +++ b/docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLoggerConfiguration.cs @@ -1,9 +1,13 @@ using System; +using System.Collections.Generic; using Microsoft.Extensions.Logging; public class ColorConsoleLoggerConfiguration { public int EventId { get; set; } - public LogLevel LogLevel { get; set; } = LogLevel.Information; - public ConsoleColor Color { get; set; } = ConsoleColor.Green; + + public Dictionary LogLevels { get; set; } = new() + { + [LogLevel.Information] = ConsoleColor.Green + }; } diff --git a/docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLoggerProvider.cs b/docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLoggerProvider.cs index 52139f4cae86d..859aa89c98661 100644 --- a/docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLoggerProvider.cs +++ b/docs/core/extensions/snippets/configuration/console-custom-logging/ColorConsoleLoggerProvider.cs @@ -1,17 +1,27 @@ -using System.Collections.Concurrent; +using System; +using System.Collections.Concurrent; using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Options; public sealed class ColorConsoleLoggerProvider : ILoggerProvider { - private readonly ColorConsoleLoggerConfiguration _config; - private readonly ConcurrentDictionary _loggers = - new ConcurrentDictionary(); + private readonly IDisposable _onChangeToken; + private ColorConsoleLoggerConfiguration _currentConfig; + private readonly ConcurrentDictionary _loggers = new(); - public ColorConsoleLoggerProvider(ColorConsoleLoggerConfiguration config) => - _config = config; + public ColorConsoleLoggerProvider( + IOptionsMonitor config) + { + _currentConfig = config.CurrentValue; + _onChangeToken = config.OnChange(updatedConfig => _currentConfig = updatedConfig); + } public ILogger CreateLogger(string categoryName) => - _loggers.GetOrAdd(categoryName, name => new ColorConsoleLogger(name, _config)); + _loggers.GetOrAdd(categoryName, name => new ColorConsoleLogger(name, _currentConfig)); - public void Dispose() => _loggers.Clear(); + public void Dispose() + { + _loggers.Clear(); + _onChangeToken.Dispose(); + } } diff --git a/docs/core/extensions/snippets/configuration/console-custom-logging/Extensions/ColorConsoleLoggerExtensions.cs b/docs/core/extensions/snippets/configuration/console-custom-logging/Extensions/ColorConsoleLoggerExtensions.cs index e5a00312b469a..bf77f45047963 100644 --- a/docs/core/extensions/snippets/configuration/console-custom-logging/Extensions/ColorConsoleLoggerExtensions.cs +++ b/docs/core/extensions/snippets/configuration/console-custom-logging/Extensions/ColorConsoleLoggerExtensions.cs @@ -1,28 +1,32 @@ using System; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.DependencyInjection.Extensions; using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Logging.Configuration; public static class ColorConsoleLoggerExtensions { public static ILoggingBuilder AddColorConsoleLogger( - this ILoggingBuilder builder) => - builder.AddColorConsoleLogger( - new ColorConsoleLoggerConfiguration()); - - public static ILoggingBuilder AddColorConsoleLogger( - this ILoggingBuilder builder, - Action configure) + this ILoggingBuilder builder) { - var config = new ColorConsoleLoggerConfiguration(); - configure(config); + builder.AddConfiguration(); + + builder.Services.TryAddEnumerable( + ServiceDescriptor.Singleton()); - return builder.AddColorConsoleLogger(config); + LoggerProviderOptions.RegisterProviderOptions + (builder.Services); + + return builder; } public static ILoggingBuilder AddColorConsoleLogger( this ILoggingBuilder builder, - ColorConsoleLoggerConfiguration config) + Action configure) { - builder.AddProvider(new ColorConsoleLoggerProvider(config)); + builder.AddColorConsoleLogger(); + builder.Services.Configure(configure); + return builder; } } diff --git a/docs/core/extensions/snippets/configuration/console-custom-logging/Program.cs b/docs/core/extensions/snippets/configuration/console-custom-logging/Program.cs index 8a2e6828304a2..59d914b52a84f 100644 --- a/docs/core/extensions/snippets/configuration/console-custom-logging/Program.cs +++ b/docs/core/extensions/snippets/configuration/console-custom-logging/Program.cs @@ -6,7 +6,7 @@ class Program { - static Task Main(string[] args) + static async Task Main(string[] args) { using IHost host = CreateHostBuilder(args).Build(); @@ -17,24 +17,18 @@ static Task Main(string[] args) logger.LogWarning(5, "Warning... that was odd."); logger.LogError(7, "Oops, there was an error."); - return host.RunAsync(); + await host.RunAsync(); } static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) .ConfigureLogging(builder => builder.ClearProviders() - .AddProvider( - new ColorConsoleLoggerProvider( - new ColorConsoleLoggerConfiguration - { - LogLevel = LogLevel.Error, - Color = ConsoleColor.Red - })) - .AddColorConsoleLogger() .AddColorConsoleLogger(configuration => { - configuration.LogLevel = LogLevel.Warning; - configuration.Color = ConsoleColor.DarkMagenta; + configuration.LogLevels.Add( + LogLevel.Warning, ConsoleColor.DarkMagenta); + configuration.LogLevels.Add( + LogLevel.Error, ConsoleColor.Red); })); } diff --git a/docs/core/extensions/snippets/configuration/console-di-disposable/Program.cs b/docs/core/extensions/snippets/configuration/console-di-disposable/Program.cs index d4124c1c6815b..53004dee4cb2f 100644 --- a/docs/core/extensions/snippets/configuration/console-di-disposable/Program.cs +++ b/docs/core/extensions/snippets/configuration/console-di-disposable/Program.cs @@ -7,7 +7,7 @@ namespace ConsoleDisposable.Example { class Program { - static Task Main(string[] args) + static async Task Main(string[] args) { using IHost host = CreateHostBuilder(args).Build(); @@ -17,7 +17,7 @@ static Task Main(string[] args) ExemplifyDisposableScoping(host.Services, "Scope 2"); Console.WriteLine(); - return host.RunAsync(); + await host.RunAsync(); } // Sample output: // Scope 1... diff --git a/docs/core/extensions/snippets/configuration/custom-provider/Extensions/ConfigurationBuilderExtensions.cs b/docs/core/extensions/snippets/configuration/custom-provider/Extensions/ConfigurationBuilderExtensions.cs index 1f9a0ad245331..a107f07d44c31 100644 --- a/docs/core/extensions/snippets/configuration/custom-provider/Extensions/ConfigurationBuilderExtensions.cs +++ b/docs/core/extensions/snippets/configuration/custom-provider/Extensions/ConfigurationBuilderExtensions.cs @@ -1,14 +1,17 @@ -using System; -using CustomProvider.Example.Providers; -using Microsoft.EntityFrameworkCore; +using CustomProvider.Example.Providers; namespace Microsoft.Extensions.Configuration { public static class ConfigurationBuilderExtensions { public static IConfigurationBuilder AddEntityConfiguration( - this IConfigurationBuilder builder, - Action optionsAction) => - builder.Add(new EntityConfigurationSource(optionsAction)); + this IConfigurationBuilder builder) + { + var tempConfig = builder.Build(); + var connectionString = + tempConfig.GetConnectionString("WidgetConnectionString"); + + return builder.Add(new EntityConfigurationSource(connectionString)); + } } } diff --git a/docs/core/extensions/snippets/configuration/custom-provider/Program.cs b/docs/core/extensions/snippets/configuration/custom-provider/Program.cs index 2096167b6a506..30998d342650b 100644 --- a/docs/core/extensions/snippets/configuration/custom-provider/Program.cs +++ b/docs/core/extensions/snippets/configuration/custom-provider/Program.cs @@ -1,9 +1,9 @@ using System; -using System.Linq; using System.Threading.Tasks; -using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Options; namespace CustomProvider.Example { @@ -13,29 +13,27 @@ static async Task Main(string[] args) { using IHost host = CreateHostBuilder(args).Build(); - // Application code should start here. + var options = host.Services.GetRequiredService>().Value; + Console.WriteLine($"DisplayLabel={options.DisplayLabel}"); + Console.WriteLine($"EndpointId={options.EndpointId}"); + Console.WriteLine($"WidgetRoute={options.WidgetRoute}"); await host.RunAsync(); } + // Sample output: + // WidgetRoute=api/widgets + // EndpointId=b3da3c4c-9c4e-4411-bc4d-609e2dcc5c67 + // DisplayLabel=Widgets Incorporated, LLC. static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) .ConfigureAppConfiguration((_, configuration) => { configuration.Sources.Clear(); - - configuration.AddEntityConfiguration( - options => options.UseInMemoryDatabase("InMemoryDb")); - - foreach ((string key, string value) in - configuration.Build().AsEnumerable().Where(t => t.Value is not null)) - { - Console.WriteLine($"{key}={value}"); - } - }); - // Sample output: - // WidgetRoute=api/widgets - // EndpointId=b3da3c4c-9c4e-4411-bc4d-609e2dcc5c67 - // DisplayLabel=Widgets Incorporated, LLC. + configuration.AddEntityConfiguration(); + }) + .ConfigureServices((context, services) => + services.Configure( + context.Configuration.GetSection("WidgetOptions"))); } } diff --git a/docs/core/extensions/snippets/configuration/custom-provider/Providers/EntityConfigurationContext.cs b/docs/core/extensions/snippets/configuration/custom-provider/Providers/EntityConfigurationContext.cs index a07de5698dac9..b05029331c164 100644 --- a/docs/core/extensions/snippets/configuration/custom-provider/Providers/EntityConfigurationContext.cs +++ b/docs/core/extensions/snippets/configuration/custom-provider/Providers/EntityConfigurationContext.cs @@ -5,11 +5,20 @@ namespace CustomProvider.Example.Providers { public class EntityConfigurationContext : DbContext { + private readonly string _connectionString; + public DbSet Settings { get; set; } - public EntityConfigurationContext(DbContextOptions options) - : base(options) + public EntityConfigurationContext(string connectionString) => + _connectionString = connectionString; + + protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder) { + _ = _connectionString switch + { + { Length: > 0 } => optionsBuilder.UseSqlServer(_connectionString), + _ => optionsBuilder.UseInMemoryDatabase("InMemoryDatabase") + }; } } } diff --git a/docs/core/extensions/snippets/configuration/custom-provider/Providers/EntityConfigurationProvider.cs b/docs/core/extensions/snippets/configuration/custom-provider/Providers/EntityConfigurationProvider.cs index 1786cd371f27a..ea1cae21da456 100644 --- a/docs/core/extensions/snippets/configuration/custom-provider/Providers/EntityConfigurationProvider.cs +++ b/docs/core/extensions/snippets/configuration/custom-provider/Providers/EntityConfigurationProvider.cs @@ -2,26 +2,20 @@ using System.Collections.Generic; using System.Linq; using CustomProvider.Example.Models; -using Microsoft.EntityFrameworkCore; using Microsoft.Extensions.Configuration; namespace CustomProvider.Example.Providers { public class EntityConfigurationProvider : ConfigurationProvider { - private readonly Action _optionsAction; + private readonly string _connectionString; - public EntityConfigurationProvider( - Action optionsAction) => - _optionsAction = optionsAction; + public EntityConfigurationProvider(string connectionString) => + _connectionString = connectionString; public override void Load() { - var builder = new DbContextOptionsBuilder(); - - _optionsAction(builder); - - using var dbContext = new EntityConfigurationContext(builder.Options); + using var dbContext = new EntityConfigurationContext(_connectionString); dbContext.Database.EnsureCreated(); @@ -36,9 +30,9 @@ static IDictionary CreateAndSaveDefaultValues( var settings = new Dictionary( StringComparer.OrdinalIgnoreCase) { - ["EndpointId"] = "b3da3c4c-9c4e-4411-bc4d-609e2dcc5c67", - ["DisplayLabel"] = "Widgets Incorporated, LLC.", - ["WidgetRoute"] = "api/widgets" + ["WidgetOptions:EndpointId"] = "b3da3c4c-9c4e-4411-bc4d-609e2dcc5c67", + ["WidgetOptions:DisplayLabel"] = "Widgets Incorporated, LLC.", + ["WidgetOptions:WidgetRoute"] = "api/widgets" }; context.Settings.AddRange( diff --git a/docs/core/extensions/snippets/configuration/custom-provider/Providers/EntityConfigurationSource.cs b/docs/core/extensions/snippets/configuration/custom-provider/Providers/EntityConfigurationSource.cs index 6093cba71edd2..abc9d7ac16e07 100644 --- a/docs/core/extensions/snippets/configuration/custom-provider/Providers/EntityConfigurationSource.cs +++ b/docs/core/extensions/snippets/configuration/custom-provider/Providers/EntityConfigurationSource.cs @@ -1,18 +1,15 @@ -using System; -using Microsoft.EntityFrameworkCore; -using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.Configuration; namespace CustomProvider.Example.Providers { public class EntityConfigurationSource : IConfigurationSource { - private readonly Action _optionsAction; + private readonly string _connectionString; - public EntityConfigurationSource( - Action optionsAction) => - _optionsAction = optionsAction; + public EntityConfigurationSource(string connectionString) => + _connectionString = connectionString; public IConfigurationProvider Build(IConfigurationBuilder builder) => - new EntityConfigurationProvider(_optionsAction); + new EntityConfigurationProvider(_connectionString); } } diff --git a/docs/core/extensions/snippets/configuration/custom-provider/WidgetOptions.cs b/docs/core/extensions/snippets/configuration/custom-provider/WidgetOptions.cs new file mode 100644 index 0000000000000..466a1003c6f58 --- /dev/null +++ b/docs/core/extensions/snippets/configuration/custom-provider/WidgetOptions.cs @@ -0,0 +1,13 @@ +using System; + +namespace CustomProvider.Example +{ + public class WidgetOptions + { + public Guid EndpointId { get; set; } + + public string DisplayLabel { get; set; } + + public string WidgetRoute { get; set; } + } +} diff --git a/docs/core/extensions/snippets/configuration/custom-provider/custom-provider.csproj b/docs/core/extensions/snippets/configuration/custom-provider/custom-provider.csproj index 7befeddb2bff5..8c27f5abcad7c 100644 --- a/docs/core/extensions/snippets/configuration/custom-provider/custom-provider.csproj +++ b/docs/core/extensions/snippets/configuration/custom-provider/custom-provider.csproj @@ -7,8 +7,9 @@ - - + + + diff --git a/docs/core/extensions/snippets/configuration/options-configparam/ServiceCollectionExtensions.cs b/docs/core/extensions/snippets/configuration/options-configparam/ServiceCollectionExtensions.cs index 4bf5cd808c34d..46465e0d13871 100644 --- a/docs/core/extensions/snippets/configuration/options-configparam/ServiceCollectionExtensions.cs +++ b/docs/core/extensions/snippets/configuration/options-configparam/ServiceCollectionExtensions.cs @@ -9,11 +9,9 @@ public static IServiceCollection AddMyLibraryService( this IServiceCollection services, IConfiguration namedConfigurationSection) { - namedConfigurationSection.Bind(new LibraryOptions - { - // Default library options are overridden - // by bound configuration values. - }); + // Default library options are overridden + // by bound configuration values. + services.Configure(namedConfigurationSection); // Register lib services here... // services.AddScoped(); diff --git a/docs/core/extensions/snippets/configuration/worker-scope/AutoIncrementingIdProvider.cs b/docs/core/extensions/snippets/configuration/worker-scope/AutoIncrementingIdProvider.cs new file mode 100644 index 0000000000000..cb02074f843e8 --- /dev/null +++ b/docs/core/extensions/snippets/configuration/worker-scope/AutoIncrementingIdProvider.cs @@ -0,0 +1,9 @@ +namespace WorkerScope.Example +{ + class AutoIncrementingIdProvider : IObjectIdProvider + { + static int s_id; + + int IObjectIdProvider.GetNextId() => ++ s_id; + } +} diff --git a/docs/core/extensions/snippets/configuration/worker-scope/IObjectIdProvider.cs b/docs/core/extensions/snippets/configuration/worker-scope/IObjectIdProvider.cs new file mode 100644 index 0000000000000..e7f6debabf660 --- /dev/null +++ b/docs/core/extensions/snippets/configuration/worker-scope/IObjectIdProvider.cs @@ -0,0 +1,7 @@ +namespace WorkerScope.Example +{ + interface IObjectIdProvider + { + int GetNextId(); + } +} diff --git a/docs/core/extensions/snippets/configuration/worker-scope/IObjectProcessor.cs b/docs/core/extensions/snippets/configuration/worker-scope/IObjectProcessor.cs new file mode 100644 index 0000000000000..d8504a483c971 --- /dev/null +++ b/docs/core/extensions/snippets/configuration/worker-scope/IObjectProcessor.cs @@ -0,0 +1,9 @@ +using System.Threading.Tasks; + +namespace WorkerScope.Example +{ + interface IObjectProcessor + { + Task ProcessAsync(ObjectGraph obj); + } +} diff --git a/docs/core/extensions/snippets/configuration/worker-scope/IObjectRelay.cs b/docs/core/extensions/snippets/configuration/worker-scope/IObjectRelay.cs new file mode 100644 index 0000000000000..1461177051460 --- /dev/null +++ b/docs/core/extensions/snippets/configuration/worker-scope/IObjectRelay.cs @@ -0,0 +1,9 @@ +using System.Threading.Tasks; + +namespace WorkerScope.Example +{ + interface IObjectRelay + { + Task RelayAsync(ObjectGraph obj); + } +} diff --git a/docs/core/extensions/snippets/configuration/worker-scope/IObjectStore.cs b/docs/core/extensions/snippets/configuration/worker-scope/IObjectStore.cs new file mode 100644 index 0000000000000..b704dd75f456b --- /dev/null +++ b/docs/core/extensions/snippets/configuration/worker-scope/IObjectStore.cs @@ -0,0 +1,11 @@ +using System.Threading.Tasks; + +namespace WorkerScope.Example +{ + interface IObjectStore + { + Task GetNextAsync(); + + Task MarkAsync(ObjectGraph graph); + } +} diff --git a/docs/core/extensions/snippets/configuration/worker-scope/ObjectGraph.cs b/docs/core/extensions/snippets/configuration/worker-scope/ObjectGraph.cs new file mode 100644 index 0000000000000..9de7e222590b3 --- /dev/null +++ b/docs/core/extensions/snippets/configuration/worker-scope/ObjectGraph.cs @@ -0,0 +1,4 @@ +namespace WorkerScope.Example +{ + record ObjectGraph(int Id, string Name, bool IsProcessed = false); +} diff --git a/docs/core/extensions/snippets/configuration/worker-scope/ObjectWorkerService.cs b/docs/core/extensions/snippets/configuration/worker-scope/ObjectWorkerService.cs new file mode 100644 index 0000000000000..2913a3566d42e --- /dev/null +++ b/docs/core/extensions/snippets/configuration/worker-scope/ObjectWorkerService.cs @@ -0,0 +1,55 @@ +using System; +using System.Collections.Concurrent; +using System.Threading.Tasks; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Logging; + +namespace WorkerScope.Example +{ + internal class ObjectWorkerService : + IObjectProcessor, + IObjectRelay, + IObjectStore + { + static readonly Random s_random = new((int)DateTime.Now.Ticks); + static readonly ConcurrentDictionary s_objects = new(); + + static int NextRandomDelay => s_random.Next(250, 3000); + + readonly IObjectIdProvider _objectIdProvider; + + public ObjectWorkerService(ILogger logger, IServiceProvider serviceProvider) + { + _objectIdProvider = serviceProvider.GetRequiredService(); + + logger.LogInformation( + "ObjectWorkerService's provider hash: {hash}", + serviceProvider.GetHashCode()); + } + + public async Task GetNextAsync() + { + await Task.Delay(NextRandomDelay); + + var id = _objectIdProvider.GetNextId(); + + return s_objects.GetOrAdd(id, _ => new(id, $"Object #{id}")); + } + + public int GetNextId() => s_objects.Count + 1; + + public async Task MarkAsync(ObjectGraph obj) + { + await Task.Delay(NextRandomDelay); + + return s_objects.TryUpdate(obj.Id, obj with { IsProcessed = true }, obj) && + s_objects.TryGetValue(obj.Id, out ObjectGraph updatedObject) + ? updatedObject + : obj; + } + + public Task ProcessAsync(ObjectGraph obj) => Task.Delay(NextRandomDelay); + + public Task RelayAsync(ObjectGraph obj) => Task.Delay(NextRandomDelay); + } +} diff --git a/docs/core/extensions/snippets/configuration/worker-scope/Program.cs b/docs/core/extensions/snippets/configuration/worker-scope/Program.cs new file mode 100644 index 0000000000000..fb69ba09ceec6 --- /dev/null +++ b/docs/core/extensions/snippets/configuration/worker-scope/Program.cs @@ -0,0 +1,16 @@ +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using WorkerScope.Example; + +using var host = + Host.CreateDefaultBuilder(args) + .ConfigureServices( + (_, services) => + services.AddHostedService() + .AddScoped() + .AddScoped() + .AddScoped() + .AddScoped()) + .Build(); + +await host.RunAsync(); diff --git a/docs/core/extensions/snippets/configuration/worker-scope/Worker.cs b/docs/core/extensions/snippets/configuration/worker-scope/Worker.cs new file mode 100644 index 0000000000000..f397da53ceb78 --- /dev/null +++ b/docs/core/extensions/snippets/configuration/worker-scope/Worker.cs @@ -0,0 +1,55 @@ +using System; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; + +namespace WorkerScope.Example +{ + public class Worker : BackgroundService + { + private readonly ILogger _logger; + private readonly IServiceScopeFactory _serviceScopeFactory; + + public Worker(ILogger logger, IServiceScopeFactory serviceScopeFactory) => + (_logger, _serviceScopeFactory) = (logger, serviceScopeFactory); + + protected override async Task ExecuteAsync(CancellationToken stoppingToken) + { + while (!stoppingToken.IsCancellationRequested) + { + using (IServiceScope scope = _serviceScopeFactory.CreateScope()) + { + try + { + _logger.LogInformation( + "Starting scoped work, provider hash: {hash}.", + scope.ServiceProvider.GetHashCode()); + + var store = scope.ServiceProvider.GetRequiredService(); + var next = await store.GetNextAsync(); + _logger.LogInformation("{next}", next); + + var processor = scope.ServiceProvider.GetRequiredService(); + await processor.ProcessAsync(next); + _logger.LogInformation("Processing {name}.", next.Name); + + var relay = scope.ServiceProvider.GetRequiredService(); + await relay.RelayAsync(next); + _logger.LogInformation("Processed results have been relayed."); + + var marked = await store.MarkAsync(next); + _logger.LogInformation("Marked as processed: {next}", marked); + } + finally + { + _logger.LogInformation( + "Finished scoped work, provider hash: {hash}.{nl}", + scope.ServiceProvider.GetHashCode(), Environment.NewLine); + } + } + } + } + } +} diff --git a/docs/core/extensions/snippets/configuration/worker-scope/worker-scope.csproj b/docs/core/extensions/snippets/configuration/worker-scope/worker-scope.csproj new file mode 100644 index 0000000000000..d4c54bc4c4b64 --- /dev/null +++ b/docs/core/extensions/snippets/configuration/worker-scope/worker-scope.csproj @@ -0,0 +1,11 @@ + + + + net5.0 + WorkerScope.Example + + + + + + diff --git a/docs/core/extensions/snippets/workers/.dockerignore b/docs/core/extensions/snippets/workers/.dockerignore new file mode 100644 index 0000000000000..3729ff0cd1acc --- /dev/null +++ b/docs/core/extensions/snippets/workers/.dockerignore @@ -0,0 +1,25 @@ +**/.classpath +**/.dockerignore +**/.env +**/.git +**/.gitignore +**/.project +**/.settings +**/.toolstarget +**/.vs +**/.vscode +**/*.*proj.user +**/*.dbmdl +**/*.jfm +**/azds.yaml +**/bin +**/charts +**/docker-compose* +**/Dockerfile* +**/node_modules +**/npm-debug.log +**/obj +**/secrets.dev.yaml +**/values.dev.yaml +LICENSE +README.md \ No newline at end of file diff --git a/docs/core/extensions/snippets/workers/background-service/App.WorkerService.csproj b/docs/core/extensions/snippets/workers/background-service/App.WorkerService.csproj new file mode 100644 index 0000000000000..6eb5908382295 --- /dev/null +++ b/docs/core/extensions/snippets/workers/background-service/App.WorkerService.csproj @@ -0,0 +1,14 @@ + + + + net5.0 + App.WorkerService + Linux + enable + + + + + + + diff --git a/docs/core/extensions/snippets/workers/background-service/Dockerfile b/docs/core/extensions/snippets/workers/background-service/Dockerfile new file mode 100644 index 0000000000000..305bdd37f779f --- /dev/null +++ b/docs/core/extensions/snippets/workers/background-service/Dockerfile @@ -0,0 +1,21 @@ +# See https://aka.ms/containerfastmode to understand how Visual Studio uses this +# Dockerfile to build your images for faster debugging. + +FROM mcr.microsoft.com/dotnet/runtime:5.0 AS base +WORKDIR /app + +FROM mcr.microsoft.com/dotnet/sdk:5.0 AS build +WORKDIR /src +COPY ["background-service/App.BackgroundService.csproj", "background-service/"] +RUN dotnet restore "background-service/App.BackgroundService.csproj" +COPY . . +WORKDIR "/src/background-service" +RUN dotnet build "App.BackgroundService.csproj" -c Release -o /app/build + +FROM build AS publish +RUN dotnet publish "App.BackgroundService.csproj" -c Release -o /app/publish + +FROM base AS final +WORKDIR /app +COPY --from=publish /app/publish . +ENTRYPOINT ["dotnet", "App.BackgroundService.dll"] diff --git a/docs/core/extensions/snippets/workers/background-service/Program.cs b/docs/core/extensions/snippets/workers/background-service/Program.cs new file mode 100644 index 0000000000000..ff3dca369944f --- /dev/null +++ b/docs/core/extensions/snippets/workers/background-service/Program.cs @@ -0,0 +1,24 @@ +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using System; +using System.Collections.Generic; +using System.Linq; +using System.Threading.Tasks; + +namespace App.WorkerService +{ + public class Program + { + public static void Main(string[] args) + { + CreateHostBuilder(args).Build().Run(); + } + + public static IHostBuilder CreateHostBuilder(string[] args) => + Host.CreateDefaultBuilder(args) + .ConfigureServices((hostContext, services) => + { + services.AddHostedService(); + }); + } +} diff --git a/docs/core/extensions/snippets/workers/background-service/Properties/launchSettings.json b/docs/core/extensions/snippets/workers/background-service/Properties/launchSettings.json new file mode 100644 index 0000000000000..1e14e1408ff21 --- /dev/null +++ b/docs/core/extensions/snippets/workers/background-service/Properties/launchSettings.json @@ -0,0 +1,14 @@ +{ + "profiles": { + "App.WorkerService": { + "commandName": "Project", + "environmentVariables": { + "DOTNET_ENVIRONMENT": "Development" + }, + "dotnetRunMessages": "true" + }, + "Docker": { + "commandName": "Docker" + } + } +} diff --git a/docs/core/extensions/snippets/workers/background-service/Worker.cs b/docs/core/extensions/snippets/workers/background-service/Worker.cs new file mode 100644 index 0000000000000..4d7948b8b5442 --- /dev/null +++ b/docs/core/extensions/snippets/workers/background-service/Worker.cs @@ -0,0 +1,34 @@ +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; +using System; +using System.Threading; +using System.Threading.Tasks; + +namespace App.WorkerService +{ + public class Worker : BackgroundService + { + private readonly ILogger _logger; + + public Worker(ILogger logger) + { + _logger = logger; + } + + protected override async Task ExecuteAsync(CancellationToken stoppingToken) + { + while (!stoppingToken.IsCancellationRequested) + { + _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now); + try + { + await Task.Delay(1000, stoppingToken); + } + catch (OperationCanceledException) + { + break; + } + } + } + } +} diff --git a/docs/core/extensions/snippets/workers/background-service/appsettings.Development.json b/docs/core/extensions/snippets/workers/background-service/appsettings.Development.json new file mode 100644 index 0000000000000..8983e0fc1c5e2 --- /dev/null +++ b/docs/core/extensions/snippets/workers/background-service/appsettings.Development.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + } + } +} diff --git a/docs/core/extensions/snippets/workers/background-service/appsettings.json b/docs/core/extensions/snippets/workers/background-service/appsettings.json new file mode 100644 index 0000000000000..8983e0fc1c5e2 --- /dev/null +++ b/docs/core/extensions/snippets/workers/background-service/appsettings.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + } + } +} diff --git a/docs/core/extensions/snippets/workers/queue-service/App.QueueService.csproj b/docs/core/extensions/snippets/workers/queue-service/App.QueueService.csproj new file mode 100644 index 0000000000000..f1d6256ad0fec --- /dev/null +++ b/docs/core/extensions/snippets/workers/queue-service/App.QueueService.csproj @@ -0,0 +1,12 @@ + + + + net5.0 + App.QueueService + enable + + + + + + diff --git a/docs/core/extensions/snippets/workers/queue-service/DefaultBackgroundTaskQueue.cs b/docs/core/extensions/snippets/workers/queue-service/DefaultBackgroundTaskQueue.cs new file mode 100644 index 0000000000000..a7b52ec4037d9 --- /dev/null +++ b/docs/core/extensions/snippets/workers/queue-service/DefaultBackgroundTaskQueue.cs @@ -0,0 +1,41 @@ +using System; +using System.Threading; +using System.Threading.Channels; +using System.Threading.Tasks; + +namespace App.QueueService +{ + public class DefaultBackgroundTaskQueue : IBackgroundTaskQueue + { + private readonly Channel> _queue; + + public DefaultBackgroundTaskQueue(int capacity) + { + BoundedChannelOptions options = new(capacity) + { + FullMode = BoundedChannelFullMode.Wait + }; + _queue = Channel.CreateBounded>(options); + } + + public async ValueTask QueueBackgroundWorkItemAsync( + Func workItem) + { + if (workItem is null) + { + throw new ArgumentNullException(nameof(workItem)); + } + + await _queue.Writer.WriteAsync(workItem); + } + + public async ValueTask> DequeueAsync( + CancellationToken cancellationToken) + { + Func? workItem = + await _queue.Reader.ReadAsync(cancellationToken); + + return workItem; + } + } +} diff --git a/docs/core/extensions/snippets/workers/queue-service/IBackgroundTaskQueue.cs b/docs/core/extensions/snippets/workers/queue-service/IBackgroundTaskQueue.cs new file mode 100644 index 0000000000000..096ed8967870c --- /dev/null +++ b/docs/core/extensions/snippets/workers/queue-service/IBackgroundTaskQueue.cs @@ -0,0 +1,15 @@ +using System; +using System.Threading; +using System.Threading.Tasks; + +namespace App.QueueService +{ + public interface IBackgroundTaskQueue + { + ValueTask QueueBackgroundWorkItemAsync( + Func workItem); + + ValueTask> DequeueAsync( + CancellationToken cancellationToken); + } +} diff --git a/docs/core/extensions/snippets/workers/queue-service/MonitorLoop.cs b/docs/core/extensions/snippets/workers/queue-service/MonitorLoop.cs new file mode 100644 index 0000000000000..3e9c10d49a8a4 --- /dev/null +++ b/docs/core/extensions/snippets/workers/queue-service/MonitorLoop.cs @@ -0,0 +1,81 @@ +using System; +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; + +namespace App.QueueService +{ + public class MonitorLoop + { + private readonly IBackgroundTaskQueue _taskQueue; + private readonly ILogger _logger; + private readonly CancellationToken _cancellationToken; + + public MonitorLoop( + IBackgroundTaskQueue taskQueue, + ILogger logger, + IHostApplicationLifetime applicationLifetime) + { + _taskQueue = taskQueue; + _logger = logger; + _cancellationToken = applicationLifetime.ApplicationStopping; + } + + public void StartMonitorLoop() + { + _logger.LogInformation($"{nameof(MonitorAsync)} loop is starting."); + + // Run a console user input loop in a background thread + Task.Run(async () => await MonitorAsync()); + } + + private async ValueTask MonitorAsync() + { + while (!_cancellationToken.IsCancellationRequested) + { + var keyStroke = Console.ReadKey(); + if (keyStroke.Key == ConsoleKey.W) + { + // Enqueue a background work item + await _taskQueue.QueueBackgroundWorkItemAsync(BuildWorkItemAsync); + } + } + } + + private async ValueTask BuildWorkItemAsync(CancellationToken token) + { + // Simulate three 5-second tasks to complete + // for each enqueued work item + + int delayLoop = 0; + var guid = Guid.NewGuid(); + + _logger.LogInformation("Queued work item {Guid} is starting.", guid); + + while (!token.IsCancellationRequested && delayLoop < 3) + { + try + { + await Task.Delay(TimeSpan.FromSeconds(5), token); + } + catch (OperationCanceledException) + { + // Prevent throwing if the Delay is cancelled + } + + ++ delayLoop; + + _logger.LogInformation("Queued work item {Guid} is running. {DelayLoop}/3", guid, delayLoop); + } + + string format = delayLoop switch + { + 3 => "Queued Background Task {Guid} is complete.", + _ => "Queued Background Task {Guid} was cancelled." + }; + + _logger.LogInformation(format, guid); + } + } +} diff --git a/docs/core/extensions/snippets/workers/queue-service/Program.cs b/docs/core/extensions/snippets/workers/queue-service/Program.cs new file mode 100644 index 0000000000000..67b84dca2f44d --- /dev/null +++ b/docs/core/extensions/snippets/workers/queue-service/Program.cs @@ -0,0 +1,25 @@ +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using App.QueueService; + +using IHost host = Host.CreateDefaultBuilder(args) + .ConfigureServices((context, services) => + { + services.AddSingleton(); + services.AddHostedService(); + services.AddSingleton(_ => + { + if (!int.TryParse(context.Configuration["QueueCapacity"], out var queueCapacity)) + { + queueCapacity = 100; + } + + return new DefaultBackgroundTaskQueue(queueCapacity); + }); + }) + .Build(); + +MonitorLoop monitorLoop = host.Services.GetRequiredService()!; +monitorLoop.StartMonitorLoop(); + +await host.RunAsync(); diff --git a/docs/core/extensions/snippets/workers/queue-service/Properties/launchSettings.json b/docs/core/extensions/snippets/workers/queue-service/Properties/launchSettings.json new file mode 100644 index 0000000000000..be1cadc9740e6 --- /dev/null +++ b/docs/core/extensions/snippets/workers/queue-service/Properties/launchSettings.json @@ -0,0 +1,11 @@ +{ + "profiles": { + "App.QueueService": { + "commandName": "Project", + "environmentVariables": { + "DOTNET_ENVIRONMENT": "Development" + }, + "dotnetRunMessages": "true" + } + } +} diff --git a/docs/core/extensions/snippets/workers/queue-service/QueuedHostedService.cs b/docs/core/extensions/snippets/workers/queue-service/QueuedHostedService.cs new file mode 100644 index 0000000000000..317f4f3e0f538 --- /dev/null +++ b/docs/core/extensions/snippets/workers/queue-service/QueuedHostedService.cs @@ -0,0 +1,59 @@ +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; +using System; +using System.Threading; +using System.Threading.Tasks; + +namespace App.QueueService +{ + public sealed class QueuedHostedService : BackgroundService + { + private readonly IBackgroundTaskQueue _taskQueue; + private readonly ILogger _logger; + + public QueuedHostedService( + IBackgroundTaskQueue taskQueue, + ILogger logger) => + (_taskQueue, _logger) = (taskQueue, logger); + + protected override Task ExecuteAsync(CancellationToken stoppingToken) + { + _logger.LogInformation( + $"{nameof(QueuedHostedService)} is running.{Environment.NewLine}" + + $"{Environment.NewLine}Tap W to add a work item to the " + + $"background queue.{Environment.NewLine}"); + + return ProcessTaskQueueAsync(stoppingToken); + } + + private async Task ProcessTaskQueueAsync(CancellationToken stoppingToken) + { + while (!stoppingToken.IsCancellationRequested) + { + try + { + Func? workItem = + await _taskQueue.DequeueAsync(stoppingToken); + + await workItem(stoppingToken); + } + catch (OperationCanceledException) + { + // Prevent throwing if stoppingToken was signaled + } + catch (Exception ex) + { + _logger.LogError(ex, "Error occurred executing task work item."); + } + } + } + + public override async Task StopAsync(CancellationToken stoppingToken) + { + _logger.LogInformation( + $"{nameof(QueuedHostedService)} is stopping."); + + await base.StopAsync(stoppingToken); + } + } +} diff --git a/docs/core/extensions/snippets/workers/queue-service/appsettings.Development.json b/docs/core/extensions/snippets/workers/queue-service/appsettings.Development.json new file mode 100644 index 0000000000000..8983e0fc1c5e2 --- /dev/null +++ b/docs/core/extensions/snippets/workers/queue-service/appsettings.Development.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + } + } +} diff --git a/docs/core/extensions/snippets/workers/queue-service/appsettings.json b/docs/core/extensions/snippets/workers/queue-service/appsettings.json new file mode 100644 index 0000000000000..8983e0fc1c5e2 --- /dev/null +++ b/docs/core/extensions/snippets/workers/queue-service/appsettings.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + } + } +} diff --git a/docs/core/extensions/snippets/workers/scoped-service/App.ScopedService.csproj b/docs/core/extensions/snippets/workers/scoped-service/App.ScopedService.csproj new file mode 100644 index 0000000000000..52ee847c73f22 --- /dev/null +++ b/docs/core/extensions/snippets/workers/scoped-service/App.ScopedService.csproj @@ -0,0 +1,12 @@ + + + + net5.0 + App.ScopedService + enable + + + + + + diff --git a/docs/core/extensions/snippets/workers/scoped-service/DefaultScopedProcessingService.cs b/docs/core/extensions/snippets/workers/scoped-service/DefaultScopedProcessingService.cs new file mode 100644 index 0000000000000..01e5b844fc83b --- /dev/null +++ b/docs/core/extensions/snippets/workers/scoped-service/DefaultScopedProcessingService.cs @@ -0,0 +1,31 @@ +using System.Threading; +using System.Threading.Tasks; +using Microsoft.Extensions.Logging; + +namespace App.ScopedService +{ + public class DefaultScopedProcessingService : IScopedProcessingService + { + private int _executionCount; + private readonly ILogger _logger; + + public DefaultScopedProcessingService( + ILogger logger) => + _logger = logger; + + public async Task DoWorkAsync(CancellationToken stoppingToken) + { + while (!stoppingToken.IsCancellationRequested) + { + ++ _executionCount; + + _logger.LogInformation( + "{ServiceName} working, execution count: {Count}", + nameof(DefaultScopedProcessingService), + _executionCount); + + await Task.Delay(10_000, stoppingToken); + } + } + } +} diff --git a/docs/core/extensions/snippets/workers/scoped-service/IScopedProcessingService.cs b/docs/core/extensions/snippets/workers/scoped-service/IScopedProcessingService.cs new file mode 100644 index 0000000000000..3d08a95d70341 --- /dev/null +++ b/docs/core/extensions/snippets/workers/scoped-service/IScopedProcessingService.cs @@ -0,0 +1,10 @@ +using System.Threading; +using System.Threading.Tasks; + +namespace App.ScopedService +{ + public interface IScopedProcessingService + { + Task DoWorkAsync(CancellationToken stoppingToken); + } +} diff --git a/docs/core/extensions/snippets/workers/scoped-service/Program.cs b/docs/core/extensions/snippets/workers/scoped-service/Program.cs new file mode 100644 index 0000000000000..5b4dc1f54e028 --- /dev/null +++ b/docs/core/extensions/snippets/workers/scoped-service/Program.cs @@ -0,0 +1,13 @@ +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using App.ScopedService; + +using IHost host = Host.CreateDefaultBuilder(args) + .ConfigureServices(services => + { + services.AddHostedService(); + services.AddScoped(); + }) + .Build(); + +await host.RunAsync(); diff --git a/docs/core/extensions/snippets/workers/scoped-service/Properties/launchSettings.json b/docs/core/extensions/snippets/workers/scoped-service/Properties/launchSettings.json new file mode 100644 index 0000000000000..2e95be32ec382 --- /dev/null +++ b/docs/core/extensions/snippets/workers/scoped-service/Properties/launchSettings.json @@ -0,0 +1,11 @@ +{ + "profiles": { + "App.ScopedService": { + "commandName": "Project", + "environmentVariables": { + "DOTNET_ENVIRONMENT": "Development" + }, + "dotnetRunMessages": "true" + } + } +} diff --git a/docs/core/extensions/snippets/workers/scoped-service/ScopedBackgroundService.cs b/docs/core/extensions/snippets/workers/scoped-service/ScopedBackgroundService.cs new file mode 100644 index 0000000000000..81c8bdd6855bd --- /dev/null +++ b/docs/core/extensions/snippets/workers/scoped-service/ScopedBackgroundService.cs @@ -0,0 +1,50 @@ +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; +using System; +using System.Threading; +using System.Threading.Tasks; + +namespace App.ScopedService +{ + public sealed class ScopedBackgroundService : BackgroundService + { + private readonly IServiceProvider _serviceProvider; + private readonly ILogger _logger; + + public ScopedBackgroundService( + IServiceProvider serviceProvider, + ILogger logger) => + (_serviceProvider, _logger) = (serviceProvider, logger); + + protected override async Task ExecuteAsync(CancellationToken stoppingToken) + { + _logger.LogInformation( + $"{nameof(ScopedBackgroundService)} is running."); + + await DoWorkAsync(stoppingToken); + } + + private async Task DoWorkAsync(CancellationToken stoppingToken) + { + _logger.LogInformation( + $"{nameof(ScopedBackgroundService)} is working."); + + using (IServiceScope scope = _serviceProvider.CreateScope()) + { + IScopedProcessingService scopedProcessingService = + scope.ServiceProvider.GetRequiredService(); + + await scopedProcessingService.DoWorkAsync(stoppingToken); + } + } + + public override async Task StopAsync(CancellationToken stoppingToken) + { + _logger.LogInformation( + $"{nameof(ScopedBackgroundService)} is stopping."); + + await base.StopAsync(stoppingToken); + } + } +} diff --git a/docs/core/extensions/snippets/workers/scoped-service/appsettings.Development.json b/docs/core/extensions/snippets/workers/scoped-service/appsettings.Development.json new file mode 100644 index 0000000000000..8983e0fc1c5e2 --- /dev/null +++ b/docs/core/extensions/snippets/workers/scoped-service/appsettings.Development.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + } + } +} diff --git a/docs/core/extensions/snippets/workers/scoped-service/appsettings.json b/docs/core/extensions/snippets/workers/scoped-service/appsettings.json new file mode 100644 index 0000000000000..8983e0fc1c5e2 --- /dev/null +++ b/docs/core/extensions/snippets/workers/scoped-service/appsettings.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + } + } +} diff --git a/docs/core/extensions/snippets/workers/timer-service/App.TimerHostedService.csproj b/docs/core/extensions/snippets/workers/timer-service/App.TimerHostedService.csproj new file mode 100644 index 0000000000000..636d4a5ca95b8 --- /dev/null +++ b/docs/core/extensions/snippets/workers/timer-service/App.TimerHostedService.csproj @@ -0,0 +1,12 @@ + + + + net5.0 + App.TimerHostedService + enable + + + + + + diff --git a/docs/core/extensions/snippets/workers/timer-service/Program.cs b/docs/core/extensions/snippets/workers/timer-service/Program.cs new file mode 100644 index 0000000000000..6c0b1b175cdc5 --- /dev/null +++ b/docs/core/extensions/snippets/workers/timer-service/Program.cs @@ -0,0 +1,12 @@ +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using App.TimerHostedService; + +using IHost host = Host.CreateDefaultBuilder(args) + .ConfigureServices(services => + { + services.AddHostedService(); + }) + .Build(); + +await host.RunAsync(); diff --git a/docs/core/extensions/snippets/workers/timer-service/Properties/launchSettings.json b/docs/core/extensions/snippets/workers/timer-service/Properties/launchSettings.json new file mode 100644 index 0000000000000..6e17df44a38bf --- /dev/null +++ b/docs/core/extensions/snippets/workers/timer-service/Properties/launchSettings.json @@ -0,0 +1,11 @@ +{ + "profiles": { + "App.TimerHostedService": { + "commandName": "Project", + "environmentVariables": { + "DOTNET_ENVIRONMENT": "Development" + }, + "dotnetRunMessages": "true" + } + } +} diff --git a/docs/core/extensions/snippets/workers/timer-service/TimerService.cs b/docs/core/extensions/snippets/workers/timer-service/TimerService.cs new file mode 100644 index 0000000000000..354586e26ee4d --- /dev/null +++ b/docs/core/extensions/snippets/workers/timer-service/TimerService.cs @@ -0,0 +1,55 @@ +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; +using System; +using System.Threading; +using System.Threading.Tasks; + +namespace App.TimerHostedService +{ + public sealed class TimerService : IHostedService, IAsyncDisposable + { + private readonly Task _completedTask = Task.CompletedTask; + private readonly ILogger _logger; + private int _executionCount = 0; + private Timer? _timer; + + public TimerService(ILogger logger) => _logger = logger; + + public Task StartAsync(CancellationToken stoppingToken) + { + _logger.LogInformation($"{nameof(TimerHostedService)} is running."); + _timer = new Timer(DoWork, null, TimeSpan.Zero, TimeSpan.FromSeconds(5)); + + return _completedTask; + } + + private void DoWork(object? state) + { + int count = Interlocked.Increment(ref _executionCount); + + _logger.LogInformation( + $"{nameof(TimerHostedService)} is working, execution count: {{Count:#,0}}", + count); + } + + public Task StopAsync(CancellationToken stoppingToken) + { + _logger.LogInformation( + $"{nameof(TimerHostedService)} is stopping."); + + _timer?.Change(Timeout.Infinite, 0); + + return _completedTask; + } + + public async ValueTask DisposeAsync() + { + if (_timer is IAsyncDisposable timer) + { + await timer.DisposeAsync(); + } + + _timer = null; + } + } +} diff --git a/docs/core/extensions/snippets/workers/timer-service/appsettings.Development.json b/docs/core/extensions/snippets/workers/timer-service/appsettings.Development.json new file mode 100644 index 0000000000000..8983e0fc1c5e2 --- /dev/null +++ b/docs/core/extensions/snippets/workers/timer-service/appsettings.Development.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + } + } +} diff --git a/docs/core/extensions/snippets/workers/timer-service/appsettings.json b/docs/core/extensions/snippets/workers/timer-service/appsettings.json new file mode 100644 index 0000000000000..8983e0fc1c5e2 --- /dev/null +++ b/docs/core/extensions/snippets/workers/timer-service/appsettings.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + } + } +} diff --git a/docs/core/extensions/snippets/workers/windows-service/App.WindowsService.csproj b/docs/core/extensions/snippets/workers/windows-service/App.WindowsService.csproj new file mode 100644 index 0000000000000..63c9a6bce6514 --- /dev/null +++ b/docs/core/extensions/snippets/workers/windows-service/App.WindowsService.csproj @@ -0,0 +1,19 @@ + + + + net5.0 + App.WindowsService + enable + exe + true + win-x64 + x64 + true + + + + + + + + diff --git a/docs/core/extensions/snippets/workers/windows-service/JokeService.cs b/docs/core/extensions/snippets/workers/windows-service/JokeService.cs new file mode 100644 index 0000000000000..510078389a574 --- /dev/null +++ b/docs/core/extensions/snippets/workers/windows-service/JokeService.cs @@ -0,0 +1,44 @@ +using System; +using System.Net.Http; +using System.Net.Http.Json; +using System.Text.Json; +using System.Threading.Tasks; + +namespace App.WindowsService +{ + public class JokeService + { + private readonly HttpClient _httpClient; + private readonly JsonSerializerOptions _options = new() + { + PropertyNameCaseInsensitive = true + }; + + private const string JokeApiUrl = + "https://official-joke-api.appspot.com/jokes/programming/random"; + + public JokeService(HttpClient httpClient) => _httpClient = httpClient; + + public async Task GetJokeAsync() + { + try + { + // The API returns an array with a single entry. + Joke[]? jokes = await _httpClient.GetFromJsonAsync( + JokeApiUrl, _options); + + Joke? joke = jokes?[0]; + + return joke is not null + ? $"{joke.Setup}{Environment.NewLine}{joke.Punchline}" + : "No joke here..."; + } + catch (Exception ex) + { + return $"That's not funny! {ex}"; + } + } + } + + public record Joke(int Id, string Type, string Setup, string Punchline); +} diff --git a/docs/core/extensions/snippets/workers/windows-service/Program.cs b/docs/core/extensions/snippets/workers/windows-service/Program.cs new file mode 100644 index 0000000000000..e87d277d419e9 --- /dev/null +++ b/docs/core/extensions/snippets/workers/windows-service/Program.cs @@ -0,0 +1,17 @@ +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using App.WindowsService; + +using IHost host = Host.CreateDefaultBuilder(args) + .UseWindowsService(options => + { + options.ServiceName = ".NET Joke Service"; + }) + .ConfigureServices(services => + { + services.AddHostedService(); + services.AddHttpClient(); + }) + .Build(); + +await host.RunAsync(); diff --git a/docs/core/extensions/snippets/workers/windows-service/Properties/PublishProfiles/FolderProfile.pubxml b/docs/core/extensions/snippets/workers/windows-service/Properties/PublishProfiles/FolderProfile.pubxml new file mode 100644 index 0000000000000..1d6a74da22c94 --- /dev/null +++ b/docs/core/extensions/snippets/workers/windows-service/Properties/PublishProfiles/FolderProfile.pubxml @@ -0,0 +1,18 @@ + + + + + Release + Any CPU + bin\Release\net5.0\win-x64\publish\ + FileSystem + net5.0 + win-x64 + true + True + True + True + + diff --git a/docs/core/extensions/snippets/workers/windows-service/Properties/launchSettings.json b/docs/core/extensions/snippets/workers/windows-service/Properties/launchSettings.json new file mode 100644 index 0000000000000..9a42edc53d4d4 --- /dev/null +++ b/docs/core/extensions/snippets/workers/windows-service/Properties/launchSettings.json @@ -0,0 +1,11 @@ +{ + "profiles": { + "App.WindowsService": { + "commandName": "Project", + "environmentVariables": { + "DOTNET_ENVIRONMENT": "Development" + }, + "dotnetRunMessages": "true" + } + } +} diff --git a/docs/core/extensions/snippets/workers/windows-service/WindowsBackgroundService.cs b/docs/core/extensions/snippets/workers/windows-service/WindowsBackgroundService.cs new file mode 100644 index 0000000000000..b449b702adcc2 --- /dev/null +++ b/docs/core/extensions/snippets/workers/windows-service/WindowsBackgroundService.cs @@ -0,0 +1,37 @@ +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; +using System; +using System.Threading; +using System.Threading.Tasks; + +namespace App.WindowsService +{ + public sealed class WindowsBackgroundService : BackgroundService + { + private readonly JokeService _jokeService; + private readonly ILogger _logger; + + public WindowsBackgroundService( + JokeService jokeService, + ILogger logger) => + (_jokeService, _logger) = (jokeService, logger); + + protected override async Task ExecuteAsync(CancellationToken stoppingToken) + { + while (!stoppingToken.IsCancellationRequested) + { + try + { + string joke = await _jokeService.GetJokeAsync(); + _logger.LogWarning(joke); + + await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken); + } + catch (OperationCanceledException) + { + break; + } + } + } + } +} diff --git a/docs/core/extensions/snippets/workers/windows-service/appsettings.Development.json b/docs/core/extensions/snippets/workers/windows-service/appsettings.Development.json new file mode 100644 index 0000000000000..8983e0fc1c5e2 --- /dev/null +++ b/docs/core/extensions/snippets/workers/windows-service/appsettings.Development.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + } + } +} diff --git a/docs/core/extensions/snippets/workers/windows-service/appsettings.json b/docs/core/extensions/snippets/workers/windows-service/appsettings.json new file mode 100644 index 0000000000000..8983e0fc1c5e2 --- /dev/null +++ b/docs/core/extensions/snippets/workers/windows-service/appsettings.json @@ -0,0 +1,9 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning", + "Microsoft.Hosting.Lifetime": "Information" + } + } +} diff --git a/docs/core/extensions/snippets/workers/workers.sln b/docs/core/extensions/snippets/workers/workers.sln new file mode 100644 index 0000000000000..6111183018978 --- /dev/null +++ b/docs/core/extensions/snippets/workers/workers.sln @@ -0,0 +1,49 @@ + +Microsoft Visual Studio Solution File, Format Version 12.00 +# Visual Studio Version 16 +VisualStudioVersion = 16.0.31313.381 +MinimumVisualStudioVersion = 10.0.40219.1 +Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "App.WorkerService", "background-service\App.WorkerService.csproj", "{51530BFA-E250-468A-BC9F-215222BB5CB5}" +EndProject +Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "App.QueueService", "queue-service\App.QueueService.csproj", "{BEB98EBB-60C0-4BB1-A606-CECAAB6E7B6E}" +EndProject +Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "App.ScopedService", "scoped-service\App.ScopedService.csproj", "{BA9F54FA-12C7-4A2A-B128-10BC2C079728}" +EndProject +Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "App.TimerHostedService", "timer-service\App.TimerHostedService.csproj", "{70D6B8C4-BDE0-4231-94F1-7B403B640647}" +EndProject +Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "App.WindowsService", "windows-service\App.WindowsService.csproj", "{0642A687-220B-4E1E-99B8-A31B5DC40A35}" +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Any CPU = Debug|Any CPU + Release|Any CPU = Release|Any CPU + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {51530BFA-E250-468A-BC9F-215222BB5CB5}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {51530BFA-E250-468A-BC9F-215222BB5CB5}.Debug|Any CPU.Build.0 = Debug|Any CPU + {51530BFA-E250-468A-BC9F-215222BB5CB5}.Release|Any CPU.ActiveCfg = Release|Any CPU + {51530BFA-E250-468A-BC9F-215222BB5CB5}.Release|Any CPU.Build.0 = Release|Any CPU + {BEB98EBB-60C0-4BB1-A606-CECAAB6E7B6E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {BEB98EBB-60C0-4BB1-A606-CECAAB6E7B6E}.Debug|Any CPU.Build.0 = Debug|Any CPU + {BEB98EBB-60C0-4BB1-A606-CECAAB6E7B6E}.Release|Any CPU.ActiveCfg = Release|Any CPU + {BEB98EBB-60C0-4BB1-A606-CECAAB6E7B6E}.Release|Any CPU.Build.0 = Release|Any CPU + {BA9F54FA-12C7-4A2A-B128-10BC2C079728}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {BA9F54FA-12C7-4A2A-B128-10BC2C079728}.Debug|Any CPU.Build.0 = Debug|Any CPU + {BA9F54FA-12C7-4A2A-B128-10BC2C079728}.Release|Any CPU.ActiveCfg = Release|Any CPU + {BA9F54FA-12C7-4A2A-B128-10BC2C079728}.Release|Any CPU.Build.0 = Release|Any CPU + {70D6B8C4-BDE0-4231-94F1-7B403B640647}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {70D6B8C4-BDE0-4231-94F1-7B403B640647}.Debug|Any CPU.Build.0 = Debug|Any CPU + {70D6B8C4-BDE0-4231-94F1-7B403B640647}.Release|Any CPU.ActiveCfg = Release|Any CPU + {70D6B8C4-BDE0-4231-94F1-7B403B640647}.Release|Any CPU.Build.0 = Release|Any CPU + {0642A687-220B-4E1E-99B8-A31B5DC40A35}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {0642A687-220B-4E1E-99B8-A31B5DC40A35}.Debug|Any CPU.Build.0 = Debug|Any CPU + {0642A687-220B-4E1E-99B8-A31B5DC40A35}.Release|Any CPU.ActiveCfg = Release|Any CPU + {0642A687-220B-4E1E-99B8-A31B5DC40A35}.Release|Any CPU.Build.0 = Release|Any CPU + EndGlobalSection + GlobalSection(SolutionProperties) = preSolution + HideSolutionNode = FALSE + EndGlobalSection + GlobalSection(ExtensibilityGlobals) = postSolution + SolutionGuid = {E9D03BDE-225F-4A4B-8441-8551EE03BD08} + EndGlobalSection +EndGlobal diff --git a/docs/core/extensions/timer-service.md b/docs/core/extensions/timer-service.md new file mode 100644 index 0000000000000..f50ac0feb67b9 --- /dev/null +++ b/docs/core/extensions/timer-service.md @@ -0,0 +1,95 @@ +--- +title: Implement the IHostedService interface +description: Learn how to implement a custom IHostedService interface with .NET. +author: IEvangelist +ms.author: dapine +ms.date: 05/26/2021 +ms.topic: tutorial +--- + +# Implement the `IHostedService` interface + +When you need finite control beyond the provided , you can implement your own . The interface is the basis for all long running services in .NET. Custom implementations are registered with the extension method. + +In this tutorial, you learn how to: + +> [!div class="checklist"] +> +> - Implement the , and interfaces. +> - Create a timer-based service. +> - Register the custom implemenation with dependency injection and logging. + +## Prerequisites + +- The [.NET 5.0 SDK or later](https://dotnet.microsoft.com/download/dotnet) +- A .NET integrated development environment (IDE) + - Feel free to use [Visual Studio](https://visualstudio.microsoft.com) + + +[!INCLUDE [file-new-worker](includes/file-new-worker.md)] + +## Create timer service + +The timer-based background service makes use of the class. The timer triggers the `DoWork` method. The timer is disabled on and disposed when the service container is disposed on : + +Replace the contents of the `Worker` from the template with the following C# code, and rename the file to *TimerService.cs*: + +:::code source="snippets/workers/timer-service/TimerService.cs" highlight="40,47-50"::: + +> [!IMPORTANT] +> The `Worker` was a subclass of . Now, the `TimerService` implements both the , and interfaces. + +The `TimerService` is `sealed`, and cascades the `DisposeAsync` call from its `_timer` instance. For more information on the "cascading dispose pattern", see [Implement a `DisposeAsync` method](../../standard/garbage-collection/implementing-disposeasync.md). + +When is called, the timer is instantiated, thus starting the timer. + +> [!TIP] +> The doesn't wait for previous executions of `DoWork` to finish, so the approach shown might not be suitable for every scenario. is used to increment the execution counter as an atomic operation, which ensures that multiple threads don't update `_executionCount` concurrently. + +Replace the existing `Program` contents with the following C# code: + +:::code source="snippets/workers/timer-service/Program.cs" highlight="8"::: + +The service is registered in `IHostBuilder.ConfigureServices` (*Program.cs*) with the `AddHostedService` extension method. This is the same extension method you use when registering subclasses, as they both implement the interface. + +For more information on registering services, see [Dependency injection in .NET](dependency-injection.md). + +## Verify service functionality + +[!INCLUDE [run-app](includes/run-app.md)] + +Let the application run for a bit to generate several execution count increments. You will see output similar to the following: + +```Output +info: App.TimerHostedService.TimerService[0] + TimerHostedService is running. +info: Microsoft.Hosting.Lifetime[0] + Application started. Press Ctrl+C to shut down. +info: Microsoft.Hosting.Lifetime[0] + Hosting environment: Development +info: Microsoft.Hosting.Lifetime[0] + Content root path: .\timer-service +info: App.TimerHostedService.TimerService[0] + TimerHostedService is working, execution count: 1 +info: App.TimerHostedService.TimerService[0] + TimerHostedService is working, execution count: 2 +info: App.TimerHostedService.TimerService[0] + TimerHostedService is working, execution count: 3 +info: App.TimerHostedService.TimerService[0] + TimerHostedService is working, execution count: 4 +info: Microsoft.Hosting.Lifetime[0] + Application is shutting down... +info: App.TimerHostedService.TimerService[0] + TimerHostedService is stopping. +``` + +[!INCLUDE [stop-app](includes/stop-app.md)] + +## See also + +There are several related tutorials to consider: + +- [Worker Services in .NET](workers.md) +- [Create a Queue Service](queue-service.md) +- [Use scoped services within a `BackgroundService`](scoped-service.md) +- [Create a Windows Service using `BackgroundService`](windows-service.md) diff --git a/docs/core/extensions/windows-service.md b/docs/core/extensions/windows-service.md new file mode 100644 index 0000000000000..87f5995fa92f5 --- /dev/null +++ b/docs/core/extensions/windows-service.md @@ -0,0 +1,250 @@ +--- +title: Create a Windows Service using BackgroundService +description: Learn how to create a Windows Service using the BackgroundService in .NET. +author: IEvangelist +ms.author: dapine +ms.date: 05/26/2021 +ms.topic: tutorial +--- + +# Create a Windows Service using `BackgroundService` + +.NET Framework developers are probably familiar with Windows Service apps. Before .NET Core and .NET 5+, developers who relied on .NET Framework could create Windows Services to perform background tasks or execute long-running processes. This functionality is still available and you can create Worker Services that run as a Windows Service. + +In this tutorial, you'll learn how to: + +> [!div class="checklist"] +> +> - Publish a .NET worker app as a single file executable. +> - Create a Windows Service. +> - Create the `BackgroundService` app as a Windows Service. +> - Start and stop the Windows Service. +> - View event logs. +> - Delete the Windows Service. + +## Prerequisites + +- The [.NET 5.0 SDK or later](https://dotnet.microsoft.com/download/dotnet) +- A Windows OS +- A .NET integrated development environment (IDE) + - Feel free to use [Visual Studio](https://visualstudio.microsoft.com) + + +[!INCLUDE [file-new-worker](includes/file-new-worker.md)] + +## Install NuGet package + +In order to interop with native Windows Services from .NET implementations, you'll need to install the [`Microsoft.Extensions.Hosting.WindowsServices` NuGet package](https://nuget.org/packages/Microsoft.Extensions.Hosting.WindowsServices). + +To install this from Visual Studio, use the **Manage NuGet Packages...** dialog. Search for "Microsoft.Extensions.Hosting.WindowsServices", and install it. If you're rather use the .NET CLI, run the `dotnet add package` command: + +```dotnetcli +dotnet add package Microsoft.Extensions.Hosting.WindowsServices +``` + +As part of the example source code for this tutorial, you'll need to also install the [`Microsoft.Extensions.Http` NuGet package](https://nuget.org/packages/Microsoft.Extensions.Http). + +```dotnetcli +dotnet add package Microsoft.Extensions.Http +``` + +For more information on the .NET CLI add package command, see [`dotnet add package`](../tools/dotnet-add-package.md). + +After successfully adding the packages, your project file should now contain the following package references: + +:::code language="xml" source="snippets/workers/windows-service/App.WindowsService.csproj" range="14-18" highlight="2-4"::: + +## Create the service + +Add a new class to the project named *JokeService.cs*, and replace its contents with the following C# code: + +:::code source="snippets/workers/windows-service/JokeService.cs"::: + +The preceding joke service source code exposes a single functionality, the `GetJokeAsync` method. This is a returning method where `T` is a `string`, and it represents a random programming joke. The is injected into the constructor and assigned to a class-scope `_httpClient` variable. + +> [!TIP] +> The joke API is from an [open source project on GitHub](https://github.com/15Dkatz/official_joke_api). It is used for demonstration purposes, and we make no guarantee that it will be available in the future. To quickly test the API, open the following URL in a browser: +> +> ```http +> https://official-joke-api.appspot.com/jokes/programming/random +> ``` + +## Rewrite the Worker class + +Replace the existing `Worker` from the template with the following C# code, and rename the file to *WindowsBackgroundService.cs*: + +:::code source="snippets/workers/windows-service/WindowsBackgroundService.cs"::: + +In the preceding code, the `JokeService` is injected along with an `ILogger`. Both are made available to the class as `private readonly` fields. In the `ExecuteAsync` method, the joke service requests a joke and writes it to the logger. In this case, the logger is implemented by the Windows Event Log - . Logs written are persisted to, and available for viewing in the **Event Viewer**. + +> [!NOTE] +> By default, the *Event Log* severity is . This can be configured, but for demonstration purposes the `WindowsBackgroundService` logs with the extension method. To specifically target the `EventLog` level, add an entry in the **appsettings.{Environment}.json**, or provide an value. +> +> ```json +> "Logging": { +> "EventLog": { +> "LogLevel": { +> "Default": "Information" +> } +> } +> } +> ``` +> +> For more information on configuring log levels, see [Logging providers in .NET: Configure Windows EventLog](logging-providers.md#windows-eventlog). + +Replace the template *Program.cs* file contents with the following C# code: + +:::code source="snippets/workers/windows-service/Program.cs" highlight="6-9,12-13"::: + +The extension method configures the app to work as a Windows Service. The service name is set to `".NET Joke Service"`. The hosted service is registered, and the `HttpClient` is registered to the `JokeService` for dependency injection. + +For more information on registering services, see [Dependency injection in .NET](dependency-injection.md). + +## Publish the app + +To create the .NET Worker Service app as a Windows Service, it will need to be published as a single file executable. + +:::code language="xml" source="snippets/workers/windows-service/App.WindowsService.csproj" highlight="7-11"::: + +The preceding highlighted lines of the project file define the following behaviors: + +- `exe`: Creates a console application. +- `true`: Enables single-file publishing. +- `win-x64`: Specifies the [RID](../rid-catalog.md) of `win-x64`. +- `x64`: Specify the target platform CPU of 64-bit. +- `true`: Embeds all required .dll files into the resulting .exe file. + +To publish the app from Visual Studio, you can create a publish profile. Right-click on the project in the **Solution Explorer**, and select **Publish...**. Then, select **Add a publish profile** to create a profile. From the **Publish** dialog, select **Folder** as your **Target**. + +:::image type="content" source="media/publish-dialog.png" lightbox="media/publish-dialog.png" alt-text="The Visual Studio Publish dialog"::: + +Leave the default **Location**, and then select **Finish**. Once the profile is created, select **Show all settings**, and verify your **Profile settings**. + +:::image type="content" source="media/profile-settings.png" lightbox="media/profile-settings.png" alt-text="The Visual Studio Profile settings"::: + +Ensure that the following settings are specified: + +- **Deployment mode**: Self-contained +- **Produce single file**: checked +- **Enable ReadyToRun compilation**: checked +- **Trim unused assemblies (in preview)**: checked + +Finally, select **Publish**. The app is compiled, and the resulting .exe file is published to the */publish* output directory. + +Alternatively, you could use the .NET CLI to publish the app: + +```dotnetcli +dotnet publish --output "C:\custom\publish\directory" +``` + +For more information, see [`dotnet publish`](../tools/dotnet-publish.md). + +## Create the Windows Service + +To create the Windows Service, use the native Windows Service Control Manager's (sc.exe) create command. Run PowerShell as an Administrator. + +```powershell +sc.exe create ".NET Joke Service" binpath=C:\Path\To\App.WindowsService.exe +``` + +You'll see an output message: + +```powershell +[SC] CreateService SUCCESS +``` + +For more information, see [sc.exe create](/windows-server/administration/windows-commands/sc-create). + +To see the app created as a Windows Service, open **Services**. Select the Windows key (or Ctrl + Esc), and search from "Services". From the **Services** app, you should be able to find your service by its name. + +:::image type="content" source="media/windows-service.png" lightbox="media/windows-service.png" alt-text="The Services user interface"::: + +## Verify service functionality + +To verify that the service is functioning as expected, you need to: + +- Start the service +- View the logs +- Stop the service + +### Start the Windows Service + +To start the Windows Service, use the `sc.exe start` command: + +```powershell +sc.exe start ".NET Joke Service" +``` + +You'll see output similar to the following: + +```powershell +SERVICE_NAME: .NET Joke Service + TYPE : 10 WIN32_OWN_PROCESS + STATE : 2 START_PENDING + (NOT_STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN) + WIN32_EXIT_CODE : 0 (0x0) + SERVICE_EXIT_CODE : 0 (0x0) + CHECKPOINT : 0x0 + WAIT_HINT : 0x7d0 + PID : 37636 + FLAGS +``` + +The service **Status** will transition out of `START_PENDING` to **Running**. + +### View logs + +To view logs, open the **Event Viewer**. Select the Windows key (or Ctrl + Esc), and search for `"Event Viewer"`. Select the **Event Viewer (Local)** > **Windows Logs** > **Application** node. You should see a **Warning** level entry with a **Source** matching the apps namespace. Double-click the entry, or right-click and select **Event Properties** to view the details. + +:::image type="content" source="media/event-properties.png" lightbox="media/event-properties.png" alt-text="The Event Properties dialog, with details logged from the service"::: + +After seeing logs in the **Event Log**, you should stop the service. It's designed to log a random joke once per minute. This is intentional behaviour, but is not practical for production services. + +### Stop the Windows Service + +To stop the Windows Service, use the `sc.exe stop` command: + +```powershell +sc.exe stop ".NET Joke Service" +``` + +You'll see output similar to the following: + +```powershell +SERVICE_NAME: .NET Joke Service + TYPE : 10 WIN32_OWN_PROCESS + STATE : 3 STOP_PENDING + (STOPPABLE, NOT_PAUSABLE, ACCEPTS_SHUTDOWN) + WIN32_EXIT_CODE : 0 (0x0) + SERVICE_EXIT_CODE : 0 (0x0) + CHECKPOINT : 0x0 + WAIT_HINT : 0x0 +``` + +The service **Status** will transition out of `STOP_PENDING` to **Stopped**. + +## Delete the Windows Service + +To delete the Windows Service, use the native Windows Service Control Manager's (sc.exe) delete command. Run PowerShell as an Administrator. + +> [!IMPORTANT] +> If the service is not in the **Stopped** state, it will not be immediately deleted. Ensure that the service is stopped before issuing the delete command. + +```powershell +sc.exe delete ".NET Joke Service" +``` + +You'll see an output message: + +```powershell +[SC] DeleteService SUCCESS +``` + +For more information, see [sc.exe delete](/windows-server/administration/windows-commands/sc-delete). + +## See also + +- [Worker Services in .NET](workers.md) +- [Create a Queue Service](queue-service.md) +- [Use scoped services within a `BackgroundService`](scoped-service.md) +- [Implement the `IHostedService` interface](timer-service.md) diff --git a/docs/core/extensions/workers.md b/docs/core/extensions/workers.md new file mode 100644 index 0000000000000..71e163dd780e6 --- /dev/null +++ b/docs/core/extensions/workers.md @@ -0,0 +1,132 @@ +--- +title: Worker Services in .NET +description: Learn how to implement a custom IHostedService and use existing implementations with .NET. +author: IEvangelist +ms.author: dapine +ms.date: 05/26/2021 +ms.topic: overview +--- + +# Worker Services in .NET + +There are numerous reasons for creating long-running services such as: + +- Processing CPU intensive data. +- Queuing work items in the background. +- Performing a time-based operation on a schedule. + +Background service processing usually doesn't involve a user interface (UI), but UIs can be built around them. In the early days with .NET Framework, Windows developers could create Windows Services for these reasons. Now with .NET, you can use the — which is an implementation of , or implement your own. + +With .NET, you're no longer restricted to Windows. You can develop background services that are cross-platform. Hosted services are logging, configuration, and dependency injection (DI) ready. They're a part of the extensions suite of libraries, meaning they're fundamental to all .NET workloads that work with the [generic host](generic-host.md). + +## Terminology + +There are many terms that are mistakenly used synonymously. In this section, there are definitions for some of these terms to make their intent more apparent. + +- **Background Service**: Refers to the type. +- **Hosted Service**: Implementations of , or referring to the itself. +- **Long-running Service:** Any service that runs continuously. +- **Windows Service**: The *Windows Service* infrastructure, originally .NET Framework centric but now accessible via .NET. +- **Worker Service**: Refers to the *Worker Service* template. + +## Worker Service template + +The Worker Service template is available to the .NET CLI, and Visual Studio. For more information, see [.NET CLI, `dotnet new worker` - template](/dotnet/core/tools/dotnet-new-sdk-templates#web-others). The template consists of a `Program` and `Worker` class. + +:::code language="csharp" source="snippets/workers/background-service/Program.cs"::: + +The preceding `Program` class: + +- Creates the default . +- Calls to add the `Worker` class as a hosted service with . +- Builds an from the builder. +- Calls `Run` on the `host` instance, which runs the app. + +The *Program.cs* file from the template can be rewritten using top-level statements: + +```csharp +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using App.WorkerService; + +using IHost host = Host.CreateDefaultBuilder(args) + .ConfigureServices((hostContext, services) => + { + services.AddHostedService(); + }) + .Build(); + +await host.RunAsync(); +``` + +This is functionally equivalent to the original template. For more information on C# 9 features, see [What's new in C# 9.0](../../csharp/whats-new/csharp-9.md). + +As for the `Worker`, the template provides a simple implementation. + +:::code language="csharp" source="snippets/workers/background-service/Worker.cs"::: + +The preceding `Worker` class is a subclass of , which implements . The is an `abstract class` and requires the subclass to implement . In the template implementation the `ExecuteAsync` loops once per second, logging the current date and time until the process is signaled to cancel. + +### The project file + +The Worker Service template relies on the following project file `Sdk`: + +```xml + +``` + +For more information, see [.NET project SDKs](../project-sdk/overview.md). + +### NuGet package + +An app based on the Worker Service template uses the `Microsoft.NET.Sdk.Worker` SDK and has an explicit package reference to the [Microsoft.Extensions.Hosting](https://www.nuget.org/packages/Microsoft.Extensions.Hosting) package. + +### Containers and cloud adoptability + +With most modern .NET workloads, containers are a viable option. When creating a long-running service from the Worker Service template in Visual Studio, you can opt-in to **Docker support**. Doing so will create a *Dockerfile* that will containerize your .NET app. A [*Dockerfile*](https://docs.docker.com/engine/reference/builder) is a set of instructions to build an image. For .NET apps, the *Dockerfile* usually sits in the root of the directory next to a solution file. + +:::code language="dockerfile" source="snippets/workers/background-service/Dockerfile"::: + +The preceding *Dockerfile* steps include: + +- Setting the base image from `mcr.microsoft.com/dotnet/runtime:5.0` as the alias `base`. +- Changing the working directory to */app*. +- Setting the `build` alias from the `mcr.microsoft.com/dotnet/sdk:5.0` image. +- Changing the working directory to */src*. +- Copying the contents and publishing the .NET app: + - The app is published using the [`dotnet publish`](../tools/dotnet-publish.md) command. +- Relayering the .NET SDK image from `mcr.microsoft.com/dotnet/runtime:5.0` (the `base` alias). +- Copying the published build output from the */publish*. +- Defining the entry point, which delegates to [`dotnet App.BackgroundService.dll`](../tools/dotnet.md). + +> [!TIP] +> The MCR in `mcr.microsoft.com` stands for "Microsoft Container Registry", and is Microsoft's syndicated container catalog from the official Docker hub. The [Microsoft syndicates container catalog](https://azure.microsoft.com/blog/microsoft-syndicates-container-catalog) article contains additional details. + +Wen targeting Docker as a deployment strategy for your .NET Worker Service, there are a few considerations in the project file: + +:::code language="xml" source="snippets/workers/background-service/App.WorkerService.csproj" highlight="6,12"::: + +In the preceding project file, the `` element specifies `Linux` as its target. To target Windows containers, use `Windows` instead. The [`Microsoft.VisualStudio.Azure.Containers.Tools.Targets` NuGet package](https://www.nuget.org/packages/Microsoft.VisualStudio.Azure.Containers.Tools.Targets) is automatically added as a package reference when **Docker support** is selected from the template. + +For more information on Docker with .NET, see [Tutorial: Containerize a .NET app](../docker/build-container.md). + +## Hosted Service extensibility + +The interface defines two methods: + +- +- + +These two methods serve as *lifecycle* methods - they're called during host start and stop events respectively. + +> [!IMPORTANT] +> The interface serves as a generic-type parameter constraint on the extension method, meaning only implementations are permitted. You're free to use the provided with a subclass, or implement your own entirely. + +## See also + +- subclass tutorials: + - [Create a Queue Service in .NET](queue-service.md) + - [Use scoped services within a `BackgroundService` in .NET](scoped-service.md) + - [Create a Windows Service using `BackgroundService` in .NET](windows-service.md) +- Custom implementation: + - [Implement the `IHostedService` interface in .NET](timer-service.md) diff --git a/docs/core/get-started.md b/docs/core/get-started.md index f7400487683d2..7c4191baf8e5e 100644 --- a/docs/core/get-started.md +++ b/docs/core/get-started.md @@ -5,6 +5,7 @@ author: adegeo ms.author: adegeo ms.date: 09/29/2020 ms.custom: vs-dotnet +ms.topic: tutorial --- # Get started with .NET diff --git a/docs/core/install/includes/linux-install-20-dnf.md b/docs/core/install/includes/linux-install-20-dnf.md deleted file mode 100644 index 4ee1ea44f0d0a..0000000000000 --- a/docs/core/install/includes/linux-install-20-dnf.md +++ /dev/null @@ -1,22 +0,0 @@ - -### Install the SDK - -The .NET Core SDK allows you to develop apps with .NET Core. If you install the .NET Core SDK, you don't need to install the corresponding runtime. To install the .NET Core SDK, run the following commands: - -```bash -sudo dnf install dotnet-sdk-2.0 -``` - -### Install the runtime - -The .NET Core Runtime allows you to run apps that were made with .NET Core that didn't include the runtime. The following commands install the ASP.NET Core Runtime, which is the most compatible runtime for .NET Core. In your terminal, run the following commands. - -```bash -sudo dnf install aspnetcore-runtime-2.0 -``` - -As an alternative to the ASP.NET Core Runtime, you can install the .NET Core Runtime, which doesn't include ASP.NET Core support: replace `aspnetcore-runtime-2.0` in the previous command with `dotnet-runtime-2.0`. - -```bash -sudo dnf install dotnet-runtime-2.0 -``` diff --git a/docs/core/install/includes/linux-install-21-dnf.md b/docs/core/install/includes/linux-install-21-dnf.md deleted file mode 100644 index 7680b66899ad2..0000000000000 --- a/docs/core/install/includes/linux-install-21-dnf.md +++ /dev/null @@ -1,22 +0,0 @@ - -### Install the SDK - -The .NET Core SDK allows you to develop apps with .NET Core. If you install the .NET Core SDK, you don't need to install the corresponding runtime. To install the .NET Core SDK, run the following commands: - -```bash -sudo dnf install dotnet-sdk-2.1 -``` - -### Install the runtime - -The .NET Core Runtime allows you to run apps that were made with .NET Core that didn't include the runtime. The following commands install the ASP.NET Core Runtime, which is the most compatible runtime for .NET Core. In your terminal, run the following commands. - -```bash -sudo dnf install aspnetcore-runtime-2.1 -``` - -As an alternative to the ASP.NET Core Runtime, you can install the .NET Core Runtime, which doesn't include ASP.NET Core support: replace `aspnetcore-runtime-2.1` in the previous command with `dotnet-runtime-2.1`. - -```bash -sudo dnf install dotnet-runtime-2.1 -``` diff --git a/docs/core/install/includes/linux-install-21-yum.md b/docs/core/install/includes/linux-install-21-yum.md deleted file mode 100644 index 92f7d0af00e32..0000000000000 --- a/docs/core/install/includes/linux-install-21-yum.md +++ /dev/null @@ -1,22 +0,0 @@ - -### Install the SDK - -The .NET Core SDK allows you to develop apps with .NET Core. If you install the .NET Core SDK, you don't need to install the corresponding runtime. To install the .NET Core SDK, run the following commands: - -```bash -sudo yum install dotnet-sdk-2.1 -``` - -### Install the runtime - -The .NET Core Runtime allows you to run apps that were made with .NET Core that didn't include the runtime. The following commands install the ASP.NET Core Runtime, which is the most compatible runtime for .NET Core. In your terminal, run the following commands. - -```bash -sudo yum install aspnetcore-runtime-2.1 -``` - -As an alternative to the ASP.NET Core Runtime, you can install the .NET Core Runtime, which doesn't include ASP.NET Core support: replace `aspnetcore-runtime-2.1` in the previous command with `dotnet-runtime-2.1`. - -```bash -sudo yum install dotnet-runtime-2.1 -``` diff --git a/docs/core/install/includes/linux-install-30-dnf.md b/docs/core/install/includes/linux-install-30-dnf.md deleted file mode 100644 index a23176f179458..0000000000000 --- a/docs/core/install/includes/linux-install-30-dnf.md +++ /dev/null @@ -1,22 +0,0 @@ - -### Install the SDK - -The .NET Core SDK allows you to develop apps with .NET Core. If you install the .NET Core SDK, you don't need to install the corresponding runtime. To install the .NET Core SDK, run the following commands: - -```bash -sudo dnf install dotnet-sdk-3.0 -``` - -### Install the runtime - -The .NET Core Runtime allows you to run apps that were made with .NET Core that didn't include the runtime. The following commands install the ASP.NET Core Runtime, which is the most compatible runtime for .NET Core. In your terminal, run the following commands. - -```bash -sudo dnf install aspnetcore-runtime-3.0 -``` - -As an alternative to the ASP.NET Core Runtime, you can install the .NET Core Runtime, which doesn't include ASP.NET Core support: replace `aspnetcore-runtime-3.0` in the previous command with `dotnet-runtime-3.0`. - -```bash -sudo dnf install dotnet-runtime-3.0 -``` diff --git a/docs/core/install/includes/linux-install-31-yum.md b/docs/core/install/includes/linux-install-31-yum.md deleted file mode 100644 index d2ee296253e15..0000000000000 --- a/docs/core/install/includes/linux-install-31-yum.md +++ /dev/null @@ -1,22 +0,0 @@ - -### Install the SDK - -The .NET Core SDK allows you to develop apps with .NET Core. If you install the .NET Core SDK, you don't need to install the corresponding runtime. To install the .NET Core SDK, run the following commands: - -```bash -sudo yum install dotnet-sdk-3.1 -``` - -### Install the runtime - -The .NET Core Runtime allows you to run apps that were made with .NET Core that didn't include the runtime. The following commands install the ASP.NET Core Runtime, which is the most compatible runtime for .NET Core. In your terminal, run the following commands. - -```bash -sudo yum install aspnetcore-runtime-3.1 -``` - -As an alternative to the ASP.NET Core Runtime, you can install the .NET Core Runtime, which doesn't include ASP.NET Core support: replace `aspnetcore-runtime-2.1` in the previous command with `dotnet-runtime-3.1`. - -```bash -sudo yum install dotnet-runtime-3.1 -``` diff --git a/docs/core/install/includes/linux-install-31-zyp.md b/docs/core/install/includes/linux-install-31-zyp.md deleted file mode 100644 index b95ce184e9824..0000000000000 --- a/docs/core/install/includes/linux-install-31-zyp.md +++ /dev/null @@ -1,22 +0,0 @@ - -### Install the SDK - -The .NET Core SDK allows you to develop apps with .NET Core. If you install the .NET Core SDK, you don't need to install the corresponding runtime. To install the .NET Core SDK, run the following commands: - -```bash -sudo zypper install dotnet-sdk-3.1 -``` - -### Install the runtime - -The .NET Core Runtime allows you to run apps that were made with .NET Core that didn't include the runtime. The following commands install the ASP.NET Core Runtime, which is the most compatible runtime for .NET Core. In your terminal, run the following commands. - -```bash -sudo zypper install aspnetcore-runtime-3.1 -``` - -As an alternative to the ASP.NET Core Runtime, you can install the .NET Core Runtime, which doesn't include ASP.NET Core support: replace `aspnetcore-runtime-3.1` in the previous command with `dotnet-runtime-3.1`. - -```bash -sudo zypper install dotnet-runtime-3.1 -``` diff --git a/docs/core/install/includes/linux-install-snap.md b/docs/core/install/includes/linux-install-snap.md deleted file mode 100644 index c55e43b9f1df3..0000000000000 --- a/docs/core/install/includes/linux-install-snap.md +++ /dev/null @@ -1,82 +0,0 @@ - -[.NET Core is available from the Snap Store.](https://snapcraft.io/dotnet-sdk) - -A snap is a bundle of an app and its dependencies that works without modification across many different Linux distributions. Snaps are discoverable and installable from the Snap Store. For more information about Snap, see [Getting started with Snap](https://snapcraft.io/docs/getting-started). - -Only supported versions of .NET Core are available through Snap. - -### Install the SDK - -Snap packages for .NET SDK are all published under the same identifier: `dotnet-sdk`. A specific version of the SDK can be installed by specifying the channel. The SDK includes the corresponding runtime. The following table lists the channels: - -| .NET version | Snap package | -|--------------|--------------------------| -| 5.0 | `5.0` or `latest/stable` | -| 3.1 (LTS) | `3.1` or `lts/stable` | -| 2.1 (LTS) | `2.1` | - -Use the `snap install` command to install a .NET SDK snap package. Use the `--channel` parameter to indicate which version to install. If this parameter is omitted, `latest/stable` is used. In this example, `5.0` is specified: - -```bash -sudo snap install dotnet-sdk --classic --channel=5.0 -``` - -Next, register the `dotnet` command for the system with the `snap alias` command: - -```bash -sudo snap alias dotnet-sdk.dotnet dotnet -``` - -This command is formatted as: `sudo snap alias {package}.{command} {alias}`. You can choose any `{alias}` name you would like. For example, you could name the command after the specific version installed by snap: `sudo snap alias dotnet-sdk.dotnet dotnet50`. When you use the command `dotnet50`, you'll invoke this specific version of .NET. But this is incompatible with most tutorials and examples as they expect a `dotnet` command to be available. - -### Install the runtime - -Snap packages for .NET Core Runtime are each published under their own package identifier. The following table lists the package identifiers: - -| .NET version | Snap package | -|-------------------|---------------------| -| 5.0 | `dotnet-runtime-50` | -| 3.1 (LTS) | `dotnet-runtime-31` | -| 3.0 | `dotnet-runtime-30` | -| 2.2 | `dotnet-runtime-22` | -| 2.1 (LTS) | `dotnet-runtime-21` | - -Use the `snap install` command to install a .NET Runtime snap package. In this example, .NET 5.0 is installed: - -```bash -sudo snap install dotnet-runtime-50 --classic -``` - -Next, register the `dotnet` command for the system with the `snap alias` command: - -```bash -sudo snap alias dotnet-runtime-50.dotnet dotnet -``` - -This command is formatted as: `sudo snap alias {package}.{command} {alias}`. You can choose any `{alias}` name you would like. For example, you could name the command after the specific version installed by snap: `sudo snap alias dotnet-runtime-50.dotnet dotnet50`. When you use the command `dotnet50`, you'll invoke this specific version of .NET. But this is incompatible with most tutorials and examples as they expect a `dotnet` command to be available. - -### SSL Certificate errors - -When .NET is installed through Snap, it's possible that on some distros the .NET SSL certificates may not be found and you may receive an error similar to the following during `restore`: - -```bash -Processing post-creation actions... -Running 'dotnet restore' on /home/myhome/test/test.csproj... - Restoring packages for /home/myhome/test/test.csproj... -/snap/dotnet-sdk/27/sdk/2.2.103/NuGet.targets(114,5): error : Unable to load the service index for source https://api.nuget.org/v3/index.json. [/home/myhome/test/test.csproj] -/snap/dotnet-sdk/27/sdk/2.2.103/NuGet.targets(114,5): error : The SSL connection could not be established, see inner exception. [/home/myhome/test/test.csproj] -/snap/dotnet-sdk/27/sdk/2.2.103/NuGet.targets(114,5): error : The remote certificate is invalid according to the validation procedure. [/home/myhome/test/test.csproj] -``` - -To resolve this issue, set a few environment variables: - -```bash -export SSL_CERT_FILE=[path-to-certificate-file] -export SSL_CERT_DIR=/dev/null -``` - -The certificate location will vary by distro. Here are the locations for the distros where we have experienced the issue. - -* Fedora - `/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem` -* OpenSUSE - `/etc/ssl/ca-bundle.pem` -* Solus - `/etc/ssl/certs/ca-certificates.crt` diff --git a/docs/core/install/includes/linux-not-supported-fedora.md b/docs/core/install/includes/linux-not-supported-fedora.md deleted file mode 100644 index b62710321c190..0000000000000 --- a/docs/core/install/includes/linux-not-supported-fedora.md +++ /dev/null @@ -1,2 +0,0 @@ - -❌ Please note that this version of Fedora is no longer supported. diff --git a/docs/core/install/includes/linux-rpm-install-dependencies.md b/docs/core/install/includes/linux-rpm-install-dependencies.md index e4dd8791f97e5..be83d2045bbc1 100644 --- a/docs/core/install/includes/linux-rpm-install-dependencies.md +++ b/docs/core/install/includes/linux-rpm-install-dependencies.md @@ -8,7 +8,7 @@ When you install with a package manager, these libraries are installed for you. If the target runtime environment's OpenSSL version is 1.1 or newer, you'll need to install **compat-openssl10**. -For more information about the dependencies, see [Self-contained Linux apps](https://github.com/dotnet/core/blob/master/Documentation/self-contained-linux-apps.md). +For more information about the dependencies, see [Self-contained Linux apps](https://github.com/dotnet/core/blob/main/Documentation/self-contained-linux-apps.md). For .NET Core apps that use the *System.Drawing.Common* assembly, you'll also need the following dependency: diff --git a/docs/core/install/linux-alpine.md b/docs/core/install/linux-alpine.md index 68453d113836e..3576aede4ace5 100644 --- a/docs/core/install/linux-alpine.md +++ b/docs/core/install/linux-alpine.md @@ -30,6 +30,7 @@ The following table is a list of currently supported .NET releases and the versi | Alpine | .NET Core 2.1 | .NET Core 3.1 | .NET 5.0 | |-------- |---------------|---------------|----------------| +| ✔️ 3.13 | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ✔️ 3.12 | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ✔️ 3.11 | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ✔️ 3.10 | ✔️ 2.1 | ✔️ 3.1 | ❌ 5.0 | @@ -49,12 +50,25 @@ The following versions of .NET are no longer supported. The downloads for these - icu-libs - krb5-libs - libgcc +- libgdiplus (if the .NET app requires the *System.Drawing.Common* assembly) - libintl - libssl1.1 (Alpine v3.9 or greater) - libssl1.0 (Alpine v3.8 or lower) - libstdc++ - zlib +To install the needed requirements, run the following command: + +```bash +apk add bash icu-libs krb5-libs libgcc libintl libssl1.1 libstdc++ zlib +``` + +To install **libgdiplus**, you may need to specify a repository: + +```bash +apk add libgdiplus --repository https://dl-3.alpinelinux.org/alpine/edge/testing/ +``` + ## Next steps - [How to enable TAB completion for the .NET CLI](../tools/enable-tab-autocomplete.md) diff --git a/docs/core/install/linux-centos.md b/docs/core/install/linux-centos.md index bc4182dd31fd1..68fa6bd44360b 100644 --- a/docs/core/install/linux-centos.md +++ b/docs/core/install/linux-centos.md @@ -71,6 +71,10 @@ This section provides information on common errors you may get while using the p [!INCLUDE [package-manager-failed-to-fetch-rpm](includes/package-manager-failed-to-fetch-rpm.md)] +### Errors related to missing `fxr`, `libhostfxr.so`, or `FrameworkList.xml` + +For more information about solving these problems, see [Troubleshoot `fxr`, `libhostfxr.so`, and `FrameworkList.xml` errors](linux-package-mixup.md). + ## Dependencies [!INCLUDE [linux-rpm-install-dependencies](includes/linux-rpm-install-dependencies.md)] diff --git a/docs/core/install/linux-debian.md b/docs/core/install/linux-debian.md index 01db556ab7723..30ef0722eb831 100644 --- a/docs/core/install/linux-debian.md +++ b/docs/core/install/linux-debian.md @@ -94,6 +94,8 @@ sudo apt-get update sudo apt-get upgrade ``` +If you've upgraded your Linux distribution since installing .NET, you may need to reconfigure the Microsoft package repository. Run the installation instructions for your current distribution version to upgrade to the appropriate package repository for .NET updates. + ## APT troubleshooting This section provides information on common errors you may get while using APT to install .NET. diff --git a/docs/core/install/linux-fedora.md b/docs/core/install/linux-fedora.md index 0842449a9e4ec..43e0620eab2e5 100644 --- a/docs/core/install/linux-fedora.md +++ b/docs/core/install/linux-fedora.md @@ -36,11 +36,11 @@ The following table is a list of currently supported .NET releases and the versi - A ❌ indicates that the version of Fedora or .NET isn't supported on that Fedora release. - When both a version of Fedora and a version of .NET have ✔️, that OS and .NET combination is supported. -| .NET Version | Fedora 33 ✔️ | 32 ✔️ | 31 ❌ | 30 ❌ | 29 ❌ | 28 ❌ | 27 ❌ | -| ------------ | ---------: | --: | --: | --: | --: | --: | --: | -| .NET 5.0 | ✔️ | ✔️ | ❌|❌ |❌ |❌ |❌ | -| .NET Core 3.1 | ✔️ | ✔️ | ✔️|✔️ |✔️ |❌ |❌ | -| .NET Core 2.1 | ✔️ | ✔️ | ✔️|✔️ |✔️ |✔️ |✔️ | +| .NET Version | Fedora 34 ✔️ | 33 ✔️ | 32 ✔️ | 31 ❌ | 30 ❌ | 29 ❌ | 28 ❌ | 27 ❌ | +| ------------ | ---------: | --: | --: | --: | --: | --: | --: | --: | +| .NET 5.0 | ✔️ | ✔️ | ✔️ | ❌|❌ |❌ |❌ |❌ | +| .NET Core 3.1 | ✔️ | ✔️ | ✔️ | ✔️|✔️ |✔️ |❌ |❌ | +| .NET Core 2.1 | ✔️ | ✔️ | ✔️ | ✔️|✔️ |✔️ |✔️ |✔️ | The following versions of .NET are no longer supported. The downloads for these still remain published: @@ -102,6 +102,10 @@ For more information on installing .NET without a package manager, see one of th [!INCLUDE [package-manager-failed-to-fetch-rpm](includes/package-manager-failed-to-fetch-rpm.md)] +### Errors related to missing `fxr`, `libhostfxr.so`, or `FrameworkList.xml` + +For more information about solving these problems, see [Troubleshoot `fxr`, `libhostfxr.so`, and `FrameworkList.xml` errors](linux-package-mixup.md). + ## Next steps - [How to enable TAB completion for the .NET CLI](../tools/enable-tab-autocomplete.md) diff --git a/docs/core/install/linux-opensuse.md b/docs/core/install/linux-opensuse.md index 5651f976371c3..33747907c01b4 100644 --- a/docs/core/install/linux-opensuse.md +++ b/docs/core/install/linux-opensuse.md @@ -76,7 +76,7 @@ When you install with a package manager, these libraries are installed for you. If the target runtime environment's OpenSSL version is 1.1 or newer, you'll need to install **compat-openssl10**. -For more information about the dependencies, see [Self-contained Linux apps](https://github.com/dotnet/core/blob/master/Documentation/self-contained-linux-apps.md). +For more information about the dependencies, see [Self-contained Linux apps](https://github.com/dotnet/core/blob/main/Documentation/self-contained-linux-apps.md). For .NET apps that use the *System.Drawing.Common* assembly, you'll also need the following dependency: diff --git a/docs/core/install/linux-package-mixup.md b/docs/core/install/linux-package-mixup.md new file mode 100644 index 0000000000000..539016cde5502 --- /dev/null +++ b/docs/core/install/linux-package-mixup.md @@ -0,0 +1,136 @@ +--- +title: Troubleshoot .NET Package Mix ups on Linux +description: Learn about how to troubleshoot strange .NET package errors on Linux. +author: omajid +ms.date: 05/12/2021 +no-loc: ['usr','lib64','share','dotnet','libhostfxr.so', 'fxr', 'FrameworkList.xml', 'System.IO.FileNotFoundException'] +--- + +# Troubleshoot _fxr_, _libhostfxr.so_, and _FrameworkList.xml_ errors + +When you try to use .NET 5+ (and .NET Core), commands such as `dotnet new` and `dotnet run` may fail with a message related to something not being found. Some of the error messages may be similar to the following: + +- **System.IO.FileNotFoundException** + + > System.IO.FileNotFoundException: Could not find file '/usr/share/dotnet/packs/Microsoft.NETCore.App.Ref/5.0.0/data/FrameworkList.xml'. + +- **A fatal error occurred.** + + > A fatal error occurred. The required library _libhostfxr.so_ could not be found. + + or + + > A fatal error occurred. The folder [/usr/share/dotnet/host/fxr] does not exist. + + or + + > A fatal error occurred, the folder [/usr/share/dotnet/host/fxr] does not contain any version-numbered child folders. + +- **Generic messages about dotnet not found** + + A general message may appear that indicates the SDK isn't found, or that the package has already been installed. + +One symptom of these problems is that both the `/usr/lib64/dotnet` and `/usr/share/dotnet` folders are on your system. + +## What's going on + +This generally happens when two Linux package repositories provide .NET packages. While Microsoft provides a Linux package repository to source .NET packages, some Linux distributions also provide .NET packages, such as: + +- Arch +- CentOS +- Fedora +- RHEL + +Mixing .NET packages from two different sources will most likely lead to issues since the packages may place things at different paths, and may be compiled differently. + +## Solutions + +The solution to these problems is to use .NET from one package repository. Which repository to pick, and how to do it, varies by use-case and the Linux distribution. + +If your distribution provides .NET packages, it's recommended that you use that package repository instead of Microsoft's. + +01. **I only use .NET and no other packages from the Microsoft repository, and my distribution provides .NET packages.** + + If you only use the Microsoft repository for .NET packages and not for any other Microsoft package such as `mdatp`, `powershell`, or `mssql`, then: + + 01. Remove the Microsoft repository + 01. Remove the .NET related packages from your OS + 01. Install the .NET packages from the distribution repository + + For Fedora, CentOS 8+, RHEL 8+, use the following bash commands: + + ```bash + sudo dnf remove packages-microsoft-prod + sudo dnf remove 'dotnet*' 'aspnet*' 'netstandard*' + sudo dnf install dotnet-sdk-5.0 + ``` + +02. **I want to use the distribution provided .NET packages, but I also use the Microsoft repository for other packages.** + + If you use the Microsoft repository for Microsoft packages such as `mdatp`, `powershell`, or `mssql`, but you don't want to use the repository for .NET, then: + + 01. Configure the Microsoft repository to exclude any .NET package + 01. Remove the .NET related packages from your OS + 01. Install the .NET packages from the distribution repository + + For Fedora, CentOS 8+, RHEL 8+, use the following bash commands: + + ```bash + echo 'excludepkgs=dotnet*,aspnet*,netstandard*' | sudo tee -a /etc/yum.repos.d/microsoft-prod.repo + sudo dnf remove 'dotnet*' 'aspnet*' 'netstandard*' + sudo dnf install dotnet-sdk-5.0 + ``` + +03. **I need a recent version of .NET that's not provided by the Linux distribution repositories.** + + In this case, keep the Microsoft repository, but configure it so .NET packages from the Microsoft repository are considered a higher priority. Then, remove the already-installed .NET packages and then re-install the .NET packages from the Microsoft repository. + + For Fedora, CentOS 8+, RHEL 8+, use the following bash commands: + + ```bash + echo 'priority=50' | sudo tee -a /etc/yum.repos.d/microsoft-prod.repo + sudo dnf remove 'dotnet*' 'aspnet*' 'netstandard*' + sudo dnf install dotnet-sdk-5.0 + ``` + +04. **I've encountered a bug in the Linux distribution version of .NET, I need the latest Microsoft version.** + + Use solution 3 to solve this problem. + +## Online references + +Many of these problems have been reported by users such as yourself. The following is a list of those issues. You can read through them for insights on what may be happening: + +- System.IO.FileNotFoundException and '/usr/share/dotnet/packs/Microsoft.NETCore.App.Ref/5.0.0/data/FrameworkList.xml' + + - [SDK #15785: unable to build brand new project after upgrading to 5.0.3](https://github.com/dotnet/sdk/issues/15785) + - [SDK #15863: "MSB4018 ResolveTargetingPackAssets task failed unexpectedly" after updating to 5.0.103](https://github.com/dotnet/sdk/issues/15863) + - [SDK #17411: dotnet build always throwing error](https://github.com/dotnet/sdk/issues/17411) + - [SDK #12075: dotnet 3.1.301 on Fedora 32 unable to find FrameworkList.xml because it doesn't exist](https://github.com/dotnet/sdk/issues/12075) + +- Fatal error: _libhostfxr.so_ couldn't be found + + - [SDK #17570: After updating Fedora 33 to 34 and dotnet 5.0.5 to 5.0.6 I get error regarding libhostfxr.so](https://github.com/dotnet/sdk/issues/17570): + +- Fatal error: folder _/host/fxr_ doesn't exist + + - [Core #5746: The folder does not exist when installing 3.1 on CentOS 8 with packages.microsoft.com repo enabled](https://github.com/dotnet/core/issues/5746) + - [SDK #15476: A fatal error occurred. The folder [/usr/share/dotnet/host/fxr] does not exist](https://github.com/dotnet/sdk/issues/15476): + +- Fatal error: folder _/host/fxr_ doesn't contain any version-numbered child folders + + - [Installer #9254: Error when install dotnet/core/aspnet:3.1 on CentOS 8 - Folder does not contain any version-numbered child folders](https://github.com/dotnet/installer/issues/9254) + - [StackOverflow: Error when install dotnet/core/aspnet:3.1 on CentOS 8 - Folder does not contain any version-numbered child folders](https://stackoverflow.com/questions/65422998/) + +- Generic errors without clear messages + + - [Core #4605: cannot run "dotnet new console"](https://github.com/dotnet/core/issues/4605) + - [Core #4644: Cannot install .NET Core SDK 2.1 on Fedora 32](https://github.com/dotnet/core/issues/4655) + - [Runtime #49375: After updating to 5.0.200-1 using package manager, it appears that no sdks are installed](https://github.com/dotnet/runtime/issues/49375) + +## Next steps + +- [Install .NET on Linux](linux.md) +- [How to remove the .NET Runtime and SDK](remove-runtime-sdk-versions.md?pivots=os-linux) +- [Tutorial: Create a new app with Visual Studio Code](../tutorials/with-visual-studio-code.md). +- [Tutorial: Containerize a .NET app](../docker/build-container.md). diff --git a/docs/core/install/linux-rhel.md b/docs/core/install/linux-rhel.md index d378c84b562e4..0dd8756bafb60 100644 --- a/docs/core/install/linux-rhel.md +++ b/docs/core/install/linux-rhel.md @@ -139,6 +139,14 @@ As an alternative to the ASP.NET Core Runtime, you can install the .NET Core Run Consult the [Red Hat documentation for .NET](https://access.redhat.com/documentation/net/5.0/) on the steps required to install other releases of .NET. +## Troubleshoot the package manager + +This section provides information on common errors you may get while using the package manager to install .NET or .NET Core. + +### Errors related to missing `fxr`, `libhostfxr.so`, or `FrameworkList.xml` + +For more information about solving these problems, see [Troubleshoot `fxr`, `libhostfxr.so`, and `FrameworkList.xml` errors](linux-package-mixup.md). + ## Next steps - [How to enable TAB completion for the .NET CLI](../tools/enable-tab-autocomplete.md) diff --git a/docs/core/install/linux-scripted-manual.md b/docs/core/install/linux-scripted-manual.md index 8d7643f3dcbf5..6dd260a5a69d3 100644 --- a/docs/core/install/linux-scripted-manual.md +++ b/docs/core/install/linux-scripted-manual.md @@ -40,7 +40,7 @@ It's possible that when you install .NET, specific dependencies may not be insta - [SLES](linux-sles.md#dependencies) - [Ubuntu](linux-ubuntu.md#dependencies) -For generic information about the dependencies, see [Self-contained Linux apps](https://github.com/dotnet/core/blob/master/Documentation/self-contained-linux-apps.md). +For generic information about the dependencies, see [Self-contained Linux apps](https://github.com/dotnet/core/blob/main/Documentation/self-contained-linux-apps.md). ### RPM dependencies @@ -77,6 +77,9 @@ For .NET apps that use the *System.Drawing.Common* assembly, you'll also need th The [dotnet-install scripts](../tools/dotnet-install-script.md) are used for automation and non-admin installs of the **SDK** and **Runtime**. You can download the script from . +> ![IMPORTANT] +> Bash is required to run the script. + The script defaults to installing the latest SDK [long term support (LTS)](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) version, which is .NET Core 3.1. To install the current release, which may not be an (LTS) version, use the `-c Current` parameter. ```bash diff --git a/docs/core/install/linux-sles.md b/docs/core/install/linux-sles.md index 4fe66f9a7744a..da39ff5c9a4b3 100644 --- a/docs/core/install/linux-sles.md +++ b/docs/core/install/linux-sles.md @@ -85,7 +85,7 @@ When you install with a package manager, these libraries are installed for you. If the target runtime environment's OpenSSL version is 1.1 or newer, you'll need to install **compat-openssl10**. -For more information about the dependencies, see [Self-contained Linux apps](https://github.com/dotnet/core/blob/master/Documentation/self-contained-linux-apps.md). +For more information about the dependencies, see [Self-contained Linux apps](https://github.com/dotnet/core/blob/main/Documentation/self-contained-linux-apps.md). For .NET apps that use the *System.Drawing.Common* assembly, you'll also need the following dependency: diff --git a/docs/core/install/linux-snap.md b/docs/core/install/linux-snap.md index cf75dc01a4eca..980f4e0a2e38e 100644 --- a/docs/core/install/linux-snap.md +++ b/docs/core/install/linux-snap.md @@ -83,6 +83,25 @@ sudo snap alias dotnet-runtime-50.dotnet dotnet The command is formatted as: `sudo snap alias {package}.{command} {alias}`. You can choose any `{alias}` name you would like. For example, you could name the command after the specific version installed by snap: `sudo snap alias dotnet-runtime-50.dotnet dotnet50`. When you use the command `dotnet50`, you'll invoke a specific version of .NET. But choosing a different alias is incompatible with most tutorials and examples as they expect a `dotnet` command to be available. +## Export the install location + +The `DOTNET_ROOT` environment variable is often used by tools to determine where .NET is installed. When .NET is installed through Snap, this environment variable isn't configured. You should configure the *DOTNET_ROOT* environment variable in your profile. The path to the snap uses the following format: `/snap/{package}/current`. For example, if you installed the `dotnet-sdk` snap, use the following command to set the environment variable to where .NET is located: + +```bash +export DOTNET_ROOT=/snap/dotnet-sdk/current +``` + +> [!TIP] +> The preceding `export` command only sets the environment variable for the terminal session in which it was run. +> +> You can edit your shell profile to permanently add the commands. There are a number of different shells available for Linux and each has a different profile. For example: +> +> - **Bash Shell**: *~/.bash_profile*, *~/.bashrc* +> - **Korn Shell**: *~/.kshrc* or *.profile* +> - **Z Shell**: *~/.zshrc* or *.zprofile* +> +> Edit the appropriate source file for your shell and add `export DOTNET_ROOT=/snap/dotnet-sdk/current`. + ## TLS/SSL Certificate errors When .NET is installed through Snap, it's possible that on some distros the .NET TLS/SSL certificates may not be found and you may receive an error during `restore`: diff --git a/docs/core/install/linux-ubuntu.md b/docs/core/install/linux-ubuntu.md index 5cf6a08a6df26..0996fa198e6de 100644 --- a/docs/core/install/linux-ubuntu.md +++ b/docs/core/install/linux-ubuntu.md @@ -24,6 +24,7 @@ The following table is a list of currently supported .NET releases and the versi | Ubuntu | .NET Core 2.1 | .NET Core 3.1 | .NET 5.0 | |--------------------------|---------------|---------------|----------------| +| ✔️ [21.04](#2104-) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ✔️ [20.10](#2010-) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ✔️ [20.04 (LTS)](#2004-) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ❌ [19.10](#1910-) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | @@ -45,6 +46,17 @@ The following versions of .NET are no longer supported. The downloads for these [!INCLUDE [package-manager uninstall notice](./includes/linux-uninstall-preview-info.md)] +## 21.04 ✔️ + +[!INCLUDE [linux-prep-intro-apt](includes/linux-prep-intro-apt.md)] + +```bash +wget https://packages.microsoft.com/config/ubuntu/21.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb +sudo dpkg -i packages-microsoft-prod.deb +``` + +[!INCLUDE [linux-apt-install-50](includes/linux-install-50-apt.md)] + ## 20.10 ✔️ [!INCLUDE [linux-prep-intro-apt](includes/linux-prep-intro-apt.md)] @@ -180,6 +192,8 @@ sudo apt-get update sudo apt-get upgrade ``` +If you've upgraded your Linux distribution since installing .NET, you may need to reconfigure the Microsoft package repository. Run the installation instructions for your current distribution version to upgrade to the appropriate package repository for .NET updates. + ## APT troubleshooting This section provides information on common errors you may get while using APT to install .NET. diff --git a/docs/core/install/linux.md b/docs/core/install/linux.md index 5e3c65d08a68c..e624072df55eb 100644 --- a/docs/core/install/linux.md +++ b/docs/core/install/linux.md @@ -50,6 +50,7 @@ The following table is a list of currently supported .NET releases and the versi | Alpine | .NET Core 2.1 | .NET Core 3.1 | .NET 5.0 | |-----------------------------|---------------|---------------|----------------| +| ✔️ [3.13](linux-alpine.md) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ✔️ [3.12](linux-alpine.md) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ✔️ [3.11](linux-alpine.md) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ✔️ [3.10](linux-alpine.md) | ✔️ 2.1 | ✔️ 3.1 | ❌ 5.0 | @@ -101,6 +102,7 @@ The following table is a list of currently supported .NET releases and the versi | Fedora | .NET Core 2.1 | .NET Core 3.1 | .NET 5.0 | |--------------------------|---------------|---------------|----------------| +| ✔️ [34](linux-fedora.md#install-net-50) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ✔️ [33](linux-fedora.md#install-net-50) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ✔️ [32](linux-fedora.md#install-net-50) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ❌ [31](linux-fedora.md#install-on-older-distributions) | ✔️ 2.1 | ✔️ 3.1 | ❌ 5.0 | @@ -169,6 +171,7 @@ The following table represents the support status of Ubuntu and .NET. | Ubuntu | .NET Core 2.1 | .NET Core 3.1 | .NET 5.0 | |--------------------------|---------------|---------------|----------------| +| ✔️ [21.04](linux-ubuntu.md#2104-) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ✔️ [20.10](linux-ubuntu.md#2010-) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ✔️ [20.04 (LTS)](linux-ubuntu.md#2004-) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | | ❌ [19.10](linux-ubuntu.md#1910-) | ✔️ 2.1 | ✔️ 3.1 | ✔️ 5.0 | diff --git a/docs/core/install/macos.md b/docs/core/install/macos.md index 0fa5808b5af76..f406bbb206db2 100644 --- a/docs/core/install/macos.md +++ b/docs/core/install/macos.md @@ -72,11 +72,11 @@ The SDK is used to build and publish .NET apps and libraries. Installing the SDK | .NET Core Version | macOS | Architectures | More information | | ----------------- | --------------------- | --------------| --- | -| 5.0 | High Sierra (10.13+) | x64 | [More information](https://github.com/dotnet/core/blob/master/release-notes/5.0/5.0-supported-os.md) | -| 3.1 | High Sierra (10.13+) | x64 | [More information](https://github.com/dotnet/core/blob/master/release-notes/3.1/3.1-supported-os.md) | -| 3.0 | High Sierra (10.13+) | x64 | [More information](https://github.com/dotnet/core/blob/master/release-notes/3.0/3.0-supported-os.md) | -| 2.2 | Sierra (10.12+) | x64 | [More information](https://github.com/dotnet/core/blob/master/release-notes/2.2/2.2-supported-os.md) | -| 2.1 | Sierra (10.12+) | x64 | [More information](https://github.com/dotnet/core/blob/master/release-notes/2.1/2.1-supported-os.md) | +| 5.0 | High Sierra (10.13+) | x64 | [More information](https://github.com/dotnet/core/blob/main/release-notes/5.0/5.0-supported-os.md) | +| 3.1 | High Sierra (10.13+) | x64 | [More information](https://github.com/dotnet/core/blob/main/release-notes/3.1/3.1-supported-os.md) | +| 3.0 | High Sierra (10.13+) | x64 | [More information](https://github.com/dotnet/core/blob/main/release-notes/3.0/3.0-supported-os.md) | +| 2.2 | Sierra (10.12+) | x64 | [More information](https://github.com/dotnet/core/blob/main/release-notes/2.2/2.2-supported-os.md) | +| 2.1 | Sierra (10.12+) | x64 | [More information](https://github.com/dotnet/core/blob/main/release-notes/2.1/2.1-supported-os.md) | Beginning with macOS Catalina (version 10.15), all software built after June 1, 2019 that is distributed with Developer ID, must be notarized. This requirement applies to the .NET runtime, .NET SDK, and software created with .NET. @@ -189,7 +189,7 @@ Containers provide a lightweight way to isolate your application from the rest o Microsoft provides images that are tailored for specific scenarios. For example, the [ASP.NET Core repository](https://hub.docker.com/_/microsoft-dotnet-aspnet) provides images that are built for running ASP.NET Core apps in production. -For more information about using .NET Core in a Docker container, see [Introduction to .NET and Docker](../docker/introduction.md) and [Samples](https://github.com/dotnet/dotnet-docker/blob/master/samples/README.md). +For more information about using .NET Core in a Docker container, see [Introduction to .NET and Docker](../docker/introduction.md) and [Samples](https://github.com/dotnet/dotnet-docker/blob/main/samples/README.md). ## Next steps @@ -199,9 +199,9 @@ For more information about using .NET Core in a Docker container, see [Introduct - [Tutorial: Create a new app with Visual Studio Code](../tutorials/with-visual-studio-code.md). - [Tutorial: Containerize a .NET Core app](../docker/build-container.md). -[release-notes-21]: https://github.com/dotnet/core/blob/master/release-notes/2.1/2.1-supported-os.md -[release-notes-31]: https://github.com/dotnet/core/blob/master/release-notes/3.1/3.1-supported-os.md -[release-notes-50]: https://github.com/dotnet/core/blob/master/release-notes/5.0/5.0-supported-os.md -[release-notes-20]: https://github.com/dotnet/core/blob/master/release-notes/2.0/2.0-supported-os.md -[release-notes-22]: https://github.com/dotnet/core/blob/master/release-notes/2.2/2.2-supported-os.md -[release-notes-30]: https://github.com/dotnet/core/blob/master/release-notes/3.0/3.0-supported-os.md +[release-notes-21]: https://github.com/dotnet/core/blob/main/release-notes/2.1/2.1-supported-os.md +[release-notes-31]: https://github.com/dotnet/core/blob/main/release-notes/3.1/3.1-supported-os.md +[release-notes-50]: https://github.com/dotnet/core/blob/main/release-notes/5.0/5.0-supported-os.md +[release-notes-20]: https://github.com/dotnet/core/blob/main/release-notes/2.0/2.0-supported-os.md +[release-notes-22]: https://github.com/dotnet/core/blob/main/release-notes/2.2/2.2-supported-os.md +[release-notes-30]: https://github.com/dotnet/core/blob/main/release-notes/3.0/3.0-supported-os.md diff --git a/docs/core/install/windows.md b/docs/core/install/windows.md index 29b8afa896056..7337a9a9bf50b 100644 --- a/docs/core/install/windows.md +++ b/docs/core/install/windows.md @@ -97,7 +97,7 @@ The following Windows versions are supported with .NET 5.0: | Windows Server Core | 2012 R2+ | x64, x86 | | Nano Server | Version 1809+ | x64 | -For more information about .NET 5.0 supported operating systems, distributions, and lifecycle policy, see [.NET 5.0 Supported OS Versions](https://github.com/dotnet/core/blob/master/release-notes/5.0/5.0-supported-os.md). +For more information about .NET 5.0 supported operating systems, distributions, and lifecycle policy, see [.NET 5.0 Supported OS Versions](https://github.com/dotnet/core/blob/main/release-notes/5.0/5.0-supported-os.md). # [.NET Core 3.1](#tab/netcore31) @@ -113,7 +113,7 @@ The following Windows versions are supported with .NET Core 3.1: | Windows Server | 2012 R2+ | x64, x86 | | Nano Server | Version 1803+ | x64, ARM32 | -For more information about .NET Core 3.1 supported operating systems, distributions, and lifecycle policy, see [.NET Core 3.1 Supported OS Versions](https://github.com/dotnet/core/blob/master/release-notes/3.1/3.1-supported-os.md). +For more information about .NET Core 3.1 supported operating systems, distributions, and lifecycle policy, see [.NET Core 3.1 Supported OS Versions](https://github.com/dotnet/core/blob/main/release-notes/3.1/3.1-supported-os.md). # [.NET Core 3.0](#tab/netcore30) @@ -131,7 +131,7 @@ The following Windows versions are supported with .NET Core 3.0: | Windows Server | 2012 R2+ | x64, x86 | | Nano Server | Version 1803+ | x64, ARM32 | -For more information about .NET Core 3.0 supported operating systems, distributions, and lifecycle policy, see [.NET Core 3.0 Supported OS Versions](https://github.com/dotnet/core/blob/master/release-notes/3.0/3.0-supported-os.md). +For more information about .NET Core 3.0 supported operating systems, distributions, and lifecycle policy, see [.NET Core 3.0 Supported OS Versions](https://github.com/dotnet/core/blob/main/release-notes/3.0/3.0-supported-os.md). # [.NET Core 2.2](#tab/netcore22) @@ -149,7 +149,7 @@ The following Windows versions are supported with .NET Core 2.2: | Windows Server | 2008 R2 SP1+ | x64, x86 | | Nano Server | Version 1803+ | x64, ARM32 | -For more information about .NET Core 2.2 supported operating systems, distributions, and lifecycle policy, see [.NET Core 2.2 Supported OS Versions](https://github.com/dotnet/core/blob/master/release-notes/2.2/2.2-supported-os.md). +For more information about .NET Core 2.2 supported operating systems, distributions, and lifecycle policy, see [.NET Core 2.2 Supported OS Versions](https://github.com/dotnet/core/blob/main/release-notes/2.2/2.2-supported-os.md). # [.NET Core 2.1](#tab/netcore21) @@ -165,7 +165,7 @@ The following Windows versions are supported with .NET Core 2.1: | Windows Server | 2008 R2 SP1+ | x64, x86 | | Nano Server | Version 1803+ | x64, | -For more information about .NET Core 2.1 supported operating systems, distributions, and lifecycle policy, see [.NET Core 2.1 Supported OS Versions](https://github.com/dotnet/core/blob/master/release-notes/2.1/2.1-supported-os.md). +For more information about .NET Core 2.1 supported operating systems, distributions, and lifecycle policy, see [.NET Core 2.1 Supported OS Versions](https://github.com/dotnet/core/blob/main/release-notes/2.1/2.1-supported-os.md). ### Offline install for Windows 7 @@ -324,7 +324,7 @@ Containers provide a lightweight way to isolate your application from the rest o Microsoft provides images that are tailored for specific scenarios. For example, the [ASP.NET Core repository](https://hub.docker.com/_/microsoft-dotnet-aspnet) provides images that are built for running ASP.NET Core apps in production. -For more information about using .NET in a Docker container, see [Introduction to .NET and Docker](../docker/introduction.md) and [Samples](https://github.com/dotnet/dotnet-docker/blob/master/samples/README.md). +For more information about using .NET in a Docker container, see [Introduction to .NET and Docker](../docker/introduction.md) and [Samples](https://github.com/dotnet/dotnet-docker/blob/main/samples/README.md). ## Next steps diff --git a/docs/core/introduction.md b/docs/core/introduction.md index 7cf9e89b1f2eb..9df052c462409 100644 --- a/docs/core/introduction.md +++ b/docs/core/introduction.md @@ -4,6 +4,7 @@ description: Learn about .NET, a free, open-source development platform for buil author: tdykstra ms.date: 11/16/2020 ms.custom: "updateeachrelease" +recommendations: false --- # Introduction to .NET @@ -48,13 +49,13 @@ Supported processor architectures include: .NET lets you use platform-specific capabilities, such as operating system APIs. Examples are Windows Forms and WPF on Windows and the native bindings to each mobile platform from Xamarin. -For more information, see [Supported OS lifecycle policy](https://github.com/dotnet/core/blob/master/os-lifecycle-policy.md) and [.NET RID Catalog](rid-catalog.md). +For more information, see [Supported OS lifecycle policy](https://github.com/dotnet/core/blob/main/os-lifecycle-policy.md) and [.NET RID Catalog](rid-catalog.md). ## Open source -.NET is open source, using [MIT and Apache 2 licenses](https://github.com/dotnet/runtime/blob/master/LICENSE.TXT). .NET is a project of the [.NET Foundation](https://dotnetfoundation.org/). +.NET is open source, using [MIT and Apache 2 licenses](https://github.com/dotnet/runtime/blob/main/LICENSE.TXT). .NET is a project of the [.NET Foundation](https://dotnetfoundation.org/). -For more information, see the [list of project repositories on GitHub.com](https://github.com/dotnet/core/blob/master/Documentation/core-repos.md). +For more information, see the [list of project repositories on GitHub.com](https://github.com/dotnet/core/blob/main/Documentation/core-repos.md). ## Support @@ -91,7 +92,7 @@ For more information, see [Releases and support for .NET Core and .NET 5](releas Here are some of the capabilities that .NET languages support: * [Type safety](../standard/base-types/common-type-system.md) -* Type inference - [C#](../csharp/programming-guide/types/index.md#specifying-types-in-variable-declarations), [F#](../fsharp/language-reference/type-inference.md), [Visual Basic](../visual-basic/programming-guide/language-features/variables/local-type-inference.md) +* Type inference - [C#](../csharp/fundamentals/types/index.md#specifying-types-in-variable-declarations), [F#](../fsharp/language-reference/type-inference.md), [Visual Basic](../visual-basic/programming-guide/language-features/variables/local-type-inference.md) * [Generic types](../standard/generics.md) * [Delegates](../standard/delegates-lambdas.md) * [Lambdas](../standard/delegates-lambdas.md) @@ -277,7 +278,7 @@ Here are some examples of types defined in the .NET runtime libraries: * [Serialization](../standard/serialization/index.md) utility types, such as and . * High-performance types, such as , , and [Pipelines](../standard/io/pipelines.md). -For more information, see the [Runtime libraries overview](../standard/runtime-libraries-overview.md). The source code for the libraries is in [the GitHub dotnet/runtime repository](https://github.com/dotnet/runtime/tree/master/src/libraries). +For more information, see the [Runtime libraries overview](../standard/runtime-libraries-overview.md). The source code for the libraries is in [the GitHub dotnet/runtime repository](https://github.com/dotnet/runtime/tree/main/src/libraries). ### Extensions to the runtime libraries @@ -379,7 +380,7 @@ For more information, see [Native interoperability](../standard/native-interop/i Depending on language support, the CLR lets you access native memory and do pointer arithmetic via `unsafe` code. These operations are needed for certain algorithms and system interoperability. Although powerful, use of unsafe code is discouraged unless it's necessary to interoperate with system APIs or implement the most efficient algorithm. Unsafe code may not execute the same way in different environments and also loses the benefits of a garbage collector and type safety. It's recommended to confine and centralize unsafe code as much as possible and test that code thoroughly. -For more information, see [Unsafe code and pointers](../csharp/programming-guide/unsafe-code-pointers/index.md). +For more information, see [Unsafe code and pointers](../csharp/language-reference/unsafe-code.md). ## Next steps @@ -387,7 +388,7 @@ For more information, see [Unsafe code and pointers](../csharp/programming-guide > [Choose a .NET tutorial](tutorials/index.md) > [!div class="nextstepaction"] -> [Try .NET in your browser](../csharp/tutorials/intro-to-csharp/numbers-in-csharp.yml) +> [Try .NET in your browser](../csharp/tour-of-csharp/tutorials/numbers-in-csharp.yml) > [!div class="nextstepaction"] > [Take a tour of C#](../csharp/tour-of-csharp/index.md) diff --git a/docs/core/migration/20-21.md b/docs/core/migration/20-21.md deleted file mode 100644 index 01e2c93800323..0000000000000 --- a/docs/core/migration/20-21.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Migrate from .NET Core 2.0 to 2.1 -description: Learn how to upgrade your .NET Core 2.0 app to 2.1. -ms.date: 08/06/2018 ---- -# Migrate from .NET Core 2.0 to 2.1 - -This article shows you the basic steps for migrating your .NET Core 2.0 app to 2.1. If you're looking to migrate your ASP.NET Core app to 2.1, see [Migrate from ASP.NET Core 2.0 to 2.1](/aspnet/core/migration/20_21). - -For an overview of the new features in .NET Core 2.1, see [What's new in .NET Core 2.1](../whats-new/dotnet-core-2-1.md). - -## Update the project file to use 2.1 versions - -- Open the project file (the \*.csproj, \*.vbproj, or \*.fsproj file). - -- Change the [target framework](../../standard/frameworks.md) value from `netcoreapp2.0` to `netcoreapp2.1`. The target framework is defined by the `` or `` element. - - For example, change `netcoreapp2.0` to `netcoreapp2.1`. - -- Remove `` references for tools that are bundled in the .NET Core 2.1 SDK (v 2.1.300 or later). These references include: - - - [dotnet-watch](https://github.com/dotnet/aspnetcore/blob/master/src/Tools/dotnet-watch/README.md) (Microsoft.DotNet.Watcher.Tools) - - [dotnet-user-secrets](https://github.com/dotnet/aspnetcore/blob/master/src/Tools/dotnet-user-secrets/README.md) (Microsoft.Extensions.SecretManager.Tools) - - [dotnet-sql-cache](https://github.com/dotnet/aspnetcore/blob/master/src/Tools/dotnet-sql-cache/README.md) (Microsoft.Extensions.Caching.SqlConfig.Tools) - - [dotnet-ef](/ef/core/miscellaneous/cli/dotnet) (Microsoft.EntityFrameworkCore.Tools.DotNet) - - In previous .NET Core SDK versions, the reference to one of these tools in your project file looks similar to the following example: - - ```xml - - ``` - - Since this entry isn't used by the .NET Core SDK any longer, you'll see a warning similar to the following if you still have references to one of these bundled tools in your project: - - `The tool 'Microsoft.EntityFrameworkCore.Tools.DotNet' is now included in the .NET Core SDK. Here is information on resolving this warning.` - - Removing the `` references for those tools from your project file fixes this issue. - -## See also - -- [Migrate from ASP.NET Core 2.0 to 2.1](/aspnet/core/migration/20_21) -- [What's new in .NET Core 2.1](../whats-new/dotnet-core-2-1.md) diff --git a/docs/core/migration/assembly-info.md b/docs/core/migration/assembly-info.md deleted file mode 100644 index c3b15ed1bed37..0000000000000 --- a/docs/core/migration/assembly-info.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: AssemblyInfo properties -description: Learn about assembly attributes and how they correspond to MSBuild properties in .NET Core 2.1 and later versions. -ms.topic: reference -ms.date: 01/08/2021 ---- -# Map AssemblyInfo attributes to properties - -[Assembly attributes](../../standard/assembly/set-attributes.md) that were typically present in an *AssemblyInfo* file in .NET Core 2.0 and earlier versions are automatically generated from MSBuild properties, starting in .NET Core 2.1. - -## Properties per attribute - -As shown in the following table, each attribute has a corresponding property that controls its content and another that disables its generation: - -| Attribute | Property | Property to disable | -|----------------------------------------------------------------|------------------------|-------------------------------------------------| -| | `Company` | `GenerateAssemblyCompanyAttribute` | -| | `Configuration` | `GenerateAssemblyConfigurationAttribute` | -| | `Copyright` | `GenerateAssemblyCopyrightAttribute` | -| | `Description` | `GenerateAssemblyDescriptionAttribute` | -| | `FileVersion` | `GenerateAssemblyFileVersionAttribute` | -| | `InformationalVersion` | `GenerateAssemblyInformationalVersionAttribute` | -| | `Product` | `GenerateAssemblyProductAttribute` | -| | `AssemblyTitle` | `GenerateAssemblyTitleAttribute` | -| | `AssemblyVersion` | `GenerateAssemblyVersionAttribute` | -| | `NeutralLanguage` | `GenerateNeutralResourcesLanguageAttribute` | - -Notes: - -- `AssemblyVersion` and `FileVersion` default to the value of `$(Version)` without the suffix. For example, if `$(Version)` is `1.2.3-beta.4`, then the value would be `1.2.3`. -- `InformationalVersion` defaults to the value of `$(Version)`. -- If the `$(SourceRevisionId)` property is present, it's appended to `InformationalVersion`. You can disable this behavior using `IncludeSourceRevisionInInformationalVersion`. -- `Copyright` and `Description` properties are also used for NuGet metadata. -- `Configuration`, which defaults to `Debug`, is shared with all MSBuild targets. You can set it via the `--configuration` option of `dotnet` commands, for example, [dotnet pack](../tools/dotnet-pack.md). - -## GenerateAssemblyInfo - -A Boolean that enables or disables the AssemblyInfo generation. The default value is `true`. - -## GeneratedAssemblyInfoFile - -The relative or absolute path of the generated assembly info file. Defaults to a file named *[project-name].AssemblyInfo.[cs|vb]* in the `$(IntermediateOutputPath)` (*obj*) directory. diff --git a/docs/core/native-interop/expose-components-to-com.md b/docs/core/native-interop/expose-components-to-com.md index 0a67b5b3c3a09..34522ad2e71b4 100644 --- a/docs/core/native-interop/expose-components-to-com.md +++ b/docs/core/native-interop/expose-components-to-com.md @@ -80,14 +80,32 @@ Open an elevated command prompt and run `regsvr32 ProjectName.comhost.dll`. That The resulting output will now also have a `ProjectName.X.manifest` file. This file is the side-by-side manifest for use with Registry-Free COM. +## Embedding type libraries in the COM host + +Unlike in .NET Framework, there is no support in .NET Core or .NET 5+ for generating a [COM Type Library (TLB)](/windows/win32/midl/com-dcom-and-type-libraries#type-library) from a .NET assembly. The guidance is to either manually write an IDL file or a C/C++ header for the native declarations of the COM interfaces. If you decide to write an IDL file, you can compile it with the Visual C++ SDK's MIDL compiler to produce a TLB. + +In .NET 6 Preview 5 and later versions, the .NET SDK supports embedding already-compiled TLBs into the COM host as part of your project build. + +To embed a type library into your application, follow these steps: + +1. Open the `.csproj` project file and add `` inside an `` tag. +2. Replace `` with a positive integer value. The value must be unique among the TLBs you specify to be embedded in the COM host. + - The `Id` attribute is optional if you only add one `ComHostTypeLibrary` to your project. + +For example, the following code block adds the `Server.tlb` type library at index `1` to the COM host: + +```xml + + + +``` + ## Sample -There is a fully functional [COM server sample](https://github.com/dotnet/samples/tree/master/core/extensions/COMServerDemo) in the dotnet/samples repository on GitHub. +There is a fully functional [COM server sample](https://github.com/dotnet/samples/tree/main/core/extensions/COMServerDemo) in the dotnet/samples repository on GitHub. ## Additional notes -Unlike in .NET Framework, there is no support in .NET Core for generating a COM Type Library (TLB) from a .NET Core assembly. The guidance is to either manually write an IDL file or a C/C++ header for the native declarations of the COM interfaces. - > [!IMPORTANT] > In .NET Framework, an "Any CPU" assembly can be consumed by both 32-bit and 64-bit clients. By default, in .NET Core, .NET 5, and later versions, "Any CPU" assemblies are accompanied by a 64-bit *\*.comhost.dll*. Because of this, they can only be consumed by 64-bit clients. That is the default because that is what the SDK represents. This behavior is identical to how the "self-contained" feature is published: by default it uses what the SDK provides. The `NETCoreSdkRuntimeIdentifier` MSBuild property determines the bitness of *\*.comhost.dll*. The managed part is actually bitness agnostic as expected, but the accompanying native asset defaults to the targeted SDK. diff --git a/docs/core/porting/cpp-cli.md b/docs/core/porting/cpp-cli.md index c50e76397930d..b7f6742e1ae8c 100644 --- a/docs/core/porting/cpp-cli.md +++ b/docs/core/porting/cpp-cli.md @@ -64,14 +64,14 @@ It's also possible to build C++/CLI projects without using MSBuild. Follow these 2. Reference necessary .NET Core reference assemblies. 3. When linking, provide the .NET Core app host directory as a `LibPath` (so that *ijwhost.lib* can be found). 4. Copy *ijwhost.dll* (from the .NET Core app host directory) to the project's output directory. -5. Make sure a [runtimeconfig.json](https://github.com/dotnet/cli/blob/master/Documentation/specs/runtime-configuration-file.md) file exists for the first component of the application that will run managed code. If the application has a managed entry point, a `runtime.config` file will be created and copied automatically. If the application has a native entry point, though, you need to create a `runtimeconfig.json` file for the first C++/CLI library to use the .NET Core runtime. +5. Make sure a [runtimeconfig.json](https://github.com/dotnet/sdk/blob/main/documentation/specs/runtime-configuration-file.md) file exists for the first component of the application that will run managed code. If the application has a managed entry point, a `runtime.config` file will be created and copied automatically. If the application has a native entry point, though, you need to create a `runtimeconfig.json` file for the first C++/CLI library to use the .NET Core runtime. ## Known issues -There are a couple known issues to look out for when working with C++/CLI projects targeting .NET Core. +There are a few known issues to look out for when working with C++/CLI projects targeting .NET Core. * A WPF framework reference in .NET Core C++/CLI projects currently causes some extraneous warnings about being unable to import symbols. These warnings can be safely ignored and should be fixed soon. -* If the application has a native entry point, the C++/CLI library that first executes managed code needs a [runtimeconfig.json](https://github.com/dotnet/cli/blob/master/Documentation/specs/runtime-configuration-file.md) file. This config file is used when the .NET Core runtime starts. C++/CLI projects don't create `runtimeconfig.json` files automatically at build time yet, so the file must be generated manually. If a C++/CLI library is called from a managed entry point, then the C++/CLI library doesn't need a `runtimeconfig.json` file (since the entry point assembly will have one that is used when starting the runtime). A simple sample `runtimeconfig.json` file is shown below. For more information, see the [spec on GitHub](https://github.com/dotnet/cli/blob/master/Documentation/specs/runtime-configuration-file.md). +* If the application has a native entry point, the C++/CLI library that first executes managed code needs a [runtimeconfig.json](https://github.com/dotnet/sdk/blob/main/documentation/specs/runtime-configuration-file.md) file. This config file is used when the .NET Core runtime starts. C++/CLI projects don't create `runtimeconfig.json` files automatically at build time yet, so the file must be generated manually. If a C++/CLI library is called from a managed entry point, then the C++/CLI library doesn't need a `runtimeconfig.json` file (since the entry point assembly will have one that is used when starting the runtime). A simple sample `runtimeconfig.json` file is shown below. For more information, see the [spec on GitHub](https://github.com/dotnet/sdk/blob/main/documentation/specs/runtime-configuration-file.md). ```json { @@ -84,3 +84,5 @@ There are a couple known issues to look out for when working with C++/CLI projec } } ``` + +* On Windows 7, loading a .NET Core C++/CLI assembly when the entry application is native may exhibit failing behavior. This failing behavior is due to the Windows 7 loader not respecting non-`mscoree.dll` entry points for C++/CLI assemblies. The recommended course of action is to convert the entry application to managed code. Scenarios involving Thread Local Storage (TLS) are specifically unsupported in all cases on Windows 7. diff --git a/docs/core/porting/index.md b/docs/core/porting/index.md index 13aba86ae9019..32294fa0ec8e8 100644 --- a/docs/core/porting/index.md +++ b/docs/core/porting/index.md @@ -1,116 +1,162 @@ --- -title: Port from .NET Framework to .NET Core -description: Understand the porting process and discover tools you may find helpful when porting a .NET Framework project to .NET Core. -author: cartermp -ms.date: 10/22/2019 +title: Port from .NET Framework to .NET 5 +description: Understand the porting process and discover tools you may find helpful when porting a .NET Framework project to .NET 5 (and .NET Core 3.1). +author: adegeo +ms.date: 05/04/2021 +no-loc: ["package.config", PackageReference] --- -# Overview of porting from .NET Framework to .NET Core +# Overview of porting from .NET Framework to .NET -You might have code that currently runs on the .NET Framework that you're interested in porting to .NET Core. This article provides: +This article provides an overview of what you should consider when porting your code from .NET Framework to .NET (formerly named .NET Core). Porting to .NET from .NET Framework for many projects is relatively straightforward. The complexity of your projects dictates how much work you'll do after the initial migration of the project files. -* An overview of the porting process. -* A list of tools that you may find helpful when you're porting your code to .NET Core. +Projects where the app-model is available in .NET (such as libraries, console apps, and desktop apps) usually require little change. Projects that require a new app model, such as moving to ASP.NET Core from ASP.NET, require more work. Many patterns from the old app model have equivalents that can be used during the conversion. -## Overview of the porting process +## Unavailable technologies -Porting to .NET Core (or .NET Standard) from .NET Framework for many projects is relatively straightforward. There are a number of changes that are required, but many of them follow the patterns outlined below. Projects where the app-model is available in .NET Core (such as libraries, console apps, and desktop applications) usually require little changes. Projects that require a new app model, such as moving to ASP.NET Core from ASP.NET, require a bit more work, but many patterns have analogs that can be used during the conversion. This document should help with identifying the main strategies that have been employed by users to successfully convert their code bases to target .NET Standard or .NET Core and will address the conversion at two levels: solution-wide and project specific. See the links at the bottom for directions on app-model specific conversions. +There are a few technologies in .NET Framework that don't exist in .NET: -We recommend you use the following process when porting your project to .NET Core. Each of these steps introduces potential places for behavior changes, so ensure that you adequately test your library or application before continuing on to later steps. The first steps are to get your project ready for a switch to .NET Standard or .NET Core. If you have unit tests, it's best to convert them first so that you can continue testing changes in the product you're working on. Because porting to .NET Core is such a significant change to your codebase, it's highly recommended to port your test projects so that you can run tests as you port your code over. MSTest, xUnit, and NUnit all work on .NET Core. +- [Application domains](net-framework-tech-unavailable.md#application-domains) -## Getting started + Creating additional application domains isn't supported. For code isolation, use separate processes or containers as an alternative. -The following tools will be used throughout the process: +- [Remoting](net-framework-tech-unavailable.md#remoting) -- Visual Studio 2019 -- Download [.NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md) -- _Optional_ Install [dotnet try-convert](https://github.com/dotnet/try-convert) + Remoting is used for communicating across application domains, which are no longer supported. For communication across processes, consider inter-process communication (IPC) mechanisms as an alternative to remoting, such as the class or the class. -## Porting a solution +- [Code access security (CAS)](net-framework-tech-unavailable.md#code-access-security-cas) -When there are multiple projects in a solution, the porting can seem more complicated because you must address projects in a specific order. The conversion process should be a bottom-up approach, where the projects with no dependencies on other projects in the solution are converted first, and continue up through the whole solution. + CAS was a sandboxing technique supported by .NET Framework but deprecated in .NET Framework 4.0. It was replaced by Security Transparency and it's not supported in .NET. Instead, use security boundaries provided by the operating system, such as virtualization, containers, or user accounts. -In order to identify the order projects should be migrated, you can use the following tools: +- [Security transparency](net-framework-tech-unavailable.md#security-transparency) -- [Dependency Diagrams in Visual Studio](/visualstudio/modeling/create-layer-diagrams-from-your-code) can create a directed graph of the code in a solution. -- Run `msbuild _SolutionPath_ /t:GenerateRestoreGraphFile /p:RestoreGraphOutputPath=graph.dg.json` to generate a json document that includes list of project references. -- Run [.NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md) with the `-r DGML` switch to retrieve a dependency diagram of the assemblies. For more information, see [here](../../standard/analyzers/portability-analyzer.md#solution-wide-view). + Similar to CAS, this sandboxing technique is no longer recommended for .NET Framework applications and it's not supported in .NET. Instead, use security boundaries provided by the operating system, such as virtualization, containers, or user accounts. + +- -Once you have dependency information, you can use that information to start at the leaf nodes and work your way up the dependency tree applying the steps in the next section. + (COM+) isn't supported in .NET. -## Per project steps +- Windows Workflow Foundation (WF) and Windows Communication Foundation (WCF) -We recommend you use the following process when porting your project to .NET Core: + WF and WCF aren't supported in .NET 5+ (including .NET Core). For alternatives, see [CoreWF](https://github.com/UiPath/corewf) and [CoreWCF](https://github.com/CoreWCF/CoreWCF). -1. Convert all of your `packages.config` dependencies to the [PackageReference](/nuget/consume-packages/package-references-in-project-files) format with the [conversion tool in Visual Studio](/nuget/consume-packages/migrate-packages-config-to-package-reference). +For more information about these unsupported technologies, see [.NET Framework technologies unavailable on .NET Core and .NET 5+](net-framework-tech-unavailable.md). - This step involves converting your dependencies from the legacy `packages.config` format. `packages.config` doesn't work on .NET Core, so this conversion is required if you have package dependencies. It also only requires the dependencies you are directly using in a project, which makes later steps easier by reducing the number of dependencies you must manage. +## Windows desktop technologies -1. Convert your project file to the new SDK-style files structure. You can create new projects for .NET Core and copy over source files, or attempt to convert your existing project file with a tool. +Many applications created for .NET Framework use a desktop technology such as Windows Forms or Windows Presentation Foundation (WPF). Both Windows Forms and WPF have been ported to .NET, but these remain Windows-only technologies. - .NET Core uses a simplified (and different) [project file format](../project-sdk/overview.md) than .NET Framework. You'll need to convert your project files into this format to continue. This project style allows you to also target .NET Framework, which at this point you'll still want to target. +Consider the following dependencies before you migrate a Windows Forms or WPF application: - You can attempt to port smaller solutions or individual projects in one operation to the .NET Core project file format with the [dotnet try-convert](https://github.com/dotnet/try-convert) tool. `dotnet try-convert` is not guaranteed to work for all your projects, and it may cause subtle changes in behavior that you depended on. Use it as a _starting point_ that automates the basic things that can be automated. It isn't a guaranteed solution to migrating a project, as there are many differences in the targets used by the SDK style projects compared to the old-style project files. +01. Project files for .NET use a different format than .NET Framework. +01. Your project may use an API that isn't available in .NET. +01. 3rd-party controls and libraries may not have been ported to .NET and remain only available to .NET Framework. +01. Your project uses a [technology that is no longer available](net-framework-tech-unavailable.md) in .NET. -1. Retarget all projects you wish to port to target .NET Framework 4.7.2 or higher. +.NET uses the open-source versions of Windows Forms and WPF and includes enhancements over .NET Framework. - This step ensures that you can use API alternatives for .NET Framework-specific targets when .NET Core doesn't support a particular API. +For tutorials on migrating your desktop application to .NET 5, see one of the following articles: -1. Update all dependencies to the latest version. Projects may be using older versions of libraries that may not have .NET Standard support. However, later versions may support it with a simple switch. This may require code changes if there are breaking changes in libraries. +- [Migrate .NET Framework WPF apps to .NET](/dotnet/desktop/wpf/migration/convert-project-from-net-framework?view=netdesktop-5.0&preserve-view=true) +- [Migrate .NET Framework Windows Forms apps to .NET](/dotnet/desktop/winforms/migration/?view=netdesktop-5.0&preserve-view=true) + +## Windows-specific APIs + +Applications can still P/Invoke native libraries on platforms supported by .NET. This technology isn't limited to Windows. However, if the library you're referencing is Windows-specific, such as a _user32.dll_ or _kernal32.dll_, then the code only works on Windows. For each platform you want your app to run on, you'll have to either find platform-specific versions, or make your code generic enough to run on all platforms. + +When porting an application from .NET Framework to .NET, your application probably used a library provided distributed with the .NET Framework. Many APIs that were available in .NET Framework weren't ported to .NET because they relied on Windows-specific technology, such as the Windows Registry or the GDI+ drawing model. + +The **Windows Compatibility Pack** provides a large portion of the .NET Framework API surface to .NET and is provided via the [Microsoft.Windows.Compatibility NuGet package](https://www.nuget.org/packages/Microsoft.Windows.Compatibility). + +For more information, see [Use the Windows Compatibility Pack to port code to .NET](windows-compat-pack.md). + +## .NET Framework compatibility mode + +The .NET Framework compatibility mode was introduced in .NET Standard 2.0. This compatibility mode allows .NET Standard and .NET 5+ (and .NET Core 3.1) projects to reference .NET Framework libraries on Windows-only. Referencing .NET Framework libraries doesn't work for all projects, such as if the library uses Windows Presentation Foundation (WPF) APIs, but it does unblock many porting scenarios. For more information, see the [Analyze your dependencies to port code from .NET Framework to .NET](third-party-deps.md#net-framework-compatibility-mode). + +## Cross-platform + +.NET (formerly known as .NET Core) is designed to be cross-platform. If your code doesn't depend on Windows-specific technologies, it may run on other platforms such as macOS, Linux, and Android. This includes project types like: + +- Libraries +- Console-based tools +- Automation +- ASP.NET sites + +.NET Framework is a Windows-only component. When your code uses Windows-specific technologies or APIs, such as Windows Forms and Windows Presentation Foundation (WPF), the code can still run on .NET but it won't run on other operating systems. + +It's possible that your library or console-based application can be used cross-platform without changing much. When porting to .NET, you may want to take this into consideration and test your application on other platforms. + +## The future of .NET Standard + +[.NET Standard](https://github.com/dotnet/standard) is a formal specification of .NET APIs that are available on multiple .NET implementations. The motivation behind .NET Standard was to establish greater uniformity in the .NET ecosystem. Starting with .NET 5, a different approach to establishing uniformity has been adopted, and this new approach eliminates the need for .NET Standard in many scenarios. For more information, see [.NET 5 and .NET Standard](../../standard/net-standard.md#net-5-and-net-standard). + +.NET Standard 2.0 was the last version to support .NET Framework. + +## Tools to assist porting + +Instead of manually porting an application from .NET Framework to .NET, you can use different tools to help automate some aspects of the migration. Porting a complex project is, in itself, a complex process. These tools may help in that journey. + +Even if you use a tool to help port your application, you should review the [Considerations when porting section](#considerations-when-porting) in this article. + +### .NET Upgrade Assistant + +The [.NET Upgrade Assistant](upgrade-assistant-overview.md) is a command-line tool that can be run on different kinds of .NET Framework apps. It's designed to assist with upgrading .NET Framework apps to .NET 5. After running the tool, **in most cases the app will require more effort to complete the migration**. The tool includes the installation of analyzers that can assist with completing the migration. This tool works on the following types of .NET Framework applications: + +- Windows Forms +- WPF +- ASP.NET MVC +- Console +- Class libraries + +This tool uses the other tools listed in this article and guides the migration process. For more information about the tool, see [Overview of the .NET Upgrade Assistant](upgrade-assistant-overview.md). + +### try-convert + +The try-convert tool is a .NET global tool that can convert a project or entire solution to the .NET SDK, including moving desktop apps to .NET 5. However, this tool isn't recommended if your project has a complicated build process such as custom tasks, targets, or imports. + +For more information, see the [try-convert GitHub repository](https://github.com/dotnet/try-convert). -1. Use the [.NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md) to analyze your assemblies and see if they're portable to .NET Core. +### .NET Portability Analyzer - The .NET Portability Analyzer tool analyzes your compiled assemblies and generates a report. This report shows a high-level portability summary and a breakdown of each API you're using that isn't available on .NET Core. While using the tool, only submit the individual project you are converting to focus on the API changes that are potentially needed. Many of the APIs have equivalent availability in .NET Core, which you'll want to switch to. +The .NET Portability Analyzer is a tool that analyzes assemblies and provides a detailed report on .NET APIs that are missing for the applications or libraries to be portable on your specified targeted .NET platforms. - While reading the reports generated by the analyzer, the important information is the actual APIs that are being used and not necessarily the percentage of support for the target platform. Many APIs have equivalent options in .NET Standard/Core, and so understanding the scenarios your library or application needs the API for will help determine the implication for portability. +To use the .NET Portability Analyzer in Visual Studio, install the [extension from the marketplace](https://marketplace.visualstudio.com/items?itemName=ConnieYau.NETPortabilityAnalyzer). - There are some cases where APIs are not equivalent and you'll need to do some compiler preprocessor directives (that is, `#if NET45`) to special case the platforms. At this point, your project will still be targeting .NET Framework. For each of these targeted cases, it is recommended to use well-known conditionals that can be understood as a scenario. For example, AppDomain support in .NET Core is limited, but for the scenario of loading and unloading assemblies, there is a new API that's not available in .NET Core. A common way to handle this in code would be something like this: +For more information, see [The .NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md). - ```csharp - #if FEATURE_APPDOMAIN_LOADING - // Code that uses appdomains - #elif FEATURE_ASSEMBLY_LOAD_CONTEXT - // Code that uses assembly load context - #else - #error Unsupported platform - #endif - ``` +### Platform compatibility analyzer -1. Install the [.NET API analyzer](../../standard/analyzers/api-analyzer.md) into your projects to identify APIs that throw on some platforms and some other potential compatibility issues. +The [Platform compatibility analyzer](../../standard/analyzers/platform-compat-analyzer.md) analyzes whether or not you're using an API that will throw a at run time. Although this isn't common if you're moving from .NET Framework 4.7.2 or higher, it's good to check. For more information about APIs that throw exceptions on .NET, see [APIs that always throw exceptions on .NET Core](../compatibility/unsupported-apis.md). - This tool is similar to the portability analyzer, but instead of analyzing if code can build on .NET Core, it analyzes whether you're using an API in a way that will throw a at run time. Although this isn't common if you're moving from .NET Framework 4.7.2 or higher, it's good to check. For more information about APIs that throw exceptions on .NET Core, see [APIs that always throw exceptions on .NET Core](../compatibility/unsupported-apis.md). +For more information, see [Platform compatibility analyzer](../../standard/analyzers/platform-compat-analyzer.md). -1. At this point, you can switch to targeting .NET Core (generally for applications) or .NET Standard (for libraries). +## Considerations when porting - The choice between .NET Core and .NET Standard is largely dependent on where the project will be run. If it is a library that will be consumed by other applications or distributed via NuGet, the preference is usually to target .NET Standard. However, there may be APIs that are only available on .NET Core for performance or other reasons; if that's the case, .NET Core should be targeted with potentially a .NET Standard build available as well with reduced performance or functionality. By targeting .NET Standard, the project will be ready to run on new platforms (such as WebAssembly). If the project has dependencies on specific app frameworks (such as ASP.NET Core), then the target will be limited by what the dependencies support. +When porting your application to .NET, consider the following suggestions in order. - If there are no preprocessor directives to conditional compile code for .NET Framework or .NET Standard, this will be as simple as finding the following in the project file: +✔️ CONSIDER using the [.NET Upgrade Assistant](upgrade-assistant-overview.md) to migrate your projects. Even though this tool is in preview, it automates most of the manual steps detailed in this article and gives you a great starting point for continuing your migration path. - ```xml - net472 - ``` +✔️ CONSIDER examining your dependencies first. Your dependencies must target .NET 5, .NET Standard, or .NET Core. - and switch it to the desired framework. For .NET Core 3.1, this would be: +✔️ DO migrate from a NuGet _packages.config_ file to [PackageReference](/nuget/consume-packages/package-references-in-project-files) settings in the project file. Use Visual Studio to [convert the _package.config_ file](/nuget/consume-packages/migrate-packages-config-to-package-reference#migration-steps). - ```xml - netcoreapp3.1 - ``` +✔️ CONSIDER upgrading to the latest project file format even if you can't yet port your app. .NET Framework projects use an outdated project format. Even though the latest project format, known as SDK-style projects, was created for .NET Core and beyond, they work with .NET Framework. Having your project file in the latest format gives you a good basis for porting your app in the future. - However, if this is a library for which you want to continue supporting .NET Framework-specific builds, you can [multi-target](../../standard/library-guidance/cross-platform-targeting.md) by replacing it with the following: +✔️ DO retarget your .NET Framework project to at least .NET Framework 4.7.2. This ensures the availability of the latest API alternatives for cases where .NET Standard doesn't support existing APIs. - ```xml - net472;netstandard2.0 - ``` +✔️ CONSIDER targeting .NET 5 instead of .NET Core 3.1. While .NET Core 3.1 is under long-term support (LTS), .NET 5 is the latest and .NET 6 will be LTS when released. - If you're using Windows-specific APIs (such as registry access), install the [Windows Compatibility Pack](./windows-compat-pack.md). +✔️ DO target .NET 5 for **Windows Forms and WPF** projects. .NET 5 contains many improvements for Desktop apps. -## Next steps +✔️ CONSIDER targeting .NET Standard 2.0 if you're migrating a library that may also be used with .NET Framework projects. You can also multitarget your library, targeting both .NET Framework and .NET Standard. -> [!div class="nextstepaction"] -> [Analyze dependencies](third-party-deps.md) -> [Package a NuGet package](../deploying/creating-nuget-packages.md) +✔️ DO add reference to the [Microsoft.Windows.Compatibility NuGet package](https://www.nuget.org/packages/Microsoft.Windows.Compatibility) if, after migrating, you get errors of missing APIs. A large portion of the .NET Framework API surface is available to .NET via the NuGet package. ## See also +- [Overview of the .NET Upgrade Assistant](upgrade-assistant-overview.md) - [ASP.NET to ASP.NET Core migration](/aspnet/core/migration/proper-to-2x) -- [Migrate WPF apps to .NET Core](/dotnet/desktop/wpf/migration/convert-project-from-net-framework) +- [Migrate .NET Framework WPF apps to .NET](/dotnet/desktop/wpf/migration/convert-project-from-net-framework?view=netdesktop-5.0&preserve-view=true) - [Migrate .NET Framework Windows Forms apps to .NET](/dotnet/desktop/winforms/migration/?view=netdesktop-5.0&preserve-view=true) +- [Port .NET Framework libraries to .NET](libraries.md) +- [.NET 5 vs. .NET Framework for server apps](../../standard/choosing-core-framework-server.md) diff --git a/docs/core/porting/libraries.md b/docs/core/porting/libraries.md index 4a777d1e9a646..f4067334a5961 100644 --- a/docs/core/porting/libraries.md +++ b/docs/core/porting/libraries.md @@ -1,34 +1,36 @@ --- -title: Port libraries to .NET Core -description: Learn how to port library projects from the .NET Framework to .NET Core. +title: Port libraries to .NET +description: Learn how to port library projects from the .NET Framework to .NET. author: cartermp -ms.date: 12/07/2018 +ms.date: 03/04/2021 --- -# Port .NET Framework libraries to .NET Core +# Port .NET Framework libraries to .NET -Learn how to port .NET Framework library code to .NET Core, where it runs cross-platform and expands the reach of the apps that use it. +Learn how to port .NET Framework library code to .NET, where it runs cross-platform and expands the reach of the apps that use it. ## Prerequisites This article assumes that you: -- Are using Visual Studio 2017 or later. (.NET Core isn't supported on earlier versions of Visual Studio.) +- Are using Visual Studio 2019 or later? + - .NET 5 requires Visual Studio 2019 (v16.9) or later. + - .NET Core 3.1 requires Visual Studio 2019 (v16.4) or later. - Understand the [recommended porting process](index.md). - Have resolved any issues with [third-party dependencies](third-party-deps.md). -You should also become familiar with the content of the following articles: +Familiarize yourself with the content of the following articles: -[.NET Standard](../../standard/net-standard.md)\ +- [.NET Standard.](../../standard/net-standard.md)\ This article describes the formal specification of .NET APIs that are intended to be available on all .NET implementations. -[Developing Libraries with Cross Platform Tools](../tutorials/libraries.md)\ -This article explains how to write libraries using the .NET Core CLI. +- [Develop libraries with the .NET CLI.](../tutorials/libraries.md)\ +This article explains how to write libraries using the .NET CLI. -[.NET project SDKs](../project-sdk/overview.md)\ +- [.NET project SDKs.](../project-sdk/overview.md)\ This article describes the SDK-style project file format. -[Porting to .NET Core - Analyzing your Third-Party Party Dependencies](third-party-deps.md)\ -This article discusses the portability of third-party dependencies and what to do when a NuGet package dependency doesn't run on .NET Core. +- [Analyze your dependencies to port code from .NET Framework to .NET.](third-party-deps.md)\ +This article discusses the portability of third-party dependencies, and what to do when a NuGet package dependency doesn't run on .NET. ## Retarget to .NET Framework 4.7.2 @@ -36,9 +38,9 @@ If your code isn't targeting .NET Framework 4.7.2, we recommended that you retar For each of the projects you wish to port, do the following in Visual Studio: -1. Right-click on the project and select **Properties**. -1. In the **Target Framework** dropdown, select **.NET Framework 4.7.2**. -1. Recompile the project. +01. Right-click on the project and select **Properties**. +01. In the **Target Framework** dropdown, select **.NET Framework 4.7.2**. +01. Recompile the project. Because your projects now target .NET Framework 4.7.2, use that version of the .NET Framework as your base for porting code. @@ -46,64 +48,70 @@ Because your projects now target .NET Framework 4.7.2, use that version of the . The next step is to run the API Portability Analyzer (ApiPort) to generate a portability report for analysis. -Make sure you understand the [API Portability Analyzer (ApiPort)](../../standard/analyzers/portability-analyzer.md) and how to generate portability reports for targeting .NET Core. How you do this likely varies based on your needs and personal tastes. The following sections detail a few different approaches. You may find yourself mixing steps of these approaches depending on how your code is structured. +Make sure you understand the [API Portability Analyzer (ApiPort)](../../standard/analyzers/portability-analyzer.md) and how to generate portability reports for targeting .NET. How you do this likely varies based on your needs and personal tastes. The following sections detail a few different approaches. You may find yourself mixing steps of these approaches depending on how your code is structured. ### Deal primarily with the compiler This approach works well for small projects or projects that don't use many .NET Framework APIs. The approach is simple: -1. Optionally, run ApiPort on your project. If you run ApiPort, gain knowledge from the report on issues you'll need to address. -1. Copy all of your code over into a new .NET Core project. -1. While referring to the portability report (if generated), solve compiler errors until the project fully compiles. +01. Optionally, run ApiPort on your project. If you run ApiPort, gain knowledge from the report on issues you'll need to address. +01. Copy all of your code over into a new .NET project. +01. While referring to the portability report (if generated), solve compiler errors until the project fully compiles. -Although it is unstructured, this code-focused approach often resolves issues quickly. A project that contains only data models might be an ideal candidate for this approach. +Although it's unstructured, this code-focused approach often resolves issues quickly. A project that contains only data models might be an ideal candidate for this approach. ### Stay on the .NET Framework until portability issues are resolved This approach might be the best if you prefer to have code that compiles during the entire process. The approach is as follows: -1. Run ApiPort on a project. -1. Address issues by using different APIs that are portable. -1. Take note of any areas where you're prevented from using a direct alternative. -1. Repeat the prior steps for all projects you're porting until you're confident each is ready to be copied over into a new .NET Core project. -1. Copy the code into a new .NET Core project. -1. Work out any issues where you noted that a direct alternative doesn't exist. +01. Run ApiPort on a project. +01. Address issues by using different APIs that are portable. +01. Take note of any areas where you're prevented from using a direct alternative. +01. Repeat the prior steps for all projects you're porting until you're confident each is ready to be copied over into a new .NET project. +01. Copy the code into a new .NET project. +01. Work out any issues where you noted that a direct alternative doesn't exist. This careful approach is more structured than simply working out compiler errors, but it's still relatively code-focused and has the benefit of always having code that compiles. The way you resolve certain issues that couldn't be addressed by just using another API varies greatly. You may find that you need to develop a more comprehensive plan for certain projects, which is covered in the next approach. ### Develop a comprehensive plan of attack -This approach might be best for larger and more complex projects, where restructuring code or completely rewriting certain areas of code might be necessary to support .NET Core. The approach is as follows: +This approach might be best for larger and more complex projects, where restructuring code or completely rewriting certain areas of code might be necessary to support .NET. The approach is as follows: -1. Run ApiPort on a project. -1. Understand where each non-portable type is used and how that affects overall portability. - - Understand the nature of those types. Are they small in number but used frequently? Are they large in number but used infrequently? Is their use concentrated, or is it spread throughout your code? - - Is it easy to isolate code that isn't portable so that you can deal with it more effectively? - - Do you need to refactor your code? - - For those types that aren't portable, are there alternative APIs that accomplish the same task? For example, if you're using the class, you might be able to use the class instead. - - Are there different portable APIs available to accomplish a task, even if it's not a drop-in replacement? For example, if you're using to parse XML but don't require XML schema discovery, you could use APIs and implement parsing yourself as opposed to relying on an API. -1. If you have assemblies that are difficult to port, is it worth leaving them on .NET Framework for now? Here are some things to consider: - - You may have some functionality in your library that's incompatible with .NET Core because it relies too heavily on .NET Framework or Windows-specific functionality. Is it worth leaving that functionality behind for now and releasing a temporary .NET Core version of your library with less features until resources are available to port the features? - - Would a refactor help? -1. Is it reasonable to write your own implementation of an unavailable .NET Framework API? - You could consider copying, modifying, and using code from the [.NET Framework reference source](https://github.com/Microsoft/referencesource). The reference source code is licensed under the [MIT License](https://github.com/Microsoft/referencesource/blob/master/LICENSE.txt), so you have significant freedom to use the source as a basis for your own code. Just be sure to properly attribute Microsoft in your code. -1. Repeat this process as needed for different projects. +01. Run ApiPort on a project. +01. Understand where each non-portable type is used and how that affects overall portability. -The analysis phase could take some time depending on the size of your codebase. Spending time in this phase to thoroughly understand the scope of changes needed and to develop a plan usually saves you time in the long run, particularly if you have a complex codebase. + - Understand the nature of those types. Are they small in number but used frequently? Are they large in number but used infrequently? Is their use concentrated, or is it spread throughout your code? + - Is it easy to isolate code that isn't portable so that you can deal with it more effectively? + - Do you need to refactor your code? + - For those types that aren't portable, are there alternative APIs that accomplish the same task? For example, if you're using the class, use the class instead. + - Are there different portable APIs available to accomplish a task, even if it's not a drop-in replacement? For example, if you're using to parse XML but don't require XML schema discovery, you could use APIs and implement parsing yourself instead of relying on an API. -Your plan could involve making significant changes to your codebase while still targeting .NET Framework 4.7.2, making this a more structured version of the previous approach. How you go about executing your plan is dependent on your codebase. +01. If you have assemblies that are difficult to port, is it worth leaving them on .NET Framework for now? Here are some things to consider: + + - You may have some functionality in your library that's incompatible with .NET because it relies too heavily on .NET Framework or Windows-specific functionality. Is it worth leaving that functionality behind for now and releasing a temporary .NET version of your library with fewer features until resources are available to port the features? + - Would a refactor help? + +01. Is it reasonable to write your own implementation of an unavailable .NET Framework API? + + You could consider copying, modifying, and using code from the [.NET Framework reference source](https://github.com/Microsoft/referencesource). The reference source code is licensed under the [MIT License](https://github.com/Microsoft/referencesource/blob/master/LICENSE.txt), so you have significant freedom to use the source as a basis for your own code. Just be sure to properly attribute Microsoft in your code. + +01. Repeat this process as needed for different projects. + +The analysis phase could take some time depending on the size of your codebase. Spending time in this phase to thoroughly understand the scope of changes needed and to develop a plan usually saves you time in the end, particularly if you have a complex codebase. + +Your plan could involve making significant changes to your codebase while still targeting .NET Framework 4.7.2. This is a more structured version of the previous approach. How you go about executing your plan is dependent on your codebase. ### Mixed approach -It's likely that you'll mix the above approaches on a per-project basis. You should do what makes the most sense to you and for your codebase. +It's likely that you'll mix the above approaches on a per-project basis. Do what makes the most sense to you and for your codebase. ## Port your tests -The best way to make sure everything works when you've ported your code is to test your code as you port it to .NET Core. To do this, you'll need to use a testing framework that builds and runs tests for .NET Core. Currently, you have three options: +The best way to make sure everything works when you've ported your code is to test your code as you port it to .NET. To do this, you'll need to use a testing framework that builds and runs tests for .NET. Currently, you have three options: - [xUnit](https://xunit.net/) - [Getting Started](https://xunit.net/docs/getting-started/netcore/cmdline) - - [Tool to convert an MSTest project to xUnit](https://github.com/dotnet/codeformatter/tree/master/src/XUnitConverter) + - [Tool to convert an MSTest project to xUnit](https://github.com/dotnet/codeformatter/tree/main/src/XUnitConverter) - [NUnit](https://nunit.org/) - [Getting Started](https://github.com/nunit/docs/wiki/Installation) - [Blog post about migrating from MSTest to NUnit](https://www.florian-rappl.de/News/Page/275/convert-mstest-to-nunit) @@ -113,15 +121,15 @@ The best way to make sure everything works when you've ported your code is to te Ultimately, the porting effort depends heavily on how your .NET Framework code is structured. A good way to port your code is to begin with the *base* of your library, which is the foundational components of your code. This might be data models or some other foundational classes and methods that everything else uses directly or indirectly. -1. Port the test project that tests the layer of your library that you're currently porting. -1. Copy over the base of your library into a new .NET Core project and select the version of .NET Standard you wish to support. -1. Make any changes needed to get the code to compile. Much of this may require adding NuGet package dependencies to your *csproj* file. -1. Run the tests and make any needed adjustments. -1. Pick the next layer of code to port over and repeat the prior steps. +01. Port the test project that tests the layer of your library that you're currently porting. +01. Copy over the base of your library into a new .NET project and select the version of .NET Standard you wish to support. +01. Make any changes needed to get the code to compile. Much of this may require adding NuGet package dependencies to your *csproj* file. +01. Run the tests and make any needed adjustments. +01. Pick the next layer of code to port over and repeat the prior steps. If you start with the base of your library and move outward from the base and test each layer as needed, porting is a systematic process where problems are isolated to one layer of code at a time. ## Next steps >[!div class="nextstepaction"] ->[Organize projects for .NET Core](project-structure.md) +>[Organize projects for .NET](project-structure.md) diff --git a/docs/core/porting/net-framework-tech-unavailable.md b/docs/core/porting/net-framework-tech-unavailable.md index 6ee1bba49b4e8..30c82a0d7a8d7 100644 --- a/docs/core/porting/net-framework-tech-unavailable.md +++ b/docs/core/porting/net-framework-tech-unavailable.md @@ -1,25 +1,26 @@ --- title: .NET Framework technologies unavailable on .NET Core and .NET 5+ titleSuffix: "" -description: Learn about .NET Framework technologies that are unavailable on .NET Core and .NET 5.0 and later versions. +description: Learn about .NET Framework technologies that are unavailable on .NET Core and .NET 5 and later versions. author: cartermp -ms.date: 01/26/2021 +ms.date: 05/21/2021 +ms.topic: reference --- # .NET Framework technologies unavailable on .NET Core and .NET 5+ -Several technologies available to .NET Framework libraries aren't available for use with .NET Core and .NET 5.0 and later versions, such as app domains, remoting, and code access security (CAS). If your libraries rely on one or more of the technologies listed on this page, consider the alternative approaches that are mentioned. +Several technologies available to .NET Framework libraries aren't available for use with .NET 5+ (and .NET Core), such as app domains, remoting, and code access security (CAS). If your libraries rely on one or more of the technologies listed on this page, consider the alternative approaches mentioned. For more information on API compatibility, see [Breaking changes in .NET](../compatibility/breaking-changes.md). ## Application domains -Application domains (AppDomains) isolate apps from one another. AppDomains require runtime support and are generally expensive. Creating additional app domains is not supported, and there are no plans to add this capability in the future. For code isolation, use separate processes or containers as an alternative. To dynamically load assemblies, use the class. +Application domains (AppDomains) isolate apps from one another. AppDomains require runtime support and are resource-expensive. Creating more app domains isn't supported, and there are no plans to add this capability in the future. For code isolation, use separate processes or containers as an alternative. To dynamically load assemblies, use the class. -To make code migration from .NET Framework easier, .NET 5+ exposes some of the API surface. Some of the APIs function normally (for example, ), some members do nothing (for example, ), and some of them throw (for example, ). Check the types you use against the [`System.AppDomain` reference source](https://github.com/dotnet/runtime/blob/master/src/libraries/System.Private.CoreLib/src/System/AppDomain.cs) in the [dotnet/runtime GitHub repository](https://github.com/dotnet/runtime). Make sure to select the branch that matches your implemented version. +To make code migration from .NET Framework easier, .NET 5+ exposes some of the API surface. Some of the APIs function normally (for example, ), some members do nothing (for example, ), and some of them throw (for example, ). Check the types you use against the [`System.AppDomain` reference source](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Private.CoreLib/src/System/AppDomain.cs) in the [dotnet/runtime GitHub repository](https://github.com/dotnet/runtime). Make sure to select the branch that matches your implemented version. ## Remoting -.NET remoting was identified as a problematic architecture. It's used for communicating across application domains, which are no longer supported. Also, remoting requires runtime support, which is expensive to maintain. For these reasons, .NET Remoting isn't supported on .NET Core and .NET 5+, and we don't plan on adding support for it in the future. +.NET Remoting isn't supported on .NET 5+ (and .NET Core). .NET remoting was identified as a problematic architecture. It's used for communicating across application domains, which are no longer supported. Also, remoting requires runtime support, which is expensive to maintain. For communication across processes, consider inter-process communication (IPC) mechanisms as an alternative to remoting, such as the class or the class. @@ -27,7 +28,7 @@ Across machines, use a network-based solution as an alternative. Preferably, use ## Code access security (CAS) -Sandboxing, which relies on the runtime or the framework to constrain which resources a managed application or library uses or runs, [isn't supported on .NET Framework](../../framework/misc/code-access-security.md) and therefore is also not supported on .NET Core and .NET 5+. There are too many cases in the .NET Framework and the runtime where an elevation of privileges occurs to continue treating CAS as a security boundary. In addition, CAS makes the implementation more complicated and often has correctness-performance implications for applications that don't intend to use it. +Sandboxing, which relies on the runtime or the framework to constrain which resources a managed application or library uses or runs, [isn't supported on .NET Framework](../../framework/misc/code-access-security.md) and therefore is also not supported on .NET Core and .NET 5+. There are too many cases in the .NET Framework and the runtime where an elevation of privileges occurs to continue treating CAS as a security boundary. Also, CAS makes the implementation more complicated and often has correctness-performance implications for applications that don't intend to use it. Use security boundaries provided by the operating system, such as virtualization, containers, or user accounts, for running processes with the minimum set of privileges. @@ -39,12 +40,24 @@ Use security boundaries provided by the operating system, such as virtualization ## System.EnterpriseServices - (COM+) is not supported by .NET Core and .NET 5+. + (COM+) isn't supported by .NET Core and .NET 5+. ## Workflow Foundation and WCF Windows Workflow Foundation (WF) and Windows Communication Foundation (WCF) are not supported in .NET 5+ (including .NET Core). For alternatives, see [CoreWF](https://github.com/UiPath/corewf) and [CoreWCF](https://github.com/CoreWCF/CoreWCF). +## Saving assemblies generated by reflection + +.NET 5+ (including .NET Core) does not support saving assemblies that are generated by the APIs. The method is not available in .NET 5+ (including .NET Core). In addition, the following fields of the enumeration aren't available: + +- +- +- + +As an alternative, consider the [ILPack library](https://github.com/Lokad/ILPack). + +For more information, see [dotnet/runtime issue 15704](https://github.com/dotnet/runtime/issues/15704). + ## See also -- [Overview of porting from .NET Framework to .NET Core](index.md) +- [Overview of porting from .NET Framework to .NET](index.md) diff --git a/docs/core/porting/project-structure.md b/docs/core/porting/project-structure.md index b176329f3b444..9a3e9574119fe 100644 --- a/docs/core/porting/project-structure.md +++ b/docs/core/porting/project-structure.md @@ -31,7 +31,7 @@ Consider the repository below: ![Existing project](./media/project-structure/existing-project-structure.png) -[**Source Code**](https://github.com/dotnet/samples/tree/master/framework/libraries/migrate-library/) +[**Source Code**](https://github.com/dotnet/samples/tree/main/framework/libraries/migrate-library/) The following describes several ways to add support for .NET Core for this repository depending on the constraints and complexity of the existing projects. @@ -41,11 +41,11 @@ Reorganize the repository so that any existing *\*.csproj* files are removed and ![Create a csproj that targets multiple frameworks](./media/project-structure/multi-targeted-project.png) -[**Source Code**](https://github.com/dotnet/samples/tree/master/framework/libraries/migrate-library-csproj/) +[**Source Code**](https://github.com/dotnet/samples/tree/main/framework/libraries/migrate-library-csproj/) Changes to note are: -- Replacement of *packages.config* and *\*.csproj* with a new [.NET Core *\*.csproj*](https://github.com/dotnet/samples/tree/master/framework/libraries/migrate-library-csproj/src/Car/Car.csproj). NuGet packages are specified with ` ItemGroup`. +- Replacement of *packages.config* and *\*.csproj* with a new [.NET Core *\*.csproj*](https://github.com/dotnet/samples/tree/main/framework/libraries/migrate-library-csproj/src/Car/Car.csproj). NuGet packages are specified with ` ItemGroup`. ## Keep existing projects and create a .NET Core project @@ -53,7 +53,7 @@ If there are existing projects that target older frameworks, you may want to lea ![.NET Core project with existing project in different folder](./media/project-structure/separate-projects-same-source.png) -[**Source Code**](https://github.com/dotnet/samples/tree/master/framework/libraries/migrate-library-csproj-keep-existing/) +[**Source Code**](https://github.com/dotnet/samples/tree/main/framework/libraries/migrate-library-csproj-keep-existing/) The .NET Core and existing projects are kept in separate folders. Keeping projects in separate folders avoids forcing you to have Visual Studio 2017 or later versions. You can create a separate solution that only opens the old projects. diff --git a/docs/core/porting/third-party-deps.md b/docs/core/porting/third-party-deps.md index 229d7fa3603a5..8ff65bee1ccff 100644 --- a/docs/core/porting/third-party-deps.md +++ b/docs/core/porting/third-party-deps.md @@ -1,22 +1,24 @@ --- -title: Analyze dependencies to port code to .NET Core -description: Learn how to analyze external dependencies in order to port your project from .NET Framework to .NET Core. +title: Analyze dependencies to port code +description: Learn how to analyze external dependencies to port your project from .NET Framework to .NET. author: cartermp -ms.date: 10/22/2019 +ms.date: 03/04/2021 --- -# Analyze your dependencies to port code to .NET Core +# Analyze your dependencies to port code from .NET Framework to .NET -To port your code to .NET Core or .NET Standard, you must understand your dependencies. External dependencies are the NuGet packages or `.dll` files you reference in your project, but that you don't build yourself. +To port your code to .NET or .NET Standard, you must understand your dependencies. External dependencies are the NuGet packages or `.dll` files you reference in your project, but that you don't build yourself. + +Porting your code to .NET Standard 2.0 or below ensures that it can be used with both .NET Framework and .NET. However, if you don't need to use the library with .NET Framework, consider targeting the latest version of .NET. ## Migrate your NuGet packages to `PackageReference` -.NET Core uses [PackageReference](/nuget/consume-packages/package-references-in-project-files) to specify package dependencies. If you're using [packages.config](/nuget/reference/packages-config) to specify your packages in your project, convert it to the `PackageReference` format, because `packages.config` isn't supported in .NET Core. +.NET can't use the [_packages.config_](/nuget/reference/packages-config) file for NuGet references. Both .NET and .NET Framework can use [PackageReference](/nuget/consume-packages/package-references-in-project-files) to specify package dependencies. If you're using _packages.config_ to specify your packages in your project, convert it to the `PackageReference` format. To learn how to migrate, see the [Migrate from packages.config to PackageReference](/nuget/reference/migrate-packages-config-to-package-reference) article. ## Upgrade your NuGet packages -After you migrate your project to the `PackageReference` format, verify if your packages are compatible with .NET Core. +After you migrate your project to the `PackageReference` format, verify if your packages are compatible with .NET. First, upgrade your packages to the latest version that you can. This can be done with the NuGet Package Manager UI in Visual Studio. It's likely that newer versions of your package dependencies are already compatible with .NET Core. @@ -42,13 +44,12 @@ The easiest way to inspect NuGet package folders is to use the [NuGet Package Ex 4. Select the package name from the search results and click **open**. 5. Expand the *lib* folder on the right-hand side and look at folder names. -Look for a folder with names using one the following patterns: `netstandardX.Y` or `netcoreappX.Y`. +Look for a folder with names using one the following patterns: `netstandardX.Y`, `netX.Y`, or `netcoreappX.Y`. -These values are the [Target Framework Monikers (TFMs)](../../standard/frameworks.md) that map to versions of [.NET Standard](../../standard/net-standard.md), .NET Core, and traditional Portable Class Library (PCL) profiles that are compatible with .NET Core. +These values are the [Target Framework Monikers (TFMs)](../../standard/frameworks.md) that map to versions of [.NET Standard](../../standard/net-standard.md), .NET, and .NET Core, which are all compatible with .NET. > [!IMPORTANT] -> When looking at the TFMs that a package supports, note that `netcoreapp*`, while compatible, is for .NET Core projects only and not for .NET Standard projects. -> A library that only targets `netcoreapp*` and not `netstandard*` can only be consumed by other .NET Core apps. +> When looking at the TFMs that a package supports, note that a TFM other than `netstandard*` targets a specific implementation of .NET, such as .NET 5, .NET Core, or .NET Framework. Starting with .NET 5, the `net*` TFM (without an operating system designation) effectively replaces `netstandard*` as a [portable target](../../standard/net-standard.md#net-5-and-net-standard). For example, `net5.0` targets the .NET 5 API surface and is cross-platform friendly, but `net5.0-windows` targets the .NET 5 API surface as implemented on the Windows operating system. ## .NET Framework compatibility mode @@ -56,7 +57,7 @@ After analyzing the NuGet packages, you might find that they only target the .NE Starting with .NET Standard 2.0, the .NET Framework compatibility mode was introduced. This compatibility mode allows .NET Standard and .NET Core projects to reference .NET Framework libraries. Referencing .NET Framework libraries doesn't work for all projects, such as if the library uses Windows Presentation Foundation (WPF) APIs, but it does unblock many porting scenarios. -When you reference NuGet packages that target .NET Framework in your project, such as [Huitian.PowerCollections](https://www.nuget.org/packages/Huitian.PowerCollections), you get a package fallback warning ([NU1701](/nuget/reference/errors-and-warnings/nu1701)) similar to the following example: +When you reference NuGet packages that target .NET Framework in your project, such as [`Huitian.PowerCollections`](https://www.nuget.org/packages/Huitian.PowerCollections), you get a package fallback warning ([NU1701](/nuget/reference/errors-and-warnings/nu1701)) similar to the following example: `NU1701: Package ‘Huitian.PowerCollections 1.0.0’ was restored using ‘.NETFramework,Version=v4.6.1’ instead of the project target framework ‘.NETStandard,Version=v2.0’. This package may not be fully compatible with your project.` @@ -72,7 +73,7 @@ To suppress the warning by editing the project file, find the `PackageReference` For more information on how to suppress compiler warnings in Visual Studio, see [Suppressing warnings for NuGet packages](/visualstudio/ide/how-to-suppress-compiler-warnings#suppress-warnings-for-nuget-packages). -## What to do when your NuGet package dependency doesn't run on .NET Core +## If NuGet packages won't run on .NET There are a few things you can do if a NuGet package you depend on doesn't run on .NET Core: @@ -88,11 +89,11 @@ If you can't resolve your issue with any of these options, you may have to port The .NET Team would like to know which libraries are the most important to support with .NET Core. You can send an email to dotnet@microsoft.com about the libraries you'd like to use. -## Analyze dependencies that aren't NuGet packages +## Analyze non-NuGet dependencies You may have a dependency that isn't a NuGet package, such as a DLL in the file system. The only way to determine the portability of that dependency is to run the [.NET Portability Analyzer](https://github.com/Microsoft/dotnet-apiport) tool. The tool analyzes assemblies that target the .NET Framework and identifies APIs that aren't portable to other .NET platforms such as .NET Core. You can run the tool as a console application or as a [Visual Studio extension](../../standard/analyzers/portability-analyzer.md). ## Next steps ->[!div class="nextstepaction"] ->[Port libraries](libraries.md) +- [Overview of porting from .NET Framework to .NET](index.md) +- [Port libraries](libraries.md) diff --git a/docs/core/porting/tools.md b/docs/core/porting/tools.md deleted file mode 100644 index e928b4e7b8692..0000000000000 --- a/docs/core/porting/tools.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Tools for porting to .NET Core -description: Learn about some of the tools you can use to port to .NET Core -author: cartermp -ms.date: 05/03/2020 ---- -# Tools to help with porting to .NET Core - -You may find the tools listed in this article helpful when porting: - -- [.NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md) - A toolchain that can generate a report of how portable your code is between .NET Framework and .NET Core: - - As a [command-line tool](https://github.com/Microsoft/dotnet-apiport/releases) - - As a [Visual Studio extension](https://marketplace.visualstudio.com/items?itemName=ConnieYau.NETPortabilityAnalyzer) -- [Platform compatibility analyzer](../../standard/analyzers/platform-compat-analyzer.md) - A Roslyn analyzer that informs developers when they use platform-specific APIs from call sites where the API might not be available. -- [.NET API analyzer](../../standard/analyzers/api-analyzer.md) - A Roslyn analyzer that can help detect platform compatibility issues in cross-platform apps and libraries. -- [try-convert](https://www.nuget.org/packages/try-convert/) - A .NET Core global tool that can convert a project or entire solution to the .NET SDK, including moving desktop apps to .NET Core. It is not recommended if you have a more complicated build established (such as custom tasks, targets, or imports), and it rejects many project types that are incompatible with .NET Core. diff --git a/docs/core/porting/upgrade-assistant-aspnetmvc.md b/docs/core/porting/upgrade-assistant-aspnetmvc.md index 9f1536c965653..f0674eb8e85d7 100644 --- a/docs/core/porting/upgrade-assistant-aspnetmvc.md +++ b/docs/core/porting/upgrade-assistant-aspnetmvc.md @@ -2,14 +2,14 @@ title: Upgrade ASP.NET MVC apps to .NET 5 description: Use the .NET Upgrade Assistant to upgrade an existing .NET Framework ASP.NET MVC app to .NET 5. The .NET Upgrade Assistant is a CLI tool that assists in migrating an app from .NET Framework to .NET 5. author: ardalis -ms.date: 02/25/2021 +ms.date: 03/08/2021 --- # Upgrade an ASP.NET MVC App to .NET 5 with the .NET Upgrade Assistant The [.NET Upgrade Assistant](upgrade-assistant-overview.md) is a command-line tool that can assist with upgrading .NET Framework ASP.NET MVC apps to .NET 5. This article provides: -* A demonstration of how to run the tool against a .NET Framework ASP.NET MVC app -* Troubleshooting tips +- A demonstration of how to run the tool against a .NET Framework ASP.NET MVC app +- Troubleshooting tips ## Upgrade .NET Framework ASP.NET MVC apps @@ -57,7 +57,7 @@ The tool prompts for a custom path for the backup, or to use the default, which Once the project format has been updated, the next step is to update the TFM of the project. -:::image type="content" source="media/upgrade-assistant-aspnetmvc/update-tfm.png" alt-text=".NET Upgrade Assistant convert project to SDK style"::: +:::image type="content" source="media/upgrade-assistant-aspnetmvc/update-tfm.png" alt-text=".NET Upgrade Assistant update TFM"::: Next, the tool updates the project's NuGet packages. Several packages need updates, and a new analyzer package is added. @@ -80,7 +80,7 @@ Next, the tool migrates config files. The tool identifies app settings and disab The tool completes the migration of config files by migrating `system.web.webPages.razor/pages/namespaces`. -:::image type="content" source="media/upgrade-assistant-aspnetmvc/migrate-config2.png" alt-text=".NET Upgrade Assistant migrate config"::: +:::image type="content" source="media/upgrade-assistant-aspnetmvc/migrate-config2.png" alt-text=".NET Upgrade Assistant migrate config completed"::: The tool applies known fixes to migrate C# references to their new counterparts. @@ -107,7 +107,7 @@ Once this process has completed, open the project file and review it. Look for s ``` -Static files that should be served by the web server should be moved to an appropriate folder within a root level folder named `wwwroot`. See [Static files in ASP.NET Core](/aspnet/core/fundamentals/static-files?view=aspnetcore-5.0) for details. Once the files have been moved, the `` elements in the project file corresponding to these files can be deleted. In fact, all `` elements and their containing groups can be removed. Also, any `` to a client-side library like `bootstrap` or `jQuery` should be removed. +Static files that should be served by the web server should be moved to an appropriate folder within a root level folder named `wwwroot`. See [Static files in ASP.NET Core](/aspnet/core/fundamentals/static-files?view=aspnetcore-5.0&preserve-view=true) for details. Once the files have been moved, the `` elements in the project file corresponding to these files can be deleted. In fact, all `` elements and their containing groups can be removed. Also, any `` to a client-side library like `bootstrap` or `jQuery` should be removed. By default, the project will be converted as a class library. Change the first line's `Sdk` attribute to `Microsoft.NET.Sdk.Web` and set the `` to `net5.0`. Compile the project. At this point, the number of errors should be fairly small. When porting a new ASP.NET 4.6.1 MVC project, the remaining errors refer to files in the `App_Start` folder: @@ -117,7 +117,7 @@ By default, the project will be converted as a class library. Change the first l These files - and the entire `App_Start` folder - can be deleted. Likewise, the `Global.asax` and `Global.asax.cs` files can be removed. -At this point the only errors that remain are related to bundling. There are [several ways to configure bundling and minification in ASP.NET Core](/aspnet/core/migration/mvc?view=aspnetcore-5.0#configure-bundling-and-minification). Choose whatever makes the most sense for your project. +At this point the only errors that remain are related to bundling. There are [several ways to configure bundling and minification in ASP.NET Core](/aspnet/core/migration/mvc?view=aspnetcore-5.0&preserve-view=true#configure-bundling-and-minification). Choose whatever makes the most sense for your project. ## Troubleshooting tips diff --git a/docs/core/porting/upgrade-assistant-overview.md b/docs/core/porting/upgrade-assistant-overview.md index c796b65bbdba5..64bc3cf68e4c7 100644 --- a/docs/core/porting/upgrade-assistant-overview.md +++ b/docs/core/porting/upgrade-assistant-overview.md @@ -2,14 +2,14 @@ title: Overview of the .NET Upgrade Assistant description: Introducing the .NET Upgrade Assistant tool that helps migrate from .NET Framework and upgrades your projects to .NET 5. author: ardalis -ms.date: 02/25/2021 +ms.date: 03/08/2021 --- # Overview of the .NET Upgrade Assistant You might have apps that currently run on the .NET Framework that you're interested in porting to .NET 5. The .NET Upgrade Assistant tool can assist with this process. This article provides: -* An overview of the .NET Upgrade Assistant. -* How to install the .NET Upgrade Assistant. +- An overview of the .NET Upgrade Assistant. +- How to install the .NET Upgrade Assistant. ## What is the .NET Upgrade Assistant @@ -38,9 +38,17 @@ The [Get Started tutorial](https://aka.ms/dotnet-upgrade-assistant-install) walk ### Installation steps -The tool can be installed as a .NET CLI tool by running: `dotnet tool install -g upgrade-assistant --add-source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json` +The tool can be installed as a .NET CLI tool by running: -Similarly, because the .NET Upgrade Assistant is installed as a .NET CLI tool, it can be easily updated by running: `https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json` +```dotnet +dotnet tool install -g upgrade-assistant +``` + +Similarly, because the .NET Upgrade Assistant is installed as a .NET CLI tool, it can be easily updated by running: + +```dotnet +dotnet tool update -g upgrade-assistant +``` For detailed installation instructions, please refer to the project's [README](https://github.com/dotnet/upgrade-assistant). diff --git a/docs/core/porting/upgrade-assistant-winforms-framework.md b/docs/core/porting/upgrade-assistant-winforms-framework.md index e104c8e18cb75..c632a61741b2a 100644 --- a/docs/core/porting/upgrade-assistant-winforms-framework.md +++ b/docs/core/porting/upgrade-assistant-winforms-framework.md @@ -2,14 +2,14 @@ title: Upgrade Windows Forms apps to .NET 5 description: Use the .NET Upgrade Assistant to upgrade an existing .NET Framework Windows Forms app to .NET 5. The .NET Upgrade Assistant is a CLI tool that helps migrating an app from .NET Framework to .NET 5. author: ardalis -ms.date: 02/25/2021 +ms.date: 03/08/2021 --- # Upgrade a Windows Forms App to .NET 5 with the .NET Upgrade Assistant The [.NET Upgrade Assistant](upgrade-assistant-overview.md) is a command-line tool that can assist with upgrading .NET Framework Windows Forms (WinForms) apps to .NET 5. This article provides: -* A demonstration of how to run the tool against a .NET Framework Windows Forms app -* Troubleshooting tips +- A demonstration of how to run the tool against a .NET Framework Windows Forms app +- Troubleshooting tips ## Upgrade .NET Framework Windows Forms apps @@ -53,7 +53,7 @@ The tool prompts for a custom path for the backup, or to use the default, which Once the project format has been updated, the next step is to update the TFM of the project. -:::image type="content" source="media/upgrade-assistant-winforms-framework/update-tfm.png" alt-text=".NET Upgrade Assistant convert project to SDK style"::: +:::image type="content" source="media/upgrade-assistant-winforms-framework/update-tfm.png" alt-text=".NET Upgrade Assistant update TFM"::: Next, the tool updates the project's NuGet packages. diff --git a/docs/core/porting/upgrade-assistant-wpf-framework.md b/docs/core/porting/upgrade-assistant-wpf-framework.md index 171ea5c5b9557..8cbb6a9e743d6 100644 --- a/docs/core/porting/upgrade-assistant-wpf-framework.md +++ b/docs/core/porting/upgrade-assistant-wpf-framework.md @@ -2,14 +2,14 @@ title: Upgrade WPF apps to .NET 5 description: Use the .NET Upgrade Assistant to upgrade an existing .NET Framework WPF app to .NET 5. The .NET Upgrade Assistant is a CLI tool that helps migrating an app from .NET Framework to .NET 5. author: ardalis -ms.date: 02/25/2021 +ms.date: 03/08/2021 --- # Upgrade a WPF App to .NET 5 with the .NET Upgrade Assistant The [.NET Upgrade Assistant](upgrade-assistant-overview.md) is a command-line tool that can assist with upgrading .NET Framework WPF apps to .NET 5. This article provides: -* A demonstration of how to run the tool against a .NET Framework WPF app -* Troubleshooting tips +- A demonstration of how to run the tool against a .NET Framework WPF app +- Troubleshooting tips ## Upgrade .NET Framework WPF apps @@ -53,7 +53,7 @@ The tool prompts for a custom path for the backup, or to use the default, which Once the project format has been updated, the next step is to update the TFM of the project. -:::image type="content" source="media/upgrade-assistant-wpf-framework/update-tfm.png" alt-text=".NET Upgrade Assistant convert project to SDK style"::: +:::image type="content" source="media/upgrade-assistant-wpf-framework/update-tfm.png" alt-text=".NET Upgrade Assistant update TFM"::: Next, the tool updates the project's NuGet packages. diff --git a/docs/core/porting/windows-compat-pack.md b/docs/core/porting/windows-compat-pack.md index 606faaac18de2..2ea95d4a81578 100644 --- a/docs/core/porting/windows-compat-pack.md +++ b/docs/core/porting/windows-compat-pack.md @@ -1,20 +1,20 @@ --- -title: Use the Windows Compatibility Pack to port code to .NET Core -description: Learn about the Windows Compatibility Pack and how can you use it to port existing .NET Framework code to .NET Core. +title: Use the Windows Compatibility Pack to port code +description: Learn about the Windows Compatibility Pack and how can you use it to port existing .NET Framework code to .NET 5 and .NET Core 3.1. author: terrajobst -ms.date: 12/07/2018 +ms.date: 05/04/2021 --- -# Use the Windows Compatibility Pack to port code to .NET Core +# Use the Windows Compatibility Pack to port code to .NET 5+ -Some of the most common issues found when porting existing code to .NET Core are dependencies on APIs and technologies that are only found in .NET Framework. The *Windows Compatibility Pack* provides many of these technologies, so it's much easier to build .NET Core applications and .NET Standard libraries. +Some of the most common issues found when porting existing code from .NET Framework to .NET are dependencies on APIs and technologies that are only found in .NET Framework. The *Windows Compatibility Pack* provides many of these technologies, so it's much easier to build .NET applications and .NET Standard libraries. -The compatibility pack is a logical [extension of .NET Standard 2.0](../whats-new/dotnet-core-2-0.md#api-changes-and-library-support) that significantly increases the API set. Existing code compiles with almost no modifications. To keep its promise of "the set of APIs that all .NET implementations provide", .NET Standard doesn't include technologies that can't work across all platforms, such as registry, Windows Management Instrumentation (WMI), or reflection emit APIs. The Windows Compatibility Pack sits on top of .NET Standard and provides access to these Windows-only technologies. It's especially useful for customers that want to move to .NET Core but plan to stay on Windows, at least as a first step. In that scenario, being able to use Windows-only technologies removes the migration hurdle. +The compatibility pack is a logical [extension of .NET Standard 2.0](../whats-new/dotnet-core-2-0.md#api-changes-and-library-support) that significantly increases the API set. Existing code compiles with almost no modifications. To keep its promise of "the set of APIs that all .NET implementations provide", .NET Standard doesn't include technologies that can't work across all platforms, such as registry, Windows Management Instrumentation (WMI), or reflection emit APIs. The Windows Compatibility Pack sits on top of .NET Standard and provides access to these Windows-only technologies. It's especially useful for customers that want to move to .NET but plan to stay on Windows, at least as a first step. In that scenario, you can use Windows-only technologies removes the migration hurdle. ## Package contents -The Windows Compatibility Pack is provided via the [Microsoft.Windows.Compatibility NuGet package](https://www.nuget.org/packages/Microsoft.Windows.Compatibility) and can be referenced from projects that target .NET Core or .NET Standard. +The Windows Compatibility Pack is provided via the [Microsoft.Windows.Compatibility NuGet package](https://www.nuget.org/packages/Microsoft.Windows.Compatibility) and can be referenced from projects that target .NET or .NET Standard. -It provides about 20,000 APIs, including Windows-only as well as cross-platform APIs from the following technology areas: +It provides about 20,000 APIs, including Windows-only and cross-platform APIs from the following technology areas: - Code Pages - CodeDom @@ -34,17 +34,17 @@ It provides about 20,000 APIs, including Windows-only as well as cross-platform - Windows Runtime Caching - Windows Services -For more information, see the [specification of the compatibility pack](https://github.com/dotnet/designs/blob/master/accepted/2018/compat-pack/compat-pack.md). +For more information, see the [specification of the compatibility pack](https://github.com/dotnet/designs/blob/main/accepted/2018/compat-pack/compat-pack.md). ## Get started 1. Before porting, make sure to take a look at the [Porting process](index.md). -2. When porting existing code to .NET Core or .NET Standard, install the [Microsoft.Windows.Compatibility NuGet package](https://www.nuget.org/packages/Microsoft.Windows.Compatibility). +2. When porting existing code to .NET or .NET Standard, install the [Microsoft.Windows.Compatibility NuGet package](https://www.nuget.org/packages/Microsoft.Windows.Compatibility). If you want to stay on Windows, you're all set. -3. If you want to run the .NET Core application or .NET Standard library on Linux or macOS, use the [API Analyzer](../../standard/analyzers/api-analyzer.md) to find usage of APIs that won't work cross-platform. +3. If you want to run the .NET application or .NET Standard library on Linux or macOS, use the [Platform compatibility analyzer](../../standard/analyzers/platform-compat-analyzer.md) to find usage of APIs that won't work cross-platform. 4. Either remove the usages of those APIs, replace them with cross-platform alternatives, or guard them using a platform check, like: @@ -69,3 +69,11 @@ For more information, see the [specification of the compatibility pack](https:// ``` For a demo, check out the [Channel 9 video of the Windows Compatibility Pack](https://channel9.msdn.com/Events/Connect/2017/T123). + +## See also + +- [Overview of porting from .NET Framework to .NET](index.md) +- [ASP.NET to ASP.NET Core migration](/aspnet/core/migration/proper-to-2x) +- [Migrate .NET Framework WPF apps to .NET](/dotnet/desktop/wpf/migration/convert-project-from-net-framework?view=netdesktop-5.0&preserve-view=true) +- [Migrate .NET Framework Windows Forms apps to .NET](/dotnet/desktop/winforms/migration/?view=netdesktop-5.0&preserve-view=true) +- [Port .NET Framework libraries to .NET](libraries.md) diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index 60a7551fd4ea3..ef4f1402a2aa7 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -14,6 +14,8 @@ This page is a reference for the MSBuild properties and items that you can use t ## Framework properties +The following MSBuild properties are documented in this section: + - [TargetFramework](#targetframework) - [TargetFrameworks](#targetframeworks) - [NetStandardImplicitPackageVersion](#netstandardimplicitpackageversion) @@ -59,6 +61,174 @@ Use the `NetStandardImplicitPackageVersion` property when you want to specify a ``` +## Assembly info generation properties + +- [GenerateAssemblyCompanyAttribute](#generateassemblycompanyattribute) +- [GenerateAssemblyConfigurationAttribute](#generateassemblyconfigurationattribute) +- [GenerateAssemblyCopyrightAttribute](#generateassemblycopyrightattribute) +- [GenerateAssemblyDescriptionAttribute](#generateassemblydescriptionattribute) +- [GenerateAssemblyFileVersionAttribute](#generateassemblyfileversionattribute) +- [GenerateAssemblyInfo](#generateassemblyinfo) +- [GenerateAssemblyInformationalVersionAttribute](#generateassemblyinformationalversionattribute) +- [GenerateAssemblyProductAttribute](#generateassemblyproductattribute) +- [GenerateAssemblyTitleAttribute](#generateassemblytitleattribute) +- [GenerateAssemblyVersionAttribute](#generateassemblyversionattribute) +- [GeneratedAssemblyInfoFile](#generatedassemblyinfofile) +- [GenerateNeutralResourcesLanguageAttribute](#generateneutralresourceslanguageattribute) + +### GenerateAssemblyCompanyAttribute + +This property controls whether or not the `Company` property generates the for the assembly. The default value is `true`. + +```xml + + false + +``` + +### GenerateAssemblyConfigurationAttribute + +This property controls whether or not the `Configuration` property generates the for the assembly. The default value is `true`. + +```xml + + false + +``` + +### GenerateAssemblyCopyrightAttribute + +This property controls whether or not the `Copyright` property generates the for the assembly. The default value is `true`. + +```xml + + false + +``` + +### GenerateAssemblyDescriptionAttribute + +This property controls whether or not the `Description` property generates the for the assembly. The default value is `true`. + +```xml + + false + +``` + +### GenerateAssemblyFileVersionAttribute + +This property controls whether or not the `FileVersion` property generates the for the assembly. The default value is `true`. + +```xml + + false + +``` + +### GenerateAssemblyInfo + +Controls `AssemblyInfo` attribute generation for the project. The default value is `true`. Use `false` to disable generation of the file: + +```xml + + false + +``` + +The [GeneratedAssemblyInfoFile](#generatedassemblyinfofile) setting controls the name of the generated file. + +When the `GenerateAssemblyInfo` value is `true`, project properties are transformed into `AssemblyInfo` attributes. The following table lists the project properties that generate the attributes, and the properties that can disable that generation: + +| Property | Attribute | Property to disable | +|------------------------|----------------------------------------------------------------|---------------------------------------------------------------------------------------------------| +| `Company` | | [`GenerateAssemblyCompanyAttribute`](#generateassemblycompanyattribute) | +| `Configuration` | | [`GenerateAssemblyConfigurationAttribute`](#generateassemblyconfigurationattribute) | +| `Copyright` | | [`GenerateAssemblyCopyrightAttribute`](#generateassemblycopyrightattribute) | +| `Description` | | [`GenerateAssemblyDescriptionAttribute`](#generateassemblydescriptionattribute) | +| `FileVersion` | | [`GenerateAssemblyFileVersionAttribute`](#generateassemblyfileversionattribute) | +| `InformationalVersion` | | [`GenerateAssemblyInformationalVersionAttribute`](#generateassemblyinformationalversionattribute) | +| `Product` | | [`GenerateAssemblyProductAttribute`](#generateassemblyproductattribute) | +| `AssemblyTitle` | | [`GenerateAssemblyTitleAttribute`](#generateassemblytitleattribute) | +| `AssemblyVersion` | | [`GenerateAssemblyVersionAttribute`](#generateassemblyversionattribute) | +| `NeutralLanguage` | | [`GenerateNeutralResourcesLanguageAttribute`](#generateneutralresourceslanguageattribute) | + +Notes about these settings: + +- `AssemblyVersion` and `FileVersion` default to the value of `$(Version)` without the suffix. For example, if `$(Version)` is `1.2.3-beta.4`, then the value would be `1.2.3`. +- `InformationalVersion` defaults to the value of `$(Version)`. +- If the `$(SourceRevisionId)` property is present, it's appended to `InformationalVersion`. You can disable this behavior using `IncludeSourceRevisionInInformationalVersion`. +- `Copyright` and `Description` properties are also used for NuGet metadata. +- `Configuration`, which defaults to `Debug`, is shared with all MSBuild targets. You can set it via the `--configuration` option of `dotnet` commands, for example, [dotnet pack](../tools/dotnet-pack.md). +- Some of the properties are used when creating a NuGet package. For more information, see [Package properties](#package-properties). + +#### Migrating from .NET Framework + +.NET Framework project templates create a code file with these assembly info attributes set. The file is typically located at *.\Properties\AssemblyInfo.cs* or *.\Properties\AssemblyInfo.vb*. SDK-style projects generate this file for you based on the project settings. **You can't have both.** When porting your code to .NET 5 (and .NET Core 3.1) or later, do one of the following: + +- Disable the generation of the temporary code file that contains the assembly info attributes by setting `GenerateAssemblyInfo` to `false`. This enables you to keep your *AssemblyInfo* file. +- Migrate the settings in the `AssemblyInfo` file to the project file, and delete the `AssemblyInfo` file. + +### GenerateAssemblyInformationalVersionAttribute + +This property controls whether or not the `InformationalVersion` property generates the for the assembly. The default value is `true`. + +```xml + + false + +``` + +### GenerateAssemblyProductAttribute + +This property controls whether or not the `Product` property generates the for the assembly. The default value is `true`. + +```xml + + false + +``` + +### GenerateAssemblyTitleAttribute + +This property controls whether or not the `AssemblyTitle` property generates the for the assembly. The default value is `true`. + +```xml + + false + +``` + +### GenerateAssemblyVersionAttribute + +This property controls whether or not the `AssemblyVersion` property generates the for the assembly. The default value is `true`. + +```xml + + false + +``` + +### GeneratedAssemblyInfoFile + +The property defines the relative or absolute path of the generated assembly info file. Defaults to a file named *[project-name].AssemblyInfo.[cs|vb]* in the `$(IntermediateOutputPath)` (usually the *obj*) directory. + +```xml + + assemblyinfo.cs + +``` + +### GenerateNeutralResourcesLanguageAttribute + +This property controls whether or not the `NeutralLanguage` property generates the for the assembly. The default value is `true`. + +```xml + + false + +``` + ## Package properties You can specify properties such as `PackageId`, `PackageVersion`, `PackageIcon`, `Title`, and `Description` to describe the package that gets created from your project. For information about these and other properties, see [pack target](/nuget/reference/msbuild-targets#pack-target). @@ -73,46 +243,20 @@ You can specify properties such as `PackageId`, `PackageVersion`, `PackageIcon`, ``` -## Publish properties, items, and metadata +## Publish-related properties + +The following MSBuild properties are documented in this section: - [AppendRuntimeIdentifierToOutputPath](#appendruntimeidentifiertooutputpath) - [AppendTargetFrameworkToOutputPath](#appendtargetframeworktooutputpath) - [CopyLocalLockFileAssemblies](#copylocallockfileassemblies) -- [CopyToPublishDirectory](#copytopublishdirectory) -- [LinkBase](#linkbase) +- [IsPublishable](#ispublishable) - [PreserveCompilationContext](#preservecompilationcontext) - [PreserveCompilationReferences](#preservecompilationreferences) - [RuntimeIdentifier](#runtimeidentifier) - [RuntimeIdentifiers](#runtimeidentifiers) -- [TrimmerRootAssembly](#trimmerrootassembly) - [UseAppHost](#useapphost) -### CopyToPublishDirectory - -The `CopyToPublishDirectory` metadata on an MSBuild item controls when the item is copied to the publish directory. Allowable values are `PreserveNewest`, which only copies the item if it has changed, `Always`, which always copies the item, and `Never`, which never copies the item. From a performance standpoint, `PreserveNewest` is preferable because it enables an incremental build. - -```xml - - - -``` - -### LinkBase - -For an item that's outside of the project directory and its subdirectories, the publish target uses the item's [Link metadata](/visualstudio/msbuild/common-msbuild-item-metadata) to determine where to copy the item to. `Link` also determines how items outside of the project tree are displayed in the Solution Explorer window of Visual Studio. - -If `Link` is not specified for an item that's outside of the project cone, it defaults to `%(LinkBase)\%(RecursiveDir)%(Filename)%(Extension)`. `LinkBase` lets you specify a sensible base folder for items outside of the project cone. The folder hierarchy under the base folder is preserved via `RecursiveDir`. If `LinkBase` is not specified, it's omitted from the `Link` path. - -```xml - - - -``` - -The following image shows how a file that's included via the previous item `Include` glob displays in Solution Explorer. - -:::image type="content" source="media/solution-explorer-linkbase.png" alt-text="Solution Explorer showing item with LinkBase metadata."::: - ### AppendTargetFrameworkToOutputPath The `AppendTargetFrameworkToOutputPath` property controls whether the [target framework moniker (TFM)](../../standard/frameworks.md) is appended to the output path (which is defined by [OutputPath](/visualstudio/msbuild/common-msbuild-project-properties#list-of-common-properties-and-parameters)). The .NET SDK automatically appends the target framework and, if present, the runtime identifier to the output path. Setting `AppendTargetFrameworkToOutputPath` to `false` prevents the TFM from being appended to the output path. However, without the TFM in the output path, multiple build artifacts may overwrite each other. @@ -150,6 +294,18 @@ The `CopyLocalLockFileAssemblies` property is useful for plugin projects that ha > [!TIP] > Alternatively, you can use `dotnet publish` to publish the class library. For more information, see [dotnet publish](../tools/dotnet-publish.md). +### IsPublishable + +The `IsPublishable` property allows the `Publish` target to run. This property only affects processes that use *.\*proj* files and the `Publish` target, such as the [dotnet publish](../tools/dotnet-publish.md) command. It does not affect publishing in Visual Studio, which uses the `PublishOnly` target. The default value is `true`. + +This property is useful if you run `dotnet publish` on a solution file, as it allows automatic selection of projects that should be published. + +```xml + + false + +``` + ### PreserveCompilationContext The `PreserveCompilationContext` property allows a built or published application to compile more code at run time using the same settings that were used at build time. The assemblies referenced at build time will be copied into the *ref* subdirectory of the output directory. The names of the reference assemblies are stored in the application's *.deps.json* file along with the options passed to the compiler. You can retrieve this information using the and properties. @@ -197,18 +353,6 @@ The `RuntimeIdentifiers` property lets you specify a semicolon-delimited list of ``` -### TrimmerRootAssembly - -The `TrimmerRootAssembly` item lets you exclude an assembly from [*trimming*](../deploying/trim-self-contained.md). Trimming is the process of removing unused parts of the runtime from a packaged application. In some cases, trimming might incorrectly remove required references. - -The following XML excludes the `System.Security` assembly from trimming. - -```xml - - - -``` - ### UseAppHost The `UseAppHost` property controls whether or not a native executable is created for a deployment. A native executable is required for self-contained deployments. @@ -223,7 +367,9 @@ In .NET Core 3.0 and later versions, a framework-dependent executable is created For more information about deployment, see [.NET application deployment](../deploying/index.md). -## Compile properties +## Compilation-related properties + +The following MSBuild properties are documented in this section: - [EmbeddedResourceUseDependentUponConvention](#embeddedresourceusedependentuponconvention) - [LangVersion](#langversion) @@ -257,6 +403,8 @@ For more information, see [C# language versioning](../../csharp/language-referen ## Default item inclusion properties +The following MSBuild properties are documented in this section: + - [DefaultExcludesInProjectFolder](#defaultexcludesinprojectfolder) - [DefaultItemExcludes](#defaultitemexcludes) - [EnableDefaultCompileItems](#enabledefaultcompileitems) @@ -330,6 +478,8 @@ The `EnableDefaultNoneItems` property controls whether `None` items (files that ## Code analysis properties +The following MSBuild properties are documented in this section: + - [AnalysisLevel](#analysislevel) - [AnalysisMode](#analysismode) - [CodeAnalysisTreatWarningsAsErrors](#codeanalysistreatwarningsaserrors) @@ -404,6 +554,9 @@ The `CodeAnalysisTreatWarningsAsErrors` property lets you configure whether code ``` +> [!NOTE] +> This property applies specifically to the built-in analyzers in the .NET 5+ SDK. It should not be used when you install a NuGet code analysis package. + ### EnforceCodeStyleInBuild > [!NOTE] @@ -523,14 +676,14 @@ The `TieredCompilationQuickJitForLoops` property configures whether the JIT comp ``` -## Reference properties and items +## Reference properties + +The following MSBuild properties are documented in this section: - [AssetTargetFallback](#assettargetfallback) - [DisableImplicitFrameworkReferences](#disableimplicitframeworkreferences) -- [PackageReference](#packagereference) -- [ProjectReference](#projectreference) -- [Reference](#reference) - [Restore-related properties](#restore-related-properties) +- [ValidateExecutableReferencesMatchSelfContained](#validateexecutablereferencesmatchselfcontained) ### AssetTargetFallback @@ -556,86 +709,27 @@ Set this property to `true` to disable implicit `FrameworkReference` or [Package ``` -### PackageReference - -The `PackageReference` item defines a reference to a NuGet package. - -The `Include` attribute specifies the package ID. The `Version` attribute specifies the version or version range. For information about how to specify a minimum version, maximum version, range, or exact match, see [Version ranges](/nuget/concepts/package-versioning#version-ranges). You can also add [asset attributes](#asset-attributes) to a package reference. - -The project file snippet in the following example references the [System.Runtime](https://www.nuget.org/packages/System.Runtime/) package. - -```xml - - - -``` - -For more information, see [Package references in project files](/nuget/consume-packages/package-references-in-project-files). - -#### Asset attributes - -The `IncludeAssets`, `ExcludeAssets`, and `PrivateAssets` metadata can be added to a package reference. - -| Attribute | Description | -| - | - | -| `IncludeAssets` | Specifies which assets belonging to the package specified by `` should be consumed. By default, all package assets are included. | -| `ExcludeAssets`| Specifies which assets belonging to the package specified by `` should not be consumed. | -| `PrivateAssets` | Specifies which assets belonging to the package specified by `` should be consumed but not flow to the next project. The `Analyzers`, `Build`, and `ContentFiles` assets are private by default when this attribute is not present. | - -These attributes can contain one or more of the following items, separated by a semicolon `;` if more than -one is listed: - -- `Compile` – the contents of the *lib* folder are available to compile against. -- `Runtime` – the contents of the *runtime* folder are distributed. -- `ContentFiles` – the contents of the *contentfiles* folder are used. -- `Build` – the props/targets in the *build* folder are used. -- `Native` – the contents from native assets are copied to the *output* folder for runtime. -- `Analyzers` – the analyzers are used. - -Alternatively, the attribute can contain: - -- `None` – none of the assets are used. -- `All` – all assets are used. - -### ProjectReference - -The `ProjectReference` item defines a reference to another project. The referenced project is added as a NuGet package dependency, that is, it's treated the same as a `PackageReference`. - -The `Include` attribute specifies the path to the project. You can also add the following metadata to a project reference: `IncludeAssets`, `ExcludeAssets`, and `PrivateAssets`. - -The project file snippet in the following example references a project named `Project2`. - -```xml - - - -``` - -### Reference - -The `Reference` item defines a reference to an assembly file. +### Restore-related properties -The `Include` attribute specifies the name of the file, and the `HintPath` metadata specifies the path to the assembly. +Restoring a referenced package installs all of its direct dependencies and all the dependencies of those dependencies. You can customize package restoration by specifying properties such as `RestorePackagesPath` and `RestoreIgnoreFailedSources`. For more information about these and other properties, see [restore target](/nuget/reference/msbuild-targets#restore-target). ```xml - - - ..\..\Assemblies\MyAssembly.dll - - + + true + ``` -### Restore-related properties +### ValidateExecutableReferencesMatchSelfContained -Restoring a referenced package installs all of its direct dependencies and all the dependencies of those dependencies. You can customize package restoration by specifying properties such as `RestorePackagesPath` and `RestoreIgnoreFailedSources`. For more information about these and other properties, see [restore target](/nuget/reference/msbuild-targets#restore-target). +The `ValidateExecutableReferencesMatchSelfContained` property can be used to disable errors related to executable project references. If .NET detects that a self-contained executable project references a framework-dependent executable project, or vice versa, it generates errors NETSDK1150 and NETSDK1151, respectively. To avoid these errors when the reference is intentional, set the `ValidateExecutableReferencesMatchSelfContained` property to `false`. ```xml - true + false ``` -## Run properties +## Run-related properties The following properties are used for launching an app with the [`dotnet run`](../tools/dotnet-run.md) command: @@ -665,7 +759,9 @@ The `RunWorkingDirectory` property defines the working directory for the applica ``` -## Hosting properties +## Hosting-related properties + +The following MSBuild properties are documented in this section: - [EnableComHosting](#enablecomhosting) - [EnableDynamicLoading](#enabledynamicloading) @@ -696,6 +792,86 @@ The `EnableDynamicLoading` property indicates that an assembly is a dynamically ``` +## Items + +[MSBuild items](/visualstudio/msbuild/msbuild-items) are inputs into the build system. Items are specified according to their type, which is the element name. For example, `Compile` and `Reference` are two [common item types](/visualstudio/msbuild/common-msbuild-project-items). The following additional item types are made available by the .NET SDK: + +- [PackageReference](#packagereference) +- [TrimmerRootAssembly](#trimmerrootassembly) + +You can use any of the standard [item attributes](/visualstudio/msbuild/item-element-msbuild#attributes-and-elements), for example, `Include` and `Update`, on these items. Use `Include` to add a new item, and use `Update` to modify an existing item. For example, `Update` is often used to modify an item that has implicitly been added by the .NET SDK. + +### PackageReference + +The `PackageReference` item defines a reference to a NuGet package. + +The `Include` attribute specifies the package ID. The `Version` attribute specifies the version or version range. For information about how to specify a minimum version, maximum version, range, or exact match, see [Version ranges](/nuget/concepts/package-versioning#version-ranges). + +The project file snippet in the following example references the [System.Runtime](https://www.nuget.org/packages/System.Runtime/) package. + +```xml + + + +``` + +You can also [control dependency assets](/nuget/consume-packages/package-references-in-project-files#controlling-dependency-assets) using metadata such as `PrivateAssets`. + +```xml + + + all + + +``` + +For more information, see [Package references in project files](/nuget/consume-packages/package-references-in-project-files). + +### TrimmerRootAssembly + +The `TrimmerRootAssembly` item lets you exclude an assembly from [*trimming*](../deploying/trim-self-contained.md). Trimming is the process of removing unused parts of the runtime from a packaged application. In some cases, trimming might incorrectly remove required references. + +The following XML excludes the `System.Security` assembly from trimming. + +```xml + + + +``` + +## Item metadata + +In addition to the standard [MSBuild item attributes](/visualstudio/msbuild/item-element-msbuild#attributes-and-elements), the following item metadata tags are made available by the .NET SDK: + +- [CopyToPublishDirectory](#copytopublishdirectory) +- [LinkBase](#linkbase) + +### CopyToPublishDirectory + +The `CopyToPublishDirectory` metadata on an MSBuild item controls when the item is copied to the publish directory. Allowable values are `PreserveNewest`, which only copies the item if it has changed, `Always`, which always copies the item, and `Never`, which never copies the item. From a performance standpoint, `PreserveNewest` is preferable because it enables an incremental build. + +```xml + + + +``` + +### LinkBase + +For an item that's outside of the project directory and its subdirectories, the publish target uses the item's [Link metadata](/visualstudio/msbuild/common-msbuild-item-metadata) to determine where to copy the item to. `Link` also determines how items outside of the project tree are displayed in the Solution Explorer window of Visual Studio. + +If `Link` is not specified for an item that's outside of the project cone, it defaults to `%(LinkBase)\%(RecursiveDir)%(Filename)%(Extension)`. `LinkBase` lets you specify a sensible base folder for items outside of the project cone. The folder hierarchy under the base folder is preserved via `RecursiveDir`. If `LinkBase` is not specified, it's omitted from the `Link` path. + +```xml + + + +``` + +The following image shows how a file that's included via the previous item `Include` glob displays in Solution Explorer. + +:::image type="content" source="media/solution-explorer-linkbase.png" alt-text="Solution Explorer showing item with LinkBase metadata."::: + ## See also - [MSBuild schema reference](/visualstudio/msbuild/msbuild-project-file-schema-reference) diff --git a/docs/core/releases-and-support.md b/docs/core/releases-and-support.md index ad0677da26ca5..5e455b1646867 100644 --- a/docs/core/releases-and-support.md +++ b/docs/core/releases-and-support.md @@ -99,7 +99,7 @@ End of support refers to the date after which Microsoft no longer provides fixes When an operating system version goes out of support, we stop testing that version and providing support for that version. Users need to move forward to a supported operating system version to get support. -For more information, see the [.NET OS Lifecycle Policy](https://github.com/dotnet/core/blob/master/os-lifecycle-policy.md). +For more information, see the [.NET OS Lifecycle Policy](https://github.com/dotnet/core/blob/main/os-lifecycle-policy.md). ## Get support diff --git a/docs/core/rid-catalog.md b/docs/core/rid-catalog.md index b9a269016b70b..a1612ee9a68ed 100644 --- a/docs/core/rid-catalog.md +++ b/docs/core/rid-catalog.md @@ -2,6 +2,7 @@ title: .NET Runtime Identifier (RID) catalog description: Learn about the Runtime Identifier (RID) and how RIDs are used in .NET. ms.date: 01/28/2021 +ms.topic: reference --- # .NET RID Catalog @@ -33,7 +34,7 @@ RIDs that represent concrete operating systems usually follow this pattern: `[os ## RID graph -The RID graph or runtime fallback graph is a list of RIDs that are compatible with each other. The RIDs are defined in the [Microsoft.NETCore.Platforms](https://www.nuget.org/packages/Microsoft.NETCore.Platforms/) package. You can see the list of supported RIDs and the RID graph in the [*runtime.json*](https://github.com/dotnet/runtime/blob/master/src/libraries/Microsoft.NETCore.Platforms/pkg/runtime.json) file, which is located in the `dotnet/runtime` repository. In this file, you can see that all RIDs, except for the base one, contain an `"#import"` statement. These statements indicate compatible RIDs. +The RID graph or runtime fallback graph is a list of RIDs that are compatible with each other. The RIDs are defined in the [Microsoft.NETCore.Platforms](https://www.nuget.org/packages/Microsoft.NETCore.Platforms/) package. You can see the list of supported RIDs and the RID graph in the [*runtime.json*](https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.NETCore.Platforms/src/runtime.json) file, which is located in the `dotnet/runtime` repository. In this file, you can see that all RIDs, except for the base one, contain an `"#import"` statement. These statements indicate compatible RIDs. When NuGet restores packages, it tries to find an exact match for the specified runtime. If an exact match is not found, NuGet walks back the graph until it finds the closest compatible system according to the RID graph. @@ -74,7 +75,7 @@ There are some considerations about RIDs that you have to keep in mind when work ## Using RIDs To be able to use RIDs, you have to know which RIDs exist. New values are added regularly to the platform. -For the latest and complete version, see the [runtime.json](https://github.com/dotnet/runtime/blob/master/src/libraries/Microsoft.NETCore.Platforms/pkg/runtime.json) file in the `dotnet/runtime` repository. +For the latest and complete version, see the [runtime.json](https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.NETCore.Platforms/src/runtime.json) file in the `dotnet/runtime` repository. Portable RIDs are values added to the RID graph that aren't tied to a specific version or OS distribution. They are the preferred choice, especially when dealing with multiple Linux distros since most distribution RIDs are mapped to the portable RIDs. @@ -82,7 +83,7 @@ The following list shows a small subset of the most common RIDs used for each OS ## Windows RIDs -Only common values are listed. For the latest and complete version, see the [runtime.json](https://github.com/dotnet/runtime/blob/master/src/libraries/Microsoft.NETCore.Platforms/pkg/runtime.json) file in the `dotnet/runtime` repository. +Only common values are listed. For the latest and complete version, see the [runtime.json](https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.NETCore.Platforms/src/runtime.json) file in the `dotnet/runtime` repository. - Portable - `win-x64` @@ -106,7 +107,7 @@ For more information, see [.NET dependencies and requirements](./install/windows ## Linux RIDs -Only common values are listed. For the latest and complete version, see the [runtime.json](https://github.com/dotnet/runtime/blob/master/src/libraries/Microsoft.NETCore.Platforms/pkg/runtime.json) file in the `dotnet/runtime` repository. Devices running a distribution not listed below may work with one of the Portable RIDs. For example, Raspberry Pi devices running a Linux distribution not listed can be targeted with `linux-arm`. +Only common values are listed. For the latest and complete version, see the [runtime.json](https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.NETCore.Platforms/src/runtime.json) file in the `dotnet/runtime` repository. Devices running a distribution not listed below may work with one of the Portable RIDs. For example, Raspberry Pi devices running a Linux distribution not listed can be targeted with `linux-arm`. - Portable - `linux-x64` (Most desktop distributions like CentOS, Debian, Fedora, Ubuntu, and derivatives) @@ -125,7 +126,7 @@ For more information, see [.NET dependencies and requirements](./install/linux.m ## macOS RIDs -macOS RIDs use the older "OSX" branding. Only common values are listed. For the latest and complete version, see the [runtime.json](https://github.com/dotnet/runtime/blob/master/src/libraries/Microsoft.NETCore.Platforms/pkg/runtime.json) file in the `dotnet/runtime` repository. +macOS RIDs use the older "OSX" branding. Only common values are listed. For the latest and complete version, see the [runtime.json](https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.NETCore.Platforms/src/runtime.json) file in the `dotnet/runtime` repository. - Portable - `osx-x64` (Minimum OS version is macOS 10.12 Sierra) @@ -149,4 +150,4 @@ For more information, see [.NET dependencies and requirements](./install/macos.m ## See also -- [Runtime IDs](https://github.com/dotnet/runtime/blob/master/src/libraries/Microsoft.NETCore.Platforms/readme.md) +- [Runtime IDs](https://github.com/dotnet/runtime/blob/main/src/libraries/Microsoft.NETCore.Platforms/readme.md) diff --git a/docs/core/run-time-config/compilation.md b/docs/core/run-time-config/compilation.md index 65b8894e71a70..18af6bb55519f 100644 --- a/docs/core/run-time-config/compilation.md +++ b/docs/core/run-time-config/compilation.md @@ -6,6 +6,10 @@ ms.topic: reference --- # Run-time configuration options for compilation +This article details the settings you can use to configure .NET compilation. + +[!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)] + ## Tiered compilation - Configures whether the just-in-time (JIT) compiler uses [tiered compilation](../whats-new/dotnet-core-3-0.md#tiered-compilation). Tiered compilation transitions methods through two tiers: @@ -13,13 +17,13 @@ ms.topic: reference - The second tier generates optimized code in the background ("optimizing JIT"). - In .NET Core 3.0 and later, tiered compilation is enabled by default. - In .NET Core 2.1 and 2.2, tiered compilation is disabled by default. -- For more information, see the [Tiered compilation guide](https://github.com/dotnet/runtime/blob/master/docs/design/features/tiered-compilation.md). +- For more information, see the [Tiered compilation guide](https://github.com/dotnet/runtime/blob/main/docs/design/features/tiered-compilation.md). | | Setting name | Values | | - | - | - | | **runtimeconfig.json** | `System.Runtime.TieredCompilation` | `true` - enabled
`false` - disabled | | **MSBuild property** | `TieredCompilation` | `true` - enabled
`false` - disabled | -| **Environment variable** | `COMPlus_TieredCompilation` | `1` - enabled
`0` - disabled | +| **Environment variable** | `DOTNET_TieredCompilation` | `1` - enabled
`0` - disabled | ### Examples @@ -59,7 +63,7 @@ Project file: | - | - | - | | **runtimeconfig.json** | `System.Runtime.TieredCompilation.QuickJit` | `true` - enabled
`false` - disabled | | **MSBuild property** | `TieredCompilationQuickJit` | `true` - enabled
`false` - disabled | -| **Environment variable** | `COMPlus_TC_QuickJit` | `1` - enabled
`0` - disabled | +| **Environment variable** | `DOTNET_TC_QuickJit` | `1` - enabled
`0` - disabled | ### Examples @@ -98,7 +102,7 @@ Project file: | - | - | - | | **runtimeconfig.json** | `System.Runtime.TieredCompilation.QuickJitForLoops` | `false` - disabled
`true` - enabled | | **MSBuild property** | `TieredCompilationQuickJitForLoops` | `false` - disabled
`true` - enabled | -| **Environment variable** | `COMPlus_TC_QuickJitForLoops` | `0` - disabled
`1` - enabled | +| **Environment variable** | `DOTNET_TC_QuickJitForLoops` | `0` - disabled
`1` - enabled | ### Examples @@ -134,4 +138,4 @@ Project file: | | Setting name | Values | | - | - | - | -| **Environment variable** | `COMPlus_ReadyToRun` | `1` - enabled
`0` - disabled | +| **Environment variable** | `DOTNET_ReadyToRun` | `1` - enabled
`0` - disabled | diff --git a/docs/core/run-time-config/debugging-profiling.md b/docs/core/run-time-config/debugging-profiling.md index a23ff66259c6c..6806740331bf2 100644 --- a/docs/core/run-time-config/debugging-profiling.md +++ b/docs/core/run-time-config/debugging-profiling.md @@ -6,6 +6,10 @@ ms.topic: reference --- # Run-time configuration options for debugging and profiling +This article details the settings you can use to configure .NET debugging and profiling. + +[!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)] + ## Enable diagnostics - Configures whether the debugger, the profiler, and EventPipe diagnostics are enabled or disabled. @@ -14,7 +18,7 @@ ms.topic: reference | | Setting name | Values | | - | - | - | | **runtimeconfig.json** | N/A | N/A | -| **Environment variable** | `COMPlus_EnableDiagnostics` | `1` - enabled
`0` - disabled | +| **Environment variable** | `DOTNET_EnableDiagnostics` | `1` - enabled
`0` - disabled | ## Enable profiling @@ -39,7 +43,7 @@ ms.topic: reference - Specifies the path to the profiler DLL to load into the currently running process (or 32-bit or 64-bit process). - If more than one variable is set, the bitness-specific variables take precedence. They specify which bitness of profiler to load. -- For more information, see [Finding the profiler library](https://github.com/dotnet/runtime/blob/master/docs/design/coreclr/profiling/Profiler%20Loading.md). +- For more information, see [Finding the profiler library](https://github.com/dotnet/runtime/blob/main/docs/design/coreclr/profiling/Profiler%20Loading.md). | | Setting name | Values | | - | - | - | @@ -55,7 +59,7 @@ ms.topic: reference | | Setting name | Values | | - | - | - | | **runtimeconfig.json** | N/A | N/A | -| **Environment variable** | `COMPlus_PerfMapEnabled` | `0` - disabled
`1` - enabled | +| **Environment variable** | `DOTNET_PerfMapEnabled` | `0` - disabled
`1` - enabled | ## Perf log markers @@ -65,7 +69,7 @@ ms.topic: reference | | Setting name | Values | | - | - | - | | **runtimeconfig.json** | N/A | N/A | -| **Environment variable** | `COMPlus_PerfMapIgnoreSignal` | `0` - disabled
`1` - enabled | +| **Environment variable** | `DOTNET_PerfMapIgnoreSignal` | `0` - disabled
`1` - enabled | > [!NOTE] -> This setting is ignored if [COMPlus_PerfMapEnabled](#write-perf-map) is omitted or set to `0` (that is, disabled). +> This setting is ignored if [DOTNET_PerfMapEnabled](#write-perf-map) is omitted or set to `0` (that is, disabled). diff --git a/docs/core/run-time-config/garbage-collector.md b/docs/core/run-time-config/garbage-collector.md index 48920901e371d..06a1b26d0c71a 100644 --- a/docs/core/run-time-config/garbage-collector.md +++ b/docs/core/run-time-config/garbage-collector.md @@ -15,6 +15,7 @@ Settings are arranged into groups on this page. The settings within each group a > - These settings can also be changed dynamically by the app as it's running, so any run-time settings you set may be overridden. > - Some settings, such as [latency level](../../standard/garbage-collection/latency.md), are typically set only through the API at design time. Such settings are omitted from this page. > - For number values, use decimal notation for settings in the *runtimeconfig.json* file and hexadecimal notation for environment variable settings. For hexadecimal values, you can specify them with or without the "0x" prefix. +> - If you're using the environment variables, .NET 6 standardizes on the prefix `DOTNET_` instead of `COMPlus_`. However, the `COMPlus_` prefix will continue to work. If you're using a previous version of the .NET runtime, you should still use the `COMPlus_` prefix, for example, `COMPlus_gcServer`. ## Flavors of garbage collection @@ -36,7 +37,7 @@ Use the following settings to select flavors of garbage collection: | - | - | - | - | | **runtimeconfig.json** | `System.GC.Server` | `false` - workstation
`true` - server | .NET Core 1.0 | | **MSBuild property** | `ServerGarbageCollection` | `false` - workstation
`true` - server | .NET Core 1.0 | -| **Environment variable** | `COMPlus_gcServer` | `0` - workstation
`1` - server | .NET Core 1.0 | +| **Environment variable** | `DOTNET_gcServer` | `0` - workstation
`1` - server | .NET Core 1.0 | | **app.config for .NET Framework** | [GCServer](../../framework/configure-apps/file-schema/runtime/gcserver-element.md) | `false` - workstation
`true` - server | | #### Examples @@ -75,7 +76,7 @@ Project file: | - | - | - | - | | **runtimeconfig.json** | `System.GC.Concurrent` | `true` - background GC
`false` - non-concurrent GC | .NET Core 1.0 | | **MSBuild property** | `ConcurrentGarbageCollection` | `true` - background GC
`false` - non-concurrent GC | .NET Core 1.0 | -| **Environment variable** | `COMPlus_gcConcurrent` | `1` - background GC
`0` - non-concurrent GC | .NET Core 1.0 | +| **Environment variable** | `DOTNET_gcConcurrent` | `1` - background GC
`0` - non-concurrent GC | .NET Core 1.0 | | **app.config for .NET Framework** | [gcConcurrent](../../framework/configure-apps/file-schema/runtime/gcconcurrent-element.md) | `true` - background GC
`false` - non-concurrent GC | | #### Examples @@ -133,7 +134,7 @@ For more information about some of these settings, see the [Middle ground betwee | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.HeapCount` | *decimal value* | .NET Core 3.0 | -| **Environment variable** | `COMPlus_GCHeapCount` | *hexadecimal value* | .NET Core 3.0 | +| **Environment variable** | `DOTNET_GCHeapCount` | *hexadecimal value* | .NET Core 3.0 | | **app.config for .NET Framework** | [GCHeapCount](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md) | *decimal value* | .NET Framework 4.6.2 | Example: @@ -161,7 +162,7 @@ Example: | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.HeapAffinitizeMask` | *decimal value* | .NET Core 3.0 | -| **Environment variable** | `COMPlus_GCHeapAffinitizeMask` | *hexadecimal value* | .NET Core 3.0 | +| **Environment variable** | `DOTNET_GCHeapAffinitizeMask` | *hexadecimal value* | .NET Core 3.0 | | **app.config for .NET Framework** | [GCHeapAffinitizeMask](../../framework/configure-apps/file-schema/runtime/gcheapaffinitizemask-element.md) | *decimal value* | .NET Framework 4.6.2 | Example: @@ -188,7 +189,7 @@ Example: | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.GCHeapAffinitizeRanges` | Comma-separated list of processor numbers or ranges of processor numbers.
Unix example: "1-10,12,50-52,70"
Windows example: "0:1-10,0:12,1:50-52,1:70" | .NET Core 3.0 | -| **Environment variable** | `COMPlus_GCHeapAffinitizeRanges` | Comma-separated list of processor numbers or ranges of processor numbers.
Unix example: "1-10,12,50-52,70"
Windows example: "0:1-10,0:12,1:50-52,1:70" | .NET Core 3.0 | +| **Environment variable** | `DOTNET_GCHeapAffinitizeRanges` | Comma-separated list of processor numbers or ranges of processor numbers.
Unix example: "1-10,12,50-52,70"
Windows example: "0:1-10,0:12,1:50-52,1:70" | .NET Core 3.0 | Example: @@ -215,11 +216,11 @@ Example: | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.CpuGroup` | `0` - disabled
`1` - enabled | .NET 5.0 | -| **Environment variable** | `COMPlus_GCCpuGroup` | `0` - disabled
`1` - enabled | .NET Core 1.0 | +| **Environment variable** | `DOTNET_GCCpuGroup` | `0` - disabled
`1` - enabled | .NET Core 1.0 | | **app.config for .NET Framework** | [GCCpuGroup](../../framework/configure-apps/file-schema/runtime/gccpugroup-element.md) | `false` - disabled
`true` - enabled | | > [!NOTE] -> To configure the common language runtime (CLR) to also distribute threads from the thread pool across all CPU groups, enable the [Thread_UseAllCpuGroups element](../../framework/configure-apps/file-schema/runtime/thread-useallcpugroups-element.md) option. For .NET Core apps, you can enable this option by setting the value of the `COMPlus_Thread_UseAllCpuGroups` environment variable to `1`. +> To configure the common language runtime (CLR) to also distribute threads from the thread pool across all CPU groups, enable the [Thread_UseAllCpuGroups element](../../framework/configure-apps/file-schema/runtime/thread-useallcpugroups-element.md) option. For .NET Core apps, you can enable this option by setting the value of the `DOTNET_Thread_UseAllCpuGroups` environment variable to `1`. ### Affinitize @@ -230,7 +231,7 @@ Example: | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.NoAffinitize` | `false` - affinitize
`true` - don't affinitize | .NET Core 3.0 | -| **Environment variable** | `COMPlus_GCNoAffinitize` | `0` - affinitize
`1` - don't affinitize | .NET Core 3.0 | +| **Environment variable** | `DOTNET_GCNoAffinitize` | `0` - affinitize
`1` - don't affinitize | .NET Core 3.0 | | **app.config for .NET Framework** | [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md) | `false` - affinitize
`true` - don't affinitize | .NET Framework 4.6.2 | Example: @@ -258,7 +259,7 @@ Example: | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.HeapHardLimit` | *decimal value* | .NET Core 3.0 | -| **Environment variable** | `COMPlus_GCHeapHardLimit` | *hexadecimal value* | .NET Core 3.0 | +| **Environment variable** | `DOTNET_GCHeapHardLimit` | *hexadecimal value* | .NET Core 3.0 | Example: @@ -282,7 +283,7 @@ Example: - This setting only applies to 64-bit computers. - If the process is running inside a container that has a specified memory limit, the percentage is calculated as a percentage of that memory limit. - This setting is ignored if the [Per-object-heap limits](#per-object-heap-limits) are configured. -- The default value, which only applies in certain cases, is the lesser of 20 MB or 75% of the memory limit on the container. The default value applies if: +- The default value, which only applies in certain cases, is the greater of 20 MB or 75% of the memory limit on the container. The default value applies if: - The process is running inside a container that has a specified memory limit. - [System.GC.HeapHardLimit](#heap-limit) is not set. @@ -290,7 +291,7 @@ Example: | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.HeapHardLimitPercent` | *decimal value* | .NET Core 3.0 | -| **Environment variable** | `COMPlus_GCHeapHardLimitPercent` | *hexadecimal value* | .NET Core 3.0 | +| **Environment variable** | `DOTNET_GCHeapHardLimitPercent` | *hexadecimal value* | .NET Core 3.0 | Example: @@ -311,23 +312,23 @@ Example: You can specify the GC's allowable heap usage on a per-object-heap basis. The different heaps are the large object heap (LOH), small object heap (SOH), and pinned object heap (POH). -- If you specify a value for any of the `COMPLUS_GCHeapHardLimitSOH`, `COMPLUS_GCHeapHardLimitLOH`, or `COMPLUS_GCHeapHardLimitPOH` settings, you must also specify a value for `COMPLUS_GCHeapHardLimitSOH` and `COMPLUS_GCHeapHardLimitLOH`. If you don't, the runtime will fail to initialize. -- The default value for `COMPLUS_GCHeapHardLimitPOH` is 0. `COMPLUS_GCHeapHardLimitSOH` and `COMPLUS_GCHeapHardLimitLOH` don't have default values. +- If you specify a value for any of the `DOTNET_GCHeapHardLimitSOH`, `DOTNET_GCHeapHardLimitLOH`, or `DOTNET_GCHeapHardLimitPOH` settings, you must also specify a value for `DOTNET_GCHeapHardLimitSOH` and `DOTNET_GCHeapHardLimitLOH`. If you don't, the runtime will fail to initialize. +- The default value for `DOTNET_GCHeapHardLimitPOH` is 0. `DOTNET_GCHeapHardLimitSOH` and `DOTNET_GCHeapHardLimitLOH` don't have default values. | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.HeapHardLimitSOH` | *decimal value* | .NET 5.0 | -| **Environment variable** | `COMPLUS_GCHeapHardLimitSOH` | *hexadecimal value* | .NET 5.0 | +| **Environment variable** | `DOTNET_GCHeapHardLimitSOH` | *hexadecimal value* | .NET 5.0 | | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.HeapHardLimitLOH` | *decimal value* | .NET 5.0 | -| **Environment variable** | `COMPLUS_GCHeapHardLimitLOH` | *hexadecimal value* | .NET 5.0 | +| **Environment variable** | `DOTNET_GCHeapHardLimitLOH` | *hexadecimal value* | .NET 5.0 | | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.HeapHardLimitPOH` | *decimal value* | .NET 5.0 | -| **Environment variable** | `COMPLUS_GCHeapHardLimitPOH` | *hexadecimal value* | .NET 5.0 | +| **Environment variable** | `DOTNET_GCHeapHardLimitPOH` | *hexadecimal value* | .NET 5.0 | > [!TIP] > If you're setting the option in *runtimeconfig.json*, specify a decimal value. If you're setting the option as an environment variable, specify a hexadecimal value. For example, to specify a heap hard limit of 200 mebibytes (MiB), the values would be 209715200 for the JSON file and 0xC800000 or C800000 for the environment variable. @@ -336,25 +337,25 @@ You can specify the GC's allowable heap usage on a per-object-heap basis. The di You can specify the GC's allowable heap usage on a per-object-heap basis. The different heaps are the large object heap (LOH), small object heap (SOH), and pinned object heap (POH). -- If you specify a value for any of the `COMPLUS_GCHeapHardLimitSOHPercent`, `COMPLUS_GCHeapHardLimitLOHPercent`, or `COMPLUS_GCHeapHardLimitPOHPercent` settings, you must also specify a value for `COMPLUS_GCHeapHardLimitSOHPercent` and `COMPLUS_GCHeapHardLimitLOHPercent`. If you don't, the runtime will fail to initialize. -- These settings are ignored if `COMPLUS_GCHeapHardLimitSOH`, `COMPLUS_GCHeapHardLimitLOH`, and `COMPLUS_GCHeapHardLimitPOH` are specified. +- If you specify a value for any of the `DOTNET_GCHeapHardLimitSOHPercent`, `DOTNET_GCHeapHardLimitLOHPercent`, or `DOTNET_GCHeapHardLimitPOHPercent` settings, you must also specify a value for `DOTNET_GCHeapHardLimitSOHPercent` and `DOTNET_GCHeapHardLimitLOHPercent`. If you don't, the runtime will fail to initialize. +- These settings are ignored if `DOTNET_GCHeapHardLimitSOH`, `DOTNET_GCHeapHardLimitLOH`, and `DOTNET_GCHeapHardLimitPOH` are specified. - A value of 1 means that GC uses 1% of total physical memory for that object heap. - Each value must be greater than zero and less than 100. Additionally, the sum of the three percentage values must be less than 100. Otherwise, the runtime will fail to initialize. | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.HeapHardLimitSOHPercent` | *decimal value* | .NET 5.0 | -| **Environment variable** | `COMPLUS_GCHeapHardLimitSOHPercent` | *hexadecimal value* | .NET 5.0 | +| **Environment variable** | `DOTNET_GCHeapHardLimitSOHPercent` | *hexadecimal value* | .NET 5.0 | | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.HeapHardLimitLOHPercent` | *decimal value* | .NET 5.0 | -| **Environment variable** | `COMPLUS_GCHeapHardLimitLOHPercent` | *hexadecimal value* | .NET 5.0 | +| **Environment variable** | `DOTNET_GCHeapHardLimitLOHPercent` | *hexadecimal value* | .NET 5.0 | | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.HeapHardLimitPOHPercent` | *decimal value* | .NET 5.0 | -| **Environment variable** | `COMPLUS_GCHeapHardLimitPOHPercent` | *hexadecimal value* | .NET 5.0 | +| **Environment variable** | `DOTNET_GCHeapHardLimitPOHPercent` | *hexadecimal value* | .NET 5.0 | > [!TIP] > If you're setting the option in *runtimeconfig.json*, specify a decimal value. If you're setting the option as an environment variable, specify a hexadecimal value. For example, to limit the heap usage to 30%, the values would be 30 for the JSON file and 0x1E or 1E for the environment variable. @@ -363,7 +364,7 @@ You can specify the GC's allowable heap usage on a per-object-heap basis. The di Memory load is indicated by the percentage of physical memory in use. By default, when the physical memory load reaches **90%**, garbage collection becomes more aggressive about doing full, compacting garbage collections to avoid paging. When memory load is below 90%, GC favors background collections for full garbage collections, which have shorter pauses but don't reduce the total heap size by much. On machines with a significant amount of memory (80GB or more), the default load threshold is between 90% and 97%. -The high memory load threshold can be adjusted by the `COMPlus_GCHighMemPercent` environment variable or `System.GC.HighMemoryPercent` JSON configuration setting. Consider adjusting the threshold if you want to control heap size. For example, for the dominant process on a machine with 64GB of memory, it's reasonable for GC to start reacting when there's 10% of memory available. But for smaller processes, for example, a process that only consumes 1GB of memory, GC can comfortably run with less than 10% of memory available. For these smaller processes, consider setting the threshold higher. On the other hand, if you want larger processes to have smaller heap sizes (even when there's plenty of physical memory available), lowering this threshold is an effective way for GC to react sooner to compact the heap down. +The high memory load threshold can be adjusted by the `DOTNET_GCHighMemPercent` environment variable or `System.GC.HighMemoryPercent` JSON configuration setting. Consider adjusting the threshold if you want to control heap size. For example, for the dominant process on a machine with 64GB of memory, it's reasonable for GC to start reacting when there's 10% of memory available. But for smaller processes, for example, a process that only consumes 1GB of memory, GC can comfortably run with less than 10% of memory available. For these smaller processes, consider setting the threshold higher. On the other hand, if you want larger processes to have smaller heap sizes (even when there's plenty of physical memory available), lowering this threshold is an effective way for GC to react sooner to compact the heap down. > [!NOTE] > For processes running in a container, GC considers the physical memory based on the container limit. @@ -371,7 +372,7 @@ The high memory load threshold can be adjusted by the `COMPlus_GCHighMemPercent` | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.HighMemoryPercent` | *decimal value* | .NET 5.0 | -| **Environment variable** | `COMPlus_GCHighMemPercent` | *hexadecimal value* | | +| **Environment variable** | `DOTNET_GCHighMemPercent` | *hexadecimal value* | .NET Core 3.0
.NET Framework 4.7.2 | > [!TIP] > If you're setting the option in *runtimeconfig.json*, specify a decimal value. If you're setting the option as an environment variable, specify a hexadecimal value. For example, to set the high memory threshold to 75%, the values would be 75 for the JSON file and 0x4B or 4B for the environment variable. @@ -385,7 +386,7 @@ The high memory load threshold can be adjusted by the `COMPlus_GCHighMemPercent` | - | - | - | - | | **runtimeconfig.json** | `System.GC.RetainVM` | `false` - release to OS
`true` - put on standby | .NET Core 1.0 | | **MSBuild property** | `RetainVMGarbageCollection` | `false` - release to OS
`true` - put on standby | .NET Core 1.0 | -| **Environment variable** | `COMPlus_GCRetainVM` | `0` - release to OS
`1` - put on standby | .NET Core 1.0 | +| **Environment variable** | `DOTNET_GCRetainVM` | `0` - release to OS
`1` - put on standby | .NET Core 1.0 | #### Examples @@ -422,7 +423,7 @@ Project file: | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | N/A | N/A | N/A | -| **Environment variable** | `COMPlus_GCLargePages` | `0` - disabled
`1` - enabled | .NET Core 3.0 | +| **Environment variable** | `DOTNET_GCLargePages` | `0` - disabled
`1` - enabled | .NET Core 3.0 | ## Allow large objects @@ -433,7 +434,7 @@ Project file: | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | N/A | N/A | N/A | -| **Environment variable** | `COMPlus_gcAllowVeryLargeObjects` | `1` - enabled
`0` - disabled | .NET Core 1.0 | +| **Environment variable** | `DOTNET_gcAllowVeryLargeObjects` | `1` - enabled
`0` - disabled | .NET Core 1.0 | | **app.config for .NET Framework** | [gcAllowVeryLargeObjects](../../framework/configure-apps/file-schema/runtime/gcallowverylargeobjects-element.md) | `1` - enabled
`0` - disabled | .NET Framework 4.5 | ## Large object heap threshold @@ -445,7 +446,7 @@ Project file: | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | `System.GC.LOHThreshold` | *decimal value* | .NET Core 1.0 | -| **Environment variable** | `COMPlus_GCLOHThreshold` | *hexadecimal value* | .NET Core 1.0 | +| **Environment variable** | `DOTNET_GCLOHThreshold` | *hexadecimal value* | .NET Core 1.0 | | **app.config for .NET Framework** | [GCLOHThreshold](../../framework/configure-apps/file-schema/runtime/gclohthreshold-element.md) | *decimal value* | .NET Framework 4.8 | Example: @@ -466,9 +467,9 @@ Example: ## Standalone GC - Specifies a path to the library containing the garbage collector that the runtime intends to load. -- For more information, see [Standalone GC loader design](https://github.com/dotnet/runtime/blob/master/docs/design/features/standalone-gc-loading.md). +- For more information, see [Standalone GC loader design](https://github.com/dotnet/runtime/blob/main/docs/design/features/standalone-gc-loading.md). | | Setting name | Values | Version introduced | | - | - | - | - | | **runtimeconfig.json** | N/A | N/A | N/A | -| **Environment variable** | `COMPlus_GCName` | *string_path* | .NET Core 2.0 | +| **Environment variable** | `DOTNET_GCName` | *string_path* | .NET Core 2.0 | diff --git a/docs/core/run-time-config/globalization.md b/docs/core/run-time-config/globalization.md index 3421536d48825..f04968fa8d01c 100644 --- a/docs/core/run-time-config/globalization.md +++ b/docs/core/run-time-config/globalization.md @@ -10,7 +10,7 @@ ms.topic: reference - Determines whether a .NET Core app runs in globalization-invariant mode without access to culture-specific data and behavior. - If you omit this setting, the app runs with access to cultural data. This is equivalent to setting the value to `false`. -- For more information, see [.NET Core globalization invariant mode](https://github.com/dotnet/runtime/blob/master/docs/design/features/globalization-invariant-mode.md). +- For more information, see [.NET Core globalization invariant mode](https://github.com/dotnet/runtime/blob/main/docs/design/features/globalization-invariant-mode.md). | | Setting name | Values | | - | - | - | diff --git a/docs/core/run-time-config/index.md b/docs/core/run-time-config/index.md index bb7743dd990dd..8845486272d3f 100644 --- a/docs/core/run-time-config/index.md +++ b/docs/core/run-time-config/index.md @@ -107,7 +107,9 @@ MSBuild properties for configuring run-time behavior are noted in the individual ## Environment variables -Environment variables can be used to supply some run-time configuration information. Configuring a run-time option by using an environment variable applies the setting to all .NET Core apps. Configuration knobs specified as environment variables generally have the prefix **COMPlus_**. +Environment variables can be used to supply some run-time configuration information. Configuring a run-time option by using an environment variable applies the setting to all .NET Core apps. Configuration knobs specified as environment variables generally have the prefix **DOTNET_**. + +[!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)] You can define environment variables from the Windows Control Panel, at the command line, or programmatically by calling the method on both Windows and Unix-based systems. @@ -115,11 +117,11 @@ The following examples show how to set an environment variable at the command li ```shell # Windows -set COMPlus_GCRetainVM=1 +set DOTNET_GCRetainVM=1 # Powershell -$env:COMPlus_GCRetainVM="1" +$env:DOTNET_GCRetainVM="1" # Unix -export COMPlus_GCRetainVM=1 +export DOTNET_GCRetainVM=1 ``` diff --git a/docs/core/run-time-config/threading.md b/docs/core/run-time-config/threading.md index 37e18b2776145..6b726b06f6cbe 100644 --- a/docs/core/run-time-config/threading.md +++ b/docs/core/run-time-config/threading.md @@ -6,6 +6,10 @@ ms.topic: reference --- # Run-time configuration options for threading +This article details the settings you can use to configure threading in .NET. + +[!INCLUDE [complus-prefix](../../../includes/complus-prefix.md)] + ## CPU groups - Configures whether threads are automatically distributed across CPU groups. @@ -14,7 +18,7 @@ ms.topic: reference | | Setting name | Values | | - | - | - | | **runtimeconfig.json** | N/A | N/A | -| **Environment variable** | `COMPlus_Thread_UseAllCpuGroups` | `0` - disabled
`1` - enabled | +| **Environment variable** | `DOTNET_Thread_UseAllCpuGroups` | `0` - disabled
`1` - enabled | ## Minimum threads diff --git a/docs/core/testing/order-unit-tests.md b/docs/core/testing/order-unit-tests.md index 921c20d502428..76599266445d4 100644 --- a/docs/core/testing/order-unit-tests.md +++ b/docs/core/testing/order-unit-tests.md @@ -5,6 +5,7 @@ author: IEvangelist ms.author: dapine ms.date: 05/18/2020 zone_pivot_groups: unit-testing-framework-set-one +recommendations: false --- # Order unit tests diff --git a/docs/core/testing/selective-unit-tests.md b/docs/core/testing/selective-unit-tests.md index bc0e110205854..e9e23f13ed5c0 100644 --- a/docs/core/testing/selective-unit-tests.md +++ b/docs/core/testing/selective-unit-tests.md @@ -4,6 +4,7 @@ description: How to use a filter expression to run selective unit tests with the author: smadala ms.date: 05/18/2020 zone_pivot_groups: unit-testing-framework-set-one +ms.topic: reference --- # Run selective unit tests diff --git a/docs/core/testing/snippets/unit-testing-using-mstest/csharp/PrimeService.Tests/PrimeService.Tests.csproj b/docs/core/testing/snippets/unit-testing-using-mstest/csharp/PrimeService.Tests/PrimeService.Tests.csproj new file mode 100644 index 0000000000000..d2f82b32fef1e --- /dev/null +++ b/docs/core/testing/snippets/unit-testing-using-mstest/csharp/PrimeService.Tests/PrimeService.Tests.csproj @@ -0,0 +1,18 @@ + + + + net5.0 + + + + + + + + + + + + + + diff --git a/samples/snippets/core/testing/unit-testing-using-mstest/csharp/PrimeService.Tests/PrimeService_IsPrimeShould.cs b/docs/core/testing/snippets/unit-testing-using-mstest/csharp/PrimeService.Tests/PrimeService_IsPrimeShould.cs similarity index 100% rename from samples/snippets/core/testing/unit-testing-using-mstest/csharp/PrimeService.Tests/PrimeService_IsPrimeShould.cs rename to docs/core/testing/snippets/unit-testing-using-mstest/csharp/PrimeService.Tests/PrimeService_IsPrimeShould.cs diff --git a/samples/snippets/core/testing/unit-testing-using-mstest/csharp/PrimeService/PrimeService.cs b/docs/core/testing/snippets/unit-testing-using-mstest/csharp/PrimeService/PrimeService.cs similarity index 100% rename from samples/snippets/core/testing/unit-testing-using-mstest/csharp/PrimeService/PrimeService.cs rename to docs/core/testing/snippets/unit-testing-using-mstest/csharp/PrimeService/PrimeService.cs diff --git a/docs/core/testing/snippets/unit-testing-using-mstest/csharp/PrimeService/PrimeService.csproj b/docs/core/testing/snippets/unit-testing-using-mstest/csharp/PrimeService/PrimeService.csproj new file mode 100644 index 0000000000000..f208d303c9811 --- /dev/null +++ b/docs/core/testing/snippets/unit-testing-using-mstest/csharp/PrimeService/PrimeService.csproj @@ -0,0 +1,7 @@ + + + + net5.0 + + + diff --git a/samples/snippets/core/testing/unit-testing-using-mstest/csharp/README.md b/docs/core/testing/snippets/unit-testing-using-mstest/csharp/README.md similarity index 100% rename from samples/snippets/core/testing/unit-testing-using-mstest/csharp/README.md rename to docs/core/testing/snippets/unit-testing-using-mstest/csharp/README.md diff --git a/docs/core/testing/snippets/unit-testing-using-mstest/csharp/unit-testing-using-mstest.sln b/docs/core/testing/snippets/unit-testing-using-mstest/csharp/unit-testing-using-mstest.sln new file mode 100644 index 0000000000000..ddbc9e53e286c --- /dev/null +++ b/docs/core/testing/snippets/unit-testing-using-mstest/csharp/unit-testing-using-mstest.sln @@ -0,0 +1,48 @@ + +Microsoft Visual Studio Solution File, Format Version 12.00 +# Visual Studio Version 16 +VisualStudioVersion = 16.6.30114.105 +MinimumVisualStudioVersion = 10.0.40219.1 +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PrimeService", "PrimeService\PrimeService.csproj", "{F8B8C6CD-C8E1-4927-AC7B-865925B6F6FD}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PrimeService.Tests", "PrimeService.Tests\PrimeService.Tests.csproj", "{A965B579-FEA6-4253-8D30-EEA46F655DD9}" +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Any CPU = Debug|Any CPU + Debug|x64 = Debug|x64 + Debug|x86 = Debug|x86 + Release|Any CPU = Release|Any CPU + Release|x64 = Release|x64 + Release|x86 = Release|x86 + EndGlobalSection + GlobalSection(SolutionProperties) = preSolution + HideSolutionNode = FALSE + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {F8B8C6CD-C8E1-4927-AC7B-865925B6F6FD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {F8B8C6CD-C8E1-4927-AC7B-865925B6F6FD}.Debug|Any CPU.Build.0 = Debug|Any CPU + {F8B8C6CD-C8E1-4927-AC7B-865925B6F6FD}.Debug|x64.ActiveCfg = Debug|Any CPU + {F8B8C6CD-C8E1-4927-AC7B-865925B6F6FD}.Debug|x64.Build.0 = Debug|Any CPU + {F8B8C6CD-C8E1-4927-AC7B-865925B6F6FD}.Debug|x86.ActiveCfg = Debug|Any CPU + {F8B8C6CD-C8E1-4927-AC7B-865925B6F6FD}.Debug|x86.Build.0 = Debug|Any CPU + {F8B8C6CD-C8E1-4927-AC7B-865925B6F6FD}.Release|Any CPU.ActiveCfg = Release|Any CPU + {F8B8C6CD-C8E1-4927-AC7B-865925B6F6FD}.Release|Any CPU.Build.0 = Release|Any CPU + {F8B8C6CD-C8E1-4927-AC7B-865925B6F6FD}.Release|x64.ActiveCfg = Release|Any CPU + {F8B8C6CD-C8E1-4927-AC7B-865925B6F6FD}.Release|x64.Build.0 = Release|Any CPU + {F8B8C6CD-C8E1-4927-AC7B-865925B6F6FD}.Release|x86.ActiveCfg = Release|Any CPU + {F8B8C6CD-C8E1-4927-AC7B-865925B6F6FD}.Release|x86.Build.0 = Release|Any CPU + {A965B579-FEA6-4253-8D30-EEA46F655DD9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {A965B579-FEA6-4253-8D30-EEA46F655DD9}.Debug|Any CPU.Build.0 = Debug|Any CPU + {A965B579-FEA6-4253-8D30-EEA46F655DD9}.Debug|x64.ActiveCfg = Debug|Any CPU + {A965B579-FEA6-4253-8D30-EEA46F655DD9}.Debug|x64.Build.0 = Debug|Any CPU + {A965B579-FEA6-4253-8D30-EEA46F655DD9}.Debug|x86.ActiveCfg = Debug|Any CPU + {A965B579-FEA6-4253-8D30-EEA46F655DD9}.Debug|x86.Build.0 = Debug|Any CPU + {A965B579-FEA6-4253-8D30-EEA46F655DD9}.Release|Any CPU.ActiveCfg = Release|Any CPU + {A965B579-FEA6-4253-8D30-EEA46F655DD9}.Release|Any CPU.Build.0 = Release|Any CPU + {A965B579-FEA6-4253-8D30-EEA46F655DD9}.Release|x64.ActiveCfg = Release|Any CPU + {A965B579-FEA6-4253-8D30-EEA46F655DD9}.Release|x64.Build.0 = Release|Any CPU + {A965B579-FEA6-4253-8D30-EEA46F655DD9}.Release|x86.ActiveCfg = Release|Any CPU + {A965B579-FEA6-4253-8D30-EEA46F655DD9}.Release|x86.Build.0 = Release|Any CPU + EndGlobalSection +EndGlobal diff --git a/docs/core/testing/unit-testing-code-coverage.md b/docs/core/testing/unit-testing-code-coverage.md index bd3aee72270b7..4901a109cbfd4 100644 --- a/docs/core/testing/unit-testing-code-coverage.md +++ b/docs/core/testing/unit-testing-code-coverage.md @@ -4,6 +4,7 @@ description: Learn how to use the code coverage capabilities for .NET unit tests author: IEvangelist ms.author: dapine ms.date: 02/10/2021 +recommendations: false --- # Use code coverage for unit testing @@ -22,7 +23,7 @@ The "system under test" refers to the code that you're writing unit tests agains ### Create a class library -From a command prompt in a new directory named `UnitTestingCodeCoverage`, create a new .NET standard class library using the [`dotnet new classlib`](../tools/dotnet-new.md#classlib) command: +From a command prompt in a new directory named `UnitTestingCodeCoverage`, create a new .NET standard class library using the [`dotnet new classlib`](../tools/dotnet-new-sdk-templates.md#classlib) command: ```dotnetcli dotnet new classlib -n Numbers @@ -60,7 +61,7 @@ namespace System.Numbers ### Create test projects -Create two new **xUnit Test Project (.NET Core)** templates from the same command prompt using the [`dotnet new xunit`](../tools/dotnet-new.md#test) command: +Create two new **xUnit Test Project (.NET Core)** templates from the same command prompt using the [`dotnet new xunit`](../tools/dotnet-new-sdk-templates.md#test) command: ```dotnetcli dotnet new xunit -n XUnit.Coverlet.Collector diff --git a/docs/core/testing/unit-testing-fsharp-with-dotnet-test.md b/docs/core/testing/unit-testing-fsharp-with-dotnet-test.md index 5396e0f76936d..1fc72be04b8b2 100644 --- a/docs/core/testing/unit-testing-fsharp-with-dotnet-test.md +++ b/docs/core/testing/unit-testing-fsharp-with-dotnet-test.md @@ -7,7 +7,7 @@ ms.date: 08/30/2017 --- # Unit testing F# libraries in .NET Core using dotnet test and xUnit -This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/master/core/getting-started/unit-testing-with-fsharp/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). +This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/main/core/getting-started/unit-testing-with-fsharp/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). [!INCLUDE [testing an ASP.NET Core project from .NET Core](../../../includes/core-testing-note-aspnet.md)] @@ -62,7 +62,7 @@ The test project requires other packages to create and run unit tests. `dotnet n dotnet add reference ../MathService/MathService.fsproj ``` -You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-with-fsharp/MathService.Tests/MathService.Tests.fsproj) on GitHub. +You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-with-fsharp/MathService.Tests/MathService.Tests.fsproj) on GitHub. You have the following final solution layout: diff --git a/docs/core/testing/unit-testing-fsharp-with-mstest.md b/docs/core/testing/unit-testing-fsharp-with-mstest.md index 98bc00145808c..52dcde1bf9f10 100644 --- a/docs/core/testing/unit-testing-fsharp-with-mstest.md +++ b/docs/core/testing/unit-testing-fsharp-with-mstest.md @@ -7,7 +7,7 @@ ms.date: 08/30/2017 --- # Unit testing F# libraries in .NET Core using dotnet test and MSTest -This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/master/core/getting-started/unit-testing-with-fsharp-mstest/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). +This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/main/core/getting-started/unit-testing-with-fsharp-mstest/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). [!INCLUDE [testing an ASP.NET Core project from .NET Core](../../../includes/core-testing-note-aspnet.md)] @@ -62,7 +62,7 @@ The test project requires other packages to create and run unit tests. `dotnet n dotnet add reference ../MathService/MathService.fsproj ``` -You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-with-fsharp/MathService.Tests/MathService.Tests.fsproj) on GitHub. +You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-with-fsharp/MathService.Tests/MathService.Tests.fsproj) on GitHub. You have the following final solution layout: diff --git a/docs/core/testing/unit-testing-fsharp-with-nunit.md b/docs/core/testing/unit-testing-fsharp-with-nunit.md index 3026b9adcd059..0fed4070d20a2 100644 --- a/docs/core/testing/unit-testing-fsharp-with-nunit.md +++ b/docs/core/testing/unit-testing-fsharp-with-nunit.md @@ -8,7 +8,7 @@ dev_langs: --- # Unit testing F# libraries in .NET Core using dotnet test and NUnit -This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/master/core/getting-started/unit-testing-with-fsharp-nunit/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). +This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/main/core/getting-started/unit-testing-with-fsharp-nunit/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). [!INCLUDE [testing an ASP.NET Core project from .NET Core](../../../includes/core-testing-note-aspnet.md)] @@ -88,7 +88,7 @@ The test project requires other packages to create and run unit tests. `dotnet n dotnet add reference ../MathService/MathService.fsproj ``` -You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-with-fsharp/MathService.Tests/MathService.Tests.fsproj) on GitHub. +You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-with-fsharp/MathService.Tests/MathService.Tests.fsproj) on GitHub. You have the following final solution layout: diff --git a/docs/core/testing/unit-testing-visual-basic-with-dotnet-test.md b/docs/core/testing/unit-testing-visual-basic-with-dotnet-test.md index a04f1c18ee893..76eaa29e5a843 100644 --- a/docs/core/testing/unit-testing-visual-basic-with-dotnet-test.md +++ b/docs/core/testing/unit-testing-visual-basic-with-dotnet-test.md @@ -7,7 +7,7 @@ ms.date: 05/18/2020 --- # Unit testing Visual Basic .NET Core libraries using dotnet test and xUnit -This tutorial shows how to build a solution containing a unit test project and library project. To follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/master/core/getting-started/unit-testing-using-dotnet-test/). For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). +This tutorial shows how to build a solution containing a unit test project and library project. To follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/main/core/getting-started/unit-testing-using-dotnet-test/). For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). ## Create the solution @@ -216,7 +216,7 @@ Public Function IsPrime(candidate As Integer) As Boolean End Function ``` -Following the TDD approach, add more failing tests, then update the target code. See the [finished version of the tests](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-vb-dotnet-test/PrimeService.Tests/PrimeService_IsPrimeShould.vb) and the [complete implementation of the library](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-vb-dotnet-test/PrimeService/PrimeService.vb). +Following the TDD approach, add more failing tests, then update the target code. See the [finished version of the tests](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-vb-dotnet-test/PrimeService.Tests/PrimeService_IsPrimeShould.vb) and the [complete implementation of the library](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-vb-dotnet-test/PrimeService/PrimeService.vb). The completed `IsPrime` method is not an efficient algorithm for testing primality. diff --git a/docs/core/testing/unit-testing-visual-basic-with-mstest.md b/docs/core/testing/unit-testing-visual-basic-with-mstest.md index 1fa36600c6855..0c225f7a54e23 100644 --- a/docs/core/testing/unit-testing-visual-basic-with-mstest.md +++ b/docs/core/testing/unit-testing-visual-basic-with-mstest.md @@ -7,7 +7,7 @@ ms.date: 09/01/2017 --- # Unit testing Visual Basic .NET Core libraries using dotnet test and MSTest -This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/master/core/getting-started/unit-testing-vb-mstest/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). +This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/main/core/getting-started/unit-testing-vb-mstest/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). [!INCLUDE [testing an ASP.NET Core project from .NET Core](../../../includes/core-testing-note-aspnet.md)] @@ -67,7 +67,7 @@ The test project requires other packages to create and run unit tests. `dotnet n dotnet add reference ../PrimeService/PrimeService.vbproj ``` -You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-vb-mstest/PrimeService.Tests/PrimeService.Tests.vbproj) on GitHub. +You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-vb-mstest/PrimeService.Tests/PrimeService.Tests.vbproj) on GitHub. You have the following final solution layout: @@ -136,6 +136,6 @@ Run `dotnet test`, and two of these tests fail. To make all of the tests pass, c if candidate < 2 ``` -Continue to iterate by adding more tests, more theories, and more code in the main library. You have the [finished version of the tests](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-vb-mstest/PrimeService.Tests/PrimeService_IsPrimeShould.vb) and the [complete implementation of the library](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-vb-mstest/PrimeService/PrimeService.vb). +Continue to iterate by adding more tests, more theories, and more code in the main library. You have the [finished version of the tests](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-vb-mstest/PrimeService.Tests/PrimeService_IsPrimeShould.vb) and the [complete implementation of the library](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-vb-mstest/PrimeService/PrimeService.vb). You've built a small library and a set of unit tests for that library. You've structured the solution so that adding new packages and tests is part of the normal workflow. You've concentrated most of your time and effort on solving the goals of the application. diff --git a/docs/core/testing/unit-testing-visual-basic-with-nunit.md b/docs/core/testing/unit-testing-visual-basic-with-nunit.md index 836aac644e1fc..e9aa1366bea69 100644 --- a/docs/core/testing/unit-testing-visual-basic-with-nunit.md +++ b/docs/core/testing/unit-testing-visual-basic-with-nunit.md @@ -6,7 +6,7 @@ ms.date: 10/04/2018 --- # Unit testing Visual Basic .NET Core libraries using dotnet test and NUnit -This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/master/core/getting-started/unit-testing-vb-nunit/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). +This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/main/core/getting-started/unit-testing-vb-nunit/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). [!INCLUDE [testing an ASP.NET Core project from .NET Core](../../../includes/core-testing-note-aspnet.md)] @@ -84,7 +84,7 @@ The test project requires other packages to create and run unit tests. `dotnet n dotnet add reference ../PrimeService/PrimeService.vbproj ``` -You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-vb-nunit/PrimeService.Tests/PrimeService.Tests.vbproj) on GitHub. +You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-vb-nunit/PrimeService.Tests/PrimeService.Tests.vbproj) on GitHub. You have the following final solution layout: @@ -157,6 +157,6 @@ Run `dotnet test`, and two of these tests fail. To make all of the tests pass, c if candidate < 2 ``` -Continue to iterate by adding more tests, more theories, and more code in the main library. You have the [finished version of the tests](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-vb-nunit/PrimeService.Tests/PrimeService_IsPrimeShould.vb) and the [complete implementation of the library](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-vb-nunit/PrimeService/PrimeService.vb). +Continue to iterate by adding more tests, more theories, and more code in the main library. You have the [finished version of the tests](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-vb-nunit/PrimeService.Tests/PrimeService_IsPrimeShould.vb) and the [complete implementation of the library](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-vb-nunit/PrimeService/PrimeService.vb). You've built a small library and a set of unit tests for that library. You've structured the solution so that adding new packages and tests is part of the normal workflow. You've concentrated most of your time and effort on solving the goals of the application. diff --git a/docs/core/testing/unit-testing-with-dotnet-test.md b/docs/core/testing/unit-testing-with-dotnet-test.md index 99b7e7ea8f107..7095819f88873 100644 --- a/docs/core/testing/unit-testing-with-dotnet-test.md +++ b/docs/core/testing/unit-testing-with-dotnet-test.md @@ -7,7 +7,7 @@ ms.date: 10/21/2020 --- # Unit testing C# in .NET Core using dotnet test and xUnit -This tutorial shows how to build a solution containing a unit test project and source code project. To follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/master/core/getting-started/unit-testing-using-dotnet-test/). For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). +This tutorial shows how to build a solution containing a unit test project and source code project. To follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/main/core/getting-started/unit-testing-using-dotnet-test/). For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). ## Create the solution @@ -213,7 +213,7 @@ public bool IsPrime(int candidate) } ``` -Following the TDD approach, add more failing tests, then update the target code. See the [finished version of the tests](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-using-dotnet-test/PrimeService.Tests/PrimeService_IsPrimeShould.cs) and the [complete implementation of the library](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-using-dotnet-test/PrimeService/PrimeService.cs). +Following the TDD approach, add more failing tests, then update the target code. See the [finished version of the tests](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-using-dotnet-test/PrimeService.Tests/PrimeService_IsPrimeShould.cs) and the [complete implementation of the library](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-using-dotnet-test/PrimeService/PrimeService.cs). The completed `IsPrime` method is not an efficient algorithm for testing primality. diff --git a/docs/core/testing/unit-testing-with-mstest.md b/docs/core/testing/unit-testing-with-mstest.md index 6f38f12999b88..b30ffb9e153be 100644 --- a/docs/core/testing/unit-testing-with-mstest.md +++ b/docs/core/testing/unit-testing-with-mstest.md @@ -1,20 +1,23 @@ --- -title: Unit testing C# with MSTest and .NET Core -description: Learn unit test concepts in C# and .NET Core through an interactive experience building a sample solution step-by-step using dotnet test and MSTest. +title: Unit testing C# with MSTest and .NET +description: Learn unit test concepts in C# and .NET through an interactive experience building a sample solution step-by-step using dotnet test and MSTest. author: ncarandini ms.author: wiwagn -ms.date: 10/21/2020 +ms.date: 05/19/2021 --- -# Unit testing C# with MSTest and .NET Core +# Unit testing C# with MSTest and .NET -This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-using-mstest/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). +This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-using-mstest/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). -[!INCLUDE [testing an ASP.NET Core project from .NET Core](../../../includes/core-testing-note-aspnet.md)] +[!INCLUDE [testing an ASP.NET Core project from .NET](../../../includes/core-testing-note-aspnet.md)] + +## Prerequisites + +* The [.NET 5.0 SDK or later](https://dotnet.microsoft.com/download) ## Create the source project -Open a shell window. Create a directory called *unit-testing-using-mstest* to hold the solution. Inside this new directory, run [`dotnet new sln`](../tools/dotnet-new.md) to create -a new solution file for the class library and the test project. Next, create a *PrimeService* directory. The following outline shows the directory and file structure thus far: +Open a shell window. Create a directory called *unit-testing-using-mstest* to hold the solution. Inside this new directory, run [`dotnet new sln`](../tools/dotnet-new.md) to create a new solution file for the class library and the test project. Create a *PrimeService* directory. The following outline shows the directory and file structure thus far: ```console /unit-testing-using-mstest @@ -22,7 +25,7 @@ a new solution file for the class library and the test project. Next, create a * /PrimeService ``` -Make *PrimeService* the current directory and run [`dotnet new classlib`](../tools/dotnet-new.md) to create the source project. Rename *Class1.cs* to *PrimeService.cs*. You create a failing implementation of the `PrimeService` class: +Make *PrimeService* the current directory and run [`dotnet new classlib`](../tools/dotnet-new.md) to create the source project. Rename *Class1.cs* to *PrimeService.cs*. Replace the code in the file with the following code to create a failing implementation of the `PrimeService` class: ```csharp using System; @@ -39,11 +42,15 @@ namespace Prime.Services } ``` -Change the directory back to the *unit-testing-using-mstest* directory. Run [`dotnet sln add PrimeService/PrimeService.csproj`](../tools/dotnet-sln.md) to add the class library project to the solution. +Change the directory back to the *unit-testing-using-mstest* directory. Run [`dotnet sln add`](../tools/dotnet-sln.md) to add the class library project to the solution: + +```dotnetcli +dotnet sln add PrimeService/PrimeService.csproj +``` ## Create the test project -Next, create the *PrimeService.Tests* directory. The following outline shows the directory structure: +Create the *PrimeService.Tests* directory. The following outline shows the directory structure: ```console /unit-testing-using-mstest @@ -54,23 +61,26 @@ Next, create the *PrimeService.Tests* directory. The following outline shows the /PrimeService.Tests ``` -Make the *PrimeService.Tests* directory the current directory and create a new project using [`dotnet new mstest`](../tools/dotnet-new.md). The dotnet new command creates a test project that uses MSTest as the test library. The generated template configures the test runner in the *PrimeServiceTests.csproj* file: +Make the *PrimeService.Tests* directory the current directory and create a new project using [`dotnet new mstest`](../tools/dotnet-new.md). The dotnet new command creates a test project that uses MSTest as the test library. The template configures the test runner in the *PrimeServiceTests.csproj* file: ```xml - - - + + + + ``` -The test project requires other packages to create and run unit tests. `dotnet new` in the previous step added the MSTest SDK, the MSTest test framework, and the MSTest runner. Now, add the `PrimeService` class library as another dependency to the project. Use the [`dotnet add reference`](../tools/dotnet-add-reference.md) command: +The test project requires other packages to create and run unit tests. `dotnet new` in the previous step added the MSTest SDK, the MSTest test framework, the MSTest runner, and coverlet for code coverage reporting. + +Add the `PrimeService` class library as another dependency to the project. Use the [`dotnet add reference`](../tools/dotnet-add-reference.md) command: ```dotnetcli dotnet add reference ../PrimeService/PrimeService.csproj ``` -You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-using-mstest/PrimeService.Tests/PrimeService.Tests.csproj) on GitHub. +You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-using-mstest/PrimeService.Tests/PrimeService.Tests.csproj) on GitHub. The following outline shows the final solution layout: @@ -85,11 +95,15 @@ The following outline shows the final solution layout: PrimeServiceTests.csproj ``` -Execute [`dotnet sln add .\PrimeService.Tests\PrimeService.Tests.csproj`](../tools/dotnet-sln.md) in the *unit-testing-using-mstest* directory. +Change to the *unit-testing-using-mstest* directory, and run [`dotnet sln add`](../tools/dotnet-sln.md): + +```dotnetcli +dotnet sln add .\PrimeService.Tests\PrimeService.Tests.csproj +``` ## Create the first test -You write one failing test, make it pass, then repeat the process. Remove *UnitTest1.cs* from the *PrimeService.Tests* directory and create a new C# file named *PrimeService_IsPrimeShould.cs* with the following content: +Write a failing test, make it pass, then repeat the process. Remove *UnitTest1.cs* from the *PrimeService.Tests* directory and create a new C# file named *PrimeService_IsPrimeShould.cs* with the following content: ```csharp using Microsoft.VisualStudio.TestTools.UnitTesting; @@ -100,11 +114,17 @@ namespace Prime.UnitTests.Services [TestClass] public class PrimeService_IsPrimeShould { + private readonly PrimeService _primeService; + + public PrimeService_IsPrimeShould() + { + _primeService = new PrimeService(); + } + [TestMethod] public void IsPrime_InputIs1_ReturnFalse() { - var primeService = new PrimeService(); - bool result = primeService.IsPrime(1); + bool result = _primeService.IsPrime(1); Assert.IsFalse(result, "1 should not be prime"); } @@ -135,17 +155,17 @@ In the *unit-testing-using-mstest* directory, run `dotnet test` again. The `dotn Now that you've made one test pass, it's time to write more. There are a few other simple cases for prime numbers: 0, -1. You could add new tests with the [TestMethod attribute](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute), but that quickly becomes tedious. There are other MSTest attributes that enable you to write a suite of similar tests. A [DataTestMethod attribute](xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataTestMethodAttribute) represents a suite of tests that execute the same code but have different input arguments. You can use the [DataRow attribute](xref:Microsoft.VisualStudio.TestTools.UnitTesting.DataRowAttribute) to specify values for those inputs. -Instead of creating new tests, apply these two attributes to create a single data driven test. The data driven test is a method that tests several values less than two, which is the lowest prime number: +Instead of creating new tests, apply these two attributes to create a single data driven test. The data driven test is a method that tests several values less than two, which is the lowest prime number. Add a new test method in *PrimeService_IsPrimeShould.cs*: -[!code-csharp[Sample_TestCode](../../../samples/snippets/core/testing/unit-testing-using-mstest/csharp/PrimeService.Tests/PrimeService_IsPrimeShould.cs?name=Sample_TestCode)] +:::code language="csharp" source="snippets/unit-testing-using-mstest/csharp/PrimeService.Tests/PrimeService_IsPrimeShould.cs" id="Sample_TestCode"::: -Run `dotnet test`, and two of these tests fail. To make all of the tests pass, change the `if` clause at the beginning of the method: +Run `dotnet test`, and two of these tests fail. To make all of the tests pass, change the `if` clause at the beginning of the `IsPrime` method in the *PrimeService.cs* file: ```csharp if (candidate < 2) ``` -Continue to iterate by adding more tests, more theories, and more code in the main library. You have the [finished version of the tests](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-using-mstest/PrimeService.Tests/PrimeService_IsPrimeShould.cs) and the [complete implementation of the library](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-using-mstest/PrimeService/PrimeService.cs). +Continue to iterate by adding more tests, more theories, and more code in the main library. You have the [finished version of the tests](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-using-mstest/PrimeService.Tests/PrimeService_IsPrimeShould.cs) and the [complete implementation of the library](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-using-mstest/PrimeService/PrimeService.cs). You've built a small library and a set of unit tests for that library. You've structured the solution so that adding new packages and tests is part of the normal workflow. You've concentrated most of your time and effort on solving the goals of the application. diff --git a/docs/core/testing/unit-testing-with-nunit.md b/docs/core/testing/unit-testing-with-nunit.md index 8b3017249ce58..30540b51babf4 100644 --- a/docs/core/testing/unit-testing-with-nunit.md +++ b/docs/core/testing/unit-testing-with-nunit.md @@ -6,7 +6,7 @@ ms.date: 08/31/2018 --- # Unit testing C# with NUnit and .NET Core -This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-using-nunit/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). +This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-using-nunit/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). [!INCLUDE [testing an ASP.NET Core project from .NET Core](../../../includes/core-testing-note-aspnet.md)] @@ -89,7 +89,7 @@ The test project requires other packages to create and run unit tests. `dotnet n dotnet add reference ../PrimeService/PrimeService.csproj ``` -You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-using-nunit/PrimeService.Tests/PrimeService.Tests.csproj) on GitHub. +You can see the entire file in the [samples repository](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-using-nunit/PrimeService.Tests/PrimeService.Tests.csproj) on GitHub. The following outline shows the final solution layout: @@ -175,6 +175,6 @@ Run `dotnet test`, and two of these tests fail. To make all of the tests pass, c if (candidate < 2) ``` -Continue to iterate by adding more tests, more theories, and more code in the main library. You have the [finished version of the tests](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-using-nunit/PrimeService.Tests/PrimeService_IsPrimeShould.cs) and the [complete implementation of the library](https://github.com/dotnet/samples/blob/master/core/getting-started/unit-testing-using-nunit/PrimeService/PrimeService.cs). +Continue to iterate by adding more tests, more theories, and more code in the main library. You have the [finished version of the tests](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-using-nunit/PrimeService.Tests/PrimeService_IsPrimeShould.cs) and the [complete implementation of the library](https://github.com/dotnet/samples/blob/main/core/getting-started/unit-testing-using-nunit/PrimeService/PrimeService.cs). You've built a small library and a set of unit tests for that library. You've structured the solution so that adding new packages and tests is part of the normal workflow. You've concentrated most of your time and effort on solving the goals of the application. diff --git a/docs/core/tools/dependencies.md b/docs/core/tools/dependencies.md index 397ef14b1fc5e..bb6757bf47f24 100644 --- a/docs/core/tools/dependencies.md +++ b/docs/core/tools/dependencies.md @@ -70,5 +70,5 @@ dotnet remove package Microsoft.EntityFrameworkCore ## See also -* [Package references in project files](../project-sdk/msbuild-props.md#reference-properties-and-items) +* [Package references in project files](../project-sdk/msbuild-props.md#reference-properties) * [dotnet list package command](dotnet-list-package.md) diff --git a/docs/core/tools/dotnet-add-package.md b/docs/core/tools/dotnet-add-package.md index 171da7067eb5f..15b6f4934e535 100644 --- a/docs/core/tools/dotnet-add-package.md +++ b/docs/core/tools/dotnet-add-package.md @@ -85,7 +85,7 @@ The *ToDo.csproj* file now contains a [``](/nuget/consume-pack - **`--prerelease`** - Allows prerelease packages to be installed. + Allows prerelease packages to be installed. Available since .NET Core 5 SDK - **`-s|--source `** diff --git a/docs/core/tools/dotnet-build.md b/docs/core/tools/dotnet-build.md index 0d4f5b21ac701..ed55d9a8b6fe2 100644 --- a/docs/core/tools/dotnet-build.md +++ b/docs/core/tools/dotnet-build.md @@ -61,6 +61,9 @@ To produce a library, omit the `` property or change its value to `L In addition to its options, the `dotnet build` command accepts MSBuild options, such as `-p` for setting properties or `-l` to define a logger. For more information about these options, see the [MSBuild Command-Line Reference](/visualstudio/msbuild/msbuild-command-line-reference). Or you can also use the [dotnet msbuild](dotnet-msbuild.md) command. +> [!NOTE] +> When `dotnet build` is run automatically by `dotnet run`, arguments like `-property:property=value` aren't respected. + Running `dotnet build` is equivalent to running `dotnet msbuild -restore`; however, the default verbosity of the output is different. ## Arguments diff --git a/docs/core/tools/dotnet-install-script.md b/docs/core/tools/dotnet-install-script.md index 762674fe25c1a..85080c796a218 100644 --- a/docs/core/tools/dotnet-install-script.md +++ b/docs/core/tools/dotnet-install-script.md @@ -261,4 +261,4 @@ The install scripts do not update the registry on Windows. They just download th ## See also - [.NET releases](https://github.com/dotnet/core/releases) -- [.NET Runtime and SDK download archive](https://github.com/dotnet/core/blob/master/release-notes/download-archive.md) +- [.NET Runtime and SDK download archive](https://github.com/dotnet/core/blob/main/release-notes/download-archive.md) diff --git a/docs/core/tools/dotnet-list-package.md b/docs/core/tools/dotnet-list-package.md index b4774046715bc..57b293fa6b5a3 100644 --- a/docs/core/tools/dotnet-list-package.md +++ b/docs/core/tools/dotnet-list-package.md @@ -25,7 +25,7 @@ dotnet list package -h|--help ## Description -The `dotnet list package` command provides a convenient option to list all NuGet package references for a specific project or a solution. You first need to build the project in order to have the assets needed for this command to process. The following example shows the output of the `dotnet list package` command for the [SentimentAnalysis](https://github.com/dotnet/samples/tree/master/machine-learning/tutorials/SentimentAnalysis) project: +The `dotnet list package` command provides a convenient option to list all NuGet package references for a specific project or a solution. You first need to build the project in order to have the assets needed for this command to process. The following example shows the output of the `dotnet list package` command for the [SentimentAnalysis](https://github.com/dotnet/samples/tree/main/machine-learning/tutorials/SentimentAnalysis) project: ```output Project 'SentimentAnalysis' has the following package references @@ -52,7 +52,7 @@ Project `SentimentAnalysis` has the following updates to its packages > Microsoft.ML 1.4.0 1.4.0 1.5.0-preview ``` -If you need to find out whether your project has transitive dependencies, use the `--include-transitive` option. Transitive dependencies occur when you add a package to your project that in turn relies on another package. The following example shows the output from running the `dotnet list package --include-transitive` command for the [HelloPlugin](https://github.com/dotnet/samples/tree/master/core/extensions/AppWithPlugin/HelloPlugin) project, which displays top-level packages and the packages they depend on: +If you need to find out whether your project has transitive dependencies, use the `--include-transitive` option. Transitive dependencies occur when you add a package to your project that in turn relies on another package. The following example shows the output from running the `dotnet list package --include-transitive` command for the [HelloPlugin](https://github.com/dotnet/samples/tree/main/core/extensions/AppWithPlugin/HelloPlugin) project, which displays top-level packages and the packages they depend on: ```output Project 'HelloPlugin' has the following package references diff --git a/docs/core/tools/dotnet-new-install.md b/docs/core/tools/dotnet-new-install.md new file mode 100644 index 0000000000000..1e1ad28350c9e --- /dev/null +++ b/docs/core/tools/dotnet-new-install.md @@ -0,0 +1,62 @@ +--- +title: dotnet new --install option +description: The dotnet new --install option installs a template package. +ms.date: 04/29/2021 +--- +# dotnet new --install option + +**This article applies to:** ✔️ .NET Core 2.0 SDK and later versions + +## Name + +`dotnet new --install` - installs a template package. + +## Synopsis + +```dotnetcli +dotnet new --install [--interactive] [--nuget-source ] +``` + +## Description + +The `dotnet new --install` command installs a template package from the `PATH` or `NUGET_ID` provided. If you want to install a prerelease version of a template package, specify the version in the format `::`. By default, `dotnet new` passes \* for the version, which represents the latest stable package version. For more information, see the [Examples](#examples) section. + + If a version of the template was already installed when you run this command, the template will be updated to the specified version, or to the latest stable version if no version was specified. + For information on creating custom templates, see [Custom templates for dotnet new](custom-templates.md). + +## Options + +- **`--interactive`** + + Allows the command to stop and wait for user input or action (for example to complete authentication). Available since .NET Core 5.0 SDK. + +- **`--nuget-source `** + + By default, `dotnet new --install` uses the hierarchy of NuGet configuration files from the current directory to determine the NuGet source the package can be installed from. If `--nuget-source` is specified, the source will be added to the list of sources to be checked. + To check the configured sources for the current directory use [`dotnet nuget list source`](dotnet-nuget-list-source.md). For more information, see [Common NuGet Configurations](/nuget/consume-packages/configuring-nuget-behavior) + +## Examples + +- Install the latest version of SPA templates for ASP.NET Core: + + ```dotnetcli + dotnet new --install Microsoft.DotNet.Web.Spa.ProjectTemplates + ``` + +- Install version 2.0 of the SPA templates for ASP.NET Core: + + ```dotnetcli + dotnet new --install Microsoft.DotNet.Web.Spa.ProjectTemplates::2.0.0 + ``` + +- Install version 2.0 of the SPA templates for ASP.NET Core from a custom NuGet source using interactive mode: + + ```dotnetcli + dotnet new --install Microsoft.DotNet.Web.Spa.ProjectTemplates::2.0.0 --nuget-source "https://api.my-custom-nuget.com/v3/index.json" --interactive + ``` + +## See also + +- [dotnet new command](dotnet-new.md) +- [dotnet new --search option](dotnet-new-search.md) +- [Custom templates for dotnet new](custom-templates.md) diff --git a/docs/core/tools/dotnet-new-list.md b/docs/core/tools/dotnet-new-list.md new file mode 100644 index 0000000000000..9b058c122de91 --- /dev/null +++ b/docs/core/tools/dotnet-new-list.md @@ -0,0 +1,109 @@ +--- +title: dotnet new --list option +description: The dotnet new --list option lists available templates. +ms.date: 04/29/2021 +--- +# dotnet new --list option + +**This article applies to:** ✔️ .NET Core 2.0 SDK and later versions + +## Name + +`dotnet new --list` - Lists available templates to be run using `dotnet new`. + +## Synopsis + +```dotnetcli +dotnet new [] -l|--list [--author ] [-lang|--language {"C#"|"F#"|VB}] + [--tag ] [--type ] [--columns ] [--columns-all] +``` + +## Description + +The `dotnet new --list` option lists available templates to use with `dotnet new`. If the is specified, lists templates containing the specified name. This option lists only default and installed templates. To find templates in NuGet that you can install locally, use the [`--search`](dotnet-new-search.md) option. + +## Arguments + +- **`TEMPLATE_NAME`** + + If the argument is specified, only the templates containing `` in template name or short name will be shown. + +## Options + +- **`--author `** + + Filters templates based on template author. Partial match is supported. Available since .NET Core 5.0.300 SDK. + +- **`--columns `** + + Comma-separated list of columns to display in the output. The supported columns are: + - `language` - A comma-separated list of languages supported by the template. + - `tags` - The list of template tags. + - `author` - The template author. + - `type` - The template type: project or item. + + The template name and short name are always shown. The default list of columns is template name, short name, language, and tags. This list is equivalent to specifying `--columns=language,tags`. + Available since .NET Core 5.0.300 SDK. + +- **`--columns-all`** + + Displays all columns in the output. Available since .NET Core 5.0.300 SDK. + +- **`-lang|--language {C#|F#|VB}`** + + Filters templates based on language supported by the template. The language accepted varies by the template. Not valid for some templates. + + > [!NOTE] + > Some shells interpret `#` as a special character. In those cases, enclose the language parameter value in quotes. For example, `dotnet new --list --language "F#"`. + +- **`--tag `** + + Filters templates based on template tags. To be selected, a template must have at least one tag that exactly matches the criteria. Available since .NET Core 5.0.300 SDK. + +- **`--type `** + + Filters templates based on template type. Predefined values are `project` and `item`. + +## Examples + +- List all templates + + ```dotnetcli + dotnet new --list + ``` + +- List all Single Page Application (SPA) templates: + + ```dotnetcli + dotnet new spa --list + ``` + +- List all templates matching the *we* substring. + + ```dotnetcli + dotnet new we --list + ``` + +- List all templates matching the *we* substring that support the F# language. + + ```dotnetcli + dotnet new we --list --language "F#" + ``` + +- List all item templates. + + ```dotnetcli + dotnet new --list --type item + ``` + +- List all C# templates, showing the author and the type in the output. + + ```dotnetcli + dotnet new --list --language "C#" --columns "author,type" + ``` + +## See also + +- [dotnet new command](dotnet-new.md) +- [dotnet new --search option](dotnet-new-search.md) +- [Custom templates for dotnet new](custom-templates.md) diff --git a/docs/core/tools/dotnet-new-sdk-templates.md b/docs/core/tools/dotnet-new-sdk-templates.md new file mode 100644 index 0000000000000..ed59a0510267b --- /dev/null +++ b/docs/core/tools/dotnet-new-sdk-templates.md @@ -0,0 +1,680 @@ +--- +title: .NET default templates for dotnet new +description: The information about dotnet new templates shipped with dotnet SDK. +no-loc: [Blazor, WebAssembly] +ms.date: 04/29/2021 +--- +# .NET default templates for dotnet new + +When you install the [.NET SDK](https://dotnet.microsoft.com/download), you receive over a dozen built-in templates for creating projects and files, including console apps, class libraries, unit test projects, ASP.NET Core apps (including [Angular](https://angular.io/) and [React](https://reactjs.org/) projects), and configuration files. To list the built-in templates, run the `dotnet new` command with the `-l|--list` option: + +```dotnetcli +dotnet new --list +``` + +The following table shows the templates that come pre-installed with the .NET SDK. The default language for the template is shown inside the brackets. Click on the short name link to see the specific template options. + +| Templates | Short name | Language | Tags | Introduced | +|----------------------------------------------|-----------------------------------|--------------|---------------------------------------|------------| +| Console Application | [`console`](#console) | [C#], F#, VB | Common/Console | 1.0 | +| Class library | [`classlib`](#classlib) | [C#], F#, VB | Common/Library | 1.0 | +| WPF Application | [`wpf`](#wpf) | [C#], VB | Common/WPF | 3.0 (5.0 for VB)| +| WPF Class library | [`wpflib`](#wpf) | [C#], VB | Common/WPF | 3.0 (5.0 for VB)| +| WPF Custom Control Library | [`wpfcustomcontrollib`](#wpf) | [C#], VB | Common/WPF | 3.0 (5.0 for VB)| +| WPF User Control Library | [`wpfusercontrollib`](#wpf) | [C#], VB | Common/WPF | 3.0 (5.0 for VB)| +| Windows Forms (WinForms) Application | [`winforms`](#winforms) | [C#], VB | Common/WinForms | 3.0 (5.0 for VB)| +| Windows Forms (WinForms) Class library | [`winformslib`](#winforms) | [C#], VB | Common/WinForms | 3.0 (5.0 for VB)| +| Worker Service | [`worker`](#web-others) | [C#] | Common/Worker/Web | 3.0 | +| Unit Test Project | [`mstest`](#test) | [C#], F#, VB | Test/MSTest | 1.0 | +| NUnit 3 Test Project | [`nunit`](#nunit) | [C#], F#, VB | Test/NUnit | 2.1.400 | +| NUnit 3 Test Item | `nunit-test` | [C#], F#, VB | Test/NUnit | 2.2 | +| xUnit Test Project | [`xunit`](#test) | [C#], F#, VB | Test/xUnit | 1.0 | +| Razor Component | `razorcomponent` | [C#] | Web/ASP.NET | 3.0 | +| Razor Page | [`page`](#page) | [C#] | Web/ASP.NET | 2.0 | +| MVC ViewImports | [`viewimports`](#namespace) | [C#] | Web/ASP.NET | 2.0 | +| MVC ViewStart | `viewstart` | [C#] | Web/ASP.NET | 2.0 | +| Blazor Server App | [`blazorserver`](#blazorserver) | [C#] | Web/Blazor | 3.0 | +| Blazor WebAssembly App | [`blazorwasm`](#blazorwasm) | [C#] | Web/Blazor/WebAssembly | 3.1.300 | +| ASP.NET Core Empty | [`web`](#web) | [C#], F# | Web/Empty | 1.0 | +| ASP.NET Core Web App (Model-View-Controller) | [`mvc`](#web-options) | [C#], F# | Web/MVC | 1.0 | +| ASP.NET Core Web App | [`webapp, razor`](#web-options) | [C#] | Web/MVC/Razor Pages | 2.2, 2.0 | +| ASP.NET Core with Angular | [`angular`](#spa) | [C#] | Web/MVC/SPA | 2.0 | +| ASP.NET Core with React.js | [`react`](#spa) | [C#] | Web/MVC/SPA | 2.0 | +| ASP.NET Core with React.js and Redux | [`reactredux`](#reactredux) | [C#] | Web/MVC/SPA | 2.0 | +| Razor Class Library | [`razorclasslib`](#razorclasslib) | [C#] | Web/Razor/Library/Razor Class Library | 2.1 | +| ASP.NET Core Web API | [`webapi`](#webapi) | [C#], F# | Web/WebAPI | 1.0 | +| ASP.NET Core gRPC Service | [`grpc`](#web-others) | [C#] | Web/gRPC | 3.0 | +| dotnet gitignore file | `gitignore` | | Config | 3.0 | +| global.json file | [`globaljson`](#globaljson) | | Config | 2.0 | +| NuGet Config | `nugetconfig` | | Config | 1.0 | +| Dotnet local tool manifest file | `tool-manifest` | | Config | 3.0 | +| Web Config | `webconfig` | | Config | 1.0 | +| Solution File | `sln` | | Solution | 1.0 | +| Protocol Buffer File | [`proto`](#namespace) | | Web/gRPC | 3.0 | + +## Template options + +Each template may have additional options available. The core templates have the following additional options: + +## `console` + +- **`-f|--framework `** + + Specifies the [framework](../../standard/frameworks.md) to target. Available since .NET Core 3.0 SDK. + + The following table lists the default values according to the SDK version number you're using: + + | SDK version | Default value | + |-------------|-----------------| + | 5.0 | `net5.0` | + | 3.1 | `netcoreapp3.1` | + | 3.0 | `netcoreapp3.0` | + +- **`--langVersion `** + + Sets the `LangVersion` property in the created project file. For example, use `--langVersion 7.3` to use C# 7.3. Not supported for F#. Available since .NET Core 2.2 SDK. + + For a list of default C# versions, see [Defaults](../../csharp/language-reference/configure-language-version.md#defaults). + +- **`--no-restore`** + + If specified, doesn't execute an implicit restore during project creation. Available since .NET Core 2.2 SDK. + +*** + +## `classlib` + +- **`-f|--framework `** + + Specifies the [framework](../../standard/frameworks.md) to target. Values: `net5.0` or `netcoreapp` to create a .NET Class Library or `netstandard` to create a .NET Standard Class Library. The default value for .NET 5.0 SDK is `net5.0`. + +- **`--langVersion `** + + Sets the `LangVersion` property in the created project file. For example, use `--langVersion 7.3` to use C# 7.3. Not supported for F#. Available since .NET Core 2.2 SDK. + + For a list of default C# versions, see [Defaults](../../csharp/language-reference/configure-language-version.md#defaults). + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +*** + +## `wpf`, `wpflib`, `wpfcustomcontrollib`, `wpfusercontrollib` + +- **`-f|--framework `** + + Specifies the [framework](../../standard/frameworks.md) to target. The default value is `net5.0`. Available since .NET Core 3.1 SDK. + +- **`--langVersion `** + + Sets the `LangVersion` property in the created project file. For example, use `--langVersion 7.3` to use C# 7.3. + + For a list of default C# versions, see [Defaults](../../csharp/language-reference/configure-language-version.md#defaults). + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +*** + +## `winforms`, `winformslib` + +- **`--langVersion `** + + Sets the `LangVersion` property in the created project file. For example, use `--langVersion 7.3` to use C# 7.3. + + For a list of default C# versions, see [Defaults](../../csharp/language-reference/configure-language-version.md#defaults). + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +*** + +## `worker`, `grpc` + +- **`-f|--framework `** + + Specifies the [framework](../../standard/frameworks.md) to target. The default value is `netcoreapp3.1`. Available since .NET Core 3.1 SDK. + +- **`--exclude-launch-settings`** + + Excludes *launchSettings.json* from the generated template. + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +*** + +## `mstest`, `xunit` + +- **`-f|--framework `** + + Specifies the [framework](../../standard/frameworks.md) to target. Option available since .NET Core 3.0 SDK. + + The following table lists the default values according to the SDK version number you're using: + + | SDK version | Default value | + |-------------|-----------------| + | 5.0 | `net5.0` | + | 3.1 | `netcoreapp3.1` | + | 3.0 | `netcoreapp3.0` | + +- **`-p|--enable-pack`** + + Enables packaging for the project using [dotnet pack](dotnet-pack.md). + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +*** + +## `nunit` + +- **`-f|--framework `** + + Specifies the [framework](../../standard/frameworks.md) to target. + + The following table lists the default values according to the SDK version number you're using: + + | SDK version | Default value | + |-------------|-----------------| + | 5.0 | `net5.0` | + | 3.1 | `netcoreapp3.1` | + | 3.0 | `netcoreapp3.0` | + | 2.2 | `netcoreapp2.2` | + | 2.1 | `netcoreapp2.1` | + +- **`-p|--enable-pack`** + + Enables packaging for the project using [dotnet pack](dotnet-pack.md). + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +*** + +## `page` + +- **`-na|--namespace `** + + Namespace for the generated code. The default value is `MyApp.Namespace`. + +- **`-np|--no-pagemodel`** + + Creates the page without a PageModel. + +*** + +## `viewimports`, `proto` + +- **`-na|--namespace `** + + Namespace for the generated code. The default value is `MyApp.Namespace`. + +*** + +## `blazorserver` + +- **`-au|--auth `** + + The type of authentication to use. The possible values are: + + - `None` - No authentication (Default). + - `Individual` - Individual authentication. + - `IndividualB2C` - Individual authentication with Azure AD B2C. + - `SingleOrg` - Organizational authentication for a single tenant. + - `MultiOrg` - Organizational authentication for multiple tenants. + - `Windows` - Windows authentication. + +- **`--aad-b2c-instance `** + + The Azure Active Directory B2C instance to connect to. Use with `IndividualB2C` authentication. The default value is `https://login.microsoftonline.com/tfp/`. + +- **`-ssp|--susi-policy-id `** + + The sign-in and sign-up policy ID for this project. Use with `IndividualB2C` authentication. + +- **`-rp|--reset-password-policy-id `** + + The reset password policy ID for this project. Use with `IndividualB2C` authentication. + +- **`-ep|--edit-profile-policy-id `** + + The edit profile policy ID for this project. Use with `IndividualB2C` authentication. + +- **`--aad-instance `** + + The Azure Active Directory instance to connect to. Use with `SingleOrg` or `MultiOrg` authentication. The default value is `https://login.microsoftonline.com/`. + +- **`--client-id `** + + The Client ID for this project. Use with `IndividualB2C`, `SingleOrg`, or `MultiOrg` authentication. The default value is `11111111-1111-1111-11111111111111111`. + +- **`--domain `** + + The domain for the directory tenant. Use with `SingleOrg` or `IndividualB2C` authentication. The default value is `qualified.domain.name`. + +- **`--tenant-id `** + + The TenantId ID of the directory to connect to. Use with `SingleOrg` authentication. The default value is `22222222-2222-2222-2222-222222222222`. + +- **`--callback-path `** + + The request path within the application's base path of the redirect URI. Use with `SingleOrg` or `IndividualB2C` authentication. The default value is `/signin-oidc`. + +- **`-r|--org-read-access`** + + Allows this application read-access to the directory. Only applies to `SingleOrg` or `MultiOrg` authentication. + +- **`--exclude-launch-settings`** + + Excludes *launchSettings.json* from the generated template. + +- **`--no-https`** + + Turns off HTTPS. This option only applies if `Individual`, `IndividualB2C`, `SingleOrg`, or `MultiOrg` aren't being used for `--auth`. + +- **`-uld|--use-local-db`** + + Specifies LocalDB should be used instead of SQLite. Only applies to `Individual` or `IndividualB2C` authentication. + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +*** + +## `blazorwasm` + +- **`-f|--framework `** + + Specifies the [framework](../../standard/frameworks.md) to target. + + The following table lists the default values according to the SDK version number you're using: + + | SDK version | Default value | + |-------------|-----------------| + | 5.0 | `net5.0` | + | 3.1 | `netcoreapp3.1` | + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +- **`-ho|--hosted`** + + Includes an ASP.NET Core host for the Blazor WebAssembly app. + +- **`-au|--auth `** + + The type of authentication to use. The possible values are: + + - `None` - No authentication (Default). + - `Individual` - Individual authentication. + - `IndividualB2C` - Individual authentication with Azure AD B2C. + - `SingleOrg` - Organizational authentication for a single tenant. + +- **`--authority `** + + The authority of the OIDC provider. Use with `Individual` authentication. The default value is `https://login.microsoftonline.com/`. + +- **`--aad-b2c-instance `** + + The Azure Active Directory B2C instance to connect to. Use with `IndividualB2C` authentication. The default value is `https://aadB2CInstance.b2clogin.com/`. + +- **`-ssp|--susi-policy-id `** + + The sign-in and sign-up policy ID for this project. Use with `IndividualB2C` authentication. + +- **`--aad-instance `** + + The Azure Active Directory instance to connect to. Use with `SingleOrg` authentication. The default value is `https://login.microsoftonline.com/`. + +- **`--client-id `** + + The Client ID for this project. Use with `IndividualB2C`, `SingleOrg`, or `Individual` authentication in standalone scenarios. The default value is `33333333-3333-3333-33333333333333333`. + +- **`--domain `** + + The domain for the directory tenant. Use with `SingleOrg` or `IndividualB2C` authentication. The default value is `qualified.domain.name`. + +- **`--app-id-uri `** + + The App ID Uri for the server API you want to call. Use with `SingleOrg` or `IndividualB2C` authentication. The default value is `api.id.uri`. + +- **`--api-client-id `** + + The Client ID for the API that the server hosts. Use with `SingleOrg` or `IndividualB2C` authentication. The default value is `11111111-1111-1111-11111111111111111`. + +- **`-s|--default-scope `** + + The API scope the client needs to request to provision an access token. Use with `SingleOrg` or `IndividualB2C` authentication. The default value is `user_impersonation`. + +- **`--tenant-id `** + + The TenantId ID of the directory to connect to. Use with `SingleOrg` authentication. The default value is `22222222-2222-2222-2222-222222222222`. + +- **`-r|--org-read-access`** + + Allows this application read-access to the directory. Only applies to `SingleOrg` authentication. + +- **`--exclude-launch-settings`** + + Excludes *launchSettings.json* from the generated template. + +- **`-p|--pwa`** + + produces a Progressive Web Application (PWA) supporting installation and offline use. + +- **`--no-https`** + + Turns off HTTPS. This option only applies if `Individual`, `IndividualB2C`, or `SingleOrg` aren't being used for `--auth`. + +- **`-uld|--use-local-db`** + + Specifies LocalDB should be used instead of SQLite. Only applies to `Individual` or `IndividualB2C` authentication. + +- **`--called-api-url `** + + URL of the API to call from the web app. Only applies to `SingleOrg` or `IndividualB2C` authentication without an ASP.NET Core host specified. The default value is `https://graph.microsoft.com/v1.0/me`. + +- **`--calls-graph`** + + Specifies if the web app calls Microsoft Graph. Only applies to `SingleOrg` authentication. + +- **`--called-api-scopes `** + + Scopes to request to call the API from the web app. Only applies to `SingleOrg` or `IndividualB2C` authentication without an ASP.NET Core host specified. The default is `user.read`. + +*** + +## `web` + +- **`--exclude-launch-settings`** + + Excludes *launchSettings.json* from the generated template. + +- **`-f|--framework `** + + Specifies the [framework](../../standard/frameworks.md) to target. Option not available in .NET Core 2.2 SDK. + + The following table lists the default values according to the SDK version number you're using: + + | SDK version | Default value | + |-------------|-----------------| + | 5.0 | `net5.0` | + | 3.1 | `netcoreapp3.1` | + | 3.0 | `netcoreapp3.0` | + | 2.1 | `netcoreapp2.1` | + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +- **`--no-https`** + + Turns off HTTPS. + +*** + +## `mvc`, `webapp` + +- **`-au|--auth `** + + The type of authentication to use. The possible values are: + + - `None` - No authentication (Default). + - `Individual` - Individual authentication. + - `IndividualB2C` - Individual authentication with Azure AD B2C. + - `SingleOrg` - Organizational authentication for a single tenant. + - `MultiOrg` - Organizational authentication for multiple tenants. + - `Windows` - Windows authentication. + +- **`--aad-b2c-instance `** + + The Azure Active Directory B2C instance to connect to. Use with `IndividualB2C` authentication. The default value is `https://login.microsoftonline.com/tfp/`. + +- **`-ssp|--susi-policy-id `** + + The sign-in and sign-up policy ID for this project. Use with `IndividualB2C` authentication. + +- **`-rp|--reset-password-policy-id `** + + The reset password policy ID for this project. Use with `IndividualB2C` authentication. + +- **`-ep|--edit-profile-policy-id `** + + The edit profile policy ID for this project. Use with `IndividualB2C` authentication. + +- **`--aad-instance `** + + The Azure Active Directory instance to connect to. Use with `SingleOrg` or `MultiOrg` authentication. The default value is `https://login.microsoftonline.com/`. + +- **`--client-id `** + + The Client ID for this project. Use with `IndividualB2C`, `SingleOrg`, or `MultiOrg` authentication. The default value is `11111111-1111-1111-11111111111111111`. + +- **`--domain `** + + The domain for the directory tenant. Use with `SingleOrg` or `IndividualB2C` authentication. The default value is `qualified.domain.name`. + +- **`--tenant-id `** + + The TenantId ID of the directory to connect to. Use with `SingleOrg` authentication. The default value is `22222222-2222-2222-2222-222222222222`. + +- **`--callback-path `** + + The request path within the application's base path of the redirect URI. Use with `SingleOrg` or `IndividualB2C` authentication. The default value is `/signin-oidc`. + +- **`-r|--org-read-access`** + + Allows this application read-access to the directory. Only applies to `SingleOrg` or `MultiOrg` authentication. + +- **`--exclude-launch-settings`** + + Excludes *launchSettings.json* from the generated template. + +- **`--no-https`** + + Turns off HTTPS. This option only applies if `Individual`, `IndividualB2C`, `SingleOrg`, or `MultiOrg` aren't being used. + +- **`-uld|--use-local-db`** + + Specifies LocalDB should be used instead of SQLite. Only applies to `Individual` or `IndividualB2C` authentication. + +- **`-f|--framework `** + + Specifies the [framework](../../standard/frameworks.md) to target. Option available since .NET Core 3.0 SDK. + + The following table lists the default values according to the SDK version number you're using: + + | SDK version | Default value | + |-------------|-----------------| + | 5.0 | `net5.0` | + | 3.1 | `netcoreapp3.1` | + | 3.0 | `netcoreapp3.0` | + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +- **`--use-browserlink`** + + Includes BrowserLink in the project. Option not available in .NET Core 2.2 and 3.1 SDK. + +- **`-rrc|--razor-runtime-compilation`** + + Determines if the project is configured to use [Razor runtime compilation](/aspnet/core/mvc/views/view-compilation#runtime-compilation) in Debug builds. Option available since .NET Core 3.1.201 SDK. + +*** + +## `angular`, `react` + +- **`-au|--auth `** + + The type of authentication to use. Available since .NET Core 3.0 SDK. + + The possible values are: + + - `None` - No authentication (Default). + - `Individual` - Individual authentication. + +- **`--exclude-launch-settings`** + + Excludes *launchSettings.json* from the generated template. + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +- **`--no-https`** + + Turns off HTTPS. This option only applies if authentication is `None`. + +- **`-uld|--use-local-db`** + + Specifies LocalDB should be used instead of SQLite. Only applies to `Individual` or `IndividualB2C` authentication. Available since .NET Core 3.0 SDK. + +- **`-f|--framework `** + + Specifies the [framework](../../standard/frameworks.md) to target. Option not available in .NET Core 2.2 SDK. + + The following table lists the default values according to the SDK version number you're using: + + | SDK version | Default value | + |-------------|-----------------| + | 5.0 | `net5.0` | + | 3.1 | `netcoreapp3.1` | + | 3.0 | `netcoreapp3.0` | + | 2.1 | `netcoreapp2.0` | + +*** + +## `reactredux` + +- **`--exclude-launch-settings`** + + Excludes *launchSettings.json* from the generated template. + +- **`-f|--framework `** + + Specifies the [framework](../../standard/frameworks.md) to target. Option not available in .NET Core 2.2 SDK. + + The following table lists the default values according to the SDK version number you're using: + + | SDK version | Default value | + |-------------|-----------------| + | 5.0 | `net5.0` | + | 3.1 | `netcoreapp3.1` | + | 3.0 | `netcoreapp3.0` | + | 2.1 | `netcoreapp2.0` | + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +- **`--no-https`** + + Turns off HTTPS. + +*** + +## `razorclasslib` + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +- **`-s|--support-pages-and-views`** + + Supports adding traditional Razor pages and Views in addition to components to this library. Available since .NET Core 3.0 SDK. + +*** + +## `webapi` + +- **`-au|--auth `** + + The type of authentication to use. The possible values are: + + - `None` - No authentication (Default). + - `IndividualB2C` - Individual authentication with Azure AD B2C. + - `SingleOrg` - Organizational authentication for a single tenant. + - `Windows` - Windows authentication. + +- **`--aad-b2c-instance `** + + The Azure Active Directory B2C instance to connect to. Use with `IndividualB2C` authentication. The default value is `https://login.microsoftonline.com/tfp/`. + +- **`-ssp|--susi-policy-id `** + + The sign-in and sign-up policy ID for this project. Use with `IndividualB2C` authentication. + +- **`--aad-instance `** + + The Azure Active Directory instance to connect to. Use with `SingleOrg` authentication. The default value is `https://login.microsoftonline.com/`. + +- **`--client-id `** + + The Client ID for this project. Use with `IndividualB2C` or `SingleOrg` authentication. The default value is `11111111-1111-1111-11111111111111111`. + +- **`--domain `** + + The domain for the directory tenant. Use with `IndividualB2C` or `SingleOrg` authentication. The default value is `qualified.domain.name`. + +- **`--tenant-id `** + + The TenantId ID of the directory to connect to. Use with `SingleOrg` authentication. The default value is `22222222-2222-2222-2222-222222222222`. + +- **`-r|--org-read-access`** + + Allows this application read-access to the directory. Only applies to `SingleOrg` authentication. + +- **`--exclude-launch-settings`** + + Excludes *launchSettings.json* from the generated template. + +- **`--no-https`** + + Turns off HTTPS. `app.UseHsts` and `app.UseHttpsRedirection` aren't added to `Startup.Configure`. This option only applies if `IndividualB2C` or `SingleOrg` aren't being used for authentication. + +- **`-uld|--use-local-db`** + + Specifies LocalDB should be used instead of SQLite. Only applies to `IndividualB2C` authentication. + +- **`-f|--framework `** + + Specifies the [framework](../../standard/frameworks.md) to target. Option not available in .NET Core 2.2 SDK. + + The following table lists the default values according to the SDK version number you're using: + + | SDK version | Default value | + |-------------|-----------------| + | 5.0 | `net5.0` | + | 3.1 | `netcoreapp3.1` | + | 3.0 | `netcoreapp3.0` | + | 2.1 | `netcoreapp2.1` | + +- **`--no-restore`** + + Doesn't execute an implicit restore during project creation. + +*** + +## `globaljson` + +- **`--sdk-version `** + + Specifies the version of the .NET SDK to use in the *global.json* file. + +## See also + +- [dotnet new command](dotnet-new.md) +- [dotnet new --list option](dotnet-new-list.md) +- [Custom templates for dotnet new](custom-templates.md) +- [Create a custom template for dotnet new](../tutorials/cli-templates-create-item-template.md) diff --git a/docs/core/tools/dotnet-new-search.md b/docs/core/tools/dotnet-new-search.md new file mode 100644 index 0000000000000..50c9c9655eaf0 --- /dev/null +++ b/docs/core/tools/dotnet-new-search.md @@ -0,0 +1,104 @@ +--- +title: dotnet new --search option +description: The dotnet new --search option searches for templates on NuGet.org. +ms.date: 04/29/2021 +--- +# dotnet new --search option + +**This article applies to:** ✔️ .NET Core 5.0.300 SDK and later versions + +## Name + +`dotnet new --search` - searches for the templates supported by `dotnet new` on NuGet.org. + +## Synopsis + +```dotnetcli +dotnet new --search + +dotnet new [] --search [--author ] [-lang|--language {"C#"|"F#"|VB}] + [--package ] [--tag ] [--type ] + [--columns ] [--columns-all] +``` + +## Description + +The `dotnet new --search` option searches for templates supported by `dotnet new` on NuGet.org. When the is specified, searches for templates containing the specified name. + +## Arguments + +- **`TEMPLATE_NAME`** + + If the argument is specified, only templates containing `` in the template name or short name will be shown. + The argument is mandatory when `--author`, `--language`, `--package`, `--tag` or `--type` options are not specified. + +## Options + +- **`--author `** + + Filters templates based on template author. Partial match is supported. + +- **`--columns `** + + Comma-separated list of columns to display in the output. The supported columns are: + - `language` - A comma-separated list of languages supported by the template. + - `tags` - The list of template tags. + - `author` - The template author. + - `type` - The template type: project or item. + + The template name, short name, package name and total downloads count are always shown. The default list of columns is template name, short name, author, language, package, and total downloads. This list is equivalent to specifying `--columns=author,language`. + +- **`--columns-all`** + + Displays all columns in the output. + +- **`-lang|--language {C#|F#|VB}`** + + Filters templates based on language supported by the template. The language accepted varies by the template. Not valid for some templates. + + > [!NOTE] + > Some shells interpret `#` as a special character. In those cases, enclose the language parameter value in quotes. For example, `dotnet new --search --language "F#"`. + +- **`--package `** + + Filters templates based on NuGet package ID. Partial match is supported. + +- **`--tag `** + + Filters templates based on template tags. To be selected, a template must have at least one tag that exactly matches the criteria. + +- **`--type `** + + Filters templates based on template type. Predefined values are `project` and `item`. + +## Examples + +- Search for all templates available on NuGet.org matching the *spa* substring. + + ```dotnetcli + dotnet new spa --search + ``` + +- Search for all templates available on NuGet.org matching the *we* substring and supporting the F# language. + + ```dotnetcli + dotnet new we --search --language "F#" + ``` + +- Search for item templates. + + ```dotnetcli + dotnet new --search --type item + ``` + +- Search for all C# templates, showing the type and tags in the output. + + ```dotnetcli + dotnet new --search --language "C#" --columns "type,tags" + ``` + +## See also + +- [dotnet new command](dotnet-new.md) +- [dotnet new --list option](dotnet-new-list.md) +- [Custom templates for dotnet new](custom-templates.md) diff --git a/docs/core/tools/dotnet-new-uninstall.md b/docs/core/tools/dotnet-new-uninstall.md new file mode 100644 index 0000000000000..f6e8867854a55 --- /dev/null +++ b/docs/core/tools/dotnet-new-uninstall.md @@ -0,0 +1,49 @@ +--- +title: dotnet new --uninstall option +description: The dotnet new --uninstall option uninstalls a template package. +ms.date: 04/29/2021 +--- +# dotnet new --uninstall option + +**This article applies to:** ✔️ .NET Core 2.0 SDK and later versions + +## Name + +`dotnet new --uninstall` - uninstalls a template package. + +## Synopsis + +```dotnetcli + +dotnet new --uninstall + +``` + +## Description + +The `dotnet new --install` uninstalls a template package at the `PATH` or `NUGET_ID` provided. When the `` value isn't specified, all currently installed template packages and their associated templates are displayed. When specifying `NUGET_ID`, don't include the version number. + If you don't specify a parameter to this option, the command lists the installed templates and details about them. + > [!NOTE] + > To uninstall a template using a `PATH`, you need to fully qualify the path. For example, *C:/Users/\/Documents/Templates/GarciaSoftware.ConsoleTemplate.CSharp* will work, but *./GarciaSoftware.ConsoleTemplate.CSharp* from the containing folder will not. + > Don't include a final terminating directory slash on your template path. + +## Examples + +- List the installed templates and details about them, including how to uninstall them: + + ```dotnetcli + dotnet new -u + ``` + +- Uninstall the SPA templates for ASP.NET Core: + + ```dotnetcli + dotnet new -u Microsoft.DotNet.Web.Spa.ProjectTemplates + ``` + +## See also + +- [dotnet new command](dotnet-new.md) +- [dotnet new --list option](dotnet-new-list.md) +- [dotnet new --search option](dotnet-new-search.md) +- [Custom templates for dotnet new](custom-templates.md) diff --git a/docs/core/tools/dotnet-new-update.md b/docs/core/tools/dotnet-new-update.md new file mode 100644 index 0000000000000..1438efc179608 --- /dev/null +++ b/docs/core/tools/dotnet-new-update.md @@ -0,0 +1,34 @@ +--- +title: dotnet new --update-* options +description: The dotnet new --update-* options check for and apply updates to installed template packages. +ms.date: 04/29/2021 +--- +# dotnet new --update-check and --update-apply options + +**This article applies to:** ✔️ .NET Core 3.0 SDK and later versions + +## Name + +`dotnet new --update-check` checks for available updates for installed template packages. + +`dotnet new --update-apply` applies updates to installed template packages. + +## Synopsis + +```dotnetcli +dotnet new --update-check + +dotnet new --update-apply +``` + +## Description + +The `dotnet new --update-check` option checks if there are updates available for the template packs that are currently installed. +The `dotnet new --update-apply` option checks if there are updates available for the template packages that are currently installed and installs them. + +## See also + +- [dotnet new command](dotnet-new.md) +- [dotnet new --search option](dotnet-new-search.md) +- [dotnet new --install option](dotnet-new-install.md) +- [Custom templates for dotnet new](custom-templates.md) diff --git a/docs/core/tools/dotnet-new.md b/docs/core/tools/dotnet-new.md index 054700b6cd845..20b41f1c4bd66 100644 --- a/docs/core/tools/dotnet-new.md +++ b/docs/core/tools/dotnet-new.md @@ -15,12 +15,8 @@ ms.date: 09/04/2020 ## Synopsis ```dotnetcli -dotnet new